forgedock 1.12.0 → 1.13.0

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/label-state-machine.md

@@ -14,6 +14,7 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
 | `workflow:ready-to-build` | Investigation complete, build not started | Investigator agent |
 | `workflow:building` | Build phase active | Builder agent |
 | `workflow:in-review` | PR created, review active | Orchestrator agent |
+| `workflow:remediating` | Autonomous remediation pending: review handed a ci-gate refusal, an in-PR fix request or a pure base conflict to `work-on:remediate`, which fixes it with no human action. NOT a human gate, NOT terminal; orchestrate classifies it IN_PROGRESS (never GATED) and `work-on:remediate` clears it on every exit | Review phase (`work-on/review.md` R4); cleared by `work-on/remediate.md` |
 | `workflow:awaiting-merge` | Remediated + re-reviewed, awaiting a human merge decision | Review-pr Phase 8 (auto-merge guard) |
 | `workflow:merged` | PR merged, issue closed | Close phase agent |
 | `workflow:invalid` | Issue closed as invalid | Investigator agent |
@@ -21,6 +22,8 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
 | `needs-human` | Pipeline blocked, human intervention required | Any agent on error |
 | `workflow:engine-error` | Pipeline blocked by the engine/tool itself breaking (CLI crash, missing SDK/API key, exhausted retries with no attempt ever reaching a real outcome) — not a genuine content-level judgment call | `terminate()` in `bin/engine.mjs` |
 
