mandrel 1.59.0 → 1.60.0

package/.agents/docs/configuration.md

@@ -38,8 +38,8 @@ top-level keys are validation errors.
 | ------------- | -------- | ---------------------------------------------------------------------------------- |
 | `project`     | **Yes**  | Project-local paths, base branch, validation commands, and context-hydration files. |
 | `github`      | No       | Ticketing provider config: owner/repo, branch protection, merge methods, notifications. |
-| `planning`    | No       | `/epic-plan` tuning: ticket budget, risk heuristics, codebase snapshot, context cap. |
-| `delivery`    | No       | `/epic-deliver` and `/story-deliver` tuning: quality gates, worktree isolation, runners, lifecycle. |
+| `planning`    | No       | `/plan` tuning: ticket budget, risk heuristics, codebase snapshot, context cap. |
+| `delivery`    | No       | `/deliver` and `/deliver` tuning: quality gates, worktree isolation, runners, lifecycle. |
 | `$schema`     | No       | JSON Schema pointer for editor tooling.                                            |
 
 ---
@@ -266,13 +266,13 @@ top-level keys are validation errors.
 | `mergeWatch.intervalSeconds` | No | `integer` | `30` | Seconds between MergeWatcher polls. Default 30. |
 | `mergeWatch.maxBudgetSeconds` | No | `integer` | `3600` | Total wall-clock budget (seconds) for the MergeWatcher poll loop. Default 3600 (60 minutes). |
 | `epicAudit` | No | `object` | — | Nested configuration block. |
