mandrel 1.87.0 → 1.89.0

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

@@ -1,204 +1,22 @@
 ---
 description: >-
-  Phase 8 of sprint planning — decompose an Epic's sectioned body (which
-  carries the folded Tech Spec) into a
-  backlog of child Stories, persist the backlog, and flip the Epic to
-  `agent::ready`. Host-LLM authored; no external API calls.
+  Thin pointer — Phase 8 (decompose) of sprint planning now lives entirely in
+  `helpers/plan-epic.md`. This file is kept only so pre-existing links to
+  `helpers/epic-plan-decompose.md` still resolve.
 ---
 
-# Sprint Plan — Decompose Phase (helper)
-
-> **Helper module.** Not a slash command. Invoked by `/plan` (Phase 8).
-> To run the decompose phase interactively, use `/plan [Epic_ID]` — it
-> delegates here after the spec phase.
-
-## Role
-
-Director / Architect
-
-## Context
-
-This helper is the **decompose phase** of the split planning pipeline. It
-reads the Epic body — whose managed sections carry the Tech Spec previously
-produced by the spec phase
-helper ([`epic-plan-spec.md`](epic-plan-spec.md)) — generates the Epic's child
-Story tickets, persists them to GitHub, and flips the Epic to
-`agent::ready` (parking) so a human can run `/deliver` when
-execution should begin.
-
-The ticket array is authored **directly by you, the host LLM**.
-`epic-plan-decompose.js` is a deterministic wrapper that (a) emits the
-authoring context you need and (b) validates, persists, and transitions the
-Epic lifecycle state.
-
-The ticket array contains `type::story` tickets only — no Feature
-containers and no `type::task` children. Acceptance criteria and verification
-steps are inlined on each Story body via the `acceptance[]` and
-`verify[]` fields. The decomposer system prompt lives in the
-[`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
-skill.
-
-## Constraint
-
-- **Do not** run this skill until the spec phase is complete. The Epic body
-  must carry Tech Spec content (the managed section or a `## Delivery
-  Slicing` heading); the script will refuse to proceed otherwise.
-- **Do not** restructure the Story set after the decomposition
-  writes — the `epic-plan-state` checkpoint records the structure as
-  committed. Use `--force` to rebuild from scratch.
-- **Every** temp file must include the Epic ID in its name. Multiple Epics
-  may be decomposed concurrently; bare names will collide.
-- **Do not** flip the Epic past `agent::ready` from this helper. Execution
-  begins when an operator runs `/deliver [Epic_ID]`.
-
-## Prerequisites
-
-1. **Epic is on `agent::review-spec`** — i.e. the spec phase has already run
-   and the Epic body carries the Tech Spec sections.
-2. **API keys** — `GITHUB_TOKEN` set in `.env`.
-
-## Step 1 — Gather decomposition context
-
-```bash
-node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] --emit-context \
-  > temp/epic-[Epic_ID]/decomposer-context.json
-```
-
-The emitted JSON contains the Epic body (`epicBody` — the spec sections and
-acceptance table travel inside it), risk heuristics, the
-decomposer system prompt, and the `maxTickets` **reviewability budget**
-(Story #2798 — not a hard cap; over-budget plans require an explicit
-`--allow-over-budget` override at persist time).
-
-## Step 2 — Author the ticket array
-
-Read `temp/epic-[Epic_ID]/decomposer-context.json`. Produce a JSON array of
-Story objects that conforms to the schema in the system prompt
-and write it to `temp/epic-[Epic_ID]/tickets.json`.
-
-When the Tech Spec carries a `## Delivery Slicing` section, author toward the
-Architect's proposed shippable-Story clusters rather than mapping Epic
-capabilities 1:1; degrade gracefully (current behaviour) when it is absent.
-
-## Step 2.5 — Phase 8.3: Holistic Consolidation (HITL diff gate)
-
-The decompose phase runs in the sequence **emit-context → author →
-consolidate → validate+persist**. Step 2 is the *author* half; this step is
-the *consolidate* half, a separate critic pass run **before** the
-deterministic validator and **before** the GitHub write.
-
-Activate the
-[`epic-plan-consolidate`](../../skills/core/epic-plan-consolidate/SKILL.md)
-skill with `[Epic_ID]` as input. It reads the draft
-`temp/epic-[Epic_ID]/tickets.json` plus the Epic body (with its folded
-Tech Spec sections) from
-`decomposer-context.json`, reconciles the draft against the Tech Spec
-`## Delivery Slicing` target (degrading gracefully when absent), and emits:
-
-- a **consolidated** `temp/epic-[Epic_ID]/tickets.json` (overwriting the draft),
-- a human-readable `temp/epic-[Epic_ID]/consolidation-report.md` (rationale +
-  before/after diff).
-
-The pass is constrained to scope-preserving operations only — **merge sibling
-Stories and rewire `depends_on`**. It MUST NOT add scope or invent tickets.
-It consolidates fragmented slices by merging them into a cohesive Story,
-never by splitting one into two; the `assertAllTicketsAreStories` validator
-(in `lib/orchestration/ticket-validator.js`) stays as the post-consolidation
-backstop that rejects any non-Story ticket the pass might emit.
-
-> **HITL diff gate.** Show the operator
-> `temp/epic-[Epic_ID]/consolidation-report.md` (the before/after diff +
-> rationale) **before** running the persist call in Step 3. Consolidation is
-> never auto-applied without operator review — the operator approves the
-> consolidated plan (or rejects it and the draft is persisted instead). Only
-> after approval proceed to Step 3.
-
-This sub-step does **not** renumber the top-level lifecycle phases (9–12); it
-is a sub-step of Phase 8.
-
-## Step 3 — Persist and transition
-
-```bash
-# Normal decomposition
-node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
-  --tickets temp/epic-[Epic_ID]/tickets.json
-
-# Re-decompose (closes existing child Features/Stories first)
-node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
-  --tickets temp/epic-[Epic_ID]/tickets.json --force
-
-# Persist an over-budget plan (Story #2798 — only after the operator
-# has confirmed the over_budget_rationale on the Epic)
-node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
-  --tickets temp/epic-[Epic_ID]/tickets.json --allow-over-budget
-```
-
-On success the script:
-
-- Creates the Feature / Story hierarchy under the Epic.
-- Updates the `epic-plan-state` structured comment with the ticket count
-  and decompose timestamp.
-- Flips the Epic to `agent::ready`.
-
-## Step 4 — Cross-validation
-
-Delegate the structural invariants (hierarchy completeness, dependency DAG
-acyclicity, missing complexity labels) to `epic-plan-healthcheck.js`. It is
-the single source of truth for post-decompose validation — the Phase 10 run
-inside `/plan` calls the same script, so local and remote flows agree.
-
-```bash
-node .agents/scripts/epic-plan-healthcheck.js --epic [Epic_ID] --paranoid
-```
-
-`--paranoid` is the flag that runs the richer hierarchy and dependency
-checks; pair it with `--epic [Epic_ID]` so the script can fetch the
-ticket tree. `--dry-run` exists as well but only emits the planned
-checks without performing any I/O — it is not a substitute for
-`--paranoid` when you need the hierarchy invariants validated.
-
-The script exits 0 regardless of findings (non-blocking), but lists any
-`ERR`-level findings that must be addressed before execution:
-
-- Missing `type::story` tickets.
-- Stories without `complexity::` labels.
-- Dependency cycles across Stories.
-
-For the semantic checks the healthcheck cannot automate, do these by eye:
-
-- **Scope-overlap check**: Stories whose scope is "docs / runbook / README"
-  downstream of a "config + runbook" Story in the same Epic should carry a
-  scope-verification note pointing at
-  `git diff main -- <path>` against the upstream Story branch.
-- **Risk flagging**: Confirm `risk::high` Stories match the heuristics in
-  the decomposer context.
-
-Fix any gaps by creating additional issues or updating existing ones.
-
-## Step 5 — Cleanup
-
-The wrapper script deletes the phase-scoped temp files automatically when
-Step 3 succeeds — no operator action required. The cleanup contract lives in
-[`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js), which
-is the single source of truth for which temp paths this phase owns.
-
-## Handoff
-
-- Surface the backlog summary and the Wave 0 candidates to the operator:
-
-  > "Decomposition complete. Epic #[ID] is on `agent::ready` with NN ticket(s)
-  > across MM Stories. Run `/deliver [Epic_ID]` to begin execution."
-
-## Troubleshooting
-
-- "Epic #N body carries no Tech Spec sections (no ## Delivery Slicing)" —
-  run `/plan [Epic_ID]`
-  first (it will run the spec phase if the Tech Spec sections are missing).
-- Validator rejects the tickets file — the most common causes are a
-  Story whose `parent_slug` does not point at a Feature, a missing
-  `acceptance[]` / `verify[]` array on a Story body, or a Story
-  `depends_on` slug that does not resolve to another Story in the same
-  Epic.
-- If `--force` is required but the script refuses, confirm the Epic has the
-  linked artifacts first — `--force` only re-decomposes; it does not bypass
-  the spec-phase prerequisite.
+# Sprint Plan — Decompose Phase (thin pointer)
+
+> **Superseded.** This file used to carry its own Phase 8 step-by-step
+> procedure — a drifted duplicate of the authoritative one, and a pre-skill
+> pattern. Story #4403 collapsed it: the full, current Phase 8 procedure
+> (context gathering, the
+> [`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
+> skill activation, the Phase 8.3 consolidation / Phase 8.4 reachability /
+> Phase 8.5 pre-mortem critic passes, the persist call, cross-validation, and
+> cleanup) lives in
+> [`helpers/plan-epic.md` § Phase 8](plan-epic.md#phase-8-work-breakdown-decomposition).
+> Read that section — do not resurrect an inline copy here.
+
+The complementary Phase 7 pointer is
+[`helpers/epic-plan-spec.md`](epic-plan-spec.md).

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

@@ -1,184 +1,22 @@
 ---
 description: >-
-  Phase 7 of sprint planning — generate the Tech Spec and Acceptance Table for
-  an Epic, persist them as managed sections of the Epic body, and flip the
-  Epic to `agent::review-spec`. Host-LLM authored; no external API calls.
+  Thin pointer — Phase 7 (spec) of sprint planning now lives entirely in
+  `helpers/plan-epic.md`. This file is kept only so pre-existing links to
+  `helpers/epic-plan-spec.md` still resolve.
 ---
 
-# Sprint Plan — Spec Phase (helper)
-
-> **Helper module.** Not a slash command. Invoked by `/plan` (Phase 7).
-> To run the spec phase interactively, use `/plan [Epic_ID]` — it
-> delegates here.
-
-## Role
-
-Director / Architect
-
-## Context
-
-This helper is the **spec phase** of the split planning pipeline. It produces
-two planning artifacts for an Epic — a Technical Specification and an
-Acceptance Table — persists them as **marker-delimited managed sections of
-the Epic body** (`<!-- mandrel:tech-spec:start/end -->` and
-`<!-- mandrel:acceptance-table:start/end -->`), and flips the Epic to
-`agent::review-spec` (parking) so a human reviewer can read the updated Epic
-body on GitHub before decomposition. A `/plan` Epic run creates exactly
-**one** issue — the Epic. The PRD artifact class was retired (Story #4314);
-its one novel section, **User Stories**, lives inline in the Epic body.
-Story #4324 retired the `context::tech-spec` / `context::acceptance-spec`
-ticket classes the same way — the content semantics are unchanged, only
-where the output lives moved.
-
-> **Single prose home.** The canonical, full-detail spec-phase contract
-> (idempotent managed sections, the fold rationale, the
-> `acceptance::n-a` waiver, the Epic-lease preflight) lives in
-> [`epic-plan.md` § Phase 7](plan-epic.md). This helper carries only the
-> operational step list; when the two disagree, `epic-plan.md` wins.
-
-The Tech Spec and Acceptance Table are authored **directly by you, the host
-LLM**. `epic-plan-spec.js` is a deterministic wrapper that (a) emits the
-authoring context you need and (b) persists the sections and transitions the
-Epic lifecycle state.
-
-The complementary Phase 8 helper is
-[`epic-plan-decompose.md`](epic-plan-decompose.md). The `/plan`
-wrapper chains both helpers with a confirmation gate in between.
-
-## Constraint
-
-- **Do not** create any tickets from this phase — the only GitHub write is
-  the section-scoped Epic body update (plus structured comments);
-  decomposition belongs to
-  [`epic-plan-decompose.md`](epic-plan-decompose.md).
-- **Do not** flip the Epic to `agent::ready` from this skill. The terminal
-  label for the spec phase is `agent::review-spec`.
-- **Every** temp file must include the Epic ID in its name. Multiple Epics may
-  be planned concurrently; bare names like `temp/techspec.md` will collide.
-- **Stop and hand back to the operator** after Step 4 when
-  `planningRisk.requiresReview` is true or the operator passed
-  `--force-review` — do not chain into decomposition. Low-risk Epics
-  auto-proceed to Phase 8 after the persist stdout confirms
-  `reviewRouting.decision === 'auto-proceed'`.
-
-## Prerequisites
-
-1. **GitHub Epic** — an open issue with the `type::epic` label. The Epic's
-   body should contain enough narrative context (including its `## User
-   Stories` section) to seed the Tech Spec.
-2. **API keys** — `GITHUB_TOKEN` set in `.env`.
-
-## Step 1 — Gather authoring context
-
-Run the spec-phase CLI in context-emission mode to collect the Epic body, the
-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
-```
-
-## Step 2 — Author the Tech Spec
-
-Read `temp/epic-[Epic_ID]/planner-context.json`. Using
-`systemPrompts.techSpec`, the Epic body (its Context / Goal / Scope / User
-Stories sections), and `docsContext`, write the Tech Spec to
-`temp/epic-[Epic_ID]/techspec.md`. Open the document with the
-`## Delivery Slicing` section (no `<h1>`); do not restate the Epic's
-Context / Goal / Scope — the output lands as sections of the same Epic body.
-
-## Step 2.5 — Author the risk verdict
-
-Judge the change described by the Epic body and Tech Spec you just wrote and
-write `temp/epic-[Epic_ID]/risk-verdict.json` conforming to
-[`risk-verdict.schema.json`](../../schemas/risk-verdict.schema.json):
-`{ axes: [{ axis, level, rationale }], summary }`. The authoritative
-authoring rules (axis vocabulary, judgment-not-keywords, derivation
-preview) live in the
-[`epic-plan-spec-author` Skill, Step 4](../../skills/core/epic-plan-spec-author/SKILL.md).
-
-## Step 2.6 — Author the Acceptance Table
-
-Using `systemPrompts.acceptanceSpec`, the Epic body, and the Tech Spec, write
-the Acceptance Spec to `temp/epic-[Epic_ID]/acceptance-spec.md`. It opens
-with `## Acceptance Table` and captures the stable-ID acceptance criteria
-table (`| AC ID | Outcome | Feature File | Scenario | Disposition |`) that
-drives close-time reconciliation in `/deliver` Phase 6.
-
-**Skip this step only** when the Epic carries the `acceptance::n-a` waiver
-label (refactor-only or docs-only Epics); in that case omit
-`--acceptance-table` from Step 3.
-
-## Step 3 — Persist and transition
-
-```bash
-# Normal flow (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-plan (--force overwrites the managed sections in place)
-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
-```
-
-On success the script:
-
-- Validates the risk verdict against `risk-verdict.schema.json` (a
-  malformed verdict fails closed before any GitHub mutation) and derives
-  the `planningRisk` envelope from it.
-- Upserts the Tech Spec content and (unless waived) the `## Acceptance
-  Table` as managed sections of the Epic body, stripping any legacy
-  `## Planning Artifacts` section. The Acceptance Table is skipped when
-  `--acceptance-table` is omitted under the `acceptance::n-a` waiver.
-- Upserts the `risk-verdict` structured comment recording the verdict and
-  the derived envelope.
-- Upserts the `epic-plan-state` structured comment with the current phase,
-  the persisted-section flags (`techSpecPersisted`, `acceptanceTable`),
-  the `riskVerdict` field, and timestamps.
-- Flips the Epic to `agent::review-spec`.
-
-## Step 4 — Cleanup
-
-The wrapper script deletes the phase-scoped temp files automatically when
-Step 3 succeeds — no operator action required. The cleanup contract lives in
-[`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js), which
-is the single source of truth for which temp paths this phase owns. If you
-need to inspect the temp artefacts after the fact, re-run
-`epic-plan-spec.js --emit-context` to regenerate the planner context.
-
-## Handoff
-
-Branch on the shared planning risk decision surfaced in the persist stdout
-JSON (`planningRisk`, `reviewRouting`):
-
-- **High risk or `--force-review` — STOP.** Surface the Epic URL to the
-  operator:
-
-  > "Spec phase complete for Epic #[ID]. Review the updated Epic body
-  > (Tech Spec sections + `## Acceptance Table`) on GitHub. When you're
-  > ready, re-run `/plan [Epic_ID]` — the wrapper will pick up where it
-  > left off and run the decompose phase."
-
-- **Low risk — auto-proceed.** Relay `reviewRouting.operatorMessage` and
-  continue directly to Phase 8 decomposition without waiting for verbal
-  approval in this session.
-
-## Troubleshooting
-
-- If `--emit-context` fails with "Epic not found", confirm the ID matches the
-  GitHub issue number and the token has `issues:read`.
-- If the persist call fails after writing the Tech Spec section but before
-  the Acceptance Table, re-run with `--force` (the section upsert is
-  idempotent — it replaces the managed regions in place).
-- If the Epic does not flip to `agent::review-spec` after the script claims
-  success, the label write likely races with a concurrent mutation — re-run the
-  persist step; it's idempotent against the already-persisted sections.
+# Sprint Plan — Spec Phase (thin pointer)
+
+> **Superseded.** This file used to carry its own Phase 7 step-by-step
+> procedure — a drifted duplicate of the authoritative one, and a pre-skill
+> pattern that instructed inline authoring from the envelope's
+> (now-retired) `systemPrompts` field. Story #4403 collapsed it: the full,
+> current Phase 7 procedure (context gathering, the
+> [`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md)
+> skill activation, the persist call and its folded Tech Spec section gate,
+> review routing, freshness/BDD advisories, and cleanup) lives in
+> [`helpers/plan-epic.md` § Phase 7](plan-epic.md#phase-7-epic-planning-tech-spec--acceptance-spec).
+> Read that section — do not resurrect an inline copy here.
+
+The complementary Phase 8 pointer is
+[`helpers/epic-plan-decompose.md`](epic-plan-decompose.md).