mandrel 1.80.0 → 1.82.0

package/.agents/workflows/helpers/code-review.md

@@ -79,13 +79,15 @@ review yourself, honor the `depth` semantics above directly.
 
 1. Resolve `[TICKET_ID]` from `ticketId` (Story or Epic depending on `scope`).
 2. Resolve `[BASE_REF]` from `baseRef` and `[HEAD_REF]` from `headRef`.
-3. Fetch the `[TICKET_ID]` ticket and identify linked context tickets:
+3. Fetch the `[TICKET_ID]` ticket and resolve the planning context:
    - **Story scope** — read the parent Epic from the Story body, then load
-     the Epic's `context::prd` (PRD) and `context::tech-spec` (Tech Spec).
-   - **Epic scope** — load the Epic's `context::prd` (PRD) and
-     `context::tech-spec` (Tech Spec) directly from the Epic body.
-4. Read both the PRD and Tech Spec fully to understand the intended scope,
-   architectural decisions, and acceptance criteria.
+     the Epic body (including its `## User Stories` section and its folded
+     Tech Spec sections).
+   - **Epic scope** — read the Epic body directly; its managed sections
+     carry the Tech Spec.
+4. Read the Epic body fully (including its Tech Spec sections) to
+   understand the intended
+   scope, architectural decisions, and acceptance criteria.
 
 ## Step 1 — Automated Audit (Pre-Review)
 
@@ -120,7 +122,7 @@ before finalizing findings.
 
 ### Pillar 1: Spec Adherence
 
-Does the implementation match the PRD requirements and Tech Spec architecture?
+Does the implementation match the Epic's requirements and Tech Spec architecture?
 
 - Compare each completed Story/Task against its stated acceptance criteria.
 - Flag any undocumented deviations, missing features, or scope creep.
@@ -251,7 +253,7 @@ anything not fixed in-place.
      structured comment for the operator to triage in Step 5.
 2. **Leave the finding on the structured comment for Step 5.** 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.
@@ -359,7 +361,7 @@ to the next phase of the parent workflow.
   the scope is set by the caller, and reviewing against the wrong base
   produces either a hollow review (too small a diff) or noise (too large a
   diff that includes unrelated history).
-- **Always** read the PRD and Tech Spec before reviewing code. Findings without
+- **Always** read the Epic body and Tech Spec before reviewing code. Findings without
   spec context are noise.
 - **Never** implement fixes unless the operator explicitly requests it. The
   default mode is read-only audit.

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

@@ -167,24 +167,17 @@ Validates `type::epic`, enumerates `type::story` descendants, parses
 (to enumerate the open Story set), and upserts the `epic-run-state`
 checkpoint in the per-Story-status shape (a flat `stories` map seeded at
 `pending`, plus the global `concurrencyCap`). Treat the printed JSON as
-`state`: `{ epicId, storyCount, concurrencyCap, stories, prdId, techSpecId, checkpointInitializedAt }`.
+`state`: `{ epicId, storyCount, concurrencyCap, stories, checkpointInitializedAt }`.
 `stories` is the flat dispatch hint (`{ storyId, worktree, title }` per open
 Story); the ready-set `tick` (Phase 2) decides which to dispatch on each
 beat. Flip the Epic to `agent::executing` (idempotent) after the CLI returns.
 
