mandrel 1.91.0 → 1.92.0

package/.agents/workflows/helpers/plan-epic.md

@@ -1,1038 +1,285 @@
 ---
 description:
-  Orchestrates end-to-end Epic planning (Tech Spec, Acceptance Spec, and
-  Work Breakdown) for a GitHub Epic.
+  Epic planning path invoked by /plan — three steps (interrogate → author →
+  persist) that produce the Epic body's Tech Spec + Acceptance Table managed
+  sections and the Story backlog (or a single-delivery routing marker).
 ---
 
 # helpers/plan-epic — Epic planning path (invoked by /plan)
 
-## Role
+## Shape
 
-Director / Architect
+Three steps replace the retired 12-phase pipeline (Epic #4474). All GitHub
+reads concentrate in `plan-context.js` (step 1), all GitHub writes in
+`plan-persist.js` (step 3); the authoring middle reads one JSON envelope and
+writes 2–4 files. Exactly two HITL STOP gates: **gate #1** at the exit of
+interrogate, **gate #2** risk-routed before persist. Every deterministic
+validator of the old pipeline survives inside the persist CLI.
 
-## Context
+## Constraints
 
-You are the master orchestrator for the v5 Epic-Centric ticketing pipeline. Your
-goal is to transform a high-level Epic into a fully decomposed, ready-to-execute
-backlog of Stories.
+- Do not modify existing issues without explicit permission. Every GitHub
+  mutation runs inside `plan-persist.js` — or `epic-plan-clarity.js` for a
+  gate-#1-approved body refinement — never via ad-hoc `gh issue edit`.
+- Never bypass a persist rejection by editing GitHub directly: fix the named
+  artifact and re-run the CLI (one targeted amend pass, below).
 
-`/plan` is the unified planning entry point. This file (`helpers/plan-epic.md`)
-is the single authoritative home for Phase 7 (spec) and Phase 8 (decompose) —
-it carries the full step-by-step procedure for both and delegates only the
-authoring middle of each to the
-[`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md) /
-[`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
-skills. It runs both phases sequentially with a human confirmation gate
-between them. The Epic ID is the single positional argument.
+## Step 1 — Interrogate
 
-> **Thin pointers, not duplicate procedures.** [`helpers/epic-plan-spec.md`](epic-plan-spec.md)
-> and [`helpers/epic-plan-decompose.md`](epic-plan-decompose.md) used to
-> restate Phase 7/8 as their own inline step lists — a drifted, pre-skill
-> pattern now that authoring is delegated to the two skills above. Both files
-> are now thin pointers back to this one; do not resurrect inline step lists
-> in either.
+Goal: shared understanding and a confirmed planning basis. Grilling
+discipline: ask questions **one at a time** — asking multiple questions at
+once is bewildering. If a **fact** can be found by exploring the codebase,
+look it up rather than asking; the **decisions** are the operator's — put
+each one to them. Do not proceed to authoring until shared understanding is
+confirmed (gate #1).
 
-As of v5.6, planning artifacts (Tech Spec, ticket decomposition) are
-authored **directly by you, the host LLM** — no external Gemini / Anthropic /
-OpenAI API is called. The Node scripts are deterministic GitHub I/O wrappers
-that (a) emit the authoring context you need and (b) validate and persist the
-artifacts you author.
+### Ideation entry (`--idea "<seed>"` or no argument)
 
-## Constraint
-
-- Do not modify existing issues without explicit permission.
-- Wait for user validation before migrating to Phase 8 when
-  `planningRisk.requiresReview` is true (or the operator passes
-  `--force-review`). Low-risk Epics auto-proceed after spec validation.
-  See [SDLC § Adaptive planning risk routing](../../docs/SDLC.md#adaptive-planning-risk-routing)
-  for the full envelope shape and the planner-selected
-  `acceptance::n-a` route.
-- Delegate Phase 7 and Phase 8 authoring to the
-  [`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md)
-  and [`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
-  skills respectively — the deterministic `epic-plan-spec.js` /
-  `epic-plan-decompose.js` CLIs (invoked by this file's own Phase 7 / Phase 8
-  steps) own the Epic lifecycle label transitions and the `epic-plan-state`
-  checkpoint. This wrapper must not apply those labels directly.
-
-## Prerequisites
-
-1. **GitHub Epic**: An existing GitHub Issue with the `type::epic` label.
-   Skipped when entering via Phase 1 / `--idea` (the Epic does not exist
-   yet — Phases 1–4 will create it).
-2. **API Keys**: `GITHUB_TOKEN` must be set in the `.env` file.
-
-## Phase 1: Idea Refinement (s-plan-ideation entry)
-
-This phase runs **only** when no `<epic#>` argument is supplied, or when
-`--idea "<seed>"` is passed. If an Epic ID was provided, skip directly to
-Phase 5 (Re-Plan Detection).
-
-1. **Activate the ideation skill**: Read
-   `<agentRoot>/skills/core/idea-refinement/SKILL.md` via the `Read`
-   tool (resolve `<agentRoot>` from `project.paths.agentRoot` —
-   default `.agents`) and execute its procedure with the `--idea` value
-   (or a user-supplied seed if no argument was given) as the seed. The
-   skill drives its own three-phase divergent → convergent → sharpen
-   loop and returns a markdown one-pager with the canonical sections
-   (Problem Statement, Recommended Direction, Key Assumptions, MVP
-   Scope, Not Doing). This is the canonical pattern for framework
-   skills — they are library-style content read on-demand per
-   `<agentRoot>/instructions.md` section 1.B, not entries in the
-   host's harness-level skill registry.
-
-2. **Run Phase 1.5 (Scope Triage) before the HITL stop**: The sharpened
-   one-pager feeds the scope-triage gate below, whose verdict folds into
-   the **same** Phase 1 HITL confirmation. Do not stop twice.
-
-3. **HITL stop — confirm the sharpened one-pager** (**gate #1**): Display
-   the one-pager to the operator and **STOP**. Do not proceed to Phase 2
-   until the user explicitly confirms the direction. This is the same gate
-   the skill's own Phase 3 enforces; surfacing it here makes the wait
-   contract visible to `/plan` callers. When the Phase 1.5 verdict is
-   `story` or `borderline`, this stop carries the three-way choice the
-   triage gate defines (below) instead of a plain confirm.
-
-   > **`--yes` (headless) auto-proceed.** When `/plan` was invoked with
-   > `--yes`, this gate does **not** STOP: the one-pager confirm resolves as
-   > **approved** and the run continues to Phase 2. A `story` / `borderline`
-   > triage verdict resolves to its **Recommended** branch (below) rather
-   > than prompting the three-way choice. Display the one-pager and the
-   > verdict line for the record, then proceed without waiting. See
-   > [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
-
-## Phase 1.5: Scope Triage (ideation path only)
-
-This phase runs the shared scope-triage gate over the Phase 1 one-pager. The
-gate mechanics — verdict meanings, the three-way operator choice, the `--yes`
-resolution, and the no-re-triage rule — live in the single-homed fragment
-[`scope-triage-gate.md`](scope-triage-gate.md); read it and follow it. This
-phase supplies only its path-specific firing conditions:
-
-- **When it runs**: only on the ideation path, immediately after Phase 1
-  produces the sharpened one-pager. The rubric is applied to the **Phase 1
-  one-pager**, and the verdict folds into the **existing Phase 1 HITL stop**
-  (do **not** add a second stop).
-- **When it is skipped**: entirely, when an Epic ID argument was supplied (the
-  existing-Epic path jumps straight to Phase 5); and when `/plan` was entered
-  via a scope-triage handoff from [`/plan`](plan-story.md) (the no-re-triage
-  rule in the fragment).
-- **Recommended branch on a `story` / `borderline` verdict**: persist the
-  one-pager to a notes file and hand off to `/plan --from-notes <path>`,
-  identifying the invocation as a scope-triage handoff so `/plan` skips its
-  own gate, then **exit `/plan`**. The alternative branches are **plan as Epic
-  anyway** (continue to Phase 2) and **abort**.
-
-## Phase 2: Cross-Epic Duplicate Search
-
-Runs immediately after Phase 1 (and only on the s-plan-ideation path).
-Its job is to surface open Epics whose scope already overlaps with the
-sharpened one-pager so the operator can fold the work in rather than
-opening a duplicate.
-
-1. **Invoke the duplicate-search module**: Call
-   `findSimilarOpenEpics({ onePager, provider })` exported from
-   [`.agents/scripts/lib/duplicate-search.js`](../../scripts/lib/duplicate-search.js).
-   The `provider` is the resolved ticketing provider
-   (`provider-factory.js`), and `onePager` is the markdown returned by
-   Phase 1.
-
-2. **HITL pause on match**: If the module returns a non-empty ranked
-   list, render the candidates (id, title, score, URL) and **STOP**. Do
-   not proceed to Phase 3 until the user either (a) confirms the new
-   Epic is genuinely distinct or (b) chooses to fold the idea into one of
-   the existing Epics, in which case `/plan` exits and the operator
-   resumes work on the existing Epic ID.
-
-3. **No-match fast path**: If the module returns `[]`, proceed
-   immediately to Phase 3 — no operator intervention required.
-
-## Phase 3: Render Epic Body from One-Pager
-
-Runs after Phase 2 clears (no duplicates, or operator confirmed the
-new Epic is genuinely distinct).
-
-1. **Render the body**: Call
-   `renderEpicBody({ onePager, template })` exported from
-   [`.agents/scripts/lib/epic-plan-ideation.js`](../../scripts/lib/epic-plan-ideation.js).
-   The `template` argument is the contents of
-   [`.agents/templates/epic-from-idea.md`](../../templates/epic-from-idea.md),
-   which carries the five canonical sections (Context, Goal, Non-Goals,
-   Scope, Acceptance Criteria). Sections missing from the one-pager are
-   rendered as `_(not specified)_` rather than left as raw `{{token}}`
-   placeholders.
-
-2. **HITL stop — confirm the body**: Display the rendered body to the
-   operator and **STOP**. Do not proceed to Phase 4 until the user
-   explicitly confirms the body is correct. This is the last chance to
-   tweak wording before the GitHub Issue is opened.
-
-## Phase 4: Open the GitHub Issue (`type::epic` only)
-
-1. **Open the Epic Issue**: Call
-   `openEpicFromOnePager({ onePager, template, createIssue })` from the
-   same `epic-plan-ideation.js` module. Pass a `createIssue` port that
-   delegates to the resolved ticketing provider's `createIssue` method
-   (`provider-factory.js`; GitHub: `TicketGateway.createIssue`) so the
-   labels and body land via the canonical I/O surface.
-
-   **Board membership (Story #3822)**: the provider's `createIssue`
-   adds the new Epic to the configured Projects V2 board via the
-   shared `addIssueToBoard` helper
-   ([`providers/github/board-add.js`](../../scripts/providers/github/board-add.js))
-   — idempotent, non-fatal (warn-on-error), and a no-op when no
-   project number is configured — so the Epic lands on the board
-   without relying on GitHub's "Auto-add to project" built-in
-   workflow (off by default on fresh boards and not enableable via
-   API). The created issue's GraphQL `node_id` is surfaced as
-   `nodeId` on the returned envelope for follow-up board operations.
-
-2. **Label discipline**: The Issue is opened with **only** the
-   `type::epic` label. **Do not** add any `state::*` label at creation
-   time — the Epic carries only `type::epic` until spec authoring
-   advances it to `agent::review-spec` in Phase 7. The
-   `openEpicFromOnePager` helper already enforces this; the workflow
-   prose codifies the intent so future label-set tweaks don't silently
-   widen it.
-
-3. **Continue to Phase 5**: The captured Epic ID becomes the new
-   `[Epic_ID]` for the rest of the planning pipeline. Re-Plan Detection
-   (Phase 5) will short-circuit because the fresh Epic body carries no
-   Tech Spec sections yet, so the run flows naturally into Phase 6
-   (Epic Clarity Gate) and then Phase 7.
-
-## Phase 5: Re-Plan Detection
-
-Before generating any artifacts, check whether the Epic has already been
-planned.
-
-1. **Fetch Epic**: Read the Epic issue body and check for Tech Spec
-   content — the managed `<!-- mandrel:tech-spec:start/end -->` section or
-   a bare `## Delivery Slicing` heading (`hasTechSpecContent` in
-   [`lib/epic-body-sections.js`](../../scripts/lib/epic-body-sections.js)).
-   The Tech Spec sections alone are the already-planned signal. Historical
-   Epics may still carry a legacy `## Planning Artifacts` section linking
-   retired `context::*` tickets — those links are **ignored** (never
-   fetched); only the body sections count.
-2. **If already planned**: Inform the user that this Epic already carries
-   planning sections. Ask:
-
-   > "Epic #[ID] already carries a Tech Spec (`## Delivery Slicing`) with
-   > YY decomposed tickets. Do you want to **re-plan**? This will
-   > **overwrite the Tech Spec and Acceptance Table sections of the Epic
-   > body in place** (comment history preserved) and **close-and-recreate**
-   > all child Story tickets."
-
-3. **If user confirms re-plan**: Pass `--force` to all subsequent script
-   invocations. Under `--force`, the Epic body's managed sections (Tech
-   Spec, Acceptance Table) are overwritten in place — the Epic's issue
-   number and prior discussion are preserved, and the Epic receives a
-   one-line regeneration audit comment. Child Story tickets are still
-   closed and recreated, because a re-decomposition can legitimately produce a
-   different ticket set.
-4. **If user declines**: Abort gracefully.
-
-## Phase 5.5: Story-Sized Advisory (existing-Epic path)
-
-An **advisory** scope-triage check that catches a story-sized scope which was
-hand-opened directly as a `type::epic` issue before any ceremony is paid for.
-Phase 6's Epic Clarity Gate scores section *presence*, not scope *size* — a
-perfectly clear but story-sized Epic (typically a thin, freshly opened issue)
-sails straight through to full planning. This advisory is the size check the
-clarity gate does not make.
-
-### Firing condition (load-bearing)
-
-The advisory runs **only** when **both** hold:
-
-1. **Phase 5 found no planning sections** — the Epic body carries no Tech
-   Spec content (no managed section, no `## Delivery Slicing` heading —
-   i.e. Phase 5 did **not** enter its re-plan branch).
-2. **The Epic has no open Story children** — no open `type::story`
-   sub-issues are linked to this Epic.
-
-If **either** condition fails, **skip this phase silently** and continue to
-Phase 6. It must **never** fire on the re-plan path: recommending a "downgrade
-to a Story" on an Epic that already carries folded Tech Spec sections and a
-ticket tree is nonsense and would collide with the `--force` re-plan flow. The advisory also
-does not fire on the ideation path — that path already ran the Phase 1.5 scope
-triage on the one-pager before the Epic existed.
-
-### Triage
-
-Run the shared scope-triage gate over the **Epic body** — the gate mechanics
-(verdict meanings, the three-way operator choice, the `--yes` resolution, and
-the no-re-triage rule) live in [`scope-triage-gate.md`](scope-triage-gate.md);
-read it and follow it. The scope-triage skill is artifact-agnostic, so it
-reads the same against an Epic body as against a one-pager or a Story draft.
-The path-specific bindings for this advisory:
-
-- **`epic` verdict** → proceed silently to Phase 6. No extra prompt, no HITL
-  stop.
-- **`story` / `borderline` verdict** → **STOP** and present the three-way
-  choice, whose **Recommended** branch here is **convert to a standalone
-  Story** via the conversion path below. The alternative branches are
-  **proceed as Epic anyway** (continue to Phase 6 with the Epic unchanged) and
-  **abort** (the Epic is left exactly as it was; no labels move and nothing is
-  closed).
-
-### Conversion path (close-and-recreate)
-
-Conversion is **close-and-recreate**, not in-place relabeling. A `type::epic`
-body does not satisfy `validateStoryBody` (it lacks the required Story
-sections and would have to drop the Epic shape), and editing or relabeling the
-existing issue violates the workflow's "Do not modify existing issues without
-explicit permission" Constraint. So the conversion seeds a fresh Story and
-closes the Epic in its favor, and **every** issue mutation below happens
-**only after the operator explicitly confirms the conversion in-session**:
-
-1. **Seed a notes file from the Epic body.** Write the Epic's Context / Goal /
-   Scope / Acceptance Criteria into a seed file under
-   `temp/epic-[Epic_ID]/scope-triage-seed.md` (the `temp/` tree is gitignored).
-   This is the same notes-file shape `/plan --from-notes` consumes.
-
-2. **Hand off to `/plan --from-notes`.** Invoke
-   [`/plan --from-notes temp/epic-[Epic_ID]/scope-triage-seed.md`](plan-story.md),
-   **identifying the invocation as a scope-triage handoff** so `/plan`
-   skips its own escalation gate (the skill's no-re-triage rule — a handoff is
-   a settled triage decision, and re-running the gate on the receiving side
-   would re-litigate it and risk a ping-pong between the two workflows). The
-   replacement Story's `## Notes` section links back to the closed Epic
-   (`Converted from Epic #[Epic_ID] — scope triaged as a standalone Story`) so
-   the audit trail is bidirectional.
-
-3. **Close the Epic in favor of the replacement.** Once `/plan` has
-   created the replacement Story (capture its number as `#N`), close the Epic
-   with a cross-linking comment:
+1. Activate the [`core/idea-refinement`](../../skills/core/idea-refinement/SKILL.md)
+   skill with the seed. It returns a one-pager with the canonical sections
+   (Problem Statement, Recommended Direction, Key Assumptions, MVP Scope,
+   Not Doing). Write it to `temp/plan-ideation/<slug>/one-pager.md` (slug
+   from the title; the tree is gitignored).
+2. Emit the authoring envelope:
 
    ```bash
-   gh issue close [Epic_ID] --repo <owner>/<repo> \
-     --comment "Closed in favor of #N — scope triaged as a standalone Story."
+   node .agents/scripts/plan-context.js \
+     --one-pager temp/plan-ideation/<slug>/one-pager.md \
+     > temp/plan-ideation/<slug>/plan-context.json
    ```
 
-   This is the only `gh issue close` in the path, and it runs **after** the
-   replacement Story exists, so the conversion never strands a closed Epic
-   with no successor. The replacement-Story back-link plus this close comment
-   give a reviewer the full bidirectional trail.
-
-The conversion mutates two issues (creates the Story, closes the Epic) — both
-behind the single operator confirmation above. After conversion `/plan`
-exits: the work now lives on the standalone Story, which the operator delivers
-via [`/single-story-deliver`](single-story-deliver.md) or
-[`/deliver`](deliver-stories.md).
-
-## Phase 6: Epic Clarity Gate
-
-Runs on every existing-Epic invocation, after Phase 5 (Re-Plan
-Detection) and the Phase 5.5 story-sized advisory, and before Phase 7
-(Tech Spec & Acceptance Spec). The gate scores the Epic body
-against the five clarity-scored canonical
-sections from
-[`.agents/templates/epic-from-idea.md`](../../templates/epic-from-idea.md)
-(Context, Goal, Non-Goals, Scope, Acceptance Criteria — the template
-also carries a `## User Stories` section, which the clarity rubric does
-not score) and either
-skips fast (when the Epic body is already clear) or drops into a
-refinement loop seeded from the current Epic body. The scorer also
-accepts common heading variants for back-compat (e.g. `## Problem`,
-`## Direction`, `## MVP Scope`, `## Not Doing`, `## Out of Scope`) so
-hand-authored Epics that predate the canonical headings continue to
-pass without rewording.
-
-The rubric is deterministic: section-presence against the five
-canonical headings. A `clear` verdict requires **both** ≥ 4 of 5
-sections present **and** the **Acceptance Criteria** section present —
-AC is a required section, not one of the four optional passers, so an
-Epic with no Acceptance Criteria is always `needs-refinement` (it would
-otherwise hard-fail the `/deliver` start gate downstream). See
-[`lib/epic-plan-clarity.js`](../../scripts/lib/epic-plan-clarity.js)
-for the scoring logic.
-
-1. **Score the body**: Run the clarity-check CLI in context-emission
-   mode.
+   The ideation envelope carries `duplicates[]` (cross-Epic dup search),
+   `deliveryShapeSignal`, `docsContext`, `codebaseSnapshot`, `ticketSchema`,
+   and the rendered `systemPrompts`. The Epic does **not** exist yet —
+   creation happens in step 3.
+3. Run the shared scope-triage gate over the one-pager — mechanics in
+   [`scope-triage-gate.md`](scope-triage-gate.md). The verdict folds into
+   gate #1. The Recommended branch on a `story` / `borderline` verdict:
+   persist the one-pager as a notes file and hand off to
+   [`plan-story.md`](plan-story.md) via `/plan --from-notes <path>` as a
+   scope-triage handoff (no re-triage on the receiving side), then exit this
+   path. Skipped entirely when `/plan` was itself entered via a scope-triage
+   handoff.
+4. Review `duplicates[]`. A non-empty ranked list folds into gate #1: the
+   operator either confirms the new Epic is distinct or folds the idea into
+   an existing Epic (in which case `/plan` exits).
+
+### Existing-Epic entry (`/plan <epicId>`)
+
+1. Emit the authoring envelope:
 
    ```bash
-   node .agents/scripts/epic-plan-clarity.js --epic [Epic_ID] --emit-context \
-     > temp/epic-[Epic_ID]/clarity-context.json
+   node .agents/scripts/plan-context.js --epic [Epic_ID] \
+     > temp/epic-[Epic_ID]/plan-context.json
    ```
 
-   The envelope carries
-   `{ epicId, epicBody, verdict, sections, missingOrPlaceholder }`.
-
-2. **Clear fast path**: When `verdict === 'clear'`, print
-   `Epic clarity: clear — proceeding to Phase 7.` and continue. No
-   HITL, no prompt.
-
-3. **Needs-refinement path**: When `verdict === 'needs-refinement'`,
-   activate the
-   [`core/idea-refinement`](../../skills/core/idea-refinement/SKILL.md)
-   skill **seeded from the current Epic body** (not a blank seed),
-   with `missingOrPlaceholder` as the convergence target. The skill
-   runs its three-phase divergent → convergent → sharpen loop and
-   returns a sharpened one-pager.
-
-4. **Re-render the body**: Call
-   `renderEpicBody({ onePager, template })` from
-   [`lib/epic-plan-ideation.js`](../../scripts/lib/epic-plan-ideation.js)
-   (the same helper Phase 3 uses), passing the contents of
-   [`.agents/templates/epic-from-idea.md`](../../templates/epic-from-idea.md).
-   Write the result to `temp/epic-[Epic_ID]/clarity-update.md`.
-
-5. **HITL stop — confirm the diff**: Display the diff between the
-   current Epic body and the sharpened body and **STOP**. Operator
-   approves, edits, or aborts. Flag the blast radius in the
-   confirmation prompt: an approved body change feeds **two**
-   downstream artifacts (Tech Spec, Acceptance Spec) — treat
-   this gate as a one-shot rewrite, not an iterative draft. The
-   Constraint ("Do not modify existing issues without explicit
-   permission") is honored — no `gh issue edit` call until the
-   operator confirms.
-
-   > **`--yes` (headless) auto-proceed.** This refinement-diff confirm is the
-   > clarity-gate face of `/plan`'s **gate #1** on the existing-Epic
-   > (`/plan <epicId>`) path — it is an operator *wait*, not a deterministic
-   > validator (the deterministic half is the section-presence *scoring* in
-   > step 1, which always runs). When `/plan` was invoked with `--yes`, this
-   > confirm does **not** STOP: the sharpened body is auto-**approved** and the
-   > run proceeds to step 6 (persist). The blast-radius note is still displayed
-   > for the record; only the operator wait is suppressed. This keeps
-   > `/plan <epicId> --yes` driveable headlessly even when the Epic body needs
-   > refinement (`gh issue edit` still runs only via the step 6 persist call,
-   > which the auto-approval authorizes). See
-   > [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
-
-6. **Persist**: On approval, run the persist mode:
+   The epic envelope additionally carries `clarity` (section-presence
+   rubric), `replan` (already-planned signals), and `planState`.
+2. **Re-plan detection** (`replan.alreadyPlanned === true`): the Epic body
+   already carries Tech Spec sections. Fold the decision into gate #1: a
+   confirmed re-plan runs step 3 with `--force` (managed sections are
+   overwritten in place; child Stories are closed and recreated); a decline
+   aborts gracefully.
+3. **Story-sized advisory**: only when the Epic is not already planned
+   **and** `replan.openStoryCount` is 0, run the shared scope-triage gate
+   over the Epic body ([`scope-triage-gate.md`](scope-triage-gate.md)). On a
+   `story` / `borderline` verdict the Recommended branch converts via
+   close-and-recreate: seed `temp/epic-[Epic_ID]/scope-triage-seed.md` from
+   the Epic body, hand off to `/plan --from-notes <path>` as a scope-triage
+   handoff, and — only after the replacement Story `#N` exists — close the
+   Epic with a cross-linking comment
+   (`gh issue close [Epic_ID] --comment "Closed in favor of #N — scope triaged as a standalone Story."`).
+   Both mutations happen only after the operator confirms at gate #1.
+4. **Clarity refinement** (`clarity.verdict === 'needs-refinement'`): the
+   deterministic scoring already ran inside the envelope build (a `clear`
+   verdict requires ≥ 4 of 5 canonical sections **and** Acceptance
+   Criteria). Interrogate the operator on the named gaps
+   (`clarity.missingOrPlaceholder`) — one question at a time — and draft the
+   refined body to `temp/epic-[Epic_ID]/clarity-update.md`. The refined-body
+   diff folds into gate #1; on approval persist it:
 
    ```bash
    node .agents/scripts/epic-plan-clarity.js --epic [Epic_ID] \
      --updated-body temp/epic-[Epic_ID]/clarity-update.md
    ```
 
-   The CLI persists the new body via `provider.updateTicket` and
-   posts a `clarity-gate-update` audit comment recording the change.
-   Idempotent: no-op when the file content matches the current body.
-
-7. **Re-verify**: Re-run the `--emit-context` step once to confirm
-   the verdict flipped to `clear`. If it still reads
-   `needs-refinement`, abort with a non-zero exit and surface a
-   remediation hint to the operator. Do not loop — one refinement
-   pass per invocation, matching the `--force` re-plan pattern.
-
-## Phase 7: Epic Planning (Tech Spec & Acceptance Spec)
-
-> **Phase-7 guards & managed-section rationale (reference).** This phase runs
-> behind an **Epic-lease preflight** (`--steal` transfers a confirmed-dead
-> claim; the lease releases after Phase 8), writes **idempotent managed
-> sections** (`--force` overwrites them in place), lands **one planning
-> document** (Tech Spec + Acceptance Table folded into the Epic body;
-> `acceptance::n-a` waives the table), and namespaces every temp file under
-> the durable **per-Epic tree** (`temp/epic-[Epic_ID]/…`). The full rationale
-> for each guard is in
-> [`plan-epic-reference.md` § Phase 7 — background rationale](plan-epic-reference.md#phase-7--background-rationale).
-
-1. **Gather Authoring Context**: Run the spec-phase CLI in context-emission
-   mode to fetch the Epic body, scraped project docs, and the recommended
-   system prompts.
-
-   ```bash
-   node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] --emit-context > temp/epic-[Epic_ID]/planner-context.json
-   ```
-
-2. **Activate the `epic-plan-spec-author` skill**: Read
-   [`<agentRoot>/skills/core/epic-plan-spec-author/SKILL.md`](../../skills/core/epic-plan-spec-author/SKILL.md)
-   via the `Read` tool (resolve `<agentRoot>` from
-   `project.paths.agentRoot` — default `.agents`) and execute its
-   procedure with `[Epic_ID]` as input. The skill reads
-   `temp/epic-[Epic_ID]/planner-context.json`, authors the Tech
-   Spec, **risk verdict**, and **Acceptance Spec** against the embedded
-   system prompts, and writes them to
-   `temp/epic-[Epic_ID]/techspec.md`,
-   `temp/epic-[Epic_ID]/risk-verdict.json`, and
-   `temp/epic-[Epic_ID]/acceptance-spec.md`. The skill is the
-   authoritative authoring step — do **not** inline the Tech
-   Spec / risk-verdict / Acceptance Spec drafting in the workflow
-   body. The skill front-matter declares
-   `allowed_tools: [Read, Write, Bash]`; it never calls GitHub.
-
-   The skill body carries the authoritative Tech Spec and
-   Acceptance Spec system prompts. The `systemPrompts` field on the
-   `--emit-context` envelope is a backstop for legacy callers; the
-   skill body wins when the two surfaces diverge.
-
-   > **One-pass refinement contract (amend, don't regenerate).** When step 3's
-   > persist call rejects the authored artifacts (missing `## Delivery
-   > Slicing`, a schema-invalid risk verdict), re-entering this step applies
-   > **targeted edits** to the existing `temp/epic-[Epic_ID]/{techspec.md,
-   > risk-verdict.json,acceptance-spec.md}` files — fix only what the
-   > rejection named — per the `epic-plan-spec-author` skill's re-emit rule.
-   > This refinement is bounded to **one pass**: fix the named gap and
-   > re-run step 3 once: do not loop wholesale re-authoring across multiple
-   > rejections. The same one-pass shape already governs the Phase 6 Epic
-   > Clarity Gate's refinement loop above ("Do not loop — one refinement
-   > pass per invocation").
-
-3. **Persist to GitHub**: Run the spec-phase CLI's persist half. It
-   schema-validates the planner-authored risk verdict (`--risk-verdict`,
-   required — a missing or malformed verdict fails closed before any
-   GitHub mutation), derives the `planningRisk` envelope from it
-   (`deriveRiskEnvelope`), records a `risk-verdict` structured comment
-   on the Epic, flips the Epic to `agent::review-spec`, and writes the
-   `epic-plan-state` checkpoint (including the `riskVerdict` field).
-   The `--acceptance-table` flag persists the AC-ID table as the Epic
-   body's `## Acceptance Table` managed section alongside the Tech Spec
-   sections; the persist half fails loudly if any file is missing or
-   empty. Omit `--acceptance-table` only when the Epic carries the
-   `acceptance::n-a` waiver label.
-
-   ```bash
-   # Normal planning (both managed sections)
-   node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] \
-     --tech-spec temp/epic-[Epic_ID]/techspec.md \
-     --risk-verdict temp/epic-[Epic_ID]/risk-verdict.json \
-     --acceptance-table temp/epic-[Epic_ID]/acceptance-spec.md
-
-   # Re-planning (--force overwrites the Epic body's managed sections
-   # IN PLACE — same Epic issue, refreshed section bodies, one
-   # regeneration audit comment on the Epic. Child Story tickets are
-   # still close-and-recreate at decomposition time.)
-   node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] \
-     --tech-spec temp/epic-[Epic_ID]/techspec.md \
-     --risk-verdict temp/epic-[Epic_ID]/risk-verdict.json \
-     --acceptance-table temp/epic-[Epic_ID]/acceptance-spec.md --force
-
-   # Waived (acceptance::n-a label on Epic — no acceptance table authored)
-   node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] \
-     --tech-spec temp/epic-[Epic_ID]/techspec.md \
-     --risk-verdict temp/epic-[Epic_ID]/risk-verdict.json
-   ```
-
-4. **Verification and review routing**:
-   - Verify that the Technical Specification sections and (when not
-     waived) the `## Acceptance Table` section have landed as managed
-     sections of the Epic body.
-   - Read `planningRisk` from the persist stdout JSON (or the
-     `epic-plan-state` checkpoint). Branch on
-     `planningRisk.requiresReview` unless the operator passed
-     `--force-review`:
-     - **High risk** (`requiresReview === true`) or **operator override**
-       (`--force-review`) — **gate #2**: **STOP**. Ask the USER to review the
-       updated Epic body (its Tech Spec sections and `## Acceptance
-       Table`) on GitHub. Approval is the user's verbal OK in this
-       session — the sections live on the Epic itself, so there is
-       nothing to close at delivery time. Do NOT proceed
-       to decomposition until the user confirms the plan is accurate.
-
-       > **`--yes` (headless) auto-proceed.** When `/plan` was invoked with
-       > `--yes`, this review gate does **not** STOP, even when
-       > `requiresReview === true` or `--force-review` was also passed: the
-       > review resolves as **approved** and the run **continues directly to
-       > Phase 8**, exactly as the low-risk auto-proceed branch below; only
-       > the operator *wait* is suppressed. This is `/plan`'s **gate #2** —
-       > the second and last HITL STOP `--yes` suppresses. `--yes` does
-       > **not** alter risk routing or the review criteria themselves; it
-       > only forces a proceed where this gate would otherwise STOP. See
-       > [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
-     - **Low risk** (`requiresReview === false` and no `--force-review`):
-       Emit the auto-proceed message from the persist stdout
-       (`reviewRouting.operatorMessage`) and **continue directly to Phase 8**
-       without an extra review stop. The Epic still carries
-       `agent::review-spec` until decomposition completes; the routing
-       decision is recorded in the `epic-plan-state` checkpoint. (`--yes` is
-       a no-op on this branch — there is no STOP to suppress.)
-
-5. **Tech Spec freshness check (advisory)**: After the Tech Spec sections
-   are persisted, `epic-plan-spec.js` runs
-   [`validateSpecFreshness`](../../scripts/lib/orchestration/spec-freshness.js)
-   against the authored Tech Spec body, probing every cited path-shape
-   reference (backticked paths, `// header` lines in code blocks, and
-   inline mentions of paths under `.agents/`, `src/`, `lib/`, `app/`,
-   `tests/`, `packages/`, `scripts/`, `docs/`) against the configured
-   `baseBranch`. Results land in three buckets:
-   - **fresh** — path exists at the base ref (no action).
-   - **ambiguous** — path is absent but surrounding prose carries a
-     net-new cue (`introduce`, `add`, `create`, `new file`, `to be
-     created`, etc.); surfaced for review without alarm.
-   - **stale** — path is absent and no net-new cue is nearby; likely a
-     reference the Architect inherited from drift-stale docs.
-
-   When ≥1 stale reference is detected, a `spec-freshness` structured
-   comment is upserted on the **Epic** listing each citation
-   with its line number. The full report is also written to
-   `<tempRoot>/epic-<id>-spec-freshness.json` for downstream tooling.
-   The check is **advisory and non-blocking** — Phase 7 completes even
-   when stale references are present, so the operator retains final
-   judgment on edge cases. If the run summary shows
-   `⚠️ Spec freshness: N stale / M ambiguous`, review the Epic's
-   `spec-freshness` comment and correct the cited spec sections
-   before approving the plan for Phase 8.
-
-6. **BDD scenario cross-reference (advisory)**: When the project has
-   adopted BDD, `epic-plan-spec.js` populates the planner-context
-   envelope with `bddScenarios` — the output of
-   [`scanBddScenarios`](../../scripts/lib/bdd-scenario-scanner.js) over
-   the canonical feature roots resolved by
-   [`resolveFeatureRoots`](../../scripts/lib/bdd-runner-detect.js)
-   (`tests/features`, `features`, `test/features`). The Acceptance
-   Engineer step in the [`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md)
-   skill scores each planned AC against the scenario index via
-   `findBestScenarioMatch`; when an existing scenario covers an AC's
-   outcome, the AC's `Scenario` column is annotated with `<file>:L<line>`
-   and the `Disposition` becomes `unchanged` / `refined` instead of
-   `new`. When `bddScenarios` is empty (no `.feature` files), the skill
-   degrades silently and the spec is authored exactly as before. The
-   matcher is keyword-based and deterministic so re-runs produce stable
-   dispositions.
-
-7. **Cleanup**: The wrapper script (`epic-plan-spec.js`) deletes the Phase 7
-   temp files automatically on success — no operator action required. The
-   cleanup contract lives in
-   [`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js).
-
-> **Tech Spec section gate (folded into Step 3 persist).** The persist call
-> in Step 3 above validates the authored Tech Spec for the required
-> `## Delivery Slicing` heading (case-insensitive; also accepts the variant
-> `## Delivery slicing` and the shorthand `## Slicing`) via
-> [`lib/orchestration/spec-section-validator.js`](../../scripts/lib/orchestration/spec-section-validator.js#validateSpecSections)
-> **before** acquiring the Epic-lease or making any GitHub mutation — a
-> Tech Spec missing the section fails the persist call closed with a message
-> naming the gap and the two recovery paths (re-author, or add the section by
-> hand). This used to run as a separate, standalone
-> `epic-plan-spec-validate.js` CLI invoked as its own Phase 7.5 workflow
-> step; that ordering ran the check *after* the persist had already written
-> to GitHub and *after* `cleanupPhaseTempFiles` had deleted the temp spec
-> file the check read, so the "blocking gate" could never actually block.
-> Folding the check into the persist path's input validation makes it a
-> real hard gate. **Why this gate exists**: Phase 8.3 (Holistic
-> Consolidation) reconciles the draft ticket array against the Tech Spec's
-> `## Delivery Slicing` section, which the
-> [`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
-> skill uses as the capability-boundary anchor (see Phase 8 step 2 below).
-> Without it, the consolidation pass runs against a void and produces
-> groupings that reflect **technical shape** (e.g. cron jobs together)
-> rather than **capability boundaries** — reproduced on Epic #18 in
-> `dsj1984/athportal` (planned with v1.54.0), whose spec carried a detailed
-> `## Core Components` table but no `## Delivery Slicing` section. On a
-> persist failure, re-enter the Step 2 spec-author step and apply a
-> **targeted edit** adding the missing `## Delivery Slicing` section to the
-> existing `techspec.md` (amend, don't regenerate — the one-pass refinement
-> contract above) — or add the section by hand — then re-run Step 3 once.
-
-## Phase 8: Work Breakdown Decomposition
-
-> **Open-children guard (workflow guard).** Before persisting the breakdown,
-> `epic-plan-decompose.js` refuses to run when the Epic **already has open
-> Story children**, unless `--force` (close + recreate the tree) or
-> `--resume` (continue a partial persist) is set. This stops a re-run from
-> stacking a duplicate Story set on top of an existing one — the
-> phase exits non-zero and lists the open children. Once persist completes,
-> the Epic-lease acquired in Phase 7 is **released** (best-effort; a release
-> failure never fails decompose).
-
-<!-- separator: adjacent blockquotes -->
-
-> **Hierarchy.** The decomposer emits a flat Story backlog under the Epic.
-> Acceptance criteria and verification steps are inlined on each Story
-> body (`acceptance[]` / `verify[]` fields) and resolved against the
-> Epic body's `## Acceptance Table` section at close time. See
-> [`.agents/instructions.md` § 5.D](../../instructions.md) for the full
-> contract.
-
-1. **Gather Decomposition Context**:
-
-   ```bash
-   node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] --emit-context > temp/epic-[Epic_ID]/decomposer-context.json
-   ```
-
-2. **Activate the `epic-plan-decompose-author` skill**: Read
-   [`<agentRoot>/skills/core/epic-plan-decompose-author/SKILL.md`](../../skills/core/epic-plan-decompose-author/SKILL.md)
-   via the `Read` tool (resolve `<agentRoot>` from
-   `project.paths.agentRoot` — default `.agents`) and execute its
-   procedure with `[Epic_ID]` as input. The skill reads
-   `temp/epic-[Epic_ID]/decomposer-context.json` (`epicBody` — carrying
-   the folded Tech Spec sections and Acceptance Table — risk
-   heuristics, `maxTickets` cap, `contextMode`), applies its
-   embedded decomposer system prompt + ticket schema, and writes the
-   ticket array to `temp/epic-[Epic_ID]/tickets.json`. Do **not** inline
-   the JSON authoring in the workflow body.
-
-   The `maxTickets` cap is a **framework constant**
-   (`LIMITS_DEFAULTS.maxTickets` in
-   `.agents/scripts/lib/config/limits.js`; not operator-configurable) and
-   a **reviewability budget**, not a hard authoring ceiling: a draft over
-   budget warns at authoring time and is rejected at persist unless rerun
-   with `--allow-over-budget` (after confirming the over-budget rationale
-   on the Epic). The `epic-plan-decompose.js` script also logs the
-   resolved budget to stderr. The decomposer system prompt is
-   single-sourced in
-   `.agents/scripts/lib/templates/decomposer-prompts.js`
-   (`renderDecomposerSystemPrompt`); the `epic-plan-decompose-author`
-   skill references that rendered `systemPrompt` rather than carrying
-   its own copy of the prompt body.
-
-   When the Tech Spec carries a `## Delivery Slicing` section (authored by
-   `epic-plan-spec-author` in Phase 7), the decompose-author skill authors
-   toward the Architect's proposed shippable-Story clusters; it degrades
-   gracefully when the section is absent.
-
-   > **One-pass refinement contract (amend, don't regenerate).** When the
-   > deterministic validator (`validateAndNormalizeTickets`) rejects the
-   > draft, or the 8.3 / 8.4 / 8.5 critics below flag specific Stories,
-   > re-entering this step applies
-   > **targeted edits** to the existing `temp/epic-[Epic_ID]/tickets.json` —
-   > fix only the rejected or flagged Stories — per the
-   > `epic-plan-decompose-author` skill's re-emit rule, rather than
-   > re-authoring the whole array from scratch. Each critic's feedback gets
-   > **one refinement pass**: apply the targeted edit and re-run the
-   > relevant downstream step (validator or persist) once, matching the
-   > Phase 7 spec-author contract above; do not loop wholesale re-authoring
-   > across repeated rejections.
-
-3. **Phase 8.3 — Holistic Consolidation (HITL diff gate, precondition-gated
-   dispatch)**: After the draft `temp/epic-[Epic_ID]/tickets.json` exists and
-   **before** the persist call below, first consult the deterministic
-   dispatch precondition — [`evaluateConsolidationPrecondition`](../../scripts/lib/orchestration/consolidation-precondition.js),
-   called with the draft Story array and the Epic body (which carries the
-   folded Tech Spec `## Delivery Slicing` section). The precondition compares
-   the draft against the Delivery Slicing table **1:1** — same shippable-Story
-   count (excluding the wave-0 `bdd-scaffold` Story) and a `depends_on` shape
-   that agrees with each slice's `Independent?` answer — and returns
-   `{ dispatch, reasons }`. It **fails open** (`dispatch: true`) on every
-   ambiguous input: a missing or unparseable Delivery Slicing section, or an
-   unparseable `Independent?` cell.
-
-   - **`dispatch: false`** — the draft already matches the Delivery Slicing
-     target, so the consolidation critic has nothing to reconcile. **Skip the
-     sub-agent dispatch** and surface the skip as a **one-line progress
-     note** naming the precondition's `reasons` — quoting verbatim the
-     string `evaluateConsolidationPrecondition` actually emits: "Draft
-     matches Delivery Slicing 1:1 in count and dependency shape (N
-     slice(s)) — skipping the 8.3 consolidation dispatch." (`N` is the
-     interpolated `slicing.length`). Proceed straight to Phase 8.4 with the
-     draft `tickets.json` unchanged (no `consolidation-report.md` is
-     produced when the dispatch is skipped).
-   - **`dispatch: true`** — **dispatch a genuine fresh-context sub-agent**
-     (`Agent` tool, `subagent_type: general-purpose`) whose task is to read
-     the
-     [`epic-plan-consolidate`](../../skills/core/epic-plan-consolidate/SKILL.md)
-     skill and execute its procedure with `[Epic_ID]` as input, including the
-     precondition's `reasons` in the HITL diff context so the operator sees
-     *why* the critic ran. Dispatching the critic as a sub-agent — **not**
-     activating the skill inline in your authoring turn — is what makes it a
-     **separate critic pass with fresh context**: the sub-agent does not
-     inherit the conversation that authored the draft, so it cannot grade its
-     own homework (the same nested-dispatch mechanic the acceptance self-eval
-     loop uses, now that the sub-agent depth limit is lifted — see
-     [`.agents/instructions.md` § 4](../../instructions.md)). The sub-agent
-     reads the draft array plus the Epic body (which carries the Tech Spec
-     sections), reconciles the draft against the Tech Spec `## Delivery
-     Slicing` target, and emits a **consolidated** `tickets.json` plus a
-     human-readable `temp/epic-[Epic_ID]/consolidation-report.md`. Its operations are scope-preserving only — **merge sibling Stories and
-     rewire `depends_on`** — and it MUST NOT add scope or invent tickets; it
-     consolidates fragmented slices by merging them into a cohesive Story,
-     never by splitting one. The sub-agent **never writes to GitHub**: it
-     emits only the two temp artifacts and returns control to this operator
-     session. It runs **before** the deterministic validator
-     (`validateAndNormalizeTickets`), so the validator re-checks its output
-     and the critic cannot emit an invalid plan. **Show the operator the
-     consolidation report (the before/after
-     diff + rationale) before persisting.** The HITL diff-confirm and the
-     persist call both run here in the **operator session**, never inside
-     the sub-agent — consolidation is never auto-applied without review: on
-     operator approval, persist the consolidated `tickets.json`; on
-     rejection, persist the draft instead.
-
-   Phase 8.4 (Reachability Completeness Critic), Phase 8.5 (Planning
-   Pre-Mortem Critic), and the deterministic ticket validator
-   (`validateAndNormalizeTickets`) are
-   **unconditional** — the precondition governs only the 8.3 sub-agent
-   dispatch, never any other Phase 8 gate. This is a sub-step of Phase 8 — it
-   does **not** renumber the top-level lifecycle phases (9–12).
-
-4. **Phase 8.4 — Reachability Completeness Critic (HITL diff gate, F6)**:
-   After consolidation (8.3) and **before** the persist call below, run the
-   completeness critic. This is a **distinct pass** from
-   [`epic-plan-consolidate`](../../skills/core/epic-plan-consolidate/SKILL.md)
-   and **must NOT relax** that skill's scope-preserving conservation invariant:
-   the consolidate critic is merge-and-rewire-only (it MUST NOT add scope or
-   invent tickets), whereas this critic is permitted exactly one **additive**
-   operation — appending a **single reachability Story** when, and only when, an
-   Epic introduces a user-facing surface (a new route/page) that **no Story
-   gives a navigation owner** (no nav-registry entry, no menu/link door from an
-   authenticated home). The two passes are deliberately separate so the
-   conservation invariant stays intact: consolidation never adds, and this
-   critic's only addition is the reachability Story.
-
-   - **Detection.** Scan the consolidated `tickets.json` for Stories that add a
-     route-shaped surface (paths under the consumer-configured
-     `planning.navigation.routeGlobs`, mirroring the
-     `epic-plan-healthcheck.js --paranoid` reachability check, F7). For each
-     such surface, confirm some Story's `acceptance[]` / `changes[]` references
-     the consumer's nav-registry SSOT (`planning.navigation.navRegistry`). A
-     surface with **no** nav owner is an orphan.
-   - **Action.** When at least one orphan surface exists, append **one**
-     reachability Story whose `acceptance[]` requires the orphaned surface to be
-     reachable by navigation from the relevant persona's authenticated home
-     (never by deep-link), and wire its `depends_on` to the surface-adding
-     Story. Append **at most one** reachability Story per decompose run — batch
-     every orphan under it — so the critic never fans out a parallel backlog.
-   - **No-op when unconfigured.** With no `planning.navigation` config present,
-     the critic degrades to a silent no-op (it cannot identify route-shaped
-     surfaces or a nav registry), exactly like the F7 healthcheck flag.
-   - **HITL.** The added Story is surfaced in the **same Phase 8 HITL diff** as
-     consolidation, **before** any GitHub write — never auto-persisted. On
-     operator rejection, drop the added Story and persist without it. The
-     deterministic validator (`validateAndNormalizeTickets`) re-checks the
-     critic's output, so an invalid addition cannot reach GitHub.
-
-5. **Phase 8.5 — Planning Pre-Mortem Critic (code-reading, F9)**: After the
-   reachability critic (8.4) and **before** the persist call below, **dispatch a
-   genuine fresh-context sub-agent** (`Agent` tool,
-   `subagent_type: general-purpose`) whose task is to read the
-   [`epic-plan-premortem`](../../skills/core/epic-plan-premortem/SKILL.md)
-   skill and execute its procedure with `[Epic_ID]` as input. Like the 8.3
-   consolidate pass, dispatching the critic as a sub-agent — **not** activating
-   the skill inline in your authoring turn — is what makes it a genuine
-   **fresh-context critic** sibling to `epic-plan-consolidate`: the sub-agent
-   does not inherit the authoring conversation, so its code-reading review is
-   independent of the draft it grades. It reads the drafted `tickets.json`, the
-   Epic body (with its folded Tech Spec sections), **and the actual cited code
-   surfaces** (the files each Story's
-   `changes[]` / `references[]` name), then emits predicted-rework findings —
-   unverifiable acceptance criteria, over- or under-specified Stories, and
-   semantically-wrong assumptions the structural file-assumption gate (step 7)
-   cannot catch — to `temp/epic-[Epic_ID]/premortem-report.md`.
-
-   Unlike the consolidate critic it is **not** scope-preserving-only: it may
-   recommend splitting an under-specified Story or tightening an AC. But it
-   **never writes to GitHub** and never persists `tickets.json` — it only emits
-   the report and returns control to this operator session. Its findings are
-   shown in the **same Phase 8 HITL diff** (which stays in the operator
-   session), and on
-   operator approval the author re-runs (Step 2) on the findings **before** the
-   persist call — applying **targeted edits** to the flagged Stories in the
-   existing `tickets.json` (amend, don't regenerate; **one refinement pass**
-   per the contract above), not a wholesale re-author. The critic runs
-   **before** the deterministic validator (`validateAndNormalizeTickets`),
-   so the persist below is the single GitHub write for the whole phase.
-
-6. **Persist to GitHub**: Run the decompose CLI's persist half. It
-   validates the ticket array (`validateAndNormalizeTickets`), creates
-   the Story issues, flips the Epic to `agent::ready`, and
-   writes the `epic-plan-state` checkpoint.
-
-   ```bash
-   # Normal decomposition
-   node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
-     --tickets temp/epic-[Epic_ID]/tickets.json
-
-   # Re-planning (close old tickets first)
-   node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
-     --tickets temp/epic-[Epic_ID]/tickets.json --force
-   ```
-
-   > On a large Epic (~60+ tickets) the persist can trip GitHub's secondary
-   > rate limit mid-run. Resume from the partial backlog with `--resume` — the
-   > full recovery contract is in
-   > [`plan-epic-reference.md` § Phase 8 — `--resume` recovery (secondary rate limit)](plan-epic-reference.md#phase-8----resume-recovery-secondary-rate-limit).
-
-7. **Cross-Validation**:
-   - Hierarchy completeness, dependency-DAG acyclicity, and `risk::high`
-     labelling are deterministic invariants enforced by
-     `validateAndNormalizeTickets` in
-     [`lib/orchestration/ticket-validator.js`](../../scripts/lib/orchestration/ticket-validator.js);
-     its output during decomposition is the canonical proof — no manual
-     re-check needed.
-   - **File-assumption gate (Story #2636)**: Each Story's `body.changes`
-     and `body.references` entries declare an explicit `assumption` ∈
-     `creates | refactors-existing | exists | deletes`. The validator
-     probes the base branch for every declared path and rejects the
-     decompose when the declaration contradicts reality:
-     - `creates` + path **exists** at base → error.
-     - `refactors-existing` / `exists` / `deletes` + path **absent** at
-       base → error.
-     Errors are batched per-Story into the validator's `errors` envelope
-     so the decompose loop surfaces every mismatch in a single re-prompt
-     rather than one at a time.
-   - **Scope-overlap check (docs/runbook downstream of config work)**:
-     Scan for Stories whose scope is "docs update", "runbook", or
-     "README" that land downstream of an earlier "config + runbook"
-     Story in the same Epic. If the earlier Story's AC already covers
-     the same document, the downstream Story's deliverable is likely
-     absorbed. Append a "Scope verification note" to the downstream
-     Story body pointing the executor to `git diff main -- <path>`
-     against the upstream Story branch so they can confirm whether a
-     substantive edit is still required (or only a cross-reference
-     remains). The decomposer system prompt emits this flag
-     automatically where it can detect the pattern — this checklist
-     item is the human/host-LLM backstop.
-   - **Action**: Fix any scope-overlap exceptions or validator failures by
-     re-running the scripted force path so the change is recorded in tooling
-     rather than hand-applied:
-
-     ```bash
-     node .agents/scripts/epic-plan-decompose.js \
-       --epic [Epic_ID] \
-       --tickets temp/epic-[Epic_ID]/tickets.json \
-       --force
-     ```
-
-8. **Audit**:
-   - Check the Epic's comment thread to ensure the backlog summary was posted.
-   - Verify that at least one `type::story` issue was created.
-
-9. **Cleanup**: The wrapper script (`epic-plan-decompose.js`) deletes the
-   Phase 8 temp files automatically on success — no operator action required.
-   The cleanup contract lives in
-   [`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js).
-
-## Phase 9: Execution Roadmap (Story Dispatch)
-
-1. **Generate Roadmap**: Automatically invoke the dispatcher in dry-run mode to
-   calculate execution waves and model recommendations:
-
-   ```bash
-   node .agents/scripts/dispatcher.js [Epic_ID] --dry-run
-   ```
-
-2. **Verify Output**:
-   - Confirm the **Story Dispatch Table** is printed.
-   - Check for any stories in **Wave 0** — these are ready for immediate
-     execution.
-
-   > **Manifest persistence (v5.9.0):** the dispatcher also posts the manifest
-   > as a `dispatch-manifest` structured comment on the Epic (idempotent —
-   > re-runs replace the prior comment). That comment is the source of truth for
-   > the Wave Completeness Gate in `/deliver` Step 0.5 and for any external
-   > wave-tracking tooling.
-
-3. **Handoff**: Provide the user with the recommended next step:
-
-   > "Planning is complete. Run `/deliver #[Epic ID]` to start the wave
-   > loop, or pick a single Story from Wave 0 and run `/deliver #[Story
-   > ID]` to drive it directly."
-
-## Phase 10: Readiness Health Check
-
-Run the post-plan health check to validate the backlog before handing off to
-`/deliver`. The default mode runs only the cheap checks
-(config + git remote) and targets sub-2-second turnaround. The script itself
-always exits 0; the structured JSON on stdout reports findings.
+   One refinement pass per invocation — do not loop.
+
+### Gate #1 — exit of interrogate (HITL STOP)
+
+One operator confirmation folds every interrogate outcome: the one-pager (or
+the refined-body diff), the scope-triage verdict, the duplicate candidates,
+and the re-plan decision. Display them together and **STOP**. Do not enter
+step 2 until the operator explicitly confirms.
+
+> **`--yes` (headless) auto-proceed.** Under `--yes` this gate does **not**
+> STOP: the confirm resolves as **approved**, and a `story` / `borderline`
+> triage verdict resolves to its **Recommended** branch. The interrogation
+> itself runs exactly **one bounded pass** — no operator questions are asked;
+> facts come from the codebase and every unresolved unknown lands in the
+> one-pager's **Key Assumptions** section instead of a question, so a
+> headless driver can never hang. See
+> [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
+
+## Step 2 — Author
+
+Read the envelope with the `Read` tool and write the planning artifacts to
+`temp/epic-[Epic_ID]/` (ideation: the `temp/plan-ideation/<slug>/` tree).
+The single `plan-context.json` envelope supersedes the per-phase
+`planner-context.json` / `decomposer-context.json` files the authoring
+skills name — read the envelope wherever a skill asks for either.
+
+1. **`techspec.md`** — activate the
+   [`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md)
+   skill. The Tech Spec opens with `## Delivery Slicing` and never restates
+   the Epic's Context/Goal/Scope.
+2. **`risk-verdict.json`** — same skill; the schema-conformant verdict
+   **plus `deliveryShape: "fan-out"|"single"`** and a one-line rationale.
+   Seed the shape from the envelope's `deliveryShapeSignal` (advisory —
+   the operator vetoes it at gate #2). `"single"` means one-pass-sized or a
+   pure dependent chain: the plan ships as spec-only, with **no tickets**.
+3. **`acceptance-spec.md`** — same skill; omit only when the Epic carries
+   the `acceptance::n-a` waiver label.
+4. **`tickets.json`** — fan-out shape only: activate the
+   [`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
+   skill against the same envelope (its `systemPrompts.decompose`,
+   `ticketSchema`, and `maxTickets` fields). In single-delivery shape author
+   **no** tickets file — the Delivery Slicing table is the plan.
+
+> **One-pass refinement contract (amend, don't regenerate).** When a critic
+> flags Stories or the step 3 persist rejects an artifact, apply **targeted
+> edits** to the existing files — fix only what was named — and re-run the
+> rejected step **once**. Never loop wholesale re-authoring.
+
+### Conditional critics (between authoring and gate #2)
+
+Evaluate the dispatch conditions deterministically first — one git-local
+CLI call, zero GitHub reads:
 
 ```bash
-node .agents/scripts/epic-plan-healthcheck.js --epic [Epic_ID]
+node .agents/scripts/plan-critics.js --epic [Epic_ID]
 ```
 
-**The healthcheck is a blocking exit condition for `agent::ready`.**
-Story #2921 (Epic #2880 F7) wired the persist half of
-`epic-plan-decompose.js` to re-run the same default check before
-flipping the Epic to `agent::ready`.
-When the inline run reports `ok: false`, the persist phase **refuses the
-flip** and throws with the failing check's `reason`. The Epic stays on its
-prior label (`agent::review-spec` in the normal flow) until either the
-underlying check passes on a rerun, or the operator applies the
-`planning::healthcheck-waived` label to the Epic and reruns the persist
-phase. See `.agents/docs/SDLC.md` § "`agent::ready` exit conditions" for the
-full handoff contract and the waiver scope.
+(ideation: pass `--tech-spec`/`--risk-verdict`/`--tickets` explicitly). The
+verdict names each critic with `dispatch: true|false` and reasons. Dispatch
+a sub-agent ONLY for a critic with `dispatch: true`; surface each skip as a
+one-line note. Every skip decision is appended to the plan-metrics ledger
+(`kind: "critic-skip"`, with reasons) so under-firing is auditable — the
+persist validators remain unchanged hard gates either way.
+
+Both critics are **fresh-context sub-agents** (`Agent` tool,
+`subagent_type: general-purpose`) — never inline skill activations, so they
+cannot grade their own homework. Both are report-only: they never write to
+GitHub and never persist `tickets.json`; their findings fold into the gate #2
+view, and accepted findings get one targeted amend pass (above).
+
+- **Consolidation critic** (fan-out only): fires when the draft does NOT
+  already match the Tech Spec's Delivery Slicing table 1:1 in Story count
+  and dependency shape, AND the divergence is worth a dispatch — the draft
+  has more than 5 stories, or the mismatch is confirmed (a small draft
+  whose table is merely missing/unparseable skips: gate #2's single view
+  covers it). On dispatch the sub-agent reads the
+  [`epic-plan-consolidate`](../../skills/core/epic-plan-consolidate/SKILL.md)
+  skill and reconciles the draft against the slicing target. Its operations
+  are scope-preserving only — merge sibling Stories and rewire `depends_on`;
+  it MUST NOT add scope or invent tickets.
+- **Pre-mortem critic**: fires when the risk verdict's overall level is
+  high, OR the ticket count is at least half `maxTickets`, OR any
+  `planning.riskHeuristics` phrase matches the plan text. On dispatch the
+  sub-agent reads the
+  [`epic-plan-premortem`](../../skills/core/epic-plan-premortem/SKILL.md)
+  skill, reads the actual cited code surfaces, and emits predicted-rework
+  findings to `temp/epic-[Epic_ID]/premortem-report.md`.
+
+## Step 3 — Persist
+
+### Gate #2 — risk-routed review (HITL STOP, before any GitHub write)
+
+Present the whole plan in **one view**: the Tech Spec, the Acceptance Table,
+the tickets (or the Delivery Slicing table in single shape), the risk
+verdict, the `deliveryShape`, and any critic reports. This is the single
+seam where the operator vetoes single-vs-fan-out routing.
+
+- **High risk** (any risk axis high / `requiresReview`-shaped verdict) or
+  **operator override** (`--force-review`): **STOP** for explicit operator
+  approval before running the persist CLI.
+- **Low risk**: emit a one-line auto-proceed note and continue directly to
+  the persist call — no operator wait. (`--yes` is a no-op on this branch —
+  there is no STOP to suppress.)
+
+> **`--yes` (headless) auto-proceed.** Under `--yes` this review gate does
+> **not** STOP, even when the verdict is high-risk or `--force-review` was
+> passed: the review resolves as **approved** and the run continues to the
+> persist call. `--yes` does **not** alter risk routing or the review
+> criteria themselves — it only forces a proceed where this gate would
+> otherwise STOP. See
+> [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
+
+### Run the persist CLI
 
-The script emits a single line of JSON to stdout:
-
-```json
-{
-  "ok": true,
-  "degraded": false,
-  "reason": null,
-  "checks": [
-    { "name": "config",     "ok": true, "durationMs": 12,  "detail": "..." },
-    { "name": "git-remote", "ok": true, "durationMs": 234, "detail": "..." }
-  ]
-}
+```bash
+# Normal persist (artifact paths default to temp/epic-[Epic_ID]/)
+node .agents/scripts/plan-persist.js --epic [Epic_ID]
+
+# Re-plan (overwrite managed sections in place; close + recreate the tree)
+node .agents/scripts/plan-persist.js --epic [Epic_ID] --force
+
+# Ideation (opens the Epic itself; artifact paths must be explicit)
+node .agents/scripts/plan-persist.js \
+  --one-pager temp/plan-ideation/<slug>/one-pager.md \
+  --tech-spec temp/plan-ideation/<slug>/techspec.md \
+  --risk-verdict temp/plan-ideation/<slug>/risk-verdict.json \
+  --acceptance-table temp/plan-ideation/<slug>/acceptance-spec.md \
+  --tickets temp/plan-ideation/<slug>/tickets.json
+
+# Change-request delta (tickets carry op: add|modify|keep|close;
+# close ops additionally require --explicit-delete after the dry-run diff)
+node .agents/scripts/plan-persist.js --epic [Epic_ID] --amend
 ```
 
-Modes (additive — the fast checks always run):
-
-- **(default)** — config validation + git remote check only.
-- **`--paranoid`** — adds ticket-hierarchy revalidation. Requires `--epic`.
-  Use this when you want the full backlog audit before execution.
-- **`--prime-install`** — adds the pnpm content-addressable-store prime
-  (`pnpm install --frozen-lockfile`, up to 300s). Run only when
-  `nodeModulesStrategy: 'pnpm-store'` is configured and you want subsequent
-  worktree installs to be near-instant instead of fetching from scratch.
-
-If `ok` is `false`, review the entries in `checks[]`, resolve the failing
-check(s), and rerun the persist phase. Apply `planning::healthcheck-waived`
-to the Epic only when the failure is environmental and the operator has
-triaged it (e.g. a known `origin` outage during a maintenance window).
-
-## Phase 11: Plan Comprehension Gate
-
-An **opt-in, advisory** gate that offers the operator a guided walkthrough of
-the freshly planned backlog before they hand off to `/deliver`. The plan
-is the moment the operator authorizes an autonomous fan-out of subagents — this
-phase exists so they can *understand and endorse* the approach while it is
-still free to change, not after the code lands.
-
-> **Non-blocking by construction.** This phase runs **after** Phase 10 has
-> already flipped the Epic to `agent::ready`. It never gates that flip, never
-> blocks the handoff, and the operator can decline or stop it at any point.
-> `risk::high` remains planning metadata and `agent::blocked` remains the only
-> mandatory runtime pause — this gate adds neither.
-
-### 1. Decide whether to offer the walkthrough (LM judgment)
-
-There is **no `--flag`**. Evaluate the plan with judgment and **default to
-skipping silently**. Offer the walkthrough only when the plan is genuinely
-worth one. Signals that warrant offering:
-
-- The roadmap spans **multiple waves** or a **large Story count**.
-- Any Story or the Epic carries **`risk::high`**, or the plan matches the
-  `planning.riskHeuristics` in `.agentrc.json` (destructive/irreversible
-  changes, shared auth/security, CI/CD gate changes, monorepo-wide rewrites,
-  destructive migrations).
-- The Tech Spec introduces a **novel architectural decision** or a wide
-  **blast radius** across subsystems.
-
-A small, single-wave, low-risk plan proceeds straight to Phase 12 with no
-prompt. When in doubt on a borderline plan, make a one-line offer rather than
-forcing the walkthrough.
-
-### 2. Run the walkthrough (when offered and accepted)
-
-Activate the
-[`core/knowledge-transfer`](../../skills/core/knowledge-transfer/SKILL.md) skill
-with the **plan** as the subject — the Epic body (whose managed sections
-carry the Tech Spec), the decomposition (Stories with inline
-`acceptance[]` / `verify[]`), and the Phase 9 wave roadmap. The skill owns the
-method (restate-first, the why-ladder, mastery gates, depth levels, optional
-quizzing, the persistent `temp/comprehension-*.md` checklist).
-
-**Interruptible at every checkpoint.** Each step MUST offer an explicit
-"I'm good — proceed to `/deliver`" exit. The instant the operator takes
-it, stop the walkthrough and advance to Phase 12. Never trap the operator in
-the loop.
-
-### 3. Advance
-
-Whether the walkthrough was skipped, declined, completed, or stopped early,
-proceed to Phase 12. This gate produces no label transition and no blocking
-condition.
-
-## Phase 12: Notification & Handoff
-
-1. **Notify Operator (INFO)**:
-   - Post a summary comment on the Epic issue with work breakdown stats.
-   - @mention the operator (informational — no webhook for planning) by running
-     the notification script:
-
-   ```bash
-   node .agents/scripts/notify.js [Epic_ID] "Planning complete, review tickets. Backlog decomposition complete. Epic is ready for /deliver." --action
-   ```
+The CLI runs every deterministic step in one ordered, fail-closed pass:
+section gate (`## Delivery Slicing` required) → risk-verdict validation +
+mode-coherence hard error (`deliveryShape: "single"` with tickets, or
+fan-out without them, refuses) → `validateAndNormalizeTickets` +
+file-assumption gate + DAG + sizing/budget (fan-out and amend) → ideation
+Epic creation → Epic lease (`--steal` transfers a confirmed-dead claim) →
+managed sections + `risk-verdict` comment + spec-freshness advisory → story
+tree via the structural reconciler (single shape: the `delivery::single`
+routing marker and a zero-ticket checkpoint instead) → inline healthcheck
+(the **blocking** `agent::ready` exit condition; waive only via the
+`planning::healthcheck-waived` label) → one terminal `agent::ready` flip (no
+intermediate `agent::review-spec`) → checkpoint v2 + a single `plan-summary`
+comment carrying the dry-run wave table → temp cleanup **only at terminal
+success**, so a failed run leaves the artifacts in place for `--force` /
+`--resume` reuse.
+
+### Persist rejections and soft failures
+
+Each rejection names the artifact and the gap; apply the one-pass amend
+contract (step 2) and re-run the persist once:
+
+- **Section gate / validator / file-assumption / DAG errors** — targeted
+  edit to `techspec.md` or `tickets.json`.
+- **Reachability orphans** (deterministic route-glob vs `navRegistry` check;
+  a silent no-op when `planning.navigation` is unconfigured) — a named
+  **soft failure** (exit 3, before any GitHub write) listing the orphaned
+  surfaces: apply one targeted amend adding a navigation owner
+  (at most one reachability Story per plan), then re-persist.
+- **Over budget** (`maxTickets`) — re-scope, or re-run with
+  `--allow-over-budget` after confirming the rationale on the Epic.
+- **Rate-limit abort on a large Epic** — resume with `--resume`; see
+  [`plan-epic-reference.md` § `--resume` recovery](plan-epic-reference.md#persist----resume-recovery-secondary-rate-limit).
+
+### Handoff
+
+> "Planning is complete. Run `/deliver #[Epic_ID]` to start the wave loop,
+> or pick a single Story from Wave 0 (the `plan-summary` comment's wave
+> table) and run `/deliver #[Story_ID]` to drive it directly."
 
 ## Troubleshooting & recovery
 
-Troubleshooting symptoms (emit-context failures, tickets-file rejections, a
-decomposition that persisted but left the Epic off `agent::ready`) and the
-large-Epic **secondary-rate-limit `--resume`** recovery path live in the
-reference companion — they are consulted only when a run hits the edge:
+Edge-case procedures live in the reference companion:
 
 - [`plan-epic-reference.md` § Troubleshooting](plan-epic-reference.md#troubleshooting)
-- [`plan-epic-reference.md` § Phase 8 — `--resume` recovery (secondary rate limit)](plan-epic-reference.md#phase-8----resume-recovery-secondary-rate-limit)
+- [`plan-epic-reference.md` § Persist guards — background rationale](plan-epic-reference.md#persist-guards--background-rationale)
+- [`plan-epic-reference.md` § `--resume` recovery](plan-epic-reference.md#persist----resume-recovery-secondary-rate-limit)