mandrel 1.94.0 → 2.0.0

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

@@ -1,146 +0,0 @@
----
-name: epic-plan-premortem
-description: >-
-  Run a fresh-context, code-reading pre-mortem critic over the draft Story
-  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 `plan-persist.js`
-  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
-  - Write
-  - Bash
-  - Grep
----
-
-# epic-plan-premortem
-
-## 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 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).
-- **You are not scope-preserving.** 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.
-- Hunt for the three predicted-rework finding classes the structural gates cannot catch: **(1) unverifiable acceptance criteria** (an AC no `verify[]` command or readable code state can prove); **(2) over- or under-specified Stories** (a Story whose `acceptance[]` is far broader or narrower than its `changes[]` footprint and the cited code support); **(3) semantically-wrong assumptions** (the cited file exists but does not contain the seam / export / shape the Story assumes — the file-assumption gate passes, the work would still rework).
-- Log only file/route/Story identifiers and short rationale in the report — never paste full source bodies, persona data, or secret material (per `rules/security-baseline.md` data-leakage MUSTs).
-
-## Role
-
-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. The `/plan`
-workflow delivers that fresh context by **dispatching this skill inside a
-genuine sub-agent** (`Agent` tool, `subagent_type: general-purpose`) at Phase
-8.5, rather than activating it inline in the authoring turn — the sub-agent does
-not inherit the authoring conversation, so its code-reading review is
-independent of the draft it grades.
-
-> **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
-
-`/plan` Phase 8, as the **8.5 — Planning Pre-Mortem Critic** sub-step:
-after `epic-plan-decompose-author` writes (and, when present,
-`epic-plan-consolidate` consolidates) `temp/epic-<Epic_ID>/tickets.json`, after
-the reachability completeness critic (8.4), and **before**
-`plan-persist.js --tickets …` validates and persists. The pass operates
-on the temp artifact and emits a report so the operator sees predicted rework in
-the Phase 8 HITL diff before the GitHub write; the author re-runs on the
-findings and the deterministic validator runs *after*, so nothing this critic
-surfaces reaches GitHub unreviewed.
-
-## Inputs
-
-The `/plan` workflow dispatches this skill inside a fresh-context sub-agent,
-passing 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 `plan-context.js --epic <Epic_ID>`. 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.
-
-## Outputs
-
-- `temp/epic-<Epic_ID>/premortem-report.md` — a human-readable findings report.
-  Each finding names its Story, the cited surface it read, the finding class
-  (unverifiable-AC / over-or-under-specified / wrong-assumption), a one-line
-  rationale grounded in what the file actually contains, and a recommended
-  re-authoring action. End with a one-line verdict
-  (`findings: N` / `findings: 0 — no predicted rework`).
-
-This file MUST exist before the Skill returns. The Skill writes **no** other
-artifact and mutates **no** GitHub state.
-
-## Procedure
-
-### 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 `epicBody`). If the
-draft array is missing, fail loudly and instruct the caller to run the
-`epic-plan-decompose-author` Skill first.
-
-### Step 2 — Read the cited code surfaces
-
-For each Story, collect the paths in its `changes[]` and `references[]`. For
-each path that exists in the working tree, `Read` it (or `Grep` for the specific
-export / seam the Story assumes when the file is large). Build, per Story, a
-short note of what the cited code actually contains versus what the Story's
-`acceptance[]` / `changes[]` assume.
-
-### Step 3 — Hunt the three finding classes
-
-Across the backlog, surface predicted rework:
-
-- **Unverifiable AC** — an acceptance item nothing in `verify[]` (or readable
-  code state) can prove. Recommend a concrete verify command or a reworded,
-  checkable AC.
-- **Over- / under-specified Story** — `acceptance[]` materially broader or
-  narrower than the `changes[]` footprint and the cited code support. Recommend
-  a split (under-specified one Story doing the work of several) or a tightening.
-- **Semantically-wrong assumption** — the cited file exists (so the
-  file-assumption gate passes) but does not contain the seam, export, function,
-  or data shape the Story assumes. Recommend the corrected target or an explicit
-  "create the seam first" Story.
-
-Record each finding with its Story, cited surface, class, rationale, and
-recommended action.
-
-### Step 4 — Write the report
-
-Write all findings to `temp/epic-<Epic_ID>/premortem-report.md` with the verdict
-line. Paste identifiers and short rationale only — never full source bodies.
-
-### Step 5 — Hand back to `/plan`
-
-Return control. The workflow shows the operator the pre-mortem report at the
-Phase 8 HITL diff; on operator approval it re-runs
-`epic-plan-decompose-author` on the findings **before** the persist call
-(`node .agents/scripts/plan-persist.js --epic <Epic_ID> --tickets
-temp/epic-<Epic_ID>/tickets.json`). This Skill itself persists nothing.
-
-## Constraints
-
-- Do **not** call the GitHub API from this Skill. It reads temp artifacts plus
-  the working tree and writes one temp report; persistence belongs to the
-  script, re-authoring belongs to `epic-plan-decompose-author`.
-- Do **not** write outside `temp/epic-<Epic_ID>/`, and do **not** mutate
-  `temp/epic-<Epic_ID>/tickets.json` — this critic is report-only.
-- Do **not** log full source bodies, persona data, or secrets into the report
-  (per `rules/security-baseline.md`). Identifiers and short rationale only.
-- If `temp/epic-<Epic_ID>/tickets.json` is missing, fail loudly and instruct the
-  caller to run the `epic-plan-decompose-author` Skill first.
-- The validator
-  ([`lib/orchestration/ticket-validator.js`](../../../scripts/lib/orchestration/ticket-validator.js))
-  remains the authoritative post-re-author gate. This critic surfaces
-  *semantic* rework the structural validator cannot — it does not replace it.

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

@@ -1,53 +0,0 @@
-# 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,383 +0,0 @@
----
-name: epic-plan-spec-author
-description: >-
-  Author the Tech Spec, Acceptance Table markdown, and risk-verdict JSON
-  for an Epic from the planner authoring context emitted by
-  `plan-context.js --epic <Epic_ID>`. Use during Phase 7 of `/plan` when
-  the host LLM needs to write the three artifacts before `plan-persist.js`
-  folds them into the Epic body's managed sections.
-allowed_tools:
-  - Read
-  - Write
-  - Bash
----
-
-# 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 `plan-context.js --epic <Epic_ID>` has written `temp/epic-<Epic_ID>/planner-context.json`; fail loudly if the file is missing rather than fabricating context.
-- 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.
-- **Re-emit rule (amend, don't regenerate — Story #4431).** On a re-emit — the Phase 7 persist call rejecting an artifact (e.g. a missing `## Delivery Slicing` heading, a schema-invalid risk verdict) — apply **targeted edits** to the existing `temp/epic-<Epic_ID>/` artifact that fix only what the rejection named; do NOT rewrite an artifact wholesale from a blank draft. `helpers/plan-epic.md` bounds this to **one refinement pass** per invocation (the same shape as the Epic Clarity Gate's own "one refinement pass per invocation" contract) — do not loop.
-- 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`).
-- Emit a `Runner Verification` line directly under the AC table reflecting the `bddRunner` envelope (`<runner> supports <pendingTag>` when supported, or `Fallback: dependencies-first ordering (reason: …)` on fallback).
-- Each AC Outcome MUST describe a single user-visible behaviour — no DB assertions, HTTP status codes, or implementation details — and MUST NOT prescribe a commit subject that starts with a non-Conventional-Commits prefix (the literal `baseline-refresh:` prefix is forbidden; use a body trailer instead).
-- Do not mutate GitHub issues from this Skill; persistence is the script's job. Reads MAY span anything `docsContext` references plus the planner-context JSON.
-- Respect the planning-context budget: when `epic.body` is `null` but `epic.bodySummary` is present, work from the summary instead of re-fetching the full body.
-
-## Role
-
-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 `plan-context.js --epic <Epic_ID>`
-writes `temp/epic-<Epic_ID>/planner-context.json`. This Skill replaces the
-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
-
-The dispatcher passes the Epic ID as the Skill argument. The Skill itself
-reads:
-
-- `temp/epic-<Epic_ID>/planner-context.json` — produced by
-  `node .agents/scripts/plan-context.js --epic <Epic_ID>`.
-  Fields:
-  - `epic.id`, `epic.title`, `epic.body` (or `epic.bodySummary` when the
-    planning-context budget downgrades the body to a summary)
-  - `docsContext` — digest-first (Story #4433, hard cutover of the § 3.1
-    planning read contract): `{ mode: 'digest', digestPath }` pointing at
-    the per-Epic docs digest (`<tempRoot>/epic-<Epic_ID>/docs-digest.md` —
-    the same file the `/deliver` story sub-agents already consume, Story
-    #4338 / #4324), or `null` when `project.docsContextFiles` is unset. Read
-    the digest at `digestPath` for "how does the codebase do X today?"
-    orientation (path, byte size, heading outline with line numbers, first
-    paragraph per `##` section), then pull the full file on demand with your
-    own Read tool — jump straight to the line the digest names — only when a
-    section bears on the spec. There is no full-content `items[]` field;
-    embedding whole/summarized doc bodies in this envelope was retired in
-    the same cutover that made the `/deliver` children digest-first.
-  - `codebaseSnapshot` — Story #2634 structural view of the consumer repo
-    (file tree, `package.json` exports + scripts, recently-touched
-    directories, detected test runner + BDD feature roots, and — at the
-    `medium` tier — per-file export signatures). Prefer module / file
-    names that appear in this snapshot over names that appear only in
-    the docs digest; the docs may be stale relative to the actual
-    source tree. When the spec needs to cite a file that is **not** in
-    `codebaseSnapshot.files`, surface that as a `<!-- DRIFT -->` callout
-    in the Tech Spec body naming the cited path, so the freshness gate
-    (Story #2635) has prose context for the operator to read.
-    - `codebaseSnapshot.grounding` (Story #4139) — operator-visible
-      grounding signals derived before you author:
-      - `grounding.truncation` — non-null when the snapshot dropped files
-        (the skinny-tier cap kept only the first ~250 of N matched files).
-        Carries `{ dropped, matched, shown, tier, remedies[] }`. When it is
-        present, the file tree you see is **partial** — do not assume a
-        module is absent just because it is missing from
-        `codebaseSnapshot.files`; raise the partiality in a `<!-- DRIFT -->`
-        callout and prefer the `medium` tier (or a narrowed `include`) for
-        a grounded spec.
-      - `grounding.citedButAbsent[]` — paths the Epic body already cites
-        that are **not** in the snapshot and are not phrased as net-new.
-        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.techSpec` and `systemPrompts.acceptanceSpec` — the
-    **authoritative** rendered system prompts (single-sourced in
-    `lib/templates/spec-author-prompts.js`). Apply them verbatim; the
-    procedure below describes how to use them, it does not restate them.
-  - `bddRunner` — BDD runner pending-tag verification result. Shape:
-    `{ runner, pendingTag, supported, fallback, reason? }`. When
-    `supported: true`, render the verified `pendingTag` in the
-    acceptance-spec body so the features-first Story can scaffold
-    `.feature` files with that exact tag. When `fallback: true`, render
-    `"Fallback: dependencies-first ordering"` and omit the pending-tag
-    line — Phase 8 reverts to topological ordering.
-  - `bddScenarios` — Story #2637 scenario index for the project's
-    existing `.feature` files. Each row is
-    `{ file, line, scenarioTitle, tags, outcomeKeywords }`. Empty array
-    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 4).
-  Planning risk is **not** an input — this Skill authors it. The risk
-  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>/techspec.md` — Tech Spec markdown starting with
-  `## 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 Table` (no `<h1>`).
-
-All three files MUST exist on disk before this Skill returns control. The
-caller will invoke
-`plan-persist.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.
-
-## Procedure
-
-### 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, including the Epic's `## User Stories`
-section), and the `docsContext` digest pointer (`digestPath`, or `null`).
-When non-null, read the digest file at `digestPath` next — that outline,
-not the planner-context envelope, is where the actual doc orientation
-lives; pull a full doc on demand only when a section looks relevant.
-
-### Step 2 — Author the Tech Spec (Engineering Architect persona)
-
-Apply the Tech Spec system prompt below to the Epic body (Context / Goal /
-Scope / User Stories), the docs digest (plus any full file pulled on
-demand), 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:
-
-- **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.
-- Cite the source files / modules it touches by relative path. Avoid
-  pseudocode — name real symbols when proposing edits.
-
-#### Delivery Slicing section (authoritative ceiling for Phase 8 consolidation)
-
-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 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).
-
-Apply the `systemPrompts.techSpec` string from the emitted envelope verbatim —
-it is the single source (rendered from `lib/templates/spec-author-prompts.js`).
-It fixes the section order (Delivery Slicing first as the Phase 8 ceiling, then
-Architecture, Data Models, API Changes, Core Components, Security), forbids
-`<h1>` and any restatement of Epic Context/Goal/Scope, and mandates the
-`Slice | What ships | Independent?` table with a justification on every
-`Independent? No` row. Do not re-transcribe it here.
-
-### Step 3 — Author the risk verdict (Risk Assessor persona)
-
-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
-`.agents/schemas/risk-verdict.schema.json`:
-
-```json
-{
-  "axes": [
-    { "axis": "<axis>", "level": "low|medium|high", "rationale": "<why>" }
-  ],
-  "summary": "<one-paragraph overall risk narrative>"
-}
-```
-
-Axis vocabulary (fixed — the schema rejects anything else):
-
-- **Required axes** (presence forces a `required` acceptance disposition):
-  `visible-behavior`, `public-api`, `security`, `data-migration`,
-  `billing`, `destructive-mutation`, `critical-workflow`.
-- **Not-applicable axes** (when they are the only signals, the acceptance
-  spec is waived): `docs-only`, `test-harness`, `internal-refactor`.
-
-Authoring rules:
-
-- Include an axis only when the change **genuinely exercises it** — judge
-  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 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
-  when you can defend that in `summary`.
-- The harness owns the gate: the persist half derives `overallLevel` /
-  `requiresReview` / `acceptanceDisposition` / `gateDecision`
-  deterministically from your axes (`deriveRiskEnvelope`). You supply
-  judgment, not control flow.
-
-The derivation rules you are feeding (so you can anticipate the
-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 4 — Author the Acceptance Spec (Acceptance Engineer persona)
-
-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
-[`lib/bdd-scenario-scanner.js#scanBddScenarios`](../../../scripts/lib/bdd-scenario-scanner.js)
-and carries one row per `.feature` scenario found under the project's
-canonical BDD roots, with `{ file, line, scenarioTitle, tags,
-outcomeKeywords }`. Before emitting each AC row, run
-`findBestScenarioMatch(<AC outcome>, bddScenarios)`: when a match is
-found, annotate the AC's `Scenario` column with `<file>:L<line>` and
-set `Disposition` to `unchanged` (carried through verbatim) or
-`refined` (Outcome wording adjusted but the scenario already covers the
-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 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 Table — waived (planner-selected)`.
-
-Write to `temp/epic-<Epic_ID>/acceptance-spec.md`. The Acceptance Spec
-MUST:
-
-- 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
-  IDs do not shift).
-- Tag every row's `Disposition` with one of the canonical enum values:
-  `new` (first appearance), `updated` (Outcome text or Scenario reshaped
-  vs. prior plan), `unchanged` (carried through verbatim from prior plan).
-- Cite proposed feature files under `tests/features/**` by relative path
-  so the Phase 8 features-first Story can scaffold the matching scenarios.
-- Render a **Runner Verification** line directly under the AC table that
-  records what `bddRunner` from the planner-context envelope reports:
-  - `supported: true` → write
-    `Runner Verification: <runner> supports <pendingTag>` (e.g.
-    `playwright-bdd supports @skip`). The features-first Story will tag
-    pending scenarios with this exact string.
-  - `fallback: true` → write
-    `Runner Verification: Fallback: dependencies-first ordering (reason: <reason>)`.
-    Phase 8 still proceeds; AC reconciliation defers to dependency order.
-
-Apply the `systemPrompts.acceptanceSpec` string from the emitted envelope
-verbatim — it is the single source (rendered from
-`lib/templates/spec-author-prompts.js`). It mandates the
-`AC ID | Outcome | Feature File | Scenario | Disposition` table, stable
-`AC-<n>` IDs that survive re-plans, one Outcome per user-visible behaviour
-anchored to a specific Epic `## Acceptance Criteria` bullet, complete and
-auditable anchor coverage, and Conventional-Commits subjects (no
-`baseline-refresh` subject prefix). Do not re-transcribe it here.
-
-### Step 5 — Hand back to `/plan`
-
-All three files exist; return. The caller will run
-`node .agents/scripts/plan-persist.js --epic <Epic_ID>
---tech-spec temp/epic-<Epic_ID>/techspec.md
---risk-verdict temp/epic-<Epic_ID>/risk-verdict.json
---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
-
-- Do **not** modify GitHub issues from this Skill. Persistence is the
-  script's job; the Skill is pure markdown authoring.
-- Do **not** open files outside `temp/epic-<Epic_ID>/` for write. Reads
-  may cover anything `docsContext` references plus the planner-context
-  JSON itself.
-- If `temp/epic-<Epic_ID>/planner-context.json` is missing, **fail
-  loudly** — instruct the caller to run `--emit-context` first. Do not
-  silently fabricate a context.
-- Respect the planning-context budget: when `epic.body` is `null` and
-  `epic.bodySummary` is present, work from the summary rather than
-  re-fetching the full body. The budget cap is deliberate.