forgedock 1.16.2 → 1.18.0

package/docs/TELEMETRY.md

@@ -0,0 +1,65 @@
+# Gate Telemetry
+
+Gate scripts record their decisions as structured events so gate block rates, finding funnels and malformed-check
+counts can be measured without re-reading comments with a model. GitHub is the source of truth: records are written
+by code (never by a model) into a `FORGE:TELEMETRY` comment, and everything can be rebuilt from the GitHub API alone.
+Local files are only a cache.
+
+## Where records live
+
+- One `<!-- FORGE:TELEMETRY v1 -->` comment per issue, or per PR for review-side events (`review_panel`,
+  `finding_disposition`, `ci_gate` go to the PR when one is known, everything else to the issue).
+- The comment is edited in place. The records are JSONL inside a fenced `jsonl` block.
+- Near 60,000 characters (GitHub's limit is 65,536) a new `<!-- FORGE:TELEMETRY v1 part=N -->` comment is started.
+- Written with the pipeline's own `gh` token. Readers must take only comments that pass `scripts/trusted-comments.sh`
+  (OWNER/MEMBER/COLLABORATOR, or a Bot author); the emitter itself only edits trusted telemetry comments.
+- If a write fails the record is appended to `~/.forge/telemetry-buffer/<owner>_<repo>__<number>.jsonl` and flushed
+  with the next emit for the same target, from any machine that touches the issue. Lines already present in the
+  comment are not written twice. Deleting the buffer loses only records that never reached GitHub.
+
+## Record shape
+
+```json
+{"v":1,"ts":"2026-10-11T19:38:54Z","forge_version":"1.16.1","repo":"o/r","issue":5,"pr":null,"run":null,"phase":null,"event":"diff_size","lines":10}
+```
+
+`issue`, `pr`, `run` and `phase` come from `FORGE_ISSUE`, `FORGE_PR`, `FORGE_RUN` and `FORGE_PHASE` (null when unset);
+`repo` from `FORGE_REPO`, else the `origin` remote. A record with no repo or no numeric issue/PR has no destination and
+is dropped. Payload keys are `[A-Za-z0-9_]+` and cannot shadow the shared keys; integers and `true`/`false` are typed.
+
+## Event catalogue
+
+| Event | Emitted by | Payload |
+|-------|-----------|---------|
+| `diff_size` | `scripts/diff-size.sh`; `work-on/build.md` B5.5 (final result) | `lines`, `excluded`, `ws_lines`, `review_weight`, `modules`, `result`; the script emits the legacy `threshold` and `OK` \| `OVER` \| `COHESIVE`, the B5.5 call site emits the final `result` = `OK` \| `EXTENDED_REVIEW` \| `SCOPE_FLAGGED` \| `OVERRIDDEN` plus `estimate` (plan), `actual` (whitespace-insensitive lines), `scope` = `ok` \| `out_of_plan` \| `no_baseline` and `review_depth` = `STANDARD` \| `EXTENDED` (calibration inputs, forge#3862) |
+| `acceptance_gate` | `work-on/build.md` B6.5 (`phase=build`); `scripts/review-acceptance-gate.sh` (`phase=review`) | `phase`, `verified`, `failed`, `malformed`, `deferred` |
+| `finding_disposition` | `scripts/classify-finding.sh`, one per finding | `severity`, `confidence`, `agent`, `disposition` = `ISSUE` \| `NOTE` \| `INPR_FIX`, `reason` |
+| `review_panel` | `review-pr.md` Phase 4 | `agents_selected`, `agents_completed`, `mode` = `FULL` \| `DELTA` \| `BASE_SYNC_ONLY` |
+| `ci_gate` | `scripts/wait-ci-green.sh` | `result` = `PASS` \| `FAIL` \| `ERROR` \| `TIMEOUT`, `rc`, `checks` |
+| `liveness` | `scripts/remediate-liveness.sh` | `decision` = `PROCEED` \| `DEFER` \| `EXHAUSTED`, `why` |
+| `phase_attempt` | the engine (`bin/engine/telemetry-seam.mjs`, one per phase attempt; `phase` = the phase id) | `attempt`, `model`, `turns`, `duration_ms`, `cost_usd`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens` (any value the runner did not report is omitted) |
+| `run_terminal` | the engine (`terminate()`, one per run segment) | `reason` (terminal reason), `code` (see `docs/OUTCOME-CODES.md`), `wall_ms` (this engine process, start to terminal) |
+
+The engine records carry `run` = `r_<issue>_<start epoch seconds>` (one per `forgedock run-issue` process) so `forgedock stats`
+(`docs/STATS.md`) can group the attempts of a run and tell a finished run from an unfinished one. They are the GitHub-side
+source for Cost, Time and outcome codes (`run` is per process, but stats count one run per issue, last wins): without them a fresh machine can rebuild only the gate and review sections.
+
+The classifier and the scripts emit only when a destination is known: callers export `FORGE_ISSUE` and/or `FORGE_PR`
+(`review-pr.md` exports them before classifying; the other scripts default `FORGE_REPO`/`FORGE_ISSUE`/`FORGE_PR` from
+their own arguments).
+
+## Guarantees
+
+- Never fails or alters the caller: `forge_emit` always returns 0, runs in a subshell with all output discarded, bounds
+  each `gh` call to 30 seconds, and gate stdout and exit codes are identical with it on or off.
+- `FORGE_TELEMETRY=off` makes every emit a no-op (the test runner sets it so suites never touch `~/.forge`).
+- Emitters: `scripts/lib/telemetry.sh` (`forge_emit <event> key=value...`, also runnable as
+  `bash scripts/lib/telemetry.sh <event> key=value...`) and `bin/engine/telemetry.mjs` (`emit(event, payload)`),
+  with the same record shape.
+
+## Privacy note
+
+Records contain ids, counts and codes only: never comment bodies, issue text, file contents, diffs or secrets. Values
+are restricted to `A-Za-z0-9 _.:/#@+=,-` (anything else becomes `_`) and truncated to 200 characters, so a value
+cannot carry markup, backticks or newlines into the comment. Treat the comment as public to anyone who can read the
+issue or PR.

package/docs/WORK-ON-RUNTIME.md

@@ -51,6 +51,12 @@ Only the router may invoke them, so they always run at router layer + 1 (L2 unde
 L1 solo). When another phase needs one, it returns a handoff (`status: NEXT`, `next: <phase>`) and
 the router invokes it. Concretely: review returns `next: remediate` instead of calling remediation.
 
+The same rule gives the `PHASE_TRAIL_FAILED` re-dispatch a single owner: `work-on:review` Phase R4 alone
+re-runs the missing phases. `/review-pr` (Phase 8, via `scripts/review-finalize.sh merge-gate`) and
+`work-on:remediate` (Phase M6) only report the status with its `MISSING:` lines and never re-dispatch. When
+`/review-pr` finds neither `Task` nor `Agent` ("neither tool available"), the usual cause is this depth limit
+(F1/F5): the review was invoked from inside a fork instead of by the router, so `Agent` was withheld.
+
 **R2 — Non-dispatching forks may nest.** Phases and children that never spawn sub-agents may invoke
 further forks at any depth (F5): build → context/architect/implement/validate → quality-gate,
 review → quality-gate / missing-phase re-dispatch, remediate → close. Forking them keeps each
@@ -117,3 +123,16 @@ remediate L2, reviewers L3, same as the table.
 - `/orchestrate` still dispatches one worker `Agent` per issue (L1).
 - Phases keep their specs, `*_RESULT` contracts and GitHub markers; phase-trail verification is unchanged.
 - Solo `/work-on` gets one extra layer of headroom.
+
+## 7. Pipeline cost report
+
+`bash scripts/cost-report.sh [--runs-dir DIR] [--last N] [--versions a,b] [--min-n N]` reads the engine run logs (`~/.forge/runs/*.jsonl`) and prints a markdown table per ForgeDock version and repo: finished-run count `n`, mean and median cache-read tokens per issue, mean per phase, remediated %, merged %, and cache-read tokens per merged issue. Groups with `n` below `--min-n` (default 10) are flagged `low-n`. The staging review (`commands/review-pr-staging.md` Phase 8) embeds it for the current version and the previous two (`--last 3`).
+
+- Only finished runs count (a `RUN_TERMINAL` after any `RUN_REOPEN` / `RUN_NEXT_CYCLE`). Unfinished runs and hydrated runs (reconstructed from `FORGE:STATE`, no usage data) are excluded and counted in the footer.
+- Attribution comes from `RUN_START`, which now records `version` (from `package.json`) and `repo` (`owner/repo`) on all three writers: the engine's fresh start, the hydrate path (`hydrated: true`), and the interactive hook. Both are best-effort and null when unresolved; `deriveState` ignores them.
+- Older logs have neither: the repo shows `unknown` and the version is estimated from the log's mtime against release times (git tags `v*`, or `--release-times FILE` with `<version> <epoch>` lines), marked `~`.
+- Fixture test: `bash scripts/cost-report.test.sh` (fixtures in `scripts/fixtures/cost-report/`).
+
+## 8. Outcome codes
+
+Every `PHASE_FAILED`, blocked `PHASE_COMMIT` and `RUN_TERMINAL` run-log event carries a machine-readable `code` from a closed, versioned enum (`bin/engine/outcome-codes.mjs`), and `FORGE:STATE` records the causing code as `outcomeCode`. Codes come from structured evidence only, never from the prose `detail`; an unmapped outcome is `unclassified` with the raw reason kept. See `docs/OUTCOME-CODES.md`.

package/docs/site/command-reference.md

@@ -419,7 +419,7 @@ Cleans up stale labels, missing workflow state, project board gaps, dangling wor
 /cleanup branches                 # Prune merged branches
 /cleanup milestones               # Archive shipped milestones
 /cleanup board                    # Fix project board gaps
-/cleanup orphans                  # Remove dangling worktrees
+/cleanup orphans                  # Remove dangling worktrees; close dead orchestrate claims boards
 /cleanup all                      # Everything
 ```
 

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

@@ -535,8 +535,8 @@ needed.
 
 | Marker | Category | Meaning |
 |--------|----------|---------|
-| `<!-- FORGE:DIFF_SIZE -->` | Lifecycle (no completion sentinel) | Measured diff size of the staged build: `diff_lines`, `excluded_lines`, `threshold`, `result: OK \| OVERRIDDEN \| COHESIVE \| OVER`, optional `estimated_diff_lines` (sub-issues), cohesion figures and a reviewer note on `COHESIVE`, and on `OVER` a `### Split Proposal`. Refreshed in place; readers take the latest trusted comment. Consumed by decompose (plan source) and close (records `diff_lines` in `FORGE:TRAJECTORY`) |
-| `<!-- FORGE:SIZE_OVERRIDE -->` | Control | Posted by a human to let an over-threshold build proceed. Valid only from a trusted author and with a non-empty justification on the line after the marker |
+| `<!-- FORGE:DIFF_SIZE -->` | Lifecycle (no completion sentinel) | Record of the build's post-build scope check (B5.5): `diff_lines`, `excluded_lines`, `ws_lines`, `review_weight`, `modules`, `estimated_diff_lines`, `scope: ok \| out_of_plan \| no_baseline`, `review_depth: STANDARD \| EXTENDED`, `result: OK \| EXTENDED_REVIEW \| SCOPE_FLAGGED \| OVERRIDDEN` plus `out_of_plan:` / `overrun:` / `trimmed:` notes. Never a size gate and never a decompose signal (a finished build is not routed to decompose). Refreshed in place; readers take the latest trusted comment. Consumed by review-pr (review depth) and close (records `diff_lines` in `FORGE:TRAJECTORY`). Older records carrying `threshold` / `result: OVER \| COHESIVE` still parse |
+| `<!-- FORGE:SIZE_OVERRIDE -->` | Control | Posted by a human to suppress the scope-check flag (out-of-plan files or estimate overrun) and the decompose loop guard. Valid only from a trusted author and with a non-empty justification on the line after the marker |
 
 Both lookups are anchored at the start of the comment body and trust-filtered
 (`scripts/trusted-comments.sh`); an unreadable lookup fails closed.

package/docs/spec/label-state-machine.md

@@ -20,7 +20,7 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
 | `workflow:invalid` | Issue closed as invalid | Investigator agent |
 | `workflow:decomposed` | Issue decomposed into sub-issues | Decomposer agent |
 | `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: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` (also removes a stacked `workflow:remediating`, and adds `needs-human` when the run was remediating) |
 
 `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`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.16.2",
+  "version": "1.18.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -35,6 +35,7 @@
   "files": [
     "bin/",
     "!bin/tests/",
+    "!bin/stats/fixtures/",
     "commands/",
     "docs/",
     "!docs/site/.vitepress/",
@@ -47,7 +48,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test \"bin/tests/**/*.test.mjs\" \"bin/engine/**/*.test.mjs\" \"packages/protocol/test/**/*.test.mjs\"",
+    "test": "node --test \"bin/tests/**/*.test.mjs\" \"bin/engine/**/*.test.mjs\" \"bin/stats/**/*.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",

package/packages/protocol/src/phases.js

@@ -57,8 +57,8 @@ export const PHASE_IDS = ['investigate', 'decompose', 'build', 'review', 'remedi
  *   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} [sizeGateMarker] - (build only) bare annotation-opener of the scope-check record (diff size, review weight, scope outcome).
+ * @property {string} [sizeOverrideMarker] - (build only) bare annotation-opener of the scope-check override.
  * @property {string} [investigationMarker] - (build only) bare marker of the durable
  *   investigation-deliverables comment, posted as `<!-- FORGE:INVESTIGATION:DELIVERABLES -->`.
  * @property {string} [partialMarker] - sentinel for an interrupted/partial annotation.
@@ -108,9 +108,9 @@ export const PHASE_MARKERS = {
   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.
+    // Scope-check (B5.5) records. Neither is a completion sentinel and neither routes anywhere
+    // (forge#3862): a finished build is never sent to decompose. DIFF_SIZE is the record of the
+    // scope-check outcome; SIZE_OVERRIDE suppresses the scope flag and the decompose loop guard.
     sizeGateMarker: `FORGE:${RESERVED_TYPES.DIFF_SIZE.type}`, // 'FORGE:DIFF_SIZE'
     sizeOverrideMarker: `FORGE:${RESERVED_TYPES.SIZE_OVERRIDE.type}`, // 'FORGE:SIZE_OVERRIDE'
     // Investigation exit (implement.md I2): no code, no PR, so no FORGE:BUILDER:COMPLETE.

package/scripts/builder-resume-match.test.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# builder-resume-match.test.sh — the anchored, trusted FORGE:BUILDER resume selector (forge#3668, mirrors forge#3648)
+# Exercises the exact jq used by commands/work-on/build/implement.md Resume Check. No network.
+# Usage: bash scripts/builder-resume-match.test.sh
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+set -uo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+PASS=0; FAILN=0
+ok()  { PASS=$((PASS+1)); echo "ok   - $1"; }
+bad() { FAILN=$((FAILN+1)); echo "FAIL - $1"; }
+eq()  { if [ "$2" = "$3" ]; then ok "$1"; else bad "$1 (got '$2', want '$3')"; fi; }
+
+SELECT_JQ='[.[][] | select((.body // "") | startswith("<!-- FORGE:BUILDER -->")) | select((.user.type // "") == "Bot" or ((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR"))) | {id: .id, complete: (.body | contains("<!-- FORGE:BUILDER:COMPLETE -->")), other: (.body | test("<!-- FORGE:(INVESTIGATOR|CONTEXT|CONTRACT|ARCHITECT)"))}]'
+DELETE_JQ='[.[] | select(.complete | not)] | if length == 1 and (.[0].other | not) then .[0].id else empty end'
+
+# c <id> <assoc> <type> <body>
+c() { jq -nc --argjson i "$1" --arg a "$2" --arg t "$3" --arg b "$4" '{id:$i,author_association:$a,user:{type:$t},body:$b}'; }
+arch()    { printf '%s' "$1" | jq -sc . | jq -s "$SELECT_JQ"; }
+n_complete() { arch "$1" | jq '[.[] | select(.complete)] | length'; }
+del_id()  { arch "$1" | jq -r "$DELETE_JQ"; }
+
+PLAN=$'<!-- FORGE:BUILDER -->\n## Implementation\n\n<!-- FORGE:BUILDER:COMPLETE -->'
+PARTIAL=$'<!-- FORGE:BUILDER -->\n## Implementation (in progress)'
+INVEST=$'<!-- FORGE:INVESTIGATOR -->\nThe build phase later posts FORGE:BUILDER and FORGE:BUILDER:COMPLETE.'
+CTX=$'<!-- FORGE:CONTEXT -->\nmentions <!-- FORGE:BUILDER -->'
+MIXED=$'<!-- FORGE:BUILDER -->\nquoted <!-- FORGE:INVESTIGATOR -->'
+
+eq "INVESTIGATOR mentioning FORGE:BUILDER is not selected" "$(arch "$(c 1 NONE Bot "$INVEST")" | jq length)" 0
+eq "INVESTIGATOR mentioning FORGE:BUILDER is never deleted" "$(del_id "$(c 1 NONE Bot "$INVEST")")" ""
+eq "CONTEXT mentioning the marker mid-body is not selected" "$(arch "$(c 2 NONE Bot "$CTX")" | jq length)" 0
+eq "complete comment by bot is complete" "$(n_complete "$(c 3 NONE Bot "$PLAN")")" 1
+eq "complete comment by MEMBER is complete" "$(n_complete "$(c 3 MEMBER User "$PLAN")")" 1
+eq "single partial comment -> delete its id" "$(del_id "$(c 4 NONE Bot "$PARTIAL")")" 4
+eq "two partial comments -> delete nothing" "$(del_id "$(c 4 NONE Bot "$PARTIAL")"$'\n'"$(c 5 NONE Bot "$PARTIAL")")" ""
+eq "untrusted author partial ignored" "$(del_id "$(c 6 NONE User "$PARTIAL")")" ""
+eq "untrusted author complete ignored" "$(n_complete "$(c 6 NONE User "$PLAN")")" 0
+eq "partial carrying another FORGE marker is not deleted" "$(del_id "$(c 7 NONE Bot "$MIXED")")" ""
+eq "investigator + partial comment -> only the comment id" "$(del_id "$(c 1 NONE Bot "$INVEST")"$'\n'"$(c 8 NONE Bot "$PARTIAL")")" 8
+eq "paginated concatenated arrays" "$(printf '[%s]\n[%s]' "$(c 1 NONE Bot "$INVEST")" "$(c 9 NONE Bot "$PLAN")" | jq -s "$SELECT_JQ" | jq '[.[] | select(.complete)] | length')" 1
+
+ARCHC=$'<!-- FORGE:ARCHITECT -->\nplan; the builder will post <!-- FORGE:BUILDER -->'
+eq "ARCHITECT mentioning the marker is not selected" "$(arch "$(c 10 NONE Bot "$ARCHC")" | jq length)" 0
+eq "unparsable input fails closed" "$(printf 'not json' | jq -s "$SELECT_JQ" 2>/dev/null | jq -r "$DELETE_JQ" 2>/dev/null)" ""
+
+# Spec drift guard: every mutating site carries this exact predicate and no unanchored selector.
+for f in commands/work-on/build/implement.md commands/work-on/build.md commands/work-on/build/validate.md; do
+  SPEC="$ROOT/$f"
+  ! grep -qE 'contains\(.FORGE:BUILDER.\) and' "$SPEC" && ok "$f has no unanchored selector" || bad "$f still uses unanchored selector"
+  grep -qF "$SELECT_JQ" "$SPEC" && ok "$f uses the tested select jq" || bad "$f select jq drifted from this test"
+  grep -qF "$DELETE_JQ" "$SPEC" && ok "$f uses the tested pick jq" || bad "$f pick jq drifted from this test"
+done
+
+echo "passed=$PASS failed=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/cap-findings.sh

@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# cap-findings.sh — PR-level cap on filed review findings (review-pr §6B.5, review-pr-staging §7B).
+#                   classify-finding.sh decides one finding at a time; this is the aggregation
+#                   step after it: at most N ISSUE dispositions per review run are kept, the rest
+#                   become `NOTE capped` (listed in FORGE:NOTE_DISPOSITION, never dropped).
+#
+# Usage:
+#   cap-findings.sh [--cap N] [--lineage none|review-finding] [--input FILE]
+#
+# Input (stdin, or --input FILE): TSV rows
+#   ID<TAB>SEVERITY<TAB>CONFIDENCE<TAB>DISPOSITION[<TAB>AGENT]
+# DISPOSITION is the classifier output (`ISSUE <reason>`, `NOTE <reason>`, `INPR_FIX <reason>`).
+#
+# Output (stdout): one `ID<TAB>DISPOSITION` row per input row, in input order, then a final
+# `CAPPED=<N>` line (no tab) counting the rows rewritten to `NOTE capped`. Callers read the rows
+# with `awk -F'\t' 'NF >= 2'`.
+#
+# Rules:
+#   - Only ISSUE rows are considered. NOTE and INPR_FIX rows pass through untouched and never
+#     consume the cap.
+#   - HIGH/CRITICAL ISSUE rows are NEVER capped (they always file and still block via the review's
+#     severity gate).
+#   - `ISSUE fix-efficacy-*` rows (the classifier's never-damped "the linked issue is not fixed / the
+#     PR re-introduces its defect" exemption, #3857) are NEVER capped either: capping one would merge
+#     a known-broken fix and close its issue as fixed. They are treated like HIGH rows (under
+#     --lineage review-finding they consume the budget).
+#   - Remaining ISSUE rows are ranked by severity (MEDIUM > LOW), then confidence (CONFIRMED >
+#     LIKELY > POSSIBLE), then safety domain (Security/Auth/Billing/Concurrency/Database agent
+#     first), then input order. Unparseable severity or confidence ranks as MEDIUM / LIKELY, so the
+#     cap still applies to it (it is not an automatic ISSUE).
+#   - Cap default: 2. Under --lineage review-finding the default is 1 and every filed HIGH/CRITICAL
+#     consumes that budget (a fix for a finding must not mint a new generation of findings).
+#     An explicit --cap overrides the default in both lineages. 0 is valid (cap everything
+#     cappable). A non-numeric or negative --cap falls back to the default with a warning on stderr.
+#
+# Exit codes: 0 ok, 2 usage error. Bash 3.2 compatible (no mapfile, no associative arrays).
+
+set -u
+
+CAP=""; LINEAGE="none"; INPUT=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --cap) [ $# -ge 2 ] || { echo "cap-findings.sh: --cap needs a value" >&2; exit 2; }; CAP="$2"; shift 2 ;;
+    --lineage) [ $# -ge 2 ] || { echo "cap-findings.sh: --lineage needs a value" >&2; exit 2; }; LINEAGE="$2"; shift 2 ;;
+    --input) [ $# -ge 2 ] || { echo "cap-findings.sh: --input needs a value" >&2; exit 2; }; INPUT="$2"; shift 2 ;;
+    *) echo "cap-findings.sh: unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+case "$LINEAGE" in
+  none|review-finding) ;;
+  *) echo "cap-findings.sh: --lineage must be none or review-finding (got '$LINEAGE')" >&2; exit 2 ;;
+esac
+
+if [ "$LINEAGE" = "review-finding" ]; then DEFAULT_CAP=1; else DEFAULT_CAP=2; fi
+case "$CAP" in
+  "") CAP="$DEFAULT_CAP" ;;
+  *[!0-9]*) echo "cap-findings.sh: invalid cap '$CAP', using default $DEFAULT_CAP" >&2; CAP="$DEFAULT_CAP" ;;
+esac
+
+if [ -n "$INPUT" ] && [ ! -r "$INPUT" ]; then
+  echo "cap-findings.sh: cannot read --input $INPUT" >&2; exit 2
+fi
+
+awk -F'\t' -v cap="$CAP" -v lineage="$LINEAGE" '
+function up(s) { return toupper(s) }
+function sevclass(s) { s = up(s); gsub(/[^A-Z]/, "", s); if (s == "CRITICAL" || s == "HIGH") return 3; if (s == "LOW") return 1; return 2 }
+function confrank(c) { c = up(c); if (c == "CONFIRMED") return 3; if (c == "POSSIBLE") return 1; return 2 }
+function domain(a) { a = tolower(a); return (a ~ /(security|auth|billing|concurrency|database)/) ? 1 : 0 }
+/^[ \t\r]*$/ { next }
+{
+  n++
+  sub(/\r$/, "")
+  id[n] = $1; disp[n] = $4; agent[n] = $5
+  if (NF < 4 || $4 == "") disp[n] = "ISSUE malformed-row"
+  split(disp[n], w, " ")
+  isissue[n] = (w[1] == "ISSUE")
+  sc = sevclass($2)
+  # the classifier already decided HIGH/CRITICAL: never cap those, whatever the raw severity text looked like
+  if (w[2] ~ /^severity-(HIGH|CRITICAL)$/) sc = 3
+  # fix-efficacy is never damped (classify-finding.sh): the per-review cap must not re-damp it
+  if (w[2] ~ /^fix-efficacy-/) sc = 3
+  if (isissue[n] && sc == 3) { high++ ; capable[n] = 0 }
+  else if (isissue[n]) { capable[n] = 1; score[n] = sc * 1000 + confrank($3) * 100 + domain($5) * 10 }
+  else capable[n] = 0
+}
+END {
+  budget = cap + 0
+  if (lineage == "review-finding") budget -= high
+  if (budget < 0) budget = 0
+  kept = 0
+  while (kept < budget) {
+    best = 0
+    for (i = 1; i <= n; i++) {
+      if (!capable[i] || keep[i]) continue
+      if (best == 0 || score[i] > score[best]) best = i
+    }
+    if (best == 0) break
+    keep[best] = 1; kept++
+  }
+  capped = 0
+  for (i = 1; i <= n; i++) {
+    if (capable[i] && !keep[i]) { printf "%s\tNOTE capped\n", id[i]; capped++ }
+    else printf "%s\t%s\n", id[i], disp[i]
+  }
+  printf "CAPPED=%d\n", capped
+}' ${INPUT:+"$INPUT"}

