mandrel 1.81.0 → 1.83.0

package/.agents/skills/core/epic-plan-premortem/examples.md

@@ -0,0 +1,53 @@
+# epic-plan-premortem — examples & extended rationale
+
+Read this file on demand. The SKILL.md carries the operating contract (Policy
+Capsule, Inputs / Outputs, Procedure, Constraints); this file carries the
+extended rationale behind the pre-mortem critic — why it is a separate,
+fresh-context, code-reading pass and how its three predicted-rework finding
+classes differ from the structural gates.
+
+## Why a separate fresh-context code-reading critic
+
+This Skill acts as a Senior Engineer + Architect in the role of a
+**fresh-context pre-mortem critic**. It is deliberately *separate* from
+`epic-plan-decompose-author` (the generator) and from `epic-plan-consolidate`
+(the scope-preserving merge critic): a same-pass self-critique is the weak mode
+this is built to escape. The generator maps Epic capabilities to Stories
+against the spec text; this critic opens the **actual cited code** and asks "if
+I tried to deliver this exact backlog, where would it rework?" — before any
+GitHub write makes the rework expensive.
+
+**You MUST read the actual cited code surfaces.** This is the load-bearing
+difference between this critic and the structural file-assumption gate: that
+gate proves a path **exists** (or does not); this critic reads what the file
+actually **contains**. A pre-mortem that did not open the cited files has not
+run.
+
+## Not scope-preserving (unlike consolidation)
+
+Unlike `epic-plan-consolidate` (merge-and-rewire only), this critic MAY
+recommend splitting an under-specified Story, tightening or rewording an
+acceptance criterion, or flagging an over-specified Story — because it only
+*recommends* in a report; it never applies the change itself. The conservation
+invariant belongs to consolidation; this pass is deliberately a separate,
+additive-recommendation lens. It never writes to GitHub, never persists
+`tickets.json`, and never flips a label — re-authoring on its findings is the
+author skill's job (the workflow re-runs `epic-plan-decompose-author` on the
+report before the persist call).
+
+## The three predicted-rework finding classes
+
+Hunt for the three classes the structural gates cannot catch:
+
+1. **Unverifiable acceptance criteria** — an AC no `verify[]` command or
+   readable code state can prove. Recommend a concrete verify command or a
+   reworded, checkable AC.
+2. **Over- or under-specified Stories** — a Story whose `acceptance[]` is far
+   broader or narrower than its `changes[]` footprint and the cited code
+   support. Recommend a split (under-specified: one Story doing the work of
+   several) or a tightening.
+3. **Semantically-wrong assumptions** — the cited file exists (so the
+   file-assumption gate passes) but does not contain the seam / export /
+   function / data shape the Story assumes — the file-assumption gate passes,
+   the work would still rework. Recommend the corrected target or an explicit
+   "create the seam first" Story.

package/.agents/skills/core/epic-plan-spec-author/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: epic-plan-spec-author
 description: >-
-  Author the PRD, Tech Spec, Acceptance Spec markdown, and risk-verdict JSON
+  Author the Tech Spec, Acceptance Table markdown, and risk-verdict JSON
   for an Epic from the planner authoring context emitted by
   `epic-plan-spec.js --emit-context`. Use during Phase 7 of `/plan` when
-  the host LLM needs to write the four artifacts before `epic-plan-spec.js`
-  persists them.
+  the host LLM needs to write the three artifacts before `epic-plan-spec.js`
+  folds them into the Epic body's managed sections.
 allowed_tools:
   - Read
   - Write
@@ -14,13 +14,30 @@ allowed_tools:
 
 # epic-plan-spec-author
 
