forgedock 1.12.1 → 1.13.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
 # ---------------------------------------------------------------------------

package/scripts/check-test-wiring.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Lint: every scripts/*.test.sh must be referenced by a workflow in .github/workflows/*.yml.
+# An unreferenced test never runs in CI, so regressions in the script under test merge silently.
+# Lists EVERY unwired test before exiting non-zero. bash 3.2 portable (no bash-4 builtins, no PCRE grep).
+#
+# Usage: bash scripts/check-test-wiring.sh [<scripts_dir> [<workflows_dir>]]
+#   defaults: scripts  .github/workflows   (relative to the current directory)
+# Exit: 0 all wired | 1 one or more unwired, or workflows dir missing/empty | 2 bad scripts dir
+
+set -u
+SCRIPTS_DIR="${1:-scripts}"
+WORKFLOWS_DIR="${2:-.github/workflows}"
+
+[ -d "$SCRIPTS_DIR" ] || { echo "check-test-wiring: scripts dir not found: $SCRIPTS_DIR" >&2; exit 2; }
+[ -d "$WORKFLOWS_DIR" ] || { echo "check-test-wiring: workflows dir not found: $WORKFLOWS_DIR" >&2; exit 1; }
+
+wf_files=""
+for w in "$WORKFLOWS_DIR"/*.yml "$WORKFLOWS_DIR"/*.yaml; do
+  [ -f "$w" ] && wf_files="$wf_files
+$w"
+done
+if [ -z "$wf_files" ]; then
+  echo "check-test-wiring: no workflow files in $WORKFLOWS_DIR" >&2
+  exit 1
+fi
+
+total=0
+unwired=0
+for t in "$SCRIPTS_DIR"/*.test.sh; do
+  [ -f "$t" ] || continue
+  total=$((total+1))
+  base=$(basename "$t")
+  # Escape '.' for ERE; names are [A-Za-z0-9._-]. Delimiter-aware: the name must not be a
+  # fragment of a longer filename (foo.test.sh must not be satisfied by barfoo.test.sh).
+  esc=$(printf '%s' "$base" | sed 's/\./\\./g')
+  found=0
+  while IFS= read -r w; do
+    [ -n "$w" ] || continue
+    if grep -Eq "(^|[^A-Za-z0-9._-])${esc}([^A-Za-z0-9._-]|\$)" "$w" 2>/dev/null; then found=1; break; fi
+  done <<EOF2
+$wf_files
+EOF2
+  if [ "$found" -eq 0 ]; then
+    echo "UNWIRED: $base is not referenced by any workflow in $WORKFLOWS_DIR"
+    unwired=$((unwired+1))
+  fi
+done
+
+if [ "$unwired" -gt 0 ]; then
+  echo "check-test-wiring: $unwired of $total test script(s) unwired — add each to a workflow (e.g. shell-compat.yml)" >&2
+  exit 1
+fi
+echo "check-test-wiring: all $total test script(s) wired"
+exit 0

package/scripts/check-test-wiring.test.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Fixtures for scripts/check-test-wiring.sh. Run: bash scripts/check-test-wiring.test.sh (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+S="$DIR/check-test-wiring.sh"
+T=$(mktemp -d "${TMPDIR:-/tmp}/check-test-wiring-test.XXXXXX")
+trap 'rm -rf "$T"' EXIT
+pass=0; fail=0
+
+# check <want_rc> <want_substring|-> <unwanted_substring|-> <desc> <scripts_dir> <workflows_dir>
+check() {
+  want_rc="$1"; want="$2"; unwant="$3"; desc="$4"; sd="$5"; wd="$6"
+  out=$(bash "$S" "$sd" "$wd" 2>&1); rc=$?
+  ok=1
+  if [ "$want" != "-" ]; then case "$out" in *"$want"*) ;; *) ok=0 ;; esac; fi
+  if [ "$unwant" != "-" ]; then case "$out" in *"$unwant"*) ok=0 ;; esac; fi
+  if [ "$rc" = "$want_rc" ] && [ "$ok" = 1 ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc (rc=$rc)"; printf '%s\n' "$out" | sed 's/^/    /'; fi
+}
+
+mk() { mkdir -p "$T/$1/scripts" "$T/$1/wf"; }
+
+# 1. all wired -> pass
+mk ok
+for n in a b c; do : > "$T/ok/scripts/$n.test.sh"; done
+printf 'steps:\n  - run: bash scripts/a.test.sh\n  - run: |\n      /bin/bash scripts/b.test.sh\n      bash scripts/c.test.sh\n' > "$T/ok/wf/x.yml"
+check 0 "all 3 test script(s) wired" - "all wired passes" "$T/ok/scripts" "$T/ok/wf"
+
+# 2. two+ unwired -> fail, both listed, wired one not listed
+mk bad
+for n in a b c d; do : > "$T/bad/scripts/$n.test.sh"; done
+printf 'run: bash scripts/a.test.sh\n' > "$T/bad/wf/x.yml"
+check 1 "UNWIRED: b.test.sh" "UNWIRED: a.test.sh" "unwired b reported, wired a not" "$T/bad/scripts" "$T/bad/wf"
+check 1 "UNWIRED: c.test.sh" - "unwired c reported too" "$T/bad/scripts" "$T/bad/wf"
+check 1 "UNWIRED: d.test.sh" - "unwired d reported too" "$T/bad/scripts" "$T/bad/wf"
+check 1 "3 of 4" - "summary counts every offender" "$T/bad/scripts" "$T/bad/wf"
+
+# 3. substring of a longer name does not satisfy the match
+mk sub
+: > "$T/sub/scripts/foo.test.sh"
+printf 'run: bash scripts/barfoo.test.sh\nrun: bash scripts/foo.test.sh.bak\nrun: bash scripts/foo-test-sh\n' > "$T/sub/wf/x.yml"
+check 1 "UNWIRED: foo.test.sh" - "longer-name substring is not a match" "$T/sub/scripts" "$T/sub/wf"
+
+# 4. '.' is literal, not a regex wildcard
+mk dot
+: > "$T/dot/scripts/foo.test.sh"
+printf 'run: bash scripts/fooXtestYsh\n' > "$T/dot/wf/x.yml"
+check 1 "UNWIRED: foo.test.sh" - "dot is not a wildcard" "$T/dot/scripts" "$T/dot/wf"
+
+# 5. reference in a second workflow file counts
+mk multi
+: > "$T/multi/scripts/a.test.sh"
+printf 'name: one\n' > "$T/multi/wf/one.yml"
+printf 'run: bash scripts/a.test.sh\n' > "$T/multi/wf/two.yaml"
+check 0 "wired" - "reference in any workflow counts" "$T/multi/scripts" "$T/multi/wf"
+
+# 6. empty / missing workflows dir fails
+mk empty
+: > "$T/empty/scripts/a.test.sh"
+check 1 "no workflow files" - "empty workflows dir fails" "$T/empty/scripts" "$T/empty/wf"
+check 1 "workflows dir not found" - "missing workflows dir fails" "$T/empty/scripts" "$T/empty/nope"
+
+# 7. missing scripts dir is a usage error
+check 2 "scripts dir not found" - "missing scripts dir fails" "$T/nope" "$T/empty/wf"
+
+echo "check-test-wiring.test.sh: passed=$pass failed=$fail"
+[ "$fail" -eq 0 ]