@nathapp/nax 0.80.0 → 0.80.1

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

@@ -12,7 +12,7 @@
  * 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";
+import type { Finding, FindingDisposition, FinishPhase } from "./types";
 
 /** Git's conventional soft cap for a commit summary line. */
 const MAX_SUBJECT_LEN = 72;
@@ -89,6 +89,14 @@ interface MessageCtx {
 interface MessageOptions {
   /** Absolute repo root, used to rewrite quoted paths as repo-relative. */
   workdir?: string;
+  /**
+   * What `fix_<phase>` did with each finding it was handed, by 1-based index.
+   *
+   * Only `commit_<phase>` callers have this — `gate`/`acceptance` commits, and
+   * any caller that has not run a fix node yet, pass nothing, and every finding
+   * renders as before (`Fix: <text>`).
+   */
+  dispositions?: FindingDisposition[];
 }
 
 interface PhaseOutputs {
@@ -179,15 +187,31 @@ function bodyFor(phase: FinishPhase, ctx: MessageCtx, opts: MessageOptions): str
   }
   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"),
-  ];
+  const dispositions = opts.dispositions ?? [];
+  return [findings.map((f, i) => findingBody(f, i, dispositions)).join("\n")];
+}
+
+/**
+ * Render one finding's line(s) in the commit body, honouring `fix_<phase>`'s
+ * disposition when one exists.
+ *
+ * A rejected finding must not read `Fix: <the fix text>` — nothing was applied
+ * — so it renders the same way `pr-body.ts`'s `renderRejected` does: as
+ * rejected, with its evidence citation, so shipped git history and the PR body
+ * agree on what happened to the finding.
+ */
+function findingBody(f: Finding, index: number, dispositions: FindingDisposition[]): string {
+  const d = dispositions.find((x) => x.index === index + 1);
+  if (d?.disposition === "rejected") {
+    const evidence = d.evidence ? `\`${d.evidence}\`` : "no evidence cited";
+    const caveat = d.evidenceMissing ? " (evidence path not found)" : "";
+    return [`- [${f.severity}] ${f.title} — rejected: ${evidence}${caveat}`, f.problem ? `  ${f.problem}` : ""]
+      .filter(Boolean)
+      .join("\n");
+  }
+  return [`- [${f.severity}] ${f.title}`, f.problem ? `  ${f.problem}` : "", f.fix ? `  Fix: ${f.fix}` : ""]
+    .filter(Boolean)
+    .join("\n");
 }
 
 /** Human-readable phase label for the attribution trailer. */

package/flows/nax-finish/findings-parse.ts

@@ -0,0 +1,150 @@
+/**
+ * Turning a reviewer's free-form reply into structured findings.
+ *
+ * The reviewer's contract is text, not JSON, for two reasons. The dimension
+ * references both hinge on an enumeration — a per-AC walk and a per-changed-
+ * function walk — and a reply constrained to one JSON object has nowhere to put
+ * one. And a text reply has no cliff: a malformed line costs that line, where an
+ * unparseable JSON object used to cost the entire review (#1614).
+ *
+ * Every function here is pure and non-throwing. `verdict.ts` documents why that
+ * is load-bearing: a throw inside an acpx `parse` fails the whole flow.
+ */
+import type { Finding, FindingDisposition, ReviewReport, Severity, Touchpoint } from "./types";
+
+type Section = "touchpoints" | "walk" | "findings";
+
+/** Headings are matched loosely — any level, any case, optional trailing colon. */
+const HEADING = /^\s*#{1,6}\s*(TOUCHPOINTS|WALK|FINDINGS|DISPOSITIONS)\s*:?\s*$/i;
+const BLOCK = /^\s*\[(CRITICAL|HIGH|MEDIUM|LOW)\]\s+(.+?)\s*$/;
+const FIELD = /^\s*(Problem|Fix|Judgment)\s*:\s*(.*)$/i;
+const NO_FINDINGS = /^\s*no findings\.?\s*$/i;
+const BULLET = /^\s*[-*]\s+(.+?)\s*$/;
+const DISPOSITION = /^\s*\[?(\d+)\]?\s*[.:)]?\s*(fixed|rejected)\b\s*(.*)$/i;
+const EVIDENCE = /evidence\s*:\s*(\S+)/i;
+
+/** `- path/to/file.ts:symbol — why`, tolerant of backticks and of `-` for `—`. */
+function parseTouchpoint(text: string): Touchpoint | null {
+  const m = /^(\S+)\s*(?:[—–-]\s*)?(.*)$/.exec(text);
+  if (!m) return null;
+  const locator = m[1].replace(/[`,]/g, "");
+  const note = m[2].trim();
+  if (/^none$/i.test(locator)) return { path: "none", note };
+  const cut = locator.lastIndexOf(":");
+  return cut > 0 ? { path: locator.slice(0, cut), symbol: locator.slice(cut + 1), note } : { path: locator, note };
+}
+
+function parseJudgment(value: string): { judgment: boolean; judgmentReason?: string } {
+  const m = /^\s*(yes|true)\b\s*(?:[—–-]\s*)?(.*)$/i.exec(value);
+  if (!m) return { judgment: false };
+  const reason = m[2].trim();
+  return reason ? { judgment: true, judgmentReason: reason } : { judgment: true };
+}
+
+/**
+ * Parse a reviewer reply.
+ *
+ * Section state starts at `findings`, not "none": a reviewer that emits blocks
+ * and no headings at all is a partial failure of the contract, and its findings
+ * are still worth keeping — losing them is the exact failure this replaces. The
+ * `saw*Section` flags stay false in that case, which is what the audit gate in
+ * `steps/review-audit.ts` keys off.
+ */
+export function parseReviewReport(text: string): ReviewReport {
+  const report: ReviewReport = {
+    findings: [],
+    touchpoints: [],
+    walk: [],
+    sawNoFindings: false,
+    sawTouchpointsSection: false,
+    sawWalkSection: false,
+  };
+  let section: Section = "findings";
+  let current: Finding | null = null;
+  let lastField: "problem" | "fix" | null = null;
+
+  const flush = () => {
+    if (current) report.findings.push(current);
+    current = null;
+    lastField = null;
+  };
+
+  for (const line of text.split("\n")) {
+    const heading = HEADING.exec(line);
+    if (heading) {
+      flush();
+      const name = heading[1].toLowerCase();
+      if (name === "touchpoints") {
+        section = "touchpoints";
+        report.sawTouchpointsSection = true;
+      } else if (name === "walk") {
+        section = "walk";
+        report.sawWalkSection = true;
+      } else {
+        section = "findings";
+      }
+      continue;
+    }
+
+    if (section === "touchpoints") {
+      const bullet = BULLET.exec(line);
+      const tp = bullet ? parseTouchpoint(bullet[1]) : null;
+      if (tp) report.touchpoints.push(tp);
+      continue;
+    }
+    if (section === "walk") {
+      if (line.trim().length > 0) report.walk.push(line.trim());
+      continue;
+    }
+
+    const block = BLOCK.exec(line);
+    if (block) {
+      flush();
+      current = { severity: block[1] as Severity, title: block[2], problem: "", fix: "" };
+      continue;
+    }
+    if (NO_FINDINGS.test(line)) {
+      report.sawNoFindings = true;
+      continue;
+    }
+    if (!current) continue;
+    const field = FIELD.exec(line);
+    if (field) {
+      const key = field[1].toLowerCase();
+      if (key === "problem") {
+        current.problem = field[2].trim();
+        lastField = "problem";
+      } else if (key === "fix") {
+        current.fix = field[2].trim();
+        lastField = "fix";
+      } else {
+        Object.assign(current, parseJudgment(field[2]));
+        lastField = null;
+      }
+      continue;
+    }
+    // A continuation line for the field above it — the reviewer wraps prose, and
+    // a wrapped Problem read as nothing is how detail silently disappears.
+    if (lastField && line.trim().length > 0) {
+      current[lastField] = `${current[lastField]} ${line.trim()}`.trim();
+    }
+  }
+  flush();
+  return report;
+}
+
+/** Parse the `## DISPOSITIONS` section of a fix node's reply. */
+export function parseDispositions(text: string): FindingDisposition[] {
+  const out: FindingDisposition[] = [];
+  for (const line of text.split("\n")) {
+    const m = DISPOSITION.exec(line);
+    if (!m) continue;
+    const evidence = EVIDENCE.exec(m[3])?.[1];
+    out.push({
+      index: Number(m[1]),
+      disposition: m[2].toLowerCase() as "fixed" | "rejected",
+      ...(evidence ? { evidence } : {}),
+    });
+  }
+  return out;
+}

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

@@ -143,3 +143,8 @@ export function incrementalSince(ctx: OutputsCtx & StepsCtx, phase: "spec" | "qu
   if (!firstCommit) return null;
   return (firstCommit.output as { shaBefore?: string | null } | undefined)?.shaBefore ?? null;
 }
+
+/** Why this phase's last review was sent back, so the retry is told what was missing. */
+export function reviewGapsOf(ctx: OutputsCtx, phase: "spec" | "quality"): string[] {
+  return ((ctx.outputs as Record<string, { gaps?: string[] } | undefined>)[`route_${phase}`]?.gaps ?? []) as string[];
+}

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

@@ -50,7 +50,15 @@
  */
 import { defineFlow } from "acpx/flows";
 import { buildFixCommitMessage } from "./commit-message";
-import { findingsOf, fixAttemptCount, gateOutputs, incrementalSince, inputOf, loadCtxOf } from "./flow-ctx";
+import {
+  findingsOf,
+  fixAttemptCount,
+  gateOutputs,
+  incrementalSince,
+  inputOf,
+  loadCtxOf,
+  reviewGapsOf,
+} from "./flow-ctx";
 import { narrativePrompt, parseNarrativeNode } from "./narrative";
 import { buildReviewPrompt, fixPrompt } from "./review-prompts";
 import {
@@ -73,12 +81,13 @@ import {
   qualityGatesNode,
   resolveFeature,
   routeReviewAndRecord,
+  validateDispositions,
   writeResult,
 } from "./steps";
 import type { Forge } from "./steps/forge";
 import { _prBodyDeps, buildFinishBody, buildFinishTitle } from "./steps/pr-body";
-import type { FinishInput, FinishPhase, FinishResult, ReviewVerdict } from "./types";
-import { parseFixVerdict, parseReviewVerdict, repromptCount } from "./verdict";
+import type { FindingDisposition, FinishInput, FinishPhase, FinishResult, ReviewVerdict } from "./types";
+import { parseFixVerdict, parseReviewVerdict } from "./verdict";
 
 /**
  * Disabled only on an explicit "0". An unset variable means enabled, so a flow
@@ -161,12 +170,24 @@ function commitFixNode(phase: FinishPhase) {
     }): Promise<{ committed: boolean; route: string; shaBefore: string | null; shaAfter: string | null }> {
       const i = inputOf(ctx);
       const messageCtx = { outputs: ctx.outputs as Record<string, unknown> };
+      // A rejection is only as good as its citation, so the path is checked the
+      // same way a reviewer's touchpoints are. A missing file does not veto the
+      // rejection — the fixer may have cited a line rather than a path, or moved
+      // the file — it marks it, so the PR body (and the commit message below)
+      // can say the waiver is unverified rather than silently presenting it as
+      // evidenced. Resolved before the commit so the shipped commit message can
+      // render a rejection the same way the PR body does, instead of `Fix: …`.
+      const dispositions = await validateDispositions(
+        i.workdir,
+        (ctx.outputs as Record<string, { dispositions?: FindingDisposition[] } | undefined>)[`fix_${phase}`]
+          ?.dispositions ?? [],
+      );
       // 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.
       const { committed, shaBefore, shaAfter } = await commitFixes(
         i.workdir,
-        buildFixCommitMessage(phase, i.feature, messageCtx, { workdir: i.workdir }),
+        buildFixCommitMessage(phase, i.feature, messageCtx, { workdir: i.workdir, dispositions }),
         { skipHooks: true },
       );
       // Routed BEFORE the round is recorded: `buildCommitRound` needs the
@@ -190,6 +211,7 @@ function commitFixNode(phase: FinishPhase) {
           failing: phase === "gate" ? (gateOutputs(ctx).failing ?? []) : undefined,
           shaAfter,
           now: new Date().toISOString(),
+          dispositions,
         }),
       );
       return { committed, route, shaBefore, shaAfter };
@@ -246,7 +268,7 @@ export default defineFlow({
           specPath: outs.specPath ?? "",
           since: incrementalSince(ctx, "spec"),
           priorFindings: findingsOf(ctx, "spec"),
-          retry: repromptCount(ctx, "spec") > 0,
+          gaps: reviewGapsOf(ctx, "spec"),
         });
       },
       parse: parseReviewVerdict,
@@ -272,7 +294,7 @@ export default defineFlow({
           specPath: outs.specPath ?? "",
           since: incrementalSince(ctx, "quality"),
           priorFindings: findingsOf(ctx, "quality"),
-          retry: repromptCount(ctx, "quality") > 0,
+          gaps: reviewGapsOf(ctx, "quality"),
         });
       },
       parse: parseReviewVerdict,
@@ -478,7 +500,13 @@ export default defineFlow({
       from: "route_spec",
       switch: {
         on: "$.route",
-        cases: { clean: "review_quality", fix: "fix_spec", escalate: "escalate", reprompt: "review_spec" },
+        cases: {
+          clean: "review_quality",
+          fix: "fix_spec",
+          escalate: "escalate",
+          reprompt: "review_spec",
+          incomplete: "review_spec",
+        },
       },
     },
     // Spec fixes re-run the acceptance gate first (they can break it), and the
@@ -490,7 +518,13 @@ export default defineFlow({
       from: "route_quality",
       switch: {
         on: "$.route",
-        cases: { clean: "quality_gates", fix: "fix_quality", escalate: "escalate", reprompt: "review_quality" },
+        cases: {
+          clean: "quality_gates",
+          fix: "fix_quality",
+          escalate: "escalate",
+          reprompt: "review_quality",
+          incomplete: "review_quality",
+        },
       },
     },
     // Quality fixes are re-reviewed by the same lens; the repo-root gates that

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

@@ -295,33 +295,51 @@ the dispatcher.
 `;
 
 const CLASSIFIER = [
-  "After producing findings, classify the OVERALL route for this phase:",
-  '- Route "proceed" when every finding has a clear recommended fix you can apply now',
-  "  (CRITICAL/HIGH, or MEDIUM whose fix is clear and low-risk) — you will fix them and re-verify.",
-  '- Route "escalate" when ANY finding is a spec conflict, a contradiction with the spec,',
-  "  or a design/judgment concern with no safe mechanical fix. Do not attempt to fix those.",
-].join("\n");
-
-const JSON_CONTRACT = [
-  "Return exactly one JSON object and nothing else. First char `{`, last char `}`.",
-  "Shape:",
-  "{",
-  '  "route": "proceed" | "escalate",',
-  '  "findings": [{ "severity": "CRITICAL"|"HIGH"|"MEDIUM"|"LOW", "title": string, "problem": string, "fix": string }],',
-  '  "escalationReason": string   // required when route is "escalate"; omit otherwise',
-  "}",
+  "Mark a finding for human judgment — and only such a finding — by adding a",
+  "`Judgment: yes — <why>` line to its block. Use it when the finding is a spec",
+  "conflict, or a design/judgment call with no safe mechanical fix. Everything",
+  "else will be fixed and re-verified automatically, so a finding with a clear,",
+  "low-risk fix must NOT carry the marker.",
 ].join("\n");
 
 /**
- * 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.
+ * The reply contract.
+ *
+ * This supersedes the "Output format — return ONLY this" section of
+ * `WORKER_PROTOCOL` above, which is kept verbatim so it stays diffable against
+ * the skill's `references/worker-protocol.md`. Its `[SEVERITY]` blocks are
+ * exactly this contract's `## FINDINGS` section; the two sections before it are
+ * what the flow adds, because the flow — unlike the skill's dispatcher — has no
+ * human reading the reply and so must be able to check the obligations itself.
+ *
+ * There is no JSON. A reply constrained to one JSON object has nowhere to put
+ * the per-AC and per-function enumerations both dimension references depend on,
+ * and an unreadable object used to discard the entire review (#1614).
  */
-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");
+function outputContract(phase: "spec" | "quality"): string {
+  const walk =
+    phase === "spec"
+      ? "one line per AC in the spec: `AC-3 Covered|Partial|Missing — <one clause>`"
+      : "one line per function or method the diff adds or changes: `path.ts:name — earns its place|concern: <one clause>`";
+  return `# Reply contract — your reply must be these three sections, in this order
+
+## TOUCHPOINTS
+One line per external touchpoint whose definition you actually opened:
+\`- path/to/file.ts:symbol — why you opened it\`. If the diff genuinely has none,
+the single line \`- none — <justification>\`. The paths are checked against the
+repo: a list whose paths do not exist is treated as an incomplete review, not a
+clean one, and you will be asked again.
+
+## WALK
+${walk}. This is the enumeration your dimension reference requires. One line each,
+no prose. A missing or empty WALK section is an incomplete review.
+
+## FINDINGS
+The \`[SEVERITY] …\` blocks defined in the worker protocol above — or the literal
+line \`No findings.\` if you found none. This section is the only thing that
+becomes a finding; the two above are the evidence that you were in a position to
+write it.`;
+}
 
 /**
  * Build the reviewer prompt.
@@ -348,25 +366,34 @@ export function buildReviewPrompt(
     specPath: string;
     since?: string | null;
     priorFindings?: Finding[];
-    retry?: boolean;
+    gaps?: string[];
   },
 ): string {
   const dims = phase === "spec" ? SPEC_REVIEW_DIMENSIONS : QUALITY_REVIEW_DIMENSIONS;
-  const lead = args.retry ? [RETRY_NOTICE] : [];
+  const gapNotice =
+    args.gaps && args.gaps.length > 0
+      ? [
+          [
+            "IMPORTANT — your previous review was not accepted, because it skipped a required section:",
+            ...args.gaps.map((g) => `- ${g}`),
+            "Do the reading this time and emit all three sections. A verdict without them is not a review.",
+          ].join("\n"),
+        ]
+      : [];
   if (!args.since) {
     return [
-      ...lead,
+      ...gapNotice,
       `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,
+      outputContract(phase),
     ].join("\n\n");
   }
   return [
-    ...lead,
+    ...gapNotice,
     `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)}`,
@@ -380,26 +407,62 @@ export function buildReviewPrompt(
     WORKER_PROTOCOL,
     dims,
     CLASSIFIER,
-    JSON_CONTRACT,
+    outputContract(phase),
   ].join("\n\n");
 }
 
+/**
+ * The fix node's contract.
+ *
+ * For the two review phases it is no longer "apply these". Every finding used to
+ * be implemented unconditionally, so a false positive was always built — and on
+ * the diff behind #1614 the comparison review raised one finding a human
+ * withdrew, because the change it proposed contradicted a test deliberately
+ * pinning the current behaviour. `quality_gates` would then have proved the
+ * resulting suite green. Reporting more findings without a way to reject one
+ * scales the false-positive exposure with the true-positive one, so the two ship
+ * together.
+ *
+ * A rejection must cite the file:line that pins the behaviour: an unevidenced
+ * "I disagree" is how a real finding gets waived, and `commit_<phase>` checks
+ * that the cited path exists.
+ */
 export function fixPrompt(
   phase: "acceptance" | "spec" | "quality" | "gate",
   ctx: { outputs: Record<string, unknown> },
 ): string {
-  const outs = ctx.outputs as Record<string, { findings?: unknown; output?: string }>;
-  const detail =
-    phase === "gate"
-      ? (outs.quality_gates?.output ?? "")
-      : phase === "acceptance"
-        ? (outs.acceptance?.output ?? "")
-        : JSON.stringify(outs[`review_${phase}`]?.findings ?? []);
+  const outs = ctx.outputs as Record<string, { findings?: Finding[]; output?: string }>;
+  if (phase === "gate" || phase === "acceptance") {
+    const detail = phase === "gate" ? (outs.quality_gates?.output ?? "") : (outs.acceptance?.output ?? "");
+    return [
+      `Apply the recommended fixes for the ${phase} phase, directly in the repo.`,
+      "Do not commit, push, or open PRs — nax-finish commits and pushes your edits itself.",
+      `Context:\n${detail}`,
+      "After fixing, re-run the feature's acceptance tests and the relevant checks; only proceed when they pass.",
+      'Return exactly {"route":"proceed"} when done and green.',
+    ].join("\n\n");
+  }
+  const findings = outs[`review_${phase}`]?.findings ?? [];
+  const numbered = findings
+    .map((f, i) => `[${i + 1}] [${f.severity}] ${f.title}\n  Problem: ${f.problem}\n  Fix: ${f.fix}`)
+    .join("\n");
   return [
-    `Apply the recommended fixes for the ${phase} phase, directly in the repo.`,
+    `Resolve the ${phase} review findings below, directly in the repo.`,
     "Do not commit, push, or open PRs — nax-finish commits and pushes your edits itself.",
-    `Context:\n${detail}`,
-    "After fixing, re-run the feature's acceptance tests and the relevant checks; only proceed when they pass.",
-    'Return exactly {"route":"proceed"} when done and green.',
+    numbered,
+    [
+      "A finding may be REJECTED rather than fixed — but only on evidence, not on preference.",
+      "Reject when the change it asks for would contradict an existing test that deliberately",
+      "pins the current behaviour, or a spec statement that requires it. Cite the `file:line`.",
+      "Anything else you fix.",
+    ].join("\n"),
+    [
+      "After fixing, re-run the feature's acceptance tests and the relevant checks; only proceed when they pass.",
+      "Then end your reply with one line per finding, in this exact shape:",
+      "",
+      "## DISPOSITIONS",
+      "[1] fixed",
+      "[2] rejected — evidence: test/unit/foo.test.ts:42",
+    ].join("\n"),
   ].join("\n\n");
 }

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

@@ -8,7 +8,7 @@
  *
  * Pairs with `./review-round`, which records the rounds that produce no commit.
  */
-import type { Finding, FinishPhase, FinishRound, FinishRoundOutcome } from "../types";
+import type { Finding, FindingDisposition, FinishPhase, FinishRound, FinishRoundOutcome } from "../types";
 
 /** Phases that own a reviewer node; every other phase's round has nobody behind it. */
 const REVIEWED_PHASES: FinishPhase[] = ["spec", "quality"];
@@ -40,6 +40,8 @@ export interface CommitRoundInput {
   /** Post-commit HEAD, when there was a commit. */
   shaAfter?: string | null;
   now: string;
+  /** What the fixer did with each finding it was handed (spec/quality phases). */
+  dispositions?: FindingDisposition[];
 }
 
 /**
@@ -60,5 +62,6 @@ export function buildCommitRound(i: CommitRoundInput): FinishRound {
     route: i.route,
     ...(i.failing ? { failing: i.failing } : {}),
     ...(i.committed && i.shaAfter ? { sha: i.shaAfter } : {}),
+    ...(i.dispositions && i.dispositions.length > 0 ? { dispositions: i.dispositions } : {}),
   };
 }

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

@@ -9,4 +9,5 @@ export * from "./pr";
 export * from "./pr-narrative";
 export * from "./commit-round";
 export * from "./result";
+export * from "./review-audit";
 export * from "./review-round";

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

@@ -25,7 +25,7 @@ import { readSpecSummary, resolveNarrative } from "../narrative";
 import { findPrTemplate } from "../pr-template";
 import { type BodySection, type TemplateMode, mergeTemplate } from "../pr-template-merge";
 import { resolveTitle } from "../pr-title";
-import type { Finding, FinishInput, FinishRound, RunFn } from "../types";
+import type { Finding, FindingDisposition, FinishInput, FinishRound, RunFn } from "../types";
 import type { Forge } from "./forge";
 import { readRounds } from "./result";
 
@@ -359,6 +359,7 @@ const EMPTY_ROUND_NOTE: Record<string, string> = {
   unparseable: "- _reviewer output could not be parsed_",
   escalated: "- _escalated for human review_",
   "review-skipped": "- _re-review skipped: this fix touched test files only_",
+  incomplete: "- _review sent back: required evidence sections missing_",
 };
 
 function buildRoundBlock(round: FinishRound): string {
@@ -366,7 +367,13 @@ function buildRoundBlock(round: FinishRound): string {
   if (round.findings.length === 0) {
     lines.push(EMPTY_ROUND_NOTE[round.outcome ?? ""] ?? "- _no findings_");
   } else {
-    for (const finding of round.findings) lines.push(renderFinding(finding));
+    if (round.outcome === "incomplete") {
+      lines.push("- _not acted on — the review was sent back for missing evidence sections_");
+    }
+    for (const [i, finding] of round.findings.entries()) {
+      const d = round.dispositions?.find((x) => x.index === i + 1);
+      lines.push(d?.disposition === "rejected" ? renderRejected(finding, d) : renderFinding(finding));
+    }
   }
   return lines.join("\n");
 }
@@ -380,6 +387,19 @@ function renderFinding(finding: Finding): string {
   return `- [${finding.severity}] ${finding.title}`;
 }
 
+/**
+ * A waived finding, shown as waived.
+ *
+ * The alternative — dropping it — would make a rejection indistinguishable from
+ * a fix in the only artifact a human reads, which is the failure this whole
+ * mechanism exists to avoid.
+ */
+function renderRejected(finding: Finding, d: FindingDisposition): string {
+  const evidence = d.evidence ? `\`${d.evidence}\`` : "_no evidence cited_";
+  const caveat = d.evidenceMissing ? " — **evidence path not found**" : "";
+  return `- [${finding.severity}] ${finding.title} — _rejected_: ${evidence}${caveat}`;
+}
+
 /**
  * Body only — the heading is attached by `buildFinishBody`, which drops any
  * section whose body is null. "No text" therefore cannot render a bare