@nathapp/nax 0.75.6 → 0.77.0

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

@@ -31,17 +31,35 @@
  *   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 { defineFlow } from "acpx/flows";
+import { buildFixCommitMessage } from "./commit-message";
+import { findingsOf, fixAttemptCount, gateOutputs, incrementalSince, inputOf, loadCtxOf } from "./flow-ctx";
+import { narrativePrompt, parseNarrative } from "./narrative";
 import { buildReviewPrompt, fixPrompt } from "./review-prompts";
 import {
   _contextDeps,
+  amendPrBodyNode,
+  appendRound,
   buildEscalationComment,
   commitAndPush,
   commitFixes,
   detectBaseBranch,
+  detectForge,
+  filesInCommit,
+  loadFinishPrContext,
   loadQualityCommands,
   openOrPromotePr,
+  partitionTestFiles,
   postEscalation,
   preflight,
   resolveFeature,
@@ -49,34 +67,28 @@ import {
   runQualityGates,
   writeResult,
 } from "./steps";
-import type { AcceptanceGroup, FinishInput, FinishResult, ReviewVerdict } from "./types";
-
-const inputOf = (ctx: { input: unknown }) => ctx.input as FinishInput;
+import type { Forge } from "./steps/forge";
+import { _prBodyDeps, buildFinishBody, buildFinishTitle } from "./steps/pr-body";
+import type { FinishInput, FinishPhase, FinishResult, ReviewVerdict } from "./types";
+import { MAX_FIX_ATTEMPTS, parseFixVerdict, parseReviewVerdict, repromptCount, routeReview } from "./verdict";
 
 /**
- * Cap on fix-and-reverify iterations, per phase, before escalating instead of
- * looping forever. acpx's flow engine has no built-in cycle guard, so without
- * this cap a stubborn failure (LLM can't fix it, or fixes something else each
- * time) hangs `acpx flow run` — and the post-run plugin awaits that subprocess.
+ * Disabled only on an explicit "0". An unset variable means enabled, so a flow
+ * invoked directly by `acpx flow run` — outside the plugin that sets the env —
+ * still writes the narrative.
  */
-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;
-}
+const NARRATIVE_ENABLED = process.env.NAX_FINISH_NARRATIVE !== "0";
 
-function loadCtxOf(ctx: { outputs: unknown }): LoadCtxOutput {
-  return ((ctx.outputs as Record<string, LoadCtxOutput | undefined>).load_ctx ?? {}) as LoadCtxOutput;
-}
+/**
+ * Injectable seam for the `open_pr` node's title/body assembly — tests stub
+ * these to control the fallback-vs-built-metadata paths without a real PRD or
+ * git checkout.
+ */
+export const _openPrDeps = {
+  loadFinishPrContext,
+  buildFinishTitle,
+  buildFinishBody,
+};
 
 /**
  * Re-run the acceptance gate, routing on the shared fix-cap rules.
@@ -132,35 +144,34 @@ async function acceptanceGateNode(ctx: {
 }
 
 /**
- * Turn a reviewer verdict into a deterministic route.
+ * Route for `commit_gate`, whose successor depends on what the fix touched.
  *
- * `clean` (no findings) skips the fix node entirely — prompting an agent to
- * "apply the recommended fixes" for an empty finding list burns a turn and
- * invites unrequested edits.
+ * - `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.
  */
