mandrel 1.59.0 → 1.60.0

package/.agents/scripts/lib/presentation/manifest-story-views.js

@@ -83,9 +83,7 @@ export function printStoryDispatchTable(storyManifest, opts = {}) {
   const log = opts.logger?.log ?? ((line) => Logger.info(line));
   if (!storyManifest || storyManifest.length === 0) return;
 
-  // Split into wave-eligible Stories and Feature containers
-  const stories = storyManifest.filter((s) => s.type !== 'feature');
-  const features = storyManifest.filter((s) => s.type === 'feature');
+  const stories = storyManifest;
 
   log('\n┌─────────┬──────────────────────────────────────┬──────┐');
   log('│                  📋 STORY DISPATCH TABLE                 │');
@@ -106,14 +104,7 @@ export function printStoryDispatchTable(storyManifest, opts = {}) {
   log('└─────────┴──────────────────────────────────────┴──────┘');
   log('');
   log('  💡 Stories in the same [Wave] can be executed in parallel.');
-  log('  💡 Use /epic-deliver #[Story ID] to execute a Story.');
+  log('  💡 Use /deliver #[Story ID] to execute a Story.');
 
-  if (features.length > 0) {
-    log('');
-    log('  📦 Feature Containers (not directly executable):');
-    for (const f of features) {
-      log(`     #${f.storyId} — ${f.storySlug}`);
-    }
-  }
   log('');
 }

package/.agents/scripts/lib/signals/schema.js

@@ -98,7 +98,7 @@ export const EVENT_KINDS = Object.freeze({
   // Story #3819 — per-criterion acceptance self-eval signal emitted by
   // acceptance-eval.js. One record per Story per eval-loop terminus,
   // carrying which acceptance items needed rework and the round count, so
-  // the retro and /epic-plan Phase 0 feedback fetch can see acceptance
+  // the retro and /plan Phase 0 feedback fetch can see acceptance
   // churn alongside friction/hotspot data.
   ACCEPTANCE_EVAL: 'acceptance-eval',
 });

package/.agents/scripts/lib/spec/index.js

@@ -2,7 +2,7 @@
  * lib/spec/index.js — public surface for the spec I/O module.
  *
  * Re-exports the loader (and, in Wave 1, future spec utilities) so
- * downstream consumers — the reconciler, the rewritten /epic-plan, the
+ * downstream consumers — the reconciler, the rewritten /plan, the
  * wave-runner — can `import * from '../lib/spec/index.js'` without
  * reaching into individual submodules.
  *

package/.agents/scripts/lib/spec/loader.js

@@ -8,7 +8,7 @@
  *   - `temp/epic-<epic-id>/<epic-id>.state.json`  — slug→issue mapping (observed)
  *
  * Both files live under the per-Epic ephemeral tree `temp/epic-<id>/`
- * (already gitignored) so /epic-plan reruns don't churn a tracked path
+ * (already gitignored) so /plan reruns don't churn a tracked path
  * and so concurrent Epics never collide on a single shared directory.
  * Tests inject `opts.epicsDir` to point at a sandbox; the default for
  * production callers is derived from `lib/config/temp-paths.js#epicTempDir`.
@@ -382,7 +382,7 @@ export function writeState(epicId, state, opts = {}) {
  * the schema from the file itself.
  *
  * Story #1498 / Task #1525 introduced this writer so the rewritten
- * `/epic-plan` halves can persist the spec from the decomposer's
+ * `/plan` halves can persist the spec from the decomposer's
  * ticket-array projection (`renderSpec`) without reaching into raw
  * `js-yaml` calls scattered across the planning scripts.
  *

package/.agents/scripts/lib/spec/state.js

@@ -108,7 +108,7 @@ export function sha256Hex(input) {
 }
 
 /**
- * Hash a spec entry (a Feature, Story, or Task object) deterministically.
+ * Hash a spec entry (a Story object) deterministically.
  * The entry is canonicalised (recursive key-sort), serialised, and
  * sha256'd. Equivalent entries (any key order, equivalent nested order
  * for the object-valued fields) hash to the same digest.
@@ -126,10 +126,9 @@ export function hashSpecEntry(entry) {
 
 /**
  * Iterate every slug-bearing entity in the spec. Yields tuples of
- * `[slug, entry]` where `entry` is the raw object as authored in the
- * spec (feature/story/task). Order is feature-major, story-minor,
- * task-tertiary — the natural read order, useful for deterministic
- * mapping iteration.
+ * `[slug, entry]` where `entry` is the raw Story object as authored in
+ * the spec. Order follows `spec.stories[]` — the natural read order,
+ * useful for deterministic mapping iteration.
  *
  * Exported for tests; the reconciler diff path uses `projectMapping`
  * (below) rather than this generator directly.
@@ -138,17 +137,9 @@ export function hashSpecEntry(entry) {
  * @returns {Generator<[string, object]>}
  */
 export function* iterSpecEntries(spec) {
-  if (!spec || !Array.isArray(spec.features)) return;
-  for (const feature of spec.features) {
-    if (feature?.slug) yield [feature.slug, feature];
-    if (!Array.isArray(feature?.stories)) continue;
-    for (const story of feature.stories) {
-      if (story?.slug) yield [story.slug, story];
-      if (!Array.isArray(story?.tasks)) continue;
-      for (const task of story.tasks) {
-        if (task?.slug) yield [task.slug, task];
-      }
-    }
+  if (!spec || !Array.isArray(spec.stories)) return;
+  for (const story of spec.stories) {
+    if (story?.slug) yield [story.slug, story];
   }
 }
 

package/.agents/scripts/lib/story-init/context-resolver.js

@@ -21,7 +21,7 @@ import { resolveStoryHierarchy } from '../story-lifecycle.js';
  * @param {number} deps.input.storyId
  * @param {number|null} [deps.input.recutOf]
  * @param {boolean} [deps.input.dryRun]
- * @returns {Promise<{ story: object, body: string, epicId: number, featureId: number|null }>}
+ * @returns {Promise<{ story: object, body: string, epicId: number, parentId: number|null }>}
  */
 export async function resolveContext({ provider, logger, input }) {
   const { storyId, recutOf = null, dryRun = false } = input;
@@ -43,7 +43,7 @@ export async function resolveContext({ provider, logger, input }) {
   }
 
   let body = story.body ?? '';
-  const { epicId, featureId } = resolveStoryHierarchy(body);
+  const { epicId, parentId } = resolveStoryHierarchy(body);
 
   if (!epicId) {
     throw new Error(
@@ -88,5 +88,5 @@ export async function resolveContext({ provider, logger, input }) {
     }
   }
 
-  return { story, body, epicId, featureId };
+  return { story, body, epicId, parentId };
 }

package/.agents/scripts/lib/story-init/state-transitioner.js

@@ -2,8 +2,8 @@
  * state-transitioner.js — Stage 6 of the story-init pipeline.
  *
  * Flips the Story ticket to `agent::executing` at init time. Under the
- * 3-tier hierarchy the Story has inline acceptance and no child Task
- * lifecycle — `/story-deliver` runs a single Story-implementation phase.
+ * 2-tier hierarchy the Story has inline acceptance and no child Task
+ * lifecycle — `/deliver` runs a single Story-implementation phase.
  */
 
 import {

package/.agents/scripts/lib/story-init/task-graph-builder.js

@@ -14,7 +14,7 @@ import { fetchChildTickets } from '../story-lifecycle.js';
 
 /**
  * Detect whether a Story body carries inline acceptance criteria, the
- * structural signal that the Story is authored in the 3-tier
+ * structural signal that the Story is authored in the 2-tier
  * (Story-with-inline-acceptance) shape and therefore should not be expected
  * to enumerate child Task tickets. Recognises both `## Acceptance` and
  * `## Acceptance Criteria` headings, with at least one list bullet under
@@ -67,15 +67,15 @@ function sortTasksByDependencies(tasks) {
  * @param {object} deps.input
  * @param {number} deps.input.storyId
  * @param {string} [deps.input.storyBody]   Story body — used to detect
- *   whether the Story carries inline acceptance (3-tier shape) so the
+ *   whether the Story carries inline acceptance (2-tier shape) so the
  *   empty-Task-list path is treated as expected rather than as a warning.
  *
  * Task #3154 (Epic #3078) deleted the `planning.hierarchy` flag; the
- * 3-tier vs 4-tier mode is now derived entirely from the ticket shape —
- * inline acceptance + zero Tasks resolves to `'3-tier'`, otherwise
+ * 2-tier vs 4-tier mode is now derived entirely from the ticket shape —
+ * inline acceptance + zero Tasks resolves to `'2-tier'`, otherwise
  * `'4-tier'`.
  *
- * @returns {Promise<{ sortedTasks: Array<object>, mode: '3-tier'|'4-tier' }>}
+ * @returns {Promise<{ sortedTasks: Array<object>, mode: '2-tier'|'4-tier' }>}
  */
 export async function buildTaskGraph({ provider, logger, input }) {
   const { storyId, storyBody = '' } = input;
@@ -85,13 +85,13 @@ export async function buildTaskGraph({ provider, logger, input }) {
   const tasks = await fetchChildTickets(provider, storyId);
 
   const inlineAcceptance = hasInlineAcceptance(storyBody);
-  const mode = tasks.length === 0 && inlineAcceptance ? '3-tier' : '4-tier';
+  const mode = tasks.length === 0 && inlineAcceptance ? '2-tier' : '4-tier';
 
   if (tasks.length === 0) {
     if (inlineAcceptance) {
       progress(
         'TASKS',
-        `Story #${storyId} has inline acceptance — no child Tasks expected (3-tier shape).`,
+        `Story #${storyId} has inline acceptance — no child Tasks expected (2-tier shape).`,
       );
     } else {
       warn(

package/.agents/scripts/lib/story-lifecycle.js

@@ -10,7 +10,7 @@
  * (branch bootstrap, merge, cascade, notifications). Expanding this module to
  * cover those would over-abstract — they are genuinely different concerns.
  *
- * Under the 3-tier hierarchy (Epic #3078) Stories have no child tickets, so
+ * Under the 2-tier hierarchy (Epic #3078) Stories have no child tickets, so
  * `fetchChildTickets` typically returns `[]` — but the helper remains in
  * place so legacy callers still resolve the Story's direct children cleanly.
  */
@@ -24,7 +24,7 @@ import {
  * Parse the `Epic: #N` and `parent: #N` references from a Story body.
  *
  * @param {string} body  Raw Story body Markdown.
- * @returns {{ epicId: number|null, featureId: number|null }}
+ * @returns {{ epicId: number|null, parentId: number|null }}
  */
 export function resolveStoryHierarchy(body) {
   const source = body ?? '';
@@ -32,17 +32,17 @@ export function resolveStoryHierarchy(body) {
   const parentMatch = source.match(/(?:^\s*parent:\s*#(\d+))/im);
   return {
     epicId: epicMatch ? Number.parseInt(epicMatch[1], 10) : null,
-    featureId: parentMatch ? Number.parseInt(parentMatch[1], 10) : null,
+    parentId: parentMatch ? Number.parseInt(parentMatch[1], 10) : null,
   };
 }
 
 /**
  * Fetch the Story's direct child tickets via the provider.
  *
- * Under the 3-tier hierarchy (Epic #3078) Stories no longer enumerate
+ * Under the 2-tier hierarchy (Epic #3078) Stories no longer enumerate
  * child Task tickets — acceptance criteria and verification steps live
- * inline on the Story body, and decomposers emit only Epic / Feature /
- * Story issues. For those Stories this helper resolves to an empty
+ * inline on the Story body, and decomposers emit only Epic / Story
+ * issues. For those Stories this helper resolves to an empty
  * array because `provider.getSubTickets(storyId)` itself returns no
  * rows. The helper is retained as a thin pass-through so the three
  * orchestration callers (`story-init` prepare, `task-graph-builder`,
@@ -50,7 +50,7 @@ export function resolveStoryHierarchy(body) {
  * hydration that is easy to mock in tests and to instrument in the
  * provider layer.
  *
- * Legacy ticket trees that were planned before the 3-tier cutover may
+ * Legacy ticket trees that were planned before the 2-tier cutover may
  * still carry sub-tickets (PRD/Tech-Spec links recorded as direct
  * children, for example). The helper deliberately does **not** filter
  * those out — the caller is responsible for classifying anything that
@@ -59,7 +59,7 @@ export function resolveStoryHierarchy(body) {
  *
  * @param {object} provider  ITicketingProvider instance.
  * @param {number} storyId   Story ticket number to hydrate children for.
- * @returns {Promise<object[]>} Array of child tickets (empty under 3-tier).
+ * @returns {Promise<object[]>} Array of child tickets (empty under 2-tier).
  */
 export async function fetchChildTickets(provider, storyId) {
   return provider.getSubTickets(storyId);

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

@@ -1,5 +1,5 @@
 /**
- * story-plan.js — helpers for `/story-plan`.
+ * story-plan.js — helpers for `/plan`.
  *
  * Pure functions used by `.agents/scripts/story-plan.js` (the CLI).
  * Kept side-effect-free so the CLI stays a thin orchestrator and these

package/.agents/scripts/lib/templates/decomposer-prompts.js

@@ -2,7 +2,6 @@ import { LIMITS_DEFAULTS } from '../config/limits.js';
 import {
   DEFAULT_TASK_SIZING,
   DELIVERABLE_GRANULARITY_GUIDANCE,
-  SOFT_STORIES_PER_FEATURE,
 } from '../orchestration/ticket-validator-sizing.js';
 
 /**
@@ -13,22 +12,23 @@ import {
  * resolved value; importing it here means a fallback path (no caller-supplied
  * value) still tracks the framework default in `lib/config/limits.js`.
  *
- * 3-tier is the only published hierarchy after Task #3154 deleted the
- * `planning.hierarchy` flag: the prompt omits the Task layer entirely and
- * asks the planner to inline acceptance/verify on the Story body.
+ * 2-tier is the only published hierarchy after Story #4041 removed the
+ * Feature tier: the prompt emits Stories only (direct Epic children) and
+ * asks the planner to carry acceptance/verify as top-level ticket arrays.
  */
 export function renderDecomposerSystemPrompt({
   maxTickets = LIMITS_DEFAULTS.maxTickets,
 } = {}) {
-  return render3TierPrompt({ maxTickets });
+  return render2TierPrompt({ maxTickets });
 }
 
 /**
- * 3-tier prompt (Epic #3078). Decomposes to Feature → Story only — no Task
- * layer. Acceptance criteria and verification commands live inline on the
- * Story body so the executing agent has everything it needs in one ticket.
+ * 2-tier prompt (Story #4041). Decomposes to Stories only — no Feature and
+ * no Task layer. Acceptance criteria and verification commands live inline
+ * on the Story body so the executing agent has everything it needs in one
+ * ticket. Thematic grouping lives as prose in the Epic body / Tech Spec.
  */
-function render3TierPrompt({ maxTickets }) {
+function render2TierPrompt({ maxTickets }) {
   // Sizing thresholds are sourced from the single DEFAULT_TASK_SIZING constant
   // (ticket-validator-sizing.js) so the prompt and the validator cannot drift.
   const { softFiles, hardFiles, maxAcceptance, softAcceptanceCount } =
@@ -40,16 +40,16 @@ function render3TierPrompt({ maxTickets }) {
   const { definition: granularityDefinition, singleConsumerRule } =
     DELIVERABLE_GRANULARITY_GUIDANCE;
   return `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 highly-granular 2-level 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").
-2. **Stories**: Specific user-facing or architectural user stories (e.g., "Implement JWT Token Exchange").
-   - MUST be nested under a Feature.
-   - **Story-Level Execution**: Each Story will be executed end-to-end on a single branch by a single agent. There is NO Task layer in this hierarchy — acceptance criteria and verification commands live inline on the Story body (see STORY BODY SCHEMA below).
+1. **Stories**: Specific user-facing or architectural user stories (e.g., "Implement JWT Token Exchange").
+   - Every Story attaches directly to the Epic — there is NO Feature tier and NO Task layer in this hierarchy.
+   - **Story-Level Execution**: Each Story will be executed end-to-end on a single branch by a single agent. Acceptance criteria and verification commands live as top-level \`acceptance[]\` / \`verify[]\` arrays on the Story ticket (see STORY BODY SCHEMA below).
+   - Thematic grouping is prose in the Epic body / Tech Spec, never a ticket.
 
 ### LABEL CONVENTIONS:
-- Every ticket must have a \`type::[feature|story]\` label. The \`type::task\` label is FORBIDDEN under this hierarchy.
+- Every ticket must have the \`type::story\` label. No other type label is allowed — the retired Feature and Task tiers have no labels under this hierarchy.
 - Every ticket must have a \`persona::[engineer|architect|qa-engineer|engineer-web|etc]\` label indicating WHO should execute it.
 
 ### OUTPUT FORMAT:
@@ -58,43 +58,52 @@ You MUST respond ONLY with a valid JSON array of objects. No prose, no markdown
 ### JSON SCHEMA:
 [
   {
-    "slug": "unique_string_id",
-    "type": "feature" | "story",
+    "slug": "hyphen-case-id",
+    "type": "story",
     "title": "Short descriptive title",
-    "body": <string for features; see STORY BODY SCHEMA below for stories>,
-    "labels": ["type::...", "persona::..."],
-    "parent_slug": "slug_of_parent_ticket" (leave empty for features to nest under epic),
-    "depends_on": ["slug_of_blocking_dependency"] (optional array of slugs that block execution)
+    "body": <string — see STORY BODY SCHEMA below>,
+    "acceptance": ["<testable, observable criterion>", ...],
+    "verify": ["<exact command or test path> (<tier>)", ...],
+    "labels": ["type::story", "persona::..."],
+    "depends_on": ["slug-of-blocking-dependency"] (optional array of Story slugs that block execution)
   }
 ]
 
-### 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.
+**Slug format**: \`^[a-z0-9][a-z0-9-]*\$\` — hyphen-case only. Underscores are rejected by the validator.
 
-#### FEATURE GROUPING — CAPABILITY/STAKEHOLDER, NOT EXECUTION SHAPE:
+### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
+\`body\` MUST be a **string** — the serialized markdown produced by \`serialize()\` from \`lib/story-body/story-body.js\`. Do NOT emit \`body\` as a JSON object: an object body throws \`StoryBodyParseError\` in the reconciler (Story #3302) and is discarded by the GitHub provider, producing an empty issue body. Stories are consumed by non-interactive sub-agents that must self-verify from the Story ticket alone — so the ticket must carry everything an agent needs to execute and self-verify.
 
-- **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.
-- **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.
+The \`acceptance[]\` and \`verify[]\` arrays live at the **top level** of the Story ticket object (not nested inside \`body\`). The validator reads \`story.acceptance\` and \`story.verify\` directly — nesting them inside the body makes them invisible to the validator and the decompose is rejected.
 
-### STORY BODY SCHEMA (REQUIRED FOR EVERY STORY):
-For stories, \`body\` is a STRUCTURED OBJECT, not a string. Stories are consumed by non-interactive sub-agents that must self-verify from the Story body alone — there is no Task layer below — so the Story itself must carry everything an agent needs to execute and self-verify.
-
-  "body": {
-    "goal":                  "<one sentence — tie this story to the parent Feature slug, naming the slug>",
-    "changes":               ["<file path>: <verb> <object>", ...],
-    "acceptance":            ["<testable, observable criterion>", ...],
-    "verify":                ["<exact command or test path> (<tier>)", ...],
-    "estimated_test_files":  <integer — number of test files this Story is expected to create or modify; omit when not estimable>
-  }
+The serialized \`body\` string renders these markdown sections (in order):
+
+    ## Goal
+    <one sentence — why this Story exists within the Epic>
+
+    ## Changes
+    - {"path": "<file path>", "assumption": "creates" | "refactors-existing" | "deletes"}
+    - ...
+
+    ## Acceptance
+    - [ ] <testable, observable criterion>
+    - ...
+
+    ## Verify
+    - <exact command or test path> (<tier>)
+    - ...
+
+    ## References
+    - {"path": "<read-only dependency path>", "assumption": "exists"}
+    - ...
 
 #### STORY BODY RULES:
 
-- **goal**: One sentence stating WHY this story exists. MUST name the parent Feature slug.
-- **changes**: Each bullet MUST be \`<path-or-glob>: <concrete verb> <object>\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Vague verbs ("clean up", "refactor", "improve", "polish", "tighten") are FORBIDDEN unless paired with a named target — "refactor src/x.ts: extract handleSubmit" is fine, "refactor the form" is not.
-- **acceptance**: Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
-- **verify**: Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
-- **estimated_test_files** (optional): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
+- **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\`. Acceptable path shapes include explicit files (\`src/components/Foo.tsx\`), glob patterns (\`tests/e2e/*.spec.ts\`, \`**/*.astro\`), and module identifiers that resolve to files. Use \`refactors-existing\` for in-place edits to a file already on \`main\`; \`creates\` for net-new files; \`deletes\` for removals.
+- **acceptance** (top-level array on the ticket object): Items MUST be observable from outside the agent. Acceptable shapes: a specific command exits 0, a file exists at a given path, a snapshot test matches, a \`data-testid\` resolves under a given selector, a row count in a fixture matches. UNACCEPTABLE: "verify by reading the diff", "looks good", "matches the spec" — push these down into a \`verify\` command instead.
+- **verify** (top-level array on the ticket object): Each entry MUST name a testing tier in parentheses, drawn from \`unit\` / \`contract\` / \`e2e\` / \`validate\`. Example: \`npm run test -- src/x.test.ts (unit)\`, \`npm run validate (validate)\`. Stories with zero verify entries SHOULD fail validation; if a story is genuinely unverifiable in isolation (e.g., a copy edit auditor will eyeball), the literal entry \`manual:<reason>\` is allowed so the absence is intentional, not lazy. Manual entries without a reason are rejected.
+- **estimated_test_files** (optional, encoded in the \`<!-- meta: {...} -->\` comment appended to the serialized body string — NOT a top-level ticket field): Integer estimate of how many test files this Story creates or modifies. Omit when the number is not estimable. Informational only — it does not gate the decompose.
 
 #### STORY SIZING — COHESION FIRST (the numeric ceiling is only a backstop):
 
@@ -104,10 +113,8 @@ The primary question is **cohesion, not count**: *is this one coherent change wi
 
 - **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 — or two Stories that should be one.
 - ${singleConsumerRule}
-- **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). Declaring \`wide\` lifts the hard file-width ceiling — see below.
-- **Every Feature MUST decompose into at least TWO Stories.** A Feature with a single Story is the work of a Story, not a Feature — collapse it (drop the Feature wrapper and attach its lone Story to a sibling Feature, or merge the Feature into another). The validator HARD-rejects a Feature with fewer than two Stories.
-- **Features typically decompose into ≤${SOFT_STORIES_PER_FEATURE} Stories; otherwise split into a sibling Feature.** A Feature stretching past ${SOFT_STORIES_PER_FEATURE} Stories is a sign the Feature scope is two features.
 
 **Numeric backstop (validator-enforced).** These thresholds are sourced from the single \`DEFAULT_TASK_SIZING\` constant in \`ticket-validator-sizing.js\` — there is no second copy to drift:
 
@@ -117,7 +124,7 @@ The primary question is **cohesion, not count**: *is this one coherent change wi
 
 #### \`wide\` DECLARATION (optional — for legitimately broad changes):
 
-A Story whose footprint is legitimately broad declares \`body.wide\` carrying a one-line human-readable reason:
+A Story whose footprint is legitimately broad declares \`wide\` carrying a one-line human-readable reason. Encode it in the \`<!-- meta: {"wide": {"reason": "..."}} -->\` comment that \`serialize()\` appends to the body string — it is NOT a top-level ticket field:
 
 \`\`\`json
 "wide": { "reason": "hard contract cutover: migrate every <X> call site in one PR" }
@@ -139,11 +146,11 @@ Declaring \`wide\` with a non-empty reason **lifts the \`hardFiles\` rejection**
 - Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of \`docs/style-guide.md\` in \`acceptance\` (e.g. \`"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]\`). If \`docs/style-guide.md\` does not exist or has no relevant section, state that explicitly: \`"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in PRD §2"]\`. Silence on style sourcing is a smell.
 
 ### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when the Acceptance Spec has \`new\`-disposition rows):
-The Acceptance Spec's AC table (columns \`AC ID | Outcome | Feature File | Scenario | Disposition\`) tags each row's \`Disposition\` with one of \`new | updated | unchanged\`. A \`new\` row names a \`.feature\` file + scenario that does NOT yet exist on \`main\`. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file.
+The Acceptance Spec's AC table (columns \`AC ID | Outcome | Feature File | Scenario | Disposition\`) tags each row's \`Disposition\` with one of \`new | updated | unchanged\`. A \`new\` row names a \`.feature\` file + scenario that does NOT yet exist on \`main\`. The framework is features-first: implementing Stories reference those \`.feature\` paths in their \`verify[]\` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file. (These Gherkin \`.feature\` files are BDD artifacts, unrelated to any ticket tier.)
 
 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 the \`.feature\` files with \`@skip\`-tagged scenarios BEFORE any implementation Story runs:
 
-- **goal**: contains the literal token \`bdd-scaffold\` (e.g. "bdd-scaffold: create the @skip-tagged feature files the implementation Stories verify against, for parent Feature <slug>").
+- **goal**: contains the literal token \`bdd-scaffold\` (e.g. "bdd-scaffold: create the @skip-tagged feature files the implementation Stories verify against").
 - **depends_on**: EMPTY (\`[]\`) — it runs first, in wave 0.
 - **changes**: one entry per distinct \`.feature\` file named in a \`new\` row, each \`{ "path": "<feature file path>", "assumption": "creates" }\`.
 - **acceptance**: MUST assert (a) every new \`.feature\` file exists, and (b) every new scenario within them carries an \`@skip\` tag. Keep these observable (a grep/validate command exits 0, a file exists at a path).
@@ -153,16 +160,16 @@ When the Acceptance Spec contains **one or more \`Disposition: new\` rows**, you
 When the Acceptance Spec contains **zero \`new\`-disposition rows** (every row is \`updated\` or \`unchanged\`), do NOT emit a scaffold Story — there is nothing to create.
 
 ### SCOPE-OVERLAP FLAGGING (docs/runbook downstream of config work):
-When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same Epic whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story \`body.acceptance\` by appending an item of the form:
+When a "docs update" / "runbook" / "README" Story appears downstream of an earlier Story in the same Epic whose AC already covers updating the same document (e.g. a "config + runbook" Story followed by a "docs" Story touching the same runbook), the downstream Story's deliverable may be fully absorbed by the earlier Story. Flag the risk directly in the Story's top-level \`acceptance\` array by appending an item of the form:
 "Scope verification note: this story's deliverable may already be satisfied by Story #<slug-or-id>'s AC — before implementing, \`git diff main -- <path>\` against the upstream Story branch and confirm whether a substantive edit is still required, or whether only a cross-reference remains."
 This prevents the executing agent from redoing work the upstream Story already merged.
 
-CRITICAL: Dependencies should follow execution blockers. For hierarchical grouping, strictly use 'parent_slug' (Story parent MUST be a Feature). Features should have no 'parent_slug' (they attach to Epic).
-IMPORTANT DEPENDENCY RULE: Cross-Feature Story dependencies are allowed via \`depends_on\` at the Story level (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
+CRITICAL: Dependencies should follow execution blockers. Stories attach directly to the Epic — never emit a 'parent_slug' field.
+IMPORTANT DEPENDENCY RULE: Story-to-Story dependencies are expressed via \`depends_on\` (one Story depends_on another Story's slug). Use this to express execution ordering across the plan.
 
 ### REVIEWABILITY BUDGET (Story #2798):
 \`maxTickets = ${maxTickets}\` is a **reviewability budget**, not a hard authoring cap. It marks the count of tickets a human operator can comfortably review in one planning pass; emitting more than this overflows the operator's review window. Default behaviour:
 - **Stay at or under the budget when possible.** Merge narrow, single-module stories into larger, cohesive capability stories before splitting; small Stories should merge back into siblings rather than spawn their own container.
-- **Do NOT truncate or over-compress to fit.** If the plan genuinely needs more tickets than the budget, emit the full plan anyway and add a compact \`over_budget_rationale\` string at the top of the FIRST Feature's \`body\` explaining (a) why the plan exceeds the budget and (b) what was already merged to keep the count down. The operator will then either accept the plan by re-running the decompose with the explicit \`--allow-over-budget\` override flag, or push back and ask for a re-scope.
+- **Do NOT truncate or over-compress to fit.** If the plan genuinely needs more tickets than the budget, emit the full plan anyway and add a compact \`over_budget_rationale\` note inside the FIRST Story's \`## Goal\` section explaining (a) why the plan exceeds the budget and (b) what was already merged to keep the count down. The operator will then either accept the plan by re-running the decompose with the explicit \`--allow-over-budget\` override flag, or push back and ask for a re-scope.
 - **Never stop mid-array.** Always emit complete JSON — partial arrays are rejected by the validator.`;
 }

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

@@ -37,7 +37,7 @@ import { WaveRunnerError } from './wave-runner-error.js';
  *   totalWaves:     number
  *
  * Wave grouping comes from the checkpoint's `state.plan` (the GH-derived
- * dependency-DAG grouping originally seeded by /epic-plan).
+ * dependency-DAG grouping originally seeded by /plan).
  *
  * @typedef {object} WaveTickArgs
  * @property {number | { id: number }} epic

package/.agents/scripts/lifecycle-emit-story-dispatch.js

@@ -5,7 +5,7 @@
  *
  * Thin host-loop CLI that appends a single `story.dispatch.start`
  * NDJSON record to `temp/epic-<id>/lifecycle.ndjson`. Invoked by
- * `/epic-deliver` Phase 2 immediately BEFORE each per-Story Agent
+ * `/deliver` Phase 2 immediately BEFORE each per-Story Agent
  * tool call so the lifecycle ledger durably records every dispatch
  * attempt. The `wave-tick.js` reconciler (Story #2891 Task #2901)
  * then derives `nextAction['in-flight']` from this ledger to surface

package/.agents/scripts/lifecycle-emit.js

@@ -6,7 +6,7 @@
  *
  * Replaces the three single-purpose emit shims
  * (`epic-deliver-finalize.js`, `epic-deliver-automerge.js`,
- * `epic-deliver-cleanup.js`) that the `/epic-deliver` workflow markdown
+ * `epic-deliver-cleanup.js`) that the `/deliver` workflow markdown
  * invoked in Phase 6, 7.5, and 8. Those shims each did exactly one
  * thing: construct a bus and emit one event. Collapsing them into a
  * single argv-driven CLI lets the workflow stay declarative ("fire

package/.agents/scripts/providers/github/board-add.js

@@ -3,7 +3,7 @@
  *
  * Story #3822 — single source of truth for the post-create board-add
  * step. Issues created through any create path (`createTicket`,
- * `createIssue` — which backs `/story-plan` persist and the `/epic-plan`
+ * `createIssue` — which backs `/plan` persist and the `/plan`
  * Phase 4 Epic open) must land on the configured Projects V2 board
  * without relying on GitHub's "Auto-add to project" built-in workflow,
  * which is off by default on fresh boards and cannot be enabled via API.

package/.agents/scripts/providers/github/errors.js

@@ -109,7 +109,7 @@ export function classifyGithubError(err) {
 // callers (paginateRest, getTicket, getNativeSubIssues, …) absorb the same
 // jittered exponential backoff on transient GitHub errors instead of
 // bubbling a one-shot 502/429/ECONNRESET that kills a longer pipeline
-// (e.g. the /epic-deliver Phase E retro).
+// (e.g. the /deliver Phase E retro).
 
 export const TRANSIENT_RETRY_DEFAULTS = Object.freeze({
   maxAttempts: 6,

package/.agents/scripts/providers/github/mappers.js

@@ -57,7 +57,7 @@ export function issueToEpic(issue) {
 export function subIssueNodeToTicket(node) {
   // Story #3097 (Wave-0 additive, Epic #3078 Strategy B) — return `null`
   // for absent sub-issue nodes instead of dereferencing properties on
-  // `null`/`undefined`. In 3-tier mode a Story can legitimately have zero
+  // `null`/`undefined`. In 2-tier mode a Story can legitimately have zero
   // Task children, which surfaces as an empty / missing sub-issue node
   // when callers iterate the GraphQL response and pass each entry through
   // this mapper. The legacy 4-tier path also benefits — a transient
@@ -83,7 +83,7 @@ export function subIssueNodeToTicket(node) {
  * any null/undefined entries. Story #3097 (Wave-0 additive, Epic #3078
  * Strategy B) — gives callers a single Storyless-tolerant entry point so
  * the existing per-node mappers can stay strict for the 4-tier path while
- * the 3-tier path (Storyless: a Story with zero child Tasks) gets a
+ * the 2-tier path (Storyless: a Story with zero child Tasks) gets a
  * well-defined empty-array result.
  *
  * @param {Array<object|null|undefined>|null|undefined} nodes

package/.agents/scripts/providers/github/tickets.js

@@ -42,8 +42,8 @@ import {
 const SEARCH_PAGE_CAP = 10;
 
 /**
- * Compose the final markdown body for a created ticket. Under the 3-tier
- * hierarchy (Epic → Feature → Story), `body` is always a string supplied
+ * Compose the final markdown body for a created ticket. Under the 2-tier
+ * hierarchy (Epic → Story), `body` is always a string supplied
  * by the caller (the decomposer, the spec planner, or the reconciler-apply
  * engine). This helper appends the canonical orchestrator footer
  * (`parent: #<n>` / `Epic: #<m>` / `blocked by #<x>`) byte-stable with the
@@ -361,8 +361,8 @@ export class TicketGateway {
   /**
    * Create a **bare** issue — no `parent: #N` footer composition and no
    * sub-issue link. Serves the standalone create paths that bypass
-   * `createTicket`'s Story-shaped body rendering: the `/story-plan`
-   * persist step and the `/epic-plan` Phase 4 Epic open
+   * `createTicket`'s Story-shaped body rendering: the `/plan`
+   * persist step and the `/plan` Phase 4 Epic open
    * (`openEpicFromOnePager`'s `createIssue` port).
    *
    * After the POST, the new issue is added to the configured Project V2

package/.agents/scripts/resync-status-column.js

@@ -5,7 +5,7 @@
  * resync-status-column.js — re-assert the GitHub Projects v2 Status
  * column for a ticket after auto-merge has fired (Story #2845).
  *
- * The `/single-story-deliver` and `/story-deliver` workflow docs call
+ * The `/single-story-deliver` and `/deliver` workflow docs call
  * this CLI after Step 5 confirms `state: "MERGED"` so the orchestrator
  * wins the race against the GitHub built-in `Pull request merged`
  * workflow, which would otherwise overwrite Status to whatever value

package/.agents/scripts/retro-run.js

@@ -2,9 +2,9 @@
 /* node:coverage ignore file */
 
 /**
- * retro-run.js — execute the `/epic-deliver` Phase 6 retro from a CLI.
+ * retro-run.js — execute the `/deliver` Phase 6 retro from a CLI.
  *
- * Phase 6 of `/epic-deliver` posts the Epic retro by invoking the
+ * Phase 6 of `/deliver` posts the Epic retro by invoking the
  * in-process retro module (`lib/orchestration/retro-runner.js`'s
  * `runRetro`). That module is a library entry point — it has no CLI
  * wrapper and hard-requires both a GitHub `provider` and a lifecycle

package/.agents/scripts/run-lint.js

@@ -64,7 +64,7 @@ const tasks = [
     // only the canonical `<axis>::<value>` separator from
     // `lib/label-constants.js` appears. Closes the drift gap that
     // let the original `type/epic` typo land at
-    // `.agents/workflows/epic-plan.md:49`.
+    // `.agents/workflows/helpers/plan-epic.md:49`.
     name: 'label-vocabulary',
     cmd: 'node',
     args: ['.agents/scripts/lint-label-vocabulary.js'],

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

@@ -139,7 +139,7 @@ export function makeGhRunner(cwd) {
 export function assertDeliverableStory(story, storyId) {
   if (!story.labels.includes(TYPE_LABELS.STORY)) {
     throw new Error(
-      `Issue #${storyId} is not a Story (labels: ${story.labels.join(', ')}). Use /story-deliver or /epic-deliver for Epic-attached work.`,
+      `Issue #${storyId} is not a Story (labels: ${story.labels.join(', ')}). Use /deliver or /deliver for Epic-attached work.`,
     );
   }
   if (story.state === 'closed') {