@nathapp/nax 0.75.6 → 0.76.0

package/flows/nax-finish/commit-message.ts

@@ -0,0 +1,136 @@
+/**
+ * Commit messages for the flow's `commit_<phase>` checkpoints.
+ *
+ * These commits are shipped history — they land on the feature branch and a
+ * human reviews them in the PR. Every one of them used to read
+ * `fix(<feature>): nax-finish <phase> fixes` with an empty body, so a reviewer
+ * looking at six such commits could not tell which one re-enabled a disabled
+ * market gate and which one renamed a variable. The reviewer already produced
+ * exactly the material needed to say so — severity, title, problem, fix — and
+ * it was being discarded at the one moment it could have been recorded.
+ *
+ * Subject lines follow the repo's conventional-commit rule and the 72-column
+ * git summary convention; the findings go in the body, one bullet each.
+ */
+import type { Finding, FinishPhase } from "./types";
+
+/** Git's conventional soft cap for a commit summary line. */
+const MAX_SUBJECT_LEN = 72;
+
+/** Worst-first, so the subject of a mixed batch reports the severity that matters. */
+const SEVERITY_ORDER = ["CRITICAL", "HIGH", "MEDIUM", "LOW"] as const;
+
+/** How much gate output to quote in the body before it stops being a commit message. */
+const MAX_GATE_OUTPUT_LINES = 20;
+
+interface MessageCtx {
+  outputs: Record<string, unknown>;
+}
+
+interface PhaseOutputs {
+  findings?: Finding[];
+  failing?: string[];
+  output?: string;
+}
+
+function outputsFor(ctx: MessageCtx, nodeId: string): PhaseOutputs {
+  return (ctx.outputs[nodeId] ?? {}) as PhaseOutputs;
+}
+
+function findingsFor(ctx: MessageCtx, phase: FinishPhase): Finding[] {
+  const raw = outputsFor(ctx, `review_${phase}`).findings;
+  return Array.isArray(raw) ? raw.filter((f): f is Finding => Boolean(f?.title)) : [];
+}
+
+function worstSeverity(findings: Finding[]): string {
+  const present = new Set(findings.map((f) => f.severity));
+  return SEVERITY_ORDER.find((s) => present.has(s)) ?? findings[0]?.severity ?? "LOW";
+}
+
+/**
+ * Lowercase a finding title's leading word for the subject line.
+ *
+ * Reviewers write titles as sentences ("Market gate skip branch is
+ * unreachable"); conventional-commit subjects read better in lower case. Only
+ * the first character is touched — an all-caps leading token is an acronym
+ * (`SSRF guard …`) and must survive intact.
+ */
+function subjectCase(title: string): string {
+  const [first = "", ...rest] = title.split(" ");
+  const isAcronym = first.length > 1 && first === first.toUpperCase();
+  return isAcronym
+    ? title
+    : `${first.charAt(0).toLowerCase()}${first.slice(1)}${rest.length ? ` ${rest.join(" ")}` : ""}`;
+}
+
+function truncate(s: string): string {
+  return s.length <= MAX_SUBJECT_LEN ? s : `${s.slice(0, MAX_SUBJECT_LEN - 3)}...`;
+}
+
+/** "lint and test", "lint, test and typecheck" — a readable list for the subject. */
+function humanList(items: string[]): string {
+  if (items.length <= 1) return items[0] ?? "";
+  return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+
+function reviewSubject(phase: FinishPhase, findings: Finding[]): string {
+  if (findings.length === 1) return subjectCase(findings[0].title);
+  return `address ${findings.length} ${phase} review findings (worst: ${worstSeverity(findings)})`;
+}
+
+function subjectFor(phase: FinishPhase, ctx: MessageCtx): string {
+  if (phase === "gate") {
+    const failing = outputsFor(ctx, "quality_gates").failing ?? [];
+    return failing.length > 0 ? `repair failing ${humanList(failing)} gates` : "repair failing quality gates";
+  }
+  if (phase === "acceptance") return "repair failing acceptance tests";
+  const findings = findingsFor(ctx, phase);
+  return findings.length > 0 ? reviewSubject(phase, findings) : `apply ${phase} review fixes`;
+}
+
+function bodyFor(phase: FinishPhase, ctx: MessageCtx): string[] {
+  if (phase === "gate") {
+    const gate = outputsFor(ctx, "quality_gates");
+    const failing = gate.failing ?? [];
+    const tail = (gate.output ?? "").trim().split("\n").slice(-MAX_GATE_OUTPUT_LINES).join("\n");
+    return [...(failing.length > 0 ? [`Failing: ${failing.join(", ")}`] : []), ...(tail ? [tail] : [])];
+  }
+  if (phase === "acceptance") {
+    const tail = (outputsFor(ctx, "acceptance").output ?? "")
+      .trim()
+      .split("\n")
+      .slice(-MAX_GATE_OUTPUT_LINES)
+      .join("\n");
+    return tail ? [tail] : [];
+  }
+  const findings = findingsFor(ctx, phase);
+  if (findings.length === 0) return [];
+  return [
+    findings
+      .map((f) =>
+        [`- [${f.severity}] ${f.title}`, f.problem ? `  ${f.problem}` : "", f.fix ? `  Fix: ${f.fix}` : ""]
+          .filter(Boolean)
+          .join("\n"),
+      )
+      .join("\n"),
+  ];
+}
+
+/** Human-readable phase label for the attribution trailer. */
+function phaseLabel(phase: FinishPhase): string {
+  return phase === "gate" ? "quality gate" : phase === "acceptance" ? "acceptance" : `${phase} review`;
+}
+
+/**
+ * Build the commit message for a `commit_<phase>` checkpoint.
+ *
+ * Never throws and never returns an empty subject: a missing or malformed
+ * reviewer output degrades to the phase label. A commit that cannot be
+ * described is still a commit that must happen — failing here would strand the
+ * fix uncommitted and reintroduce the stale-diff bug (#1397).
+ */
+export function buildFixCommitMessage(phase: FinishPhase, feature: string, ctx: MessageCtx): string {
+  const subject = truncate(`fix(${feature}): ${subjectFor(phase, ctx)}`);
+  const body = bodyFor(phase, ctx);
+  return [subject, ...body, `nax-finish: ${phaseLabel(phase)} fixes`].join("\n\n");
+}

package/flows/nax-finish/flow-ctx.ts

@@ -0,0 +1,95 @@
+/**
+ * Readers over an acpx `FlowNodeContext` — the flow graph's view of its own
+ * state.
+ *
+ * Split out of `nax-finish.flow.ts` (600-line source cap). These are all pure
+ * functions of `ctx.input` / `ctx.outputs` / `ctx.state.steps`; anything that
+ * shells out lives under `./steps/`.
+ *
+ * Two views of the same run, and the difference matters in a graph whose whole
+ * shape is loops:
+ *
+ * - `ctx.outputs` is a map keyed by node id, so it holds only each node's
+ *   **latest** output. A node re-entering a loop cannot see its own previous
+ *   round there.
+ * - `ctx.state.steps` is the ordered history and carries every step's `output`,
+ *   so an earlier round IS recoverable from it. A step is appended on its
+ *   *outcome*, so the currently-executing node is never in this list — which is
+ *   what lets `incrementalSince` find the *previous* review rather than itself.
+ */
+import type { AcceptanceGroup, Finding, FinishInput, FinishPhase, ReviewVerdict } from "./types";
+
+/** Minimal shapes so each reader takes only the part of the context it reads. */
+export interface StepsCtx {
+  state: { steps: { nodeId: string; output?: unknown }[] };
+}
+export interface OutputsCtx {
+  outputs: unknown;
+}
+
+export const inputOf = (ctx: { input: unknown }) => ctx.input as FinishInput;
+
+/** What `load_ctx` resolves once, for every downstream node to read. */
+export interface LoadCtxOutput {
+  base?: string;
+  specPath?: string;
+  groups?: AcceptanceGroup[];
+  /** `nax features resolve`'s acceptance status: "ok" | "disabled" | "no-prd". */
+  acceptanceStatus?: string;
+  /** Test-file regex sources from `nax features resolve`; empty = cannot classify. */
+  testFileRegex?: string[];
+  route?: string;
+}
+
+export function fixAttemptCount(ctx: StepsCtx, fixNodeId: string): number {
+  return (ctx.state.steps ?? []).filter((s) => s.nodeId === fixNodeId).length;
+}
+
+export function loadCtxOf(ctx: OutputsCtx): LoadCtxOutput {
+  return ((ctx.outputs as Record<string, LoadCtxOutput | undefined>).load_ctx ?? {}) as LoadCtxOutput;
+}
+
+export function gateOutputs(ctx: OutputsCtx): { failing?: string[] } {
+  return ((ctx.outputs as Record<string, { failing?: string[] } | undefined>).quality_gates ?? {}) as {
+    failing?: string[];
+  };
+}
+
+/** The findings the `fix_<phase>` node was asked to resolve; empty for non-review phases. */
+export function findingsOf(ctx: OutputsCtx, phase: FinishPhase): Finding[] {
+  if (phase !== "spec" && phase !== "quality") return [];
+  return (ctx.outputs as Record<string, ReviewVerdict | undefined>)[`review_${phase}`]?.findings ?? [];
+}
+
+/**
+ * The ref a re-review should diff from, or null to review the whole branch.
+ *
+ * A reviewer node re-reads the spec in full and the entire `git diff
+ * base...HEAD` on every round. Reviews were 58% of the wall clock on
+ * rs-stock/pipeline-run-outcome (7 calls, 1306s of 2232s), and round 3 re-read
+ * everything rounds 1-2 had already cleared.
+ *
+ * The scoping ref is the `shaBefore` of the **first** `commit_*` step after this
+ * phase's last review — that commit's parent is, by construction, the tree the
+ * previous verdict passed on, since only `commit_*` nodes commit. Taking the
+ * first (not the last) is what makes the window complete when more than one
+ * commit landed in it, which happens when the acceptance loop commits between a
+ * spec fix and its re-review: `firstCommit.shaBefore..HEAD` spans both.
+ *
+ * Read from `ctx.state.steps[].output`, not `ctx.outputs` — the latter keeps
+ * only each node's newest output, which for two commit steps of the same node id
+ * would have discarded the earlier `shaBefore` and silently under-scoped the
+ * review.
+ *
+ * Returns null — a full review — when there is no prior review of this phase
+ * (round 1), no commit since it (nothing new to look at), or the commit step
+ * recorded no `shaBefore`.
+ */
+export function incrementalSince(ctx: OutputsCtx & StepsCtx, phase: "spec" | "quality"): string | null {
+  const steps = ctx.state.steps ?? [];
+  const lastReview = steps.map((s) => s.nodeId).lastIndexOf(`review_${phase}`);
+  if (lastReview < 0) return null;
+  const firstCommit = steps.slice(lastReview + 1).find((s) => s.nodeId.startsWith("commit_"));
+  if (!firstCommit) return null;
+  return (firstCommit.output as { shaBefore?: string | null } | undefined)?.shaBefore ?? null;
+}

package/flows/nax-finish/nax-finish.flow.ts

@@ -31,17 +31,31 @@
  *   the `acceptance` node last passed, and the repo-root `test` command does
  *   not cover per-feature acceptance tests — so without this a fix could break
  *   the contract the first gate proved and still ship.
+ * - `commit_gate` re-enters `review_quality` when its fix touched non-test code
+ *   — the gate loop was previously the one editing loop whose output only ever
+ *   faced mechanical checks. A test-only fix skips the re-review by explicit
+ *   cost tradeoff; see `gateCommitRoute` for why that is a known hole.
+ * - Every `commit_*` node appends its round to the finish-audit trail as it
+ *   happens, rather than a terminal node reconstructing them from
+ *   `ctx.state.steps`. Appending live is what makes the trail survive a flow
+ *   that is killed or times out — no terminal node runs on that path, and a
+ *   crashed finish is exactly when the record of what it changed matters most.
  */
 import { defineFlow, extractJsonObject } from "acpx/flows";
+import { buildFixCommitMessage } from "./commit-message";
+import { findingsOf, fixAttemptCount, gateOutputs, incrementalSince, inputOf, loadCtxOf } from "./flow-ctx";
 import { buildReviewPrompt, fixPrompt } from "./review-prompts";
 import {
   _contextDeps,
+  appendRound,
   buildEscalationComment,
   commitAndPush,
   commitFixes,
   detectBaseBranch,
+  filesInCommit,
   loadQualityCommands,
   openOrPromotePr,
+  partitionTestFiles,
   postEscalation,
   preflight,
   resolveFeature,
@@ -49,9 +63,7 @@ import {
   runQualityGates,
   writeResult,
 } from "./steps";
-import type { AcceptanceGroup, FinishInput, FinishResult, ReviewVerdict } from "./types";
-
-const inputOf = (ctx: { input: unknown }) => ctx.input as FinishInput;
+import type { FinishInput, FinishPhase, FinishResult, ReviewVerdict } from "./types";
 
 /**
  * Cap on fix-and-reverify iterations, per phase, before escalating instead of
@@ -61,23 +73,6 @@ const inputOf = (ctx: { input: unknown }) => ctx.input as FinishInput;
  */
 const MAX_FIX_ATTEMPTS = 3;
 
-interface LoadCtxOutput {
-  base?: string;
-  specPath?: string;
-  groups?: AcceptanceGroup[];
-  /** `nax features resolve`'s acceptance status: "ok" | "disabled" | "no-prd". */
-  acceptanceStatus?: string;
-  route?: string;
-}
-
-function fixAttemptCount(ctx: { state: { steps: { nodeId: string }[] } }, fixNodeId: string): number {
-  return (ctx.state.steps ?? []).filter((s) => s.nodeId === fixNodeId).length;
-}
-
-function loadCtxOf(ctx: { outputs: unknown }): LoadCtxOutput {
-  return ((ctx.outputs as Record<string, LoadCtxOutput | undefined>).load_ctx ?? {}) as LoadCtxOutput;
-}
-
 /**
  * Re-run the acceptance gate, routing on the shared fix-cap rules.
  *
@@ -169,16 +164,91 @@ function routeReview(
  * One node per phase rather than a single shared one because each returns to a
  * different successor, and acpx routes on the node id — a shared node would
  * need a switch reconstructing which fix ran from the step history.
+ *
+ * Also the audit seam: this is the only point in the graph where a round's
+ * findings and its commit are both known. `ctx.outputs` keeps only the latest
+ * output per node, so a round not recorded here is a round no terminal node
+ * can reconstruct.
+ */
+/**
+ * Route for `commit_gate`, whose successor depends on what the fix touched.
+ *
+ * - `unchanged` — nothing committed; no new diff, so nothing to review.
+ * - `tests-only` — every touched path matched the repo's test-file patterns.
+ *   Skipped by explicit choice: the re-review is the flow's most expensive node
+ *   and a gate fix is usually a mechanical test repair. **This is a real hole.**
+ *   The defect that motivated the re-entry (rs-stock `b6fb66dd`) was itself
+ *   test-only — 8 copy-pasted stubs across 3 test files — so this route would
+ *   not have caught it. Widen it here if test-quality regressions start
+ *   shipping.
+ * - `changed` — production code was touched, or the paths could not be
+ *   classified at all. "Cannot classify" reviews rather than skips.
+ */
+async function gateCommitRoute(
+  i: FinishInput,
+  committed: boolean,
+  shaAfter: string | null,
+  testFileRegex: string[],
+): Promise<string> {
+  if (!committed) return "unchanged";
+  // Committed, but HEAD did not resolve: the fix is real and unclassifiable, so
+  // it must be reviewed. Folding this into the `!committed` branch would skip
+  // the review for a change that actually landed — the one direction this
+  // function must never fail in.
+  if (!shaAfter) return "changed";
+  const files = await filesInCommit(i.workdir, shaAfter);
+  if (files.length === 0) return "changed";
+  return partitionTestFiles(files, testFileRegex).nonTest.length > 0 ? "changed" : "tests-only";
+}
+
+/**
+ * Build the `commit_<phase>` node that follows `fix_<phase>`.
+ *
+ * One node per phase rather than a single shared one because each returns to a
+ * different successor, and acpx routes on the node id — a shared node would
+ * need a switch reconstructing which fix ran from the step history.
+ *
+ * Also the audit seam: this is the only point in the graph where a round's
+ * findings and its commit are both known. `ctx.outputs` keeps only the latest
+ * output per node, so a round not recorded here is a round no terminal node
+ * can reconstruct. `shaBefore` is recorded for the same reason — it is what the
+ * next review of this phase diffs from (see `incrementalSince`).
  */
-function commitFixNode(phase: "acceptance" | "spec" | "quality" | "gate") {
+function commitFixNode(phase: FinishPhase) {
   return {
     nodeType: "action" as const,
-    async run(ctx: { input: unknown }): Promise<{ committed: boolean }> {
+    async run(ctx: {
+      input: unknown;
+      outputs: unknown;
+      state: { steps: { nodeId: string }[] };
+    }): Promise<{ committed: boolean; route: string; shaBefore: string | null; shaAfter: string | null }> {
       const i = inputOf(ctx);
+      const messageCtx = { outputs: ctx.outputs as Record<string, unknown> };
       // skipHooks: an intermediate checkpoint must not be rejected by a repo's
       // pre-commit hook — quality_gates runs the repo's real gates before any
       // PR opens, and a hook failure here would kill the flow mid-loop.
-      return commitFixes(i.workdir, `fix(${i.feature}): nax-finish ${phase} fixes`, { skipHooks: true });
+      const { committed, shaBefore, shaAfter } = await commitFixes(
+        i.workdir,
+        buildFixCommitMessage(phase, i.feature, messageCtx),
+        { skipHooks: true },
+      );
+      await appendRound(i, {
+        ts: new Date().toISOString(),
+        phase,
+        attempt: fixAttemptCount(ctx, `fix_${phase}`),
+        committed,
+        findings: findingsOf(ctx, phase),
+        ...(phase === "gate" ? { failing: gateOutputs(ctx).failing ?? [] } : {}),
+      });
+      // Only `commit_gate` routes on this; the other phases have unconditional
+      // edges and ignore it.
+      const route =
+        phase === "gate"
+          ? await gateCommitRoute(i, committed, shaAfter, loadCtxOf(ctx).testFileRegex ?? [])
+          : committed
+            ? "changed"
+            : "unchanged";
+      return { committed, route, shaBefore, shaAfter };
     },
   };
 }
@@ -212,6 +282,7 @@ export default defineFlow({
           specPath: resolution.specPath,
           acceptanceStatus: resolution.acceptanceStatus,
           groups: resolution.groups,
+          testFileRegex: resolution.testFileRegex,
           commitsAhead: pf.commitsAhead,
           route: pf.route,
         };
@@ -233,7 +304,12 @@ export default defineFlow({
       profile: process.env.NAX_FINISH_SPEC_PROFILE || undefined,
       prompt(ctx) {
         const outs = loadCtxOf(ctx);
-        return buildReviewPrompt("spec", { base: outs.base ?? "origin/main", specPath: outs.specPath ?? "" });
+        return buildReviewPrompt("spec", {
+          base: outs.base ?? "origin/main",
+          specPath: outs.specPath ?? "",
+          since: incrementalSince(ctx, "spec"),
+          priorFindings: findingsOf(ctx, "spec"),
+        });
       },
       parse: parseVerdict,
     },
@@ -253,7 +329,12 @@ export default defineFlow({
       profile: process.env.NAX_FINISH_QUALITY_PROFILE || undefined,
       prompt(ctx) {
         const outs = loadCtxOf(ctx);
-        return buildReviewPrompt("quality", { base: outs.base ?? "origin/main", specPath: outs.specPath ?? "" });
+        return buildReviewPrompt("quality", {
+          base: outs.base ?? "origin/main",
+          specPath: outs.specPath ?? "",
+          since: incrementalSince(ctx, "quality"),
+          priorFindings: findingsOf(ctx, "quality"),
+        });
       },
       parse: parseVerdict,
     },
@@ -350,7 +431,7 @@ export default defineFlow({
       async run(ctx) {
         const i = inputOf(ctx);
         if (loadCtxOf(ctx).route === "nothing-to-finish") {
-          await writeResult(i.workdir, { feature: i.feature, status: "nothing-to-finish" });
+          await writeResult(i, { feature: i.feature, status: "nothing-to-finish" });
           return { route: "done", status: "nothing-to-finish" };
         }
         // Every fix node edited the working tree; without this the PR would be
@@ -362,7 +443,7 @@ export default defineFlow({
           `nax-finish: ${i.feature}`,
           `Automated finish of \`${i.feature}\`.`,
         );
-        await writeResult(i.workdir, { feature: i.feature, status: r.status, url: r.url });
+        await writeResult(i, { feature: i.feature, status: r.status, url: r.url });
         return { route: "done", committed: sync.committed, ...r };
       },
     },
@@ -409,7 +490,7 @@ export default defineFlow({
           escalationReason: reason,
           findings: verdict?.findings ?? [],
         };
-        await writeResult(i.workdir, result);
+        await writeResult(i, result);
 
         const comment = buildEscalationComment(i.feature, reason, verdict?.findings ?? []) + syncNote;
         let url: string | undefined;
@@ -424,7 +505,7 @@ export default defineFlow({
         } catch (err) {
           deliveryError = String(err);
         }
-        await writeResult(i.workdir, { ...result, url, deliveryError });
+        await writeResult(i, { ...result, url, deliveryError });
 
         return { route: "done", url, channel, deliveryError, escalationReason: reason };
       },
@@ -464,6 +545,24 @@ export default defineFlow({
       switch: { on: "$.route", cases: { green: "open_pr", fix: "fix_gate", escalate: "escalate" } },
     },
     { from: "fix_gate", to: "commit_gate" },
-    { from: "commit_gate", to: "quality_gates" },
+    // A gate fix that changed code goes back through the quality reviewer, not
+    // straight to the gates. The gate loop is the last one to edit the tree and
+    // was the only one whose edits nothing reviewed: `quality_gates` proves the
+    // repo's commands are green, which a bad fix can satisfy. Observed on
+    // rs-stock/pipeline-run-outcome — the gate round repaired 8 tests by
+    // copy-pasting an identical 4-line stub into each, and it shipped, because
+    // no reviewer ran after it. Re-entry costs one review per gate round; both
+    // loops stay bounded by their own MAX_FIX_ATTEMPTS caps.
+    //
+    // `unchanged` skips it: with nothing committed there is no new diff to
+    // review, and re-running the reviewer on an identical tree would burn a
+    // turn to re-report what route_quality already called clean.
+    {
+      from: "commit_gate",
+      switch: {
+        on: "$.route",
+        cases: { changed: "review_quality", "tests-only": "quality_gates", unchanged: "quality_gates" },
+      },
+    },
   ],
 });

package/flows/nax-finish/review-prompts.ts

@@ -1,3 +1,5 @@
+import type { Finding } from "./types";
+
 export const SPEC_REVIEW_DIMENSIONS = `# Spec-relative review dimensions
 
 Reference for the post-impl-review **spec-relative** pass: Compliance, Drift,
@@ -310,12 +312,48 @@ const JSON_CONTRACT = [
   "}",
 ].join("\n");
 
-export function buildReviewPrompt(phase: "spec" | "quality", args: { base: string; specPath: string }): string {
+/**
+ * Build the reviewer prompt.
+ *
+ * With `since` set this is a **re-review**: the same reviewer already read the
+ * whole branch and raised `priorFindings`, a fix was applied and committed, and
+ * the only new material is `since..HEAD`. Re-reading the full branch diff every
+ * round made reviews 58% of the flow's wall clock, most of it re-reading code an
+ * earlier round had already cleared. The narrowed round still has the full repo
+ * available — it is told to open whatever the fix touches — it just is not asked
+ * to re-derive a verdict on unchanged code.
+ *
+ * `since` is only ever supplied when exactly one commit separates the two
+ * reviews (see `incrementalSince`), so `since..HEAD` provably contains every
+ * change made since the previous verdict.
+ */
+export function buildReviewPrompt(
+  phase: "spec" | "quality",
+  args: { base: string; specPath: string; since?: string | null; priorFindings?: Finding[] },
+): string {
   const dims = phase === "spec" ? SPEC_REVIEW_DIMENSIONS : QUALITY_REVIEW_DIMENSIONS;
+  if (!args.since) {
+    return [
+      `You are the ${phase.toUpperCase()} reviewer for a completed feature.`,
+      `The spec/requirements source is: ${args.specPath}. Read it in full.`,
+      `Fetch and review the diff: \`git diff ${args.base}...HEAD\` (also \`--name-only\` for the file list).`,
+      WORKER_PROTOCOL,
+      dims,
+      CLASSIFIER,
+      JSON_CONTRACT,
+    ].join("\n\n");
+  }
   return [
-    `You are the ${phase.toUpperCase()} reviewer for a completed feature.`,
-    `The spec/requirements source is: ${args.specPath}. Read it in full.`,
-    `Fetch and review the diff: \`git diff ${args.base}...HEAD\` (also \`--name-only\` for the file list).`,
+    `You are the ${phase.toUpperCase()} reviewer for a completed feature, continuing a review you already started.`,
+    `On your previous pass over \`git diff ${args.base}...HEAD\` you raised the findings below, and they have since been fixed and committed. Everything else in that diff you already judged acceptable — do not re-derive a verdict on it.`,
+    `Your findings from the previous pass:\n${JSON.stringify(args.priorFindings ?? [], null, 2)}`,
+    `The fix is \`git diff ${args.since}..HEAD\` — this is the only code that has changed since your last verdict. Review it, and only it, for two questions:`,
+    [
+      "1. **Resolved?** Does the fix actually resolve each finding above? A finding that was papered over (assertion weakened, test deleted, check disabled) is NOT resolved — re-raise it.",
+      "2. **Broken?** Did the fix introduce a new problem, in the changed lines or in the unchanged code they now call into?",
+      "",
+      `Read whatever files you need — the spec is at ${args.specPath} and the whole repo is available. Scope means *what you judge*, not *what you may read*.`,
+    ].join("\n"),
     WORKER_PROTOCOL,
     dims,
     CLASSIFIER,

package/flows/nax-finish/steps/context.ts

@@ -17,6 +17,13 @@ export interface FeatureResolution {
   specKind: "markdown" | "prd";
   acceptanceStatus: string;
   groups: AcceptanceGroup[];
+  /**
+   * Test-file classification regexes, as sources, from `nax features resolve`
+   * (the ADR-009 SSOT). Empty when the CLI is older than the field or could not
+   * resolve them — callers must treat empty as "cannot classify", never as
+   * "nothing is a test file".
+   */
+  testFileRegex: string[];
 }
 
 /**
@@ -30,6 +37,7 @@ export async function resolveFeature(feature: string, workdir: string): Promise<
   let parsed: {
     specSource?: { kind: "markdown" | "prd"; path: string };
     acceptance?: { status?: string; groups?: AcceptanceGroup[] };
+    testPatterns?: { regex?: string[] };
   };
   try {
     parsed = JSON.parse(res.stdout);
@@ -51,9 +59,39 @@ export async function resolveFeature(feature: string, workdir: string): Promise<
     specKind: parsed.specSource.kind,
     acceptanceStatus: parsed.acceptance?.status ?? "no-prd",
     groups: parsed.acceptance?.groups ?? [],
+    testFileRegex: parsed.testPatterns?.regex ?? [],
   };
 }
 
+/**
+ * Split paths into test and non-test, using the regexes `nax features resolve`
+ * reported.
+ *
+ * With no patterns (older nax, or a config the resolver choked on) every path is
+ * reported as non-test. That is the safe direction for the one caller: the gate
+ * loop skips its re-review only for a test-only change, so "cannot classify"
+ * must mean "review it", never "skip it".
+ *
+ * An unparseable regex source is skipped rather than thrown — a bad pattern in
+ * one config entry must not take the flow down mid-loop.
+ */
+export function partitionTestFiles(paths: string[], regexSources: string[]): { test: string[]; nonTest: string[] } {
+  const matchers: RegExp[] = [];
+  for (const src of regexSources) {
+    try {
+      matchers.push(new RegExp(src));
+    } catch {
+      // Skip — see the doc comment above.
+    }
+  }
+  const test: string[] = [];
+  const nonTest: string[] = [];
+  for (const p of paths) {
+    (matchers.some((re) => re.test(p)) ? test : nonTest).push(p);
+  }
+  return { test, nonTest };
+}
+
 export async function preflight(
   workdir: string,
   base: string,

package/flows/nax-finish/steps/git.ts

@@ -58,12 +58,35 @@ async function isDirty(repoRoot: string): Promise<boolean> {
  * A failing commit still throws: the fix is then unreviewable, and continuing
  * would silently reproduce the stale-diff bug this exists to fix.
  */
+/** Current HEAD sha, or null outside a repo / on an unborn branch. */
+async function headSha(repoRoot: string): Promise<string | null> {
+  const res = await _gitDeps.run(["git", "rev-parse", "HEAD"], { cwd: repoRoot });
+  return res.exitCode === 0 ? res.stdout.trim() || null : null;
+}
+
+/**
+ * Repo-root-relative paths touched by a commit.
+ *
+ * `--format=` suppresses the header so the output is just the file list.
+ * Failure yields `[]`, which the gate loop reads as "cannot tell what changed"
+ * and therefore reviews — see `partitionTestFiles`.
+ */
+export async function filesInCommit(repoRoot: string, sha: string): Promise<string[]> {
+  const res = await _gitDeps.run(["git", "show", "--name-only", "--format=", sha], { cwd: repoRoot });
+  if (res.exitCode !== 0) return [];
+  return res.stdout
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0);
+}
+
 export async function commitFixes(
   repoRoot: string,
   message: string,
   opts: { skipHooks?: boolean } = {},
-): Promise<{ committed: boolean }> {
-  if (!(await isDirty(repoRoot))) return { committed: false };
+): Promise<{ committed: boolean; shaBefore: string | null; shaAfter: string | null }> {
+  const shaBefore = await headSha(repoRoot);
+  if (!(await isDirty(repoRoot))) return { committed: false, shaBefore, shaAfter: shaBefore };
 
   const add = await _gitDeps.run(["git", "add", "-A"], { cwd: repoRoot });
   if (add.exitCode !== 0) {
@@ -82,7 +105,7 @@ export async function commitFixes(
       { stage: "finish-git", repoRoot },
     );
   }
-  return { committed: true };
+  return { committed: true, shaBefore, shaAfter: await headSha(repoRoot) };
 }
 
 /**