mandrel 1.90.0 → 1.92.0

package/.agents/scripts/analyze-execution.js

@@ -41,6 +41,16 @@
  *   node .agents/scripts/analyze-execution.js --story <sid> --epic <eid> \
  *       [--phase-timings <path>]
  *   node .agents/scripts/analyze-execution.js --epic <eid>
+ *   node .agents/scripts/analyze-execution.js --epic <eid> --plan-metrics-json
+ *
+ * `--plan-metrics-json` (Epic #4474 PR7 — the G2 extraction surface) is a
+ * **local read-only** mode: it reads the per-Epic plan-metrics ledger
+ * (`temp/epic-<eid>/plan-metrics.json`), rolls it up with
+ * `summarizePlanMetrics`, and prints one compact JSON envelope
+ * `{ epicId, planMetrics, summaryLine }` to stdout — no provider call, no
+ * comment write, all logs on stderr — so a bench cohort can extract
+ * turns-per-plan / per-mode invocation counts / critic skips without
+ * scraping GitHub or the human log.
  *
  * @see docs/data-dictionary.md §StoryPerfSummary, §EpicPerfReport
  */
@@ -51,7 +61,7 @@ import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
 import { signalsFile } from './lib/config/temp-paths.js';
 import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
-import { Logger } from './lib/Logger.js';
+import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
 import { computeBaselineRefreshRate } from './lib/observability/baseline-refresh-rate.js';
 import {
   computeEpicPerfReport,
@@ -72,6 +82,11 @@ import {
   renderStoryBody,
   STORY_PERF_TYPE,
 } from './lib/observability/perf-report-render.js';
+import {
+  readPlanMetrics,
+  renderPlanMetricsSummaryLine,
+  summarizePlanMetrics,
+} from './lib/orchestration/plan-metrics.js';
 import { upsertStructuredComment } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 
@@ -284,11 +299,34 @@ export async function runEpicMode(ctx) {
   logger.info?.(
     `[analyze-execution] epic-perf-report upserted on Epic #${epicId} (commentId=${result.commentId}, stories=${summaries.length})`,
   );
+
+  // Plan-metrics roll-up (#4474 PR1) — surface the plan-CLI invocation
+  // ledger (`temp/epic-<id>/plan-metrics.json`) alongside the perf report.
+  // Additive and non-fatal: a missing or unreadable ledger yields `null`.
+  let planMetrics = null;
+  try {
+    planMetrics = summarizePlanMetrics(
+      await readPlanMetrics(epicId, ctx.config),
+    );
+    if (planMetrics) {
+      logger.info?.(
+        `[analyze-execution] ${renderPlanMetricsSummaryLine(planMetrics)}`,
+      );
+    }
+  } catch (err) {
+    logger.warn?.(
+      `[analyze-execution] plan-metrics read failed (non-fatal): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+
   return {
     commentId: result.commentId,
     payload,
     baselineRefreshRate,
     qualityGateFriction,
+    planMetrics,
   };
 }
 
@@ -300,6 +338,7 @@ function parseCli(argv) {
       epic: { type: 'string' },
       'phase-timings': { type: 'string' },
       'window-days': { type: 'string' },
+      'plan-metrics-json': { type: 'boolean', default: false },
       cwd: { type: 'string' },
     },
     strict: false,
@@ -316,10 +355,33 @@ function parseCli(argv) {
     phaseTimingsPath: values['phase-timings'] ?? null,
     windowDays:
       Number.isInteger(windowDays) && windowDays > 0 ? windowDays : null,
+    planMetricsJson: values['plan-metrics-json'] === true,
     cwd: values.cwd ?? null,
   };
 }
 
+/**
+ * `--plan-metrics-json` — local, read-only G2 extraction surface (Epic
+ * #4474 PR7). Reads the per-Epic plan-metrics ledger and prints one
+ * compact JSON envelope to stdout. No provider, no comment write; stdout
+ * is reserved for the envelope (all logs on stderr). A missing ledger is
+ * not an error — it yields `planMetrics: null` so a cohort script can
+ * branch on the field instead of the exit code.
+ *
+ * @param {{ epicId: number, config: object }} input
+ * @returns {Promise<{ epicId: number, planMetrics: object|null, summaryLine: string }>}
+ */
+export async function runPlanMetricsJsonMode({ epicId, config }) {
+  const planMetrics = summarizePlanMetrics(
+    await readPlanMetrics(epicId, config),
+  );
+  return {
+    epicId,
+    planMetrics,
+    summaryLine: renderPlanMetricsSummaryLine(planMetrics),
+  };
+}
+
 async function main(argv = process.argv.slice(2)) {
   const args = parseCli(argv);
 
@@ -331,6 +393,19 @@ async function main(argv = process.argv.slice(2)) {
 
   const cwd = path.resolve(args.cwd ?? PROJECT_ROOT);
   const config = resolveConfig({ cwd });
+
+  if (args.planMetricsJson) {
+    // Stdout is reserved for the compact envelope — flip every log sink to
+    // stderr before any pipeline code runs (Story #2278 discipline).
+    routeAllOutputToStderr();
+    const result = await runPlanMetricsJsonMode({
+      epicId: args.epicId,
+      config,
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+
   const provider = createProvider(config);
 
   if (args.storyId) {

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

@@ -50,6 +50,9 @@ export const RETIRED_COMMANDS = new Set([
   'agents-bootstrap-github',
   'single-story-plan',
   'mandrel',
+  // #4482 — dead workflow surface retired (host-native equivalents).
+  'explain',
+  'git-merge-pr',
 ]);
 
 // Tokens that look like `/foo` in prose but are not slash commands. Tokens

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

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+/* node:coverage ignore file */
+
+/**
+ * check-workflow-cli-lint.js — enforce the "no workflow instructs a
+ * no-CLI library call" rule (Epic #4474 PR5; sibling of
+ * check-lifecycle-lint.js).
+ *
+ * The measured failure mode this rule kills: workflow prose that tells the
+ * host LLM to "Call `someExportedFunction({...})` exported from
+ * `lib/whatever.js`". There is no runnable form of that instruction, so the
+ * model greps the framework source and writes throwaway `.mjs` shims to
+ * invoke the export — the mandrel-bench N=2 cohort measured ~12–15 turns of
+ * shim-writing per plan for exactly this pattern. Workflows must instruct
+ * `node .agents/scripts/<cli>.js …` commands instead.
+ *
+ * Scope: every `*.md` under `.agents/workflows/`.
+ *
+ * Heuristic (tuned to zero false positives on the surviving corpus —
+ * descriptive mentions like "the automatic paths call `foo()`" are prose
+ * about script internals, not instructions, and are NOT flagged):
+ *
+ *   Rule 1 — imperative library call. A paragraph (fenced code blocks
+ *     stripped; lines joined) matching /\b(Call|Invoke)\s+`ident\s*\(/ —
+ *     a capitalized imperative directly instructing a function call.
+ *
+ *   Rule 2 — "exported from" instruction. A paragraph containing both a
+ *     backticked call token (`ident(`) and the phrase "exported from" —
+ *     the canonical shape of the retired Phase 2/3/4 prose.
+ *
+ *   Rule 3 — prose-level lib import. `import(` / `require(` naming a
+ *     `scripts/lib/` path OUTSIDE a fenced code block. (A complete,
+ *     runnable `node -e` one-liner inside a fenced block is exempt: it
+ *     costs zero shim-writing turns because it is executable as written.)
+ *
+ * Exit codes:
+ *   0 — clean.
+ *   1 — at least one violation; offending file + paragraph line printed
+ *       to stderr.
+ *
+ * Ships as part of `npm run lint` (run-lint.js task list), alongside the
+ * lifecycle lint and the label-vocabulary lint.
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runAsCli } from './lib/cli-utils.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+export const DEFAULT_WORKFLOWS_DIR = path.join(
+  REPO_ROOT,
+  '.agents',
+  'workflows',
+);
+
+const IMPERATIVE_CALL_RE = /\b(?:Call|Invoke)\s+`[A-Za-z_$][\w$]*\s*\(/;
+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\//;
+
+/**
+ * Strip fenced code blocks (``` / ~~~), replacing their lines with empty
+ * strings so line numbers stay stable. Complete runnable commands live in
+ * fences and are exempt by design (see header).
+ *
+ * @param {string} source
+ * @returns {string[]} lines with fenced content blanked.
+ */
+export function stripFences(source) {
+  const lines = source.split('\n');
+  let inFence = false;
+  return lines.map((line) => {
+    const fence = /^\s*(```|~~~)/.test(line);
+    if (fence) {
+      inFence = !inFence;
+      return '';
+    }
+    return inFence ? '' : line;
+  });
+}
+
+/**
+ * Split blanked lines into paragraphs — runs of consecutive non-empty
+ * lines — keeping the 1-based line number of each paragraph's first line.
+ *
+ * @param {string[]} lines
+ * @returns {Array<{ text: string, line: number }>}
+ */
+export function toParagraphs(lines) {
+  const paragraphs = [];
+  let buf = [];
+  let start = 0;
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim().length > 0) {
+      if (buf.length === 0) start = i + 1;
+      buf.push(lines[i]);
+    } else if (buf.length > 0) {
+      paragraphs.push({ text: buf.join(' '), line: start });
+      buf = [];
+    }
+  }
+  if (buf.length > 0) paragraphs.push({ text: buf.join(' '), line: start });
+  return paragraphs;
+}
+
+/**
+ * Lint one markdown source. Returns violations
+ * `{ rule, line, hint }[]` (empty when clean).
+ *
+ * @param {string} source markdown content.
+ * @returns {Array<{ rule: string, line: number, hint: string }>}
+ */
+export function lintWorkflowSource(source) {
+  const violations = [];
+  const lines = stripFences(source);
+  for (const para of toParagraphs(lines)) {
+    if (IMPERATIVE_CALL_RE.test(para.text)) {
+      violations.push({
+        rule: 'no-cli-library-call',
+        line: para.line,
+        hint:
+          'Workflow prose instructs calling a function directly ("Call/Invoke `fn(...)`"). ' +
+          'There is no runnable form of that instruction — the model must write a throwaway shim. ' +
+          'Instruct a `node .agents/scripts/<cli>.js …` command instead (add a CLI if none exists).',
+      });
+      continue;
+    }
+    if (EXPORTED_FROM_RE.test(para.text) && BACKTICK_CALL_RE.test(para.text)) {
+      violations.push({
+        rule: 'no-cli-library-call',
+        line: para.line,
+        hint:
+          'Workflow prose points at an exported library function ("`fn(...)` exported from …") ' +
+          'with no CLI entrypoint. Instruct a `node .agents/scripts/<cli>.js …` command instead.',
+      });
+      continue;
+    }
+    if (LIB_IMPORT_RE.test(para.text)) {
+      violations.push({
+        rule: 'no-prose-lib-import',
+        line: para.line,
+        hint:
+          'Workflow prose (outside a fenced code block) instructs importing a scripts/lib module. ' +
+          'Give a complete runnable command in a fenced block, or add a CLI entrypoint.',
+      });
+    }
+  }
+  return violations;
+}
+
+/**
+ * Recursively collect `*.md` files under a directory.
+ *
+ * @param {string} dir
+ * @returns {string[]} absolute paths.
+ */
+export function collectMarkdown(dir) {
+  const out = [];
+  for (const entry of readdirSync(dir)) {
+    const abs = path.join(dir, entry);
+    const st = statSync(abs);
+    if (st.isDirectory()) out.push(...collectMarkdown(abs));
+    else if (entry.endsWith('.md')) out.push(abs);
+  }
+  return out;
+}
+
+/**
+ * Run the check over a workflows directory. Exported for tests (pass a
+ * fixture directory).
+ *
+ * @param {string} [workflowsDir]
+ * @returns {Array<{ file: string, rule: string, line: number, hint: string }>}
+ */
+export function runCheck(workflowsDir = DEFAULT_WORKFLOWS_DIR) {
+  const violations = [];
+  for (const file of collectMarkdown(workflowsDir)) {
+    const source = readFileSync(file, 'utf8');
+    for (const v of lintWorkflowSource(source)) {
+      violations.push({ file: path.relative(REPO_ROOT, file), ...v });
+    }
+  }
+  return violations;
+}
+
+async function main() {
+  const violations = runCheck();
+  if (violations.length === 0) {
+    process.stdout.write(
+      '[workflow-cli-lint] clean: no workflow instructs a no-CLI library call.\n',
+    );
+    return 0;
+  }
+  for (const v of violations) {
+    process.stderr.write(
+      `[workflow-cli-lint][${v.rule}] ${v.file}:${v.line}\n  ${v.hint}\n`,
+    );
+  }
+  return 1;
+}
+
+await runAsCli(import.meta.url, main, {
+  source: 'check-workflow-cli-lint',
+  propagateExitCode: true,
+});

package/.agents/scripts/epic-audit-recheck.js

@@ -9,7 +9,7 @@
  * `.agents/workflows/helpers/code-review.md` Step 4.6) and emit the
  * subset of audit lenses whose `filePatterns` overlap that list.
  *
- * The CLI is intentionally narrower than `select-audits.js`: it does NOT
+ * The CLI is intentionally narrower than `lib/audit-suite/selector.js`: it does NOT
  * run a git diff and does NOT consult the Epic ticket body for keyword
  * triggers. The auto-fix tail already knows exactly which paths it touched —
  * only file-pattern overlap is relevant for deciding which lenses are stale

package/.agents/scripts/epic-deliver-preflight.js

@@ -11,7 +11,12 @@
  *      `storyCount`, `installCostSeconds`, `dependencyDepth`,
  *      `githubApiRequests`, `claudeQuotaTokens`, plus `breaches`
  *      (the non-empty subset of `delivery.preflight.max*` thresholds the
- *      estimate exceeds).
+ *      estimate exceeds), plus `remoteVerified` / `remoteProbe` — the
+ *      issue #4483 deterministic remote evidence (`git remote get-url
+ *      origin` + bounded `git ls-remote origin HEAD`). On
+ *      `remoteVerified: false` the workflow MUST flip the Epic to
+ *      `agent::blocked` quoting `remoteProbe.detail` — inline delivery to
+ *      local `main` is never a sanctioned fallback.
  *   2. When `--post` is set (and `--dry-run` is not), an upserted
  *      `delivery-preflight` structured comment on the Epic ticket so
  *      reviewers reading the Epic discover the same numbers without
@@ -66,6 +71,7 @@ import {
   computeBaseSha,
   writePreflightCache,
 } from './lib/orchestration/preflight-cache.js';
+import { verifyRemote } from './lib/orchestration/remote-verifier.js';
 import { upsertStructuredComment } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 
@@ -218,10 +224,23 @@ export function renderPreflightBody({
   estimate,
   breaches,
   thresholds,
+  remote,
 }) {
   const lines = [];
   lines.push(`### 🛫 Delivery preflight — Epic #${epicId}`);
   lines.push('');
+  // Issue #4483 — verified remote evidence at entry. Rendered before the
+  // metric table so a reviewer (and the orchestrating agent) sees the
+  // land-or-block fact first. Omitted when the caller has no probe result
+  // (legacy callers / tests that only exercise the estimate math).
+  if (remote) {
+    lines.push(
+      remote.remoteVerified
+        ? `✅ **remoteVerified: true** — ${remote.detail}`
+        : `⛔ **remoteVerified: false** — ${remote.detail} — \`/deliver\` MUST transition the Epic to \`agent::blocked\` quoting this probe; inline delivery to local \`main\` is forbidden.`,
+    );
+    lines.push('');
+  }
   lines.push('| Metric | Estimate | Threshold |');
   lines.push('| --- | ---: | ---: |');
   const rows = [
@@ -276,6 +295,7 @@ export function renderPreflightBody({
  *   perStoryClaudeTokens?: number,
  *   injectedProvider?: object,
  *   injectedConfig?: object,
+ *   verifyRemoteFn?: typeof verifyRemote,
  * }} args
  */
 export async function runPreflight({
@@ -288,6 +308,7 @@ export async function runPreflight({
   perStoryClaudeTokens,
   injectedProvider,
   injectedConfig,
+  verifyRemoteFn = verifyRemote,
 }) {
   if (!Number.isInteger(epicId) || epicId <= 0) {
     throw new TypeError('runPreflight: --epic must be a positive integer');
@@ -297,6 +318,13 @@ export async function runPreflight({
   const provider = injectedProvider ?? createProvider(config);
   const thresholds = getPreflight(config);
 
+  // Issue #4483 — deterministic remote evidence at entry. Probe BEFORE any
+  // provider work so the envelope always carries verified fact (not the
+  // agent's perception) about whether a live, pushable `origin` exists.
+  // The CLI records; the `/deliver` workflow owns the `agent::blocked`
+  // transition on `remoteVerified: false` (same split as breach handling).
+  const remote = verifyRemoteFn({ cwd });
+
   // Compose the same two phases /deliver Phase 1 runs so the
   // preflight numbers match the actual dispatch plan.
   const ctx = { epicId, provider };
@@ -348,6 +376,13 @@ export async function runPreflight({
     thresholds,
     baseSha,
     cacheWritten,
+    // Issue #4483 — verified remote evidence. `remoteVerified: false`
+    // REQUIRES the workflow to block explicitly (never build inline).
+    remoteVerified: remote.remoteVerified,
+    remoteProbe: {
+      remoteUrl: remote.remoteUrl,
+      detail: remote.detail,
+    },
   };
 
   if (post && !dryRun) {
@@ -356,6 +391,7 @@ export async function runPreflight({
       estimate,
       breaches,
       thresholds,
+      remote,
     });
     await upsertStructuredComment(provider, epicId, 'delivery-preflight', body);
     envelope.commentUpserted = true;

package/.agents/scripts/epic-plan-clarity.js

@@ -34,6 +34,7 @@ import {
 } from './lib/config-resolver.js';
 import { scoreEpicBody } from './lib/epic-plan-clarity.js';
 import { Logger, routeAllOutputToStderr } from './lib/Logger.js';
+import { recordPlanInvocation } from './lib/orchestration/plan-metrics.js';
 import { upsertStructuredComment } from './lib/orchestration/ticketing.js';
 import { createProvider } from './lib/provider-factory.js';
 
@@ -175,7 +176,11 @@ async function main() {
   // additions cannot silently corrupt the captured file.
   if (values['emit-context']) {
     routeAllOutputToStderr();
-    const envelope = await buildClarityContext({ epicId, provider });
+    // Plan-metrics ledger (#4474 PR1): stamp entry/exit + mode.
+    const envelope = await recordPlanInvocation(
+      { cli: 'epic-plan-clarity', mode: 'emit-context', epicId, config },
+      () => buildClarityContext({ epicId, provider }),
+    );
     const json = values.pretty
       ? JSON.stringify(envelope, null, 2)
       : JSON.stringify(envelope);
@@ -190,11 +195,16 @@ async function main() {
   }
 
   const updatedBody = await readFile(values['updated-body'], 'utf8');
-  const result = await persistClarityUpdate({
-    epicId,
-    updatedBody,
-    provider,
-  });
+  // Plan-metrics ledger (#4474 PR1): stamp entry/exit + mode.
+  const result = await recordPlanInvocation(
+    { cli: 'epic-plan-clarity', mode: 'persist', epicId, config },
+    () =>
+      persistClarityUpdate({
+        epicId,
+        updatedBody,
+        provider,
+      }),
+  );
   process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 }
 

package/.agents/scripts/epic-plan-decompose.js

@@ -1,76 +1,54 @@
 #!/usr/bin/env node
+
 /* node:coverage ignore file */
 
 /**
- * epic-plan-decompose.js — Story #2466 thin CLI shell.
- *
- * Phase 8 (decompose) entry point for the split planning flow. The
- * deterministic decomposer engine and reconciler-based persist flow
- * have been split into phase modules under
- * `lib/orchestration/epic-plan-decompose/phases/`:
- *
- *   1. planning-artifacts — `resolveConflictPolicy`.
- *   2. dag                — `resolveDependencies`,
- *                            `orderTicketsForCreation`.
- *   3. context            — `buildDecomposerSystemPrompt`,
- *                            `buildDecompositionContext`.
- *   4. creation           — sub-issue link reconciliation, Epic label
- *                            transitions, and the advisory ticket-cap
- *                            warning (`reconcileSubIssueLinks`,
- *                            `setEpicLabel`, `warnTicketCapNearLimit`).
- *   5. persist            — `runDecomposePhase` (reconciler-based flow).
- *   6. cli                — argument parsing + `main()` pipeline.
- *
- * Modes:
- *   --emit-context     Prints the decomposer authoring context (Epic body,
- *                      Tech Spec body, risk heuristics, system prompt,
- *                      ticket cap) as JSON. The authoring middle is the
- *                      `epic-plan-decompose-author` Skill
- *                      (`.agents/skills/core/epic-plan-decompose-author/SKILL.md`).
+ * epic-plan-decompose.js — RETIRED delegate CLI (Epic #4474, PR7).
  *
- *   (default)          Given an author-provided tickets JSON file,
- *                      persists the Feature/Story/Task hierarchy via the
- *                      structural reconciler, flips the Epic to
- *                      `agent::ready`, and updates the `epic-plan-state`
- *                      structured comment.
+ * The 12-phase plan pipeline collapsed to context → author → persist:
  *
- * --force re-decomposes (closes existing child Features/Stories/Tasks).
+ *   - `--emit-context` moved to `plan-context.js` (the single authoring
+ *     envelope carries the decomposer context — ticket schema, risk
+ *     heuristics, ticket cap — alongside the spec half).
+ *   - The persist half (ticket validator, file-assumption gate, DAG,
+ *     budget, story creation, healthcheck, `agent::ready` flip) moved to
+ *     `plan-persist.js` (single GitHub-write surface).
  *
- * Exit codes:
- *   0 — phase complete, Epic is now `agent::ready`.
- *   1 — fatal error (see stderr).
+ * This file is a **re-export shim only** — it carries external importers of
+ * the historic named-export surface one more release (#4474 design §6 PR7
+ * risk note) and is deleted in the next release. Internal consumers import
+ * the phase modules directly; do not add new imports of this file.
  *
- * Public CLI surface and named exports are byte-identical to the pre-
- * refactor implementation.
+ * Invoking it as a CLI is refused with a pointer to the successor CLIs.
  */
 
-// Fail-fast if the framework's runtime deps are not installed — must be the
-// first import so the check runs before any third-party-importing sibling
-// module is evaluated (Story #3432).
-import './lib/runtime-deps/ensure-installed.js';
-import { runAsCli } from './lib/cli-utils.js';
-import { main } from './lib/orchestration/epic-plan-decompose/phases/cli.js';
-import {
-  buildDecomposerSystemPrompt,
-  buildDecompositionContext,
-} from './lib/orchestration/epic-plan-decompose/phases/context.js';
-import {
-  orderTicketsForCreation,
-  resolveDependencies,
-} from './lib/orchestration/epic-plan-decompose/phases/dag.js';
-import { runDecomposePhase } from './lib/orchestration/epic-plan-decompose/phases/persist.js';
+// cli-opt-out: retired delegate shim (Epic #4474 PR7) — deliberately
+// refuses CLI execution with a pointer to plan-context.js/plan-persist.js
+// instead of wiring runAsCli around a dead main().
+import { pathToFileURL } from 'node:url';
 
-// Named exports preserved for the existing test surface. The pre-refactor
-// module published these and the consumers (`tests/ticket-decomposer.test.js`,
-// `tests/scripts/epic-plan-decompose.body-preservation.test.js`,
-// `tests/scripts/epic-plan-decompose.sub-issue-safety-net.test.js`,
-// `tests/scripts/epic-plan.spec-flow.test.js`) still depend on them.
 export {
   buildDecomposerSystemPrompt,
   buildDecompositionContext,
+} from './lib/orchestration/epic-plan-decompose/phases/context.js';
+export {
   orderTicketsForCreation,
   resolveDependencies,
-  runDecomposePhase,
-};
+} from './lib/orchestration/epic-plan-decompose/phases/dag.js';
+export { runDecomposePhase } from './lib/orchestration/epic-plan-decompose/phases/persist.js';
 
-runAsCli(import.meta.url, main, { source: 'epic-plan-decompose' });
+// CLI execution is retired — fail loudly with the successor surface instead
+// of silently doing nothing (a stale automation script should break visibly).
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  process.stderr.write(
+    '[epic-plan-decompose] retired (Epic #4474): the plan pipeline is ' +
+      'context → author → persist.\n' +
+      '  - authoring envelope:  node .agents/scripts/plan-context.js --epic <id>\n' +
+      '  - persist (all gates): node .agents/scripts/plan-persist.js --epic <id> --tickets ...\n' +
+      'This file survives one release as an import shim only.\n',
+  );
+  process.exit(1);
+}