mandrel 1.76.0 → 1.77.0

package/.agents/scripts/lib/orchestration/ticket-validator-sizing.js

@@ -30,6 +30,62 @@
  *     decomposer prompt and authoring SKILL.
  */
 
+import { parse as parseStoryBody } from '../story-body/story-body.js';
+
+/**
+ * Normalize a Story's `body` to the structured object the sizing layers
+ * score, mirroring `validateAcFreshness` / `collectStoryAssumptionEntries`
+ * (Story #3302) and `resolveStructuredBody` in `task-body-validator.js`.
+ *
+ * The decomposer emits `body` as the canonical serialized **string**
+ * (`decomposer-prompts.js`), but the sizing layers historically read
+ * `story.body` only when it was already an object — so on the production
+ * string shape `changes` / `wide` fell through to empty and the `hardFiles`
+ * / unanchored-constant backstops emitted nothing. A defensive parse here
+ * restores parity:
+ *   - **string body** → parsed via `parseStoryBody`; an unparseable string
+ *     yields `null` (the gate degrades to "no structured signal", never
+ *     throws mid-validation).
+ *   - **object body** → returned verbatim (a caller may pass the
+ *     pre-serialize shape directly; `parse` round-trips it).
+ *   - **null / other** → `null`.
+ *
+ * @param {object} story
+ * @returns {object|null}
+ */
+function resolveStoryBody(story) {
+  const body = story?.body;
+  if (typeof body === 'string') {
+    if (body.trim().length === 0) return null;
+    try {
+      return parseStoryBody(body).body;
+    } catch {
+      return null;
+    }
+  }
+  if (body !== null && typeof body === 'object') return body;
+  return null;
+}
+
+/**
+ * Resolve the acceptance-criteria array for a Story, preferring the
+ * authoritative top-level `story.acceptance` (the binding contract the
+ * validator already requires every Story to carry inline) over the
+ * structured body's `acceptance`. Reading the top-level array makes the
+ * acceptance ceiling correct regardless of body shape — a string body whose
+ * structured `acceptance` is only reachable after a parse, or an object body
+ * (Story #4271). Falls back to `resolveStoryBody(story).acceptance` only when
+ * the top-level array is absent.
+ *
+ * @param {object} story
+ * @returns {unknown[]}
+ */
+function resolveAcceptance(story) {
+  if (Array.isArray(story?.acceptance)) return story.acceptance;
+  const body = resolveStoryBody(story);
+  return Array.isArray(body?.acceptance) ? body.acceptance : [];
+}
+
 export const DEFAULT_TASK_SIZING = Object.freeze({
   // Typical-Story warning thresholds (soft — emit advisory findings).
   // Story #4162 raised `softFiles` 8 → 15: a capability-sized Story routinely
@@ -71,6 +127,39 @@ export const DELIVERABLE_GRANULARITY_GUIDANCE = Object.freeze({
     '**Single-consumer merge rule.** A Story whose only consumer is one sibling Story should be **merged into that sibling** rather than emitted separately — a single-consumer downstream slice is not its own unit of work.',
 });
 
+/**
+ * `AUTHORING_ALTITUDE_GUIDANCE` is the **single source of truth** for the
+ * binding-vs-advisory authoring altitude (Epic #4131 F8) and the New-File
+ * Contract (Story #4272). It is stated ONCE here and consumed by BOTH the
+ * decomposer prompt template
+ * (`.agents/scripts/lib/templates/decomposer-prompts.js`, which interpolates
+ * the strings verbatim into the rendered system prompt) AND the authoring
+ * SKILL (`.agents/skills/core/epic-plan-decompose-author/SKILL.md`, whose
+ * prose mirrors these sentences). The SKILL cannot import JS, so the
+ * `ticket-decomposer` prompt test asserts the canonical phrasing on both
+ * surfaces — a divergent restatement fails that gate. This reuses the #3777
+ * single-source mechanism (one constant, two surfaces, drift-gated by tests).
+ *
+ * The altitude: `acceptance[]` / `verify[]` are the **binding contract** (the
+ * sole definition of "done"); `changes[]` / `references[]` are an **advisory
+ * implementation sketch** the executor MAY revise. Author acceptance to assert
+ * the **outcome** independent of file layout — never pin an incidental helper
+ * name or private path into an acceptance item. The advisory sketch is still
+ * validated (base-branch probes, New-File Contract) and never licenses
+ * skipping `acceptance[]` / `verify[]` or any `rules/security-baseline.md` MUST.
+ */
+export const AUTHORING_ALTITUDE_GUIDANCE = Object.freeze({
+  // The binding-vs-advisory altitude statement.
+  altitude:
+    '**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.',
+  // The advisory-does-not-mean-unvalidated caveat.
+  advisoryCaveat:
+    "**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.",
+  // The New-File Contract.
+  newFileContract:
+    '**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.',
+});
+
 /**
  * Configuration-constant phrase patterns the `unanchored-constant` heuristic
  * scans Story acceptance criteria for. Each entry matches the *kind* of
@@ -143,8 +232,11 @@ function makeUnanchoredConstant(slug, criterion) {
  */
 function computeUnanchoredConstantFindings(story) {
   const out = [];
-  const body = story.body && typeof story.body === 'object' ? story.body : null;
-  const acceptance = Array.isArray(body?.acceptance) ? body.acceptance : [];
+  // Read the authoritative top-level `story.acceptance` (the binding
+  // contract), falling back to the structured body's acceptance only when the
+  // top-level array is absent. This is correct regardless of body shape —
+  // string or object (Story #4271).
+  const acceptance = resolveAcceptance(story);
   for (const item of acceptance) {
     const criterion = String(item ?? '');
     if (CONCRETE_VALUE_RE.test(criterion)) continue;
@@ -158,6 +250,47 @@ function computeUnanchoredConstantFindings(story) {
   return out;
 }
 
+/**
+ * Soft, advisory `missing-reason-to-exist` finding (Story #4273). Surfaces a
+ * Story whose body carries no non-empty `reason_to_exist` — the
+ * machine-checkable form of the cohesion rule (**one Story = one coherent
+ * change with one reason to exist**). `reason_to_exist` is marked REQUIRED by
+ * the decomposer prompt and is the field the `epic-plan-consolidate` critic
+ * gates on, but that critic is an honor-system LLM check with no runtime
+ * backstop. This deterministic finding is the cheap backstop.
+ *
+ * Severity is `soft` (not a hard reject) so existing `reason_to_exist`-less
+ * standalone / audit Stories are surfaced as an advisory nudge rather than
+ * blocked — matching the `unanchored-constant` finding's advisory contract.
+ */
+function makeMissingReasonToExist(slug) {
+  return {
+    kind: 'missing-reason-to-exist',
+    severity: 'soft',
+    ticketSlug: slug,
+    message:
+      'Story body carries no non-empty `reason_to_exist`. State the single coherent reason this Story exists in one sentence (the machine-checkable form of "one Story = one coherent change with one reason to exist"), encoded as the `reason_to_exist` field of the body meta comment.',
+  };
+}
+
+/**
+ * Emit a soft `missing-reason-to-exist` finding when the Story body resolves
+ * to no non-empty `reason_to_exist`. The body parser
+ * (`story-body/story-body.js`) already normalizes `reason_to_exist` to a
+ * non-empty trimmed string or `null`, so reading `body.reason_to_exist` after
+ * `resolveStoryBody` is correct regardless of body shape — a serialized
+ * **string** body (the production decomposer shape) or an object body
+ * (Story #4271). A body that fails to parse resolves to `null` and trips the
+ * finding, which is the right advisory signal: the author should re-emit a
+ * parseable body carrying the field. One finding per Story.
+ */
+function computeMissingReasonToExistFinding(story) {
+  const body = resolveStoryBody(story);
+  const reason = body?.reason_to_exist;
+  const hasReason = typeof reason === 'string' && reason.trim().length > 0;
+  return hasReason ? [] : [makeMissingReasonToExist(story.slug)];
+}
+
 /**
  * Returns true when a `changes[]` entry is a glob pattern. Handles both the
  * canonical PathEntry object form `{ path, assumption }` and legacy strings.
@@ -253,8 +386,12 @@ function isDeclaredWide(wide) {
  */
 function computeStorySizingFindings(story, sizing) {
   const out = [];
-  const body = story.body && typeof story.body === 'object' ? story.body : null;
-  const acceptance = Array.isArray(body?.acceptance) ? body.acceptance : [];
+  // Story #4271: normalize the body so the canonical serialized **string**
+  // shape the decomposer emits is scored at parity with the pre-serialize
+  // object shape. The acceptance ceiling reads the authoritative top-level
+  // `story.acceptance` (the binding contract), not `body.acceptance`.
+  const body = resolveStoryBody(story);
+  const acceptance = resolveAcceptance(story);
   const changes = Array.isArray(body?.changes) ? body.changes : [];
   const declaredWide = isDeclaredWide(body?.wide ?? null);
 
@@ -263,6 +400,13 @@ function computeStorySizingFindings(story, sizing) {
   // the numeric sizing layers below — purely an authoring nudge.
   out.push(...computeUnanchoredConstantFindings(story));
 
+  // Soft, advisory: flag a Story body that carries no non-empty
+  // `reason_to_exist` (Story #4273). The decomposer prompt marks the field
+  // REQUIRED and the consolidate critic gates on it, but that critic has no
+  // runtime backstop — this deterministic finding is the cheap backstop.
+  // Independent of the numeric sizing layers below.
+  out.push(...computeMissingReasonToExistFinding(story));
+
   // Acceptance ceiling + soft warn.
   if (acceptance.length > sizing.maxAcceptance) {
     out.push(

package/.agents/scripts/lib/orchestration/ticketing/transition.js

@@ -179,6 +179,7 @@ async function syncProjectStatusColumn(
   ticketId,
   newState,
   _makeColumnSync,
+  config,
 ) {
   try {
     let sync;
@@ -191,10 +192,15 @@ async function syncProjectStatusColumn(
       // The instance's `_meta` cache survives across label transitions
       // so the invariant project metadata (projectId, fieldId, options)
       // is only fetched once per process run. Story #3661.
+      //
+      // Story #4252 — `config` is threaded so the on-disk board-metadata
+      // cache lands under the project's configured tempRoot. It is read at
+      // construction only; the registry caches the first instance per
+      // provider, so a later transition's config is intentionally ignored.
       if (!_columnSyncRegistry.has(provider)) {
         _columnSyncRegistry.set(
           provider,
-          new ColumnSync({ provider, logger: Logger }),
+          new ColumnSync({ provider, logger: Logger, config }),
         );
       }
       sync = _columnSyncRegistry.get(provider);
@@ -363,6 +369,7 @@ export async function transitionTicketState(
     ticketId,
     newState,
     opts._makeColumnSync,
+    opts.config,
   );
 
   // Automatically trigger upward cascade on every transition (Story

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);