forgedock 1.13.1 → 1.15.0

package/commands/work-on/review.md

@@ -529,7 +529,7 @@ else:
 
 Wait for that task's completed result before Phase R4. Propagate its `REVIEW_RESULT` as this module's child state; do not return `REVIEW_RESULT`, report progress, release an orchestrator slot, or begin close work while the child is running. If the child errors or returns no parseable `REVIEW_RESULT`, return `REVIEW_RESULT: status: BLOCKED` with the child failure as the blocker. The normal `Skill(...)` invocation above remains the non-OpenCode path.
 
-/review-pr handles: full domain-agent review → post findings as separate issues (non-blocking) → merge the PR. It does NOT close the issue or clean up the worktree — `work-on:close` does both.
+/review-pr handles: the domain-agent review (it picks FULL, DELTA or BASE_SYNC_ONLY itself: a head that only merged the base is carried forward without reviewers) → post findings as separate issues (non-blocking) → merge the PR. It does NOT close the issue or clean up the worktree — `work-on:close` does both.
 
 If `review-pr` is not found under `{FORGE_SKILL_PREFIX}review-pr` or `review-pr`, print `REVIEW_RESULT: status: BLOCKED`, blocker: "skill not found: review-pr" and STOP. Never review inline.
 
@@ -564,7 +564,7 @@ gh issue view {NUMBER} {GH_FLAG} --json state --jq '.state'
 
 - `REVIEW_RESULT: status: BLOCKED` from /review-pr whose blocker mentions the phase trail (any blocker containing "phase trail": "phase trail unreadable" when the Phase 8 verifier exited ≥2 / 127, "phase trail incomplete…", or "auto-merge requires --issue", forge#3147): the merge gate refused or could not run. Do NOT re-run phases (nothing is missing) and do NOT attempt the manual merge below, because that would bypass the gate. Add `needs-human` and return `REVIEW_RESULT: status: BLOCKED` with the same blocker. The PR stays open and unmerged.
 
-- `REVIEW_RESULT: status: BLOCKED` from /review-pr whose blocker contains "stale review" (a commit landed on the PR after the verdict, or the head moved during the CI wait, so the code that would merge is not the reviewed code): do NOT merge. The re-review bound is persisted, not remembered: count `<!-- FORGE:STALE_REREVIEW: pr={PR_NUMBER} -->` comments on the issue. If the count is 0, post that marker (with the new head SHA), run the quality gate on the new head (`Skill(skill="{FORGE_SKILL_PREFIX}quality-gate", args="<changed files> --worktree {WORKTREE_PATH}")`, which posts a fresh `FORGE:QUALITY_GATE` for the code that will actually merge), then re-invoke Phase R3 once — a full review of the new head. If the count is already ≥ 1 (the head keeps moving after review), add `needs-human` and return `REVIEW_RESULT: status: BLOCKED`, blocker: "PR head keeps moving after review". <!-- forge#3188 -->
+- `REVIEW_RESULT: status: BLOCKED` from /review-pr whose blocker contains "stale review" (a commit landed on the PR after the verdict, or the head moved during the CI wait, so the code that would merge is not the reviewed code): do NOT merge. The re-review bound is persisted, not remembered: count `<!-- FORGE:STALE_REREVIEW: pr={PR_NUMBER} -->` comments on the issue. If the count is 0, post that marker (with the new head SHA), run the quality gate on the new head (`Skill(skill="{FORGE_SKILL_PREFIX}quality-gate", args="<changed files> --worktree {WORKTREE_PATH}")`, which posts a fresh `FORGE:QUALITY_GATE` for the code that will actually merge), then re-invoke Phase R3 once — a review of the new head (scoped by /review-pr: full, delta or carried forward). If the count is already ≥ 1 (the head keeps moving after review), add `needs-human` and return `REVIEW_RESULT: status: BLOCKED`, blocker: "PR head keeps moving after review". <!-- forge#3188 -->
 
 - **Remediation-pending handoff (shared by the ci-gate, in-pr-fix and base-conflict cases below)** <!-- Added: forge#3541 -->: these three cases are autonomous pipeline work, not a human decision, so the issue must NOT carry `needs-human` while remediation is pending. `needs-human` is a human-gate signal (operators alert on it, and orchestrate holds DAG dependents as GATED on it). Mark the handoff with the non-human state `workflow:remediating` instead, and clear any `needs-human` that review-pr Phase 8 already set for the ci-gate refusal. `work-on:remediate` accepts either label (a bare `needs-human` from an older run still works), clears `workflow:remediating` on every exit, and re-asserts `needs-human` only when it cannot fix the PR. Run this block, then return `REVIEW_RESULT: status: NEXT`:
   ```bash
@@ -577,7 +577,7 @@ gh issue view {NUMBER} {GH_FLAG} --json state --jq '.state'
   gh pr edit {PR_NUMBER} {GH_FLAG} --remove-label "needs-human" 2>/dev/null || true # allowlist:check-command-side-effects
   ```
 
-- `REVIEW_RESULT: status: BLOCKED` from /review-pr whose blocker contains "ci gate" (Phase 8 refused to merge because checks failed, were cancelled, or stayed pending past the gate retries): do NOT attempt the manual merge below — that would bypass the CI gate. Fixing red CI is pipeline work, not a human decision: hand remediation to the router **once**. Bound: count `<!-- FORGE:CI_REMEDIATION: pr={PR_NUMBER} -->` comments on the issue first; if ≥ 1, do not remediate again — remove `workflow:remediating`, label the issue `needs-human` (the bound is exhausted, so a human is now genuinely needed) and return `REVIEW_RESULT: status: BLOCKED` with blocker "ci gate not green after remediation". Otherwise run the remediation-pending handoff block above (sets `workflow:remediating`, removes the `needs-human` that Phase 8 set) and return `REVIEW_RESULT: status: NEXT` with `next: remediate` and `remediation: ci-gate` (see Output). Do not post the marker here: the router posts it immediately before it invokes remediation (Phase 4R), so a handoff interrupted before remediation starts is retried instead of being counted as used. **Never invoke `work-on:remediate` from this phase** (forge#3398): remediation re-reviews through `/review-pr`, which spawns domain-reviewer sub-agents, so it must run one level below the router, not nested inside this fork. Nested here, it lands at the sub-agent depth limit under `/orchestrate` with no `Agent` tool and strands the PR at `REREVIEW-REQUIRED` (forge#3391). The router runs `work-on:remediate`, which classifies a CI-gate refusal as FIXABLE, swaps `workflow:remediating` (or a legacy `needs-human`) for `workflow:in-review`, fixes the failing jobs on the PR branch, re-runs the quality gate and a full review, and auto-lands through the same CI gate. <!-- forge#3191 -->
+- `REVIEW_RESULT: status: BLOCKED` from /review-pr whose blocker contains "ci gate" (Phase 8 refused to merge because checks failed, were cancelled, or stayed pending past the gate retries): do NOT attempt the manual merge below — that would bypass the CI gate. Fixing red CI is pipeline work, not a human decision: hand remediation to the router **once**. Bound: count `<!-- FORGE:CI_REMEDIATION: pr={PR_NUMBER} -->` comments on the issue first; if ≥ 1, do not remediate again — remove `workflow:remediating`, label the issue `needs-human` (the bound is exhausted, so a human is now genuinely needed) and return `REVIEW_RESULT: status: BLOCKED` with blocker "ci gate not green after remediation". Otherwise run the remediation-pending handoff block above (sets `workflow:remediating`, removes the `needs-human` that Phase 8 set) and return `REVIEW_RESULT: status: NEXT` with `next: remediate` and `remediation: ci-gate` (see Output). Do not post the marker here: the router posts it immediately before it invokes remediation (Phase 4R), so a handoff interrupted before remediation starts is retried instead of being counted as used. **Never invoke `work-on:remediate` from this phase** (forge#3398): remediation re-reviews through `/review-pr`, which spawns domain-reviewer sub-agents, so it must run one level below the router, not nested inside this fork. Nested here, it lands at the sub-agent depth limit under `/orchestrate` with no `Agent` tool and strands the PR at `REREVIEW-REQUIRED` (forge#3391). The router runs `work-on:remediate`, which classifies a CI-gate refusal as FIXABLE, swaps `workflow:remediating` (or a legacy `needs-human`) for `workflow:in-review`, fixes the failing jobs on the PR branch, re-runs the quality gate and re-reviews the new head (scoped by /review-pr: full, delta or carried forward), and auto-lands through the same CI gate. <!-- forge#3191 -->
 
 - `REVIEW_RESULT: status: BLOCKED` from /review-pr whose blocker contains "in-pr fix required" (review-pr §6B.6: CONFIRMED MEDIUM findings in files this PR changed, requested on the PR in a `FORGE:INPR_FIX` comment at the current head): do NOT merge and do NOT leave the issue at `needs-human` because of this gate. Run **one** fix round, bounded by `<!-- FORGE:INPR_REMEDIATION: pr={PR_NUMBER} -->` on the issue (`{BOUND}` = `INPR_REMEDIATION` below).
   - **Bound unused**: run the remediation-pending handoff block above (set `workflow:remediating`, no `needs-human`; remediation accepts that state and its Phase M1 clears it as FIXABLE). Then return `REVIEW_RESULT: status: NEXT` with `next: remediate` and `remediation: inpr-fix` (the router posts the bound marker, as in the ci-gate case) — never invoke `work-on:remediate` from this phase (same reason as the ci-gate case). The router runs remediation, which reads the `FORGE:INPR_FIX` work order, fixes exactly those findings, re-reviews the new head and auto-lands. On the re-review, any finding still present is filed as an issue (the round is used). If remediation does not land, the router re-invokes this phase, which then finds the bound used and takes the branch below.

package/docs/CONFIG.md

@@ -496,6 +496,15 @@ build:
     # Changed-line ceiling. Default: 1000. 0 disables the gate.
     threshold: 1000
 
+    # Pre-build estimate (investigate): an estimate above threshold x factor routes
+    # straight to decompose without building. Default: 1.2. Skipped when threshold is 0.
+    estimate_factor: 1.2
+
+    # Pre-build estimate (investigate): a batch with at least this many independent
+    # seams defaults to one sub-issue per seam unless the estimate is at or under
+    # half the threshold. Default: 3.
+    batch_seam_min: 3
+
     # Extra exclusion globs, ADDITIVE to the built-in defaults below.
     exclude_globs:
       - "docs/api/*"
@@ -505,11 +514,15 @@ build:
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `diff_size.threshold` | integer | No | Changed lines allowed before the gate trips. Default: 1000. `0` disables the gate |
+| `diff_size.estimate_factor` | number | No | Multiplier on `threshold` for the pre-build estimate: the investigator forces a decomposition when `ESTIMATED_DIFF_LINES` > `threshold` x `estimate_factor`. The investigator emits the effective value as an own-line `ESTIMATE_FACTOR` field, and the engine's fail-toward-decompose net (`isDecomposed`) uses it even if the verdict says NO (1.2 when the field is absent or invalid). That net is suppressed (treated as not decomposed) for a sub-issue (`**Parent**: #N`), an issue with a trusted `FORGE:DECOMPOSED` comment, or a justified `FORGE:SIZE_OVERRIDE`, because decompose Guard 1 refuses those. Default: 1.2. Skipped when `threshold` is `0` |
+| `diff_size.batch_seam_min` | integer | No | Independent seams (batch members) at which an issue defaults to one sub-issue per seam, unless `ESTIMATED_DIFF_LINES` is at or under half of `threshold`. Default: 3. Skipped when `threshold` is `0` |
 | `diff_size.exclude_globs` | list of strings | No | Globs excluded from the measurement, in addition to the built-in defaults. Default: `[]` |
 
 **Built-in default exclusions** (always applied, defined once in `scripts/diff-size.sh`): lockfiles (`package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `Cargo.lock`, `poetry.lock`, `uv.lock`, `go.sum`, `Gemfile.lock`, `composer.lock`), `*.min.*`, `*.snap`, and the directories `dist/`, `build/`, `generated/`, `fixtures/`, `vendor/` (anchored to the repo root, so first-party directories such as `commands/work-on/build/` are counted) plus `__generated__/` and `__snapshots__/` (any depth). The diff is measured against the merge base of `HEAD` and `origin/<base>`, so commits that landed on the base after the branch point are not counted. A configured glob ending in `/` matches that directory at any depth; any other glob is matched against the file basename and the full path. Globs are treated as data, never evaluated.
 
-**Over the threshold**: the build posts a `FORGE:DIFF_SIZE` comment with a split proposal and exits `BUILD_RESULT: status: NEEDS_DECOMPOSE`; the router then runs `work-on:decompose`. To build the oversized diff anyway, post a `FORGE:SIZE_OVERRIDE` comment whose body has a non-empty justification on the line after the marker (only comments from trusted authors count). An issue that is already a decomposed child, or that already has `FORGE:DECOMPOSED`, is not decomposed again: the build blocks until an override is posted. The measured `diff_lines` is recorded in the `FORGE:TRAJECTORY` comment.
+**Over the threshold**: the build posts a `FORGE:DIFF_SIZE` comment with a split proposal and exits `BUILD_RESULT: status: NEEDS_DECOMPOSE`; the router then runs `work-on:decompose`. To build the oversized diff anyway, post a `FORGE:SIZE_OVERRIDE` comment whose body has a non-empty justification on the line after the marker (only comments from trusted authors count). An issue that is already a decomposed child, or that already has `FORGE:DECOMPOSED`, is not decomposed again: the build blocks until an override is posted. The staged diff is also persisted before the exit (pushed ref `forge/wip/{NUMBER}`, or a patch file when the push fails) and each split-proposal line links its hunks, so they survive worktree cleanup; decompose copies the link into each sub-issue. The measured `diff_lines` is recorded in the `FORGE:TRAJECTORY` comment.
+
+**Pre-build estimate**: `work-on:investigate` emits `ESTIMATED_DIFF_LINES`, `INDEPENDENT_SEAMS`, `GATE_THRESHOLD` and `ESTIMATE_FACTOR` inside `### Decomposition Assessment`. An estimate above `threshold` x `estimate_factor` (or a batch of `batch_seam_min`+ seams whose estimate is not well under the gate) answers `**YES**`, so the issue is decomposed before any build. The estimate rule is skipped when `threshold` is `0`.
 
 **Commands that use this section**: `work-on` (build phase B5.5, `decompose`, `close`)
 

package/docs/RELEASE-NOTES.md

@@ -2,6 +2,26 @@
 
 Operator-facing notes for behavior changes that need action or awareness. Newest first.
 
+## Re-flag gate ignores generic words (#3719)
+
+`scripts/classify-finding.sh` no longer counts generic stopwords (`the`, `with`, `before`, `write`, ...) as topical similarity in the cross-head/cross-PR re-flag gate. The line-overlap match needs >= 1 shared non-stopword title token, and the title-only match needs >= 3 shared tokens of which >= 2 are non-stopword. Domain words such as `lock` and `retry` still count. `/review-pr` §6B.5 and `/review-pr-staging` §7B.5 carry the same wording.
+
+Action: none. Fewer real findings are demoted to `NOTE reflag-note`; a duplicate is preferred over a suppressed finding.
+
+## Unlinked prior re-flag rows no longer suppress MEDIUM findings (#3718)
+
+The prior-findings TSV now marks a reviewer-body finding whose issue linkage failed as prior-disposition `unknown` (a recorded `FORGE:NOTE_DISPOSITION` row without a linked issue stays `note`). `scripts/classify-finding.sh` ignores an `unknown` row for MEDIUM CONFIRMED/LIKELY findings, so a regression of a finding filed under a reworded title is filed instead of demoted to `NOTE reflag-note`. LOW and POSSIBLE findings still demote against an `unknown` row. `/review-pr` §6B.5 and `/review-pr-staging` §7B.5 carry the same change.
+
+Action: none. A re-flagged MEDIUM finding with a reworded prior issue may now be filed again; a duplicate is preferred over a suppressed regression.
+
+## Cross-head and cross-PR re-flag dedup (#3641)
+
+`scripts/classify-finding.sh` takes `--prior-findings <TSV>` (file, line-start, line-end, title, prior-disposition, issue#) plus `--title`, `--line-start`/`--line-end` and an optional `--diff-map`. A finding that re-raises one already posted or noted earlier (same file AND line IoU >= 0.6 or >= 3 shared title tokens) becomes `NOTE reflag-filed #N` or `NOTE reflag-note` instead of a new issue. HIGH/CRITICAL are never demoted, and a prior row whose issue is closed is ignored so a regression is not swallowed.
+
+`/review-pr` §6B.5 builds the TSV from trusted reviewer comments of earlier heads and earlier `FORGE:NOTE_DISPOSITION` records; `/review-pr-staging` §7B.5 builds it from every bundle member PR. Both read comments only through `scripts/trusted-comments.sh`. In the staging spec §7B.6 (provenance gates) now comes before §7B.5. The `FORGE:NOTE_DISPOSITION` marker gains `notes_reflag=` (and `/review-pr` also `reviewed_sha=`); consumers match the marker prefix only.
+
+Action: none. Records posted before this change lack `reviewed_sha=` and are not read as prior findings by `/review-pr`.
+
 ## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.13.1",
+  "version": "1.15.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/packages/protocol/src/phases.js

@@ -59,6 +59,8 @@ export const PHASE_IDS = ['investigate', 'decompose', 'build', 'review', 'remedi
  *   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} [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.
  * @property {string} [presenceMarker] - bare annotation-opener substring, used only by
  *   phases whose completion is non-critical (see `context` below) — presence alone
@@ -111,6 +113,10 @@ export const PHASE_MARKERS = {
     // 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'
+    // Investigation exit (implement.md I2): no code, no PR, so no FORGE:BUILDER:COMPLETE.
+    // This comment is the engine's ground truth that the build ended INVESTIGATION_COMPLETE.
+    // Not a completion sentinel: the drift script only checks completionMarker/completionLabel.
+    investigationMarker: 'FORGE:INVESTIGATION:DELIVERABLES',
   },
   review: {
     // No RESERVED_TYPES entry defines this sentinel (REVIEWER has no

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

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# architect-resume-match.test.sh — the anchored, trusted FORGE:ARCHITECT resume selector (forge#3648)
+# Exercises the exact jq used by commands/work-on/build/architect.md Resume Check. No network.
+# Usage: bash scripts/architect-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)"
+SPEC="$ROOT/commands/work-on/build/architect.md"
+
+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:ARCHITECT -->")) | select((.user.type // "") == "Bot" or ((.author_association // "") | IN("OWNER","MEMBER","COLLABORATOR"))) | {id: .id, complete: (.body | contains("<!-- FORGE:ARCHITECT:COMPLETE -->")), other: (.body | test("<!-- FORGE:(INVESTIGATOR|CONTEXT|CONTRACT|BUILDER)"))}]'
+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:ARCHITECT -->\n## Plan\n\n<!-- FORGE:ARCHITECT:COMPLETE -->'
+PARTIAL=$'<!-- FORGE:ARCHITECT -->\n## Plan (in progress)'
+INVEST=$'<!-- FORGE:INVESTIGATOR -->\nThe architect phase posts FORGE:ARCHITECT and FORGE:ARCHITECT:COMPLETE later.'
+CTX=$'<!-- FORGE:CONTEXT -->\nmentions <!-- FORGE:ARCHITECT -->'
+MIXED=$'<!-- FORGE:ARCHITECT -->\nquoted <!-- FORGE:INVESTIGATOR -->'
+
+eq "INVESTIGATOR mentioning FORGE:ARCHITECT is not selected" "$(arch "$(c 1 NONE Bot "$INVEST")" | jq length)" 0
+eq "INVESTIGATOR mentioning FORGE:ARCHITECT 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 plan by bot is complete" "$(n_complete "$(c 3 NONE Bot "$PLAN")")" 1
+eq "complete plan by MEMBER is complete" "$(n_complete "$(c 3 MEMBER User "$PLAN")")" 1
+eq "single partial plan -> delete its id" "$(del_id "$(c 4 NONE Bot "$PARTIAL")")" 4
+eq "two partial plans -> 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 plan -> only the plan 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
+
+# Spec drift guard: the spec carries this exact predicate and no unanchored selector.
+! grep -qF 'contains("FORGE:ARCHITECT")' "$SPEC" && ok "architect.md has no unanchored contains(FORGE:ARCHITECT)" || bad "architect.md still uses unanchored contains"
+grep -qF 'startswith("<!-- FORGE:ARCHITECT -->")' "$SPEC" && ok "architect.md anchors with startswith" || bad "architect.md lacks the startswith anchor"
+grep -qF "$SELECT_JQ" "$SPEC" && ok "architect.md uses the tested select jq" || bad "architect.md select jq drifted from this test"
+grep -qF "$DELETE_JQ" "$SPEC" && ok "architect.md uses the tested delete jq" || bad "architect.md delete jq drifted from this test"
+
+echo "passed=$PASS failed=$FAILN"
+[ "$FAILN" -eq 0 ]

package/scripts/check-spec-bash.sh

@@ -14,6 +14,7 @@
 #   check-spec-bash.sh [--base <git-ref>] [--shellcheck] <file.md>...
 #   check-spec-bash.sh --positional [<file.md>...]
 #   check-spec-bash.sh --fence-state <VAR>... -- <file.md>...
+#   check-spec-bash.sh --fence-funcs -- <file.md>...
 #   check-spec-bash.sh            (no args: same as --positional over all Skill-loaded commands/**/*.md,
 #                                  excluding orchestrate/**, pipeline-health/**, review-pr-agents/**)
 #
@@ -33,6 +34,13 @@
 #                 does not match `$REPO_FLAG`. Suppress a deliberate read by putting
 #                 `allowlist:fence-state` on the same line. Pseudo-tool-call fences are scanned too.
 #                 Output: `FAIL <file>:<line> fence-state ...` then `SPEC-FENCE-STATE: ...`.
+#   --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
+#                 fence. Fail any fence that calls (command position) a function that the same file
+#                 defines only in a DIFFERENT fence. A fence that carries its own definition (also
+#                 `declare -f name >/dev/null || name() {...}`) is fine. Comment lines are ignored.
+#                 Suppress a deliberate call with `allowlist:fence-funcs` on the same line.
+#                 Output: `FAIL <file>:<line> fence-funcs ...` then `SPEC-FENCE-FUNCS: ...`.
 #   --base <ref>   Only check blocks that contain a line changed relative to <ref>
 #                  (`git diff -U0 <ref> -- <file>`), so pre-existing blocks never fail
 #                  a new change. Without --base every block is checked.
@@ -53,8 +61,8 @@
 
 set -u
 
-BASE=""; SHELLCHECK=0; POSITIONAL=0; FILES=""; FENCESTATE=0; FSVARS=""
-usage() { echo "ERROR: Usage: check-spec-bash.sh [--base <git-ref>] [--shellcheck] <file.md>... | --positional [<file.md>...] | --fence-state <VAR>... -- <file.md>..." >&2; exit 2; }
+BASE=""; SHELLCHECK=0; POSITIONAL=0; FILES=""; FENCESTATE=0; FSVARS=""; FENCEFUNCS=0
+usage() { echo "ERROR: Usage: check-spec-bash.sh [--base <git-ref>] [--shellcheck] <file.md>... | --positional [<file.md>...] | --fence-state <VAR>... -- <file.md>... | --fence-funcs -- <file.md>..." >&2; exit 2; }
 
 while [ "$#" -gt 0 ]; do
   case "$1" in
@@ -69,6 +77,10 @@ while [ "$#" -gt 0 ]; do
       done
       [ "$#" -gt 0 ] && [ -n "$FSVARS" ] || usage
       shift ;;
+    --fence-funcs)
+      FENCEFUNCS=1; shift
+      [ "$#" -gt 0 ] && [ "$1" = "--" ] || usage
+      shift ;;
     --*) usage ;;
     *) FILES="$FILES
 $1"; shift ;;
@@ -78,7 +90,7 @@ done
 # No file arguments: default to the --positional check over every Skill-loaded spec under commands/
 # (orchestrate/**, pipeline-health/** and the review-pr-agents catalog are Read-loaded, not substituted).
 # Resolved relative to this script, so it works from any cwd and from linked worktrees.
-if [ -z "$FILES" ] && [ "$FENCESTATE" = 0 ] && { [ "$#" -eq 0 ] && [ "$POSITIONAL" = 0 ] && [ -z "$BASE" ] && [ "$SHELLCHECK" = 0 ] || [ "$POSITIONAL" = 1 ]; }; then
+if [ -z "$FILES" ] && [ "$FENCESTATE" = 0 ] && [ "$FENCEFUNCS" = 0 ] && { [ "$#" -eq 0 ] && [ "$POSITIONAL" = 0 ] && [ -z "$BASE" ] && [ "$SHELLCHECK" = 0 ] || [ "$POSITIONAL" = 1 ]; }; then
   POSITIONAL=1
   cd "$(dirname "$0")/.." || exit 2
   FILES=$(find commands -name '*.md' -not -path 'commands/orchestrate/*' \
@@ -127,6 +139,64 @@ EOS
   exit $?
 fi
 
+if [ "$FENCEFUNCS" = 1 ]; then
+  ffail=0; ffiles=0
+  while IFS= read -r f; do
+    [ -n "$f" ] || continue
+    case "$f" in *.md) ;; *) continue ;; esac
+    [ -f "$f" ] || { echo "SKIP $f missing"; continue; }
+    ffiles=$((ffiles + 1))
+    hits=$(awk -v f="$f" '
+      function isdef(line, name) {
+        return line ~ ("(^|[;&|{ \t])(function[ \t]+)?" name "[ \t]*[(][)]") || line ~ ("(^|[;&|{ \t])function[ \t]+" name "([ \t;{]|$)")
+      }
+      # A non-bash fence (prompt templates) can nest ```lang fences: track depth so they stay ignored.
+      other && /^[ \t]*```[A-Za-z]/ { depth++; next }
+      other && /^[ \t]*```[ \t]*$/ { if (depth > 0) depth--; else other = 0; next }
+      other { next }
+      !inb && /^[ \t]*```(bash|sh)[ \t]*$/ { inb = 1; nf++; next }
+      !inb && /^[ \t]*```/ { other = 1; depth = 0; next }
+      inb && /^[ \t]*```[ \t]*$/ { inb = 0; next }
+      inb {
+        n++; fen[n] = nf; ln[n] = NR; txt[n] = $0
+        if ($0 ~ /^[ \t]*#/) next
+        # Function definitions: `name()` or `function name`, wherever they sit on the line.
+        s = $0
+        while (match(s, /(^|[;&|{ \t])(function[ \t]+)?[A-Za-z_][A-Za-z0-9_]*[ \t]*[(][)]/)) {
+          d = substr(s, RSTART, RLENGTH); s = substr(s, RSTART + RLENGTH)
+          sub(/^[;&|{ \t]+/, "", d); sub(/^function[ \t]+/, "", d); sub(/[ \t]*[(][)]$/, "", d)
+          defn[d, nf] = 1; if (!(d in seen)) { seen[d] = 1; names[++nn] = d }
+        }
+        s = $0
+        while (match(s, /(^|[;&|{ \t])function[ \t]+[A-Za-z_][A-Za-z0-9_]*/)) {
+          d = substr(s, RSTART, RLENGTH); s = substr(s, RSTART + RLENGTH)
+          sub(/^[;&|{ \t]+/, "", d); sub(/^function[ \t]+/, "", d)
+          defn[d, nf] = 1; if (!(d in seen)) { seen[d] = 1; names[++nn] = d }
+        }
+      }
+      END {
+        for (k = 1; k <= nn; k++) {
+          name = names[k]
+          for (i = 1; i <= n; i++) {
+            if (defn[name, fen[i]] || reported[name, fen[i]]) continue
+            if (txt[i] ~ /^[ \t]*#/ || txt[i] ~ /allowlist:fence-funcs/) continue
+            if (txt[i] ~ ("(^[ \t]*|[;&|({][ \t]*|[$][(][ \t]*|(then|do|else|elif|if|while|until|!)[ \t]+)" name "([ \t;&|)]|$)")) {
+              reported[name, fen[i]] = 1
+              print "FAIL " f ":" ln[i] " fence-funcs: " name "() is called in a fence that does not define it (fresh shell per Bash call; defined only in another fence): " txt[i]
+            }
+          }
+        }
+      }
+    ' "$f" | LC_ALL=C sort -t: -k2,2n)
+    if [ -n "$hits" ]; then printf '%s\n' "$hits"; ffail=$((ffail + $(printf '%s\n' "$hits" | wc -l))); fi
+  done <<EOS
+$FILES
+EOS
+  echo "SPEC-FENCE-FUNCS: files=$ffiles violations=$ffail"
+  [ "$ffail" -eq 0 ]
+  exit $?
+fi
+
 if [ "$POSITIONAL" = 1 ]; then
   pfail=0; pfiles=0
   while IFS= read -r f; do

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

@@ -165,5 +165,55 @@ 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-funcs: a function defined only in another fence, then called, is flagged.
+cat > "$T/ff-bad.md" <<EOF
+${FENCE}bash
+helper() {
+  echo hi
+}
+helper
+${FENCE}
+${FENCE}bash
+X=\$(helper arg)
+${FENCE}
+${FENCE}bash
+if helper; then :; fi
+${FENCE}
+EOF
+cat > "$T/ff-good.md" <<EOF
+Prose calls helper and mentions helper() freely.
+${FENCE}bash
+helper() { echo hi; }
+function other_fn { :; }
+helper
+${FENCE}
+${FENCE}bash
+declare -f helper >/dev/null 2>&1 || helper() { echo hi; }
+helper
+${FENCE}
+${FENCE}bash
+# helper is only named in a comment
+declare -f helper >/dev/null 2>&1
+echo "call helper later"
+git log --grep helper
+helper # allowlist:fence-funcs
+${FENCE}
+${FENCE}text
+helper
+${FENCE}
+${FENCE}
+Template with a nested fence:
+${FENCE}bash
+helper
+${FENCE}
+${FENCE}
+EOF
+check 1 "FAIL ff-bad.md:8 fence-funcs: helper()"  "--fence-funcs flags a call in a fence without the definition" -- --fence-funcs -- ff-bad.md
+check 1 "FAIL ff-bad.md:11 fence-funcs: helper()" "--fence-funcs flags a call after if" -- --fence-funcs -- ff-bad.md
+check 1 "violations=2"                           "--fence-funcs counts violations"  -- --fence-funcs -- ff-bad.md
+check 0 "violations=0"                           "--fence-funcs passes same-fence defs, guarded redefinition, comments, quoted/arg uses, allowlist, prose, non-bash fences" -- --fence-funcs -- ff-good.md
+check 2 "Usage"                                  "--fence-funcs without -- is a usage error" -- --fence-funcs ff-good.md
+check 2 "Usage"                                  "--fence-funcs without files is a usage error" -- --fence-funcs --
+
 echo "check-spec-bash.test.sh: passed=$pass failed=$fail"
 [ "$fail" -eq 0 ]

package/scripts/check-spec-markers.sh

@@ -127,6 +127,7 @@ MARKER_REGISTRY="
   INPR_FIX
   INPR_FIX_WAIVED
   INPR_REMEDIATION
+  INVESTIGATION
   INVESTIGATOR
   JSONL_PARSER_UTIL
   KNOWLEDGE_GIST
@@ -161,6 +162,7 @@ MARKER_REGISTRY="
   RECOVERY_CLAIM
   RECOVERY_CLAIM_RELEASED
   REMEDIATION
+  REMEDIATION_HELD
   REREVIEW_DISPATCHED
   REREVIEW_RELEASED
   REREVIEW_SKIPPED

package/scripts/checkbox-sections.test.sh

@@ -49,4 +49,23 @@ SINGLE_BODY=$'## Acceptance Criteria\n- [ ] complete this work'
   exit 1
 }
 
+# forge#3545: the investigate placeholder box is scaffolding and must not form a section.
+PLACEHOLDER_SECOND=$'## Success Criteria\n- [ ] real work\n\n## Acceptance Criteria\n- [ ] Fix confirmed during investigation.'
+[[ "$(printf '%s\n' "$PLACEHOLDER_SECOND" | awk "$CLOSE_CLASSIFIER")" == "1" ]] || {
+  printf 'FAIL: placeholder box must not count as a second checkbox section\n' >&2
+  exit 1
+}
+PLACEHOLDER_ONLY=$'## Acceptance Criteria\n- [ ] Fix confirmed during investigation.'
+[[ "$(printf '%s\n' "$PLACEHOLDER_ONLY" | awk "$CLOSE_CLASSIFIER")" == "0" ]] || {
+  printf 'FAIL: placeholder-only body must count zero checkbox sections\n' >&2
+  exit 1
+}
+grep -Fq 'Fix confirmed during investigation' "$ROOT/commands/work-on/close.md" || {
+  printf 'FAIL: close.md must exclude the investigate placeholder\n' >&2
+  exit 1
+}
+# REMAINING_BEFORE must also ignore the placeholder (placeholder-only body => 0).
+REM=$(printf '%s\n' "$PLACEHOLDER_ONLY" | grep -vE '^[-*+] \[ \] Fix confirmed during investigation\.?[[:space:]]*$' | grep -cE '^[-*+] \[ \]' || true)
+[[ "$REM" == "0" ]] || { printf 'FAIL: placeholder counted in REMAINING_BEFORE\n' >&2; exit 1; }
+
 printf 'PASS: close-path classifier supports setext section boundaries\n'

package/scripts/classify-finding.sh

@@ -11,6 +11,7 @@
 #   classify-finding.sh --severity <S> [--confidence <C>] [--agent <A>]
 #                       [--lineage none|review-finding] [--text <T> | --text-file <F>]
 #                       [--inpr-diff <F> --file <P>] [--contract-scope <F> --contract-open <F> [--pr-files <F>] [--merge-issue <N>]]
+#                       [--prior-findings <F> [--title <T>] [--line-start <N> [--line-end <M>]] [--diff-map <F>]]
 #
 #   --severity    CRITICAL | HIGH | MEDIUM | LOW (case-insensitive). Missing or
 #                 unparseable → ISSUE (fail toward filing, never drop).
@@ -45,6 +46,25 @@
 #                 `--pr-files <F>` is the PR's changed paths, one per line, supplied for this guard
 #                 alone (it never triggers INPR_FIX). The gate runs after the severity and in-PR gates. Without the flags output is unchanged.
 #
+#   --prior-findings <F> --file <P> [--title <T>] [--line-start <N> [--line-end <M>]] [--diff-map <F>]
+#                 Cross-head / cross-PR re-flag gate: F is a TSV of findings already raised for an
+#                 earlier head of this PR or by a bundle's member PRs, one per line, columns
+#                 file<TAB>line-start<TAB>line-end<TAB>title<TAB>prior-disposition<TAB>issue#.
+#                 prior-disposition is `filed` (its issue is still open), `filed-closed` (issue closed:
+#                 the row is IGNORED so a regressed defect is classified normally), `note` (a recorded NOTE) or
+#                 `unknown` (a reviewer-body row whose issue linkage failed: it is IGNORED for a MEDIUM
+#                 CONFIRMED/LIKELY finding so it can never suppress one, and behaves like `note` otherwise).
+#                 Line columns may be empty (NOTE-sourced rows carry no range). A finding re-flags a row
+#                 when it is the same file AND ((line IoU >= 0.6 and >= 1 shared title token), or >= 3 shared title tokens). Output is
+#                 `NOTE reflag-filed #N` (row has an issue number) or `NOTE reflag-note`; this gate never
+#                 emits ISSUE. `--file` may carry `path:line`; explicit --line-start wins.
+#                 `--diff-map <F>` (optional, best-effort) lists `git diff <old>..<new>` hunks as
+#                 file<TAB>old-start<TAB>old-count<TAB>new-start<TAB>new-count; a prior range lying
+#                 wholly after hunks is shifted by their net line delta before the IoU. A missing or
+#                 unparseable map means the unshifted range is used. The gate runs after the severity
+#                 parse (HIGH/CRITICAL and unparseable severity stay ISSUE) and before the in-PR gate.
+#                 Without the flags output is unchanged.
+#
 # Output (stdout, one line): `ISSUE <reason>`, `NOTE <reason>` or `INPR_FIX <reason>`.
 # Exit codes: 0 classified, 2 usage error.
 #
@@ -80,9 +100,14 @@ CONTRACT_SCOPE=""
 CONTRACT_OPEN=""
 PR_FILES=""
 MERGE_ISSUE=""
+PRIOR_FINDINGS=""
+TITLE=""
+LINE_START=""
+LINE_END=""
+DIFF_MAP=""
 
 usage() {
-  echo "ERROR: Usage: classify-finding.sh --severity <S> [--confidence <C>] [--agent <A>] [--lineage none|review-finding] [--text <T> | --text-file <F>] [--inpr-diff <F> --file <P>] [--contract-scope <F> --contract-open <F> [--pr-files <F>] [--merge-issue <N>]]" >&2
+  echo "ERROR: Usage: classify-finding.sh --severity <S> [--confidence <C>] [--agent <A>] [--lineage none|review-finding] [--text <T> | --text-file <F>] [--inpr-diff <F> --file <P>] [--contract-scope <F> --contract-open <F> [--pr-files <F>] [--merge-issue <N>]] [--prior-findings <F> [--title <T>] [--line-start <N> [--line-end <M>]] [--diff-map <F>]]" >&2
   exit 2
 }
 
@@ -99,6 +124,11 @@ while [ "$#" -gt 0 ]; do
     --contract-open)  [ "$#" -ge 2 ] || usage; CONTRACT_OPEN="$2"; shift 2 ;;
     --pr-files)       [ "$#" -ge 2 ] || usage; PR_FILES="$2"; shift 2 ;;
     --merge-issue)    [ "$#" -ge 2 ] || usage; MERGE_ISSUE="${2#\#}"; shift 2 ;;
+    --prior-findings) [ "$#" -ge 2 ] || usage; PRIOR_FINDINGS="$2"; shift 2 ;;
+    --title)          [ "$#" -ge 2 ] || usage; TITLE="$2"; shift 2 ;;
+    --line-start)     [ "$#" -ge 2 ] || usage; LINE_START="$2"; shift 2 ;;
+    --line-end)       [ "$#" -ge 2 ] || usage; LINE_END="$2"; shift 2 ;;
+    --diff-map)       [ "$#" -ge 2 ] || usage; DIFF_MAP="$2"; shift 2 ;;
     --text-file)
       [ "$#" -ge 2 ] || usage
       [ -r "$2" ] || { echo "ERROR: --text-file not readable: $2" >&2; exit 2; }
