@nathapp/nax 0.76.0 → 0.77.1

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

@@ -0,0 +1,140 @@
+/**
+ * The PR title — sentinel, sanitiser, and the fallback chain.
+ *
+ * `buildFinishTitle` used to return `feat: <feature>` unconditionally, so every
+ * finish-opened PR was titled with its feature slug: `feat: schema-drift-gate`
+ * describes the run, not the change. The narrative node has already read the
+ * whole diff by the time the body is amended, so a real conventional-commit
+ * subject costs one extra sentinel in a prompt that was being sent anyway.
+ *
+ * No deterministic source can replace it. The spec's H1 is the slug in prose
+ * (`# SPEC: Schema drift gate`), the PRD carries no feature-level title, and
+ * concatenating story titles reads worse than the slug it replaces — which is
+ * why this is the one part of the PR metadata that is model-derived, and why
+ * everything below assumes the model may return junk.
+ *
+ * Lives beside `narrative.ts` rather than in `src/prompts/builders/` for the
+ * same reason that file gives: `flows/` runs in acpx's Node process and imports
+ * nothing from `src/`.
+ */
+
+/** Sentinel wrapping the title. See `narrative.ts` for why a delimiter is required at all. */
+export const TITLE_OPEN_TAG = "<title>";
+export const TITLE_CLOSE_TAG = "</title>";
+
+/**
+ * Longest title rendered onto a PR.
+ *
+ * 72 is the conventional-commit subject norm, and GitHub truncates around this
+ * width in list views.
+ */
+export const TITLE_MAX_CHARS = 72;
+
+/**
+ * Conventional-commit prefix, split into the type-with-scope and the subject.
+ *
+ * Types mirror the list in `.claude/rules/project-conventions.md`, plus
+ * `revert`. Captured rather than merely tested so the two halves can be
+ * rejoined with exactly one space — `feat:no space` and `feat:` both reach
+ * here, and testing alone let the latter become `feat: feat:`.
+ *
+ * A title arriving without any prefix is prefixed rather than rejected: the
+ * prose is usually right even when the model forgets the ceremony.
+ */
+const CONVENTIONAL_PREFIX_RE =
+  /^((?:feat|fix|refactor|perf|docs|test|chore|ci|build|style|revert)(?:\([^)]*\))?!?):\s*([\s\S]*)$/i;
+
+const DEFAULT_TYPE = "feat";
+
+/** Wrapping quotes/backticks the model adds when it treats the title as a quoted string. */
+const WRAPPING_CHARS = new Set(['"', "'", "`", "*", "_"]);
+
+function stripWrapping(text: string): string {
+  let out = text;
+  // Loop: models nest these ("`fix: thing`" arrives quoted *and* fenced).
+  while (out.length >= 2) {
+    const first = out[0];
+    const last = out[out.length - 1];
+    if (first !== undefined && first === last && WRAPPING_CHARS.has(first)) {
+      out = out.slice(1, -1).trim();
+      continue;
+    }
+    break;
+  }
+  return out;
+}
+
+/**
+ * Cut to `TITLE_MAX_CHARS` on a word boundary where one is available.
+ *
+ * A mid-word cut reads as corruption rather than brevity; falling back to a
+ * hard slice only matters for a title with no spaces at all.
+ */
+function clamp(text: string): string {
+  if (text.length <= TITLE_MAX_CHARS) return text;
+  const cut = text.slice(0, TITLE_MAX_CHARS);
+  const lastSpace = cut.lastIndexOf(" ");
+  // Guard against a long type prefix eating the whole budget: only honour a
+  // word boundary that leaves a meaningful subject behind.
+  const MIN_KEEP = 20;
+  return (lastSpace >= MIN_KEEP ? cut.slice(0, lastSpace) : cut).trimEnd();
+}
+
+/**
+ * Normalise a model-supplied title, or `undefined` if nothing usable survives.
+ *
+ * Never throws — this feeds `parse` on an acp node, and the flow's PR is
+ * already open by the time it runs.
+ */
+export function sanitizeTitle(raw: string | undefined): string | undefined {
+  if (typeof raw !== "string") return undefined;
+
+  // First non-empty line: a title is single-line by definition, and a model
+  // that adds a rationale below it must not push that onto the PR.
+  const firstLine = raw.split(/\r?\n/).find((line) => line.trim().length > 0);
+  if (firstLine === undefined) return undefined;
+
+  // Collapse internal runs of whitespace before measuring, so the length cap
+  // reflects what a reader sees.
+  let title = stripWrapping(firstLine.trim()).replace(/\s+/g, " ");
+  // Markdown heading marks, for a model that answers the "write a title" ask
+  // with a heading.
+  title = title.replace(/^#+\s*/, "").trim();
+  title = stripWrapping(title);
+  // Trailing sentence punctuation — conventional-commit subjects carry none.
+  title = title.replace(/[.\s]+$/, "");
+  if (!title) return undefined;
+
+  const match = CONVENTIONAL_PREFIX_RE.exec(title);
+  const type = match?.[1] ?? DEFAULT_TYPE;
+  const subject = (match?.[2] ?? title).trim();
+  // A bare `feat:` carries no subject, and a type alone is not a title.
+  if (!subject) return undefined;
+
+  return clamp(`${type}: ${subject}`);
+}
+
+/**
+ * Extract the title from the narrative node's reply.
+ *
+ * Last opening tag wins, mirroring `parseNarrative` — a model that narrates the
+ * tag before emitting it must not beat the real one.
+ */
+export function parseTitle(text: string): string | undefined {
+  if (typeof text !== "string") return undefined;
+  const open = text.lastIndexOf(TITLE_OPEN_TAG);
+  if (open === -1) return undefined;
+  const from = open + TITLE_OPEN_TAG.length;
+  const close = text.indexOf(TITLE_CLOSE_TAG, from);
+  return sanitizeTitle(close === -1 ? text.slice(from) : text.slice(from, close));
+}
+
+/**
+ * The title to render, best source first.
+ *
+ * `feat: <feature>` remains the floor: it is what shipped before, it is what
+ * the auto-PR plugin opens with, and it is always available.
+ */
+export function resolveTitle(agentTitle: string | undefined, feature: string): string {
+  return sanitizeTitle(agentTitle) ?? `${DEFAULT_TYPE}: ${feature}`;
+}

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

@@ -312,6 +312,17 @@ const JSON_CONTRACT = [
   "}",
 ].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.
+ */
+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");
+
 /**
  * Build the reviewer prompt.
  *
@@ -329,11 +340,19 @@ const JSON_CONTRACT = [
  */
 export function buildReviewPrompt(
   phase: "spec" | "quality",
-  args: { base: string; specPath: string; since?: string | null; priorFindings?: Finding[] },
+  args: {
+    base: string;
+    specPath: string;
+    since?: string | null;
+    priorFindings?: Finding[];
+    retry?: boolean;
+  },
 ): string {
   const dims = phase === "spec" ? SPEC_REVIEW_DIMENSIONS : QUALITY_REVIEW_DIMENSIONS;
+  const lead = args.retry ? [RETRY_NOTICE] : [];
   if (!args.since) {
     return [
+      ...lead,
       `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).`,
@@ -344,6 +363,7 @@ export function buildReviewPrompt(
     ].join("\n\n");
   }
   return [
+    ...lead,
     `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)}`,

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

@@ -5,4 +5,5 @@ export * from "./escalate";
 export * from "./forge";
 export * from "./git";
 export * from "./pr";
+export * from "./pr-narrative";
 export * from "./result";

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

@@ -0,0 +1,410 @@
+/**
+ * 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, assembled by string joins over the
+ * fields in `FinishPrContext`. Every *section* is reproducible from artifacts
+ * that exist before `open_pr` runs, so the body stays greppable in PR history.
+ *
+ * Two fields are the exception, and both arrive later, from the narrative node
+ * that runs after the PR is already open: `narrative` and `title`. Each has a
+ * deterministic fallback (`resolveNarrative`, `resolveTitle`) so `open_pr` never
+ * waits on a model — see `steps/pr-narrative.ts`.
+ *
+ * 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 { resolveTitle } from "../pr-title";
+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;
+  /**
+   * `--shortstat` for the nax artifacts held out of `diffstat`. Absent when the
+   * branch touched none, so a repo that gitignores them renders nothing.
+   */
+  artifactSummary?: string;
+  /** Repository PR/MR template, verbatim. Absent when none resolves. */
+  template?: string;
+  /** Resolved "What changed" prose. Absent when neither source produced text. */
+  narrative?: string;
+  /**
+   * Resolved conventional-commit PR title. Always set — `resolveTitle` falls
+   * back to `feat: <feature>` when the narrative node produced nothing usable.
+   */
+  title: 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,
+    }));
+}
+
+/**
+ * Pathspec matching nax's own run artifacts, at any depth.
+ *
+ * `**` and the `glob` magic word are both load-bearing. nax writes artifacts
+ * to a repo-root `.nax/` *and* to a per-package `<pkg>/.nax/` — a root-anchored
+ * `:!.nax/**` silently keeps the per-package copy, which is routinely the
+ * largest file in the diff (587 of 2039 insertions on the run that motivated
+ * this). Without `glob`, git's default wildmatch lets `*` cross `/` and the
+ * two forms stop being distinguishable.
+ */
+const NAX_ARTIFACT_PATHSPEC = "**/.nax/**";
+
+/** The two halves of the branch's diff: what is under review, and what was held out. */
+interface DiffstatResult {
+  diffstat?: string;
+  artifactSummary?: string;
+}
+
+/** Run `git diff <...args>` under `workdir`, or `undefined` on any non-happy path. */
+async function runGitDiff(workdir: string, args: string[]): Promise<string | undefined> {
+  try {
+    const res = await _prBodyDeps.run(["git", "diff", ...args], { cwd: workdir });
+    if (res.exitCode !== 0) return undefined;
+    return res.stdout;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Diffstat of the branch, excluding nax's own artifacts.
+ *
+ * The artifacts (`spec.md`, `prd.json`, the generated acceptance test) are
+ * committed and real, but they are the run's exhaust rather than the change
+ * under review, and they dominate the totals — quoting them in the headline
+ * advertises a 2039-line change where 791 lines are reviewable code.
+ * `artifactSummary` keeps them accounted for rather than silently dropped, so
+ * the body still reconciles against `gh pr diff`.
+ *
+ * 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<DiffstatResult> {
+  // 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 {};
+  const range = `${base}...HEAD`;
+  const [diffstat, artifacts] = await Promise.all([
+    runGitDiff(workdir, ["--stat", range, "--", `:(glob,exclude)${NAX_ARTIFACT_PATHSPEC}`]),
+    runGitDiff(workdir, ["--shortstat", range, "--", `:(glob)${NAX_ARTIFACT_PATHSPEC}`]),
+  ]);
+  const summary = artifacts?.trim();
+  return { diffstat, artifactSummary: summary ? summary : 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; title?: 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, stat, 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[],
+    DiffstatResult,
+    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: stat.diffstat,
+    artifactSummary: stat.artifactSummary,
+    template,
+    narrative: resolveNarrative(args.narrative, specSummary),
+    title: resolveTitle(args.title, input.feature),
+    run: {
+      durationMs: status?.durationMs,
+      storiesPassed: status?.progress?.passed,
+      storiesTotal: status?.progress?.total,
+    },
+  };
+}
+
+/**
+ * The PR title: the narrative node's conventional-commit subject when it
+ * produced one, else `feat: <feature>`.
+ *
+ * That fallback is what this returned unconditionally, and is still what
+ * `buildTitle` in `src/plugins/builtin/auto-pr/pr-body.ts` opens with — so a
+ * finish run that reaches `open_pr` before the narrative node has spoken still
+ * reads identically to an auto-PR-opened one in a list view. The two diverge
+ * only once there is something better to say: `feat: schema-drift-gate` names
+ * the run, not the change.
+ */
+export function buildFinishTitle(ctx: FinishPrContext): string {
+  return ctx.title;
+}
+
+/**
+ * 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");
+}
+
+/**
+ * Takes the whole context rather than the five fields it reads: the section
+ * grew past the three-positional-parameter cap in the coding standards, and
+ * every field it wants is already on `FinishPrContext`.
+ */
+function buildVerificationSection(ctx: FinishPrContext): string | null {
+  const { acceptance, regression, gatesRan, diffstat, artifactSummary } = ctx;
+  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\`\`\``);
+  // Stated even though the files are excluded above: a reviewer who diffs the
+  // branch themselves sees more than the diffstat quotes, and an unexplained
+  // mismatch reads as a stale body.
+  if (artifactSummary !== undefined && artifactSummary.length > 0) {
+    lines.push(`- Excluded from diffstat — nax run artifacts: ${artifactSummary}`);
+  }
+  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);
+  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,46 @@
+/**
+ * `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, prTitleOf } 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);
+  const title = prTitleOf(ctx);
+  // Nothing to add: the body already in place is correct, and rewriting it
+  // identically would spend a forge call to change nothing. A title alone is
+  // still worth the call — it is the part a reviewer reads first.
+  if (!narrative && !title) 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,
+      title,
+    });
+    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 };
+  }
+}