mandrel 1.57.0

package/.agents/scripts/quality-preview.js

@@ -0,0 +1,327 @@
+#!/usr/bin/env node
+/**
+ * .agents/scripts/quality-preview.js — Per-file MI/CRAP delta preview.
+ *
+ * Runs the maintainability + CRAP gates in-process via the per-kind
+ * preview runners under `lib/baselines/preview-gates.js`, then merges
+ * their structured envelopes into a single per-file delta table
+ * contributors can read while the diff is still warm. Designed for
+ * three callers:
+ *
+ *   1. `npm run quality:preview`   — interactive operator, pretty table.
+ *   2. `npm run quality:watch`     — chokidar wrapper re-emits on save.
+ *   3. `.husky/pre-commit`         — block the commit on threshold violations.
+ *
+ * Story #1394 (Epic #1386) flipped the default scope of both gates to
+ * diff-against-`main`, so passing `--changed-since HEAD` here mirrors what the
+ * pre-commit hook actually wants: the delta the operator is about to commit.
+ *
+ * The CLI exits 0 when both envelopes report zero violations and the script
+ * could not surface a regression. Any violation in either envelope, or any
+ * non-zero gate exit, propagates as a non-zero exit code so git/husky/CI
+ * surface the failure. The merge logic is exported as `mergeEnvelopes` for
+ * unit testing without spawning the gate scripts.
+ */
+
+import path from 'node:path';
+import process from 'node:process';
+import {
+  runCrapPreview,
+  runMaintainabilityPreview,
+} from './lib/baselines/preview-gates.js';
+
+/**
+ * Parse `--changed-since <ref>` from argv. Defaults to `HEAD` when the flag is
+ * present without a value. Returns `null` when the flag is absent so callers
+ * can fall through to the gate scripts' own diff defaults.
+ *
+ * @param {string[]} argv
+ * @returns {string | null}
+ */
+export function parseChangedSinceArg(argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--changed-since') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) return next;
+      return 'HEAD';
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect `--json` (machine-readable mode). When set, the merged envelope is
+ * written to stdout as JSON instead of the human-readable table; the exit code
+ * still reflects gate health so CI runners can fail fast.
+ *
+ * @param {string[]} argv
+ * @returns {boolean}
+ */
+export function parseJsonFlag(argv) {
+  return argv.includes('--json');
+}
+
+/**
+ * Detect `--staged` (pre-commit mode). Used by `.husky/pre-commit` to
+ * scope both MI and CRAP preview gates to `git diff --name-only --cached`
+ * so only index (staged) paths are scored. When present, `--staged` takes
+ * precedence over `--changed-since`.
+ *
+ * @param {string[]} argv
+ * @returns {boolean}
+ */
+export function parseStagedFlag(argv) {
+  return argv.includes('--staged');
+}
+
+/**
+ * Merge an MI envelope (from `runMaintainabilityPreview`) and a CRAP
+ * envelope (from `runCrapPreview`) into a per-file delta map. Pure —
+ * no I/O, no spawn. Tests pin the math without invoking the runners.
+ *
+ * Output rows are keyed by file (forward-slash relative path) and carry:
+ *   - `miDrop`: maintainability score drop from baseline (0 when unchanged or
+ *     improved). Higher = worse.
+ *   - `worstCrapDelta`: largest CRAP regression delta among the file's
+ *     methods (max of `crap - baseline` for matched-baseline rows, `crap`
+ *     for new-method rows). 0 when the file has no CRAP violations.
+ *   - `newOverCeilingMethods`: count of new-method violations (kind:'new')
+ *     scoring above the `c=8` ceiling (matches the column header
+ *     "new-method count over c=8" in the AC). The CRAP envelope's
+ *     `cyclomatic` field is the per-method `c` reading.
+ *
+ * @param {{ violations?: Array<{ file: string, drop?: number }> } | null} miEnvelope
+ * @param {{ violations?: Array<{
+ *   file: string,
+ *   crap: number,
+ *   baseline: number | null,
+ *   ceiling: number,
+ *   cyclomatic: number,
+ *   kind: 'new' | 'regression' | 'drifted-regression' | string,
+ * }>} | null} crapEnvelope
+ * @returns {{
+ *   rows: Array<{
+ *     file: string,
+ *     miDrop: number,
+ *     worstCrapDelta: number,
+ *     newOverCeilingMethods: number,
+ *   }>,
+ *   totals: { miRegressions: number, crapViolations: number },
+ * }}
+ */
+export function mergeEnvelopes(miEnvelope, crapEnvelope) {
+  /** @type {Map<string, { miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>} */
+  const byFile = new Map();
+  const ensure = (file) => {
+    let row = byFile.get(file);
+    if (!row) {
+      row = { miDrop: 0, worstCrapDelta: 0, newOverCeilingMethods: 0 };
+      byFile.set(file, row);
+    }
+    return row;
+  };
+
+  const miViolations = miEnvelope?.violations ?? [];
+  for (const v of miViolations) {
+    if (!v?.file) continue;
+    const row = ensure(v.file);
+    const drop = Number(v.drop ?? 0);
+    if (Number.isFinite(drop) && drop > row.miDrop) row.miDrop = drop;
+  }
+
+  const crapViolations = crapEnvelope?.violations ?? [];
+  for (const v of crapViolations) {
+    if (!v?.file) continue;
+    const row = ensure(v.file);
+    const crap = Number(v.crap ?? 0);
+    if (v.kind === 'new') {
+      const ceiling = Number(v.ceiling ?? 0);
+      const delta = crap - ceiling;
+      if (Number.isFinite(delta) && delta > row.worstCrapDelta) {
+        row.worstCrapDelta = delta;
+      }
+      const cyclomatic = Number(v.cyclomatic ?? 0);
+      if (Number.isFinite(cyclomatic) && cyclomatic > 8) {
+        row.newOverCeilingMethods += 1;
+      }
+    } else {
+      const baseline = Number(v.baseline ?? 0);
+      const delta = crap - baseline;
+      if (Number.isFinite(delta) && delta > row.worstCrapDelta) {
+        row.worstCrapDelta = delta;
+      }
+    }
+  }
+
+  const rows = Array.from(byFile.entries())
+    .map(([file, agg]) => ({ file, ...agg }))
+    .sort((a, b) => a.file.localeCompare(b.file));
+
+  return {
+    rows,
+    totals: {
+      miRegressions: miEnvelope?.summary?.regressions ?? 0,
+      crapViolations:
+        (crapEnvelope?.summary?.regressions ?? 0) +
+        (crapEnvelope?.summary?.newViolations ?? 0),
+    },
+  };
+}
+
+/**
+ * Compute the CLI exit code from a merge result + per-gate exit codes. Pure.
+ *
+ * The exit code is non-zero (1) whenever:
+ *   - either gate returned a non-zero exit code (real violations or runtime
+ *     failure), OR
+ *   - the merged envelope reports any violation rows at all.
+ *
+ * Both signals are combined so a transient gate failure (e.g. JSON write
+ * error) still surfaces even if the violations array happens to be empty.
+ *
+ * @param {{ rows: Array<unknown>, totals: { miRegressions: number, crapViolations: number } }} merged
+ * @param {number} miExit
+ * @param {number} crapExit
+ * @returns {number}
+ */
+export function computeExitCode(merged, miExit, crapExit) {
+  if (miExit !== 0 || crapExit !== 0) return 1;
+  if (merged.rows.length > 0) return 1;
+  if (merged.totals.miRegressions > 0) return 1;
+  if (merged.totals.crapViolations > 0) return 1;
+  return 0;
+}
+
+/**
+ * Render the per-file delta table. Header columns match the AC verbatim:
+ *   "file", "MI delta", "worst CRAP delta", "new-method count over c=8".
+ *
+ * Pure — accepts pre-computed merge rows and returns a multi-line string. The
+ * table renders even on a clean diff so operators see the "no drift" signal.
+ *
+ * @param {{ rows: Array<{ file: string, miDrop: number, worstCrapDelta: number, newOverCeilingMethods: number }>, totals: { miRegressions: number, crapViolations: number } }} merged
+ * @returns {string}
+ */
+export function renderTable(merged) {
+  const header = [
+    'file',
+    'MI delta',
+    'worst CRAP delta',
+    'new-method count over c=8',
+  ];
+  const lines = [];
+  lines.push(`| ${header.join(' | ')} |`);
+  lines.push(`| ${header.map(() => '---').join(' | ')} |`);
+  if (merged.rows.length === 0) {
+    lines.push('| _(no per-file regressions)_ | — | — | — |');
+  } else {
+    for (const row of merged.rows) {
+      lines.push(
+        `| ${row.file} | -${row.miDrop.toFixed(2)} | +${row.worstCrapDelta.toFixed(2)} | ${row.newOverCeilingMethods} |`,
+      );
+    }
+  }
+  lines.push('');
+  lines.push(
+    `Totals: MI regressions=${merged.totals.miRegressions} · CRAP violations=${merged.totals.crapViolations}`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Top-level CLI entry: invoke both per-kind preview runners, merge, render,
+ * and exit with the right code. Exposed as `runCli` so tests can drive the
+ * full pipeline through injected runner stubs.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ *   runMi?: typeof runMaintainabilityPreview,
+ *   runCrap?: typeof runCrapPreview,
+ * }} [opts]
+ * @returns {Promise<{ exitCode: number, merged: ReturnType<typeof mergeEnvelopes> }>}
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  runMi = runMaintainabilityPreview,
+  runCrap = runCrapPreview,
+} = {}) {
+  const json = parseJsonFlag(argv);
+  const staged = parseStagedFlag(argv);
+  const ref = staged ? null : (parseChangedSinceArg(argv) ?? 'HEAD');
+
+  const [miResult, crapResult] = await Promise.all([
+    runMi({ cwd, staged, changedSinceRef: ref }).catch((err) => {
+      stderr.write(
+        `[quality:preview] MI runner failed: ${err?.message ?? err}\n`,
+      );
+      return { exitCode: 1, envelope: null };
+    }),
+    runCrap({ cwd, staged, changedSinceRef: ref }).catch((err) => {
+      stderr.write(
+        `[quality:preview] CRAP runner failed: ${err?.message ?? err}\n`,
+      );
+      return { exitCode: 1, envelope: null };
+    }),
+  ]);
+  const miExit = miResult.exitCode;
+  const crapExit = crapResult.exitCode;
+  const miEnvelope = miResult.envelope;
+  const crapEnvelope = crapResult.envelope;
+  const merged = mergeEnvelopes(miEnvelope, crapEnvelope);
+
+  if (json) {
+    stdout.write(
+      `${JSON.stringify(
+        {
+          ref: staged ? null : ref,
+          staged,
+          mi: { exit: miExit, envelope: miEnvelope },
+          crap: { exit: crapExit, envelope: crapEnvelope },
+          merged,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    stdout.write('\n--- quality:preview ---\n');
+    stdout.write(
+      staged
+        ? 'scope=staged (git diff --cached)\n\n'
+        : `scope=diff ref=${ref}\n\n`,
+    );
+    stdout.write(`${renderTable(merged)}\n`);
+    if (miExit !== 0 || crapExit !== 0) {
+      stderr.write(
+        `\n[quality:preview] gate exits: mi=${miExit} crap=${crapExit}\n`,
+      );
+    }
+  }
+
+  return { exitCode: computeExitCode(merged, miExit, crapExit), merged };
+}
+
+// cli-opt-out: Windows-aware main-guard with leading-slash drive-letter normalisation; mirrors quality-watch.js so the diagnostic surface stays consistent across the gate suite.
+// Only run main when invoked directly — keep the module importable from tests.
+const isDirect = (() => {
+  try {
+    const invoked = process.argv[1] ? path.resolve(process.argv[1]) : '';
+    const self = new URL(import.meta.url).pathname;
+    const normalizedSelf = /^\/[A-Za-z]:/.test(self) ? self.slice(1) : self;
+    return path.resolve(normalizedSelf) === invoked;
+  } catch {
+    return false;
+  }
+})();
+
+if (isDirect) {
+  runCli().then(({ exitCode }) => {
+    process.exit(exitCode);
+  });
+}

package/.agents/scripts/quality-watch.js

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/* node:coverage ignore file -- MI 0 long-lived chokidar watcher; one-shot dev tool that respawns quality-preview, no test seam without mocking the watcher event loop */
+
+/**
+ * .agents/scripts/quality-watch.js — chokidar wrapper around quality-preview.
+ *
+ * Long-lived watcher that re-runs `quality-preview` (debounced) whenever a
+ * source file under the configured MI/CRAP target dirs changes. Designed for
+ * `npm run quality:watch` — operators leave it running in a side terminal and
+ * see live MI/CRAP deltas as they edit.
+ *
+ * Wiring:
+ *   - chokidar.watch(targetDirs, { ignored: ['node_modules', '.git', ...] })
+ *   - on 'add' | 'change' | 'unlink' → debounce, then spawn the preview.
+ *   - SIGINT → close the watcher, exit 0.
+ *
+ * The preview spawn payload is exported as `buildPreviewSpawn` for unit tests
+ * that stub `chokidar.watch` and assert what would be invoked. The watcher
+ * factory (`createWatcher`) accepts injected `chokidar` and `spawn` so the
+ * tests never load the real chokidar (devDependency) or actually fork node.
+ */
+
+import { spawn as defaultSpawn } from 'node:child_process';
+import path from 'node:path';
+import process from 'node:process';
+import { getQuality, resolveConfig } from './lib/config-resolver.js';
+
+const DEFAULT_DEBOUNCE_MS = 250;
+
+/**
+ * Resolve the union of MI + CRAP target dirs from the project's agent config.
+ * Falls back to `['.agents/scripts', 'tests']` when neither block is
+ * configured so the watcher always has something to watch in a fresh repo.
+ *
+ * Pure-ish — exported so tests can pass a synthetic config shape without
+ * reaching into the real config resolver.
+ *
+ * @param {object} resolved Canonical resolved config (`resolveConfig()` output).
+ * @returns {string[]}
+ */
+export function resolveWatchTargets(resolved) {
+  const quality = getQuality(resolved);
+  const miDirs = quality?.maintainability?.targetDirs ?? [];
+  const crapDirs = quality?.crap?.targetDirs ?? [];
+  const merged = Array.from(new Set([...miDirs, ...crapDirs]));
+  if (merged.length === 0) return ['.agents/scripts', 'tests'];
+  return merged;
+}
+
+/**
+ * Build the spawn payload for the per-save preview run. Pure: returns the
+ * exact `(command, args, options)` tuple that the watcher hands to `spawn`,
+ * so unit tests can assert wire-level intent without forking node.
+ *
+ * @param {{ cwd?: string, ref?: string }} [opts]
+ * @returns {{ command: string, args: string[], options: { cwd: string, stdio: 'inherit' } }}
+ */
+export function buildPreviewSpawn({ cwd = process.cwd(), ref = 'HEAD' } = {}) {
+  return {
+    command: process.execPath,
+    args: [
+      path.resolve(cwd, '.agents', 'scripts', 'quality-preview.js'),
+      '--changed-since',
+      ref,
+    ],
+    options: { cwd, stdio: 'inherit' },
+  };
+}
+
+/**
+ * Pure debouncer factory. Keeps the watcher's "I just saw N saves in 50ms"
+ * behaviour testable without sleeping. Exported so the per-save coalescing
+ * contract can be pinned in unit tests.
+ *
+ * @param {number} ms
+ * @param {{ setTimeout?: typeof setTimeout, clearTimeout?: typeof clearTimeout }} [io]
+ * @returns {{ schedule: (fn: () => void) => void, flush: () => void }}
+ */
+export function createDebouncer(
+  ms,
+  { setTimeout: setT = setTimeout, clearTimeout: clearT = clearTimeout } = {},
+) {
+  let pending = null;
+  let nextFn = null;
+  return {
+    schedule(fn) {
+      nextFn = fn;
+      if (pending) clearT(pending);
+      pending = setT(() => {
+        const f = nextFn;
+        pending = null;
+        nextFn = null;
+        if (f) f();
+      }, ms);
+    },
+    flush() {
+      if (pending) {
+        clearT(pending);
+        pending = null;
+      }
+      if (nextFn) {
+        const f = nextFn;
+        nextFn = null;
+        f();
+      }
+    },
+  };
+}
+
+/**
+ * Wire chokidar + spawn + the debouncer into a long-lived watcher. Returns a
+ * `{ close }` handle so the caller (or tests) can shut it down deterministically.
+ *
+ * @param {{
+ *   chokidar: { watch: (paths: string[], opts: object) => { on: Function, close: () => Promise<void> } },
+ *   spawn?: typeof defaultSpawn,
+ *   targets: string[],
+ *   cwd?: string,
+ *   ref?: string,
+ *   debounceMs?: number,
+ *   onSpawn?: (payload: ReturnType<typeof buildPreviewSpawn>) => void,
+ *   stdout?: { write: (s: string) => void },
+ * }} opts
+ */
+export function createWatcher({
+  chokidar,
+  spawn = defaultSpawn,
+  targets,
+  cwd = process.cwd(),
+  ref = 'HEAD',
+  debounceMs = DEFAULT_DEBOUNCE_MS,
+  onSpawn,
+  stdout = process.stdout,
+}) {
+  const watcher = chokidar.watch(targets, {
+    ignored: [/node_modules/, /\.git/, /\.worktrees/, /coverage/, /temp/],
+    ignoreInitial: true,
+    cwd,
+  });
+  const debouncer = createDebouncer(debounceMs);
+  const trigger = () => {
+    const payload = buildPreviewSpawn({ cwd, ref });
+    if (onSpawn) onSpawn(payload);
+    spawn(payload.command, payload.args, payload.options);
+  };
+  for (const ev of ['add', 'change', 'unlink']) {
+    watcher.on(ev, (file) => {
+      stdout.write(`[quality:watch] ${ev} ${file}\n`);
+      debouncer.schedule(trigger);
+    });
+  }
+  watcher.on('ready', () => {
+    stdout.write(
+      `[quality:watch] watching ${targets.length} target dir(s); press Ctrl+C to exit.\n`,
+    );
+  });
+  return {
+    /**
+     * Resolve once chokidar has stopped watching. The wrapper triggers
+     * `flush()` first so any in-flight save still produces one final preview
+     * run before the process exits.
+     */
+    async close() {
+      debouncer.flush();
+      await watcher.close();
+    },
+    debouncer,
+    watcher,
+  };
+}
+
+/**
+ * CLI entry. Lazy-loads the real chokidar so importing this module in tests
+ * (which inject a stub) never touches the devDependency.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   chokidarLoader?: () => Promise<{ default?: object } & object>,
+ *   resolved?: object,
+ * }} [opts]
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  chokidarLoader = () => import('chokidar'),
+  resolved,
+} = {}) {
+  void argv;
+  const config = resolved ?? resolveConfig();
+  const targets = resolveWatchTargets(config);
+  const chokidarMod = await chokidarLoader();
+  const chokidar = chokidarMod?.default ?? chokidarMod;
+  const handle = createWatcher({ chokidar, targets, cwd });
+  const shutdown = async () => {
+    process.stdout.write('\n[quality:watch] SIGINT received; closing.\n');
+    await handle.close();
+    process.exit(0);
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+  return handle;
+}
+
+// cli-opt-out: Windows-aware main-guard with leading-slash drive-letter normalisation; mirrors check-maintainability.js / check-crap.js so the diagnostic surface stays consistent across the gate suite.
+// Only run main when invoked directly — keep the module importable from tests.
+const isDirect = (() => {
+  try {
+    const invoked = process.argv[1] ? path.resolve(process.argv[1]) : '';
+    const self = new URL(import.meta.url).pathname;
+    const normalizedSelf = /^\/[A-Za-z]:/.test(self) ? self.slice(1) : self;
+    return path.resolve(normalizedSelf) === invoked;
+  } catch {
+    return false;
+  }
+})();
+
+if (isDirect) {
+  runCli().catch((err) => {
+    process.stderr.write(`[quality:watch] fatal: ${err?.message ?? err}\n`);
+    process.exit(1);
+  });
+}

package/.agents/scripts/render-manifest.js

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+/**
+ * .agents/scripts/render-manifest.js — Derived-view Manifest Renderer
+ *
+ * Regenerates `temp/epic-<epicId>/manifest.{md,json}` from the
+ * `dispatch-manifest` structured comment on the Epic (Epic #1030 Story
+ * #1040 / Task #1054 — migrated from the legacy flat
+ * `temp/dispatch-manifest-<epicId>.{md,json}` layout). The comment is
+ * the single source of truth for which Stories the sprint committed to;
+ * the per-Epic files are a convenience view that lets wave-gate runs,
+ * local tooling, and CI consumers work offline.
+ *
+ * Running this script never mutates GitHub state — it only performs a read
+ * of the existing comment and writes the derived artefacts under the
+ * per-Epic tree.
+ *
+ * Usage:
+ *   node .agents/scripts/render-manifest.js --epic <EPIC_ID>
+ *
+ * Exit codes:
+ *   0 — render succeeded.
+ *   1 — no manifest comment (or no parseable JSON) on the Epic.
+ *   2 — configuration or provider transport error.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { runAsCli } from './lib/cli-utils.js';
+import { epicArtifactPath } from './lib/config/temp-paths.js';
+import { PROJECT_ROOT, resolveConfig } from './lib/config-resolver.js';
+import { Logger } from './lib/Logger.js';
+import { parseFencedJson } from './lib/orchestration/structured-comment-parser.js';
+import { findStructuredComment } from './lib/orchestration/ticketing.js';
+import { atomicWrite } from './lib/presentation/manifest-persistence.js';
+import { createProvider } from './lib/provider-factory.js';
+
+export function extractManifestJson(body) {
+  return parseFencedJson(body);
+}
+
+/**
+ * Write the rendered manifest files. Separated from the I/O boundary so
+ * tests can exercise the pure contract without touching disk.
+ *
+ * @param {{ epicId: number, body: string, parsed: object, projectRoot?: string }} opts
+ * @returns {{ mdPath: string, jsonPath: string }}
+ */
+export function writeRenderedManifest({
+  epicId,
+  body,
+  parsed,
+  projectRoot = PROJECT_ROOT,
+  config,
+}) {
+  // Per-Epic layout (Epic #1030 Story #1040): write under
+  // `<projectRoot>/temp/epic-<eid>/manifest.{md,json}`. Bind the artifact
+  // path to the explicit projectRoot (Story #3900): pre-absolutise the
+  // tempRoot against projectRoot so temp-paths honours it verbatim rather
+  // than anchoring a relative tempRoot to the main checkout (correct for the
+  // lifecycle ledger, wrong for this per-project on-disk manifest write).
+  const relTempRoot =
+    config?.project?.paths?.tempRoot &&
+    !path.isAbsolute(config.project.paths.tempRoot)
+      ? config.project.paths.tempRoot
+      : 'temp';
+  const boundConfig = path.isAbsolute(config?.project?.paths?.tempRoot ?? '')
+    ? config
+    : { project: { paths: { tempRoot: path.join(projectRoot, relTempRoot) } } };
+  const mdPath = epicArtifactPath(epicId, 'manifest.md', boundConfig);
+  const jsonPath = epicArtifactPath(epicId, 'manifest.json', boundConfig);
+  const epicDir = path.dirname(mdPath);
+  if (!fs.existsSync(epicDir)) {
+    fs.mkdirSync(epicDir, { recursive: true });
+  }
+  // Both writes go through the atomic write-then-rename helper so a
+  // crash mid-write (rename throws / process killed) leaves either the
+  // pre-existing artefact intact or no file at all — never a partial
+  // truncation. The `.tmp` residue is best-effort removed on failure
+  // (see `atomicWrite` in manifest-persistence.js).
+  atomicWrite(mdPath, body);
+  atomicWrite(jsonPath, `${JSON.stringify(parsed, null, 2)}\n`);
+  return { mdPath, jsonPath };
+}
+
+export async function renderManifestFromComment({
+  epicId,
+  injectedProvider,
+} = {}) {
+  if (!epicId || Number.isNaN(epicId) || epicId <= 0) {
+    throw new Error('Usage: node render-manifest.js --epic <EPIC_ID>');
+  }
+
+  const config = resolveConfig();
+  const provider = injectedProvider || createProvider(config);
+
+  const comment = await findStructuredComment(
+    provider,
+    epicId,
+    'dispatch-manifest',
+  );
+  if (!comment) {
+    Logger.error(
+      `[render-manifest] No dispatch-manifest comment on Epic #${epicId}. ` +
+        `Run the dispatcher (\`node .agents/scripts/dispatcher.js ${epicId}\`) first.`,
+    );
+    process.exit(1);
+  }
+
+  const parsed = extractManifestJson(comment.body);
+  if (!parsed) {
+    Logger.error(
+      `[render-manifest] dispatch-manifest comment #${comment.id} on Epic #${epicId} did not contain a parseable JSON block.`,
+    );
+    process.exit(1);
+  }
+
+  const { mdPath, jsonPath } = writeRenderedManifest({
+    epicId,
+    body: comment.body,
+    parsed,
+  });
+
+  const storyCount = Array.isArray(parsed.stories) ? parsed.stories.length : 0;
+  Logger.info(
+    `[render-manifest] ✅ Rendered ${storyCount} story(ies) for Epic #${epicId}:\n` +
+      `  - ${mdPath}\n` +
+      `  - ${jsonPath}`,
+  );
+  return { mdPath, jsonPath, stories: storyCount };
+}
+
+async function main() {
+  const { values } = parseArgs({
+    options: { epic: { type: 'string' } },
+    strict: false,
+  });
+  const epicId = Number.parseInt(values.epic ?? '', 10);
+  await renderManifestFromComment({ epicId });
+}
+
+runAsCli(import.meta.url, main, { source: 'render-manifest' });