mandrel 1.81.0 → 1.83.0

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

@@ -44,12 +44,15 @@ change-set selection. Both lens sources fire through the **same**
 2. Resolve `[EPIC_BRANCH]` — `epic/<epicId>`.
 3. Resolve `[BASE_BRANCH]` from `baseBranch` in `.agentrc.json` (default:
    `main`).
-4. Fetch the Epic ticket and identify linked context tickets:
-   - **PRD** — the `context::prd` ticket linked in the Epic body.
-   - **Tech Spec** — the `context::tech-spec` ticket linked in the Epic
-     body.
-5. Read both the PRD and Tech Spec fully to understand the intended scope,
-   selected lenses, and acceptance criteria.
+4. Fetch the Epic ticket — the Epic body is the single planning
+   document:
+   - **Narrative sections** — Context / Goal / Scope / User Stories /
+     Acceptance Criteria.
+   - **Tech Spec** — the folded Tech Spec sections (opening with
+     `## Delivery Slicing`) inside the body's managed region.
+5. Read the Epic body fully (including its Tech Spec sections) to
+   understand the intended
+   scope, selected lenses, and acceptance criteria.
 
 ## Step 1 — Prepare (`epic-audit-prepare.js`)
 
@@ -226,7 +229,7 @@ For each 🔴 / 🟠 finding, the host LLM MUST decide between two paths:
      (path 2) and record the attempt context in Step 4.
 2. **Escalate to the operator via Step 4.** Required when the finding
    falls into any of the following classes:
-   - `spec-deviation` — the change diverges from the PRD/Tech Spec.
+   - `spec-deviation` — the change diverges from the Epic/Tech Spec.
    - `secrets` — credentials, tokens, or PII surfaced in the diff.
    - `test-deletion` — coverage was removed without an explicit
      decision in the spec.
@@ -282,7 +285,7 @@ The body MUST include:
 
 - **Always** diff against `[BASE_BRANCH]`, not against individual Story
   branches. The audit examines the cumulative effect of the entire Epic.
-- **Always** read the PRD and Tech Spec before walking lenses. Findings
+- **Always** read the Epic body and Tech Spec before walking lenses. Findings
   without spec context are noise.
 - **Always** cap focused fixes at one attempt per finding (Step 3). The
   host LLM is the executor; there is no shared retry/anti-thrash module

package/.agents/workflows/helpers/epic-deliver-story.md

@@ -77,21 +77,15 @@ the parent's permissions but have **no input channel** mid-run.
 Run from the **main checkout** (the worktree does not exist yet):
 
 ```bash
-node .agents/scripts/story-init.js --story <storyId> \
-  --prd <prdId> --tech-spec <techSpecId>
+node .agents/scripts/story-init.js --story <storyId>
 ```
 
