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

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" };
+}

package/src/loop/gate-fanin.mjs

@@ -63,13 +63,19 @@ export function scheduleFanoutWaves(dispatchGroups, maxConcurrent = 4) {
 }
 
 /**
- * Adaptive 429-backoff concurrency (issue #1601): halve the active batch before
- * escalating to foreground one-at-a-time fallback. On a 429, the conductor
- * recomputes the wave plan with `backoffMaxConcurrent(maxConcurrent)` and
- * retries the failed wave; if a single-unit wave still 429s, it falls back to
- * foreground (one-at-a-time) dispatch. The backoff is recorded in the round's
- * provenance (see skills/docs/gate-review-sub-loop-contract.md). Pure; never
- * returns 0 (a backoff from 1 stays 1 → foreground fallback owns that path).
+ * Adaptive concurrency backoff (issue #1601; retry discipline refined by #1907):
+ * halve the active batch before escalating to foreground one-at-a-time fallback.
+ * A transient dispatch failure (429/5xx) is first retried on the SAME unit with
+ * exponential backoff — safe because a reviewer's findings artifact is an
+ * idempotent single-write at a deterministic path — and the conductor reduces
+ * concurrency ONLY after that unit's retries are exhausted (~3 failed attempts),
+ * recomputing the wave plan with `backoffMaxConcurrent(maxConcurrent)` and
+ * retrying the reduced wave; if a single-unit wave still fails, it falls back to
+ * foreground (one-at-a-time) dispatch. This "retry the unit before reducing
+ * concurrency" ordering is owned by GATE-EXEC-DISPATCH-RETRY-BACKOFF in
+ * skills/docs/gate-review-sub-loop-contract.md; the backoff is recorded in the
+ * round's provenance. Pure; never returns 0 (a backoff from 1 stays 1 →
+ * foreground fallback owns that path).
  * @param {number} maxConcurrent
  * @returns {number}
  */
