mandrel 1.76.0 → 1.78.0

package/.agents/scripts/lib/story-body/story-body.js

@@ -15,6 +15,7 @@
  *   acceptance:          string[],         // observable criteria
  *   verify:              string[],         // exact commands / tier annotation
  *   references:          PathEntry[],      // read-only paths (optional)
+ *   non_goals:           string[],         // negative-scope bullets (optional, advisory)
  *   wide:                { reason } | null,// declared-wide footprint (optional)
  *   reason_to_exist:     string | null,    // one-sentence cohesion reason (optional)
  *   depends_on:          string[],         // blocker story slugs or #ids
@@ -69,6 +70,7 @@ import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js
  * @property {string[]}      acceptance          - Observable acceptance criteria.
  * @property {string[]}      verify              - Exact commands with tier annotation.
  * @property {PathEntry[]}   references          - Read-only paths (may be empty).
+ * @property {string[]}      non_goals           - Negative-scope bullets (advisory; may be empty).
  * @property {{ reason: string }|null} wide      - Declared-wide footprint (reason), or null.
  * @property {string|null}   reason_to_exist     - One-sentence cohesion reason ("why this Story exists"), or null.
  * @property {string[]}      depends_on          - Blocking story slugs / issue refs.
@@ -89,6 +91,7 @@ import { FILE_ASSUMPTION_VALUES } from '../orchestration/file-assumption-enum.js
  * @property {boolean} hasAcceptanceSection - Whether a `## Acceptance` section was found.
  * @property {boolean} hasVerifySection     - Whether a `## Verify` section was found.
  * @property {boolean} hasReferencesSection - Whether a `## References` section was found.
+ * @property {boolean} hasNonGoalsSection   - Whether a `## Non-Goals` section was found.
  * @property {boolean} isLegacyStringBody   - True when no structured sections were found.
  */
 