@@ -127,6 +157,10 @@ if [ -n "$PR_FILES" ] && [ ! -r "$PR_FILES" ]; then
   echo "ERROR: --pr-files not readable: $PR_FILES" >&2; exit 2
 fi
 
+if [ -n "$PRIOR_FINDINGS" ] && [ ! -r "$PRIOR_FINDINGS" ]; then
+  echo "ERROR: --prior-findings not readable: $PRIOR_FINDINGS" >&2; exit 2
+fi
+
 upper() { printf '%s' "$1" | tr '[:lower:]' '[:upper:]' | tr -d '[:space:]'; }
 SEV=$(upper "$SEVERITY")
 CONF=$(upper "$CONFIDENCE")
@@ -137,6 +171,74 @@ case "$SEV" in
   *) echo "ISSUE unparseable-severity"; exit 0 ;;
 esac
 
+# Cross-head / cross-PR re-flag gate (#3641). Runs after the severity parse so HIGH/CRITICAL and
+# unparseable severity have already exited as ISSUE. Emits only NOTE; fails toward the normal
+# classification below on a missing file, no match, or an unusable diff map.
+if [ -n "$PRIOR_FINDINGS" ] && [ -n "$FINDING_FILE" ]; then
+  _rpath="${FINDING_FILE#./}"; _rline=""
+  case "$_rpath" in *:[0-9]*) _rline="${_rpath#*:}"; _rline="${_rline%%[!0-9]*}" ;; esac
+  _rpath="${_rpath%%:*}"
+  _rls="${LINE_START:-$_rline}"; _rle="${LINE_END:-$_rls}"
+  case "$_rls" in ''|*[!0-9]*) _rls=""; _rle="" ;; esac
+  case "$_rle" in ''|*[!0-9]*) _rle="$_rls" ;; esac
+  _dmap="$DIFF_MAP"; { [ -n "$_dmap" ] && [ -r "$_dmap" ]; } || _dmap=""
+  _reflag=$(awk -F '\t' -v file="$_rpath" -v ls="$_rls" -v le="$_rle" -v title="$TITLE" -v dmap="$_dmap" -v sev="$SEV" -v conf="$CONF" '
+    function toks(str, arr,    n, i, parts, t, c) {
+      c = 0; str = tolower(str); gsub(/[^a-z0-9]+/, " ", str)
+      n = split(str, parts, " ")
+      for (i = 1; i <= n; i++) { t = parts[i]; if (length(t) >= 3 && !(t in arr)) { arr[t] = 1; c++ } }
+      return c
+    }
+    function shift(f, s, e,    k, delta) {
+      delta = 0
+      for (k = 1; k <= nh; k++)
+        if (hf[k] == f && (hc[k] == 0 ? ho[k] < s : ho[k] + hc[k] <= s)) delta += hc2[k] - hc[k]
+      return delta
+    }
+    BEGIN {
+      if (dmap != "") {
+        while ((getline line < dmap) > 0) {
+          if (split(line, p, "\t") >= 5 && p[2] ~ /^[0-9]+$/ && p[3] ~ /^[0-9]+$/ && p[4] ~ /^[0-9]+$/ && p[5] ~ /^[0-9]+$/) {
+            nh++; hf[nh] = p[1]; ho[nh] = p[2] + 0; hc[nh] = p[3] + 0; hn[nh] = p[4] + 0; hc2[nh] = p[5] + 0
+          }
+        }
+        close(dmap)
+      }
+      # Generic words count toward the token set but never as topical similarity (#3719).
+      ns = split("the and with for from before after write read when that this into not are but can has have via use using does should may all any only also than then over under without within while where which what its it was were been being each both one two", sw, " ")
+      for (i = 1; i <= ns; i++) stop[sw[i]] = 1
+      ntitle = toks(title, ft)
+    }
+    {
+      pf = $1; sub(/^\.\//, "", pf)
+      if (pf != file) next
+      if ($5 == "filed-closed") next
+      if ($5 == "unknown" && sev == "MEDIUM" && (conf == "CONFIRMED" || conf == "LIKELY")) next
+      hit = 0
+      delete pt; toks($4, pt); shared = 0; cshared = 0
+      for (t in pt) if (t in ft) { shared++; if (!(t in stop)) cshared++ }
+      # Line overlap alone is not a match (an unrelated finding can land on the same line): it also
+      # needs at least one shared non-stopword title token. Title-only matching needs >= 3 shared
+      # tokens, of which >= 2 are non-stopword (generic words never count as topical similarity).
+      if (cshared >= 1 && ls != "" && $2 ~ /^[0-9]+$/) {
+        ps = $2 + 0; pe = ($3 ~ /^[0-9]+$/) ? $3 + 0 : ps
+        if (pe < ps) pe = ps
+        d = shift(pf, ps, pe); ps += d; pe += d
+        lo = (ps > ls) ? ps : ls; hi = (pe < le) ? pe : le
+        inter = hi - lo + 1; if (inter < 0) inter = 0
+        uni = (pe - ps + 1) + (le - ls + 1) - inter
+        if (uni > 0 && inter / uni >= 0.6) hit = 1
+      }
+      if (!hit && ntitle >= 3 && shared >= 3 && cshared >= 2) hit = 1
+      if (!hit) next
+      if ($5 == "filed" && $6 ~ /^#?[0-9]+$/) { n = $6; sub(/^#/, "", n); print "NOTE reflag-filed #" n; found = 1; exit }
+      if (!note) note = "NOTE reflag-note"
+    }
+    END { if (!found && note) print note }
+  ' "$PRIOR_FINDINGS" 2>/dev/null) || _reflag=""
+  if [ -n "$_reflag" ]; then echo "$_reflag"; exit 0; fi
+fi
+
 # In-PR fix gate (#3387, narrowed). MEDIUM CONFIRMED is an ISSUE under every rule below
 # (lineage included), so checking here changes only where it is handled, never whether.
 if [ -n "$INPR_DIFF" ] && [ -n "$FINDING_FILE" ] && [ "$SEV" = "MEDIUM" ] && [ "$CONF" = "CONFIRMED" ]; then

package/scripts/classify-finding.test.sh

@@ -152,6 +152,62 @@ rm -f "$CSCOPE" "$COPEN"
 expect_exit 2 "unreadable --contract-scope"   -- --severity MEDIUM --contract-scope /nonexistent/s --file x
 expect_exit 2 "unreadable --contract-open"    -- --severity MEDIUM --contract-open /nonexistent/o --file x
 
+# --- Cross-head / cross-PR re-flag gate (#3641) ---
+expect_out() { # expect_out <full output> <description> -- args...
+  want="$1"; desc="$2"; shift 3
+  got=$(bash "$S" "$@" 2>/dev/null)
+  if [ "$got" = "$want" ]; then pass=$((pass+1)); else fail=$((fail+1)); echo "FAIL: $desc (want '$want', got '${got}')"; fi
+}
+TAB=$(printf '\t')
+PRIOR=$(mktemp "${TMPDIR:-/tmp}/classify-finding-prior.XXXXXX")
+DMAP=$(mktemp "${TMPDIR:-/tmp}/classify-finding-dmap.XXXXXX")
+{
+  printf 'src/sync.sh\t40\t50\tlock released before write completes\tnote\t\n'
+  printf 'src/api.py\t10\t20\tmissing retry on timeout handler\tfiled\t123\n'
+  printf 'src/closed.py\t5\t15\tstale cache entry never evicted\tfiled-closed\t77\n'
+  printf 'src/notes.py\t\t\tduplicated predicate counted twice\tnote\t\n'
+  printf 'src/unlinked.py\t30\t40\tunvalidated redirect target in login handler\tunknown\t\n'
+} > "$PRIOR"
+PF=(--prior-findings "$PRIOR")
+M=(--severity MEDIUM --confidence CONFIRMED)
+
+expect_out "NOTE reflag-note" "re-flag by line IoU (same range)" -- "${M[@]}" "${PF[@]}" --file src/sync.sh --line-start 42 --line-end 50 --title "lock handling wording here"
+expect_out "NOTE reflag-note" "re-flag via path:line tolerated" -- "${M[@]}" "${PF[@]}" --file src/sync.sh:41 --line-end 50 --title "lock x"
+printf 'src/sync.sh\t1\t2\t1\t12\n' > "$DMAP"   # 2 lines became 12: prior 40-50 is now 50-60
+expect_out "NOTE reflag-note" "re-flag after the line moved, shifted by diff map" -- "${M[@]}" "${PF[@]}" --diff-map "$DMAP" --file src/sync.sh --line-start 50 --line-end 60 --title "lock something else"
+expect ISSUE "line moved with no diff map does not match" -- "${M[@]}" "${PF[@]}" --file src/sync.sh --line-start 50 --line-end 60 --title "lock something else"
+printf 'garbage\n' > "$DMAP"
+expect_out "NOTE reflag-note" "unparseable diff map falls back to unshifted range" -- "${M[@]}" "${PF[@]}" --diff-map "$DMAP" --file src/sync.sh --line-start 41 --line-end 50 --title "lock x"
+expect_out "NOTE reflag-note" "re-flag by title tokens (far line)" -- "${M[@]}" "${PF[@]}" --file src/sync.sh --line-start 300 --title "Lock released before the write"
+expect_out "NOTE reflag-note" "NOTE row with empty line columns matches by title" -- "${M[@]}" "${PF[@]}" --file src/notes.py --line-start 9 --title "Duplicated predicate is counted twice"
+expect ISSUE "same line, different topic MEDIUM CONFIRMED is not swallowed (SEC-1)" -- "${M[@]}" --agent security "${PF[@]}" --file src/sync.sh --line-start 42 --line-end 50 --title "SQL injection via unsanitized token"
+expect ISSUE "same line with no title at all is not swallowed" -- "${M[@]}" "${PF[@]}" --file src/sync.sh --line-start 42 --line-end 50
+expect_out "NOTE reflag-note" "same line, same topic (one shared token) still NOTE" -- "${M[@]}" "${PF[@]}" --file src/sync.sh --line-start 42 --line-end 50 --title "Lock handling is racy"
+expect ISSUE "same line, only a stopword-class word shared is not swallowed (#3719)" -- "${M[@]}" "${PF[@]}" --file src/sync.sh --line-start 42 --line-end 50 --title "Path traversal in the write target"
+expect ISSUE "far line, only generic words shared is not swallowed (#3719)" -- "${M[@]}" "${PF[@]}" --file src/sync.sh --line-start 300 --title "Command injection before write with the lock"
+expect ISSUE "non-overlapping same-file finding is classified normally" -- "${M[@]}" "${PF[@]}" --file src/sync.sh --line-start 200 --line-end 210 --title "missing bounds check"
+expect ISSUE "two shared tokens are not enough"       -- "${M[@]}" "${PF[@]}" --file src/sync.sh --line-start 200 --title "lock released late"
+expect ISSUE "same title on a different file is classified normally" -- "${M[@]}" "${PF[@]}" --file src/other.sh --line-start 45 --title "lock released before write completes"
+expect ISSUE "unknown row does not demote MEDIUM CONFIRMED (unlinked prior)" -- "${M[@]}" "${PF[@]}" --file src/unlinked.py --line-start 300 --title "Unvalidated redirect target in the login handler"
+expect ISSUE "unknown row does not demote MEDIUM CONFIRMED by line IoU" -- "${M[@]}" "${PF[@]}" --file src/unlinked.py --line-start 32 --line-end 40 --title "redirect target unchecked"
+expect ISSUE "unknown row does not demote MEDIUM LIKELY" -- --severity MEDIUM --confidence LIKELY "${PF[@]}" --file src/unlinked.py --line-start 300 --title "Unvalidated redirect target in the login handler"
+expect_out "NOTE reflag-note" "unknown row still demotes LOW" -- --severity LOW --confidence CONFIRMED "${PF[@]}" --file src/unlinked.py --line-start 300 --title "Unvalidated redirect target in the login handler"
+expect_out "NOTE reflag-note" "unknown row still demotes MEDIUM POSSIBLE" -- --severity MEDIUM --confidence POSSIBLE "${PF[@]}" --file src/unlinked.py --line-start 300 --title "Unvalidated redirect target in the login handler"
+expect ISSUE "HIGH unaffected by unknown row" -- --severity HIGH --confidence CONFIRMED "${PF[@]}" --file src/unlinked.py --line-start 300 --title "Unvalidated redirect target in the login handler"
+expect_out "NOTE reflag-filed #123" "re-flag of an already-filed issue links it" -- "${M[@]}" "${PF[@]}" --file src/api.py --line-start 12 --line-end 18 --title "retry x"
+expect_out "NOTE reflag-filed #123" "filed re-flag by title tokens" -- "${M[@]}" "${PF[@]}" --file src/api.py --line-start 99 --title "Missing retry on timeout"
+expect ISSUE "filed-closed row is ignored (regression not swallowed)" -- "${M[@]}" "${PF[@]}" --file src/closed.py --line-start 5 --line-end 15 --title "stale cache entry never evicted"
+expect ISSUE "HIGH is never demoted by a re-flag"     -- --severity HIGH --confidence CONFIRMED "${PF[@]}" --file src/api.py --line-start 12 --line-end 18 --title "missing retry on timeout handler"
+expect ISSUE "CRITICAL is never demoted by a re-flag" -- --severity CRITICAL "${PF[@]}" --file src/api.py --line-start 12 --line-end 18
+expect ISSUE "unparseable severity is never demoted"  -- --severity INFO "${PF[@]}" --file src/api.py --line-start 12 --line-end 18
+expect ISSUE "no --file: gate skipped"                -- "${M[@]}" "${PF[@]}" --title "lock released before write completes"
+expect ISSUE "no --prior-findings: unchanged"         -- "${M[@]}" --file src/api.py --line-start 12 --line-end 18
+expect NOTE  "re-flag wins over in-PR fix gate"       -- "${M[@]}" "${PF[@]}" --file src/api.py --line-start 12 --line-end 18 --title "retry gap" --inpr-diff "$PRIOR"
+: > "$PRIOR"
+expect ISSUE "empty prior-findings: unchanged"        -- "${M[@]}" "${PF[@]}" --file src/api.py --line-start 12 --line-end 18 --title "missing retry"
+rm -f "$PRIOR" "$DMAP"
+expect_exit 2 "unreadable --prior-findings"   -- --severity MEDIUM --prior-findings /nonexistent/p --file x
+
 # --- usage errors ---
 expect_exit 2 "unknown flag"                  -- --bogus x
 expect_exit 2 "bad lineage"                   -- --severity LOW --lineage P3