@nathapp/nax 0.80.1 → 0.81.0-canary.2

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

@@ -1,102 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { FinishError } from "../errors";
-import { DEFAULT_GATE_TIMEOUT_MS, runShell } from "../exec";
-import type { ShellRunFn } from "../types";
-
-export interface QualityCommands {
-  build?: string;
-  typecheck?: string;
-  lint?: string;
-  test?: string;
-  format?: string;
-}
-
-export const _qualityDeps: { runShell: ShellRunFn; readText: (path: string) => Promise<string | null> } = {
-  runShell,
-  // node:fs, not Bun.file — this module runs inside acpx's Node process, where
-  // the `Bun` global does not exist (see the header of `../exec.ts`). A single
-  // read that treats ENOENT as "absent" also avoids the exists()-then-read race
-  // the Bun version had.
-  readText: async (path) => {
-    try {
-      return await readFile(path, "utf8");
-    } catch (err) {
-      if ((err as NodeJS.ErrnoException).code === "ENOENT") return null;
-      throw err;
-    }
-  },
-};
-
-const GATE_ORDER: (keyof QualityCommands)[] = ["build", "typecheck", "lint", "test", "format"];
-
-export interface QualityGateOutcome {
-  passed: boolean;
-  /** Gate names that actually ran — empty means nothing was configured. */
-  ran: string[];
-  failing: string[];
-  output: string;
-}
-
-/**
- * Run the repo's configured quality commands in order, each through
- * `/bin/sh -c` (matching `src/quality/runner.ts`) so `&&`, quoting and globs
- * survive, and each under a wall-clock cap so a hung gate can't stall the flow.
- *
- * `passed` is only true when at least one gate ran. A repo with no configured
- * commands must not report a green gate — that previously let the flow open a
- * "ready" PR having verified nothing.
- */
-export async function runQualityGates(
-  repoRoot: string,
-  commands: QualityCommands,
-  opts: { timeoutMs?: number } = {},
-): Promise<QualityGateOutcome> {
-  const failing: string[] = [];
-  const ran: string[] = [];
-  const chunks: string[] = [];
-  const timeoutMs = opts.timeoutMs ?? DEFAULT_GATE_TIMEOUT_MS;
-  for (const gate of GATE_ORDER) {
-    const command = commands[gate];
-    if (!command) continue;
-    ran.push(gate);
-    const res = await _qualityDeps.runShell(command, { cwd: repoRoot, timeoutMs });
-    chunks.push(`[${gate}] exit=${res.exitCode}\n${res.stdout}\n${res.stderr}`);
-    if (res.exitCode !== 0) failing.push(gate);
-  }
-  if (ran.length === 0) {
-    return {
-      passed: false,
-      ran,
-      failing: [],
-      output: "[quality] no quality.commands configured in .nax/config.json — nothing was verified",
-    };
-  }
-  return { passed: failing.length === 0, ran, failing, output: chunks.join("\n\n") };
-}
-
-/**
- * Read `quality.commands` from the repo-root `.nax/config.json` only.
- *
- * Deliberately root-scoped: per-package `.nax/mono/<pkg>/config.json` overrides
- * are unreliable as a repo-root gate (a package's own `test` command does not
- * verify the repo), and this gate runs once at the root by design.
- */
-export async function loadQualityCommands(workdir: string): Promise<QualityCommands> {
-  const text = await _qualityDeps.readText(`${workdir}/.nax/config.json`);
-  if (!text) return {};
-  let cfg: { quality?: { commands?: QualityCommands } };
-  try {
-    cfg = JSON.parse(text);
-  } catch (cause) {
-    throw new FinishError(
-      "Failed to parse .nax/config.json while loading quality commands",
-      "FINISH_CONFIG_UNPARSEABLE",
-      {
-        stage: "finish-quality",
-        path: `${workdir}/.nax/config.json`,
-        cause,
-      },
-    );
-  }
-  return cfg.quality?.commands ?? {};
-}

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

