@nathapp/nax 0.76.0 → 0.77.0

package/flows/nax-finish/steps/pr-body.ts

@@ -0,0 +1,345 @@
+/**
+ * nax-finish PR title and body — pure deterministic builder, plus the loader
+ * that assembles a `FinishPrContext` from finish-audit artifacts on disk.
+ *
+ * The finish flow opens a PR via `openOrPromotePr` and used to ship a
+ * hardcoded `nax-finish: <feature>` title and a one-sentence body, throwing
+ * away every artifact the run produced on the way. This module restores that
+ * context as a deterministic markdown body — the title matches
+ * `src/plugins/builtin/auto-pr/pr-body.ts:buildTitle`, and the body is
+ * assembled by string joins over the fields in `FinishPrContext`. No model
+ * call: every section is reproducible from artifacts that exist before
+ * `open_pr` runs, and so the body stays greppable in PR history.
+ *
+ * Reimplemented here (rather than imported from `src/`) because `flows/`
+ * ships to a different runtime — `acpx flow run` runs it in acpx's own Node
+ * process where nax's `src/` and its `@/*` alias are not available.
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join } from "node:path";
+import { runArgv } from "../exec";
+import { readSpecSummary, resolveNarrative } from "../narrative";
+import { findPrTemplate } from "../pr-template";
+import type { Finding, FinishInput, FinishRound, RunFn } from "../types";
+import type { Forge } from "./forge";
+import { readRounds } from "./result";
+
+const SECONDS_PER_MINUTE = 60;
+const MS_PER_SECOND = 1000;
+
+/** Six hex + one — the abbreviated form used everywhere in PR bodies and logs. */
+const SHORT_SHA_LEN = 7;
+
+/** One row in the Stories table. */
+export interface FinishPrStory {
+  id: string;
+  title: string;
+  acCount: number;
+}
+
+/** Everything `open_pr` renders, sourced from finish-audit artifacts. */
+export interface FinishPrContext {
+  feature: string;
+  stories: FinishPrStory[];
+  outOfScope: string[];
+  acceptance?: string;
+  regression?: string;
+  gatesRan: string[];
+  diffstat?: string;
+  /** Repository PR/MR template, verbatim. Absent when none resolves. */
+  template?: string;
+  /** Resolved "What changed" prose. Absent when neither source produced text. */
+  narrative?: string;
+  rounds: FinishRound[];
+  run: {
+    durationMs?: number;
+    storiesPassed?: number;
+    storiesTotal?: number;
+  };
+}
+
+export const _prBodyDeps: {
+  run: RunFn;
+  readText: (path: string) => Promise<string | null>;
+  warn: (message: string, details: { path: string; error: unknown }) => void;
+} = {
+  run: runArgv,
+  // ENOENT is the routine case (status.json/prd.json not yet written) and must
+  // stay silent — mirrors `_qualityDeps.readText` in `steps/quality.ts`. Only a
+  // genuine I/O failure (permission denied, corrupted mount) should warn.
+  readText: async (path) => {
+    try {
+      return await readFile(path, "utf8");
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw err;
+    }
+  },
+  warn: (message, details) => process.emitWarning(message, { detail: `${details.path}: ${String(details.error)}` }),
+};
+
+interface PrdArtifact {
+  userStories?: { id: string; title: string; acceptanceCriteria?: unknown[] }[];
+  outOfScope?: string[];
+}
+
+interface StatusArtifact {
+  postRun?: { acceptance?: { status?: string }; regression?: { status?: string } };
+  durationMs?: number;
+  progress?: { passed?: number; total?: number };
+}
+
+async function readJson(path: string): Promise<unknown> {
+  let text: string | null;
+  try {
+    text = await _prBodyDeps.readText(path);
+  } catch (error) {
+    _prBodyDeps.warn("[finish-pr] Failed to read PR context artifact", { path, error });
+    return undefined;
+  }
+  if (text === null) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    _prBodyDeps.warn("[finish-pr] Failed to parse PR context artifact", { path, error });
+    return undefined;
+  }
+}
+
+function storiesFrom(prd: PrdArtifact | undefined): FinishPrStory[] {
+  if (!Array.isArray(prd?.userStories)) return [];
+  // A hand-edited or older-schema PRD can carry a story with a missing/non-string
+  // `id`/`title` — drop only that row rather than letting `escapeTableCell` throw
+  // and take down the entire PR body (caught upstream by `open_pr`'s fallback).
+  return prd.userStories
+    .filter((story) => typeof story.id === "string" && typeof story.title === "string")
+    .map((story) => ({
+      id: story.id,
+      title: story.title,
+      acCount: Array.isArray(story.acceptanceCriteria) ? story.acceptanceCriteria.length : 0,
+    }));
+}
+
+/**
+ * Run `git diff --stat <base>...HEAD` and return its stdout on success.
+ *
+ * Fail-open on every non-happy path — a non-zero exit (no commits, divergent
+ * branch, base missing), a rejected run promise (forks too slow to start), or
+ * any thrown error — returning `undefined`. The PR's Verification block is
+ * optional, and a routine empty-branch finish must not lose `open_pr` to a
+ * throw that the body can simply skip.
+ */
+async function runDiffstat(workdir: string, base: string): Promise<string | undefined> {
+  // An empty `base` would interpolate to `...HEAD`, which git resolves as
+  // `HEAD...HEAD` — exit 0, empty stdout — masking the missing-base case as
+  // "no changes" instead of skipping explicitly.
+  if (!base) return undefined;
+  try {
+    const res = await _prBodyDeps.run(["git", "diff", "--stat", `${base}...HEAD`], { cwd: workdir });
+    if (res.exitCode !== 0) return undefined;
+    return res.stdout;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve the repository's PR/MR template, fail-open.
+ *
+ * An absent template is the common case and never warns. A genuine read failure
+ * is swallowed too: the body is useful without this section, and `open_pr` must
+ * not lose a PR to a permissions error on a file most repos do not have.
+ */
+async function loadTemplate(workdir: string, forge: Forge | undefined): Promise<string | undefined> {
+  if (forge === undefined) return undefined;
+  try {
+    return (await findPrTemplate(workdir, forge, { readText: _prBodyDeps.readText })) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function loadFinishPrContext(
+  input: FinishInput,
+  args: { base: string; gatesRan: string[]; forge?: Forge; specPath?: string; narrative?: string },
+): Promise<FinishPrContext> {
+  const inputPrdPath = input.prdPath || "prd.json";
+  const prdPath = isAbsolute(inputPrdPath) ? inputPrdPath : join(input.workdir, inputPrdPath);
+  // [US-004] The audit trail (`rounds`), the diffstat, and the spec summary
+  // are independent of the PRD/status reads — fetching them in parallel keeps
+  // the loader's wall clock at max(readRounds, readJson×2, diffstat, spec).
+  const [prd, status, rounds, diffstat, template, specSummary] = (await Promise.all([
+    readJson(prdPath),
+    readJson(join(dirname(prdPath), "status.json")),
+    readRounds(input),
+    runDiffstat(input.workdir, args.base),
+    loadTemplate(input.workdir, args.forge),
+    readSpecSummary(args.specPath, _prBodyDeps.readText),
+  ])) as [
+    PrdArtifact | undefined,
+    StatusArtifact | undefined,
+    FinishRound[],
+    string | undefined,
+    string | undefined,
+    string | null,
+  ];
+  return {
+    feature: input.feature,
+    stories: storiesFrom(prd),
+    outOfScope: Array.isArray(prd?.outOfScope) ? prd.outOfScope : [],
+    acceptance: status?.postRun?.acceptance?.status,
+    regression: status?.postRun?.regression?.status,
+    gatesRan: args.gatesRan,
+    rounds,
+    diffstat,
+    template,
+    narrative: resolveNarrative(args.narrative, specSummary),
+    run: {
+      durationMs: status?.durationMs,
+      storiesPassed: status?.progress?.passed,
+      storiesTotal: status?.progress?.total,
+    },
+  };
+}
+
+/**
+ * Conventional-commit title matching `buildTitle` in
+ * `src/plugins/builtin/auto-pr/pr-body.ts`, so finish-opened and
+ * auto-PR-opened PRs read the same in a list view.
+ */
+export function buildFinishTitle(ctx: FinishPrContext): string {
+  return `feat: ${ctx.feature}`;
+}
+
+/**
+ * Escape a string for safe inclusion in a single markdown table cell.
+ *
+ * Mirrors `escapeTableCell` in `src/plugins/builtin/auto-pr/pr-body.ts`,
+ * trimmed to the cases the finish body actually needs: pipes (which break
+ * the column boundary) and newlines (which create new rows). Backslashes are
+ * escaped first so the pipe escape survives a literal backslash in a title.
+ */
+function escapeTableCell(value: string): string {
+  return value.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+function formatDuration(durationMs: number): string {
+  // `Math.max(0, NaN)` returns NaN, and `Math.floor(Infinity / 1000)` returns
+  // Infinity — both would render as `"NaNm NaNs"` / `"Infinitym Infinitys"`.
+  // A non-finite duration is a corrupted artifact (status.json is hand-editable),
+  // so fall back to zero rather than let it leak into the PR body verbatim.
+  if (!Number.isFinite(durationMs)) return "0m 00s";
+  const clampedMs = Math.max(0, Math.round(durationMs));
+  const totalSeconds = Math.floor(clampedMs / MS_PER_SECOND);
+  const minutes = Math.floor(totalSeconds / SECONDS_PER_MINUTE);
+  const seconds = totalSeconds % SECONDS_PER_MINUTE;
+  return `${minutes}m ${seconds.toString().padStart(2, "0")}s`;
+}
+
+function buildStoriesSection(stories: FinishPrStory[]): string {
+  const lines: string[] = [];
+  lines.push("## Stories");
+  lines.push("| Story | Title | ACs |");
+  lines.push("|-------|-------|-----|");
+  for (const story of stories) {
+    lines.push(`| ${escapeTableCell(story.id)} | ${escapeTableCell(story.title)} | ${story.acCount} |`);
+  }
+  return lines.join("\n");
+}
+
+function buildVerificationSection(
+  acceptance: string | undefined,
+  regression: string | undefined,
+  gatesRan: string[],
+  diffstat: string | undefined,
+): string | null {
+  const lines: string[] = ["## Verification"];
+  if (acceptance !== undefined) lines.push(`- Acceptance: ${acceptance}`);
+  if (regression !== undefined) lines.push(`- Regression: ${regression}`);
+  if (gatesRan.length > 0) lines.push(`- Gates: ${gatesRan.join(", ")}`);
+  if (diffstat !== undefined && diffstat.length > 0) lines.push(`- Diffstat:\n\n\`\`\`\n${diffstat}\n\`\`\``);
+  if (lines.length === 1) return null;
+  return lines.join("\n");
+}
+
+function buildRoundHeading(round: FinishRound): string {
+  const base = `### ${round.phase} attempt ${round.attempt}`;
+  if (!round.committed || !round.sha) return base;
+  const short = round.sha.slice(0, SHORT_SHA_LEN);
+  return `${base} (${short})`;
+}
+
+function buildRoundBlock(round: FinishRound): string {
+  const lines: string[] = [buildRoundHeading(round)];
+  if (round.findings.length === 0) {
+    lines.push("- _no findings_");
+  } else {
+    for (const finding of round.findings) lines.push(renderFinding(finding));
+  }
+  return lines.join("\n");
+}
+
+function buildRoundsSection(rounds: FinishRound[]): string | null {
+  if (rounds.length === 0) return null;
+  const blocks = rounds.map(buildRoundBlock);
+  return ["## Review rounds", ...blocks].join("\n\n");
+}
+
+function renderFinding(finding: Finding): string {
+  return `- [${finding.severity}] ${finding.title}`;
+}
+
+/**
+ * Heading and text are produced together, so "no text" cannot render a bare
+ * `## What changed` heading — the empty-heading case #1477 forbids.
+ */
+function buildNarrativeSection(narrative: string | undefined): string | null {
+  const text = narrative?.trim();
+  if (!text) return null;
+  return ["## What changed", text].join("\n\n");
+}
+
+function buildOutOfScopeSection(outOfScope: string[]): string | null {
+  if (outOfScope.length === 0) return null;
+  const lines: string[] = ["## Out of scope"];
+  for (const item of outOfScope) lines.push(`- ${item}`);
+  return lines.join("\n");
+}
+
+function buildFooter(run: FinishPrContext["run"]): string | null {
+  const { storiesPassed, storiesTotal, durationMs } = run;
+  if (storiesPassed === undefined && storiesTotal === undefined && durationMs === undefined) return null;
+  const counts =
+    storiesPassed !== undefined && storiesTotal !== undefined ? `${storiesPassed}/${storiesTotal} stories` : null;
+  const timing = durationMs !== undefined ? formatDuration(durationMs) : null;
+  const parts = [counts, timing].filter((p): p is string => p !== null);
+  if (parts.length === 0) return null;
+  return parts.join(" · ");
+}
+
+export function buildFinishBody(ctx: FinishPrContext): string {
+  const sections: string[] = [];
+
+  const narrativeSection = buildNarrativeSection(ctx.narrative);
+  if (narrativeSection !== null) sections.push(narrativeSection);
+
+  if (ctx.stories.length > 0) sections.push(buildStoriesSection(ctx.stories));
+
+  const verification = buildVerificationSection(ctx.acceptance, ctx.regression, ctx.gatesRan, ctx.diffstat);
+  if (verification !== null) sections.push(verification);
+
+  const roundsSection = buildRoundsSection(ctx.rounds);
+  if (roundsSection !== null) sections.push(roundsSection);
+
+  const outOfScopeSection = buildOutOfScopeSection(ctx.outOfScope);
+  if (outOfScopeSection !== null) sections.push(outOfScopeSection);
+
+  const footer = buildFooter(ctx.run);
+  if (footer !== null) sections.push(footer);
+
+  // Appended last and verbatim: `gh` / `glab` suppress the repo's own template
+  // whenever `--body` / `--description` is passed, so it has to be re-embedded.
+  if (ctx.template !== undefined && ctx.template.trim().length > 0) sections.push(ctx.template.trim());
+
+  return sections.join("\n\n");
+}

package/flows/nax-finish/steps/pr-narrative.ts

@@ -0,0 +1,43 @@
+/**
+ * `amend_body` — rewrite the PR body once the narrative node has produced prose.
+ *
+ * Runs *after* the PR is open and its result file written, which is the whole
+ * point: acpx has no error edge, so an acp node placed before `open_pr` could
+ * kill the flow and cost the PR. Here the worst case is a body missing one
+ * section.
+ *
+ * Every failure is warned and swallowed for the same reason — a throw would
+ * fail a flow whose real work already succeeded.
+ */
+import { gateOutputs, inputOf, loadCtxOf, narrativeOf } from "../flow-ctx";
+import { detectForge } from "./forge";
+import { updatePrBody } from "./pr";
+import { _prBodyDeps, buildFinishBody, buildFinishTitle, loadFinishPrContext } from "./pr-body";
+
+export async function amendPrBodyNode(ctx: {
+  input: unknown;
+  outputs: unknown;
+}): Promise<{ route: "done"; amended: boolean }> {
+  const narrative = narrativeOf(ctx);
+  // Nothing to add: the body already in place is correct, and rewriting it
+  // identically would spend a forge call to change nothing.
+  if (!narrative) return { route: "done", amended: false };
+
+  const i = inputOf(ctx);
+  const loadCtx = loadCtxOf(ctx);
+  try {
+    const forge = await detectForge(_prBodyDeps.run, i.workdir, "finish-pr");
+    const prCtx = await loadFinishPrContext(i, {
+      base: loadCtx.base ?? "",
+      gatesRan: gateOutputs(ctx).ran ?? [],
+      forge,
+      specPath: loadCtx.specPath,
+      narrative,
+    });
+    await updatePrBody(forge, i.workdir, i.branch, buildFinishTitle(prCtx), buildFinishBody(prCtx));
+    return { route: "done", amended: true };
+  } catch (error) {
+    _prBodyDeps.warn("[finish-pr] Failed to amend the PR body with the narrative", { path: i.branch, error });
+    return { route: "done", amended: false };
+  }
+}

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

@@ -1,9 +1,19 @@
 import { FinishError } from "../errors";
-import { runArgv } from "../exec";
 import type { RunFn } from "../types";
 import { type Forge, detectForge, extractUrl, viewArgv } from "./forge";
+import { _prBodyDeps, loadFinishPrContext } from "./pr-body";
 
-export const _prDeps: { run: RunFn } = { run: runArgv };
+// `loadFinishPrContext` moved to `./pr-body` (the spec's stated module
+// boundary); re-exported here so consumers importing from `./pr` (or the
+// `steps` barrel, which re-exports `./pr`) keep working.
+export { loadFinishPrContext };
+
+// `_prDeps` is deliberately the *same object* as `./pr-body`'s `_prBodyDeps`,
+// not a copy — this module's `run` calls (forge CLI) and pr-body's
+// `readText`/`warn`/diffstat `run` calls share one injectable seam, so a
+// single test stub controls both. Typed to `{ run: RunFn }` here because
+// that's the only member this module actually calls.
+export const _prDeps: { run: RunFn } = _prBodyDeps;
 
 /**
  * Parse `gh pr view --json isDraft,url` / `glab mr view --output json` stdout.
@@ -33,8 +43,12 @@ export async function openOrPromotePr(
   branch: string,
   title: string,
   body: string,
+  // Optional so a caller whose own `detectForge` threw still gets the previous
+  // behaviour. Passing it in is what stops the body and the create-command from
+  // disagreeing about the forge when both would otherwise detect separately.
+  knownForge?: Forge,
 ): Promise<{ status: "opened" | "promoted" | "already-ready"; url?: string }> {
-  const forge = await detectForge(_prDeps.run, repoRoot, "finish-pr");
+  const forge = knownForge ?? (await detectForge(_prDeps.run, repoRoot, "finish-pr"));
   const view = await _prDeps.run(viewArgv(forge, branch, "isDraft,url"), { cwd: repoRoot });
 
   if (view.exitCode !== 0) {
@@ -64,8 +78,39 @@ export async function openOrPromotePr(
         { stage: "finish-pr", branch },
       );
     }
+    await updatePrBody(forge, repoRoot, branch, title, body);
     return { status: "promoted", url };
   }
 
+  await updatePrBody(forge, repoRoot, branch, title, body);
   return { status: "already-ready", url };
 }
+
+/**
+ * Write the finish title/body onto an already-open PR/MR.
+ *
+ * Non-fatal by design: this runs after the PR exists, so a failed metadata
+ * write must not throw away that state — the caller's returned status/url
+ * stays valid either way. Exported because `amend_body` calls it after the
+ * narrative node produces prose.
+ */
+export async function updatePrBody(
+  forge: Forge,
+  repoRoot: string,
+  branch: string,
+  title: string,
+  body: string,
+): Promise<void> {
+  const editCmd =
+    forge === "github"
+      ? ["gh", "pr", "edit", branch, "--title", title, "--body", body]
+      : ["glab", "mr", "update", branch, "--title", title, "--description", body];
+  try {
+    const res = await _prDeps.run(editCmd, { cwd: repoRoot });
+    if (res.exitCode !== 0) {
+      _prBodyDeps.warn("[finish-pr] Failed to write PR title/body", { path: branch, error: res.stderr.trim() });
+    }
+  } catch (error) {
+    _prBodyDeps.warn("[finish-pr] Failed to write PR title/body", { path: branch, error });
+  }
+}

package/flows/nax-finish/types.ts

@@ -16,13 +16,21 @@ export interface Finding {
 }
 export interface ReviewVerdict {
   /**
-   * `clean` is not a model-produced route — the review nodes' `parse` rewrites
-   * `proceed` with zero findings to `clean` so the graph can skip the fix node
-   * entirely instead of prompting an agent to "apply fixes" for nothing.
+   * Neither `clean` nor `reprompt` is a model-produced route.
+   *
+   * `clean` — `parse` rewrites `proceed` with zero findings, so the graph can
+   * skip the fix node instead of prompting an agent to "apply fixes" for nothing.
+   *
+   * `reprompt` — `parse` could not read JSON out of the reply at all. Returning
+   * this rather than throwing is deliberate: a throw fails the acp node and kills
+   * the whole flow with no result file, bypassing the `escalate` sink that exists
+   * to report exactly this kind of dead end.
    */
-  route: "proceed" | "escalate" | "clean";
+  route: "proceed" | "escalate" | "clean" | "reprompt";
   findings: Finding[];
   escalationReason?: string;
+  /** Bounded tail of an unparseable reply; set only when `route` is `reprompt`. */
+  raw?: string;
 }
 /** Wall-clock budgets, forwarded from `finish.autoFlow.timeouts` by the plugin. */
 export interface FinishTimeouts {
@@ -53,6 +61,13 @@ export interface FinishRound {
   findings: Finding[];
   /** Gate commands that were red this round (gate phase). */
   failing?: string[];
+  /**
+   * `HEAD` SHA after this round's commit (set only when `committed`); absent
+   * on no-op rounds so a reader can distinguish "no commit" from "record lost".
+   * Lets "Fixed in `<sha>`" be reconstructed from the audit trail alone, rather
+   * than by matching round timestamps against `git log`.
+   */
+  sha?: string;
 }
 
 export interface FinishInput {

package/flows/nax-finish/verdict.ts

@@ -0,0 +1,159 @@
+/**
+ * Turning a reviewer's reply into a deterministic route.
+ *
+ * Lives outside `nax-finish.flow.ts` for two reasons: the flow file sits within
+ * a few lines of the 600-line hard limit, and this is a cohesive unit —
+ * `routeReview` consumes exactly what the parsers produce.
+ *
+ * The central invariant: **no parser here ever throws.** acpx has no node-level
+ * retry and no error edge (`AcpNodeDefinition` offers only `prompt`/`parse`;
+ * `FlowEdge` is only `to` or `switch`), so a throw inside `parse` fails the node
+ * and fails the run — exit 1, no result file, no notification, bypassing the
+ * `escalate` node that exists to report precisely this.
+ */
+import { extractJsonObject } from "acpx/flows";
+import { type OutputsCtx, type StepsCtx, fixAttemptCount } from "./flow-ctx";
+import type { Finding, ReviewVerdict } from "./types";
+
+/**
+ * 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.
+ *
+ * Lives here rather than in the flow file because `routeReview` needs it; the
+ * flow imports it back for the acceptance node and the two `quality_gates` caps.
+ */
+export const MAX_FIX_ATTEMPTS = 3;
+
+/**
+ * Unparseable reviews tolerated per phase before escalating.
+ *
+ * One. A reviewer that ignores the JSON contract twice in a row is not going to
+ * comply on a third ask, and each review is the most expensive node in the flow
+ * (128s and ~4.2M tokens on the run that motivated this).
+ */
+export const MAX_REPROMPT_ATTEMPTS = 1;
+
+/** How much of an unparseable reply to carry forward — it lands in a PR comment and a Telegram message. */
+export const RAW_TAIL_LIMIT = 500;
+
+function tail(text: string): string {
+  const t = text.trim();
+  return t.length <= RAW_TAIL_LIMIT ? t : `…${t.slice(-(RAW_TAIL_LIMIT - 1))}`;
+}
+
+/** Shared happy path: read the object, normalise findings, rewrite empty `proceed` to `clean`. */
+function parseVerdictJson(text: string): ReviewVerdict {
+  const raw = extractJsonObject(text) as Partial<ReviewVerdict>;
+  const findings: Finding[] = Array.isArray(raw.findings) ? raw.findings : [];
+  const route = raw.route === "escalate" ? "escalate" : findings.length === 0 ? "clean" : "proceed";
+  return { route, findings, escalationReason: raw.escalationReason };
+}
+
+/**
+ * Parser for `review_spec` / `review_quality`, whose JSON is load-bearing —
+ * `findingsOf` reads it and the fix loop is driven by it. An unreadable reply
+ * routes to `reprompt` so `routeReview` can ask once more before escalating.
+ */
+export function parseReviewVerdict(text: string): ReviewVerdict {
+  try {
+    return parseVerdictJson(text);
+  } catch {
+    return { route: "reprompt", findings: [], raw: tail(text) };
+  }
+}
+
+/**
+ * Parser for the four `fix_*` nodes, whose parsed value nothing reads —
+ * `findingsOf` only ever looks at `review_spec`/`review_quality`, and
+ * `commitFixNode` decides from git rather than from the model's word.
+ *
+ * Never routes `reprompt`: the fix nodes have unconditional edges
+ * (`fix_spec → commit_spec`), so a reprompt route would have nowhere to go.
+ */
+export function parseFixVerdict(text: string): ReviewVerdict {
+  try {
+    return parseVerdictJson(text);
+  } catch {
+    return { route: "proceed", findings: [] };
+  }
+}
+
+/**
+ * How many times this phase's review already came back unparseable.
+ *
+ * Counts step *outputs*, not step ids: `commit_quality → review_quality` and
+ * `commit_gate → review_quality` are legitimate re-entries in the normal fix
+ * loop, so counting bare `review_<phase>` steps would escalate a healthy run.
+ *
+ * This is observable only because `parseReviewVerdict` returns rather than
+ * throws — a returned verdict makes acpx record the step as successful with
+ * this output. A throw would record it `failed`, with nothing to count.
+ *
+ * SELF-INCLUSIVE, not self-exclusive: acpx's runtime calls
+ * `recordFlowStepOutcome(runDir, state, step)` (acpx/src/flows/runtime.ts:262),
+ * which pushes the just-finished step onto `state.steps`
+ * (acpx/src/flows/runtime.ts:499), BEFORE `resolveNextNode` runs and before the
+ * following node (`route_<phase>`) executes. So by the time `routeReview` reads
+ * `ctx.state.steps` here, the current round's own `review_<phase>` step is
+ * already included. On the very first unparseable reply this already returns
+ * 1, not 0. `routeReview`'s comparison against `MAX_REPROMPT_ATTEMPTS` MUST
+ * stay `<=` (not `<`) for that reason — see routeReview below.
+ */
+export function repromptCount(ctx: StepsCtx, phase: "spec" | "quality"): number {
+  return (ctx.state.steps ?? []).filter(
+    (s) => s.nodeId === `review_${phase}` && (s.output as ReviewVerdict | undefined)?.route === "reprompt",
+  ).length;
+}
+
+/**
+ * Turn a reviewer verdict into a deterministic route.
+ *
+ * `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.
+ *
+ * The `reprompt` branch MUST come first. A reprompt verdict carries zero
+ * findings, so checking `findings.length === 0` ahead of it would route an
+ * unreadable review to `clean`, and the flow would open a PR having reviewed
+ * nothing. That silent false green is worse than the crash this replaces.
+ */
+export function routeReview(
+  ctx: OutputsCtx & StepsCtx,
+  phase: "spec" | "quality",
+): { route: string; escalationReason?: string; findings: Finding[] } {
+  const verdict = (ctx.outputs as Record<string, ReviewVerdict | undefined>)[`review_${phase}`];
+  const findings = verdict?.findings ?? [];
+  if (verdict?.route === "reprompt") {
+    // `attempts` is self-inclusive (see repromptCount) — it already counts this
+    // round's failure, so `<=` (not `<`) is what makes MAX_REPROMPT_ATTEMPTS=1
+    // tolerate exactly one retry before escalating.
+    const attempts = repromptCount(ctx, phase);
+    if (attempts <= MAX_REPROMPT_ATTEMPTS) return { route: "reprompt", findings };
+    return {
+      route: "escalate",
+      escalationReason:
+        `${phase} reviewer returned unparseable output after ${attempts} attempts. ` +
+        `Last reply: ${verdict.raw ?? "(empty)"}`,
+      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 };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.76.0",
+  "version": "0.77.0",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {