@nathapp/nax 0.76.0 → 0.77.0

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

@@ -48,10 +48,22 @@ export function fixAttemptCount(ctx: StepsCtx, fixNodeId: string): number {
 export function loadCtxOf(ctx: OutputsCtx): LoadCtxOutput {
   return ((ctx.outputs as Record<string, LoadCtxOutput | undefined>).load_ctx ?? {}) as LoadCtxOutput;
 }
+/**
+ * The narrative node's parsed prose.
+ *
+ * Absent when the node was skipped by config, died, or produced only
+ * whitespace — `amend_body` treats all three identically, so there is one
+ * branch downstream rather than three.
+ */
+export function narrativeOf(ctx: OutputsCtx): string | undefined {
+  const out = (ctx.outputs as Record<string, unknown>).narrative;
+  return typeof out === "string" && out.trim().length > 0 ? out : undefined;
+}
 
-export function gateOutputs(ctx: OutputsCtx): { failing?: string[] } {
-  return ((ctx.outputs as Record<string, { failing?: string[] } | undefined>).quality_gates ?? {}) as {
+export function gateOutputs(ctx: OutputsCtx): { failing?: string[]; ran?: string[] } {
+  return ((ctx.outputs as Record<string, { failing?: string[]; ran?: string[] } | undefined>).quality_gates ?? {}) as {
     failing?: string[];
+    ran?: string[];
   };
 }
 

package/flows/nax-finish/narrative.ts

@@ -0,0 +1,133 @@
+/**
+ * The PR body's "What changed" section — prompt, parse, and the chain that
+ * decides what text (if any) the section carries.
+ *
+ * Prompt building lives here rather than in `src/prompts/builders/` because
+ * `flows/` is loaded by acpx in its own Node process and imports nothing from
+ * `src/`. `review-prompts.ts` sits beside this file for the same reason.
+ *
+ * `resolveNarrative` is a standalone pure function, not flow wiring, because
+ * the acp node that produces the model text cannot be executed in tests. The
+ * degradation chain is the part that must never break, so it lives where a
+ * test can reach it.
+ */
+
+/** Longest narrative rendered into a PR body, in characters, including the ellipsis. */
+export const NARRATIVE_MAX_CHARS = 4000;
+
+const TRUNCATION_SUFFIX = "…";
+
+/** Headings a spec uses for its lead paragraph, in priority order. */
+const SUMMARY_HEADINGS = ["summary", "overview"] as const;
+
+/**
+ * Prompt for the narrative node.
+ *
+ * Two jobs: point the agent at the real diff (never the spec, which describes
+ * intent rather than what shipped), and forbid restating the sections the body
+ * already renders deterministically.
+ */
+/**
+ * `prompt` for the `narrative` flow node. Lives here rather than inline in
+ * `nax-finish.flow.ts` to keep that file under its 600-line cap — the node
+ * just needs `ctx.outputs.load_ctx.base`, which is all this wrapper reads.
+ */
+export function narrativePrompt(ctx: { outputs: unknown }): string {
+  const base = (ctx.outputs as { load_ctx?: { base?: string } }).load_ctx?.base ?? "origin/main";
+  return buildNarrativePrompt({ base });
+}
+
+export function buildNarrativePrompt(args: { base: string }): string {
+  return [
+    'Write the "What changed" section of a pull request body.',
+    "",
+    `Read the branch diff yourself: \`git diff ${args.base}...HEAD\`.`,
+    "Read whatever source files you need to understand it.",
+    "",
+    "The PR body ALREADY renders these deterministically, from run artifacts:",
+    "- a Stories table (story id, title, acceptance-criteria count)",
+    "- a Verification block (acceptance status, regression status, gates run, diffstat)",
+    "- a Review rounds block (every finding, with its severity)",
+    "- an Out of scope list",
+    "",
+    "Do NOT restate, summarise, or refer to any of them. Repeating them is how the",
+    "written and the generated halves of this body drift apart.",
+    "",
+    "Describe what the change actually does, in prose: the shape of the change, and",
+    "anything a reviewer would otherwise have to reconstruct from the diff by hand.",
+    `Hard limit: ${NARRATIVE_MAX_CHARS} characters.`,
+    "Do not write a heading — the heading is added for you.",
+    "Return the prose only. No JSON, no code fences, no preamble.",
+  ].join("\n");
+}
+
+/**
+ * `parse` for the narrative acp node.
+ *
+ * Never throws. A throw inside `parse` fails the node, and acpx has no error
+ * edge — see `verdict.ts`. Here that would mean the flow dying *after* the PR
+ * was already opened.
+ */
+export function parseNarrative(text: string): string {
+  return typeof text === "string" ? text.trim() : "";
+}
+
+function truncate(text: string): string {
+  if (text.length <= NARRATIVE_MAX_CHARS) return text;
+  return text.slice(0, NARRATIVE_MAX_CHARS - TRUNCATION_SUFFIX.length) + TRUNCATION_SUFFIX;
+}
+
+/**
+ * Pick the narrative text, best source first.
+ *
+ * The spec summary is the fallback rather than the primary source because a
+ * spec describes intent: when an implementation deviates and the deviation is
+ * accepted, a spec-derived narrative confidently describes code that does not
+ * exist.
+ *
+ * `undefined` means "render no section at all" — never an empty heading.
+ */
+export function resolveNarrative(agentText: string | undefined, specSummary: string | null): string | undefined {
+  const fromAgent = agentText?.trim();
+  if (fromAgent) return truncate(fromAgent);
+  const fromSpec = specSummary?.trim();
+  if (fromSpec) return truncate(fromSpec);
+  return undefined;
+}
+
+function sectionBody(lines: string[], heading: string): string | null {
+  const start = lines.findIndex((line) => line.trim().toLowerCase() === `## ${heading}`);
+  if (start === -1) return null;
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex((line) => line.startsWith("## "));
+  const body = (end === -1 ? rest : rest.slice(0, end)).join("\n").trim();
+  return body.length > 0 ? body : null;
+}
+
+/**
+ * First `## Summary` or `## Overview` block in the spec, or `null`.
+ *
+ * Both headings are accepted because both occur in this repository's real
+ * specs — five of six use `## Summary`, the older `plugin-001` uses
+ * `## Overview`. Fail-open on every read error: a missing or unreadable spec
+ * costs the section, never the PR.
+ */
+export async function readSpecSummary(
+  specPath: string | undefined,
+  readText: (path: string) => Promise<string | null>,
+): Promise<string | null> {
+  if (!specPath) return null;
+  let text: string | null;
+  try {
+    text = await readText(specPath);
+  } catch {
+    return null;
+  }
+  if (text === null) return null;
+  const lines = text.split(/\r?\n/);
+  for (const heading of SUMMARY_HEADINGS) {
+    const body = sectionBody(lines, heading);
+    if (body !== null) return body;
+  }
+  return null;
+}

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

@@ -41,18 +41,22 @@
  *   that is killed or times out — no terminal node runs on that path, and a
  *   crashed finish is exactly when the record of what it changed matters most.
  */
-import { defineFlow, extractJsonObject } from "acpx/flows";
+import { defineFlow } from "acpx/flows";
 import { buildFixCommitMessage } from "./commit-message";
 import { findingsOf, fixAttemptCount, gateOutputs, incrementalSince, inputOf, loadCtxOf } from "./flow-ctx";
+import { narrativePrompt, parseNarrative } from "./narrative";
 import { buildReviewPrompt, fixPrompt } from "./review-prompts";
 import {
   _contextDeps,
+  amendPrBodyNode,
   appendRound,
   buildEscalationComment,
   commitAndPush,
   commitFixes,
   detectBaseBranch,
+  detectForge,
   filesInCommit,
+  loadFinishPrContext,
   loadQualityCommands,
   openOrPromotePr,
   partitionTestFiles,
@@ -63,15 +67,28 @@ import {
   runQualityGates,
   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 { MAX_FIX_ATTEMPTS, parseFixVerdict, parseReviewVerdict, repromptCount, routeReview } from "./verdict";
 
 /**
- * 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.
+ * Disabled only on an explicit "0". An unset variable means enabled, so a flow
+ * invoked directly by `acpx flow run` — outside the plugin that sets the env —
+ * still writes the narrative.
  */
-const MAX_FIX_ATTEMPTS = 3;
+const NARRATIVE_ENABLED = process.env.NAX_FINISH_NARRATIVE !== "0";
+
+/**
+ * Injectable seam for the `open_pr` node's title/body assembly — tests stub
+ * these to control the fallback-vs-built-metadata paths without a real PRD or
+ * git checkout.
+ */
+export const _openPrDeps = {
+  loadFinishPrContext,
+  buildFinishTitle,
+  buildFinishBody,
+};
 
 /**
  * Re-run the acceptance gate, routing on the shared fix-cap rules.
@@ -126,50 +143,6 @@ async function acceptanceGateNode(ctx: {
   return { route: "fix", output: r.output };
 }
 
-/**
- * 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.
- */
-function routeReview(
-  ctx: { outputs: unknown; state: { steps: { nodeId: string }[] } },
-  phase: "spec" | "quality",
-): { route: string; escalationReason?: string; findings: ReviewVerdict["findings"] } {
-  const verdict = (ctx.outputs as Record<string, ReviewVerdict | undefined>)[`review_${phase}`];
-  const findings = verdict?.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 };
-}
-
-/**
- * Build the `commit_<phase>` node that follows `fix_<phase>`.
- *
- * One node per phase rather than a single shared one because each returns to a
- * different successor, and acpx routes on the node id — a shared node would
- * need a switch reconstructing which fix ran from the step history.
- *
- * Also the audit seam: this is the only point in the graph where a round's
- * findings and its commit are both known. `ctx.outputs` keeps only the latest
- * output per node, so a round not recorded here is a round no terminal node
- * can reconstruct.
- */
 /**
  * Route for `commit_gate`, whose successor depends on what the fix touched.
  *
@@ -239,6 +212,11 @@ function commitFixNode(phase: FinishPhase) {
         committed,
         findings: findingsOf(ctx, phase),
         ...(phase === "gate" ? { failing: gateOutputs(ctx).failing ?? [] } : {}),
+        // Carry `shaAfter` onto committed rounds only: a no-op round has no
+        // commit, so no SHA to record — keeping the field absent (rather than
+        // null/undefined) lets the result-file reader distinguish "no commit"
+        // from "record lost".
+        ...(committed && shaAfter ? { sha: shaAfter } : {}),
       });
       // Only `commit_gate` routes on this; the other phases have unconditional
       // edges and ignore it.
@@ -253,14 +231,6 @@ function commitFixNode(phase: FinishPhase) {
   };
 }
 
-/** Normalise a reviewer's JSON, rewriting a findings-free `proceed` to `clean`. */
-function parseVerdict(text: string): ReviewVerdict {
-  const raw = extractJsonObject(text) as Partial<ReviewVerdict>;
-  const findings = Array.isArray(raw.findings) ? raw.findings : [];
-  const route = raw.route === "escalate" ? "escalate" : findings.length === 0 ? "clean" : "proceed";
-  return { route, findings, escalationReason: raw.escalationReason };
-}
-
 export default defineFlow({
   name: "nax-finish",
   permissions: {
@@ -295,7 +265,7 @@ export default defineFlow({
     fix_acceptance: {
       nodeType: "acp",
       prompt: (ctx) => fixPrompt("acceptance", ctx),
-      parse: parseVerdict,
+      parse: parseFixVerdict,
     },
     commit_acceptance: commitFixNode("acceptance"),
     review_spec: {
@@ -309,9 +279,10 @@ export default defineFlow({
           specPath: outs.specPath ?? "",
           since: incrementalSince(ctx, "spec"),
           priorFindings: findingsOf(ctx, "spec"),
+          retry: repromptCount(ctx, "spec") > 0,
         });
       },
-      parse: parseVerdict,
+      parse: parseReviewVerdict,
     },
     route_spec: {
       nodeType: "compute",
@@ -320,7 +291,7 @@ export default defineFlow({
     fix_spec: {
       nodeType: "acp",
       prompt: (ctx) => fixPrompt("spec", ctx),
-      parse: parseVerdict,
+      parse: parseFixVerdict,
     },
     commit_spec: commitFixNode("spec"),
     review_quality: {
@@ -334,9 +305,10 @@ export default defineFlow({
           specPath: outs.specPath ?? "",
           since: incrementalSince(ctx, "quality"),
           priorFindings: findingsOf(ctx, "quality"),
+          retry: repromptCount(ctx, "quality") > 0,
         });
       },
-      parse: parseVerdict,
+      parse: parseReviewVerdict,
     },
     route_quality: {
       nodeType: "compute",
@@ -345,13 +317,13 @@ export default defineFlow({
     fix_quality: {
       nodeType: "acp",
       prompt: (ctx) => fixPrompt("quality", ctx),
-      parse: parseVerdict,
+      parse: parseFixVerdict,
     },
     commit_quality: commitFixNode("quality"),
     fix_gate: {
       nodeType: "acp",
       prompt: (ctx) => fixPrompt("gate", ctx),
-      parse: parseVerdict,
+      parse: parseFixVerdict,
     },
     commit_gate: commitFixNode("gate"),
     quality_gates: {
@@ -430,23 +402,65 @@ export default defineFlow({
       nodeType: "action",
       async run(ctx) {
         const i = inputOf(ctx);
-        if (loadCtxOf(ctx).route === "nothing-to-finish") {
+        const loadCtx = loadCtxOf(ctx);
+        if (loadCtx.route === "nothing-to-finish") {
           await writeResult(i, { feature: i.feature, status: "nothing-to-finish" });
           return { route: "done", status: "nothing-to-finish" };
         }
         // Every fix node edited the working tree; without this the PR would be
         // opened from a remote branch missing all of them.
         const sync = await commitAndPush(i.workdir, i.branch, `fix(${i.feature}): nax-finish automated fixes`);
-        const r = await openOrPromotePr(
-          i.workdir,
-          i.branch,
-          `nax-finish: ${i.feature}`,
-          `Automated finish of \`${i.feature}\`.`,
-        );
+
+        const fallbackTitle = `nax-finish: ${i.feature}`;
+        const fallbackBody = `Automated finish of \`${i.feature}\`.`;
+        let title = fallbackTitle;
+        let body = fallbackBody;
+        // Detected once, here, and handed to both the body builder (which needs
+        // it for the repo template) and the opener. Detecting in both would let
+        // them disagree. On a throw it stays undefined and `openOrPromotePr`
+        // detects for itself, exactly as it did before.
+        let forge: Forge | undefined;
+        try {
+          forge = await detectForge(_prBodyDeps.run, i.workdir, "finish-pr");
+          const prCtx = await _openPrDeps.loadFinishPrContext(i, {
+            base: loadCtx.base ?? "",
+            gatesRan: gateOutputs(ctx).ran ?? [],
+            forge,
+            specPath: loadCtx.specPath,
+          });
+          title = _openPrDeps.buildFinishTitle(prCtx);
+          body = _openPrDeps.buildFinishBody(prCtx);
+        } catch (error) {
+          _prBodyDeps.warn("[finish-pr] Falling back to default PR title/body", { path: i.prdPath, error });
+          title = fallbackTitle;
+          body = fallbackBody;
+        }
+
+        const r = await openOrPromotePr(i.workdir, i.branch, title, body, forge);
         await writeResult(i, { feature: i.feature, status: r.status, url: r.url });
-        return { route: "done", committed: sync.committed, ...r };
+        // The PR now exists with the mechanical narrative already in place.
+        // Anything the narrative node does from here is an improvement on a
+        // body that is already correct.
+        return { route: NARRATIVE_ENABLED ? "narrate" : "done", committed: sync.committed, ...r };
       },
     },
+    narrative: {
+      nodeType: "acp",
+      session: { isolated: true },
+      profile: process.env.NAX_FINISH_NARRATIVE_PROFILE || undefined,
+      prompt: narrativePrompt,
+      parse: parseNarrative,
+    },
+    amend_body: {
+      nodeType: "action",
+      run: amendPrBodyNode,
+    },
+    // Inert terminal. acpx switch cases must name a real node, so the `done`
+    // route out of open_pr needs somewhere to land.
+    finish_done: {
+      nodeType: "compute",
+      run: () => ({ route: "done" }),
+    },
     escalate: {
       nodeType: "action",
       async run(ctx) {
@@ -525,7 +539,10 @@ export default defineFlow({
     { from: "review_spec", to: "route_spec" },
     {
       from: "route_spec",
-      switch: { on: "$.route", cases: { clean: "review_quality", fix: "fix_spec", escalate: "escalate" } },
+      switch: {
+        on: "$.route",
+        cases: { clean: "review_quality", fix: "fix_spec", escalate: "escalate", reprompt: "review_spec" },
+      },
     },
     // Spec fixes re-run the acceptance gate first (they can break it), and the
     // acceptance node's `proceed` edge leads back into review_spec for re-review.
@@ -534,7 +551,10 @@ export default defineFlow({
     { from: "review_quality", to: "route_quality" },
     {
       from: "route_quality",
-      switch: { on: "$.route", cases: { clean: "quality_gates", fix: "fix_quality", escalate: "escalate" } },
+      switch: {
+        on: "$.route",
+        cases: { clean: "quality_gates", fix: "fix_quality", escalate: "escalate", reprompt: "review_quality" },
+      },
     },
     // Quality fixes are re-reviewed by the same lens; the repo-root gates that
     // follow catch anything the fix broke mechanically.
@@ -564,5 +584,9 @@ export default defineFlow({
         cases: { changed: "review_quality", "tests-only": "quality_gates", unchanged: "quality_gates" },
       },
     },
+    // The narrative runs only once the PR exists. acpx has no error edge, so an
+    // acp node before `open_pr` would be able to fail the flow and cost the PR.
+    { from: "open_pr", switch: { on: "$.route", cases: { narrate: "narrative", done: "finish_done" } } },
+    { from: "narrative", to: "amend_body" },
   ],
 });

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

@@ -0,0 +1,56 @@
+/**
+ * Repository PR/MR template discovery, ported from
+ * `src/plugins/builtin/auto-pr/template.ts`.
+ *
+ * Ported rather than imported: `flows/` is loaded by acpx in its own Node
+ * process, where nax's `src/` and its `@/*` alias do not exist. This matches
+ * the convention already in this directory — `errors.ts`, `exec.ts`, `types.ts`
+ * and the PR body builder are all flow-local re-implementations.
+ *
+ * The duplication is stable: these candidate paths are an external convention
+ * set by GitHub and GitLab, not internal logic that drifts with the codebase.
+ *
+ * Why preserve-not-fill: passing `--body` / `--description` to `gh` / `glab`
+ * suppresses the repo's default template, so it must be read and re-embedded.
+ */
+import { join } from "node:path";
+import type { Forge } from "./steps/forge";
+
+/**
+ * Candidate template paths for GitHub, in priority order.
+ * Multi-template directories (`PULL_REQUEST_TEMPLATE/`) are intentionally
+ * skipped because they are ambiguous unattended.
+ */
+const GITHUB_TEMPLATE_PATHS: readonly string[] = [
+  ".github/PULL_REQUEST_TEMPLATE.md",
+  ".github/pull_request_template.md",
+  "PULL_REQUEST_TEMPLATE.md",
+  "docs/PULL_REQUEST_TEMPLATE.md",
+] as const;
+
+/** Preferred single-template location for GitLab. */
+const GITLAB_DEFAULT_TEMPLATE_PATH = ".gitlab/merge_request_templates/Default.md";
+
+/** Only `readText` is consulted, so any caller with a file reader can supply it. */
+export interface TemplateDeps {
+  readText: (path: string) => Promise<string | null>;
+}
+
+async function firstExisting(workdir: string, deps: TemplateDeps, paths: readonly string[]): Promise<string | null> {
+  for (const relPath of paths) {
+    const content = await deps.readText(join(workdir, relPath));
+    if (content !== null) return content;
+  }
+  return null;
+}
+
+/**
+ * Locate the PR/MR template for the current repository.
+ *
+ * @returns Template text verbatim, or `null` when none resolves — which is the
+ *          common case and never an error.
+ */
+export async function findPrTemplate(workdir: string, forge: Forge, deps: TemplateDeps): Promise<string | null> {
+  if (forge === "github") return firstExisting(workdir, deps, GITHUB_TEMPLATE_PATHS);
+  return firstExisting(workdir, deps, [GITLAB_DEFAULT_TEMPLATE_PATH]);
+}

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";