-**Epic linkages resolved once (Story #4253).** The envelope also carries
-`prdId` and `techSpecId` — the Epic's linked PRD / Tech-Spec issue ids,
-resolved a **single** time here from the Epic snapshot prepare already
-holds (no extra fetch). Capture both and thread them into **every**
-per-Story `story-init.js` invocation (§ 2b → `epic-deliver-story` Step 0)
-as `--prd <prdId> --tech-spec <techSpecId>`. This collapses the N
-per-Story `getEpic` round-trips (one per child, each in its own process
-with its own provider cache) to this one parent-side resolution — the
-immutable Epic issue is invariant for the lifetime of a delivery run.
-When a linkage is `null` (the Epic links no PRD or Tech Spec), omit the
-corresponding flag; the child's `story-init.js` then falls back to its
-own `getEpic` resolution for the missing id, preserving graceful
-degradation.
+**No spec-ticket linkage to resolve (Story #4324).** The Tech Spec lives
+as managed sections of the Epic body itself — there is no separate
+Tech-Spec issue id in the envelope and no `--tech-spec` flag to thread
+into the per-Story `story-init.js` invocations. Story agents receive the
+Tech Spec via context hydration, which embeds the Epic body (with the
+`## Acceptance Table` section stripped) directly into each Story prompt.
 
 > **Preflight guards (Story #3482 / F-workflow-guards).** Before the
 > snapshot phase runs — and before any worktree is created — prepare runs
@@ -218,19 +211,19 @@ degradation.
 
 Once the preflight guards pass, the snapshot phase applies one more gate:
 
-> **Acceptance-spec start gate.** Before the wave loop fans out, the
+> **Acceptance-table start gate.** Before the wave loop fans out, the
 > snapshot phase
 > ([`lib/orchestration/epic-runner/phases/snapshot.js`](../../scripts/lib/orchestration/epic-runner/phases/snapshot.js))
 > asserts that the Epic either carries the `acceptance::n-a` waiver
-> label **or** has a linked `context::acceptance-spec` ticket. The
-> ticket's GitHub state (open / closed) is **not** checked —
-> presence is sufficient, matching the PRD and Tech Spec contract.
+> label **or** has a `## Acceptance Table` managed section in its
+> body — section presence is sufficient.
 > The reviewer's OK during `/plan` Phase 7 is the approval
-> signal, not a manual ticket-close action. Neither condition met →
+> signal. Neither condition met →
 > the snapshot throws a clear error
-> (`[epic-deliver] Epic #<id> cannot launch: …`) and `runAsCli`
+> (`[epic-deliver] Epic #<id> cannot launch: …` — naming the missing
+> `## Acceptance Table` section and the absent waiver) and `runAsCli`
 > maps it to `process.exit(1)`. Operator remediation: either run
-> `/plan` Phase 7 to author the spec, or apply the
+> `/plan` Phase 7 to author the acceptance table, or apply the
 > `acceptance::n-a` label to opt out.
 
 ---
@@ -348,10 +341,7 @@ matching `story.dispatch.end` record is appended later by
 `epic-execute-record-wave.js` (via `emit-story-dispatch-end.js`, Story #3900)
 after the Agent return is recorded in § 2c.
 
-Each Agent call's prompt must (1) name the Story + Epic ids **and the
-`prdId` / `techSpecId` from the Phase 1 prepare envelope** (Story #4253) so
-the child can thread `--prd <prdId> --tech-spec <techSpecId>` into its
-`story-init.js` Step 0 — omit whichever flag is `null`, (2)
+Each Agent call's prompt must (1) name the Story + Epic ids, (2)
 instruct the child to invoke `helpers/epic-deliver-story <storyId>`
 (whose Step 4 defines the child's return shape), (3) remind the child
 of the **non-interactive contract** (no clarifying questions;
@@ -765,19 +755,22 @@ bus-owned finalize) composes three helpers under
 chain.** Treat this section as a runtime contract — `/deliver`
 just fires the emit and reads the resulting ledger.
 
-1. **Acceptance-spec reconciliation — bus-driven.** The
+1. **Acceptance-table reconciliation — bus-driven.** The
    `AcceptanceReconciler` listener invokes
    [`acceptance-spec-reconciler.js`](../../scripts/acceptance-spec-reconciler.js)
-   to diff the AC IDs declared in the linked `context::acceptance-spec`
-   body against `@ac-*` / `@pending` tags in `tests/features/**`. A
+   to diff the AC IDs declared in the Epic body's `## Acceptance Table`
+   section against `@ac-*` / `@pending` tags in `tests/features/**`,
+   recording each row's verification outcome
+   (`satisfied` / `pending` / `missing`) into the table's Disposition
+   column via a section-scoped upsert of the Epic body. A
    non-OK reconciliation throws (per
    [`rules/orchestration-error-handling.md`](../../rules/orchestration-error-handling.md)),
-   aborting finalize **before** any PR is opened or planning artifacts
-   are closed — so the PRD, Tech Spec, and Acceptance Spec stay open
-   until the AC coverage gap is fixed. The reconciler returns
+   aborting finalize **before** any PR is opened — so the Epic stays
+   unfinalized until the AC coverage gap is fixed. The reconciler returns
    `status: 'waived'` without scanning features when the Epic carries
    `acceptance::n-a`, and defends against direct CLI invocation by
-   refusing to run when no spec is linked and no waiver is set (the
+   refusing to run when the body has no `## Acceptance Table` section
+   and no waiver is set (the
    start gate in Phase 1 would normally catch that first).
 2. **PR open — bus-driven (Story #2894).** On
    `acceptance.reconcile.ok` the `Finalizer` listener invokes
@@ -800,21 +793,16 @@ just fires the emit and reads the resulting ledger.
    in [`check-lifecycle-lint.js`](../../scripts/check-lifecycle-lint.js)
    keeps `gh pr merge --auto --squash --delete-branch` confined to
    `AutomergeArmer` — Phase 7 never shells the merge command.
-3. **Planning-artifact close + hand-off — bus-driven (Story
-   #2894).** After `openOrLocatePr` returns, the `Finalizer` chains
-   [`closePlanningTickets`](../../scripts/lib/orchestration/finalize/close-planning-tickets.js)
-   to close the three planning context tickets
-   (`context::prd`, `context::tech-spec`, `context::acceptance-spec`)
-   so the Epic's `Closes #<id>` auto-close path is not blocked by
-   open sub-issues, then
+3. **Hand-off — bus-driven (Story #2894).** After `openOrLocatePr`
+   returns, the `Finalizer` chains
    [`postHandoffComment`](../../scripts/lib/orchestration/finalize/post-handoff-comment.js)
    to upsert the canonical `epic-handoff` structured comment naming
-   the PR URL. Both helpers are idempotent — already-closed tickets
-   are counted under `alreadyClosed`, and the handoff comment is
+   the PR URL. The helper is idempotent — the handoff comment is
    edited in place via `upsertStructuredComment` rather than
-   appending a duplicate. When the `acceptance::n-a` waiver is set
-   and no Acceptance Spec ticket was ever opened, the third
-   planning-ticket close is recorded as `skipped`.
+   appending a duplicate. There is **no planning-ticket close sweep**
+   (Story #4324): the planning artifacts live as sections of the Epic
+   body itself, so there are no context tickets to close and nothing
+   blocks the Epic's `Closes #<id>` auto-close path.
 
 Branch cleanup is out-of-band (Phase 9 reaps local refs after merge; the
 rare "scrap and reset" case for an unmerged Epic is handled manually).

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

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