mandrel 2.0.0 → 2.1.0

package/.agents/scripts/lib/orchestration/ticket-lease.js

@@ -5,9 +5,19 @@
  * an exclusive, time-bounded claim on a ticket so two concurrent runs do not
  * both drive the same Story. Rather than invent a new state column, the lease
  * rides the ticket's existing **assignees** surface: the single assignee *is*
- * the lease owner. Liveness is decided by the owner's most-recent
- * `story.heartbeat` timestamp (the `operator` field added in this Story links
- * a heartbeat back to the claimant) compared against a configured TTL.
+ * the lease owner. Liveness is decided by the owner's last-heartbeat epoch-ms
+ * compared against a configured TTL.
+ *
+ * **There is no live heartbeat source.** The `story.heartbeat` emitter this
+ * module was designed against was structurally inert (it demanded an
+ * `epicId >= 1` that v2, which has no Epics, never supplies) and has been
+ * deleted. Every caller now reaches `acquireLease` through
+ * `lease-guard-shared.acquireLeaseFailClosed` with `anchorHeartbeatToNow`,
+ * which pins `heartbeatAt` to `now`: the lease **fails closed**, so any
+ * foreign claim reads as live and refuses. A stranded claim is cleared with
+ * `--steal`, never by TTL expiry. The TTL and the stale-reclaim branch below
+ * are therefore reachable only via an explicit caller-supplied `heartbeatAt`
+ * — the seam is kept, the automatic expiry is not real.
  *
  * The three exported operations are deliberately thin and provider-agnostic:
  *
@@ -31,19 +41,16 @@
  * Liveness seam: callers supply the owner's last-heartbeat epoch-ms via the
  * `heartbeatAt` option (a number, or `null`/`undefined` when no heartbeat has
  * ever been recorded for the current owner). Threading the timestamp in keeps
- * this module pure and trivially unit-testable — it does not read the
- * lifecycle ledger itself. A claim with no heartbeat is treated as stale
- * (reclaimable) so an abandoned assignment never wedges the ticket.
+ * this module pure and trivially unit-testable — it does not read any ledger
+ * itself. A claim with no heartbeat is treated as stale (reclaimable) by
+ * `isClaimLive`; note the live guards never take that branch, per the
+ * fail-closed anchoring described above.
  *
  * `now` is injectable (epoch ms) for deterministic tests; it defaults to
  * `Date.now()`.
  */
 
-import { readFileSync } from 'node:fs';
-
 import { resolveLeaseTtlMs } from '../config/limits.js';
