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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-loops/core",
-  "version": "1.0.1",
+  "version": "1.0.2-pre.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -35,6 +35,7 @@
     "./loop/copilot-loop-iterations": "./src/loop/copilot-loop-iterations.mjs",
     "./loop/copilot-loop-state": "./src/loop/copilot-loop-state.mjs",
     "./loop/gate-carry-forward": "./src/loop/gate-carry-forward.mjs",
+    "./loop/gate-evidence-reconcile": "./src/loop/gate-evidence-reconcile.mjs",
     "./loop/gate-fanin": "./src/loop/gate-fanin.mjs",
     "./loop/handoff-envelope": "./src/loop/handoff-envelope.mjs",
     "./loop/lifecycle-state": "./src/loop/lifecycle-state.mjs",
@@ -67,6 +68,7 @@
     "./loop/run-context": "./src/loop/run-context.mjs",
     "./loop/run-inspection": "./src/loop/run-inspection.mjs",
     "./loop/run-post-merge-actions": "./src/loop/run-post-merge-actions.mjs",
+    "./loop/spec-authority": "./src/loop/spec-authority.mjs",
     "./loop/spike-exit-contract": "./src/loop/spike-exit-contract.mjs",
     "./loop/spike-intake-contract": "./src/loop/spike-intake-contract.mjs",
     "./loop/steering": "./src/loop/steering.mjs",
@@ -100,7 +102,7 @@
     "bin/**/*.mjs"
   ],
   "scripts": {
-    "test": "node --test ./test/*.test.mjs"
+    "test": "bun ../../scripts/run-bun-test.mjs ./test/*.test.mjs"
   },
   "publishConfig": {
     "access": "public",

package/src/claude/hook-decisions.mjs

@@ -369,6 +369,99 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
   };
 }
 
