mandrel 1.59.0 → 1.60.0

package/.agents/scripts/stories-wave-tick.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 /**
- * stories-wave-tick.js — DAG/wave engine for the top-level /story-deliver workflow.
+ * stories-wave-tick.js — DAG/wave engine for the top-level /deliver workflow.
  *
  * Consumes an operator-supplied dependency DAG of standalone Story IDs and
  * emits ordered execution waves. Analogous to wave-tick.js but for standalone
@@ -26,11 +26,11 @@
  *   }
  *
  * The per-wave concurrency cap is resolved from the same config seam
- * `/epic-deliver` uses — `resolveConfig` + `getRunners` reading
+ * `/deliver` uses — `resolveConfig` + `getRunners` reading
  * `delivery.deliverRunner.concurrencyCap` (default 3) — so a
  * `.agentrc.local.json` override is honored. A `--concurrency <n>` CLI flag
  * overrides the config-resolved value for that run only. This puts both the
- * standalone (`/story-deliver`) and Epic (`/epic-deliver`) delivery paths on
+ * standalone (`/deliver`) and Epic (`/deliver`) delivery paths on
  * one deterministic config source.
  *
  * On cycle detection, exits with code 2 and sets cycleError in the envelope.
@@ -149,7 +149,7 @@ export function buildAdjacency(nodes) {
 /**
  * Resolve the per-wave concurrency cap.
  *
- * Mirrors the `/epic-deliver` seam (`epic-deliver-prepare.js`): resolve the
+ * Mirrors the `/deliver` seam (`epic-deliver-prepare.js`): resolve the
  * project config (which deep-merges `.agentrc.local.json` over `.agentrc.json`)
  * then read `delivery.deliverRunner.concurrencyCap` via `getRunners` (default
  * 3). An explicit `override` (the `--concurrency <n>` CLI flag) wins over
@@ -177,7 +177,7 @@ export function resolveConcurrencyCap({ cwd, config, override } = {}) {
  *
  * Uses detectCycle from Graph.js to validate the DAG before computing
  * layers via assignLayers. Returns the wave envelope, carrying the resolved
- * per-wave `concurrencyCap` so the `/story-deliver` workflow dispatches
+ * per-wave `concurrencyCap` so the `/deliver` workflow dispatches
  * `min(wave.stories.length, concurrencyCap)` from a deterministic field rather
  * than from recalled prose.
  *

package/.agents/scripts/story-close.js

@@ -22,7 +22,7 @@
  *   1  error
  *   2  prior-state (pass --resume / --restart) OR preflight refused
  *
- * @see .agents/workflows/story-deliver.md
+ * @see .agents/workflows/helpers/deliver-stories.md
  */
 
 import { runAsCli } from './lib/cli-utils.js';

package/.agents/scripts/story-init.js

@@ -15,7 +15,7 @@
  *   5. branch-initializer   — materialise the story branch (single-tree
  *                             checkout or isolated worktree).
  *   6. state-transitioner   — flip the Story to `agent::executing`. Under
- *                             the 3-tier hierarchy the Story has inline
+ *                             the 2-tier hierarchy the Story has inline
  *                             acceptance and no child Task lifecycle.
  *
  * Usage:
@@ -25,7 +25,7 @@
  *   0 — Initialization complete. Agent can start implementation.
  *   1 — Blocked or error (details in stderr).
  *
- * @see .agents/workflows/story-deliver.md
+ * @see .agents/workflows/helpers/deliver-stories.md
  */
 
 import path from 'node:path';
@@ -141,7 +141,7 @@ export async function runStoryInit({
   progress('INIT', `Initializing Story #${storyId}...`);
 
   // Stage 1 — context.
-  const { story, body, epicId, featureId } = await resolveContext({
+  const { story, body, epicId, parentId } = await resolveContext({
     provider,
     logger: stageLogger,
     input: { storyId, recutOf, dryRun },
@@ -154,10 +154,7 @@ export async function runStoryInit({
     input: { epicId },
   });
 
-  progress(
-    'CONTEXT',
-    `Epic: #${epicId}, Feature/Parent: #${featureId ?? 'none'}`,
-  );
+  progress('CONTEXT', `Epic: #${epicId}, Parent: #${parentId ?? 'none'}`);
   progress(
     'CONTEXT',
     `PRD: #${prdId ?? 'none'}, Tech Spec: #${techSpecId ?? 'none'}`,
@@ -192,8 +189,8 @@ export async function runStoryInit({
     progress('BLOCKERS', '✅ All blockers resolved');
 
   // Stage 4 — task graph. Pass the Story body so buildTaskGraph can detect
-  // the inline-acceptance 3-tier shape. After Task #3154 collapsed the
-  // hierarchy flag, 3-tier is the only supported shape.
+  // the inline-acceptance 2-tier shape. After Task #3154 collapsed the
+  // hierarchy flag, 2-tier is the only supported shape.
   const { sortedTasks, mode: hierarchyMode } = await buildTaskGraph({
     provider,
     logger: stageLogger,
@@ -327,7 +324,7 @@ export async function runStoryInit({
     worktreeCreated,
     installStatus,
     sortedTasks,
-    featureId,
+    parentId,
     prdId,
     techSpecId,
     dryRun,
@@ -500,7 +497,7 @@ function buildStoryInitResult({
   worktreeCreated,
   installStatus,
   sortedTasks,
-  featureId,
+  parentId,
   prdId,
   techSpecId,
   dryRun,
@@ -514,11 +511,11 @@ function buildStoryInitResult({
     storyBranch,
     epicBranch,
     storyTitle: story.title,
-    // Hierarchy mode resolved by buildTaskGraph. 3-tier is the only
+    // Hierarchy mode resolved by buildTaskGraph. 2-tier is the only
     // supported shape after Task #3154 deleted the `planning.hierarchy`
     // flag; this is retained as a constant marker for downstream
     // consumers and persisted artefacts.
-    hierarchy: hierarchy ?? '3-tier',
+    hierarchy: hierarchy ?? '2-tier',
     worktreeEnabled,
     workCwd,
     worktreeCreated,
@@ -534,7 +531,7 @@ function buildStoryInitResult({
       labels: t.labels,
       dependencies: t.dependsOn ?? parseBlockedBy(t.body ?? ''),
     })),
-    context: { featureId, prdId, techSpecId },
+    context: { parentId, prdId, techSpecId },
     dryRun,
   };
 }
@@ -591,10 +588,10 @@ export function renderStoryInitCommentBody(result) {
     epicId: result.epicId,
     storyBranch: result.storyBranch,
     epicBranch: result.epicBranch,
-    // Hierarchy mode is always `'3-tier'` after Task #3154 deleted the
+    // Hierarchy mode is always `'2-tier'` after Task #3154 deleted the
     // `planning.hierarchy` flag. Persisted so resumed runs can read it
     // without re-resolving anything in the worker.
-    hierarchy: result.hierarchy ?? '3-tier',
+    hierarchy: result.hierarchy ?? '2-tier',
     worktreeEnabled: result.worktreeEnabled,
     workCwd: result.workCwd,
     worktreeCreated: result.worktreeCreated,

package/.agents/scripts/story-phase.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 
 /**
- * story-phase.js — phase snapshot + heartbeat writer (3-tier).
+ * story-phase.js — phase snapshot + heartbeat writer (2-tier).
  *
  * Replaces the deleted per-Task progress writer from the 4-tier era
- * (removed under #3157). `/story-deliver` calls this CLI at each Story-
+ * (removed under #3157). `/deliver` calls this CLI at each Story-
  * level phase transition (init → implementing → closing → done, or any
  * → blocked). Each call:
  *
@@ -14,7 +14,7 @@
  *      longer posts a `story-run-progress` comment (the redundant mid-flight
  *      progress surface was deleted); the snapshot is render-only.
  *   2. Appends one `story.heartbeat` lifecycle record to
- *      `temp/epic-<epicId>/lifecycle.ndjson` so `/epic-deliver`'s
+ *      `temp/epic-<epicId>/lifecycle.ndjson` so `/deliver`'s
  *      §2e Idle Watchdog (`wave-tick.js --check-idle 30`) can confirm
  *      forward progress without polling the Story comment.
  *
@@ -35,7 +35,7 @@
  *
  * `renderedBody` is the markdown body upserted onto the Story so the
  * caller can relay it to chat verbatim (mirrors the contract the deleted
- * per-Task progress writer exposed and that `/story-deliver` Step 1 / 3
+ * per-Task progress writer exposed and that `/deliver` Step 1 / 3
  * already documents).
  */
 
@@ -175,7 +175,7 @@ async function resolveStoryBranch({ provider, storyId }) {
  * lease-owner handle the SAME way the lease primitive does
  * (`normalizeOperatorHandle(github.operatorHandle)`) and stamps it as
  * `operator` so `latestHeartbeatForOwner({ epicId, owner })` resolves a real
- * heartbeat — without it `isClaimLive(null)` is false and /epic-deliver
+ * heartbeat — without it `isClaimLive(null)` is false and /deliver
  * silently reclaims a live foreign claim (audit #3513). The field is attached
  * only when a handle resolves, preserving the "omit when absent" shape for
  * repos that have not configured `github.operatorHandle`. A failed append is

package/.agents/scripts/story-plan.js

@@ -2,9 +2,9 @@
 /* node:coverage ignore file */
 
 /**
- * story-plan.js — Local `/story-plan` wrapper.
+ * story-plan.js — Local `/plan` wrapper.
  *
- * Standalone counterpart to `/epic-plan` for Stories that do **not**
+ * Standalone counterpart to `/plan` for Stories that do **not**
  * attach to an Epic. The script is deliberately a thin CLI around the
  * pure helpers in `lib/story-plan.js`:
  *
@@ -24,7 +24,7 @@
  *      GitHub. Echoes the rendered body and the `gh` argv it would
  *      have run.
  *
- * Mirrors the `/epic-plan` pattern: deterministic Node I/O wrappers
+ * Mirrors the `/plan` pattern: deterministic Node I/O wrappers
  * with HITL gating handled by the host LLM in chat. No external LLM
  * APIs are called from this script.
  */

package/.agents/scripts/sync-branch-from-base.js

@@ -6,7 +6,7 @@
  *
  * Use this from workflow markdown when the operator needs to sync a
  * working branch with `origin/<baseBranch>` before opening a PR — for
- * example as a pre-Phase-6 step in `/epic-deliver` so the Epic→main PR
+ * example as a pre-Phase-6 step in `/deliver` so the Epic→main PR
  * opens with the latest `main` commits already integrated.
  *
  * For `/single-story-deliver`, the sync runs in-process inside

package/.agents/scripts/validate-docs-freshness.js

@@ -201,7 +201,7 @@ export function renderFreshnessFailureMessage(epicId) {
   return (
     `[docs-freshness] ❌ Documentation freshness gate FAILED for Epic #${epicId}.\n\n` +
     `Update each failing file so its commit message or body references #${epicId}, ` +
-    `then re-run /epic-deliver.`
+    `then re-run /deliver.`
   );
 }
 

package/.agents/scripts/wave-tick.js

@@ -6,7 +6,7 @@
  *
  * Reads the `epic-run-state` checkpoint plus fresh Story labels and
  * prints one `WaveTickResult` envelope. The slash-command operator
- * (`/epic-deliver`) consumes the envelope to decide whether to dispatch
+ * (`/deliver`) consumes the envelope to decide whether to dispatch
  * the next wave, observe in-flight stories, or finalize the Epic.
  *
  * Usage:

package/.agents/skills/core/analyze-execution/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Aggregate per-Story or per-Epic execution signals into a structured
   perf-summary or perf-report and upsert it onto the corresponding GitHub
   ticket. Use after a Story closes (Story mode) or as part of
-  `/epic-deliver` Phase 6 (Epic mode). Reads NDJSON via
+  `/deliver` Phase 6 (Epic mode). Reads NDJSON via
   `lib/signals/read` and writes a single structured comment.
 allowed_tools:
   - Read
@@ -36,7 +36,7 @@ into the Epic dashboard.
   pipeline dispatches this Skill (or the wrapping script) to roll up the
   Story's NDJSON signals into a single `<!-- structured:story-perf-summary -->`
   marker comment on the Story ticket.
-- **Epic mode** — during `/epic-deliver` Phase 6.0 (or the retro
+- **Epic mode** — during `/deliver` Phase 6.0 (or the retro
   composer), the Skill fans out across every Story under the Epic,
   reads each Story's structured perf summary, and posts a single
   `<!-- structured:epic-perf-report -->` marker on the Epic ticket.

package/.agents/skills/core/epic-plan-consolidate/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: epic-plan-consolidate
 description: >-
-  Run a holistic, pre-persist consolidation pass over the draft Feature/Story
+  Run a holistic, pre-persist consolidation pass over the draft Story
   ticket array an Epic's decompose phase produced. Use during Phase 8 of
-  `/epic-plan`, after `epic-plan-decompose-author` writes
+  `/plan`, after `epic-plan-decompose-author` writes
   `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js`
   validates and persists it. Reconciles the draft against the Tech Spec
   "Delivery Slicing" target via scope-preserving operations only.
@@ -19,13 +19,12 @@ allowed_tools:
 
 - Run only after `epic-plan-decompose-author` has written `temp/epic-<Epic_ID>/tickets.json`; fail loudly if the draft array is missing. Read the PRD / Tech Spec from `temp/epic-<Epic_ID>/decomposer-context.json` (the same envelope the author skill consumed) — never re-fetch from GitHub, and never call the GitHub API from this Skill.
 - Emit exactly two artifacts inside `temp/epic-<Epic_ID>/`: the **consolidated** `tickets.json` (overwriting the draft array in place) and a human-readable `consolidation-report.md` (the rationale + before/after diff the operator reviews at the HITL gate). Both MUST exist before returning.
-- **Scope conservation is the load-bearing invariant.** You are a *critic*, not a second author: you MUST NOT add scope, invent tickets, or drop acceptance criteria. Every acceptance item and every `verify` entry present in the draft MUST survive into the consolidated array (possibly re-homed onto a merged Story). **This is your contract, not a machine guarantee:** there is **no runtime acceptance-union diff** on your output. The only deterministic runtime backstop the validator applies after you run is `assertNoSingleStoryFeature` (Story #3777) plus the standard ticket-structure validation — neither re-derives the pre-consolidation acceptance/verify union, so a critic that silently dropped an acceptance item would **not** be caught downstream. (The repo's unit test exercises a *pure model* of the merge over an over-fragmented fixture to document the intended invariant; it does not inspect this Skill's actual output.) Conserve scope yourself, deliberately, on every merge.
-- Your operations are constrained to exactly four shapes: **(1) merge two or more Stories** into one (union their `changes`/`acceptance`/`verify`/`references`, keep one coherent `goal`); **(2) collapse a single-Story Feature** into a sibling Feature (re-parent its lone Story, drop the empty Feature) — **never** by manufacturing a second Story; **(3) re-parent** a Story to a different sibling Feature; **(4) rewire `depends_on`** so the edges still reference surviving sibling-Story slugs. No other mutation is permitted.
-- Consume the Tech Spec **"Delivery Slicing"** section as the authoritative target grouping when one is present: cluster the draft's Stories toward the N shippable Stories the Architect proposed. When the section is **absent**, degrade gracefully — apply only the cohesion + single-Story-Feature rules below and leave the rest of the draft shape intact.
-- Implement rec #2: resolve every single-Story Feature by **collapsing** it into a sibling (operation 2), not by splitting its lone Story into two. The `assertNoSingleStoryFeature` validator from Story #3777 stays as the post-consolidation backstop — your output must already satisfy it.
+- **Scope conservation is the load-bearing invariant.** You are a *critic*, not a second author: you MUST NOT add scope, invent tickets, or drop acceptance criteria. Every acceptance item and every `verify` entry present in the draft MUST survive into the consolidated array (possibly re-homed onto a merged Story). **This is your contract, not a machine guarantee:** there is **no runtime acceptance-union diff** on your output. The only deterministic runtime backstop the validator applies after you run is the standard ticket-structure validation — it does not re-derive the pre-consolidation acceptance/verify union, so a critic that silently dropped an acceptance item would **not** be caught downstream. (The repo's unit test exercises a *pure model* of the merge over an over-fragmented fixture to document the intended invariant; it does not inspect this Skill's actual output.) Conserve scope yourself, deliberately, on every merge.
+- Your operations are constrained to exactly two shapes: **(1) merge two or more Stories** into one (union their `changes`/`acceptance`/`verify`/`references`, keep one coherent `goal`); **(2) rewire `depends_on`** so the edges still reference surviving sibling-Story slugs. No other mutation is permitted.
+- Consume the Tech Spec **"Delivery Slicing"** section as the authoritative target grouping when one is present: cluster the draft's Stories toward the N shippable Stories the Architect proposed. When the section is **absent**, degrade gracefully — apply only the cohesion rules below and leave the rest of the draft shape intact.
 - Apply the same cohesion heuristic the author skill leads with: **one Story = one coherent change with one reason to exist**, and the **single-consumer merge rule** (a Story whose only consumer is one sibling Story is merged into that sibling). Lead every merge decision with the change's reason, not its file count.
-- After every merge / collapse / re-parent, **rewire `depends_on`**: drop self-edges, collapse edges that now point at the absorbing Story onto itself, and re-point any edge that named a now-deleted slug at its surviving successor. Never leave a `depends_on` referencing a slug absent from the consolidated array — the validator HARD-rejects unknown deps.
-- The consolidation report MUST name each operation applied (merged slugs → surviving slug, collapsed Feature → sibling, re-parented Story, rewired edges) with a one-line reason, plus a before/after Story-count line, so the operator can approve or reject at the HITL diff gate before the persist call.
+- After every merge, **rewire `depends_on`**: drop self-edges, collapse edges that now point at the absorbing Story onto itself, and re-point any edge that named a now-deleted slug at its surviving successor. Never leave a `depends_on` referencing a slug absent from the consolidated array — the validator HARD-rejects unknown deps.
+- The consolidation report MUST name each operation applied (merged slugs → surviving slug, rewired edges) with a one-line reason, plus a before/after Story-count line, so the operator can approve or reject at the HITL diff gate before the persist call.
 
 ## Role
 
@@ -38,7 +37,7 @@ against the Tech Spec's intentional grouping before any GitHub write.
 
 ## When to use
 
-`/epic-plan` Phase 8, as the **8.3 — Holistic Consolidation** sub-step:
+`/plan` Phase 8, as the **8.3 — Holistic Consolidation** sub-step:
 immediately after `epic-plan-decompose-author` writes
 `temp/epic-<Epic_ID>/tickets.json` and **before**
 `epic-plan-decompose.js --tickets …` validates and persists. The pass operates
@@ -51,7 +50,7 @@ emit a plan the validator would reject.
 The dispatcher passes the Epic ID as the Skill argument. The Skill itself
 reads:
 
-- `temp/epic-<Epic_ID>/tickets.json` — the **draft** Feature/Story array the
+- `temp/epic-<Epic_ID>/tickets.json` — the **draft** Story array the
   `epic-plan-decompose-author` Skill wrote. This is the consolidation input.
 - `temp/epic-<Epic_ID>/decomposer-context.json` — the authoring envelope
   emitted by `epic-plan-decompose.js --emit-context`. Read `prd.body` /
@@ -62,7 +61,7 @@ reads:
 ## Outputs
 
 - `temp/epic-<Epic_ID>/tickets.json` — the **consolidated** array, overwriting
-  the draft. Same schema as the author skill emits (Feature → Story; Stories
+  the draft. Same schema as the author skill emits (flat Story array; Stories
   carry top-level `acceptance[]` / `verify[]`; `body` is a serialized string).
   The downstream `epic-plan-decompose.js --tickets …` validator is the final
   gate — author for its rules, not for "looks right."
@@ -83,21 +82,18 @@ anything:
 
 1. The **target grouping** — the N shippable Stories the Architect proposed in
    Delivery Slicing, or `null` when the section is absent (graceful-degrade
-   mode: cohesion + single-Story-Feature rules only).
-2. The **draft Story count per Feature** — so you can spot single-Story
-   Features and over-fragmented capability clusters.
+   mode: cohesion rules only).
+2. The **draft Story count** — so you can spot over-fragmented capability
+   clusters.
 
 ### Step 2 — Plan the consolidation
 
-For each Feature, decide which Stories merge, which collapse, which re-parent:
+Across the draft Story array, decide which Stories merge:
 
-- **Single-Story Feature** → collapse its lone Story into a sibling Feature
-  whose capability is closest (Delivery-Slicing target, else thematic
-  proximity). Drop the now-empty Feature. Never split the lone Story.
 - **Over-fragmented capability** → when several draft Stories map to one
   Delivery-Slicing target (or one coherent reason to exist), merge them into a
   single Story: union their `changes` / `acceptance` / `verify` / `references`,
-  write one `goal` naming the parent Feature, and keep the union of labels.
+  write one coherent `goal`, and keep the union of labels.
 - **Single-consumer Story** → merge into the one sibling that consumes it.
 
 Record each decision with its one-line reason for the report.
@@ -120,7 +116,7 @@ Write the consolidated array to `temp/epic-<Epic_ID>/tickets.json` (2-space
 indent, machine-consumed) and the rationale + before/after diff to
 `temp/epic-<Epic_ID>/consolidation-report.md`.
 
-### Step 5 — Hand back to `/epic-plan`
+### Step 5 — Hand back to `/plan`
 
 Return control. The workflow shows the operator the consolidation report at the
 HITL diff gate; on approval it runs
@@ -133,13 +129,12 @@ persists the hierarchy, and flips the Epic to `agent::ready`.
 - Do **not** call the GitHub API from this Skill. It reads two temp artifacts
   and writes two temp artifacts; persistence belongs to the script.
 - Do **not** write outside `temp/epic-<Epic_ID>/`.
-- Do **not** add scope or invent tickets. The four permitted operations (merge
-  Stories, collapse single-Story Features, re-parent, rewire `depends_on`) are
-  exhaustive — anything else is out of contract.
+- Do **not** add scope or invent tickets. The two permitted operations (merge
+  Stories, rewire `depends_on`) are exhaustive — anything else is out of
+  contract.
 - If `temp/epic-<Epic_ID>/tickets.json` is missing, fail loudly and instruct
   the caller to run the `epic-plan-decompose-author` Skill first.
 - The validator
   ([`lib/orchestration/ticket-validator.js`](../../../scripts/lib/orchestration/ticket-validator.js))
-  is the authoritative post-consolidation gate — including
-  `assertNoSingleStoryFeature`. Re-consolidate when it rejects rather than
-  patching tickets by hand.
+  is the authoritative post-consolidation gate. Re-consolidate when it
+  rejects rather than patching tickets by hand.

package/.agents/skills/core/epic-plan-decompose-author/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: epic-plan-decompose-author
 description: >-
-  Author the Feature/Story ticket JSON for an Epic from the decomposer
+  Author the Story ticket JSON for an Epic from the decomposer
   authoring context emitted by `epic-plan-decompose.js --emit-context`. Use
-  during Phase 8 of `/epic-plan` when the host LLM needs to write the ticket
+  during Phase 8 of `/plan` when the host LLM needs to write the ticket
   array before `epic-plan-decompose.js` validates and persists it.
 allowed_tools:
   - Read
@@ -18,10 +18,10 @@ allowed_tools:
 - Run only after `epic-plan-decompose.js --emit-context` has written `temp/epic-<Epic_ID>/decomposer-context.json`; fail loudly if the file is missing.
 - Emit exactly one artifact: `temp/epic-<Epic_ID>/tickets.json` (a JSON array). Do not write anywhere else, and never call the GitHub API from this Skill — persistence belongs to the script.
 - Output is JSON only — no prose, no Markdown fence. The downstream validator (`lib/orchestration/ticket-validator.js`) is the authoritative gate; re-author rather than hand-patching when it rejects.
-- Treat **`maxTickets`** from the context envelope as a **reviewability budget**, not a hard authoring cap (Story #2798). Merge narrow, single-module Stories into their capability first; if the plan genuinely needs more, emit the full plan and add a compact `over_budget_rationale` field at the top of the first Feature's `body` explaining why the plan exceeds the budget. Operator persistence then requires the explicit `--allow-over-budget` override on `epic-plan-decompose.js`; without it the persist step rejects the over-budget array. Never truncate the JSON array to fit.
-- Honour the two-level hierarchy under each Epic: **Feature → Story**. Stories carry the implementation scope inline; no lower ticket tier exists.
-- **Decompose at deliverable granularity, not module/task level.** A Story is a capability slice a frontier model delivers and self-verifies in one pass — a shippable slice a reviewer would accept as a single PR — not a single module or file. Every Feature MUST decompose into at least TWO Stories; the validator HARD-rejects a single-Story Feature. See the STORY SIZING section for the full guidance and the single-consumer merge rule.
-- Every ticket carries `type::[feature|story]` and `persona::*` labels. Every Story ticket object MUST carry top-level `acceptance: string[]` and `verify: string[]` arrays (read by `hasInlineAcceptanceAndVerify` in the validator) and `body` MUST be a **string** produced by `serialize()` from `lib/story-body/story-body.js` — an object body causes `createOp` in `epic-spec-reconciler-ops.js` to throw `StoryBodyParseError` (Story #3302), and is also silently discarded by `composeStoryBody` in the GitHub provider, producing an empty issue body.
+- Treat **`maxTickets`** from the context envelope as a **reviewability budget**, not a hard authoring cap (Story #2798). Merge narrow, single-module Stories into their capability first; if the plan genuinely needs more, emit the full plan and add a compact `over_budget_rationale` note inside the first Story's `## Goal` section explaining why the plan exceeds the budget. Operator persistence then requires the explicit `--allow-over-budget` override on `epic-plan-decompose.js`; without it the persist step rejects the over-budget array. Never truncate the JSON array to fit.
+- Honour the 2-tier hierarchy: every ticket is a **Story** attached directly to the Epic. Stories carry the implementation scope inline; no Feature and no lower ticket tier exists. Thematic grouping is prose in the Epic body / Tech Spec, never a ticket.
+- **Decompose at deliverable granularity, not module/task level.** A Story is a capability slice a frontier model delivers and self-verifies in one pass — a shippable slice a reviewer would accept as a single PR — not a single module or file. See the STORY SIZING section for the full guidance and the single-consumer merge rule.
+- Every ticket carries `type::story` and `persona::*` labels. Every Story ticket object MUST carry top-level `acceptance: string[]` and `verify: string[]` arrays (read by `hasInlineAcceptanceAndVerify` in the validator) and `body` MUST be a **string** produced by `serialize()` from `lib/story-body/story-body.js` — an object body causes `createOp` in `epic-spec-reconciler-ops.js` to throw `StoryBodyParseError` (Story #3302), and is also silently discarded by `composeStoryBody` in the GitHub provider, producing an empty issue body.
 - **New-File Contract**: any path referenced in `goal`, `acceptance`, or `verify` that does not exist on `main` MUST appear in the Story's `changes[]` with `assumption: "creates"`; otherwise the freshness validator rejects the decompose.
 - Acceptance items MUST be **observable from outside the agent** (command exits 0, file exists, snapshot matches, testid resolves). Items like "verify by reading the diff" or "looks good" are forbidden — push them into `verify` commands instead.
 - Acceptance MUST NOT prescribe a commit subject starting with a non-Conventional-Commits prefix; the literal `baseline-refresh:` leading token is forbidden (use a body trailer instead — see Epic #2501).
@@ -31,12 +31,12 @@ allowed_tools:
 ## Role
 
 Senior Project Manager + Orchestrator. The Skill's job is to take a PRD plus
-a Tech Spec and emit a Feature → Story ticket hierarchy the orchestrator
-can execute autonomously.
+a Tech Spec and emit a flat Story backlog the orchestrator can execute
+autonomously.
 
 ## When to use
 
-`/epic-plan` Phase 8, immediately after
+`/plan` Phase 8, immediately after
 `epic-plan-decompose.js --emit-context` writes
 `temp/epic-<Epic_ID>/decomposer-context.json`. The Skill replaces the
 inline "Author the Ticket Array" step in the legacy workflow body —
@@ -74,7 +74,7 @@ Skill's body below is the authoritative version going forward.
 
 ## Outputs
 
-- `temp/epic-<Epic_ID>/tickets.json` — JSON array of Feature/Story
+- `temp/epic-<Epic_ID>/tickets.json` — JSON array of Story
   objects conforming to the schema in this Skill's body.
 
 The file MUST exist before the Skill returns. The caller will then run
@@ -116,7 +116,7 @@ Write the final JSON array to `temp/epic-<Epic_ID>/tickets.json` with
 the `Write` tool. Do not pretty-print past 2-space indent — the file is
 machine-consumed.
 
-### Step 4 — Hand back to `/epic-plan`
+### Step 4 — Hand back to `/plan`
 
 Return control. The caller invokes
 `node .agents/scripts/epic-plan-decompose.js --epic <Epic_ID> --tickets
@@ -132,17 +132,16 @@ budget (Story #2798) — stay under by default; over-budget plans need an
 
 ```text
 You are an expert Senior Project Manager and Orchestrator.
-Your job is to take a Product Requirements Document (PRD) and a Technical Specification and decompose them into a Feature → Story ticket hierarchy for an AI Agent to execute.
+Your job is to take a Product Requirements Document (PRD) and a Technical Specification and decompose them into a flat list of Story tickets for an AI Agent to execute.
 
 ### HIERARCHY RULES:
-1. **Features**: Large functional milestones (e.g., "Authentication Provider Integration"). Features are navigational containers — no implementation work hangs off the Feature body itself.
-2. **Stories**: Capability-sized, verifiable units of work (e.g., "Implement JWT Token Exchange").
-   - MUST be nested under a Feature via `parent_slug`.
+1. **Stories**: Capability-sized, verifiable units of work (e.g., "Implement JWT Token Exchange").
+   - Attach directly to the Epic — there is NO Feature tier; thematic grouping is prose in the Epic body / Tech Spec.
    - **Story-Level Execution**: Each Story is executed on a single Story branch (`story-<storyId>`), implemented in one Story-implementation phase, then merged into the Epic branch. The Story body carries the full execution contract (goal, changes, acceptance, verify).
-   - Do NOT emit a lower ticket tier — the validator only accepts `type::feature` and `type::story`.
+   - Do NOT emit any other ticket tier — the validator only accepts `type::story`.
 
 ### LABEL CONVENTIONS:
-- Every ticket must have a `type::[feature|story]` label.
+- Every ticket must have the `type::story` label.
 - Every ticket must have a `persona::[engineer|architect|qa-engineer|engineer-web|etc]` label indicating WHO should execute it.
 
 ### OUTPUT FORMAT:
@@ -152,48 +151,18 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 [
   {
     "slug": "hyphen-case-id",
-    "type": "feature" | "story",
+    "type": "story",
     "title": "Short descriptive title",
     "body": <string — see BODY RULES below>,
     "acceptance": ["<testable criterion>", ...],  // STORIES ONLY — top-level, read by validator
     "verify": ["<exact command> (<tier>)", ...],  // STORIES ONLY — top-level, read by validator
-    "labels": ["type::...", "persona::..."],
-    "parent_slug": "slug_of_parent_ticket" (leave empty for features to nest under epic; required for stories — must point at a sibling Feature),
+    "labels": ["type::story", "persona::..."],
     "depends_on": ["slug_of_blocking_dependency"] (optional array of Story slugs that block execution)
   }
 ]
 
 **Slug format**: `^[a-z0-9][a-z0-9-]*$` — hyphen-case only. Underscores are rejected by the validator.
 
-### FEATURE BODY:
-For Features, `body` is a brief string under 2 sentences. Features are navigational — the work happens at the Story level — so dense bodies waste output budget.
-
-FEATURE GROUPING — CAPABILITY/STAKEHOLDER, NOT EXECUTION SHAPE:
-
-- Do not group Stories by technical execution shape (cron jobs, middleware, scripts). Group by the capability or stakeholder they serve. Two Stories that happen to share a delivery mechanism — both are cron sweeps, both are Express middleware, both are CLI scripts — do NOT belong in the same Feature just because of that shared shape. The Feature axis is the user-facing capability or the stakeholder served, never the implementation vehicle.
-- Operational/compliance work gets its own Feature. Retention purges, audit-log sweeps, scheduled cleanups, observability emitters, and other operational/compliance chores serve operators and compliance, not end users. Place them in a dedicated `compliance-and-observability` or `data-retention` Feature — do NOT fold them into a user-facing Feature (e.g. notification flows) merely because they share a cron/scheduled execution shape with user-facing Stories.
-
-ANTI-PATTERN (based on Epic #18 -> Feature #1446):
-
-A decomposition produced a Feature "Notification flows: reminders, schedule-change, retention" grouping three Stories. WRONG — grouped by execution shape (all three are cron sweeps):
-
-    Feature: notification-flows  ("Notification flows: reminders, schedule-change, retention")
-      [X] Story: send-appointment-reminders      (user-facing: emails patients)
-      [X] Story: send-schedule-change-notices    (user-facing: emails patients)
-      [X] Story: purge-email-audit-log-retention (compliance: deletes audit rows past retention)
-
-The email audit-log retention purge was folded in only because all three run as scheduled cron jobs — a shared execution shape, not a shared capability. The purge serves compliance/operators, not the patients the other two Stories notify. CORRECT — regroup by capability/stakeholder:
-
-    Feature: notification-flows  ("Patient notification flows")
-      Story: send-appointment-reminders      (user-facing)
-      Story: send-schedule-change-notices    (user-facing)
-    Feature: compliance-and-observability  ("Data-retention and audit-log compliance")
-      Story: purge-email-audit-log-retention (compliance)
-
-The cron shape is the false grouping signal. Once the retention purge has a sibling under a dedicated compliance Feature it ceases to be a lone-Story Feature (which the validator would reject); pair it with other operational/compliance sweeps (e.g. a session-token cleanup or a metrics-rollup job) under the same `compliance-and-observability` Feature.
-
-- Smell test: if the only thing two Stories have in common is how they run (a scheduled job, a request interceptor, a build step) rather than whom they serve or what capability they deliver, they are mis-grouped. Re-home the operational/compliance Story into its own capability Feature.
-
 ### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
 For Stories, `body` MUST be a **string** — the serialized markdown produced by calling `serialize()` from `lib/story-body/story-body.js`. Do NOT emit `body` as a JSON object: `createOp` in `epic-spec-reconciler-ops.js` will throw `StoryBodyParseError` when it receives an object body (Story #3302 serialize-or-throw contract), and `composeStoryBody` in the GitHub provider also discards non-string bodies producing an empty issue. The canonical pipeline requires a serialized string body end-to-end. The freshness gate (`collectTaskChangesPaths`) and the assumption gate (`collectStoryAssumptionEntries`) both parse the string body via `story-body.js#parse` to recover `changes[]`/`references[]` — they operate correctly only on the serialized string form.
 
@@ -202,7 +171,7 @@ The `acceptance[]` and `verify[]` arrays live at the **top level** of the Story
 The serialized `body` string renders these markdown sections (in order):
 
     ## Goal
-    <one sentence — why this Story exists; tie it to the parent Feature slug>
+    <one sentence — why this Story exists within the Epic>
 
     ## Changes
     - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
@@ -225,7 +194,7 @@ Fields `wide` and `estimated_test_files` are encoded as a `<!-- meta: {...} -->`
 #### STORY BODY RULES:
 
 - **slug**: MUST be hyphen-case (`^[a-z0-9][a-z0-9-]*$`). Do not use underscores.
-- **goal** (in body string): One sentence stating WHY this Story exists. SHOULD name the parent Feature slug.
+- **goal** (in body string): One sentence stating WHY this Story exists within the Epic.
 - **changes** (in body string): Each entry is an object `{ path, assumption }` where `assumption` is one of `creates | refactors-existing | deletes`. The Phase 8 validator probes the base branch for every declared path and rejects the decompose when the declared assumption contradicts reality: `creates` against an existing path is an error, `refactors-existing` / `deletes` against a missing path is an error. Use `refactors-existing` for in-place edits to a file already on `main`; `creates` for net-new files; `deletes` for removals. Acceptable path shapes include explicit files (`src/components/Foo.tsx`), glob patterns (`tests/e2e/*.spec.ts`, `**/*.astro`), and module identifiers that resolve to files.
 - **references** (in body string, optional): Object-form entries `{ path, assumption: "exists" }` for paths the Story **reads** but does not modify (test fixtures it relies on, sibling modules it imports, feature files it scans). The validator probes these like `changes` and rejects the decompose when an `exists` path is absent on the base branch. Use this list to make read-dependencies explicit so a hallucinated or stale assumption surfaces at planning time rather than execution time.
 - **NEW-FILE CONTRACT (must-follow)**: Any path the Story references in `goal`, `acceptance`, or `verify` that does **not** already exist on `main` MUST also appear in the same Story's `changes` array with `assumption: "creates"`. The freshness validator probes `main` for every referenced code path and rejects the decompose when a missing path is absent from `changes` — even when the Story is the one authoring the file. Example: a Story creating `tests/lib/foo.test.js` whose `verify` runs `node --test tests/lib/foo.test.js` MUST include `{ "path": "tests/lib/foo.test.js", "assumption": "creates" }` in `changes`, otherwise the validator emits a freshness miss and the decompose round trips for a re-emit.
@@ -245,9 +214,8 @@ The first question is **cohesion, not count**: *is this one coherent change with
 
 - **One Story = one coherent change with one reason to exist.** If you cannot state that reason in a sentence, the Story is probably two Stories.
 - **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.
-- **Split independent, parallelizable work** into sibling Stories under the same Feature — but only when the pieces genuinely have separate reasons to exist.
+- **Split independent, parallelizable work** into sibling Stories — but only when the pieces genuinely have separate reasons to exist.
 - **Declare `wide` with a one-line reason when a change is legitimately broad** (a cohesive cutover that spans many files for one reason).
-- **Every Feature MUST decompose into at least TWO Stories.** A Feature with a single Story is the work of a Story, not a Feature. **Resolve it by COLLAPSING, not splitting** — drop the Feature wrapper and attach its lone Story to a sibling Feature (or merge the Feature into another). Do NOT manufacture a second Story to satisfy the rule; splitting a lone Story into two inflates ticket count and defeats the "fewer, right-sized Stories" goal. The validator (`ticket-validator.js` → `assertNoSingleStoryFeature`) HARD-rejects a decomposition containing a Feature with fewer than two Stories, naming the offending Feature; the Phase 8 consolidation pass (`epic-plan-consolidate`) performs the collapse holistically before the validator runs.
 
 **Numeric backstop.** The thresholds are defined **once**, in the `DEFAULT_TASK_SIZING` constant in `ticket-validator-sizing.js` (operator-overridable via `agentSettings.planning.taskSizing`). They are a backstop, not the primary rule — do not restate divergent numbers anywhere else. The defaults:
 
@@ -291,7 +259,7 @@ The Acceptance Spec's AC table (columns `AC ID | Outcome | Feature File | Scenar
 
 When the Acceptance Spec contains **one or more `Disposition: new` rows**, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create those `.feature` files with `@skip`-tagged scenarios BEFORE any implementation Story runs:
 
-- **goal** (in body string): contains the literal token `bdd-scaffold` and names the parent Feature slug.
+- **goal** (in body string): contains the literal token `bdd-scaffold`.
 - **depends_on**: EMPTY (`[]`) — the scaffold runs first, in wave 0.
 - **changes** (in body string): one `{ path, assumption: "creates" }` entry per distinct `.feature` file named in a `new` row.
 - **acceptance** (top-level array): MUST assert (a) every new `.feature` file exists, and (b) every new scenario within them carries an `@skip` tag. Keep items observable (a command exits 0; a file exists at a path).
@@ -306,7 +274,6 @@ When the Acceptance Spec contains **zero `new`-disposition rows** (every row is
       "slug": "scaffold-billing-feature-files",
       "type": "story",
       "title": "Scaffold @skip-tagged billing feature files",
-      "parent_slug": "billing-flows",
       "depends_on": [],
       "labels": ["type::story", "persona::qa-engineer"],
       "acceptance": [
@@ -398,7 +365,7 @@ Do NOT silently allow two Stories to write the same root configuration
 file in the same wave; parallel dispatch would produce a merge conflict
 on every Story-to-Epic close after the first.
 
-CRITICAL: Dependencies should follow execution blockers. For hierarchical grouping, strongly strictly use 'parent_slug' (Story parent MUST be a Feature). Features should have no 'parent_slug' (they attach to Epic).
+CRITICAL: Dependencies should follow execution blockers. Stories attach directly to the Epic — never emit a 'parent_slug' field.
 IMPORTANT DEPENDENCY RULE: A Story's `depends_on` MUST only reference other Stories within the SAME Epic. If two Stories have a logical ordering requirement, express it via Story-level `depends_on`.
 WARNING: You MUST conserve your output limit. Do NOT generate more than ${maxTickets} tickets in total. Merge narrow work into cohesive capability Stories. Do NOT cut off the JSON array prematurely!
 

package/.agents/skills/core/epic-plan-spec-author/SKILL.md

@@ -3,7 +3,7 @@ name: epic-plan-spec-author
 description: >-
   Author the PRD, Tech Spec, Acceptance Spec markdown, and risk-verdict JSON
   for an Epic from the planner authoring context emitted by
-  `epic-plan-spec.js --emit-context`. Use during Phase 7 of `/epic-plan` when
+  `epic-plan-spec.js --emit-context`. Use during Phase 7 of `/plan` when
   the host LLM needs to write the four artifacts before `epic-plan-spec.js`
   persists them.
 allowed_tools:
@@ -16,7 +16,7 @@ allowed_tools:
 
 ## Policy Capsule
 
-- Run only during `/epic-plan` Phase 7, after `epic-plan-spec.js --emit-context` has written `temp/epic-<Epic_ID>/planner-context.json`; fail loudly if the file is missing rather than fabricating context.
+- Run only during `/plan` Phase 7, after `epic-plan-spec.js --emit-context` has written `temp/epic-<Epic_ID>/planner-context.json`; fail loudly if the file is missing rather than fabricating context.
 - Write exactly four artifacts and only inside `temp/epic-<Epic_ID>/`: `prd.md`, `techspec.md`, `risk-verdict.json`, `acceptance-spec.md`. All four MUST exist on disk before returning.
 - Start each markdown artifact at the correct `##` heading (PRD → `## Overview`, Tech Spec → `## Technical Overview`, Acceptance Spec → `## Acceptance Criteria`) — never emit a top-level `#` heading. `risk-verdict.json` is raw JSON conforming to `.agents/schemas/risk-verdict.schema.json`.
 - Judge risk from what the change *does* (the PRD / Tech Spec you just wrote), never from keyword presence — "out of scope: billing" is not a billing change; "rotate the credential vault" is high-risk even without a security keyword.
@@ -40,7 +40,7 @@ the Acceptance Spec).
 
 ## When to use
 
-`/epic-plan` Phase 7, immediately after `epic-plan-spec.js --emit-context`
+`/plan` Phase 7, immediately after `epic-plan-spec.js --emit-context`
 writes `temp/epic-<Epic_ID>/planner-context.json`. This Skill replaces the
 inline "Author the PRD" / "Author the Tech Spec" steps from the legacy
 workflow body — the calling workflow dispatches this Skill via the `Skill`
@@ -366,7 +366,7 @@ CRITICAL REQUIREMENTS:
 - Acceptance Outcomes MUST NOT prescribe a commit subject that begins with a non-Conventional-Commits prefix (allowed leading types: feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert). The legacy `baseline-refresh` token used as a leading subject prescription is forbidden — commitlint will reject it at commit time, and the decompose-time validator (`ticket-validator.js` → `validateAcceptanceSubjectPrefix`) will reject the decompose with `code: 'forbidden-subject-prefix'`. Use a Conventional-Commits subject (e.g. `chore(baselines): refresh ...`) and a body trailer (e.g. `baseline-refresh: true` — trailer with a value, not a subject prefix) when a machine-readable marker is needed. See Epic #2501 for rationale.
 ```
 
-### Step 6 — Hand back to `/epic-plan`
+### Step 6 — Hand back to `/plan`
 
 All four files exist; return. The caller will run
 `node .agents/scripts/epic-plan-spec.js --epic <Epic_ID> --prd

package/.agents/skills/core/hydrate-context/SKILL.md

@@ -25,8 +25,8 @@ allowed_tools:
 
 ## Role
 
-Context aggregator. Resolves a ticket's hierarchy (Task → Story →
-Feature → Epic) and stitches the linked planning artifacts into a
+Context aggregator. Resolves a ticket's hierarchy (Story → Epic)
+and stitches the linked planning artifacts into a
 single prompt the executor consumes.
 
 ## When to use