mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/{epic-plan-spec/phases → planning}/authoring-context.js

@@ -2,7 +2,7 @@
  * phases/authoring-context.js — emit-context phase.
  *
  * Builds the authoring context the host LLM (or the
- * `epic-plan-spec-author` Skill) needs to write the Tech Spec.
+ * `/plan` author step) needs to write the Tech Spec.
  * Returns a plain JSON-serialisable object; never hits the network beyond
  * the provider call needed to load the Epic.
  */
@@ -12,17 +12,16 @@ import path from 'node:path';
 import {
   resolveFeatureRoots,
   verifyBddRunnerPendingTag,
-} from '../../../bdd-runner-detect.js';
-import { scanBddScenarios } from '../../../bdd-scenario-scanner.js';
-import { buildCodebaseSnapshot } from '../../../codebase-snapshot.js';
-import { getLimits, getPaths, PROJECT_ROOT } from '../../../config-resolver.js';
-import { hasEpicSection } from '../../../epic-body-sections.js';
-import { scanMemoryFreshness } from '../../../feedback-loop/memory-freshness.js';
-import { fetchPriorFeedback } from '../../../feedback-loop/prior-feedback-fetcher.js';
-import { Logger } from '../../../Logger.js';
-import { ensureDocsDigest } from '../../docs-digest.js';
-import { applyBudget } from '../../planning-context-budget.js';
-import { collectReferences, hasNewFileCue } from '../../spec-freshness.js';
+} from '../../bdd-runner-detect.js';
+import { scanBddScenarios } from '../../bdd-scenario-scanner.js';
+import { buildCodebaseSnapshot } from '../../codebase-snapshot.js';
+import { getPaths, PROJECT_ROOT } from '../../config-resolver.js';
+import { scanMemoryFreshness } from '../../feedback-loop/memory-freshness.js';
+import { fetchPriorFeedback } from '../../feedback-loop/prior-feedback-fetcher.js';
+import { Logger } from '../../Logger.js';
+import { hasTicketSection } from '../../ticket-body-sections.js';
+import { ensureDocsDigest } from '../docs-digest.js';
+import { collectReferences, hasNewFileCue } from '../spec-freshness.js';
 import { buildAuthoringGrounding } from './spec-authoring-grounding.js';
 
 /**
@@ -60,11 +59,11 @@ function resolveMemoryDir({ github } = {}) {
  *
  * Ensures a docs digest exists at the **same** per-Epic temp path the
  * `/deliver` story sub-agents already consume
- * (`<tempRoot>/epic-<epicId>/docs-digest.md`) via the shared
+ * (`<tempRoot>/epic-<seedIssueId>/docs-digest.md`) via the shared
  * `ensureDocsDigest` export in `docs-digest.js` — one generator, one file,
  * reused across the planning and delivery surfaces for the same Epic. The
  * envelope carries only the digest path, not embedded doc content; the
- * planner (host LLM or the `epic-plan-spec-author` Skill) reads the digest
+ * planner (host LLM driving the `/plan` author step) reads the digest
  * and pulls a full file/section on demand when it bears on the decision.
  *
  * Returns `null` — a silent no-op — when `project.docsContextFiles` is not
@@ -72,10 +71,10 @@ function resolveMemoryDir({ github } = {}) {
  * planning; that fallback remains a `doc-reader.js` primitive used
  * elsewhere, not part of this envelope.
  *
- * @param {{ epicId: number, settings: object, cwd: string }} args
+ * @param {{ seedIssueId: number, settings: object, cwd: string }} args
  * @returns {Promise<{ mode: 'digest', digestPath: string } | null>}
  */
