docs(ci): define real staging gate rules

scripts/ci/final_decision_consistency_check.sh

@@ -14,6 +14,10 @@ LOG_FILE="${OUT_DIR}/final_decision_consistency_${TS}.log"
 # - 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
+# Real staging gate design:
+# - DEFERRED / PASS_REHEARSAL must not be counted as release completion
+# - override metadata, if present, must include approver, timestamp, run_id, and reason
+# - final consistency WARN must not upgrade a non-real staging run into release PASS
 
 latest_file_or_empty() {
   local pattern="$1"

scripts/ci/staging_real_readiness_check.sh

@@ -15,6 +15,12 @@ TS="$(date +%F_%H%M%S)"
 REPORT_FILE="${OUT_DIR}/staging_real_readiness_${TS}.md"
 LOG_FILE="${OUT_DIR}/staging_real_readiness_${TS}.log"
 
+# Planned blocking output contract:
+# - real_staging_pass=true|false
+# - classification=REAL|REHEARSAL
+# - reason_code=<stable_code>
+# - run_id=<required in release flow>
+
 CHECK_IDS=()
 CHECK_STATUS=()
 CHECK_DESC=()
@@ -164,6 +170,11 @@ if [[ "${has_fail}" == "1" ]]; then
   NOTE="at least one required check failed"
 fi
 
+# Future status mapping:
+# - READY => PASS_REAL only when ENV_CLASS=real-staging
+# - BLOCKED => FAIL
+# - local-mock / placeholder classifications must never be treated as PASS_REAL
+
 {
   echo "# 真实 STG 就绪度检查"
   echo

scripts/ci/superpowers_release_pipeline.sh

@@ -13,6 +13,11 @@ ENABLE_MINIMAX_MONITORING="${ENABLE_MINIMAX_MONITORING:-0}"
 MINIMAX_ENV_FILE="${MINIMAX_ENV_FILE:-scripts/supply-gate/.env.minimax-dev}"
 MINIMAX_RUN_ACTIVE_SMOKE="${MINIMAX_RUN_ACTIVE_SMOKE:-0}"
 
+# Planned real-staging hard gate:
+# - fail fast immediately after STEP-01 if stage validation is not PASS_REAL
+# - STEP-02 onward must not run release-path decisions on PASS_REHEARSAL/DEFERRED
+# - override, if ever allowed, must require approver, timestamp, run_id, and reason
+
 log() {
   echo "$1" | tee -a "${LOG_FILE}"
 }
@@ -101,6 +106,10 @@ run_optional_step_non_blocking \
   "${ENABLE_MINIMAX_MONITORING}" \
   "cd \"${ROOT_DIR}\" && RUN_ACTIVE_SMOKE=\"${MINIMAX_RUN_ACTIVE_SMOKE}\" bash \"scripts/ci/minimax_upstream_daily_snapshot.sh\" \"${TODAY_TAG}\" \"${MINIMAX_ENV_FILE}\" && bash \"scripts/ci/minimax_upstream_trend_report.sh\" \"${TODAY_TAG}\""
 
+# Planned fail-fast insertion point:
+# - parse STEP-01 report here
+# - if real staging status != PASS_REAL and no valid override record exists, exit 1 before STEP-02
+
 has_fail=0
 for row in "${STEP_RESULTS[@]}"; do
   status="$(echo "${row}" | awk -F'|' '{print $2}')"

scripts/ci/superpowers_stage_validate.sh

@@ -115,6 +115,12 @@ run_phase07() {
     "env_class=local-mock|placeholder token detected|placeholder API_BASE_URL|missing env var|API_BASE_URL unreachable"
 }
 
+# Real staging decision design:
+# - PASS_REAL: PHASE-07 runs against real staging and succeeds.
+# - PASS_REHEARSAL: all executable rehearsal phases pass, but PHASE-07 is local/mock/deferred.
+# - FAIL: any required phase fails, or PHASE-07 is not real-pass when release flow requests hard gate.
+# - DEFERRED must never be promoted to PASS_REAL.
+
 ensure_mock_server() {
   if curl -sS -m 2 "http://127.0.0.1:18080/actuator/health" >/dev/null 2>&1; then
     echo "already_running"
@@ -240,6 +246,11 @@ if is_mock_staging_env "${STAGING_ENV_FILE}" && [[ "${DECISION}" == "GO" ]]; the
   DECISION_REASON="all phases passed but PHASE-07 used local/mock staging env"
 fi
 
+# Future release hard-gate mapping:
+# - GO maps to PASS_REAL only when PHASE-07 is real-staging PASS.
+# - CONDITIONAL_GO maps to PASS_REHEARSAL and must not satisfy release pass.
+# - NO_GO maps to FAIL.
+
 {
   echo "# Superpowers 阶段验证报告"
   echo