mandrel 1.94.0 → 2.1.0

package/.agents/workflows/plan.md

@@ -1,171 +1,303 @@
 ---
 description:
-  Unified planning entry point. Routes a seed idea (via scope triage) or an
-  existing Epic ID to the right planning path — the 3-step Epic path
-  (interrogate → author → persist) or the standalone-Story authoring path —
-  and absorbs every planning flag.
+  Unified planning entry point. Interrogate → author → persist. Emits one
+  Story by default (folded Tech Spec in the Story body); splits into N>1
+  only under the default-single split policy.
 ---
 
-# /plan [Epic ID] | --idea "<seed>" | --from-notes <path>
+# /plan --seed "<text>" | --seed-file <path> | --tickets <ids>
 
 ## Role
 
-Router. `/plan` owns argument parsing and path selection only — all step
-content lives in the two path helpers:
+Single planning path. `/plan` owns the full ceremony — there is no
+Epic/Story router, no scope-triage `epic|story` verdict, and no
+`deliveryShape`. Two operator modes only:
 
-- [`helpers/plan-epic.md`](helpers/plan-epic.md) — the 3-step Epic planning
-  path (interrogate → author → persist; Tech Spec + Acceptance Table folded
-  into the Epic body, then the Story backlog or a single-delivery marker).
-- [`helpers/plan-story.md`](helpers/plan-story.md) — the standalone-Story
-  authoring path (context envelope → host-LLM draft → HITL → issue create).
+1. **Text** — seed from chat or a file.
+2. **Tickets** — analyze existing issue(s) into proper Stories.
 
-The existing **scope-triage skill**
-([`core/scope-triage`](../skills/core/scope-triage/SKILL.md), verdicts
-`epic | story | borderline`) is the router's classifier on the `--idea`
-path; no new classification machinery exists.
+Audit findings become Stories via [`/audit-to-stories`](audit-to-stories.md)
+(separate workflow), which hands off with `--emit-plan-seed` →
+`/plan --seed-file <path>`.
 
 ## Inputs
 
 | Invocation | Behavior |
 | --- | --- |
-| `/plan --idea "<seed>"` | Ideation → **scope triage**. Verdict `epic` → run [`helpers/plan-epic.md`](helpers/plan-epic.md) from its ideation entry. Verdict `story` → run [`helpers/plan-story.md`](helpers/plan-story.md) Phases 1–3. Verdict `borderline` → present both options and let the operator choose. |
-| `/plan <epicId>` | Existing-Epic path — run [`helpers/plan-epic.md`](helpers/plan-epic.md) from its existing-Epic entry. When the helper's story-sized advisory fires (the Epic is really one Story), convert **internally** by switching to [`helpers/plan-story.md`](helpers/plan-story.md) — do not re-triage and do not hop commands. |
-| `/plan --from-notes <path>` | Internal handoff target (e.g. from `/audit-to-stories`). The notes file already encodes the path decision; do **not** re-run scope triage. Route per the notes' declared shape. |
+| `/plan --seed "<text>"` | Ideation from chat text: interrogate → author **one Story by default** → persist. |
+| `/plan --seed-file <path>` | Author from on-disk notes / plan seed (e.g. audit-to-stories handoff). |
+| `/plan --tickets 123[,456…]` | Fetch issue(s), analyze into proper Stories (prefer N=1 rewrite). |
+
+`--body` is **not** a `/plan` entry. Persist always goes through
+`plan-persist.js --stories …`.
 
 ## Flags
 