+/**
+ * Env var that authorizes a deliberate main-checkout mutation while a worktree
+ * cycle is active. Reuses the existing default-branch-guard override
+ * (`DEVLOOPS_ALLOW_MAIN`, GUARD_OVERRIDE_ENV) — both mean "I intend to operate on
+ * the primary checkout on purpose" — so the operator surface stays one flag.
+ */
+export const WORKTREE_CHECKOUT_GUARD_OVERRIDE_ENV = "DEVLOOPS_ALLOW_MAIN";
+
+/**
+ * Decide whether a PreToolUse Write/Edit is a WRONG-CHECKOUT mutation: the call
+ * context is operating inside a linked worktree (the active cycle worktree) but
+ * the target resolves to a TRACKED file in the MAIN checkout instead of that
+ * worktree.
+ *
+ * After `ensure-worktree.mjs` establishes an isolated worktree for a cycle, an
+ * absolute-path `Edit`/`Write` that names the main-checkout copy of a source
+ * file lands the change on the wrong checkout — silently, until a `git status`
+ * in the worktree turns up empty (observed in practice: six edits hit main
+ * before a self-caught restore). This guard catches that before it reaches a commit.
+ *
+ * The "active worktree" is anchored to the CALL CONTEXT's cwd, not to a durable
+ * marker: this repo accumulates many stale `tmp/worktrees/` worktrees, so "a
+ * worktree exists" cannot mean "a cycle is active". The worktree that CONTAINS
+ * cwd is the one this context is driving; a write escaping it into main is the
+ * wrong-checkout mistake.
+ *
+ * The hook resolves the facts (via the shared `worktree-guard.mjs` primitives)
+ * and passes booleans so this decider stays pure and unit-testable:
+ * - `activeWorktreeRoot`: the listed worktree root containing cwd, or null when
+ *   cwd is not inside any worktree (no active cycle context — AC3).
+ * - `isTargetUnderActiveWorktree`: the target resolves inside that worktree (a
+ *   legitimate in-worktree edit — AC2).
+ * - `isMainCheckoutTracked`: the target resolves under the main checkout AND is
+ *   a tracked (non-gitignored) file. The hook sets this true when the status is
+ *   UNRESOLVABLE (e.g. `git check-ignore` errored) so an ambiguous context fails
+ *   safe rather than silently allowing a wrong-checkout write (AC4).
+ * - `allowMainCheckout`: the deliberate-override signal (`DEVLOOPS_ALLOW_MAIN=1`)
+ *   for an intended main-checkout edit (AC3).
+ *
+ * @param {Object} params
+ * @param {string} params.filePath - Target file path (as supplied to the tool).
+ * @param {string|null} [params.activeWorktreeRoot] - Listed worktree root containing cwd, or null.
+ * @param {boolean} [params.isTargetUnderActiveWorktree] - Target is inside the active worktree.
+ * @param {boolean} [params.isMainCheckoutTracked] - Target is a tracked main-checkout file (or unresolvable).
+ * @param {boolean} [params.allowMainCheckout] - Deliberate override (DEVLOOPS_ALLOW_MAIN=1).
+ * @param {string|null} [params.suggestedWorktreePath] - The worktree-local path the write should target.
+ * @returns {HookDecision}
+ */
+export function decideWorktreeCheckoutGuard({
+  filePath,
+  activeWorktreeRoot = null,
+  isTargetUnderActiveWorktree = false,
+  isMainCheckoutTracked = false,
+  allowMainCheckout = false,
+  suggestedWorktreePath = null,
+}) {
+  // No active worktree context — this is the main checkout / orchestrator / a
+  // consumer repo's own interactive dev. A main-checkout edit is intended here
+  // (AC3). Also the only path that runs for repos never using dev-loop worktrees.
+  if (!activeWorktreeRoot) {
+    return ALLOW;
+  }
+  // Deliberate, operator-authorized main-checkout write during an active cycle (AC3).
+  if (allowMainCheckout) {
+    return ALLOW;
+  }
+  // Legitimate in-worktree edit — no false positive (AC2).
+  if (isTargetUnderActiveWorktree) {
+    return ALLOW;
+  }
+  // Outside the active worktree AND not a tracked main-checkout file: a scratch
+  // path (/tmp), a gitignored path, another worktree's file, or outside the repo
+  // entirely — none is the wrong-checkout mistake this guard exists to catch.
+  if (!isMainCheckoutTracked) {
+    return ALLOW;
+  }
+  // A worktree cycle is active and the target is a tracked main-checkout file
+  // (or an unresolvable/ambiguous context that fails safe — AC4). This is a
+  // wrong-checkout mutation (AC1).
+  const fix = suggestedWorktreePath
+    ? ` Edit the worktree copy instead: "${suggestedWorktreePath}".`
+    : "";
+  return {
+    decision: "deny",
+    reason:
+      `WORKTREE-WRONG-CHECKOUT-GUARD: wrong-checkout mutation blocked — a worktree cycle is active ` +
+      `("${activeWorktreeRoot}") but this Write/Edit targets the MAIN checkout's non-gitignored file ` +
+      `"${filePath}".${fix} A file mutation that lands on the main checkout while a worktree is ` +
+      "active is silently lost from the branch. Set DEVLOOPS_ALLOW_MAIN=1 only for a deliberate " +
+      "main-checkout edit. See skills/docs/worktree-guidance.md.",
+  };
+}
+
 /**
  * Env var that exempts an interactive session awaiting commit authorization from the
  * SubagentStop uncommitted-work guard (#1619).
@@ -384,21 +477,26 @@ export function decideWriteGuard({ filePath, isRepoMutation, enforce = false, en
 export const DEVLOOPS_COMMIT_AUTH_PENDING_VAR = "DEVLOOPS_COMMIT_AUTH_PENDING";
 
 /**
- * Env var that exempts an orchestrator-owned-commit dispatch from the SubagentStop
- * uncommitted-work guard (#1786).
+ * Subagent roles whose contract forbids committing to the repository (#1925).
  *
- * A "LOCAL EDITS ONLY: no commit" dispatch (e.g. the `developer`/`quality`/`docs` delegation
- * pattern in `skills/local-implementation/SKILL.md` "Delegation contract") tells the subagent to
- * make local edits and report changed files, leaving commit + push to the dispatching
- * orchestrator once it consolidates results. Without an exemption, that subagent's own
- * SubagentStop event still sees the dirty worktree it was told not to commit and deadlocks. The
- * dispatcher sets `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT=1` for that dispatch to declare it owns the
- * commit — same opt-in `DEVLOOPS_*` signal shape as `DEVLOOPS_COMMIT_AUTH_PENDING`, but distinct:
- * this one exempts a non-interactive delegated dispatch whose commit responsibility sits with its
- * caller, not an interactive session awaiting operator authorization. Left unset, an ordinary
- * dispatch's commit-before-exit obligation stays enforced (fail closed by default).
+ * The `judge` and `review` agents are read-only over the repository: the judge writes only its
+ * own verdict artifact (under `tmp/`, gitignored) and the gate reviewer writes only its findings
+ * artifact (also under `tmp/`) — neither ever authors a tracked-file edit. So any uncommitted
+ * tracked change present in such a subagent's worktree is FOREIGN: it belongs to the orchestrator
+ * that dispatched it (a pending orchestrator edit that was in the shared worktree when the
+ * read-only pass ran), not to the read-only subagent. `LOCAL-COMMIT-BEFORE-EXIT` must not force
+ * one of these roles to author a commit of that foreign work — doing so violates the verdict-only
+ * contract (`agents/judge.agent.md`: "The only thing you write is your own verdict artifact").
+ * The data-loss protection is enforced against the OWNER of the edit (the orchestrator) on its own
+ * stop instead. This is intentionally scoped to read-only roles: editing roles (`developer`,
+ * `fixer`, `docs`, `quality`) and the orchestrator stay enforced (#1925 non-goal).
  */
