mandrel 2.0.0 → 2.1.0

package/.agents/scripts/check-dead-exports.js

@@ -9,12 +9,18 @@
  * misconfigured knip installation cannot block CI when we have no current
  * snapshot to compare against.
  *
+ * Story #4575 adds the **production pass** (`--production`), the test-only-
+ * importer discount: default mode counts a test as an importer, so
+ * production-dead code hides behind its own tests. See
+ * `lib/dead-exports-mode.js` for why the two passes carry separate baselines.
+ *
  * Contract:
- *   - Reads the committed baseline at `baselines/dead-exports.json`
- *     (override with `--baseline <path>`). Envelope shape:
+ *   - Reads the committed baseline at `baselines/dead-exports.json` — or
+ *     `baselines/dead-exports-production.json` under `--production`
+ *     (override either with `--baseline <path>`). Envelope shape:
  *       { $schema, kernelVersion, generatedAt, rows: [{ file, symbol }] }
- *   - Spawns `npx knip --reporter json --no-progress`, parses stdout,
- *     extracts `{ file, symbol }` rows from `issues[].exports[]`.
+ *   - Spawns `npx knip --reporter json --no-progress` (plus `--production`),
+ *     parses stdout, extracts `{ file, symbol }` rows from `issues[].exports[]`.
  *   - Diffs current vs. baseline by `(file, symbol)` identity.
  *   - Prints `+ <file>: <symbol>` for each added dead export and
  *     `- <file>: <symbol>` for each removed one, then a summary line.
@@ -25,24 +31,30 @@
  *     Knip spawn/parse failure exits 0 (advisory) with a stderr warning.
  */
 
-import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import process from 'node:process';
 import { runAsCli } from './lib/cli-utils.js';
+import {
+  extractRowsFromKnip,
+  readKnipOutput,
+  runKnip,
+} from './lib/dead-exports-knip.js';
+import { resolveDeadExportsMode } from './lib/dead-exports-mode.js';
 
 /**
- * Parse argv for `--baseline <path>`, `--json`, and `--knip-output <path>`.
- * `--knip-output` is a test seam: pass a pre-captured knip JSON file instead
- * of spawning knip. Exported so unit tests can pin the parser.
+ * Parse argv for `--baseline <path>`, `--json`, `--knip-output <path>`, and
+ * `--production`. `--knip-output` is a test seam: pass a pre-captured knip JSON
+ * file instead of spawning knip. Exported so unit tests can pin the parser.
  *
  * @param {string[]} argv
- * @returns {{ baselinePath: string | null, json: boolean, knipOutputPath: string | null }}
+ * @returns {{ baselinePath: string | null, json: boolean, knipOutputPath: string | null, production: boolean }}
  */
 export function parseArgv(argv = []) {
   let baselinePath = null;
   let json = false;
   let knipOutputPath = null;
+  let production = false;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
     if (a === '--baseline') {
@@ -53,6 +65,8 @@ export function parseArgv(argv = []) {
       }
     } else if (a === '--json') {
       json = true;
+    } else if (a === '--production') {
+      production = true;
     } else if (a === '--knip-output') {
       const next = argv[i + 1];
       if (next && !next.startsWith('--')) {
@@ -61,7 +75,7 @@ export function parseArgv(argv = []) {
       }
     }
   }
-  return { baselinePath, json, knipOutputPath };
+  return { baselinePath, json, knipOutputPath, production };
 }
 
 /**
@@ -84,36 +98,6 @@ export function loadBaseline(baselinePath) {
   }
 }
 
-/**
- * Pure helper: normalize knip's `--reporter json` output into a flat array of
- * `{ file, symbol }` rows. Knip emits `{ issues: [{ file, exports: [{ name, ... }], ... }, ...] }`.
- * Only `exports` rows are mapped — the dead-export ratchet ignores file-level,
- * dependency-level, and duplicate-level issues (knip surfaces those via
- * separate `rules` keys).
- *
- * @param {unknown} knipEnvelope The parsed knip JSON report.
- * @returns {Array<{ file: string, symbol: string }>}
- */
-export function extractRowsFromKnip(knipEnvelope) {
-  const rows = [];
-  if (!knipEnvelope || typeof knipEnvelope !== 'object') return rows;
-  const issues = Array.isArray(knipEnvelope.issues) ? knipEnvelope.issues : [];
-  for (const issue of issues) {
-    const file = issue?.file;
-    if (typeof file !== 'string' || file.length === 0) continue;
-    const exports_ = Array.isArray(issue.exports) ? issue.exports : [];
-    for (const e of exports_) {
-      const symbol =
-        (e && typeof e.name === 'string' && e.name) ||
-        (e && typeof e.symbol === 'string' && e.symbol) ||
-        null;
-      if (!symbol) continue;
-      rows.push({ file, symbol });
-    }
-  }
-  return rows;
-}
-
 /**
  * Pure helper: diff two `{ file, symbol }` row sets. Returns `added` (in
  * current but not baseline) and `removed` (in baseline but not current).
@@ -151,75 +135,24 @@ export function diffRows(baselineRows, currentRows) {
  * "no drift" signal. When added rows are present the summary includes a
  * "(gate fail)" marker so the ratchet violation is visible in CI output.
  *
+ * `label` distinguishes the two passes in CI logs, which run back to back and
+ * would otherwise emit two identical-looking summaries.
+ *
  * @param {{ added: Array, removed: Array }} diff
+ * @param {string} [label='dead-exports']
  * @returns {string}
  */
