mandrel 1.76.0 → 1.78.0

package/.agents/docs/configuration.md

@@ -138,7 +138,7 @@ top-level keys are validation errors.
 | `worktreeIsolation` | No | `object` | — | Nested configuration block. |
 | `worktreeIsolation.enabled` | No | `boolean` | — | — |
 | `worktreeIsolation.root` | No | `string` | — | — |
-| `worktreeIsolation.nodeModulesStrategy` | No | `"per-worktree"` \| `"symlink"` \| `"pnpm-store"` | — | — |
+| `worktreeIsolation.nodeModulesStrategy` | No | `"per-worktree"` \| `"clone"` \| `"symlink"` \| `"pnpm-store"` | — | — |
 | `worktreeIsolation.primeFromPath` | No | `string` \| `null` | — | — |
 | `worktreeIsolation.allowSymlinkOnWindows` | No | `boolean` | — | — |
 | `worktreeIsolation.reapOnSuccess` | No | `boolean` | — | — |
@@ -526,7 +526,7 @@ checkout's HEAD.
 | ----------------------- | --------------- | ---------------- | ----------------------------------------------------------- |
 | `enabled`               | No              | `false`          | Master switch.                                              |
 | `root`                  | Conditional     | `.worktrees`     | Required when `enabled: true`. Worktree parent directory.    |
-| `nodeModulesStrategy`   | No              | `per-worktree`   | One of `per-worktree`, `symlink`, `pnpm-store`.              |
+| `nodeModulesStrategy`   | No              | `clone` (darwin/linux); `per-worktree` (Windows) | One of `per-worktree`, `clone`, `symlink`, `pnpm-store`. `clone` copy-on-write (reflink/clonefile) clones the donor's `node_modules` and skips the per-tree install on a byte-exact lockfile match, falling back to `per-worktree` on any failure. |
 | `primeFromPath`         | No              | `null`           | Optional source path used to prime `node_modules`.            |
 | `allowSymlinkOnWindows` | No              | `false`          | Permit symlink strategy on Windows (requires admin/dev mode). |
 | `reapOnSuccess`         | No              | `true`           | Reap the worktree after a successful Story close.            |

package/.agents/docs/workflows.md

@@ -20,6 +20,13 @@ slash command (e.g. `/deliver`). The projection writes only
 `.claude/commands/<name>.md` — there is no plugin manifest and no
 marketplace listing. The commands load in every Claude Code environment.
 
+Loop units are the one namespaced exception: files under
+`.agents/workflows/loops/<name>.md` project to
+`.claude/commands/loops/<name>.md` and are invoked as the namespaced
+`/loops:<name>` command. On hosts that flatten subdirectory commands the
+same unit surfaces under the flat fallback `/loops-<name>`. They are
+listed separately in the **Loops namespace** section below.
+
 This index is regenerated from each workflow’s front-matter `description:`
 by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