-import { epicLedgerPath } from '../config/temp-paths.js';
-import { parseLedger } from './lifecycle/trace-logger.js';
 
 /**
  * The shipped, non-personal operator-identity placeholder (and its bare,
@@ -87,76 +94,22 @@ export function normalizeOperatorHandle(raw) {
   return trimmed;
 }
 
-/**
- * Read the most-recent `story.heartbeat` epoch-ms recorded for a given lease
- * owner from an Epic lifecycle ledger. Returns `null` when the ledger is
- * absent, unreadable, or carries no heartbeat for that owner — which the lease
- * primitive treats as a stale (reclaimable) claim.
- *
- * The ledger is NDJSON; each `story.heartbeat` record carries
- * `payload.operator` (Story #3480) and `payload.timestamp` (ISO-8601). A
- * malformed ledger downgrades to `null` rather than throwing so a corrupt
- * observability artifact never wedges the lease preflight.
- *
- * This is the shared liveness source the lease guards thread into
- * `acquireLease` via `heartbeatAt`; `/plan` and `/deliver` both
- * reuse it so a live foreign claim actually refuses.
- *
- * @param {object} args
- * @param {number} args.epicId
- * @param {string} args.owner            Lease owner whose heartbeat to find.
- * @param {object} [args.config]         Resolved config (for ledger path).
- * @param {string} [args.ledgerPath]     Explicit path override (tests).
- * @param {(eid: number, config?: object) => string} [args.ledgerPathResolver]
- *        Injectable resolver (tests). Defaults to `epicLedgerPath`.
- * @param {(p: string) => string} [args.readFile]  Injectable reader (tests).
- * @returns {number|null}
- */
-export function latestHeartbeatForOwner({
-  epicId,
-  owner,
-  config,
-  ledgerPath,
-  ledgerPathResolver = epicLedgerPath,
-  readFile = (p) => readFileSync(p, 'utf8'),
-}) {
-  if (typeof owner !== 'string' || owner.length === 0) return null;
-  const resolvedPath = ledgerPath ?? ledgerPathResolver(epicId, config);
-
-  let text;
-  try {
-    text = readFile(resolvedPath);
-  } catch (_err) {
-    // No ledger yet (fresh Epic) → no heartbeat → reclaimable.
-    return null;
-  }
-
-  let records;
-  try {
-    records = parseLedger(text);
-  } catch (_err) {
-    // Corrupt ledger is an observability problem, not a coordination blocker.
-    return null;
-  }
-
-  let latest = null;
-  for (const record of records) {
-    const payload = record?.payload;
-    if (!payload || payload.event !== 'story.heartbeat') continue;
-    if (payload.operator !== owner) continue;
-    const ts = Date.parse(payload.timestamp ?? '');
-    if (!Number.isFinite(ts)) continue;
-    if (latest === null || ts > latest) latest = ts;
-  }
-  return latest;
-}
-
 /**
  * Decide whether a foreign claim is still "live" given the owner's last
  * heartbeat and the configured TTL. A claim is live when a heartbeat exists
  * and is no older than `ttlMs`. A missing heartbeat (`null`/`undefined`) or a
  * heartbeat older than the TTL is stale and therefore reclaimable.
  *
+ * The `heartbeatAt` seam is retained, but there is no longer any in-repo
+ * heartbeat *source*: the `story.heartbeat` emitter was structurally inert
+ * (it required an `epicId >= 1` that v2 never sets) and was deleted along
+ * with the ledger reader that scanned for it. Every live caller reaches this
+ * through `lease-guard-shared.acquireLeaseFailClosed` with
+ * `anchorHeartbeatToNow`, which pins `heartbeatAt` to `now` so ANY foreign
+ * claim reads live and the guard fails closed — a stranded claim is cleared
+ * with `--steal`, not by TTL expiry. The parameter stays because that
+ * anchoring is expressed through it.
+ *
  * @param {object} args
  * @param {number|null|undefined} args.heartbeatAt  Owner's last heartbeat (epoch ms).
  * @param {number} args.ttlMs                        Lease TTL in milliseconds.

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

@@ -589,13 +589,53 @@ function registryRegistry(producers, assumptionEntries, patterns, cache) {
 }
 
 /**
- * Compute `fan-out-warning` findings (Story #2962).
+ * Normalize a fan-out probe result into `{ count, files, probe }`.
  *
- * For each `body.changes` entry whose `assumption` is `"deletes"` (or
- * `"refactors-existing"` when the planner declared a symbol replacement),
- * count the number of distinct files in the base branch that reference
- * the deleted module via its basename. When the count exceeds the
- * configured `largeFanOutThreshold`, emit a finding.
+ * The production probe reports its referencing files and the exact command
+ * that found them so an operator can reproduce the figure (Story #4547).
+ * A bare number stays valid — injected test counters and any consumer
+ * counter written against the Story #2962 contract keep working, they just
+ * carry no audit trail.
+ */
+function normalizeFanOutProbe(result) {
+  if (typeof result === 'number') {
+    return { count: result, files: [], probe: null };
+  }
+  if (result === null || typeof result !== 'object') {
+    return { count: 0, files: [], probe: null };
+  }
+  const files = Array.isArray(result.files) ? result.files : [];
+  const count = Number.isFinite(result.count) ? result.count : files.length;
+  return { count, files, probe: result.probe ?? null };
+}
+
+/**
+ * Index the basenames this spec *creates*, so a deletion that is really one
+ * half of a move can be told apart from a genuine wide-coupling removal.
+ */
+function indexCreatedBasenames(assumptionEntries) {
+  const byBasename = new Map();
+  for (const entry of assumptionEntries) {
+    if (entry.assumption !== 'creates') continue;
+    const base = entry.path.slice(entry.path.lastIndexOf('/') + 1);
+    if (!byBasename.has(base)) byBasename.set(base, entry.path);
+  }
+  return byBasename;
+}
+
+/**
+ * Compute `fan-out-warning` findings (Story #2962, reworked in #4547).
+ *
+ * For each `body.changes` entry whose `assumption` is `"deletes"`, probe the
+ * files at the base branch that genuinely import or require the deleted
+ * module. When that count exceeds the configured `largeFanOutThreshold`,
+ * emit a finding carrying the referencing files and the probe that produced
+ * them.
+ *
+ * The finding also records whether the deletion is **rename-shaped** — the
+ * same spec creates a file with the deleted module's basename elsewhere —
+ * because the remedy diverges: a move wants its importers repointed in one
+ * Story, not a subsystem-by-subsystem migration split across several.
  *
  * The default severity is always `'soft'` — the persist gate enforces a
  * hard refusal via the `--allow-large-fan-out` operator flag, since the
@@ -613,21 +653,28 @@ function computeFanOutFindings({
   if (!Number.isFinite(threshold) || threshold < 0) return [];
   const findings = [];
   const cache = new Map();
+  const createdBasenames = indexCreatedBasenames(assumptionEntries);
   for (const entry of assumptionEntries) {
     if (entry.assumption !== 'deletes') continue;
-    let count = cache.get(entry.path);
-    if (count === undefined) {
-      count = counter({ path: entry.path }) ?? 0;
-      cache.set(entry.path, count);
+    let probed = cache.get(entry.path);
+    if (probed === undefined) {
+      probed = normalizeFanOutProbe(counter({ path: entry.path }));
+      cache.set(entry.path, probed);
     }
-    if (count <= threshold) continue;
+    if (probed.count <= threshold) continue;
+    const base = entry.path.slice(entry.path.lastIndexOf('/') + 1);
+    const renameTarget = createdBasenames.get(base);
     findings.push({
       kind: 'fan-out-warning',
       severity,
       taskSlug: entry.taskSlug,
       storySlug: entry.storySlug,
       path: entry.path,
-      callSiteCount: count,
+      callSiteCount: probed.count,
+      callSites: probed.files,
+      probe: probed.probe,
+      renameShaped: renameTarget !== undefined && renameTarget !== entry.path,
+      renameTarget: renameTarget === entry.path ? null : (renameTarget ?? null),
       threshold,
     });
   }
@@ -701,6 +748,60 @@ export function computeConflictFindings({ stories, policy } = {}) {
   ];
 }
 
+/**
+ * Render the audit trail behind a fan-out finding's number, so an operator
+ * can check the figure rather than trust it (Story #4547).
+ *
+ * Every importer is named — the list is deliberately **not** truncated. A
+ * gate that fires at 100 importers is precisely when the operator needs the
+ * list, and a `…and 109 more` tail would leave the figure uncheckable in
+ * exactly the case the gate exists for. This message is a fail-closed stop,
+ * not a log line; its length is the point.
+ *
+ * The probe is reported as what it is — the *candidate* net, which each hit
+ * is then re-resolved against. It will report at least as many lines as the
+ * gate counts files, so labelling it as the thing that produced the number
+ * would send an operator chasing a discrepancy that is by design.
+ *
+ * Returns `''` for a bare-number counter, which carries no audit trail.
+ */
+export function renderFanOutEvidence(finding) {
+  const files = Array.isArray(finding.callSites) ? finding.callSites : [];
+  const parts = [];
+  if (files.length > 0) {
+    parts.push(`    Importers (${files.length}):`);
+    for (const file of files) parts.push(`      ${file}`);
+  }
+  if (finding.probe) {
+    parts.push(
+      `    Candidate probe (each hit re-resolved against its importer's directory):`,
+      `      ${finding.probe}`,
+    );
+  }
+  return parts.length > 0 ? `\n${parts.join('\n')}` : '';
+}
+
+/**
+ * Render the remedy that actually fits the finding. A rename-shaped
+ * deletion has nowhere to split to — the importers just need repointing at
+ * the path the same plan creates — so telling the operator to split it
+ * across Stories leaves the override as the only exit, which is exactly the
+ * habit that defeats the gate (Story #4547).
+ */
+export function renderFanOutRemedy(finding) {
+  if (finding.renameShaped && finding.renameTarget) {
+    return (
+      `This deletion is rename-shaped: the same plan creates "${finding.renameTarget}" under the same basename. ` +
+      `Repoint the importer(s) at the new path inside this Story — a move has no subsystems to split across — ` +
+      `then rerun --allow-large-fan-out.`
+    );
+  }
+  return (
+    `Split the deletion into a subsystem-by-subsystem migration across multiple Stories, ` +
+    `or rerun --allow-large-fan-out after confirming the deletion is intentional.`
+  );
+}
+
 /**
  * Render a `'hard'`-severity conflict finding as a human-readable error
  * message. Used by the validator when policy flags upgrade a finding to
@@ -712,14 +813,18 @@ export function renderHardConflictError(finding) {
     return `Shared-editor conflict: "${finding.path}" is written by ${finding.storySlugs.length} concurrent Stories (${stories}). Add depends_on chains between them or split the edits into a dedicated late-wave wiring Story.`;
   }
   if (finding.kind === 'implicit-cross-story-dep') {
-    return `Implicit cross-Story dependency: Task "${finding.consumer.taskSlug}" in Story "${finding.consumer.storySlug}" references "${finding.path}" (produced by Task "${finding.producer.taskSlug}" in Story "${finding.producer.storySlug}") via body.${finding.consumer.sourceField}, but Story "${finding.consumer.storySlug}" has no depends_on link to Story "${finding.producer.storySlug}". Add depends_on: ["${finding.producer.storySlug}"] to the consumer Story or remove the reference.`;
+    return `Implicit cross-Story dependency: Story "${finding.consumer.storySlug}" references "${finding.path}" (produced by Story "${finding.producer.storySlug}") via body.${finding.consumer.sourceField}, but Story "${finding.consumer.storySlug}" has no depends_on link to Story "${finding.producer.storySlug}". Add depends_on: ["${finding.producer.storySlug}"] to the consumer Story or remove the reference.`;
   }
   if (finding.kind === 'cross-cutting-registries') {
     const stories = finding.storySlugs.map((s) => `"${s}"`).join(', ');
     return `Cross-cutting registry conflict: ${finding.storySlugs.length} concurrent Stories (${stories}) edit or register into "${finding.registryPath}". Add depends_on chains between them so the registry updates serialize, or split the registration into a dedicated late-wave wiring Story.`;
   }
   if (finding.kind === 'fan-out-warning') {
-    return `Large fan-out: Task "${finding.taskSlug}" in Story "${finding.storySlug}" deletes "${finding.path}" with ${finding.callSiteCount} call site(s) on the base branch (threshold ${finding.threshold}). Split into a subsystem-by-subsystem migration across multiple Stories, or rerun --allow-large-fan-out after confirming the deletion is intentional.`;
+    return (
+      `Large fan-out: Story "${finding.storySlug}" deletes "${finding.path}" ` +
+      `with ${finding.callSiteCount} importer(s) on the base branch (threshold ${finding.threshold}). ` +
+      `${renderFanOutRemedy(finding)}${renderFanOutEvidence(finding)}`
+    );
   }
   if (finding.kind === 'missing-bdd-scaffold') {
     return `Missing BDD scaffold: Story "${finding.consumer.storySlug}" verifies against "${finding.path}" (created by Story "${finding.producer.storySlug}") via body.${finding.consumer.sourceField}, but "${finding.consumer.storySlug}" has no depends_on path to "${finding.producer.storySlug}" — the .feature file is scaffolded in the same wave (or later), so verification runs before the file exists. Add depends_on: ["${finding.producer.storySlug}"] to the consumer Story so the scaffold lands in an earlier wave.`;

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

@@ -14,10 +14,9 @@
  *
  * `DEFAULT_MODEL_CAPACITY` is the **single source of truth** for the capacity
  * thresholds. The decomposer prompt template
- * (`.agents/scripts/lib/templates/decomposer-prompts.js`) and the authoring
- * SKILL (`.agents/skills/core/epic-plan-decompose-author/SKILL.md`) reference
- * these numbers rather than restating divergent ones — the prompt generates
- * its threshold sentence from this constant so the two surfaces cannot drift.
+ * (`.agents/scripts/lib/templates/decomposer-prompts.js`) generates its
+ * threshold sentence from this constant rather than restating divergent
+ * numbers, so the two surfaces cannot drift.
  *
  * Capacity model:
  *   - Plan-time **session mass** = authored tokens only (`estimateTokens` of

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

@@ -3,7 +3,10 @@ import { detectCycle } from '../Graph.js';
 import { gitSpawn } from '../git-utils.js';
 
 import { Logger } from '../Logger.js';
-import { parse as parseStoryBody } from '../story-body/story-body.js';
+import {
+  parse as parseStoryBody,
+  StoryBodyParseError,
+} from '../story-body/story-body.js';
 import { validateStoryFileAssumptions } from './file-assumptions.js';
 import {
   computeConflictFindings,
@@ -43,6 +46,95 @@ function collectPathsFromText(text, paths) {
   }
 }
 
+/**
+ * Parse a Story's serialized markdown body, translating a
+ * `StoryBodyParseError` into a `ValidationError` that names the offending
+ * **section** and **entry** (Story #4541).
+ *
+ * `StoryBodyParseError` already carries `field` (the section the parser was
+ * reading) and `raw` (the entry text that failed); this lifts both into an
+ * operator-legible message and a structured `violation` payload so an
+ * authoring loop can point at the exact bullet instead of re-deriving it
+ * from a downstream freshness miss.
+ *
+ * @param {object} story Story whose `body` is a non-empty markdown string.
+ * @returns {object} The structured body.
+ * @throws {ValidationError} `code: 'story-body-unparseable'`.
+ */
+function parseStoryBodyOrThrow(story) {
+  try {
+    return parseStoryBody(story.body).body;
+  } catch (err) {
+    if (!(err instanceof StoryBodyParseError)) throw err;
+    const slug = story.slug ?? '<unknown>';
+    const section = err.field ?? 'body';
+    const entry = err.raw ?? null;
+    const entryLine = entry === null ? '' : `\n      entry: ${entry}`;
+    const violation = { slug, section, entry, reason: err.message };
+    const error = new ValidationError(
+      `Cross-Validation Failed: Story "${slug}" has an unparseable body — ` +
+        `the ## ${section} section could not be read: ${err.message}` +
+        `${entryLine}\n\nFix the offending entry; this is a malformed body, ` +
+        'not a stale path reference.',
+      { violations: [violation] },
+    );
+    error.code = 'story-body-unparseable';
+    error.violations = [violation];
+    throw error;
+  }
+}
+
+/**
+ * Refuse the plan when any Story's serialized body cannot be parsed, before
+ * either git-probe gate runs (Story #4541). Ordering matters: the freshness
+ * gate consults `body.changes` for its net-new whitelist, so an unparseable
+ * body used to reach the operator as a freshness miss naming declared paths.
+ *
+ * @param {{ tickets: object[] }} opts
+ * @throws {ValidationError} `code: 'story-body-unparseable'` on the first
+ *   offending Story.
+ */
+function assertStoryBodiesParse({ tickets }) {
+  for (const story of (tickets ?? []).filter((t) => t.type === 'story')) {
+    if (typeof story.body !== 'string' || story.body.trim().length === 0) {
+      continue;
+    }
+    parseStoryBodyOrThrow(story);
+  }
+}
+
+/**
+ * Resolve every acceptance line a Story declares, across both authoring
+ * shapes (Story #4541).
+ *
+ * The canonical shape is a **serialized string body** with the criteria at
+ * the ticket's **top level** — the machine contract persist syncs into the
+ * body. `validateAcceptanceSubjectPrefix` used to read `body.acceptance` on
+ * an object body only, so on every real plan it scanned nothing and the gate
+ * silently passed. Union both sources (deduplicated) so the gate fires on
+ * whichever surface the author used.
+ *
+ * @param {object} story
+ * @returns {string[]}
+ */
+function resolveAcceptanceLines(story) {
+  const lines = new Set();
+  if (Array.isArray(story?.acceptance)) {
+    for (const item of story.acceptance) lines.add(String(item ?? ''));
+  }
+  const body = story?.body;
+  let bodyAcceptance = null;
+  if (typeof body === 'string' && body.trim().length > 0) {
+    bodyAcceptance = parseStoryBodyOrThrow(story).acceptance;
+  } else if (body !== null && typeof body === 'object') {
+    bodyAcceptance = body.acceptance;
+  }
+  if (Array.isArray(bodyAcceptance)) {
+    for (const item of bodyAcceptance) lines.add(String(item ?? ''));
+  }
+  return [...lines];
+}
+
 function collectTaskPathReferences(task) {
   const paths = new Set();
   const body = task.body;
@@ -82,7 +174,7 @@ function collectTaskPathReferences(task) {
  *    path out of the prose.
  * 3. **Object form** — `{ path: "<path>", assumption: "creates" | ... }`,
  *    introduced by Story #2636 as the canonical declaration shape and
- *    documented in `epic-plan-decompose-author/SKILL.md`. The path is
+ *    documented in `lib/templates/decomposer-prompts.js`. The path is
  *    trusted verbatim.
  *
  * Only `body.changes` (and `body.references`) is consulted —
@@ -100,15 +192,16 @@ function collectTaskChangesPaths(task) {
   // arrays before scanning. Without this, a string body causes the
   // object-form branch below to fall through on every item, leaving the
   // freshness gate blind to declared paths.
+  //
+  // Story #4541: a parse failure is NOT swallowed here. Swallowing it
+  // returned an empty whitelist, so a single malformed `## Changes` entry
+  // surfaced downstream as "files do not exist at main" naming the very
+  // paths the Story *had* declared — a misdiagnosis that cost two authoring
+  // round-trips. `assertStoryBodiesParse` runs before the freshness gate and
+  // owns that failure with a named error; the throw here is the same error
+  // for any caller that drives `validateAcFreshness` directly.
   if (typeof body === 'string' && body.trim().length > 0) {
-    let parsed;
-    try {
-      parsed = parseStoryBody(body).body;
-    } catch {
-      // Unparseable body — no paths to whitelist; the freshness gate will
-      // catch any real references in the text scan below.
-      return paths;
-    }
+    const parsed = parseStoryBodyOrThrow(task);
     for (const arrName of ['changes', 'references']) {
       const arr = parsed[arrName];
       if (!Array.isArray(arr)) continue;
@@ -307,11 +400,16 @@ const SUBJECT_PREFIX_RE = /Commit subject begins with ['"`]([^'"`]+):['"`]/g;
  * the form `baseline-refresh` is rejected because no Conventional-Commits
  * type starts with that token.
  *
- * Only `body.acceptance[]` is scanned; `body.goal` / `body.verify` /
+ * Only acceptance criteria are scanned; `body.goal` / `body.verify` /
  * `body.changes` are not commit-subject prescriptions by convention and
  * scanning them would surface false positives from prose that happens to
  * quote a forbidden prefix while explaining why it's forbidden.
  *
+ * Both authoring shapes are covered (Story #4541): the canonical top-level
+ * `acceptance[]` on a serialized string body, and the pre-serialize
+ * `body.acceptance[]` object shape. Scanning only the latter made the gate
+ * inert on every real plan.
+ *
  * @param {object}   opts
  * @param {object[]} opts.tickets - Validated ticket hierarchy.
  * @throws {ValidationError} when one or more Story acceptance items
@@ -324,11 +422,7 @@ export function validateAcceptanceSubjectPrefix({ tickets }) {
   const violations = [];
   const stories = (tickets ?? []).filter((t) => t.type === 'story');
   for (const story of stories) {
-    const body = story.body;
-    if (body === null || typeof body !== 'object') continue;
-    if (!Array.isArray(body.acceptance)) continue;
-    for (const item of body.acceptance) {
-      const line = String(item ?? '');
+    for (const line of resolveAcceptanceLines(story)) {
       // Reset the global regex between iterations.
       SUBJECT_PREFIX_RE.lastIndex = 0;
       let match = SUBJECT_PREFIX_RE.exec(line);
@@ -381,8 +475,8 @@ function renderMissLine({ slug, path }) {
  * The returned tickets array carries two extra non-array properties:
  *   - `findings` — structured sizing findings (hard + soft) keyed by the
  *     three-layer sizing model. The bounded re-decomposition loop in
- *     `epic-plan-decompose` reads `findings.filter(f => f.severity === 'hard')`
- *     to decide whether to re-prompt.
+ *     `/plan` reads `findings.filter(f => f.severity === 'hard')` to decide
+ *     whether to re-prompt.
  *   - `errors`   — human-readable strings, one per hard finding. Non-empty
  *     `errors[]` is the AC-visible "block normalization" signal; the legacy
  *     hierarchy/cycle/freshness checks continue to throw, so callers that
@@ -540,6 +634,14 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
 
   assertAcyclic(slugAdjacency);
 
+  // Story #4541 — refuse an unparseable Story body up front, with a named
+  // error pointing at the offending section + entry. Must precede both the
+  // subject-prefix scan and the freshness gate: each parses the body, and
+  // the freshness gate's net-new whitelist comes from `body.changes`, so a
+  // malformed body used to surface as a stale-path miss naming the paths the
+  // Story had legitimately declared.
+  assertStoryBodiesParse({ tickets });
+
   // Reject any Task acceptance item that prescribes a non-Conventional-Commits
   // subject prefix (e.g. legacy "Commit subject begins with 'baseline-refresh:'"
   // from pre-Epic-#2501 planner output). Runs before the freshness gate so
@@ -648,6 +750,7 @@ export function validateAndNormalizeTickets(tickets, opts = {}) {
 
 // Internal helpers exposed for unit tests; not part of the public surface.
 export const _internal = {
+  assertStoryBodiesParse,
   indexTicketsBySlug,
   assertAllTicketsAreStories,
   assertEveryStoryHasInlineContract,

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

@@ -357,7 +357,7 @@ async function processCascadeParentLocked(
  *   unset so the module-level {@link Logger} is used.
  * @returns {Promise<{ cascadedTo: number[], failed: Array<{ parentId: number, error: string }> }>}
  */
-export async function cascadeCompletion(provider, ticketId, opts = {}) {
+async function cascadeCompletion(provider, ticketId, opts = {}) {
   const ticket = await provider.getTicket(ticketId);
 
   // Determine if this ticket is agent::done
@@ -365,43 +365,14 @@ export async function cascadeCompletion(provider, ticketId, opts = {}) {
     return { cascadedTo: [], failed: [] };
   }
 
+  // Story #4545 — one strategy, not three. The `parent: #N` body footer and
+  // the native sub-issue link were both written by `createTicket`, the
+  // Epic-hierarchy write surface deleted in the same Story; with no writer,
+  // the body regex could only ever miss and the native lookup could only
+  // ever spend an API call to learn the same. The operator-settable `blocks`
+  // annotation is the one parent edge that can still exist.
   const { blocks: parentIds } = await provider.getTicketDependencies(ticketId);
-
-  // Fallback: parse `parent: #NNN` from the body when `blocks` syntax isn't used (C-5).
-  let parsedParents = parentIds;
-  if (!parsedParents || parsedParents.length === 0) {
-    const parentMatch = ticket.body
-      ? [...ticket.body.matchAll(/parent:\s*#(\d+)/gi)]
-      : [];
-    parsedParents = parentMatch.map((m) => Number.parseInt(m[1], 10));
-  }
-
-  // Story #2982 — third fallback: GitHub's native Sub-Issues API. The
-  // resume reconciler can strip the `parent: #N` orchestrator footer
-  // from a Story body (see Issue 2 in #2982); without the body marker
-  // the cascade silently returned `{ cascadedTo: [], failed: [] }` and
-  // left intermediate parent tickets stranded OPEN. The native link is
-  // independent of body text, so consult it when the first two
-  // strategies came back empty.
-  if (
-    parsedParents.length === 0 &&
-    typeof provider._getNativeParent === 'function' &&
-    ticket.nodeId
-  ) {
-    try {
-      const nativeParent = await provider._getNativeParent(
-        ticket.nodeId,
-        ticketId,
-      );
-      if (typeof nativeParent === 'number') {
-        parsedParents = [nativeParent];
-      }
-    } catch (err) {
-      Logger.warn(
-        `[cascadeCompletion] native parent lookup failed for #${ticketId}: ${err.message}`,
-      );
-    }
-  }
+  const parsedParents = Array.isArray(parentIds) ? parentIds : [];
 
   if (parsedParents.length === 0) {
     return { cascadedTo: [], failed: [] };
@@ -537,22 +508,18 @@ export async function cascadeParentState(provider, ticketId, opts = {}) {
 }
 
 /**
- * Resolve the parent issue ids for a ticket: native `blocks:` dependency
- * annotations first, then `parent: #NNN` body references as a fallback.
- * Mirrors the resolution path used by {@link cascadeCompletion}.
+ * Resolve the parent issue ids for a ticket from its `blocks:` dependency
+ * annotations. Mirrors the resolution path used by {@link cascadeCompletion}
+ * — see there for why the `parent: #NNN` body fallback is gone (Story #4545).
  *
  * @param {import('../../ITicketingProvider.js').ITicketingProvider} provider
- * @param {object} ticket
+ * @param {object} _ticket
  * @param {number} ticketId
  * @returns {Promise<number[]>}
  */
-async function resolveParentIds(provider, ticket, ticketId) {
+async function resolveParentIds(provider, _ticket, ticketId) {
   const { blocks: parentIds } = await provider.getTicketDependencies(ticketId);
-  if (Array.isArray(parentIds) && parentIds.length > 0) return parentIds;
-  const parentMatch = ticket?.body
-    ? [...ticket.body.matchAll(/parent:\s*#(\d+)/gi)]
-    : [];
-  return parentMatch.map((m) => Number.parseInt(m[1], 10));
+  return Array.isArray(parentIds) ? parentIds : [];
 }
 
 /**