@nathapp/nax 0.80.0 → 0.80.1

package/flows/nax-finish/steps/review-audit.ts

@@ -0,0 +1,91 @@
+/**
+ * Checking that a review discharged its obligations before its verdict counts.
+ *
+ * `WORKER_PROTOCOL` has always told the reviewer to enumerate the external
+ * touchpoints and open their definitions, and both dimension references have
+ * always required a per-item enumeration. Neither was checkable: `routeReview`
+ * saw only a route and a finding list, so a reviewer that read the diff and
+ * nothing else was indistinguishable from one that did the work — and on the run
+ * behind #1614 that is exactly what happened, at 86 seconds for 3,716 changed
+ * lines.
+ *
+ * The disk check is what makes this a gate rather than a ritual. It proves the
+ * paths are real, not that they were read: a reviewer can still list files it
+ * only globbed. That raises the cost of faking the list without eliminating it,
+ * which is the honest ceiling for a check that costs one `stat` per line.
+ *
+ * A verdict from the legacy JSON parsing tier carries no `saw*` fields (they are
+ * optional), so it always reports both gaps and is sent back for one re-review
+ * under the new prompt. That is intentional, not a bug: the safe direction is
+ * an extra review, never a false approval, and the retry self-corrects because
+ * the new prompt contract produces a verdict the gate can actually check.
+ *
+ * `node:fs` — not `Bun.file` — because `flows/` runs inside acpx's Node process.
+ *
+ * Both `touchpoint.path` and a disposition's `evidence` come from the
+ * reviewer/fixer's reply text — untrusted the same way any parsed LLM output
+ * is. `exists()` confines its resolved path under `workdir` before stat-ing
+ * it, so a `../`-laden path can never be used to probe existence outside the
+ * repo; a path that escapes reads as "does not exist," which is the correct
+ * verdict anyway since a legitimate touchpoint is always inside it.
+ */
+import { stat } from "node:fs/promises";
+import * as path from "node:path";
+import type { FindingDisposition, ReviewVerdict } from "../types";
+
+/** Paths stat-ed per review. A reviewer listing more than this is not the failure mode. */
+const MAX_CHECKED = 20;
+
+async function exists(workdir: string, rel: string): Promise<boolean> {
+  const root = path.resolve(workdir);
+  const resolved = path.resolve(root, rel);
+  if (resolved !== root && !resolved.startsWith(root + path.sep)) return false;
+  try {
+    await stat(resolved);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * What this review failed to do. Empty means it may be routed on.
+ *
+ * Only ever called for a verdict that already parsed; an unreadable reply is the
+ * `reprompt` path's business and is handled before this runs.
+ */
+export async function auditGaps(verdict: ReviewVerdict, workdir: string): Promise<string[]> {
+  const gaps: string[] = [];
+  const touchpoints = verdict.touchpoints ?? [];
+  if (!verdict.sawTouchpointsSection || touchpoints.length === 0) {
+    gaps.push("no `## TOUCHPOINTS` section: list every external definition you opened, or `- none — <justification>`");
+  } else if (!touchpoints.some((t) => t.path === "none")) {
+    const checked = touchpoints.slice(0, MAX_CHECKED);
+    const found = await Promise.all(checked.map((t) => exists(workdir, t.path)));
+    if (!found.some(Boolean)) {
+      gaps.push(
+        `touchpoint path does not exist in the repo (checked: ${checked
+          .map((t) => t.path)
+          .join(", ")}) — list files you actually opened`,
+      );
+    }
+  }
+  if (!verdict.sawWalkSection || (verdict.walk ?? []).length === 0) {
+    gaps.push("no `## WALK` section: the per-AC (spec) or per-function (quality) enumeration is required");
+  }
+  return gaps;
+}
+
+/** Mark any rejection whose cited `file:line` does not resolve in the repo. */
+export async function validateDispositions(
+  workdir: string,
+  dispositions: FindingDisposition[],
+): Promise<FindingDisposition[]> {
+  return Promise.all(
+    dispositions.map(async (d) => {
+      if (d.disposition !== "rejected" || !d.evidence) return d;
+      const file = d.evidence.split(":")[0];
+      return (await exists(workdir, file)) ? d : { ...d, evidenceMissing: true };
+    }),
+  );
+}

package/flows/nax-finish/steps/review-round.ts

@@ -18,15 +18,17 @@
  */
 import { inputOf } from "../flow-ctx";
 import type { OutputsCtx, StepsCtx } from "../flow-ctx";
-import type { Finding, FinishRoundOutcome } from "../types";
-import { routeReview } from "../verdict";
+import type { Finding, FinishRoundOutcome, ReviewVerdict } from "../types";
+import { MAX_INCOMPLETE_ATTEMPTS, routeReview } from "../verdict";
 import { appendRound } from "./result";
+import { auditGaps } from "./review-audit";
 
 /** Route → what to call the round. `fix` is absent by construction — see below. */
 const OUTCOME_BY_ROUTE: Record<string, FinishRoundOutcome> = {
   clean: "passed",
   reprompt: "unparseable",
   escalate: "escalated",
+  incomplete: "incomplete",
 };
 
 /**
@@ -42,6 +44,20 @@ function reviewAttemptCount(ctx: StepsCtx, phase: "spec" | "quality"): number {
   return (ctx.state.steps ?? []).filter((s) => s.nodeId === `review_${phase}`).length;
 }
 
+/**
+ * How many previous rounds of this phase were sent back as incomplete.
+ *
+ * NOT self-inclusive, unlike `repromptCount` — that one counts `review_<phase>`
+ * steps, which acpx has already recorded by the time `route_<phase>` runs, while
+ * this counts `route_<phase>` steps and we are *inside* the current one. So the
+ * comparison below is `<`, where `routeReview`'s reprompt comparison is `<=`.
+ */
+function incompleteCount(ctx: StepsCtx, phase: "spec" | "quality"): number {
+  return (ctx.state.steps ?? []).filter(
+    (s) => s.nodeId === `route_${phase}` && (s.output as { route?: string } | undefined)?.route === "incomplete",
+  ).length;
+}
+
 /**
  * Route this phase's review verdict, and record the round when it produced no
  * commit.
@@ -57,18 +73,37 @@ function reviewAttemptCount(ctx: StepsCtx, phase: "spec" | "quality"): number {
 export async function routeReviewAndRecord(
   ctx: { input: unknown } & OutputsCtx & StepsCtx,
   phase: "spec" | "quality",
-): Promise<{ route: string; escalationReason?: string; findings: Finding[] }> {
+): Promise<{ route: string; escalationReason?: string; findings: Finding[]; gaps?: string[] }> {
   const routed = routeReview(ctx, phase);
-  const outcome = OUTCOME_BY_ROUTE[routed.route];
+  const input = inputOf(ctx);
+  // The gate runs only on a verdict the flow would otherwise act on. `reprompt`
+  // and `escalate` already end the round, and re-checking a verdict with no
+  // content would report the same two gaps as a second failure mode.
+  let result: { route: string; escalationReason?: string; findings: Finding[]; gaps?: string[] } = routed;
+  if (routed.route === "clean" || routed.route === "fix") {
+    const verdict = (ctx.outputs as Record<string, ReviewVerdict | undefined>)[`review_${phase}`];
+    const gaps = verdict ? await auditGaps(verdict, input.workdir) : [];
+    if (gaps.length > 0) {
+      result =
+        incompleteCount(ctx, phase) < MAX_INCOMPLETE_ATTEMPTS
+          ? { ...routed, route: "incomplete", gaps }
+          : {
+              ...routed,
+              route: "escalate",
+              escalationReason: `${phase} review never discharged its reading obligations: ${gaps.join("; ")}`,
+            };
+    }
+  }
+  const outcome = OUTCOME_BY_ROUTE[result.route];
   if (outcome) {
-    await appendRound(inputOf(ctx), {
+    await appendRound(input, {
       ts: new Date().toISOString(),
       phase,
       attempt: reviewAttemptCount(ctx, phase),
       committed: false,
       outcome,
-      findings: routed.findings,
+      findings: result.findings,
     });
   }
-  return routed;
+  return result;
 }

package/flows/nax-finish/types.ts

@@ -15,6 +15,49 @@ export interface Finding {
   title: string;
   problem: string;
   fix: string;
+  /**
+   * Set when the reviewer marked this finding as needing a human — a spec
+   * conflict or a design call with no safe mechanical fix. This replaces the
+   * whole-reply `escalate` route the reviewer used to choose: escalation is a
+   * property of one finding, not of the phase, so reporting a design concern no
+   * longer halts the pipeline by itself.
+   */
+  judgment?: boolean;
+  /** Why this finding needs a human; the escalation reason when it escalates. */
+  judgmentReason?: string;
+}
+
+/** One external definition the reviewer says it opened before judging. */
+export interface Touchpoint {
+  /** Repo-relative path, or the literal `none` sentinel. */
+  path: string;
+  /** Symbol or line after the final `:`, when the reviewer gave one. */
+  symbol?: string;
+  /** The reviewer's stated reason for opening it (or for there being none). */
+  note: string;
+}
+
+/** A reviewer reply, parsed. Sections are reported separately from their content
+ * so an *absent* section is distinguishable from an *empty* one — only the first
+ * is a reviewer that skipped the obligation. */
+export interface ReviewReport {
+  findings: Finding[];
+  touchpoints: Touchpoint[];
+  walk: string[];
+  sawNoFindings: boolean;
+  sawTouchpointsSection: boolean;
+  sawWalkSection: boolean;
+}
+
+/** What the fix node did with one finding it was handed. */
+export interface FindingDisposition {
+  /** 1-based index into the findings list the fix prompt numbered. */
+  index: number;
+  disposition: "fixed" | "rejected";
+  /** `file:line` pinning the current behaviour; required for a rejection. */
+  evidence?: string;
+  /** Set by `commit_<phase>` when the cited evidence path does not exist. */
+  evidenceMissing?: boolean;
 }
 export interface ReviewVerdict {
   /**
@@ -33,6 +76,15 @@ export interface ReviewVerdict {
   escalationReason?: string;
   /** Bounded tail of an unparseable reply; set only when `route` is `reprompt`. */
   raw?: string;
+  /** Touchpoints the reviewer listed; read by the audit gate in `routeReviewAndRecord`. */
+  touchpoints?: Touchpoint[];
+  /** The per-AC or per-function walk lines the reviewer emitted. */
+  walk?: string[];
+  /** Whether the section was present at all — absent and empty are different failures. */
+  sawTouchpointsSection?: boolean;
+  sawWalkSection?: boolean;
+  /** Set on a `fix_<phase>` output: what the fixer did with each finding it was handed. */
+  dispositions?: FindingDisposition[];
 }
 /** Wall-clock budgets, forwarded from `finish.autoFlow.timeouts` by the plugin. */
 export interface FinishTimeouts {
@@ -92,7 +144,11 @@ export type FinishRoundOutcome =
    * new meaning — a reader hitting it in an old artifact must still be told
    * what it meant when it was written.
    */
-  | "review-skipped";
+  | "review-skipped"
+  /** The reviewer replied with findings but skipped a required audit section, so
+   * the verdict was not acted on. Distinct from `unparseable`: there was a
+   * readable verdict, it just had no evidence behind it. */
+  | "incomplete";
 
 export interface FinishRound {
   ts: string;
@@ -127,6 +183,8 @@ export interface FinishRound {
    * than by matching round timestamps against `git log`.
    */
   sha?: string;
+  /** What the fixer did with each finding it was handed (spec/quality phases). */
+  dispositions?: FindingDisposition[];
 }
 
 export interface FinishInput {

package/flows/nax-finish/verdict.ts

@@ -12,6 +12,7 @@
  * `escalate` node that exists to report precisely this.
  */
 import { extractJsonObject } from "acpx/flows";
+import { parseDispositions, parseReviewReport } from "./findings-parse";
 import { type OutputsCtx, type StepsCtx, fixAttemptCount } from "./flow-ctx";
 import type { Finding, ReviewVerdict } from "./types";
 
@@ -35,6 +36,15 @@ export const MAX_FIX_ATTEMPTS = 3;
  */
 export const MAX_REPROMPT_ATTEMPTS = 1;
 
+/**
+ * Reviews sent back for missing evidence sections, per phase, before escalating.
+ *
+ * One, for the same reason `MAX_REPROMPT_ATTEMPTS` is one: a reviewer that
+ * ignores the reply contract twice is not going to honour it on a third ask, and
+ * a review is the most expensive node in the flow.
+ */
+export const MAX_INCOMPLETE_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;
 
@@ -52,11 +62,29 @@ function parseVerdictJson(text: string): ReviewVerdict {
 }
 
 /**
- * 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.
+ * Read a reviewer's reply, block format first.
+ *
+ * Three tiers, in cost order: the block contract the prompt asks for; then the
+ * JSON object older runs produced (a flow resumed from a journal recorded before
+ * #1614, or a reviewer that answered in the old shape anyway); then reprompt.
+ * The JSON tier is three lines and removes a whole class of resume failure, so
+ * it stays even though nothing asks for JSON any more.
  */
 export function parseReviewVerdict(text: string): ReviewVerdict {
+  const report = parseReviewReport(text);
+  if (report.findings.length > 0 || report.sawNoFindings) {
+    const judged = report.findings.find((f) => f.judgment);
+    const route = judged ? "escalate" : report.findings.length === 0 ? "clean" : "proceed";
+    return {
+      route,
+      findings: report.findings,
+      ...(judged ? { escalationReason: judged.judgmentReason ?? `Needs human judgment: ${judged.title}` } : {}),
+      touchpoints: report.touchpoints,
+      walk: report.walk,
+      sawTouchpointsSection: report.sawTouchpointsSection,
+      sawWalkSection: report.sawWalkSection,
+    };
+  }
   try {
     return parseVerdictJson(text);
   } catch {
@@ -73,10 +101,16 @@ export function parseReviewVerdict(text: string): ReviewVerdict {
  * (`fix_spec → commit_spec`), so a reprompt route would have nowhere to go.
  */
 export function parseFixVerdict(text: string): ReviewVerdict {
+  const dispositions = parseDispositions(text);
+  // Route is always "proceed" — nothing downstream reads it (see docstring
+  // above), and computing it from `parseVerdictJson` is unsafe here: acpx's
+  // balanced-JSON matcher happily parses a bare `[1]` (the disposition line
+  // `[1] fixed`) as a one-element JSON array, which would silently flip the
+  // route to "clean" on a perfectly good disposition-only reply.
   try {
-    return parseVerdictJson(text);
+    return { route: "proceed", findings: parseVerdictJson(text).findings, dispositions };
   } catch {
-    return { route: "proceed", findings: [] };
+    return { route: "proceed", findings: [], dispositions };
   }
 }
 

package/package.json

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