-`/plan` absorbs every planning flag and forwards it to the active path
-helper:
-
-| Flag | Path | Meaning |
-| --- | --- | --- |
-| `--idea "<seed>"` | both | Seed text; triggers scope triage. |
-| `--from-notes <path>` | both | Pre-triaged handoff notes; skips triage. |
-| `--force` | Epic | Re-plan: overwrite managed sections in place and close + recreate the ticket tree. |
-| `--amend` | Epic | Change-request delta persist: tickets carry `op: add\|modify\|keep\|close`; close ops require `--explicit-delete` after the dry-run diff. |
-| `--force-review` | Epic | Force the gate #2 operator review even when risk routing would skip it. |
-| `--allow-over-budget` | Epic | Permit a decomposition that exceeds the framework `maxTickets` reviewability budget. |
-| `--yes` | both | **Non-interactive / headless mode.** Deterministically auto-proceeds the two `/plan` HITL STOP gates — gate #1 (exit of interrogate) and gate #2 (risk-routed pre-persist review) — without waiting for operator input. Parallel to [`/deliver --yes`](deliver.md). Composes with `--allow-over-budget` and with the risk-routed gate #2 skip (it forces a proceed where those do not apply). Default (flag absent) behavior is unchanged: both gates still STOP for interactive use. |
-| `--steal` | Epic | Forcibly transfer a foreign Epic-lease. |
-| `--resume` | Epic | Continue a partial persist (rate-limit / crash recovery). |
-| `--dry-run` | Story | Author + validate without GitHub writes (`story-plan.js --dry-run`). |
-| `--body <path>` | Story | Pre-authored Story body file; validate (and create, unless `--dry-run`) without re-authoring. |
-| `--persona <name>` | Story | Override the persona label on the drafted Story. |
-| `--refine` / `--no-refine` | Story | Toggle the draft refinement loop. |
-
-**Cross-path flags are no-ops with a warning.** An Epic-only flag passed on
-the story path (or vice versa) is reported once
-(`[plan] --force has no effect on the story path`) and ignored — never an
-error. The historical bidirectional escalation between the two planning
-commands (story-sized Epic ↘ Story; epic-sized Story draft ↗ Epic) is an
-**internal branch switch** inside this router: same skills, same helpers, no
-command hop and no operator re-entry.
-
-### Headless / non-interactive mode (`--yes`)
-
-`--yes` is the headless escape hatch for an unattended driver (CI, a
-benchmark harness, or any `claude -p` run with no human at the keyboard). It
-is the `/plan`-side parallel of [`/deliver --yes`](deliver.md). `/plan` has
-exactly **two** HITL STOP gates, and `--yes` deterministically auto-proceeds
-**both** without waiting for operator input:
-
-1. **Gate #1 — the exit of the interrogate step.** One conceptual gate with
-   a face per entry form, and `--yes` auto-proceeds all of them:
-   - On the `--idea` Epic path, the interrogate step of
-     [`helpers/plan-epic.md`](helpers/plan-epic.md) STOPs to confirm the
-     sharpened one-pager, folding in the scope-triage verdict and the
-     duplicate-candidate review.
-   - On the `--idea` Story path,
-     [`helpers/plan-story.md`](helpers/plan-story.md) Phase 2 STOPs to
-     confirm the drafted Story body.
-   - On the existing-Epic (`/plan <epicId>`) path, the interrogate step
-     STOPs to confirm the folded re-plan / clarity-refinement / advisory
-     outcomes (the Clarity Gate's refined-body diff among them).
-
-   Under `--yes` each resolves as **approved**, and a `story` /
-   `borderline` triage verdict resolves to its **Recommended** branch rather
-   than prompting the three-way choice. **The interrogation itself runs
-   exactly one bounded pass**: no operator questions are asked — facts come
-   from the codebase, and every unresolved unknown lands in the one-pager's
-   **Key Assumptions** section instead of a question, so a headless driver
-   can never hang inside a free-form interrogation. On the `--idea` Epic
-   path this bounded pass IS the seed entry (#4496): `plan-context.js
-   --seed` replaces the idea-refinement prelude, and the one-pager is
-   authored in the same batched write as the spec artifacts. The verdict / clarity
-   scoring is still recorded in chat (one line); only the *wait* is
-   suppressed — the deterministic clarity *scoring* inside the
-   `plan-context.js` envelope always runs.
-2. **Gate #2 — the risk-routed pre-persist review.** When the authored risk
-   verdict routes to review (high risk, or the operator also passed
-   `--force-review`), [`helpers/plan-epic.md`](helpers/plan-epic.md) step 3
-   STOPs for operator approval of the assembled plan (spec, tickets, risk,
-   and `deliveryShape` in one view) before the persist CLI runs. Under
-   `--yes` this review auto-proceeds straight to the persist call, exactly
-   as on the low-risk auto-proceed branch.
-
-**Composition.** `--yes` is orthogonal to the other planning flags and
-composes cleanly:
-
-- With **`--allow-over-budget`**: `--yes` suppresses the gate *waits* while
-  `--allow-over-budget` still governs the `maxTickets` over-budget persist —
-  passing `--yes` alone does **not** waive the budget gate.
-- With the **risk-routed gate #2 skip**: when risk routing already
-  auto-proceeds the review (low-risk, no `--force-review`), `--yes` is a
-  no-op for that gate — it only *forces a proceed where the gate would
-  otherwise STOP*, it never *adds* a stop or relaxes any non-HITL validator.
-
-**`--yes` suppresses only the HITL operator *waits* above.** It does **not**
-relax any deterministic gate — the clarity scoring, the Tech Spec section
-gate, the ticket validator / file-assumption / DAG / budget gates, the
-inline readiness healthcheck, and the `agent::blocked` runtime pause all
-behave exactly as without the flag; it is an operator-input suppressor, not
-a validation override. A `--yes` run that hits one of those still fails
-closed. The smaller operator-input waits folded into the two gates — the
-duplicate-candidate review, the clarity refinement-diff confirm, and the
-advisory critic diffs — auto-proceed for the same headless reason.
+| Flag | Meaning |
+| --- | --- |
+| `--seed "<text>"` | Seed text for ideation. |
+| `--seed-file <path>` | Pre-authored notes / plan-seed path. |
+| `--tickets <ids>` | Comma-separated issue ids to analyze. Closed as superseded at persist (see below). |
+| `--no-close-superseded` | Keep the `--tickets` source issues open — no supersede comment, no close. |
+| `--force-review` | STOP at gate #2 for operator review of the assembled plan. The only thing that gates review — there is no risk-derived routing (Story #4542). |
+| `--allow-over-budget` | Permit a plan that exceeds `maxTickets` (rare N>1). |
+| `--yes` | Non-interactive: auto-proceed gate #1 and gate #2 HITL waits. |
+| `--dry-run` | Author + validate without GitHub writes. Run it as a pre-pass before every real persist (see below). |
+
+## Default-single split policy
+
+Author **one Story** unless:
+
+1. the pieces have **near-zero overlap** (genuinely independent capabilities), or
+2. there is an **architectural seam** (different deployables, migration vs consumer).
+
+Coupled work stays one Story — decompose it inside `## Slicing` as
+intra-session checkpoints, not sibling tickets. When N>1, every acceptance
+criterion must belong to exactly one Story; `plan-persist` runs
+`assertAcceptancePartition` and refuses coupled splits.
+
+**N=1 is the lean path:** one authoring prompt, folded `## Spec` in the
+Story body, light risk/critic profile. Do not run Epic-scale decompose,
+clarity, or reconciler ceremony for a single Story.
 
 ## Procedure
 
-1. **Parse args.** Exactly one of `<epicId>`, `--idea`, `--from-notes`, or
-   `--body` must be present; anything else is a usage error naming the four
-   forms. A `--body` invocation routes to the story path (no triage).
-2. **Triage (idea path only).** Attended: run the
-   [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) skill on the
-   seed. Record the verdict in chat (one line). **Under `--yes`, do not
-   Read the skill**: delegate straight to
-   [`helpers/plan-epic.md`](helpers/plan-epic.md)'s ideation entry — its
-   `plan-context.js --seed` envelope carries the rubric's verdict applied
-   CLI-side (`scopeTriage`), and a `story` / `borderline` verdict resolves
-   to the Recommended handoff from inside the helper (see
-   [`helpers/scope-triage-gate.md`](helpers/scope-triage-gate.md)).
-3. **Delegate.** Read the selected path helper **in full** and execute it
-   from its entry, forwarding the absorbed flags (including `--yes`). The
-   helper's steps, HITL gates, and scripts are the procedure — this router
-   adds no step content. When `--yes` is present, the two HITL STOP gates
-   auto-proceed per [Headless / non-interactive mode](#headless--non-interactive-mode---yes)
-   above; every deterministic gate still runs. **Under `--yes`, when the
-   helper content is already injected or present in context, execute it
-   directly — do not spend a separate read-in-full turn re-reading content
-   you already hold.**
-4. **Internal returns.** When a path helper would historically have handed
-   off to the other planning command, switch helpers in-place and continue;
-   surface the switch to the operator as a one-line note.
+### 1. Interrogate
+
+```bash
+node .agents/scripts/plan-context.js --seed "<seed>" \
+  --out temp/plan-<slug>/plan-context.json
+# or: --seed-file <path>
+# or: --tickets 123,456
+```
+
+**Always pass `--out temp/plan-<slug>/plan-context.json`.** The CLI writes the
+envelope there (creating parent dirs); persist auto-discovers that file from
+`--plan-dir` and derives the `--tickets` source ids from its `sourceTickets[]`.
+That is what makes superseding work without anyone re-typing ids
+(Story #4554). The envelope still goes to stdout too, so piping is unaffected.
+
+The envelope carries docs context, codebase snapshot, BDD probe, risk
+heuristics, the story-author system prompt, `sourceTickets[]` (`--tickets`
+mode), and `duplicates[]` (open **Stories** whose title/body overlap the
+seed — never Epics).
+Under `--yes`, do not ask free-form operator questions — unresolved
+unknowns land in Key Assumptions.
+
+**Gate #1** — STOP to confirm the sharpened plan intent and any
+duplicate-candidate review. Under `--yes`, auto-proceed.
+
+### 2. Author
+
+Write artifacts under `temp/plan-<slug>/`:
+
+- `stories.json` — array of Story tickets (**length 1 by default**). Each
+  body uses the canonical `story-body` shape (`## Goal`, optional
+  `## Slicing`, optional `## Spec`, `## Changes`, `## Acceptance`,
+  `## Verify`, …). The Story is the single executable document: put lean
+  approach prose in `## Spec`, binding criteria in top-level
+  `acceptance[]` / `verify[]` (persist syncs them into the body). Do not
+  restate Goal/Acceptance inside Spec. Over-budget Specs fail closed —
+  split the Story or tighten Spec; never write Specs under `docs/`.
+- optional `techspec.md` — **N===1 only** convenience when Spec was authored
+  outside the Story JSON; persist folds it into that Story's `## Spec`.
+  Forbidden for N>1 (each Story must carry its own Spec).
+- optional `acceptance-manifest.json` — plan-level AC list (a JSON
+  `string[]`) for partition coverage when N>1. Pass it to persist as
+  `--plan-acceptance` or it is not read.
+
+For N=1, use the envelope `systemPrompts.story` and emit one cohesive
+Story. Split only under the policy above.
+
+**Tickets mode — author `supersedes[]` on every Story.** In `--tickets`
+mode each Story carries a top-level `supersedes` array claiming the source
+issues it replaces. It is bookkeeping, not part of the Story body, so it is
+never serialized into the markdown:
+
+```jsonc
+{
+  "slug": "close-superseded",
+  "supersedes": [
+    4525,
+    { "id": 4529, "note": "The filed `--changed-only` fix is provably inert; the correction is recorded here." }
+  ]
+}
+```
+
+Entries are bare issue numbers, or `{ id, note }` when the plan has
+something to say about *that* source issue — a correction to its analysis,
+or why it was folded in with others. The optional `note` is rendered into
+that issue's supersede comment, so planning that materially corrects a
+source issue records the correction on the ticket rather than emitting
+template-only prose.
+
+### Supersede-map partition
+
+`plan-persist` refuses a partial supersede map **before** it creates any
+Story (mirroring `assertAcceptancePartition`): every id passed to
+`--tickets` must be claimed by **exactly one** Story, and no Story may
+claim an id that was not a source ticket. With N>1 the mapping is not
+total by default — an authored map is the only thing that can say
+`#4525-#4528 → #4530` while `#4529 → #4531`, which a blanket "superseded by
+this plan-run" reference could not.
+
+### 3. Persist
+
+**Gate #2** — when the operator passed `--force-review`, STOP for approval of
+the assembled plan before persist. Under `--yes`, auto-proceed.
+
+`--force-review` is the **only** thing that raises this gate. Story #4542
+retired the risk-derived alternative: the planner authored its own risk verdict,
+persist computed a `requiresStop` from it *after* `createStoryIssues` had already
+run, and nothing read the result — the STOP was prose executed by the same
+session that wrote the verdict. A gate a plan can lower for itself is not a gate.
+
+#### Dry-run pre-pass (always)
+
+Run persist with `--dry-run` **before** the real one. It is the same command
+with the same flags — only the GitHub writes are suppressed:
+
+```bash
+node .agents/scripts/plan-persist.js \
+  --stories temp/plan-<slug>/stories.json \
+  [--plan-acceptance temp/plan-<slug>/acceptance-manifest.json] \
+  [--tech-spec temp/plan-<slug>/techspec.md] \
+  --plan-dir temp/plan-<slug> \
+  --dry-run
+```
+
+Every gate — ticket validator, body parse, subject-prefix, DAG, capacity,
+budget, reachability, split-policy and supersede partitions, Spec fold —
+runs **before** the first `createIssue`, so a dry-run exercises all of them
+write-free. An authoring mistake surfaces here, where the fix costs one
+re-author, instead of after `k` of `N` Stories are already live.
+
+#### The real persist
+
+```bash
+node .agents/scripts/plan-persist.js \
+  --stories temp/plan-<slug>/stories.json \
+  [--plan-acceptance temp/plan-<slug>/acceptance-manifest.json] \
+  [--tech-spec temp/plan-<slug>/techspec.md] \
+  [--plan-dir temp/plan-<slug>] \
+  [--plan-context temp/plan-<slug>/plan-context.json] \
+  [--source-tickets 123,456] \
+  [--no-close-superseded] \
+  [--force-review] \
+  [--allow-over-budget]
+```
+
+Pass `--plan-acceptance` whenever step 2 wrote an `acceptance-manifest.json`
+— it is what `assertAcceptancePartition` checks the N>1 split against.
+
+Persist creates Story issue(s) with `type::story` (plus any sanitized
+authored `labels[]`) and, when N>1, writes each authored `depends_on` edge
+into the sibling's body as a `blocked by #<id>` footer — the ordering
+`/deliver` resolves from. No batch label is applied (Story #4540 retired
+`plan-run::<id>`). Ends by naming the exact command:
+`/deliver <storyId> [<storyId> ...]`.
+
+stdout is a pure JSON result; all log lines go to stderr, so a headless
+driver can `JSON.parse` the stdout stream directly.
+
+#### Ready means fully persisted
+
+`agent::ready` is the **terminal** step, not part of the creating POST
+(Story #4541). The order is: create unlabelled → upsert `story-plan-state` on
+every Story → upsert `plan-summary` on the primary → flip every Story to
+`agent::ready`.
+
+This is what lets `/deliver` trust the label: a Story carrying
+`agent::ready` always has its persist receipt on the ticket, so nothing can
+pick it up mid-write and read a half-persisted plan.
+
+#### Resuming a failed persist
+
+Persist is **idempotent over the same authored artifacts**. Each created body
+carries an invisible plan fingerprint (derived from the Story's slug +
+title), and persist indexes the open `type::story` backlog by it before
+creating anything.
+
+So if a transient GitHub failure strands the run at Story `k` of `N`:
+
+| | Behaviour |
+| --- | --- |
+| The `1..k-1` Stories | Live, but **not** `agent::ready` — invisible to `/deliver`, not half-delivered. |
+| Re-running persist | Adopts them by fingerprint, creates only the missing ones, then flips the whole cohort ready. |
+| Editing `stories.json` first | Changing a slug or title changes the fingerprint — the old issue is orphaned rather than adopted. Close it by hand. |
+
+Just re-run the same command. Do not hand-delete the stranded issues first.
+
+#### Temp hygiene
+
+A terminal-success run deletes its own `--plan-dir`. Every persist also reaps
+abandoned `temp/plan-*` directories older than 7 days, so dry-runs, failed
+gates, and abandoned authoring sessions do not accumulate under `temp/`.
+
+### How the source ids reach persist
+
+In `--tickets` mode persist needs to know which ids were fetched. It resolves
+them **envelope-first** (Story #4554):
+
+| Channel | When it wins |
+| --- | --- |
+| Envelope `sourceTickets[]` | **The normal path.** Written by step 1's `--out`, then read from `--plan-context <file>` or auto-discovered at `<plan-dir>/plan-context.json`. No ids to re-type. |
+| `--source-tickets <ids>` | Explicit **override** for hand-driven runs (no captured envelope, or deliberately narrowing the set). Wins over the envelope; a disagreement is warned about, not silently reconciled. |
+
+The result envelope's `supersede.sourceTicketOrigin` reports which channel was
+used (`envelope` \| `flag` \| `none`).
+
+Every path with no envelope is **audible** — persist cannot tell a legitimate
+`--seed` run from a `--tickets` run whose envelope was never captured, so it
+says so rather than deciding silently:
+
+| Situation | Behaviour |
+| --- | --- |
+| Neither `--plan-dir` nor `--plan-context` | **Warn** — nothing was read; only `--source-tickets` can supply ids. |
+| Auto-discovered `<plan-dir>/plan-context.json` absent | **Warn** — degrade to `--source-tickets`; a `--seed` run legitimately has none. |
+| Explicit `--plan-context` missing | **Fatal** — the operator named a file and meant it. |
+| Envelope present but unparseable | **Fatal** — a corrupt envelope is not "no source tickets"; treating it as such is how a `--tickets` run used to report success having superseded nothing. |
+
+Whichever channel supplies them, the supersede-map partition above still
+fail-closes: a `--tickets` run whose Stories forgot `supersedes[]` is now
+**caught** (`source ticket #N is not claimed by any Story`) instead of
+partitioning an empty set and passing vacuously.
+
+### Closing superseded source tickets
+
+**Default on.** After the Stories exist, persist comments on each source
+issue naming the specific Story that claims it — plus that Story's optional
+per-supersede `note` — and closes it with reason **`not_planned`**
+(`state_reason`). Nothing has shipped at persist time and the issue will not
+be actioned in its own right, so `not_planned` is the honest reason;
+`completed` would be a lie. This is what keeps the tracker from asserting
+that already-planned work is still unowned, and it writes down the supersede
+link that makes the history readable.
+
+| Behaviour | Contract |
+| --- | --- |
+| Default | Comment + close every source ticket as `not_planned`. |
+| `--no-close-superseded` | Skips all commenting and closing. Story creation is unchanged. Use it for a genuinely partial supersede — when the plan folded in only *part* of an issue and the remainder must stay open. |
+| `--dry-run` | Posts no comment and closes nothing; reports what it would have done. |
+| Re-run | Idempotent — the comment is keyed off a `superseded-by` structured-comment marker, and an already-closed source is skipped. |
+| Already closed / deleted / inaccessible | Skipped and reported. Never throws. |
+| Close-phase failure | **Never fails the run.** Stories stay created; the result envelope's `supersede` report names which tickets were and were not closed so the operator can finish by hand. |
+
+`--seed` / `--seed-file` modes have no source tickets, so no close phase
+runs at all.
 
 ## Constraints
 
-- The plan→deliver boundary stays a hard stop: `/plan` never starts
-  delivery. It ends by naming the follow-up — `/deliver <epicId>` for a
-  planned Epic, `/deliver <storyId>` for a standalone Story.
-- The router never calls planning scripts directly; the path helpers own
-  every script invocation.
-- Checkout hygiene (branch sweep) and day-0 doc readiness are owned by
-  [`/git-cleanup`](git-cleanup.md) and `mandrel doctor` respectively —
-  `/plan` runs no boot sweep and no first-run preflight.
+- `/plan` never starts delivery.
+- No Epic ticket is opened. No reconciler. No `delivery::single` marker.
+- Duplicate search targets open Stories (`type::story`), not Epics.
+- Deterministic gates (ticket validator, split policy, reachability, budget)
+  still fail closed under `--yes`.
 
 ## See also
 
-- [`/deliver`](deliver.md) — the unified delivery entry point. Accepts a
-  single Epic, one or more standalone Stories, or any mix of ≥1 Epics and
-  standalone Stories — mixed sets compose a sequential segment plan.
-- [`helpers/plan-epic.md`](helpers/plan-epic.md) /
-  [`helpers/plan-story.md`](helpers/plan-story.md) — the path helpers.
+- [`/deliver`](deliver.md) — delivery entry point (`/deliver <storyId>`).
+- [`/audit-to-stories`](audit-to-stories.md) — audit findings → plan seed →
+  `/plan --seed-file`.
+- [`core/scope-triage`](../skills/core/scope-triage/SKILL.md) — optional
+  split-advisory notes only (no routing verdict).

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

@@ -21,7 +21,7 @@ high-quality, triage-ready ledger. The session has four movements:
    a final review of the **entire** ledger and asks any last clarifying
    questions.
 4. **Triage & Plan** (Phase 4) — only then does the agent route the full ledger
-   into [`/plan`](plan.md) to generate Epics and/or Stories.
+   into [`/plan`](plan.md) to generate Stories.
 
 Unlike [`/qa-explore`](qa-explore.md) (where the *agent* drives open-ended
 exploration of a named surface), `/qa-assist` is **human-led**: the human owns
@@ -45,16 +45,14 @@ never reimplements those decisions in prose.**
 > triage-ready finding without breaking stride — then, when the testing pass is
 > done, turned into a plan in one batch.
 >
-> **Persona**: `qa-engineer` · **Skills**: `core/qa-coverage-mapping`
+> **Skills**: `core/qa-coverage-mapping`
 
-## Persona
+## Role framing
 
-Adopt the **`qa-engineer`** persona
-([`.agents/personas/qa-engineer.md`](../personas/qa-engineer.md)) for the whole
-run. You are the quality gatekeeper: you value coverage, hermetic
-environments, deterministic results, and — per that persona's Golden Rule —
-you **never invent the signal**. The human owns what was observed; you enrich
-it. Re-read that persona file as your first action.
+You are the quality gatekeeper for this run: value coverage, hermetic
+environments, and deterministic results. **Never invent the signal** — the
+human owns what was observed; you enrich it. Apply the QA skills; there is
+no separate persona pack.
 
 ## Slash Command
 
@@ -69,7 +67,7 @@ it. Re-read that persona file as your first action.
 | `observation` | no       | `"sync-commands wipes .claude on a reused name"` | An optional first observation, or a brain dump of several. **Usually omitted** — the normal launch is a bare `/qa-assist`, which does Setup and then waits. If supplied, run Setup first, then feed it in as the first intake (splitting it if it carries multiple observations). |
 
 A bare `/qa-assist` is the expected entry point. **Do not** demand an
-observation up front and **do not** synthesize one — the `qa-engineer` Golden
+observation up front and **do not** synthesize one — the QA Golden
 Rule forbids inventing the signal. Set up, announce ready, and wait.
 
 ## Project contract
@@ -140,7 +138,7 @@ ledger is hard-gated.**
 
 Goal: become the operator's QA assistant before any observation arrives.
 
-1. Re-read the `qa-engineer` persona.
+1. Re-read the QA role framing and `core/qa-coverage-mapping` skill.
 2. **Load codebase context.** Read the files in `project.docsContextFiles`
    (architecture, decisions, patterns) and, when the testing touches UI/routing,
    `docs/style-guide.md` / `docs/web-routes.md`. This is the context you will
@@ -226,13 +224,13 @@ every decision to the shared core helpers; never re-derive them in prose.
 
 3. **Hydrate the QA context** to locate code precisely, via
    [`qa-context-hydrator.js`](../scripts/lib/qa/qa-context-hydrator.js) — it
-   resolves the Epic (whose body carries the planning sections), the
+   resolves the source ticket body, the
    feature-file set, the surface
    map, and recent git log:
 
    ```js
    import { hydrateQaContext } from '../scripts/lib/qa/qa-context-hydrator.js';
-   const context = await hydrateQaContext({ epicNumber, githubPort, gitPort, surfaceMap });
+   const context = await hydrateQaContext({ ticketNumber, githubPort, gitPort, surfaceMap });
    ```
 
 4. **Compute the coverage verdict** for the surface the observation points at,
@@ -321,32 +319,28 @@ its transition is **explicitly operator-gated**.
    import { promoteFindings } from '../scripts/lib/findings/promote-finding.js';
    const { promotions } = await promoteFindings(ledgerItems, {
      searchIssues, // GitHub provider, open + closed
-     createStory, // tight cluster (≤2 surfaces): render seed → /plan --from-notes
-     createEpic, // broad cluster (>2 surfaces): render seed → /plan --idea
+     createStory, // tight cluster (≤2 surfaces): seed → /plan --seed-file
+     createPlanSeed, // broad cluster (>2 surfaces): same /plan --seed-file path (may N>1)
    });
    ```
 
    - **Sizing is delegated, not decided in prose.** `promoteFindings` runs
      `clusterLedgerItems` + `targetForCluster`: a cluster spanning **≤2**
      distinct coverage surfaces routes to `createStory`; **>2** routes to
-     `createEpic`. Do not re-cluster, re-size, or re-dedup in the workflow —
+     `createPlanSeed`. Neither port opens an Epic ticket — both chain
+     `/plan --seed-file`. Do not re-cluster, re-size, or re-dedup in the
+     workflow —
      [`route-finding.js`](../scripts/lib/findings/route-finding.js) /
      [`promote-finding.js`](../scripts/lib/findings/promote-finding.js) are the
      single implementation.
-   - **`createStory` (`/plan --from-notes`)** — render a **redacted**
-     `--from-notes` seed from the cluster (reuse the `/audit-to-stories`
-     Phase 5b notes shape; redaction already ran in Phase 2), **stamp the
+   - **`createStory` / `createPlanSeed` (`/plan --seed-file`)** — render a
+     **redacted** plan seed from the cluster (reuse the `/audit-to-stories`
+     Phase 5a seed shape; redaction already ran in Phase 2), **stamp the
      cluster's `fingerprintFooter(sha)` verbatim into the seed body**, then
-     chain `/plan --from-notes <seed>`. The footer must survive into the issue
-     body the Story create path writes — it round-trips through
-     `story-plan.js --body <file> --dry-run` unchanged (asserted by the
-     deterministic round-trip test under `tests/`) so a later `routeFinding`
-     dedups the same finding instead of re-filing it.
-   - **`createEpic` (`/plan --idea`)** — carry the cluster's
-     `fingerprintFooter(sha)` into the `/plan --idea` seed, then chain
-     `/plan --idea <seed>`. **Known limitation (not solved here):**
-     per-child-Story fingerprint propagation through full Epic decomposition is
-     *not* guaranteed — the fingerprint is carried in the Epic seed only.
+     chain `/plan --seed-file <seed>`. Prefer one Story; split only under
+     the default-single policy. The footer must survive into the issue body
+     so a later `routeFinding` dedups the same finding instead of re-filing
+     it.
    - **A `file` disposition never opens a raw GitHub Issue.** Every `file`
      finding flows through `promoteFindings` → `/plan`; only `defer` (carry
      forward as backlog) and `dismiss` (non-actionable) skip the handoff.
@@ -359,8 +353,8 @@ its transition is **explicitly operator-gated**.
 
 After planning, summarize: the findings recorded, the route/promotion decisions
 (`new`/`update-existing`/`duplicate`/`regression-of-closed`), whether each
-cluster became a Story (`/plan --from-notes`) or Epic (`/plan --idea`), and any
-`defer` backlog a resumed session will pick up.
+cluster became a Story via `/plan --seed-file`, and any `defer` backlog a
+resumed session will pick up.
 
 ---
 
@@ -404,7 +398,7 @@ cluster became a Story (`/plan --from-notes`) or Epic (`/plan --idea`), and any
   are deterministic — never re-derive them in prose.
 - **Promote through `/plan`, never a raw Issue.** A `file`-dispositioned
   finding is promoted via `promoteFindings`, which chains into
-  [`/plan`](plan.md) (`--from-notes` for a tight cluster, `--idea` for a broad
+  [`/plan`](plan.md) (`--seed-file` for a tight cluster, `--seed` for a broad
   one) — mirroring [`/audit-to-stories`](audit-to-stories.md). `/qa-assist`
   never opens a bare GitHub Issue for a `file` finding. The cluster's
   `fingerprintFooter(sha)` is stamped verbatim into the seed so a future
@@ -413,7 +407,7 @@ cluster became a Story (`/plan --from-notes`) or Epic (`/plan --idea`), and any
 ## See also
 
 - [`/plan`](plan.md) — the planning pipeline `/qa-assist` chains into in
-  Phase 4 (`--from-notes` for a Story, `--idea` for an Epic). The plan→deliver
+  Phase 4 (`--seed-file` / `--seed`). The plan→deliver
   hard stop is preserved across the handoff.
 - [`/qa-explore`](qa-explore.md) — the agent-led sibling that drives a named
   surface and triages through the same `/plan` handoff.