mandrel 1.81.0 → 1.83.0

package/.agents/scripts/lint-label-vocabulary.js

@@ -66,7 +66,6 @@ export const KNOWN_AXES = Object.freeze([
   'type',
   'status',
   'persona',
-  'context',
   'acceptance',
   'meta',
   'planning',
@@ -156,11 +155,11 @@ export function findVocabularyViolations(src, axes = KNOWN_AXES) {
   //   - value is a lowercase identifier (`[a-z][a-z0-9-]*`)
   //
   // The whole-body anchor avoids false positives on:
-  //   - `context::acceptance-spec` — canonical label, value contains a
+  //   - `acceptance::n-a` — canonical label, value contains a
   //     hyphen but is not at axis position.
   //   - `<type>/<slug>` — template placeholders.
   //   - `delivery.maxTokenBudget` — config-key paths with `.`.
-  //   - `context.{prdId,techSpecId}` — JS destructure shapes.
+  //   - `delivery.{maxTickets}` — JS destructure shapes.
   //   - `agent-protocol.md` — filenames / concept slugs.
   //
   // Real drift like `type/epic` matches because the WHOLE body is

package/.agents/scripts/providers/github/mappers.js

@@ -11,8 +11,6 @@
  * Extracted from `../github.js` in Story #1846 / Task #1859.
  */
 
-import { parseLinkedIssues } from '../../lib/issue-link-parser.js';
-
 function normalizeLabels(issue) {
   const raw = issue?.labels;
   if (!raw) return [];
@@ -50,7 +48,6 @@ export function issueToEpic(issue) {
     body: issue.body ?? '',
     labels,
     labelSet: new Set(labels),
-    linkedIssues: parseLinkedIssues(issue.body),
   };
 }
 

package/.agents/scripts/providers/github/tickets.js

@@ -112,7 +112,7 @@ export class TicketGateway {
     this._cache = cache ?? createInlineTicketCache();
     /**
      * Per-instance memo of `getTickets(epicId, filters)` results (Story
-     * #3988). The planning-state-manager fetches the same child list twice
+     * #3988). Planning-era healing fetched the same child list twice
      * per planning pass; without this memo each fetch re-pays the full
      * search/list round-trip. Invalidated on every write surface.
      * @type {Map<string, object[]>}
@@ -322,24 +322,13 @@ export class TicketGateway {
     // Mirror the Epic create path (issues.js:160 → `labels: TYPE_LABELS.EPIC`):
     // inject TYPE_LABELS.STORY so a spec that omits the labels array cannot
     // produce an unlabeled, undispatchable Story. Dedupe to avoid duplicates
-    // when the caller already carries the label.
-    //
-    // Context spec tickets (PRD / Tech Spec / Acceptance Spec) are a distinct
-    // ticket class created through this same factory carrying a `context::*`
-    // label (and no `type::story`). They MUST NOT be stamped `type::story`:
-    // doing so makes every `type::story`-counting consumer — the decompose
-    // open-children guard (`assertNoOpenPlanChildren`), the delivery wave
-    // builder (`discoverOpenStories`), the plan healthcheck — mis-classify
-    // them as deliverable Stories. Skip the injection when the caller's labels
-    // already classify the ticket as context.
+    // when the caller already carries the label. (Story #4324 retired the
+    // `context::*` ticket classes, so every ticket created through this
+    // factory is a Story.)
     const callerLabels = ticketData.labels ?? [];
-    const isContextTicket = callerLabels.some(
-      (l) => typeof l === 'string' && l.startsWith('context::'),
-    );
-    const labels =
-      isContextTicket || callerLabels.includes(TYPE_LABELS.STORY)
-        ? callerLabels
-        : [TYPE_LABELS.STORY, ...callerLabels];
+    const labels = callerLabels.includes(TYPE_LABELS.STORY)
+      ? callerLabels
+      : [TYPE_LABELS.STORY, ...callerLabels];
     const result = await this._gh.api({
       method: 'POST',
       endpoint: `/repos/${this.owner}/${this.repo}/issues`,

package/.agents/scripts/single-story-init.js

@@ -23,7 +23,6 @@
  *   6. Flip the Story to `agent::executing`.
  *
  * What this script does NOT do (and why):
- *   - Skips `traceHierarchy` — no Epic → no PRD/Tech-Spec.
  *   - Skips `validateBlockers` against the body's `Blocked by:` markers —
  *     pre-flight is still the operator's responsibility, but the Epic-scope
  *     blocker chain doesn't fit.

package/.agents/scripts/story-init.js

@@ -9,7 +9,6 @@
  * pipeline stages from `lib/story-init/`:
  *
  *   1. context-resolver     — fetch the Story + optionally mark as recut.
- *   2. hierarchy-tracer     — resolve Feature/Epic → PRD / Tech Spec.
  *   3. blocker-validator    — refuse to proceed while dependencies are open.
  *   4. task-graph-builder   — fetch + topologically sort child Tasks.
  *   5. branch-initializer   — materialise the story branch (single-tree
@@ -53,7 +52,6 @@ import {
   planStoryBranchSeed,
 } from './lib/story-init/branch-initializer.js';
 import { resolveContext } from './lib/story-init/context-resolver.js';
-import { traceHierarchy } from './lib/story-init/hierarchy-tracer.js';
 import { transitionStoryToExecuting } from './lib/story-init/state-transitioner.js';
 import { buildTaskGraph } from './lib/story-init/task-graph-builder.js';
 import { createPhaseTimer } from './lib/util/phase-timer.js';
@@ -88,8 +86,6 @@ export async function runStoryInit({
   dryRun: dryRunParam,
   cwd: cwdParam,
   recutOf: recutOfParam,
-  prdId: prdIdParam,
-  techSpecId: techSpecIdParam,
   injectedProvider,
   injectedConfig,
 } = {}) {
@@ -100,17 +96,10 @@ export async function runStoryInit({
           dryRun: !!dryRunParam,
           cwd: cwdParam ?? null,
           recutOf: recutOfParam ?? null,
-          prdId: prdIdParam ?? null,
-          techSpecId: techSpecIdParam ?? null,
         }
       : parseSprintArgs();
   const { storyId, dryRun } = parsed;
   const recutOf = recutOfParam ?? parsed.recutOf ?? null;
-  // Story #4253: pre-resolved Epic linkages (from the /deliver fan-out's
-  // one-time Epic resolution). When both are present, hierarchy-tracer skips
-  // the per-Story getEpic round-trip; when absent it resolves them itself.
-  const threadedPrdId = prdIdParam ?? parsed.prdId ?? null;
-  const threadedTechSpecId = techSpecIdParam ?? parsed.techSpecId ?? null;
   // Worktree-aware cwd resolution: explicit param > --cwd flag > env > PROJECT_ROOT.
   const cwd = path.resolve(cwdParam ?? parsed.cwd ?? PROJECT_ROOT);
 
@@ -155,20 +144,7 @@ export async function runStoryInit({
     input: { storyId, recutOf, dryRun },
   });
 
-  // Stage 2 — hierarchy. When the /deliver fan-out threaded --prd/--tech-spec
-  // (both resolved once by the parent), this short-circuits the per-Story
-  // getEpic. Absent flags fall back to the legacy getEpic resolution.
-  const { prdId, techSpecId } = await traceHierarchy({
-    provider,
-    logger: stageLogger,
-    input: { epicId, prdId: threadedPrdId, techSpecId: threadedTechSpecId },
-  });
-
   progress('CONTEXT', `Epic: #${epicId}, Parent: #${parentId ?? 'none'}`);
-  progress(
-    'CONTEXT',
-    `PRD: #${prdId ?? 'none'}, Tech Spec: #${techSpecId ?? 'none'}`,
-  );
 
   // Stage 3 — blockers.
   const { openBlockers } = await validateBlockers({
@@ -335,8 +311,6 @@ export async function runStoryInit({
     installStatus,
     sortedTasks,
     parentId,
-    prdId,
-    techSpecId,
     dryRun,
     recutOf,
     hierarchy: hierarchyMode,
@@ -473,8 +447,6 @@ function buildStoryInitResult({
   installStatus,
   sortedTasks,
   parentId,
-  prdId,
-  techSpecId,
   dryRun,
   recutOf,
   hierarchy,
@@ -506,7 +478,7 @@ function buildStoryInitResult({
       labels: t.labels,
       dependencies: t.dependsOn ?? parseBlockedBy(t.body ?? ''),
     })),
-    context: { parentId, prdId, techSpecId },
+    context: { parentId },
     dryRun,
   };
 }

package/.agents/skills/core/epic-plan-consolidate/SKILL.md

@@ -6,7 +6,7 @@ description: >-
   `/plan`, after `epic-plan-decompose-author` writes
   `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js`
   validates and persists it. Reconciles the draft against the Tech Spec
-  "Delivery Slicing" target via scope-preserving operations only.
+  "Delivery Slicing" ceiling via scope-preserving operations only.
 allowed_tools:
   - Read
   - Write
@@ -17,24 +17,26 @@ allowed_tools:
 
 ## Policy Capsule
 
-- Run only after `epic-plan-decompose-author` has written `temp/epic-<Epic_ID>/tickets.json`; fail loudly if the draft array is missing. Read the PRD / Tech Spec from `temp/epic-<Epic_ID>/decomposer-context.json` (the same envelope the author skill consumed) — never re-fetch from GitHub, and never call the GitHub API from this Skill.
+- Run only after `epic-plan-decompose-author` has written `temp/epic-<Epic_ID>/tickets.json`; fail loudly if the draft array is missing. Read the sectioned Epic body (which carries the folded Tech Spec sections) from `temp/epic-<Epic_ID>/decomposer-context.json` (the same envelope the author skill consumed) — never re-fetch from GitHub, and never call the GitHub API from this Skill.
 - Emit exactly two artifacts inside `temp/epic-<Epic_ID>/`: the **consolidated** `tickets.json` (overwriting the draft array in place) and a human-readable `consolidation-report.md` (the rationale + before/after diff the operator reviews at the HITL gate). Both MUST exist before returning.
 - **Scope conservation is the load-bearing invariant.** You are a *critic*, not a second author: you MUST NOT add scope, invent tickets, or drop acceptance criteria. Every acceptance item and every `verify` entry present in the draft MUST survive into the consolidated array (possibly re-homed onto a merged Story). **This is your contract, not a machine guarantee:** there is **no runtime acceptance-union diff** on your output. The only deterministic runtime backstop the validator applies after you run is the standard ticket-structure validation — it does not re-derive the pre-consolidation acceptance/verify union, so a critic that silently dropped an acceptance item would **not** be caught downstream. (The repo's unit test exercises a *pure model* of the merge over an over-fragmented fixture to document the intended invariant; it does not inspect this Skill's actual output.) Conserve scope yourself, deliberately, on every merge.
 - Your operations are constrained to exactly two shapes: **(1) merge two or more Stories** into one (union their `changes`/`acceptance`/`verify`/`references`, keep one coherent `goal`); **(2) rewire `depends_on`** so the edges still reference surviving sibling-Story slugs. No other mutation is permitted.
-- Consume the Tech Spec **"Delivery Slicing"** section as the authoritative target grouping when one is present: cluster the draft's Stories toward the N shippable Stories the Architect proposed. When the section is **absent**, degrade gracefully — apply only the cohesion rules below and leave the rest of the draft shape intact.
+- Consume the Tech Spec **"Delivery Slicing"** section as a **ceiling, not a target**, when one is present: the Architect's proposed N shippable Stories is an *upper bound*, not a floor. Cluster the draft's Stories toward that grouping, and go **below** N when slices form dependent single-consumer chains — a slice whose "Independent? No" row carries no justification (parallelism, risk isolation, or delivery-envelope pressure) folds into its consumer. You **never** split above N. When the section is **absent**, degrade gracefully — apply only the cohesion rules below and leave the rest of the draft shape intact.
 - Apply the same cohesion heuristic the author skill leads with: **one Story = one coherent change with one reason to exist**, and the **single-consumer merge rule** (a Story whose only consumer is one sibling Story is merged into that sibling). Lead every merge decision with the change's reason, not its file count.
 - **Missing reason-to-exist check (cohesion gate).** Every draft Story body MUST carry a non-empty `reason_to_exist` meta field (the parseable form of "one Story = one coherent change with one reason to exist", encoded in the `<!-- meta: {"reason_to_exist": "..."} -->` comment and surfaced as `body.reason_to_exist` by `lib/story-body/story-body.js`). Flag any Story whose body carries **no** non-empty reason to exist: a Story that cannot state its single reason in one sentence is a cohesion smell — it is probably two Stories, or two Stories that should be merged into one. Name each flagged Story in the consolidation report so the operator sees the cohesion gap at the HITL diff gate.
 - After every merge, **rewire `depends_on`**: drop self-edges, collapse edges that now point at the absorbing Story onto itself, and re-point any edge that named a now-deleted slug at its surviving successor. Never leave a `depends_on` referencing a slug absent from the consolidated array — the validator HARD-rejects unknown deps.
-- The consolidation report MUST name each operation applied (merged slugs → surviving slug, rewired edges) with a one-line reason, plus a before/after Story-count line, so the operator can approve or reject at the HITL diff gate before the persist call.
+- The consolidation report MUST name each operation applied (merged slugs → surviving slug, rewired edges) with a one-line reason, plus a before/after Story-count line, so the operator can approve or reject at the HITL diff gate before the persist call. When the consolidated count drops **below** the Delivery-Slicing count (a below-ceiling coarsening), the report MUST surface that fact explicitly — e.g. `Below ceiling: N (Delivery Slicing) → M (consolidated)` — and attach a one-line rationale to each below-ceiling merge (which dependent single-consumer slice folded into which consumer, and why it was unjustified), so the operator sees the coarsening at the Phase 8.3 advisory diff.
 
 ## Role
 
 Senior Project Manager + Orchestrator, acting as a **holistic critic** with
-fresh context. This Skill is deliberately *separate* from
-`epic-plan-decompose-author` (the generator): a same-pass self-critique is the
-weak mode this is built to escape. The generator maps PRD capabilities to
-Stories ~1:1; this critic steps back and looks at the *whole* decomposition
-against the Tech Spec's intentional grouping before any GitHub write.
+fresh context — deliberately *separate* from `epic-plan-decompose-author` (the
+generator) so the pass is a fresh-context review, not a same-pass self-critique.
+
+> **Read [`examples.md`](./examples.md) on demand** for the extended rationale:
+> why this critic runs with fresh context, why scope conservation is your
+> contract rather than a runtime guarantee, and how the below-ceiling
+> coarsening case is reported.
 
 ## When to use
 
@@ -54,10 +56,13 @@ reads:
 - `temp/epic-<Epic_ID>/tickets.json` — the **draft** Story array the
   `epic-plan-decompose-author` Skill wrote. This is the consolidation input.
 - `temp/epic-<Epic_ID>/decomposer-context.json` — the authoring envelope
-  emitted by `epic-plan-decompose.js --emit-context`. Read `prd.body` /
-  `prd` and `techSpec.body` / `techSpec` from it. The **"Delivery Slicing"**
-  section (authored by `epic-plan-spec-author` in the Tech Spec) is the
-  target grouping when present; degrade gracefully when it is absent.
+  emitted by `epic-plan-decompose.js --emit-context`. Read `epicBody`
+  from it — the sectioned Epic body carrying the folded Tech Spec
+  sections (there is no separate `techSpec` key — Story #4324). The
+  **"Delivery Slicing"**
+  section (authored by `epic-plan-spec-author`) is the
+  grouping **ceiling** when present (you may merge below it, never split above
+  it); degrade gracefully when it is absent.
 
 ## Outputs
 
@@ -74,16 +79,21 @@ Both files MUST exist before the Skill returns.
 
 ## Procedure
 
-### Step 1 — Load the draft and the target
+### Step 1 — Load the draft and the ceiling
 
 Read `temp/epic-<Epic_ID>/tickets.json` (the draft array) and
-`temp/epic-<Epic_ID>/decomposer-context.json` (for the PRD / Tech Spec). Locate
-the Tech Spec **"Delivery Slicing"** section. Pin two facts before mutating
+`temp/epic-<Epic_ID>/decomposer-context.json` (for the `epicBody`, which
+carries the Tech Spec sections). Locate
+the **"Delivery Slicing"** section. Pin two facts before mutating
 anything:
 
-1. The **target grouping** — the N shippable Stories the Architect proposed in
+1. The **grouping ceiling** — the N shippable Stories the Architect proposed in
    Delivery Slicing, or `null` when the section is absent (graceful-degrade
-   mode: cohesion rules only).
+   mode: cohesion rules only). Treat N as an upper bound you may go below, not a
+   floor you must hit. Note which slices are marked "Independent? No" and
+   whether each carries a justification (parallelism, risk isolation, or
+   delivery-envelope pressure) — an unjustified dependent slice is a
+   fold-into-consumer candidate.
 2. The **draft Story count** — so you can spot over-fragmented capability
    clusters.
 
@@ -92,17 +102,23 @@ anything:
 Across the draft Story array, decide which Stories merge:
 
 - **Over-fragmented capability** → when several draft Stories map to one
-  Delivery-Slicing target (or one coherent reason to exist), merge them into a
+  Delivery-Slicing slice (or one coherent reason to exist), merge them into a
   single Story: union their `changes` / `acceptance` / `verify` / `references`,
   write one coherent `goal`, and keep the union of labels.
-- **Single-consumer Story** → merge into the one sibling that consumes it.
+- **Single-consumer Story** → merge into the one sibling that consumes it. This
+  is the primary lever for going **below** the Delivery-Slicing ceiling: an
+  "Independent? No" slice whose only consumer is one sibling folds into that
+  sibling unless its row justifies staying separate (parallelism, risk
+  isolation, or delivery-envelope pressure). Coarsening below N here is
+  expected, not an over-reach — record it as a below-ceiling merge (see Step 4).
 - **Missing reason to exist** → flag any Story whose body carries no non-empty
   `reason_to_exist` meta field. A Story that cannot name its single coherent
   reason is a cohesion smell; record it in the report so the operator can
   re-scope it (merge, split, or have the author supply the reason) at the HITL
   gate.
 
-Record each decision with its one-line reason for the report.
+Never split a draft Story to *reach* N — N is a ceiling, and adding scope is
+out of contract. Record each decision with its one-line reason for the report.
 
 ### Step 3 — Rewire dependencies and conserve scope
 
@@ -120,7 +136,12 @@ After applying the operations:
 
 Write the consolidated array to `temp/epic-<Epic_ID>/tickets.json` (2-space
 indent, machine-consumed) and the rationale + before/after diff to
-`temp/epic-<Epic_ID>/consolidation-report.md`.
+`temp/epic-<Epic_ID>/consolidation-report.md`. When the consolidated count
+landed **below** the Delivery-Slicing ceiling, the report MUST call that out
+explicitly — a `Below ceiling: N (Delivery Slicing) → M (consolidated)` line
+plus a one-line rationale per below-ceiling merge (which dependent
+single-consumer slice folded into which consumer, and why it was unjustified) —
+so the operator sees the coarsening at the Phase 8.3 advisory diff.
 
 ### Step 5 — Hand back to `/plan`
 

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

@@ -0,0 +1,51 @@
+# epic-plan-consolidate — 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 consolidation pass — why it is a separate,
+fresh-context critic and how the scope-conservation invariant is enforced by
+you rather than by the runtime.
+
+## Why a separate fresh-context critic
+
+This Skill acts as a **holistic critic** with fresh context (a Senior Project
+Manager + Orchestrator lens). It is deliberately *separate* from
+`epic-plan-decompose-author` (the generator): a same-pass self-critique is the
+weak mode this is built to escape. The generator maps Epic capabilities to
+Stories ~1:1; this critic steps back and looks at the *whole* decomposition
+against the Tech Spec's intentional grouping before any GitHub write.
+
+## Scope conservation is your contract, not a machine guarantee
+
+Scope conservation is the load-bearing invariant: you MUST NOT add scope,
+invent tickets, or drop acceptance criteria. Every acceptance item and every
+`verify` entry present in the draft MUST survive into the consolidated array
+(possibly re-homed onto a merged Story).
+
+**This is your contract, not a machine guarantee.** There is **no runtime
+acceptance-union diff** on your output. The only deterministic runtime backstop
+the validator applies after you run is the standard ticket-structure
+validation — it does not re-derive the pre-consolidation acceptance/verify
+union, so a critic that silently dropped an acceptance item would **not** be
+caught downstream. (The repo's unit test exercises a *pure model* of the merge
+over an over-fragmented fixture to document the intended invariant; it does not
+inspect this Skill's actual output.) Conserve scope yourself, deliberately, on
+every merge — and if you cannot preserve an item, you have over-reached, so back
+the operation out.
+
+## Ceiling, not target — the below-ceiling coarsening case
+
+Consume the Tech Spec **"Delivery Slicing"** section as a **ceiling, not a
+target** when present: the Architect's proposed N shippable Stories is an
+*upper bound*, not a floor. Cluster the draft's Stories toward that grouping,
+and go **below** N when slices form dependent single-consumer chains — a slice
+whose "Independent? No" row carries no justification (parallelism, risk
+isolation, or delivery-envelope pressure) folds into its consumer. You **never**
+split above N.
+
+When the consolidated count drops **below** the Delivery-Slicing count, the
+consolidation report MUST surface that fact explicitly — e.g.
+`Below ceiling: N (Delivery Slicing) → M (consolidated)` — and attach a one-line
+rationale to each below-ceiling merge (which dependent single-consumer slice
+folded into which consumer, and why it was unjustified), so the operator sees
+the coarsening at the Phase 8.3 advisory diff.

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

@@ -32,9 +32,10 @@ allowed_tools:
 
 ## Role
 
-Senior Project Manager + Orchestrator. The Skill's job is to take a PRD plus
-a Tech Spec and emit a flat Story backlog the orchestrator can execute
-autonomously.
+Senior Project Manager + Orchestrator. The Skill's job is to take the
+sectioned Epic body (whose managed sections carry the folded Tech Spec and
+Acceptance Table — Story #4324) and emit a flat Story backlog the
+orchestrator can execute autonomously.
 
 ## When to use
 
@@ -55,10 +56,12 @@ reads:
   `node .agents/scripts/epic-plan-decompose.js --epic <Epic_ID> --emit-context`.
   Fields:
   - `epic.id`, `epic.title`
-  - `prd.body` (or `prd.bodySummary` when downgraded by the
-    planning-context budget) — required for User-Story extraction
-  - `techSpec.body` (or `techSpec.bodySummary`) — required for module
-    boundary + dependency-DAG extraction
+  - `epicBody` — the sectioned Epic body. It carries everything the
+    decomposer needs in one document: the `## User Stories` section
+    (User-Story extraction), the folded Tech Spec sections
+    (`## Delivery Slicing` onward — module boundary + dependency-DAG
+    extraction), and the `## Acceptance Table` AC-ID table. There is no
+    separate `techSpec` envelope key (Story #4324).
   - `heuristics[]` — risk heuristics surfaced from
     `agentSettings.planning.riskHeuristics`. Apply each one against the
     Stories you are emitting; flag matches via `risk::high` labels.
@@ -117,7 +120,7 @@ Pin three values explicitly before writing any tickets:
 Apply the fully-rendered decomposer system prompt — the `systemPrompt`
 field of the loaded context envelope, produced by
 [`decomposer-prompts.js`](../../../scripts/lib/templates/decomposer-prompts.js)
-— to the PRD + Tech Spec bodies. That rendered string is the authoritative
+— to the sectioned Epic body (`epicBody`). That rendered string is the authoritative
 prompt body (with `maxTickets`, `maxTokenBudget`, and the sizing thresholds
 already interpolated); the authoring-guidance sections below complement it
 without restating it. Emit JSON only (no prose, no Markdown fence). The
@@ -224,6 +227,8 @@ They are NOT top-level ticket fields.
 
 The first question is **cohesion, not count**: *is this one coherent change with one reason to exist?* File count cannot tell a trivial 10-file mechanical rename from a hard 3-file parser+caller+config change — so lead with the change's reason, not its size. Size against the real one-pass delivery envelope (`maxTokenBudget`): a Story is correctly sized when a single agent can hold its full change, acceptance, and verification in one pass within that budget.
 
+The envelope also has a **floor**, not just a ceiling: a Story that would plausibly use well under a third of `maxTokenBudget` and is neither parallel-deliverable nor orthogonal to its siblings is a **merge candidate** — modern frontier models one-shot capability-sized changes, so a chain of small dependent Stories needlessly pays a full per-Story delivery session (hydration, branch, PR, review, CI) per link. This is soft guidance, not a threshold or validator finding; the canonical phrasing lives in `DELIVERABLE_GRANULARITY_GUIDANCE.envelopeFloor` in `ticket-validator-sizing.js`, which the decomposer prompt interpolates — do not restate a divergent version here.
+
 - **One Story = one coherent change with one reason to exist.** If you cannot state that reason in a sentence, the Story is probably two Stories.
 - **Single-consumer merge rule.** A Story whose only consumer is one sibling Story should be **merged into that sibling** rather than emitted separately — a single-consumer downstream slice is not its own unit of work.
 - **Split independent, parallelizable work** into sibling Stories — but only when the pieces genuinely have separate reasons to exist.
@@ -237,11 +242,11 @@ The first question is **cohesion, not count**: *is this one coherent change with
 
 #### DELIVERY SLICING (consume the Tech Spec target grouping when present)
 
-The Tech Spec may carry a `## Delivery Slicing` section authored by the
-Architect, proposing how the PRD's enumerated capabilities cluster into N
+The Epic body's Tech Spec sections may carry a `## Delivery Slicing` section authored by the
+Architect, proposing how the Epic's enumerated capabilities cluster into N
 shippable Stories. When that section is **present**, treat it as the **target
 grouping**: prefer emitting Stories that match the Architect's proposed
-clusters rather than mapping PRD capabilities 1:1. When it is **absent**,
+clusters rather than mapping Epic capabilities 1:1. When it is **absent**,
 degrade gracefully — decompose at deliverable granularity using the cohesion
 rules above, exactly as before. The Phase 8 holistic consolidation pass
 (`epic-plan-consolidate`) reconciles your draft against this same Delivery
@@ -263,7 +268,7 @@ Declaring `wide` with a non-empty reason **lifts the `hardFiles` rejection** —
 
 #### BRAND / COPY / STYLE WORK
 
-- Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of `docs/style-guide.md` in `acceptance` (e.g. `"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]`). If `docs/style-guide.md` does not exist or has no relevant section, state that explicitly: `"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in PRD §2"]`. Silence on style sourcing is a smell.
+- Stories that touch user-visible copy, brand assets, or visual style MUST cite the relevant section of `docs/style-guide.md` in `acceptance` (e.g. `"acceptance": ["Hero copy matches docs/style-guide.md §3 (voice & tone)"]`). If `docs/style-guide.md` does not exist or has no relevant section, state that explicitly: `"acceptance": ["docs/style-guide.md absent — copy reviewed against the inline brand brief in the Epic body"]`. Silence on style sourcing is a smell.
 
 #### BINDING ACCEPTANCE vs ADVISORY CHANGES (authoring altitude)
 
@@ -281,11 +286,11 @@ When a Story's acceptance describes a **signed-in / authenticated** persona reac
 - Phrase it as: `"From the signed-in home, the persona navigates to Reports → Export and sees the export button"` — not `"GET /reports/export returns the export view"`.
 - This applies to signed-in journeys only; an unauthenticated landing page or a deliberately deep-linkable share URL is exempt — say so in the acceptance item when you take that exemption.
 
-### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when the Acceptance Spec has `new`-disposition rows)
+### WAVE-0 BDD SCAFFOLD STORY (features-first; emit when the Acceptance Table has `new`-disposition rows)
 
-The Acceptance Spec's AC table (columns `AC ID | Outcome | Feature File | Scenario | Disposition`) tags each row's `Disposition` with one of `new | updated | unchanged`. A `new` row names a `.feature` file + scenario that does NOT yet exist on `main`. The framework is features-first: implementation Stories reference those `.feature` paths in their `verify[]` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file (observed gap: Epic #18 in `dsj1984/athportal` had 9 `new` rows and no Story tasked with creating the feature files Stories #1457 / #1466 verified against).
+The Epic body's `## Acceptance Table` section (columns `AC ID | Outcome | Feature File | Scenario | Disposition`) tags each row's `Disposition` with one of `new | updated | unchanged`. A `new` row names a `.feature` file + scenario that does NOT yet exist on `main`. The framework is features-first: implementation Stories reference those `.feature` paths in their `verify[]` lines, so the files MUST already exist when those Stories run — otherwise verification fails mid-delivery on a missing file (observed gap: Epic #18 in `dsj1984/athportal` had 9 `new` rows and no Story tasked with creating the feature files Stories #1457 / #1466 verified against).
 
-When the Acceptance Spec contains **one or more `Disposition: new` rows**, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create those `.feature` files with `@skip`-tagged scenarios BEFORE any implementation Story runs:
+When the Acceptance Table contains **one or more `Disposition: new` rows**, you MUST emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create those `.feature` files with `@skip`-tagged scenarios BEFORE any implementation Story runs:
 
 - **goal** (in body string): contains the literal token `bdd-scaffold`.
 - **depends_on**: EMPTY (`[]`) — the scaffold runs first, in wave 0.
@@ -295,30 +300,12 @@ When the Acceptance Spec contains **one or more `Disposition: new` rows**, you M
 - **verify** (top-level array): a grep/validate command (tier `validate`), NOT an e2e runner — verifying that a file exists with the required tags needs no browser/playwright run. Include a check that each new AC ID's namespaced tag is present in the scaffolded files, alongside the `@skip` check.
 - Each implementation Story whose `verify[]` references a scaffolded `.feature` path MUST add `depends_on: ["<scaffold-slug>"]` so the scaffold lands in an earlier wave. Omitting the link trips the soft `missing-bdd-scaffold` finding in `ticket-validator-conflicts.js` (advisory, not a hard block).
 
-When the Acceptance Spec contains **zero `new`-disposition rows** (every row is `updated` or `unchanged`), do NOT emit a scaffold Story — there is nothing to create.
-
-**Worked example.** Epic #42, Acceptance Spec with two `new` rows (`AC-1` -> `tests/features/billing/invoice.feature`, `AC-2` -> `tests/features/billing/refund.feature`). The scaffold Story below uses a serialized string `body`, top-level `acceptance`/`verify` arrays, an empty `depends_on`, and tags each scenario with both `@skip` and its namespaced `@epic-42-ac-N` tag:
-
-    {
-      "slug": "scaffold-billing-feature-files",
-      "type": "story",
-      "title": "Scaffold @skip-tagged billing feature files",
-      "depends_on": [],
-      "labels": ["type::story", "persona::qa-engineer"],
-      "acceptance": [
-        "tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch",
-        "every Scenario in the two new feature files is preceded by an @skip tag (grep for un-skipped scenarios returns zero matches)",
-        "the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2"
-      ],
-      "verify": [
-        "test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)",
-        "test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)",
-        "grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)"
-      ],
-      "body": "## Goal\nbdd-scaffold: create the @skip-tagged, @epic-42-ac-N-tagged feature files the billing-flows implementation Stories verify against, so wave-0 lands them before any implementation Story runs.\n\n## Changes\n- {\"path\": \"tests/features/billing/invoice.feature\", \"assumption\": \"creates\"}\n- {\"path\": \"tests/features/billing/refund.feature\", \"assumption\": \"creates\"}\n\n## Acceptance\n- [ ] tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch\n- [ ] every Scenario in the two new feature files is preceded by an @skip tag\n- [ ] the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2\n\n## Verify\n- test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)\n- test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)\n- grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)\n"
-    }
-
-The implementation Stories that later un-skip and flesh out these scenarios each carry `depends_on: ["scaffold-billing-feature-files"]`, placing them in a later wave than the scaffold. They MUST NOT add the `@epic-42-ac-N` tag themselves — it is already present from the scaffold pass; their job is to remove `@skip` once the scenario passes.
+When the Acceptance Table contains **zero `new`-disposition rows** (every row is `updated` or `unchanged`), do NOT emit a scaffold Story — there is nothing to create.
+
+> **Read [`examples.md`](./examples.md) on demand** for a fully worked wave-0
+> scaffold Story (Epic #42, two `new` rows) showing the serialized string
+> `body`, the top-level `acceptance`/`verify` arrays, the empty `depends_on`,
+> and the paired `@skip` + `@epic-<id>-ac-N` tagging.
 
 ### SCOPE-OVERLAP FLAGGING (docs/runbook downstream of config work)
 
@@ -407,7 +394,7 @@ any logical ordering requirement via Story-level `depends_on`.
 - Do **not** call the GitHub API from this Skill. Persistence is the
   script's job; the Skill is pure JSON authoring.
 - Do **not** write outside `temp/epic-<Epic_ID>/`. Reads may cover the
-  PRD/Tech Spec bodies plus any docs the context envelope cites.
+  Epic body plus any docs the context envelope cites.
 - The decomposer prompt's `${maxTickets}` value is the **reviewability
   budget** (Story #2798). Staying under is the default; exceeding it
   requires both an `over_budget_rationale` in the JSON output and the

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

@@ -0,0 +1,47 @@
+# epic-plan-decompose-author — examples & extended rationale
+
+Read this file on demand while authoring the ticket array. The SKILL.md carries
+the operating contract (Policy Capsule, Inputs / Outputs, Procedure, the
+authoring guidance that complements the rendered decomposer prompt, and
+Constraints); this file carries the worked WAVE-0 BDD scaffold Story and the
+extended reasoning behind it.
+
+## WAVE-0 BDD scaffold Story — worked example
+
+The contract lives in SKILL.md under **WAVE-0 BDD SCAFFOLD STORY**: when the
+Epic body's `## Acceptance Table` carries one or more `Disposition: new` rows,
+emit **exactly one** dedicated wave-0 scaffold Story whose sole job is to create
+those `.feature` files with `@skip`-tagged scenarios (each also carrying its
+namespaced `@epic-<id>-ac-N` tag) BEFORE any implementation Story runs.
+
+**Worked example.** Epic #42, Acceptance Table with two `new` rows
+(`AC-1` -> `tests/features/billing/invoice.feature`,
+`AC-2` -> `tests/features/billing/refund.feature`). The scaffold Story below
+uses a serialized string `body`, top-level `acceptance`/`verify` arrays, an
+empty `depends_on`, and tags each scenario with both `@skip` and its namespaced
+`@epic-42-ac-N` tag:
+
+    {
+      "slug": "scaffold-billing-feature-files",
+      "type": "story",
+      "title": "Scaffold @skip-tagged billing feature files",
+      "depends_on": [],
+      "labels": ["type::story", "persona::qa-engineer"],
+      "acceptance": [
+        "tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch",
+        "every Scenario in the two new feature files is preceded by an @skip tag (grep for un-skipped scenarios returns zero matches)",
+        "the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2"
+      ],
+      "verify": [
+        "test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)",
+        "test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)",
+        "grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)"
+      ],
+      "body": "## Goal\nbdd-scaffold: create the @skip-tagged, @epic-42-ac-N-tagged feature files the billing-flows implementation Stories verify against, so wave-0 lands them before any implementation Story runs.\n\n## Changes\n- {\"path\": \"tests/features/billing/invoice.feature\", \"assumption\": \"creates\"}\n- {\"path\": \"tests/features/billing/refund.feature\", \"assumption\": \"creates\"}\n\n## Acceptance\n- [ ] tests/features/billing/invoice.feature and tests/features/billing/refund.feature both exist on the branch\n- [ ] every Scenario in the two new feature files is preceded by an @skip tag\n- [ ] the invoice.feature scenario carries @epic-42-ac-1 and the refund.feature scenario carries @epic-42-ac-2\n\n## Verify\n- test -f tests/features/billing/invoice.feature && test -f tests/features/billing/refund.feature (validate)\n- test -z \"$(grep -rL '@skip' tests/features/billing/*.feature)\" (validate)\n- grep -q '@epic-42-ac-1' tests/features/billing/invoice.feature && grep -q '@epic-42-ac-2' tests/features/billing/refund.feature (validate)\n"
+    }
+
+The implementation Stories that later un-skip and flesh out these scenarios each
+carry `depends_on: ["scaffold-billing-feature-files"]`, placing them in a later
+wave than the scaffold. They MUST NOT add the `@epic-42-ac-N` tag themselves —
+it is already present from the scaffold pass; their job is to remove `@skip`
+once the scenario passes.

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

@@ -5,7 +5,7 @@ description: >-
   ticket array an Epic's decompose phase produced. Use during Phase 8 of
   `/plan`, after `epic-plan-decompose-author` / `epic-plan-consolidate` write
   `temp/epic-<Epic_ID>/tickets.json` and before `epic-plan-decompose.js`
-  validates and persists it. Reads the PRD / Tech Spec AND the actual cited
+  validates and persists it. Reads the sectioned Epic body AND the cited
   code surfaces, then emits predicted-rework findings before any GitHub write.
 allowed_tools:
   - Read
@@ -18,7 +18,7 @@ allowed_tools:
 
 ## Policy Capsule
 
-- Run only after a draft `temp/epic-<Epic_ID>/tickets.json` exists (authored by `epic-plan-decompose-author`, and consolidated by `epic-plan-consolidate` if that pass ran); fail loudly if the draft array is missing. Read the PRD / Tech Spec from `temp/epic-<Epic_ID>/decomposer-context.json` (the same envelope the author skill consumed) — never re-fetch from GitHub, and never call the GitHub API from this Skill.
+- Run only after a draft `temp/epic-<Epic_ID>/tickets.json` exists (authored by `epic-plan-decompose-author`, and consolidated by `epic-plan-consolidate` if that pass ran); fail loudly if the draft array is missing. Read the sectioned Epic body from `temp/epic-<Epic_ID>/decomposer-context.json` (the same envelope the author skill consumed) — never re-fetch from GitHub, and never call the GitHub API from this Skill.
 - **You MUST read the actual cited code surfaces.** For every Story, open the files named in its `changes[]` / `references[]` (resolve each path against the repo root; use `Read` / `Grep`) and read enough of each to judge whether the Story's `acceptance[]` is verifiable against the real code and whether its `changes[]` assumptions hold. 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.
 - Emit exactly one artifact: a human-readable `temp/epic-<Epic_ID>/premortem-report.md` — the predicted-rework findings the operator reviews at the Phase 8 HITL diff. It MUST exist before returning.
 - **This critic never writes to GitHub and never persists `tickets.json`.** It is read-and-report only: it does NOT mutate the draft array, does NOT create issues, and does NOT flip any 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).
@@ -28,14 +28,15 @@ allowed_tools:
 
 ## Role
 
-Senior Engineer + Architect, acting as a **fresh-context pre-mortem critic**.
-This Skill 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 PRD 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.
+Senior Engineer + Architect, acting as a **fresh-context pre-mortem critic** —
+deliberately *separate* from `epic-plan-decompose-author` (the generator) and
+`epic-plan-consolidate` (the scope-preserving merge critic) so it is a
+fresh-context, code-reading review, not a same-pass self-critique.
+
+> **Read [`examples.md`](./examples.md) on demand** for the extended rationale:
+> why this critic opens the actual cited code, why it is additive-recommendation
+> (not scope-preserving) unlike consolidation, and the three predicted-rework
+> finding classes in full.
 
 ## When to use
 
@@ -56,8 +57,9 @@ The workflow passes the Epic ID as the Skill argument. The Skill itself reads:
 - `temp/epic-<Epic_ID>/tickets.json` — the **draft** (or consolidated) Story
   array. This is the pre-mortem subject.
 - `temp/epic-<Epic_ID>/decomposer-context.json` — the authoring envelope emitted
-  by `epic-plan-decompose.js --emit-context`. Read `prd.body` / `prd` and
-  `techSpec.body` / `techSpec` from it.
+  by `epic-plan-decompose.js --emit-context`. Read `epicBody` from it —
+  the sectioned Epic body carrying the folded Tech Spec sections
+  (there is no separate `techSpec` key — Story #4324).
 - **The repository working tree** — the actual files each Story's `changes[]` /
   `references[]` name. Resolve each path against the repo root and read it.
 
@@ -78,7 +80,7 @@ artifact and mutates **no** GitHub state.
 ### Step 1 — Load the draft and the spec
 
 Read `temp/epic-<Epic_ID>/tickets.json` (the Story array) and
-`temp/epic-<Epic_ID>/decomposer-context.json` (for the PRD / Tech Spec). If the
+`temp/epic-<Epic_ID>/decomposer-context.json` (for the `epicBody`). If the
 draft array is missing, fail loudly and instruct the caller to run the
 `epic-plan-decompose-author` Skill first.