@nathapp/nax 0.77.3 → 0.78.0

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

@@ -17,6 +17,7 @@
  *   *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. */
@@ -34,11 +35,13 @@ export interface LoadCtxOutput {
   base?: string;
   specPath?: string;
   groups?: AcceptanceGroup[];
-  /** `nax features resolve`'s acceptance status: "ok" | "disabled" | "no-prd". */
-  acceptanceStatus?: string;
+  /** `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 {
@@ -111,15 +114,32 @@ export function findingsOf(ctx: OutputsCtx, phase: FinishPhase): Finding[] {
  * 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 since it (nothing new to look at), or the commit step
- * recorded no `shaBefore`.
+ * (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_"));
+  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;
 }

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

@@ -36,6 +36,12 @@
  *   faced mechanical checks. A test-only fix skips the re-review by explicit
  *   cost tradeoff; see `gateCommitRoute` for why that is a known hole. The skip
  *   records `review-skipped`, so it is visible in the audit.
+ * - `load_ctx` and `open_pr` both route to `escalate` rather than throwing on
+ *   their own failures. acpx has no error edge, so a throw ends the run with no
+ *   result file for the plugin to read or notify from — the one outcome that
+ *   must always be reported is "a human is needed" (#1399). `open_pr` matters
+ *   most: it is reached only after every gate is green, so a failed push or
+ *   forge call there discards a completed, verified run.
  * - Every `commit_*` node appends its round to the finish-audit trail as it
  *   happens, rather than a terminal node reconstructing them from
  *   `ctx.state.steps`. Appending live is what makes the trail survive a flow
@@ -49,6 +55,7 @@ import { narrativePrompt, parseNarrativeNode } from "./narrative";
 import { buildReviewPrompt, fixPrompt } from "./review-prompts";
 import {
   _contextDeps,
+  acceptanceGateNode,
   amendPrBodyNode,
   appendRound,
   buildCommitRound,
@@ -59,21 +66,19 @@ import {
   detectForge,
   filesInCommit,
   loadFinishPrContext,
-  loadQualityCommands,
   openOrPromotePr,
   partitionTestFiles,
   postEscalation,
   preflight,
+  qualityGatesNode,
   resolveFeature,
   routeReviewAndRecord,
-  runAcceptanceGate,
-  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 } from "./verdict";
+import { parseFixVerdict, parseReviewVerdict, repromptCount } from "./verdict";
 
 /**
  * Disabled only on an explicit "0". An unset variable means enabled, so a flow
@@ -93,59 +98,6 @@ export const _openPrDeps = {
   buildFinishBody,
 };
 
-/**
- * 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 BOTH
- * `no-prd` and `disabled`, and reports `exists: false` for a group whose test
- * was expected at its canonical path but never generated. Treating all 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.
- */
-async function acceptanceGateNode(ctx: {
-  input: unknown;
-  outputs: unknown;
-  state: { steps: { nodeId: string }[] };
-}): Promise<{ route: string; reason?: string; output: string }> {
-  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,
-      };
-    }
-    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 };
-}
-
 /**
  * Route for `commit_gate`, whose successor depends on what the fix touched.
  *
@@ -260,6 +212,7 @@ export default defineFlow({
           testFileRegex: resolution.testFileRegex,
           commitsAhead: pf.commitsAhead,
           route: pf.route,
+          ...(pf.reason ? { reason: pf.reason } : {}),
         };
       },
     },
@@ -333,75 +286,7 @@ export default defineFlow({
     commit_gate: commitFixNode("gate"),
     quality_gates: {
       nodeType: "action",
-      async run(ctx) {
-        const i = inputOf(ctx);
-
-        // 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, 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.
-        //
-        // `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.
-        const acc = await runAcceptanceGate(i.workdir, loadCtxOf(ctx).groups ?? [], {
-          timeoutMs: i.timeouts?.acceptanceMs,
-        });
-        if (!acc.passed) {
-          // 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 accAttempts = fixAttemptCount(ctx, "fix_gate");
-          const failing = ["acceptance"];
-          if (accAttempts >= MAX_FIX_ATTEMPTS) {
-            return {
-              route: "escalate",
-              reason: `A later fix broke the feature's own contract: acceptance still failing after ${accAttempts} fix attempts.`,
-              ran: [],
-              failing,
-              output: acc.output,
-            };
-          }
-          return { route: "fix", ran: [], failing, output: acc.output };
-        }
-
-        const cmds = 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 };
-      },
+      run: qualityGatesNode,
     },
     open_pr: {
       nodeType: "action",
@@ -414,7 +299,24 @@ export default defineFlow({
         }
         // 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`);
+        //
+        // Routed, not thrown. acpx has no error edge, so a throw here kills the
+        // flow — and this is the last node on the happy path, reached only once
+        // every gate is green and every fix has landed. It died before
+        // `writeResult`, so the plugin found no result file and notified
+        // nobody: the #1399 failure mode the `escalate` node was hardened
+        // against and this one was not. A protected branch, an expired token or
+        // a non-fast-forward push is exactly the kind of dead end `escalate`
+        // exists to report.
+        let sync: { committed: boolean };
+        try {
+          sync = await commitAndPush(i.workdir, i.branch, `fix(${i.feature}): nax-finish automated fixes`);
+        } catch (error) {
+          return {
+            route: "escalate",
+            reason: `nax-finish could not push "${i.branch}", so no PR was opened: ${String(error)}`,
+          };
+        }
 
         const fallbackTitle = `nax-finish: ${i.feature}`;
         const fallbackBody = `Automated finish of \`${i.feature}\`.`;
@@ -441,7 +343,18 @@ export default defineFlow({
           body = fallbackBody;
         }
 
-        const r = await openOrPromotePr(i.workdir, i.branch, title, body, forge);
+        // Same reasoning as the push above: a forge that refuses to create or
+        // promote (rate limit, revoked token, unrecognised remote) must reach a
+        // human through `escalate`, not take the flow down silently.
+        let r: { status: "opened" | "promoted" | "already-ready"; url?: string };
+        try {
+          r = await openOrPromotePr(i.workdir, i.branch, title, body, forge);
+        } catch (error) {
+          return {
+            route: "escalate",
+            reason: `nax-finish could not open or promote the PR for "${i.branch}": ${String(error)}`,
+          };
+        }
         await writeResult(i, { feature: i.feature, status: r.status, url: r.url });
         // The PR now exists with the mechanical narrative already in place.
         // Anything the narrative node does from here is an improvement on a
@@ -478,12 +391,14 @@ export default defineFlow({
             : routed.route_quality?.route === "escalate"
               ? routed.route_quality
               : undefined;
-        const loopExhausted =
-          outs.acceptance?.route === "escalate"
-            ? outs.acceptance
-            : outs.quality_gates?.route === "escalate"
-              ? outs.quality_gates
-              : undefined;
+        // Ordered by how far down the graph the node sits, so the *last* thing
+        // that gave up names the reason. `load_ctx` and `open_pr` are here
+        // because both can now route here rather than throw — a base ref that
+        // does not resolve, and a push or forge call that failed after every
+        // gate was green.
+        const loopExhausted = [outs.open_pr, outs.quality_gates, outs.acceptance, outs.load_ctx].find(
+          (o) => o?.route === "escalate",
+        );
         const reason =
           verdict?.escalationReason ?? loopExhausted?.reason ?? "nax-finish could not reach a green, shippable state";
 
@@ -531,7 +446,15 @@ export default defineFlow({
     },
   },
   edges: [
-    { from: "load_ctx", switch: { on: "$.route", cases: { proceed: "acceptance", "nothing-to-finish": "open_pr" } } },
+    {
+      from: "load_ctx",
+      switch: {
+        on: "$.route",
+        // `escalate`: the branch could not be measured against its base at all,
+        // so neither "proceed" nor "nothing-to-finish" would be a true claim.
+        cases: { proceed: "acceptance", "nothing-to-finish": "open_pr", escalate: "escalate" },
+      },
+    },
     {
       from: "acceptance",
       switch: { on: "$.route", cases: { proceed: "review_spec", fix: "fix_acceptance", escalate: "escalate" } },
@@ -591,7 +514,10 @@ export default defineFlow({
     },
     // 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: "open_pr",
+      switch: { on: "$.route", cases: { narrate: "narrative", done: "finish_done", escalate: "escalate" } },
+    },
     { from: "narrative", to: "amend_body" },
   ],
 });

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/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,6 +1,7 @@
 export * from "./context";
 export * from "./acceptance";
 export * from "./quality";
+export * from "./gates";
 export * from "./escalate";
 export * from "./forge";
 export * from "./git";