forgedock 1.12.0 → 1.13.0

package/scripts/check-blast-radius.test.sh

@@ -0,0 +1,183 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Fixtures for scripts/check-blast-radius.sh. Run: bash scripts/check-blast-radius.test.sh (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+S="$DIR/check-blast-radius.sh"
+T=$(mktemp -d "${TMPDIR:-/tmp}/check-blast-radius-test.XXXXXX")
+trap 'rm -rf "$T"' EXIT
+pass=0; fail=0
+OUT=""; RC=0
+
+g() { git -C "$T/r" -c user.name=t -c user.email=t@example.com -c commit.gpgsign=false "$@" >/dev/null 2>&1; }
+run() { OUT=$(bash "$S" --manifest "$T/m" --base staging --repo "$T/r" 2>&1); RC=$?; }
+manifest() { { echo '<!-- FORGE:BLAST_RADIUS:BEGIN -->'; cat; echo '<!-- FORGE:BLAST_RADIUS:END -->'; } > "$T/m"; }
+expect() { # expect <want_rc> <desc> [want_substring]
+  if [ "$RC" = "$1" ] && { [ -z "${3:-}" ] || case "$OUT" in *"$3"*) true ;; *) false ;; esac; }; then
+    pass=$((pass+1))
+  else
+    fail=$((fail+1)); echo "FAIL: $2 (rc=$RC, want $1)"; printf '%s\n' "$OUT" | sed 's/^/    /'
+  fi
+}
+expect_absent() { # expect_absent <desc> <substring>
+  case "$OUT" in *"$2"*) fail=$((fail+1)); echo "FAIL: $1 (unexpected '$2')"; printf '%s\n' "$OUT" | sed 's/^/    /' ;; *) pass=$((pass+1)) ;; esac
+}
+reset_branch() { g checkout -q -f staging; g branch -q -D feat; g checkout -q -b feat; }
+
+mkdir "$T/r"; git -C "$T/r" init -q -b staging >/dev/null 2>&1 || { git -C "$T/r" init -q; g checkout -b staging; }
+mkdir -p "$T/r/routers" "$T/r/docs"
+for f in a b c; do printf 'def handler():\n    use(billing_principal)\n' > "$T/r/routers/$f.py"; done
+echo 'notes about nothing' > "$T/r/docs/readme.md"
+g add -A; g commit -m base
+g checkout -q -b feat
+
+SYM='SYMBOL: id=s1 kind=field name=billing_principal query="billing_principal"'
+
+# (a) 3 sibling callers, 1 changed, 2 unlisted -> FAIL naming both unlisted files
+echo 'use(billing_principal, new)' >> "$T/r/routers/a.py"; g add -A; g commit -m "change a"
+manifest <<M
+$SYM
+HIT: symbol=s1 file=routers/a.py role=consumer disposition=change
+M
+run; expect 1 "3 siblings, 1 changed, 2 unlisted fails" "UNLISTED: s1 routers/b.py"
+case "$OUT" in *"UNLISTED: s1 routers/c.py"*) pass=$((pass+1)) ;; *) fail=$((fail+1)); echo "FAIL: second unlisted sibling not named"; echo "$OUT" ;; esac
+expect_absent "changed file is not unlisted" "UNLISTED: s1 routers/a.py"
+
+# (b) all 3 changed -> PASS
+echo 'use(billing_principal, new)' >> "$T/r/routers/b.py"; echo 'use(billing_principal, new)' >> "$T/r/routers/c.py"
+g add -A; g commit -m "change b c"
+manifest <<M
+$SYM
+HIT: symbol=s1 file=routers/a.py role=consumer disposition=change
+M
+run; expect 0 "all siblings changed passes (changed files need no row)" "OK:"
+
+# (c) 1 changed + 2 verified-unaffected -> PASS
+reset_branch; echo 'use(billing_principal, new)' >> "$T/r/routers/a.py"; g add -A; g commit -m "change a"
+manifest <<M
+$SYM
+HIT: symbol=s1 file=routers/a.py role=consumer disposition=change
+HIT: symbol=s1 file=routers/b.py role=sibling disposition=verified-unaffected reason=reads-only-never-writes
+HIT: symbol=s1 file=routers/c.py role=sibling disposition=verified-unaffected reason=dead-code-path
+M
+run; expect 0 "verified-unaffected siblings pass" "OK:"
+
+# (c2) staged but uncommitted and untracked changes count (validate runs before the commit)
+reset_branch; echo 'use(billing_principal, new)' >> "$T/r/routers/a.py"; echo 'use(billing_principal, new)' >> "$T/r/routers/b.py"
+g add routers/a.py; echo 'billing_principal = 1' > "$T/r/routers/d.py"
+manifest <<M
+$SYM
+M
+run; expect 1 "uncommitted: c.py still unlisted" "UNLISTED: s1 routers/c.py"
+expect_absent "staged change counts" "UNLISTED: s1 routers/a.py"
+expect_absent "unstaged tracked change counts" "UNLISTED: s1 routers/b.py"
+expect_absent "untracked new file counts" "UNLISTED: s1 routers/d.py"
+g checkout -q -f staging; rm -f "$T/r/routers/d.py"; g checkout -q -f feat; rm -f "$T/r/routers/d.py"; g reset -q --hard
+
+# (d) change row whose file is not in the diff -> FAIL (planned but not done)
+reset_branch; echo 'use(billing_principal, new)' >> "$T/r/routers/a.py"; g add -A; g commit -m "change a"
+manifest <<M
+$SYM
+HIT: symbol=s1 file=routers/a.py role=consumer disposition=change
+HIT: symbol=s1 file=docs/readme.md role=consumer disposition=change
+HIT: symbol=s1 file=routers/b.py role=sibling disposition=verified-unaffected reason=x-reason
+HIT: symbol=s1 file=routers/c.py role=sibling disposition=verified-unaffected reason=x-reason
+M
+run; expect 1 "planned-but-not-done change row fails" "NOT_DONE: s1 docs/readme.md"
+
+# (e) rc 2 cases
+manifest <<M
+SYMBOL: id=s1 kind=field name=x query="-rf"
+M
+run; expect 2 "leading dash query rejected"
+manifest <<M
+SYMBOL: id=s1 kind=field name=x query=""
+M
+run; expect 2 "empty query rejected"
+manifest <<M
+SYMBOL: id=s1 kind=field name=x query="ab"
+M
+run; expect 2 "too-short query rejected"
+manifest <<M
+SYMBOL: id=s1 kind=field name=x query="foo bar baz"
+M
+run; expect 2 "query with spaces rejected"
+manifest <<M
+SYMBOL: id=s1 kind=field name=x query="a;rm -rf"
+M
+run; expect 2 "query with shell metacharacters rejected"
+manifest <<M
+$SYM
+this is not a record
+M
+run; expect 2 "malformed line rejected"
+manifest <<M
+$SYM
+HIT: symbol=s1 file=routers/b.py role=sibling disposition=verified-unaffected
+M
+run; expect 2 "verified-unaffected without reason rejected"
+manifest <<M
+$SYM
+HIT: symbol=s9 file=routers/b.py role=sibling disposition=change
+M
+run; expect 2 "HIT with unknown symbol rejected"
+manifest <<M
+$SYM
+HIT: symbol=s1 file=routers/b.py role=sibling disposition=maybe
+M
+run; expect 2 "invalid disposition rejected"
+manifest <<M
+$SYM
+$SYM
+M
+run; expect 2 "duplicate symbol id rejected"
+printf '<!-- FORGE:BLAST_RADIUS:BEGIN -->\n%s\n' "$SYM" > "$T/m"
+run; expect 2 "unterminated BEGIN rejected"
+manifest <<M
+$SYM
+M
+OUT=$(bash "$S" --manifest "$T/m" --base no-such-ref --repo "$T/r" 2>&1); RC=$?; expect 2 "bad base ref is rc 2, not a pass"
+mkdir "$T/notgit"
+OUT=$(bash "$S" --manifest "$T/m" --base staging --repo "$T/notgit" 2>&1); RC=$?; expect 2 "non-git repo is rc 2, not a pass"
+OUT=$(bash "$S" --manifest "$T/missing" --base staging --repo "$T/r" 2>&1); RC=$?; expect 2 "missing manifest file is rc 2"
+OUT=$(bash "$S" --base staging 2>&1); RC=$?; expect 2 "missing --manifest is rc 2"
+
+# (f) absent / empty manifest -> SKIP rc 0
+: > "$T/m"; run; expect 0 "empty manifest skips" "SKIP: no manifest"
+printf '## Implementation Plan\nno block here\n' > "$T/m"; run; expect 0 "no BEGIN/END block skips" "SKIP: no manifest"
+printf '## Plan\nprose\n<!-- FORGE:BLAST_RADIUS:BEGIN -->\n%s\nHIT: symbol=s1 file=routers/a.py role=consumer disposition=change\n<!-- FORGE:BLAST_RADIUS:END -->\ntrailing prose\n<!-- FORGE:ARCHITECT:COMPLETE -->\n' "$SYM" > "$T/m"
+run; expect 1 "whole comment body is accepted, prose outside the block ignored" "UNLISTED: s1 routers/b.py"
+
+# fixed-string, not regex: a query with metacharacter-like text must match literally
+g checkout -q -f staging; echo 'a.b(c)' > "$T/r/docs/regex.txt"; echo 'aXb(c)' > "$T/r/docs/other.txt"; g add -A; g commit -m regex
+g branch -q -D feat; g checkout -q -b feat
+manifest <<M
+SYMBOL: id=s1 kind=function name=dot query="a.b"
+M
+run; expect 1 "fixed-string match lists the literal hit" "UNLISTED"
+expect_absent "regex-style wildcard does not match aXb" "other.txt"
+HIT_OK='HIT: symbol=s1 file=docs/regex.txt role=producer disposition=verified-unaffected reason=literal-only'
+manifest <<M
+SYMBOL: id=s1 kind=function name=dot query="a.b"
+$HIT_OK
+M
+run; expect 0 "literal hit covered by verified-unaffected" "OK:"
+
+# zero-hit symbol passes
+manifest <<M
+SYMBOL: id=s1 kind=flag name=nothing query="zz_never_present_zz"
+M
+run; expect 0 "zero-hit symbol passes" "OK:"
+
+# query too broad -> rc 2
+reset_branch; mkdir -p "$T/r/many"; i=0; while [ "$i" -lt 205 ]; do echo broadtoken > "$T/r/many/f$i.txt"; i=$((i+1)); done; g add -A; g commit -m many
+manifest <<M
+SYMBOL: id=s1 kind=flag name=broad query="broadtoken"
+M
+run; expect 2 "over-broad query is rc 2" "too broad"
+
+echo "check-blast-radius.test.sh: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/scripts/check-contract-scope.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-contract-scope.sh — Parser/validator for the `### Out of Scope` section of a
+#                            FORGE:CONTRACT comment. One grammar shared by work-on:build
+#                            (validate before posting) and review-pr (list, to demote findings
+#                            that match a contract-declared item).
+#
+# Usage:
+#   check-contract-scope.sh validate [<file>]   # exit 0 valid, 1 invalid (one line per bad item on stderr)
+#   check-contract-scope.sh list     [<file>]   # TSV: disposition<TAB>path<TAB>issue, one row per path
+#   Input is the contract comment body, from <file> or stdin.
+#
+# Grammar. The section is either the single line `None.` or a list of bullets, each naming at
+# least one backticked path or symbol followed by exactly one disposition:
+#   - `path` — deferred → #N: <why>        (a follow-up issue exists; `->` is accepted for `→`)
+#   - `path` — not-affected: <evidence>
+#   - `path` — accepted-risk: <reason>
+# `deferred` without an issue number, an item without a backticked path, an item with no
+# disposition, and a missing or empty section are all invalid.
+#
+# `list` prints disposition as one of: deferred, not-affected, accepted-risk. The issue column is
+# the number for deferred rows and empty otherwise. A trailing `/` is stripped from paths. `*`
+# is not a glob: consumers match literally (equal, or under the path as a directory prefix).
+# `list` on an invalid section prints nothing and exits 1 (fail toward filing in review).
+#
+# Exit: 0 ok; 1 invalid section; 2 usage error. Portable: bash 3.2, no network.
+
+set -u
+
+usage() { echo "ERROR: Usage: check-contract-scope.sh validate|list [<file>]" >&2; exit 2; }
+
+MODE="${1:-}"
+case "$MODE" in validate|list) ;; *) usage ;; esac
+[ "$#" -le 2 ] || usage
+if [ "$#" -eq 2 ]; then
+  [ -r "$2" ] || { echo "ERROR: not readable: $2" >&2; exit 2; }
+  BODY=$(cat "$2")
+else
+  BODY=$(cat)
+fi
+
+SECTION=$(printf '%s\n' "$BODY" | tr -d '\r' | awk '
+  /^### Out of Scope[[:space:]]*$/ { p = 1; found = 1; next }
+  p && /^### / { p = 0 }
+  p && /^> Pipeline powered by/ { p = 0 }
+  p && /^<!--/ { p = 0 }
+  p { print }
+  END { if (!found) exit 3 }
+')
+RC=$?
+if [ "$RC" -ne 0 ]; then
+  echo "invalid: no '### Out of Scope' section" >&2
+  exit 1
+fi
+
+ROWS=""
+ERRS=""
+COUNT=0
+NONE=0
+ITEM=""
+
+flush_item() {
+  [ -n "$ITEM" ] || return 0
+  COUNT=$((COUNT + 1))
+  _text=$(printf '%s' "$ITEM" | sed -E 's/deferred[[:space:]]*(→|->)[[:space:]]*/deferred → /g')
+  # Earliest disposition keyword wins; the prefix before it holds the paths.
+  _pre_n="${_text%%not-affected:*}"
+  _pre_a="${_text%%accepted-risk:*}"
+  _pre_d="${_text%%deferred → *}"
+  _disp=""; _pre="$_text"
+  if [ "$_pre_n" != "$_text" ]; then _disp="not-affected"; _pre="$_pre_n"; fi
+  if [ "$_pre_a" != "$_text" ] && { [ -z "$_disp" ] || [ "${#_pre_a}" -lt "${#_pre}" ]; }; then _disp="accepted-risk"; _pre="$_pre_a"; fi
+  if [ "$_pre_d" != "$_text" ] && { [ -z "$_disp" ] || [ "${#_pre_d}" -lt "${#_pre}" ]; }; then _disp="deferred"; _pre="$_pre_d"; fi
+  _issue=""
+  if [ -z "$_disp" ]; then
+    ERRS="${ERRS}untyped item (needs deferred → #N, not-affected:, or accepted-risk:): ${ITEM}
+"
+    ITEM=""; return 0
+  fi
+  if [ "$_disp" = "deferred" ]; then
+    _rest="${_text#*deferred → }"
+    if [[ "$_rest" =~ ^#([0-9]+) ]]; then
+      _issue="${BASH_REMATCH[1]}"
+    else
+      ERRS="${ERRS}deferred item has no issue number (needs deferred → #N): ${ITEM}
+"
+      ITEM=""; return 0
+    fi
+  fi
+  _paths=$(printf '%s' "$_pre" | grep -o '`[^`][^`]*`' | tr -d '`')
+  if [ -z "$_paths" ]; then
+    ERRS="${ERRS}item names no backticked path or symbol: ${ITEM}
+"
+    ITEM=""; return 0
+  fi
+  while IFS= read -r _p; do
+    [ -n "$_p" ] || continue
+    _p="${_p%/}"
+    ROWS="${ROWS}${_disp}	${_p}	${_issue}
+"
+  done <<EOP
+$_paths
+EOP
+  ITEM=""
+}
+
+while IFS= read -r line; do
+  trimmed=$(printf '%s' "$line" | sed -E 's/^[[:space:]]+//; s/[[:space:]]+$//')
+  [ -n "$trimmed" ] || continue
+  case "$trimmed" in
+    "None."|"- None."|"* None.") NONE=1; continue ;;
+    "- "*|"* "*)
+      flush_item
+      ITEM=$(printf '%s' "$trimmed" | sed -E 's/^[-*][[:space:]]+//') ;;
+    *)
+      if [ -n "$ITEM" ]; then ITEM="${ITEM} ${trimmed}"
+      else ERRS="${ERRS}unexpected text outside a bullet: ${trimmed}
+"; fi ;;
+  esac
+done <<EOS
+$SECTION
+EOS
+flush_item
+
+if [ "$COUNT" -eq 0 ] && [ "$NONE" -eq 0 ] && [ -z "$ERRS" ]; then
+  ERRS="empty '### Out of Scope' section (write None. or typed items)
+"
+fi
+
+if [ -n "$ERRS" ]; then
+  printf 'invalid: %s' "$ERRS" >&2
+  exit 1
+fi
+[ "$MODE" = "list" ] && printf '%s' "$ROWS"
+exit 0

