forgedock 1.12.0 → 1.13.0

package/scripts/review-delta.test.sh

@@ -0,0 +1,213 @@
+#!/usr/bin/env bash
+# review-delta.test.sh — fixture cases for scripts/review-delta.sh (forge#3636).
+# Real git repos (local bare origin), synthetic comment JSON, and the REAL scripts/trusted-comments.sh.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+RD="$ROOT/scripts/review-delta.sh"
+TC="$ROOT/scripts/trusted-comments.sh"
+PASS=0; FAILN=0
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+command -v jq >/dev/null 2>&1 || { echo "review-delta.test.sh: jq missing, skipped"; exit 0; }
+command -v git >/dev/null 2>&1 || { echo "review-delta.test.sh: git missing, skipped"; exit 0; }
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+
+# hermetic git: no user config, hooks or signing
+export GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_SYSTEM=/dev/null GIT_CONFIG_NOSYSTEM=1
+export GIT_AUTHOR_NAME=t GIT_AUTHOR_EMAIL=t@example.invalid GIT_COMMITTER_NAME=t GIT_COMMITTER_EMAIL=t@example.invalid
+g() { git -C "$W" -c commit.gpgsign=false -c core.hooksPath=/dev/null "$@"; }
+commit() { # file content msg
+  mkdir -p "$W/$(dirname "$1")"; printf '%s\n' "$2" > "$W/$1"; g add -A >/dev/null; g commit -q -m "$3" >/dev/null
+}
+
+CASE=0
+mkrepo() { # sets W; main has a.txt, origin/main fetched, branch feat checked out with one PR commit
+  CASE=$((CASE+1)); local o="$TMP/o$CASE"; W="$TMP/w$CASE"
+  git init -q --bare -b main "$o"
+  git clone -q "$o" "$W" 2>/dev/null
+  g checkout -q -b main 2>/dev/null
+  commit a.txt "base" "base"
+  g push -q origin main
+  g checkout -q -b feat
+  commit pr.txt "pr1" "pr1"
+}
+sha() { g rev-parse "$1"; }
+base_advance() { # file content -> new commit on origin/main, fetched
+  g checkout -q main; commit "$1" "$2" "base: $1"; g push -q origin main; g checkout -q feat; g fetch -q origin
+}
+
+# --- comment fixtures
+body_agent() { printf '<!-- FORGE:REVIEW-AGENT:%s -->\nReviewed-SHA: %s\n\n<!-- REVIEW-FINDINGS-START -->\nNo findings.\n<!-- REVIEW-FINDINGS-END -->' "$1" "$2"; }
+body_synth() { printf '<!-- REVIEW-FINDINGS-SYNTHESIZED-START -->\nReviewed-SHA: %s\n\nsynth' "$1"; }
+body_summary() { printf '# PR Review Summary\n\n**Reviewed commit**: `%s` | **Current HEAD**: `%s` | **Status**: CURRENT\n**Domains**: x | **Agents**: %s (x)\n' "$1" "$1" "$2"; }
+cm() { jq -n --arg b "$1" --arg t "${2:-Bot}" --arg a "${3:-NONE}" '{"body":$b,"author_association":$a,"user":{"type":$t,"login":"x"}}'; }
+# comments <comment-json>... -> JSON array file path in $CF
+comments() { CF="$TMP/c$CASE.json"; printf '%s\n' "$@" | jq -s '.' > "$CF"; }
+panel() { # full proven panel for sha: 2 agents + synthesized body
+  comments "$(cm "$(body_agent security "$1")")" "$(cm "$(body_agent api "$1")")" "$(cm "$(body_synth "$1")")"
+}
+
+run_rd() { # prints stdout; args after the fixed set are appended
+  (cd "$W" && bash "$RD" --pr 1 --head "$HEAD" --base main --trusted-script "$TC" --comments-file "$CF" --labels "" "$@" 2>&1)
+}
+expect() { # name expected-line1 [expected-rounds]
+  local out l1 l2; out=$(run_rd "${@:4}"); l1=$(printf '%s\n' "$out" | sed -n 1p); l2=$(printf '%s\n' "$out" | sed -n 2p)
+  [ "$l1" = "$2" ] && ok || bad "$1: expected '$2', got '$l1'"
+  if [ -n "${3-}" ]; then [ "$l2" = "FULL_ROUNDS=$3" ] && ok || bad "$1: expected FULL_ROUNDS=$3, got '$l2'"; fi
+}
+
+# 1. ancestor delta -> DELTA
+mkrepo; R=$(sha HEAD); commit pr.txt "pr2" "pr2"; HEAD=$(sha HEAD); panel "$R"
+expect "ancestor delta" "DELTA $R..$HEAD" 1
+
+# 2. head == reviewed -> empty delta, documented as DELTA
+mkrepo; R=$(sha HEAD); HEAD=$R; panel "$R"
+expect "head == reviewed" "DELTA $R..$R" 1
+
+# 3. force-push / rebase -> FULL
+mkrepo; R=$(sha HEAD); panel "$R"; g reset -q --hard HEAD~1; commit pr.txt "rewritten" "rewritten"; HEAD=$(sha HEAD)
+expect "force-push (reviewed not an ancestor)" "FULL" 1
+mkrepo; R=$(sha HEAD); panel "$R"; base_advance b.txt "b1"; g rebase -q origin/main >/dev/null 2>&1; HEAD=$(sha HEAD)
+expect "rebase onto new base" "FULL" 1
+
+# 4. clean base merge -> BASE_SYNC_ONLY
+mkrepo; R=$(sha HEAD); panel "$R"; base_advance b.txt "b1"; g merge -q --no-ff -m "merge main" origin/main >/dev/null 2>&1; HEAD=$(sha HEAD)
+expect "clean base merge" "BASE_SYNC_ONLY $R" 1
+
+# 5. base merge with a conflict-resolution edit -> not BASE_SYNC_ONLY
+mkrepo; commit shared.txt "line" "shared"; g push -q origin feat; R=$(sha HEAD); panel "$R"
+g checkout -q main; commit shared.txt "base side" "base edits shared"; g push -q origin main; g checkout -q feat; g fetch -q origin
+commit shared.txt "feat side" "feat edits shared"; R=$(sha HEAD); panel "$R"
+g merge -q --no-ff origin/main >/dev/null 2>&1; printf 'resolved\n' > "$W/shared.txt"; g add -A >/dev/null; g commit -q -m "merge main (resolved)" >/dev/null; HEAD=$(sha HEAD)
+out=$(run_rd | sed -n 1p); case "$out" in BASE_SYNC_ONLY*) bad "conflict-resolution merge must not be BASE_SYNC_ONLY (got $out)" ;; *) ok ;; esac
+
+# 6. mixed: base merge plus a regular commit -> DELTA
+mkrepo; R=$(sha HEAD); panel "$R"; base_advance b.txt "b1"; g merge -q --no-ff -m "merge main" origin/main >/dev/null 2>&1; commit pr.txt "pr2" "pr2"; HEAD=$(sha HEAD)
+expect "base merge plus regular commit" "DELTA $R..$HEAD" 1
+
+# 6b. merge of a non-base branch -> DELTA
+mkrepo; R=$(sha HEAD); panel "$R"; g checkout -q -b other; commit o.txt "o" "other"; g checkout -q feat; g merge -q --no-ff -m "merge other" other >/dev/null 2>&1; HEAD=$(sha HEAD)
+expect "merge of a non-base branch" "DELTA $R..$HEAD" 1
+
+# 6c. crafted base "merge" whose second parent is an OLD base commit, reverting a binary file or a mode to that
+# old version. diff-tree --cc is empty (result equals the second parent) and the 3-dot diffs have identical +/-
+# lines, so only the per-path shape (binary blob ids, modes) can tell the PR change moved.
+crafted_merge() { # path-from-old-base -> HEAD = merge(R, old base) taking that one path from the old base
+  local tree; g checkout -q "$OLD_B" -- "$1"; tree=$(g write-tree); HEAD=$(g commit-tree "$tree" -p "$R" -p "$OLD_B" -m "merge main")
+  g reset -q --hard "$HEAD"
+}
+mkrepo; g checkout -q main; printf '\000\001v1' > "$W/img.bin"; g add -A >/dev/null; g commit -q -m "img v1" >/dev/null; OLD_B=$(sha HEAD)
+printf '\000\001v2' > "$W/img.bin"; g add -A >/dev/null; g commit -q -m "img v2" >/dev/null; g push -q origin main; g fetch -q origin
+g checkout -q feat; g merge -q --no-ff -m "sync" origin/main >/dev/null 2>&1; R=$(sha HEAD); panel "$R"
+crafted_merge img.bin
+expect "crafted merge reverting a binary file" "DELTA $R..$HEAD" 1
+# binary the PR already changes, swapped for the old base's bytes: same path set and modes, only the blob id differs
+mkrepo; g checkout -q main; printf '\000\001v1' > "$W/img.bin"; g add -A >/dev/null; g commit -q -m "img v1" >/dev/null; OLD_B=$(sha HEAD)
+printf '\000\001v2' > "$W/img.bin"; g add -A >/dev/null; g commit -q -m "img v2" >/dev/null; g push -q origin main; g fetch -q origin
+g checkout -q feat; g merge -q --no-ff -m "sync" origin/main >/dev/null 2>&1
+printf '\000\001pr' > "$W/img.bin"; g add -A >/dev/null; g commit -q -m "pr img" >/dev/null; R=$(sha HEAD); panel "$R"
+crafted_merge img.bin
+expect "crafted merge swapping a PR-changed binary" "DELTA $R..$HEAD" 1
+mkrepo; g checkout -q main; chmod +x "$W/a.txt"; g add -A >/dev/null; g commit -q -m "a 755" >/dev/null; OLD_B=$(sha HEAD)
+chmod -x "$W/a.txt"; g add -A >/dev/null; g commit -q -m "a 644" >/dev/null; g push -q origin main; g fetch -q origin
+g checkout -q feat; g merge -q --no-ff -m "sync" origin/main >/dev/null 2>&1; R=$(sha HEAD); panel "$R"
+crafted_merge a.txt
+expect "crafted merge reverting a file mode" "DELTA $R..$HEAD" 1
+
+# 7. spec / config changes in the delta -> FULL
+for f in forge.yaml commands/review-pr.md commands/review-pr-agents.md commands/review-pr-agents/x.md scripts/review-delta.sh scripts/trusted-comments.sh; do
+  mkrepo; R=$(sha HEAD); panel "$R"; commit "$f" "changed" "touch $f"; HEAD=$(sha HEAD)
+  expect "$f changed in delta" "FULL" 1
+done
+
+# 8. checkpoint trust and shape
+mkrepo; R=$(sha HEAD); commit pr.txt "pr2" "pr2"; HEAD=$(sha HEAD)
+comments "$(cm "$(body_agent security "$R")" User NONE)" "$(cm "$(body_agent api "$R")" User NONE)" "$(cm "$(body_synth "$R")" User NONE)"
+expect "untrusted reviewer comments" "FULL" 0
+comments "$(cm "$(body_agent security "$R")" User MEMBER)" "$(cm "$(body_synth "$R")" User MEMBER)"
+expect "trusted by author_association" "DELTA $R..$HEAD" 1
+comments "$(cm "<!-- FORGE:REVIEW_ROUTE mode=single-pr spec=review-pr.md sha=${R:0:7} -->")"
+expect "7-char ROUTE sha is never a checkpoint" "FULL" 0
+comments "$(cm "$(body_agent security "${R:0:7}")")" "$(cm "$(body_synth "${R:0:7}")")"
+expect "7-char Reviewed-SHA is never a checkpoint" "FULL" 0
+comments "$(cm "$(body_agent security "$R")")" "$(cm "$(body_agent api "$R")")"
+expect "agent bodies without the post-guard proof (partial panel)" "FULL" 0
+comments "$(cm "$(body_agent security "$R")")" "$(cm "$(body_summary "$R" 2)")"
+expect "summary Agents count above distinct domains" "FULL" 0
+comments "$(cm "$(body_agent security "$R")")" "$(cm "$(body_agent api "$R")")" "$(cm "$(body_summary "$R" 2)")"
+expect "summary Agents count equal to distinct domains" "DELTA $R..$HEAD" 1
+comments "$(cm "<!-- FORGE:REVIEW-AGENT:security -->
+Reviewed-SHA: $R
+
+no findings block")" "$(cm "$(body_synth "$R")")"
+expect "agent body without REVIEW-FINDINGS-START" "FULL" 0
+comments "$(cm "$(body_agent security "$R")")" "$(cm "$(body_synth "$R")")" "$(cm "<!-- FORGE:GATE_FAILURE:TYPE=review-panel-integrity -->
+panel degraded")"
+expect "review-panel-integrity gate failure after the agents" "FULL" 0
+comments "$(cm "<!-- FORGE:REVIEW_DEGRADED -->")" "$(cm "$(body_agent security "$R")")" "$(cm "$(body_synth "$R")")"
+expect "degraded marker before the agents does not disqualify" "DELTA $R..$HEAD" 1
+comments "$(cm "$(body_agent security "$R")")" "$(cm "$(body_synth "$R")")" "$(cm "<!-- FORGE:REVIEW_BLOCKED -->")"
+expect "REVIEW_BLOCKED after the agents" "FULL" 0
+panel "$R"
+expect "review-degraded label" "FULL" 0 --labels "needs-human,review-degraded"
+# --labels given twice: last wins in the parser, so use a fresh invocation without the fixed --labels
+out=$(cd "$W" && bash "$RD" --pr 1 --head "$HEAD" --base main --trusted-script "$TC" --comments-file "$CF" --labels "bug,docs" 2>&1 | sed -n 1p)
+[ "$out" = "DELTA $R..$HEAD" ] && ok || bad "unrelated labels must not force FULL (got $out)"
+
+# 9. FULL_ROUNDS
+mkrepo; R1=$(sha HEAD); commit pr.txt "pr2" "pr2"; R2=$(sha HEAD); commit pr.txt "pr3" "pr3"; HEAD=$(sha HEAD)
+comments "$(cm "$(body_agent security "$R1")")" "$(cm "$(body_synth "$R1")")" \
+         "$(cm "$(body_agent security "$R2")")" "$(cm "$(body_synth "$R2")")"
+expect "two complete SHAs: newest is the checkpoint, FULL_ROUNDS=2" "DELTA $R2..$HEAD" 2
+comments "$(cm "$(body_agent security "$R1")")" "$(cm "$(body_synth "$R1")")" "$(cm "$(body_agent api "$R1")")" \
+         "$(cm "$(body_agent security "$R2")")" "$(cm "$(body_synth "$R2")")" "$(cm "$(body_synth "$R2")")"
+expect "duplicate SHA counted once" "DELTA $R2..$HEAD" 2
+comments "$(cm "$(body_agent security "$R1")")" "$(cm "$(body_synth "$R1")")" "$(cm "$(body_agent security "$R2")")"
+expect "partial SHA ignored in FULL_ROUNDS" "DELTA $R1..$HEAD" 1
+
+# 10. error paths all print FULL (+ FULL_ROUNDS line)
+mkrepo; R=$(sha HEAD); commit pr.txt "pr2" "pr2"; HEAD=$(sha HEAD); panel "$R"
+expect "relative --trusted-script" "FULL" "" --trusted-script "scripts/trusted-comments.sh"
+out=$(run_rd --trusted-script "scripts/trusted-comments.sh" | sed -n 2p); case "$out" in FULL_ROUNDS=*) ok ;; *) bad "error path must print a FULL_ROUNDS line (got '$out')" ;; esac
+expect "nonexistent --trusted-script" "FULL" "" --trusted-script "$TMP/nope.sh"
+printf '#!/usr/bin/env bash\nexit 2\n' > "$TMP/tc-fail.sh"
+expect "trust script exits 2" "FULL" 0 --trusted-script "$TMP/tc-fail.sh"
+expect "unreadable comments file" "FULL" 0 --comments-file "$TMP/missing.json"
+: > "$TMP/empty.json"
+expect "empty comments file" "FULL" 0 --comments-file "$TMP/empty.json"
+printf 'not json' > "$TMP/bad.json"
+expect "malformed comments JSON" "FULL" 0 --comments-file "$TMP/bad.json"
+BADHEAD=$HEAD; HEAD="${HEAD:0:7}"; expect "7-char --head" "FULL" ""; HEAD="ZZZ"; expect "malformed --head" "FULL" ""; HEAD=$BADHEAD
+out=$(cd "$W" && bash "$RD" --pr x --head "$HEAD" --base main --trusted-script "$TC" --comments-file "$CF" --labels "" 2>&1 | sed -n 1p); [ "$out" = FULL ] && ok || bad "non-numeric --pr (got $out)"
+out=$(cd "$W" && bash "$RD" --pr 1 --head "$HEAD" --base "--evil" --trusted-script "$TC" --comments-file "$CF" --labels "" 2>&1 | sed -n 1p); [ "$out" = FULL ] && ok || bad "option-like --base (got $out)"
+out=$(cd "$W" && bash "$RD" --bogus 2>&1 | sed -n 1p); [ "$out" = FULL ] && ok || bad "unknown flag (got $out)"
+out=$(cd "$W" && bash "$RD" 2>&1 | sed -n 1p); [ "$out" = FULL ] && ok || bad "no args (got $out)"
+out=$(cd "$W" && bash "$RD" --pr 1 --head "$HEAD" --base main --trusted-script "$TC" --comments-file "$CF" 2>&1 | sed -n 1p); [ "$out" = FULL ] && ok || bad "labels neither given nor fetchable (got $out)"
+out=$(cd "$W" && bash "$RD" --pr 1 --head "$HEAD" --base nosuchbranch --trusted-script "$TC" --comments-file "$CF" --labels "" 2>&1 | sed -n 1p); [ "$out" = FULL ] && ok || bad "missing origin/<base> (got $out)"
+# unknown reviewed object: the checkpoint names a well-formed SHA that is not in the repo
+GHOST=0123456789abcdef0123456789abcdef01234567; panel "$GHOST"
+expect "unknown reviewed object" "FULL" 1
+# not a git repo
+panel "$R"; NOGIT="$TMP/nogit"; mkdir -p "$NOGIT"
+out=$(bash "$RD" --pr 1 --head "$HEAD" --base main --trusted-script "$TC" --comments-file "$CF" --labels "" --repo-path "$NOGIT" 2>&1 | sed -n 1p); [ "$out" = FULL ] && ok || bad "not a git repo (got $out)"
+
+# 11. pagination shape: two concatenated arrays
+CF="$TMP/paged.json"; { printf '[%s]\n' "$(cm "$(body_agent security "$R")")"; printf '[%s]\n' "$(cm "$(body_synth "$R")")"; } > "$CF"
+expect "concatenated pagination arrays" "DELTA $R..$HEAD" 1
+
+# 12. 64-hex (sha256) checkpoints are accepted shape-wise
+mkrepo; R=$(sha HEAD); commit pr.txt "pr2" "pr2"; HEAD=$(sha HEAD)
+R64="${R}0123456789abcdef01234567"; R64=${R64:0:64}; panel "$R64"
+expect "64-hex checkpoint not in repo -> FULL (validated, then unknown object)" "FULL" 1
+
+# 13. trust script is never taken from the cwd: a planted copy must not change the verdict
+mkrepo; R=$(sha HEAD); commit pr.txt "pr2" "pr2"; HEAD=$(sha HEAD)
+comments "$(cm "$(body_agent security "$R")" User NONE)" "$(cm "$(body_synth "$R")" User NONE)"
+mkdir -p "$W/scripts"; printf '#!/usr/bin/env bash\ncat >/dev/null; jq -c . <<< "\\"$1\\""\n' > "$W/scripts/trusted-comments.sh"
+out=$(cd "$W" && bash "$RD" --pr 1 --head "$HEAD" --base main --trusted-script "$TC" --comments-file "$CF" --labels "" 2>&1 | sed -n 1p)
+[ "$out" = FULL ] && ok || bad "planted cwd trust script must be ignored (got $out)"
+
+echo "review-delta tests: pass=$PASS fail=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/review-pr-domain-map.test.sh

