forgedock 1.12.1 → 1.13.1

package/docs/CONFIG.md

@@ -457,6 +457,35 @@ pipeline:
 
 ---
 
+## `engine` (OPTIONAL)
+
+Per-command `--model` and `--max-turns` for the CLI backend (`forgedock run-issue` phases and `forgedock run <command>`). Opt-in: with no keys set, the `claude` invocation is unchanged and uses the CLI's own default model with no turn bound. `forge.yaml` is parsed one level deep, so settings are **flat** keys under `engine:`, named `<key>_model` and `<key>_max_turns`, where `<key>` is the command name with every non-alphanumeric character replaced by `_`.
+
+```yaml
+engine:
+  # work-on/review -> work_on_review (the review phase is the most expensive).
+  work_on_review_model: sonnet
+  work_on_review_max_turns: 120
+
+  # review-pr-staging -> review_pr_staging (non-work-on commands work the same way).
+  review_pr_staging_max_turns: 80
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `<key>_model` | string | No | Model alias (`sonnet`, `opus`, `haiku`) or full model id passed as `--model`. Invalid values are ignored. |
+| `<key>_max_turns` | integer | No | Positive integer passed as `--max-turns`. Invalid values are ignored. |
+
+**Precedence** (model): `engine.<key>_model`, then the run-level model the caller passed explicitly, then omitted. `max_turns` comes only from this section. No defaults ship.
+
+**Version gate**: the flags are added only when the installed `claude --version` supports them (`--max-turns` is hidden from `claude --help`, so help text is never scraped); an unparseable version omits both flags.
+
+**Turn exhaustion**: when `--max-turns` is exhausted the run ends `engine-error` (detail `max-turns`) and the phase is never committed, so `forgedock run-issue --retry` re-enters the same phase. Raise `<key>_max_turns` before retrying. Phase runlog events record `model` and `turns` next to `usage` so a limit can be sized from measured turn counts.
+
+**Commands that use this section**: CLI backend (`runCommand` in `bin/runner.mjs`)
+
+---
+
 ## `build` (OPTIONAL)
 
 Tuning for the `/work-on` build phase. Today it holds the diff-size gate: after the implement phase stages its changes and before validation commits them, the build measures the changed lines (added plus deleted) of the index and any earlier commits against `origin/{base}`, using `scripts/diff-size.sh`. Review findings per PR rise steeply with diff size, so an oversized build is split before it is validated.

package/docs/RELEASE-NOTES.md

@@ -2,6 +2,51 @@
 
 Operator-facing notes for behavior changes that need action or awareness. Newest first.
 
+## Review damper: LOW needs keyword + CONFIRMED; a missing classifier blocks the review (#3639)
+
+`scripts/classify-finding.sh` is stricter for LOW findings. A safety keyword now files a LOW finding only when it is also CONFIRMED (LOW LIKELY/POSSIBLE with a keyword is a NOTE), and a dedicated domain agent (Auth, Billing, Concurrency, Database) rescues MEDIUM findings only, no longer LOW CONFIRMED. MEDIUM behaviour is unchanged.
+
+`/review-pr` §6B.5 and `/review-pr-staging` §7B.5 no longer let the model hand-classify (`classifier=manual`) when the script cannot be resolved. They return `REVIEW_RESULT: status: BLOCKED` with blocker `classifier unavailable (classify-finding.sh not resolvable through the trusted resolver)`, file nothing and do not merge or approve a deploy. The staging per-finding runtime-failure fallback is renamed `ISSUE classifier-error`. The `classifier=` marker stays and is always `script`.
+
+Action: if reviews now report `classifier unavailable`, fix the ForgeDock install so the trusted resolver finds `scripts/classify-finding.sh`, then re-run the review.
+
+## Introduced-line gate no longer demotes CRITICAL/HIGH (#3597, #3598)
+
+`/review-pr` §6B.4 gate 2 never routes a CRITICAL/HIGH finding (any confidence) as `pre-existing`: a new caller of an unchanged unsafe helper is an interaction defect (`protocols.md` §5), so it stays a blocking `review-finding` under §7B criterion 2, including with `--auto-merge`. The pre-existing route now covers MEDIUM and lower only. A file with no `patch` in the PR files API (large or truncated diff) is treated as UNKNOWN and its findings are kept, never routed as pre-existing. Expect slightly more blocking findings on PRs that touch unsafe code through unchanged helpers.
+
+## Contract out-of-scope items now typed; review demotes matching findings (#3447)
+
+The `### Out of Scope` section of `FORGE:CONTRACT` is no longer free text. It is `None.` or bullets that each name a backticked path and one disposition: `deferred → #N`, `not-affected: <evidence>` or `accepted-risk: <reason>`. A contract that keeps a known-flawed design must list it as `deferred → #N`.
+
+- **Build** (B2.0) files a follow-up issue for each `deferred` item before the contract is posted (idempotent through a `FORGE:DEFERRED_FROM: #N` body marker) and validates the section with the new `scripts/check-contract-scope.sh`. An untyped item blocks the build after one retry.
+- **Review** (`/review-pr` §6B.5) reads the latest trusted contract and passes it to `scripts/classify-finding.sh --contract-scope`. A finding on a `deferred` path (follow-up still open) or an `accepted-risk` path becomes a note instead of a new `review-finding`; deferred matches are commented on the existing issue. `not-affected` items, HIGH/CRITICAL findings, safety-exempt `accepted-risk` findings and files the PR itself changed are never demoted. `FORGE:NOTE_DISPOSITION` gains `contract_demoted=N`.
+- The review scope-creep check now reads only the contract's `### Deliverables`, so backticked out-of-scope paths no longer count as in-scope files.
+
+Action: none. Older contracts with free-text Out of Scope sections are not parsed and demote nothing.
+
+## Review provenance gates and noise share (#3452)
+
+`/review-pr` §6B.4 now checks each finding before it can become a `review-finding` issue: the cited line must exist at the reviewed head SHA (else dropped as stale), must be added or changed by the PR diff (else routed as `pre-existing`), and must carry a concrete `**Failure scenario**` (else demoted to a note; CRITICAL/HIGH, any confidence, are exempt). Pre-existing defects are never counted as this PR's findings or in the amplification ratio; only MEDIUM or lower ones are routed this way, and the safety-domain ones are filed once with the new `pre-existing` label. The `FORGE:NOTE_DISPOSITION` record gains `findings_dropped_stale`, `findings_preexisting`, `notes_demoted_no_scenario`, and `/pipeline-health` reports a noise share (2E.5).
+
+Action: run `npx forgedock labels setup` to create the `pre-existing` label (the review also creates it on demand).
+
+## Diff-size gate in `/work-on` build (#3450)
+
+`/work-on` build now measures the changed lines (added plus deleted) after implement stages its changes and before validate commits them. The gate is **on by default at 1000 lines**. Review findings per PR rise steeply with diff size, so an oversized build is split instead of validated.
+
+- **Over the threshold**: the build posts a `FORGE:DIFF_SIZE` comment with a split proposal and exits `NEEDS_DECOMPOSE`; the router then runs `work-on:decompose`.
+- **Tune or disable**: set `build.diff_size.threshold` in `forge.yaml` (`0` disables the gate) and add exclusions with `build.diff_size.exclude_globs`. Lockfiles, `*.min.*`, `*.snap` and vendored/generated directories are excluded by default.
+- **Per-issue bypass**: post a `FORGE:SIZE_OVERRIDE` comment with a non-empty justification on the line after the marker. Only comments from trusted authors count.
+- **No re-decomposition**: an issue that is already a decomposed child, or has `FORGE:DECOMPOSED`, blocks until an override is posted instead of being split again.
+
+Action: if your builds routinely exceed 1000 changed lines, raise `build.diff_size.threshold` or set it to `0`. See the `build` section of [CONFIG.md](CONFIG.md).
+
+## Stricter `review-pr` / `review-pr-staging` argument rejection (#3466)
+
+`/review-pr` and `/review-pr-staging` now reject an argument string as a whole if it contains a quote, backtick, `$`, backslash, newline or tab. Nothing is parsed from a rejected string, so no PR number, repo, merge value or flag survives, and `--auto-merge` is not honoured. `/review-pr-staging` stops with nothing reviewed and nothing posted.
+
+Action: callers must pass `--gh-flag -R owner/repo` unquoted, and must not forward untrusted text (issue titles, comment bodies) into the argument string.
+
 ## Spec bash no longer corrupted by Claude Code argument substitution
 
 Claude Code replaces `$0`..`$9` in a skill body with the invocation's arguments (0-based), so spec bash loaded via `Skill(...)` with args was silently rewritten: `awk '{print $2}'` became `awk '{print --issue}'`, `local AGENT="$1"` became `local AGENT="--auto-merge"`, which broke `/review-pr` agent selection and the CI/deploy comparisons with no error. `${N}`, `$(N)`, `$NF`, `$@`, `$#` and `$10`+ are not substituted.