-export const DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT_VAR = "DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT";
+export const READONLY_SUBAGENT_ROLES = Object.freeze(["judge", "review"]);
+
+/** Whether `agentType` (Claude `agent_type` from the SubagentStop payload) is a read-only role. */
+export function isReadOnlySubagentRole(agentType) {
+  return typeof agentType === "string" && READONLY_SUBAGENT_ROLES.includes(agentType);
+}
 
 /**
  * Decide whether a SubagentStop must be blocked because the subagent's worktree has
@@ -408,10 +506,19 @@ export const DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT_VAR = "DEVLOOPS_ORCHESTRATOR_OWNS
  * uncommitted changes in a worktree are destroyed with no warning. `LOCAL-COMMIT-BEFORE-EXIT`
  * existed only as prose. This decider makes it mechanical: refuse the subagent stop when the
  * cwd is under `tmp/worktrees/` and `git status --porcelain` is non-empty, unless the session
- * is an interactive one awaiting commit authorization, or the dispatch is an explicit
- * orchestrator-owned-commit exemption (#1786) (either exempt). A clean worktree, a cwd
+ * is an interactive one awaiting commit authorization (exempt). A clean worktree, a cwd
  * outside `tmp/worktrees/`, and a git-error/empty-porcelain case all allow the stop.
  *
+ * Editing roles (`developer`/`fixer`/`docs`/`quality`) stay fully enforced: an editing
+ * sub-delegate commits its own work before exit (`LOCAL-COMMIT-BEFORE-EXIT`), so a dirty exit is
+ * always a real defect, never a sanctioned "orchestrator owns the commit" split. The removed
+ * `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT` env-var exemption (#1786) deadlocked such a role under a
+ * task-scoped no-commit instruction whenever the orchestrator could not set a per-dispatch env
+ * var (the Claude harness): the hook demanded a commit the session then denied, then re-blocked
+ * the exit (#1936). Disallowing the edit-here/commit-there split at the contract level makes the
+ * guard the enforcer and the deadlock structurally impossible while preserving data-loss
+ * protection. An orchestrator that wants one consolidated commit performs the edits itself.
+ *
  * Pure and side-effect free. The hook script gathers `cwd` and the `git status --porcelain`
  * output and calls this; the block decision is surfaced via exit code 2 + stderr JSON by the
  * hook (the SubagentStop contract differs from PreToolUse's `permissionDecision` form).
@@ -424,21 +531,38 @@ export const DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT_VAR = "DEVLOOPS_ORCHESTRATOR_OWNS
  * @param {boolean} [params.pendingCommitAuthorization] - True when the interactive session is
  *   awaiting commit authorization (exempt) — derived by the hook script from the
  *   `DEVLOOPS_COMMIT_AUTH_PENDING=1` opt-in env signal.
- * @param {boolean} [params.orchestratorOwnsCommit] - True when this dispatch is an explicit
- *   orchestrator-owned-commit exemption (exempt) — derived by the hook script from the
- *   `DEVLOOPS_ORCHESTRATOR_OWNS_COMMIT=1` opt-in env signal.
+ * @param {string|null} [params.agentType] - Claude `agent_type` from the SubagentStop payload;
+ *   a read-only role (`judge`/`review`, per `READONLY_SUBAGENT_ROLES`) is exempt (#1925) — its
+ *   contract forbids commits, so any dirty tracked edit in its worktree is foreign
+ *   (orchestrator-owned) and must not be pinned on it.
  * @returns {HookDecision}
  */
