mandrel 1.76.0 → 1.77.0

package/.agents/scripts/run-coverage.js

@@ -27,6 +27,14 @@
  * `c8 report` path is ~19% faster end-to-end on a Windows dev host
  * while producing an identical `coverage-final.json` artifact for the
  * CRAP gate.
+ *
+ * Test-runner concurrency: the suite spawn reuses `TEST_RUNNER_FLAGS`
+ * from `run-tests.js` — the single source of truth for the
+ * `--test-concurrency` value, derived at startup from the host's
+ * available parallelism and clamped to `[TEST_CONCURRENCY_MIN,
+ * TEST_CONCURRENCY_MAX]`. This keeps the coverage gate (which runs the
+ * suite at every story close on both delivery paths) host-aware instead
+ * of pinned to the historical literal of 8.
  */
 
 import { spawnSync } from 'node:child_process';
@@ -37,6 +45,7 @@ import { fileURLToPath } from 'node:url';
 
 import { cleanupRepoTestTempArtifacts } from './cleanup-repo-test-temp.js';
 import { C8_CLI } from './lib/c8-cli-path.js';
+import { TEST_RUNNER_FLAGS } from './run-tests.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..', '..');
@@ -45,59 +54,90 @@ const require = createRequire(import.meta.url);
 const C8_CONFIG = require('../../.c8rc.cjs');
 const V8_TMP = path.join(COVERAGE_DIR, 'tmp');
 
-rmSync(COVERAGE_DIR, { recursive: true, force: true });
-mkdirSync(V8_TMP, { recursive: true });
+/**
+ * Build the `node --test` argv for the coverage suite spawn.
+ *
+ * Reuses the shared `TEST_RUNNER_FLAGS` (the single source of truth for
+ * the host-aware, clamped `--test-concurrency` value) so the coverage
+ * path never drifts from `run-tests.js`. The `runnerFlags` parameter is
+ * injected in tests so the argv can be asserted without touching the OS.
+ *
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.runnerFlags]
+ * @param {string} [opts.testGlob]
+ * @returns {string[]}
+ */
+export function buildCoverageTestArgs({
+  runnerFlags = TEST_RUNNER_FLAGS,
+  testGlob = 'tests/**/*.test.js',
+} = {}) {
+  return [...runnerFlags, testGlob];
+}
+
+/**
+ * Execute the coverage pipeline: run the suite under `NODE_V8_COVERAGE`,
+ * post-process the dumps with `c8 report`, then gate on the coverage
+ * baseline. Returns the first non-zero exit code across the three stages
+ * (or the baseline check's status when both prior stages pass).
+ *
+ * @returns {number}
+ */
+function runCoveragePipeline() {
+  rmSync(COVERAGE_DIR, { recursive: true, force: true });
+  mkdirSync(V8_TMP, { recursive: true });
 
-const testRun = spawnSync(
-  process.execPath,
-  [
-    '--experimental-test-module-mocks',
-    '--test',
-    '--test-concurrency=8',
-    'tests/**/*.test.js',
-  ],
-  {
+  const testRun = spawnSync(process.execPath, buildCoverageTestArgs(), {
     cwd: ROOT,
     stdio: 'inherit',
     env: { ...process.env, NODE_V8_COVERAGE: V8_TMP },
-  },
-);
+  });
 
-cleanupRepoTestTempArtifacts({ repoRoot: ROOT });
+  cleanupRepoTestTempArtifacts({ repoRoot: ROOT });
 
-const includeArgs = (C8_CONFIG.include ?? []).flatMap((p) => ['--include', p]);
-const excludeArgs = (C8_CONFIG.exclude ?? []).flatMap((p) => ['--exclude', p]);
+  const includeArgs = (C8_CONFIG.include ?? []).flatMap((p) => [
+    '--include',
+    p,
+  ]);
+  const excludeArgs = (C8_CONFIG.exclude ?? []).flatMap((p) => [
+    '--exclude',
+    p,
+  ]);
 
-const reportRun = spawnSync(
-  process.execPath,
-  [
-    C8_CLI,
-    'report',
-    '--reporter=json',
-    '--reporter=text',
-    '--temp-directory',
-    V8_TMP,
-    ...includeArgs,
-    ...excludeArgs,
-  ],
-  { cwd: ROOT, stdio: 'inherit', shell: false },
-);
+  const reportRun = spawnSync(
+    process.execPath,
+    [
+      C8_CLI,
+      'report',
+      '--reporter=json',
+      '--reporter=text',
+      '--temp-directory',
+      V8_TMP,
+      ...includeArgs,
+      ...excludeArgs,
+    ],
+    { cwd: ROOT, stdio: 'inherit', shell: false },
+  );
 
-const checkRun = spawnSync(
-  process.execPath,
-  [
-    path.join(ROOT, '.agents', 'scripts', 'check-baselines.js'),
-    '--gate',
-    'coverage',
-  ],
-  { cwd: ROOT, stdio: 'inherit' },
-);
+  const checkRun = spawnSync(
+    process.execPath,
+    [
+      path.join(ROOT, '.agents', 'scripts', 'check-baselines.js'),
+      '--gate',
+      'coverage',
+    ],
+    { cwd: ROOT, stdio: 'inherit' },
+  );
 
-const exitCode =
-  testRun.status !== 0
-    ? testRun.status
+  return testRun.status !== 0
+    ? (testRun.status ?? 1)
     : reportRun.status !== 0
-      ? reportRun.status
-      : checkRun.status;
+      ? (reportRun.status ?? 1)
+      : (checkRun.status ?? 1);
+}
 