package/docs/spec/forge-protocol-v1.md

@@ -251,9 +251,30 @@ findings and what will actually be built.
 {auth model, new configuration, data-safety, security surface, migration risk}
 
 ### Out of Scope
-{items explicitly excluded}
+None.
 ```
 
+`### Out of Scope` is either the single line `None.` or a list of typed bullets. Each bullet names at
+least one backticked path or symbol followed by exactly one disposition:
+
+```
+- `path` — deferred → #N: <why>
+- `path` — not-affected: <evidence>
+- `path` — accepted-risk: <reason>
+```
+
+- `deferred → #N`: a follow-up issue `#N` was filed before the contract was posted (`->` is accepted
+  for `→`). A contract that keeps a known-flawed design must list the flaw as a `deferred` item.
+- `not-affected: <evidence>`: the path was checked and is not reached by the change.
+- `accepted-risk: <reason>`: a known gap that is knowingly kept.
+- Free-text items, a `deferred` item without an issue number, or a missing/empty section are invalid.
+  `scripts/check-contract-scope.sh validate|list` is the reference parser (TSV
+  `disposition<TAB>path<TAB>issue`).
+- Review demotion: a finding on a `deferred` path (follow-up issue still open) or an `accepted-risk`
+  path becomes a note instead of a new `review-finding`; `not-affected` items, HIGH/CRITICAL findings,
+  safety-exempt `accepted-risk` findings and files the PR changed are never demoted. Only a trusted
+  author's contract is read. The count is recorded as `contract_demoted` in `FORGE:NOTE_DISPOSITION`.
+
 #### `FORGE:CONTEXT`
 
 - **Written by**: a context-gathering agent

