docs(ci): define release manifest contract

Add the run_id and manifest contract doc, reserve the reports/releases tree, record the decision in the execution log, and annotate the four release scripts with their planned manifest-based inputs.

scripts/ci/final_decision_consistency_check.sh

@@ -4,11 +4,17 @@ set -euo pipefail
 ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
 TS="$(date +%F_%H%M%S)"
 OUT_DIR="${ROOT_DIR}/reports/archive/gate_verification"
+RELEASES_DIR="${ROOT_DIR}/reports/releases"
 mkdir -p "${OUT_DIR}"
 
 REPORT_FILE="${OUT_DIR}/final_decision_consistency_${TS}.md"
 LOG_FILE="${OUT_DIR}/final_decision_consistency_${TS}.log"
 
+# Manifest migration design:
+# - preferred entry: --manifest <reports/releases/<run_id>/manifest.json>
+# - this script should bind final_decision, tok007_recheck and stage validation inputs
+#   to one run_id and stop reading historical "latest" outputs
+
 latest_file_or_empty() {
   local pattern="$1"
   local latest
@@ -74,6 +80,10 @@ parse_machine_decision() {
 }
 
 FINAL_DECISION_FILE="${ROOT_DIR}/review/final_decision_2026-03-31.md"
+# Planned manifest keys:
+# - decision_inputs.final_decision_report
+# - decision_inputs.tok007_recheck_report
+# - decision_inputs.superpowers_stage_validation_report
 TOK007_FILE="$(latest_file_or_empty "${ROOT_DIR}/review/outputs/tok007_release_recheck_*.md")"
 SP_FILE="$(latest_file_or_empty "${OUT_DIR}/superpowers_stage_validation_*.md")"
 

scripts/ci/staging_evidence_autofill.sh

@@ -3,12 +3,18 @@ set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
 OUT_DIR="${ROOT_DIR}/reports/archive/gate_verification"
+RELEASES_DIR="${ROOT_DIR}/reports/releases"
 TS="$(date +%F_%H%M%S)"
 OUT_FILE="${OUT_DIR}/staging_token_go_evidence_autofill_${TS}.md"
 LOG_FILE="${OUT_DIR}/staging_token_go_evidence_autofill_${TS}.log"
 
 mkdir -p "${OUT_DIR}"
 
+# Manifest migration design:
+# - preferred entry: --manifest <reports/releases/<run_id>/manifest.json>
+# - this script should read only decision_inputs/artifact_paths from the supplied manifest
+# - no future release evidence should be discovered by latest_file_or_empty()
+
 usage() {
   cat <<'EOF'
 Usage:
@@ -211,6 +217,12 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
+# Planned manifest keys:
+# - decision_inputs.staging_run_log
+# - decision_inputs.stage_report
+# - decision_inputs.token_runtime_readiness_report
+# - decision_inputs.tok007_recheck_report
+# - artifact_paths.superpowers_release_pipeline_report
 if [[ -z "${STAGING_RUN_LOG}" ]]; then
   STAGING_RUN_LOG="$(latest_file_or_empty "${OUT_DIR}/staging_run_*.log")"
 fi

scripts/ci/staging_release_pipeline.sh

@@ -10,12 +10,20 @@ else
 fi
 TS="$(date +%F_%H%M%S)"
 OUT_DIR="${ROOT_DIR}/reports/archive/gate_verification"
+RELEASES_DIR="${ROOT_DIR}/reports/releases"
 mkdir -p "${OUT_DIR}"
 
 REPORT_FILE="${OUT_DIR}/staging_release_pipeline_${TS}.md"
 LOG_FILE="${OUT_DIR}/staging_release_pipeline_${TS}.log"
 ALLOW_LOCAL_MOCK_STAGING="${ALLOW_LOCAL_MOCK_STAGING:-0}"
 
+# Manifest migration design:
+# - run_id format: YYYYMMDD_HHMMSS_<shortsha>_<env>[-rNN]
+# - release root: ${RELEASES_DIR}/<run_id>/
+# - manifest path: ${RELEASES_DIR}/<run_id>/manifest.json
+# - this script becomes the manifest seed writer and must pass the resolved manifest path
+#   to downstream scripts instead of relying on latest_file_or_empty().
+
 log() {
   echo "$1" | tee -a "${LOG_FILE}"
 }
@@ -124,6 +132,12 @@ run_step \
   "Superpowers release pipeline with staging env" \
   "cd \"${ROOT_DIR}\" && STAGING_ENV_FILE=\"${ENV_FILE_REL}\" bash \"scripts/ci/superpowers_release_pipeline.sh\""
 
+# Planned manifest inputs for staging_evidence_autofill.sh:
+# - decision_inputs.staging_run_log
+# - decision_inputs.stage_report
+# - decision_inputs.token_runtime_readiness_report
+# - decision_inputs.tok007_recheck_report
+# - artifact_paths.superpowers_release_pipeline_report
 LATEST_STAGING_RUN_LOG="$(latest_file_or_empty "${OUT_DIR}/staging_run_*.log")"
 LATEST_STAGE_REPORT="$(latest_file_or_empty "${OUT_DIR}/superpowers_stage_validation_*.md")"
 LATEST_TOKEN_READINESS="$(latest_file_or_empty "${OUT_DIR}/token_runtime_readiness_*.md")"

scripts/ci/tok007_release_recheck.sh

@@ -6,12 +6,18 @@ TS="$(date +%F_%H%M%S)"
 OUT_DIR="${ROOT_DIR}/review/outputs"
 mkdir -p "${OUT_DIR}"
 GATE_OUT_DIR="${ROOT_DIR}/reports/archive/gate_verification"
+RELEASES_DIR="${ROOT_DIR}/reports/releases"
 mkdir -p "${GATE_OUT_DIR}"
 MARK_SCRIPT="${ROOT_DIR}/scripts/ci/mark_historical_snapshots.sh"
 CURRENT_POINTER_FILE="review/outputs/current_machine_review_sources.md"
 OUT_FILE="${OUT_DIR}/tok007_release_recheck_${TS}.md"
 LOG_FILE="${GATE_OUT_DIR}/tok007_release_recheck_${TS}.log"
 
+# Manifest migration design:
+# - preferred entry: --manifest <reports/releases/<run_id>/manifest.json>
+# - this script should read run-scoped TOK006 / stage validation / token readiness inputs
+#   from manifest.decision_inputs instead of scanning latest files across history
+
 log() {
   echo "$1" | tee -a "${LOG_FILE}"
 }
@@ -100,6 +106,12 @@ extract_pass_fail_result() {
   echo "UNKNOWN"
 }
 
+# Planned manifest keys:
+# - decision_inputs.tok006_gate_bundle_report
+# - decision_inputs.superpowers_stage_validation_report
+# - decision_inputs.token_runtime_readiness_report
+# - decision_inputs.supply_gate_review_report
+# - decision_inputs.final_decision_report
 TOK006_REPORT="$(latest_file_or_empty "${GATE_OUT_DIR}/tok006_gate_bundle_*.md")"
 SP_REPORT="$(latest_file_or_empty "${GATE_OUT_DIR}/superpowers_stage_validation_*.md")"
 TOK_RUNTIME_READINESS_REPORT="$(latest_file_or_empty "${GATE_OUT_DIR}/token_runtime_readiness_*.md")"