package/scripts/cap-findings.test.sh

@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Fixtures for scripts/cap-findings.sh (review-pr §6B.5 / review-pr-staging §7B per-review cap).
+# Run: bash scripts/cap-findings.test.sh   (bash 3.2 compatible)
+
+set -u
+DIR=$(cd "$(dirname "$0")" && pwd)
+S="$DIR/cap-findings.sh"
+pass=0; fail=0
+T=$(printf '\t')
+
+# rows <id:sev:conf:disp[:agent]>...  -> TSV on stdout (disp may use ~ for space)
+rows() {
+  local spec id sev conf disp agent
+  for spec in "$@"; do
+    IFS=: read -r id sev conf disp agent <<EOF2
+$spec
+EOF2
+    disp=$(printf '%s' "$disp" | tr '~' ' ')
+    printf '%s\t%s\t%s\t%s\t%s\n' "$id" "$sev" "$conf" "$disp" "$agent"
+  done
+}
+
+# expect <description> <expected "id=CLASS ..."> <script args> -- <row specs>
+# Compares the first word of each output row's disposition, in input order, plus the CAPPED trailer.
+expect() {
+  local desc="$1" want="$2"; shift 2
+  local args=()
+  while [ "$1" != "--" ]; do args+=("$1"); shift; done
+  shift
+  local got
+  got=$(rows "$@" | bash "$S" ${args[@]+"${args[@]}"} 2>/dev/null | awk -F'\t' 'NF >= 2 { split($2, w, " "); printf "%s=%s%s ", $1, w[1], (w[2] == "capped" ? "(capped)" : "") } /^CAPPED=/ { printf "%s", $0 }')
+  if [ "$got" = "$want" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc"; echo "  want: $want"; echo "  got:  $got"; fi
+}
+expect_exit() { # expect_exit <code> <description> -- args...
+  local want="$1" desc="$2"; shift 3
+  bash "$S" "$@" </dev/null >/dev/null 2>&1; local got=$?
+  if [ "$got" = "$want" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc (want exit $want, got $got)"; fi
+}
+
+# --- Default cap is 2; ranking by severity, then confidence ---
+expect "under the cap: nothing capped" "a=ISSUE b=ISSUE CAPPED=0" -- \
+  a:MEDIUM:LIKELY:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x
+expect "overflow becomes NOTE capped, lowest rank loses" "a=NOTE(capped) b=ISSUE c=ISSUE CAPPED=1" -- \
+  a:MEDIUM:POSSIBLE:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "ranks by confidence CONFIRMED > LIKELY > POSSIBLE" "a=NOTE(capped) b=ISSUE c=ISSUE d=NOTE(capped) CAPPED=2" -- \
+  a:MEDIUM:POSSIBLE:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x d:MEDIUM:POSSIBLE:ISSUE~x
+expect "MEDIUM outranks LOW even at lower confidence" "a=NOTE(capped) b=ISSUE c=ISSUE CAPPED=1" -- \
+  a:LOW:CONFIRMED:ISSUE~x b:MEDIUM:POSSIBLE:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "ties broken by safety-domain agent" "a=NOTE(capped) b=NOTE(capped) c=ISSUE d=ISSUE CAPPED=2" -- \
+  a:MEDIUM:LIKELY:ISSUE~x:General b:MEDIUM:LIKELY:ISSUE~x:General c:MEDIUM:LIKELY:ISSUE~x:Auth d:MEDIUM:LIKELY:ISSUE~x:Concurrency_reviewer
+expect "remaining ties broken by input order (stable)" "a=ISSUE b=ISSUE c=NOTE(capped) CAPPED=1" -- \
+  a:MEDIUM:LIKELY:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+
+# --- HIGH/CRITICAL are never capped and do not consume the default budget ---
+expect "HIGH and CRITICAL never capped past the cap" "a=ISSUE b=ISSUE c=ISSUE d=ISSUE e=ISSUE CAPPED=0" -- \
+  a:HIGH:POSSIBLE:ISSUE~x b:CRITICAL:LIKELY:ISSUE~x c:HIGH:CONFIRMED:ISSUE~x d:MEDIUM:CONFIRMED:ISSUE~x e:MEDIUM:LIKELY:ISSUE~x
+expect "HIGH does not consume the default budget" "a=ISSUE b=ISSUE c=ISSUE d=NOTE(capped) CAPPED=1" -- \
+  a:HIGH:LIKELY:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x d:MEDIUM:POSSIBLE:ISSUE~x
+expect "lowercase high is never capped" "a=ISSUE b=NOTE(capped) CAPPED=1" --cap 0 -- \
+  a:high:POSSIBLE:ISSUE~x b:medium:LIKELY:ISSUE~x
+
+# --- Unparseable severity/confidence ranks as MEDIUM/LIKELY and IS capped ---
+expect "unparseable severity is capped like MEDIUM" "a=NOTE(capped) b=ISSUE c=ISSUE CAPPED=1" -- \
+  a:INFO:POSSIBLE:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "missing severity and confidence rank MEDIUM/LIKELY (above POSSIBLE, below CONFIRMED)" "a=ISSUE b=NOTE(capped) c=ISSUE CAPPED=1" -- \
+  a:MEDIUM:CONFIRMED:ISSUE~x b:MEDIUM:POSSIBLE:ISSUE~x c::ISSUE~x
+expect "unparseable severity cannot displace a ranked MEDIUM CONFIRMED when cap is 1" "a=NOTE(capped) b=ISSUE CAPPED=1" --cap 1 -- \
+  a::ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x
+
+# --- Lineage review-finding: default 1, filed HIGH+ consumes the budget ---
+expect "lineage default 1 keeps only the best" "a=NOTE(capped) b=ISSUE c=NOTE(capped) CAPPED=2" --lineage review-finding -- \
+  a:MEDIUM:LIKELY:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "lineage: a filed HIGH consumes the budget, all MEDIUM capped" "a=ISSUE b=NOTE(capped) c=NOTE(capped) CAPPED=2" --lineage review-finding -- \
+  a:HIGH:LIKELY:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "lineage: CRITICAL still never capped" "a=ISSUE b=ISSUE CAPPED=0" --lineage review-finding -- \
+  a:CRITICAL:CONFIRMED:ISSUE~x b:HIGH:CONFIRMED:ISSUE~x
+expect "lineage: explicit cap 3 with one HIGH keeps two MEDIUM" "a=ISSUE b=ISSUE c=ISSUE d=NOTE(capped) CAPPED=1" --lineage review-finding --cap 3 -- \
+  a:HIGH:LIKELY:ISSUE~x b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x d:MEDIUM:POSSIBLE:ISSUE~x
+
+# --- Explicit cap, 0, invalid cap ---
+expect "explicit cap 3 overrides default 2" "a=ISSUE b=ISSUE c=ISSUE CAPPED=0" --cap 3 -- \
+  a:MEDIUM:LIKELY:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "cap 0 caps every cappable row, never HIGH" "a=NOTE(capped) b=ISSUE c=NOTE(capped) CAPPED=2" --cap 0 -- \
+  a:MEDIUM:CONFIRMED:ISSUE~x b:HIGH:LIKELY:ISSUE~x c:LOW:CONFIRMED:ISSUE~x
+expect "invalid cap falls back to default 2" "a=ISSUE b=ISSUE c=NOTE(capped) CAPPED=1" --cap abc -- \
+  a:MEDIUM:CONFIRMED:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x c:MEDIUM:POSSIBLE:ISSUE~x
+expect "negative cap falls back to default 2" "a=ISSUE b=ISSUE c=NOTE(capped) CAPPED=1" --cap -1 -- \
+  a:MEDIUM:CONFIRMED:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x c:MEDIUM:POSSIBLE:ISSUE~x
+expect "invalid cap under lineage falls back to 1" "a=ISSUE b=NOTE(capped) CAPPED=1" --lineage review-finding --cap x -- \
+  a:MEDIUM:CONFIRMED:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x
+
+# --- Pass-through rows never consume the cap ---
+expect "NOTE and INPR_FIX rows pass through" "a=NOTE b=INPR_FIX c=ISSUE d=ISSUE e=NOTE(capped) CAPPED=1" -- \
+  a:MEDIUM:LIKELY:NOTE~reflag-note b:MEDIUM:CONFIRMED:INPR_FIX~in-pr c:MEDIUM:CONFIRMED:ISSUE~x d:MEDIUM:LIKELY:ISSUE~x e:MEDIUM:POSSIBLE:ISSUE~x
+expect "empty input prints only the trailer" "CAPPED=0" --
+
+# --- Reason text and original rows survive ---
+out=$(rows "a:MEDIUM:CONFIRMED:ISSUE~medium~confirmed" | bash "$S" 2>/dev/null | head -n 1)
+if [ "$out" = "a${T}ISSUE medium confirmed" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: kept row keeps its classifier reason (got '$out')"; fi
+out=$(rows "a:MEDIUM:CONFIRMED:NOTE~stale" | bash "$S" 2>/dev/null | head -n 1)
+if [ "$out" = "a${T}NOTE stale" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: NOTE row passes through verbatim (got '$out')"; fi
+
+# --- Severity text noise never demotes HIGH/CRITICAL (classifier strips whitespace and uppercases) ---
+expect "whitespace/markdown HIGH still uncapped at cap 0" "a=ISSUE b=ISSUE c=ISSUE d=NOTE(capped) CAPPED=1" --cap 0 -- \
+  "a:HIGH :CONFIRMED:ISSUE~severity-HIGH" 'b:**HIGH**:CONFIRMED:ISSUE~severity-HIGH' c:High:LIKELY:ISSUE~severity-HIGH d:MEDIUM:LIKELY:ISSUE~x
+expect "fix-efficacy ISSUE rows are never capped (#3857 exemption survives the cap)" "a=ISSUE b=ISSUE c=NOTE(capped) CAPPED=1" --cap 1 -- \
+  a:MEDIUM:LIKELY:ISSUE~fix-efficacy-fails b:MEDIUM:CONFIRMED:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x
+expect "lineage: fix-efficacy beats an unrelated CONFIRMED MEDIUM and consumes the budget" "a=NOTE(capped) b=ISSUE CAPPED=1" --lineage review-finding -- \
+  a:MEDIUM:CONFIRMED:ISSUE~lineage-medium-CONFIRMED b:MEDIUM:LIKELY:ISSUE~fix-efficacy-regresses
+expect "classifier severity-HIGH/CRITICAL reason is never capped" "a=ISSUE b=ISSUE CAPPED=0" --cap 0 -- \
+  "a:weird:CONFIRMED:ISSUE~severity-HIGH" "b:weird:CONFIRMED:ISSUE~severity-CRITICAL"
+expect "lineage budget counts noisy HIGH" "a=ISSUE b=NOTE(capped) CAPPED=1" --cap 1 --lineage review-finding -- \
+  "a:HIGH :CONFIRMED:ISSUE~severity-HIGH" b:MEDIUM:CONFIRMED:ISSUE~x
+
+# --- --input file and usage errors ---
+tmp=$(mktemp)
+rows a:MEDIUM:LIKELY:ISSUE~x b:MEDIUM:LIKELY:ISSUE~x c:MEDIUM:LIKELY:ISSUE~x > "$tmp"
+got=$(bash "$S" --input "$tmp" 2>/dev/null | tail -n 1)
+rm -f "$tmp"
+if [ "$got" = "CAPPED=1" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: --input file (got '$got')"; fi
+expect_exit 2 "unknown arg is a usage error"  -- --bogus
+expect_exit 2 "bad lineage is a usage error"  -- --lineage sideways
+expect_exit 2 "missing --input file is a usage error" -- --input /nonexistent/cap-findings-rows
+expect_exit 0 "empty stdin exits 0"           -- 
+
+echo "cap-findings.test.sh: $pass passed, $fail failed"
+[ "$fail" -eq 0 ]

package/scripts/check-spec-bash.sh

@@ -33,6 +33,8 @@
 #                 `export VAR=`, `read VAR`, `for VAR in`) at or before its first read. Comment-only lines are ignored; `$REPO`
 #                 does not match `$REPO_FLAG`. Suppress a deliberate read by putting
 #                 `allowlist:fence-state` on the same line. Pseudo-tool-call fences are scanned too.
+#                 A line that sources scripts/lib/fence-bootstrap.sh and ends in `# FENCE_BOOTSTRAP` binds the variables that
+#                 library derives (PR_NUMBER ALL_PR_NUMBERS GH_REPO DEFAULT_BRANCH STAGING_BRANCH CONFIG_FILE _SD FORGE_RUN_KEY).
 #                 Output: `FAIL <file>:<line> fence-state ...` then `SPEC-FENCE-STATE: ...`.
 #   --fence-funcs Different check, opt-in: shell functions are per-shell too, so a function defined
 #                 (`name() {`, `function name`) in one ```bash/sh fence is undefined in every other
@@ -113,15 +115,17 @@ if [ "$FENCESTATE" = 1 ]; then
         }
       }
       function reset(   i) { for (i = 1; i <= nv; i++) { asg[vn[i]] = 0; first[vn[i]] = ""; firsttxt[vn[i]] = "" } }
-      BEGIN { nv = split(vars, vn, " ") }
+      BEGIN { nv = split(vars, vn, " "); nb = split("PR_NUMBER ALL_PR_NUMBERS GH_REPO DEFAULT_BRANCH STAGING_BRANCH CONFIG_FILE _SD FORGE_RUN_KEY", bv, " ") }
       !inb && /^[ \t]*```(bash|sh)[ \t]*$/ { inb = 1; reset(); next }
       !inb && /^[ \t]*```/ { other = !other; next }
       other { next }
       inb && /^[ \t]*```[ \t]*$/ { flush(); inb = 0; next }
       inb {
         if ($0 ~ /^[ \t]*#/) next
+        boot = ($0 ~ /fence-bootstrap\.sh/ && $0 ~ /# FENCE_BOOTSTRAP[ \t]*$/)
         for (i = 1; i <= nv; i++) {
           v = vn[i]
+          if (boot && first[v] == "") for (j = 1; j <= nb; j++) if (bv[j] == v) asg[v] = 1
           if (first[v] == "" && ($0 ~ ("(^|[;&|( \t])(export[ \t]+|local[ \t]+|declare[ \t]+(-[A-Za-z]+[ \t]+)?|readonly[ \t]+)?" v "=") ||
               $0 ~ ("(^|[;&|( \t])read[ \t]+(-[A-Za-z]+[ \t]+)*([A-Za-z0-9_]+[ \t]+)*" v "([ \t;]|$)") ||
               $0 ~ ("(^|[;&|( \t])for[ \t]+" v "[ \t]+in[ \t]"))) asg[v] = 1

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

@@ -165,6 +165,26 @@ check 0 "violations=0"                   "--fence-state passes declared, loop, e
 check 2 "Usage"                          "--fence-state without -- is a usage error"  -- --fence-state PR_NUMBER fs-good.md
 check 2 "Usage"                          "--fence-state without vars is a usage error" -- --fence-state -- fs-good.md
 
+# --fence-state: a FENCE_BOOTSTRAP source line binds the variables scripts/lib/fence-bootstrap.sh derives (and only those, and only on a marked line)
+cat > "$T/fs-boot.md" <<EOF
+${FENCE}bash
+. "\$(forge_resolve lib/fence-bootstrap.sh)" || exit 1   # FENCE_BOOTSTRAP
+gh pr view "\$PR_NUMBER" -R "\$GH_REPO" --json state
+${FENCE}
+EOF
+cat > "$T/fs-boot-bad.md" <<EOF
+${FENCE}bash
+. "\$(forge_resolve lib/fence-bootstrap.sh)" || exit 1
+gh pr view "\$PR_NUMBER" -R "\$GH_REPO" --json state
+${FENCE}
+${FENCE}bash
+. "\$(forge_resolve lib/fence-bootstrap.sh)" || exit 1   # FENCE_BOOTSTRAP
+echo "\$MERGE_ISSUE"
+${FENCE}
+EOF
+check 0 "violations=0"                   "--fence-state treats a FENCE_BOOTSTRAP source line as binding PR_NUMBER and GH_REPO" -- --fence-state PR_NUMBER GH_REPO -- fs-boot.md
+check 1 "violations=3"                   "--fence-state ignores an unmarked source line and a var the bootstrap does not derive" -- --fence-state PR_NUMBER GH_REPO MERGE_ISSUE -- fs-boot-bad.md
+
 # --fence-funcs: a function defined only in another fence, then called, is flagged.
 cat > "$T/ff-bad.md" <<EOF
 ${FENCE}bash

package/scripts/check-spec-markers.sh

@@ -165,12 +165,14 @@ MARKER_REGISTRY="
   REMEDIATION
   REMEDIATION_HELD
   REMEDIATION_DEFERRED
+  REMEDIATION_DISPATCH
   REREVIEW_DISPATCHED
   REREVIEW_RELEASED
   REREVIEW_SKIPPED
   REVIEW
   REVIEWER
   REVIEW_ROUTE
+  REVIEW_TIER
   REVIEW_STARTED
   SECURITY_AUDIT
   SIGNAL_RESOLVED