@@ -0,0 +1,87 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Guards the review-pr roster-label to marker-domain mapping: every roster spelling collapses to one marker
+# domain, the helper is identical wherever it is inlined, the roster dedups across spellings, and every
+# persona file is covered by the table and the catalog. Run: bash scripts/review-pr-domain-map.test.sh
+# (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+ROOT=$(cd "$DIR/.." && pwd)
+SPEC="$ROOT/commands/review-pr.md"
+CATALOG="$ROOT/commands/review-pr-agents.md"
+PERSONAS="$ROOT/commands/review-pr-agents"
+pass=0; fail=0
+ok() { pass=$((pass+1)); }
+bad() { fail=$((fail+1)); echo "FAIL: $1"; }
+
+WORK=$(mktemp -d "${TMPDIR:-/tmp}/review-pr-domain-map.XXXXXX")
+trap 'rm -rf "$WORK"' EXIT
+
+# Test 1: helper copies. Every inline definition must be byte-identical (each Bash call is a fresh shell).
+awk -v dir="$WORK" '
+  /^# BEGIN review-pr-agent-domain/ {n++; out=dir "/helper." n; on=1}
+  on {print > out}
+  /^# END review-pr-agent-domain/ {on=0; close(out)}
+' "$SPEC"
+copies=$(ls "$WORK"/helper.* 2>/dev/null | wc -l | tr -d ' ')
+if [ "$copies" -ge 4 ]; then ok; else bad "expected >=4 inline agent_domain copies (roster, canonicalize, dispatch, phase 4), found $copies"; fi
+for f in "$WORK"/helper.*; do
+  [ -f "$f" ] || continue
+  if cmp -s "$f" "$WORK/helper.1"; then ok; else bad "$(basename "$f") differs from helper.1"; fi
+done
+
+# Test 2: no site derives the marker by lowercasing the roster label directly
+if grep -nE "AGENT_DOMAIN=.*tr '\[:upper:\]' '\[:lower:\]'" "$SPEC" >/dev/null; then bad "direct lowercase marker derivation remains"; else ok; fi
+sites=$(grep -c 'AGENT_DOMAIN=$(agent_domain "$AGENT")' "$SPEC")
+if [ "$sites" -ge 2 ]; then ok; else bad "expected >=2 agent_domain derivation sites, found $sites"; fi
+
+# Test 3: spelling collapse
+# shellcheck disable=SC1090
+. "$WORK/helper.1"
+check() { got=$(agent_domain "$1"); if [ "$got" = "$2" ]; then ok; else bad "agent_domain '$1' = '$got', want '$2'"; fi; }
+for l in INFRA Infrastructure infra infrastructure; do check "$l" infra; done
+for l in SCRAPING Scraping scraper Scraper scraping; do check "$l" scraper; done
+for l in FRONTEND Frontend frontend Web; do check "$l" frontend; done
+for l in Security SECURITY; do check "$l" security; done
+for l in AUTH Auth; do check "$l" auth; done
+for l in BILLING Billing; do check "$l" billing; done
+for l in CONCURRENCY Concurrency; do check "$l" concurrency; done
+for l in DATABASE Database; do check "$l" database; done
+for l in API Api; do check "$l" api; done
+check "CustomDomain" customdomain
+
+# Test 4: add_agent dedups across spellings; canonicalization block yields one entry per persona
+ADD=$(awk '/^add_agent\(\) \{/{on=1} on{print} on && /^\}/{exit}' "$SPEC")
+if [ -n "$ADD" ]; then ok; else bad "add_agent not found in spec"; fi
+eval "$ADD"
+SELECTED_AGENTS="Security INFRA SCRAPING"
+add_agent "Infrastructure"; add_agent "Scraping"; add_agent "Auth"; add_agent "AUTH"; add_agent "security"
+want=$(printf '%s' "Security INFRA SCRAPING auth")
+if [ "$SELECTED_AGENTS" = "$want" ]; then ok; else bad "add_agent roster '$SELECTED_AGENTS', want '$want'"; fi
+
+CANON=$(awk '/^# END review-pr-agent-domain/{seen++} seen && /^CANON_ROSTER=/{on=1} on{print} on && /^SELECTED_AGENTS=/{exit}' "$SPEC" | head -20)
+SELECTED_AGENTS="Security AUTH INFRA Infrastructure SCRAPING Scraping Frontend API api"
+eval "$CANON"
+want="security auth infra scraper frontend api"
+if [ "$SELECTED_AGENTS" = "$want" ]; then ok; else bad "canonical roster '$SELECTED_AGENTS', want '$want'"; fi
+cnt=$(printf '%s' "$SELECTED_AGENTS" | tr ' ' '\n' | grep -c '.')
+if [ "$cnt" -eq 6 ]; then ok; else bad "roster count $cnt, want 6"; fi
+
+# Test 5: every persona file (minus protocols and spec-cli) has a table row in the spec and a catalog row
+for pf in "$PERSONAS"/*.md; do
+  name=$(basename "$pf" .md)
+  case "$name" in protocols|spec-cli) continue ;; esac
+  if grep -qE "^\| .*\| \`$name\` \| \`$name\.md\` \|" "$SPEC"; then ok; else bad "spec table has no row for persona $name"; fi
+  if grep -qE "^\| .*\| \`$name\` \| \`review-pr-agents/$name\.md\` \|" "$CATALOG"; then ok; else bad "catalog has no marker-domain row for persona $name"; fi
+  got=$(agent_domain "$name")
+  if [ "$got" = "$name" ]; then ok; else bad "persona $name maps to $got"; fi
+done
+
+# Test 6: the protocol defines the marker domain through the mapping
+if grep -qF 'marker domain' "$PERSONAS/protocols.md"; then ok; else bad "protocols.md does not define the marker domain"; fi
+
+echo "review-pr-domain-map: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/scripts/review-pr-gate2.test.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# review-pr-gate2.test.sh — cases for the review-pr §6B.4 gate-2 sketch (forge#3597, #3598).
+# Extracts the fenced bash block from commands/review-pr.md, runs its set-up against a stubbed
+# `gh`, then applies the per-finding rules the block documents (gone, no patch, introduced, severity).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SPEC="$ROOT/commands/review-pr.md"
+PASS=0; FAILN=0
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+command -v jq >/dev/null 2>&1 || { echo "review-pr-gate2.test.sh: jq missing, skipped"; exit 0; }
+
+# Extract the sketch: the fenced block that declares NOPATCH_FILES_FILE, minus comment-only lines.
+awk '/^```bash$/{b="";in_b=1;next} /^```$/{if(in_b&&b~/NOPATCH_FILES_FILE=/)printf "%s",b; in_b=0;next} in_b{b=b $0 "\n"}' "$SPEC" \
+  | grep -v '^#' > "$TMP/sketch.sh"
+if [ -s "$TMP/sketch.sh" ]; then ok; else bad "sketch block not found in review-pr.md"; echo "review-pr-gate2.test.sh: failed=$FAILN"; exit 1; fi
+
+# Fixture files API: a.sh patch adds line 10; big.txt has no patch; gone.txt removed.
+cat > "$TMP/files.json" <<'JSON'
+[{"filename":"a.sh","status":"modified","patch":"@@ -9,2 +9,3 @@\n ctx\n+added\n ctx"},
+ {"filename":"big.txt","status":"modified"},
+ {"filename":"gone.txt","status":"removed"},
+ {"filename":"new.sh","status":"renamed","previous_filename":"old.sh","patch":"@@ -1,1 +1,1 @@\n+x"}]
+JSON
+mkdir "$TMP/bin"
+printf '#!/bin/sh\ncat "%s/files.json"\n' "$TMP" > "$TMP/bin/gh"; chmod +x "$TMP/bin/gh"
+
+# Spec's executable severity rule: the SEV= line and the case line from the sketch comments, comment marker stripped.
+grep -E '^#[[:space:]]+(SEV=|case "\$SEV" in)' "$SPEC" | sed -e 's/^#[[:space:]]*//' -e 's/[[:space:]]*#.*$//' > "$TMP/rule.sh"
+if [ "$(wc -l < "$TMP/rule.sh")" -eq 2 ]; then ok; else bad "severity rule lines not found in review-pr.md"; fi
+
+{
+  printf 'export PATH="%s/bin:$PATH" FORGE_SCRATCHPAD="%s"\n' "$TMP" "$TMP"
+  printf 'SEVERITY_RULE=%q\n' "$(cat "$TMP/rule.sh")"
+  sed -e 's/{GH_REPO}/o\/r/; s/{PR_NUMBER}/1/; s/{REVIEW_SHA}/0123456789abcdef0123456789abcdef01234567/' "$TMP/sketch.sh"
+  cat <<'CLASSIFY'
+# classify FILE LINE SEVERITY -> KEEP | pre-existing (mirrors the per-finding rules in the sketch comments)
+classify() {
+  FILE="$1"; LINE="$2"; SEVERITY="$3"; INTRODUCED=0
+  grep -qxF -- "$FILE" "$GONE_FILES_FILE" && { echo KEEP; return; }
+  grep -qxF -- "$FILE" "$NOPATCH_FILES_FILE" && { echo KEEP; return; }
+  LO=$((LINE>5?LINE-5:1))
+  for L in $(seq "$LO" $((LINE+5))); do grep -qxF -- "${FILE}:${L}" "$ADDED_LINES_FILE" && INTRODUCED=1; done
+  SCOPE=changed
+  # The severity rule is the spec's own line (extracted below), not a re-implementation.
+  eval "$SEVERITY_RULE"
+  if [ "$SCOPE" = pre-existing ]; then echo pre-existing; else echo KEEP; fi
+}
+classify "$@"
+CLASSIFY
+} > "$TMP/run.sh"
+
+check() { # name want file line severity
+  local got; got="$(bash "$TMP/run.sh" "$3" "$4" "$5" 2>&1 | tail -n1)"
+  if [ "$got" = "$2" ]; then ok; else bad "$1 (got '$got' want '$2')"; fi
+}
+check "added line intersects"            KEEP         a.sh    10  MEDIUM
+check "MEDIUM far from added -> pre"     pre-existing a.sh    100 MEDIUM
+check "HIGH far from added kept"         KEEP         a.sh    100 HIGH
+check "CRITICAL far from added kept"     KEEP         a.sh    100 CRITICAL
+check "null-patch file MEDIUM kept"      KEEP         big.txt 3   MEDIUM
+check "lowercase high kept"              KEEP         a.sh    100 high
+check "padded HIGH kept"                 KEEP         a.sh    100 "HIGH "
+check "empty severity kept"              KEEP         a.sh    100 ""
+check "unparseable severity kept"        KEEP         a.sh    100 "SEVERE"
+check "lowercase medium -> pre"          pre-existing a.sh    100 medium
+check "INFO far from added -> pre"       pre-existing a.sh    100 INFO
+check "renamed file kept"                KEEP         old.sh  3   MEDIUM
+check "patched file still pre w/ nopatch sibling" pre-existing a.sh 100 LOW
+check "removed file kept"                KEEP         gone.txt 3  LOW
+check "file absent from diff MEDIUM pre" pre-existing other.sh 5  MEDIUM
+if grep -qF 'select(.patch == null' "$SPEC"; then ok; else bad "spec lacks null-patch selector"; fi
+
+# Mirrored wording must stay in sync across the spec family.
+for f in commands/review-pr-staging.md commands/review-pr-agents/protocols.md docs/spec/review-protocol.md; do
+  if grep -qiE 'CRITICAL/HIGH.*never routed as pre-existing' "$ROOT/$f"; then ok; else bad "$f lacks the CRITICAL/HIGH never-pre-existing rule"; fi
+done
+if grep -qF 'only known low severities' "$SPEC"; then ok; else bad "spec lacks inverted severity rule comment"; fi
+
+echo "review-pr-gate2.test.sh: passed=$PASS failed=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/review-pr-staging-scope.test.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# review-pr-staging-scope.test.sh — cases for the review-pr-staging scoped-review gates (forge#3451):
+#   (1) the 7B out-of-scope rule may only demote MEDIUM/LOW/INFO, never HIGH/CRITICAL or unknown severity;
+#   (2) the 0B.1 "reviewed" test needs the full-length Reviewed-SHA line, not a 7-char substring.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SPEC="$ROOT/commands/review-pr-staging.md"
+TC="$ROOT/scripts/trusted-comments.sh"
+PASS=0; FAILN=0
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+command -v jq >/dev/null 2>&1 || { echo "review-pr-staging-scope.test.sh: jq missing, skipped"; exit 0; }
+TMP="$(mktemp -d)"; trap 'rm -rf "$TMP"' EXIT
+
+# (1) severity rule: the two SCOPE_RULE lines, marker stripped
+grep -E '# SCOPE_RULE$' "$SPEC" | sed 's/[[:space:]]*# SCOPE_RULE$//; s/^[[:space:]]*//' > "$TMP/rule.sh"
+if [ "$(wc -l < "$TMP/rule.sh")" -eq 2 ]; then ok; else bad "SCOPE_RULE lines not found (expected 2)"; fi
+demote() { FINDING_SEVERITY="$1"; OOS_DEMOTE=; eval "$(cat "$TMP/rule.sh")"; echo "$OOS_DEMOTE"; }
+chk() { [ "$(demote "$1")" = "$2" ] && ok || bad "severity '$1' expected demote=$2"; }
+chk HIGH 0; chk high 0; chk " High " 0; chk CRITICAL 0; chk critical 0
+chk MEDIUM 1; chk medium 1; chk LOW 1; chk INFO 1
+chk "" 0; chk "SEVERE" 0; chk "HIGH/MEDIUM" 0
+
+# (2) full-sha reviewed test: the _AGENT regex from the spec, run through the real trusted-comments predicate
+LINE=$(grep -E '^[[:space:]]*_AGENT=' "$SPEC" | head -1)
+RE=$(printf '%s' "$LINE" | sed -n 's/.*count "\(.*\)") ||.*/\1/p')
+if [ -n "$RE" ]; then ok; else bad "_AGENT regex not found in review-pr-staging.md"; fi
+FULL=0123456789abcdef0123456789abcdef01234567; SHORT=${FULL:0:7}
+RE=${RE//\\\\/\\}; RE=${RE//\$\{_HEAD\}/$FULL}
+FB=$'<!-- REVIEW-FINDINGS-START -->\nNo findings.\n<!-- REVIEW-FINDINGS-END -->'
+mk() { jq -n --arg b "$1" --arg t "$2" '[{"body":$b,"author_association":"NONE","user":{"type":$t,"login":"x"}}]'; }
+cnt() { bash "$TC" count "$RE"; }
+[ "$(mk $'<!-- FORGE:REVIEW-AGENT:security -->\nReviewed-SHA: '"$FULL"$'\n\n'"$FB" Bot | cnt)" = 1 ] && ok || bad "full Reviewed-SHA line should count"
+[ "$(mk $'<!-- FORGE:REVIEW-AGENT:security -->\nreviewed '"$SHORT"' only' Bot | cnt)" = 0 ] && ok || bad "7-char substring must not count"
+[ "$(mk $'<!-- FORGE:REVIEW-AGENT:security -->\nReviewed-SHA: '"$SHORT"$'\n' Bot | cnt)" = 0 ] && ok || bad "short Reviewed-SHA must not count"
+[ "$(mk $'<!-- FORGE:REVIEW-AGENT:security -->\nReviewed-SHA: '"${FULL}"$'ff\n'"$FB" Bot | cnt)" = 0 ] && ok || bad "longer sha must not count"
+[ "$(mk $'<!-- FORGE:REVIEW-AGENT:security -->\nReviewed-SHA: '"$FULL"$'\n'"$FB" User | cnt)" = 0 ] && ok || bad "untrusted author must not count"
+[ "$(mk $'<!-- FORGE:REVIEW-AGENT:security -->\nReviewed-SHA: '"$FULL"$'\n\nno findings block here' Bot | cnt)" = 0 ] && ok || bad "comment without a findings block must not count (panel integrity)"
+
+# (3) _ROUTE regex: real mode on the final head counts, spec-evolution-blocked and a stale sha do not
+RLINE=$(grep -E '^[[:space:]]*_ROUTE=' "$SPEC" | head -1)
+RRE=$(printf '%s' "$RLINE" | sed -n 's/.*count "\(.*\)") ||.*/\1/p'); RRE=${RRE//\\\\/\\}; RRE=${RRE//\$\{_HEAD7\}/$SHORT}
+rcnt() { bash "$TC" count "$RRE"; }
+[ "$(mk '<!-- FORGE:REVIEW_ROUTE mode=single-pr spec=review-pr.md sha='"$SHORT"' -->' Bot | rcnt)" = 1 ] && ok || bad "route marker on the final head should count"
+[ "$(mk '<!-- FORGE:REVIEW_ROUTE mode=spec-evolution-blocked spec=review-pr.md sha='"$SHORT"' -->' Bot | rcnt)" = 0 ] && ok || bad "spec-evolution-blocked route must not count"
+[ "$(mk '<!-- FORGE:REVIEW_ROUTE mode=single-pr spec=review-pr.md sha=abcdef0 -->' Bot | rcnt)" = 0 ] && ok || bad "stale-sha route must not count"
+
+# (4) spec text guards: agents may not be told to suppress findings; no $PWD tier in the classifier resolver; git reads are status-checked
+if grep -q 'MUST NOT report a defect' "$SPEC"; then bad "Phase 2 must not tell agents to suppress findings (7B owns demotion)"; else ok; fi
+if grep -n 'FINDING_TEXT_FILE=$(mktemp' "$SPEC" >/dev/null && grep -q '> "$FINDING_TEXT_FILE"' "$SPEC"; then ok; else bad "FINDING_TEXT_FILE must be written before the classifier call"; fi
+if awk '/^CLASSIFY_SCRIPT=""/,/^done <<</' "$SPEC" | grep -q 'PWD'; then bad "classifier resolver must have no PWD tier"; else ok; fi
+if grep -qE "^DEPLOY_WIRING_FILES=.*git diff" "$SPEC"; then bad "DEPLOY_WIRING_FILES must not pipe git diff directly"; else ok; fi
+if grep -q 'git diff-tree .*|| { SCOPE_MODE=full' "$SPEC"; then ok; else bad "git diff-tree reads must fall back to full scope"; fi
+if grep -q 'classify_one()' "$SPEC" && grep -q 'REVIEWED_MERGES' "$SPEC" && grep -q '_scope.env' "$SPEC"; then ok; else bad "7B.5 must be a per-finding function with persisted scope state"; fi
+if grep -q 'DUPLICATE: #' "$SPEC" && grep -q 'grep -qF -- "$_SAFE_FILE"' "$SPEC"; then ok; else bad "7E exit 1 must be confirmed by file before skipping"; fi
+# (5) run the spec's classify_one with a stub classifier: HIGH out of scope stays ISSUE; LOW out of scope is demoted and listed; multi-file in-scope is not demoted
+awk '/^classify_one\(\) \{/,/^\}/' "$SPEC" > "$TMP/fn.sh"
+printf '#!/bin/sh\necho "$STUB_DISP"\n' > "$TMP/classify.sh"
+run1() { # severity stub-disposition paths -> prints DISPOSITION
+  ( _SD="$TMP"; PR_NUMBER=9; CLASSIFY_SCRIPT="$TMP/classify.sh"; SCOPE_MODE=scoped; CROSS_PR_FILES="a/in.sh"; UNREVIEWED_FILES=""; DEPLOY_WIRING_FILES=""
+    NOTE_LIST_FILE="$TMP/n.md"; : > "$NOTE_LIST_FILE"; NOTES_LISTED=0; FINDINGS_FILED=0; OUT_OF_SCOPE=0
+    FINDING_ID=X1; FINDING_SEVERITY="$1"; FINDING_CONFIDENCE=CONFIRMED; FINDING_AGENT=Security; FINDING_TITLE=t; FINDING_BODY=b; FINDING_FILE=z/out.sh; FINDING_PATHS="$3"
+    export STUB_DISP="$2"; . "$TMP/fn.sh"; classify_one; echo "$DISPOSITION" ) 2>&1 | tail -1; }
+[ "$(run1 HIGH 'ISSUE severity-HIGH' 'z/out.sh')" = "ISSUE severity-HIGH" ] && ok || bad "HIGH out of scope must stay ISSUE"
+[ "$(run1 high 'ISSUE severity-HIGH' 'z/out.sh')" = "ISSUE severity-HIGH" ] && ok || bad "lowercase high out of scope must stay ISSUE"
+[ "$(run1 LOW 'NOTE LOW-LIKELY' 'z/out.sh')" = "NOTE out_of_scope" ] && ok || bad "LOW out of scope should be demoted and listed"
+[ "$(run1 MEDIUM 'ISSUE MEDIUM-CONFIRMED' 'z/out.sh')" = "NOTE out_of_scope" ] && ok || bad "MEDIUM out of scope should be demoted"
+[ "$(run1 MEDIUM 'ISSUE MEDIUM-CONFIRMED' $'z/out.sh\na/in.sh')" = "ISSUE MEDIUM-CONFIRMED" ] && ok || bad "multi-file finding with an in-scope file must not be demoted"
+[ "$(run1 LOW 'ISSUE safety-exemption-auth' 'z/out.sh')" = "ISSUE safety-exemption-auth" ] && ok || bad "safety-exempt finding must not be demoted"
+# (6) behavioural --text-file: each classify_one call must hand the classifier its OWN finding text (a shared/stale text file would leak the first finding into the second)
+cat > "$TMP/classify-textfile.sh" <<'STUB'
+#!/bin/bash
+tf=""
+while [ $# -gt 0 ]; do case "$1" in --text-file) tf="$2"; shift ;; esac; shift; done
+[ -n "$tf" ] && [ -r "$tf" ] || { echo "NOTE no-text-file"; exit 0; }
+if grep -q 'MARKER_TOKEN' "$tf"; then echo "ISSUE saw-marker"; else echo "NOTE no-marker"; fi
+STUB
+mkdir -p "$TMP/sd6"
+run2() { # prints the dispositions of two consecutive classify_one calls in ONE shell
+  ( _SD="$TMP/sd6"; PR_NUMBER=9; CLASSIFY_SCRIPT="$TMP/classify-textfile.sh"; SCOPE_MODE=full; CROSS_PR_FILES=""; UNREVIEWED_FILES=""; DEPLOY_WIRING_FILES=""
+    NOTE_LIST_FILE="$TMP/n6.md"; : > "$NOTE_LIST_FILE"; NOTES_LISTED=0; FINDINGS_FILED=0; OUT_OF_SCOPE=0
+    FINDING_ID=X1; FINDING_SEVERITY=LOW; FINDING_CONFIDENCE=CONFIRMED; FINDING_AGENT=Security; FINDING_BODY=b; FINDING_FILE=z/a.sh; FINDING_PATHS=z/a.sh
+    . "$TMP/fn.sh"
+    FINDING_TITLE="has MARKER_TOKEN"; classify_one; echo "$DISPOSITION"
+    FINDING_TITLE="plain title"; classify_one; echo "$DISPOSITION"
+    FINDING_TITLE="has MARKER_TOKEN"; classify_one; echo "$DISPOSITION" ) 2>&1
+}
+OUT6=$(run2 | tr '\n' '|')
+[ "$OUT6" = "ISSUE saw-marker|NOTE no-marker|ISSUE saw-marker|" ] && ok || bad "each classify_one call must classify its own text-file content (got '$OUT6')"
+if ls "$TMP/sd6"/staging-finding.* >/dev/null 2>&1; then bad "classify_one must remove its per-finding temp file"; else ok; fi
+# (7) fail-closed guard: BLOCKED when the classifier is unresolvable, no manual classifier mode, no classifier-unavailable fallback
+SPEC_MAIN="$(dirname "$SPEC")/review-pr.md"
+for _s in "$SPEC" "$SPEC_MAIN"; do
+  if grep -qE 'BLOCKED.*classifier unavailable' "$_s" && ! grep -qF 'echo script || echo manual' "$_s" && ! grep -qF 'classifier=manual' "$_s" && ! grep -qF 'classifier-unavailable' "$_s"; then ok; else bad "$(basename "$_s") must fail closed with BLOCKED classifier unavailable and have no manual fallback"; fi
+done
+echo "review-pr-staging-scope.test.sh: passed=$PASS failed=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/run-shell-tests.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# run-shell-tests.sh — glob runner for every scripts/*.test.sh suite.
+#
+# Usage: bash scripts/run-shell-tests.sh [suite-file ...]
+#   No args: runs every scripts/*.test.sh (sorted). New suites need no workflow edit.
+#   Args:    runs only the given suite files (used to point at fixtures).
+#
+# Env:
+#   SHELL_TEST_TIMEOUT  per-suite timeout in seconds (default 300)
+#
+# Exit: 0 when every suite passes; 1 on any FAIL/TIMEOUT or when no suite is found.
+# Bash 3.2 portable: no mapfile, no associative arrays.
+
+set -u
+
+SCRIPT_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)
+REPO_ROOT=$(cd "$SCRIPT_DIR/.." && pwd)
+cd "$REPO_ROOT" || exit 1
+
+TIMEOUT_SECS="${SHELL_TEST_TIMEOUT:-300}"
+# WIRE:PROVEN — manual: SHELL_TEST_TIMEOUT=abc and SHELL_TEST_TIMEOUT=0 both print the error and exit 2
+case "$TIMEOUT_SECS" in
+  ''|*[!0-9]*) echo "run-shell-tests: SHELL_TEST_TIMEOUT must be a positive integer, got '$TIMEOUT_SECS'" >&2; exit 2 ;;
+esac
+if [ "$TIMEOUT_SECS" -eq 0 ]; then
+  echo "run-shell-tests: SHELL_TEST_TIMEOUT must be a positive integer, got '$TIMEOUT_SECS'" >&2
+  exit 2
+fi
+
+TIMEOUT_BIN=""
+# WIRE:PROVEN — manual: timeout branch runs on Linux; gtimeout branch is the macOS fallback (same invocation shape); neither-found branch only warns and runs suites unbounded
+if command -v timeout >/dev/null 2>&1; then
+  TIMEOUT_BIN="timeout"
+elif command -v gtimeout >/dev/null 2>&1; then
+  TIMEOUT_BIN="gtimeout"
+else
+  echo "run-shell-tests: no timeout/gtimeout found; suites run without a per-suite timeout" >&2
+fi
+
+SUITES=""
+if [ "$#" -gt 0 ]; then
+  for f in "$@"; do
+    SUITES="${SUITES}${f}
+"
+  done
+else
+  for f in scripts/*.test.sh; do
+    [ -e "$f" ] || continue
+    SUITES="${SUITES}${f}
+"
+  done
+fi
+
+if [ -z "$SUITES" ]; then
+  echo "run-shell-tests: no suites found (scripts/*.test.sh)" >&2
+  exit 1
+fi
+
+# WIRE:PROVEN — manual: GITHUB_ACTIONS=true emits ::group::/::endgroup:: lines, unset prints "=== suite"
+GROUPING=false
+[ "${GITHUB_ACTIONS:-}" = "true" ] && GROUPING=true
+
+TOTAL=0
+FAILED=0
+SUMMARY=""
+
+while IFS= read -r suite; do
+  [ -n "$suite" ] || continue
+  TOTAL=$((TOTAL + 1))
+  # WIRE:PROVEN — manual: passing a nonexistent suite path prints FAIL (missing file) and exits 1
+  if [ ! -f "$suite" ]; then
+    SUMMARY="${SUMMARY}FAIL     ${suite} (missing file)
+"
+    FAILED=$((FAILED + 1))
+    continue
+  fi
+
+  if $GROUPING; then echo "::group::${suite}"; else echo "=== ${suite}"; fi
+  start=$(date +%s)
+  if [ -n "$TIMEOUT_BIN" ]; then
+    "$TIMEOUT_BIN" "$TIMEOUT_SECS" bash "$suite"
+  else
+    bash "$suite"
+  fi
+  rc=$?
+  elapsed=$(( $(date +%s) - start ))
+  if $GROUPING; then echo "::endgroup::"; fi
+
+  if [ "$rc" -eq 0 ]; then
+    status="PASS"
+  # WIRE:PROVEN — manual: SHELL_TEST_TIMEOUT=1 against a `sleep 5` fixture suite yields rc 124 -> TIMEOUT
+  elif [ "$rc" -eq 124 ] && [ -n "$TIMEOUT_BIN" ]; then
+    status="TIMEOUT"
+    FAILED=$((FAILED + 1))
+  else
+    status="FAIL"
+    FAILED=$((FAILED + 1))
+  fi
+  [ "$status" = "PASS" ] || echo "${status}: ${suite} (exit ${rc})"
+  SUMMARY="${SUMMARY}$(printf '%-8s %s (%ss)' "$status" "$suite" "$elapsed")
+"
+done <<EOF_SUITES
+${SUITES}
+EOF_SUITES
+
+echo
+echo "=== Shell test summary ==="
+printf '%s' "$SUMMARY"
+echo "Total: ${TOTAL}  Failed: ${FAILED}"
+
+[ "$FAILED" -eq 0 ] || exit 1
+exit 0