@dev-loops/core 1.0.1 → 1.0.2-slim.0

package/src/loop/bash-command-classify.mjs

@@ -26,7 +26,7 @@ const SHELL_SEGMENT_SEPARATOR = /\s*(?:&&|\|\||;|\||\n|\r)\s*/;
 /**
  * Strip a single balanced surrounding quote pair (`'…'` or `"…"`) from a shell arg value.
  * A repo flag value may reach us quoted (`--repo 'owner/name'`); the scope check compares against
- * the bare slug, so quotes must be normalized or a quoted on-target repo evades the guard (#1074).
+ * the bare slug, so quotes must be normalized or a quoted on-target repo evades the guard.
  * ponytail: single balanced pair only — no full shell tokenization (mismatched/partial quotes stay).
  * @param {string|null} value @returns {string|null}
  */
@@ -43,7 +43,7 @@ function stripSurroundingQuotes(value) {
  * Read an inline `GH_REPO=<value>` env-assignment prefix on a single command segment.
  * `gh` resolves its target repo from the `GH_REPO` env var, and a segment may set it inline
  * (`GH_REPO=owner/name gh issue create …`) — same targeting intent as `--repo owner/name`, so the
- * scope check must treat it the same or an off-cwd redirect evades the guard (#1074). Only the
+ * scope check must treat it the same or an off-cwd redirect evades the guard. Only the
  * FIRST leading env assignment matching `GH_REPO=` is read (env assignments precede the executable);
  * the value is quote-normalized. Ambient `process.env.GH_REPO` is out of scope — this is a static
  * command-string classifier, so only the inline assignment in the string is considered.
@@ -177,16 +177,15 @@ const GIT_GLOBAL_OPTION_RUN =
   "(?:(?:-C|-c)\\s+\\S+\\s+|--(?:git-dir|work-tree)=\\S+\\s+|--?[A-Za-z][\\w-]*\\s+)*";
 
 /**
- * Whether `command` contains a `git stash` invocation (any subcommand: bare, `push`, `pop`,
- * `apply`, `save`, `list`, ...) in ANY shell segment — including behind the same env-assignment /
- * `command`/`env`/`exec` wrapper / binary-path prefix (`GIT_DIR=.git git stash`, `command git
- * stash`, `/usr/bin/git stash`) and git global options between `git` and `stash` (`git -C /tmp
- * stash`, `git -c name=value stash pop`) that the sibling `gh` classifiers in this file already
- * tolerate. Anchored per-segment, so `git stashed`, `git commit -m "git stash"`, or a path literal
- * containing "git stash" never match. `refs/stash` is a single ref shared by every worktree over
- * this repo's one `.git` directory, so a stash from one worktree can pop into another's — the
- * PreToolUse gate blocks it outright on the target repo (see
- * `skills/docs/worktree-guidance.md#never-git-stash-in-a-shared-git-layout`).
+ * Whether `command` contains a `git stash` invocation (any subcommand: bare,
+ * `push`, `pop`, `apply`, `save`, `list`, ...) in ANY shell segment —
+ * including behind an env-assignment/wrapper/path prefix and git global
+ * options between `git` and `stash` (mirrors the `gh` classifiers' tolerance
+ * in this file). Anchored per-segment, so `git stashed` or a path literal
+ * containing "git stash" never match. `refs/stash` is shared by every
+ * worktree over this repo's one `.git` directory, so a stash from one
+ * worktree can pop into another's — the PreToolUse gate blocks it outright
+ * (see `skills/docs/worktree-guidance.md#never-git-stash-in-a-shared-git-layout`).
  * @param {string} command @returns {boolean}
  */
 export function commandContainsGitStash(command) {
@@ -237,7 +236,7 @@ function extractRepoFlagFromSubcmdSegment(segment, subcmd, verb) {
     if (repoEqMatch) return stripSurroundingQuotes(repoEqMatch[1]);
   }
   // No explicit --repo/-R flag: fall back to an inline GH_REPO= env assignment (flag wins,
-  // mirroring gh's own precedence). This closes the GH_REPO repo-targeting bypass (#1074).
+  // mirroring gh's own precedence). This closes the GH_REPO repo-targeting bypass.
   return extractGhRepoEnvAssignment(segment);
 }
 
@@ -379,7 +378,7 @@ function extractRepoFlagFromSegment(segment, verb) {
   }
   // No explicit --repo/-R flag: fall back to an inline GH_REPO= env assignment (flag wins,
   // mirroring gh's own precedence). Applied here too so gh pr ready/merge/create scope checks get
-  // consistent GH_REPO handling — the root-cause fix, not just the external-write path (#1074).
+  // consistent GH_REPO handling — the root-cause fix, not just the external-write path.
   return extractGhRepoEnvAssignment(segment);
 }
 
@@ -498,21 +497,20 @@ export function extractRepoFlagFromGhPrMerge(command) {
 }
 
 // ---------------------------------------------------------------------------
-// gh api URL-path matchers + the six guard-rule classifiers (#1622).
+// gh api URL-path matchers + the six guard-rule classifiers.
 // These make the six rules that describe operations the Bash gate could refuse
 // enforceable at one seam (decideBashGate in hook-decisions.mjs), where raw
 // `gh api` shapes were previously unclassified (anything expressed as a raw API
 // call was invisible to the gate).
 // ---------------------------------------------------------------------------
 
-/** gh api value-taking flags (short forms). Each consumes the following token. Lowercase (compared
- * against token.toLowerCase()) — covers every value-taking short flag gh api accepts so a flag
- * placed BEFORE the endpoint skips its value and the real endpoint is still read (#1622):
- * -X/--method, -m/--method, -f/--field, -F/--raw-field (both case-fold to -f), -q/--jq, -p/--preview,
- * -t/--template, -r/--repo. `-h` (help) is intentionally EXCLUDED: it is a boolean help flag that
- * consumes no value, and case-folding it together with `-H` (header) made a mid-command `-h`
- * swallow the real endpoint and bypass the write-path deny (#1622). `-H` is matched as an exact
- * token in the scanner so it stays a value-taking flag despite the case-fold. */
+/** gh api value-taking flags (short forms); each consumes the following token. Lowercase-compared,
+ * covering every value-taking short flag gh api accepts so a flag placed BEFORE the endpoint skips
+ * its value and the real endpoint is still read: -X/--method, -m/--method, -f/--field, -F/--raw-field
+ * (both case-fold to -f), -q/--jq, -p/--preview, -t/--template, -r/--repo. `-h` (help) is EXCLUDED —
+ * it takes no value, and folding it with `-H` (header) would let a mid-command `-h` swallow the real
+ * endpoint and bypass the write-path deny. `-H` stays an exact-token value-taking flag
+ * despite the case-fold. */
 const GH_API_VALUE_FLAGS = new Set(["-x", "-m", "-f", "-r", "-q", "-p", "-t"]);
 /** gh api value-taking flags (long forms). Each consumes the following token. */
 const GH_API_VALUE_LONG_FLAGS = new Set([
@@ -588,7 +586,7 @@ function targetGhApiPathRegex(suffix) {
 /** Strip a `scheme://host` prefix from an absolute gh api URL endpoint (`https://api.github.com/...`),
  * yielding the bare `/repos/<slug>/…` path that the write-path anchors match. gh api accepts both a
  * bare `repos/<slug>/…`/`issues/…` path and an absolute https:// URL, so both must reach the same
- * anchors or an absolute-URL write bypasses the deny (#1622). */
+ * anchors or an absolute-URL write bypasses the deny. */
 function normalizeGhApiEndpoint(endpoint) {
   if (!endpoint) return endpoint;
   return endpoint.replace(/^https?:\/\/[^/]+/, "").replace(/^\//, "").replace(/\/+$/, "");
@@ -679,14 +677,10 @@ export function commandContainsCopilotRequestBypass(command) {
  */
 export function commandContainsCopilotSummonComment(command) {
   if (!findGhSubcmdVerbSegment(command, "pr", "comment")) return false;
-  // A bare summon is `/copilot` or `/copilot re-review` on its own (optionally quoted) — never a
-  // prose mention like `see /copilot for more` / `see /copilot docs`. A bare `/copilot` must run to
-  // the end of the (quoted) body; the explicit `re-review` form allows trailing modifiers
-  // (`/copilot re-review now`) so appending a word cannot defeat the summon deny (#1622).
-  // A summon is `/copilot`/`/copilot re-review` at the START of the quoted body — anchored on the
-  // opening quote so a trailing prose mention (`--body "see /copilot"` / `"thanks /copilot"`) is
-  // NOT misread as a bare summon, and an in-prose `/copilot re-review` (`"see ... re-review in
-  // docs"`) is likewise not a summon. Only `gh pr comment` segments reach here (guard above).
+  // A summon is `/copilot`/`/copilot re-review` anchored at the START of the quoted body — a
+  // trailing prose mention (`--body "see /copilot"`) or in-prose `/copilot re-review` never
+  // matches. The `re-review` form allows trailing modifiers (`/copilot re-review now`) so
+  // appending a word cannot defeat the deny. Only `gh pr comment` segments reach here.
   return /(["'])\s*\/copilot(?:\s+re-review\b(?:\s+[^\s"']+)*|\s*(?:["']|$))/i.test(command);
 }
 
@@ -699,17 +693,10 @@ export function commandContainsCopilotSummonComment(command) {
  */
 export function commandContainsDetachedWaitTool(command) {
   const whole = command.trim();
-  // while/until/seq polling loop with both a sleep and a gh or loop-state call. The loop body is
-  // `;`-delimited, so this is checked against the whole command (a per-segment split would
-  // separate the `while` head from the `sleep`/`gh` body calls and miss the pattern).
-  // A polling loop is detected wherever the `while`/`until`/`seq` head appears (a leading expression
-  // like `gh pr view 1 && while ...` must not silence the deny) as long as the body carries both a
-  // `sleep` and a gh/loop-state call. `gh` must be a standalone token (followed by whitespace/end) —
-  // a bare mention of `gh` inside another word (`grep gh-notes`) is not a GitHub call.
-  // while/until/for loop heads (a bare `seq` sequence generator is not a loop head on its own —
-  // `seq | while read` is caught by the `while` head), with `sleep` and a gh/loop-state *call*.
-  // loop-state must sit at a command-head position (`; lo`, `&& lo`, start), not be a substring of
-  // a grep/echo target (no false-deny on `grep loop-state x`).
+  // Checked on the WHOLE command (not per-segment): the `while`/`until`/`for` loop body is
+  // `;`-delimited, so a per-segment split would separate the loop head from its `sleep`/`gh`
+  // body calls and miss the pattern. `gh` must be a standalone token (not `grep gh-notes`), and
+  // `loop-state` must sit at a command-head position (not a substring inside `grep loop-state x`).
   if (/(?:while|until|for)\b/i.test(whole) && /\bsleep\b/.test(whole) && /\bgh(?=\s|$)|(?:^|[;&|(])\s*loop-state(?=\s|$)/.test(whole)) {
     return true;
   }
@@ -730,11 +717,9 @@ function interpreterRegex(bin) {
 
 /**
  * OPS-NO-INLINE-INTERPRETER: an inline interpreter — `node -e`/`--eval`/`-p`, `python3 -c`, or a
- * heredoc fed to node/python (`node - <<EOF`, `python3 - <<EOF`). Ported from the long-orphaned
- * inline-interpreter classifier in the retrospective-tooling check (zero production callers). Sanctioned
- * output parsing uses `--jq`/`--silent`, never an inline interpreter. Actor-independent: the rule bars
- * "Coordinator and agent flows" (both actors). Script-path invocations (running a `.mjs` file,
- * `python3 script.py`) never match.
+ * heredoc fed to node/python (`node - <<EOF`, `python3 - <<EOF`). Sanctioned output parsing uses
+ * `--jq`/`--silent`, never an inline interpreter. Actor-independent (bars both coordinator and
+ * agent flows). Script-path invocations (running a `.mjs` file, `python3 script.py`) never match.
  * @param {string} command @returns {boolean}
  */
 export function commandContainsInlineInterpreter(command) {
@@ -748,7 +733,7 @@ export function commandContainsInlineInterpreter(command) {
       const tokens = code.split(/\s+/).filter(Boolean);
       // Node value-taking flags (short + long) each consume the following token. Consuming them lets
       // a value-taking flag BEFORE the interpreter flag (`node --require ./setup.js -e "..."`) route
-      // on to `-e`/`--eval`/`-p` instead of breaking the scan at the flag's value (#1622).
+      // on to `-e`/`--eval`/`-p` instead of breaking the scan at the flag's value.
       const NODE_VALUE_FLAGS = new Set(["-r", "--require", "--import", "--loader", "--experimental-loader", "--env-file", "--conditions", "-C", "--cwd"]);
       for (let i = 0; i < tokens.length; i++) {
         const t = tokens[i];

package/src/loop/commit-msg-guard.mjs

@@ -84,7 +84,7 @@ if (process.env.CLAUDECODE === "1") {
     errors.push("missing required trailer: Co-Authored-By: Claude <model> <noreply@anthropic.com>");
   }
   if (!/^Claude-Session:\s*\S+/imu.test(message)) {
-    errors.push("missing required trailer: Claude-Session: <url>");
+    errors.push("missing required trailer: Claude-Session: <url> (e.g. Claude-Session: https://claude.ai/code/session_abc123)");
   }
 }
 

package/src/loop/conductor-routing.mjs

@@ -1,30 +1,22 @@
 /**
- * Conductor routing contract: deterministic routing and handoff decisions
- * above family-local state machines.
- *
- * This module provides:
- * - ROUTING_OUTCOME: closed routing outcome taxonomy constants
- * - LOOP_FAMILY: loop family identifier constants
- * - SOURCE_MODE: confidence/source mode constants
- * - ENTRYPOINT: handoff entrypoint identifier constants
- * - STOP_REASON: stop reason code constants (for outer-loop backward compat)
- * - evaluateConductorRouting: shared evaluator/policy entrypoint
+ * Conductor routing contract: deterministic routing and handoff decisions above
+ * family-local state machines. See skills/docs/conductor-routing-contract.md.
  *
  * Contract guarantees:
- * - One deterministic routing outcome per normalized input set
+ * - One deterministic routing outcome per normalized input set.
  * - Ambiguous, conflicting, or insufficient inputs return `needs_reconcile`
- *   rather than a guessed handoff
- * - The evaluator is purely functional; no I/O or side effects
- * - Callers use evaluateConductorRouting as the single routing authority
+ *   rather than a guessed handoff.
+ * - The evaluator is purely functional; no I/O or side effects.
+ * - evaluateConductorRouting is the single routing authority.
  *
- * Integration boundary (see skills/docs/conductor-routing-contract.md):
- * - This module starts after active-run identity and ownership are already resolved
- * - It consumes already-detected family-local lifecycle states as inputs
- * - It derives the routing outcome directly from states; it does not take a
- *   pre-computed outer-loop action as an input
- * - It emits routing decisions and handoff envelopes; it does not perform handoff
- * - Ownership/idempotency rules remain in conductor-ownership.mjs (#32)
- * - Family-local state machine semantics remain in copilot-loop-state.mjs etc. (#26)
+ * Integration boundary:
+ * - Starts after active-run identity and ownership are already resolved; it
+ *   consumes already-detected family-local lifecycle states as inputs.
+ * - Derives the routing outcome directly from states; it does not take a
+ *   pre-computed outer-loop action as an input.
+ * - Emits routing decisions and handoff envelopes; it does not perform handoff.
+ * - Ownership/idempotency rules remain in conductor-ownership.mjs; family-local
+ *   state machine semantics remain in copilot-loop-state.mjs etc.
  */
 
 // ---------------------------------------------------------------------------
@@ -580,7 +572,7 @@ function routeFromStates({
  * @param {{ repo: string, pr: number }} input.target
  *   Explicit target identity (already resolved by the caller).
  * @param {string} [input.ownershipState]
- *   Settled ownership/idempotency classification from conductor-ownership (#32).
+ *   Settled ownership/idempotency classification from conductor-ownership.
  *   "live_owner" → stay_with_current_live_owner (no new handoff this cycle).
  *   "duplicate_local_owners" → needs_reconcile.
  *   Other values or omission → routing continues from states.

package/src/loop/copilot-loop-state.mjs

@@ -1,15 +1,9 @@
 /**
  * Deterministic state machine for the async Copilot review/fix loop.
  *
- * This module provides:
- * - STATE: stable state name constants
- * - TRANSITIONS: legal next-state graph for each state
- * - normalizeSnapshot: validate and canonicalize a raw loop-state snapshot
- * - interpretLoopState: map a snapshot to one current state + allowed transitions + next action
- *
- * The state machine owns workflow control.
- * Agent judgment (accept/defer a comment, confirm a fix, decide on another Copilot pass)
- * becomes an explicit bounded input (agentFixStatus) rather than hidden orchestration behavior.
+ * The state machine owns workflow control. Agent judgment (accept/defer a
+ * comment, confirm a fix, decide on another Copilot pass) enters as an explicit
+ * bounded input (agentFixStatus), never as hidden orchestration behavior.
  */
 
 import { deriveLoopCiStatusFromRollup } from "./copilot-ci-status.mjs";
@@ -76,9 +70,8 @@ export const DISPOSITION = Object.freeze({
 });
 
 /**
- * Legal transitions for each state.
- * Each entry lists the states that are reachable from the given state.
- * The agent layer selects among allowed transitions; the state machine enforces the graph.
+ * Legal transitions for each state. The agent layer selects among allowed
+ * transitions; the state machine enforces the graph.
  */
 export const TRANSITIONS = Object.freeze({
   [STATE.NO_PR]: [],
@@ -168,12 +161,9 @@ function isBlockedCiStatus(status) {
 
 /**
  * Single source of truth for whether the Copilot review round cap has been
- * reached (issue #1126). `copilot-pr-handoff.mjs` enforces the cap by calling
- * `interpretLoopState`, which uses this predicate internally; every other
- * caller that needs the same "cap reached" boolean (gate coordination,
- * detect-pr-gate-coordination-state) MUST call this function too rather than
- * re-deriving `copilotReviewRoundCount >= maxCopilotRounds` locally, so the
- * two never disagree at the cap boundary.
+ * reached. Every caller that needs the "cap reached" boolean MUST call this
+ * rather than re-derive `copilotReviewRoundCount >= maxCopilotRounds`, so no two
+ * callers disagree at the cap boundary.
  *
  * `copilotReviewRoundCount` counts COMPLETED rounds, so `>=` means every
  * permitted round has already happened. `maxCopilotRounds` of `null`/`0`/
@@ -211,9 +201,9 @@ export function buildSnapshotFromPrFacts({
   const prState = typeof prData?.state === "string" ? prData.state.toUpperCase() : "OPEN";
   const prMerged = prState === "MERGED";
   const prClosed = prState === "CLOSED";
-  // Default derivation excludes the loop's own gate-evidence check (#1358) so a
-  // caller that never threads an explicit ciStatus (e.g. gate-coordination
-  // detection) still never treats it as a blocking CI failure.
+  // Default derivation excludes the loop's own gate-evidence check so a caller
+  // that never threads an explicit ciStatus (e.g. gate-coordination detection)
+  // still never treats it as a blocking CI failure.
   const rollupDerivation = deriveLoopCiStatusFromRollup(prData?.statusCheckRollup);
 
   return normalizeSnapshot({
@@ -245,30 +235,17 @@ function isAutoRerequestEligible(snapshot, state) {
 
 /**
  * Normalize a raw snapshot object into a validated, canonical snapshot.
+ * Unknown or invalid field values are replaced with safe defaults. Throws if
+ * `raw` is not a non-null object.
  *
- * Unknown or invalid field values are replaced with safe defaults.
- * Throws if `raw` is not a non-null object.
- *
- * Snapshot schema:
- * - prExists {boolean} — whether a PR was found
- * - prNumber {number|null} — PR number if prExists, otherwise null
- * - prDraft {boolean} — whether the PR is in draft state
- * - prMerged {boolean} — whether the PR has been merged
- * - prClosed {boolean} — whether the PR has been closed without merge
- * - copilotReviewRequestStatus {"requested"|"already-requested"|"unavailable"|"none"|"failed"}
- *     — current known Copilot review-request state, or "none" if unknown
- * - copilotReviewPresent {boolean} — whether at least one Copilot review exists on the PR
- * - copilotReviewOnCurrentHead {boolean} — whether a submitted (non-PENDING) Copilot review
- *     exists for the current head commit; this alone does not prove the current-head
- *     review-request lifecycle is settled, so callers must still check request-state fields
- * - unresolvedThreadCount {number} — total unresolved review-thread count
- * - actionableThreadCount {number} — unresolved threads with non-bot actionable comments
- * - copilotReviewRoundCount {number} — completed Copilot review rounds observed on the PR
- * - ciStatus {"success"|"failure"|"pending"|"none"|"crediblyGreen"} — current CI check rollup status
- * - lastCopilotRoundMaxSignal {"high"|"mid"|"low"|null} — highest signal level across Copilot-authored threads
- * - agentFixStatus {"applied"|null} — agent-provided input: "applied" when code has been fixed
- * - failureDetails {Array<string>} — names of failing visible check-runs from refreshed head-scoped CI evidence
- * - excludedFailureDetails {Array<string>} — names of failing check-runs filtered out by PR-visibility intersection
+ * Non-obvious field semantics:
+ * - copilotReviewOnCurrentHead: a submitted (non-PENDING) Copilot review exists
+ *     for the current head. This alone does NOT prove the current-head
+ *     review-request lifecycle is settled; callers must still check request-state.
+ * - copilotReviewRoundCount: COMPLETED Copilot review rounds observed on the PR.
+ * - agentFixStatus: agent-provided input; "applied" when code has been fixed.
+ * - failureDetails vs excludedFailureDetails: visible failing check-runs vs
+ *     check-runs filtered out by the PR-visibility intersection.
  *
  * @param {object} raw - raw snapshot input
  * @returns {object} normalized snapshot
@@ -315,14 +292,12 @@ export function normalizeSnapshot(raw) {
 }
 
 /**
- * Return the post-request snapshot that should drive the next wait-cycle interpretation
- * once a Copilot review request has been explicitly issued or confirmed.
+ * Return the post-request snapshot that drives the next wait-cycle
+ * interpretation once a Copilot review request is issued or confirmed.
  *
- * This keeps the handoff helper on the same shared state-machine contract instead of
- * emitting a watch action that contradicts a same-head clean-convergence interpretation.
- * A confirmed request starts a new wait cycle for the current head, so prior
- * current-head clean-review convergence is cleared for handoff purposes while
- * preserving whether a submitted Copilot review has ever been observed on the PR.
+ * A confirmed active request starts a new wait cycle for the current head, so
+ * prior current-head clean-review convergence is cleared while whether a
+ * submitted Copilot review was ever observed on the PR is preserved.
  *
  * @param {object} snapshot
  * @param {string} reviewRequestStatus
@@ -363,7 +338,7 @@ export function applyConfirmedReviewRequest(snapshot, reviewRequestStatus) {
  * @param {number} [refinementConfig.lowSignalRoundThreshold]
  * @param {number} [refinementConfig.lowSignalMaxComments]
  * @param {number} [refinementConfig.maxCopilotRounds]
- * @param {boolean} [refinementConfig.preApprovalRequireCi] - #1337: default true. When false,
+ * @param {boolean} [refinementConfig.preApprovalRequireCi] - default true. When false,
  *   the pre-approval CI precondition is opted out, so a non-draft PR with a pending/none/failure
  *   CI verdict is not routed to waiting_for_ci / blocked_needs_user_decision (it is past the draft gate).
  * @returns {{
@@ -378,13 +353,11 @@ export function applyConfirmedReviewRequest(snapshot, reviewRequestStatus) {
 export function interpretLoopState(snapshot, refinementConfig) {
   const s = normalizeSnapshot(snapshot);
 
-  // Pre-approval CI opt-out (#1337): when `gates.preApproval.requireCi` is false,
-  // the CI verdict must not gate progression at the pre-approval boundary. A
-  // non-draft PR is past the draft gate, so this is the applicable knob — treat
-  // pending/none/failure CI as non-blocking here so a repo with no CI is not
-  // routed to WAITING_FOR_CI / BLOCKED_NEEDS_USER_DECISION before the downstream
-  // gate-coordination guards (which already honor this flag) are ever reached.
-  // Default true preserves current behavior for every caller that does not thread it.
+  // Pre-approval CI opt-out: when `gates.preApproval.requireCi` is false, the CI
+  // verdict must not gate progression at the pre-approval boundary. A non-draft
+  // PR is past the draft gate, so treat pending/none/failure CI as non-blocking
+  // here (a repo with no CI is not routed to WAITING_FOR_CI /
+  // BLOCKED_NEEDS_USER_DECISION). Default true preserves prior behavior.
   const preApprovalRequireCi = refinementConfig?.preApprovalRequireCi !== false;
   const ciBlocks = preApprovalRequireCi && isBlockedCiStatus(s.ciStatus);
   const ciWaits = preApprovalRequireCi && isWaitingCiStatus(s.ciStatus);
@@ -403,35 +376,19 @@ export function interpretLoopState(snapshot, refinementConfig) {
     state = STATE.BLOCKED_NEEDS_USER_DECISION;
   }
 
-  // Round-cap enforcement: when maxCopilotRounds is configured and the review-round
-  // count has been exhausted, stop re-requests before entering fix/reply-resolve routing.
-  // Gating here (before unresolved-thread checks) lets a CLEAN PR at the cap terminate as
-  // ROUND_CAP_CLEAN_FALLBACK ahead of the normal fix/wait routing. It does NOT blanket-
-  // override that routing: a NOT-clean PR (unresolved threads or non-green CI) with an
-  // in-flight request deliberately falls through to the normal fix/wait routing below
-  // (see the `!reviewInFlight` branch), and only a not-clean PR with no in-flight request
-  // hard-stops at ROUND_CAP_REACHED.
-  //
-  // Precedence at the cap: copilotReviewRoundCount counts COMPLETED rounds, so at
-  // `>= maxRounds` every permitted Copilot round is already done and any lingering
-  // in-flight request (requested/already-requested) is for a forbidden over-cap round.
-  // A stale Copilot reviewer assignment must therefore NOT block the clean fallback:
-  // when threads are clean and CI is green, route to ROUND_CAP_CLEAN_FALLBACK even if
-  // copilotReviewRequestStatus is requested/already-requested. Otherwise a lingering
-  // assignment would dead-end the loop at WAITING_FOR_COPILOT_REVIEW waiting for a
-  // review that can never come (no further round is permitted past the cap). The
-  // pre_approval_gate (current-head clean evidence, enforced elsewhere) reviews any
-  // post-cap head change, so this proceeds without skipping review of new code.
-  //
-  // An in-flight request only still blocks the cap block when the PR is NOT clean
-  // (unresolved threads or non-green CI) — that legitimately stays in the fix/wait
-  // routing below rather than terminating as a clean fallback.
-  //
-  // Head-advanced handling: even when the head has advanced past the last submitted
-  // Copilot review with clean threads and green CI, re-requesting another Copilot pass
-  // is forbidden at the cap, so this routes to ROUND_CAP_CLEAN_FALLBACK (not
-  // READY_TO_REREQUEST_REVIEW, which would trigger an illegal auto re-request). The
-  // pre_approval_gate handles the current head.
+  // Round-cap enforcement, gated before the fix/reply-resolve routing below.
+  // copilotReviewRoundCount counts COMPLETED rounds, so at `>= maxRounds` every
+  // permitted round is done and any lingering in-flight request is for a
+  // forbidden over-cap round. Precedence at the cap:
+  //   - clean PR (clean threads + green CI): ROUND_CAP_CLEAN_FALLBACK, even with
+  //     a lingering in-flight request or an advanced head — no further round is
+  //     permitted, so never re-open for re-request or wait on Copilot. Re-opening
+  //     would dead-end at WAITING_FOR_COPILOT_REVIEW on a review that can never
+  //     come. The pre_approval_gate (enforced elsewhere) reviews post-cap head
+  //     changes, so this skips no review of new code.
+  //   - not clean, no in-flight request: hard stop at ROUND_CAP_REACHED.
+  //   - not clean WITH an in-flight request: fall through to the normal
+  //     fix/reply-resolve/wait routing below (no forced clean fallback).
   const maxRounds = refinementConfig?.maxCopilotRounds;
   const reviewInFlight = s.copilotReviewRequestStatus === "requested"
     || s.copilotReviewRequestStatus === "already-requested";
@@ -442,16 +399,11 @@ export function interpretLoopState(snapshot, refinementConfig) {
     const ciClean = s.ciStatus === "success" || s.ciStatus === "crediblyGreen" || !preApprovalRequireCi;
     const cleanThreads = s.unresolvedThreadCount === 0;
     if (cleanThreads && ciClean) {
-      // Clean PR at the cap: proceed to the pre_approval_gate fallback regardless of a
-      // lingering Copilot reviewer assignment or an advanced head — no further Copilot
-      // round is permitted, so never re-open for re-request or wait on Copilot here.
       state = STATE.ROUND_CAP_CLEAN_FALLBACK;
     } else if (!reviewInFlight) {
-      // Not clean and no in-flight request: hard stop at the cap.
       state = STATE.ROUND_CAP_REACHED;
     }
-    // Not clean WITH an in-flight request: leave state undecided so the normal
-    // fix/reply-resolve/wait routing below handles it (do not force a clean fallback).
+    // Not clean WITH an in-flight request: leave state undecided for the routing below.
   }
 
   if (state === undefined) {

package/src/loop/gate-carry-forward.mjs

@@ -1,22 +1,30 @@
 /**
- * Gate carry-forward: a pure, fail-closed seam that decides whether a clean gate
- * angle verdict recorded at head A may be CARRIED FORWARD to head B without
- * re-running that angle's reviewer.
+ * Gate carry-forward: a pure, fail-closed seam that decides whether an angle's
+ * verdict recorded at head A (clean OR findings-present) may be CARRIED FORWARD
+ * to head B without re-running that angle's reviewer.
  *
  * Motivation: fresh-context-per-head re-fans ALL gate angles on every head bump,
  * even when the delta between the two heads provably cannot affect most angles
  * (e.g. a doc-only follow-up commit cannot change what a code-correctness angle
- * would find). Carry-forward lets the gate reuse the prior clean verdict for such
- * angles — but ONLY when it is provably safe.
+ * would find). Carry-forward lets the gate reuse the prior verdict for such
+ * angles — but ONLY when it is provably safe. This holds for a findings-present
+ * prior verdict too: a fixer push that never touches an angle's
+ * surface must not force that angle's OPEN findings to be re-litigated from
+ * scratch — the caller carries the prior findings forward unchanged, still
+ * open, still blocking. Carry-forward NEVER converts a finding into an
+ * approval; it only ever skips re-running a reviewer whose surface the delta
+ * provably did not touch.
  *
- * FAIL-CLOSED is paramount. An angle carries forward ONLY when EVERY changed file
- * in the delta A..B is provably OUTSIDE that angle's declared review surface. The
- * default in every uncertain case (non-clean prior verdict, empty/unavailable
- * delta, an unclassifiable file, an angle with no declared surface, a mandatory /
- * always-run angle) is MUST-RE-RUN. Carry-forward never fabricates a verdict: the
- * caller records the carried verdict with provenance pointing at the PRIOR head's
- * reviewer (that reviewer genuinely reviewed this angle's surface, which the delta
- * did not touch), clearly marked as carried — see
+ * FAIL-CLOSED is paramount. An angle carries forward ONLY when its prior verdict
+ * is carry-forward-eligible (clean or findings_present) AND EVERY changed file in
+ * the delta A..B is provably OUTSIDE that angle's declared review surface. The
+ * default in every uncertain case (an ineligible prior verdict — e.g. "blocked"
+ * or missing, empty/unavailable delta, an unclassifiable file, an angle with no
+ * declared surface, a mandatory / always-run angle) is MUST-RE-RUN. Carry-forward
+ * never fabricates a verdict: the caller records the carried verdict (and, for a
+ * findings-present carry, the carried findings) with provenance pointing at the
+ * PRIOR head's reviewer (that reviewer genuinely reviewed this angle's surface,
+ * which the delta did not touch), clearly marked as carried — see
  * skills/docs/gate-review-sub-loop-contract.md and write-gate-findings-log.mjs's
  * `carriedFromHead` provenance field.
  *
@@ -57,7 +65,7 @@ import { ALWAYS_INCLUDE, CATEGORY_ANGLE_MAP } from "../analysis/change-classifie
  * @type {Record<string, string[]>}
  */
 const KIND_TO_CATEGORIES = {
-  // #1442: a docs file is PROSE_PRESENT when it lands on the prose surface, so
+  // A docs file is PROSE_PRESENT when it lands on the prose surface, so
   // deslop's carry-forward surface is the `docs` kind (a non-docs delta never
   // re-runs a clean deslop verdict).
   docs: ["DOCS_ONLY", "PROSE_PRESENT"],
@@ -153,10 +161,16 @@ export function angleReviewSurface(angle, { alwaysRerun } = {}) {
 /**
  * Pure, deterministic, FAIL-CLOSED carry-forward decision for a single angle.
  *
- * Given a prior CLEAN verdict recorded at head A, the changed files of the delta
- * A..B, and the angle's declared review surface, decide whether the clean verdict
- * may be carried forward to head B (carryForward: true) or the angle MUST re-run
- * (carryForward: false). Defaults to must-re-run in every uncertain case.
+ * Given a prior carry-forward-eligible verdict recorded at head A (clean OR
+ * findings_present), the changed files of the delta A..B, and the angle's
+ * declared review surface, decide whether that verdict (and, for a
+ * findings-present angle, its open findings) may be carried forward to head B
+ * (carryForward: true) or the angle MUST re-run (carryForward: false).
+ * Defaults to must-re-run in every uncertain case. This function never
+ * inspects or mutates findings content — it only decides whether the delta
+ * proves the angle's surface untouched; the caller is responsible for
+ * carrying the actual prior findings through unchanged (never converting an
+ * open finding into an approval) when it honors `carryForward: true`.
  *
  * @param {object} input
  * @param {string} input.angle
@@ -164,11 +178,18 @@ export function angleReviewSurface(angle, { alwaysRerun } = {}) {
  *   derived from {@link angleReviewSurface} when omitted.
  * @param {string[]} input.changedFiles — repo-relative paths changed between head
  *   A and head B (the delta, NOT the full PR diff against base).
- * @param {string} input.prevVerdict — the angle's verdict at head A. Only "clean"
- *   is carry-forward-eligible.
+ * @param {string} input.prevVerdict — the angle's verdict at head A. "clean" and
+ *   "findings_present" are carry-forward-eligible; anything else (e.g.
+ *   "blocked", missing) is not.
  * @returns {{ carryForward: boolean, reason: string }}
  */
 
+// The only per-angle prior verdicts eligible to carry forward — matches the
+// two verdict values gate-fanin's VALID_VERDICTS actually produces per angle
+// (packages/core/src/loop/gate-fanin.mjs). Any other value (e.g. "blocked",
+// undefined, a typo) fails closed to must-re-run.
+const CARRY_FORWARD_ELIGIBLE_VERDICTS = new Set(["clean", "findings_present"]);
+
 // A path whose change rewrites the dev-loop review system itself — the angle
 // pool, mandatory floor, and reviewer personas/prompts — rather than a
 // reviewed surface. A clean verdict produced under the OLD config cannot
@@ -187,8 +208,11 @@ export function isDevLoopConfigSourcePath(filePath) {
 }
 
 export function resolveAngleCarryForward({ angle, angleSurface, changedFiles, prevVerdict }) {
-  if (prevVerdict !== "clean") {
-    return { carryForward: false, reason: `prior verdict is ${JSON.stringify(prevVerdict ?? null)}, not "clean"` };
+  if (!CARRY_FORWARD_ELIGIBLE_VERDICTS.has(prevVerdict)) {
+    return {
+      carryForward: false,
+      reason: `prior verdict is ${JSON.stringify(prevVerdict ?? null)}, not carry-forward-eligible (clean or findings_present)`,
+    };
   }
   const surface = angleSurface ?? angleReviewSurface(angle);
   if (surface.kind === "always") {