@nathapp/nax 0.80.1 → 0.81.0-canary.2

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

@@ -1,150 +0,0 @@
-/**
- * Readers over an acpx `FlowNodeContext` — the flow graph's view of its own
- * state.
- *
- * Split out of `nax-finish.flow.ts` (600-line source cap). These are all pure
- * functions of `ctx.input` / `ctx.outputs` / `ctx.state.steps`; anything that
- * shells out lives under `./steps/`.
- *
- * Two views of the same run, and the difference matters in a graph whose whole
- * shape is loops:
- *
- * - `ctx.outputs` is a map keyed by node id, so it holds only each node's
- *   **latest** output. A node re-entering a loop cannot see its own previous
- *   round there.
- * - `ctx.state.steps` is the ordered history and carries every step's `output`,
- *   so an earlier round IS recoverable from it. A step is appended on its
- *   *outcome*, so the currently-executing node is never in this list — which is
- *   what lets `incrementalSince` find the *previous* review rather than itself.
- */
-import type { AcceptanceStatus } from "./steps/context";
-import type { AcceptanceGroup, Finding, FinishInput, FinishPhase, ReviewVerdict } from "./types";
-
-/** Minimal shapes so each reader takes only the part of the context it reads. */
-export interface StepsCtx {
-  state: { steps: { nodeId: string; output?: unknown }[] };
-}
-export interface OutputsCtx {
-  outputs: unknown;
-}
-
-export const inputOf = (ctx: { input: unknown }) => ctx.input as FinishInput;
-
-/** What `load_ctx` resolves once, for every downstream node to read. */
-export interface LoadCtxOutput {
-  base?: string;
-  specPath?: string;
-  groups?: AcceptanceGroup[];
-  /** `nax features resolve`'s acceptance status, narrowed at `resolveFeature`. */
-  acceptanceStatus?: AcceptanceStatus;
-  /** Test-file regex sources from `nax features resolve`; empty = cannot classify. */
-  testFileRegex?: string[];
-  route?: string;
-  /** Set only when `route` is `escalate` — see `preflight`. */
-  reason?: string;
-}
-
-export function fixAttemptCount(ctx: StepsCtx, fixNodeId: string): number {
-  return (ctx.state.steps ?? []).filter((s) => s.nodeId === fixNodeId).length;
-}
-
-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.
- *
- * Accepts the bare string the node used to return as well as the
- * `{ narrative, title }` it returns now: a flow resumed from a run recorded
- * before the title landed replays the old shape from its journal.
- */
-export function narrativeOf(ctx: OutputsCtx): string | undefined {
-  const out = (ctx.outputs as Record<string, unknown>).narrative;
-  const prose = typeof out === "string" ? out : (out as { narrative?: unknown } | undefined)?.narrative;
-  return typeof prose === "string" && prose.trim().length > 0 ? prose : undefined;
-}
-
-/**
- * The narrative node's parsed PR title, already sanitised by `parseTitle`.
- *
- * Absent whenever the node is — `resolveTitle` then falls back to
- * `feat: <feature>`, which is what shipped before and what auto-PR opens with.
- */
-export function prTitleOf(ctx: OutputsCtx): string | undefined {
-  const out = (ctx.outputs as Record<string, unknown>).narrative;
-  if (typeof out !== "object" || out === null) return undefined;
-  const title = (out as { title?: unknown }).title;
-  return typeof title === "string" && title.trim().length > 0 ? title : undefined;
-}
-
-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[];
-  };
-}
-
-/** The findings the `fix_<phase>` node was asked to resolve; empty for non-review phases. */
-export function findingsOf(ctx: OutputsCtx, phase: FinishPhase): Finding[] {
-  if (phase !== "spec" && phase !== "quality") return [];
-  return (ctx.outputs as Record<string, ReviewVerdict | undefined>)[`review_${phase}`]?.findings ?? [];
-}
-
-/**
- * The ref a re-review should diff from, or null to review the whole branch.
- *
- * A reviewer node re-reads the spec in full and the entire `git diff
- * base...HEAD` on every round. Reviews were 58% of the wall clock on
- * rs-stock/pipeline-run-outcome (7 calls, 1306s of 2232s), and round 3 re-read
- * everything rounds 1-2 had already cleared.
- *
- * The scoping ref is the `shaBefore` of the **first** `commit_*` step after this
- * phase's last review — that commit's parent is, by construction, the tree the
- * previous verdict passed on, since only `commit_*` nodes commit. Taking the
- * first (not the last) is what makes the window complete when more than one
- * commit landed in it, which happens when the acceptance loop commits between a
- * spec fix and its re-review: `firstCommit.shaBefore..HEAD` spans both.
- *
- * Read from `ctx.state.steps[].output`, not `ctx.outputs` — the latter keeps
- * only each node's newest output, which for two commit steps of the same node id
- * would have discarded the earlier `shaBefore` and silently under-scoped the
- * review.
- *
- * Only commit steps that actually **committed** anchor the window. A fix node
- * that edited nothing still records a `commit_*` step, and its `shaBefore` is
- * the current HEAD — so scoping to it asks the reviewer for `HEAD..HEAD`, an
- * empty diff, while the prompt tells it the prior findings "have since been
- * fixed and committed". It returns clean, `route_*` sends the flow onward, and
- * the findings ship unfixed. That leaves the loop through the green door, so
- * `MAX_FIX_ATTEMPTS` never catches it. A no-op round therefore either yields
- * the window to a later real commit, or falls back to a full review.
- *
- * Rounds journalled before `committed` existed carry no such field; `!== false`
- * keeps replaying them on the previous behaviour rather than widening every
- * resumed review to the whole branch.
- *
- * Returns null — a full review — when there is no prior review of this phase
- * (round 1), no commit landed since it (nothing new to look at), or the commit
- * step recorded no `shaBefore`.
- */
-export function incrementalSince(ctx: OutputsCtx & StepsCtx, phase: "spec" | "quality"): string | null {
-  const steps = ctx.state.steps ?? [];
-  const lastReview = steps.map((s) => s.nodeId).lastIndexOf(`review_${phase}`);
-  if (lastReview < 0) return null;
-  const firstCommit = steps
-    .slice(lastReview + 1)
-    .find(
-      (s) => s.nodeId.startsWith("commit_") && (s.output as { committed?: boolean } | undefined)?.committed !== false,
-    );
-  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/narrative.ts

@@ -1,215 +0,0 @@
-/**
- * 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.
- */
-
-import { TITLE_CLOSE_TAG, TITLE_MAX_CHARS, TITLE_OPEN_TAG, parseTitle } from "./pr-title";
-
-/** Longest narrative rendered into a PR body, in characters, including the ellipsis. */
-export const NARRATIVE_MAX_CHARS = 4000;
-
-const TRUNCATION_SUFFIX = "…";
-
-/**
- * Sentinel wrapping the prose, so `parseNarrative` has an explicit anchor
- * rather than an inferred one.
- *
- * acpx hands `parse` the concatenation of *every* agent message chunk in the
- * turn — `chunks.join("")` in its `createQuietCaptureOutput`. This node reads
- * the diff with tools, so the agent's between-tool-call narration ("Now I have
- * a clear picture. Let me check…") is structurally part of that string. A
- * prompt asking for "no preamble" cannot prevent it; only a delimiter can.
- *
- * A sentinel rather than the JSON contract the sibling nodes use: this payload
- * is multi-paragraph prose about code, full of backticks, quotes and newlines.
- * Literal newlines inside a JSON string are invalid JSON, so a JSON contract
- * would fail on exactly the inputs this node exists to carry.
- */
-const OPEN_TAG = "<narrative>";
-const CLOSE_TAG = "</narrative>";
-
-/**
- * Headings the agent emits despite being told not to. Anchors the fallback
- * strip when the sentinel is absent: everything up to and including the
- * heading is preamble.
- */
-const HEADING_RE = /^[\s\S]*?(?:\*\*What changed\*\*|##+\s*What changed)\s*/i;
-
-/** A `<title>…</title>` block, closed or not — removed wholesale from the prose. */
-const TITLE_BLOCK_RE = new RegExp(`${TITLE_OPEN_TAG}[\\s\\S]*?(?:${TITLE_CLOSE_TAG}|$)`, "gi");
-
-/** 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.",
-    "",
-    "Then write the pull request title: a conventional-commit subject describing",
-    `the change (\`fix: …\`, \`feat: …\`, \`refactor: …\`), at most ${TITLE_MAX_CHARS} characters.`,
-    "Describe what the change does — not the feature's name, which the reader",
-    "can already see on the branch.",
-    "",
-    "Reply with exactly these two blocks, and write nothing after the last one:",
-    `${TITLE_OPEN_TAG}conventional-commit subject${TITLE_CLOSE_TAG}`,
-    `${OPEN_TAG}the prose${CLOSE_TAG}`,
-    "",
-    "Everything outside those tags is discarded, so anything you say while working",
-    "through the diff is safe to leave where it falls.",
-  ].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, so every branch below degrades instead of rejecting.
- *
- * Three tiers, strongest anchor first:
- *   1. Sentinel — the contract the prompt asks for.
- *   2. Heading — the agent ignored the sentinel but still wrote
- *      `**What changed**`, which marks where its preamble stopped.
- *   3. Bare trim — no anchor available; better a narrative with preamble than
- *      no narrative at all.
- */
-export function parseNarrative(text: string): string {
-  if (typeof text !== "string") return "";
-
-  // Last opening tag, not the first: if the agent narrates the tag before
-  // emitting it for real ("I'll wrap this in <narrative>"), the real one wins.
-  const open = text.lastIndexOf(OPEN_TAG);
-  if (open !== -1) {
-    const from = open + OPEN_TAG.length;
-    const close = text.indexOf(CLOSE_TAG, from);
-    const inner = (close === -1 ? text.slice(from) : text.slice(from, close)).trim();
-    if (inner) return inner;
-  }
-
-  // Strip tag markers before the heading pass: an empty or malformed sentinel
-  // falls through to here, and leftover `<narrative>` markup in a PR body is
-  // worse than the preamble this function exists to remove. The title block
-  // goes entirely — tags and content — since it is not part of the prose.
-  const untagged = text.replace(TITLE_BLOCK_RE, "").split(OPEN_TAG).join("").split(CLOSE_TAG).join("");
-  return untagged.replace(HEADING_RE, "").trim();
-}
-
-/** What the `narrative` acp node returns: the prose, and the title to rename the PR to. */
-export interface NarrativeNodeResult {
-  narrative: string;
-  title?: string;
-}
-
-/**
- * `parse` for the narrative acp node.
- *
- * Both halves are optional to the flow: a missing title leaves the PR on
- * `feat: <feature>`, and missing prose leaves the body's mechanical sections
- * alone. Never throws, for the reason `parseNarrative` documents.
- */
-export function parseNarrativeNode(text: string): NarrativeNodeResult {
-  return { narrative: parseNarrative(text), title: parseTitle(text) };
-}
-
-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;
-}