package/docs/spec/review-protocol.md

@@ -25,6 +25,9 @@ Pipeline agents MUST NOT use `find` (unbounded or filesystem-wide) to locate pro
 Every agent MUST follow this protocol:
 
 ### 1. Start From the PR Diff
+
+**Input scoping**: You have been given a pre-computed diff slice containing only the files relevant to your domain (`[DOMAIN_DIFF_SLICE]`). Do NOT re-fetch `gh pr diff [PR_NUMBER]` in full — use the slice provided. This is capped at ~100K chars, mirroring the runner's tool-result limit.
+
 ```bash
 # Verify review is still current before reading diff
 CURRENT_SHA=$(gh pr view [PR_NUMBER] --json headRefOid --jq '.headRefOid')
@@ -34,10 +37,24 @@ if [ "$CURRENT_SHA" != "[REVIEW_SHA]" ]; then
     echo "Current HEAD: $(echo $CURRENT_SHA | cut -c1-7)"
 fi
 
+# List files in your domain slice
 gh pr diff [PR_NUMBER] --name-only
-gh pr diff [PR_NUMBER]
+
+# Materialize the pre-computed domain diff slice supplied by the orchestrator.
+# Persona greps below read "$SLICE_FILE" -- they never re-fetch the full diff.
+# Deterministic path (PR + reviewed SHA + domain): every Bash call is a fresh shell, so later fences
+# re-declare this exact line instead of relying on a variable set here.
+SLICE_FILE="${TMPDIR:-/tmp}/forge-slice-[PR_NUMBER]-[REVIEW_SHA_SHORT]-[AGENT_DOMAIN].diff"
+rm -f "$SLICE_FILE"
+cat > "$SLICE_FILE" <<'FORGE_SLICE_EOF'
+[DOMAIN_DIFF_SLICE]
+FORGE_SLICE_EOF
 ```
 
+**Later fences**: persona fences that read `$SLICE_FILE` re-declare the identical `SLICE_FILE=` line above and guard it with `[ -f "$SLICE_FILE" ] || { echo "SLICE_FILE missing ..." >&2; exit 1; }`. The guard tests existence, not size, so a legitimately empty slice still takes the fallback below while a lost path fails loudly instead of reporting a false clean scan.
+
+**Empty or truncated slice**: if the slice is empty or ends mid-hunk, read the specific changed files with bounded reads (`sed -n 'X,Yp'`, `head -N`) — never fall back to fetching the full PR diff.
+
 **Hot-spot prior**:
 [CHURN_CONTEXT]
 