-**Thread the Epic linkages (Story #4253).** The parent `/deliver` resolved
-the Epic's `prdId` / `techSpecId` **once** in its Phase 1 prepare and passed
-them into your dispatch prompt. Forward them as `--prd` / `--tech-spec` so
-this `story-init.js` run **skips** the per-Story `getEpic` round-trip — the
-two ids are invariant for the whole delivery run, so re-fetching the
-immutable Epic per Story is pure waste (and secondary-rate-limit pressure
-during wide fan-out). **Omit** whichever flag the prompt reported as `null`;
-`story-init.js` then falls back to its own `getEpic` resolution for the
-missing id (graceful degradation on a missing Epic linkage). When dispatched
-interactively with neither flag, drop both — the legacy single-fetch path is
-unchanged.
+**No spec-ticket threading (Story #4324).** The Tech Spec lives as managed
+sections of the Epic body — there is no separate Tech-Spec issue, no
+`--tech-spec` flag, and no per-Story hierarchy trace to a spec ticket.
+Your hydrated prompt already embeds the Epic body (with the
+`## Acceptance Table` section stripped), which carries the folded Tech
+Spec sections; do not fetch a Tech Spec issue.
 
 > **Execution mode (sub-agents must read).** This command typically takes
 > 3–6 minutes when the worktree's per-tree install runs. Invoke it
@@ -105,15 +99,15 @@ unchanged.
 > partial state, so the recovery is to re-run it synchronously, but
 > prevention is cheaper: just give Bash the 10-minute timeout and block.
 
-The script validates `type::story`, checks blockers, traces the
-Epic → PRD/Tech-Spec hierarchy, seeds `story-<id>` from the
+The script validates `type::story`, checks blockers, resolves the parent
+Epic id, seeds `story-<id>` from the
 Epic branch, and (when worktree isolation is on) runs `git worktree add`
 at `.worktrees/story-<id>/`. The Story flips to `agent::executing`. A
 `story-init` structured comment is upserted with the Story's inline
 `acceptance[]` and `verify[]` arrays from the body.
 
 Capture `workCwd`, `dependenciesInstalled` (tri-state), and
-`context.{prdId,techSpecId,acceptance,verify}`. Add `--dry-run` to check
+`context.parentId`. Add `--dry-run` to check
 status without git or ticket changes.
 
 ### Step 0.5 — `cd` into the workCwd
@@ -139,11 +133,15 @@ in-process (retrying the install command when
 `dependenciesInstalled === 'false'`, default `npm ci`) and rendered the
 initial snapshot (`phase: "init"`). There is no separate command to run.
 
-The Step 0 result envelope carries a `prepare.renderedBody` field — the
-markdown body for the initial Story-phase table. **Relay it verbatim to
-chat** so operators see the initial progress block before the first commit
-lands. Do the same after every transition in Step 1 / Step 3 (the body is
-the Story-level rollup the parent `/deliver` aggregator reads).
+Step 0's init run already upserted the initial `story-run-progress`
+snapshot (`phase: "init"`) as a structured comment on the Story — that
+comment, refreshed by `story-phase.js` at each transition, is the
+authoritative Story-level rollup the parent `/deliver` aggregator reads.
+You do **not** relay `prepare.renderedBody` verbatim to chat. Instead,
+relay **one line per phase transition** (e.g. `Story #<id>: init →
+implementing`), and do the same after every transition in Step 1 / Step 3.
+The snapshot CLI carries the full body; the chat line is a terse progress
+delta, not a body dump.
 
 ---
 
@@ -168,6 +166,20 @@ Run a single Story-implementation phase against the inline `acceptance[]`
    `context.verify`). Treat the acceptance items as the contract and
    the verify items as the canonical at-keyboard checks.
 
+   **Docs context — read the digest, not the full set.** Do **not**
+   re-read every file in `project.docsContextFiles`. The parent prompt
+   passes a `docsDigestPath` (the per-Epic docs digest at
+   `temp/epic-<epicId>/docs-digest.md`, written by
+   `epic-deliver-prepare.js`). Read that digest — a compact per-file
+   outline (path, size, heading outline with line numbers, first
+   paragraph under each `##`) — to decide which docs bear on this Story,
+   then **pull the full file on demand** (jump to the section at the line
+   number the digest names) only when relevant. When `docsDigestPath` is
+   null (the project configured no `docsContextFiles`), there is no
+   digest and no per-Story docs mandate — read a full doc only if the
+   Story's own context points you at one. See
+   [`.agents/instructions.md` § 3](../../instructions.md).
+
 3. Implement the work as one or more commits on `story-<storyId>`.
    Author commits directly with the project's editor / `git commit`,
    following
@@ -246,10 +258,14 @@ partially-implemented Story picks up from whatever commits are already
 on `story-<storyId>`; the agent inspects `git log` to decide what work
 remains.
 
-After each `story-phase.js` call, **relay the envelope's
-`renderedBody` to chat** as the Story's progress update. Skip chat
-relay only when running in a non-interactive sub-agent context where
-the parent will aggregate.
+After each `story-phase.js` call, relay **one line naming the phase
+transition** (e.g. `Story #<id>: implementing → closing`) as the Story's
+progress update — not the envelope's `renderedBody` verbatim. The
+`story-phase.js` CLI has already upserted the full body into the
+`story-run-progress` snapshot; that comment is the authoritative rollup
+the parent `/deliver` aggregator reads. Skip chat relay entirely when
+running in a non-interactive sub-agent context where the parent will
+aggregate.
 
 > Rebase pauses on conflicts → follow
 > [`_merge-conflict-template.md`](_merge-conflict-template.md).
@@ -344,8 +360,10 @@ regardless of the reap status.
 `story-phase.js` (typically the `phase: 'done'` snapshot at close,
 or the `phase: 'blocked'` snapshot on a blocker). The parent
 `/deliver` may inline a digest of this in its wave-level Notable
-section. When run interactively (no parent), omit it — the chat already
-has the latest body relayed during Step 1 / Step 3.
+section. When run interactively (no parent), omit it — the authoritative
+body lives in the `story-run-progress` snapshot the phase CLI upserted,
+and the chat already carries the per-transition progress lines from
+Step 1 / Step 3.
 
 ---
 

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

@@ -1,6 +1,7 @@
 ---
 description: >-
-  Phase 8 of sprint planning — decompose an Epic's PRD and Tech Spec into a
+  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.
 ---
@@ -18,8 +19,9 @@ Director / Architect
 ## Context
 
 This helper is the **decompose phase** of the split planning pipeline. It
-reads the PRD and Tech Spec previously produced by the spec phase helper
-([`epic-plan-spec.md`](epic-plan-spec.md)), generates the Epic's child
+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.
@@ -38,9 +40,9 @@ skill.
 
 ## Constraint
 
-- **Do not** run this skill until the spec phase is complete. The Epic must
-  have linked `context::prd` and `context::tech-spec` issues; the script will
-  refuse to proceed otherwise.
+- **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.
@@ -52,7 +54,7 @@ skill.
 ## Prerequisites
 
 1. **Epic is on `agent::review-spec`** — i.e. the spec phase has already run
-   and the PRD / Tech Spec exist.
+   and the Epic body carries the Tech Spec sections.
 2. **API keys** — `GITHUB_TOKEN` set in `.env`.
 
 ## Step 1 — Gather decomposition context
@@ -62,7 +64,8 @@ node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] --emit-context \
   > temp/epic-[Epic_ID]/decomposer-context.json
 ```
 
-The emitted JSON contains the PRD body, Tech Spec body, risk heuristics, the
+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).
@@ -74,7 +77,7 @@ 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 PRD
+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)
@@ -87,7 +90,8 @@ 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 PRD / Tech Spec from
+`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:
 
@@ -187,8 +191,9 @@ is the single source of truth for which temp paths this phase owns.
 
 ## Troubleshooting
 
-- "Epic #N is missing a linked PRD or Tech Spec" — run `/plan [Epic_ID]`
-  first (it will run the spec phase if the PRD / Tech Spec are missing).
+- "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

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

@@ -1,8 +1,8 @@
 ---
 description: >-
-  Phase 7 of sprint planning — generate the PRD and Tech Spec for an Epic,
-  persist them as linked GitHub issues, and flip the Epic to
-  `agent::review-spec`. Host-LLM authored; no external API calls.
+  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.
 ---
 
 # Sprint Plan — Spec Phase (helper)
@@ -18,22 +18,28 @@ Director / Architect
 ## Context
 
 This helper is the **spec phase** of the split planning pipeline. It produces
-**three** planning artifacts for an Epic — a Product Requirements Document, a
-Technical Specification, and an Acceptance Spec — persists them as
-`context::prd`, `context::tech-spec`, and `context::acceptance-spec` issues
-under the Epic, and flips the Epic to `agent::review-spec` (parking) so a human
-reviewer can read the artifacts on GitHub before decomposition.
+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 context tickets, the three-ticket rationale, the
+> (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 PRD and Tech Spec 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 artifacts and transitions the Epic
-lifecycle state.
+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`
@@ -41,14 +47,14 @@ wrapper chains both helpers with a confirmation gate in between.
 
 ## Constraint
 
-- **Do not** create or modify tickets outside the `context::prd` /
-  `context::tech-spec` / `context::acceptance-spec` contract —
+- **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/prd.md` will collide.
+  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
@@ -58,7 +64,8 @@ wrapper chains both helpers with a confirmation gate in between.
 ## Prerequisites
 
 1. **GitHub Epic** — an open issue with the `type::epic` label. The Epic's
-   body should contain enough narrative context to seed the PRD.
+   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
@@ -71,23 +78,18 @@ node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] --emit-context \
   > temp/epic-[Epic_ID]/planner-context.json
 ```
 
-## Step 2 — Author the PRD
+## Step 2 — Author the Tech Spec
 
-Read `temp/epic-[Epic_ID]/planner-context.json`. Using `systemPrompts.prd`
-combined with the Epic title/body, write the PRD markdown to
-`temp/epic-[Epic_ID]/prd.md`. Use the four-section structure (Context & Goals,
-User Stories, Acceptance Criteria, Out of Scope) and start the document with
-`## Overview` (no `<h1>`).
+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 3 — Author the Tech Spec
+## Step 2.5 — Author the risk verdict
 