+> **PRD retired (Story #4314).** The `context::prd` PRD artifact class was
+> retired; this Skill no longer authors `prd.md`. Its one novel section —
+> User Stories — now lives inline in the Epic body under a `## User Stories`
+> heading, which is the requirements input. Both the Tech Spec and the
+> Acceptance Spec now consume the Epic body directly (Context / Goal / Scope /
+> User Stories) rather than a paraphrased PRD.
+>
+> **Context tickets retired (Story #4324).** The `context::tech-spec` /
+> `context::acceptance-spec` ticket classes are retired too. The artifacts
+> this Skill authors still land in `temp/epic-<Epic_ID>/` under the same
+> filenames, but the persist half folds them into **managed sections of the
+> Epic body** — the `## Delivery Slicing`-led Tech Spec sections and the
+> `## Acceptance Table` AC-ID table — instead of creating separate tickets.
+> On a re-plan, the Epic body's existing sections are the previous-spec
+> input (that is how AC IDs stay stable across re-plans).
+
 ## Policy Capsule
 
 - Run only during `/plan` Phase 7, after `epic-plan-spec.js --emit-context` has written `temp/epic-<Epic_ID>/planner-context.json`; fail loudly if the file is missing rather than fabricating context.
-- Write exactly four artifacts and only inside `temp/epic-<Epic_ID>/`: `prd.md`, `techspec.md`, `risk-verdict.json`, `acceptance-spec.md`. All four MUST exist on disk before returning.
-- Start each markdown artifact at the correct `##` heading (PRD → `## Overview`, Tech Spec → `## Technical Overview`, Acceptance Spec → `## Acceptance Criteria`) — never emit a top-level `#` heading. `risk-verdict.json` is raw JSON conforming to `.agents/schemas/risk-verdict.schema.json`.
-- Judge risk from what the change *does* (the PRD / Tech Spec you just wrote), never from keyword presence — "out of scope: billing" is not a billing change; "rotate the credential vault" is high-risk even without a security keyword.
-- The Tech Spec MUST carry a `## Delivery Slicing` section proposing how the PRD's enumerated capabilities cluster into N shippable Stories — the intentional target the Phase 8 consolidation pass (`epic-plan-consolidate`) reconciles the decomposer draft against. Do NOT coarsen the PRD enumeration to produce it; the grouping recommendation is the granularity lever.
+- Write exactly three artifacts and only inside `temp/epic-<Epic_ID>/`: `techspec.md`, `risk-verdict.json`, `acceptance-spec.md`. All three MUST exist on disk before returning.
+- Start each markdown artifact at the correct `##` heading (Tech Spec → `## Delivery Slicing`, Acceptance Spec → `## Acceptance Table` — never the Epic's own `## Acceptance Criteria` heading, which stays the ideation bullets) — never emit a top-level `#` heading. `risk-verdict.json` is raw JSON conforming to `.agents/schemas/risk-verdict.schema.json`.
+- The Tech Spec MUST open with `## Delivery Slicing` and MUST NOT restate the Epic's Context, Goal, or Scope — your output lands as sections of the same Epic body, which travels into every downstream story agent's prompt, so any restatement is duplication and a drift risk. A `## Technical Overview` section is optional and, when present, is a 2–3 sentence orientation of the *technical approach* only (which subsystems are touched and reused), never a re-narration of the problem statement, goals, or scope.
+- Judge risk from what the change *does* (the Epic body / Tech Spec you just wrote), never from keyword presence — "out of scope: billing" is not a billing change; "rotate the credential vault" is high-risk even without a security keyword.
+- The Tech Spec MUST carry a `## Delivery Slicing` section proposing how the Epic's enumerated capabilities cluster into N shippable Stories — the intentional grouping the Phase 8 consolidation pass (`epic-plan-consolidate`) reconciles the decomposer draft against. The proposed count is a **ceiling, not a target**: consolidation may merge below it when slices form dependent single-consumer chains, but never splits above it. Mark a slice "Independent? No" only with a one-line justification (parallelism, risk isolation, or delivery-envelope pressure); an unjustified dependent single-consumer slice folds into its consumer. Do NOT coarsen the Epic enumeration to produce it; the grouping recommendation is the granularity lever.
 - Cite real module / file names from `codebaseSnapshot.files` and `codebaseSnapshot.signatures` before citing docs-only names; flag any cited path that is missing from the snapshot with a `<!-- DRIFT -->` callout.
 - Assign stable AC IDs of the form `AC-<n>` in document order; reuse existing IDs across re-plans when Outcome wording is materially unchanged and tag every row's `Disposition` with one of `new | updated | unchanged`.
 - Render the AC table with the canonical columns `AC ID | Outcome | Feature File | Scenario | Disposition`; when `bddScenarios` is non-empty, run `findBestScenarioMatch` per AC and annotate matched rows with `<file>:L<line>` (never tag a covered outcome as `new`).
@@ -31,22 +48,21 @@ allowed_tools:
 
 ## Role
 
-Technical Product Manager + Engineering Architect + Risk Assessor +
-Acceptance Engineer (four personas, one Skill — the PRD persona produces the
-requirements; the Architect persona consumes the PRD to produce the Tech
-Spec; the Risk Assessor judges the change the two specs describe to produce
-the risk verdict; the Acceptance Engineer consumes all of them to produce
-the Acceptance Spec).
+Engineering Architect + Risk Assessor + Acceptance Engineer (three authoring
+roles, one Skill — the Architect persona consumes the Epic body to produce the
+Tech Spec; the Risk Assessor judges the change the Epic and Tech Spec describe
+to produce the risk verdict; the Acceptance Engineer consumes the Epic body and
+the Tech Spec to produce the Acceptance Spec).
 
 ## When to use
 
 `/plan` Phase 7, immediately after `epic-plan-spec.js --emit-context`
 writes `temp/epic-<Epic_ID>/planner-context.json`. This Skill replaces the
-inline "Author the PRD" / "Author the Tech Spec" steps from the legacy
-workflow body — the calling workflow dispatches this Skill via the `Skill`
-tool, supplies the Epic ID, and on completion has `temp/epic-<Epic_ID>/prd.md`,
-`temp/epic-<Epic_ID>/techspec.md`, `temp/epic-<Epic_ID>/risk-verdict.json`,
-and `temp/epic-<Epic_ID>/acceptance-spec.md` ready for the persist half of
+inline "Author the Tech Spec" step from the legacy workflow body — the calling
+workflow dispatches this Skill via the `Skill` tool, supplies the Epic ID, and
+on completion has `temp/epic-<Epic_ID>/techspec.md`,
+`temp/epic-<Epic_ID>/risk-verdict.json`, and
+`temp/epic-<Epic_ID>/acceptance-spec.md` ready for the persist half of
 the script.
 
 ## Inputs
@@ -87,7 +103,7 @@ reads:
         Treat each as a likely drift signal: confirm the path exists (it may
         have been dropped by truncation) or mark it net-new explicitly in
         the spec so the post-author freshness gate does not flag it.
-  - `systemPrompts.prd`, `systemPrompts.techSpec`, and
+  - `systemPrompts.techSpec` and
     `systemPrompts.acceptanceSpec` — left in the envelope as a backstop;
     this Skill's own body below carries the authoritative versions and is
     the source of truth going forward
@@ -104,29 +120,28 @@ reads:
     means the project has not adopted BDD; degrade silently and proceed
     as before. Non-empty means the Acceptance Engineer step MUST run
     `findBestScenarioMatch` for each planned AC and annotate the
-    Disposition column accordingly (see Step 5).
+    Disposition column accordingly (see Step 4).
   Planning risk is **not** an input — this Skill authors it. The risk
-  verdict (`risk-verdict.json`, Step 4 below) is the fourth planning
-  artifact; the persist half validates it against
+  verdict (`risk-verdict.json`, Step 3 below) is one of the three planning
+  artifacts; the persist half validates it against
   `.agents/schemas/risk-verdict.schema.json` and derives the deterministic
   `planningRisk` envelope (`deriveRiskEnvelope`) that drives gate routing
   and the acceptance disposition (Epic #3865).
 
 ## Outputs
 
-- `temp/epic-<Epic_ID>/prd.md` — PRD markdown starting with `## Overview`
-  (no `<h1>`).
 - `temp/epic-<Epic_ID>/techspec.md` — Tech Spec markdown starting with
-  `## Technical Overview` (no `<h1>`).
+  `## Delivery Slicing` (no `<h1>`; an optional 2–3 sentence
+  `## Technical Overview` may follow, never restating Epic context).
 - `temp/epic-<Epic_ID>/risk-verdict.json` — planner risk verdict JSON
   conforming to `.agents/schemas/risk-verdict.schema.json`:
   `{ axes: [{ axis, level, rationale }], summary }`.
 - `temp/epic-<Epic_ID>/acceptance-spec.md` — Acceptance Spec markdown
-  starting with `## Acceptance Criteria` (no `<h1>`).
+  starting with `## Acceptance Table` (no `<h1>`).
 
-All four files MUST exist on disk before this Skill returns control. The
+All three files MUST exist on disk before this Skill returns control. The
 caller will invoke
-`epic-plan-spec.js --epic <Epic_ID> --prd ... --techspec ... --risk-verdict ... --acceptance-spec ...`
+`epic-plan-spec.js --epic <Epic_ID> --tech-spec ... --risk-verdict ... --acceptance-table ...`
 next, and the persist half will fail loudly if any file is missing, empty,
 or (for the verdict) schema-invalid.
 
@@ -135,136 +150,85 @@ or (for the verdict) schema-invalid.
 ### Step 1 — Load the context
 
 Read `temp/epic-<Epic_ID>/planner-context.json` with the `Read` tool. Pull
-the Epic title, body (or body summary), the `docsContext` items, and (for
-reference) the two system prompts.
-
-### Step 2 — Author the PRD (Technical Product Manager persona)
-
-Apply the PRD system prompt below to the Epic title + body. Write the PRD
-to `temp/epic-<Epic_ID>/prd.md` using the `Write` tool. The PRD MUST:
+the Epic title, body (or body summary, including the Epic's `## User Stories`
+section), the `docsContext` items, and (for reference) the two system prompts.
 
-- Start with `## Overview` — never a top-level `#` heading.
-- Contain four sections: **Context & Goals**, **User Stories**,
-  **Acceptance Criteria**, **Out of Scope**.
-- Be valid Markdown — no fenced code blocks of prose, no smart quotes that
-  break the issue body renderer.
+### Step 2 — Author the Tech Spec (Engineering Architect persona)
 
-#### PRD system prompt (authoritative)
-
-```text
-You are an expert Technical Product Manager.
-Your job is to convert a high-level Epic description into a structured Product Requirements Document (PRD).
-
-The PRD should outline:
-1. Context & Goals
-2. User Stories
-3. Acceptance Criteria
-4. Out of Scope
-
-CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Start with ## Overview.
-- Format requirements clearly with bullet points and bold text where appropriate.
-```
-
-### Step 3 — Author the Tech Spec (Engineering Architect persona)
-
-Apply the Tech Spec system prompt below to the PRD just written, the
+Apply the Tech Spec system prompt below to the Epic body (Context / Goal /
+Scope / User Stories), the
 `docsContext` items, and the `codebaseSnapshot` envelope (so the spec is
 grounded in the actual codebase, not hallucinated patterns). Cite module
 and file names from `codebaseSnapshot.files` / `codebaseSnapshot.signatures`
 before reaching for names that appear only in the documentation. Write to
 `temp/epic-<Epic_ID>/techspec.md`. The Tech Spec MUST:
 
-- Start with `## Technical Overview` — never a top-level `#` heading.
+- **Open with `## Delivery Slicing`** (see below) — never a top-level `#`
+  heading, and never an Epic-context recap. The Delivery Slicing section is
+  the primary input to Phase 8 consolidation, so author it first and hang the
+  rest of the spec off it.
+- **Do NOT restate the Epic's Context, Goal, or Scope.** The Epic body always
+  travels alongside the Tech Spec into every downstream story agent's prompt,
+  so restating the problem statement, goals, or scope is pure duplication
+  (~300–500 tokens per Epic) and a drift risk. A `## Technical Overview`
+  section is **optional**; when you include one, cap it at 2–3 sentences that
+  orient the reader on the *technical approach* only (which subsystems are
+  touched and reused) — never re-narrate the problem, goals, or scope.
 - Cover Architecture & Design, Data Models (if any), API Changes (if any),
   Core Components, Security & Privacy Considerations.
-- Include a **`## Delivery Slicing`** section (see below) proposing how the
-  PRD's enumerated capabilities cluster into N shippable Stories.
 - Cite the source files / modules it touches by relative path. Avoid
   pseudocode — name real symbols when proposing edits.
 
-#### Delivery Slicing section (authoritative target for Phase 8 consolidation)
+#### Delivery Slicing section (authoritative ceiling for Phase 8 consolidation)
 
-The Tech Spec MUST carry a `## Delivery Slicing` section in which the Architect
-— who holds the full design — proposes how the PRD's enumerated capabilities
-**cluster into N shippable Stories**. This section is the intentional target
-grouping the Phase 8 consolidation pass
+The Tech Spec MUST carry a `## Delivery Slicing` section proposing how the
+Epic's enumerated capabilities **cluster into N shippable Stories** — the
+intentional grouping the Phase 8 consolidation pass
 ([`epic-plan-consolidate`](../epic-plan-consolidate/SKILL.md)) reconciles the
-decomposer's draft against before any GitHub write. Without it, the decompose
-phase maps PRD capabilities to Stories ~1:1 and cannot produce a coarser,
-holistic plan; with it, the consolidation critic has a well-defined target
-instead of a guess.
-
-**Write the Delivery Slicing section before any other section — it is the
-primary input to Phase 8 consolidation.** Author it first so the rest of the
-spec (Core Components, API Changes, Data Models) hangs off a deliberate
-slicing decision rather than being reverse-engineered into one at the end.
-Drafting it last is exactly how the model omits it under the weight of the
-other sections.
-
-Author the section as a table — one row per proposed slice — naming the
-capability cluster each slice would deliver, what ships in it, and whether it
-can ship independently. Use **noun phrases** for slice names ("Foundation",
-"Transport seam", "Send helper") so they map cleanly onto Feature titles in the
-resulting decomposition — never verb phrases ("Add transport") or file names
-("`sender.ts`"). Do **not** coarsen the PRD's capability enumeration to produce
-the slicing: the granularity lever is *this* grouping recommendation, not a
-dumbed-down PRD.
-
-**What "Independent?" means:** can this slice ship to production and provide
-value *without the next slice landing*? A `Yes` slice is releasable on its own;
-a `No` slice only becomes valuable once a later slice lands on top of it.
-
-Worked example:
-
-```text
-## Delivery Slicing
-
-Proposed shippable slices (consolidation target for Phase 8):
-
-| Slice          | What ships                                              | Independent? |
-| -------------- | ------------------------------------------------------ | ------------ |
-| Foundation     | Config schema, types, and the no-op default path       | Yes          |
-| Transport seam | The pluggable transport interface + in-memory adapter  | Yes          |
-| Send helper    | The send() helper built on the transport seam          | No           |
-
-- **Foundation** folds PRD capabilities "config surface" + "type model" — they
-  share a reason to exist and ship as one reviewable PR.
-- **Transport seam** is the pluggable boundary; it provides value on its own
-  (in-memory adapter is usable for tests) so it is independently shippable.
-- **Send helper** depends on the transport seam landing first, so it is *not*
-  independent — it is valuable only once Transport seam ships.
-```
-
-The consolidation pass degrades gracefully when this section is absent (it
-falls back to cohesion + single-Story-Feature rules only), so authoring it is
-how the Architect steers the decomposition toward fewer, right-sized Stories.
+decomposer draft against before any GitHub write. Author it as a table (one row
+per slice: `Slice | What ships | Independent?`), using **noun-phrase** slice
+names, and **write it before any other section** — it is the primary input to
+consolidation and the section the model most often omits when it drafts it last.
+
+- **The count is a ceiling, not a target.** Consolidation may merge below it
+  (dependent single-consumer chains) but never splits above it.
+- **"Independent?"** answers: can this slice ship to production and provide
+  value without the next slice landing? Mark a slice `No` only with a one-line
+  justification (parallelism, risk isolation, or delivery-envelope pressure);
+  an unjustified dependent single-consumer slice folds into its consumer.
+- Do **not** coarsen the Epic's capability enumeration to produce the slicing;
+  the grouping recommendation is the granularity lever.
+
+> **Read [`examples.md`](./examples.md) on demand** for the worked Delivery
+> Slicing table and the extended rationale behind these rules (what
+> "Independent?" means, why an unjustified `No` slice is a smell, and how the
+> consolidation pass degrades gracefully when the section is absent).
 
 #### Tech Spec system prompt (authoritative)
 
 ```text
 You are an expert Engineering Architect.
-Your job is to convert a PRD into a Technical Specification for implementation.
+Your job is to convert an Epic into a Technical Specification for implementation.
 
 The Tech Spec should outline:
-1. Architecture & Design
-2. Data Models (if any)
-3. API Changes (if any)
-4. Core Components
-5. Security & Privacy Considerations
-6. Delivery Slicing — propose how the PRD's enumerated capabilities cluster into N shippable Stories (the consolidation target for Phase 8). One bullet per proposed Story, naming the capability cluster it delivers. Do NOT coarsen the PRD enumeration to produce this; the grouping recommendation is the granularity lever.
+1. Delivery Slicing — propose how the Epic's enumerated capabilities cluster into shippable Stories. This count is a CEILING, not a target: the Phase 8 consolidation pass may merge below your proposed count when slices form dependent single-consumer chains, but never splits above it. Do NOT coarsen the Epic enumeration to produce this; the grouping recommendation is the granularity lever.
+2. Architecture & Design
+3. Data Models (if any)
+4. API Changes (if any)
+5. Core Components
+6. Security & Privacy Considerations
 
 CRITICAL REQUIREMENTS:
 - Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Start with ## Technical Overview.
+- Do not use top-level <h1> (# ) tags. Open the document with the `## Delivery Slicing` section — it is the primary input to Phase 8 consolidation, so author it first and hang the rest of the spec off it.
+- Do NOT restate the Epic's Context, Goal, or Scope — your output lands as sections of the same Epic body, which travels into every downstream story agent's prompt, so any restatement is pure duplication and a drift risk. If a brief technical orientation is genuinely useful, add an optional `## Technical Overview` of no more than 2–3 sentences that names the *technical approach* only (which subsystems are touched and reused); never re-narrate the problem statement, goals, or scope.
 - Format architectural decisions clearly with bullet points.
-- Include a `## Delivery Slicing` section proposing the shippable-Story grouping. Write the Delivery Slicing section before any other section — it is the primary input to Phase 8 consolidation. Author it as a markdown table with columns `Slice | What ships | Independent?`, using noun-phrase slice names (e.g. "Foundation", "Transport seam", "Send helper") that map onto Feature titles. "Independent?" answers: can this slice ship to production and provide value without the next slice landing?
+- Author the `## Delivery Slicing` section as a markdown table with columns `Slice | What ships | Independent?`, using noun-phrase slice names (e.g. "Foundation", "Transport seam", "Send helper") that map onto Feature titles. "Independent?" answers: can this slice ship to production and provide value without the next slice landing? A slice you mark "Independent? No" MUST carry a one-line justification (parallelism, risk isolation, or delivery-envelope pressure); an unjustified dependent single-consumer slice folds into its consumer by default rather than shipping as its own Story.
 ```
 
-### Step 4 — Author the risk verdict (Risk Assessor persona)
+### Step 3 — Author the risk verdict (Risk Assessor persona)
 
-Judge the change described by the PRD and Tech Spec you just wrote —
+Judge the change described by the Epic body and Tech Spec you just wrote —
 grounded in `codebaseSnapshot` where it helps — and write
 `temp/epic-<Epic_ID>/risk-verdict.json` with the `Write` tool. The file
 MUST be valid JSON conforming to
@@ -290,11 +254,11 @@ Axis vocabulary (fixed — the schema rejects anything else):
 Authoring rules:
 
 - Include an axis only when the change **genuinely exercises it** — judge
-  what the Epic *does*, not which words appear in it. A PRD that says
+  what the Epic *does*, not which words appear in it. An Epic that says
   "out of scope: billing" carries no `billing` axis; an Epic that rotates
   a credential vault carries `security` even if the word never appears.
 - `level` reflects blast radius and reversibility of *this* change on
-  *that* axis. `rationale` cites the PRD / Tech Spec section or code
+  *that* axis. `rationale` cites the Epic / Tech Spec section or code
   surface that justifies the entry — never an empty self-attestation.
 - An empty `axes` array is a deliberate assertion that no recognized risk
   axis applies (derives an all-low, auto-proceed envelope) — use it only
@@ -305,13 +269,13 @@ Authoring rules:
   judgment, not control flow.
 
 The derivation rules you are feeding (so you can anticipate the
-disposition Step 5 must honor): any required axis ⇒ acceptance spec
+disposition Step 4 must honor): any required axis ⇒ acceptance spec
 `required`; otherwise any `medium` level ⇒ `recommended`; otherwise
 only not-applicable axes (or no axes) ⇒ `not-applicable` (waived).
 
-### Step 5 — Author the Acceptance Spec (Acceptance Engineer persona)
+### Step 4 — Author the Acceptance Spec (Acceptance Engineer persona)
 
-Apply the Acceptance Spec system prompt below to the PRD + Tech Spec just
+Apply the Acceptance Spec system prompt below to the Epic body + Tech Spec just
 written, plus the **existing BDD scenario index** from
 `bddScenarios` on the planner-context envelope (Story #2637). The
 scenario index is the output of
@@ -327,20 +291,42 @@ behaviour) — never `new` for an AC whose outcome is already proven by
 an existing scenario. When `bddScenarios` is empty (the project has not
 adopted BDD), proceed exactly as before with no annotation.
 
-Branch on the acceptance disposition your Step 4 verdict derives (see the
+Branch on the acceptance disposition your Step 3 verdict derives (see the
 derivation rules there): `required` and `recommended` author the spec
 normally per the rules below. `not-applicable` authorizes the persist half
 to apply `acceptance::n-a` on the Epic; in that case write a one-paragraph
 waiver rationale to `temp/epic-<Epic_ID>/acceptance-spec.md` instead of
 the AC table so the audit trail still exists, and start the file with
-`## Acceptance Criteria — waived (planner-selected)`.
+`## Acceptance Table — waived (planner-selected)`.
 
 Write to `temp/epic-<Epic_ID>/acceptance-spec.md`. The Acceptance Spec
 MUST:
 
-- Start with `## Acceptance Criteria` — never a top-level `#` heading.
+- Start with `## Acceptance Table` — never a top-level `#` heading, and
+  never the Epic's own `## Acceptance Criteria` heading (the table lands
+  as a section of the same Epic body).
 - Render the AC table with the canonical column shape documented in Tech
   Spec #2083: `| AC ID | Outcome | Feature File | Scenario | Disposition |`.
+- **Key each `Outcome` off a specific Epic `## Acceptance Criteria`
+  bullet** — the Epic body's AC bullets are the single source of truth, so
+  the `Outcome` column is a **terse restatement anchored to one Epic
+  bullet**, not an independent re-elaboration. Lead each `Outcome` with its
+  anchor (the bullet's quoted lead phrase or an explicit `Epic AC N` index),
+  then state the single user-visible behaviour. A free-standing `Outcome`
+  that paraphrases a criterion in new words without naming the Epic bullet
+  it verifies is the drift this rule exists to prevent — it decouples the
+  spec from the Epic silently.
+  - **Split case (one Epic AC → several rows).** When one Epic AC bullet
+    genuinely expands into several user-visible outcomes, emit one row per
+    outcome and **declare the split on each** row (e.g. lead with
+    `splits Epic AC 3`) so the fan-out is explicit, not hidden.
+  - **Flag divergence, do not absorb it.** Anchor coverage MUST be complete
+    and auditable: every Epic AC bullet is covered by at least one row and
+    every row anchors to an Epic bullet. Call out any Epic AC bullet with
+    **no** corresponding row, and any AC row with **no** Epic anchor, in a
+    note directly beneath the AC table — surfacing spec/Epic divergence at
+    authoring time. Never silently drop an uncovered Epic bullet or emit an
+    unanchored row.
 - Use **stable AC IDs** of the form `AC-1`, `AC-2`, … assigned in document
   order. On re-plan, reuse the ID for any AC whose Outcome text is
   materially unchanged; new ACs receive fresh sequential IDs (existing
@@ -364,34 +350,40 @@ MUST:
 
 ```text
 You are an expert Acceptance Engineer.
-Your job is to convert a PRD and a Tech Spec into a structured Acceptance Specification that drives features-first BDD authoring.
+Your job is to convert an Epic and a Tech Spec into a structured Acceptance Specification that drives features-first BDD authoring.
 
 The Acceptance Spec should outline:
-1. Acceptance Criteria — one row per user-visible outcome, expressed as a Markdown table with columns: AC ID | Outcome | Feature File | Scenario | Disposition
+1. Acceptance Table — one row per user-visible outcome, expressed as a Markdown table with columns: AC ID | Outcome | Feature File | Scenario | Disposition
 2. Stable AC IDs — assign AC-1, AC-2, ... in document order; reuse the same ID across re-plans when an Outcome is materially unchanged so scenario tags (@ac-N) stay aligned
 3. Disposition — tag each row with one of: new | updated | unchanged
 
+The Epic body's `## Acceptance Criteria` bullets are the single source of truth for what the spec verifies. Your table does not re-invent criteria — it anchors each one to a specific Epic AC bullet.
+
 CRITICAL REQUIREMENTS:
 - Respond ONLY with valid Markdown.
-- Do not use top-level <h1> (# ) tags. Start with ## Acceptance Criteria.
+- Do not use top-level <h1> (# ) tags. Start with ## Acceptance Table — the table lands as a section of the Epic body, so it must NOT reuse the Epic's own ## Acceptance Criteria heading.
 - Every AC row MUST have a stable AC ID of the form AC-<n> (AC-1, AC-2, ...) — do not reorder IDs across re-plans; new ACs get fresh sequential IDs.
-- Every AC row MUST carry a Disposition value from the enum: new | updated | unchanged.
-- Each Outcome MUST be a single user-visible behaviour — no DB assertions, no HTTP status codes, no internal implementation details.
+- Every AC row MUST carry a Disposition value from the enum: new | updated | unchanged. (At Epic close, the acceptance reconciler overwrites Disposition with the verification outcome — satisfied | pending | missing — inside this section only; on re-plan, reset each row to the authoring enum.)
+- Each Outcome MUST be a **terse restatement keyed to a specific Epic `## Acceptance Criteria` bullet** — lead the Outcome with the bullet's anchor (its quoted lead phrase or an explicit "Epic AC N" index) and keep the rest to a single user-visible behaviour. Do NOT re-elaborate the Epic bullet in independent words: a free-standing Outcome that paraphrases the criterion without naming the bullet it verifies is forbidden, because it drifts from the Epic silently. No DB assertions, no HTTP status codes, no internal implementation details.
+- Where one Epic AC bullet genuinely expands into several user-visible outcomes, emit one row per outcome and declare the split on each — e.g. lead with "splits Epic AC 3" — so the fan-out is explicit rather than hidden.
+- Anchor coverage MUST be complete and auditable: every Epic AC bullet MUST be covered by at least one row, and every row MUST anchor to an Epic AC bullet. Flag divergence in the authored spec instead of dropping it — if an Epic AC bullet has no corresponding row, or a row has no Epic anchor, call it out explicitly (a note beneath the table) rather than silently omitting the bullet or emitting an unanchored row.
 - Cite proposed feature file paths under tests/features/** so Phase 8 can scaffold matching scenarios.
 - Acceptance Outcomes MUST NOT prescribe a commit subject that begins with a non-Conventional-Commits prefix (allowed leading types: feat|fix|chore|refactor|perf|docs|style|test|build|ci|revert). The legacy `baseline-refresh` token used as a leading subject prescription is forbidden — commitlint will reject it at commit time, and the decompose-time validator (`ticket-validator.js` → `validateAcceptanceSubjectPrefix`) will reject the decompose with `code: 'forbidden-subject-prefix'`. Use a Conventional-Commits subject (e.g. `chore(baselines): refresh ...`) and a body trailer (e.g. `baseline-refresh: true` — trailer with a value, not a subject prefix) when a machine-readable marker is needed. See Epic #2501 for rationale.
 ```
 
-### Step 6 — Hand back to `/plan`
+### Step 5 — Hand back to `/plan`
 
-All four files exist; return. The caller will run
-`node .agents/scripts/epic-plan-spec.js --epic <Epic_ID> --prd
-temp/epic-<Epic_ID>/prd.md --techspec temp/epic-<Epic_ID>/techspec.md
+All three files exist; return. The caller will run
+`node .agents/scripts/epic-plan-spec.js --epic <Epic_ID>
+--tech-spec temp/epic-<Epic_ID>/techspec.md
 --risk-verdict temp/epic-<Epic_ID>/risk-verdict.json
---acceptance-spec temp/epic-<Epic_ID>/acceptance-spec.md`, which validates
-the risk verdict, derives the planningRisk envelope, persists the
-artifacts, records the `risk-verdict` structured comment, appends the
-`## Planning Artifacts` section to the Epic body, flips the Epic to
-`agent::review-spec`, and cleans up the temp files.
+--acceptance-table temp/epic-<Epic_ID>/acceptance-spec.md`, which validates
+the risk verdict, derives the planningRisk envelope, folds the authored
+content into the Epic body's managed sections (`## Delivery Slicing`-led
+Tech Spec sections + the `## Acceptance Table`), records the
+`risk-verdict` structured comment, flips the Epic to
+`agent::review-spec`, and cleans up the temp files. No context tickets
+are created (Story #4324).
 
 ## Constraints
 

package/.agents/skills/core/epic-plan-spec-author/examples.md

@@ -0,0 +1,91 @@
+# epic-plan-spec-author — examples & extended rationale
+
+Read this file on demand while authoring the Tech Spec. The SKILL.md carries
+the operating contract (Policy Capsule, Inputs / Outputs, Procedure, the two
+authoritative system prompts, and Constraints); this file carries the worked
+Delivery Slicing example and the extended rationale behind the slicing rules.
+
+## Delivery Slicing — extended rationale
+
+The Tech Spec MUST carry a `## Delivery Slicing` section in which the Architect
+— who holds the full design — proposes how the Epic's enumerated capabilities
+**cluster into N shippable Stories**. This section is the intentional grouping
+the Phase 8 consolidation pass
+([`epic-plan-consolidate`](../epic-plan-consolidate/SKILL.md)) reconciles the
+decomposer's draft against before any GitHub write. Without it, the decompose
+phase maps Epic capabilities to Stories ~1:1 and cannot produce a coarser,
+holistic plan; with it, the consolidation critic has a well-defined reference
+instead of a guess.
+
+**The proposed count is a ceiling, not a target.** Consolidation reconciles
+the draft *toward* your grouping, but it treats the count as an upper bound: it
+may **merge below** your proposed count when slices form dependent
+single-consumer chains, and it **never splits above** it. Over-slicing here
+therefore locks in fragmentation only when the extra slices are genuinely
+independent — so keep a slice separate only when it earns its own delivery
+session.
+
+**Write the Delivery Slicing section before any other section — it is the
+primary input to Phase 8 consolidation.** Author it first so the rest of the
+spec (Core Components, API Changes, Data Models) hangs off a deliberate
+slicing decision rather than being reverse-engineered into one at the end.
+Drafting it last is exactly how the model omits it under the weight of the
+other sections.
+
+Author the section as a table — one row per proposed slice — naming the
+capability cluster each slice would deliver, what ships in it, and whether it
+can ship independently. Use **noun phrases** for slice names ("Foundation",
+"Transport seam", "Send helper") so they map cleanly onto Feature titles in the
+resulting decomposition — never verb phrases ("Add transport") or file names
+("`sender.ts`"). Do **not** coarsen the Epic's capability enumeration to produce
+the slicing: the granularity lever is *this* grouping recommendation, not a
+dumbed-down Epic enumeration.
+
+**What "Independent?" means:** can this slice ship to production and provide
+value *without the next slice landing*? A `Yes` slice is releasable on its own;
+a `No` slice only becomes valuable once a later slice lands on top of it.
+
+**"Independent? No" is a smell that must be justified.** A dependent,
+single-consumer slice (one that only feeds the next slice) folds into its
+consumer by default — it is not worth its own delivery session's hydration,
+branch, PR, and CI ceremony. Mark a slice `No` only when you can name a
+one-line reason to keep it separate anyway: **parallelism** (two `No` slices
+that can be delivered concurrently by different sessions), **risk isolation**
+(a blast-radius or reviewability reason to land it as its own reviewable PR),
+or **delivery-envelope pressure** (folding it in would push the consumer past a
+single-session sizing envelope). Absent such a justification, do not author the
+slice as its own row — fold it into its consumer and let the merged slice carry
+the combined capability.
+
+### Worked example
+
+```text
+## Delivery Slicing
+
+Proposed shippable slices (consolidation ceiling for Phase 8):
+
+| Slice          | What ships                                              | Independent? |
+| -------------- | ------------------------------------------------------ | ------------ |
+| Foundation     | Config schema, types, and the no-op default path       | Yes          |
+| Transport seam | The pluggable transport interface + in-memory adapter  | Yes          |
+| Send helper    | The send() helper + retries, built on the transport    | No (justified: risk isolation) |
+
+- **Foundation** folds Epic capabilities "config surface" + "type model" — they
+  share a reason to exist and ship as one reviewable PR.
+- **Transport seam** is the pluggable boundary; it provides value on its own
+  (in-memory adapter is usable for tests) so it is independently shippable.
+- **Send helper** depends on the transport seam landing first, so it is *not*
+  independent. It stays its own slice only because the retry/backoff logic is a
+  large, high-blast-radius surface worth isolating in its own reviewable PR
+  (risk isolation). Absent that justification it would fold into Transport
+  seam — a bare "depends on the previous slice" is not a reason to keep it
+  separate.
+```
+
+The consolidation pass degrades gracefully when this section is absent (it
+falls back to cohesion + single-Story-Feature rules only), so authoring it is
+how the Architect steers the decomposition toward fewer, right-sized Stories.
+Because the count is a **ceiling**, an over-sliced table is coarsened back
+during consolidation — but only where the extra slices are dependent
+single-consumer chains, so an unjustified `No` slice is the one you should fold
+in yourself rather than leaning on the consolidator to catch.