@@ -125,13 +128,16 @@ export class StoryBodyParseError extends Error {
 // Section heading map
 // ---------------------------------------------------------------------------
 
-// Heading text → body field name
+// Heading text → body field name. Keys are normalized: lower-cased with `-`
+// folded to `_` (see splitSections), so the hyphenated `## Non-Goals` heading
+// maps to the `non_goals` field.
 const HEADING_TO_FIELD = new Map([
   ['goal', 'goal'],
   ['changes', 'changes'],
   ['acceptance', 'acceptance'],
   ['verify', 'verify'],
   ['references', 'references'],
+  ['non_goals', 'non_goals'],
 ]);
 
 // ---------------------------------------------------------------------------
@@ -346,15 +352,53 @@ function splitSections(markdown) {
     // Forms (Story #4227) render every field label as a level-3 heading
     // (`### Goal`), not the level-2 the canonical serializer emits, so the
     // parser accepts both levels. Any other heading depth is ignored.
-    const headingMatch = line.match(/^#{2,3}\s+(\w+)\s*$/i);
-    if (headingMatch) {
-      const name = headingMatch[1].toLowerCase();
+    //
+    // The token class is `[\w-]+` (not bare `\w+`) so a single hyphenated
+    // heading word — the canonical `## Non-Goals` negative-scope section —
+    // matches as one token. The captured name is normalized (lower-cased,
+    // `-` folded to `_`) before the HEADING_TO_FIELD lookup, so `Non-Goals`
+    // resolves to the `non_goals` field. Multi-word headings that contain a
+    // space (`## Out of Scope`, `## Agent Prompts`) still do NOT match this
+    // single-token shape — they fall through to the catch-all heading branch
+    // below, which closes the open section. The chosen canonical spelling is
+    // therefore the hyphenated single token `## Non-Goals`.
+    const fieldHeadingMatch = line.match(/^#{2,3}\s+([\w-]+)\s*$/i);
+    if (fieldHeadingMatch) {
+      const name = fieldHeadingMatch[1].toLowerCase().replace(/-/g, '_');
       if (HEADING_TO_FIELD.has(name)) {
         inPreamble = false;
         currentSection = name;
         if (!sections.has(currentSection)) sections.set(currentSection, []);
         continue;
       }
+      // A heading that matches the canonical `## Word` shape but is not a
+      // recognized field name (e.g. a trailing free-form `## Notes`) closes
+      // the currently-open section. Without this reset, the unknown heading
+      // and its bullets bleed into the previously-recognized section,
+      // silently corrupting `verify[]` / `acceptance[]`. We do NOT re-enter
+      // the preamble (`inPreamble` stays false), so a later recognized
+      // heading still registers normally; we only stop appending to the
+      // closed section. The heading line and its body are dropped from all
+      // sections. (Multi-word free-form headings like `## Out of Scope` —
+      // with internal spaces — do not match the `[\w-]+` single-token shape
+      // and reach this branch too. The hyphenated single-token canonical
+      // negative-scope heading is `## Non-Goals`, which IS recognized above.)
+      currentSection = null;
+      continue;
+    }
+
+    // Any other markdown heading (`## …` / `### …`, single- or multi-word)
+    // that is NOT a canonical field heading TERMINATES the current structured
+    // section. Trailing extended content a producer appends after the
+    // canonical block — `audit-to-stories`'s `## Agent Prompts` / `## Context`
+    // / `## Sequencing` blocks, for instance — must not bleed into the last
+    // structured section's bullet list (Story #4270). Without this, those
+    // lines were silently absorbed into `verify[]` / `acceptance[]`. The
+    // heading and everything under it is dropped from structured parsing
+    // (it is extended, non-canonical markdown).
+    if (!inPreamble && /^#{1,6}\s+\S/.test(line)) {
+      currentSection = null;
+      continue;
     }
 
     // The trailing `<!-- meta: {...} -->` block is machine metadata, not
@@ -407,6 +451,7 @@ function parseLegacyStringBody(input, preamble, footer) {
     acceptance: [],
     verify: [],
     references: [],
+    non_goals: [],
     wide: null,
     reason_to_exist: null,
     depends_on: extractBlockedBy(footer),
@@ -421,6 +466,7 @@ function parseLegacyStringBody(input, preamble, footer) {
       hasAcceptanceSection: false,
       hasVerifySection: false,
       hasReferencesSection: false,
+      hasNonGoalsSection: false,
       isLegacyStringBody: true,
     },
   };
@@ -522,6 +568,7 @@ export function parse(input) {
   const hasAcceptanceSection = sections.has('acceptance');
   const hasVerifySection = sections.has('verify');
   const hasReferencesSection = sections.has('references');
+  const hasNonGoalsSection = sections.has('non_goals');
 
   // If no structured sections found, treat as legacy string body.
   const isLegacyStringBody =
@@ -545,6 +592,7 @@ export function parse(input) {
     sections.get('references') ?? [],
     warnings,
   );
+  const non_goals = parseTextListSection(sections.get('non_goals') ?? []);
   const dependsOn = extractBlockedBy(footer);
 
   // --- Recover wide / estimated_test_files from the meta block ---
@@ -566,6 +614,7 @@ export function parse(input) {
     acceptance,
     verify,
     references,
+    non_goals,
     wide,
     reason_to_exist,
     depends_on: dependsOn,
@@ -581,6 +630,7 @@ export function parse(input) {
       hasAcceptanceSection,
       hasVerifySection,
       hasReferencesSection,
+      hasNonGoalsSection,
       isLegacyStringBody: false,
     },
   };
@@ -625,6 +675,11 @@ function parseStructuredObject(obj) {
     if (entry !== null) references.push(entry);
   }
 
+  // non_goals (advisory negative-scope bullets)
+  const non_goals = Array.isArray(obj.non_goals)
+    ? obj.non_goals.filter((n) => typeof n === 'string' && n.trim().length > 0)
+    : [];
+
   const wide = normalizeWide(obj.wide);
   const reason_to_exist = normalizeReasonToExist(obj.reason_to_exist);
 
@@ -650,6 +705,7 @@ function parseStructuredObject(obj) {
     acceptance,
     verify,
     references,
+    non_goals,
     wide,
     reason_to_exist,
     depends_on,
@@ -665,6 +721,7 @@ function parseStructuredObject(obj) {
       hasAcceptanceSection: 'acceptance' in obj,
       hasVerifySection: 'verify' in obj,
       hasReferencesSection: 'references' in obj,
+      hasNonGoalsSection: 'non_goals' in obj,
       isLegacyStringBody: false,
     },
   };
@@ -689,7 +746,7 @@ function serializePathEntry(entry) {
 /**
  * Descriptor table for the human-readable Story-body sections, in canonical
  * emit order (`## Goal`, `## Changes`, `## Acceptance`, `## Verify`,
- * `## References`). Each descriptor reads one body field and returns the
+ * `## References`, `## Non-Goals`). Each descriptor reads one body field and returns the
  * section's markdown block when the field is present and non-empty, or `null`
  * to omit the section.
  *
@@ -735,6 +792,18 @@ const SERIALIZE_SECTIONS = [
         ? `## References\n${references.map((r) => `- ${serializePathEntry(r)}`).join('\n')}`
         : null,
   },
+  {
+    // Advisory negative-scope bullets. Rendered as the hyphenated canonical
+    // `## Non-Goals` heading (the spelling the parser's widened
+    // `[\w-]+` field-heading regex recognizes). Render-when-non-empty: an
+    // empty or absent `non_goals` emits nothing, so every pre-existing body
+    // round-trips byte-identically.
+    field: 'non_goals',
+    render: (nonGoals) =>
+      Array.isArray(nonGoals) && nonGoals.length > 0
+        ? `## Non-Goals\n${nonGoals.map((n) => `- ${n}`).join('\n')}`
+        : null,
+  },
 ];
 
 /**
@@ -793,8 +862,8 @@ function serializeFooter(body, opts) {
  * format written to GitHub issue bodies.
  *
  * The output matches the section order the spec-renderer uses:
- * `## Goal`, `## Changes`, `## Acceptance`, `## Verify`, `## References`
- * (omitted when empty).
+ * `## Goal`, `## Changes`, `## Acceptance`, `## Verify`, `## References`,
+ * `## Non-Goals` (each omitted when empty).
  *
  * `wide`, `reason_to_exist`, and `estimated_test_files` are emitted as a
  * fenced `<!-- meta -->` comment block so round-trips preserve them without

package/.agents/scripts/lib/story-init/branch-initializer.js

@@ -27,6 +27,7 @@ import {
   classifyBranchSeed,
   ensureEpicBranch,
   ensureEpicBranchRef,
+  seedStoryBranchRef,
 } from '../git-branch-lifecycle.js';
 import { gitSpawn } from '../git-utils.js';
 import { Logger } from '../Logger.js';
@@ -186,7 +187,10 @@ export function ensureStoryBranchSeed({
   progress = defaultProgress(),
   git,
 }) {
-  const spawn = git?.spawn ?? ((...args) => gitSpawn(mainCwd, ...args));
+  const spawn =
+    git?.spawn != null
+      ? (args) => git.spawn(...args)
+      : (args) => gitSpawn(mainCwd, ...args);
   const existsLocally =
     git?.existsLocally ?? ((b) => branchExistsLocally(b, mainCwd));
   // `ensureStoryBranchSeed` is always called after `fetchMainRefs` in
@@ -195,49 +199,31 @@ export function ensureStoryBranchSeed({
   const existsRemotely =
     git?.existsRemotely ?? ((b) => branchExistsViaTrackingRef(b, mainCwd));
 
-  const action = planStoryBranchSeed({
-    localHas: existsLocally(storyBranch),
-    remoteHas: existsRemotely(storyBranch),
+  // The seed-action switch shell is single-homed in `seedStoryBranchRef`
+  // (Story #4255). The Epic path runs under concurrent wave dispatch, so it
+  // opts into `swallowCreateRace: true` to treat a lost probe→create race
+  // (`git branch` exits "already exists") as reuse (Story #3482) — the ref
+  // exists, which is exactly the post-condition this function guarantees.
+  // No `fetchError` is supplied: the fetch exit status is intentionally not
+  // inspected here (the worktree bootstrap re-checks the ref downstream).
+  seedStoryBranchRef({
+    storyBranch,
+    baseRef: epicBranch,
+    swallowCreateRace: true,
+    spawn,
+    existsLocally,
+    existsRemotely,
+    progress,
+    messages: {
+      reuse: (b) => `Reusing existing story branch ref: ${b} (no re-seed)`,
+      fetch: (b) => `Fetching remote story branch: ${b}`,
+      create: (b, ref) => `Creating story branch ref: ${b} from ${ref}`,
+      createRace: (b) =>
+        `Story branch ref ${b} already exists (created concurrently) — reusing.`,
+      createError: (b, ref, stderr) =>
+        `ensureStoryBranchSeed: failed to create ${b} from ${ref}: ${stderr}`,
+    },
   });
-  if (action === 'none') {
-    // Story #3482 — a pre-existing `story-<id>` ref is reuse, not an error.
-    // The worktree bootstrap below seeds onto whatever the ref already points
-    // at (resuming a partially-implemented Story), so seeding is a no-op here.
-    progress(
-      'GIT',
-      `Reusing existing story branch ref: ${storyBranch} (no re-seed)`,
-    );
-    return;
-  }
-  if (action === 'fetch') {
-    progress('GIT', `Fetching remote story branch: ${storyBranch}`);
-    spawn('fetch', 'origin', `${storyBranch}:${storyBranch}`);
-    return;
-  }
-  progress(
-    'GIT',
-    `Creating story branch ref: ${storyBranch} from ${epicBranch}`,
-  );
-  const res = spawn('branch', storyBranch, epicBranch);
-  // Story #3482 — close the probe→create race: another concurrent
-  // dispatch (or a prior interrupted run) may have created the ref between
-  // our existence probe above and this `git branch` call. `git branch`
-  // exits non-zero with "already exists" in that window. Treat it as reuse
-  // rather than letting story-init abort — the ref exists, which is exactly
-  // the post-condition this function guarantees.
-  if (res.status !== 0) {
-    const stderr = res.stderr || res.stdout || '';
-    if (/already exists/i.test(stderr)) {
-      progress(
-        'GIT',
-        `Story branch ref ${storyBranch} already exists (created concurrently) — reusing.`,
-      );
-      return;
-    }
-    throw new Error(
-      `ensureStoryBranchSeed: failed to create ${storyBranch} from ${epicBranch}: ${stderr}`,
-    );
-  }
 }
 
 function verifyWorkspaceSafe({

package/.agents/scripts/lib/story-init/hierarchy-tracer.js

@@ -2,10 +2,19 @@ import { Logger } from '../Logger.js';
 /**
  * hierarchy-tracer.js — Stage 2 of the story-init pipeline.
  *
- * Given an epicId, resolves the linked PRD and Tech Spec issue IDs by
- * fetching the Epic. Fetch failures are logged but non-fatal — the result
- * simply reports `null` for whichever linkage could not be resolved, which
- * mirrors legacy behaviour in story-init.js.
+ * Resolves the linked PRD and Tech Spec issue IDs for a Story's parent Epic.
+ *
+ * Story #4253: when both `prdId` and `techSpecId` are supplied as input
+ * (the `/deliver` fan-out resolves the immutable Epic once at the top of the
+ * run and threads the two ids down via `story-init.js --prd/--tech-spec`),
+ * this stage short-circuits and does NOT call `provider.getEpic`. The Epic
+ * issue is invariant for the lifetime of a delivery run, so the N per-Story
+ * `getEpic` round-trips collapse to one parent-side resolution.
+ *
+ * When the flags are absent (interactive / single-story use), the legacy
+ * `getEpic` resolution runs unchanged. Fetch failures are logged but
+ * non-fatal — the result simply reports `null` for whichever linkage could
+ * not be resolved, preserving the graceful degradation on a missing Epic.
  */
 
 /**
@@ -14,12 +23,24 @@ import { Logger } from '../Logger.js';
  * @param {object} [deps.logger]
  * @param {object} deps.input
  * @param {number} deps.input.epicId
+ * @param {number|null} [deps.input.prdId] Pre-resolved PRD id (from --prd).
+ * @param {number|null} [deps.input.techSpecId] Pre-resolved Tech Spec id
+ *   (from --tech-spec). When both `prdId` and `techSpecId` are supplied,
+ *   `getEpic` is skipped.
  * @returns {Promise<{ prdId: number|null, techSpecId: number|null }>}
  */
 export async function traceHierarchy({ provider, logger, input }) {
   const { epicId } = input;
   const warn = logger?.warn ?? ((msg) => Logger.error(msg));
 
+  // Short-circuit: the parent already resolved both linkages once and threaded
+  // them in, so there is nothing left to fetch. Skip the per-Story getEpic.
+  const suppliedPrdId = input.prdId ?? null;
+  const suppliedTechSpecId = input.techSpecId ?? null;
+  if (suppliedPrdId !== null && suppliedTechSpecId !== null) {
+    return { prdId: suppliedPrdId, techSpecId: suppliedTechSpecId };
+  }
+
   let prdId = null;
   let techSpecId = null;
   try {

package/.agents/scripts/lib/story-init/task-graph-builder.js

@@ -82,22 +82,32 @@ export async function buildTaskGraph({ provider, logger, input }) {
   const warn = logger?.warn ?? ((msg) => Logger.error(msg));
   const progress = logger?.progress ?? (() => {});
 
+  // Story #4251 — under the 2-tier hierarchy every Story is childless, so the
+  // `fetchChildTickets` call (a `getTicket` + empty sub-issues GraphQL query +
+  // a never-matching `/search/issues` fallback) is pure waste on every
+  // story-init. The Story body is already in scope, so detect the inline-
+  // acceptance 2-tier shape FIRST and short-circuit without any child fetch —
+  // sparing the most aggressively rate-limited GitHub endpoint exactly during
+  // wide wave fan-out. A body lacking inline acceptance still falls through to
+  // the legacy child-enumeration path below.
+  if (hasInlineAcceptance(storyBody)) {
+    progress(
+      'TASKS',
+      `Story #${storyId} has inline acceptance — no child Tasks expected (2-tier shape).`,
+    );
+    return { sortedTasks: [], mode: '2-tier' };
+  }
+
+  // Legacy / 4-tier fall-through: a body lacking inline acceptance still
+  // enumerates child Tasks for the topological sort below.
   const tasks = await fetchChildTickets(provider, storyId);
 
-  const inlineAcceptance = hasInlineAcceptance(storyBody);
-  const mode = tasks.length === 0 && inlineAcceptance ? '2-tier' : '4-tier';
+  const mode = '4-tier';
 
   if (tasks.length === 0) {
-    if (inlineAcceptance) {
-      progress(
-        'TASKS',
-        `Story #${storyId} has inline acceptance — no child Tasks expected (2-tier shape).`,
-      );
-    } else {
-      warn(
-        `[story-init] Warning: Story #${storyId} has no child Tasks. The agent will need to work from the Story body directly.`,
-      );
-    }
+    warn(
+      `[story-init] Warning: Story #${storyId} has no child Tasks. The agent will need to work from the Story body directly.`,
+    );
   }
 
   const sortedTasks = sortTasksByDependencies(tasks);

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -1,5 +1,6 @@
 import { LIMITS_DEFAULTS } from '../config/limits.js';
 import {
+  AUTHORING_ALTITUDE_GUIDANCE,
   DEFAULT_TASK_SIZING,
   DELIVERABLE_GRANULARITY_GUIDANCE,
 } from '../orchestration/ticket-validator-sizing.js';
@@ -56,6 +57,15 @@ function render2TierPrompt({ maxTickets, maxTokenBudget }) {
   // cannot drift (Story #3777).
   const { definition: granularityDefinition, singleConsumerRule } =
     DELIVERABLE_GRANULARITY_GUIDANCE;
+  // The binding-vs-advisory authoring altitude + the New-File Contract are
+  // sourced from the single AUTHORING_ALTITUDE_GUIDANCE constant
+  // (ticket-validator-sizing.js) so the prompt and the authoring SKILL cannot
+  // drift (Story #4272).
+  const {
+    altitude: authoringAltitude,
+    advisoryCaveat,
+    newFileContract,
+  } = AUTHORING_ALTITUDE_GUIDANCE;
   return `You are an expert Senior Project Manager and Orchestrator.
 Your job is to take a Product Requirements Document (PRD) and a Technical Specification and decompose them into a flat list of Story tickets for an AI Agent to execute.
 
@@ -114,6 +124,10 @@ The serialized \`body\` string renders these markdown sections (in order):
     - {"path": "<read-only dependency path>", "assumption": "exists"}
     - ...
 
+    ## Non-Goals
+    - <a capability or change this Story explicitly does NOT deliver>
+    - ...
+
 #### STORY BODY RULES:
 
 - **goal** (in body string): One sentence stating WHY this story exists within the Epic.
@@ -122,6 +136,15 @@ The serialized \`body\` string renders these markdown sections (in order):
 - **verify** (top-level array on the ticket object): Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
 - **reason to exist** (REQUIRED, encoded as the \`reason_to_exist\` field of the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): One sentence stating the single coherent reason this Story exists, distinct from its 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**) and the \`epic-plan-consolidate\` critic flags any Story whose body carries no non-empty reason to exist. Encode it as \`<!-- meta: {"reason_to_exist": "..."} -->\`.
 - **estimated_test_files** (optional, encoded in the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
+- **non_goals** (OPTIONAL, in body string as the \`## Non-Goals\` section): A short list of capabilities or changes this Story explicitly does NOT deliver — an advisory negative-scope bound that fences the executing agent away from adjacent work. It is **advisory and NON-GATING**: the validator does not require, count, or reject on it, and an absent or empty section renders nothing. Use the EXACT single-word hyphenated heading spelling \`## Non-Goals\` (a space-separated heading like \`## Out of Scope\` is NOT recognized by the parser and will be dropped). Reach for it when a Story's negative boundary is non-obvious from its \`acceptance[]\` alone; omit it otherwise.
+
+#### AUTHORING ALTITUDE — BINDING ACCEPTANCE vs ADVISORY CHANGES:
+
+${authoringAltitude}
+
+${newFileContract}
+
+${advisoryCaveat}
 
 #### STORY SIZING — COHESION FIRST (the numeric ceiling is only a backstop):
 

package/.agents/scripts/lib/validation-evidence.js

@@ -103,25 +103,34 @@ function requirePositiveInt(value, label) {
  *   - `scopeId === epicId` → `<tempRoot>/epic-<epicId>/validation-evidence.json`
  *   - `scopeId !== epicId` → treated as a Story id → `<tempRoot>/epic-<epicId>/story-<scopeId>/validation-evidence.json`
  *
- * `epicId` is required. The legacy flat
- * `temp/validation-evidence-<scopeId>.json` layout is no longer supported —
- * callers must thread the Epic id through (Epic #1030 follow-up to Story
- * #1054). The synthetic config bag passed to `epicTempDir` keeps the
- * resolver from doing a disk-bound `.agentrc.json` lookup; bare callers can
- * pass `tempDir` via `opts` to override the default `'temp'`.
+ * **Standalone keyspace (Story #4250).** When `opts.standalone === true`,
+ * the Story has no parent Epic, so the evidence file is anchored on the
+ * Story id alone at
+ * `<tempRoot>/standalone/stories/story-<scopeId>/validation-evidence.json`
+ * (the `storyTempDir(null, sid)` layout from Story #2874). In this mode
+ * `epicId` is ignored — callers MUST NOT feed a `0`/`null` epicId into the
+ * Epic-keyed branch (the historical bug this keyspace replaces). Outside
+ * standalone mode `epicId` remains required.
+ *
+ * The legacy flat `temp/validation-evidence-<scopeId>.json` layout is no
+ * longer supported — Epic-scoped callers must thread the Epic id through
+ * (Epic #1030 follow-up to Story #1054). The synthetic config bag passed to
+ * `epicTempDir` / `storyTempDir` keeps the resolver from doing a disk-bound
+ * `.agentrc.json` lookup; bare callers can pass `tempDir` via `opts` to
+ * override the default `'temp'`.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId: number|string }} opts
+ * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean }} opts
  * @returns {string}
  */
 export function evidencePath(scopeId, opts = {}) {
-  if (opts.epicId == null) {
+  const standalone = opts.standalone === true;
+  if (!standalone && opts.epicId == null) {
     throw new Error(
-      '[validation-evidence] evidencePath requires opts.epicId (Epic-scoped path resolution).',
+      '[validation-evidence] evidencePath requires opts.epicId (Epic-scoped path resolution) unless opts.standalone is set.',
     );
   }
   const { cwd, tempDir } = resolveOpts(opts);
-  const epicId = requirePositiveInt(opts.epicId, 'epicId');
   const scope = requirePositiveInt(scopeId, 'scopeId');
   // Bind the temp tree to the explicit `cwd` (Story #3900): pre-absolutise
   // the tempRoot under `cwd` and pass it through the canonical
@@ -134,10 +143,18 @@ export function evidencePath(scopeId, opts = {}) {
     ? tempDir
     : path.join(cwd, tempDir);
   const configBag = { project: { paths: { tempRoot: absTempRoot } } };
-  const dir =
-    scope === epicId
-      ? epicTempDir(epicId, configBag)
-      : storyTempDir(epicId, scope, configBag);
+  let dir;
+  if (standalone) {
+    // Story #4250 — storyId-anchored standalone keyspace. `null` is the
+    // standalone-story sentinel `storyTempDir` accepts (Story #2874).
+    dir = storyTempDir(null, scope, configBag);
+  } else {
+    const epicId = requirePositiveInt(opts.epicId, 'epicId');
+    dir =
+      scope === epicId
+        ? epicTempDir(epicId, configBag)
+        : storyTempDir(epicId, scope, configBag);
+  }
   return path.join(dir, EVIDENCE_FILENAME);
 }
 
@@ -172,15 +189,21 @@ function emptyDoc(scopeId) {
  * cross-scopeId cases — callers don't have to branch on those failure
  * modes; they manifest as `shouldSkip()` returning `skip: false`.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved.
+ * `opts.epicId` is required so the per-Epic-tree path can be resolved,
+ * unless `opts.standalone === true` (Story #4250) routes to the
+ * storyId-anchored standalone keyspace.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId: number|string, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
  * @returns {{ storyId: number, schemaVersion: number, records: object[] }}
  */
 export function loadEvidence(scopeId, opts = {}) {
   const resolved = resolveOpts(opts);
-  const file = evidencePath(scopeId, { ...resolved, epicId: opts.epicId });
+  const file = evidencePath(scopeId, {
+    ...resolved,
+    epicId: opts.epicId,
+    standalone: opts.standalone,
+  });
   if (!resolved.fs.existsSync(file)) return emptyDoc(scopeId);
   let parsed;
   try {
@@ -200,7 +223,9 @@ export function loadEvidence(scopeId, opts = {}) {
  * Validates the resulting document against the schema before writing — a
  * malformed write throws so the bug surfaces immediately.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved.
+ * `opts.epicId` is required so the per-Epic-tree path can be resolved,
+ * unless `opts.standalone === true` (Story #4250) routes to the
+ * storyId-anchored standalone keyspace.
  *
  * @param {{
  *   storyId: number|string,
@@ -210,7 +235,7 @@ export function loadEvidence(scopeId, opts = {}) {
  *   exitCode?: number,
  *   durationMs?: number|null,
  * }} input
- * @param {{ cwd?: string, tempDir?: string, epicId: number|string, fs?: object, now?: Function }} opts
+ * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object, now?: Function }} opts
  * @returns {object} The persisted record.
  */
 export function recordPass(
@@ -231,7 +256,11 @@ export function recordPass(
     );
   }
   const resolved = resolveOpts(opts);
-  const evidenceOpts = { ...resolved, epicId: opts.epicId };
+  const evidenceOpts = {
+    ...resolved,
+    epicId: opts.epicId,
+    standalone: opts.standalone,
+  };
   const doc = loadEvidence(storyId, evidenceOpts);
   const record = {
     gateName,
@@ -268,10 +297,13 @@ export function recordPass(
  * with a machine-readable `reason` so callers can log why the skip didn't
  * fire.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved.
+ * `opts.epicId` is required so the per-Epic-tree path can be resolved,
+ * unless `opts.standalone === true` (Story #4250) routes to the
+ * storyId-anchored standalone keyspace. `opts` is forwarded verbatim to
+ * `loadEvidence`, so `standalone` flows through unchanged.
  *
  * @param {{ storyId: number|string, gateName: string, currentSha: string, configHash: string }} input
- * @param {{ cwd?: string, tempDir?: string, epicId: number|string, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
  * @returns {{ skip: boolean, reason: string, record?: object }}
  */
 export function shouldSkip(
@@ -308,15 +340,21 @@ export function shouldSkip(
  * start of each Story so a re-run always starts clean. Idempotent —
  * absent file is not an error.
  *
- * `opts.epicId` is required so the per-Epic-tree path can be resolved.
+ * `opts.epicId` is required so the per-Epic-tree path can be resolved,
+ * unless `opts.standalone === true` (Story #4250) routes to the
+ * storyId-anchored standalone keyspace.
  *
  * @param {number|string} scopeId
- * @param {{ cwd?: string, tempDir?: string, epicId: number|string, fs?: object }} opts
+ * @param {{ cwd?: string, tempDir?: string, epicId?: number|string|null, standalone?: boolean, fs?: object }} opts
  * @returns {{ cleared: boolean, path: string }}
  */
 export function forceClear(scopeId, opts = {}) {
   const resolved = resolveOpts(opts);
-  const file = evidencePath(scopeId, { ...resolved, epicId: opts.epicId });
+  const file = evidencePath(scopeId, {
+    ...resolved,
+    epicId: opts.epicId,
+    standalone: opts.standalone,
+  });
   if (!resolved.fs.existsSync(file)) return { cleared: false, path: file };
   resolved.fs.unlinkSync(file);
   return { cleared: true, path: file };