-export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthorization = false, orchestratorOwnsCommit = false }) {
+export function decideSubagentStopGuard({ cwd, porcelain, pendingCommitAuthorization = false, agentType = null }) {
   if (typeof cwd !== "string" || !isUnderWorktreePath(cwd)) {
     return ALLOW;
   }
-  if (pendingCommitAuthorization || orchestratorOwnsCommit) {
+  if (pendingCommitAuthorization) {
     return ALLOW;
   }
   if (typeof porcelain !== "string" || porcelain.trim() === "") {
     return ALLOW;
   }
+  // Read-only role exemption (#1925): the worktree is dirty, but a `judge`/`review` subagent's
+  // contract forbids commits, so this pending tracked edit is foreign — it belongs to the
+  // orchestrator that dispatched this pass. Do not force a verdict-only role to commit it; allow
+  // the stop with an advisory naming the orchestrator as the actor responsible for the edit. The
+  // data-loss guard still fires against the orchestrator on its own (editing) stop.
+  if (isReadOnlySubagentRole(agentType)) {
+    return {
+      decision: "allow",
+      advisory: true,
+      reason:
+        `LOCAL-COMMIT-BEFORE-EXIT exempt for read-only role "${agentType}": the worktree has ` +
+        "uncommitted changes, but a verdict-only role must not author a commit of work it did not " +
+        "create. This pending edit is foreign — the ORCHESTRATOR that dispatched this pass owns it " +
+        "and is responsible for committing it before its own stop.",
+    };
+  }
   const dirty = porcelain
     .split("\n")
     .map((l) => l.trim())

package/src/config/extension-defaults.yaml

@@ -199,7 +199,7 @@ gates:
       - name: docs-surface
         angles: [docs, link-check, config-drift, contract-surface]
       - name: process
-        angles: [scope, pr-description, gate-evidence, pr-checklist-matrix]
+        angles: [scope, pr-description, gate-evidence, pr-checklist]
       - name: correctness-input
         angles: [correctness, input-validation]
       - name: determinism-state
@@ -259,19 +259,24 @@ gates:
       - name: docs
         persona: docs
         prompt: "Review documentation correctness for the current change. Check that relative markdown links resolve, symlink-backed doc pointers resolve, navigable doc references are actual markdown links rather than bare backtick path mentions, command/script references still exist and use current names, and index/surface references match the current file tree. Also flag stale command references: removed or renamed npm scripts, CLI commands, or tool invocations that no longer match the current codebase. When the repo provides `scripts/docs/validate-links.mjs`, use it for the mechanical link pass; otherwise keep the review scoped to the touched doc surface and current change only."
-      - name: pr-checklist-matrix
+      - name: pr-checklist
         mandatory: true
         persona: review
         prompt: |-
+          Verify the PR carries self-contained list-form Acceptance criteria and Definition of done
+          CHECKLISTS (never a matrix/table on the PR, never checkboxes inside table cells) that are
+          faithfully DERIVED from the linked issue's authoritative AC→DoD mapping matrix (#1951).
           Completeness is enforced deterministically (#1877): the pre_approval_gate fails closed on any
           unchecked `- [ ]` in the PR body's AC/DoD checklist, so this angle's completeness duty is
-          machine-backed. Your remaining duty is TRUTHFULNESS, which the machine cannot check: verify
-          that every checked `- [x]` box in the PR body's Acceptance criteria / Definition of done
-          checklists is actually satisfied by the implementation — cite concrete code/test/behavior
-          evidence; flag a dishonestly-ticked box as a blocking finding. Also verify the checked
-          content mirrors the linked issue's AC/DoD/Non-goals matrix and that declared non-goals are
-          respected (no scope creep). The boundary is explicit: the deterministic block enforces
-          completeness (nothing left unchecked/forgotten); you verify each [x] is real.
+          machine-backed. Your remaining duty is TRUTHFULNESS + DERIVATION FIDELITY, which the machine
+          cannot check: verify that every checked `- [x]` box in the PR body's Acceptance criteria /
+          Definition of done checklists is actually satisfied by the implementation — cite concrete
+          code/test/behavior evidence; flag a dishonestly-ticked box as a blocking finding. Verify the
+          PR checklists faithfully reflect the issue matrix (every matrix row is represented, nothing
+          invented or dropped) and that declared non-goals are respected (no scope creep). Do NOT
+          require a matrix on the PR — the matrix lives on the issue; the PR carries the derived
+          checklists. The boundary is explicit: the deterministic block enforces completeness (nothing
+          left unchecked/forgotten); you verify each [x] is real and faithfully derived.
       - contradiction-lens
       - correctness-final
       - ui-validation

package/src/github/comment-id-guard.mjs

@@ -112,6 +112,44 @@ export function extractIssuePrIds(body) {
   return [...found];
 }
 
+// A consecutive run of number-sign(s) immediately before a digit. Strip EVERY
+// number-sign in the run (`#123` and `##123` alike leave `123`), or a leftover
+// still auto-links AND trips the decode-aware guard. A lookahead consumes only
+// the number-sign(s), keeping the digits.
+const BARE_ISSUE_PR_ID_RE = /#+(?=\d)/g;
+
+/**
+ * The sanctioned pre-guard transform for GENERATED comment bodies (#1922):
+ * neutralize a bare `#<digits>` auto-link token to a guard-safe, non-auto-linking
+ * form by stripping the leading `#` (`#123` -> `123`). Auto-link syntax requires
+ * the leading `#`, so the result neither auto-links on GitHub nor trips
+ * `guardCommentBodyNoIssuePrIds` — and because no decode path can reassemble a
+ * `#` from bare digits, the guard's entity-decode surface stays satisfied too.
+ *
+ * This is deliberately SEPARATE from `guardCommentBodyNoIssuePrIds`: the guard
+ * stays fail-closed for human-authored bodies (it must still REFUSE a bare id a
+ * person typed), while gate generators opt into this transform on their OWN
+ * generated finding text before handing it to the guard. It does NOT weaken the
+ * guard.
+ *
+ * Run on RAW text BEFORE any markdown sanitizer (sanitizeInline/sanitizeCodeSpan)
+ * emits its own numeric character references (e.g. `&#91;` for `[`): this strips
+ * `#` before digits without distinguishing an entity's digits from a bare id's,
+ * so applying it post-sanitize would corrupt an already-emitted entity
+ * (`&#91;` -> `&91;`).
+ *
+ * ponytail: strips only a LITERAL `#` before digits — every form a review agent
+ * actually authors (`#123`). It does NOT mirror the guard's full entity-decode
+ * surface; text already carrying an entity-encoded number-sign adjacent to
+ * digits (`&num;123`) is unreachable from reviewer prose, and the guard remains
+ * the fail-closed backstop for it. Returns non-string input unchanged (stringly
+ * callers coerce first).
+ */
+export function neutralizeBareIssuePrIds(value) {
+  if (typeof value !== "string") return value;
+  return value.replace(BARE_ISSUE_PR_ID_RE, "");
+}
+
 // A caller-supplied allowlist is normally already an array (or other
 // iterable) of ids. Guard the one mis-shaped input that would otherwise
 // silently produce the wrong set: a plain CSV string. `Array.from` over a

package/src/github/gh.mjs

@@ -92,3 +92,52 @@ export async function ghGraphql(query, vars, env, runChild = defaultRunChild, {
   }
   return payload;
 }
+
+const GET_USER_ID = [
+  "query($login:String!) {",
+  "  user(login:$login) { id }",
+  "}",
+].join("\n");
+
+const GET_ORG_ID = [
+  "query($login:String!) {",
+  "  organization(login:$login) { id }",
+  "}",
+].join("\n");
+
+/**
+ * Resolve a GitHub owner login to its node id and kind. Probes the user
+ * namespace first; a not-a-user probe failure (org logins make `gh api graphql`
+ * exit non-zero) falls through to the org namespace instead of throwing (#1949).
+ * A login that is neither a user nor an org fails closed with NO_USER_ID.
+ *
+ * The issue's "Proposed fix" wrapped only the user probe, but AC #3 requires
+ * NO_USER_ID for a genuinely non-existent owner; in production the org probe
+ * on a missing org also throws (non-zero exit), so both probes must be caught
+ * for the AC to hold. `cause` preserves the underlying org error for
+ * diagnostics. This does not change `ghGraphql`'s throw-on-non-zero-exit
+ * contract.
+ */
+export async function resolveOwner(login, env, runChild) {
+  try {
+    const userPayload = await ghGraphql(GET_USER_ID, { login }, env, runChild);
+    if (userPayload?.data?.user?.id) {
+      return { id: userPayload.data.user.id, kind: "user" };
+    }
+  } catch {
+    // not a user login → fall through to the org probe
+  }
+  let orgError;
+  try {
+    const orgPayload = await ghGraphql(GET_ORG_ID, { login }, env, runChild);
+    if (orgPayload?.data?.organization?.id) {
+      return { id: orgPayload.data.organization.id, kind: "org" };
+    }
+  } catch (err) {
+    orgError = err;
+  }
+  throw Object.assign(
+    new Error(`Could not resolve owner ID for "${login}"`),
+    { code: "NO_USER_ID", cause: orgError },
+  );
+}

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/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 (issue #2017): 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.
  *
@@ -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") {

package/src/loop/gate-evidence-reconcile.mjs

@@ -0,0 +1,75 @@
+/**
+ * gate-evidence-reconcile.mjs — deterministic self-heal for a stuck
+ * `gate-evidence` required status (issue #1935).
+ *
+ * The server-side `gate-evidence` check (`.github/workflows/gate-evidence.yml`)
+ * re-fires when a gate verdict is posted (ADR 0043). That native re-fire is
+ * racy: a verdict-post run can be CANCELLED by `cancel-in-progress` when a
+ * superseding event lands, or evaluate before the just-posted verdict is
+ * API-visible, leaving the required status stuck at `failure` even though a
+ * clean current-head `pre_approval_gate` verdict now exists. Nothing re-fires
+ * afterward, so the merge stays `UNSTABLE` until a manual `gh run rerun`
+ * (observed on PR #1934; ADR 0057).
+ *
+ * This pure decision separates the two cases the reconcile must never confuse:
+ *  - evidence genuinely satisfied but the status is stuck non-green → re-fire
+ *    the concrete run that posted the stale status (automating the manual
+ *    rerun; the rerun re-evaluates LIVE evidence, which is now satisfied).
+ *  - evidence genuinely NOT satisfied → do nothing. A head that truly lacks a
+ *    clean current-head verdict MUST keep failing the check (fail-closed).
+ */
+
+/** Required commit-status context posted by the gate-evidence workflow. */
+export const GATE_EVIDENCE_STATUS_CONTEXT = "gate-evidence";
+
+/**
+ * Extract the Actions run id from a gate-evidence commit-status `target_url`.
+ * The workflow points every posted status at its own run:
+ *   https://github.com/<owner>/<repo>/actions/runs/<run_id>
+ * Returns the numeric run id as a string, or null when the URL is absent or
+ * not an Actions-run URL (an unexpected target_url must not be coerced).
+ *
+ * @param {string} [targetUrl]
+ * @returns {string|null}
+ */
+export function parseRunIdFromTargetUrl(targetUrl) {
+  if (typeof targetUrl !== "string") return null;
+  const match = targetUrl.match(/\/actions\/runs\/(\d+)(?:[/?#]|$)/);
+  return match ? match[1] : null;
+}
+
+/**
+ * Decide whether a stuck `gate-evidence` status should be re-fired.
+ *
+ * @param {object} input
+ * @param {boolean} input.evidenceSatisfied  detect-checkpoint-evidence reports
+ *   `evidenceState === "satisfied"` for the current head (clean draft_gate +
+ *   current-head pre_approval_gate verdicts present).
+ * @param {string} [input.statusState]  the `gate-evidence` commit-status state
+ *   on the current head: `success` | `failure` | `error` | `pending` | `none`
+ *   (`none` = no gate-evidence status posted for this head yet).
+ * @param {string|null} [input.runId]  the Actions run id that posted the stale
+ *   status (from `parseRunIdFromTargetUrl`), or null when unknown.
+ * @returns {{ action: "refire"|"none", runId?: string, reason: string }}
+ */
+export function resolveGateEvidenceStatusReconcile({ evidenceSatisfied, statusState, runId } = {}) {
+  // Fail-closed: never re-fire when the verdict evidence is genuinely not
+  // satisfied. This preserves the "verdict genuinely missing" case — the head
+  // keeps failing closed exactly as before (issue #1935 AC #3).
+  if (evidenceSatisfied !== true) {
+    return { action: "none", reason: "evidence-not-satisfied-fail-closed" };
+  }
+  // Already green — nothing to reconcile.
+  if (statusState === "success") {
+    return { action: "none", reason: "already-success" };
+  }
+  // Evidence IS satisfied for the current head, but the required status is not
+  // success (the push-before-verdict race: a cancelled/stale re-fire). Re-fire
+  // the concrete run that posted the stale status. Without a run id there is
+  // nothing to re-fire deterministically; leave it to the native path rather
+  // than forging a status.
+  if (!runId) {
+    return { action: "none", reason: "no-run-to-refire" };
+  }
+  return { action: "refire", runId, reason: "evidence-satisfied-status-stale" };
+}