forgedock 1.30.0 → 1.31.0

package/scripts/review-prepare.sh

@@ -9,7 +9,7 @@
 # the PR checkout, a SPEC_CLI persona file, forge.yaml paths.root) as data.
 #
 # Usage: review-prepare.sh --pr N --repo owner/name [--merge-issue N] [--thorough true|false] [--out FILE] [--out-dir DIR]
-#                          [--checkout-pr] [--no-delta] [--build-gate block|advisory]
+#                          [--checkout-pr] [--no-delta] [--delta-from SHA] [--build-gate block|advisory]
 #   --pr            PR number (numeric, required)          --repo        owner/name (required)
 #   --merge-issue   issue the PR closes, from --issue (numeric; non-numeric is ignored)
 #   --thorough      true restores the full-union roster    --out         write the context JSON here (default: stdout)
@@ -23,6 +23,11 @@
 #   --no-delta      skip the FULL/DELTA/BASE_SYNC_ONLY resolver: the review mode is always FULL (a staging bundle review always reviews the
 #                   whole bundle), without widening the roster to the full union the way --thorough does; it also enables the pinned
 #                   local-git diff fallback when `gh pr diff` fails (e.g. HTTP 406 over 20,000 lines), which a milestone->staging PR gets without it
+#   --delta-from    explicit DELTA from a caller-supplied earlier reviewed head (forge#4360, `forgedock review-staging --delta`): skips the
+#                   resolver (even with --no-delta), narrows diff, slices and roster to SHA..review sha (the roster is the domains the delta
+#                   files touch). BLOCKED when SHA is not a full commit id in the checkout, equals or is not an ancestor of the review sha,
+#                   or has no trusted FORGE:REVIEW-AGENT body with `Reviewed-SHA: SHA` (no earlier pass to credit). An empty file delta
+#                   is FULL. Not combinable with --thorough true (exit 2).
 # Env: FORGE_CONFIG (forge.yaml path; default: the main checkout's forge.yaml, then the git top-level one),
 #      REVIEW_PREPARE_SLEEP (seconds between mergeability retries, default 5),
 #      REVIEW_PREPARE_INDEX_TIMEOUT (seconds the code-index build may take, default 120; on timeout or failure the slices say
@@ -61,10 +66,10 @@
 
 set -u
 
-PR_NUMBER=""; REPO=""; MERGE_ISSUE=""; THOROUGH="false"; OUT=""; OUT_DIR=""; CHECKOUT_PR="false"; NO_DELTA="false"; BUILD_GATE="block"
+PR_NUMBER=""; REPO=""; MERGE_ISSUE=""; THOROUGH="false"; OUT=""; OUT_DIR=""; CHECKOUT_PR="false"; NO_DELTA="false"; BUILD_GATE="block"; DELTA_FROM_OPT=""
 while [ $# -gt 0 ]; do
     case "$1" in
-        --pr|--repo|--merge-issue|--thorough|--out|--out-dir)
+        --pr|--repo|--merge-issue|--thorough|--out|--out-dir|--delta-from)
             [ $# -ge 2 ] || { echo "review-prepare: $1 requires a value" >&2; exit 2; } ;;
     esac
     case "$1" in
@@ -76,6 +81,7 @@ while [ $# -gt 0 ]; do
         --out-dir) OUT_DIR="${2:-}"; shift 2 ;;
         --checkout-pr) CHECKOUT_PR="true"; shift ;;
         --no-delta) NO_DELTA="true"; shift ;;
+        --delta-from) DELTA_FROM_OPT="${2:-}"; [ -n "$DELTA_FROM_OPT" ] || DELTA_FROM_OPT="-"; shift 2 ;;
         --build-gate) case "${2:-}" in block|advisory) BUILD_GATE="$2" ;; *) echo "review-prepare: --build-gate must be block or advisory" >&2; exit 2 ;; esac; shift 2 ;;
         *) echo "review-prepare: unknown argument: $1" >&2; exit 2 ;;
     esac
@@ -85,6 +91,7 @@ case "$REPO" in */*) ;; *) echo "review-prepare: --repo must be owner/name" >&2;
 case "$REPO" in *[!A-Za-z0-9._/-]*|*/*/*|/*|*/) echo "review-prepare: invalid --repo" >&2; exit 2 ;; esac
 case "$MERGE_ISSUE" in *[!0-9]*) MERGE_ISSUE="" ;; esac
 [ "$THOROUGH" = "true" ] || THOROUGH="false"
+if [ -n "$DELTA_FROM_OPT" ] && [ "$THOROUGH" = "true" ]; then echo "review-prepare: --delta-from cannot be combined with --thorough true" >&2; exit 2; fi
 
 # --- trusted helper resolution (install roots only; never cwd) ---
 # shellcheck source=/dev/null  # the resolver lib is found at runtime in the trusted install root
@@ -125,7 +132,7 @@ cleanup() { restore_ref; rm -rf "$TMP_DIR"; }
 trap cleanup EXIT
 
 # --- Phase 1A: fetch ---
-PR_INFO=$(gh pr view "$PR_NUMBER" -R "$REPO" --json number,title,author,baseRefName,headRefName,headRefOid,isCrossRepository,additions,deletions,changedFiles 2>/dev/null) || PR_INFO=""
+PR_INFO=$(gh pr view "$PR_NUMBER" -R "$REPO" --json number,title,author,baseRefName,headRefName,headRefOid,isCrossRepository,additions,deletions,changedFiles,labels 2>/dev/null) || PR_INFO=""
 printf '%s' "$PR_INFO" | jq -e . >/dev/null 2>&1 || PR_INFO=""
 if [ -z "$PR_INFO" ]; then block "gh pr view failed for #${PR_NUMBER}"; fi
 pj() { printf '%s' "$PR_INFO" | jq -r "$1 // empty" 2>/dev/null; }
@@ -452,7 +459,53 @@ delta_roster() {
     printf '%s' "$out"
 }
 REVIEW_MODE="FULL"; DELTA_FROM=""; CARRIED_FROM=""; FULL_ROUNDS=0; DELTA_FILES=""