-process.exit(exitCode ?? 1);
+// Run the pipeline only when invoked directly as a CLI; importing the
+// module (e.g. from a test asserting the spawn argv) must not spawn the
+// real suite.
+if (fileURLToPath(import.meta.url) === path.resolve(process.argv[1] ?? '')) {
+  process.exit(runCoveragePipeline());
+}

package/.agents/scripts/single-story-init.js

@@ -51,6 +51,7 @@ import {
   branchExistsLocally,
   branchExistsViaTrackingRef,
   classifyBranchSeed,
+  seedStoryBranchRef,
 } from './lib/git-branch-lifecycle.js';
 import { getStoryBranch, gitSpawn, gitSync } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
@@ -376,36 +377,28 @@ export async function materializeBaseBranch({
  * @param {Function} opts.progress
  */
 export function seedStoryBranch({ cwd, storyBranch, baseBranch, progress }) {
-  const seedAction = decideStoryBranchSeed({
-    localHas: branchExistsLocally(storyBranch, cwd),
-    remoteHas: branchExistsViaTrackingRef(storyBranch, cwd),
+  // Standalone path: no concurrent creator to race, so create failures are
+  // fatal (`swallowCreateRace: false`) and a failed fetch throws. The
+  // seed-action switch shell is single-homed in `seedStoryBranchRef`
+  // (Story #4255); this caller only supplies its `baseRef`, its git seams
+  // bound to `cwd`, and its own log/error vocabulary.
+  seedStoryBranchRef({
+    storyBranch,
+    baseRef: baseBranch,
+    swallowCreateRace: false,
+    spawn: (args) => gitSpawn(cwd, ...args),
+    existsLocally: (b) => branchExistsLocally(b, cwd),
+    existsRemotely: (b) => branchExistsViaTrackingRef(b, cwd),
+    progress,
+    messages: {
+      reuse: (b) => `Reusing existing local story branch: ${b}`,
+      fetch: (b) => `Fetching remote story branch: ${b}`,
+      create: (b, ref) => `Creating story branch ref: ${b} from ${ref}`,
+      createError: (b, _ref, stderr) =>
+        `Failed to create story branch ${b}: ${stderr || '(no stderr)'}`,
+      fetchError: (b, stderr) => `Failed to fetch story branch ${b}: ${stderr}`,
+    },
   });
-  if (seedAction === 'fetch') {
-    progress('GIT', `Fetching remote story branch: ${storyBranch}`);
-    const r = gitSpawn(cwd, 'fetch', 'origin', `${storyBranch}:${storyBranch}`);
-    if (r.status !== 0) {
-      throw new Error(
-        `Failed to fetch story branch ${storyBranch}: ${r.stderr || '(no stderr)'}`,
-      );
-    }
-    return;
-  }
-  if (seedAction === 'create') {
-    progress(
-      'GIT',
-      `Creating story branch ref: ${storyBranch} from ${baseBranch}`,
-    );
-    const r = gitSpawn(cwd, 'branch', storyBranch, baseBranch);
-    if (r.status !== 0) {
-      throw new Error(
-        `Failed to create story branch ${storyBranch}: ${r.stderr || '(no stderr)'}`,
-      );
-    }
-    return;
-  }
-  // seedAction === 'reuse' — the local ref already exists. Do NOT run
-  // `git branch` here; re-creating an existing ref throws. Reuse it.
-  progress('GIT', `Reusing existing local story branch: ${storyBranch}`);
 }
 
 /**

package/.agents/scripts/story-init.js

@@ -38,7 +38,6 @@ import {
 } from './lib/config-resolver.js';
 import { parseBlockedBy } from './lib/dependency-parser.js';
 import { getEpicBranch, getStoryBranch } from './lib/git-utils.js';
-import { runInstallCommand } from './lib/install-cmd-parser.js';
 import { Logger } from './lib/Logger.js';
 import { setActiveStoryEnv } from './lib/observability/active-story-env.js';
 import {
@@ -89,6 +88,8 @@ export async function runStoryInit({
   dryRun: dryRunParam,
   cwd: cwdParam,
   recutOf: recutOfParam,
+  prdId: prdIdParam,
+  techSpecId: techSpecIdParam,
   injectedProvider,
   injectedConfig,
 } = {}) {
@@ -99,10 +100,17 @@ export async function runStoryInit({
           dryRun: !!dryRunParam,
           cwd: cwdParam ?? null,
           recutOf: recutOfParam ?? null,
+          prdId: prdIdParam ?? null,
+          techSpecId: techSpecIdParam ?? null,
         }
       : parseSprintArgs();
   const { storyId, dryRun } = parsed;
   const recutOf = recutOfParam ?? parsed.recutOf ?? null;
+  // Story #4253: pre-resolved Epic linkages (from the /deliver fan-out's
+  // one-time Epic resolution). When both are present, hierarchy-tracer skips
+  // the per-Story getEpic round-trip; when absent it resolves them itself.
+  const threadedPrdId = prdIdParam ?? parsed.prdId ?? null;
+  const threadedTechSpecId = techSpecIdParam ?? parsed.techSpecId ?? null;
   // Worktree-aware cwd resolution: explicit param > --cwd flag > env > PROJECT_ROOT.
   const cwd = path.resolve(cwdParam ?? parsed.cwd ?? PROJECT_ROOT);
 
@@ -147,11 +155,13 @@ export async function runStoryInit({
     input: { storyId, recutOf, dryRun },
   });
 
-  // Stage 2 — hierarchy.
+  // Stage 2 — hierarchy. When the /deliver fan-out threaded --prd/--tech-spec
+  // (both resolved once by the parent), this short-circuits the per-Story
+  // getEpic. Absent flags fall back to the legacy getEpic resolution.
   const { prdId, techSpecId } = await traceHierarchy({
     provider,
     logger: stageLogger,
-    input: { epicId },
+    input: { epicId, prdId: threadedPrdId, techSpecId: threadedTechSpecId },
   });
 
   progress('CONTEXT', `Epic: #${epicId}, Parent: #${parentId ?? 'none'}`);
@@ -366,9 +376,16 @@ const VALID_INSTALLED_STATES = new Set(['true', 'false', 'skipped']);
 
 /**
  * Apply the dependenciesInstalled tri-state to derive the next install
- * action. Pure helper — exposes the Step 0.5 truth table as data so tests
+ * action. Pure helper — exposes the install truth table as data so tests
  * can pin each branch without spinning up a child process.
  *
+ * Story #4249: this is no longer wired into a post-init re-install. The
+ * in-`ensure` install (with its PM-aware retry budget) is the single install
+ * owner; the formerly-hardcoded `npm ci` retry inside `runStoryInitPrepare`
+ * was deleted. The tri-state still flows onto the `story-init` structured
+ * comment (`dependenciesInstalled`) as the workflow-facing signal, and this
+ * helper remains its canonical classifier.
+ *
  * @param {'true' | 'false' | 'skipped'} dependenciesInstalled
  * @param {{ skipInstall?: boolean }} [options]
  * @returns {'skip' | 'install'}
@@ -384,54 +401,33 @@ export function deriveInstallAction(dependenciesInstalled, options = {}) {
 }
 
 /**
- * Resolve the install command to run when `dependenciesInstalled === 'false'`.
- * `project.commands` does not currently carry a dedicated install key,
- * so this defaults to `npm ci`. Operators can override per-invocation via
- * the `installCmd` option.
+ * Post-init prepare step (Story #4017 — formerly a standalone prepare CLI,
+ * now consuming the in-process init result instead of re-reading the
+ * `story-init` structured comment).
  *
- * @param {{ override?: string }} [options]
- * @returns {string}
- */
-export function resolveInstallCommand(options = {}) {
-  const trimmed = options.override?.trim();
-  if (trimmed) {
-    return trimmed;
-  }
-  return 'npm ci';
-}
-
-/**
- * Post-init prepare step (Story #4017 — formerly a standalone prepare
- * CLI, now consuming the in-process init result
- * instead of re-reading the `story-init` structured comment):
+ * Story #4249: the install branch was deleted. The worktree install is owned
+ * entirely by `WorktreeManager.ensure` (via `installDependencies`), which now
+ * carries a PM-aware retry budget (`installRetryPolicy`) — so a transient
+ * first-attempt failure retries there with the correct package-manager
+ * command, never an unconditional `npm ci` re-run after init. This step is now
+ * purely the snapshot-render half:
  *
- *   1. Apply the `dependenciesInstalled` tri-state truth table — `'false'`
- *      (install attempted and failed) retries the install command in the
- *      worktree; `'true'` / `'skipped'` proceed.
- *   2. Render the initial Story-phase snapshot with every phase pinned to
- *      `pending` and `phase: 'init'` via `upsertStoryRunProgress`
- *      (render-only since Story #3909 — no comment is posted). The
- *      `renderedBody` markdown is relayed to chat by the delivery
- *      workflows so operators see the initial progress block before the
- *      first commit lands.
+ *   - Render the initial Story-phase snapshot with every phase pinned to
+ *     `pending` and `phase: 'init'` via `upsertStoryRunProgress` (render-only
+ *     since Story #3909 — no comment is posted). The `renderedBody` markdown is
+ *     relayed to chat by the delivery workflows so operators see the initial
+ *     progress block before the first commit lands.
  *
- * Install failure throws (init exits non-zero); a snapshot-render failure
- * is non-fatal observability loss and only warns.
+ * A snapshot-render failure is non-fatal observability loss and only warns.
  *
  * @param {{
  *   provider: object,
  *   storyId: number,
- *   result: { workCwd?: string, dependenciesInstalled?: string, storyBranch?: string },
+ *   result: { storyBranch?: string },
  *   notify?: Function | null,
- *   runInstall?: (cmd: string, cwd: string) => { status: number, stderr?: string },
- *   skipInstall?: boolean,
- *   installCmd?: string,
  *   logger?: object,
  * }} args
  * @returns {Promise<{
- *   installAction: 'skip' | 'install',
- *   installCmd: string | null,
- *   installResult: { status: number, stderr?: string } | null,
  *   snapshot: object | null,
  *   renderedBody: string | null,
  * }>}
@@ -441,29 +437,8 @@ export async function runStoryInitPrepare({
   storyId,
   result,
   notify: notifyFn = null,
-  runInstall = runInstallCommand,
-  skipInstall = false,
-  installCmd: installCmdOverride,
   logger = stageLogger,
 }) {
-  const dependenciesInstalled = String(
-    result?.dependenciesInstalled ?? 'skipped',
-  );
-  const installAction = deriveInstallAction(dependenciesInstalled, {
-    skipInstall,
-  });
-  let installCmd = null;
-  let installResult = null;
-  if (installAction === 'install') {
-    installCmd = resolveInstallCommand({ override: installCmdOverride });
-    installResult = runInstall(installCmd, result.workCwd);
-    if (installResult.status !== 0) {
-      throw new Error(
-        `runStoryInitPrepare: install command \`${installCmd}\` failed with status ${installResult.status}: ${installResult.stderr ?? ''}`,
-      );
-    }
-  }
-
   let snapshot = null;
   let renderedBody = null;
   try {
@@ -483,7 +458,7 @@ export async function runStoryInitPrepare({
     );
   }
 
-  return { installAction, installCmd, installResult, snapshot, renderedBody };
+  return { snapshot, renderedBody };
 }
 
 function buildStoryInitResult({

package/.agents/scripts/story-phase.js

@@ -27,6 +27,12 @@
  *   --story <id>                        Story ID (required).
  *   --phase <init|implementing|closing|blocked|done>
  *                                       Phase the Story is entering (required).
+ *   --epic <id>                         Parent Epic id from the Step 0 envelope.
+ *                                       When supplied, skips the readEpicIdFromStory
+ *                                       GitHub read.
+ *   --branch <name>                     Story branch from the Step 0 envelope.
+ *                                       When supplied, skips the resolveStoryBranch
+ *                                       GitHub read.
  *   --no-heartbeat                      Suppress the lifecycle emit (tests).
  *
  * Stdout: a single JSON envelope
@@ -67,12 +73,17 @@ const VALID_PHASES = new Set([
 
 const HELP = `Usage: node .agents/scripts/story-phase.js \\
   --story <id> --phase <init|implementing|closing|blocked|done> \\
-  [--no-heartbeat]
+  [--epic <id>] [--branch <name>] [--no-heartbeat]
 
 Renders the Story-phase snapshot for Story #<id> at the requested phase
 (returned as renderedBody for chat relay; no comment is posted) and
 (unless --no-heartbeat) appends one story.heartbeat record to the parent
 Epic's lifecycle ledger so the Idle Watchdog can confirm the Story is alive.
+
+--epic / --branch let the caller pass the parent Epic id and Story branch
+from story-init.js's Step 0 envelope, skipping the GitHub reads
+(readEpicIdFromStory / resolveStoryBranch) that would otherwise re-fetch
+these immutable values on every phase call. Omit both for interactive use.
 `;
 
 /**
@@ -216,9 +227,17 @@ function emitHeartbeatBestEffort({
  * End-to-end phase writer. DI-friendly: tests pass `provider`, override
  * the ledger path, and skip the heartbeat as needed.
  *
+ * When `epicId` / `branch` are supplied (the `/deliver` worker passes them
+ * from `story-init.js`'s Step 0 envelope), the corresponding GitHub read is
+ * skipped entirely: `epicId` short-circuits `readEpicIdFromStory` and
+ * `branch` short-circuits `resolveStoryBranch`. Omit both for interactive
+ * use to restore the original GitHub-read resolution.
+ *
  * @param {{
  *   storyId: number,
  *   phase: string,
+ *   epicId?: number|null,
+ *   branch?: string,
  *   noHeartbeat?: boolean,
  *   provider?: object,
  *   config?: object,
@@ -230,6 +249,8 @@ export async function runStoryPhase(args) {
   const {
     storyId,
     phase,
+    epicId: epicIdOverride,
+    branch: branchOverride,
     noHeartbeat = false,
     provider: providerOverride,
     config: configOverride,
@@ -253,8 +274,17 @@ export async function runStoryPhase(args) {
     : (ticketId, payload, opts = {}) =>
         notify(ticketId, payload, { config, provider, ...opts });
 
-  const branch = await resolveStoryBranch({ provider, storyId });
-  const epicId = await readEpicIdFromStory({ provider, storyId });
+  // When the Step 0 envelope supplied the branch / epicId (the /deliver
+  // worker passes them via --branch / --epic), skip the GitHub reads that
+  // would otherwise re-fetch these immutable values on every phase call.
+  const branch =
+    typeof branchOverride === 'string' && branchOverride
+      ? branchOverride
+      : await resolveStoryBranch({ provider, storyId });
+  const epicId =
+    epicIdOverride !== undefined
+      ? epicIdOverride
+      : await readEpicIdFromStory({ provider, storyId });
   const phases = phasesForWorkflowPhase(phase, now);
 
   const { body: renderedBody, payload: snapshot } =
@@ -301,17 +331,29 @@ export function parseArgv(argv) {
     options: {
       story: { type: 'string' },
       phase: { type: 'string' },
+      epic: { type: 'string' },
+      branch: { type: 'string' },
       'no-heartbeat': { type: 'boolean' },
       help: { type: 'boolean' },
     },
     strict: false,
   });
-  return {
+  // `--epic` absent → leave `epicId` undefined so runStoryPhase falls back to
+  // the readEpicIdFromStory GitHub read. `--branch` absent → leave `branch`
+  // undefined so it falls back to resolveStoryBranch.
+  const parsed = {
     help: Boolean(values.help),
     storyId: Number.parseInt(values.story ?? '', 10),
     phase: values.phase,
     noHeartbeat: Boolean(values['no-heartbeat']),
   };
+  if (values.epic !== undefined) {
+    parsed.epicId = Number.parseInt(values.epic, 10);
+  }
+  if (typeof values.branch === 'string' && values.branch) {
+    parsed.branch = values.branch;
+  }
+  return parsed;
 }
 
 export async function main(argv = process.argv.slice(2)) {

package/.agents/skills/core/epic-plan-decompose-author/SKILL.md

@@ -206,6 +206,7 @@ They are NOT top-level ticket fields.
 
 - **slug**: MUST be hyphen-case (`^[a-z0-9][a-z0-9-]*$`). Do not use underscores.
 - **goal** (in body string): One sentence stating WHY this Story exists within the Epic.
+- **reason_to_exist** (REQUIRED, encoded in the body `<!-- meta: {...} -->` comment — NOT a top-level ticket field): One sentence stating the single coherent reason this Story exists, distinct from the broader `goal` prose. Every Story MUST carry a non-empty `reason_to_exist`; it is the machine-checkable form of the cohesion rule (**one Story = one coherent change with one reason to exist**). The `epic-plan-consolidate` critic flags any Story whose body carries no non-empty reason, and the sizing validator (`ticket-validator-sizing.js`) emits a deterministic **soft** `missing-reason-to-exist` finding as the runtime backstop. Encode it as `<!-- meta: {"reason_to_exist": "..."} -->`.
 - **changes** (in body string): Each entry is an object `{ path, assumption }` where `assumption` is one of `creates | refactors-existing | deletes`. The Phase 8 validator probes the base branch for every declared path and rejects the decompose when the declared assumption contradicts reality: `creates` against an existing path is an error, `refactors-existing` / `deletes` against a missing path is an error. Use `refactors-existing` for in-place edits to a file already on `main`; `creates` for net-new files; `deletes` for removals. Acceptable path shapes include explicit files (`src/components/Foo.tsx`), glob patterns (`tests/e2e/*.spec.ts`, `**/*.astro`), and module identifiers that resolve to files.
 - **references** (in body string, optional): Object-form entries `{ path, assumption: "exists" }` for paths the Story **reads** but does not modify (test fixtures it relies on, sibling modules it imports, feature files it scans). The validator probes these like `changes` and rejects the decompose when an `exists` path is absent on the base branch. Use this list to make read-dependencies explicit so a hallucinated or stale assumption surfaces at planning time rather than execution time.
 - **NEW-FILE CONTRACT (must-follow)**: Any path the Story references in `goal`, `acceptance`, or `verify` that does **not** already exist on `main` MUST also appear in the same Story's `changes` array with `assumption: "creates"`. The freshness validator probes `main` for every referenced code path and rejects the decompose when a missing path is absent from `changes` — even when the Story is the one authoring the file. Example: a Story creating `tests/lib/foo.test.js` whose `verify` runs `node --test tests/lib/foo.test.js` MUST include `{ "path": "tests/lib/foo.test.js", "assumption": "creates" }` in `changes`, otherwise the validator emits a freshness miss and the decompose round trips for a re-emit.
@@ -266,10 +267,11 @@ Declaring `wide` with a non-empty reason **lifts the `hardFiles` rejection** —
 
 #### BINDING ACCEPTANCE vs ADVISORY CHANGES (authoring altitude)
 
-`acceptance[]` and `verify[]` are the **binding contract** the executor MUST satisfy — they are the sole definition of "done." `changes[]` and `references[]` are an **advisory implementation sketch**: your best prediction of the file footprint, which the executor is permitted to revise when the real codebase diverges from the sketch. Author at that altitude:
+The canonical altitude + New-File Contract wording is single-sourced in `AUTHORING_ALTITUDE_GUIDANCE` in `ticket-validator-sizing.js` (Story #4272); the rendered decomposer prompt interpolates the same strings, so do not restate a divergent version here. The three canonical statements:
 
-- Write `acceptance[]`/`verify[]` to capture the **outcome**, independent of any one file layout. Do NOT pin an incidental implementation detail (an internal helper name, a private file path) into an acceptance item that the advisory `changes[]` is free to reshape — assert the observable behaviour instead.
-- Keep `changes[]`/`references[]` as the honest predicted footprint. They still pass through the structural file-assumption gate (the `creates`/`refactors-existing`/`deletes` probes against the base branch) and the New-File Contract unchanged — advisory does NOT mean unvalidated. The executor's latitude to revise the approach never licenses skipping `acceptance[]`/`verify[]` or any `rules/security-baseline.md` MUST.
+- **Binding contract vs advisory sketch.** `acceptance[]` and `verify[]` are the Story's **binding contract** — the executor MUST satisfy them exactly, and they are the only definition of "done." `changes[]` and `references[]` are an **advisory implementation sketch**: your best prediction of the file footprint, which the executor MAY revise when the real codebase diverges from the sketch. Author `acceptance[]` / `verify[]` to assert the **outcome** independent of any one file layout — never pin an incidental implementation detail (an internal helper name, a private file path) into an acceptance item that the advisory `changes[]` is free to reshape; assert the observable behaviour instead.
+- **New-File Contract.** Any path named in a Story's `goal`, `acceptance`, or `verify` that does NOT already exist on `main` MUST also appear in that Story's `changes[]` with `assumption: "creates"`; otherwise the freshness validator rejects the decompose — even when the Story is the one authoring the file.
+- **Advisory does not mean unvalidated.** `changes[]` paths still pass the base-branch file-assumption probes (a `creates` against an existing path still fails), the New-File Contract still holds, and the executor's latitude to revise the approach never licenses skipping `acceptance[]` / `verify[]` or relaxing any `rules/security-baseline.md` MUST.
 
 #### NAVIGATE-DON'T-DEEP-LINK (signed-in acceptance scenarios)
 

package/.agents/workflows/helpers/acceptance-self-eval.md

@@ -43,6 +43,33 @@ per-criterion, mid-delivery, and evaluates the actual work product.
      optional advisory pre-flight — a criterion cannot be scored `met` without
      the supporting `verify[]` evidence where a `verify[]` command is relevant
      to it.
+   - **Shares `lint` / `typecheck` evidence with close (Story #4250).** When a
+     `verify[]` command is **byte-identical** to a close-validation gate — in
+     practice only the cheap, command-identical `lint` and `typecheck` gates
+     (`npm run lint` and the resolved `project.commands.typecheck`) — the
+     critic MUST run it through `evidence-gate.js` so a passing run records an
+     evidence entry in the **same keyspace** `close-validation/runner.js`
+     consults. Run it in the **same Story worktree** the close validates (the
+     HEAD-sha key enforces "unchanged HEAD") and pass the exact gate name:
+
+     ```bash
+     # Epic-attached Story:
+     node <main-repo>/.agents/scripts/evidence-gate.js \
+       --epic-id <epicId> --scope-id <storyId> --gate lint \
+       --worktree <worktree> -- npm run lint
+
+     # Standalone Story (no parent Epic) — use --standalone, omit --epic-id:
+     node <main-repo>/.agents/scripts/evidence-gate.js \
+       --standalone --scope-id <storyId> --gate typecheck \
+       --worktree <worktree> -- <resolved typecheck command>
+     ```
+
+     Close's `shouldSkip` then short-circuits that gate when HEAD is
+     unchanged; a redraft round (HEAD moves) correctly busts it. **Never**
+     run the coverage / CRAP suite through `evidence-gate.js` to stamp it
+     fresh — a false-fresh coverage record without `coverage-final.json`
+     silently weakens the floor. Limit the evidence-share to `lint` and
+     `typecheck`.
    - Emits a verdict file under `temp/` conforming to
      [`acceptance-eval-verdict.schema.json`](../../schemas/acceptance-eval-verdict.schema.json):
      one `{ index, criterion, verdict: met|partial|unmet, evidence,

package/.agents/workflows/helpers/deliver-epic.md

@@ -167,11 +167,25 @@ Validates `type::epic`, enumerates `type::story` descendants, parses
 (to enumerate the open Story set), and upserts the `epic-run-state`
 checkpoint in the per-Story-status shape (a flat `stories` map seeded at
 `pending`, plus the global `concurrencyCap`). Treat the printed JSON as
-`state`: `{ epicId, storyCount, concurrencyCap, stories, checkpointInitializedAt }`.
+`state`: `{ epicId, storyCount, concurrencyCap, stories, prdId, techSpecId, checkpointInitializedAt }`.
 `stories` is the flat dispatch hint (`{ storyId, worktree, title }` per open
 Story); the ready-set `tick` (Phase 2) decides which to dispatch on each
 beat. Flip the Epic to `agent::executing` (idempotent) after the CLI returns.
 
+**Epic linkages resolved once (Story #4253).** The envelope also carries
+`prdId` and `techSpecId` — the Epic's linked PRD / Tech-Spec issue ids,
+resolved a **single** time here from the Epic snapshot prepare already
+holds (no extra fetch). Capture both and thread them into **every**
+per-Story `story-init.js` invocation (§ 2b → `epic-deliver-story` Step 0)
+as `--prd <prdId> --tech-spec <techSpecId>`. This collapses the N
+per-Story `getEpic` round-trips (one per child, each in its own process
+with its own provider cache) to this one parent-side resolution — the
+immutable Epic issue is invariant for the lifetime of a delivery run.
+When a linkage is `null` (the Epic links no PRD or Tech Spec), omit the
+corresponding flag; the child's `story-init.js` then falls back to its
+own `getEpic` resolution for the missing id, preserving graceful
+degradation.
+
 > **Preflight guards (Story #3482 / F-workflow-guards).** Before the
 > snapshot phase runs — and before any worktree is created — prepare runs
 > two **fail-closed** guards
@@ -334,7 +348,10 @@ matching `story.dispatch.end` record is appended later by
 `epic-execute-record-wave.js` (via `emit-story-dispatch-end.js`, Story #3900)
 after the Agent return is recorded in § 2c.
 
-Each Agent call's prompt must (1) name the Story + Epic ids, (2)
+Each Agent call's prompt must (1) name the Story + Epic ids **and the
+`prdId` / `techSpecId` from the Phase 1 prepare envelope** (Story #4253) so
+the child can thread `--prd <prdId> --tech-spec <techSpecId>` into its
+`story-init.js` Step 0 — omit whichever flag is `null`, (2)
 instruct the child to invoke `helpers/epic-deliver-story <storyId>`
 (whose Step 4 defines the child's return shape), (3) remind the child
 of the **non-interactive contract** (no clarifying questions;