mandrel 1.59.0 → 1.61.0

package/.agents/scripts/lib/orchestration/epic-plan-spec/phases/run-spec-phase.js

@@ -112,7 +112,7 @@ export async function runSpecPhase(
   }
 
   // Workflow-guards (Story #3481): acquire the Epic-lease before any Phase 7
-  // mutation so two concurrent /epic-plan runs cannot both drive this Epic. The
+  // mutation so two concurrent /plan runs cannot both drive this Epic. The
   // guard fails closed (audit #3513) — any foreign assignee refuses here and
   // the CLI exits non-zero naming the owner, unless `--steal` transfers it.
   await acquireEpicPlanLease({ provider, epicId, config, steal });
@@ -158,7 +158,7 @@ export async function runSpecPhase(
   // Story #1585 (Epic #1471): the baseline-snapshot fork was previously
   // performed here at plan-time. It now runs at first-story-init time
   // inside `lib/story-init/branch-initializer.js#bootstrapWorktree` so
-  // `/epic-plan` remains git-state-free. `forkAndCommitEpicSnapshot` and
+  // `/plan` remains git-state-free. `forkAndCommitEpicSnapshot` and
   // `forkMainToEpic` remain exported for that caller.
 
   const reviewRouting = resolveReviewRouting({ planningRisk, forceReview });

package/.agents/scripts/lib/orchestration/epic-plan-state-store.js

@@ -30,7 +30,7 @@
  * the lifecycle phase is already authoritative on the Epic's `agent::*` labels,
  * so the duplicate `phase` telemetry (and its `setPhase` round-trips) was
  * deleted. The fields that survive — `spec`, `decompose`, `planningRisk`,
- * `reviewRouting`, `manifestCommentId` — are the ones `/epic-plan --resume`
+ * `reviewRouting`, `manifestCommentId` — are the ones `/plan --resume`
  * reads to skip already-completed work.
  */
 

package/.agents/scripts/lib/orchestration/epic-run-state-store.js

@@ -1,6 +1,6 @@
 /**
  * epic-run-state-store — stateless functions for reading and writing the
- * `epic-run-state` structured comment used by `/epic-deliver`.
+ * `epic-run-state` structured comment used by `/deliver`.
  *
  * This module is the function-based replacement for the legacy
  * `Checkpointer` class that previously lived at
@@ -133,7 +133,7 @@ export async function initialize({
  * Reconcile the resume pointer (`currentWave` + `waves[]` history) against
  * a freshly-recomputed wave plan.
  *
- * Story #3358 — when `/epic-deliver` is resumed on a partially-complete
+ * Story #3358 — when `/deliver` is resumed on a partially-complete
  * Epic, `epic-deliver-prepare.js` recomputes the wave DAG over only the
  * **not-done** Stories (`build-wave-dag.js#discoverOpenStories` drops the
  * closed/merged Stories). The recomputed plan is therefore *shorter* and
@@ -270,7 +270,7 @@ export async function appendIntervention({ provider, epicId, entry } = {}) {
 }
 
 /**
- * Advance the checkpoint's `phase` field to the next `/epic-deliver`
+ * Advance the checkpoint's `phase` field to the next `/deliver`
  * phase. Reads the current state first so the caller does not need to
  * keep an in-memory copy. Other state fields are preserved verbatim.
  *

package/.agents/scripts/lib/orchestration/epic-runner/concurrency-gate.js

@@ -1,10 +1,10 @@
 /**
  * Cross-Story conflict-finding gate for `epic-deliver-prepare.js`.
  *
- * Story #2297 — when the bounded `/epic-plan` flow emitted concurrency
+ * Story #2297 — when the bounded `/plan` flow emitted concurrency
  * findings (Story #2296's validator pass), the operator may have shipped
- * them through to `/epic-deliver` without resolving the underlying
- * `depends_on` gaps. This gate runs at Phase 1 of `/epic-deliver` and
+ * them through to `/deliver` without resolving the underlying
+ * `depends_on` gaps. This gate runs at Phase 1 of `/deliver` and
  * refuses to flip the Epic to `agent::executing` when the upcoming
  * waves still contain unresolved conflicts — surfacing the exact
  * remediation commands the operator should run before retrying.
@@ -138,7 +138,7 @@ export function renderGateErrorMessage(findings, ownerRepo) {
     lines.push('');
   }
   lines.push(
-    'Resolve the listed conflicts and re-run `/epic-deliver`, or pass `--ignore-concurrency-hazards` to bypass this gate.',
+    'Resolve the listed conflicts and re-run `/deliver`, or pass `--ignore-concurrency-hazards` to bypass this gate.',
   );
   return lines.join('\n');
 }

package/.agents/scripts/lib/orchestration/epic-runner/deliver-phases.js

@@ -1,5 +1,5 @@
 /**
- * deliver-phases.js — phase enum and ordering utility for `/epic-deliver`.
+ * deliver-phases.js — phase enum and ordering utility for `/deliver`.
  *
  * Story #1155 (Epic #1142, 5.40.0). Originally extracted from the
  * legacy class-based checkpoint module so the phase enum and close-tail
@@ -11,7 +11,7 @@
  */
 
 /**
- * Ordered list of `/epic-deliver` phases. The checkpoint's `phase` field
+ * Ordered list of `/deliver` phases. The checkpoint's `phase` field
  * stores the **next phase to run**, so a mid-flight crash during
  * `code-review` resumes by reading `phase === 'code-review'` and re-
  * entering Phase D from the start.
@@ -44,7 +44,7 @@ export function assertValidDeliverPhase(nextPhase) {
   if (nextPhase === 'done') return;
   if (phaseIndex(nextPhase) >= 0) return;
   throw new Error(
-    `Invalid /epic-deliver phase ${JSON.stringify(nextPhase)}. ` +
+    `Invalid /deliver phase ${JSON.stringify(nextPhase)}. ` +
       `Expected one of ${DELIVER_PHASES.join(', ')} or 'done'.`,
   );
 }

package/.agents/scripts/lib/orchestration/epic-runner/phases/build-wave-dag.js

@@ -2,13 +2,9 @@
  * Build the wave DAG from the Epic's open child Stories.
  *
  * `getSubTickets` returns the **direct** children of a parent ticket via
- * native sub-issues + checklist links + body reverse-lookup (despite an
- * older docstring claiming "every descendant"). The v5 canonical Epic
- * hierarchy is Epic → Feature → Story → Task, so Stories live as
- * **grandchildren** of the Epic. We therefore walk one level deeper from
- * each `type::feature` direct child to collect the real Story set, and
- * union with any direct-child Stories (some Epics still carry Stories
- * directly while migrating).
+ * native sub-issues + checklist links + body reverse-lookup. The
+ * canonical 2-tier hierarchy is Epic → Story, so the Epic's direct
+ * `type::story` children are the complete Story set.
  *
  * We additionally filter out closed Stories — `getSubTickets`'s reverse-
  * reference search can surface closed-as-obsolete tickets whose body
@@ -25,8 +21,8 @@ import { buildStoryAdjacency } from '../../../story-adjacency.js';
 import { WaveScheduler } from '../wave-scheduler.js';
 
 /**
- * Walk Epic → Feature → Story (one descent past the Epic's direct
- * children) and return the open `type::story` tickets, deduped by id.
+ * Collect the Epic's direct `type::story` children and return the open
+ * ones, deduped by id.
  *
  * Exported so `snapshot.js#discoverStoryIds` and `epic-deliver-preflight`
  * can share the same enumeration contract — the snapshot.end payload,
@@ -34,20 +30,9 @@ import { WaveScheduler } from '../wave-scheduler.js';
  */
 export async function discoverOpenStories({ epicId, provider }) {
   const descendants = (await provider.getSubTickets(epicId)) ?? [];
-  const features = descendants.filter((t) =>
-    (t.labels ?? []).includes(TYPE_LABELS.FEATURE),
-  );
-  const grandchildren = (
-    await Promise.all(
-      features.map(async (f) => {
-        const id = f.id ?? f.number;
-        return id == null ? [] : ((await provider.getSubTickets(id)) ?? []);
-      }),
-    )
-  ).flat();
   const seen = new Set();
   const stories = [];
-  for (const t of [...descendants, ...grandchildren]) {
+  for (const t of descendants) {
     const labels = t.labels ?? [];
     if (!labels.includes(TYPE_LABELS.STORY)) continue;
     const rawState = t.state ?? 'open';

package/.agents/scripts/lib/orchestration/epic-runner/phases/snapshot.js

@@ -2,7 +2,7 @@
  * Epic snapshot phase — fetch Epic ticket and enforce the acceptance-spec
  * start gate.
  *
- * Auto-close is now the default for `/epic-deliver` (the human PR-merge is
+ * Auto-close is now the default for `/deliver` (the human PR-merge is
  * the gate); no per-Epic label snapshot is required.
  *
  * Acceptance-spec start gate (relaxed): an Epic may be delivered when
@@ -11,9 +11,9 @@
  * `context::acceptance-spec` ticket is linked to the Epic. The ticket's
  * GitHub state (open / closed) is **not** checked — presence is
  * sufficient, matching the PRD and Tech Spec contract. The reviewer's
- * OK during /epic-plan Phase 7 is the approval signal, not a manual
+ * OK during /plan Phase 7 is the approval signal, not a manual
  * ticket-close action. This still refuses to launch Epics that skipped
- * the /epic-plan Phase 7 acceptance-spec authoring step (or didn't
+ * the /plan Phase 7 acceptance-spec authoring step (or didn't
  * waive), surfacing the gap at delivery time rather than letting Story
  * dispatch race ahead without a spec at all.
  */
@@ -66,8 +66,8 @@ export async function runSnapshotPhase(ctx, collaborators, state) {
 /**
  * Enumerate the Story IDs owned by an Epic. Delegates to
  * `discoverOpenStories` so the snapshot.end payload and the wave DAG
- * input set never disagree — both now walk Epic → Feature → Story and
- * exclude closed reverse-referenced tickets.
+ * input set never disagree — both enumerate the Epic's direct Story
+ * children and exclude closed reverse-referenced tickets.
  *
  * Returns a sorted array of positive integers (sort order makes the
  * ledger record deterministic across runs and platform iteration
@@ -82,7 +82,7 @@ async function discoverStoryIds({ epicId, provider }) {
 }
 
 /**
- * Refuse to launch /epic-deliver when the acceptance-spec precondition has
+ * Refuse to launch /deliver when the acceptance-spec precondition has
  * not been satisfied. Throws a clear `Error` (per
  * orchestration-error-handling rule) so the `runAsCli` boundary maps it to
  * `process.exit(1)` with the operator-visible message intact.
@@ -104,7 +104,7 @@ function assertAcceptanceSpecGate({ epic, epicId }) {
   if (!acceptanceSpecId) {
     throw new Error(
       `[epic-deliver] Epic #${epicId} cannot launch: no context::acceptance-spec is linked and the acceptance::n-a waiver label is absent. ` +
-        'Run /epic-plan Phase 7 to author an acceptance-spec, or apply the acceptance::n-a label to the Epic to opt out.',
+        'Run /plan Phase 7 to author an acceptance-spec, or apply the acceptance::n-a label to the Epic to opt out.',
     );
   }
 }

package/.agents/scripts/lib/orchestration/epic-runner/progress-reporter/composition.js

@@ -240,7 +240,7 @@ export async function renderProgressBody({
 /**
  * Render and upsert the rolled-up `epic-run-progress` comment on the Epic.
  *
- * Called by `/epic-deliver` Step 2b (`epic-execute-record-wave.js`) after
+ * Called by `/deliver` Step 2b (`epic-execute-record-wave.js`) after
  * each wave completes. The caller folds `state.waves[]` from the
  * `epic-run-state` checkpoint into the per-wave rows and persists the
  * unified rollup as a fenced-JSON payload on the Epic ticket via

package/.agents/scripts/lib/orchestration/epic-runner/progress-reporter/signals.js

@@ -29,7 +29,7 @@ export const PHASE_TIMINGS_TYPE = 'phase-timings';
 
 /**
  * Structured-comment kind for the per-Story run-progress snapshot that
- * `/story-deliver` upserts on every Task transition. Read by
+ * `/deliver` upserts on every Task transition. Read by
  * ProgressReporter so the Epic-level table reflects sub-agent state in
  * near-real time instead of label-derived classifications.
  */
@@ -91,7 +91,7 @@ export function phaseToState(phase) {
 }
 
 /**
- * Parse a `story-run-progress` structured comment posted by `/story-deliver`.
+ * Parse a `story-run-progress` structured comment posted by `/deliver`.
  * Returns `null` for any malformed body — the caller falls back to the
  * ticket-label state derivation in that case.
  *

package/.agents/scripts/lib/orchestration/epic-runner/progress-reporter/transport.js

@@ -1,6 +1,6 @@
 /**
  * progress-reporter/transport.js — outbound I/O for the
- * `/epic-deliver` progress narrative.
+ * `/deliver` progress narrative.
  *
  * Extracted from the parent `progress-reporter.js` so the
  * GitHub-comment posting surface (in `composition.js`) and the
@@ -16,7 +16,7 @@
  *
  * The webhook events emitted from this module are:
  *
- *   - `epic-started`  — fired once at /epic-deliver kickoff
+ *   - `epic-started`  — fired once at /deliver kickoff
  *   - `epic-progress` — fired at wave boundaries / blocker transitions
  *   - `epic-blocked`  — wave aggregated to blocked/failed outside halt path
  *   - `epic-unblocked` — operator flipped back to executing
@@ -118,7 +118,7 @@ export async function emitEpicProgress({
 }
 
 /**
- * Fire a curated `epic-started` webhook event at /epic-deliver kickoff.
+ * Fire a curated `epic-started` webhook event at /deliver kickoff.
  * The Slack consumer anchors the rest of the epic narrative to this fire.
  * Failures are swallowed.
  */
@@ -157,7 +157,7 @@ export async function emitEpicStarted({
 /**
  * Fire a curated `epic-blocked` webhook event when a wave aggregates to
  * `blocked` or `failed` outside the `BlockerHandler.halt` code path (the
- * /epic-deliver host-LLM loop has no handler instance — it calls this
+ * /deliver host-LLM loop has no handler instance — it calls this
  * helper directly from `epic-execute-record-wave.js`). The payload shape
  * matches the inline emit in `BlockerHandler.halt` so downstream consumers
  * see one canonical envelope regardless of which entry point fired.

package/.agents/scripts/lib/orchestration/epic-runner/story-launcher.js

@@ -5,10 +5,10 @@
  * After Story #908, in-session Agent-tool fan-out replaces the subprocess
  * spawn pipeline. The launcher's primary responsibility is `planWave(stories)`:
  * given a wave's Story tickets it returns a stable list of
- * `{ storyId, worktree }` entries. The `/epic-deliver` skill consumes that
+ * `{ storyId, worktree }` entries. The `/deliver` skill consumes that
  * list (one wave at a time) to format one assistant turn containing N
  * parallel `Agent` tool calls (subagent_type `general-purpose`), each of
- * which drives `/story-deliver <storyId>` for one Story.
+ * which drives `/deliver <storyId>` for one Story.
  *
  * `launchWave(stories)` is a convenience for callers that already hold a
  * concrete dispatch adapter (tests, future programmatic harnesses). It calls
@@ -46,7 +46,7 @@ export class StoryLauncher {
 
   /**
    * Produce the dispatch plan for a wave. Pure: no side effects, no IO. The
-   * caller (the `/epic-deliver` skill's wave loop, or `launchWave` below)
+   * caller (the `/deliver` skill's wave loop, or `launchWave` below)
    * decides what to do with the plan.
    *
    * @param {Array<number|{id?:number,storyId?:number,number?:number}>} stories
@@ -78,7 +78,7 @@ export class StoryLauncher {
   async launchWave(stories, signal) {
     if (typeof this.dispatch !== 'function') {
       throw new TypeError(
-        'StoryLauncher.launchWave requires a dispatch adapter (in-session Agent-tool fan-out is the responsibility of the /epic-deliver skill).',
+        'StoryLauncher.launchWave requires a dispatch adapter (in-session Agent-tool fan-out is the responsibility of the /deliver skill).',
       );
     }
     const plan = this.planWave(stories);

package/.agents/scripts/lib/orchestration/epic-runner/story-run-progress-writer.js

@@ -12,7 +12,7 @@
  * removed.
  *
  * The renderer survives because its `{ body, payload }` output still feeds
- * two non-comment contracts: the `renderedBody` markdown the `/story-deliver`
+ * two non-comment contracts: the `renderedBody` markdown the `/deliver`
  * and `single-story-deliver` CLIs (`story-phase.js`, the inline `story-init.js` prepare step)
  * relay to chat so the operator sees the phase table inline, and the snapshot
  * payload returned in those CLIs' JSON envelopes. `upsertStoryRunProgress`
@@ -71,10 +71,10 @@ const PHASE_EMOJI = {
 };
 
 /**
- * Canonical 3-tier Story-phase order. The Story-phase snapshot replaces the
+ * Canonical 2-tier Story-phase order. The Story-phase snapshot replaces the
  * 4-tier per-Task list when the Story carries inline acceptance (no child
  * Tasks). Each entry tracks `status` + `startedAt` / `endedAt` so the parent
- * `/epic-deliver` aggregator can render a coarse progress bar without
+ * `/deliver` aggregator can render a coarse progress bar without
  * walking Task tickets.
  */
 export const STORY_PHASE_ORDER = ['init', 'implement', 'validate', 'close'];
@@ -89,7 +89,7 @@ const STORY_PHASE_STATUS_EMOJI = {
 
 /**
  * Build the canonical default `phases[]` array for a freshly-initialized
- * 3-tier Story snapshot. All entries are `pending`; timestamps are null.
+ * 2-tier Story snapshot. All entries are `pending`; timestamps are null.
  * Exported so call sites (the story-init prepare step, story-phase) and
  * tests can build the same shape without re-implementing it.
  *
@@ -175,7 +175,7 @@ function normalizeTask(task) {
  * Exported so tests can pin the rendered shape without going through the
  * upsert path.
  *
- * Two shapes are supported, selected by whether `input.phases` (3-tier
+ * Two shapes are supported, selected by whether `input.phases` (2-tier
  * Story-phase snapshot) or `input.tasks` (legacy 4-tier per-Task list) is
  * provided. Callers MUST pass exactly one of the two — passing both is
  * rejected as a contract violation so a mistake at the call site fails
@@ -216,7 +216,7 @@ export function renderStoryRunProgressBody(input) {
   const hasTasks = Array.isArray(input.tasks);
   if (hasPhases && hasTasks) {
     throw new TypeError(
-      'renderStoryRunProgressBody: pass either `phases` (3-tier) or `tasks` ' +
+      'renderStoryRunProgressBody: pass either `phases` (2-tier) or `tasks` ' +
         '(4-tier), not both — the snapshot shape is mutually exclusive.',
     );
   }
@@ -296,7 +296,7 @@ function renderTasksBody({
 }
 
 /**
- * Render the 3-tier Story-phase body. Pure helper for
+ * Render the 2-tier Story-phase body. Pure helper for
  * `renderStoryRunProgressBody`. Emits a `phases[]` payload whose entries
  * carry `{ name, status, startedAt, endedAt }` for init/implement/validate/close.
  */
@@ -351,7 +351,7 @@ function renderPhasesBody({ storyId, branch, phase, phases: raw, updatedAt }) {
  * renders only and, when `notify` is supplied, mirrors a low-severity webhook
  * event for operators who wire one up.
  *
- * Two shapes are supported, selected by whether `args.phases` (3-tier
+ * Two shapes are supported, selected by whether `args.phases` (2-tier
  * Story-phase snapshot) or `args.tasks` (legacy 4-tier per-Task list) is
  * provided. The webhook mirror's `done/total` count is computed from whichever
  * shape is active.

package/.agents/scripts/lib/orchestration/epic-runner/sub-agent-return.js

@@ -1,9 +1,9 @@
 /**
  * sub-agent-return.js — parse and reconcile per-Story sub-agent return text.
  *
- * `/epic-deliver` Step 2 dispatches one `Agent` tool call per Story per
+ * `/deliver` Step 2 dispatches one `Agent` tool call per Story per
  * wave. Each sub-agent owes its parent the JSON return contract documented
- * in `.agents/workflows/epic-deliver.md`:
+ * in `.agents/workflows/helpers/deliver-epic.md`:
  *
  *   {
  *     "storyId": <number>,
@@ -27,7 +27,7 @@
  * directly to GitHub-state reconciliation plus a friction record — the
  * stronger backstop that already caught everything the heuristics caught.
  *
- * This module provides the two helpers `/epic-deliver`'s wave dispatcher
+ * This module provides the two helpers `/deliver`'s wave dispatcher
  * now uses:
  *
  *   - `parseStoryAgentReturn(raw)` — accept an already-parsed object or a
@@ -257,7 +257,7 @@ export function renderMalformedReturnsFriction({ epicId, wave, failures }) {
     '',
     `**Reason:** \`malformed-subagent-return\``,
     '',
-    `${failures.length} sub-agent return(s) did not match the /story-deliver return contract.`,
+    `${failures.length} sub-agent return(s) did not match the /deliver return contract.`,
     'Each Story below was reconciled from GitHub (labels + `story-run-progress`)',
     'and its wave-row downgraded to `failed` unless the live ticket already carried',
     '`agent::done`.',

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-apply.js

@@ -730,21 +730,13 @@ function collectStructuralEdges(spec) {
   const out = {};
   if (!spec || typeof spec !== 'object') return out;
   const epicSlug = 'epic';
-  for (const feature of spec.features ?? []) {
-    if (!feature?.slug) continue;
-    out[feature.slug] = { entity: 'feature', parentSlug: epicSlug };
-    for (const story of feature.stories ?? []) {
-      if (!story?.slug) continue;
-      out[story.slug] = {
-        entity: 'story',
-        parentSlug: feature.slug,
-        dependsOn: [...(story.dependsOn ?? [])].sort(),
-      };
-      for (const task of story.tasks ?? []) {
-        if (!task?.slug) continue;
-        out[task.slug] = { entity: 'task', parentSlug: story.slug };
-      }
-    }
+  for (const story of spec.stories ?? []) {
+    if (!story?.slug) continue;
+    out[story.slug] = {
+      entity: 'story',
+      parentSlug: epicSlug,
+      dependsOn: [...(story.dependsOn ?? [])].sort(),
+    };
   }
   return out;
 }

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-diff.js

@@ -18,12 +18,12 @@
  *
  * @typedef {object} SpecInput
  *   The parsed YAML returned by `lib/spec/loader.js#loadSpec`. Shape is
- *   `{ epic: {...}, features: [{slug, stories: [...]}], gates?: {...} }`
+ *   `{ epic: {...}, stories: [...], gates?: {...} }`
  *   per `.agents/schemas/epic-spec.schema.json`.
  *
  * @typedef {object} StateMappingEntry
  * @property {number} issueNumber          GH issue number this slug maps to.
- * @property {string} entity               'epic'|'feature'|'story'|'task'.
+ * @property {string} entity               'epic'|'story'.
  * @property {string} [contentHash]        Content hash captured at last
  *                                         reconcile; absence forces an
  *                                         update when ghState carries
@@ -115,7 +115,7 @@ function labelsEqual(a, b) {
  * a naive replace-style label diff would propose removing operator-
  * managed metadata that lives in these namespaces.
  *
- * Why: Story #2056 / Epic #1994 — `/epic-plan` was silently stripping
+ * Why: Story #2056 / Epic #1994 — `/plan` was silently stripping
  * `type::epic` and `risk::*` from the parent Epic on every decompose,
  * which then broke `dispatcher.js` (`type "unknown"`). Defence-in-depth
  * lives here in the diff engine: even if a future spec author drops
@@ -133,7 +133,7 @@ const PROTECTED_EPIC_LABEL_NAMESPACES = Object.freeze([
   'risk::',
   // Story #3050 — `acceptance::*` is set by Phase 7 spec-persist when
   // `planningRisk.acceptanceDisposition='not-applicable'` (or another
-  // disposition) and gates downstream `/epic-deliver` start/finalize
+  // disposition) and gates downstream `/deliver` start/finalize
   // behavior. Before this namespace was protected, Phase 8 decompose
   // diffed the Epic's labels against a spec entry that doesn't carry
   // `acceptance::*`, silently emitting an Update that stripped the
@@ -190,7 +190,7 @@ function normaliseBody(value) {
  * duplicate footer blocks and trailing `blocked by` lines are removed in
  * a single pass. Kept local to this module so the diff engine does not
  * depend on the Task-body renderer (Story #3185 / Epic #3163: the renderer
- * is going away with the 3-tier producer cutover).
+ * is going away with the 2-tier producer cutover).
  */
 const ORCHESTRATOR_FOOTER_RE = /\n?---[ \t]*\r?\n+parent:\s*#\d+[\s\S]*$/;
 
@@ -247,9 +247,8 @@ function renderFooter({ parentId, epicId, dependencies = [] }) {
  * `parent: #N` / `Epic: #M` / `blocked by #X` and breaking the cascade.
  *
  * Story #3185 — the footer compose/strip logic is inlined here rather
- * than reused from the legacy Task-body renderer module. Under the
- * 3-tier hierarchy (Epic → Feature → Story) that renderer is being
- * removed, so the diff engine carries its own footer shape. The shape
+ * than reused from the legacy Task-body renderer module. That renderer
+ * was removed, so the diff engine carries its own footer shape. The shape
  * is byte-identical to the legacy renderer's `parent: #<n>` /
  * `Epic: #<m>` / `blocked by #<x>` output so cascade-readers continue
  * to parse it unchanged.
@@ -326,7 +325,7 @@ function fieldChanges(specEntity, obs, mapping, ctx = {}) {
   // feature/story/task body fields): "When omitted, the GH issue body
   // is left untouched". Pre-Story-#2283 the engine treated `undefined`
   // as `""`, which emitted a destructive `body: <existing> → ""` Update
-  // on every `/epic-plan` Phase 8 because the decomposer's renderer
+  // on every `/plan` Phase 8 because the decomposer's renderer
   // projects the Epic spec entry from `{ id, title }` only. Skip the
   // body diff entirely when the spec did not carry a body string. An
   // explicit `body: ""` in the spec still produces a clear-op when the
@@ -413,9 +412,8 @@ function sortBySlug(ops) {
 
 /**
  * Walk the spec and yield one structural-entity record per visited
- * node. The walker is iterative-via-recursion but bounded by the spec's
- * nesting (epic → features → stories → tasks); the depth never exceeds
- * 4 so an explicit work-queue would just obscure the shape.
+ * node. The spec is 2-tier (epic → stories), so the walk is a single
+ * flat pass over `spec.stories` after the Epic record.
  *
  * @param {SpecInput} spec
  * @returns {Array<{
@@ -446,37 +444,35 @@ function flattenSpec(spec) {
   }
 
   const epicAnchor = spec.epic ? epicSlug(spec.epic) : null;
-  for (const feature of spec.features ?? []) {
+  // Duplicate-slug guard. The schema cannot express slug uniqueness across
+  // a hand-edited spec, and two same-slug Creates would orphan one GH
+  // issue (the second create overwrites the first's mapping entry).
+  // flattenSpec is the chokepoint both the loader path and the diff path
+  // flow through, so the check lives here.
+  const seenSlugs = new Set();
+  const duplicateSlugs = new Set();
+  for (const story of spec.stories ?? []) {
+    if (seenSlugs.has(story.slug)) duplicateSlugs.add(story.slug);
+    seenSlugs.add(story.slug);
+  }
+  if (duplicateSlugs.size > 0) {
+    throw new Error(
+      `spec contains duplicate story slug(s): ${[...duplicateSlugs].join(', ')}. ` +
+        `Each story slug must be unique — rename the duplicated entries in ` +
+        `the spec and re-run.`,
+    );
+  }
+  for (const story of spec.stories ?? []) {
     out.push({
-      slug: feature.slug,
-      entity: ENTITY_KINDS.FEATURE,
-      title: String(feature.title ?? ''),
-      body: feature.body,
-      labels: feature.labels,
+      slug: story.slug,
+      entity: ENTITY_KINDS.STORY,
+      title: String(story.title ?? ''),
+      body: story.body,
+      labels: story.labels,
+      wave: story.wave,
       parentSlug: epicAnchor,
+      dependsOn: story.dependsOn ?? [],
     });
-    for (const story of feature.stories ?? []) {
-      out.push({
-        slug: story.slug,
-        entity: ENTITY_KINDS.STORY,
-        title: String(story.title ?? ''),
-        body: story.body,
-        labels: story.labels,
-        wave: story.wave,
-        parentSlug: feature.slug,
-        dependsOn: story.dependsOn ?? [],
-      });
-      for (const task of story.tasks ?? []) {
-        out.push({
-          slug: task.slug,
-          entity: ENTITY_KINDS.TASK,
-          title: String(task.title ?? ''),
-          body: task.body,
-          labels: task.labels,
-          parentSlug: story.slug,
-        });
-      }
-    }
   }
   return out;
 }
@@ -509,6 +505,40 @@ function dependsOnEqual(a, b) {
   return labelsEqual(a, b);
 }
 
+/**
+ * Entity kinds that only exist in pre-v4 (3-tier) state files. The v4
+ * hard cutover (v1.60.0) removed the Feature/Task tiers; encountering one
+ * of these in `state.mapping` means the state file predates the cutover
+ * and must be migrated by the operator — there is deliberately no legacy
+ * close-op support (hard-cutover policy, git-conventions.md).
+ */
+const LEGACY_ENTITY_KINDS = Object.freeze(new Set(['feature', 'task']));
+
+/**
+ * Throw a loud, actionable error when the state mapping carries legacy
+ * Feature/Task entries. Raised early in `diff()` so the operator sees a
+ * migration instruction instead of `unknown entity kind: feature` from
+ * deep inside `closeOp`.
+ *
+ * @param {Record<string, StateMappingEntry>} mapping
+ */
+function assertNoLegacyEntities(mapping) {
+  const legacy = Object.entries(mapping).filter(([, entry]) =>
+    LEGACY_ENTITY_KINDS.has(entry?.entity),
+  );
+  if (legacy.length === 0) return;
+  const summary = legacy
+    .map(([slug, entry]) => `${slug} (#${entry.issueNumber}, ${entry.entity})`)
+    .join(', ');
+  throw new Error(
+    `diff: the epic state file is pre-v4 — it carries legacy Feature/Task ` +
+      `mapping entries: ${summary}. The 2-tier reconciler cannot process ` +
+      `these. Close the legacy Feature issues manually, then delete (or ` +
+      `reseed) the .agents/epics/<epicId>.state.json file per the v1.60.0 ` +
+      `migration notes, and re-run.`,
+  );
+}
+
 /**
  * Diff `(spec, state, ghState)` into a `Plan`. See the module header for
  * the full contract.
@@ -523,6 +553,7 @@ export function diff({ spec, state, ghState } = {}) {
     throw new TypeError('diff: state argument is required');
   }
   const mapping = state.mapping ?? {};
+  assertNoLegacyEntities(mapping);
   const seenSpecSlugs = new Set();
 
   for (const entity of flattenSpec(spec)) {
@@ -595,7 +626,7 @@ export function diff({ spec, state, ghState } = {}) {
     plan.closes.push(
       closeOp({
         slug,
-        entity: mapped.entity ?? ENTITY_KINDS.TASK,
+        entity: mapped.entity ?? ENTITY_KINDS.STORY,
         issueNumber: mapped.issueNumber,
         title: mapped.title,
       }),

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-ops.js

@@ -44,7 +44,7 @@
  * apply pipeline. Arrays are always present (never undefined); an empty
  * plan has all four arrays at length 0.
  *
- * @typedef {'epic'|'feature'|'story'|'task'} EntityKind
+ * @typedef {'epic'|'story'} EntityKind
  *   The structural entity kind. Matches schema $defs — agent-execution
  *   labels (agent::*) are owned by the wave-runner and never appear in
  *   the structural surface.
@@ -87,7 +87,7 @@
  * @typedef {object} RelinkOp
  * @property {'relink'} kind
  * @property {string}   slug
- * @property {EntityKind} entity     'story' (dependsOn) or 'feature'|'story'|'task' (parent).
+ * @property {EntityKind} entity     'story' (dependsOn / parent).
  * @property {number}   issueNumber
  * @property {{ before: string|null, after: string|null }} [parent]
  *   Parent slug change. `null` on either side means "no parent" (epic
@@ -117,9 +117,7 @@ export const OP_KINDS = Object.freeze({
 /** Entity-kind discriminator values, matching the schema $defs. */
 export const ENTITY_KINDS = Object.freeze({
   EPIC: 'epic',
-  FEATURE: 'feature',
   STORY: 'story',
-  TASK: 'task',
 });
 
 const VALID_OP_KINDS = new Set(Object.values(OP_KINDS));