-if [ "$THOROUGH" != "true" ] && [ "$IS_MILESTONE_TO_STAGING" != "true" ] && [ "$NO_DELTA" != "true" ]; then
+if [ -n "$DELTA_FROM_OPT" ]; then
+    # forge#4360: explicit delta. Every check fails closed (BLOCKED); only an empty file delta widens to FULL (below).
+    _dtop="${TOP:-.}"
+    case "$DELTA_FROM_OPT" in *[!0-9a-f]*|"") _dok=false ;; *) { [ "${#DELTA_FROM_OPT}" -eq 40 ] || [ "${#DELTA_FROM_OPT}" -eq 64 ]; } && _dok=true || _dok=false ;; esac
+    if [ "$_dok" != "true" ]; then block "--delta-from is not a full commit id: $(printf '%s' "$DELTA_FROM_OPT" | tr -cd '0-9A-Za-z' | cut -c1-64)"
+    elif [ "$DELTA_FROM_OPT" = "$REVIEW_SHA" ]; then block "--delta-from ${DELTA_FROM_OPT} is the review head: nothing to review"
+    elif ! git -C "$_dtop" cat-file -e "${DELTA_FROM_OPT}^{commit}" 2>/dev/null; then block "--delta-from ${DELTA_FROM_OPT} is not a commit in this checkout (fetch it first)"
+    elif ! git -C "$_dtop" merge-base --is-ancestor "$DELTA_FROM_OPT" "$REVIEW_SHA" 2>/dev/null; then block "--delta-from ${DELTA_FROM_OPT} is not an ancestor of ${REVIEW_SHA} (force-push or rebase): run a full review"
+    elif printf '%s' "$PR_INFO" | jq -e '[.labels[]?.name] | index("review-degraded") != null' >/dev/null 2>&1; then block "--delta-from ${DELTA_FROM_OPT}: the PR is labelled review-degraded (an earlier panel was incomplete): run a full review"
+    else
+        # forge#4471: the earlier pass must be complete and non-degraded, as scripts/review-delta.sh requires of a checkpoint:
+        # an agent body with a findings block for <from>, a post-panel-guard proof naming <from> (staging summary, synthesized
+        # block, or a # PR Review Summary whose Agents count matches) and no degraded marker after its first agent body.
+        _dv="error"
+        if [ -n "$TRUSTED_SCRIPT" ] && [ -n "$COMMENTS_JSON" ]; then
+            _db=$(printf '%s' "$COMMENTS_JSON" | bash "$TRUSTED_SCRIPT" bodies '^<!-- FORGE:REVIEW-AGENT:[a-z0-9-]+ -->|^<!-- REVIEW-FINDINGS-SYNTHESIZED-START -->|# PR Review Summary|^<!-- FORGE:GATE_(PASS|FAILURE) -->|<!-- FORGE:GATE_FAILURE:TYPE=review-panel-integrity|<!-- FORGE:REVIEW_DEGRADED|<!-- FORGE:REVIEW_BLOCKED' 2>/dev/null) \
+                && _dv=$(printf '%s\n' "$_db" | jq -s -r --arg f "$DELTA_FROM_OPT" '
+                    def shas($t; $re): [ $t | scan($re) | .[0] ];
+                    def one($a): if ($a | length) == 1 then $a[0] else null end;
+                    def rsha: "(?:^|\\n)Reviewed-SHA: ([0-9a-f]{40}|[0-9a-f]{64})\\r?(?:\\n|$)";
+                    to_entries as $E
+                    | [ $E[] | select((.value | test("\\A<!-- FORGE:REVIEW-AGENT:[a-z0-9-]+ -->")) and (.value | test("<!-- REVIEW-FINDINGS-START -->")))
+                        | select(one(shas(.value; rsha)) == $f)
+                        | {i: .key, d: (.value | capture("\\A<!-- FORGE:REVIEW-AGENT:(?<d>[a-z0-9-]+) -->").d)} ] as $AG
+                    | if ($AG | length) == 0 then "no-agent" else
+                        ($AG | map(.i) | min) as $first | ($AG | map(.d) | unique | length) as $nd
+                        | ([ $E[] | .value as $t | select(
+                              (($t | test("\\A<!-- FORGE:GATE_(?:PASS|FAILURE) -->\\r?\\n## Staging Review:"))
+                                and one(shas($t; "\\*\\*Head\\*\\*: `([0-9a-f]{40}|[0-9a-f]{64})`")) == $f)
+                              or (($t | startswith("<!-- REVIEW-FINDINGS-SYNTHESIZED-START -->")) and one(shas($t; rsha)) == $f)
+                              or (($t | test("# PR Review Summary"))
+                                and one(shas($t; "\\*\\*Reviewed commit\\*\\*: `?([0-9a-f]{40}|[0-9a-f]{64})`?(?:[ |\\r\\n]|$)")) == $f
+                                and one(shas($t; "\\*\\*Agents\\*\\*: ([0-9]+)")) == ($nd | tostring))) ] | length) as $proof
+                        | ([ $E[] | select(.key > $first)
+                             | select(.value | test("<!-- FORGE:GATE_FAILURE:TYPE=review-panel-integrity|<!-- FORGE:REVIEW_DEGRADED|<!-- FORGE:REVIEW_BLOCKED")) ] | length) as $deg
+                        | if $deg > 0 then "degraded" elif $proof == 0 then "no-proof" else "ok" end
+                      end' 2>/dev/null) || _dv="error"
+        fi
+        case "$_dv" in
+            ok) REVIEW_MODE="DELTA"; DELTA_FROM="$DELTA_FROM_OPT" ;;
+            no-agent) block "--delta-from ${DELTA_FROM_OPT}: no trusted FORGE:REVIEW-AGENT comment with a findings block for that head, no earlier pass to credit: run a full review" ;;
+            no-proof) block "--delta-from ${DELTA_FROM_OPT}: no trusted proof that the earlier panel completed (staging summary, synthesized block or PR Review Summary for that head): run a full review" ;;
+            degraded) block "--delta-from ${DELTA_FROM_OPT}: the earlier pass is degraded (review-panel-integrity / REVIEW_DEGRADED / REVIEW_BLOCKED after its agents): run a full review" ;;
+            *) block "--delta-from ${DELTA_FROM_OPT}: could not read the trusted review comments, no earlier pass to credit: run a full review" ;;
+        esac
+    fi
+elif [ "$THOROUGH" != "true" ] && [ "$IS_MILESTONE_TO_STAGING" != "true" ] && [ "$NO_DELTA" != "true" ]; then
     read -r RD_KIND RD_ARG RD_ROUNDS <<< "$(review_delta_mode)"
     FULL_ROUNDS="${RD_ROUNDS:-0}"
     case "$RD_KIND" in
@@ -463,7 +516,21 @@ fi
 if [ "$REVIEW_MODE" = "DELTA" ]; then
     DELTA_FILES=$(git -C "${TOP:-.}" -c core.quotepath=off diff --name-only --no-renames "${DELTA_FROM}" "${REVIEW_SHA}" 2>/dev/null) || DELTA_FILES=""
     if [ -z "$DELTA_FILES" ]; then REVIEW_MODE="FULL"; DELTA_FROM=""
-    else SELECTED_AGENTS=$(canonical_roster "$(delta_roster "$FULL_ROUNDS" "$SELECTED_AGENTS" "$DELTA_FILES")"); fi
+    else
+        # an explicit --delta-from always narrows the roster to the domains the delta touches (no full-rounds gate)
+        _drounds="$FULL_ROUNDS"
+        # forge#4471: an explicit delta that changes the review specs/config cannot credit the earlier pass (same list as
+        # scripts/review-delta.sh, which answers FULL there; review-prepare.test.sh checks the two lists match)
+        if [ -n "$DELTA_FROM_OPT" ]; then
+            while IFS= read -r _df; do
+                case "$_df" in
+                    forge.yaml|commands/review-pr*.md|commands/review-pr-agents/*|scripts/review-delta.sh|scripts/trusted-comments.sh|scripts/verify-phase-trail.sh|docs/spec/review-protocol.md|scripts/classify-finding.sh) block "--delta-from ${DELTA_FROM}: the delta changes ${_df} (review spec/config), the earlier pass cannot be credited: run a full review"; break ;;
+                esac
+            done <<< "$DELTA_FILES"
+        fi
+        [ -n "$DELTA_FROM_OPT" ] && { _drounds=2; ROSTER_REASON="delta ${DELTA_FROM:0:7}..${REVIEW_SHA:0:7}: domains the delta touches"; }
+        SELECTED_AGENTS=$(canonical_roster "$(delta_roster "$_drounds" "$SELECTED_AGENTS" "$DELTA_FILES")")
+    fi
 fi
 [ "$REVIEW_MODE" = "BASE_SYNC_ONLY" ] && SELECTED_AGENTS=""
 

package/scripts/review-prepare.test.sh

@@ -199,6 +199,91 @@ DELTA_KIND=DELTA prep "$WORK/root-delta" --thorough true; eq "thorough never goe
 setup feat/x staging "$FIXFILES" "$DIFF_AUTH_BILL" "notasha"
 DELTA_KIND=DELTA prep "$WORK/root-delta"; eq "unvalidated sha is FULL" .delta.mode FULL
 
+# --- 5b. explicit --delta-from (forge#4360: forgedock review-staging --delta): no resolver involved ---
+cmt() {   # cmt <body> [association]: one comment object
+    jq -n --arg b "$1" --arg a "${2:-OWNER}" '{body: $b, author_association: $a, user: {login: "r", type: "User"}}'
+}
+agent_body() { printf '<!-- FORGE:REVIEW-AGENT:security -->\nReviewed-SHA: %s\n<!-- REVIEW-FINDINGS-START -->\n<!-- REVIEW-FINDINGS-END -->' "$1"; }
+# shellcheck disable=SC2016  # the backticks are literal markdown
+staging_summary() { printf '<!-- FORGE:GATE_FAILURE -->\n## Staging Review: NEEDS FIXES FIRST\n\n**Head**: `%s`\n\n<!-- FORGE:GATE_FAILURE:TYPE=staging-review|BUNDLE= -->' "$1"; }
+comments_of() { jq -s . > "$FIX/comments.json"; }   # comments_of < <cmt ...>...
+earlier_pass() {   # earlier_pass <sha> [association]: a complete earlier pass (agent body + post-guard staging summary)
+    { cmt "$(agent_body "$1")" "${2:-OWNER}"; cmt "$(staging_summary "$1")" "${2:-OWNER}"; } | comments_of
+}
+git -C "$REPO_DIR" checkout -q -b pr-empty pr-branch; git -C "$REPO_DIR" commit -q --allow-empty -m C;   # own branch: pr-branch stays at B (pinned-fallback tests below)
+ SHA_C=$(git -C "$REPO_DIR" rev-parse HEAD)
+git -C "$REPO_DIR" checkout -q -b side main; echo d > "$REPO_DIR/d.txt"; git -C "$REPO_DIR" add -A; git -C "$REPO_DIR" commit -qm D
+SHA_D=$(git -C "$REPO_DIR" rev-parse HEAD); git -C "$REPO_DIR" checkout -q main
+setup staging main "$FIXFILES" "$DIFF_AUTH_BILL"; earlier_pass "$SHA_A"
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"
+rc_is "--delta-from ok" 0; eq "--delta-from mode" .delta.mode DELTA; eq "--delta-from from" .delta.from "$SHA_A"
+eq "--delta-from files" '.delta.files | join(" ")' "services/api/auth.py"
+eq "--delta-from roster is the touched domains, even before 2 full rounds" '.roster.agents | join(" ")' "security auth api"
+eq "--delta-from reason names the delta" '.roster.reason | startswith("delta ")' true
+eq "--delta-from slices narrow to the delta" '.slices.security.paths | join(" ")' "services/api/auth.py"
+eq "--delta-from full_files stays whole" '.full_files | length' 2
+prep "$WORK/root-nodelta" --no-delta; eq "--no-delta without --delta-from stays FULL" .delta.mode FULL
+earlier_pass "$SHA_A" NONE
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "untrusted earlier pass" 3
+eq "untrusted earlier pass blocker" '.blockers | join(" ") | test("no earlier pass to credit")' true
+earlier_pass "$SHA_B"
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "no earlier pass at the from sha" 3
+earlier_pass "$SHA_D"
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_D"; rc_is "non-ancestor from sha" 3
+eq "non-ancestor blocker" '.blockers | join(" ") | test("not an ancestor")' true
+earlier_pass "$SHA_B"
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_B"; rc_is "from sha == head" 3
+eq "head blocker" '.blockers | join(" ") | test("is the review head")' true
+prep "$WORK/root-nodelta" --no-delta --delta-from "0123456789012345678901234567890123456789"; rc_is "unknown commit" 3
+prep "$WORK/root-nodelta" --no-delta --delta-from "abc123"; rc_is "short sha" 3
+setup staging main "$FIXFILES" "$DIFF_AUTH_BILL" "$SHA_C"; earlier_pass "$SHA_B"
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_B"; rc_is "empty delta" 0; eq "empty delta is FULL" .delta.mode FULL
+prep "$WORK/root-nodelta" --delta-from "$SHA_B" --thorough true; rc_is "--delta-from with --thorough" 2
+# forge#4471: the earlier pass must be complete and non-degraded, and the delta must not change review specs/config
+setup staging main "$FIXFILES" "$DIFF_AUTH_BILL"
+{ cmt "$(agent_body "$SHA_A")"; cmt "<!-- FORGE:GATE_FAILURE:TYPE=review-panel-integrity -->
+panel degraded: 1 of 4 reviewers completed"; } | comments_of
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "degraded earlier pass blocks --delta-from" 3
+eq "degraded earlier pass blocker" '.blockers | join(" ") | test("earlier pass is degraded")' true
+{ cmt "$(agent_body "$SHA_A")"; cmt "$(staging_summary "$SHA_A")"; cmt "<!-- FORGE:REVIEW_DEGRADED -->"; } | comments_of
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "REVIEW_DEGRADED after a summarised pass blocks" 3
+{ cmt "<!-- FORGE:REVIEW_DEGRADED -->"; cmt "$(agent_body "$SHA_A")"; cmt "$(staging_summary "$SHA_A")"; } | comments_of
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "degraded marker before the earlier pass does not disqualify it" 0
+{ cmt "$(agent_body "$SHA_A")"; } | comments_of
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "partial earlier pass (no post-guard proof) blocks" 3
+eq "partial earlier pass blocker" '.blockers | join(" ") | test("no trusted proof that the earlier panel completed")' true
+{ cmt "$(agent_body "$SHA_A")"; cmt "$(staging_summary "$SHA_A")" NONE; } | comments_of
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "untrusted staging summary is no proof" 3
+{ cmt "$(staging_summary "$SHA_B")"; cmt "$(agent_body "$SHA_A")"; } | comments_of
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "summary for another head is no proof" 3
+{ cmt "<!-- FORGE:REVIEW-AGENT:security -->
+Reviewed-SHA: $SHA_A
+
+no findings block"; cmt "$(staging_summary "$SHA_A")"; } | comments_of
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "agent body without a findings block blocks" 3
+{ cmt "$(agent_body "$SHA_A")"; cmt "<!-- REVIEW-FINDINGS-SYNTHESIZED-START -->
+Reviewed-SHA: $SHA_A
+<!-- REVIEW-FINDINGS-SYNTHESIZED-END -->"; } | comments_of
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "synthesized block is a post-guard proof" 0
+{ cmt "$(agent_body "$SHA_A")"; cmt "# PR Review Summary
+**Reviewed commit**: \`$SHA_A\`
+**Agents**: 2"; } | comments_of
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "PR Review Summary with an Agents count above the domains blocks" 3
+earlier_pass "$SHA_A"
+sed 's/"changedFiles":1}/"changedFiles":1,"labels":[{"name":"review-degraded"}]}/' "$FIX/prinfo.json" > "$FIX/prinfo.tmp" && mv "$FIX/prinfo.tmp" "$FIX/prinfo.json"
+prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_A"; rc_is "review-degraded label blocks --delta-from" 3
+eq "review-degraded label blocker" '.blockers | join(" ") | test("labelled review-degraded")' true
+for _sf in forge.yaml scripts/trusted-comments.sh; do
+    git -C "$REPO_DIR" checkout -q -b "pr-spec-$(basename "$_sf")" pr-branch; mkdir -p "$REPO_DIR/$(dirname "$_sf")"; echo x > "$REPO_DIR/$_sf"
+    git -C "$REPO_DIR" add -A; git -C "$REPO_DIR" commit -qm "touch $_sf"; _sh=$(git -C "$REPO_DIR" rev-parse HEAD); git -C "$REPO_DIR" checkout -q main
+    setup staging main "$FIXFILES" "$DIFF_AUTH_BILL" "$_sh"; earlier_pass "$SHA_B"
+    prep "$WORK/root-nodelta" --no-delta --delta-from "$SHA_B"; rc_is "delta touching $_sf blocks --delta-from" 3
+    eq "delta touching $_sf blocker" '.blockers | join(" ") | test("review spec/config")' true
+done
+# the spec/config list must stay identical to the resolver's FULL list
+_pl() { grep -oE 'forge\.yaml\|commands/review-pr[^)]*\)' "$1" | head -n 1; }
+if [ -n "$(_pl "$ROOT/scripts/review-delta.sh")" ] && [ "$(_pl "$ROOT/scripts/review-prepare.sh")" = "$(_pl "$ROOT/scripts/review-delta.sh")" ]; then ok; else bad "review-prepare.sh spec/config list drifted from scripts/review-delta.sh"; fi
+
 # --- 6. full-build lane: empty trusted config is BLOCKED, never a silent skip ---
 TS_DIFF='diff --git a/web/src/app/page.tsx b/web/src/app/page.tsx
 +x'

package/scripts/review-staging-post.sh

@@ -0,0 +1,293 @@
+#!/usr/bin/env bash
+# review-staging-post.sh — deterministic post-dispatch checks of the staging->main review (forge#4359): the incomplete-panel guard,
+# Phase 6.75 agent delivery verification and the Phase 6.5 test-gate verdict handling, moved out of commands/review-pr-staging.md.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Usage: review-staging-post.sh delivery  --repo R --pr N --sd DIR [--head SHA]
+#        review-staging-post.sh test-gate --repo R --pr N --sd DIR --output FILE --prs-file F
+#                                         [--default BRANCH] [--config forge.yaml] [--posture blocking|advisory] [--override-phrase TEXT]
+#   delivery   counts trusted, current-head FORGE:REVIEW-AGENT comments (findings block required) for every domain listed in
+#              DIR/<N>_launched_review_agents. A shortfall labels the PR review-degraded + needs-human and posts
+#              FORGE:GATE_FAILURE:TYPE=review-panel-integrity; an empty/unreadable list or a missing domain is a delivery failure.
+#              Exit 0 = every launched reviewer delivered, 1 = not.
+#   test-gate  reads the saved /test-gate output FILE (the last FORGE:TEST_GATE:RESULT= marker; an absent marker stays empty and
+#              fails closed as BLOCK, never SKIP), applies the trusted override, the posture and the FORGE:GATE_PASS /
+#              FORGE:GATE_FAILURE test-gate comments, and persists DIR/<N>_test_gate_verdict and _reason.
+#              Exit 0 = continue, 1 = RESULT: BLOCK DEPLOY.
+# Exit: 2 on a usage error.
+#
+# The `# BEGIN <name>` ... `# END <name>` blocks below are the spec's former fences, copied without their forge_resolve locator
+# stubs (this script resolves helpers once, below). Helpers (trusted-comments.sh) resolve through forge_resolve from trusted
+# install roots only, never the working directory or the repo under review.
+set -u
+
+CMD="${1:-}"; [ $# -gt 0 ] && shift
+GH_REPO=""; PR_NUMBER=""; SD=""; HEAD_ARG=""; OUTPUT_FILE=""; PRS_FILE=""; CONFIG_ARG=""; POSTURE_ARG=""; PHRASE_ARG=""; DEFAULT_BRANCH="main"
+while [ $# -gt 0 ]; do
+  [ $# -ge 2 ] || { echo "review-staging-post: $1 requires a value" >&2; exit 2; }
+  case "$1" in
+    --repo) GH_REPO="$2" ;;
+    --pr) PR_NUMBER="$2" ;;
+    --sd) SD="$2" ;;
+    --head) HEAD_ARG="$2" ;;
+    --output) OUTPUT_FILE="$2" ;;
+    --prs-file) PRS_FILE="$2" ;;
+    --config) CONFIG_ARG="$2" ;;
+    --posture) POSTURE_ARG="$2" ;;
+    --override-phrase) PHRASE_ARG="$2" ;;
+    --default) DEFAULT_BRANCH="$2" ;;
+    *) echo "review-staging-post: unknown argument: $1" >&2; exit 2 ;;
+  esac
+  shift 2
+done
+case "$CMD" in delivery|test-gate) ;; *) echo "review-staging-post: unknown subcommand '${CMD}' (delivery|test-gate)" >&2; exit 2 ;; esac
+case "$PR_NUMBER" in ''|*[!0-9]*) echo "review-staging-post: --pr must be numeric" >&2; exit 2 ;; esac
+case "$GH_REPO" in *[!A-Za-z0-9._/-]*|*/*/*|/*|*/|'') echo "review-staging-post: invalid --repo" >&2; exit 2 ;; */*) ;; *) echo "review-staging-post: --repo must be owner/name" >&2; exit 2 ;; esac
+[ -n "$SD" ] || { echo "review-staging-post: --sd is required" >&2; exit 2; }
+mkdir -p "$SD" || exit 2
+export FORGE_SCRATCHPAD="$SD"
+_SD="$SD"
+# A malformed --head is dropped: the blocks re-resolve it and refuse on empty (fail closed).
+REVIEW_SHA_FULL="$HEAD_ARG"
+case "$REVIEW_SHA_FULL" in *[!0-9a-f]*|"") REVIEW_SHA_FULL="" ;; *) [ "${#REVIEW_SHA_FULL}" -eq 40 ] || [ "${#REVIEW_SHA_FULL}" -eq 64 ] || REVIEW_SHA_FULL="" ;; esac
+unset LAUNCHED_REVIEW_AGENTS SELECTED_AGENT_COUNT TEST_GATE_VERDICT TEST_GATE_REASON
+
+# --- trusted helper resolution (install roots only; never cwd) ---
+# shellcheck source=/dev/null  # the resolver lib is found at runtime in the trusted install root
+type forge_resolve >/dev/null 2>&1 || { setopt nonomatch 2>/dev/null || true; _SELF_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." 2>/dev/null && pwd -P)"; for _r in "$(cygpath -u "${FORGEDOCK_HOME:-}" 2>/dev/null || printf %s "${FORGEDOCK_HOME:-}")" "${CLAUDE_PLUGIN_ROOT:-}" "${FORGE_ROOT:-}" "${FORGE_HOME:-}" "$(readlink -f "$HOME/.claude/commands/work-on.md" 2>/dev/null | sed 's|/commands/work-on\.md$||')" "$(head -n 1 "${CODEX_HOME:-$HOME/.codex}/forge-home" 2>/dev/null)" "$HOME/.claude/plugins/marketplaces/forgedock" "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/forgedock/forgedock/* "$HOME/.claude"/plugins/cache/forgedock/forgedock/* "$_SELF_ROOT"; do case "$_r" in /*) [ -f "$_r/scripts/lib/forge-resolve.sh" ] && { . "$_r/scripts/lib/forge-resolve.sh"; break; };; esac; done; type forge_resolve >/dev/null 2>&1 || forge_resolve() { :; }; }
+
+if [ "$CMD" = delivery ]; then
+echo "=== Incomplete-panel guard and Phase 6.75: verify agent delivery ==="
+# BEGIN panel-guard
+# Each Bash call is a fresh shell: re-resolve the full head SHA if it is not set, and refuse when it is not a commit id
+# (an empty SHA would make the Reviewed-SHA match accept any head).
+[ -n "${REVIEW_SHA_FULL:-}" ] || REVIEW_SHA_FULL=$(gh pr view "$PR_NUMBER" -R "$GH_REPO" --json headRefOid --jq '.headRefOid' 2>/dev/null || echo "")
+case "$REVIEW_SHA_FULL" in *[!0-9a-f]*|"") REVIEW_SHA_FULL="" ;; *) [ "${#REVIEW_SHA_FULL}" -eq 40 ] || [ "${#REVIEW_SHA_FULL}" -eq 64 ] || REVIEW_SHA_FULL="" ;; esac
+TRUSTED_SCRIPT=$(forge_resolve trusted-comments.sh)
+ACTUAL_AGENT_COUNT=0
+if [ -n "$REVIEW_SHA_FULL" ] && [ -n "$TRUSTED_SCRIPT" ]; then
+  # Only TRUSTED, current-head reviewer comments count, over every page of comments. Unique domains, so a duplicate does not inflate the count.
+  ACTUAL_AGENT_COUNT=$(gh api --paginate "repos/${GH_REPO}/issues/${PR_NUMBER}/comments" 2>/dev/null \
+    | bash "$TRUSTED_SCRIPT" bodies "^<!-- FORGE:REVIEW-AGENT:[a-z0-9-]+ -->[\\s\\S]*(^|\\n)Reviewed-SHA:[ ]${REVIEW_SHA_FULL}(\\r?\\n|$)" 2>/dev/null \
+    | jq -r 'scan("^<!-- FORGE:REVIEW-AGENT:([a-z0-9-]+) -->") | .[0]' 2>/dev/null | sort -u | grep -c . || echo 0)
+fi
+case "$ACTUAL_AGENT_COUNT" in ''|*[!0-9]*) ACTUAL_AGENT_COUNT=0 ;; esac   # fail closed: unreadable or untrusted counts as not posted
+# Fresh shell: SELECTED_AGENT_COUNT is not carried over. Reload it from the PR-keyed launched-agent file, then fail closed when it is empty, non-integer or zero (a staging review always selects at least one reviewer).
+[ -n "${SELECTED_AGENT_COUNT:-}" ] || { [ -n "${PR_NUMBER:-}" ] && [ -r "$_SD/${PR_NUMBER}_launched_review_agents" ] && SELECTED_AGENT_COUNT=$(grep -E '^[a-z0-9-]+$' "$_SD/${PR_NUMBER}_launched_review_agents" | sort -u | grep -c .); }
+SELECTED_COUNT_INVALID=false
+case "${SELECTED_AGENT_COUNT:-}" in ''|*[!0-9]*|0) SELECTED_COUNT_INVALID=true; SELECTED_AGENT_COUNT=0 ;; esac
+if [ "${DISPATCH_FAILED:-}" = "true" ] || [ "$SELECTED_COUNT_INVALID" = "true" ] || [ "$ACTUAL_AGENT_COUNT" -lt "$SELECTED_AGENT_COUNT" ]; then
+  gh label create "review-degraded" --color "E4E669" --description "PR review panel was incomplete; re-review required before deployment. Managed by ForgeDock." --force -R "$GH_REPO" 2>/dev/null || true
+  gh pr edit "$PR_NUMBER" -R "$GH_REPO" --add-label "review-degraded" --add-label "needs-human" 2>/dev/null || true # allowlist:check-command-side-effects
+  gh pr comment "$PR_NUMBER" -R "$GH_REPO" --body "<!-- FORGE:GATE_FAILURE:TYPE=review-panel-integrity -->
+## Deploy Review Blocked: Incomplete Isolated Review Panel
+
+**Selected isolated reviewers**: ${SELECTED_AGENT_COUNT}
+**Completed isolated reviewers**: ${ACTUAL_AGENT_COUNT}
+
+Re-run the full staging review in a fresh session before deployment."
+  exit 1
+fi
+# END panel-guard
+# BEGIN delivery-check
+# Reload the launched-agent list persisted at dispatch (validated: lowercase marker domains only).
+[ -n "${LAUNCHED_REVIEW_AGENTS:-}" ] || { [ -r "$_SD/${PR_NUMBER}_launched_review_agents" ] && LAUNCHED_REVIEW_AGENTS=$(grep -E '^[a-z0-9-]+$' "$_SD/${PR_NUMBER}_launched_review_agents" | sort -u | tr '\n' ' '); }
+# Fail closed: a staging review always launches at least the Phase 2 material-change agent, so an empty list means lost state or skipped bookkeeping, never "nothing to verify".
+if [ -z "${PR_NUMBER:-}" ] || [ -z "${LAUNCHED_REVIEW_AGENTS:-}" ]; then
+  echo "REVIEW DELIVERY FAILURE: launched-agent list is empty or unreadable (PR_NUMBER='${PR_NUMBER:-}')"
+  echo "Recover the launched reviewer domains from the PR's FORGE:REVIEW-AGENT comments, re-append them to the launched-agent file, and rerun."
+  exit 1
+fi
+MISSING_AGENT_COMMENTS=""
+# Each Bash call is a fresh shell: re-resolve the full head SHA if it is not set, and refuse when it is not a commit id
+# (an empty SHA would make the Reviewed-SHA match accept any head).
+[ -n "${REVIEW_SHA_FULL:-}" ] || REVIEW_SHA_FULL=$(gh pr view "$PR_NUMBER" -R "$GH_REPO" --json headRefOid --jq '.headRefOid' 2>/dev/null || echo "")
+case "$REVIEW_SHA_FULL" in *[!0-9a-f]*|"") REVIEW_SHA_FULL="" ;; *) [ "${#REVIEW_SHA_FULL}" -eq 40 ] || [ "${#REVIEW_SHA_FULL}" -eq 64 ] || REVIEW_SHA_FULL="" ;; esac
+TRUSTED_SCRIPT=$(forge_resolve trusted-comments.sh)
+for AGENT_DOMAIN in $LAUNCHED_REVIEW_AGENTS; do
+  AGENT_COMMENT_COUNT=0
+  if [ -n "$REVIEW_SHA_FULL" ] && [ -n "$TRUSTED_SCRIPT" ]; then
+    AGENT_COMMENT_COUNT=$(gh api --paginate "repos/${GH_REPO}/issues/${PR_NUMBER}/comments" 2>/dev/null \
+      | bash "$TRUSTED_SCRIPT" count "^(?=[\\s\\S]*<!-- REVIEW-FINDINGS-START -->[\\s\\S]*<!-- REVIEW-FINDINGS-END -->)<!-- FORGE:REVIEW-AGENT:${AGENT_DOMAIN} -->[\\s\\S]*(^|\\n)Reviewed-SHA:[ ]${REVIEW_SHA_FULL}(\\r?\\n|$)" 2>/dev/null || echo 0)
+  fi
+  case "$AGENT_COMMENT_COUNT" in ''|*[!0-9]*) AGENT_COMMENT_COUNT=0 ;; esac   # fail closed: counts as missing
+  if [ "${AGENT_COMMENT_COUNT:-0}" -lt 1 ]; then
+    MISSING_AGENT_COMMENTS="${MISSING_AGENT_COMMENTS} ${AGENT_DOMAIN}"
+  fi
+done
+
+if [ -n "$MISSING_AGENT_COMMENTS" ]; then
+  echo "REVIEW DELIVERY FAILURE: missing findings comment(s) for:${MISSING_AGENT_COMMENTS}"
+  echo "A comment without a REVIEW-FINDINGS-START block counts as missing. Re-dispatch the missing agent once with the note: structured findings block required. A second miss is a degraded panel. Recover each agent's returned verdict, findings, and durable body path before rerunning review."
+  exit 1
+fi
+# END delivery-check
+echo "DELIVERY: OK (${ACTUAL_AGENT_COUNT}/${SELECTED_AGENT_COUNT} launched reviewers posted a findings block for head ${REVIEW_SHA_FULL})"
+exit 0
+fi
+
+# test-gate
+case "$POSTURE_ARG" in ''|blocking|advisory) ;; *) echo "review-staging-post: --posture must be blocking or advisory" >&2; exit 2 ;; esac
+[ -n "$PRS_FILE" ] || { echo "review-staging-post: --prs-file is required" >&2; exit 2; }
+[ -r "$PRS_FILE" ] || { echo "review-staging-post: --prs-file $PRS_FILE is not readable (run the pre-dispatch first)" >&2; exit 2; }
+[ -n "$OUTPUT_FILE" ] || { echo "review-staging-post: --output is required (the saved /test-gate output)" >&2; exit 2; }
+ALL_PR_NUMBERS=$(grep -E '^[0-9]+$' "$PRS_FILE")
+CONFIG_FILE="${CONFIG_ARG:-${FORGE_CONFIG:-forge.yaml}}"
+GH_FLAG="-R $GH_REPO"
+GATE_POSTURE="$POSTURE_ARG"
+[ -n "$GATE_POSTURE" ] || GATE_POSTURE=$(yq '.verification.test_gate.posture // "blocking"' "$CONFIG_FILE" 2>/dev/null || echo "blocking")
+case "$GATE_POSTURE" in advisory) ;; *) GATE_POSTURE=blocking ;; esac   # unreadable or unknown is the blocking default
+OVERRIDE_PHRASE="$PHRASE_ARG"
+[ -n "$OVERRIDE_PHRASE" ] || OVERRIDE_PHRASE=$(yq '.verification.test_gate.override_phrase // "OVERRIDE: shipping with test failures —"' "$CONFIG_FILE" 2>/dev/null || echo "OVERRIDE: shipping with test failures —")
+[ -n "$OVERRIDE_PHRASE" ] || OVERRIDE_PHRASE="OVERRIDE: shipping with test failures —"
+echo "=== Phase 6.5: Runtime Test Gate ==="
+echo "Bundle PRs: $(echo $ALL_PR_NUMBERS | tr '\n' ' ')"
+echo "Posture: ${GATE_POSTURE}"
+# Reset any stale gate result from a prior run (files are PR-keyed)
+rm -f "${_SD:?}/${PR_NUMBER:?}_test_gate_verdict" "${_SD:?}/${PR_NUMBER:?}_test_gate_reason"
+TEST_GATE_VERDICT="SKIP"
+TEST_GATE_REASON="Phase 6.5 not yet run"
+GATE_OUTPUT=""
+if [ -r "$OUTPUT_FILE" ]; then GATE_OUTPUT=$(cat "$OUTPUT_FILE"); else echo "WARNING: /test-gate output $OUTPUT_FILE unreadable: treated as a missing result"; fi
+# BEGIN test-gate-extract
+# Extract machine-readable verdict from Skill output. An absent/invalid marker stays EMPTY (never coerced to SKIP):
+# the verdict-handling fence treats an empty verdict as missing/invalid and fails closed under blocking posture.
+TEST_GATE_VERDICT=$(echo "$GATE_OUTPUT" | grep -oE 'FORGE:TEST_GATE:RESULT=(BLOCK|PASS|SKIP)' | sed 's/^FORGE:TEST_GATE:RESULT=//' | tail -1)
+[ -n "$TEST_GATE_VERDICT" ] || TEST_GATE_REASON="gate result missing/invalid (no FORGE:TEST_GATE:RESULT marker in /test-gate output)"
+# END test-gate-extract
+echo "Test-gate verdict: ${TEST_GATE_VERDICT}"
+printf '%s\n' "$TEST_GATE_VERDICT" > "$_SD/${PR_NUMBER}_test_gate_verdict"; printf '%s\n' "$TEST_GATE_REASON" > "$_SD/${PR_NUMBER}_test_gate_reason"
+# BEGIN test-gate-verdict
+# Reload the Phase 6.5 gate result persisted by its producer (validated: only a known verdict reaches a gate decision).
+[ -n "${TEST_GATE_VERDICT:-}" ] || { [ -r "$_SD/${PR_NUMBER}_test_gate_verdict" ] && TEST_GATE_VERDICT=$(sed -n -E '1{/^(BLOCK|PASS|SKIP)$/p;q}' "$_SD/${PR_NUMBER}_test_gate_verdict"); }
+[ -n "${TEST_GATE_REASON:-}" ] || { [ -r "$_SD/${PR_NUMBER}_test_gate_reason" ] && TEST_GATE_REASON=$(sed -n 1p "$_SD/${PR_NUMBER}_test_gate_reason" | tr -d '\r\000-\037' | cut -c1-400); }
+# Fail closed: a missing, empty, or unrecognised verdict is never a SKIP. Normalize it to BLOCK so the BLOCK arm applies
+# the override check, advisory/blocking posture, and exit 1; GATE_VERDICT_INVALID makes the reasons say missing/invalid.
+GATE_VERDICT_INVALID=0
+case "${TEST_GATE_VERDICT:-}" in
+  BLOCK|PASS|SKIP) ;;
+  *)
+    GATE_VERDICT_INVALID=1
+    if [ -r "$_SD/${PR_NUMBER}_test_gate_verdict" ]; then _GV_WHY="persisted verdict file present but empty/invalid"; else _GV_WHY="persisted verdict file missing"; fi
+    echo "⚠️  Test gate: gate result missing/invalid (${_GV_WHY}) — treating as BLOCK, not SKIP."
+    TEST_GATE_VERDICT="BLOCK"
+    ;;
+esac
+case "$TEST_GATE_VERDICT" in
+
+  SKIP)
+    echo "ℹ️  Test gate: SKIP — no executable changes or tests not configured."
+    echo "   This gap will appear in the Phase 8 summary. No deploy impact."
+    TEST_GATE_REASON="SKIP — no runtime tests ran (docs-only bundle, no integration tests configured, or manual-only criteria)"
+    ;;
+
+  PASS)
+    echo "✅ Test gate: PASS — all test clusters passed. Deploy may proceed."
+    TEST_GATE_REASON="PASS — all automated test clusters passed"
+    # Post FORGE:GATE_PASS for symmetric observability
+    if [ -n "$PR_NUMBER" ]; then
+      gh pr comment "$PR_NUMBER" ${GH_FLAG} --body "<!-- FORGE:GATE_PASS -->
+## Deploy Gate: PASSED
+
+**Gate**: test-gate (runtime acceptance criteria)
+**Result**: PASS — all test clusters passed. Deploy may proceed.
+**Bundle PRs**: ${ALL_PR_NUMBERS}
+**Timestamp**: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+<!-- FORGE:GATE_PASS:TYPE=test-gate|BUNDLE=$(echo $ALL_PR_NUMBERS | tr '\n' ' ' | xargs) -->" 2>/dev/null || true
+    fi
+    ;;
+
+  BLOCK)
+    # Check for override comment on the staging→main PR (mirrors Phase 0A pattern)
+    if [ -n "$PR_NUMBER" ]; then
+      # Trusted authors only, all comment pages, anchored; fail closed (no override) if the script or comments are
+      # unreadable (#3492). OVERRIDE_PHRASE comes from forge.yaml, so regex-escape it before using it as a pattern.
+      TRUSTED_SCRIPT=$(forge_resolve trusted-comments.sh)
+      TG_SCRIPT="$TRUSTED_SCRIPT"
+      TG_COMMENTS=$(gh api --paginate "repos/${GH_REPO}/issues/${PR_NUMBER}/comments" 2>/dev/null) || TG_COMMENTS=""
+      TG_OVERRIDE=0; OVERRIDE_REASON="(reason not captured)"
+      if [ -n "$TG_SCRIPT" ] && [ -n "$TG_COMMENTS" ]; then
+        TG_RE="^$(printf '%s' "$OVERRIDE_PHRASE" | sed 's/[][\\.^$*+?(){}|\/]/\\&/g')"
+        TG_OVERRIDE=$(printf '%s' "$TG_COMMENTS" | bash "$TG_SCRIPT" count "$TG_RE" 2>/dev/null || echo 0)
+        [ "${TG_OVERRIDE:-0}" -gt 0 ] && OVERRIDE_REASON=$(printf '%s' "$TG_COMMENTS" | bash "$TG_SCRIPT" bodies "$TG_RE" 2>/dev/null | tail -1 | jq -r '.' 2>/dev/null || echo "(reason not captured)")
+      fi
+    else
+      TG_OVERRIDE=0
+    fi
+
+    if [ "${TG_OVERRIDE:-0}" -gt 0 ]; then
+      echo "⚠️  Test gate: BLOCK — but override comment detected on PR #${PR_NUMBER}."
+      echo "   Override: ${OVERRIDE_REASON}"
+      echo "   Proceeding with deploy. Override is logged in Phase 8 summary."
+      TEST_GATE_VERDICT="PASS"
+      TEST_GATE_REASON="BLOCK downgraded to PASS by override: ${OVERRIDE_REASON}"
+      [ "$GATE_VERDICT_INVALID" = 1 ] && TEST_GATE_REASON="BLOCK (gate result missing/invalid) downgraded to PASS by override: ${OVERRIDE_REASON}"
+
+    elif [ "$GATE_POSTURE" = "advisory" ]; then
+      echo "⚠️  Test gate: BLOCK (advisory posture) — runtime failures detected but deploy is NOT prevented."
+      echo "   Switch verification.test_gate.posture to 'blocking' in forge.yaml to enforce this gate."
+      TEST_GATE_REASON="BLOCK (advisory) — runtime failures detected; deploy allowed by advisory posture"
+      [ "$GATE_VERDICT_INVALID" = 1 ] && TEST_GATE_REASON="BLOCK (advisory) — gate result missing/invalid; deploy allowed by advisory posture"
+
+    else
+      # blocking posture (default) — STOP
+      echo "⛔ DEPLOY BLOCKED — /test-gate returned BLOCK verdict."
+      [ "$GATE_VERDICT_INVALID" = 1 ] && echo "   (gate result missing/invalid — failing closed; re-run /test-gate or post the override comment)"
+      echo ""
+      echo "Runtime failures were detected in the staging→${DEFAULT_BRANCH} bundle."
+      echo "The failures were batch-introduced (not pre-existing on ${DEFAULT_BRANCH} baseline)."
+      echo ""
+      echo "Options:"
+      echo "  1. Fix the failing tests and merge fixes to staging before retrying the deploy."
+      echo "  2. Post a comment on this PR starting with \"${OVERRIDE_PHRASE} <reason>\" to bypass this gate."
+      echo "  3. Set verification.test_gate.posture: advisory in forge.yaml to downgrade to a warning."
+      echo ""
+      echo "RESULT: BLOCK DEPLOY"
+
+      # Post structured FORGE:GATE_FAILURE comment for pipeline-health tracking
+      GATE_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+      if [ -n "$PR_NUMBER" ]; then
+        gh pr comment "$PR_NUMBER" ${GH_FLAG} --body "<!-- FORGE:GATE_FAILURE -->
+## Deploy Gate: BLOCKED
+
+**Gate**: test-gate
+**Timestamp**: ${GATE_TIMESTAMP}
+**Bundle PRs**: $(echo $ALL_PR_NUMBERS | tr '\n' ' ')
+**Posture**: ${GATE_POSTURE}
+
+### What Happened
+
+\`/test-gate\` detected runtime failures in the staging→\`${DEFAULT_BRANCH}\` bundle that were NOT present on the \`${DEFAULT_BRANCH}\` baseline. These are batch-introduced regressions. (If the gate result was missing/invalid, no verdict could be read and the gate failed closed; re-run \`/test-gate\`.)
+
+\`/test-gate\` has filed \`test-failure\` issues for each failing cluster — check the issue tracker for details.
+
+### Resolution
+
+1. Fix the failing tests and merge fixes to staging.
+2. Retry the staging→\`${DEFAULT_BRANCH}\` deploy.
+
+To override (ship known failures with documented reason), post a comment containing:
+\`${OVERRIDE_PHRASE} <reason>\`
+
+<!-- FORGE:GATE_FAILURE:TYPE=test-gate|BUNDLE=$(echo $ALL_PR_NUMBERS | tr '\n' ' ' | xargs) -->" 2>/dev/null || true
+      fi
+      _GV_REASON="BLOCK (blocking posture, no override)"; [ "$GATE_VERDICT_INVALID" = 1 ] && _GV_REASON="BLOCK (gate result missing/invalid; blocking posture, no override)"
+      printf '%s\n' "$TEST_GATE_VERDICT" > "$_SD/${PR_NUMBER}_test_gate_verdict"; printf '%s\n' "$_GV_REASON" > "$_SD/${PR_NUMBER}_test_gate_reason"
+      exit 1
+    fi
+    ;;
+
+  *)
+    # Unreachable (normalized above); fail closed regardless — never SKIP.
+    echo "⛔ Test gate: gate result missing/invalid ('${TEST_GATE_VERDICT}') — failing closed."
+    printf '%s\n' "BLOCK" > "$_SD/${PR_NUMBER}_test_gate_verdict"; printf '%s\n' "BLOCK (gate result missing/invalid)" > "$_SD/${PR_NUMBER}_test_gate_reason"
+    exit 1
+    ;;
+
+esac
+# Persist the gate result: every Bash call is a fresh shell, and the verdict-handling fence and Phase 8 read it back (validated on reload).
+printf '%s\n' "$TEST_GATE_VERDICT" > "$_SD/${PR_NUMBER}_test_gate_verdict"; printf '%s\n' "$TEST_GATE_REASON" > "$_SD/${PR_NUMBER}_test_gate_reason"
+# END test-gate-verdict
+exit 0