package/scripts/check-contract-scope.test.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Fixtures for scripts/check-contract-scope.sh (typed `### Out of Scope` grammar).
+# Run: bash scripts/check-contract-scope.test.sh   (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+S="$DIR/check-contract-scope.sh"
+pass=0; fail=0
+TAB=$(printf '\t')
+
+mk() { printf '## Builder Contract\n\n### Deliverables\n\n| a | b |\n\n### Out of Scope\n\n%s\n\n> Pipeline powered by [ForgeDock](https://example.invalid)\n' "$1"; }
+
+# check <valid|invalid> <description> <section-text>
+check() {
+  want="$1"; desc="$2"; body=$(mk "$3")
+  printf '%s\n' "$body" | bash "$S" validate >/dev/null 2>&1; got=$?
+  if { [ "$want" = valid ] && [ "$got" = 0 ]; } || { [ "$want" = invalid ] && [ "$got" = 1 ]; }; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc (want $want, exit $got)"; fi
+}
+# list_is <description> <section-text> <expected TSV (printf-style, \t and \n)>
+list_is() {
+  desc="$1"; body=$(mk "$2"); want=$(printf "$3")
+  got=$(printf '%s\n' "$body" | bash "$S" list 2>/dev/null)
+  if [ "$got" = "$want" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+
+check valid   "None. accepted"                      'None.'
+check valid   "deferred with issue"                 '- `scripts/a.sh` — deferred → #12: tracked there'
+check valid   "not-affected with evidence"          '- `bin/engine/` — not-affected: no reader found by grep'
+check valid   "accepted-risk with reason"           '- `pkg/types.js` — accepted-risk: body-only format'
+check valid   "ASCII arrow accepted"                '- `a.sh` — deferred -> #7: later'
+check valid   "no-space arrow accepted"             '- `a.sh` — deferred→#7: later'
+check valid   "three mixed items"                   '- `a/` — not-affected: x
+- `b.js` — accepted-risk: y
+- `c.md` — deferred → #3446: z'
+check valid   "continuation line joins item"        '- `a.sh` — deferred → #5:
+  because of reasons'
+check invalid "untyped bullet rejected"             '- `a.sh` — out of scope for now'
+check invalid "deferred without number rejected"    '- `a.sh` — deferred: later'
+check invalid "deferred arrow without number"       '- `a.sh` — deferred → TBD: later'
+check invalid "no backticked path rejected"         '- the sync script — deferred → #9: later'
+check invalid "bare prose rejected"                 'Nothing relevant.'
+check invalid "one bad item among good ones"        '- `a` — not-affected: ok
+- `b` — nope'
+check invalid "empty section rejected"              ''
+
+# Missing section
+printf '## Builder Contract\n\n### Deliverables\n\nx\n' | bash "$S" validate >/dev/null 2>&1; got=$?
+if [ "$got" = 1 ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: missing section (want exit 1, got $got)"; fi
+
+list_is "list rows for three forms" '- `a/` — not-affected: x
+- `b.js` — accepted-risk: y
+- `c.md` — deferred → #3446: z' "not-affected${TAB}a${TAB}\naccepted-risk${TAB}b.js${TAB}\ndeferred${TAB}c.md${TAB}3446"
+list_is "multi-path item emits one row per path" '- `x.sh`, `y.sh` — deferred → #8: both' "deferred${TAB}x.sh${TAB}8\ndeferred${TAB}y.sh${TAB}8"
+list_is "why-text with other keywords does not change disposition" '- `a` — accepted-risk: not-affected elsewhere, deferred → #1 is separate' "accepted-risk${TAB}a${TAB}"
+list_is "None. lists nothing" 'None.' ""
+list_is "invalid section lists nothing" '- `a` — untyped' ""
+
+# Section ends at the next ### heading
+printf '### Out of Scope\n\n- `a` — not-affected: x\n\n### Quality\n\n- plain bullet\n' | bash "$S" validate >/dev/null 2>&1; got=$?
+if [ "$got" = 0 ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: section must end at next ### (exit $got)"; fi
+
+# Live-shaped contract (mixed items, trailing attribution line)
+LIVE=$(mk '- `bin/engine/` — not-affected: no engine module reads the contract Out of Scope section (grep in investigation).
+- `packages/protocol/src/types.js` — accepted-risk: CONTRACT requiredFields stays [Task type].
+- `commands/work-on/build/architect.md` — deferred → #3446: blast-radius manifest is tracked there.')
+got=$(printf '%s\n' "$LIVE" | bash "$S" list 2>/dev/null | wc -l | tr -d ' ')
+if [ "$got" = 3 ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: live-shaped contract rows (want 3, got $got)"; fi
+
+# File argument and usage errors
+TMPF=$(mktemp "${TMPDIR:-/tmp}/ccs.XXXXXX"); printf '%s\n' "$LIVE" > "$TMPF"
+bash "$S" validate "$TMPF" >/dev/null 2>&1; got=$?
+if [ "$got" = 0 ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: file argument (exit $got)"; fi
+rm -f "$TMPF"
+bash "$S" validate /nonexistent/x >/dev/null 2>&1; got=$?
+if [ "$got" = 2 ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: unreadable file (want 2, got $got)"; fi
+bash "$S" bogus </dev/null >/dev/null 2>&1; got=$?
+if [ "$got" = 2 ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: bad mode (want 2, got $got)"; fi
+
+echo "check-contract-scope.test.sh: passed=$pass failed=$fail"
+[ "$fail" -eq 0 ]

package/scripts/check-spec-bash.sh

@@ -13,6 +13,7 @@
 # Usage:
 #   check-spec-bash.sh [--base <git-ref>] [--shellcheck] <file.md>...
 #   check-spec-bash.sh --positional [<file.md>...]
+#   check-spec-bash.sh --fence-state <VAR>... -- <file.md>...
 #   check-spec-bash.sh            (no args: same as --positional over all Skill-loaded commands/**/*.md,
 #                                  excluding orchestrate/**, pipeline-health/**, review-pr-agents/**)
 #
@@ -25,6 +26,13 @@
 #                 Scope the file list to Skill-loaded specs (Read-loaded orchestrate/**,
 #                 pipeline-health/** and the review-pr-agents catalog are not substituted).
 #                 Output: `FAIL <file>:<line> positional arg ...` then `SPEC-POSITIONAL: ...`.
+#   --fence-state Different check, opt-in: every Bash tool call is a fresh shell, so a variable bound
+#                 in one fence is empty in the next. Fail any ```bash/sh fence that reads `$VAR` or
+#                 `${VAR...}` for a listed VAR without assigning it in the same fence (`VAR=`,
+#                 `export VAR=`, `read VAR`, `for VAR in`) at or before its first read. Comment-only lines are ignored; `$REPO`
+#                 does not match `$REPO_FLAG`. Suppress a deliberate read by putting
+#                 `allowlist:fence-state` on the same line. Pseudo-tool-call fences are scanned too.
+#                 Output: `FAIL <file>:<line> fence-state ...` then `SPEC-FENCE-STATE: ...`.
 #   --base <ref>   Only check blocks that contain a line changed relative to <ref>
 #                  (`git diff -U0 <ref> -- <file>`), so pre-existing blocks never fail
 #                  a new change. Without --base every block is checked.
@@ -45,14 +53,22 @@
 
 set -u
 
-BASE=""; SHELLCHECK=0; POSITIONAL=0; FILES=""
-usage() { echo "ERROR: Usage: check-spec-bash.sh [--base <git-ref>] [--shellcheck] <file.md>... | --positional [<file.md>...]" >&2; exit 2; }
+BASE=""; SHELLCHECK=0; POSITIONAL=0; FILES=""; FENCESTATE=0; FSVARS=""
+usage() { echo "ERROR: Usage: check-spec-bash.sh [--base <git-ref>] [--shellcheck] <file.md>... | --positional [<file.md>...] | --fence-state <VAR>... -- <file.md>..." >&2; exit 2; }
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
     --base) [ "$#" -ge 2 ] || usage; BASE="$2"; shift 2 ;;
     --shellcheck) SHELLCHECK=1; shift ;;
     --positional) POSITIONAL=1; shift ;;
+    --fence-state)
+      FENCESTATE=1; shift
+      while [ "$#" -gt 0 ] && [ "$1" != "--" ]; do
+        case "$1" in -*|*[!A-Za-z0-9_]*) usage ;; esac
+        FSVARS="$FSVARS $1"; shift
+      done
+      [ "$#" -gt 0 ] && [ -n "$FSVARS" ] || usage
+      shift ;;
     --*) usage ;;
     *) FILES="$FILES
 $1"; shift ;;
@@ -62,7 +78,7 @@ done
 # No file arguments: default to the --positional check over every Skill-loaded spec under commands/
 # (orchestrate/**, pipeline-health/** and the review-pr-agents catalog are Read-loaded, not substituted).
 # Resolved relative to this script, so it works from any cwd and from linked worktrees.
-if [ -z "$FILES" ] && { [ "$#" -eq 0 ] && [ "$POSITIONAL" = 0 ] && [ -z "$BASE" ] && [ "$SHELLCHECK" = 0 ] || [ "$POSITIONAL" = 1 ]; }; then
+if [ -z "$FILES" ] && [ "$FENCESTATE" = 0 ] && { [ "$#" -eq 0 ] && [ "$POSITIONAL" = 0 ] && [ -z "$BASE" ] && [ "$SHELLCHECK" = 0 ] || [ "$POSITIONAL" = 1 ]; }; then
   POSITIONAL=1
   cd "$(dirname "$0")/.." || exit 2
   FILES=$(find commands -name '*.md' -not -path 'commands/orchestrate/*' \
@@ -70,6 +86,47 @@ if [ -z "$FILES" ] && { [ "$#" -eq 0 ] && [ "$POSITIONAL" = 0 ] && [ -z "$BASE"
 fi
 [ -n "$FILES" ] || usage
 
+if [ "$FENCESTATE" = 1 ]; then
+  sfail=0; sfiles=0
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    case "$f" in *.md) ;; *) continue ;; esac
+    [ -f "$f" ] || { echo "SKIP $f missing"; continue; }
+    sfiles=$((sfiles + 1))
+    hits=$(awk -v f="$f" -v vars="$FSVARS" '
+      function flush(   i, v, ln) {
+        for (i = 1; i <= nv; i++) {
+          v = vn[i]
+          if (first[v] != "" && !asg[v]) print "FAIL " f ":" first[v] " fence-state: $" v " read in a fence before it is assigned (fresh shell per Bash call): " firsttxt[v]
+        }
+      }
+      function reset(   i) { for (i = 1; i <= nv; i++) { asg[vn[i]] = 0; first[vn[i]] = ""; firsttxt[vn[i]] = "" } }
+      BEGIN { nv = split(vars, vn, " ") }
+      !inb && /^[ \t]*```(bash|sh)[ \t]*$/ { inb = 1; reset(); next }
+      !inb && /^[ \t]*```/ { other = !other; next }
+      other { next }
+      inb && /^[ \t]*```[ \t]*$/ { flush(); inb = 0; next }
+      inb {
+        if ($0 ~ /^[ \t]*#/) next
+        for (i = 1; i <= nv; i++) {
+          v = vn[i]
+          if (first[v] == "" && ($0 ~ ("(^|[;&|( \t])(export[ \t]+|local[ \t]+|declare[ \t]+(-[A-Za-z]+[ \t]+)?|readonly[ \t]+)?" v "=") ||
+              $0 ~ ("(^|[;&|( \t])read[ \t]+(-[A-Za-z]+[ \t]+)*([A-Za-z0-9_]+[ \t]+)*" v "([ \t;]|$)") ||
+              $0 ~ ("(^|[;&|( \t])for[ \t]+" v "[ \t]+in[ \t]"))) asg[v] = 1
+          if (first[v] == "" && $0 !~ /allowlist:fence-state/ &&
+              ($0 ~ ("\\$" v "([^A-Za-z0-9_]|$)") || $0 ~ ("\\$\\{" v "([^A-Za-z0-9_]|$)"))) { first[v] = NR; firsttxt[v] = $0 }
+        }
+      }
+    ' "$f")
+    if [ -n "$hits" ]; then printf '%s\n' "$hits"; sfail=$((sfail + $(printf '%s\n' "$hits" | wc -l))); fi
+  done <<EOS
+$FILES
+EOS
+  echo "SPEC-FENCE-STATE: files=$sfiles violations=$sfail"
+  [ "$sfail" -eq 0 ]
+  exit $?
+fi
+
 if [ "$POSITIONAL" = 1 ]; then
   pfail=0; pfiles=0
   while IFS= read -r f; do

package/scripts/check-spec-bash.test.sh

@@ -109,5 +109,61 @@ check 1 "FAIL pos-bad.md:3"             "--positional flags shell \$1"
 check 1 "violations=2"                  "--positional counts violations"       -- --positional pos-bad.md
 check 0 "violations=0"                  "--positional passes safe forms, prose, allowlist" -- --positional pos-good.md
 
+# --fence-state: a listed var read in a fence without a prior assignment in that same fence is flagged.
+cat > "$T/fs-bad.md" <<EOF
+${FENCE}bash
+gh pr view "\$PR_NUMBER" -R "\$REPO" --json state
+${FENCE}
+${FENCE}bash
+X=\$(gh pr diff \${PR_NUMBER} --name-only)
+${FENCE}
+${FENCE}bash
+echo "\${REPO:-none}"
+${FENCE}
+${FENCE}bash
+gh pr view "\$PR_NUMBER"
+PR_NUMBER="{PR_NUMBER}"
+${FENCE}
+EOF
+cat > "$T/fs-good.md" <<EOF
+Prose mentions \$PR_NUMBER and \$REPO freely.
+${FENCE}bash
+# comment reads \$PR_NUMBER and \$REPO
+PR_NUMBER="{PR_NUMBER}"; REPO="{GH_REPO}"
+gh pr view "\$PR_NUMBER" -R "\$REPO"
+${FENCE}
+${FENCE}bash
+export REPO="{GH_REPO}"
+for PR_NUMBER in 1 2; do echo "\${PR_NUMBER}"; done
+echo "\$REPO"
+${FENCE}
+${FENCE}bash
+REPO="\${REPO:-\$(gh repo view)}"
+${FENCE}
+${FENCE}bash
+gh pr view \${REPO_FLAG} "\$OTHER"
+${FENCE}
+${FENCE}bash
+echo "\$PR_NUMBER" # allowlist:fence-state
+${FENCE}
+${FENCE}text
+echo \$PR_NUMBER \$REPO
+${FENCE}
+${FENCE}bash
+PR_NUMBER="{PR_NUMBER}"
+OUT=\$(Skill(skill="x", args="\$PR_NUMBER"))
+${FENCE}
+EOF
+check 1 "FAIL fs-bad.md:2 fence-state: \$PR_NUMBER" "--fence-state flags \$VAR read"        -- --fence-state PR_NUMBER REPO -- fs-bad.md
+check 1 "FAIL fs-bad.md:2 fence-state: \$REPO"      "--fence-state flags each listed var"   -- --fence-state PR_NUMBER REPO -- fs-bad.md
+check 1 "FAIL fs-bad.md:5 fence-state: \$PR_NUMBER" "--fence-state flags \${VAR} form"       -- --fence-state PR_NUMBER REPO -- fs-bad.md
+check 1 "FAIL fs-bad.md:8 fence-state: \$REPO"      "--fence-state flags \${VAR:-default}" -- --fence-state PR_NUMBER REPO -- fs-bad.md
+check 1 "FAIL fs-bad.md:11 fence-state: \$PR_NUMBER" "--fence-state flags read before assignment" -- --fence-state PR_NUMBER REPO -- fs-bad.md
+check 1 "violations=5"                   "--fence-state counts violations"        -- --fence-state PR_NUMBER REPO -- fs-bad.md
+check 0 "violations=0"                   "--fence-state ignores unlisted vars"    -- --fence-state UNLISTED -- fs-bad.md
+check 0 "violations=0"                   "--fence-state passes declared, loop, export, REPO_FLAG, allowlist, comments, prose, non-bash fences" -- --fence-state PR_NUMBER REPO -- fs-good.md
+check 2 "Usage"                          "--fence-state without -- is a usage error"  -- --fence-state PR_NUMBER fs-good.md
+check 2 "Usage"                          "--fence-state without vars is a usage error" -- --fence-state -- fs-good.md
+
 echo "check-spec-bash.test.sh: passed=$pass failed=$fail"
 [ "$fail" -eq 0 ]

package/scripts/check-spec-markers.sh

@@ -88,6 +88,7 @@ MARKER_REGISTRY="
   BASESYNC_REMEDIATION
   BATCH_MEMBERS
   BENCH_SCORECARD
+  BLAST_RADIUS
   BLOCKED_ON_HUMAN_MERGE
   BODY
   BUILDER
@@ -106,6 +107,7 @@ MARKER_REGISTRY="
   DECISION_RECORD
   DECOMPOSED
   DECOMPOSE_BLOCKED
+  DEFERRED_FROM
   DESIGN
   DIFF_SIZE
   DISPATCH
@@ -416,6 +418,33 @@ if [ -f "$WORKON_SPEC" ]; then
   fi
 fi
 
+# ---------------------------------------------------------------------------
+# Re-review claim id must be printed by both producers (forge#3472)
+# ---------------------------------------------------------------------------
+# A claim id generated in one bash block and compared in a later one is lost unless the producer prints it.
+# Orchestrator: the Step 2 claim block's final echo must carry CLAIM_ID=. Router: Claim pre-check step 3 must
+# require printing CLAIM_ID=. Scoped to the Step 2 / Claim pre-check text only; full-line HTML comments skipped.
+# WIRE:PROVEN: manual mutation in a temp copy: removing CLAIM_ID= from the Step 2 echo fired the orchestrator check, removing it from router step 3 fired the router check, clean tree passes
+P4_SPEC="$COMMANDS_DIR/orchestrate/phase-4-execution.md"
+if [ -f "$P4_SPEC" ]; then
+  STEP2_ECHO=$(awk '
+    /Step 2 — dispatch/ { on = 1 }
+    /Step 3 — outcome/ { on = 0 }
+    on && !/^[[:space:]]*<!--.*-->[[:space:]]*$/ && /^[[:space:]]*echo "REREVIEW_MARKER=/ { print }
+  ' "$P4_SPEC" || true)
+  if ! printf '%s\n' "$STEP2_ECHO" | grep -qF 'CLAIM_ID='; then
+    echo "HIGH | $P4_SPEC | Step 2 claim block's final echo does not print CLAIM_ID= (own claim id is lost across bash blocks)" >&2
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+fi
+if [ -f "$WORKON_SPEC" ]; then
+  ROUTER_STEP3=$(printf '%s\n' "${PRECHECK_STEPS:-}" | grep '^STEP3:' || true)
+  if [ -z "$ROUTER_STEP3" ] || [[ "$ROUTER_STEP3" != *CLAIM_ID=* ]]; then
+    echo "HIGH | $WORKON_SPEC | claim pre-check step 3 does not require printing CLAIM_ID= (router own claim id is lost across bash blocks)" >&2
+    VIOLATIONS=$((VIOLATIONS + 1))
+  fi
+fi
+
 # ---------------------------------------------------------------------------
 # Summary
 # ---------------------------------------------------------------------------