@nathapp/nax 0.77.2 → 0.77.3

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

@@ -23,6 +23,7 @@ import { dirname, isAbsolute, join } from "node:path";
 import { runArgv } from "../exec";
 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 { Forge } from "./forge";
@@ -57,6 +58,10 @@ export interface FinishPrContext {
   artifactSummary?: string;
   /** Repository PR/MR template, verbatim. Absent when none resolves. */
   template?: string;
+  /** How `template` is honoured. Absent → `merge`. See `pr-template-merge.ts`. */
+  templateMode?: TemplateMode;
+  /** Repo overrides for the template-heading → section-key table. */
+  templateSectionMap?: Record<string, string>;
   /** Resolved "What changed" prose. Absent when neither source produced text. */
   narrative?: string;
   /**
@@ -244,6 +249,8 @@ export async function loadFinishPrContext(
     diffstat: stat.diffstat,
     artifactSummary: stat.artifactSummary,
     template,
+    ...(input.prBody?.template !== undefined ? { templateMode: input.prBody.template } : {}),
+    ...(input.prBody?.sectionMap !== undefined ? { templateSectionMap: input.prBody.sectionMap } : {}),
     narrative: resolveNarrative(args.narrative, specSummary),
     title: resolveTitle(args.title, input.feature),
     run: {
@@ -296,7 +303,6 @@ function formatDuration(durationMs: number): string {
 
 function buildStoriesSection(stories: FinishPrStory[]): string {
   const lines: string[] = [];
-  lines.push("## Stories");
   lines.push("| Story | Title | ACs |");
   lines.push("|-------|-------|-----|");
   for (const story of stories) {
@@ -312,7 +318,7 @@ function buildStoriesSection(stories: FinishPrStory[]): string {
  */
 function buildVerificationSection(ctx: FinishPrContext): string | null {
   const { acceptance, regression, gatesRan, diffstat, artifactSummary } = ctx;
-  const lines: string[] = ["## Verification"];
+  const lines: string[] = [];
   if (acceptance !== undefined) lines.push(`- Acceptance: ${acceptance}`);
   if (regression !== undefined) lines.push(`- Regression: ${regression}`);
   if (gatesRan.length > 0) lines.push(`- Gates: ${gatesRan.join(", ")}`);
@@ -323,7 +329,7 @@ function buildVerificationSection(ctx: FinishPrContext): string | null {
   if (artifactSummary !== undefined && artifactSummary.length > 0) {
     lines.push(`- Excluded from diffstat — nax run artifacts: ${artifactSummary}`);
   }
-  if (lines.length === 1) return null;
+  if (lines.length === 0) return null;
   return lines.join("\n");
 }
 
@@ -334,10 +340,31 @@ function buildRoundHeading(round: FinishRound): string {
   return `${base} (${short})`;
 }
 
+/**
+ * What an empty finding list means, in the reader's terms.
+ *
+ * Four different things used to render identically as "_no findings_", which a
+ * human reads as "a reviewer looked at this and approved it" (#1507). Only
+ * `passed` means that. `no-reviewer` is the one that actively misleads: the
+ * gate phase has no reviewer node at all, so its empty list is the absence of a
+ * review, not the result of one.
+ *
+ * `fixed` and the legacy `undefined` both fall through to "_no findings_":
+ * rounds written before `outcome` existed carry no field to read, and claiming
+ * anything more specific about them would be inventing detail.
+ */
+const EMPTY_ROUND_NOTE: Record<string, string> = {
+  passed: "- _no findings_",
+  "no-reviewer": "- _no reviewer for this phase_",
+  unparseable: "- _reviewer output could not be parsed_",
+  escalated: "- _escalated for human review_",
+  "review-skipped": "- _re-review skipped: this fix touched test files only_",
+};
+
 function buildRoundBlock(round: FinishRound): string {
   const lines: string[] = [buildRoundHeading(round)];
   if (round.findings.length === 0) {
-    lines.push("- _no findings_");
+    lines.push(EMPTY_ROUND_NOTE[round.outcome ?? ""] ?? "- _no findings_");
   } else {
     for (const finding of round.findings) lines.push(renderFinding(finding));
   }
@@ -346,8 +373,7 @@ function buildRoundBlock(round: FinishRound): string {
 
 function buildRoundsSection(rounds: FinishRound[]): string | null {
   if (rounds.length === 0) return null;
-  const blocks = rounds.map(buildRoundBlock);
-  return ["## Review rounds", ...blocks].join("\n\n");
+  return rounds.map(buildRoundBlock).join("\n\n");
 }
 
 function renderFinding(finding: Finding): string {
@@ -355,20 +381,17 @@ function renderFinding(finding: Finding): string {
 }
 
 /**
- * Heading and text are produced together, so "no text" cannot render a bare
- * `## What changed` heading — the empty-heading case #1477 forbids.
+ * Body only — the heading is attached by `buildFinishBody`, which drops any
+ * section whose body is null. "No text" therefore 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");
+  return narrative?.trim() || null;
 }
 
 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");
+  return outOfScope.map((item) => `- ${item}`).join("\n");
 }
 
 function buildFooter(run: FinishPrContext["run"]): string | null {
@@ -382,29 +405,38 @@ function buildFooter(run: FinishPrContext["run"]): string | 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);
-  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());
+/**
+ * The nax-authored sections, in canonical order — the order they appear in
+ * when the repo has no template, and the order the leftovers are appended in
+ * when it has one. `key` is what `mergeTemplate` matches against the repo's
+ * headings; the run footer carries an empty heading so it stays unmatchable
+ * and last.
+ */
+function buildBodySections(ctx: FinishPrContext): BodySection[] {
+  const candidates: { key: string; heading: string; body: string | null }[] = [
+    { key: "narrative", heading: "What changed", body: buildNarrativeSection(ctx.narrative) },
+    { key: "stories", heading: "Stories", body: ctx.stories.length > 0 ? buildStoriesSection(ctx.stories) : null },
+    { key: "verification", heading: "Verification", body: buildVerificationSection(ctx) },
+    { key: "rounds", heading: "Review rounds", body: buildRoundsSection(ctx.rounds) },
+    { key: "outOfScope", heading: "Out of scope", body: buildOutOfScopeSection(ctx.outOfScope) },
+    { key: "footer", heading: "", body: buildFooter(ctx.run) },
+  ];
+  return candidates
+    .filter((c): c is { key: string; heading: string; body: string } => c.body !== null)
+    .map(({ key, heading, body }) => ({ key, heading, body }));
+}
 
-  return sections.join("\n\n");
+/**
+ * Assemble the body, merged into the repo's own PR template when it has one.
+ *
+ * The template supplies the *shape* (which headings, in what order) and these
+ * sections supply the *content* — see `pr-template-merge.ts` for why appending
+ * it verbatim, which is what this used to do, shipped a blank form under a
+ * filled one (nax#1504).
+ */
+export function buildFinishBody(ctx: FinishPrContext): string {
+  return mergeTemplate(ctx.template, buildBodySections(ctx), {
+    mode: ctx.templateMode,
+    sectionMap: ctx.templateSectionMap,
+  });
 }

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

@@ -0,0 +1,74 @@
+/**
+ * Recording the review rounds that produce no commit.
+ *
+ * `commit_<phase>` is the audit seam for rounds that *fix* something — it is the
+ * only point where a round's findings and its resulting commit are both known.
+ * But that made a commit the sole evidence a reviewer ever ran: a review that
+ * passed produced no `fix_*`, therefore no `commit_*`, therefore no round, and
+ * "this phase passed" became indistinguishable from "this phase never ran"
+ * (#1507). Worse, it made the owed re-review in #1506 unprovable after the fact.
+ *
+ * So the two seams split by what they know:
+ * - `commit_<phase>` records rounds that changed the tree (`outcome: "fixed"`).
+ * - here records rounds that did not (`passed` / `unparseable` / `escalated`).
+ *
+ * Wrapping `routeReview` rather than living inside it keeps that function pure
+ * and synchronous — it is the flow's routing SSOT and is exercised by a large
+ * table of unit tests that would all have to become async otherwise.
+ */
+import { inputOf } from "../flow-ctx";
+import type { OutputsCtx, StepsCtx } from "../flow-ctx";
+import type { Finding, FinishRoundOutcome } from "../types";
+import { routeReview } from "../verdict";
+import { appendRound } from "./result";
+
+/** 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",
+};
+
+/**
+ * The Nth time this phase's *review* node has run.
+ *
+ * Deliberately not `fixAttemptCount`: that counts `fix_<phase>` steps, which is
+ * the right number for a round that fixed something and the wrong one here — a
+ * review that passes on the first look runs zero fix nodes, and every clean
+ * round would be numbered 0. Self-inclusive, for the same reason `repromptCount`
+ * is: acpx records the `review_<phase>` step before `route_<phase>` executes.
+ */
+function reviewAttemptCount(ctx: StepsCtx, phase: "spec" | "quality"): number {
+  return (ctx.state.steps ?? []).filter((s) => s.nodeId === `review_${phase}`).length;
+}
+
+/**
+ * Route this phase's review verdict, and record the round when it produced no
+ * commit.
+ *
+ * `fix` is the one route that records nothing here: it leads to `fix_<phase>` →
+ * `commit_<phase>`, which appends the round with the commit attached. Recording
+ * at both seams would double-count every fixed round in the PR body.
+ *
+ * Best-effort, exactly like `appendRound` itself: the route is returned whether
+ * or not the write lands. Losing the record is bad; failing the run that has
+ * already done the work is worse.
+ */
+export async function routeReviewAndRecord(
+  ctx: { input: unknown } & OutputsCtx & StepsCtx,
+  phase: "spec" | "quality",
+): Promise<{ route: string; escalationReason?: string; findings: Finding[] }> {
+  const routed = routeReview(ctx, phase);
+  const outcome = OUTCOME_BY_ROUTE[routed.route];
+  if (outcome) {
+    await appendRound(inputOf(ctx), {
+      ts: new Date().toISOString(),
+      phase,
+      attempt: reviewAttemptCount(ctx, phase),
+      committed: false,
+      outcome,
+      findings: routed.findings,
+    });
+  }
+  return routed;
+}

package/flows/nax-finish/types.ts

@@ -1,3 +1,5 @@
+import type { TemplateMode } from "./pr-template-merge";
+
 /** One acceptance-test group as reported by `nax features resolve --json`. */
 export interface AcceptanceGroup {
   packageDir: string;
@@ -50,6 +52,47 @@ export type FinishPhase = "acceptance" | "spec" | "quality" | "gate";
  * finish that died mid-loop is exactly when the record of what it already
  * changed on the branch matters most.
  */
+/**
+ * What produced a round — the difference between "a reviewer read this and
+ * approved it" and "nothing read this".
+ *
+ * Rounds used to be appended only where a fix produced a commit, so a review
+ * that passed left no record at all and was indistinguishable from a review
+ * that never ran (#1507). Every phase that executes now records a round, and
+ * this field says which of the five things happened.
+ *
+ * Optional because rounds recorded by earlier versions have no `outcome`, and
+ * the PR body still has to render those without claiming more than it knows.
+ */
+export type FinishRoundOutcome =
+  /** A reviewer reported findings and this phase's fix node ran. */
+  | "fixed"
+  /** A reviewer ran and reported nothing. The only value that means "approved". */
+  | "passed"
+  /** The reviewer replied, but no verdict could be read out of it. */
+  | "unparseable"
+  /** Handed off to a human — an explicit escalate, a cap, or a node that emitted nothing. */
+  | "escalated"
+  /**
+   * This phase has no reviewer at all (`gate`, `acceptance`). Distinct from
+   * `passed`: an empty finding list here means "nobody looked", and rendering it
+   * as "no findings" manufactures evidence of a review that does not exist.
+   */
+  | "no-reviewer"
+  /**
+   * A re-review was owed and deliberately skipped — today only a `gate` fix
+   * that touched test files exclusively (`gateCommitRoute` → `tests-only`).
+   *
+   * Distinct from `no-reviewer`, which the same node writes when the fix *is*
+   * routed on to `review_quality`. Without the distinction both wrote
+   * `no-reviewer`, so the audit could not tell a gate fix that was re-reviewed
+   * from one whose re-review was skipped by policy — the #1507 failure mode
+   * surviving on the one path where the omission is intentional, and the path
+   * where a reader most needs to know. Recording it is also what makes "how
+   * often does this fire?" answerable before anyone decides to close the hole.
+   */
+  | "review-skipped";
+
 export interface FinishRound {
   ts: string;
   phase: FinishPhase;
@@ -57,6 +100,8 @@ export interface FinishRound {
   attempt: number;
   /** True when the fix produced a commit; false when it changed nothing. */
   committed: boolean;
+  /** What produced this round; absent on rounds written before it existed. */
+  outcome?: FinishRoundOutcome;
   /** Reviewer findings this round set out to fix (spec/quality phases). */
   findings: Finding[];
   /** Gate commands that were red this round (gate phase). */
@@ -92,6 +137,19 @@ export interface FinishInput {
    */
   escalateTelegram: boolean;
   timeouts?: FinishTimeouts;
+  /** PR/MR body composition, forwarded from `finish.autoFlow.prBody`. */
+  prBody?: FinishPrBodySettings;
+}
+
+/**
+ * How the repo's own PR/MR template is honoured when composing the body.
+ * Absent (and absent fields) mean the defaults in `pr-template-merge.ts`.
+ */
+export interface FinishPrBodySettings {
+  /** `merge` (default) · `strict` (keep unfillable headings, empty) · `ignore`. */
+  template?: TemplateMode;
+  /** Normalised template heading → body-section key, layered over the defaults. */
+  sectionMap?: Record<string, string>;
 }
 export interface FinishResult {
   feature: string;

package/flows/nax-finish/verdict.ts

@@ -118,14 +118,31 @@ export function repromptCount(ctx: StepsCtx, phase: "spec" | "quality"): number
  * 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.
+ *
+ * An **absent** verdict escalates for the same reason, and it is a distinct
+ * case from an unparseable one: `parseReviewVerdict` never returns undefined,
+ * so a missing entry means the node produced no output at all — it never ran,
+ * or it died before emitting. Neither is an approval. This must not fall
+ * through to `findings ?? []`, because `ctx.outputs` holds only each node's
+ * latest output: on a loop re-entry the previous round's clean verdict can
+ * still be sitting there, and routing on it re-approves a diff nobody read.
+ * There is no reprompt path here — a node that emitted nothing has no raw tail
+ * to quote back, so a human is the only remaining reader.
  */
 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") {
+  if (!verdict) {
+    return {
+      route: "escalate",
+      escalationReason: `${phase} reviewer produced no verdict — the node emitted no output, so nothing reviewed this diff.`,
+      findings: [],
+    };
+  }
+  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.
@@ -139,7 +156,7 @@ export function routeReview(
       findings,
     };
   }
-  if (verdict?.route === "escalate") {
+  if (verdict.route === "escalate") {
     return {
       route: "escalate",
       escalationReason: verdict.escalationReason ?? `${phase} review raised a finding needing human judgment`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nathapp/nax",
-  "version": "0.77.2",
+  "version": "0.77.3",
   "description": "AI Coding Agent Orchestrator — loops until done",
   "type": "module",
   "bin": {
@@ -64,7 +64,7 @@
     "@biomejs/biome": "^1.9.4",
     "@types/bun": "^1.3.8",
     "react-devtools-core": "^7.0.1",
-    "typescript": "^5.7.3"
+    "typescript": "^7.0.2"
   },
   "license": "MIT",
   "author": "William Khoo",