-function routeReview(
-  ctx: { outputs: unknown; state: { steps: { nodeId: string }[] } },
-  phase: "spec" | "quality",
-): { route: string; escalationReason?: string; findings: ReviewVerdict["findings"] } {
-  const verdict = (ctx.outputs as Record<string, ReviewVerdict | undefined>)[`review_${phase}`];
-  const findings = verdict?.findings ?? [];
-  if (verdict?.route === "escalate") {
-    return {
-      route: "escalate",
-      escalationReason: verdict.escalationReason ?? `${phase} review raised a finding needing human judgment`,
-      findings,
-    };
-  }
-  if (findings.length === 0) return { route: "clean", findings };
-  const attempts = fixAttemptCount(ctx, `fix_${phase}`);
-  if (attempts >= MAX_FIX_ATTEMPTS) {
-    return {
-      route: "escalate",
-      escalationReason: `${phase} review still reporting ${findings.length} finding(s) after ${attempts} fix attempts.`,
-      findings,
-    };
-  }
-  return { route: "fix", findings };
+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";
 }
 
 /**
@@ -169,28 +180,57 @@ 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. `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 ?? [] } : {}),
+        // Carry `shaAfter` onto committed rounds only: a no-op round has no
+        // commit, so no SHA to record — keeping the field absent (rather than
+        // null/undefined) lets the result-file reader distinguish "no commit"
+        // from "record lost".
+        ...(committed && shaAfter ? { sha: shaAfter } : {}),
+      });
+      // 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 };
     },
   };
 }
 
-/** Normalise a reviewer's JSON, rewriting a findings-free `proceed` to `clean`. */
-function parseVerdict(text: string): ReviewVerdict {
-  const raw = extractJsonObject(text) as Partial<ReviewVerdict>;
-  const findings = Array.isArray(raw.findings) ? raw.findings : [];
-  const route = raw.route === "escalate" ? "escalate" : findings.length === 0 ? "clean" : "proceed";
-  return { route, findings, escalationReason: raw.escalationReason };
-}
-
 export default defineFlow({
   name: "nax-finish",
   permissions: {
@@ -212,6 +252,7 @@ export default defineFlow({
           specPath: resolution.specPath,
           acceptanceStatus: resolution.acceptanceStatus,
           groups: resolution.groups,
+          testFileRegex: resolution.testFileRegex,
           commitsAhead: pf.commitsAhead,
           route: pf.route,
         };
@@ -224,7 +265,7 @@ export default defineFlow({
     fix_acceptance: {
       nodeType: "acp",
       prompt: (ctx) => fixPrompt("acceptance", ctx),
-      parse: parseVerdict,
+      parse: parseFixVerdict,
     },
     commit_acceptance: commitFixNode("acceptance"),
     review_spec: {
@@ -233,9 +274,15 @@ 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"),
+          retry: repromptCount(ctx, "spec") > 0,
+        });
       },
-      parse: parseVerdict,
+      parse: parseReviewVerdict,
     },
     route_spec: {
       nodeType: "compute",
@@ -244,7 +291,7 @@ export default defineFlow({
     fix_spec: {
       nodeType: "acp",
       prompt: (ctx) => fixPrompt("spec", ctx),
-      parse: parseVerdict,
+      parse: parseFixVerdict,
     },
     commit_spec: commitFixNode("spec"),
     review_quality: {
@@ -253,9 +300,15 @@ 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"),
+          retry: repromptCount(ctx, "quality") > 0,
+        });
       },
-      parse: parseVerdict,
+      parse: parseReviewVerdict,
     },
     route_quality: {
       nodeType: "compute",
@@ -264,13 +317,13 @@ export default defineFlow({
     fix_quality: {
       nodeType: "acp",
       prompt: (ctx) => fixPrompt("quality", ctx),
-      parse: parseVerdict,
+      parse: parseFixVerdict,
     },
     commit_quality: commitFixNode("quality"),
     fix_gate: {
       nodeType: "acp",
       prompt: (ctx) => fixPrompt("gate", ctx),
-      parse: parseVerdict,
+      parse: parseFixVerdict,
     },
     commit_gate: commitFixNode("gate"),
     quality_gates: {
@@ -349,23 +402,65 @@ export default defineFlow({
       nodeType: "action",
       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" });
+        const loadCtx = loadCtxOf(ctx);
+        if (loadCtx.route === "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
         // opened from a remote branch missing all of them.
         const sync = await commitAndPush(i.workdir, i.branch, `fix(${i.feature}): nax-finish automated fixes`);
-        const r = await openOrPromotePr(
-          i.workdir,
-          i.branch,
-          `nax-finish: ${i.feature}`,
-          `Automated finish of \`${i.feature}\`.`,
-        );
-        await writeResult(i.workdir, { feature: i.feature, status: r.status, url: r.url });
-        return { route: "done", committed: sync.committed, ...r };
+
+        const fallbackTitle = `nax-finish: ${i.feature}`;
+        const fallbackBody = `Automated finish of \`${i.feature}\`.`;
+        let title = fallbackTitle;
+        let body = fallbackBody;
+        // Detected once, here, and handed to both the body builder (which needs
+        // it for the repo template) and the opener. Detecting in both would let
+        // them disagree. On a throw it stays undefined and `openOrPromotePr`
+        // detects for itself, exactly as it did before.
+        let forge: Forge | undefined;
+        try {
+          forge = await detectForge(_prBodyDeps.run, i.workdir, "finish-pr");
+          const prCtx = await _openPrDeps.loadFinishPrContext(i, {
+            base: loadCtx.base ?? "",
+            gatesRan: gateOutputs(ctx).ran ?? [],
+            forge,
+            specPath: loadCtx.specPath,
+          });
+          title = _openPrDeps.buildFinishTitle(prCtx);
+          body = _openPrDeps.buildFinishBody(prCtx);
+        } catch (error) {
+          _prBodyDeps.warn("[finish-pr] Falling back to default PR title/body", { path: i.prdPath, error });
+          title = fallbackTitle;
+          body = fallbackBody;
+        }
+
+        const r = await openOrPromotePr(i.workdir, i.branch, title, body, forge);
+        await writeResult(i, { feature: i.feature, status: r.status, url: r.url });
+        // The PR now exists with the mechanical narrative already in place.
+        // Anything the narrative node does from here is an improvement on a
+        // body that is already correct.
+        return { route: NARRATIVE_ENABLED ? "narrate" : "done", committed: sync.committed, ...r };
       },
     },
+    narrative: {
+      nodeType: "acp",
+      session: { isolated: true },
+      profile: process.env.NAX_FINISH_NARRATIVE_PROFILE || undefined,
+      prompt: narrativePrompt,
+      parse: parseNarrative,
+    },
+    amend_body: {
+      nodeType: "action",
+      run: amendPrBodyNode,
+    },
+    // Inert terminal. acpx switch cases must name a real node, so the `done`
+    // route out of open_pr needs somewhere to land.
+    finish_done: {
+      nodeType: "compute",
+      run: () => ({ route: "done" }),
+    },
     escalate: {
       nodeType: "action",
       async run(ctx) {
@@ -409,7 +504,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 +519,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 };
       },
@@ -444,7 +539,10 @@ export default defineFlow({
     { from: "review_spec", to: "route_spec" },
     {
       from: "route_spec",
-      switch: { on: "$.route", cases: { clean: "review_quality", fix: "fix_spec", escalate: "escalate" } },
+      switch: {
+        on: "$.route",
+        cases: { clean: "review_quality", fix: "fix_spec", escalate: "escalate", reprompt: "review_spec" },
+      },
     },
     // Spec fixes re-run the acceptance gate first (they can break it), and the
     // acceptance node's `proceed` edge leads back into review_spec for re-review.
@@ -453,7 +551,10 @@ export default defineFlow({
     { from: "review_quality", to: "route_quality" },
     {
       from: "route_quality",
-      switch: { on: "$.route", cases: { clean: "quality_gates", fix: "fix_quality", escalate: "escalate" } },
+      switch: {
+        on: "$.route",
+        cases: { clean: "quality_gates", fix: "fix_quality", escalate: "escalate", reprompt: "review_quality" },
+      },
     },
     // Quality fixes are re-reviewed by the same lens; the repo-root gates that
     // follow catch anything the fix broke mechanically.
@@ -464,6 +565,28 @@ 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" },
+      },
+    },
+    // The narrative runs only once the PR exists. acpx has no error edge, so an
+    // acp node before `open_pr` would be able to fail the flow and cost the PR.
+    { from: "open_pr", switch: { on: "$.route", cases: { narrate: "narrative", done: "finish_done" } } },
+    { from: "narrative", to: "amend_body" },
   ],
 });

package/flows/nax-finish/pr-template.ts

@@ -0,0 +1,56 @@
+/**
+ * Repository PR/MR template discovery, ported from
+ * `src/plugins/builtin/auto-pr/template.ts`.
+ *
+ * Ported rather than imported: `flows/` is loaded by acpx in its own Node
+ * process, where nax's `src/` and its `@/*` alias do not exist. This matches
+ * the convention already in this directory — `errors.ts`, `exec.ts`, `types.ts`
+ * and the PR body builder are all flow-local re-implementations.
+ *
+ * The duplication is stable: these candidate paths are an external convention
+ * set by GitHub and GitLab, not internal logic that drifts with the codebase.
+ *
+ * Why preserve-not-fill: passing `--body` / `--description` to `gh` / `glab`
+ * suppresses the repo's default template, so it must be read and re-embedded.
+ */
+import { join } from "node:path";
+import type { Forge } from "./steps/forge";
+
+/**
+ * Candidate template paths for GitHub, in priority order.
+ * Multi-template directories (`PULL_REQUEST_TEMPLATE/`) are intentionally
+ * skipped because they are ambiguous unattended.
+ */
+const GITHUB_TEMPLATE_PATHS: readonly string[] = [
+  ".github/PULL_REQUEST_TEMPLATE.md",
+  ".github/pull_request_template.md",
+  "PULL_REQUEST_TEMPLATE.md",
+  "docs/PULL_REQUEST_TEMPLATE.md",
+] as const;
+
+/** Preferred single-template location for GitLab. */
+const GITLAB_DEFAULT_TEMPLATE_PATH = ".gitlab/merge_request_templates/Default.md";
+
+/** Only `readText` is consulted, so any caller with a file reader can supply it. */
+export interface TemplateDeps {
+  readText: (path: string) => Promise<string | null>;
+}
+
+async function firstExisting(workdir: string, deps: TemplateDeps, paths: readonly string[]): Promise<string | null> {
+  for (const relPath of paths) {
+    const content = await deps.readText(join(workdir, relPath));
+    if (content !== null) return content;
+  }
+  return null;
+}
+
+/**
+ * Locate the PR/MR template for the current repository.
+ *
+ * @returns Template text verbatim, or `null` when none resolves — which is the
+ *          common case and never an error.
+ */
+export async function findPrTemplate(workdir: string, forge: Forge, deps: TemplateDeps): Promise<string | null> {
+  if (forge === "github") return firstExisting(workdir, deps, GITHUB_TEMPLATE_PATHS);
+  return firstExisting(workdir, deps, [GITLAB_DEFAULT_TEMPLATE_PATH]);
+}

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,68 @@ const JSON_CONTRACT = [
   "}",
 ].join("\n");
 
-export function buildReviewPrompt(phase: "spec" | "quality", args: { base: string; specPath: string }): string {
+/**
+ * Prepended when a previous attempt at this review returned something that was
+ * not JSON. Lead position, not appended: the failure mode is a model that
+ * narrates its findings and forgets the contract at the end of a long turn.
+ */
+const RETRY_NOTICE = [
+  "IMPORTANT — your previous reply could not be parsed as JSON, so it was discarded entirely.",
+  "Do not narrate your findings in prose. Do not describe what you reported.",
+  "Your entire reply must be the JSON object described at the end of this prompt: first char `{`, last char `}`.",
+].join("\n");
+
+/**
+ * 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[];
+    retry?: boolean;
+  },
+): string {
   const dims = phase === "spec" ? SPEC_REVIEW_DIMENSIONS : QUALITY_REVIEW_DIMENSIONS;
+  const lead = args.retry ? [RETRY_NOTICE] : [];
+  if (!args.since) {
+    return [
+      ...lead,
+      `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).`,
+    ...lead,
+    `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,