@@ -82,7 +99,7 @@ If a file you are reviewing is listed above as a hot-spot, apply deeper scrutiny
 3. Will this cause degraded performance? → **MEDIUM**
 4. Is it genuinely cosmetic with no runtime impact after tracing all consumers? → **LOW**
 
-If you're unsure whether something is cosmetic or a runtime error, **assume it's a runtime error** and flag it for investigation. A false positive costs a minute of review time. A missed runtime error costs production downtime.
+**Precision first.** Report defects that are likely to be real in the code this PR changes and the code it reaches. If you cannot verify a runtime impact after tracing the path, report the finding at **POSSIBLE** confidence — do not inflate its severity or confidence to be safe. A false positive costs reviewer trust and triggers a cascade of follow-up issues and re-reviews; an unverified suspicion belongs at POSSIBLE, where it stays a non-blocking note, not at an inflated severity.
 
 ### 5. INTERACTION ANALYSIS — "Pre-existing" Is Not "Safe"
 
@@ -95,6 +112,8 @@ A redundant import, an unused variable, or a duplicated constant may be harmless
 2. For each reference, ask: "Does the pre-existing construct cause this new line to fail at runtime?"
 3. If yes → CONFIRMED finding, not a dismissal
 
+**Severity rule**: CRITICAL/HIGH findings, any confidence, are never routed as pre-existing by the `/review-pr` introduced-line gate (§6B.4): they stay blocking `review-finding` issues. The `**Scope**` tag does not gate routing.
+
 ### 6. FALSE POSITIVE PREVENTION
 
 **Before claiming variable scope issues:** Read the FULL function, count indentation levels, check if/else structure.
@@ -120,7 +139,7 @@ Every finding must include:
 
 ## Structured Findings Protocol
 
-**All review agents MUST include a machine-readable findings block at the end of their PR comment.** This is NON-OPTIONAL. Without structured findings, the review system cannot create GitHub issues, and findings die as unread PR comments. Every finding that doesn't become a GitHub issue is a finding that will never be addressed.
+**All review agents MUST include a machine-readable findings block at the end of their PR comment.** This is NON-OPTIONAL. Without structured findings, the review system cannot classify, file, or track what you found. The orchestrator (`/review-pr` §6B.4/§6B.5) decides disposition: CONFIRMED/LIKELY findings that pass its gates become issues, while LOW severity and POSSIBLE confidence findings are non-blocking NOTEs that are not filed as standalone issues.
 
 ### Persist Before Post
 