@@ -1,112 +0,0 @@
-/**
- * Finish-audit artifacts.
- *
- * These live under nax's global per-project output directory —
- * `~/.nax/<project>/finish-audit/<feature>/` — alongside `prompt-audit/` and
- * `review-audit/`, not in the user's repo. Two reasons the repo was the wrong
- * home: the artifact describes a *run*, not the source tree, so committing it
- * and gitignoring it are both wrong answers; and a per-feature, per-run path
- * makes the history queryable across runs, which a single overwritten
- * `.nax/nax-finish-result.json` never was.
- *
- * The plugin supplies `auditDir` because it owns nax's path SSOT
- * (`src/runtime/paths.ts`), which this module may not import — `flows/` is
- * loaded by acpx, outside nax's own process. Absent, we fall back to a
- * repo-local directory so a hand-run `acpx flow run` still records something.
- *
- * Two files per run:
- * - `<runId>.jsonl`       — one line per fix round, appended as it happens
- * - `<runId>.result.json` — the terminal result the plugin reads back
- */
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import type { FinishInput, FinishResult, FinishRound } from "../types";
-
-/** Used when the plugin supplied no run id (e.g. a hand-run `acpx flow run`). */
-const FALLBACK_RUN_ID = "run";
-
-type AuditTarget = Pick<FinishInput, "auditDir" | "workdir" | "feature" | "runId">;
-
-export function resolveAuditDir(input: AuditTarget): string {
-  return input.auditDir ?? join(input.workdir, ".nax", "finish-audit", input.feature);
-}
-
-export function resultPath(input: AuditTarget): string {
-  return join(resolveAuditDir(input), `${input.runId || FALLBACK_RUN_ID}.result.json`);
-}
-
-export function roundsPath(input: AuditTarget): string {
-  return join(resolveAuditDir(input), `${input.runId || FALLBACK_RUN_ID}.jsonl`);
-}
-
-export const _resultDeps: {
-  writeText: (p: string, s: string) => Promise<void>;
-  appendText: (p: string, s: string) => Promise<void>;
-  readText: (p: string) => Promise<string | null>;
-} = {
-  // node:fs, not Bun.write — this module runs inside acpx's Node process, where
-  // the `Bun` global does not exist (see the header of `../exec.ts`). The mkdir
-  // is not redundant: Bun.write creates missing parent directories implicitly,
-  // writeFile does not, and the audit directory now lives under `~/.nax/`,
-  // where for a project's first run nothing on the path exists yet.
-  writeText: async (p, s) => {
-    await mkdir(dirname(p), { recursive: true });
-    await writeFile(p, s, "utf8");
-  },
-  appendText: async (p, s) => {
-    await mkdir(dirname(p), { recursive: true });
-    await writeFile(p, s, { encoding: "utf8", flag: "a" });
-  },
-  readText: async (p) => {
-    try {
-      return await readFile(p, "utf8");
-    } catch {
-      return null;
-    }
-  },
-};
-
-/**
- * Append one fix round to the run's audit trail.
- *
- * Best-effort: an unwritable audit directory must not take the flow down
- * mid-loop. The round is a record of work already done — losing the record is
- * bad, losing the run that did the work is worse.
- */
-export async function appendRound(input: AuditTarget, round: FinishRound): Promise<void> {
-  try {
-    await _resultDeps.appendText(roundsPath(input), `${JSON.stringify(round)}\n`);
-  } catch {
-    // Intentionally swallowed — see the doc comment above.
-  }
-}
-
-/** Read back every round recorded for this run, so a terminal result can embed them. */
-export async function readRounds(input: AuditTarget): Promise<FinishRound[]> {
-  const raw = await _resultDeps.readText(roundsPath(input));
-  if (!raw) return [];
-  const rounds: FinishRound[] = [];
-  for (const line of raw.split("\n")) {
-    if (!line.trim()) continue;
-    try {
-      rounds.push(JSON.parse(line) as FinishRound);
-    } catch {
-      // A torn final line (killed mid-write) must not lose the rounds before it.
-    }
-  }
-  return rounds;
-}
-
-/**
- * Write the terminal result, embedding every round this run recorded.
- *
- * Rounds are attached on *every* status, not just `escalated`: a finish that
- * succeeded after four rounds is precisely the case worth auditing — it says
- * the run's own review gates missed four defects — and it was the one case
- * that previously recorded nothing at all.
- */
-export async function writeResult(input: AuditTarget, result: FinishResult): Promise<void> {
-  const rounds = await readRounds(input);
-  const withRounds: FinishResult = rounds.length > 0 ? { ...result, rounds } : result;
-  await _resultDeps.writeText(resultPath(input), `${JSON.stringify(withRounds, null, 2)}\n`);
-}

package/flows/nax-finish/steps/review-audit.ts

@@ -1,91 +0,0 @@
-/**
- * Checking that a review discharged its obligations before its verdict counts.
- *
- * `WORKER_PROTOCOL` has always told the reviewer to enumerate the external
- * touchpoints and open their definitions, and both dimension references have
- * always required a per-item enumeration. Neither was checkable: `routeReview`
- * saw only a route and a finding list, so a reviewer that read the diff and
- * nothing else was indistinguishable from one that did the work — and on the run
- * behind #1614 that is exactly what happened, at 86 seconds for 3,716 changed
- * lines.
- *
- * The disk check is what makes this a gate rather than a ritual. It proves the
- * paths are real, not that they were read: a reviewer can still list files it
- * only globbed. That raises the cost of faking the list without eliminating it,
- * which is the honest ceiling for a check that costs one `stat` per line.
- *
- * A verdict from the legacy JSON parsing tier carries no `saw*` fields (they are
- * optional), so it always reports both gaps and is sent back for one re-review
- * under the new prompt. That is intentional, not a bug: the safe direction is
- * an extra review, never a false approval, and the retry self-corrects because
- * the new prompt contract produces a verdict the gate can actually check.
- *
- * `node:fs` — not `Bun.file` — because `flows/` runs inside acpx's Node process.
- *
- * Both `touchpoint.path` and a disposition's `evidence` come from the
- * reviewer/fixer's reply text — untrusted the same way any parsed LLM output
- * is. `exists()` confines its resolved path under `workdir` before stat-ing
- * it, so a `../`-laden path can never be used to probe existence outside the
- * repo; a path that escapes reads as "does not exist," which is the correct
- * verdict anyway since a legitimate touchpoint is always inside it.
- */
-import { stat } from "node:fs/promises";
-import * as path from "node:path";
-import type { FindingDisposition, ReviewVerdict } from "../types";
-
-/** Paths stat-ed per review. A reviewer listing more than this is not the failure mode. */
-const MAX_CHECKED = 20;
-
-async function exists(workdir: string, rel: string): Promise<boolean> {
-  const root = path.resolve(workdir);
-  const resolved = path.resolve(root, rel);
-  if (resolved !== root && !resolved.startsWith(root + path.sep)) return false;
-  try {
-    await stat(resolved);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * What this review failed to do. Empty means it may be routed on.
- *
- * Only ever called for a verdict that already parsed; an unreadable reply is the
- * `reprompt` path's business and is handled before this runs.
- */
-export async function auditGaps(verdict: ReviewVerdict, workdir: string): Promise<string[]> {
-  const gaps: string[] = [];
-  const touchpoints = verdict.touchpoints ?? [];
-  if (!verdict.sawTouchpointsSection || touchpoints.length === 0) {
-    gaps.push("no `## TOUCHPOINTS` section: list every external definition you opened, or `- none — <justification>`");
-  } else if (!touchpoints.some((t) => t.path === "none")) {
-    const checked = touchpoints.slice(0, MAX_CHECKED);
-    const found = await Promise.all(checked.map((t) => exists(workdir, t.path)));
-    if (!found.some(Boolean)) {
-      gaps.push(
-        `touchpoint path does not exist in the repo (checked: ${checked
-          .map((t) => t.path)
-          .join(", ")}) — list files you actually opened`,
-      );
-    }
-  }
-  if (!verdict.sawWalkSection || (verdict.walk ?? []).length === 0) {
-    gaps.push("no `## WALK` section: the per-AC (spec) or per-function (quality) enumeration is required");
-  }
-  return gaps;
-}
-
-/** Mark any rejection whose cited `file:line` does not resolve in the repo. */
-export async function validateDispositions(
-  workdir: string,
-  dispositions: FindingDisposition[],
-): Promise<FindingDisposition[]> {
-  return Promise.all(
-    dispositions.map(async (d) => {
-      if (d.disposition !== "rejected" || !d.evidence) return d;
-      const file = d.evidence.split(":")[0];
-      return (await exists(workdir, file)) ? d : { ...d, evidenceMissing: true };
-    }),
-  );
-}

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

@@ -1,109 +0,0 @@
-/**
- * Recording the review rounds that produce no commit.
- *
- * `commit_<phase>` is the audit seam for rounds that *fix* something — it is the
- * only point where a round's findings and its resulting commit are both known.
- * But that made a commit the sole evidence a reviewer ever ran: a review that
- * passed produced no `fix_*`, therefore no `commit_*`, therefore no round, and
- * "this phase passed" became indistinguishable from "this phase never ran"
- * (#1507). Worse, it made the owed re-review in #1506 unprovable after the fact.
- *
- * So the two seams split by what they know:
- * - `commit_<phase>` records rounds that changed the tree (`outcome: "fixed"`).
- * - here records rounds that did not (`passed` / `unparseable` / `escalated`).
- *
- * Wrapping `routeReview` rather than living inside it keeps that function pure
- * and synchronous — it is the flow's routing SSOT and is exercised by a large
- * table of unit tests that would all have to become async otherwise.
- */
-import { inputOf } from "../flow-ctx";
-import type { OutputsCtx, StepsCtx } from "../flow-ctx";
-import type { Finding, FinishRoundOutcome, ReviewVerdict } from "../types";
-import { MAX_INCOMPLETE_ATTEMPTS, routeReview } from "../verdict";
-import { appendRound } from "./result";
-import { auditGaps } from "./review-audit";
-
-/** Route → what to call the round. `fix` is absent by construction — see below. */
-const OUTCOME_BY_ROUTE: Record<string, FinishRoundOutcome> = {
-  clean: "passed",
-  reprompt: "unparseable",
-  escalate: "escalated",
-  incomplete: "incomplete",
-};
-
-/**
- * The Nth time this phase's *review* node has run.
- *
- * Deliberately not `fixAttemptCount`: that counts `fix_<phase>` steps, which is
- * the right number for a round that fixed something and the wrong one here — a
- * review that passes on the first look runs zero fix nodes, and every clean
- * round would be numbered 0. Self-inclusive, for the same reason `repromptCount`
- * is: acpx records the `review_<phase>` step before `route_<phase>` executes.
- */
-function reviewAttemptCount(ctx: StepsCtx, phase: "spec" | "quality"): number {
-  return (ctx.state.steps ?? []).filter((s) => s.nodeId === `review_${phase}`).length;
-}
-
-/**
- * How many previous rounds of this phase were sent back as incomplete.
- *
- * NOT self-inclusive, unlike `repromptCount` — that one counts `review_<phase>`
- * steps, which acpx has already recorded by the time `route_<phase>` runs, while
- * this counts `route_<phase>` steps and we are *inside* the current one. So the
- * comparison below is `<`, where `routeReview`'s reprompt comparison is `<=`.
- */
-function incompleteCount(ctx: StepsCtx, phase: "spec" | "quality"): number {
-  return (ctx.state.steps ?? []).filter(
-    (s) => s.nodeId === `route_${phase}` && (s.output as { route?: string } | undefined)?.route === "incomplete",
-  ).length;
-}
-
-/**
- * Route this phase's review verdict, and record the round when it produced no
- * commit.
- *
- * `fix` is the one route that records nothing here: it leads to `fix_<phase>` →
- * `commit_<phase>`, which appends the round with the commit attached. Recording
- * at both seams would double-count every fixed round in the PR body.
- *
- * Best-effort, exactly like `appendRound` itself: the route is returned whether
- * or not the write lands. Losing the record is bad; failing the run that has
- * already done the work is worse.
- */
-export async function routeReviewAndRecord(
-  ctx: { input: unknown } & OutputsCtx & StepsCtx,
-  phase: "spec" | "quality",
-): Promise<{ route: string; escalationReason?: string; findings: Finding[]; gaps?: string[] }> {
-  const routed = routeReview(ctx, phase);
-  const input = inputOf(ctx);
-  // The gate runs only on a verdict the flow would otherwise act on. `reprompt`
-  // and `escalate` already end the round, and re-checking a verdict with no
-  // content would report the same two gaps as a second failure mode.
-  let result: { route: string; escalationReason?: string; findings: Finding[]; gaps?: string[] } = routed;
-  if (routed.route === "clean" || routed.route === "fix") {
-    const verdict = (ctx.outputs as Record<string, ReviewVerdict | undefined>)[`review_${phase}`];
-    const gaps = verdict ? await auditGaps(verdict, input.workdir) : [];
-    if (gaps.length > 0) {
-      result =
-        incompleteCount(ctx, phase) < MAX_INCOMPLETE_ATTEMPTS
-          ? { ...routed, route: "incomplete", gaps }
-          : {
-              ...routed,
-              route: "escalate",
-              escalationReason: `${phase} review never discharged its reading obligations: ${gaps.join("; ")}`,
-            };
-    }
-  }
-  const outcome = OUTCOME_BY_ROUTE[result.route];
-  if (outcome) {
-    await appendRound(input, {
-      ts: new Date().toISOString(),
-      phase,
-      attempt: reviewAttemptCount(ctx, phase),
-      committed: false,
-      outcome,
-      findings: result.findings,
-    });
-  }
-  return result;
-}

package/flows/nax-finish/types.ts

@@ -1,260 +0,0 @@
-import type { TemplateMode } from "./pr-template-merge";
-
-/** One acceptance-test group as reported by `nax features resolve --json`. */
-export interface AcceptanceGroup {
-  packageDir: string;
-  testPath: string;
-  exists: boolean;
-  command?: string;
-  language: string;
-}
-
-export type Severity = "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
-export interface Finding {
-  severity: Severity;
-  title: string;
-  problem: string;
-  fix: string;
-  /**
-   * Set when the reviewer marked this finding as needing a human — a spec
-   * conflict or a design call with no safe mechanical fix. This replaces the
-   * whole-reply `escalate` route the reviewer used to choose: escalation is a
-   * property of one finding, not of the phase, so reporting a design concern no
-   * longer halts the pipeline by itself.
-   */
-  judgment?: boolean;
-  /** Why this finding needs a human; the escalation reason when it escalates. */
-  judgmentReason?: string;
-}
-
-/** One external definition the reviewer says it opened before judging. */
-export interface Touchpoint {
-  /** Repo-relative path, or the literal `none` sentinel. */
-  path: string;
-  /** Symbol or line after the final `:`, when the reviewer gave one. */
-  symbol?: string;
-  /** The reviewer's stated reason for opening it (or for there being none). */
-  note: string;
-}
-
-/** A reviewer reply, parsed. Sections are reported separately from their content
- * so an *absent* section is distinguishable from an *empty* one — only the first
- * is a reviewer that skipped the obligation. */
-export interface ReviewReport {
-  findings: Finding[];
-  touchpoints: Touchpoint[];
-  walk: string[];
-  sawNoFindings: boolean;
-  sawTouchpointsSection: boolean;
-  sawWalkSection: boolean;
-}
-
-/** What the fix node did with one finding it was handed. */
-export interface FindingDisposition {
-  /** 1-based index into the findings list the fix prompt numbered. */
-  index: number;
-  disposition: "fixed" | "rejected";
-  /** `file:line` pinning the current behaviour; required for a rejection. */
-  evidence?: string;
-  /** Set by `commit_<phase>` when the cited evidence path does not exist. */
-  evidenceMissing?: boolean;
-}
-export interface ReviewVerdict {
-  /**
-   * Neither `clean` nor `reprompt` is a model-produced route.
-   *
-   * `clean` — `parse` rewrites `proceed` with zero findings, so the graph can
-   * skip the fix node instead of prompting an agent to "apply fixes" for nothing.
-   *
-   * `reprompt` — `parse` could not read JSON out of the reply at all. Returning
-   * this rather than throwing is deliberate: a throw fails the acp node and kills
-   * the whole flow with no result file, bypassing the `escalate` sink that exists
-   * to report exactly this kind of dead end.
-   */
-  route: "proceed" | "escalate" | "clean" | "reprompt";
-  findings: Finding[];
-  escalationReason?: string;
-  /** Bounded tail of an unparseable reply; set only when `route` is `reprompt`. */
-  raw?: string;
-  /** Touchpoints the reviewer listed; read by the audit gate in `routeReviewAndRecord`. */
-  touchpoints?: Touchpoint[];
-  /** The per-AC or per-function walk lines the reviewer emitted. */
-  walk?: string[];
-  /** Whether the section was present at all — absent and empty are different failures. */
-  sawTouchpointsSection?: boolean;
-  sawWalkSection?: boolean;
-  /** Set on a `fix_<phase>` output: what the fixer did with each finding it was handed. */
-  dispositions?: FindingDisposition[];
-}
-/** Wall-clock budgets, forwarded from `finish.autoFlow.timeouts` by the plugin. */
-export interface FinishTimeouts {
-  acceptanceMs?: number;
-  gateMs?: number;
-}
-/** The four fix-and-reverify loops, in graph order. */
-export type FinishPhase = "acceptance" | "spec" | "quality" | "gate";
-
-/**
- * One completed fix round, appended to the audit trail as it happens.
- *
- * Rounds are appended at `commit_<phase>` as they happen rather than
- * reconstructed by a terminal node from `ctx.state.steps` (which does retain
- * every step's output). Appending live is what makes the trail survive a flow
- * that is killed or times out: no terminal node runs on those paths, and a
- * finish that died mid-loop is exactly when the record of what it already
- * changed on the branch matters most.
- */
-/**
- * What produced a round — the difference between "a reviewer read this and
- * approved it" and "nothing read this".
- *
- * Rounds used to be appended only where a fix produced a commit, so a review
- * that passed left no record at all and was indistinguishable from a review
- * that never ran (#1507). Every phase that executes now records a round, and
- * this field says which of the five things happened.
- *
- * Optional because rounds recorded by earlier versions have no `outcome`, and
- * the PR body still has to render those without claiming more than it knows.
- */
-export type FinishRoundOutcome =
-  /** A reviewer reported findings and this phase's fix node ran. */
-  | "fixed"
-  /** A reviewer ran and reported nothing. The only value that means "approved". */
-  | "passed"
-  /** The reviewer replied, but no verdict could be read out of it. */
-  | "unparseable"
-  /** Handed off to a human — an explicit escalate, a cap, or a node that emitted nothing. */
-  | "escalated"
-  /**
-   * This phase has no reviewer at all (`gate`, `acceptance`). Distinct from
-   * `passed`: an empty finding list here means "nobody looked", and rendering it
-   * as "no findings" manufactures evidence of a review that does not exist.
-   */
-  | "no-reviewer"
-  /**
-   * A re-review was owed and deliberately skipped.
-   *
-   * **No longer emitted.** It described the `gate` → `tests-only` route, which
-   * skipped `review_quality` as a cost tradeoff; #1510 closed that hole, so
-   * every committed gate fix is now re-reviewed and nothing writes this.
-   *
-   * Retained because the audit trail is read, not just written: a project that
-   * ran an earlier nax can hold rounds carrying this outcome, and dropping it
-   * from the union would make those unrenderable. Do not reuse the name for a
-   * new meaning — a reader hitting it in an old artifact must still be told
-   * what it meant when it was written.
-   */
-  | "review-skipped"
-  /** The reviewer replied with findings but skipped a required audit section, so
-   * the verdict was not acted on. Distinct from `unparseable`: there was a
-   * readable verdict, it just had no evidence behind it. */
-  | "incomplete";
-
-export interface FinishRound {
-  ts: string;
-  phase: FinishPhase;
-  /** 1-based; the Nth time this phase's fix node has run. */
-  attempt: number;
-  /** True when the fix produced a commit; false when it changed nothing. */
-  committed: boolean;
-  /** What produced this round; absent on rounds written before it existed. */
-  outcome?: FinishRoundOutcome;
-  /** Reviewer findings this round set out to fix (spec/quality phases). */
-  findings: Finding[];
-  /** Gate commands that were red this round (gate phase). */
-  failing?: string[];
-  /**
-   * The successor this round's commit routed to — `changed` / `tests-only` /
-   * `unchanged` for `gate`, `changed` / `unchanged` elsewhere.
-   *
-   * Recorded because `outcome` stopped carrying it. Until #1510 a tests-only
-   * gate fix was the only round writing `review-skipped`, so the outcome
-   * doubled as the classification; now every committed gate fix is reviewed
-   * and writes `no-reviewer`, which would leave "what did this fix touch?"
-   * unanswerable from the trail. That question is the input to deciding
-   * whether the re-review ever needs a cheaper, test-scoped form, so it has to
-   * survive the round it was computed in.
-   */
-  route?: string;
-  /**
-   * `HEAD` SHA after this round's commit (set only when `committed`); absent
-   * on no-op rounds so a reader can distinguish "no commit" from "record lost".
-   * Lets "Fixed in `<sha>`" be reconstructed from the audit trail alone, rather
-   * than by matching round timestamps against `git log`.
-   */
-  sha?: string;
-  /** What the fixer did with each finding it was handed (spec/quality phases). */
-  dispositions?: FindingDisposition[];
-}
-
-export interface FinishInput {
-  feature: string;
-  workdir: string;
-  branch: string;
-  prdPath: string;
-  /**
-   * Directory for this feature's finish-audit artifacts, e.g.
-   * `~/.nax/<project>/finish-audit/<feature>`. Supplied by the plugin, which
-   * owns nax's path SSOT (`src/runtime/paths.ts`) that this module may not
-   * import. Absent → the flow falls back to a repo-local directory.
-   */
-  auditDir?: string;
-  /** Run id, used to name this run's audit files. Absent → "run". */
-  runId?: string;
-  /**
-   * True only when Telegram escalation is both enabled *and* credentialed, as
-   * determined by the plugin. When true the flow skips the PR/MR comment
-   * fallback (and does not open a draft to hold one) — the plugin sends the
-   * Telegram message from the result file instead.
-   */
-  escalateTelegram: boolean;
-  timeouts?: FinishTimeouts;
-  /** PR/MR body composition, forwarded from `finish.autoFlow.prBody`. */
-  prBody?: FinishPrBodySettings;
-}
-
-/**
- * How the repo's own PR/MR template is honoured when composing the body.
- * Absent (and absent fields) mean the defaults in `pr-template-merge.ts`.
- */
-export interface FinishPrBodySettings {
-  /** `merge` (default) · `strict` (keep unfillable headings, empty) · `ignore`. */
-  template?: TemplateMode;
-  /** Normalised template heading → body-section key, layered over the defaults. */
-  sectionMap?: Record<string, string>;
-}
-export interface FinishResult {
-  feature: string;
-  status: "opened" | "promoted" | "already-ready" | "escalated" | "nothing-to-finish";
-  url?: string;
-  escalationReason?: string;
-  /**
-   * The findings behind an escalation. Persisted because the reason alone is a
-   * bare count ("3 finding(s) after 3 fix attempts"), and on the Telegram
-   * channel the composed PR comment — the only other thing carrying them — is
-   * never posted. Without this the findings survived only in acpx's run bundle.
-   */
-  findings?: Finding[];
-  /**
-   * Set when the escalation could not be delivered to its channel (forge
-   * comment failed, remote unrecognised). The result file is written before
-   * delivery is attempted, so an undelivered escalation is still reported
-   * rather than lost.
-   */
-  deliveryError?: string;
-  /**
-   * Every fix round the flow ran, on *all* terminal statuses — not just
-   * escalations. A successful finish that took four rounds to get there is the
-   * case worth auditing (it says the run's own review gates missed four
-   * defects), and it was previously the one case that recorded nothing.
-   */
-  rounds?: FinishRound[];
-}
-export interface RunResult {
-  exitCode: number;
-  stdout: string;
-  stderr: string;
-  timedOut?: boolean;
-}
-export type RunFn = (cmd: string[], opts: { cwd: string; timeoutMs?: number }) => Promise<RunResult>;
-export type ShellRunFn = (command: string, opts: { cwd: string; timeoutMs?: number }) => Promise<RunResult>;