@nathapp/nax 0.75.6 → 0.77.0

package/flows/nax-finish/types.ts

@@ -16,24 +16,74 @@ 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 {
   acceptanceMs?: number;
   gateMs?: number;
 }
+/** The four fix-and-reverify loops, in graph order. */
+export type FinishPhase = "acceptance" | "spec" | "quality" | "gate";
+
+/**
+ * One completed fix round, appended to the audit trail as it happens.
+ *
+ * Rounds are appended at `commit_<phase>` as they happen rather than
+ * reconstructed by a terminal node from `ctx.state.steps` (which does retain
+ * every step's output). Appending live is what makes the trail survive a flow
+ * that is killed or times out: no terminal node runs on those paths, and a
+ * finish that died mid-loop is exactly when the record of what it already
+ * changed on the branch matters most.
+ */
+export interface FinishRound {
+  ts: string;
+  phase: FinishPhase;
+  /** 1-based; the Nth time this phase's fix node has run. */
+  attempt: number;
+  /** True when the fix produced a commit; false when it changed nothing. */
+  committed: boolean;
+  /** Reviewer findings this round set out to fix (spec/quality phases). */
+  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 {
   feature: string;
   workdir: string;
   branch: string;
   prdPath: string;
+  /**
+   * Directory for this feature's finish-audit artifacts, e.g.
+   * `~/.nax/<project>/finish-audit/<feature>`. Supplied by the plugin, which
+   * owns nax's path SSOT (`src/runtime/paths.ts`) that this module may not
+   * import. Absent → the flow falls back to a repo-local directory.
+   */
+  auditDir?: string;
+  /** Run id, used to name this run's audit files. Absent → "run". */
+  runId?: string;
   /**
    * True only when Telegram escalation is both enabled *and* credentialed, as
    * determined by the plugin. When true the flow skips the PR/MR comment
@@ -62,6 +112,13 @@ export interface FinishResult {
    * rather than lost.
    */
   deliveryError?: string;
+  /**
+   * Every fix round the flow ran, on *all* terminal statuses — not just
+   * escalations. A successful finish that took four rounds to get there is the
+   * case worth auditing (it says the run's own review gates missed four
+   * defects), and it was previously the one case that recorded nothing.
+   */
+  rounds?: FinishRound[];
 }
 export interface RunResult {
   exitCode: number;

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.75.6",
+  "version": "0.77.0",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {