mandrel 1.59.0 → 1.61.0

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/lib/worktree/node-modules-strategy.js

@@ -20,6 +20,7 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { detectPackageManager } from '../detect-package-manager.js';
 
 function sleepSync(ms) {
   if (!Number.isFinite(ms) || ms <= 0) return;
@@ -110,10 +111,12 @@ export function selectInstallCommand(strategy, wtPath, fsLike = fs) {
   if (strategy === 'pnpm-store') {
     return { cmd: 'pnpm', args: ['install', '--frozen-lockfile'] };
   }
-  if (fsLike.existsSync(path.join(wtPath, 'pnpm-lock.yaml'))) {
+  // Shared lockfile probe (Story #4048 B3 — one implementation per concept).
+  const pm = detectPackageManager(wtPath, (p) => fsLike.existsSync(p)) ?? 'npm';
+  if (pm === 'pnpm') {
     return { cmd: 'pnpm', args: ['install', '--frozen-lockfile'] };
   }
-  if (fsLike.existsSync(path.join(wtPath, 'yarn.lock'))) {
+  if (pm === 'yarn') {
     return { cmd: 'yarn', args: ['install', '--frozen-lockfile'] };
   }
   return { cmd: 'npm', args: ['ci'] };

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') {

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: