mandrel 1.87.0 → 1.89.0

package/.agents/scripts/check-context-budget.js

@@ -0,0 +1,320 @@
+/**
+ * CLI: ratchet-down gate for the always-loaded documentation context budget
+ * (Story #4438, Epic #4430 — Context Economy).
+ *
+ * Follows the standalone `check-arch-cycles.js` / `check-dead-exports.js`
+ * precedent — a pure-Node, baseline-aware, sub-second checker wired into the
+ * CI `baselines` job — rather than a `baselines/kinds/` metric. It measures the
+ * live byte total of two documentation read-tiers and compares each against a
+ * single committed budget in `baselines/context-budget.json`:
+ *
+ *   - `alwaysLoaded`  — the `CLAUDE.md` `@`-import closure re-paid on every
+ *                       session and every subagent spawn (instructions.md § 4).
+ *   - `mandatoryRead` — the resolved `project.docsContextFiles` set.
+ *
+ * A tier that resolves **empty** is skipped silently (the `docsContextFiles`
+ * half skips when unconfigured / its files are absent), so a repo with no
+ * `CLAUDE.md` and no context docs is a clean no-op.
+ *
+ * Ratchet semantics (mirroring the sibling ratchets):
+ *   - A gated tier grows beyond `baseline.tiers.<tier>.totalBytes +
+ *     baseline.toleranceBytes` → exit 1, naming the tier and its delta.
+ *   - A gated tier shrinks below its baseline total → printed as a `-`
+ *     (removal) note, warning the baseline can be refreshed downward.
+ *     Shrink-only exits 0.
+ *   - Within tolerance / clean → exit 0.
+ *   - Baseline file absent → warn + exit 0 (no-op; nothing to ratchet against).
+ *
+ * Tolerance lives in the baseline JSON (`toleranceBytes`) — there is **no**
+ * `.agentrc.json` config key; this is a framework-internal dogfooding ratchet,
+ * like arch-cycles.
+ *
+ * Flags:
+ *   --baseline <path>  override the budget path (default
+ *                      `baselines/context-budget.json`, resolved from cwd).
+ *   --root <path>      resolve tiers against an explicit repo root (default cwd).
+ *   --update           reseed the baseline from the current measurement (keeps
+ *                      the existing `toleranceBytes`, or defaults it) and exit 0.
+ *   --json             write the structured envelope to stdout.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
+import { resolveDocTiers, tierTotalBytes } from './lib/doc-tiers.js';
+
+/**
+ * The tiers this ratchet gates (in report order). `digestVisible` and
+ * `onDemand` are resolved by the tier map for the lens, but the byte budget
+ * intentionally gates only the two tiers the Epic AC names.
+ * @type {Array<'alwaysLoaded' | 'mandatoryRead'>}
+ */
+export const GATED_TIERS = ['alwaysLoaded', 'mandatoryRead'];
+
+/**
+ * Default tolerance (bytes) seeded into a fresh baseline by `--update` when the
+ * existing baseline carries none.
+ * @type {number}
+ */
+export const DEFAULT_TOLERANCE_BYTES = 2048;
+
+/**
+ * Parse argv for `--baseline <path>`, `--root <path>`, `--update`, `--json`.
+ * Exported so unit tests can pin the parser.
+ *
+ * @param {string[]} argv
+ * @returns {{ baselinePath: string|null, rootPath: string|null, update: boolean, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let baselinePath = null;
+  let rootPath = null;
+  let update = false;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--baseline') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        baselinePath = next;
+        i += 1;
+      }
+    } else if (a === '--root') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        rootPath = next;
+        i += 1;
+      }
+    } else if (a === '--update') {
+      update = true;
+    } else if (a === '--json') {
+      json = true;
+    }
+  }
+  return { baselinePath, rootPath, update, json };
+}
+
+/**
+ * Read the committed budget envelope from disk. Returns the parsed object or
+ * `null` when the file is missing or unparseable.
+ *
+ * @param {string} baselinePath
+ * @returns {{ toleranceBytes?: number, tiers?: Record<string, { totalBytes: number, files?: Array<{ path: string, bytes: number }> }> } | null}
+ */
+export function loadBaseline(baselinePath) {
+  try {
+    if (!fs.existsSync(baselinePath)) return null;
+    const parsed = JSON.parse(fs.readFileSync(baselinePath, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the committed-baseline envelope from a resolved tier map. Only the
+ * gated tiers are recorded (each as `{ totalBytes, files }`).
+ *
+ * @param {{ tiers: Record<string, Array<{ path: string, bytes: number }>> }} tierMap
+ * @param {number} toleranceBytes
+ * @returns {object}
+ */
+export function buildBaseline(tierMap, toleranceBytes) {
+  const tiers = {};
+  for (const name of GATED_TIERS) {
+    const files = tierMap.tiers[name] ?? [];
+    tiers[name] = { totalBytes: tierTotalBytes(files), files };
+  }
+  return {
+    $schema: 'https://mandrel.dev/baselines/context-budget.schema.json',
+    generatedAt: new Date().toISOString(),
+    toleranceBytes,
+    tiers,
+  };
+}
+
+/**
+ * Pure diff: compare the current tier map against the committed baseline. A
+ * gated tier with no current files is skipped; a tier absent from the baseline
+ * is skipped. `grown` entries fail the gate; `shrunk` entries are informational.
+ *
+ * @param {{ tiers: Record<string, Array<{ path: string, bytes: number }>> }} tierMap
+ * @param {{ toleranceBytes?: number, tiers?: Record<string, { totalBytes: number }> }} baseline
+ * @returns {{
+ *   grown: Array<{ tier: string, current: number, baseline: number, tolerance: number, delta: number }>,
+ *   shrunk: Array<{ tier: string, current: number, baseline: number }>,
+ *   skipped: string[],
+ * }}
+ */
+export function diffBudget(tierMap, baseline) {
+  const tolerance = Number.isFinite(baseline?.toleranceBytes)
+    ? baseline.toleranceBytes
+    : 0;
+  const grown = [];
+  const shrunk = [];
+  const skipped = [];
+  for (const tier of GATED_TIERS) {
+    const files = tierMap.tiers[tier] ?? [];
+    const current = tierTotalBytes(files);
+    const baseTier = baseline?.tiers?.[tier];
+    if (
+      files.length === 0 ||
+      !baseTier ||
+      !Number.isFinite(baseTier.totalBytes)
+    ) {
+      skipped.push(tier);
+      continue;
+    }
+    const baselineBytes = baseTier.totalBytes;
+    if (current > baselineBytes + tolerance) {
+      grown.push({
+        tier,
+        current,
+        baseline: baselineBytes,
+        tolerance,
+        delta: current - baselineBytes,
+      });
+    } else if (current < baselineBytes) {
+      shrunk.push({ tier, current, baseline: baselineBytes });
+    }
+  }
+  return { grown, shrunk, skipped };
+}
+
+/**
+ * Render the human-readable diff. `+` lines are tiers that grew beyond
+ * tolerance (gate fail); `-` lines are tiers that shrank (refreshable
+ * baseline). A one-line summary always follows.
+ *
+ * @param {ReturnType<typeof diffBudget>} diff
+ * @returns {string}
+ */
+export function renderDiff(diff) {
+  const lines = [];
+  for (const g of diff.grown) {
+    lines.push(
+      `+ ${g.tier}: ${g.current} bytes exceeds budget ${g.baseline} + tolerance ${g.tolerance} (delta +${g.delta})`,
+    );
+  }
+  for (const s of diff.shrunk) {
+    lines.push(
+      `- ${s.tier}: ${s.current} bytes below baseline ${s.baseline} — refresh baselines/context-budget.json`,
+    );
+  }
+  const tag = diff.grown.length > 0 ? '(gate fail)' : '(ok)';
+  lines.push(
+    `[context-budget] grown=${diff.grown.length} shrunk=${diff.shrunk.length} skipped=${diff.skipped.length} ${tag}`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive the full pipeline against a
+ * tmpdir fixture with an injected config and sinks.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   config?: object,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} 0 = clean / within tolerance / shrink-only / no-op;
+ *   1 = a gated tier grew beyond tolerance
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  config,
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const { baselinePath, rootPath, update, json } = parseArgv(argv);
+  const root = rootPath ? path.resolve(cwd, rootPath) : path.resolve(cwd);
+  const resolvedBaselinePath = path.resolve(
+    cwd,
+    baselinePath ?? path.join('baselines', 'context-budget.json'),
+  );
+  const resolvedConfig = config ?? resolveConfig();
+  const tierMap = resolveDocTiers(resolvedConfig, { root });
+
+  if (update) {
+    const existing = loadBaseline(resolvedBaselinePath);
+    const tolerance = Number.isFinite(existing?.toleranceBytes)
+      ? existing.toleranceBytes
+      : DEFAULT_TOLERANCE_BYTES;
+    const envelope = buildBaseline(tierMap, tolerance);
+    fs.mkdirSync(path.dirname(resolvedBaselinePath), { recursive: true });
+    fs.writeFileSync(
+      resolvedBaselinePath,
+      `${JSON.stringify(envelope, null, 2)}\n`,
+    );
+    if (!json) {
+      stdout.write(
+        `[context-budget] wrote baseline ${resolvedBaselinePath} (tolerance ${tolerance} bytes)\n`,
+      );
+    } else {
+      stdout.write(
+        `${JSON.stringify({ kind: 'context-budget-update', baselinePath: resolvedBaselinePath, envelope }, null, 2)}\n`,
+      );
+    }
+    return 0;
+  }
+
+  const baseline = loadBaseline(resolvedBaselinePath);
+  if (!baseline) {
+    if (json) {
+      stdout.write(
+        `${JSON.stringify({ kind: 'context-budget-report', baselinePath: resolvedBaselinePath, tiers: tierMap.tiers, grown: [], shrunk: [], skipped: GATED_TIERS, exitCode: 0, noBaseline: true }, null, 2)}\n`,
+      );
+    } else {
+      stderr.write(
+        `[context-budget] ⚠ budget not found at ${resolvedBaselinePath} — skipping (no-op)\n`,
+      );
+    }
+    return 0;
+  }
+
+  const diff = diffBudget(tierMap, baseline);
+  const exitCode = diff.grown.length > 0 ? 1 : 0;
+
+  if (json) {
+    const envelope = {
+      kind: 'context-budget-report',
+      baselinePath: resolvedBaselinePath,
+      toleranceBytes: Number.isFinite(baseline.toleranceBytes)
+        ? baseline.toleranceBytes
+        : 0,
+      current: Object.fromEntries(
+        GATED_TIERS.map((t) => [t, tierTotalBytes(tierMap.tiers[t] ?? [])]),
+      ),
+      grown: diff.grown,
+      shrunk: diff.shrunk,
+      skipped: diff.skipped,
+      exitCode,
+    };
+    stdout.write(`${JSON.stringify(envelope, null, 2)}\n`);
+  } else {
+    stdout.write(`\n--- context-budget preview ---\n`);
+    stdout.write(`${renderDiff(diff)}\n`);
+    if (exitCode === 1) {
+      stderr.write(
+        `[context-budget] ❌ a documentation tier grew beyond tolerance — refresh the budget consciously with \`node .agents/scripts/check-context-budget.js --update\` once the growth is intentional\n`,
+      );
+    }
+  }
+
+  return exitCode;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'context-budget',
+  propagateExitCode: true,
+  errorPrefix: '[context-budget] ❌ Fatal error',
+});

package/.agents/scripts/diagnose-friction.js

@@ -131,7 +131,7 @@ function buildFrictionSignal({
   return {
     kind: 'friction',
     eventId: crypto.randomUUID(),
-    timestamp: new Date().toISOString(),
+    ts: new Date().toISOString(),
     epicId: epicId ?? null,
     storyId: storyId ?? null,
     // 2-tier hierarchy (Epic #3163): no Task tier, so friction signals
@@ -139,11 +139,11 @@ function buildFrictionSignal({
     // and always null.
     taskId: null,
     category,
-    source: {
+    emitter: {
       tool: 'diagnose-friction.js',
       command: commandStr,
     },
-    details: errorPreview,
+    details: { errorPreview },
   };
 }
 
@@ -209,7 +209,7 @@ export async function main(args = process.argv.slice(2)) {
 
     // Story #2874 — accept story-only context (no parent Epic). When
     // only the story is resolved, write to the standalone signals
-    // stream at `<tempRoot>/standalone/story-<sid>/signals.ndjson`
+    // stream at `<tempRoot>/standalone/stories/story-<sid>/signals.ndjson`
     // by passing `epicId: null` through to the writer. The only case
     // we still skip is fully-no-context (story unresolved).
     if (resolvedStoryId != null) {

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

@@ -23,7 +23,7 @@
  *
  * Story #3939 — depth-aware lenses. The `depth` field tells the audit
  * executor (`helpers/epic-audit.md`) how thorough each selected lens should
- * be on this Epic without ever skipping a selected (or alwaysRun) lens:
+ * be on this Epic without ever skipping a selected lens:
  * `light` shrinks a lens's sweep to the changed surface + Critical/High
  * findings, `standard` is today's behavior, and `deep` widens the sweep to
  * the directly-touched modules. Depth never changes which lenses fire, the
@@ -53,6 +53,7 @@
  *     "epicBranch": "epic/2586",
  *     "depth": "deep",
  *     "selectedAudits": ["audit-security", "audit-privacy"],
+ *     "epicCloseLenses": ["audit-security"],
  *     "changeSetAudits": ["audit-privacy"],
  *     "riskRoutedAudits": ["audit-security"],
  *     "globalLenses": [],
@@ -97,7 +98,10 @@ import {
 import { defineFlags } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { resolveConfig } from './lib/config-resolver.js';
-import { resolveAuditLenses } from './lib/orchestration/code-review.js';
+import {
+  resolveAuditLenses,
+  selectEpicCloseLenses,
+} from './lib/orchestration/code-review.js';
 import { read as readPlanState } from './lib/orchestration/epic-plan-state-store.js';
 import { resolveDepth } from './lib/orchestration/review-depth.js';
 import { createProvider } from './lib/provider-factory.js';
@@ -121,6 +125,14 @@ Output (JSON envelope on stdout):
                      each SELECTED lens runs; it never changes which lenses
                      fire, the severity taxonomy, or the Phase 4 halting rule.
   selectedAudits     De-duplicated union of changeSetAudits + riskRoutedAudits.
+  epicCloseLenses    The SLIM Epic-close roster (Story #4412): selectedAudits
+                     with every local-tier change-set lens excluded, keeping
+                     only cumulative + global change-set lenses plus every
+                     risk-routed lens. This is the roster the Phase 5
+                     code-review pass walks over the cumulative Epic diff —
+                     local-tier concerns are already verified shift-left
+                     (write-time checklists + the Story-scope local-lens pass),
+                     so they are not re-run at Epic close.
   changeSetAudits    Lenses the change-set selector chose.
   riskRoutedAudits   Lenses routed from the model-judged high-risk axes plus the
                      navigability lens when a changed file matches a configured
@@ -409,6 +421,21 @@ export async function runEpicAuditPrepare(values, deps = {}) {
   );
   const selectedAudits = unionAudits(changeSetAudits, riskRoutedAudits);
 
+  // Story #4412 (Epic #4405) — the SLIM Epic-close roster. Restrict the gate3
+  // selection to the tiers the Epic-close pass owns: cumulative + global
+  // change-set lenses plus every risk-routed lens, dropping every local-tier
+  // change-set lens (routed off `resolveLensTier` in `selectEpicCloseLenses`).
+  // Local-tier concerns are already verified shift-left — the write-time
+  // checklist threading (#4410) and the maker-blind Story-scope local-lens
+  // pass (#4409) — so re-running them over the cumulative diff at close would
+  // verify the same concern at a second tier. This is the roster the Phase 5
+  // code-review pass walks; `selectedAudits` stays the pre-slim union for
+  // observability.
+  const epicCloseLenses = selectEpicCloseLenses({
+    changeSetAudits,
+    riskRoutedAudits,
+  });
+
   // Epic #4131 (F2) — surface which selected lenses are on the global-lens
   // allowlist so the helper runs them against the WHOLE route tree, exempt from
   // the cross-epic-leak guard's change-set narrowing (`#3362`). The exemption
@@ -439,6 +466,7 @@ export async function runEpicAuditPrepare(values, deps = {}) {
         epicBranch,
         depth,
         selectedAudits,
+        epicCloseLenses,
         changeSetAudits,
         riskRoutedAudits,
         globalLenses,

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

@@ -10,10 +10,18 @@
  * subset of audit lenses whose `filePatterns` overlap that list.
  *
  * The CLI is intentionally narrower than `select-audits.js`: it does NOT
- * run a git diff, does NOT consult the Epic ticket body for keyword
- * triggers, and does NOT honor `alwaysRun`. The auto-fix tail already knows
- * exactly which paths it touched — only file-pattern overlap is relevant
- * for deciding which lenses are stale and need re-invocation.
+ * 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
+ * and need re-invocation.
+ *
+ * Tier gate (Epic #4405): this is the **Epic-close** re-check, so it emits
+ * only non-`local` lenses. A `local`-tier lens is verified shift-left at
+ * write-time and Story-scope review; re-running it here would verify the same
+ * concern at a second tier. The overlap set is therefore filtered through
+ * `resolveLensTier`, dropping every `local` lens (including the universal
+ * `audit-clean-code`) so a focused-fix commit cannot drag one back into the
+ * Epic-close re-check.
  *
  * Usage:
  *   node .agents/scripts/epic-audit-recheck.js \
@@ -40,7 +48,10 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { matchesAnyFilePattern } from './lib/audit-suite/index.js';
+import {
+  matchesAnyFilePattern,
+  resolveLensTier,
+} from './lib/audit-suite/index.js';
 import { defineFlags } from './lib/cli-args.js';
 import { runAsCli } from './lib/cli-utils.js';
 import {
@@ -148,23 +159,45 @@ export function loadAuditRules(deps = {}) {
 
 /**
  * Pure overlap detector. Walks the audit-rules document and returns the
- * names of every audit whose `triggers.filePatterns` matches at least one
- * entry in `files`. Lenses without `filePatterns` (or with an empty
- * array) NEVER appear in the output — `alwaysRun` and keyword triggers
- * are intentionally ignored: this CLI answers "what was invalidated by
- * the touched paths?", not "what should I run from scratch?".
+ * names of every **non-`local`** audit whose `triggers.filePatterns` matches
+ * at least one entry in `files`. Lenses without `filePatterns` (or with an
+ * empty array) NEVER appear in the output — keyword triggers are
+ * intentionally ignored: this CLI answers "what was invalidated by the
+ * touched paths?", not "what should I run from scratch?".
+ *
+ * The output is additionally gated by tier (Epic #4405): a `local`-tier lens
+ * is verified shift-left (write-time + Story-scope) and is never re-run at
+ * Epic close, so it is dropped here even when its patterns overlap. This
+ * matters now that `audit-clean-code` carries the universal `**` glob — its
+ * overlap is universal, so without the tier gate every focused-fix commit
+ * would drag it (and any other local lens) back into the Epic-close re-check.
  *
  * @param {{ audits: Record<string, { triggers?: { filePatterns?: string[] } }> }} rules
  * @param {string[]} files
+ * @param {(lens: string) => string} [resolveLensTierFn] tier resolver
+ *   (injectable seam; defaults to {@link resolveLensTier}).
  */
-export function selectOverlappingAudits(rules, files) {
+export function selectOverlappingAudits(
+  rules,
+  files,
+  resolveLensTierFn = resolveLensTier,
+) {
   const selected = [];
   for (const [auditName, ruleOpts] of Object.entries(rules?.audits ?? {})) {
     const patterns = ruleOpts?.triggers?.filePatterns;
     if (!Array.isArray(patterns) || patterns.length === 0) continue;
-    if (matchesAnyFilePattern(patterns, files)) {
-      selected.push(auditName);
+    if (!matchesAnyFilePattern(patterns, files)) continue;
+    // Epic-close tier gate: skip `local` lenses (verified shift-left). A
+    // malformed/unknown tier is drift the schema guards against — skip it
+    // rather than throw the whole selection.
+    let tier;
+    try {
+      tier = resolveLensTierFn(auditName);
+    } catch {
+      continue;
     }
+    if (tier === 'local') continue;
+    selected.push(auditName);
   }
   return selected;
 }

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

@@ -37,12 +37,13 @@ import path from 'node:path';
 import { parseArgs } from 'node:util';
 
 import { runBootSweep } from './boot-sweep.js';
+import { buildChecklistPayload } from './lib/audit-suite/index.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { getPaths, getRunners, resolveConfig } from './lib/config-resolver.js';
 import { currentBranch as gitCurrentBranch } from './lib/git-branch-lifecycle.js';
 import { getEpicBranch, gitSpawn } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
-import { buildDocsDigest } from './lib/orchestration/docs-digest.js';
+import { ensureDocsDigest } from './lib/orchestration/docs-digest.js';
 import {
   resolveOperator,
   runPrepareGuards,
@@ -60,6 +61,7 @@ import {
 import { runBuildWaveDagPhase } from './lib/orchestration/epic-runner/phases/build-wave-dag.js';
 import { runSnapshotPhase } from './lib/orchestration/epic-runner/phases/snapshot.js';
 import { StoryLauncher } from './lib/orchestration/epic-runner/story-launcher.js';
+import { collectStoryAssumptionEntries } from './lib/orchestration/file-assumptions.js';
 import {
   computeBaseSha,
   readPreflightCache,
@@ -357,14 +359,69 @@ async function writeDocsDigest({ epicId, cwd, config }) {
   const paths = getPaths(config);
   const root = path.resolve(cwd ?? process.cwd());
   const docsRoot = path.resolve(root, paths.docsRoot);
-  const digest = await buildDocsDigest({ docsContextFiles, docsRoot });
-  if (digest == null) return null;
-
   const relPath = path.join(paths.tempRoot, `epic-${epicId}`, 'docs-digest.md');
   const absPath = path.resolve(root, relPath);
-  await fs.promises.mkdir(path.dirname(absPath), { recursive: true });
-  await fs.promises.writeFile(absPath, digest, 'utf-8');
-  return relPath;
+  const result = await ensureDocsDigest({
+    docsContextFiles,
+    docsRoot,
+    outputPath: absPath,
+  });
+  return result ? relPath : null;
+}
+
+/**
+ * Thread footprint-matched **local**-lens authoring checklists into the
+ * per-Story dispatch entries (Epic #4405, Story #4410). For each planned Story,
+ * derive its predicted footprint from the full ticket body's `changes[]` /
+ * `references[]` entries, build the budget-capped checklist payload (matched by
+ * `resolveLensTier(lens) === 'local'` + `matchesAnyFilePattern` — NOT
+ * `selectAudits`, so no provider or git diff runs here), and write it to
+ * `<tempRoot>/epic-<id>/checklists/story-<sid>.md`. The parent threads the
+ * returned repo-relative `checklistPath` into that child's maker prompt, next
+ * to `docsDigestPath`; a Story that matches no local lens gets a `null` path
+ * and no file.
+ *
+ * @param {{
+ *   epicId: number,
+ *   cwd?: string,
+ *   config: object,
+ *   stories: Array<{ storyId: number, worktree?: string, title?: string }>,
+ *   storyById: Map<number, object>,
+ * }} args
+ * @returns {Promise<Array<{ storyId: number, worktree?: string, title?: string, checklistPath: string|null }>>}
+ */
+export async function writeStoryChecklists({
+  epicId,
+  cwd,
+  config,
+  stories,
+  storyById,
+  buildPayload = buildChecklistPayload,
+}) {
+  const paths = getPaths(config);
+  const root = path.resolve(cwd ?? process.cwd());
+
+  return Promise.all(
+    stories.map(async (entry) => {
+      const ticket = storyById.get(Number(entry.storyId));
+      const footprint = ticket
+        ? collectStoryAssumptionEntries(ticket).map((e) => e.path)
+        : [];
+      const { payload } = buildPayload({ footprint, logger: Logger });
+      if (!payload) return { ...entry, checklistPath: null };
+
+      const relPath = path.join(
+        paths.tempRoot,
+        `epic-${epicId}`,
+        'checklists',
+        `story-${entry.storyId}.md`,
+      );
+      const absPath = path.resolve(root, relPath);
+      await fs.promises.mkdir(path.dirname(absPath), { recursive: true });
+      await fs.promises.writeFile(absPath, payload, 'utf-8');
+      return { ...entry, checklistPath: relPath };
+    }),
+  );
 }
 
 export async function runEpicDeliverPrepare({
@@ -450,11 +507,26 @@ export async function runEpicDeliverPrepare({
   // dispatch from. This is a dispatch *hint* — the ready-set tick decides
   // which Stories to dispatch on each beat; the prepare only enumerates them.
   const launcher = new StoryLauncher({ concurrencyCap });
-  const stories = launcher.planWave(openStories).map((entry, i) => ({
+  const plannedStories = launcher.planWave(openStories).map((entry, i) => ({
     ...entry,
     title: openStories[i]?.title ?? '',
   }));
 
+  // Thread footprint-matched local-lens authoring checklists into each Story's
+  // dispatch entry (Story #4410). Keyed off the full discovered tickets (which
+  // carry the `changes[]`/`references[]` bodies the footprint is derived from);
+  // a Story that matches no local lens gets a `null` checklistPath.
+  const storyById = new Map(
+    (state.stories ?? []).map((t) => [Number(t.id ?? t.number), t]),
+  );
+  const stories = await writeStoryChecklists({
+    epicId,
+    cwd,
+    config,
+    stories: plannedStories,
+    storyById,
+  });
+
   // Persist the `--ignore-concurrency-hazards` flag on the checkpoint so
   // retro tooling can flag a run that shipped despite an outstanding hazard
   // (the warning above is one-shot; the checkpoint is durable).

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

@@ -70,10 +70,6 @@ import {
   planEpic,
   resolveAcceptancePersistence,
 } from './lib/orchestration/epic-plan-spec/phases/plan-epic.js';
-import {
-  ACCEPTANCE_SPEC_SYSTEM_PROMPT,
-  TECH_SPEC_SYSTEM_PROMPT,
-} from './lib/orchestration/epic-plan-spec/phases/prompts.js';
 import {
   loadRiskVerdict,
   validateRiskVerdict,
@@ -86,7 +82,6 @@ import { createProvider } from './lib/provider-factory.js';
 // Re-exports for stable public API: tests and external callers import these
 // from `epic-plan-spec.js`. The implementations live in `phases/`.
 export {
-  ACCEPTANCE_SPEC_SYSTEM_PROMPT,
   buildAuthoringContext,
   drainPendingCleanupAtBoot,
   loadRiskVerdict,
@@ -96,7 +91,6 @@ export {
   resolveReviewRouting,
   runSpecFreshnessCheck,
   runSpecPhase,
-  TECH_SPEC_SYSTEM_PROMPT,
   validateRiskVerdict,
 };
 
@@ -126,8 +120,10 @@ async function main() {
   // Story #2278 — in --emit-context mode stdout is reserved for the JSON
   // envelope. Flip every Logger sink that could land on stdout to stderr
   // *before* any pipeline code runs (drainPendingCleanupAtBoot,
-  // buildAuthoringContext → buildDocsContext → scrapeProjectDocs), so a
-  // captured file is unconditionally parseable by `JSON.parse`.
+  // buildAuthoringContext → ensureDocsDigest — Story #4433 cut the digest
+  // build over from the old buildDocsContext/scrapeProjectDocs full-content
+  // read path), so a captured file is unconditionally parseable by
+  // `JSON.parse`.
   if (emitContext) routeAllOutputToStderr();
 
   try {