@nathapp/nax 0.77.2 → 0.78.0

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

@@ -0,0 +1,253 @@
+/**
+ * Merge nax's generated PR/MR body into the repository's own PR template.
+ *
+ * ## Why this exists
+ *
+ * `gh pr create --body` / `glab mr create --description` suppress the repo's
+ * template, so a generated body has to account for it. The first attempt
+ * appended the template verbatim after the generated content, which shipped a
+ * *blank form* below a filled one: placeholder comments, a dangling `Closes #`,
+ * duplicated headings, and an unchecked "`bun test` passes" box sitting under a
+ * Verification section that already said the gates were green (nax#1504).
+ *
+ * A PR template is an input form, not decoration. So the template is treated as
+ * **shape** and nax's content as **fill**:
+ *
+ * - a template heading nax can fill  → keep the heading, replace its body
+ * - a template heading nax cannot    → drop it (`merge`) or empty it (`strict`)
+ * - nax content with no home         → append under nax's own heading
+ *
+ * The governing invariant is **never emit a field that was not filled**. That
+ * is the same rule `buildFinishBody` already followed for its own sections
+ * (nax#1477 forbids a bare heading with nothing under it); this module extends
+ * it to template-derived text. `strict` mode is the one deliberate exception,
+ * for repos whose CI asserts a set of headings exists.
+ *
+ * ## Why deterministic
+ *
+ * Placement is decided by a heading-alias table, not by a model. The facts in
+ * the body — gate results, story counts, diffstat, review rounds — stay a pure
+ * string join, which is what keeps a finish body greppable in PR history. A
+ * repo whose headings the table does not know loses nothing: its sections are
+ * dropped and nax's own headings are used instead, and `sectionMap` pins the
+ * mapping explicitly when a team wants its headings honoured.
+ *
+ * Lives under `flows/` (and is imported from `src/` via `@flows/*`, not
+ * re-implemented) because `flows/` is the more constrained runtime — acpx runs
+ * it in its own Node process where `Bun` and the `@/*` alias do not exist. Code
+ * that satisfies that constraint runs in both places; the reverse is not true.
+ */
+
+/** One nax-authored section of the body. */
+export interface BodySection {
+  /**
+   * Stable id matched against the alias table. Independent of `heading` so
+   * renaming nax's own heading does not silently break template matching.
+   */
+  key: string;
+  /**
+   * nax's H2 text, used when the section is appended rather than merged.
+   * Empty means headingless (the run footer) — such a section is rendered as
+   * bare text and is never matched to a template heading, so a stray alias
+   * cannot bury the footer under someone's `## Notes`.
+   */
+  heading: string;
+  /** Markdown body without its heading line. Callers omit empty sections. */
+  body: string;
+}
+
+/**
+ * - `merge`  — template headings nax cannot fill are dropped. Default.
+ * - `strict` — they are kept, empty, for repos with heading-checking CI.
+ * - `ignore` — the template is not consulted at all.
+ */
+export type TemplateMode = "merge" | "strict" | "ignore";
+
+export interface MergeOptions {
+  mode?: TemplateMode;
+  /**
+   * Normalised template heading → `BodySection.key`, layered over
+   * `DEFAULT_SECTION_ALIASES`. An empty value suppresses a default alias,
+   * which is how a repo says "do not put anything under this heading".
+   */
+  sectionMap?: Record<string, string>;
+}
+
+/**
+ * Normalised heading → section key.
+ *
+ * Deliberately partial. `why`, `notes`, `screenshots` and friends are absent
+ * because nax has nothing truthful to put under them — an alias that mapped
+ * them to some loosely-related section would reintroduce exactly the
+ * unfilled-field problem this module exists to remove.
+ */
+export const DEFAULT_SECTION_ALIASES: Record<string, string> = {
+  // → narrative
+  what: "narrative",
+  "what changed": "narrative",
+  "whats changed": "narrative",
+  summary: "narrative",
+  description: "narrative",
+  overview: "narrative",
+  changes: "narrative",
+  "what does this do": "narrative",
+  "what does this mr do and why": "narrative",
+  "what does this pr do": "narrative",
+  // → stories
+  how: "stories",
+  implementation: "stories",
+  "implementation details": "stories",
+  "changes made": "stories",
+  approach: "stories",
+  design: "stories",
+  // → verification
+  testing: "verification",
+  tests: "verification",
+  "test plan": "verification",
+  verification: "verification",
+  qa: "verification",
+  validation: "verification",
+  "how to test": "verification",
+  "how has this been tested": "verification",
+  "how to set up and validate locally": "verification",
+};
+
+const HEADING_RE = /^##[ \t]+(.+?)[ \t]*$/;
+const FRONTMATTER_RE = /^---[ \t]*\r?\n[\s\S]*?\r?\n---[ \t]*(?:\r?\n|$)/;
+const HTML_COMMENT_RE = /<!--[\s\S]*?-->/g;
+/** `Closes #`, `Fixes # (issue)` — an issue reference with no issue. */
+const DANGLING_ISSUE_RE = /^[ \t]*(?:closes?|fixe?s?|resolves?)[ \t]*:?[ \t]*#[ \t]*(?:\([^)]*\))?[ \t]*$/i;
+/** An unticked task-list item — an unfilled field wherever it appears. */
+const UNCHECKED_BOX_RE = /^[ \t]*[-*+][ \t]+\[[ \t]\]/;
+
+interface TemplateSection {
+  heading: string;
+  body: string;
+}
+
+interface ParsedTemplate {
+  frontmatter: string;
+  preamble: string;
+  sections: TemplateSection[];
+}
+
+/** Lowercase, drop punctuation, collapse whitespace — so `## Testing:` matches `testing`. */
+function normalizeHeading(heading: string): string {
+  return heading
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/**
+ * Strip placeholders from template-derived prose.
+ *
+ * Only ever applied to the preamble — the one template region that survives
+ * into the body. Text under a matched heading is replaced wholesale and text
+ * under an unmatched one is discarded, so a checklist or a stale `Closes #`
+ * *inside a section* never reaches this function, which is why there is no
+ * checkbox-versus-gate reconciliation anywhere in this module.
+ *
+ * The preamble is the exception, because a template may open with a
+ * contributor checklist before its first heading. An unticked box there is an
+ * unfilled field like any other, so it is dropped while the prose around it is
+ * kept.
+ */
+function cleanTemplateText(text: string): string {
+  return text
+    .replace(HTML_COMMENT_RE, "")
+    .split("\n")
+    .filter((line) => !DANGLING_ISSUE_RE.test(line) && !UNCHECKED_BOX_RE.test(line))
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .trim();
+}
+
+function parseTemplate(rawText: string): ParsedTemplate {
+  // Normalised up front so a CRLF template (anything authored on Windows, or
+  // fetched through a forge web editor) cannot leak a stray carriage return
+  // into a heading this module re-emits.
+  const text = rawText.replace(/\r\n/g, "\n");
+  const frontmatterMatch = FRONTMATTER_RE.exec(text);
+  const frontmatter = frontmatterMatch ? frontmatterMatch[0].trimEnd() : "";
+  const rest = frontmatterMatch ? text.slice(frontmatterMatch[0].length) : text;
+
+  const preambleLines: string[] = [];
+  const sections: TemplateSection[] = [];
+  let current: { heading: string; lines: string[] } | null = null;
+
+  for (const line of rest.split("\n")) {
+    const heading = HEADING_RE.exec(line);
+    if (heading) {
+      if (current) sections.push({ heading: current.heading, body: current.lines.join("\n") });
+      current = { heading: heading[1], lines: [] };
+      continue;
+    }
+    if (current) current.lines.push(line);
+    else preambleLines.push(line);
+  }
+  if (current) sections.push({ heading: current.heading, body: current.lines.join("\n") });
+
+  return { frontmatter, preamble: preambleLines.join("\n"), sections };
+}
+
+function renderSection(heading: string, body: string): string {
+  if (heading.length === 0) return body;
+  return body.length === 0 ? `## ${heading}` : `## ${heading}\n\n${body}`;
+}
+
+/** Nax-only body: every section under its own heading, in the order given. */
+function renderSections(sections: BodySection[]): string {
+  return sections
+    .filter((s) => s.body.trim().length > 0)
+    .map((s) => renderSection(s.heading, s.body.trim()))
+    .join("\n\n")
+    .trim();
+}
+
+export function mergeTemplate(
+  template: string | null | undefined,
+  sections: BodySection[],
+  opts: MergeOptions = {},
+): string {
+  const mode = opts.mode ?? "merge";
+  if (mode === "ignore" || !template || template.trim().length === 0) return renderSections(sections);
+
+  const parsed = parseTemplate(template);
+  // No H2 anywhere: the template is prose, or nests everything under H1/H3.
+  // There is no shape to merge into, and appending it unparsed is the defect
+  // this module removes — so fall back to the body nax would have written.
+  if (parsed.sections.length === 0) return renderSections(sections);
+
+  // Override keys go through the same normalisation as the template headings
+  // they are matched against, so a repo pins a heading by pasting it —
+  // `"What does this MR do and why?"` — not by hand-normalising it first.
+  const aliases = { ...DEFAULT_SECTION_ALIASES };
+  for (const [heading, key] of Object.entries(opts.sectionMap ?? {})) aliases[normalizeHeading(heading)] = key;
+  const fillable = sections.filter((s) => s.heading.length > 0 && s.body.trim().length > 0);
+  const consumed = new Set<string>();
+  const parts: string[] = [];
+
+  if (parsed.frontmatter.length > 0) parts.push(parsed.frontmatter);
+  const preamble = cleanTemplateText(parsed.preamble);
+  if (preamble.length > 0) parts.push(preamble);
+
+  for (const templateSection of parsed.sections) {
+    const key = aliases[normalizeHeading(templateSection.heading)];
+    const match = key ? fillable.find((s) => s.key === key && !consumed.has(s.key)) : undefined;
+    if (match) {
+      consumed.add(match.key);
+      parts.push(renderSection(templateSection.heading, match.body.trim()));
+    } else if (mode === "strict") {
+      parts.push(renderSection(templateSection.heading, ""));
+    }
+  }
+
+  for (const section of sections) {
+    if (consumed.has(section.key) || section.body.trim().length === 0) continue;
+    parts.push(renderSection(section.heading, section.body.trim()));
+  }
+
+  return parts.join("\n\n").trim();
+}

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

@@ -334,9 +334,12 @@ const RETRY_NOTICE = [
  * available — it is told to open whatever the fix touches — it just is not asked
  * to re-derive a verdict on unchanged code.
  *
- * `since` is only ever supplied when exactly one commit separates the two
- * reviews (see `incrementalSince`), so `since..HEAD` provably contains every
- * change made since the previous verdict.
+ * `since` is the parent of the *first* commit that landed after the previous
+ * verdict, not of the latest one (see `incrementalSince`) — the acceptance loop
+ * can commit between a spec fix and its re-review, and the window has to span
+ * both. So `since..HEAD` provably contains every change made since that
+ * verdict, however many commits that took, and it is never supplied at all when
+ * no commit landed.
  */
 export function buildReviewPrompt(
   phase: "spec" | "quality",

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

@@ -0,0 +1,64 @@
+/**
+ * Assembling the audit round a `commit_<phase>` node records.
+ *
+ * Split out of `nax-finish.flow.ts` for room — that file sits against the
+ * 600-line source cap — but the split earns its keep independently: the round's
+ * shape is a data decision with four conditional fields, and it is now unit
+ * testable without driving a flow node through a git mock.
+ *
+ * Pairs with `./review-round`, which records the rounds that produce no commit.
+ */
+import type { Finding, 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"];
+
+/**
+ * What produced this round, given the successor the commit routed to.
+ *
+ * The `route` argument is why this is computed after the commit rather than
+ * alongside it: `tests-only` is only known once the committed paths have been
+ * classified, and it is the difference between "no reviewer exists for this
+ * phase" and "a reviewer exists, was owed a look, and was skipped".
+ */
+export function commitRoundOutcome(phase: FinishPhase, route: string): FinishRoundOutcome {
+  if (REVIEWED_PHASES.includes(phase)) return "fixed";
+  // Only `gate` can skip an owed re-review; `acceptance` has no reviewer to
+  // skip, so its `tests-only`-shaped routes (it has none today) stay honest.
+  if (phase === "gate" && route === "tests-only") return "review-skipped";
+  return "no-reviewer";
+}
+
+export interface CommitRoundInput {
+  phase: FinishPhase;
+  attempt: number;
+  committed: boolean;
+  /** The successor this commit routed to — see `commitRoundOutcome`. */
+  route: string;
+  findings: Finding[];
+  /** Gate commands that were red this round; omitted for non-gate phases. */
+  failing?: string[];
+  /** Post-commit HEAD, when there was a commit. */
+  shaAfter?: string | null;
+  now: string;
+}
+
+/**
+ * Build the round record for a commit checkpoint.
+ *
+ * `sha` and `failing` are omitted rather than set to null/undefined: a reader of
+ * the JSONL distinguishes "no commit" from "record lost" by the key's absence,
+ * and that only works if absence is never used to mean anything else.
+ */
+export function buildCommitRound(i: CommitRoundInput): FinishRound {
+  return {
+    ts: i.now,
+    phase: i.phase,
+    attempt: i.attempt,
+    committed: i.committed,
+    outcome: commitRoundOutcome(i.phase, i.route),
+    findings: i.findings,
+    ...(i.failing ? { failing: i.failing } : {}),
+    ...(i.committed && i.shaAfter ? { sha: i.shaAfter } : {}),
+  };
+}

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

@@ -12,10 +12,35 @@ export async function detectBaseBranch(workdir: string): Promise<string> {
   return main.exitCode === 0 ? "origin/main" : "origin/master";
 }
 
+/**
+ * The acceptance resolutions this flow knows how to route on, as emitted by
+ * `resolveFeatureAcceptance` (`src/cli/features-acceptance.ts`).
+ *
+ * A closed set, not `string`: `steps/gates.ts` branches on all three by literal
+ * — `disabled` decides whether the acceptance gate runs at all — and a typo in
+ * any of those comparisons against a `string` compiles cleanly and silently
+ * stops a gate from firing.
+ */
+export type AcceptanceStatus = "ok" | "no-prd" | "disabled";
+
+const ACCEPTANCE_STATUSES: readonly AcceptanceStatus[] = ["ok", "no-prd", "disabled"];
+
+/**
+ * Narrow the resolver's status, degrading anything unrecognised to `no-prd`.
+ *
+ * A status this flow cannot interpret is not a licence to proceed: it is
+ * neither the explicit opt-out nor a resolution to trust. `no-prd` routes to
+ * `escalate`, which is the honest answer and matches the existing default for
+ * a status that is missing entirely.
+ */
+export function toAcceptanceStatus(raw: unknown): AcceptanceStatus {
+  return ACCEPTANCE_STATUSES.find((s) => s === raw) ?? "no-prd";
+}
+
 export interface FeatureResolution {
   specPath: string;
   specKind: "markdown" | "prd";
-  acceptanceStatus: string;
+  acceptanceStatus: AcceptanceStatus;
   groups: AcceptanceGroup[];
   /**
    * Test-file classification regexes, as sources, from `nax features resolve`
@@ -57,7 +82,7 @@ export async function resolveFeature(feature: string, workdir: string): Promise<
   return {
     specPath: parsed.specSource.path,
     specKind: parsed.specSource.kind,
-    acceptanceStatus: parsed.acceptance?.status ?? "no-prd",
+    acceptanceStatus: toAcceptanceStatus(parsed.acceptance?.status),
     groups: parsed.acceptance?.groups ?? [],
     testFileRegex: parsed.testPatterns?.regex ?? [],
   };
@@ -92,11 +117,42 @@ export function partitionTestFiles(paths: string[], regexSources: string[]): { t
   return { test, nonTest };
 }
 
-export async function preflight(
-  workdir: string,
-  base: string,
-): Promise<{ commitsAhead: number; route: "proceed" | "nothing-to-finish" }> {
+export interface PreflightOutcome {
+  commitsAhead: number;
+  route: "proceed" | "nothing-to-finish" | "escalate";
+  /** Set only on `escalate` — why the count could not be trusted. */
+  reason?: string;
+}
+
+/**
+ * How far ahead of the base branch this branch is.
+ *
+ * A failed count must never be reported as zero. `base` reaches here from
+ * `detectBaseBranch`, whose last-resort `origin/master` is returned without
+ * being verified — so a repo whose base ref is not fetched locally makes
+ * `rev-list` exit non-zero with empty stdout. `Number.parseInt("") || 0` turned
+ * that into `0`, indistinguishable from "this branch has no new commits", and
+ * the flow reported `nothing-to-finish` having reviewed, verified and pushed
+ * nothing. Both the non-zero exit and unreadable output escalate instead: a
+ * human can fetch the base, and no fix node can.
+ */
+export async function preflight(workdir: string, base: string): Promise<PreflightOutcome> {
   const res = await _contextDeps.run(["git", "rev-list", "--count", `${base}..HEAD`], { cwd: workdir });
-  const commitsAhead = Number.parseInt(res.stdout.trim(), 10) || 0;
+  if (res.exitCode !== 0) {
+    const detail = res.stderr.trim() || res.stdout.trim() || `exit ${res.exitCode}`;
+    return {
+      commitsAhead: 0,
+      route: "escalate",
+      reason: `Could not count commits against "${base}" — git rev-list failed: ${detail}. The base branch may not exist locally; nax-finish will not treat that as "nothing to finish".`,
+    };
+  }
+  const commitsAhead = Number.parseInt(res.stdout.trim(), 10);
+  if (!Number.isFinite(commitsAhead)) {
+    return {
+      commitsAhead: 0,
+      route: "escalate",
+      reason: `git rev-list --count ${base}..HEAD exited 0 but printed no readable count: "${res.stdout.trim()}".`,
+    };
+  }
   return { commitsAhead, route: commitsAhead > 0 ? "proceed" : "nothing-to-finish" };
 }

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

@@ -0,0 +1,183 @@
+/**
+ * The two gate nodes — `acceptance` and `quality_gates`.
+ *
+ * Split out of `nax-finish.flow.ts`, which sits against the 600-line source
+ * cap. They belong together: both answer the same question ("did anything
+ * actually verify this tree?"), both enforce the same rule that **nothing ran
+ * is not a pass**, and both route on the shared `MAX_FIX_ATTEMPTS` cap.
+ *
+ * Keeping them out of the flow file also makes them callable in tests without
+ * reaching through `flow.nodes.*`.
+ */
+import { fixAttemptCount, inputOf, loadCtxOf } from "../flow-ctx";
+import { MAX_FIX_ATTEMPTS } from "../verdict";
+import { runAcceptanceGate } from "./acceptance";
+import { type QualityCommands, loadQualityCommands, runQualityGates } from "./quality";
+
+/** The slice of an acpx `FlowNodeContext` these nodes read. */
+export interface GateNodeCtx {
+  input: unknown;
+  outputs: unknown;
+  state: { steps: { nodeId: string }[] };
+}
+
+export interface AcceptanceNodeOutput {
+  route: string;
+  reason?: string;
+  output: string;
+}
+
+export interface QualityGatesNodeOutput {
+  route: string;
+  reason?: string;
+  ran: string[];
+  failing: string[];
+  output: string;
+}
+
+/** The repo's explicit opt-out, as reported by `nax features resolve`. */
+function acceptanceDisabled(ctx: GateNodeCtx): boolean {
+  return loadCtxOf(ctx).acceptanceStatus === "disabled";
+}
+
+/**
+ * Re-run the acceptance gate, routing on the shared fix-cap rules.
+ *
+ * "Nothing ran" is not a pass — the same rule `quality_gates` applies to an
+ * unconfigured repo. `nax features resolve` reports `groups: []` for `no-prd`,
+ * for `disabled`, **and** for an `ok` resolution whose PRD grouped to no
+ * package at all; it reports `exists: false` for a group whose test was
+ * expected at its canonical path but never generated. Treating any of those as
+ * green let the flow open a ready PR having verified nothing about the
+ * feature's own contract (#1398). Only `disabled` — the repo's explicit opt-out
+ * — skips cleanly.
+ */
+export async function acceptanceGateNode(ctx: GateNodeCtx): Promise<AcceptanceNodeOutput> {
+  const i = inputOf(ctx);
+  const { groups = [], acceptanceStatus } = loadCtxOf(ctx);
+  if (acceptanceStatus === "disabled") {
+    return { route: "proceed", output: "[acceptance] disabled in .nax/config.json — skipping" };
+  }
+  if (acceptanceStatus === "no-prd") {
+    return {
+      route: "escalate",
+      reason: `Acceptance targets could not be computed (status: no-prd) — nothing was verified for "${i.feature}".`,
+      output: "[acceptance] no prd.json resolved — acceptance targets unknown",
+    };
+  }
+
+  const r = await runAcceptanceGate(i.workdir, groups, { timeoutMs: i.timeouts?.acceptanceMs });
+  if (r.passed) {
+    // A real failure below routes to the fix loop, which is more actionable;
+    // the coverage hole is only reported once the runnable groups are green.
+    if (r.missing.length > 0) {
+      return {
+        route: "escalate",
+        reason: `Acceptance test never generated for: ${r.missing.join(", ")} — that package's contract is unverified.`,
+        output: r.output,
+      };
+    }
+    // Passed, nothing missing, and nothing ran: the resolver produced no group
+    // to run at all. `status: "ok"` does NOT imply a target exists — it means
+    // the PRD loaded — so this is the one remaining way an empty gate reports
+    // green. Escalating matches what `runQualityGates` does for a repo with no
+    // configured commands: an LLM fix node cannot invent the missing target.
+    if (r.ran === 0) {
+      return {
+        route: "escalate",
+        reason: `No acceptance test target resolved for "${i.feature}" (status: ${acceptanceStatus ?? "unknown"}) — nothing verified its contract.`,
+        output: r.output,
+      };
+    }
+    return { route: "proceed", output: r.output };
+  }
+  const attempts = fixAttemptCount(ctx, "fix_acceptance");
+  if (attempts >= MAX_FIX_ATTEMPTS) {
+    return {
+      route: "escalate",
+      reason: `Acceptance tests still failing after ${attempts} fix attempts.`,
+      output: r.output,
+    };
+  }
+  return { route: "fix", output: r.output };
+}
+
+/**
+ * Acceptance is gate zero here, not just at the `acceptance` node.
+ *
+ * Both fix loops that run after it — quality review and this gate — edit code,
+ * and the repo-root `test` command does not cover the feature's acceptance
+ * tests: they live under `<pkg>/.nax/features/<f>/` and usually need their own
+ * runner config. Re-running them here is what makes "nothing reaches open_pr
+ * without the feature's own contract passing against the tree as it will ship"
+ * true on every path (#1398).
+ *
+ * Unconditional apart from the repo's own opt-out, though the common green path
+ * re-runs a gate that already passed: acceptance is the cheapest gate in the
+ * pipeline, and a conditional skip derived from step history would be a check
+ * that can be *wrong* — a silent false green, the failure mode this exists to
+ * prevent. The `disabled` skip is not such a derivation: it is the same
+ * resolver field the `acceptance` node already honours, and the two nodes
+ * disagreeing about who owns the opt-out is its own bug.
+ *
+ * `missing` is deliberately ignored: groups are resolved once at load_ctx, so a
+ * coverage hole was already escalated by the acceptance node and cannot appear
+ * here.
+ */
+async function reverifyAcceptance(ctx: GateNodeCtx): Promise<QualityGatesNodeOutput | null> {
+  if (acceptanceDisabled(ctx)) return null;
+  const i = inputOf(ctx);
+  const acc = await runAcceptanceGate(i.workdir, loadCtxOf(ctx).groups ?? [], {
+    timeoutMs: i.timeouts?.acceptanceMs,
+  });
+  if (acc.passed) return null;
+  // Short-circuit: the repo gates are re-run next round anyway, and skipping
+  // them keeps this out of the "nothing configured" branch below, which would
+  // otherwise misreport configured-but-skipped commands as absent.
+  const attempts = fixAttemptCount(ctx, "fix_gate");
+  const failing = ["acceptance"];
+  if (attempts >= MAX_FIX_ATTEMPTS) {
+    return {
+      route: "escalate",
+      reason: `A later fix broke the feature's own contract: acceptance still failing after ${attempts} fix attempts.`,
+      ran: [],
+      failing,
+      output: acc.output,
+    };
+  }
+  return { route: "fix", ran: [], failing, output: acc.output };
+}
+
+export async function qualityGatesNode(ctx: GateNodeCtx): Promise<QualityGatesNodeOutput> {
+  const i = inputOf(ctx);
+
+  const accFailure = await reverifyAcceptance(ctx);
+  if (accFailure) return accFailure;
+
+  const cmds: QualityCommands = await loadQualityCommands(i.workdir);
+  const r = await runQualityGates(i.workdir, cmds, { timeoutMs: i.timeouts?.gateMs });
+  if (r.passed) return { route: "green", ran: r.ran, failing: r.failing, output: r.output };
+  // Nothing configured is not a pass — escalate immediately rather than open a
+  // "ready" PR having verified nothing. An LLM fix node cannot invent the
+  // repo's build/test commands.
+  if (r.ran.length === 0) {
+    return {
+      route: "escalate",
+      reason: "No quality.commands configured in .nax/config.json — nax-finish verified nothing.",
+      ran: r.ran,
+      failing: r.failing,
+      output: r.output,
+    };
+  }
+  const attempts = fixAttemptCount(ctx, "fix_gate");
+  if (attempts >= MAX_FIX_ATTEMPTS) {
+    return {
+      route: "escalate",
+      reason: `Quality gates still failing after ${attempts} fix attempts (${r.failing.join(", ")}).`,
+      ran: r.ran,
+      failing: r.failing,
+      output: r.output,
+    };
+  }
+  return { route: "fix", ran: r.ran, failing: r.failing, output: r.output };
+}

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

@@ -1,9 +1,12 @@
 export * from "./context";
 export * from "./acceptance";
 export * from "./quality";
+export * from "./gates";
 export * from "./escalate";
 export * from "./forge";
 export * from "./git";
 export * from "./pr";
 export * from "./pr-narrative";
+export * from "./commit-round";
 export * from "./result";
+export * from "./review-round";