-| `epicAudit.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /epic-deliver Phase 4 (epic-audit). 0 disables auto-fix. Default 3. |
+| `epicAudit.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /deliver Phase 4 (epic-audit). 0 disables auto-fix. Default 3. |
 | `epicAudit.maxFixScopeFiles` | No | `integer` | — | Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5. |
 | `codeReview` | No | `object` | — | Nested configuration block. |
 | `codeReview.provider` | No | `"native"` \| `"codex"` \| `"security-review"` | `"native"` | Legacy single-adapter selection. ReviewProvider that produces the Finding[] consumed by runCodeReview(). Story #2833 registered `native` (in-process maintainability/lint); Story #2830 added `codex` (invokes `/codex:review` plugin); Story #2871 added `security-review` (shells out to `claude --print /security-review`). When `providers` (chain shape) is set this field is ignored with a warning. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain. |
 | `codeReview.providers[]` | No | `array<object>` | — | Multi-provider chain (Story #2871). When set and non-empty, takes precedence over the legacy `provider` field. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Each item has: name, scopes, optional, manualPrompt, when. |
 | `codeReview.providerConfig` | No | `object` | — | Optional escape hatch for adapter-specific configuration. No documented keys in Epic #2815; reserved so future adapters can be configured without another schema migration. |
-| `codeReview.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /epic-deliver Phase 5 (code-review). 0 disables auto-fix. Default 3. |
+| `codeReview.maxFixAttempts` | No | `integer` | — | Maximum auto-fix retry attempts per finding in /deliver Phase 5 (code-review). 0 disables auto-fix. Default 3. |
 | `codeReview.maxFixScopeFiles` | No | `integer` | — | Maximum file count a single auto-fix may modify before escalating to agent::blocked. Default 5. |
 | `retro` | No | `object` | — | Story #3042 (Epic #3019). Operator-tunable retro behaviour. Currently exposes `perfThresholds`, the gates the retro perf-signals classifier uses to decide which signals to surface in the `## Performance Signals` / `## Recommended Follow-Ons` retro sections. |
 | `retro.perfThresholds` | No | `object` | — | Gates for `classifyPerfSignals` (lib/orchestration/retro-perf-heuristics.js). Defaults are 0.6 / 0.4 / 2. |
@@ -285,7 +285,7 @@ top-level keys are validation errors.
 | `acceptanceEval.maxRounds` | No | `integer` | — | Maximum number of redraft rounds before escalation. Default 2; clamped into [1, hard ceiling] by lib/config/acceptance-eval.js so the cap can never be disabled (maxRounds: 0 clamps up to 1). |
 | `ci` | No | `object` | — | Nested configuration block. |
 | `ci.skipForStoryPushes` | No | `boolean` | — | Story #2899 (Epic #2880, F13). When true (default), pre-push tooling appends a '[skip ci]' trailer to Story-branch commit subjects so intermediate pushes do not stampede the CI fleet. The Epic-branch merge commit produced by story-close.js never carries the marker, regardless of this flag. |
-| `preflight` | No | `object` | — | Story #2899 (Epic #2880, F13). Thresholds consumed by `.agents/scripts/epic-deliver-preflight.js`. When any value is exceeded the preflight envelope flags a breach and /epic-deliver Phase 1 surfaces it via agent::blocked. |
+| `preflight` | No | `object` | — | Story #2899 (Epic #2880, F13). Thresholds consumed by `.agents/scripts/epic-deliver-preflight.js`. When any value is exceeded the preflight envelope flags a breach and /deliver Phase 1 surfaces it via agent::blocked. |
 | `preflight.maxStories` | No | `integer` | — | — |
 | `preflight.maxWaves` | No | `integer` | — | — |
 | `preflight.maxInstallCostSeconds` | No | `integer` | — | — |
@@ -418,7 +418,7 @@ suppress a channel entirely, set its array to `[]`.
 
 ## `planning`
 
-`/epic-plan` tuning. All fields optional.
+`/plan` tuning. All fields optional.
 
 | Field                          | Required | Default    | Purpose                                                                                          |
 | ------------------------------ | -------- | ---------- | ------------------------------------------------------------------------------------------------ |
@@ -429,7 +429,7 @@ suppress a channel entirely, set its array to `[]`.
 
 ### `planning.context`
 
-Caps the size of `--emit-context` JSON payloads emitted during `/epic-plan`
+Caps the size of `--emit-context` JSON payloads emitted during `/plan`
 so a runaway PRD / Tech Spec can't blow the planning agent's context budget.
 
 | Field         | Required | Default  | Purpose                                                                                       |
@@ -461,7 +461,7 @@ rather than a flat lexicographic slice — so a large, dot-prefixed tree like
 the consumer's own `src/` / `lib/` source. When `.agents/scripts/**` is the
 only matching tree (the Mandrel-repo dogfood case), the round-robin
 degenerates to taking the first 250 sorted paths, so that snapshot stays
-useful. When truncation occurs, `/epic-plan` Phase 7 emits an
+useful. When truncation occurs, `/plan` Phase 7 emits an
 operator-visible warning naming the dropped file count and suggesting
 `tier: "medium"` and/or a narrowed `include`. Opt into the richer `medium`
 tier or narrow `include` if the partial skinny view is insufficient.
@@ -470,7 +470,7 @@ tier or narrow `include` if the partial skinny view is insufficient.
 
 ## `delivery`
 
-`/epic-deliver` and `/story-deliver` tuning. All sub-blocks are optional and
+`/deliver` and `/deliver` tuning. All sub-blocks are optional and
 fall back to documented defaults (or are no-ops when omitted).
 
 ### `delivery.execution`
@@ -500,7 +500,7 @@ fall back to documented defaults (or are no-ops when omitted).
 
 ### `delivery.worktreeIsolation`
 
-Story-level worktree isolation. When `enabled: true`, `/story-deliver` runs
+Story-level worktree isolation. When `enabled: true`, `/deliver` runs
 each Story inside `.worktrees/story-<id>/` instead of moving the main
 checkout's HEAD.
 
@@ -664,7 +664,7 @@ missing entries fall back to in-listener defaults.
 
 ### `delivery.epicAudit`
 
-`/epic-deliver` Phase 4 (epic-audit) auto-fix budget.
+`/deliver` Phase 4 (epic-audit) auto-fix budget.
 
 | Field              | Required | Default | Purpose                                                              |
 | ------------------ | -------- | ------- | -------------------------------------------------------------------- |
@@ -674,7 +674,7 @@ missing entries fall back to in-listener defaults.
 ### `delivery.codeReview`
 
 Configuration block for the code-review pipeline that runs at **both**
-Story-close (`story-close.js`) and Epic-close (`/epic-deliver` Phase 5).
+Story-close (`story-close.js`) and Epic-close (`/deliver` Phase 5).
 Selects the review backend, exposes an escape-hatch for adapter-specific
 configuration, and sets the auto-fix budget enforced at each close scope.
 
@@ -700,7 +700,7 @@ points in the SDLC, using the **same configured values** for both scopes:
 - **Story-close** — `story-close.js` runs `runCodeReview()` against the
   Story branch's diff and applies the budget per finding before merging
   into `epic/<epicId>`.
-- **Epic-close** — `/epic-deliver` Phase 5 runs `runCodeReview()` against
+- **Epic-close** — `/deliver` Phase 5 runs `runCodeReview()` against
   the integrated Epic branch and applies the same per-finding budget
   before opening the PR to `main`.
 
@@ -730,7 +730,7 @@ number of keys.
 
 | File                              | Audience                            | Role                                                                                                                                |
 | --------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `.agentrc.json` (repo root)       | The framework dogfooding itself     | Live config used when running `/epic-*` and `/story-deliver` workflows against this repo. Exercises the framework end-to-end on its own source tree. |
+| `.agentrc.json` (repo root)       | The framework dogfooding itself     | Live config used when running `/epic-*` and `/deliver` workflows against this repo. Exercises the framework end-to-end on its own source tree. |
 | `.agents/starter-agentrc.json`    | Downstream consumer repos           | Bootstrap delta-seed a consumer copies via `cp .agents/starter-agentrc.json .agentrc.json`. Minimum schema-required keys only.      |
 | `.agents/docs/agentrc-reference.json`       | Operators and reviewers             | Exhaustive editor reference enumerating every schema key with its framework default. Not a copy target.                             |
 
@@ -874,8 +874,8 @@ under one identity. So each contributor sets their own in `.agentrc.local.json`:
 carries only the non-personal placeholder `@[USERNAME]` (so CI and fresh clones
 validate without naming a real person). The placeholder is **not** a usable
 identity: [`normalizeOperatorHandle`](../scripts/lib/orchestration/ticket-lease.js)
-resolves `@[USERNAME]` to `null`, and the lease guards (`/epic-plan`,
-`/epic-deliver`, `/story-deliver`) **fail closed** — they throw with a
+resolves `@[USERNAME]` to `null`, and the lease guards (`/plan`,
+`/deliver`, `/deliver`) **fail closed** — they throw with a
 "set your own handle in `.agentrc.local.json`" message rather than running an
 ownerless, unguarded workflow. Your local overlay replaces the placeholder with
 your real handle, and the guards proceed. By contrast, `github.owner` / `repo`

package/.agents/docs/workflows.md

@@ -16,7 +16,7 @@ compose. This file is only for "which command does X?" lookups.
 Every command file lives at `.agents/workflows/<name>.md` and is projected
 into a flat `.claude/commands/` tree by `npm run sync:commands` (the
 UserPromptSubmit hook keeps it current) so it shows up as a bare `/<name>`
-slash command (e.g. `/epic-deliver`). The projection writes only
+slash command (e.g. `/deliver`). The projection writes only
 `.claude/commands/<name>.md` — there is no plugin manifest and no
 marketplace listing. The commands load in every Claude Code environment.
 
@@ -25,7 +25,7 @@ by `node .agents/scripts/generate-workflows-doc.js`; `npm run docs:check`
 fails when it drifts from the on-disk workflow set. To change a command’s
 description, edit the workflow file’s front-matter and regenerate.
 
-## Commands (29)
+## Commands (27)
 
 | Command | Description |
 | --- | --- |
@@ -42,19 +42,17 @@ description, edit the workflow file’s front-matter and regenerate.
 | `/audit-security` | Audit dependency CVEs, input-validation gaps, secrets handling, and auth boundaries; emit a structured High/Medium/Low findings report. |
 | `/audit-seo` | Audit SEO fundamentals and Generative Engine Optimization signals (meta, structured data, crawlability); only relevant for web targets. |
 | `/audit-sre` | "Audit production-readiness for a release candidate: SLOs, observability, runbooks, error budgets, and rollback paths." |
-| `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /epic-plan --idea or opens standalone Stories. |
+| `/audit-to-stories` | Convert findings produced by the audit-\* workflows into actionable GitHub Stories. Reads temp/audits/audit-\*-results.md, groups findings cross-audit, deduplicates against existing Issues by fingerprint, and either chains into /plan --idea or opens standalone Stories. |
 | `/audit-ux-ui` | Audit UX/UI consistency and design system adherence |
-| `/epic-deliver` | Drive an Epic from `agent::ready` to a merged pull request against `main`. The ten-phase flow runs the wave loop, close-validation, epic-audit, code-review, retro, finalize, watch-and-iterate, conditional auto-merge, and local branch cleanup. When the run is end-to-end clean (zero manual interventions, zero 🔴/🟠 review findings, compact retro) the PR auto-merges via `gh pr merge --squash --delete-branch`; otherwise the workflow falls back to the operator-merges-button path so a human inspects the surface area. |
-| `/epic-plan` | Orchestrates end-to-end Epic planning (PRD, Tech Spec, Acceptance Spec, and Work Breakdown) for a GitHub Epic. |
+| `/deliver` | Unified delivery entry point. Inspects the ticket type(s) and Epic-reference state of the supplied IDs, then routes to the Epic wave loop or the standalone multi-Story fan-out — preserving every flag and the parallel-delivery contract of the retired commands. |
 | `/explain` | Walk the operator through a code change until they genuinely understand it. Targets a PR, a branch, or the working-tree diff, then drives the `core/knowledge-transfer` skill (restate-first, why-ladder, mastery gates, persistent checklist) with an operator-controlled stop at every checkpoint. |
 | `/git-cleanup` | Tidy the local checkout in four phases: fast-forward `main`, prune stale remote-tracking refs, sweep merged branches (squash-aware), and triage `git stash` entries — each step gated by operator confirmation. |
 | `/git-commit-all` | Stage every untracked and modified file, then create a single conventional-commit on the current branch (no push). |
 | `/git-merge-pr` | Analyze, validate, resolve conflicts, and merge a given pull request by number. |
 | `/git-pr-all` | Stage all outstanding changes, commit, push to a feature branch, and open a pull request with native auto-merge enabled. |
 | `/git-push` | Commit all outstanding changes then push to the remote repository. |
-| `/onboard` | Guided first-run onboarding for a freshly installed Mandrel. Detects the consumer stack, offers to scaffold any missing docsContextFiles, runs `mandrel doctor` as a readiness gate, and hands off to a started /epic-plan. The whole path is designed to take about 15 minutes from a clean checkout to a planned Epic. |
+| `/onboard` | Guided first-run onboarding for a freshly installed Mandrel. Detects the consumer stack, offers to scaffold any missing docsContextFiles, runs `mandrel doctor` as a readiness gate, and hands off to a started /plan. The whole path is designed to take about 15 minutes from a clean checkout to a planned Epic. |
+| `/plan` | Unified planning entry point. Routes a seed idea (via scope triage) or an existing Epic ID to the right planning path — the full Epic pipeline (PRD, Tech Spec, Acceptance Spec, decomposition) or the standalone-Story authoring path — and absorbs every planning flag. |
 | `/qa-assist` | Human-led QA assist loop — ingest one operator observation, enrich it with repro + root-cause (file:line) + a coverage verdict, ask clarifying questions when it is ambiguous, and append a redacted ledger item to a persistent, resumable rolling session under temp/qa/ |
 | `/qa-explore` | Agent-led exploratory-QA loop — the agent Plans a surface with an explicit static-vs-drive method choice, drives it (browser MCP or static), and captures ledger items read-only, then Triages — a bounded per-surface session, HITL-gated at every phase transition, routed through the shared dedup/coverage/classification/missing-test/redaction/session core under temp/qa/ |
 | `/qa-run-harness` | Drive Gherkin scenarios through a real browser as an agent-driven QA sweep |
-| `/story-deliver` | Deliver one or more standalone Stories end-to-end. Accepts 1+ Story IDs, computes a dependency-aware wave plan via `stories-wave-tick.js`, asks the operator to confirm the plan, then fans out parallel Agent calls per wave — each delegating to `helpers/single-story-deliver`. Stories without an `Epic: #N` reference only; Epic-attached Stories use `/epic-deliver`. |
-| `/story-plan` | Author a standalone Story (no parent Epic) from a short prompt. Builds a context envelope, lets the host LLM draft the body, and creates the GitHub Issue with type::story and a persona label — ready to feed into /single-story-deliver. |

package/.agents/instructions.md

@@ -150,8 +150,8 @@ This protocol is not soft-prompt-only — it has a runtime substrate. While
 executing as a Story delivery sub-agent (via `helpers/epic-deliver-story`
 or `helpers/single-story-deliver`), you MUST emit a `story.heartbeat`
 lifecycle event on every Task transition (or whenever you stall on a
-long-running step) so the parent `/epic-deliver` idle watchdog (§ 2e of
-`.agents/workflows/epic-deliver.md`, re-ticked every 30 minutes via
+long-running step) so the parent `/deliver` idle watchdog (§ 2e of
+`.agents/workflows/helpers/deliver-epic.md`, re-ticked every 30 minutes via
 `wave-tick.js --check-idle 30`) can distinguish a child still making
 progress from a dead one. If you genuinely cannot proceed, transition to
 `agent::blocked` and exit non-zero — never fall silent. A child with no
@@ -219,7 +219,7 @@ stops.
   estimate (≈4 characters per token) and applies section-aware elision
   (`elideEnvelope`) so oversized envelopes drop or summarize
   lower-priority sections before you receive the prompt.
-- **`delivery.preflight.*`** (optional): before `/epic-deliver` fan-out,
+- **`delivery.preflight.*`** (optional): before `/deliver` fan-out,
   `epic-deliver-preflight.js` compares **estimated** story count, waves,
   install time, GitHub API volume, and Claude quota tokens against
   configured ceilings (`maxClaudeQuotaTokens`, etc.). A breach surfaces
@@ -303,7 +303,7 @@ them automatically; agents commit on the execution branch only.
 | Purpose          | Format                       | Owner                  | Notes                                                                                         |
 | ---------------- | ---------------------------- | ---------------------- | --------------------------------------------------------------------------------------------- |
 | Story execution  | `story-<storyId>`            | `story-init.js` | Per-Story worktree at `.worktrees/story-<storyId>/`. All Story implementation commits land here. |
-| Epic integration | `epic/<epicId>`              | `/epic-deliver` slash command | Story branches merge into this branch with `--no-ff`. Pushed per wave.                       |
+| Epic integration | `epic/<epicId>`              | `/deliver` slash command | Story branches merge into this branch with `--no-ff`. Pushed per wave.                       |
 
 - **Verification**: After `story-init.js` returns, confirm
   `git branch --show-current` reports `story-<storyId>` before making any
@@ -324,18 +324,19 @@ prompted.
 Prioritize a clean `epic/[EPIC_ID]` branch. Story branches are merged into
 the Epic branch automatically by `helpers/epic-deliver-story` (via
 `story-close.js`); the Epic branch reaches `main` via the pull request that
-`/epic-deliver` opens at the end of its run — the operator merges through
+`/deliver` opens at the end of its run — the operator merges through
 the GitHub UI. There is no in-script merge to `main`.
 
-### D. Ticket hierarchy (3-tier)
+### D. Ticket hierarchy (2-tier)
 
-Mandrel uses a **3-tier ticket hierarchy** (Epic → Feature → Story).
+Mandrel uses a **2-tier ticket hierarchy** (Epic → Story).
 Acceptance criteria and verification steps live inline on the Story
-body (`acceptance[]` / `verify[]`); there is no `type::task` ticket
-layer.
+body (`acceptance[]` / `verify[]`); there is no Feature tier and no
+`type::task` ticket layer. Thematic grouping lives as prose in the
+Epic body / Tech Spec.
 
-- The decomposer emits only `type::epic`, `type::feature`, and
-  `type::story` issues.
+- The decomposer emits only `type::epic` and `type::story` issues;
+  Stories attach directly to the Epic.
 - Each Story-implementation phase is executed by
   `helpers/epic-deliver-story` (Epic-attached) or
   `helpers/single-story-deliver` (standalone). There is no per-Task

package/.agents/personas/architect.md

@@ -51,7 +51,7 @@ Before permitting any code generation, you must enforce this workflow:
 ### C. Protocol Evolution (Self-Healing)
 
 - **Friction Analysis:** During the retro phase (Phase 5 of
-  `/epic-deliver`, driven by `lib/orchestration/retro-runner.js`), you
+  `/deliver`, driven by `lib/orchestration/retro-runner.js`), you
   MUST analyze the
   `agent-friction-log.json` to identify systemic bottlenecks, repetitive tool
   failures, or prompt ambiguities.

package/.agents/personas/product.md

@@ -43,7 +43,7 @@ UI copy, metadata, and structural assumptions align with it.
 ### B. Epic Lifecycle & Retrospectives
 
 - **Retrospectives:** Own the Epic retrospective process. Phase 5 of
-  `/epic-deliver` runs `lib/orchestration/retro-runner.js` in-process
+  `/deliver` runs `lib/orchestration/retro-runner.js` in-process
   to generate retro structured comments, analyze execution, and
   formulate action items.
 - **Epic Definition:** Lock upcoming features into a clear Epic scope.

package/.agents/personas/project-manager.md

@@ -9,7 +9,7 @@ prioritize **dependency clarity**, **parallel execution efficiency**, and
 
 **Golden Rule:** You do not write implementation code. You write the GitHub
 Issue hierarchy of instructions that other agent personas will execute.
-The ticket hierarchy is **3-tier** (Epic → Feature → Story), with
+The ticket hierarchy is **2-tier** (Epic → Story), with
 acceptance criteria and verification steps inlined on the Story body.
 There are no `type::task` children — Stories themselves carry the
 implementation scope. If you catch yourself generating application code,
@@ -21,16 +21,16 @@ SQL, or UI components — stop immediately.
    and Tech Spec (`context::tech-spec`) GitHub Issues, plus every file
    listed in `project.docsContextFiles` (typically `architecture.md`
    and the data dictionary).
-2. **Decompose:** Break Features into **Stories** that carry their own
+2. **Decompose:** Break the Epic into **Stories** that carry their own
    inline acceptance criteria and verification steps. Aim for roughly
    five acceptance bullets per Story as a soft atomicity heuristic; if
    a Story scope grows past that, split it into sequential sibling
-   Stories under the same Feature.
+   Stories.
 3. **Assign:** Dynamically select the appropriate Persona from
    `.agents/personas/` for each Story based on its complexity and
    domain, and tag the issue with the matching `persona::` label.
-4. **Format:** Generate the Feature → Story hierarchy using the
-   `/epic-plan` workflow.
+4. **Format:** Generate the Story backlog using the
+   `/plan` workflow.
 5. **Validate:** Ensure every Acceptance Criterion from the PRD has a
    corresponding Story-body acceptance bullet. Do not drop business
    logic.
@@ -39,12 +39,12 @@ SQL, or UI components — stop immediately.
 
 ### A. Epic Planning & Task Decomposition
 
-- **Fan-Out Architecture:** Structure each Epic into Features and Stories
+- **Fan-Out Architecture:** Structure each Epic into Stories
   with explicit `blocked by` links so the dispatch graph can compute parallel
   waves automatically.
-- **Issue Linkage:** Every Feature and Story GitHub Issue must declare
+- **Issue Linkage:** Every Story GitHub Issue must declare
   its `parent` and (where applicable) `blocked by` relationships in the
-  body so `/epic-plan` can build a clean dispatch manifest.
+  body so `/plan` can build a clean dispatch manifest.
 - **Dependency Mapping:** Explicitly declare blockers via `blocked by` on
   the GitHub Issue body. Ensure no Story references work that hasn't
   been completed by a predecessor Story.
@@ -52,7 +52,7 @@ SQL, or UI components — stop immediately.
   perform a limited number of logical steps — roughly five
   acceptance/verification bullets per Story is a good soft heuristic.
   When a Story grows beyond the heuristic, split it into sequential
-  sibling Stories under the same Feature.
+  sibling Stories.
 
 ### B. Resource Allocation (Persona Routing)
 
@@ -68,11 +68,11 @@ SQL, or UI components — stop immediately.
 - **QA Tasks:** Delegate QA Stories to the `/audit-quality` workflow. Do not
   write custom QA instructions.
 - **Retro Tasks:** Delegate the Epic retro to Phase 5 of
-  `/epic-deliver`, which runs `lib/orchestration/retro-runner.js`
+  `/deliver`, which runs `lib/orchestration/retro-runner.js`
   in-process. Do not write custom retro instructions.
 - **Story Finalization:** Ensure every Story's body incorporates a step
   to self-verify its own context (PRD/Tech Spec linkage, parent
-  Feature) before starting work.
+  Epic) before starting work.
 
 ### D. Quality Control
 
@@ -80,15 +80,15 @@ SQL, or UI components — stop immediately.
   every Acceptance Criterion in the PRD against the generated
   Story-body acceptance bullets. Any missed AC is a planning failure.
 - **Format Compliance:** Use the exact Issue body templates, label taxonomy,
-  and parent/blocked-by linkage rules required by `/epic-plan` so the
+  and parent/blocked-by linkage rules required by `/plan` so the
   generated dispatch manifest validates against the schema.
 
 ## 4. Output Artifacts
 
 - The GitHub Issue hierarchy under the parent Epic generated and linked
-  by `/epic-plan` — Feature → Story.
+  by `/plan` — a flat Story backlog.
 - The Epic dispatch manifest (`temp/dispatch-manifest-<epicId>.json`)
-  emitted by `/epic-plan` for the runner to consume.
+  emitted by `/plan` for the runner to consume.
 
 ## 5. Scope Boundaries
 

package/.agents/personas/technical-writer.md

@@ -38,7 +38,7 @@ wasn't in the room when it was built.
 - **Release Notes:** Use the `generate-release-notes` workflow to produce
   user-facing release notes. Focus on user impact, not implementation details.
 - **Retrospectives:** Support `lib/orchestration/retro-runner.js`
-  (driven by Phase 5 of `/epic-deliver`) with clean, well-structured
+  (driven by Phase 5 of `/deliver`) with clean, well-structured
   retro structured comments.
 
 ### B. Architecture & Reference Documentation

package/.agents/rules/changelog-style.md

@@ -3,7 +3,7 @@
 This rule governs the shape of per-release entries in the project CHANGELOG
 (typically `docs/CHANGELOG.md` or `CHANGELOG.md`). It applies whenever a
 release entry is authored or edited — most commonly inside Story #N's
-docs sweep before `/epic-deliver` opens the release PR.
+docs sweep before `/deliver` opens the release PR.
 
 The contract is **guidance-tier** in v1: no automated gate fails a close when
 an entry drifts off-template. It still binds every author.
@@ -166,7 +166,7 @@ applies.
 
 ### Deliver tail auto-invokes pre-merge gates
 
-`/epic-deliver` auto-invokes the code-review module (Phase 4) and
+`/deliver` auto-invokes the code-review module (Phase 4) and
 the retro runner (Phase 5) inline instead of halting to ask the
 operator to run them separately. `--skip-code-review` available as
 an override.
@@ -183,7 +183,7 @@ or a title starting with `📉 Epic Health:`, in addition to
 well-known lock files (`index.lock`, `HEAD.lock`, `packed-refs.lock`,
 `config.lock`, `shallow.lock`) whose mtime exceeds the threshold.
 Fresh locks belonging to in-flight ops are skipped. Runs at
-`/epic-deliver` start, before worktree GC.
+`/deliver` start, before worktree GC.
 ```
 
 Contract violations: five separate `###` sub-sections where one theme
@@ -210,12 +210,12 @@ worktree cleanup.
 - **Shared-store worktrees.** Per-story worktrees link a shared
   `node_modules` store, so parallel waves no longer duplicate installs
   or leave residue that blocks reap.
-- **`/epic-deliver` auto-invokes pre-merge gates** (code review, retro)
+- **`/deliver` auto-invokes pre-merge gates** (code review, retro)
   inline. `--skip-code-review` is available as an override.
 - **Closure sweep covers Epic Health tickets** in addition to PRD and
   Tech Spec tickets.
 - **Stale-lock sweep** on the shared `.git/` directory runs at
-  `/epic-deliver` start, clearing lock files left behind by interrupted
+  `/deliver` start, clearing lock files left behind by interrupted
   operations.
 ```
 

package/.agents/rules/git-conventions.md

@@ -18,8 +18,8 @@ All tasks within a Story MUST be committed to a shared **Story branch**:
 `story-<storyId>` (e.g., `story-104`). The runtime owns Story branch
 creation via `story-init.js`; agents commit on the active Story branch only.
 
-> **Commit subjects.** Under the 3-tier hierarchy
-> (Epic → Feature → Story), Stories have no child tickets. Commits
+> **Commit subjects.** Under the 2-tier hierarchy
+> (Epic → Story), Stories have no child tickets. Commits
 > land on `story-<storyId>` directly from the agent and the
 > Conventional Commit subject references the parent Story via
 > `(refs #<storyId>)`. See
@@ -111,7 +111,7 @@ rejected by `pre-push` hooks):
 ## Meta Labels (Retrospective Signal Routing)
 
 Two `meta::*` labels route retrospective signals into durable substrates so
-the `/epic-plan` Phase 0 fetcher (see
+the `/plan` Phase 0 fetcher (see
 [`prior-feedback-fetcher.js`](../scripts/lib/feedback-loop/prior-feedback-fetcher.js))
 can surface open feedback issues to the planner. Both labels live in
 [`label-constants.js`](../scripts/lib/label-constants.js) under the

package/.agents/schemas/agentrc.schema.json

@@ -518,7 +518,7 @@
         "maxFixAttempts": {
           "type": "integer",
           "minimum": 0,
-          "description": "Maximum auto-fix retry attempts per finding in /epic-deliver Phase 4 (epic-audit). 0 disables auto-fix. Default 3."
+          "description": "Maximum auto-fix retry attempts per finding in /deliver Phase 4 (epic-audit). 0 disables auto-fix. Default 3."
         },
         "maxFixScopeFiles": {
           "type": "integer",
@@ -600,7 +600,7 @@
         "maxFixAttempts": {
           "type": "integer",
           "minimum": 0,
-          "description": "Maximum auto-fix retry attempts per finding in /epic-deliver Phase 5 (code-review). 0 disables auto-fix. Default 3."
+          "description": "Maximum auto-fix retry attempts per finding in /deliver Phase 5 (code-review). 0 disables auto-fix. Default 3."
         },
         "maxFixScopeFiles": {
           "type": "integer",
@@ -1383,7 +1383,7 @@
         },
         "preflight": {
           "type": "object",
-          "description": "Story #2899 (Epic #2880, F13). Thresholds consumed by `.agents/scripts/epic-deliver-preflight.js`. When any value is exceeded the preflight envelope flags a breach and /epic-deliver Phase 1 surfaces it via agent::blocked.",
+          "description": "Story #2899 (Epic #2880, F13). Thresholds consumed by `.agents/scripts/epic-deliver-preflight.js`. When any value is exceeded the preflight envelope flags a breach and /deliver Phase 1 surfaces it via agent::blocked.",
           "properties": {
             "maxStories": {
               "type": "integer",

package/.agents/schemas/dispatch-manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "dispatch-manifest",
   "title": "Dispatch Manifest",
-  "description": "Output of dispatcher.js (epic-dispatch variant) and orchestration/story-executor.js (story-execution variant). Written to temp/dispatch-manifest-<epicId>.json for the epic-dispatch variant. The two variants are discriminated by the `type` field. 3-tier shape only (Epic #3078): manifests are Story-only — there is no Task-level fan-out. Open-root by design — the AJV fixture drift test is the enforcement boundary; see docs/decisions.md ADR 20260427-868a.",
+  "description": "Output of dispatcher.js (epic-dispatch variant) and orchestration/story-executor.js (story-execution variant). Written to temp/dispatch-manifest-<epicId>.json for the epic-dispatch variant. The two variants are discriminated by the `type` field. 2-tier shape only (Epic #3078): manifests are Story-only — there is no Task-level fan-out. Open-root by design — the AJV fixture drift test is the enforcement boundary; see docs/decisions.md ADR 20260427-868a.",
   "type": "object",
   "required": ["generatedAt", "dryRun"],
   "properties": {
@@ -50,8 +50,8 @@
     },
     "hierarchy": {
       "type": "string",
-      "const": "3-tier",
-      "description": "Hierarchy identifier. 3-tier is the only supported shape (Epic #3078)."
+      "const": "2-tier",
+      "description": "Hierarchy identifier. 2-tier is the only supported shape (Epic #3078)."
     },
     "summary": {
       "type": "object",
@@ -66,7 +66,7 @@
         "totalStories": {
           "type": "integer",
           "minimum": 0,
-          "description": "Story-centric count for the 3-tier shape (Epic #3078)."
+          "description": "Story-centric count for the 2-tier shape (Epic #3078)."
         },
         "doneStories": {
           "type": "integer",

package/.agents/schemas/epic-spec.schema.json

@@ -1,12 +1,12 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/epic-spec.schema.json",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "title": "Epic Spec (declarative structural SSOT)",
-  "description": "Canonical structural specification for an Epic and its children (Features, Stories), consumed by the epic-spec-reconciler. Lives on disk as .agents/epics/<epic-id>.yaml. The reconciler diffs this spec against live GitHub state and applies structural mutations (Create/Update/Close/Relink) behind a dry-run default. Slugs are stable, GH-incarnation-independent identifiers used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping persisted in the sibling .agents/epics/<epic-id>.state.json. This schema describes the 3-tier structural shape only (Epic → Feature → Story with inline Story-level acceptance[]/verify[]); agent-execution state (agent::* labels) is intentionally not modelled — that surface belongs to the wave-runner, not the reconciler.",
+  "description": "Canonical structural specification for an Epic and its child Stories, consumed by the epic-spec-reconciler. Lives on disk as .agents/epics/<epic-id>.yaml. The reconciler diffs this spec against live GitHub state and applies structural mutations (Create/Update/Close/Relink) behind a dry-run default. Slugs are stable, GH-incarnation-independent identifiers used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping persisted in the sibling .agents/epics/<epic-id>.state.json. This schema describes the 2-tier structural shape only (Epic → Story with inline Story-level acceptance[]/verify[]); agent-execution state (agent::* labels) is intentionally not modelled — that surface belongs to the wave-runner, not the reconciler.",
   "type": "object",
   "additionalProperties": false,
-  "required": ["epic", "features"],
+  "required": ["epic", "stories"],
   "properties": {
     "$schema": {
       "type": "string",
@@ -15,16 +15,16 @@
     "version": {
       "type": "string",
       "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "Optional schema-shape identifier. Identification-only — readers MUST NOT branch behavior on this value. Bumped to 3.0.0 when Task-level decomposition was removed under the 3-tier collapse (Epic #3078)."
+      "description": "Optional schema-shape identifier. Identification-only — readers MUST NOT branch behavior on this value. Bumped to 4.0.0 when the Feature tier was removed under the 2-tier collapse (Story #4041); 3.0.0 removed Task-level decomposition (Epic #3078)."
     },
     "epic": {
       "$ref": "#/$defs/epic",
       "description": "The Epic this spec describes. Carries the GH issue number, human title, and structural labels (type::epic plus any project-specific structural tags). Execution-state labels (agent::*) MUST NOT appear here."
     },
-    "features": {
+    "stories": {
       "type": "array",
-      "description": "Ordered list of Features under this Epic. Order is preserved for human readability but is not load-bearing — wave ordering is driven by stories[].wave + dependsOn, not by feature position.",
-      "items": { "$ref": "#/$defs/feature" }
+      "description": "Ordered list of Stories under this Epic. Order is preserved for human readability but is not load-bearing — execution order is driven by stories[].wave + dependsOn, not by array position.",
+      "items": { "$ref": "#/$defs/story" }
     },
     "gates": {
       "$ref": "#/$defs/gates",
@@ -36,12 +36,12 @@
       "type": "string",
       "minLength": 1,
       "pattern": "^[a-z0-9][a-z0-9-]*$",
-      "description": "Stable kebab-case identifier used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping. Slugs must be unique within their scope (features within an epic, stories within a feature). Slugs are not GH issue numbers — they survive Epic re-incarnations and ticket renumbering. Pattern: lowercase alphanumeric + hyphens, must start with [a-z0-9]."
+      "description": "Stable kebab-case identifier used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping. Slugs must be unique within the Epic's stories[] array. Slugs are not GH issue numbers — they survive Epic re-incarnations and ticket renumbering. Pattern: lowercase alphanumeric + hyphens, must start with [a-z0-9]."
     },
     "label": {
       "type": "string",
       "minLength": 1,
-      "description": "A GitHub label name. Structural labels only (e.g. type::epic, type::feature, type::story, persona::*, area::*). Execution-state labels in the AGENT_LABELS allow-list (agent::*) MUST NOT appear in the spec — they are owned by the wave-runner and the reconciler refuses to write them."
+      "description": "A GitHub label name. Structural labels only (e.g. type::epic, type::story, persona::*, area::*). Execution-state labels in the AGENT_LABELS allow-list (agent::*) MUST NOT appear in the spec — they are owned by the wave-runner and the reconciler refuses to write them."
     },
     "labels": {
       "type": "array",
@@ -53,7 +53,7 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["id", "title"],
-      "description": "Top-level Epic descriptor. Unlike Features/Stories (which are slug-keyed and may not exist in GH yet), the Epic always has a real GH issue number — the spec lives at .agents/epics/<id>.yaml and that <id> is the same number used here.",
+      "description": "Top-level Epic descriptor. Unlike Stories (which are slug-keyed and may not exist in GH yet), the Epic always has a real GH issue number — the spec lives at .agents/epics/<id>.yaml and that <id> is the same number used here.",
       "properties": {
         "id": {
           "type": "integer",
@@ -67,7 +67,7 @@
         },
         "body": {
           "type": "string",
-          "description": "Optional Epic body. When present, the reconciler updates the GH issue body to match. When omitted, the GH issue body is left untouched (allowing operator-curated bodies to coexist with structural reconciliation). Multi-line markdown is fully supported."
+          "description": "Optional Epic body. When present, the reconciler updates the GH issue body to match. When omitted, the GH issue body is left untouched (allowing operator-curated bodies to coexist with structural reconciliation). Multi-line markdown is fully supported. Thematic grouping of Stories — formerly the Feature tier's job — lives here (and in the Tech Spec) as prose."
         },
         "labels": {
           "$ref": "#/$defs/labels",
@@ -75,45 +75,15 @@
         }
       }
     },
-    "feature": {
-      "type": "object",
-      "additionalProperties": false,
-      "required": ["slug", "title", "stories"],
-      "description": "A Feature groups Stories under a common product/architectural theme. Features themselves are GitHub issues (type::feature) when materialised by the reconciler — they carry no execution state, only structure.",
-      "properties": {
-        "slug": {
-          "$ref": "#/$defs/slug",
-          "description": "Stable kebab-case identifier for this Feature. Must be unique within the parent Epic's features[] array."
-        },
-        "title": {
-          "type": "string",
-          "minLength": 1,
-          "description": "Human-readable Feature title."
-        },
-        "body": {
-          "type": "string",
-          "description": "Optional Feature body. Same semantics as epic.body — written by the reconciler when present, left untouched when omitted."
-        },
-        "labels": {
-          "$ref": "#/$defs/labels",
-          "description": "Structural labels attached to this Feature (e.g. type::feature plus any project-specific structural tags)."
-        },
-        "stories": {
-          "type": "array",
-          "description": "Ordered list of Stories under this Feature. Order is for readability; execution order is driven by stories[].wave + dependsOn.",
-          "items": { "$ref": "#/$defs/story" }
-        }
-      }
-    },
     "story": {
       "type": "object",
       "additionalProperties": false,
       "required": ["slug", "title", "wave"],
-      "description": "A Story is the unit of agent execution — exactly one Story branch (story-<id>) and exactly one Story sub-agent per Story per wave. Stories declare their wave assignment and inter-Story dependencies via slug references; the wave-runner consumes these to schedule the parallel fan-out. Under the 3-tier collapse (Epic #3078), Stories carry inline acceptance[] + verify[] arrays that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface; there is no child-Task decomposition.",
+      "description": "A Story is the unit of agent execution — exactly one Story branch (story-<id>) and exactly one Story sub-agent per Story per wave. Stories are direct children of the Epic (2-tier hierarchy, Story #4041). They declare their wave assignment and inter-Story dependencies via slug references; the wave-runner consumes these to schedule the parallel fan-out. Stories carry inline acceptance[] + verify[] arrays that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface; there is no child-Task decomposition.",
       "properties": {
         "slug": {
           "$ref": "#/$defs/slug",
-          "description": "Stable kebab-case identifier for this Story. Must be unique within the parent Feature's stories[] array, and is the value referenced by sibling Stories' dependsOn arrays."
+          "description": "Stable kebab-case identifier for this Story. Must be unique within the Epic's stories[] array, and is the value referenced by sibling Stories' dependsOn arrays."
         },
         "title": {
           "type": "string",
@@ -144,7 +114,7 @@
         },
         "acceptance": {
           "type": "array",
-          "description": "Inline acceptance criteria for this Story (Epic #3078 — 3-tier collapse). Each entry is a single user-visible acceptance statement that the Story-level agent must satisfy. Acts as the Story-level outcome contract that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface.",
+          "description": "Inline acceptance criteria for this Story. Each entry is a single user-visible acceptance statement that the Story-level agent must satisfy. Acts as the Story-level outcome contract that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface.",
           "items": {
             "type": "string",
             "minLength": 1,
@@ -153,7 +123,7 @@
         },
         "verify": {
           "type": "array",
-          "description": "Inline verification commands for this Story (Epic #3078 — 3-tier collapse). Each entry is a shell-runnable command (typically a contract test invocation) that proves the corresponding acceptance[] entries hold.",
+          "description": "Inline verification commands for this Story. Each entry is a shell-runnable command (typically a contract test invocation) that proves the corresponding acceptance[] entries hold.",
           "items": {
             "type": "string",
             "minLength": 1,

package/.agents/schemas/lifecycle/README.md

@@ -1,7 +1,7 @@
 # Lifecycle event schemas
 
 JSON Schemas for the lifecycle event taxonomy consumed by the
-`/epic-deliver` lifecycle bus
+`/deliver` lifecycle bus
 (`lib/orchestration/lifecycle/bus.js`). The bus validates every
 emit payload against one of these schemas before invoking
 listeners; a schema mismatch fails the emit and propagates the