@@ -281,8 +287,8 @@ export function severityRank(severity) {
 /**
  * A zero-initialized severity→count map, one key per SEVERITY_ORDER entry, in
  * SEVERITY_ORDER's order. The shared starting point every severity tally in
- * this codebase (consolidateFanin's own `bySeverity`, consolidate-fanin.mjs's
- * `buildAngleMarker`, reconcile-draft-gate.mjs's no-findings placeholder) used
+ * this codebase (consolidateFanin's own `bySeverity`,
+ * reconcile-draft-gate.mjs's no-findings placeholder) used
  * to hand-roll separately via `Object.fromEntries(SEVERITY_ORDER.map((s) =>
  * [s, 0]))` — one copy here means a severity added to SEVERITY_ORDER is
  * zero-initialized everywhere at once.
@@ -299,10 +305,9 @@ export function zeroSeverityCounts() {
  * finding whose normalized severity is not a recognized SEVERITY_ORDER member
  * is silently excluded from the tally rather than inflating an unknown key —
  * every routed call site here counts already-validated findings in practice
- * (consolidateFanin validates every result's severity before this runs;
- * buildAngleMarker tallies consolidateFanin's own output), so this guard is a
- * defensive floor against future drift, not an escape hatch for accepting
- * unvalidated severities. `findings` and its entries are NOT nullish-tolerant:
+ * (consolidateFanin validates every result's severity before this runs), so
+ * this guard is a defensive floor against future drift, not an escape hatch
+ * for accepting unvalidated severities. `findings` and its entries are NOT nullish-tolerant:
  * a nullish `findings` argument throws (not iterable), and a nullish
  * individual entry throws reading `.severity` — no routed caller passes
  * either shape, so a caller that does gets a loud failure instead of a
@@ -336,6 +341,30 @@ export function normalizeSeverityCounts(counts) {
   return normalized;
 }
 
+/**
+ * Resolve a finding's effective file path from EITHER shape the shared floor
+ * accepts: `file` (singular string, hand-authored / future-producer ledgers) or
+ * `files[0]` (the array shape consolidate-fanin / write-gate-findings-log emit).
+ * The ONE resolver `hasLocatableShape` and every downstream consumer keys on,
+ * so a consumer reading `finding.files[0]` directly can never crash on a
+ * singular-`file` finding that already passed the floor. The value is TRIMMED
+ * and a whitespace-only `file` is treated as ABSENT (it falls back to
+ * `files[0]`, not shadows it), so the resolved path both matches the trimmed
+ * commentable-line-set keys and is a valid GitHub review-comment `path` even
+ * for an untrimmed hand-authored ledger entry (`readGateFindingsLedger` trims
+ * `files[]` but not a singular `file`). Returns `undefined` when neither shape
+ * names a non-blank string path.
+ * @param {{ file?: unknown, files?: unknown }} finding
+ * @returns {string|undefined}
+ */
+export function resolveFindingFile(finding) {
+  if (typeof finding?.file === "string" && finding.file.trim().length > 0) return finding.file.trim();
+  if (Array.isArray(finding?.files) && typeof finding.files[0] === "string" && finding.files[0].trim().length > 0) {
+    return finding.files[0].trim();
+  }
+  return undefined;
+}
+
 /**
  * A finding is LOCATABLE-SHAPED when it names a real file (via `file` or
  * `files[0]`) and a positive-integer `line` — the ONE shared shape check
@@ -352,9 +381,7 @@ export function normalizeSeverityCounts(counts) {
  * @returns {boolean}
  */
 export function hasLocatableShape(finding) {
-  const file = typeof finding?.file === "string"
-    ? finding.file
-    : (Array.isArray(finding?.files) ? finding.files[0] : undefined);
+  const file = resolveFindingFile(finding);
   return typeof file === "string" && file.trim().length > 0
     && Number.isInteger(finding?.line) && /** @type {number} */ (finding.line) >= 1;
 }
@@ -690,7 +717,7 @@ export function fanoutReviewerPairingError(perAngle, resolvedGroups = null) {
 
 /**
  * Base angle name for a delta-suffixed re-review entry (`<angle>-delta-at-...`,
- * e.g. `pr-checklist-matrix-delta-at-current-head`): a re-review scoped to only
+ * e.g. `pr-checklist-delta-at-current-head`): a re-review scoped to only
  * the current head's delta still counts toward its base angle for both
  * mandatory-angle coverage and pool-membership checks.
  *
@@ -736,12 +763,12 @@ export function checkFanoutAngleCoverage(recordedAngles, { mandatoryAngles = [],
 
 /**
  * Angles the fan-in itself mandates and may synthesize (consolidate-fanin's
- * `--pr-checklist-matrix clean` upsert) without them appearing in any gate's
+ * `--pr-checklist clean` upsert) without them appearing in any gate's
  * configured `angles` pool. Always legal in the foreign-angle check above —
  * requiring every consumer repo to also list them per-gate would make the two
  * tools contradict the shared contract they implement.
  */
-export const FANIN_SYNTHETIC_ANGLES = Object.freeze(["pr-checklist-matrix"]);
+export const FANIN_SYNTHETIC_ANGLES = Object.freeze(["pr-checklist"]);
 
 /**
  * Validate a round's RESOLVED angle set — the full angle list the round
@@ -807,7 +834,7 @@ export function checkResolvedAngleEvidence(resolvedAngles, { recordedAngles, car
 export const DEFAULT_MAX_FANOUT_REVIEWERS = 8;
 
 // Every sanctioned angle name is a short, hand-authored slug (e.g.
-// "contradiction-lens", "pr-checklist-matrix"); nothing legitimate ever
+// "contradiction-lens", "pr-checklist"); nothing legitimate ever
 // approaches this length. Bounding it here, at the trust boundary this
 // function already owns, fails a pathological artifact closed as malformed —
 // the same place every other angle-result defect is caught — instead of

package/src/loop/handoff-envelope.mjs

@@ -123,7 +123,7 @@ register(INTERNAL_DEV_LOOP_STRATEGY.FINAL_APPROVAL, "default", {
 register(INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION, "default", {
   criteria: [
     { id: "phase-ac", must: "All phase acceptance criteria from the active phase doc are satisfied.", severity: "required" },
-    { id: "verify-green", must: "`npm run verify` passes with no failures.", severity: "required" },
+    { id: "verify-green", must: "`bun run verify` passes with no failures.", severity: "required" },
   ],
   evidence: ["commands-run", "validation-output", "changed-files"],
   maxFinalizationTurns: 6,
@@ -138,7 +138,7 @@ register(INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION, "default", {
 register(INTERNAL_DEV_LOOP_STRATEGY.LOCAL_IMPLEMENTATION, "spike", {
   criteria: [
     { id: "spike-recorded", must: "The spike exploration and its recommendation are recorded (spike file + summary).", severity: "required" },
-    { id: "verify-green", must: "`npm run verify` passes with no failures.", severity: "required" },
+    { id: "verify-green", must: "`bun run verify` passes with no failures.", severity: "required" },
   ],
   evidence: ["commands-run", "validation-output", "changed-files"],
   maxFinalizationTurns: 6,