@dev-loops/core 0.7.2 → 0.9.0

package/src/loop/public-dev-loop-routing-contract.mjs

@@ -23,6 +23,7 @@ export const DEV_LOOP_PUBLIC_INTENT = Object.freeze({
   CONTINUE_CURRENT: "continue_current",
   AUTO_CONTINUE_CURRENT: "auto_continue_current",
   INSPECT_STATE: "inspect_state",
+  REVIEW_PR_UI: "review_pr_ui",
 });
 
 export const DEV_LOOP_TARGET_KIND = Object.freeze({
@@ -76,6 +77,7 @@ export const DEV_LOOP_GATE = Object.freeze({
   EXTERNAL_PR_FOLLOWUP: "external_pr_followup",
   REVIEWER_FIXER: "reviewer_fixer",
   COPILOT_PR_FOLLOWUP: "copilot_pr_followup",
+  UI_REVIEW: "ui_review",
   FAIL_CLOSED_RECONCILE: "fail_closed_reconcile",
 });
 
@@ -87,6 +89,7 @@ export const INTERNAL_DEV_LOOP_STRATEGY = Object.freeze({
   REVIEWER_FIXER: "reviewer_fixer",
   WAIT_WATCH: "wait_watch",
   FINAL_APPROVAL: "final_approval",
+  UI_REVIEW: "ui_review",
   NONE: null,
 });
 
@@ -267,6 +270,12 @@ export const PUBLIC_DEV_LOOP_GATE_CONTRACT = Object.freeze([
     selectedStrategy: INTERNAL_DEV_LOOP_STRATEGY.COPILOT_PR_FOLLOWUP,
     summary: "Copilot-owned PR state routes to Copilot PR follow-up; an already-linked open PR stays the canonical artifact for that issue until reconciled",
   }),
+  Object.freeze({
+    gate: DEV_LOOP_GATE.UI_REVIEW,
+    routeKind: DEV_LOOP_ROUTE_KIND.ROUTE,
+    selectedStrategy: INTERNAL_DEV_LOOP_STRATEGY.UI_REVIEW,
+    summary: "an explicit UI-review request on a PR target routes to the ui_review running-app review strategy",
+  }),
   Object.freeze({
     gate: DEV_LOOP_GATE.FAIL_CLOSED_RECONCILE,
     routeKind: DEV_LOOP_ROUTE_KIND.NEEDS_RECONCILE,

package/src/loop/public-dev-loop-routing.mjs

@@ -461,7 +461,7 @@ function toRoutableCanonicalState(canonicalState) {
   };
 }
 
-function selectGateForState(canonicalState) {
+function selectGateForState(canonicalState, { uiReviewRequested = false } = {}) {
   if (canonicalState.status === DEV_LOOP_STATUS.BLOCKED || canonicalState.authorization === DEV_LOOP_AUTHORIZATION.NOT_AUTHORIZED) {
     return DEV_LOOP_GATE.STOP_BLOCKED_OR_NOT_AUTHORIZED;
   }
@@ -499,6 +499,15 @@ function selectGateForState(canonicalState) {
     return DEV_LOOP_GATE.ISSUE_INTAKE;
   }
 
+  // An explicit UI-review request intercepts a PR target ahead of the
+  // ownership-derived PR gates: the running-app review is requested regardless
+  // of who owns the PR. It stays after the authoritative lifecycle stop/terminal/
+  // approval/waiting gates so it can never bypass them. Absent the signal this
+  // branch is inert, so existing routes stay byte-identical.
+  if (uiReviewRequested && canonicalState.target.kind === DEV_LOOP_TARGET_KIND.PR) {
+    return DEV_LOOP_GATE.UI_REVIEW;
+  }
+
   if (canonicalState.target.kind === DEV_LOOP_TARGET_KIND.PR && canonicalState.ownership === DEV_LOOP_ACTOR.EXTERNAL_HUMAN) {
     return DEV_LOOP_GATE.EXTERNAL_PR_FOLLOWUP;
   }
@@ -581,10 +590,11 @@ function routeForState(
     issueAssignmentState = null,
     gateReviewEvidence = null,
     targetPreference = null,
+    uiReviewRequested = false,
   } = {},
 ) {
   const routableCanonicalState = toRoutableCanonicalState(canonicalState);
-  const selectedGate = selectGateForState(routableCanonicalState);
+  const selectedGate = selectGateForState(routableCanonicalState, { uiReviewRequested });
   if (
     selectedGate === DEV_LOOP_GATE.FINAL_APPROVAL
     && routableCanonicalState.target.kind === DEV_LOOP_TARGET_KIND.PR
@@ -763,6 +773,18 @@ function routeForState(
     });
   }
 
+  if (selectedGate === DEV_LOOP_GATE.UI_REVIEW) {
+    return buildResult({
+      selectedGate,
+      routeKind: DEV_LOOP_ROUTE_KIND.ROUTE,
+      selectedStrategy: INTERNAL_DEV_LOOP_STRATEGY.UI_REVIEW,
+      executionMode,
+      canonicalState: routableCanonicalState,
+      nextAction: "Run the UI-review route for the current PR: prove the change in the running app from an isolated worktree. Do not write product code; keep any outward review pending/draft; acknowledge destructive migrations before running them.",
+      reason: "An explicit UI-review request on a PR target routes to the ui_review strategy — the running-app review sibling of the reviewer/fixer route.",
+    });
+  }
+
   return buildReconcile(
     "The canonical current state does not map cleanly to any first-slice internal strategy.",
     routableCanonicalState,
@@ -1171,6 +1193,7 @@ export function resolveAuthoritativeStartupResumeBundle(input = {}) {
     issueAssignmentState,
     gateReviewEvidence,
     targetPreference,
+    uiReviewRequested: intent === DEV_LOOP_PUBLIC_INTENT.REVIEW_PR_UI,
   });
   if (routed.routeKind === DEV_LOOP_ROUTE_KIND.NEEDS_RECONCILE) {
     return buildStartupResumeBundleReconcile({
@@ -1703,6 +1726,23 @@ export function evaluatePublicDevLoopRouting(input = {}) {
     ));
   }
 
+  if (intent === DEV_LOOP_PUBLIC_INTENT.REVIEW_PR_UI) {
+    if (!explicitTarget || explicitTarget.kind !== DEV_LOOP_TARGET_KIND.PR) {
+      return buildInputReconcile("`review_pr_ui` requires a PR target.", null, effectiveMode);
+    }
+    if (!explicitState || explicitState.target.kind !== DEV_LOOP_TARGET_KIND.PR) {
+      return buildInputReconcile("`review_pr_ui` requires a valid canonical PR state.", explicitState, effectiveMode);
+    }
+    if (explicitState.target.pr !== explicitTarget.pr) {
+      return buildInputReconcile("`review_pr_ui` target conflicts with the canonical current PR state.", explicitState, effectiveMode);
+    }
+
+    return finalizeRoutingResult(applyWatchValidation(
+      routeForState(explicitState, { ...routingOptions, executionMode: effectiveMode, uiReviewRequested: true }),
+      watchRequested,
+    ));
+  }
+
   if (intent === DEV_LOOP_PUBLIC_INTENT.CONTINUE_CURRENT) {
     if (!explicitState) {
       return buildInputReconcile("`continue_current` requires a valid canonical current state.", null, effectiveMode);

package/src/loop/refinement-grill-state.mjs

@@ -0,0 +1,173 @@
+/**
+ * Deterministic state machine for the refinement/grill sub-loop.
+ *
+ * The refinement loop runs the grill as a CLOSED, DETERMINISTIC sub-loop:
+ * detect-gaps -> auto-answer -> synthesize -> re-grill -> terminal. The
+ * iteration lives entirely in the transition graph below; the LLM answer and
+ * synthesis enter ONLY as a bounded input consumed at the `await_answers`
+ * state (and reflected in the `synthesized` snapshot flag), never as hidden
+ * orchestration inside a deterministic coordinator script (keeps
+ * OPS-NO-INLINE-INTERPRETER, #1224, clean).
+ *
+ * Mirrors the shape of `reviewer-loop-state.mjs` / `copilot-loop-state.mjs`:
+ * a frozen STATE vocabulary, a frozen TRANSITIONS adjacency table, a
+ * `normalize*Snapshot` canonicalizer, and a pure `interpret*State` that maps a
+ * point-in-time snapshot to exactly one current state plus its legal exits.
+ *
+ * Honest handoff: when a gap is genuinely unanswerable (only-`inferred`, no
+ * citation), the machine reaches `needs_human_handoff` naming the question
+ * rather than fabricating an answer to force convergence.
+ */
+
+export const GRILL_STATE = Object.freeze({
+  LOAD_TARGET: "load_target",
+  DETECT_GAPS: "detect_gaps",
+  AWAIT_ANSWERS: "await_answers",
+  SYNTHESIZE: "synthesize",
+  RE_GRILL: "re_grill",
+  GRILL_CLEAN: "grill_clean",
+  NEEDS_HUMAN_HANDOFF: "needs_human_handoff",
+  BLOCKED_NEEDS_USER_DECISION: "blocked_needs_user_decision",
+});
+
+// The iterate-to-clean loop: detect_gaps -> await_answers -> synthesize ->
+// re_grill, with re_grill either re-entering detect_gaps (a new answerable gap
+// surfaced) or terminating at grill_clean (fixed point). Any I/O/parse failure
+// fails closed to blocked_needs_user_decision; any unresolved (uncitable) gap
+// terminates honestly at needs_human_handoff.
+export const GRILL_TRANSITIONS = Object.freeze({
+  [GRILL_STATE.LOAD_TARGET]: [
+    GRILL_STATE.DETECT_GAPS,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.DETECT_GAPS]: [
+    GRILL_STATE.AWAIT_ANSWERS,
+    GRILL_STATE.GRILL_CLEAN,
+    GRILL_STATE.NEEDS_HUMAN_HANDOFF,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.AWAIT_ANSWERS]: [
+    GRILL_STATE.SYNTHESIZE,
+    GRILL_STATE.NEEDS_HUMAN_HANDOFF,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.SYNTHESIZE]: [
+    GRILL_STATE.RE_GRILL,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.RE_GRILL]: [
+    GRILL_STATE.DETECT_GAPS,
+    GRILL_STATE.GRILL_CLEAN,
+    GRILL_STATE.NEEDS_HUMAN_HANDOFF,
+    GRILL_STATE.BLOCKED_NEEDS_USER_DECISION,
+  ],
+  [GRILL_STATE.GRILL_CLEAN]: [],
+  [GRILL_STATE.NEEDS_HUMAN_HANDOFF]: [],
+  [GRILL_STATE.BLOCKED_NEEDS_USER_DECISION]: [],
+});
+
+const GRILL_NEXT_ACTIONS = Object.freeze({
+  [GRILL_STATE.LOAD_TARGET]: "Load the target issue/PR/plan body for grilling",
+  [GRILL_STATE.DETECT_GAPS]: "Run the loop-grill gap detectors on the loaded spec",
+  [GRILL_STATE.AWAIT_ANSWERS]: "Consume the bounded answer input: --auto self-answer with a citation, or ask the human interactively",
+  [GRILL_STATE.SYNTHESIZE]: "Synthesize Acceptance criteria / Definition of done / Non-goals into the body; write raw Q&A only to the ephemeral tmp artifact",
+  [GRILL_STATE.RE_GRILL]: "Re-run gap detection to check for a fixed point",
+  [GRILL_STATE.GRILL_CLEAN]: "Grill reached a fixed point; synthesized spec is clean",
+  [GRILL_STATE.NEEDS_HUMAN_HANDOFF]: "Stop and hand off the named unanswerable question(s) to the human; headless parks with the recorded reason",
+  [GRILL_STATE.BLOCKED_NEEDS_USER_DECISION]: "Stop and request explicit user direction",
+});
+
+const VALID_SURFACES = new Set(["issue", "pr", "plan"]);
+
+function normalizeCount(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? Math.floor(value)
+    : 0;
+}
+
+function normalizeStringOrNull(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+/**
+ * Canonicalize a raw grill snapshot into a deterministic shape.
+ *
+ * @param {object} raw
+ * @returns {object}
+ */
+export function normalizeGrillSnapshot(raw) {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("Snapshot must be a non-null object");
+  }
+
+  return {
+    surface: VALID_SURFACES.has(raw.surface) ? raw.surface : "issue",
+    targetRef: normalizeStringOrNull(raw.targetRef),
+
+    loaded: Boolean(raw.loaded),
+    loadFailed: Boolean(raw.loadFailed),
+
+    detectRan: Boolean(raw.detectRan),
+    // answerable gaps still awaiting an answer this pass
+    openGapCount: normalizeCount(raw.openGapCount),
+    // uncitable gaps that must hand off honestly (never fabricated)
+    unresolvedGapCount: normalizeCount(raw.unresolvedGapCount),
+
+    // the bounded LLM answer input, consumed at await_answers
+    answersReady: Boolean(raw.answersReady),
+    // synthesized AC/DoD/Non-goals applied to the body this iteration
+    synthesized: Boolean(raw.synthesized),
+
+    // post-synthesis re-grill fixed-point signals
+    reGrillRan: Boolean(raw.reGrillRan),
+    reGrillFixedPoint: Boolean(raw.reGrillFixedPoint),
+  };
+}
+
+/**
+ * Deterministically interpret the current refinement-grill state.
+ *
+ * @param {object} snapshot
+ * @returns {{state: string, allowedTransitions: string[], nextAction: string}}
+ */
+export function interpretRefinementGrillState(snapshot) {
+  const s = normalizeGrillSnapshot(snapshot);
+
+  let state;
+
+  if (s.loadFailed) {
+    // Fail closed on any load/parse failure, from any point in the loop.
+    state = GRILL_STATE.BLOCKED_NEEDS_USER_DECISION;
+  } else if (!s.loaded) {
+    state = GRILL_STATE.LOAD_TARGET;
+  } else if (s.unresolvedGapCount > 0) {
+    // Honest handoff outranks everything else: never fabricate to converge.
+    state = GRILL_STATE.NEEDS_HUMAN_HANDOFF;
+  } else if (s.synthesized) {
+    if (!s.reGrillRan) {
+      // Synthesis applied -> re-grill to check the fixed point.
+      state = GRILL_STATE.RE_GRILL;
+    } else if (s.reGrillFixedPoint) {
+      state = GRILL_STATE.GRILL_CLEAN;
+    } else {
+      // Re-grill surfaced a new answerable gap -> iterate.
+      state = GRILL_STATE.DETECT_GAPS;
+    }
+  } else if (s.answersReady) {
+    // Bounded answer input present -> apply synthesis.
+    state = GRILL_STATE.SYNTHESIZE;
+  } else if (s.detectRan) {
+    // Detection ran with no unresolved and no pending answers:
+    // open gaps -> await answers; zero gaps -> clean fixed point
+    // (also the already-refined, zero-iteration path).
+    state = s.openGapCount > 0 ? GRILL_STATE.AWAIT_ANSWERS : GRILL_STATE.GRILL_CLEAN;
+  } else {
+    state = GRILL_STATE.DETECT_GAPS;
+  }
+
+  return {
+    state,
+    allowedTransitions: [...GRILL_TRANSITIONS[state]],
+    nextAction: GRILL_NEXT_ACTIONS[state],
+  };
+}

package/src/loop/ui-review-diagnose.mjs

@@ -0,0 +1,291 @@
+/**
+ * Diagnose + anchor for the ui_review route (Stage 3).
+ *
+ * Consumes the structured captured-failures feed from the drive stage and maps
+ * each failure — exception + JS stack or server-log traceback context — to a
+ * source location (the top in-repo stack frame), then to a diff line on the PR
+ * head so the poster stage can anchor an inline comment on a real changed line.
+ *
+ * This module is PURE: the diff text and the drive result are inputs. The thin
+ * CLI wires the real IO (loop info for PR state + the PR diff fetch).
+ *
+ * Contract: a failure is NEVER silently dropped. One that has no source
+ * location, whose file is not in the diff, whose line is not on a changed diff
+ * line, or whose file maps ambiguously to more than one changed file, is
+ * RETAINED as a finding flagged non-anchorable (with a stated reason) so the
+ * poster body-attaches it instead of inlining.
+ *
+ * Out of scope (later stages): review posting, artifact publishing, auto-fixing.
+ */
+
+const RIGHT = "RIGHT";
+
+/** Severity ordering for the ranked findings list. Unknown severities sort last
+ * but before nothing — a finding is never dropped for an unrecognized severity. */
+const SEVERITY_RANK = Object.freeze({ "must-fix": 0, note: 1 });
+const severityRank = (s) => (s in SEVERITY_RANK ? SEVERITY_RANK[s] : 2);
+
+/** Frames whose file matches a vendor/framework/runtime marker are NOT in-repo:
+ * the diagnosis anchors the change's own code, not a dependency's internals. The
+ * default is deliberately conservative — a project with an unusual layout injects
+ * its own predicate rather than loosening this shared default. */
+const VENDOR_FRAME = /node_modules|[/\\]gems[/\\]|[/\\]vendor[/\\]|\bwebpack:\/\/|^node:|[/\\]ruby[/\\]|[/\\]dist-packages[/\\]/u;
+
+/** Default in-repo predicate: a non-empty file path that is not a vendor frame. */
+export function isInRepoFrame(file) {
+  return typeof file === "string" && file.length > 0 && !VENDOR_FRAME.test(file);
+}
+
+/** Extract the exception type + message from stack/traceback text. Matches the
+ * first exception token and the text that follows it: a `SomethingError`/
+ * `SomethingException`-suffixed name (JS `TypeError: msg`, Ruby `NoMethodError
+ * (msg)`, Python/dotted `django.core.exceptions.ValidationError: msg`) OR a Ruby
+ * `::`-namespaced constant like `ActiveRecord::RecordNotFound` /
+ * `Mongoid::Errors::DocumentNotFound`, captured whole. The `::` alternative
+ * requires at least one namespace segment so it signals a class, not an
+ * arbitrary identifier. Returns nulls when no recognizable exception name is
+ * present. */
+export function parseException(text = "") {
+  const m = String(text).match(/([A-Z]\w*(?:::[A-Z]\w*)+|[A-Za-z_][\w.]*(?:Error|Exception))\b[:\s(]*([^\n)]*)/u);
+  if (!m) return { type: null, message: null };
+  const message = m[2].trim();
+  return { type: m[1], message: message.length > 0 ? message : null };
+}
+
+/** Parse a single stack/traceback line into `{file, line}` or null. Tries the
+ * three shapes the drive feed can carry: Python `File "path", line N`, JS
+ * `at ... (file:line:col)`, then a generic `path.ext:line` (Ruby, and JS frames
+ * without an `at` prefix). */
+function extractFrameFromLine(line) {
+  let m = line.match(/File "([^"]+)", line (\d+)/u);
+  if (m) return { file: m[1], line: Number(m[2]) };
+  // The file capture excludes only whitespace/parens (not `:`) and is lazy, so a
+  // served URL (`http://host:3000/assets/x.js`) is captured whole up to the
+  // trailing `:line:col` — normalizeFrameFile then strips the scheme/authority.
+  m = line.match(/\bat\s+(?:.*\()?([^\s()]+?):(\d+)(?::\d+)?\)?\s*$/u);
+  if (m) return { file: m[1], line: Number(m[2]) };
+  m = line.match(/([^\s():]+\.[A-Za-z0-9_]+):(\d+)\b/u);
+  if (m) return { file: m[1], line: Number(m[2]) };
+  return null;
+}
+
+/** Extract all frames from multi-line stack/traceback text, preserving order. */
+export function extractFrames(text = "") {
+  const frames = [];
+  for (const line of String(text).split("\n")) {
+    const frame = extractFrameFromLine(line);
+    if (frame) frames.push(frame);
+  }
+  return frames;
+}
+
+/** The top in-repo frame drives the anchor: the first frame (topmost, closest to
+ * the throw) whose file passes the in-repo predicate. We do NOT search deeper for
+ * a frame that happens to be in the diff — anchoring a lower frame would point at
+ * a caller, not the failing line. A deeper frame that is in-repo but not in the
+ * diff is handled downstream as non-anchorable, never by guessing past the top. */
+export function topInRepoFrame(frames) {
+  return frames.find((f) => isInRepoFrame(f.file)) ?? null;
+}
+
+/**
+ * Parse a unified diff into a map of changed file -> set of ADDED head line
+ * numbers (the RIGHT side). EVERY changed file is a key (registered from its
+ * `diff --git`/`+++ ` header) so a file that is changed but adds no anchorable
+ * line (deletion-only, binary, or mode-only) still reports as changed with an
+ * empty set — distinct from a file the PR never touched. Only added (`+`) lines
+ * are anchor targets: an inline comment on an added line points at code the PR
+ * introduced. Unchanged context lines advance the head counter but are not
+ * anchor targets — a defect on an unchanged line is body-attached, not falsely
+ * pinned to "changed" code.
+ *
+ * @param {string} diffOutput - raw `gh pr diff` / `git diff` unified output.
+ * @returns {Map<string, Set<number>>}
+ */
+export function parseDiffAnchors(diffOutput = "") {
+  const map = new Map();
+  const register = (p) => {
+    if (p !== null && !map.has(p)) map.set(p, new Set());
+  };
+  let currentPath = null;
+  let newLine = 0;
+  let inHunk = false;
+  for (const line of String(diffOutput).split("\n")) {
+    if (line.startsWith("diff --git")) {
+      // The only hunk terminator: a bare `diff --git` can never be hunk content
+      // (content lines always carry a `+`/`-`/space prefix), so it always resets.
+      currentPath = null;
+      inHunk = false;
+      // Register the RIGHT-side path so binary/mode-only changes (which carry no
+      // `+++ ` header) still count as changed files.
+      const m = line.match(/^diff --git a\/.+ b\/(.+)$/u);
+      if (m) register(m[1]);
+      continue;
+    }
+    // File headers appear only before the first hunk. Inside a hunk a line
+    // beginning `+++ `/`--- ` is content (an added `++ x` / a deleted `-- x`),
+    // so it must fall through to the `+`/`-` content handling below, not be
+    // misread as a header that rebinds the path or drops the rest of the hunk.
+    if (!inHunk && line.startsWith("+++ ")) {
+      const p = line.slice(4).trim();
+      currentPath = p === "/dev/null" ? null : p.replace(/^b\//u, "");
+      // Register even deletion-only files (they keep a `+++ b/path` header but
+      // add no line) so they report as changed rather than not-among-changed.
+      register(currentPath);
+      continue;
+    }
+    if (!inHunk && line.startsWith("--- ")) {
+      continue;
+    }
+    if (line.startsWith("@@")) {
+      const m = line.match(/@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/u);
+      newLine = m ? Number(m[1]) : 0;
+      inHunk = Boolean(m);
+      continue;
+    }
+    if (!inHunk || currentPath === null) continue;
+    if (line.startsWith("+")) {
+      if (!map.has(currentPath)) map.set(currentPath, new Set());
+      map.get(currentPath).add(newLine);
+      newLine += 1;
+    } else if (line.startsWith("-")) {
+      // Deleted line: present only on the old side, so it does not advance the head counter.
+    } else if (line.startsWith("\\")) {
+      // "": a marker, not a content line.
+    } else {
+      // Context line: on both sides, so it advances the head counter but is not an anchor target.
+      newLine += 1;
+    }
+  }
+  return map;
+}
+
+/** Normalize a stack-frame file to a repo-relative-comparable form: strip a URL
+ * scheme+authority (`http://host/assets/x.js` -> `/assets/x.js`) and any
+ * query/hash, then fold Windows `\` separators to `/`, so an absolute, served,
+ * or Windows-style path can be suffix-matched to a (forward-slash) diff path. */
+function normalizeFrameFile(file) {
+  let s = String(file);
+  const scheme = s.match(/^[a-z][a-z0-9+.\-]*:\/\/[^/]*(\/.*)$/iu);
+  if (scheme) s = scheme[1];
+  return s.split(/[?#]/u)[0].replace(/\\/gu, "/");
+}
+
+/** The source-file -> changed-file mapping is the fragile axis (bundlers, moved
+ * code, served paths). Match a frame file to a diff path by exact match or path
+ * suffix. Return every match so an ambiguous mapping (more than one changed file
+ * is a suffix of the frame path) is flagged rather than guessed. */
+function matchDiffPaths(frameFile, anchorPaths) {
+  const nf = normalizeFrameFile(frameFile);
+  return anchorPaths.filter((p) => nf === p || nf.endsWith(`/${p}`));
+}
+
+/**
+ * Map one Stage-2 failure to a finding: parse its exception + source location,
+ * resolve an anchor on the diff, or retain it flagged non-anchorable.
+ *
+ * @param {object} failure - a `classifyFailures` entry `{kind, severity, message, ...}`.
+ * @param {Map<string,Set<number>>} anchorsByPath
+ * @param {object|null} evidence - the reproduced-evidence reference to attach.
+ */
+function diagnoseOne(failure, anchorsByPath, evidence) {
+  // page-error carries `stack`; server-log-exception carries `context`; the
+  // wire-level failures (error/request) carry neither -> no source location.
+  const sourceText =
+    failure.kind === "page-error" ? failure.stack :
+    failure.kind === "server-log-exception" ? failure.context :
+    "";
+  const exception = parseException(sourceText || failure.message || "");
+  const finding = {
+    severity: failure.severity ?? null,
+    kind: failure.kind,
+    message: failure.message ?? null,
+    exception,
+    source: null,
+    anchor: null,
+    anchorable: false,
+    nonAnchorableReason: null,
+    evidence,
+  };
+
+  const frame = topInRepoFrame(extractFrames(sourceText || ""));
+  if (!frame) {
+    finding.nonAnchorableReason = "no source location (no in-repo stack frame in the captured failure)";
+    return finding;
+  }
+  finding.source = frame;
+
+  const matches = matchDiffPaths(frame.file, [...anchorsByPath.keys()]);
+  if (matches.length === 0) {
+    finding.nonAnchorableReason = "source file is not among the PR's changed files";
+    return finding;
+  }
+  if (matches.length > 1) {
+    finding.nonAnchorableReason = `ambiguous: source file maps to more than one changed file (${matches.join(", ")})`;
+    return finding;
+  }
+  const path = matches[0];
+  if (!anchorsByPath.get(path).has(frame.line)) {
+    finding.nonAnchorableReason = "source line is not on an added diff line";
+    return finding;
+  }
+  finding.anchor = { path, line: frame.line, side: RIGHT };
+  finding.anchorable = true;
+  return finding;
+}
+
+/**
+ * Rank findings deterministically — no wall-clock, no input-order dependence.
+ * Order: severity (must-fix first), then anchorable-first (the poster can inline
+ * these), then kind, then source file, then source line. Every key is a total
+ * order over the data so the result is stable for a given input set.
+ */
+export function rankFindings(findings) {
+  const key = (f) => [
+    severityRank(f.severity),
+    f.anchorable ? 0 : 1,
+    f.kind ?? "",
+    f.source?.file ?? "",
+    f.source?.line ?? 0,
+  ];
+  return [...findings].sort((a, b) => {
+    const ka = key(a);
+    const kb = key(b);
+    for (let i = 0; i < ka.length; i += 1) {
+      if (ka[i] < kb[i]) return -1;
+      if (ka[i] > kb[i]) return 1;
+    }
+    return 0;
+  });
+}
+
+/**
+ * Diagnose the drive stage's captured failures into a ranked findings list with
+ * diff-line anchors or explicit non-anchorable flags plus reproduced-evidence
+ * references. Pure.
+ *
+ * @param {object} input
+ * @param {object[]} [input.failures] - the drive stage's `failures`.
+ * @param {object[]} [input.captures] - the drive stage's `captures` (evidence).
+ * @param {string} [input.diffOutput] - the PR's unified diff.
+ * @returns {{ok:boolean, findings:object[], counts:{total:number,anchorable:number,nonAnchorable:number}}}
+ */
+export function diagnoseFailures({ failures = [], captures = [], diffOutput = "" } = {}) {
+  const anchorsByPath = parseDiffAnchors(diffOutput);
+  // ponytail: one reproduced-evidence reference per finding — the drive's final
+  // captured state (the last screenshot/state pair). Per-step attribution would
+  // need brittle parsing of the step-failure message; wire flow/step through the
+  // drive feed first if a stage needs frame-accurate evidence.
+  const last = captures.length > 0 ? captures[captures.length - 1] : null;
+  const evidence = last
+    ? { flow: last.flow ?? null, step: last.step ?? null, screenshotPath: last.screenshotPath ?? null, statePath: last.statePath ?? null }
+    : null;
+
+  const findings = rankFindings(failures.map((f) => diagnoseOne(f, anchorsByPath, evidence)));
+  const anchorable = findings.filter((f) => f.anchorable).length;
+  return {
+    ok: findings.length === 0,
+    findings,
+    counts: { total: findings.length, anchorable, nonAnchorable: findings.length - anchorable },
+  };
+}