@@ -54,3 +61,15 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/qa-assist` | Human-led QA assist loop — set up, then ride a rolling multi-observation intake session. The operator reports observations in any order; the agent enriches each (repro + root-cause file:line + coverage verdict for bugs; analysis + options + recommendation for enhancements), asks clarifying questions only when ambiguous, and appends a redacted ledger item — recording, never planning — to a persistent, resumable session under temp/qa/. Only when the operator says they are done does it review the full ledger and hand off to /plan. |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |
 | `/qa-run` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |
+
+## Loops namespace (3)
+
+Loop units project to `.claude/commands/loops/<name>.md` and are invoked
+as `/loops:<name>` (flat fallback `/loops-<name>` on hosts that flatten
+subdirectory commands).
+
+| Command | Description |
+| --- | --- |
+| `/loops:fix-failing-tests` | Self-paced convergence loop that drives a red test suite to green. Each round reads the latest failure, applies the smallest fix, and re-runs the verify oracle (`npm test`); the loop terminates when the oracle exits 0. The host (`/loop`) owns iteration and pacing — mandrel supplies the action, the goal, and the terminating oracle. |
+| `/loops:nightly-audit` | Cron maintenance loop that runs a nightly audit sweep over the repository and files actionable findings. Each run executes the audit workflows and routes the results; the host (`/schedule` or a cron-driven `/loop`) owns the cadence. verify is optional for a cron loop — the scheduler owns iteration, so this unit ships the action and goal, not a terminating oracle. |
+| `/loops:watch-ci` | Interval watch loop that polls a pull request's CI checks until they settle. Each round runs `gh pr checks` and reports the delta; the host (`/loop 5m`) owns the cadence and re-invokes the unit on its schedule. verify is optional for an interval loop — the externally-scheduled host owns iteration, so this unit ships the action and goal, not a terminating oracle. |

package/.agents/schemas/agentrc.schema.json

@@ -635,7 +635,7 @@
         },
         "nodeModulesStrategy": {
           "type": "string",
-          "enum": ["per-worktree", "symlink", "pnpm-store"]
+          "enum": ["per-worktree", "clone", "symlink", "pnpm-store"]
         },
         "primeFromPath": {
           "type": ["string", "null"],

package/.agents/schemas/dispatch-manifest.json

@@ -125,7 +125,7 @@
                 },
                 "verify": {
                   "type": "array",
-                  "description": "Inline verify commands or shell snippets executed at close to prove the Story.",
+                  "description": "Inline verify commands or shell snippets run by the pre-close acceptance self-eval critic as required, binding evidence that the Story's acceptance criteria are met — NOT by the close-validation gate chain (which runs only the canonical gate list).",
                   "items": { "type": "string" }
                 },
                 "dependsOn": {

package/.agents/schemas/lifecycle/loop.tick.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/loop.tick.schema.json",
+  "title": "loop.tick",
+  "description": "Emitted once per pass of a host-driven loop (e.g. a recurring loop command or a long-running poll) so each round lands an inspectable ledger record. Surfaces the loop as forward-progress evidence the /deliver idle watchdog already scans — distinct from story.heartbeat, which carries Story-phase info for a single in-flight Story. A loop is not tied to a Story tier: loop.tick carries a free-form loopName, a monotonic round counter, the configured cadence, and a status so a host loop never runs silently. cadence is the loop's configured interval label (e.g. '5m', 'self-paced'); status is the per-round verdict (running while the loop continues, done when it terminates normally, blocked when it stalls).",
+  "type": "object",
+  "required": ["event", "loopName", "round", "cadence", "status", "timestamp"],
+  "properties": {
+    "event": { "type": "string", "const": "loop.tick" },
+    "loopName": { "type": "string", "minLength": 1 },
+    "round": { "type": "integer", "minimum": 0 },
+    "cadence": { "type": "string", "minLength": 1 },
+    "status": {
+      "type": "string",
+      "enum": ["running", "done", "blocked"]
+    },
+    "timestamp": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/loop-unit.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/loop-unit.schema.json",
+  "version": "1.0.0",
+  "title": "Loop Unit (recurring-work definition)",
+  "description": "Schema for the YAML frontmatter of a loop unit — a markdown file under .agents/workflows/loops/ that defines a recurring/iterative unit of work with a checkable definition of done. The loop block carries the cadence (how the loop is paced), the goal (what the loop is trying to achieve), an optional verify command/array (the at-keyboard checks proving a round is complete — required for self-paced cadence, optional for interval/cron), a maxRounds backstop, and an onExhaust policy describing what happens when the round cap is hit without the goal being met.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["loop"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional reference to this schema file so YAML editors with $schema-aware autocomplete can resolve it from the unit file itself."
+    },
+    "description": {
+      "type": "string",
+      "description": "Optional human-readable summary of what this loop unit does."
+    },
+    "loop": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["cadence", "goal"],
+      "description": "The loop definition block. Carries the cadence, goal, conditional verify, round cap, and exhaustion policy.",
+      "properties": {
+        "cadence": {
+          "type": "string",
+          "enum": ["self-paced", "interval", "cron"],
+          "description": "How the loop is paced. 'self-paced' lets the agent decide when to run the next round and therefore MUST carry a verify[] so each round has a checkable definition of done. 'interval' and 'cron' are externally scheduled, so verify is optional."
+        },
+        "goal": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Required. What the loop is trying to achieve — the standing objective each round works toward."
+        },
+        "verify": {
+          "description": "Command(s) that prove a round is complete. A single command string or an array of command strings. Required when cadence is 'self-paced'; optional for 'interval' / 'cron'.",
+          "oneOf": [
+            { "type": "string", "minLength": 1 },
+            {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "minItems": 1
+            }
+          ]
+        },
+        "maxRounds": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Optional positive-integer backstop on the number of loop rounds before the onExhaust policy fires."
+        },
+        "onExhaust": {
+          "type": "string",
+          "enum": ["block", "report", "hand-back"],
+          "description": "What happens when maxRounds is hit without the goal met. 'block' transitions to a HITL gate; 'report' emits a summary and stops; 'hand-back' returns control to the caller."
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "cadence": { "const": "self-paced" } },
+            "required": ["cadence"]
+          },
+          "then": {
+            "required": ["verify"]
+          }
+        }
+      ]
+    }
+  }
+}

package/.agents/schemas/validation-evidence.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "validation-evidence",
   "title": "Validation Evidence",
-  "description": "Per-scope record of which validation gates have passed against which commit SHA. Written by lib/validation-evidence.js under the per-Epic temp tree at temp/epic-<epicId>/validation-evidence.json (Epic-scoped) or temp/epic-<epicId>/stories/story-<storyId>/validation-evidence.json (Story-scoped); both are gitignored via temp/. Consumed by close-validation, epic-code-review, and /deliver Phase 3 (close-validation) to skip identical re-runs against an already-validated tree. The `storyId` field carries the scope id and equals the epic id for Epic-scoped records.",
+  "description": "Per-scope record of which validation gates have passed against which commit SHA. Written by lib/validation-evidence.js under the per-Epic temp tree at temp/epic-<epicId>/validation-evidence.json (Epic-scoped) or temp/epic-<epicId>/stories/story-<storyId>/validation-evidence.json (Story-scoped). Standalone Stories (no parent Epic) use a storyId-anchored keyspace at temp/standalone/stories/story-<storyId>/validation-evidence.json. All paths are gitignored via temp/. Consumed by close-validation, epic-code-review, the acceptance self-eval critic, and /deliver Phase 3 (close-validation) to skip identical re-runs against an already-validated tree. The `storyId` field carries the scope id and equals the epic id for Epic-scoped records.",
   "type": "object",
   "required": ["storyId", "schemaVersion", "records"],
   "properties": {
@@ -32,6 +32,7 @@
           "gateName": {
             "type": "string",
             "enum": [
+              "typecheck",
               "lint",
               "test",
               "format",

package/.agents/scripts/audit-to-stories.js

@@ -40,6 +40,7 @@ import { parseAuditReports } from './lib/audit-to-stories/parse-audit-md.js';
 import { buildEpicSeedMarkdown } from './lib/audit-to-stories/seed-epic-from-findings.js';
 import { runAsCli } from './lib/cli-utils.js';
 import { Logger } from './lib/Logger.js';
+import { parse as parseStoryBody } from './lib/story-body/story-body.js';
 
 const SEVERITY_RANK = { critical: 4, high: 3, medium: 2, low: 1 };
 const DEFAULT_GLOB = 'temp/audits/audit-*-results.md';
@@ -227,6 +228,46 @@ function loadPlan(planPath) {
   return JSON.parse(fs.readFileSync(planPath, 'utf8'));
 }
 
+/**
+ * Build every eligible group into a `{ title, body, labels }` Story object and
+ * gate the batch against the inline-contract bar BEFORE any issue is opened.
+ *
+ * The `--emit-stories` path opens GitHub issues directly (no decomposer
+ * round-trip), so `assertEveryStoryHasInlineContract` never runs against these
+ * bodies. This gate restores that guarantee at the standalone seam: each
+ * emitted body is re-parsed through the canonical `story-body` parser and must
+ * carry a non-empty `acceptance[]` AND a non-empty `verify[]`. A body that
+ * fails throws, surfacing the gap instead of opening an ungated Story
+ * (Story #4270).
+ *
+ * @param {Array<{ group: object }>} eligible — classifications eligible to create.
+ * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} edges — sequencing edges.
+ * @returns {Array<{ title: string, body: string, labels: string[] }>}
+ */
+function buildAndGateStories(eligible, edges) {
+  const built = eligible.map((g) => buildStoryBody({ group: g, edges }));
+  const offenders = [];
+  for (const story of built) {
+    const { body } = parseStoryBody(story.body);
+    const ok =
+      Array.isArray(body.acceptance) &&
+      body.acceptance.length > 0 &&
+      Array.isArray(body.verify) &&
+      body.verify.length > 0;
+    if (!ok) offenders.push(story.title);
+  }
+  if (offenders.length > 0) {
+    throw new Error(
+      `inline-contract gate failed: ${offenders.length} generated audit Story/Stories lack a non-empty acceptance[] + verify[] contract: ${offenders
+        .map((t) => `"${t}"`)
+        .join(
+          ', ',
+        )}. No issues were opened. Every emitted Story must carry both arrays.`,
+    );
+  }
+  return built;
+}
+
 function persist(text, outPath) {
   if (!outPath) {
     process.stdout.write(text);
@@ -242,6 +283,7 @@ export const __testing = {
   buildPlan,
   loadProvider,
   dedupSkippedWarning,
+  buildAndGateStories,
 };
 
 async function main() {
@@ -289,7 +331,7 @@ async function main() {
     const eligible = (plan.classifications ?? [])
       .filter((c) => c.action === 'create')
       .map((c) => c.group);
-    const built = eligible.map((g) => buildStoryBody({ group: g }));
+    const built = buildAndGateStories(eligible, plan.edges ?? []);
     const out = values.json
       ? JSON.stringify(built, null, 2)
       : built

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

@@ -258,7 +258,14 @@ function stripAnchorAndQuery(target) {
 //     `temp/epic-[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.
-const SLASH_TOKEN_RE = /(?<![\w/:.>\])])\/([a-z][a-z0-9-]*)(?![\w.-])/g;
+// The optional `(?::[a-z][a-z0-9-]*)?` tail captures the namespaced
+// `/loops:<name>` command form (Story #4289). Without it the matcher would
+// stop at `loops` and try to resolve `.agents/workflows/loops.md`, which does
+// not exist — loop units live under `loops/<name>.md`. The resolver below
+// splits the captured `loops:<name>` token on the `:` to resolve the
+// namespaced path.
+const SLASH_TOKEN_RE =
+  /(?<![\w/:.>\])])\/([a-z][a-z0-9-]*(?::[a-z][a-z0-9-]*)?)(?![\w.-])/g;
 
 export function extractSlashTokens(masked) {
   const out = [];
@@ -334,6 +341,22 @@ export function checkFile(absPath, repoRoot) {
   for (const { token, line } of slashTokens) {
     if (RETIRED_COMMANDS.has(token)) continue;
     if (SLASH_ALLOWLIST.has(token)) continue;
+    // Namespaced loop commands (`/loops:<name>`, Story #4289) resolve to a
+    // loop unit under `.agents/workflows/loops/<name>.md`. Split on the `:`
+    // and resolve the namespaced path rather than a flat `loops:<name>.md`.
+    if (token.includes(':')) {
+      const [ns, name] = token.split(':');
+      const nsFile = path.join(workflowsDir, ns, `${name}.md`);
+      if (!fs.existsSync(nsFile)) {
+        violations.push({
+          file: relFile,
+          line,
+          kind: 'unknown-command',
+          message: `slash command /${token} does not resolve to .agents/workflows/${ns}/${name}.md`,
+        });
+      }
+      continue;
+    }
     const workflowFile = path.join(workflowsDir, `${token}.md`);
     const helperFile = path.join(workflowsDir, 'helpers', `${token}.md`);
     if (!fs.existsSync(workflowFile) && !fs.existsSync(helperFile)) {

package/.agents/scripts/check-loop-units.js

@@ -0,0 +1,204 @@
+/**
+ * CLI: loop-unit lint gate (Story #4288, Epic #4284).
+ *
+ * Validates every loop-unit markdown file under `.agents/workflows/loops/`
+ * against `.agents/schemas/loop-unit.schema.json` via
+ * `lib/loop-units/validate-loop-unit.js`. An absent or empty loops
+ * directory is a **clean pass** (exit 0) — the gate only fails when a unit
+ * file is present and invalid.
+ *
+ * On any invalid (or structurally unparseable) unit the CLI prints a
+ * message naming the offending file and the missing/invalid field, then
+ * exits non-zero. This is wired into `npm run lint` so a malformed loop
+ * unit fails the lint gate.
+ *
+ * Flags:
+ *   --dir <path>  override the loops directory (default
+ *                 `.agents/workflows/loops`, resolved from cwd)
+ *   --json        write a structured envelope to stdout instead of the
+ *                 human-readable preview
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { runAsCli } from './lib/cli-utils.js';
+import {
+  LoopUnitParseError,
+  validateLoopUnit,
+} from './lib/loop-units/validate-loop-unit.js';
+
+export const DEFAULT_LOOPS_DIR = path.join('.agents', 'workflows', 'loops');
+
+/**
+ * Parse argv for `--dir <path>` and `--json`. Exported so tests can pin
+ * the parser.
+ *
+ * @param {string[]} argv
+ * @returns {{ dir: string | null, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let dir = null;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--dir') {
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) {
+        dir = next;
+        i += 1;
+      }
+    } else if (a === '--json') {
+      json = true;
+    }
+  }
+  return { dir, json };
+}
+
+/**
+ * `README.md` (any case) under the loops directory is namespace
+ * documentation, not a loop unit — it carries no `loop:` frontmatter and is
+ * not projected as a `/loops:` command (see `sync-claude-commands.js`). It is
+ * excluded from the loop-unit collector so the lint gate never flags the
+ * directory's own README as a malformed unit.
+ *
+ * @param {string} name a directory-entry basename
+ * @returns {boolean}
+ */
+export function isLoopUnitFile(name) {
+  return name.endsWith('.md') && name.toLowerCase() !== 'readme.md';
+}
+
+/**
+ * Collect `*.md` loop-unit files directly under `dir`, sorted. Returns an
+ * empty array when the directory is absent (the clean-pass case). The
+ * directory's `README.md` is excluded — it is namespace documentation, not a
+ * unit (see `isLoopUnitFile`).
+ *
+ * @param {string} dir absolute path
+ * @returns {string[]} absolute paths
+ */
+export function collectLoopUnitFiles(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries
+    .filter((e) => e.isFile() && isLoopUnitFile(e.name))
+    .map((e) => path.join(dir, e.name))
+    .sort();
+}
+
+/**
+ * Validate every loop unit under `dir`. Returns the per-file results and a
+ * roll-up `failures` array carrying `{ file, issues }` for each invalid or
+ * unparseable unit.
+ *
+ * @param {string} dir absolute path
+ * @param {{ schemaPath?: string }} [opts]
+ * @returns {{ files: string[], failures: Array<{ file: string, issues: Array<{path:string,message:string}> }> }}
+ */
+export function checkLoopUnits(dir, opts = {}) {
+  const files = collectLoopUnitFiles(dir);
+  const failures = [];
+  for (const file of files) {
+    try {
+      const { valid, issues } = validateLoopUnit(file, opts);
+      if (!valid) failures.push({ file, issues });
+    } catch (err) {
+      if (err instanceof LoopUnitParseError) {
+        failures.push({ file, issues: [{ path: '/', message: err.reason }] });
+      } else {
+        throw err;
+      }
+    }
+  }
+  return { files, failures };
+}
+
+/**
+ * Render the human-readable report. Each failure lists the offending file
+ * and one line per issue naming the field path and message.
+ *
+ * @param {{ files: string[], failures: Array<{ file: string, issues: Array<{path:string,message:string}> }> }} result
+ * @returns {string}
+ */
+export function renderReport({ files, failures }) {
+  const lines = [];
+  if (files.length === 0) {
+    lines.push('[check-loop-units] no loop units found (ok)');
+    return lines.join('\n');
+  }
+  for (const { file, issues } of failures) {
+    lines.push(`✖ ${file}`);
+    for (const issue of issues) {
+      lines.push(`    ${issue.path}: ${issue.message}`);
+    }
+  }
+  const tag = failures.length > 0 ? '(gate fail)' : '(ok)';
+  lines.push(
+    `[check-loop-units] checked=${files.length} invalid=${failures.length} ${tag}`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Top-level CLI entry. Exported so tests can drive the full pipeline
+ * against a tmpdir fixture directory.
+ *
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ * }} [opts]
+ * @returns {Promise<number>} 0 = clean; 1 = at least one invalid unit
+ */
+export async function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+} = {}) {
+  const { dir, json } = parseArgv(argv);
+  const loopsDir = path.resolve(cwd, dir ?? DEFAULT_LOOPS_DIR);
+  const result = checkLoopUnits(loopsDir);
+  const exitCode = result.failures.length > 0 ? 1 : 0;
+
+  if (json) {
+    stdout.write(
+      `${JSON.stringify(
+        {
+          kind: 'loop-units-report',
+          dir: loopsDir,
+          checked: result.files.length,
+          failures: result.failures,
+          exitCode,
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } else {
+    const report = renderReport(result);
+    if (exitCode === 0) {
+      stdout.write(`${report}\n`);
+    } else {
+      stderr.write(`${report}\n`);
+    }
+  }
+
+  return exitCode;
+}
+
+async function main() {
+  return runCli();
+}
+
+runAsCli(import.meta.url, main, {
+  source: 'check-loop-units',
+  propagateExitCode: true,
+  errorPrefix: '[check-loop-units] ❌ Fatal error',
+});

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

@@ -38,6 +38,7 @@ import { runAsCli } from './lib/cli-utils.js';
 import { 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 { parseLinkedIssues } from './lib/issue-link-parser.js';
 import { Logger } from './lib/Logger.js';
 import {
   resolveOperator,
@@ -143,6 +144,8 @@ function resolveGitUserEmail(cwd) {
  *   storyCount: number,
  *   concurrencyCap: number,
  *   stories: Array<{ storyId: number, title: string, worktree?: string }>,
+ *   prdId: number|null,
+ *   techSpecId: number|null,
  *   checkpointInitializedAt: string,
  * }>}
  */
@@ -374,11 +377,21 @@ export async function runEpicDeliverPrepare({
     });
   }
 
+  // Story #4253: resolve the Epic's PRD / Tech-Spec linkages ONCE here and
+  // surface them in the prepare envelope. The /deliver fan-out threads these
+  // into each per-Story `story-init.js --prd/--tech-spec`, collapsing the
+  // N per-Story `getEpic` round-trips to this single parent-side resolution.
+  // The Epic snapshot is already in hand (`state.epic`), so this adds no
+  // extra fetch; the body-parse fallback mirrors hierarchy-tracer's source.
+  const { prdId, techSpecId } = resolveEpicLinkages(state.epic);
+
   return {
     epicId,
     storyCount: openStories.length,
     concurrencyCap,
     stories,
+    prdId,
+    techSpecId,
     checkpointInitializedAt:
       checkpointState.startedAt ??
       checkpointState.lastUpdatedAt ??
@@ -388,6 +401,24 @@ export async function runEpicDeliverPrepare({
   };
 }
 
+/**
+ * Resolve an Epic's linked PRD / Tech-Spec issue ids from the snapshot ticket.
+ * Prefers the provider-supplied `linkedIssues` map and falls back to parsing
+ * the Epic body's `## Planning Artifacts` section — the same two sources
+ * `hierarchy-tracer.js` reads — so the threaded ids match what an unthreaded
+ * `story-init.js` run would have resolved itself. Story #4253.
+ *
+ * @param {{ linkedIssues?: { prd?: number|null, techSpec?: number|null }|null, body?: string }|null|undefined} epic
+ * @returns {{ prdId: number|null, techSpecId: number|null }}
+ */
+function resolveEpicLinkages(epic) {
+  const linked = epic?.linkedIssues ?? parseLinkedIssues(epic?.body ?? '');
+  return {
+    prdId: linked?.prd ?? null,
+    techSpecId: linked?.techSpec ?? null,
+  };
+}
+
 async function main() {
   const { values } = parseArgs({
     options: {