-Using `systemPrompts.techSpec`, the PRD you just wrote, and `docsContext`,
-write the Tech Spec to `temp/epic-[Epic_ID]/techspec.md`. Start with
-`## Technical Overview` (no `<h1>`).
-
-## Step 3.5 — Author the risk verdict
-
-Judge the change described by the PRD and Tech Spec you just wrote and
+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
@@ -95,39 +97,36 @@ 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 3.6 — Author the Acceptance Spec
+## Step 2.6 — Author the Acceptance Table
 
-Using `systemPrompts.acceptanceSpec`, the PRD, and the Tech Spec, write the
-Acceptance Spec to `temp/epic-[Epic_ID]/acceptance-spec.md`. It captures the
-stable-ID acceptance criteria table
-(`| AC ID | Outcome | Feature File | Scenario | Disposition |`) that drives
-close-time reconciliation in `/deliver` Phase 6.
+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-spec`
-from Step 4.
+label (refactor-only or docs-only Epics); in that case omit
+`--acceptance-table` from Step 3.
 
-## Step 4 — Persist and transition
+## Step 3 — Persist and transition
 
 ```bash
-# Normal flow (three context tickets)
+# Normal flow (both managed sections)
 node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] \
-  --prd temp/epic-[Epic_ID]/prd.md \
-  --techspec temp/epic-[Epic_ID]/techspec.md \
+  --tech-spec temp/epic-[Epic_ID]/techspec.md \
   --risk-verdict temp/epic-[Epic_ID]/risk-verdict.json \
-  --acceptance-spec temp/epic-[Epic_ID]/acceptance-spec.md
+  --acceptance-table temp/epic-[Epic_ID]/acceptance-spec.md
 
-# Re-plan (--force overwrites the three context tickets in place)
+# Re-plan (--force overwrites the managed sections in place)
 node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] \
-  --prd temp/epic-[Epic_ID]/prd.md \
-  --techspec temp/epic-[Epic_ID]/techspec.md \
+  --tech-spec temp/epic-[Epic_ID]/techspec.md \
   --risk-verdict temp/epic-[Epic_ID]/risk-verdict.json \
-  --acceptance-spec temp/epic-[Epic_ID]/acceptance-spec.md --force
+  --acceptance-table temp/epic-[Epic_ID]/acceptance-spec.md --force
 
-# Waived (acceptance::n-a label on Epic — no Acceptance Spec authored)
+# Waived (acceptance::n-a label on Epic — no Acceptance Table authored)
 node .agents/scripts/epic-plan-spec.js --epic [Epic_ID] \
-  --prd temp/epic-[Epic_ID]/prd.md \
-  --techspec temp/epic-[Epic_ID]/techspec.md \
+  --tech-spec temp/epic-[Epic_ID]/techspec.md \
   --risk-verdict temp/epic-[Epic_ID]/risk-verdict.json
 ```
 
@@ -136,22 +135,21 @@ 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.
-- Creates `[PRD]`, `[Tech Spec]`, and `[Acceptance Spec]` child issues
-  (`context::prd` / `context::tech-spec` / `context::acceptance-spec`
-  labels). The Acceptance Spec is skipped when `--acceptance-spec` is
-  omitted under the `acceptance::n-a` waiver.
-- Appends a `## Planning Artifacts` section to the Epic body.
+- 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,
-  PRD / Tech Spec / Acceptance Spec IDs, the `riskVerdict` field, and
-  timestamps.
+  the persisted-section flags (`techSpecPersisted`, `acceptanceTable`),
+  the `riskVerdict` field, and timestamps.
 - Flips the Epic to `agent::review-spec`.
 
-## Step 5 — Cleanup
+## Step 4 — Cleanup
 
 The wrapper script deletes the phase-scoped temp files automatically when
-Step 4 succeeds — no operator action required. The cleanup contract lives in
+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
@@ -162,12 +160,13 @@ need to inspect the temp artefacts after the fact, re-run
 Branch on the shared planning risk decision surfaced in the persist stdout
 JSON (`planningRisk`, `reviewRouting`):
 
-- **High risk or `--force-review` — STOP.** Surface the PRD and Tech Spec
-  URLs to the operator:
+- **High risk or `--force-review` — STOP.** Surface the Epic URL to the
+  operator:
 