-export function renderDiff(diff) {
+export function renderDiff(diff, label = 'dead-exports') {
   const lines = [];
   for (const r of diff.added) lines.push(`+ ${r.file}: ${r.symbol}`);
   for (const r of diff.removed) lines.push(`- ${r.file}: ${r.symbol}`);
   const tag = diff.added.length > 0 ? '(gate fail)' : '(ok)';
   lines.push(
-    `[dead-exports] added=${diff.added.length} removed=${diff.removed.length} ${tag}`,
+    `[${label}] added=${diff.added.length} removed=${diff.removed.length} ${tag}`,
   );
   return lines.join('\n');
 }
 
-/**
- * Spawn `npx knip --reporter json --no-progress` and return the parsed
- * envelope. Returns `null` on spawn / parse failure — the caller logs the
- * underlying error and falls back to treating current rows as empty (which
- * surfaces every baseline row as "removed", a loud-but-safe signal).
- *
- * Exported as a hook so tests can stub the spawn without setting up a
- * functioning knip workspace.
- *
- * @param {{ cwd?: string, spawn?: typeof spawnSync }} [opts]
- * @returns {{ ok: true, envelope: unknown } | { ok: false, error: string }}
- */
-export function runKnip({ cwd = process.cwd(), spawn = spawnSync } = {}) {
-  const result = spawn(
-    process.platform === 'win32' ? 'npx.cmd' : 'npx',
-    ['knip', '--reporter', 'json', '--no-progress'],
-    {
-      cwd,
-      stdio: ['ignore', 'pipe', 'pipe'],
-      encoding: 'utf-8',
-      shell: process.platform === 'win32',
-    },
-  );
-  if (result.error) {
-    return { ok: false, error: `spawn failed: ${result.error.message}` };
-  }
-  const stdout = typeof result.stdout === 'string' ? result.stdout : '';
-  if (stdout.trim().length === 0) {
-    return { ok: false, error: 'knip produced empty stdout' };
-  }
-  try {
-    return { ok: true, envelope: JSON.parse(stdout) };
-  } catch (err) {
-    return {
-      ok: false,
-      error: `knip JSON parse failed: ${err?.message ?? err}`,
-    };
-  }
-}
-
-/**
- * Read a pre-captured knip JSON envelope from disk (for the `--knip-output`
- * test seam). Returns the parsed envelope or `null` on failure.
- *
- * @param {string} filePath
- * @returns {unknown}
- */
-function readKnipOutput(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Top-level CLI entry. Exported so tests can drive the full pipeline through
  * injected hooks without spawning knip.
@@ -242,10 +175,15 @@ export async function runCli({
   runKnipImpl = runKnip,
   loadBaselineImpl = loadBaseline,
 } = {}) {
-  const { baselinePath, json, knipOutputPath } = parseArgv(argv);
+  const { baselinePath, json, knipOutputPath, production } = parseArgv(argv);
+  const {
+    mode,
+    label,
+    baseline: defaultBaseline,
+  } = resolveDeadExportsMode(production);
   const resolvedBaselinePath = path.resolve(
     cwd,
-    baselinePath ?? path.join('baselines', 'dead-exports.json'),
+    baselinePath ?? defaultBaseline,
   );
   const baseline = loadBaselineImpl(resolvedBaselinePath);
   const baselineRows = Array.isArray(baseline?.rows) ? baseline.rows : [];
@@ -256,7 +194,7 @@ export async function runCli({
     knipEnvelope = readKnipOutput(path.resolve(cwd, knipOutputPath));
     if (!knipEnvelope) knipError = `failed to read ${knipOutputPath}`;
   } else {
-    const result = runKnipImpl({ cwd });
+    const result = runKnipImpl({ cwd, production });
     if (result.ok) {
       knipEnvelope = result.envelope;
     } else {
@@ -275,6 +213,7 @@ export async function runCli({
   if (json) {
     const envelope = {
       kind: 'dead-exports-report',
+      mode,
       baselinePath: resolvedBaselinePath,
       baselineRows,
       currentRows,
@@ -287,14 +226,14 @@ export async function runCli({
   } else {
     if (!baseline) {
       stderr.write(
-        `[dead-exports] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
+        `[${label}] ⚠ baseline not found at ${resolvedBaselinePath} — treating as empty\n`,
       );
     }
     if (knipError) {
-      stderr.write(`[dead-exports] ⚠ knip run failed: ${knipError}\n`);
+      stderr.write(`[${label}] ⚠ knip run failed: ${knipError}\n`);
     }
-    stdout.write(`\n--- dead-exports preview ---\n`);
-    stdout.write(`${renderDiff(diff)}\n`);
+    stdout.write(`\n--- ${label} preview ---\n`);
+    stdout.write(`${renderDiff(diff, label)}\n`);
   }
 
   return exitCode;

package/.agents/scripts/check-doc-links.js

@@ -257,8 +257,8 @@ function stripAnchorAndQuery(target) {
 // A slash token is `/<name>` where:
 //   - the preceding char is NOT a word char, `/`, `:`, `.`, `>`, `]`, `)`,
 //     so we don't match URL path segments or fragments embedded in paths
-//     like `temp/epic-<id>/lifecycle.ndjson` (preceded by `>`) or
-//     `temp/epic-[ID]/tickets.json` (preceded by `]`).
+//     like `temp/run-<id>/lifecycle.ndjson` (preceded by `>`) or
+//     `temp/run-[ID]/tickets.json` (preceded by `]`).
 //   - the following char is NOT a word char, `-`, or `.`, so file
 //     extensions like `/tickets.json` and identifier suffixes don't match.
 // The optional `(?::[a-z][a-z0-9-]*)?` tail captures the namespaced

package/.agents/scripts/check-lifecycle-lint.js

@@ -17,7 +17,7 @@
  *   Any module under `.agents/scripts/lib/orchestration/lifecycle/listeners/**`
  *   that calls `bus.on('*', …)` MUST NOT import a side-effecting module.
  *   The static blocklist is small (the modules that mutate GitHub state,
- *   the worktree, or write outside `temp/epic-<id>/`); we match by module
+ *   the worktree, or write outside `temp/run-<id>/`); we match by module
  *   specifier suffix to keep the rule simple and stable.
  *
  * Rule 3 — "Auto-merge lockout" (Story #2253 / Task #2255, Epic #2172

package/.agents/scripts/check-workflow-cli-lint.js

@@ -61,6 +61,19 @@ const BACKTICK_CALL_RE = /`[A-Za-z_$][\w$]*\s*\(/;
 const EXPORTED_FROM_RE = /\bexported from\b/;
 const LIB_IMPORT_RE = /\b(?:import|require)\(\s*['"`][^'"`]*scripts\/lib\//;
 
+/** A markdown table row (leading pipe, optionally indented). */
+const TABLE_ROW_RE = /^\s*\|/;
+/** A markdown heading of any level — the lookback boundary for Rule 4. */
+const HEADING_RE = /^\s*#{1,6}\s/;
+/** A backticked `--flag` occupying a table row's first cell. */
+const FLAG_CELL_RE = /^\s*\|\s*`?--[\w-]+/;
+/** A `.js` script filename — bare or path-qualified. */
+const SCRIPT_NAME_RE = /([\w./-]*[\w-]+\.js)\b/;
+/** A markdown table's delimiter row (`| --- | --- |`). */
+const TABLE_DELIMITER_RE = /^\s*\|[\s|:-]+\|?\s*$/;
+/** Minimum `--flag` rows before a table counts as a flag *table*. */
+export const MIN_FLAG_ROWS = 2;
+
 /**
  * Strip fenced code blocks (``` / ~~~), replacing their lines with empty
  * strings so line numbers stay stable. Complete runnable commands live in
@@ -106,6 +119,82 @@ export function toParagraphs(lines) {
   return paragraphs;
 }
 
+/**
+ * Rule 4 — CLI flag table. Find markdown tables that enumerate the `--flags`
+ * of a script the repo already owns, and flag them as duplicated surface.
+ *
+ * The script's own argument parser is the source of truth for its flags, and
+ * it prints them itself; a copy in prose is drift waiting to happen (the very
+ * drift Story #4546 removed). Prose must point at the command instead.
+ *
+ * The signal is deliberately narrow, to stay at zero false positives:
+ *
+ *   1. The table has at least `MIN_FLAG_ROWS` data rows whose **first cell**
+ *      is a `--flag`. One flag row among prose rows is a contract/behaviour
+ *      table (e.g. "Default | …", "`--dry-run` | …"), not a flag enumeration.
+ *   2. A `.js` script is named between the table and the nearest preceding
+ *      heading (inclusive) — i.e. the section is *about* that script, so the
+ *      table is restating its surface.
+ *
+ * A slash command's own argument table (`/plan`, `/deliver`) has no script
+ * behind it — nothing owns those flags but the workflow prose itself — so
+ * condition 2 leaves it alone by design.
+ *
+ * @param {string[]} rawLines unstripped source lines (fenced commands are the
+ *   usual place a script is named, so this rule reads the original text).
+ * @returns {Array<{ rule: string, line: number, hint: string }>}
+ */
+export function lintFlagTables(rawLines) {
+  const violations = [];
+  let inFence = false;
+
+  for (let i = 0; i < rawLines.length; i++) {
+    if (/^\s*(```|~~~)/.test(rawLines[i])) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence || !TABLE_ROW_RE.test(rawLines[i])) continue;
+
+    // Collect the contiguous table block starting here.
+    const start = i;
+    let end = i;
+    while (end + 1 < rawLines.length && TABLE_ROW_RE.test(rawLines[end + 1])) {
+      end += 1;
+    }
+    i = end; // continue scanning after this table
+
+    const flagRows = rawLines
+      .slice(start, end + 1)
+      .filter((l) => !TABLE_DELIMITER_RE.test(l) && FLAG_CELL_RE.test(l));
+    if (flagRows.length < MIN_FLAG_ROWS) continue;
+
+    // Look back to the nearest heading (inclusive) for a named script.
+    let script = null;
+    for (let j = start - 1; j >= 0; j--) {
+      const m = SCRIPT_NAME_RE.exec(rawLines[j]);
+      if (m) {
+        script = m[1];
+        break;
+      }
+      if (HEADING_RE.test(rawLines[j])) break;
+    }
+    if (!script) continue;
+
+    const base = script.split('/').pop();
+    violations.push({
+      rule: 'no-cli-flag-table',
+      line: start + 1,
+      hint:
+        `Workflow prose restates the flag surface of \`${base}\` as a table (${flagRows.length} flag rows). ` +
+        "The script's argument parser owns those flags, so a prose copy is drift waiting to happen. " +
+        `Delete the table and point at the command (\`node .agents/scripts/${base} …\`), keeping only the ` +
+        'judgement a reader cannot get from the command itself. If the script has no help output to point ' +
+        'at, add one — do not re-inline the table.',
+    });
+  }
+  return violations;
+}
+
 /**
  * Lint one markdown source. Returns violations
  * `{ rule, line, hint }[]` (empty when clean).
@@ -115,7 +204,9 @@ export function toParagraphs(lines) {
  */
 export function lintWorkflowSource(source) {
   const violations = [];
+  const rawLines = source.split('\n');
   const lines = stripFences(source);
+  violations.push(...lintFlagTables(rawLines));
   for (const para of toParagraphs(lines)) {
     if (IMPERATIVE_CALL_RE.test(para.text)) {
       violations.push({

package/.agents/scripts/deliver-recover.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+/**
+ * deliver-recover.js — probe a stranded Story's live state and print the ONE
+ * command that resumes it (Story #4543).
+ *
+ * Read-only by construction. This CLI mutates nothing: it reads the ticket's
+ * labels and lease, the Story branch locally and via its tracking ref, the
+ * worktree, and the PR (state + checks), then walks a fixed decision table
+ * and prints one command with the evidence it was derived from. It never
+ * prints a menu — a menu of options is what the operator already has, and it
+ * is the thing they cannot act on.
+ *
+ * The strand this exists for above all others is the **merged-but-label-stale**
+ * Story: a `/deliver` re-run refuses it outright, because
+ * `single-story-init.js` hard-errors on an already-closed Story. Before this
+ * surface, that Story had no automated way back.
+ *
+ * Usage:
+ *   node .agents/scripts/deliver-recover.js --story <STORY_ID> [--cwd <main-repo>]
+ *                                           [--json]
+ *
+ * Exit codes:
+ *   0 — a recovery shape was resolved and its next command printed (including
+ *       the "nothing to recover" shapes). Reading state is not a failure.
+ *   1 — the probe itself could not run (unreadable ticket, bad input).
+ *
+ * @see .agents/scripts/lib/orchestration/deliver-recover.js
+ * @see .agents/schemas/story-deliver-terminal.schema.json
+ */
+
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import {
+  recoverStory,
+  renderRecovery,
+} from './lib/orchestration/deliver-recover.js';
+import { PROJECT_ROOT } from './lib/project-root.js';
+import { createProvider } from './lib/provider-factory.js';
+
+const HELP = `Usage: node .agents/scripts/deliver-recover.js --story <id> [--cwd <main-repo>] [--json]
+
+Probes a Story's live delivery state — labels, lease, branch, worktree, PR
+state and checks — and prints the single next command that resumes it, with
+the evidence it was derived from. Read-only: mutates nothing.
+
+Flags:
+  --story   GitHub issue number of the Story (required).
+  --cwd     Main-repo checkout to probe (default: project root).
+  --json    Emit the full recovery envelope as JSON instead of prose.
+  --help    Show this message.
+`;
+
+export function parseArgv(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      story: { type: 'string' },
+      cwd: { type: 'string' },
+      json: { type: 'boolean', default: false },
+      help: { type: 'boolean', default: false },
+    },
+    strict: false,
+  });
+  return {
+    storyId: Number.parseInt(String(values.story ?? ''), 10),
+    cwd: values.cwd ?? null,
+    json: Boolean(values.json),
+    help: Boolean(values.help),
+  };
+}
+
+/**
+ * Probe and report. Exported for testing.
+ */
+export async function runDeliverRecover({
+  storyId: storyIdParam,
+  cwd: cwdParam,
+  json: jsonParam,
+  argv,
+  injectedProvider,
+  injectedConfig,
+  injectedGh,
+  injectedGitSpawn,
+} = {}) {
+  const parsed =
+    storyIdParam !== undefined
+      ? { storyId: storyIdParam, cwd: cwdParam ?? null, json: !!jsonParam }
+      : parseArgv(argv ?? process.argv.slice(2));
+
+  if (parsed.help) {
+    Logger.info(HELP);
+    return { success: true, result: null };
+  }
+  if (!Number.isInteger(parsed.storyId) || parsed.storyId <= 0) {
+    throw new Error(
+      'Usage: node deliver-recover.js --story <STORY_ID> [--cwd <main-repo>] [--json]',
+    );
+  }
+
+  const cwd = parsed.cwd ?? PROJECT_ROOT;
+  const config = injectedConfig || resolveConfig({ cwd });
+  const provider = injectedProvider || createProvider(config);
+
+  const recovery = await recoverStory({
+    storyId: parsed.storyId,
+    cwd,
+    provider,
+    config,
+    gh: injectedGh,
+    gitSpawnFn: injectedGitSpawn,
+  });
+
+  Logger.info(
+    parsed.json ? JSON.stringify(recovery, null, 2) : renderRecovery(recovery),
+  );
+  return { success: true, result: recovery };
+}
+
+runAsCli(import.meta.url, runDeliverRecover, { source: 'deliver-recover' });

package/.agents/scripts/drain-pending-cleanup.js

@@ -8,7 +8,7 @@
  * any still-stuck entries by enumerating the processes holding handles
  * inside the worktree path and terminating them.
  *
- * Invoked by `/deliver`, `/epic-plan-spec` / `/epic-plan-decompose`
+ * Invoked by `/deliver` and `/plan`
  * (via `drainPendingCleanupAtBoot` → `worktree-sweep.js`), and
  * `story-close` so the pending-cleanup ledger drains automatically
  * across the sprint lifecycle. Operators can also run it standalone:

package/.agents/scripts/evidence-gate.js

@@ -13,42 +13,22 @@
  *
  * Usage:
  *   node .agents/scripts/evidence-gate.js \
- *     (--epic-id <epicId> | --standalone) --scope-id <storyOrEpicId> --gate <name> \
+ *     --standalone --scope-id <storyId> --gate <name> \
  *     [--worktree <path>] [--no-evidence] -- <cmd> [args...]
  *
  * Examples:
- *   node .agents/scripts/evidence-gate.js --epic-id 802 --scope-id 817 --gate lint -- npm run lint
- *   node .agents/scripts/evidence-gate.js --epic-id 1030 --scope-id 1030 --gate test -- npm test
- *   node .agents/scripts/evidence-gate.js --epic-id 1114 --scope-id 1120 --gate test \
- *     --worktree .worktrees/story-1120 -- npm test
  *   node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 --gate lint \
  *     --worktree .worktrees/story-4250 -- npm run lint
+ *   node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 --gate test \
+ *     --worktree .worktrees/story-4250 -- npm test
  *
- * Either `--epic-id` or `--standalone` is required. When `scope-id ===
- * epic-id` the evidence file is Epic-scoped
- * (`<tempRoot>/epic-<eid>/validation-evidence.json`); when `scope-id !==
- * epic-id` it is Story-scoped under
- * `<tempRoot>/epic-<eid>/story-<sid>/validation-evidence.json`. With
- * `--standalone` (Story #4250) the file is anchored on the Story id alone at
+ * `--standalone` (Story #4250) is required: the evidence file is anchored on
+ * the Story id at
  * `<tempRoot>/standalone/stories/story-<sid>/validation-evidence.json` — the
  * same keyspace the standalone close consults, so the acceptance-self-eval
  * critic's verify[] runs (lint / typecheck) are shared with the close.
- *
- * **Worktree-aware spawn (Story #1120).** `--cwd` (default `PROJECT_ROOT`)
- * is the *evidence cwd* — it locates the per-Epic temp tree under the main
- * checkout's `.git/`. `--worktree` is the *spawn cwd* — when supplied, the
- * gate runner is launched with `cwd: <worktree>` and the HEAD-SHA used as
- * the evidence key is read from the worktree (so caching keys to the Story
- * branch's HEAD, not the main branch's). When `--worktree` is omitted,
- * spawn cwd falls back to `--cwd` (legacy single-tree behaviour).
- *
- * Exit codes:
- *   0 — gate passed (or skipped via evidence)
- *   N — gate failed (passes through the runner's exit code)
- *
- * `--no-evidence` forces the runner regardless of recorded state. The
- * evidence file is gitignored — evidence is a perf optimization, not a
- * trust boundary; pre-push hooks and CI continue to verify independently.
+ * v2.0.0 removed the Epic tier along with the `--epic-id` Epic-keyed
+ * keyspace.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -88,7 +68,6 @@ export function parseWrapperArgs(argv) {
     args: argv,
     options: {
       'scope-id': { type: 'string' },
-      'epic-id': { type: 'string' },
       gate: { type: 'string' },
       'no-evidence': { type: 'boolean', default: false },
       standalone: { type: 'boolean', default: false },
@@ -98,10 +77,8 @@ export function parseWrapperArgs(argv) {
     strict: false,
   });
   const scopeId = Number.parseInt(values['scope-id'] ?? '', 10);
-  const epicId = Number.parseInt(values['epic-id'] ?? '', 10);
   return {
     scopeId: Number.isNaN(scopeId) || scopeId <= 0 ? null : scopeId,
-    epicId: Number.isNaN(epicId) || epicId <= 0 ? null : epicId,
     standalone: values.standalone === true,
     gate: values.gate ?? null,
     useEvidence: values['no-evidence'] !== true,
@@ -126,15 +103,13 @@ function resolveHeadShaDefault(cwd, gitSpawnFn) {
  * Exported for tests + the CLI `main()`.
  *
  * @param {object} params
- * @param {number}   params.scopeId      — Story / Epic ID (positive integer).
- * @param {number|null} [params.epicId]  — Parent Epic id (Epic-keyed path).
- * @param {boolean}  [params.standalone] — When true, route to the
- *   storyId-anchored standalone keyspace instead of the Epic-keyed path
- *   (Story #4250). Substitutes for `epicId`.
+ * @param {number}   params.scopeId      — Story ID (positive integer).
+ * @param {boolean}  [params.standalone] — Required. Routes to the
+ *   storyId-anchored standalone keyspace (Story #4250).
  * @param {string}   params.gate         — Logical gate name (`lint`, `typecheck`, …).
  * @param {boolean}  params.useEvidence  — When false, force the runner.
- * @param {string}   params.cwd          — Evidence cwd (locates the per-Epic
- *   temp tree). The runner is spawned in `worktreePath` when set, else `cwd`.
+ * @param {string}   params.cwd          — Evidence cwd (locates the temp
+ *   tree). The runner is spawned in `worktreePath` when set, else `cwd`.
  * @param {string|null} [params.worktreePath] — Spawn cwd override (Story #1120).
  *   When set, the runner runs in the Story worktree and the HEAD-SHA used as
  *   the evidence cache key is read from the worktree, not from `cwd`.
@@ -159,7 +134,6 @@ export async function runEvidenceGate(params, deps = {}) {
   } = deps;
   const {
     scopeId,
-    epicId,
     standalone = false,
     gate,
     useEvidence,
@@ -168,31 +142,27 @@ export async function runEvidenceGate(params, deps = {}) {
     runnerArgs,
   } = params ?? {};
 
-  // `--epic-id` is required for the Epic-keyed path; `--standalone` (Story
-  // #4250) substitutes for it and routes the evidence file to the
-  // storyId-anchored standalone keyspace so the acceptance-self-eval critic
-  // can record verify[] evidence into the same keyspace the standalone close
-  // consults.
+  // `--standalone` (Story #4250) routes the evidence file to the
+  // storyId-anchored keyspace so the acceptance-self-eval critic can record
+  // verify[] evidence into the same keyspace the standalone close consults.
   if (
     !scopeId ||
-    (!epicId && !standalone) ||
+    !standalone ||
     !gate ||
     !runnerArgs ||
     runnerArgs.length === 0
   ) {
     logger.fatal(
-      'Usage: node evidence-gate.js (--epic-id <epicId> | --standalone) --scope-id <id> --gate <name> [--worktree <path>] [--no-evidence] -- <cmd> [args...]',
+      'Usage: node evidence-gate.js --standalone --scope-id <id> --gate <name> [--worktree <path>] [--no-evidence] -- <cmd> [args...]',
     );
     return { status: 1, skipped: false };
   }
-  // Evidence-store opts shared by shouldSkip + recordPass below. `standalone`
-  // routes to the storyId-anchored keyspace; otherwise the Epic-keyed path
-  // resolves under `epicId`.
-  const evidenceStoreOpts = { cwd, epicId, standalone };
+  // Evidence-store opts shared by shouldSkip + recordPass below.
+  const evidenceStoreOpts = { cwd, standalone };
 
   // Spawn cwd is the worktree when supplied — every gate command sees the
   // Story branch's tree, not the main checkout. Evidence cwd stays anchored
-  // to the main checkout so the per-Epic temp tree resolves under the main
+  // to the main checkout so the temp tree resolves under the main
   // `.git/`. The HEAD-SHA used as the cache key is read from the spawn cwd
   // (the worktree), so cache entries key against the Story branch's HEAD.
   const spawnCwd = worktreePath ?? cwd;