-async function buildPlanningDocsContext({ epicId, settings, cwd }) {
+async function buildPlanningDocsContext({ seedIssueId, settings, cwd }) {
   const docsContextFiles = Array.isArray(settings?.docsContextFiles)
     ? settings.docsContextFiles
     : [];
@@ -83,7 +82,11 @@ async function buildPlanningDocsContext({ epicId, settings, cwd }) {
 
   const paths = getPaths({ project: { paths: settings?.paths } });
   const docsRoot = path.resolve(cwd, paths.docsRoot);
-  const relPath = path.join(paths.tempRoot, `epic-${epicId}`, 'docs-digest.md');
+  const relPath = path.join(
+    paths.tempRoot,
+    `epic-${seedIssueId}`,
+    'docs-digest.md',
+  );
   const absPath = path.resolve(cwd, relPath);
 
   const result = await ensureDocsDigest({
@@ -97,18 +100,23 @@ async function buildPlanningDocsContext({ epicId, settings, cwd }) {
 
 /**
  * Build the authoring context the host LLM (or the
- * `epic-plan-spec-author` Skill) needs to write the Tech Spec.
+ * `/plan` author step) needs to write the Tech Spec.
  *
  * `docsContext` is digest-first (Story #4433): a pointer at the per-Epic
  * docs digest rather than embedded doc content, `null` when
- * `project.docsContextFiles` is unset. The Epic body itself stays bounded by
- * the planning-context budget (Epic #817 Story 9) — over-budget bodies
- * downgrade to a summary representation with headings + bounded excerpts.
- * Pass `{ fullContext: true }` (CLI: `--full-context`) to restore the
- * unbounded full Epic body.
+ * `project.docsContextFiles` is unset.
+ *
+ * The body carried here is **unbounded**. Story #4541 removed the
+ * `applyBudget` pass (and the `--full-context` flag that toggled it): both
+ * `plan-context.js` envelope builders discard this `epic` field entirely and
+ * ship the raw seed on `seed.content` instead, so the budget bounded nothing
+ * that shipped and the flag was a no-op. The raw-seed passthrough is
+ * deliberate and test-pinned; the budget pass was the orphan. Envelope size
+ * is guarded where it is actually decided — `PLAN_CONTEXT_ENVELOPE_BYTE_CEILING`
+ * in `lib/orchestration/plan-context.js`.
  */
 export async function buildAuthoringContext(
-  epicId,
+  seedIssueId,
   provider,
   settings = {},
   opts = {},
@@ -118,26 +126,19 @@ export async function buildAuthoringContext(
   // envelope build, which also needs the raw body for clarity scoring and
   // re-plan detection) does not pay a second provider fetch. Absent, the
   // fetch behaviour is unchanged.
-  const epic = opts.epic ?? (await provider.getEpic(epicId));
+  const epic = opts.epic ?? (await provider.getEpic(seedIssueId));
   if (!epic) {
-    throw new Error(`Epic #${epicId} not found.`);
+    throw new Error(`Epic #${seedIssueId} not found.`);
   }
 
-  const planningLimits = getLimits(settings).planningContext;
-  const { fullContext = false, cwd = PROJECT_ROOT } = opts;
+  const { cwd = PROJECT_ROOT } = opts;
 
   const docsContext = await buildPlanningDocsContext({
-    epicId: epic.id,
+    seedIssueId: epic.id,
     settings,
     cwd,
   });
 
-  const epicBody = applyBudget(
-    [{ path: `epic-${epic.id}.md`, content: epic.body ?? '' }],
-    planningLimits,
-    { fullContext },
-  );
-
   // Story #2094 Task #2103 — verify the project's BDD runner pending-tag
   // support so the acceptance-spec body can record either the verified tag
   // (features-first ordering) or "fallback: dependencies-first ordering"
@@ -153,7 +154,7 @@ export async function buildAuthoringContext(
     const featureRoots = resolveFeatureRoots({ cwd: PROJECT_ROOT });
     bddScenarios = scanBddScenarios({ featureRoots });
   } catch (err) {
-    Logger.warn(`[epic-plan-spec] BDD scenario scan skipped: ${err.message}`);
+    Logger.warn(`[plan-context] BDD scenario scan skipped: ${err.message}`);
   }
 
   // Story #2557 — memory-freshness pre-flight runs BEFORE the prior-feedback
@@ -220,44 +221,44 @@ export async function buildAuthoringContext(
       if (grounding.truncation) {
         const { dropped, matched, tier } = grounding.truncation;
         Logger.warn(
-          `[epic-plan-spec] codebase snapshot truncated: ${dropped} of ` +
+          `[plan-context] codebase snapshot truncated: ${dropped} of ` +
             `${matched} matched file(s) dropped from the ${tier}-tier view. ` +
-            `The spec-author context is partial. To restore full grounding, ` +
+            `The /plan authoring context is partial. To restore full ` +
+            `grounding, ` +
             `set planning.codebaseSnapshot.tier: "medium" and/or narrow ` +
             `planning.codebaseSnapshot.include in .agentrc.json.`,
         );
       }
       if (grounding.citedButAbsent.length > 0) {
         Logger.warn(
-          `[epic-plan-spec] ${grounding.citedButAbsent.length} path(s) cited ` +
-            `in the Epic body are absent from the codebase snapshot: ` +
-            `${grounding.citedButAbsent.join(', ')}. The spec author will ` +
-            `flag these as drift unless they are net-new.`,
+          `[plan-context] ${grounding.citedButAbsent.length} path(s) cited ` +
+            `in the authored Spec are absent from the codebase snapshot: ` +
+            `${grounding.citedButAbsent.join(', ')}. /plan will flag these ` +
+            `as drift unless they are net-new.`,
         );
       }
     }
   } catch (err) {
-    Logger.warn(`[epic-plan-spec] codebase snapshot skipped: ${err.message}`);
+    Logger.warn(`[plan-context] codebase snapshot skipped: ${err.message}`);
   }
 
-  // Epic #3865 — planning risk is no longer classified at emit-context
-  // time. The `epic-plan-spec-author` Skill authors the risk verdict
-  // (`risk-verdict.json`) as the fourth planning artifact, and the persist
-  // half derives the planningRisk envelope from it via deriveRiskEnvelope.
+  // Story #4542 — planning authors no risk artifact at all. Review depth and
+  // the acceptance-critic mode are derived from the diff at close time
+  // (`review-depth.js#deriveChangeLevel`), so there is nothing to classify
+  // here and nothing for the author step to judge about itself.
 
   return {
     epic: {
       id: epic.id,
       title: epic.title,
-      body: epicBody.mode === 'full' ? epic.body : null,
-      bodySummary: epicBody.mode === 'summary' ? epicBody.items[0] : null,
+      body: epic.body ?? null,
       // Story #4324: the context-ticket classes are retired. A re-planned
       // Epic's previous Tech Spec / Acceptance Table content rides along
       // inside `body` (managed sections), which is how the author keeps
       // AC IDs stable across re-plans.
       planningSections: {
-        techSpec: hasEpicSection(epic.body ?? '', 'techSpec'),
-        acceptanceTable: hasEpicSection(epic.body ?? '', 'acceptanceTable'),
+        techSpec: hasTicketSection(epic.body ?? '', 'techSpec'),
+        acceptanceTable: hasTicketSection(epic.body ?? '', 'acceptanceTable'),
       },
     },
     docsContext,

package/.agents/scripts/lib/orchestration/planning/decomposer-context.js

@@ -0,0 +1,27 @@
+/**
+ * decomposer-context.js — system-prompt builder for the `/plan` authoring
+ * pass (Story #2466; v2 keeps the prompt helper, drops the Epic-fetch
+ * decomposition envelope).
+ *
+ * `buildDecomposerSystemPrompt` is the live surface consumed by
+ * `plan-context.js#buildSystemPrompts`. The retired
+ * `buildDecompositionContext` Epic-fetch path lived here until the
+ * Story-only cutover removed every caller.
+ */
+
+import { renderDecomposerSystemPrompt } from '../../templates/decomposer-prompts.js';
+
+export function buildDecomposerSystemPrompt(
+  heuristics = [],
+  { maxTickets, epicId } = {},
+) {
+  const base = renderDecomposerSystemPrompt({
+    maxTickets,
+    epicId,
+  });
+  const heuristicsStr =
+    heuristics.length > 0
+      ? `### RISK HEURISTICS (planning metadata if any apply):\n- ${heuristics.join('\n- ')}`
+      : '';
+  return `${base}${heuristicsStr ? `\n\n${heuristicsStr}` : ''}`;
+}

package/.agents/scripts/lib/orchestration/{epic-plan-spec/phases → planning}/spec-authoring-grounding.js

@@ -1,5 +1,5 @@
 /**
- * phases/spec-authoring-grounding.js — F10 spec-authoring code-grounding.
+ * planning/spec-authoring-grounding.js — F10 Spec code-grounding.
  *
  * Story #4139 (Epic #4131). `/plan` Phase 7 authors the Tech Spec
  * from the Epic body, the scraped project docs, and the

package/.agents/scripts/lib/orchestration/pr-base-guard.js

@@ -1,47 +1,37 @@
 // .agents/scripts/lib/orchestration/pr-base-guard.js
 /**
- * pr-base-guard.js — refuse to open a pull request that would route an
- * Epic-attached Story's work directly into `main` instead of into the
- * parent Epic integration branch.
- *
- * Background: Story #2960 — during Epic #2880 wave 5 a sub-agent fell
- * back to `gh pr create --base main` after `story-close.js`
- * short-circuited as a no-op. The orphaned PR forced a manual recovery
- * (`git merge origin/main` back into `epic/2880`). This module is the
- * defence-in-depth call any framework helper that triggers `gh pr create`
- * MUST invoke before shelling out.
- *
- * Scope: the guard fires only when the Story body declares an
- * `Epic: #N` (or `Parent: #N`) reference. Stand-alone Stories — the
- * `/single-story-deliver` surface — are unaffected because they have no
- * parent reference to detect.
+ * pr-base-guard.js — refuse to open a pull request for a Story that still
+ * carries an Epic/parent footer (pre-v2 hierarchy). v2 Stories are
+ * standalone; Epic-attached bodies are a forward-cutover refusal, not a
+ * redirect onto `epic/<N>`.
  */
 
 import { resolveStoryHierarchy } from '../story-lifecycle.js';
 
 /**
- * Inspect a Story's body for an Epic parent reference and refuse a PR
- * whose `baseBranch` is not the matching `epic/<N>` integration branch.
+ * Inspect a Story's body for an Epic/parent reference and refuse any PR
+ * when one is present. Callers must re-plan Epic-attached tickets as v2
+ * Stories before delivering.
  *
  * @param {object} args
  * @param {number} args.storyId — Story ticket id (used in the error
  *   message so the operator can grep the failing surface).
  * @param {string|null|undefined} args.storyBody — raw Story body markdown.
- *   When falsy, the guard short-circuits (no parent → nothing to enforce).
- * @param {string} args.baseBranch — the `--base` value about to be passed
- *   to `gh pr create`.
- * @throws {Error} when the Story is Epic-attached and `baseBranch` is not
- *   the parent Epic's branch. The message matches the AC verbatim so
- *   reviewers can grep it.
+ *   When falsy, the guard short-circuits (no body → nothing to enforce).
+ * @param {string} args.baseBranch — retained for call-site compatibility;
+ *   unused once an Epic/parent footer is detected (any base is refused).
+ * @throws {Error} when the Story body declares an Epic or Parent footer.
  */
-export function assertStoryPrBaseAllowed({ storyId, storyBody, baseBranch }) {
+export function assertStoryPrBaseAllowed({
+  storyId,
+  storyBody,
+  baseBranch: _baseBranch,
+}) {
   if (!storyBody) return;
   const { epicId } = resolveStoryHierarchy(storyBody);
   if (epicId == null) return;
-  const expected = `epic/${epicId}`;
-  if (baseBranch === expected) return;
   throw new Error(
-    `Story #${storyId} is parented by Epic #${epicId} — merge into ${expected}, not ${baseBranch}. ` +
-      'To bypass, use /single-story-deliver explicitly.',
+    `Story #${storyId} still declares Epic/Parent #${epicId}. ` +
+      'v2 delivery is Story-only — re-plan as a standalone Story (no Epic footer) before opening a PR.',
   );
 }

package/.agents/scripts/lib/orchestration/remote-verifier.js

@@ -7,7 +7,7 @@
  * the delivery inline and committing to local `main` without pushing —
  * when the driving agent *perceived* the environment had no live GitHub
  * remote. The judgment was vibes, not fact. This module gives the entry
- * seams (`epic-deliver-preflight.js`, `single-story-init.js`) a verified
+ * seams (`single-story-init.js` for v2 `/deliver`) a verified
  * probe result to record in their envelopes so the workflow can branch on
  * `remoteVerified: true|false` deterministically: use the remote, or
  * transition to `agent::blocked` quoting the probe output — never a

package/.agents/scripts/lib/orchestration/resolve-stories.js

@@ -0,0 +1,344 @@
+/**
+ * lib/orchestration/resolve-stories.js — resolve a set of Story ids into the
+ * `{ stories, dag, done }` envelope the delivery scheduler consumes.
+ *
+ * This is the ONE resolution step for `/deliver`. It generalizes the
+ * envelope shaping proven by the retired `resolve-plan-run.js` and fixes the
+ * two defects that shipped with it:
+ *
+ *   - it fetched with `state: 'open'`, so an already-landed sibling vanished
+ *     from the envelope and `done[]` could never be populated;
+ *   - `done[]` was computed only over label-fetched issues, so a dependency
+ *     outside the fetched set could never be satisfied.
+ *
+ * Both made cross-run, over-time delivery structurally impossible. Here every
+ * dependency — in-set or foreign — is resolved against live issue state, so a
+ * Story whose blocker landed weeks ago in another plan run is simply ready.
+ *
+ * Two contracts differ deliberately from the label-scoped ancestor:
+ *
+ *   1. **Id-scoped fetch means a named non-Story is an ERROR, not a filter.**
+ *      `toStoryRecord` used to return `null` for a non-Story, which is right
+ *      when a label query returns incidental noise and wrong when an operator
+ *      names an id explicitly: silently dropping it yields a partial envelope
+ *      that under-delivers without saying so.
+ *   2. **The native-edge read fails loud.** See {@link readNativeBlockedBy}.
+ *
+ * @module lib/orchestration/resolve-stories
+ */
+
+import { extractEpicIdFromBody, parseBlockedBy } from '../dependency-parser.js';
+import { TYPE_LABELS } from '../label-constants.js';
+import { buildStoryAdjacency } from '../story-adjacency.js';
+import {
+  extractChangePaths,
+  parse as parseStoryBody,
+} from '../story-body/story-body.js';
+
+/** Labels/state that mean a blocker no longer gates its dependents. */
+const DONE_LABEL = 'agent::done';
+
+/**
+ * Module-private: `toStoryRecord` and `isSatisfiedBlocker` are its only
+ * callers. The ancestor exported it with no external consumer, which is how
+ * a symbol ends up baselined as a dead export.
+ *
+ * @param {object} issue
+ * @returns {string[]}
+ */
+function normalizeIssueLabels(issue) {
+  const raw = issue?.labels;
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .map((l) => (typeof l === 'string' ? l : l?.name))
+    .filter((n) => typeof n === 'string' && n.length > 0);
+}
+
+/**
+ * Map one fetched issue into a Story record, or throw naming the id and the
+ * remedy. Unlike the label-scoped ancestor this **never** returns `null`:
+ * under `--ids` the operator named this issue, so dropping it silently would
+ * emit a partial envelope.
+ *
+ * @param {object} issue
+ * @param {number} [requestedId] The id the operator asked for, for error text.
+ * @returns {{ id, title, body, url, labels, state }}
+ */
+export function toStoryRecord(issue, requestedId) {
+  const id = Number(issue?.number ?? issue?.id ?? requestedId);
+  if (!Number.isInteger(id) || id <= 0) {
+    throw new Error(
+      `[resolve-stories] #${requestedId ?? '?'} did not resolve to an issue number.`,
+    );
+  }
+  const labels = normalizeIssueLabels(issue);
+  if (!labels.includes(TYPE_LABELS.STORY)) {
+    throw new Error(
+      `[resolve-stories] Issue #${id} is not a Story (labels: ${labels.join(', ') || 'none'}). ` +
+        `/deliver accepts ${TYPE_LABELS.STORY} tickets only — close it or re-plan it as a v2 Story.`,
+    );
+  }
+  const body = String(issue?.body ?? '');
+  const epicId = extractEpicIdFromBody(body);
+  if (epicId !== null) {
+    throw new Error(
+      `[resolve-stories] Issue #${id} still carries an "Epic: #${epicId}" footer. ` +
+        `v2 is Story-only — re-plan it as a v2 Story or finish it on a pre-v2 checkout.`,
+    );
+  }
+  return {
+    id,
+    title: String(issue?.title ?? ''),
+    body,
+    url: issue?.html_url ?? issue?.url ?? null,
+    labels,
+    state: String(issue?.state ?? 'open').toLowerCase(),
+  };
+}
+
+/**
+ * A blocker stops gating once its issue is closed or carries `agent::done`.
+ *
+ * @param {{ state?: string, labels?: string[] }} issue
+ * @returns {boolean}
+ */
+export function isSatisfiedBlocker(issue) {
+  const state = String(issue?.state ?? '').toLowerCase();
+  if (state === 'closed') return true;
+  return normalizeIssueLabels(issue).includes(DONE_LABEL);
+}
+
+/**
+ * Footprint emitted when a Story's declared changes cannot be READ. It is a
+ * glob, so `storiesOverlap` (`lib/wave-runner/ready-set.js`) treats it as
+ * overlapping every other **declared** footprint and the Story takes its
+ * beat alone. (A Story declaring nothing still overlaps nothing — the guard
+ * short-circuits on an empty footprint either side, which is the deliberate
+ * permissive escape hatch that keeps undeclared work parallel.)
+ *
+ * Deliberately NOT `[]`. An empty footprint means "declares nothing", which
+ * the guard reads as "overlaps nothing" and never withholds — correct for a
+ * Story that genuinely declares no changes, and wrong for one whose changes
+ * we failed to parse. Those are different facts: the second is *unknown*
+ * width, and the same argument that makes a glob overlap everything
+ * ("unknown width is not no width") applies to a body we could not read.
+ */
+const UNKNOWN_FOOTPRINT = Object.freeze(['**']);
+
+/**
+ * Extract a Story's declared file footprint as **plain path strings**.
+ *
+ * The shape matters: `stories-wave-tick.js`'s `parseDag` rejects any `files`
+ * entry that is not a string, while `extractChangePaths` returns
+ * `{ path, isGlob }` objects — so forwarding its output verbatim fails every
+ * multi-Story run with an input error. Map to `.path`.
+ *
+ * Never throws — these are live, human-editable issue bodies, and one
+ * malformed body must not take the whole resolution down. It fails **safe**
+ * rather than open: an unreadable footprint yields {@link UNKNOWN_FOOTPRINT},
+ * serializing that Story instead of silently letting it race.
+ *
+ * @param {string} body
+ * @param {number} [id] Story id, for the warning.
+ * @param {(msg: string) => void} [warn]
+ * @returns {string[]}
+ */
+export function storyFootprintPaths(body, id, warn) {
+  let parsed;
+  try {
+    parsed = parseStoryBody(String(body ?? '')).body;
+  } catch (err) {
+    warn?.(
+      `[resolve-stories] #${id}: body is unparseable, so its file footprint is unknown ` +
+        `(${err?.message ?? err}). Treating it as overlapping every other Story, so it is ` +
+        `never co-dispatched — fix the body to restore parallelism.`,
+    );
+    return [...UNKNOWN_FOOTPRINT];
+  }
+  try {
+    // An empty `changes` is a real declaration of "no files", not a read
+    // failure — it keeps the permissive empty footprint.
+    return extractChangePaths(parsed?.changes ?? [])
+      .map((entry) => entry?.path)
+      .filter((p) => typeof p === 'string' && p.trim().length > 0)
+      .map((p) => p.trim());
+  } catch (err) {
+    warn?.(
+      `[resolve-stories] #${id}: malformed changes entry, so its file footprint is unknown ` +
+        `(${err?.message ?? err}). Treating it as overlapping every other Story.`,
+    );
+    return [...UNKNOWN_FOOTPRINT];
+  }
+}
+
+/**
+ * Build the DAG nodes. `dependsOn` is the union the adjacency builder already
+ * computes (body-parsed `blocked by #N` + explicit fields), plus any native
+ * edges threaded in via `nativeEdges`. `files` is a plain `string[]`.
+ *
+ * @param {object[]} stories
+ * @param {Map<number, number[]>} [nativeEdges]
+ * @param {(msg: string) => void} [warn]
+ * @returns {{ id: number, dependsOn: number[], files: string[] }[]}
+ */
+export function storiesToDag(stories, nativeEdges = new Map(), warn) {
+  const withNative = stories.map((s) => ({
+    ...s,
+    dependsOn: [
+      ...new Set([
+        ...parseBlockedBy(s.body ?? ''),
+        ...(nativeEdges.get(s.id) ?? []),
+      ]),
+    ],
+  }));
+  // dropForeign:false — a dependency outside the requested set is a real
+  // gate, not noise. What changes here is that such a gate is now
+  // *satisfiable*: `done[]` carries foreign blockers resolved from live state.
+  const adjacency = buildStoryAdjacency(withNative, { dropForeign: false });
+  return stories.map((s) => ({
+    id: s.id,
+    dependsOn: adjacency.get(s.id) ?? [],
+    files: storyFootprintPaths(s.body, s.id, warn),
+  }));
+}
+
+/**
+ * Project the dependencies API response onto issue **numbers**.
+ *
+ * The API returns both `id` (database id) and `number` (issue number); the
+ * write path (`providers/github/blocked-by-add.js`) reads `id` because its
+ * POST body needs `issue_id`. Reusing that projection here would build
+ * `dependsOn: [4902374986]` for a blocker whose issue number is 4530 — an id
+ * matching no Story, foreign to the set, never satisfiable, and (because
+ * foreign edges are real gates) a silent permanent wedge.
+ *
+ * Cross-repo blockers are rejected rather than matched: another repo's #4530
+ * is not this repo's #4530, and treating it as one could satisfy a gate that
+ * is still open.
+ *
+ * @param {unknown} data Parsed API response.
+ * @param {{ owner: string, repo: string, issueNumber: number }} ctx
+ * @returns {number[]}
+ */
+export function nativeBlockedByNumbers(data, { owner, repo, issueNumber }) {
+  if (!Array.isArray(data)) return [];
+  const out = [];
+  for (const item of data) {
+    const repoUrl = item?.repository_url ?? item?.repository?.url ?? null;
+    if (typeof repoUrl === 'string' && repoUrl.length > 0) {
+      const expected = `/repos/${owner}/${repo}`;
+      if (!repoUrl.endsWith(expected)) {
+        throw new Error(
+          `[resolve-stories] #${issueNumber} is blocked by an issue in another repository ` +
+            `(${repoUrl}). Cross-repo dependency edges are not supported — its number cannot ` +
+            `be matched against this repo's Stories without risking a false match.`,
+        );
+      }
+    }
+    const number = Number(item?.number);
+    if (Number.isInteger(number) && number > 0) out.push(number);
+  }
+  return [...new Set(out)];
+}
+
+/**
+ * Read an issue's native `blocked_by` edges as issue numbers.
+ *
+ * **Fails loud**, deliberately inverting the write path's non-fatal contract.
+ * A dropped write-side edge is cosmetic (the ordering still lives in the
+ * `blocked by #N` body footer); a dropped READ-side edge silently removes a
+ * dispatch gate, so a 403 (dependencies API disabled, or a token without the
+ * scope) would erase every native edge at once and co-dispatch the whole run
+ * against unlanded blockers. A 404 means "no dependencies on this issue" and
+ * is a legitimate empty result.
+ *
+ * @param {{ gh: object, owner: string, repo: string, issueNumber: number, parseJson: Function }} opts
+ * @returns {Promise<number[]>}
+ */
+export async function readNativeBlockedBy({
+  gh,
+  owner,
+  repo,
+  issueNumber,
+  parseJson,
+}) {
+  let result;
+  try {
+    result = await gh.api({
+      method: 'GET',
+      endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
+    });
+  } catch (err) {
+    const detail = String(err?.message ?? err);
+    if (/404|not found/i.test(detail)) return [];
+    throw new Error(
+      `[resolve-stories] Could not read native blocked_by edges for #${issueNumber}: ${detail}. ` +
+        `Refusing to continue: a dropped dependency edge would silently remove a dispatch gate ` +
+        `and co-dispatch this Story against an unlanded blocker.`,
+    );
+  }
+  return nativeBlockedByNumbers(parseJson(result), {
+    owner,
+    repo,
+    issueNumber,
+  });
+}
+
+/**
+ * Assemble the envelope from resolved records.
+ *
+ * @param {object[]} stories
+ * @param {Map<number, number[]>} nativeEdges
+ * @param {number[]} foreignDone Ids outside the set already satisfied.
+ * @param {(msg: string) => void} [warn]
+ * @returns {{ kind: string, stories: object[], dag: object[], done: number[] }}
+ */
+export function buildStoriesEnvelope({
+  stories,
+  nativeEdges = new Map(),
+  foreignDone = [],
+  warn,
+}) {
+  const sorted = [...stories].sort((a, b) => a.id - b.id);
+  const inSetDone = sorted.filter(isSatisfiedBlocker).map((s) => s.id);
+  return {
+    kind: 'stories',
+    stories: sorted.map(({ id, title, url, labels, state }) => ({
+      id,
+      title,
+      url,
+      labels,
+      state,
+    })),
+    dag: storiesToDag(sorted, nativeEdges, warn),
+    done: [...new Set([...inSetDone, ...foreignDone])].sort((a, b) => a - b),
+  };
+}
+
+/**
+ * Parse and validate the `--ids` list.
+ *
+ * @param {string|undefined} raw
+ * @returns {number[]}
+ */
+export function parseIds(raw) {
+  const ids = String(raw ?? '')
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => {
+      const n = Number.parseInt(s, 10);
+      if (!Number.isInteger(n) || n <= 0 || String(n) !== s) {
+        throw new Error(
+          `[resolve-stories] --ids must be a comma-separated list of positive issue numbers (got "${s}").`,
+        );
+      }
+      return n;
+    });
+  if (ids.length === 0) {
+    throw new Error(
+      '[resolve-stories] --ids is required: node resolve-stories.js --ids 101,102',
+    );
+  }
+  return [...new Set(ids)];
+}

package/.agents/scripts/lib/orchestration/resolves-token.js

@@ -2,7 +2,7 @@
  * resolves-token.js — single source of truth for the `(resolves #N)`
  * Story-merge integration marker.
  *
- * Background. `story-close.js` integrates each Story branch into its
+ * Background. The deleted `story-close.js` integrated each Story branch into its
  * parent Epic branch with `git merge --no-ff` and a Conventional-Commit
  * subject that carries a ` (resolves #<storyId>)` trailer. That trailer is
  * the *durable* proof a Story landed on `epic/<id>`: the local/remote