-  > "Spec phase complete for Epic #[ID]. Review PRD (#XX) and Tech Spec (#YY)
-  > 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."
+  > "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
@@ -177,8 +176,9 @@ JSON (`planningRisk`, `reviewRouting`):
 
 - 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 creating the PRD but before the Tech Spec,
-  re-run with `--force` (the script reuses the existing PRD when appropriate).
+- 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 existing PRD/Tech Spec.
+  persist step; it's idempotent against the already-persisted sections.

package/.agents/workflows/helpers/parallel-tooling.md

@@ -20,7 +20,8 @@ them in one assistant turn rather than serially. The host runtime executes
 the batch in parallel; serial calls cost N round-trips for no gain.
 
 - **Tool primitives:** `Read`, `Grep`, `Glob`, MCP `list_*` / `get_*` calls.
-- **When:** reading the PRD, Tech Spec, and Story body up front; grepping
+- **When:** reading the Epic body (with its folded Tech Spec sections)
+  and Story body up front; grepping
   for multiple unrelated patterns; globbing several directory trees;
   fetching independent GitHub tickets.
 - **Anti-pattern:** sequential `Read` → wait → `Read` → wait → `Grep` chains

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

@@ -0,0 +1,136 @@
+---
+description: >-
+  Reference companion to plan-epic.md — the recovery procedures, --resume
+  mechanics, troubleshooting, and background rationale blocks moved out of the
+  runtime core so every /plan run ingests only the phase flow. Read on demand
+  from the trigger-point pointers in plan-epic.md.
+caller: plan-epic.md
+---
+
+# helpers/plan-epic-reference — Epic-planning reference & recovery
+
+> **Not a slash command.** This file lives in `helpers/` and is a
+> path-included reference module (not projected into the plugin command
+> tree). [`plan-epic.md`](plan-epic.md) is the runtime core — the phase
+> flow, commands, and gate contracts. This file holds the secondary
+> material a run needs only when it hits an edge (a recovery path, a
+> troubleshooting symptom) or wants the design rationale behind a phase.
+> Each section below is reached from a one-line pointer at its trigger
+> point in the core.
+
+## Phase 7 — background rationale
+
+The Phase 7 (Tech Spec & Acceptance Spec) core carries only the commands and
+the gate contract. The design rationale for the phase's guards and managed
+sections lives here.
+
+### Epic-lease preflight (workflow guard)
+
+Before any Phase 7 mutation, `epic-plan-spec.js` acquires the Epic-lease via
+the assignee-as-lease primitive (`lib/orchestration/ticket-lease.js`, wired
+through `lib/orchestration/epic-plan-lease-guard.js`). The lease rides the
+Epic's single assignee: the operator (`github.operatorHandle` in
+`.agentrc.json`) claims the Epic for the duration of the plan. The guard
+**fails closed**: `/plan` emits no `story.heartbeat` during its run
+(heartbeats are a delivery-time signal), so there is no live-heartbeat source
+to judge a concurrent plan's liveness from. Any **foreign assignee** is
+therefore treated as a live claim — the persist half **exits non-zero and
+names the current owner**, so two `/plan` runs cannot drive the same Epic
+concurrently. Pass **`--steal`** to forcibly transfer a foreign claim once you
+have confirmed the other run is dead. An **unassigned** Epic, or one **already
+held by this operator**, is taken (or re-affirmed) silently. The lease is
+**released after Phase 8** (decompose) completes.
+
+### Idempotent managed sections
+
+The persist half is section-scoped and keyed on the Epic body: a re-run that
+finds the requested sections already present
+(`<!-- mandrel:tech-spec:start/end -->` /
+`<!-- mandrel:acceptance-table:start/end -->`) short-circuits as
+`already-planned` instead of duplicating content. Pass `--force` to overwrite
+the managed sections in place (same Epic issue, refreshed section bodies).
+
+### One planning document
+
+A `/plan` Epic run creates exactly **one** issue — the Epic. The planning
+artifacts land as marker-delimited managed sections of the Epic body: the Tech
+Spec (opening with `## Delivery Slicing`) inside
+`<!-- mandrel:tech-spec:start/end -->`, and the Acceptance Spec's AC-ID table
+(headed `## Acceptance Table`) inside
+`<!-- mandrel:acceptance-table:start/end -->`. The PRD artifact class was
+retired (Story #4314) — its one novel section, **User Stories**, lives inline
+in the Epic body as a `## User Stories` section — and Story #4324 retired the
+`context::tech-spec` / `context::acceptance-spec` ticket classes the same way.
+The `## Acceptance Table` section captures the stable-ID acceptance criteria
+table (`| AC ID | Outcome | Feature File | Scenario | Disposition |`) that
+drives close-time reconciliation during `/deliver` Phase 6. Operators may opt
+out for refactor-only or docs-only Epics by applying the `acceptance::n-a`
+label to the Epic ticket — when present, the `epic-plan-spec-author` skill
+skips the Acceptance Table output and the runtime gates (start gate, finalize
+reconciler) honour the waiver — the section need not be authored when the
+waiver is set. See [SDLC § Acceptance Table — the second folded planning
+section](../../docs/SDLC.md#acceptance-table--the-second-folded-planning-section)
+for the full lifecycle.
+
+### Parallel-safe file naming (per-Epic tree)
+
+Multiple Epics may be planned or decomposed concurrently. Every temp file
+written in the workflow lives under the per-Epic tree
+(`temp/epic-[Epic_ID]/<artifact>`) — e.g.
+`temp/epic-[Epic_ID]/planner-context.json`,
+`temp/epic-[Epic_ID]/techspec.md`,
+`temp/epic-[Epic_ID]/decomposer-context.json`,
+`temp/epic-[Epic_ID]/tickets.json`. The directory namespace is the isolation
+boundary; basenames inside it are stable. Do **not** reuse bare flat names
+like `temp/techspec.md` or the legacy `temp/<artifact>-epic-<id>.<ext>` shape
+— both have been retired.
+
+**Durability.** The per-Epic tree is durable across runs: only the wrapper
+scripts perform intra-phase cleanup of files they wrote in the same invocation
+(see [`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js)).
+Nothing else garbage-collects the tree, so cross-Epic artifacts — retros, perf
+reports, signals, manifests — accumulate until an operator explicitly removes
+them.
+
+## Phase 8 — `--resume` recovery (secondary rate limit)
+
+The Phase 8 (Work Breakdown Decomposition) core carries the normal-path and
+`--force` persist commands. The `--resume` recovery path — reached when a
+large decomposition aborts mid-persist — lives here.
+
+**Secondary rate limit on large Epics.** For backlogs over ~60 tickets,
+GitHub's secondary rate limit (HTTP 403, body contains "secondary rate limit")
+can trip mid-decomposition after ~80 issue creations. The http-client retries
+automatically with a 30–120s backoff and the decomposer drops `concurrencyCap`
+to 1 for the rest of the run on the first observation. If the run still aborts
+(network drop, exhausted retries, etc.), resume from the partial backlog with:
+
+```bash
+node .agents/scripts/epic-plan-decompose.js --epic [Epic_ID] \
+  --tickets temp/epic-[Epic_ID]/tickets.json --resume
+```
+
+`--resume` is idempotent: the reconciler recovers the slug→issue map from
+`temp/epic-[Epic_ID]/[Epic_ID].state.json`, and when that file is missing or
+incomplete it **reseeds the map from live GitHub state** by matching each spec
+slug against the open children of the Epic by title. Slugs that resolve to an
+existing open child diff as Updates/no-ops; only the genuinely-missing children
+are created — the existing tree is never duplicated. To force-throttle from the
+first call on a known-large Epic, set `(framework constant: decomposer
+concurrency): 1` in `.agentrc.json`.
+
+## Troubleshooting
+
+- If `epic-plan-spec.js --emit-context` fails, confirm the Epic exists and
+  has a body with enough initial context.
+- If `epic-plan-decompose.js` rejects the tickets file, re-read the
+  validator's error message — the most common causes are a ticket whose
+  `type` is not `story`, a Story missing its inline `acceptance[]` /
+  `verify[]` contract, or a dependency cycle in the Story `depends_on`
+  graph.
+- If decomposition persisted the tickets but the Epic is not on `agent::ready`,
+  you likely called `runDecomposePhase` from `epic-plan-decompose.js`
+  directly without completing the persist flow — only the CLI surface
+  (`node epic-plan-decompose.js --tickets ...`) drives the full
+  reconciler pipeline and flips the lifecycle label. Apply `agent::ready`
+  by hand and re-run via the CLI next time.