mandrel 1.76.0 → 1.77.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/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/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/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: {

package/.agents/scripts/evidence-gate.js

@@ -13,7 +13,7 @@
  *
  * Usage:
  *   node .agents/scripts/evidence-gate.js \
- *     --epic-id <epicId> --scope-id <storyOrEpicId> --gate <name> \
+ *     (--epic-id <epicId> | --standalone) --scope-id <storyOrEpicId> --gate <name> \
  *     [--worktree <path>] [--no-evidence] -- <cmd> [args...]
  *
  * Examples:
@@ -21,11 +21,18 @@
  *   node .agents/scripts/evidence-gate.js --epic-id 1030 --scope-id 1030 --gate test -- npm test
  *   node .agents/scripts/evidence-gate.js --epic-id 1114 --scope-id 1120 --gate test \
  *     --worktree .worktrees/story-1120 -- npm test
+ *   node .agents/scripts/evidence-gate.js --standalone --scope-id 4250 --gate lint \
+ *     --worktree .worktrees/story-4250 -- npm run lint
  *
- * `--epic-id` is required. When `scope-id === epic-id` the evidence file is
- * Epic-scoped (`<tempRoot>/epic-<eid>/validation-evidence.json`); when
- * `scope-id !== epic-id` it is Story-scoped under
- * `<tempRoot>/epic-<eid>/story-<sid>/validation-evidence.json`.
+ * Either `--epic-id` or `--standalone` is required. When `scope-id ===
+ * epic-id` the evidence file is Epic-scoped
+ * (`<tempRoot>/epic-<eid>/validation-evidence.json`); when `scope-id !==
+ * epic-id` it is Story-scoped under
+ * `<tempRoot>/epic-<eid>/story-<sid>/validation-evidence.json`. With
+ * `--standalone` (Story #4250) the file is anchored on the Story id alone at
+ * `<tempRoot>/standalone/stories/story-<sid>/validation-evidence.json` — the
+ * same keyspace the standalone close consults, so the acceptance-self-eval
+ * critic's verify[] runs (lint / typecheck) are shared with the close.
  *
  * **Worktree-aware spawn (Story #1120).** `--cwd` (default `PROJECT_ROOT`)
  * is the *evidence cwd* — it locates the per-Epic temp tree under the main
@@ -84,6 +91,7 @@ export function parseWrapperArgs(argv) {
       'epic-id': { type: 'string' },
       gate: { type: 'string' },
       'no-evidence': { type: 'boolean', default: false },
+      standalone: { type: 'boolean', default: false },
       cwd: { type: 'string' },
       worktree: { type: 'string' },
     },
@@ -94,6 +102,7 @@ export function parseWrapperArgs(argv) {
   return {
     scopeId: Number.isNaN(scopeId) || scopeId <= 0 ? null : scopeId,
     epicId: Number.isNaN(epicId) || epicId <= 0 ? null : epicId,
+    standalone: values.standalone === true,
     gate: values.gate ?? null,
     useEvidence: values['no-evidence'] !== true,
     cwd: values.cwd ?? PROJECT_ROOT,
@@ -118,7 +127,11 @@ function resolveHeadShaDefault(cwd, gitSpawnFn) {
  *
  * @param {object} params
  * @param {number}   params.scopeId      — Story / Epic ID (positive integer).
- * @param {string}   params.gate         — Logical gate name (`lint`, `test`, …).
+ * @param {number|null} [params.epicId]  — Parent Epic id (Epic-keyed path).
+ * @param {boolean}  [params.standalone] — When true, route to the
+ *   storyId-anchored standalone keyspace instead of the Epic-keyed path
+ *   (Story #4250). Substitutes for `epicId`.
+ * @param {string}   params.gate         — Logical gate name (`lint`, `typecheck`, …).
  * @param {boolean}  params.useEvidence  — When false, force the runner.
  * @param {string}   params.cwd          — Evidence cwd (locates the per-Epic
  *   temp tree). The runner is spawned in `worktreePath` when set, else `cwd`.
@@ -144,15 +157,38 @@ export async function runEvidenceGate(params, deps = {}) {
     recordPassFn = recordPass,
     logger = Logger,
   } = deps;
-  const { scopeId, epicId, gate, useEvidence, cwd, worktreePath, runnerArgs } =
-    params ?? {};
+  const {
+    scopeId,
+    epicId,
+    standalone = false,
+    gate,
+    useEvidence,
+    cwd,
+    worktreePath,
+    runnerArgs,
+  } = params ?? {};
 
-  if (!scopeId || !epicId || !gate || !runnerArgs || runnerArgs.length === 0) {
+  // `--epic-id` is required for the Epic-keyed path; `--standalone` (Story
+  // #4250) substitutes for it and routes the evidence file to the
+  // storyId-anchored standalone keyspace so the acceptance-self-eval critic
+  // can record verify[] evidence into the same keyspace the standalone close
+  // consults.
+  if (
+    !scopeId ||
+    (!epicId && !standalone) ||
+    !gate ||
+    !runnerArgs ||
+    runnerArgs.length === 0
+  ) {
     logger.fatal(
-      'Usage: node evidence-gate.js --epic-id <epicId> --scope-id <id> --gate <name> [--worktree <path>] [--no-evidence] -- <cmd> [args...]',
+      'Usage: node evidence-gate.js (--epic-id <epicId> | --standalone) --scope-id <id> --gate <name> [--worktree <path>] [--no-evidence] -- <cmd> [args...]',
     );
     return { status: 1, skipped: false };
   }
+  // Evidence-store opts shared by shouldSkip + recordPass below. `standalone`
+  // routes to the storyId-anchored keyspace; otherwise the Epic-keyed path
+  // resolves under `epicId`.
+  const evidenceStoreOpts = { cwd, epicId, standalone };
 
   // Spawn cwd is the worktree when supplied — every gate command sees the
   // Story branch's tree, not the main checkout. Evidence cwd stays anchored
@@ -174,7 +210,7 @@ export async function runEvidenceGate(params, deps = {}) {
         currentSha: headSha,
         configHash,
       },
-      { cwd, epicId },
+      evidenceStoreOpts,
     );
     if (verdict.skip) {
       const ts = verdict.record?.timestamp ?? 'n/a';
@@ -215,7 +251,7 @@ export async function runEvidenceGate(params, deps = {}) {
           exitCode: 0,
           durationMs: Date.now() - startedAt,
         },
-        { cwd, epicId },
+        evidenceStoreOpts,
       );
     } catch (err) {
       logger.warn?.(

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -1,10 +1,11 @@
 /**
  * lib/audit-to-stories/build-story-body.js
  *
- * Render the canonical Story body for the standalone grouping mode. The
- * body follows the contract spelled out in Story #2583 acceptance
- * criteria #8: Title (caller), Summary, Acceptance Criteria, Agent
- * Prompts, Context block, fingerprint footer.
+ * Render the canonical Story body for the standalone grouping mode so a
+ * generated audit Story clears the same inline-contract bar the decomposer
+ * enforces (`assertEveryStoryHasInlineContract`): a clean goal, observable
+ * `acceptance[]`, a populated `changes[]` footprint, and a non-empty,
+ * tier-tagged `verify[]` (Story #4270).
  *
  * Pure: returns { title, body, labels }. Labels carry one canonical
  * `audit::<lens>` per distinct source report represented in the merge
@@ -14,10 +15,11 @@
  * `risk::high`.
  *
  * The body is serialized via the canonical story-body serializer
- * (`.agents/scripts/lib/story-body/story-body.js`) so the output is
- * parseable by `parse()` and round-trippable. Audit-specific content
- * (agent prompts, context links, fingerprint footer) is appended after
- * the canonical sections as extended markdown.
+ * (`.agents/scripts/lib/story-body/story-body.js`) so the output round-trips
+ * through `parse()` / `serialize()`. Audit-specific content (agent prompts,
+ * context links, fingerprint footer) is appended after the canonical sections
+ * as extended markdown — it is informational only and is not part of the
+ * structured contract.
  */
 
 import { serialize } from '../story-body/story-body.js';
@@ -26,36 +28,128 @@ import { renderFingerprintFooter } from './finding-adapter.js';
 
 const STATIC_LABELS = Object.freeze(['type::story', 'agent::ready']);
 
+// The verify[] contract every generated audit Story carries. These commands
+// exist in this repo's harness (package.json scripts) so the Story satisfies
+// the inline-contract bar with runnable, tier-tagged gates rather than
+// placeholder prose. Kept as a frozen constant so the same contract is
+// asserted by the unit suite.
+const DEFAULT_VERIFY = Object.freeze([
+  'npm run lint (validate)',
+  'npm test (unit)',
+]);
+
 function uniq(items) {
   return [...new Set(items)];
 }
 
-function summaryFromGroup(group) {
-  const lines = group.findings.map((f, idx) => {
-    const sev = f.severity ? `[${f.severity.toUpperCase()}]` : '[—]';
-    const dim = f.dimension ? `(${f.dimension})` : '';
-    return `${idx + 1}. ${sev} ${dim} **${f.title}** — ${
-      f.currentState || '_(no current-state captured)_'
-    }`;
-  });
-  return lines.join('\n');
+/**
+ * The goal is the group intent only — the synthesized `group.title`. It
+ * carries no leading ordinal (`1.`/`2.`) and no `[SEVERITY]` / `(dimension)`
+ * prefix (the polluted shape Story #4270 replaced); those signals live in the
+ * per-finding fingerprint footer and the extended Agent Prompts section, not
+ * in the goal.
+ *
+ * @param {object} group
+ * @returns {string}
+ */
+function goalFromGroup(group) {
+  return (group.title ?? '').trim();
 }
 
-function goalFromGroup(group) {
-  // Derive a concise goal statement from the group title + finding summary.
-  const summary = summaryFromGroup(group);
-  return `${group.title}\n\n${summary}`;
+/**
+ * Map every distinct file mentioned across the merge onto a canonical
+ * `changes[]` PathEntry (`{ path, assumption }`). Audit findings remediate
+ * code that already exists, so the assumption is `refactors-existing`.
+ *
+ * `group.files` is an array post-`groupFindings`; fall back to scanning the
+ * findings' own `files[]` when an upstream caller hands a group whose `files`
+ * aggregate was not materialized.
+ *
+ * @param {object} group
+ * @returns {Array<{ path: string, assumption: string }>}
+ */
+function changesFromGroup(group) {
+  const fromGroup = Array.isArray(group.files) ? group.files : [];
+  const fromFindings = (group.findings ?? []).flatMap((f) =>
+    Array.isArray(f.files) ? f.files : [],
+  );
+  const paths = uniq(
+    [...fromGroup, ...fromFindings].filter(
+      (p) => typeof p === 'string' && p.length > 0,
+    ),
+  );
+  return paths.map((path) => ({ path, assumption: 'refactors-existing' }));
+}
+
+/**
+ * Build an observable acceptance item from a single finding: a checkable
+ * end-state a reviewer can confirm, NOT the verbatim recommendation
+ * paragraph. The recommendation prose is preserved verbatim in the Agent
+ * Prompts / fingerprint footer for the implementer; the acceptance line is
+ * the binding, confirmable outcome.
+ *
+ * Shape: `<title> is remediated in <primary file>: the recommended end-state
+ * holds and the finding is no longer reproducible.` — anchored on the finding
+ * title and primary file so the reviewer knows exactly what to check.
+ *
+ * @param {object} finding
+ * @returns {string}
+ */
+function acceptanceItemFromFinding(finding) {
+  const title = (finding.title ?? 'finding').trim();
+  const primaryFile =
+    Array.isArray(finding.files) && finding.files.length > 0
+      ? finding.files[0]
+      : null;
+  const where = primaryFile ? ` in \`${primaryFile}\`` : '';
+  return `${title} is remediated${where}: the recommended end-state holds and the finding is no longer reproducible`;
 }
 
 function acceptanceCriteriaFromGroup(group) {
-  return group.findings.map((f) => {
-    const rec = f.recommendation || '_(no recommendation captured)_';
-    return `${f.title} — ${rec}`;
-  });
+  return (group.findings ?? []).map(acceptanceItemFromFinding);
+}
+
+/**
+ * Resolve the `edges[]` sequencing anchored on this group. Each edge whose
+ * `fromGroupKey` matches this group's key contributes its `toGroupKey`. Group
+ * keys are the only stable identifier available at emit time — issues are not
+ * numbered yet — so the relationship is preserved as machine-readable keys the
+ * operator can resolve.
+ *
+ * @param {object} group
+ * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} edges
+ * @returns {string[]}
+ */
+function sequencingDepsForGroup(group, edges) {
+  if (!Array.isArray(edges) || edges.length === 0) return [];
+  const deps = edges
+    .filter((e) => e && e.fromGroupKey === group.groupKey)
+    .map((e) => e.toGroupKey)
+    .filter((k) => typeof k === 'string' && k.length > 0);
+  return uniq(deps);
+}
+
+/**
+ * Render the carried-through `edges[]` sequencing as a dedicated extended
+ * markdown block. The canonical `depends_on[]` footer only round-trips `#N`
+ * issue refs (`blocked by #123`), which do not exist before the issues are
+ * opened; rendering the group-key sequencing as its own informational section
+ * keeps the signal in the body (not discarded — Story #4270) and survives
+ * `parse()` / `serialize()` round-tripping (it is preamble/extended content,
+ * not a structured section). Returns the empty string when there is no
+ * sequencing to surface.
+ *
+ * @param {string[]} deps
+ * @returns {string}
+ */
+function sequencingSection(deps) {
+  if (deps.length === 0) return '';
+  const lines = deps.map((k) => `- depends on group \`${k}\``);
+  return ['## Sequencing', '', lines.join('\n'), ''].join('\n');
 }
 
 function agentPromptsSection(group) {
-  const blocks = group.findings
+  const blocks = (group.findings ?? [])
     .filter(
       (f) => typeof f.agentPrompt === 'string' && f.agentPrompt.length > 0,
     )
@@ -65,7 +159,7 @@ function agentPromptsSection(group) {
 
 function contextLinksFromGroup(group) {
   const reports = uniq(
-    group.findings
+    (group.findings ?? [])
       .map((f) => f.sourceReport)
       .filter((s) => typeof s === 'string'),
   );
@@ -93,34 +187,47 @@ function labelsForGroup(group) {
 /**
  * @param {object} params
  * @param {object} params.group — output of `groupFindings` (one entry).
+ * @param {Array<{ fromGroupKey: string, toGroupKey: string }>} [params.edges]
+ *   — the dependency `edges[]` emitted by `groupFindings`. Edges anchored on
+ *   this group are carried through to `depends_on[]`; omit when no sequencing
+ *   is known.
  * @returns {{ title: string, body: string, labels: string[] }}
  */
-export function buildStoryBody({ group }) {
+export function buildStoryBody({ group, edges = [] }) {
   if (!group || !Array.isArray(group.findings)) {
     throw new Error('buildStoryBody: group with findings[] is required');
   }
   const title = group.title;
 
-  // Build the canonical StoryBody object from the audit group data.
+  // Build the canonical StoryBody object from the audit group data. The
+  // acceptance + verify arrays are populated so the body clears the
+  // inline-contract bar; changes[] carries the file footprint. The edges[]
+  // sequencing is carried through as an extended `## Sequencing` block (see
+  // sequencingSection) — group keys are not `#N` refs, so they cannot ride the
+  // canonical depends_on footer.
   const storyBody = {
     goal: goalFromGroup(group),
-    changes: [],
+    changes: changesFromGroup(group),
     acceptance: acceptanceCriteriaFromGroup(group),
-    verify: [],
+    verify: [...DEFAULT_VERIFY],
     references: [],
     wide: null,
+    reason_to_exist: null,
     depends_on: [],
     estimated_test_files: null,
   };
 
-  // Serialize via the canonical serializer.
+  // Serialize via the canonical serializer (no footer — depends_on is empty).
   const canonicalSections = serialize(storyBody);
+  const sequencing = sequencingSection(sequencingDepsForGroup(group, edges));
 
-  // Append audit-specific extended sections (agent prompts, context links,
-  // fingerprint footer) that are not part of the canonical shape.
+  // Append audit-specific extended sections (sequencing, agent prompts,
+  // context links, fingerprint footer) that are not part of the canonical
+  // shape.
   const body = [
     canonicalSections,
     '',
+    ...(sequencing ? [sequencing] : []),
     '## Agent Prompts',
     '',
     agentPromptsSection(group),

package/.agents/scripts/lib/cli-args.js

@@ -60,6 +60,8 @@ export function parseSprintArgs(args = process.argv) {
       'no-full-scope-crap': { type: 'boolean', default: false },
       executor: { type: 'string' },
       cwd: { type: 'string' },
+      prd: { type: 'string' },
+      'tech-spec': { type: 'string' },
       'recut-of': { type: 'string' },
       resume: { type: 'boolean', default: false },
       restart: { type: 'boolean', default: false },
@@ -86,6 +88,10 @@ export function parseSprintArgs(args = process.argv) {
       process.env.AGENT_WORKTREE_ROOT ||
       null,
     recutOf: parseTicketId(values['recut-of']),
+    // Story #4253: pre-resolved Epic linkages threaded by the /deliver
+    // fan-out so `story-init.js` can skip the per-Story `getEpic` round-trip.
+    prdId: parseTicketId(values.prd),
+    techSpecId: parseTicketId(values['tech-spec']),
     resume: values.resume ?? false,
     restart: values.restart ?? false,
     noEvidence: values['no-evidence'] ?? false,

package/.agents/scripts/lib/close-validation/runner.js

@@ -68,11 +68,18 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
  * `cwd` (the main checkout) because the per-Epic temp tree lives under
  * the main `.git/`. Failure messages name the worktree path.
  *
- * Evidence-aware: when both `storyId` and `epicId` are provided and
- * `useEvidence !== false`, each gate consults `validation-evidence
- * .shouldSkip()` against current HEAD + the gate's command-config hash. A
- * matching record skips the gate; a successful run is recorded so the
- * next caller in the local hot path can skip in turn.
+ * Evidence-aware: when `storyId` is provided alongside either `epicId` or
+ * `standalone: true`, and `useEvidence !== false`, each gate consults
+ * `validation-evidence.shouldSkip()` against current HEAD + the gate's
+ * command-config hash. A matching record skips the gate; a successful run
+ * is recorded so the next caller in the local hot path can skip in turn.
+ *
+ * Standalone keyspace (Story #4250): the standalone path has no parent
+ * Epic, so it passes `standalone: true` (and leaves `epicId` null) to route
+ * the evidence file to the storyId-anchored
+ * `<tempRoot>/standalone/stories/story-<id>/validation-evidence.json`
+ * keyspace instead of feeding a null `epicId` into the Epic-keyed path
+ * (which structurally disabled the cache before).
  *
  * `onGateStart` is invoked immediately before each gate's runner spawn.
  * story-close uses it to drive `phaseTimer.mark(...)` for per-gate
@@ -87,6 +94,7 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
  *   onGateStart?: (gate: Gate) => void,
  *   storyId?: number|null,
  *   epicId?: number|null,
+ *   standalone?: boolean,
  *   useEvidence?: boolean,
  *   evidenceClock?: () => number,
  *   getHeadSha?: (cwd: string) => string|null,
@@ -104,6 +112,7 @@ export async function runCloseValidation({
   onGateStart,
   storyId = null,
   epicId = null,
+  standalone = false,
   useEvidence = true,
   evidenceClock = () => Date.now(),
   getHeadSha = (resolvedCwd) => defaultGetHeadSha(resolvedCwd),
@@ -112,7 +121,15 @@ export async function runCloseValidation({
 } = {}) {
   const failed = [];
   const skipped = [];
-  const evidenceActive = useEvidence && storyId != null && epicId != null;
+  // Evidence is active when a Story id is present AND there is a keyspace to
+  // anchor on: either a real Epic id (Epic path) or `standalone: true`
+  // (Story #4250 — standalone storyId-anchored keyspace). A bare `epicId:
+  // null` without `standalone` keeps the cache off, as before.
+  const evidenceActive =
+    useEvidence && storyId != null && (epicId != null || standalone);
+  // The evidence-store opts: `standalone` routes to the storyId-anchored
+  // keyspace; otherwise the Epic-keyed path resolves under `epicId`.
+  const evidenceStoreOpts = { cwd, epicId, standalone };
   // Evidence keys against the main checkout's HEAD because the per-Epic
   // evidence file lives under the main `.git/`. Gate spawn, in contrast,
   // runs in the worktree when one is supplied — that's the whole point of
@@ -134,7 +151,7 @@ export async function runCloseValidation({
         configHash,
         inputFingerprint: gate.inputFingerprint ?? null,
       },
-      { cwd, epicId },
+      evidenceStoreOpts,
     );
     if (verdict.skip) {
       const tsHint = verdict.record?.timestamp
@@ -160,7 +177,7 @@ export async function runCloseValidation({
           durationMs,
           inputFingerprint: gate.inputFingerprint ?? null,
         },
-        { cwd, epicId },
+        evidenceStoreOpts,
       );
     } catch (err) {
       log(

package/.agents/scripts/lib/config/temp-paths.js

@@ -128,7 +128,7 @@ export function _clearMainCheckoutRootCache() {
  * @param {string} tempRoot
  * @returns {string}
  */
-function anchorTempRoot(tempRoot) {
+export function anchorTempRoot(tempRoot) {
   if (path.isAbsolute(tempRoot)) return tempRoot;
   const root = mainCheckoutRoot();
   return root ? path.join(root, tempRoot) : tempRoot;