+`workflow:remediating` vs `needs-human` (forge#3541): `needs-human` is reserved for genuine human decisions and external actions (an exhausted remediation bound, an unresolvable conflict, a policy gate, spend, real-environment validation). Work the pipeline fixes by itself (a pure base-sync, a red CI gate, an in-PR finding round) is marked `workflow:remediating` instead, so operators are not alerted and orchestrate does not hold DAG dependents as GATED. `work-on:remediate` accepts either label (a bare `needs-human` from an older run still works), swaps it for `workflow:in-review` on a FIXABLE run, and on every BLOCKED/UNFIXABLE exit clears `workflow:remediating` and asserts `needs-human`.
+
 `workflow:awaiting-merge` vs `needs-human`: both are terminal (the pipeline stops advancing the issue automatically), but they mean different things. `needs-human` means the pipeline hit a condition it cannot resolve on its own (genuinely blocked — conflicting PR, failed verdict, calibration/trust escalation, etc.) and a human must diagnose and act. `workflow:awaiting-merge` means the opposite: the PR was previously escalated to `needs-human`, has since been remediated and re-reviewed to a clean `APPROVED` verdict with no mergeability blockers, but does not yet meet the automated auto-land bar (see forge#1809 Q1) — a human only needs to click merge, not diagnose a problem. `scripts/transition-label.sh` only clears `needs-human` (best-effort) when the target state is `workflow:awaiting-merge` — every other forward transition leaves a pre-existing `needs-human` label untouched, preserving its sticky/terminal semantics.
 
 `workflow:engine-error` vs `needs-human` (taxonomy split — commit `90376f5` / #2261): before this commit, `terminate()` wrote `needs-human` for *every* exhausted-retry blocked outcome, including cases where the engine/CLI tool itself was breaking (crash, missing API key, no SDK) rather than a genuine human-judgment call. As of `90376f5`, `runPhaseWithRetry()` tags an outcome `engine-error` when every exhausted attempt failed via a thrown runner exception (never reached `detectOutcome()`) — the engine/tool is broken, not the issue content — and `terminate()` writes `workflow:engine-error` instead of `needs-human` for that case. A genuine content-level block (unmerged PR, unresolved branch, a fixed-point zero-commits case) still writes `needs-human` unchanged. **Consequence for downstream consumers**: any dashboard, query, or health metric that counts `needs-human` issues computed a different, larger population before `90376f5` than after — a subset of what used to be `needs-human` now shows up as `workflow:engine-error` instead. This is a one-time taxonomy discontinuity, not a real change in pipeline reliability; consumers tracking `needs-human` counts over time should also track `workflow:engine-error` from this commit forward to get a like-for-like comparison. `bin/labels.json` already includes `workflow:engine-error` in this repo; syncing it to consumer/satellite repos is tracked separately (see forge#2346).
@@ -33,6 +36,8 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
   → workflow:ready-to-build     [Phase 2: Investigation complete]
   → workflow:building           [Phase 3: Build started]
   → workflow:in-review          [Phase 4: PR created]
+  → workflow:remediating        [Review R4: autonomous ci-gate / in-pr-fix / base-sync handoff; no human needed]
+  → workflow:in-review          [Remediate M1: fix under way]  (workflow:in-review → workflow:remediating → workflow:in-review)
   → workflow:awaiting-merge [TERMINAL] [Phase 5/review-pr: re-reviewed after needs-human, awaiting human merge]
   → workflow:merged  [TERMINAL] [Phase 5: PR merged]
   → workflow:invalid [TERMINAL] [Any phase: closed as invalid]
@@ -63,7 +68,7 @@ At most one `workflow:*` label should be active on an issue at any time. When tr
 ```bash
 gh issue edit {NUMBER} -R {REPO} \
   --add-label "workflow:building" \
-  --remove-label "workflow:investigating,workflow:ready-to-build,workflow:in-review,workflow:awaiting-merge,workflow:merged,workflow:invalid,workflow:decomposed"
+  --remove-label "workflow:investigating,workflow:ready-to-build,workflow:in-review,workflow:remediating,workflow:awaiting-merge,workflow:merged,workflow:invalid,workflow:decomposed"
 ```
 
 This is enforced by `scripts/transition-label.sh` — use `resolve_script 'transition-label'` rather than calling `gh issue edit` directly when possible.

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,19 @@ 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.
+SLICE_FILE=$(mktemp)
+cat > "$SLICE_FILE" <<'FORGE_SLICE_EOF'
+[DOMAIN_DIFF_SLICE]
+FORGE_SLICE_EOF
 ```
 
+**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 +94,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 +107,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 +134,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 +152,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`
@@ -146,8 +160,9 @@ Append this block at the very end of your comment (after the `---` footer line,
 6. **Summary**: Concise one-line description (no pipe `|` characters in summary)
 7. **Empty block**: If no findings at all, include just the START/END markers
 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 lowercase dispatched domain.
+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.0",
+  "version": "1.13.0",
   "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/packages/protocol/src/phases.js

@@ -54,10 +54,19 @@ export const PHASE_IDS = ['investigate', 'decompose', 'build', 'review', 'remedi
  *   whose presence means this phase has committed.
  * @property {string} [invalidMarker] - (investigate only) marks the issue INVALID.
  * @property {string} [decomposedMarker] - (investigate only) marks the issue DECOMPOSED.
+ *   investigate.md emits it as the HTML comment `<!-- DECOMPOSE:YES -->`.
+ * @property {string} [notDecomposedMarker] - (investigate only) the explicit not-decomposed
+ *   verdict, emitted as `<!-- DECOMPOSE:NO -->`.
+ * @property {string} [sizeGateMarker] - (build only) bare annotation-opener of the diff-size gate record.
+ * @property {string} [sizeOverrideMarker] - (build only) bare annotation-opener of the size-gate override.
  * @property {string} [partialMarker] - sentinel for an interrupted/partial annotation.
  * @property {string} [presenceMarker] - bare annotation-opener substring, used only by
  *   phases whose completion is non-critical (see `context` below) — presence alone
  *   (without `:COMPLETE`) is enough to report a soft/visible skip rather than a hard fail.
+ * @property {string} [header] - the typed-comment header (without `<!-- ` / ` -->`) a genuine
+ *   phase comment must START with (e.g. `FORGE:INVESTIGATOR`). The engine matches the
+ *   sentinel only inside a trusted comment that leads with this header (forge#3542);
+ *   additive, the bare marker strings above are unchanged.
  * @property {string} [completionLabel] - a GitHub issue *label* (not a comment marker)
  *   whose presence means this phase has committed. Only `close` uses this form.
  */
@@ -66,17 +75,21 @@ export const PHASE_IDS = ['investigate', 'decompose', 'build', 'review', 'remedi
 export const PHASE_MARKERS = {
   investigate: {
     completionMarker: RESERVED_TYPES.INVESTIGATOR.completionSentinel, // 'INVESTIGATION:COMPLETE'
+    header: 'FORGE:INVESTIGATOR',
     invalidMarker: 'INVESTIGATION:INVALID',
     decomposedMarker: 'DECOMPOSE:YES',
+    notDecomposedMarker: 'DECOMPOSE:NO',
   },
   // forge#2379: `decompose` actually runs work-on/decompose (sub-issue
   // fan-out) once `investigate` hands off on `DECOMPOSE:YES` — see
   // bin/engine/phases.mjs's `decompose` phase entry for the handoff mechanics.
   decompose: {
     completionMarker: RESERVED_TYPES.DECOMPOSED.completionSentinel, // 'FORGE:DECOMPOSED:COMPLETE'
+    header: 'FORGE:DECOMPOSED',
   },
   context: {
     completionMarker: RESERVED_TYPES.CONTEXT.completionSentinel, // 'FORGE:CONTEXT:COMPLETE'
+    header: 'FORGE:CONTEXT',
     partialMarker: RESERVED_TYPES.CONTEXT.partialSentinel, // 'FORGE:CONTEXT:PARTIAL'
     // Bare presence marker: context is documented as non-critical (spec §7) — a
     // missing completion marker is a visible skip, not a hard fail. Only
@@ -87,10 +100,17 @@ export const PHASE_MARKERS = {
   },
   architect: {
     completionMarker: RESERVED_TYPES.ARCHITECT.completionSentinel, // 'FORGE:ARCHITECT:COMPLETE'
+    header: 'FORGE:ARCHITECT',
     partialMarker: RESERVED_TYPES.ARCHITECT.partialSentinel, // 'FORGE:ARCHITECT:PARTIAL'
   },
   build: {
     completionMarker: RESERVED_TYPES.BUILDER.completionSentinel, // 'FORGE:BUILDER:COMPLETE'
+    header: 'FORGE:BUILDER',
+    // Size-gate (B5.5) records. Neither is a completion sentinel: the gate's
+    // NEEDS_DECOMPOSE exit posts no FORGE:BUILDER:COMPLETE, so the engine reads
+    // these to route an oversized build to decompose instead of retrying it.
+    sizeGateMarker: `FORGE:${RESERVED_TYPES.DIFF_SIZE.type}`, // 'FORGE:DIFF_SIZE'
+    sizeOverrideMarker: `FORGE:${RESERVED_TYPES.SIZE_OVERRIDE.type}`, // 'FORGE:SIZE_OVERRIDE'
   },
   review: {
     // No RESERVED_TYPES entry defines this sentinel (REVIEWER has no
@@ -102,6 +122,7 @@ export const PHASE_MARKERS = {
   // `remediate` phase reads it off the issue, consistent with every other phase here.
   remediate: {
     completionMarker: RESERVED_TYPES.REMEDIATION.completionSentinel, // 'FORGE:REMEDIATION:COMPLETE'
+    header: 'FORGE:REMEDIATION',
   },
   close: {
     // A GitHub label, not a comment marker — see `completionLabel` above.

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"