@@ -138,7 +157,7 @@ Append this block at the very end of your comment (after the `---` footer line,
 
 ### Rules
 
-1. **Include ALL findings at CONFIRMED, LIKELY, and POSSIBLE confidence** — every finding becomes a GitHub issue. Nothing stays as just a PR comment. **POSSIBLE findings are informational advisories (P3/non-blocking)** — they are tracked but do not require a fix PR and do not block merge. CONFIRMED and LIKELY findings are blocking at P1/P2 respectively.
+1. **Include every finding you can support at CONFIRMED, LIKELY, or POSSIBLE confidence in the block** — the orchestrator needs them all to classify. Inclusion does not mean a GitHub issue is filed: `/review-pr` §6B.4/§6B.5 decide filing. **POSSIBLE confidence and LOW severity findings are non-blocking NOTEs** — reported in the review, never filed as standalone issues, never block merge. CONFIRMED and LIKELY findings are blocking at P1/P2 respectively. Do not pad the block with unverified or speculative items; precision over recall.
 2. **One line per finding** — sequential numbering (PREFIX-1, PREFIX-2, ...)
 3. **Confidence**: `CONFIRMED`, `LIKELY`, or `POSSIBLE`
 4. **Severity**: `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW`
@@ -148,6 +167,7 @@ Append this block at the very end of your comment (after the `---` footer line,
 8. **HTML comments**: The block is invisible in rendered markdown but parseable by the review system
 9. **Agent marker**: Include exactly one `<!-- FORGE:REVIEW-AGENT:{domain} -->` marker in the persisted body, where `{domain}` is the marker domain the orchestrator passes you (the canonical value from the roster-to-marker table in `review-pr.md`, e.g. `infra` and `scraper`; never a lowercased display name such as `infrastructure` or `scraping`).
 10. **Reviewed SHA**: Include exactly one line `Reviewed-SHA: [REVIEW_SHA]` (the full 40-hex head you were pinned to) in the persisted body, outside the marker. `/review-pr` scopes its completion wait and idempotent re-entry to this line, so a comment without the current head does not count as a completed review. Do NOT put the SHA inside the `<!-- FORGE:REVIEW-AGENT:{domain} -->` marker.
+11. **Failure scenario and scope (provenance inputs)**: every finding's body section (the prose above the findings block) MUST carry a `**Failure scenario**` line — concrete inputs leading to a wrong output or behaviour — and a `**Scope**: changed` or `**Scope**: pre-existing` line (`changed` = the cited line is added or modified by this PR; `pre-existing` = it was already there). `/review-pr` §6B.4 reads these: a finding without a failure scenario is demoted to a note (unless CRITICAL/HIGH, any confidence), and a MEDIUM or lower finding whose cited line is not in the PR diff is routed as pre-existing (CRITICAL/HIGH never are; see §5). The `**Scope**` tag is informational and never gates routing. Speculative hardening with no failure scenario is a note, not a finding. The one-line `<!-- FINDING:... -->` grammar above is unchanged. <!-- Added: forge#3452 -->
 
 ### Domain Prefixes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.12.1",
+  "version": "1.13.1",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -48,6 +48,7 @@
   ],
   "scripts": {
     "test": "node --test \"bin/tests/**/*.test.mjs\" \"bin/engine/**/*.test.mjs\" \"packages/protocol/test/**/*.test.mjs\"",
+    "test:sh": "bash scripts/run-shell-tests.sh",
     "docs:dev": "vitepress dev docs/site",
     "docs:build": "vitepress build docs/site",
     "docs:preview": "vitepress preview docs/site"

package/scripts/check-blast-radius.sh

@@ -0,0 +1,164 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-blast-radius.sh — Enforce the FORGE:ARCHITECT blast-radius manifest against the final tree.
+#
+# Usage: check-blast-radius.sh --manifest <file> --base <ref> [--repo <path>]
+#
+# <file> is either the extracted manifest block or a whole FORGE:ARCHITECT comment body. Only the text between
+# <!-- FORGE:BLAST_RADIUS:BEGIN --> and <!-- FORGE:BLAST_RADIUS:END --> is parsed (all such regions, concatenated).
+# Grammar, one record per line (blank lines and markdown code-fence lines are the only other lines allowed):
+#   SYMBOL: id=<sN> kind=function|field|flag|schema|contract name=<symbol> query="<fixed-string>"
+#   HIT: symbol=<sN> file=<path> role=producer|consumer|sibling disposition=change
+#   HIT: symbol=<sN> file=<path> role=producer|consumer|sibling disposition=verified-unaffected reason=<one-token>
+# Values contain no spaces (use hyphens in reason). query must match ^[A-Za-z0-9_.:/-]{3,80}$ and not start with "-".
+#
+# For every SYMBOL the query is re-run as a fixed-string search over the final tree (working tree, tracked plus
+# untracked files, so it works before and after the commit). A file that matches must be in the change set
+# (base...HEAD plus anything staged, modified or untracked) or carry a verified-unaffected row.
+# A "change" row whose file is not in the change set is a planned-but-not-done item.
+#
+# Exit codes:
+#   0  covered, or no manifest ("SKIP: no manifest")
+#   1  UNLISTED: <symbol> <file>  and/or  NOT_DONE: <symbol> <file>
+#   2  malformed manifest, invalid query, unresolvable base/repo, or a git failure — NEVER a pass; callers report DEGRADED
+#
+# Offline: no network, no gh. Portable to bash 3.2: no mapfile, no associative arrays, no sort -V.
+
+set -uo pipefail
+
+MAX_HITS=200
+MANIFEST=""; BASE=""; REPO="."
+die2() { echo "check-blast-radius: $*" >&2; exit 2; }
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --manifest) [ "$#" -ge 2 ] || die2 "--manifest needs a value"; MANIFEST="$2"; shift 2 ;;
+    --base)     [ "$#" -ge 2 ] || die2 "--base needs a value"; BASE="$2"; shift 2 ;;
+    --repo)     [ "$#" -ge 2 ] || die2 "--repo needs a value"; REPO="$2"; shift 2 ;;
+    *) die2 "usage: check-blast-radius.sh --manifest <file> --base <ref> [--repo <path>]" ;;
+  esac
+done
+[ -n "$MANIFEST" ] || die2 "usage: check-blast-radius.sh --manifest <file> --base <ref> [--repo <path>]"
+[ -f "$MANIFEST" ] || die2 "manifest file not found: $MANIFEST"
+
+TMP=$(mktemp -d "${TMPDIR:-/tmp}/check-blast-radius.XXXXXX") || die2 "mktemp failed"
+trap 'rm -rf "$TMP"' EXIT
+
+# ---- extract BEGIN..END regions -------------------------------------------------------------------------
+awk -v out="$TMP/region" '
+  index($0, "<!-- FORGE:BLAST_RADIUS:BEGIN -->") { if (inb) { bad = 1 } inb = 1; seen = 1; next }
+  index($0, "<!-- FORGE:BLAST_RADIUS:END -->")   { if (!inb) { bad = 1 } inb = 0; next }
+  inb { print > out }
+  END { if (inb || bad) exit 3; if (!seen) exit 4 }
+' "$MANIFEST"
+case $? in
+  0) ;;
+  4) echo "SKIP: no manifest"; exit 0 ;;
+  *) die2 "unbalanced FORGE:BLAST_RADIUS:BEGIN/END markers" ;;
+esac
+[ -f "$TMP/region" ] || { echo "SKIP: no manifest"; exit 0; }
+
+# has_symbol <id>: awk over the file (no grep -q in a pipeline: SIGPIPE under pipefail misreports the status)
+has_symbol() { awk -F'\t' -v s="$1" '$1==s {ok=1} END{exit ok?0:1}' "$TMP/symbols"; }
+
+# ---- parse ----------------------------------------------------------------------------------------------
+: > "$TMP/symbols"   # id<TAB>name<TAB>query
+: > "$TMP/hits"      # symbol<TAB>file<TAB>disposition
+QRE='^[A-Za-z0-9_.:/-]{3,80}$'
+FRE='^[A-Za-z0-9_./@+=:,-]+$'
+LN=0
+while IFS= read -r line || [ -n "$line" ]; do
+  LN=$((LN+1))
+  line="${line%$'\r'}"
+  trimmed="${line#"${line%%[![:space:]]*}"}"
+  case "$trimmed" in
+    ""|'```'*) continue ;;
+    "SYMBOL: "*) kind_rec=SYMBOL; rest="${trimmed#SYMBOL: }" ;;
+    "HIT: "*)    kind_rec=HIT;    rest="${trimmed#HIT: }" ;;
+    *) die2 "line $LN: unrecognised record: $trimmed" ;;
+  esac
+  id=""; kind=""; name=""; query=""; symbol=""; file=""; role=""; disp=""; reason=""
+  set -f
+  for tok in $rest; do
+    case "$tok" in
+      *=*) k="${tok%%=*}"; v="${tok#*=}" ;;
+      *) set +f; die2 "line $LN: token without key=value: $tok" ;;
+    esac
+    case "$k" in
+      id) id="$v" ;; kind) kind="$v" ;; name) name="$v" ;;
+      query) v="${v#\"}"; v="${v%\"}"; query="$v" ;;
+      symbol) symbol="$v" ;; file) file="$v" ;; role) role="$v" ;;
+      disposition) disp="$v" ;; reason) reason="$v" ;;
+      *) set +f; die2 "line $LN: unknown key: $k" ;;
+    esac
+  done
+  set +f
+  if [ "$kind_rec" = SYMBOL ]; then
+    case "$id" in s[0-9]*) ;; *) die2 "line $LN: SYMBOL id must look like s1: '$id'" ;; esac
+    case "$id" in *[!A-Za-z0-9]*) die2 "line $LN: invalid SYMBOL id: '$id'" ;; esac
+    case "$kind" in function|field|flag|schema|contract) ;; *) die2 "line $LN: invalid kind: '$kind'" ;; esac
+    [ -n "$name" ] || die2 "line $LN: SYMBOL without name"
+    [ -n "$query" ] || die2 "line $LN: empty query"
+    case "$query" in -*) die2 "line $LN: query must not start with '-'" ;; esac
+    [[ "$query" =~ $QRE ]] || die2 "line $LN: invalid query (want $QRE): $query"
+    has_symbol "$id" && die2 "line $LN: duplicate SYMBOL id: $id"
+    printf '%s\t%s\t%s\n' "$id" "$name" "$query" >> "$TMP/symbols"
+  else
+    [ -n "$symbol" ] || die2 "line $LN: HIT without symbol"
+    has_symbol "$symbol" || die2 "line $LN: HIT references unknown symbol: $symbol"
+    [ -n "$file" ] || die2 "line $LN: HIT without file"
+    case "$file" in -*) die2 "line $LN: file must not start with '-'" ;; esac
+    [[ "$file" =~ $FRE ]] || die2 "line $LN: invalid file path: $file"
+    case "$role" in producer|consumer|sibling) ;; *) die2 "line $LN: invalid role: '$role'" ;; esac
+    case "$disp" in
+      change) ;;
+      verified-unaffected) [ -n "$reason" ] || die2 "line $LN: verified-unaffected requires reason=<token>" ;;
+      *) die2 "line $LN: invalid disposition: '$disp'" ;;
+    esac
+    printf '%s\t%s\t%s\n' "$symbol" "$file" "$disp" >> "$TMP/hits"
+  fi
+done < "$TMP/region"
+
+if [ ! -s "$TMP/symbols" ]; then
+  if [ -s "$TMP/hits" ]; then die2 "HIT records without any SYMBOL"; fi
+  echo "SKIP: no manifest"; exit 0
+fi
+
+# ---- repo, base, change set -----------------------------------------------------------------------------
+case "$BASE" in ""|-*) die2 "invalid --base: '$BASE'" ;; esac
+git -C "$REPO" rev-parse --is-inside-work-tree >/dev/null 2>&1 || die2 "not a git work tree: $REPO"
+git -C "$REPO" rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null 2>&1 || die2 "cannot resolve base ref '$BASE'"
+
+: > "$TMP/changed"
+git -C "$REPO" diff -z --name-only "${BASE}...HEAD" -- > "$TMP/c1" 2>/dev/null || die2 "git diff ${BASE}...HEAD failed"
+git -C "$REPO" diff -z --name-only HEAD -- > "$TMP/c2" 2>/dev/null || die2 "git diff HEAD failed"
+git -C "$REPO" ls-files -z --others --exclude-standard > "$TMP/c3" 2>/dev/null || die2 "git ls-files failed"
+cat "$TMP/c1" "$TMP/c2" "$TMP/c3" | tr '\0' '\n' | sed '/^$/d' | sort -u > "$TMP/changed"
+
+# ---- check ----------------------------------------------------------------------------------------------
+RC=0
+while IFS="$(printf '\t')" read -r sid sname squery; do
+  git -C "$REPO" grep -z --untracked -l -F -e "$squery" -- > "$TMP/g" 2>"$TMP/gerr"
+  grc=$?
+  if [ "$grc" -gt 1 ]; then die2 "git grep failed for symbol $sid (rc=$grc): $(head -n 1 "$TMP/gerr")"; fi
+  tr '\0' '\n' < "$TMP/g" | sed '/^$/d' | sort -u > "$TMP/found"
+  n=$(wc -l < "$TMP/found" | tr -d ' ')
+  [ "$n" -le "$MAX_HITS" ] || die2 "query too broad for symbol $sid ($n files > $MAX_HITS): use a more distinctive query"
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    if grep -Fxq -- "$f" "$TMP/changed"; then continue; fi
+    if awk -F'\t' -v s="$sid" -v f="$f" '$1==s && $2==f && $3=="verified-unaffected" {ok=1} END{exit ok?0:1}' "$TMP/hits"; then continue; fi
+    echo "UNLISTED: $sid $f"; RC=1
+  done < "$TMP/found"
+  # planned-but-not-done: change rows for this symbol whose file is not in the change set
+  while IFS="$(printf '\t')" read -r hs hf hd; do
+    [ "$hs" = "$sid" ] && [ "$hd" = change ] || continue
+    grep -Fxq -- "$hf" "$TMP/changed" || { echo "NOT_DONE: $sid $hf"; RC=1; }
+  done < "$TMP/hits"
+done < "$TMP/symbols"
+
+# HIT rows whose symbol exists were validated at parse time; a manifest that covers every hit passes.
+[ "$RC" -eq 0 ] && echo "OK: blast-radius manifest covered ($(wc -l < "$TMP/symbols" | tr -d ' ') symbol(s))"
+exit "$RC"

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 ]