mandrel 1.80.0 → 1.82.0

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

@@ -1,6 +1,6 @@
 ---
 description:
-  Orchestrates end-to-end Epic planning (PRD, Tech Spec, Acceptance Spec, and
+  Orchestrates end-to-end Epic planning (Tech Spec, Acceptance Spec, and
   Work Breakdown) for a GitHub Epic.
 ---
 
@@ -22,7 +22,7 @@ phase helpers — [`helpers/epic-plan-spec.md`](epic-plan-spec.md) and
 both phases sequentially with a human confirmation gate between them. The Epic
 ID is the single positional argument.
 
-As of v5.6, planning artifacts (PRD, Tech Spec, ticket decomposition) are
+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
@@ -207,7 +207,7 @@ new Epic is genuinely distinct).
 
 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 PRD authoring
+   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
@@ -215,30 +215,36 @@ new Epic is genuinely distinct).
 
 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 no PRD/Tech Spec is linked yet,
-   so the run flows naturally into Phase 6 (Epic Clarity Gate) and then
-   Phase 7.
+   (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 a
-   `## Planning Artifacts` section containing PRD and Tech Spec references.
-2. **If already planned**: Inform the user that this Epic already has planning
-   artifacts. Ask:
-
-   > "Epic #[ID] already has PRD (#XX) and Tech Spec (#XX) with YY decomposed
-   > tickets. Do you want to **re-plan**? This will **overwrite the PRD,
-   > Tech Spec, and Acceptance Spec in place** (same issue numbers, refreshed
-   > bodies, comment history preserved) and **close-and-recreate** all
-   > child Story tickets."
+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 three context tickets (PRD, Tech Spec,
-   Acceptance Spec) are overwritten in place — their issue numbers, Epic
-   sub-issue links, and prior discussion are preserved, and each receives a
+   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.
@@ -257,16 +263,16 @@ clarity gate does not make.
 
 The advisory runs **only** when **both** hold:
 
-1. **Phase 5 found no planning artifacts** — the Epic body has no
-   `## Planning Artifacts` section linking a PRD / Tech Spec (i.e. Phase 5
-   did **not** enter its re-plan branch).
+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 a PRD and a ticket tree is
-nonsense and would collide with the `--force` re-plan flow. The advisory also
+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.
 
@@ -352,11 +358,13 @@ via [`/single-story-deliver`](single-story-deliver.md) or
 
 Runs on every existing-Epic invocation, after Phase 5 (Re-Plan
 Detection) and the Phase 5.5 story-sized advisory, and before Phase 7
-(PRD, Tech Spec & Acceptance Spec). The gate scores the Epic body
-against the five canonical
+(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) and either
+(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`,
@@ -406,8 +414,8 @@ for the scoring logic.
 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 **three**
-   downstream artifacts (PRD, Tech Spec, Acceptance Spec) — treat
+   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
@@ -443,7 +451,7 @@ for the scoring logic.
    remediation hint to the operator. Do not loop — one refinement
    pass per invocation, matching the `--force` re-plan pattern.
 
-## Phase 7: Epic Planning (PRD, Tech Spec & Acceptance Spec)
+## Phase 7: Epic Planning (Tech Spec & Acceptance Spec)
 
 > **Epic-lease preflight (workflow guard).** Before any Phase 7 mutation,
 > `epic-plan-spec.js` acquires the Epic-lease via the assignee-as-lease
@@ -464,28 +472,36 @@ for the scoring logic.
 
 <!-- separator: adjacent blockquotes -->
 
-> **Idempotent context tickets.** The persist half is find-or-create keyed on
-> the Epic's `linkedIssues`: a re-run **reuses the already-linked PRD and Tech
-> Spec issues** (and Acceptance Spec, when present) instead of creating
-> duplicates. Pass `--force` to overwrite the canonical context tickets in
-> place (same issue numbers, refreshed bodies).
+> **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).
 
 <!-- separator: adjacent blockquotes -->
 
-> **Three context tickets, not two.** Every Epic carries three planning
-> artifacts as linked GitHub sub-issues: PRD (`context::prd`), Tech Spec
-> (`context::tech-spec`), and Acceptance Spec
-> (`context::acceptance-spec`). The Acceptance Spec 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 Spec output and
-> the runtime gates (start gate, finalize reconciler) honour the
-> waiver — the spec ticket itself need not be authored or approved when
-> the waiver is set. See [SDLC § Acceptance Spec — the third planning
-> context ticket](../../docs/SDLC.md#acceptance-spec--the-third-planning-context-ticket)
+> **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.
 
 <!-- separator: adjacent blockquotes -->
@@ -495,11 +511,11 @@ for the scoring logic.
 > 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]/prd.md`, `temp/epic-[Epic_ID]/techspec.md`,
+> `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/prd.md` or the legacy
+> 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
@@ -523,18 +539,18 @@ for the scoring logic.
    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 PRD, Tech
+   `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]/prd.md`,
+   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 PRD / Tech
+   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 PRD, Tech Spec, and
+   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.
@@ -546,59 +562,55 @@ for the scoring logic.
    (`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-spec` flag persists the third planning ticket
-   (`context::acceptance-spec`) alongside the PRD and Tech Spec; the
-   persist half fails loudly if any file is missing or empty. Omit
-   `--acceptance-spec` only when the Epic carries the `acceptance::n-a`
-   waiver label.
+   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 (three context tickets)
+   # Normal planning (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-planning (--force overwrites the three context tickets IN PLACE —
-   # same PRD / Tech Spec / Acceptance Spec issue numbers, refreshed bodies,
-   # tickets kept open, one regeneration audit comment each. Child Story
-   # tickets are still close-and-recreate at decomposition time.)
+   # 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] \
-     --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 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
    ```
 
 4. **Verification and review routing**:
-   - Verify that the PRD, Technical Specification, and (when not waived)
-     Acceptance Specification have been posted as linked issues under
-     the Epic.
+   - 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
-       generated PRD, Tech Spec, and Acceptance Spec on GitHub. Approval is
-       the user's verbal OK in this session — the three context tickets stay
-       **open** through delivery and are closed automatically by
-       `/deliver` when the Epic PR opens. Do NOT proceed
+       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. The
-       > three context tickets stay **open** through delivery as usual; only
+       > 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
@@ -612,8 +624,8 @@ for the scoring logic.
        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 issue
-   is created, `epic-plan-spec.js` runs
+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
@@ -628,14 +640,14 @@ for the scoring logic.
      reference the Architect inherited from drift-stale docs.
 
    When ≥1 stale reference is detected, a `spec-freshness` structured
-   comment is upserted on the Tech Spec issue listing each citation
+   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 Tech Spec
-   issue's `spec-freshness` comment and correct the cited spec body
+   `⚠️ 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
@@ -716,8 +728,8 @@ node .agents/scripts/epic-plan-spec-validate.js \
 
   **STOP** on a non-zero exit: do not advance to Phase 8. Re-author the Tech
   Spec (re-run the Phase 7 spec-author step) or add a `## Delivery Slicing`
-  section to the Tech Spec issue body by hand, then re-run the gate until it
-  exits 0.
+  section by hand (to the temp spec file and the Epic body's tech-spec
+  section), then re-run the gate until it exits 0.
 
 ## Phase 8: Work Breakdown Decomposition
 
@@ -735,7 +747,7 @@ node .agents/scripts/epic-plan-spec-validate.js \
 > **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
-> Acceptance Spec context ticket at close time. See
+> Epic body's `## Acceptance Table` section at close time. See
 > [`.agents/instructions.md` § 5.D](../../instructions.md) for the full
 > contract.
 
@@ -750,8 +762,9 @@ node .agents/scripts/epic-plan-spec-validate.js \
    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` (PRD body, Tech Spec
-   body, risk heuristics, `maxTickets` cap, `contextMode`), applies its
+   `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.
@@ -781,8 +794,9 @@ node .agents/scripts/epic-plan-spec-validate.js \
    [`epic-plan-consolidate`](../../skills/core/epic-plan-consolidate/SKILL.md)
    skill with `[Epic_ID]` as input. This is a **separate critic pass with
    fresh context** (not a self-review appended to the author skill): it reads
-   the draft array plus the PRD / Tech Spec, reconciles the draft against the
-   Tech Spec `## Delivery Slicing` target, and emits a **consolidated**
+   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
@@ -838,8 +852,9 @@ node .agents/scripts/epic-plan-spec-validate.js \
    reachability critic (8.4) and **before** the persist call below, activate the
    [`epic-plan-premortem`](../../skills/core/epic-plan-premortem/SKILL.md)
    skill with `[Epic_ID]` as input. This is a **fresh-context critic** sibling
-   to `epic-plan-consolidate`: it reads the drafted `tickets.json`, the PRD /
-   Tech Spec, **and the actual cited code surfaces** (the files each Story's
+   to `epic-plan-consolidate`: 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)
@@ -1032,8 +1047,8 @@ forcing the walkthrough.
 
 Activate the
 [`core/knowledge-transfer`](../../skills/core/knowledge-transfer/SKILL.md) skill
-with the **plan** as the subject — the Epic body, the linked PRD / Tech Spec
-context tickets, the decomposition (Stories with inline
+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).

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

@@ -13,7 +13,7 @@ description:
 [`/deliver`](deliver-stories.md). Use it for a Story that is **not**
 attached to an Epic — refactors carved out of closed Epics, framework
 maintenance, or any work small enough that the Epic-Centric ceremony
-(PRD + Tech Spec + decomposition + dispatch manifest + cascade) would be
+(sectioned Epic body + decomposition + dispatch manifest + cascade) would be
 overhead rather than help.
 
 ```text

package/.agents/workflows/helpers/worktree-lifecycle.md

@@ -353,7 +353,7 @@ Human reviewers should **keep using the main checkout** — not a worktree:
   the main checkout, not in any per-story worktree.
 - Opening a worktree in an IDE can mislead: the working directory looks like the
   main repo but carries a different HEAD. The main checkout is the canonical
-  place to read PRDs, Tech Specs, and run the `helpers/code-review.md`
+  place to read Epic planning bodies and run the `helpers/code-review.md`
   procedure.
 - `git worktree list --porcelain` on the main checkout enumerates any still
   in-flight story worktrees if you need to inspect one — prefer read-only

package/.agents/workflows/plan.md

@@ -2,8 +2,8 @@
 description:
   Unified planning entry point. Routes a seed idea (via scope triage) or an
   existing Epic ID to the right planning path — the full Epic pipeline
-  (PRD, Tech Spec, Acceptance Spec, decomposition) or the standalone-Story
-  authoring path — and absorbs every planning flag.
+  (sectioned Epic body: Tech Spec + Acceptance Table, then decomposition)
+  or the standalone-Story authoring path — and absorbs every planning flag.
 ---
 
 # /plan [Epic ID] | --idea "<seed>" | --from-notes <path>
@@ -14,8 +14,8 @@ Router. `/plan` owns argument parsing and path selection only — all phase
 content lives in the two path helpers:
 
 - [`helpers/plan-epic.md`](helpers/plan-epic.md) — the full Epic planning
-  pipeline (PRD, Tech Spec, Acceptance Spec, work breakdown, healthcheck,
-  handoff).
+  pipeline (Tech Spec + Acceptance Table folded into the Epic body, work
+  breakdown, healthcheck, handoff).
 - [`helpers/plan-story.md`](helpers/plan-story.md) — the standalone-Story
   authoring path (context envelope → host-LLM draft → HITL → issue create).
 
@@ -93,10 +93,10 @@ without waiting for operator input:
    forces a review (`planningRisk.requiresReview === true`, or the operator
    also passed `--force-review`),
    [`helpers/plan-epic.md`](helpers/plan-epic.md) Phase 7 STOPs for operator
-   approval of the PRD / Tech Spec / Acceptance Spec before decomposition.
-   Under `--yes` this review auto-proceeds straight to Phase 8 — the three
-   context tickets stay **open** through delivery exactly as on the low-risk
-   auto-proceed path.
+   approval of the updated Epic body (its Tech Spec sections and
+   `## Acceptance Table`) before decomposition.
+   Under `--yes` this review auto-proceeds straight to Phase 8 exactly as
+   on the low-risk auto-proceed path.
 
 **Composition.** `--yes` is orthogonal to the other planning flags and
 composes cleanly:

package/.agents/workflows/qa-assist.md

@@ -226,7 +226,8 @@ every decision to the shared core helpers; never re-derive them in prose.
 
 3. **Hydrate the QA context** to locate code precisely, via
    [`qa-context-hydrator.js`](../scripts/lib/qa/qa-context-hydrator.js) — it
-   resolves the Epic/Feature context tickets, the feature-file set, the surface
+   resolves the Epic (whose body carries the planning sections), the
+   feature-file set, the surface
    map, and recent git log:
 
    ```js

package/docs/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.82.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.81.0...mandrel-v1.82.0) (2026-07-04)
+
+
+### Added
+
+* **decomposer:** add soft envelope-floor guidance to sizing prompt (refs [#4313](https://github.com/dsj1984/mandrel/issues/4313)) ([#4321](https://github.com/dsj1984/mandrel/issues/4321)) ([e95c9e4](https://github.com/dsj1984/mandrel/commit/e95c9e4b39b7549f2f83ee104e19a9824f9bab00))
+* **epic-plan-spec:** key Acceptance Spec Outcomes to Epic AC bullets (refs [#4315](https://github.com/dsj1984/mandrel/issues/4315)) ([#4323](https://github.com/dsj1984/mandrel/issues/4323)) ([4d4103c](https://github.com/dsj1984/mandrel/commit/4d4103c79500e5704b1fa79e70f6efb985e06994))
+* **plan:** recalibrate Delivery Slicing to a ceiling, not a target (refs [#4311](https://github.com/dsj1984/mandrel/issues/4311)) ([#4317](https://github.com/dsj1984/mandrel/issues/4317)) ([b37596b](https://github.com/dsj1984/mandrel/commit/b37596b8f739da52f568cb025b84ada84ce90355))
+* **ticket-validator-sizing:** add merge-candidate under-size soft finding (refs [#4312](https://github.com/dsj1984/mandrel/issues/4312)) ([#4319](https://github.com/dsj1984/mandrel/issues/4319)) ([2b84e49](https://github.com/dsj1984/mandrel/commit/2b84e49022f9745549cb02a1237d24ab194af92c))
+
+
+### Fixed
+
+* retire the context-ticket classes: fold Tech Spec and Acceptance Spec into the sectioned Epic body ([#4324](https://github.com/dsj1984/mandrel/issues/4324)) ([#4325](https://github.com/dsj1984/mandrel/issues/4325)) ([f8cfec7](https://github.com/dsj1984/mandrel/commit/f8cfec79f1aa59fc86c51e9ced6dda2bd06f2cb3))
+
+
+### Changed
+
+* **epic-plan-spec:** open Tech Spec with Delivery Slicing, drop Epic-context restatement (refs [#4316](https://github.com/dsj1984/mandrel/issues/4316)) ([#4320](https://github.com/dsj1984/mandrel/issues/4320)) ([b20d10a](https://github.com/dsj1984/mandrel/commit/b20d10a2e61b1940ebffe0bc595d3b6bfedec604))
+* fold the PRD into the Epic body and retire the context::prd artifact class ([#4314](https://github.com/dsj1984/mandrel/issues/4314)) ([#4322](https://github.com/dsj1984/mandrel/issues/4322)) ([9c9bc7d](https://github.com/dsj1984/mandrel/commit/9c9bc7deb19ce04de1aebcaefb2eeebf949f61d5))
+
+## [1.81.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.80.0...mandrel-v1.81.0) (2026-07-01)
+
+
+### Fixed
+
+* **baselines:** add one-shot BUNDLE_SIZE_REFRESH acknowledge for the bundle-size ratchet ([#4309](https://github.com/dsj1984/mandrel/issues/4309)) ([bc466b9](https://github.com/dsj1984/mandrel/commit/bc466b98f6c7521c3a24bbb4d93ee5169c163839))
+
 ## [1.80.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.79.0...mandrel-v1.80.0) (2026-07-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.80.0",
+  "version": "1.82.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",

package/.agents/scripts/lib/issue-link-parser.js

@@ -1,74 +0,0 @@
-/**
- * Parse PRD / Tech-Spec / Acceptance-Spec references from a GitHub epic body.
- * Extracted from providers/github.js so link-parsing is not mixed with HTTP
- * transport.
- *
- * Expected markdown conventions in an epic body (case-insensitive, tolerant
- * of the `- [ ]` / `- [x]` checkbox prefix that `epic-plan-spec.js` emits in
- * the `## Planning Artifacts` section):
- *   - "PRD: #42"  or  "prd #42"
- *   - "Tech Spec: #43"  /  "Technical Spec: #43"  /  "tech-spec: #43"
- *   - "Acceptance Spec: #44"  /  "acceptance-spec: #44"  /  "accept spec: #44"
- *
- * Story #2091 added the `acceptanceSpec` slot so the
- * `closePlanningArtifacts()` cascade in `epic-deliver-finalize.js` can close
- * the `context::acceptance-spec` ticket Epic #2001 introduces alongside the
- * existing PRD / Tech-Spec pair.
- *
- * Story #3848: regexes are now scoped to the `## Planning Artifacts` section
- * only. Prose elsewhere in the body (e.g. bundled-follow-up notes that
- * mention a foreign Epic's spec ticket by number) can no longer collide with
- * the machine-managed list items.
- */
-
-const PRD_RE = /(?:PRD|prd)[:\s]+#(\d+)/;
-const TECH_SPEC_RE = /(?:Tech Spec|tech.?spec|technical.?spec)[:\s]+#(\d+)/i;
-const ACCEPTANCE_SPEC_RE =
-  /(?:Acceptance Spec|acceptance.?spec|accept.?spec)[:\s]+#(\d+)/i;
-
-/**
- * Extract the `## Planning Artifacts` section text from an Epic body.
- * Returns the slice from just after the heading line to the next `##`-level
- * heading (exclusive), or to end-of-string when no following heading is
- * present. Returns an empty string when the section is absent.
- *
- * @param {string} body
- * @returns {string}
- */
-function extractPlanningArtifactsSection(body) {
-  // Step 1: locate the heading.
-  const startMatch = body.match(/^##\s+Planning Artifacts[^\n]*/m);
-  if (!startMatch) return '';
-  // Step 2: slice from just after the heading to the next ## heading (or EOB).
-  const afterHeading = body.slice(startMatch.index + startMatch[0].length);
-  const nextHeadingMatch = afterHeading.match(/\n##\s/);
-  return nextHeadingMatch
-    ? afterHeading.slice(0, nextHeadingMatch.index)
-    : afterHeading;
-}
-
-/**
- * @param {string|null|undefined} body
- * @returns {{ prd: number|null, techSpec: number|null, acceptanceSpec: number|null }}
- */
-export function parseLinkedIssues(body) {
-  const result = { prd: null, techSpec: null, acceptanceSpec: null };
-  if (typeof body !== 'string' || body.length === 0) return result;
-
-  // Scope all regex matching to the canonical Planning Artifacts section so
-  // prose references elsewhere in the body do not shadow the machine-managed
-  // list items. When the section is absent every slot stays null — the caller
-  // (plan-epic.js) treats null as "not yet linked" and creates fresh tickets.
-  const section = extractPlanningArtifactsSection(body);
-  if (section.length === 0) return result;
-
-  const prdMatch = section.match(PRD_RE);
-  if (prdMatch) result.prd = Number.parseInt(prdMatch[1], 10);
-  const specMatch = section.match(TECH_SPEC_RE);
-  if (specMatch) result.techSpec = Number.parseInt(specMatch[1], 10);
-  const acceptanceMatch = section.match(ACCEPTANCE_SPEC_RE);
-  if (acceptanceMatch) {
-    result.acceptanceSpec = Number.parseInt(acceptanceMatch[1], 10);
-  }
-  return result;
-}