mandrel 1.94.0 → 2.1.0

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

@@ -1,160 +0,0 @@
----
-description: >-
-  Reference companion to plan-epic.md — the recovery procedures, --resume
-  mechanics, troubleshooting, and background rationale blocks moved out of the
-  runtime core so every /plan run ingests only the step flow. Read on demand
-  from the trigger-point pointers in plan-epic.md.
-caller: plan-epic.md
----
-
-# helpers/plan-epic-reference — Epic-planning reference & recovery
-
-> **Not a slash command.** This file lives in `helpers/` and is a
-> path-included reference module (not projected into the plugin command
-> tree). [`plan-epic.md`](plan-epic.md) is the runtime core — the 3-step
-> flow, commands, and gate contracts. This file holds the secondary material
-> a run needs only when it hits an edge (a recovery path, a troubleshooting
-> symptom) or wants the design rationale behind a persist guard.
-
-## Persist guards — background rationale
-
-The persist step's core carries only the commands and the ordered gate list.
-The design rationale for its guards and managed sections lives here.
-
-### Epic-lease preflight (workflow guard)
-
-Before any mutation, `plan-persist.js` acquires the Epic-lease via the
-assignee-as-lease primitive (`lib/orchestration/ticket-lease.js`). The lease
-rides the Epic's single assignee: the operator (`github.operatorHandle` in
-`.agentrc.json`) claims the Epic for the duration of the persist. The guard
-**fails closed**: `/plan` emits no `story.heartbeat` during its run, so any
-**foreign assignee** is treated as a live claim — the persist exits non-zero
-and names the current owner, so two `/plan` runs cannot drive the same Epic
-concurrently. Pass **`--steal`** to forcibly transfer a foreign claim once
-you have confirmed the other run is dead. An **unassigned** Epic, or one
-**already held by this operator**, is taken (or re-affirmed) silently. The
-lease is released on every exit path — success, gate failure, and throw
-alike.
-
-### Idempotent managed sections
-
-The persist is section-scoped and keyed on the Epic body: a re-run that
-finds the requested sections already present
-(`<!-- mandrel:tech-spec:start/end -->` /
-`<!-- mandrel:acceptance-table:start/end -->`) short-circuits as
-`already-planned` instead of duplicating content. Pass `--force` to
-overwrite the managed sections in place (same Epic issue, refreshed section
-bodies, one regeneration audit comment).
-
-### One planning document
-
-A `/plan` Epic run creates exactly **one** issue — the Epic. The planning
-artifacts land as marker-delimited managed sections of the Epic body: the
-Tech Spec (opening with `## Delivery Slicing`) inside
-`<!-- mandrel:tech-spec:start/end -->`, and the Acceptance Spec's AC-ID
-table (headed `## Acceptance Table`) inside
-`<!-- mandrel:acceptance-table:start/end -->`. The `## Acceptance Table`
-section captures the stable-ID acceptance criteria table
-(`| AC ID | Outcome | Feature File | Scenario | Disposition |`) that drives
-close-time reconciliation during `/deliver`. Operators may opt out for
-refactor-only or docs-only Epics by applying the `acceptance::n-a` label to
-the Epic — the authoring skill then skips the Acceptance Table and the
-runtime gates honour the waiver. See
-[SDLC § Acceptance Table — the second folded planning section](../../docs/SDLC.md#acceptance-table--the-second-folded-planning-section)
-for the full lifecycle.
-
-### Parallel-safe file naming (per-Epic tree)
-
-Multiple Epics may be planned concurrently. Every temp file written in the
-workflow lives under the per-Epic tree (`temp/epic-[Epic_ID]/<artifact>`) —
-e.g. `temp/epic-[Epic_ID]/plan-context.json`,
-`temp/epic-[Epic_ID]/techspec.md`, `temp/epic-[Epic_ID]/tickets.json`. The
-directory namespace is the isolation boundary; basenames inside it are
-stable. (The ideation entry, which has no Epic id yet, namespaces under
-`temp/plan-ideation/<slug>/` instead.) Do **not** reuse bare flat names like
-`temp/techspec.md`.
-
-**Durability.** The per-Epic tree is durable across runs: `plan-persist.js`
-cleans its temp files **only at terminal success**
-([`lib/plan-phase-cleanup.js`](../../scripts/lib/plan-phase-cleanup.js)), so
-a failed persist leaves every authored artifact in place for `--force` /
-`--resume` reuse. Nothing else garbage-collects the tree.
-
-## Persist — `--resume` recovery (secondary rate limit)
-
-**Secondary rate limit on large Epics.** For backlogs over ~60 tickets,
-GitHub's secondary rate limit (HTTP 403, body contains "secondary rate
-limit") can trip mid-persist after ~80 issue creations. The http-client
-retries automatically with a 30–120s backoff. If the run still aborts
-(network drop, exhausted retries, etc.), resume from the partial backlog
-with:
-
-```bash
-node .agents/scripts/plan-persist.js --epic [Epic_ID] --resume
-```
-
-`--resume` is idempotent: the managed sections short-circuit
-`already-planned`, and the reconciler recovers the slug→issue map from its
-per-slug state ledger (`temp/epic-[Epic_ID]/[Epic_ID].state.json`) —
-reseeding from live GitHub state when the file is missing — so only the
-genuinely-missing children are created; the existing tree is never
-duplicated.
-
-## Measurement — the G2 acceptance gate (Epic #4474, restated per #4496)
-
-The 3-step collapse is **measured, not asserted**. The gate is stated
-**per mode** (#4496 — adopted in the bench roadmap after the first measured
-headless run):
-
-- **Epic-mode** (`/plan <id> --yes`): **≤ ~12 turns / ≤ ~1.1M tokens**.
-- **Ideation-mode** (`/plan --idea --yes`): **≤ ~15 turns / ≤ ~1.5M
-  tokens** once the #4496 fixes (seed-mode ideation, authoritative persist
-  summaries, batched artifact writes) are in play; **interim smoke
-  threshold ≤ ~20 turns / ≤ ~2.0M tokens** for runs measured before/during
-  the rollout.
-- Verification is a cheap direct `/plan --idea --yes` probe reading the
-  plan-metrics ledger (~$3–4), not a full bench cell.
-
-Shared mechanics behind both rungs (from the 55–72-turn / 7.3–8.9M
-12-phase baseline):
-
-- The turns proxy is the plan-metrics invocation ledger
-  (`temp/epic-<id>/plan-metrics.json`) plus the host session's turn
-  accounting — ledger records count CLI invocations from the parent
-  session's perspective, not sub-agent turns.
-- Plan tokens are owned by the host's session accounting (mandrel-bench
-  `modelUsage`), not by any in-repo counter.
-- **Unchanged validator coverage** — every deterministic gate of the
-  retired pipeline still fires on the persist path: section gate, ticket
-  validator, file-assumption, DAG, budget, draft reachability, inline
-  healthcheck, mode-coherence. The enumerated receipt is
-  `tests/contract/planning/plan-persist-validator-coverage.test.js`.
-
-Where to read the measurement:
-
-- The `plan-summary` structured comment on the Epic carries the
-  plan-metrics roll-up line (invocations, per-CLI counts, span, critic
-  skips) — no runner-disk access needed.
-- `node .agents/scripts/analyze-execution.js --epic <id> --plan-metrics-json`
-  prints the compact machine-readable envelope
-  (`{ epicId, planMetrics, summaryLine }`) — local read-only, stdout-pure.
-
-## Troubleshooting
-
-- If `plan-context.js` fails, confirm the Epic exists and has a body with
-  enough initial context (epic mode), or that the one-pager file is
-  non-empty (ideation mode).
-- If `plan-persist.js` rejects the tickets file, re-read the validator's
-  error message — the most common causes are a ticket whose `type` is not
-  `story`, a Story missing its inline `acceptance[]` / `verify[]` contract,
-  a file-assumption declaration that contradicts the base branch, or a
-  dependency cycle in the Story `depends_on` graph.
-- If `plan-persist.js` refuses with a mode-coherence error, the risk
-  verdict's `deliveryShape` contradicts the tickets payload — a `"single"`
-  verdict with a `tickets.json` on disk (delete or re-shape it), or a
-  fan-out verdict with no tickets authored.
-- If the persist completed but the Epic is not on `agent::ready`, the
-  inline healthcheck refused the flip — read the failing check's `reason`
-  in the persist output, resolve it (or apply
-  `planning::healthcheck-waived` for a triaged environmental failure), and
-  re-run the persist.

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

@@ -1,353 +0,0 @@
----
-description:
-  Epic planning path invoked by /plan — three steps (interrogate → author →
-  persist) that produce the Epic body's Tech Spec + Acceptance Table managed
-  sections and the Story backlog (or a single-delivery routing marker).
----
-
-# helpers/plan-epic — Epic planning path (invoked by /plan)
-
-## Shape
-
-Three steps replace the retired 12-phase pipeline (Epic #4474). All GitHub
-reads concentrate in `plan-context.js` (step 1), all GitHub writes in
-`plan-persist.js` (step 3); the authoring middle reads one JSON envelope and
-writes 2–4 files. Exactly two HITL STOP gates: **gate #1** at the exit of
-interrogate, **gate #2** risk-routed before persist. Every deterministic
-validator of the old pipeline survives inside the persist CLI.
-
-## Constraints
-
-- Do not modify existing issues without explicit permission. Every GitHub
-  mutation runs inside `plan-persist.js` — or `epic-plan-clarity.js` for a
-  gate-#1-approved body refinement — never via ad-hoc `gh issue edit`.
-- Never bypass a persist rejection by editing GitHub directly: fix the named
-  artifact and re-run the CLI (one targeted amend pass, below).
-
-## Step 1 — Interrogate
-
-Goal: shared understanding and a confirmed planning basis. Grilling
-discipline: ask questions **one at a time** — asking multiple questions at
-once is bewildering. If a **fact** can be found by exploring the codebase,
-look it up rather than asking; the **decisions** are the operator's — put
-each one to them. Do not proceed to authoring until shared understanding is
-confirmed (gate #1).
-
-### Ideation entry (`--idea "<seed>"` or no argument)
-
-**Attended (no `--yes`)** — the interactive grill loop is HITL by
-definition and stays:
-
-1. Activate the [`core/idea-refinement`](../../skills/core/idea-refinement/SKILL.md)
-   skill with the seed. It returns a one-pager with the canonical sections
-   (Problem Statement, Recommended Direction, Key Assumptions, MVP Scope,
-   Not Doing). Write it to `temp/plan-ideation/<slug>/one-pager.md` (slug
-   from the title; the tree is gitignored).
-2. Emit the authoring envelope:
-
-   ```bash
-   node .agents/scripts/plan-context.js \
-     --one-pager temp/plan-ideation/<slug>/one-pager.md \
-     > temp/plan-ideation/<slug>/plan-context.json
-   ```
-
-   The ideation envelope carries `duplicates[]` (cross-Epic dup search),
-   `deliveryShapeSignal`, `docsContext`, `codebaseSnapshot`, `ticketSchema`,
-   and the rendered `systemPrompts`. The Epic does **not** exist yet —
-   creation happens in step 3.
-3. Run the shared scope-triage gate over the one-pager — mechanics in
-   [`scope-triage-gate.md`](scope-triage-gate.md). The verdict folds into
-   gate #1. The Recommended branch on a `story` / `borderline` verdict:
-   persist the one-pager as a notes file and hand off to
-   [`plan-story.md`](plan-story.md) via `/plan --from-notes <path>` as a
-   scope-triage handoff (no re-triage on the receiving side), then exit this
-   path. Skipped entirely when `/plan` was itself entered via a scope-triage
-   handoff.
-4. Review `duplicates[]`. A non-empty ranked list folds into gate #1: the
-   operator either confirms the new Epic is distinct or folds the idea into
-   an existing Epic (in which case `/plan` exits).
-
-**Headless (`--yes`) — seed entry (#4496 fix 1).** There is no one to
-grill, so the one-pager prelude is pure ceremony: do **not** activate the
-`idea-refinement` skill and do **not** write a separate one-pager file
-before authoring. Instead, emit the envelope directly off the seed:
-
-```bash
-node .agents/scripts/plan-context.js --seed "<seed text>" \
-  > temp/plan-ideation/<slug>/plan-context.json
-```
-
-(slug from the seed's leading phrase; the tree is gitignored). The seed envelope is the one-pager envelope plus three additive fields:
-`seed` (the raw text), `scopeTriage` (the scope-triage rubric applied
-CLI-side — no skill Reads on this path; a `story` / `borderline` verdict
-resolves to its Recommended handoff per
-[`scope-triage-gate.md`](scope-triage-gate.md)), and `onePagerSpec` (the
-canonical one-pager sections). The one-pager markdown is authored **in
-step 2's single batched write**, alongside the other artifacts — every
-unresolved unknown lands in its Key Assumptions section. `duplicates[]`
-resolves headlessly per gate #1's `--yes` note.
-
-### Existing-Epic entry (`/plan <epicId>`)
-
-1. Emit the authoring envelope:
-
-   ```bash
-   node .agents/scripts/plan-context.js --epic [Epic_ID] \
-     > temp/epic-[Epic_ID]/plan-context.json
-   ```
-
-   The epic envelope additionally carries `clarity` (section-presence
-   rubric), `replan` (already-planned signals), and `planState`.
-2. **Re-plan detection** (`replan.alreadyPlanned === true`): the Epic body
-   already carries Tech Spec sections. Fold the decision into gate #1: a
-   confirmed re-plan runs step 3 with `--force` (managed sections are
-   overwritten in place; child Stories are closed and recreated); a decline
-   aborts gracefully.
-3. **Story-sized advisory**: only when the Epic is not already planned
-   **and** `replan.openStoryCount` is 0, run the shared scope-triage gate
-   over the Epic body ([`scope-triage-gate.md`](scope-triage-gate.md)). On a
-   `story` / `borderline` verdict the Recommended branch converts via
-   close-and-recreate: seed `temp/epic-[Epic_ID]/scope-triage-seed.md` from
-   the Epic body, hand off to `/plan --from-notes <path>` as a scope-triage
-   handoff, and — only after the replacement Story `#N` exists — close the
-   Epic with a cross-linking comment
-   (`gh issue close [Epic_ID] --comment "Closed in favor of #N — scope triaged as a standalone Story."`).
-   Both mutations happen only after the operator confirms at gate #1.
-4. **Clarity refinement** (`clarity.verdict === 'needs-refinement'`): the
-   deterministic scoring already ran inside the envelope build (a `clear`
-   verdict requires ≥ 4 of 5 canonical sections **and** Acceptance
-   Criteria). Interrogate the operator on the named gaps
-   (`clarity.missingOrPlaceholder`) — one question at a time — and draft the
-   refined body to `temp/epic-[Epic_ID]/clarity-update.md`. The refined-body
-   diff folds into gate #1; on approval persist it:
-
-   ```bash
-   node .agents/scripts/epic-plan-clarity.js --epic [Epic_ID] \
-     --updated-body temp/epic-[Epic_ID]/clarity-update.md
-   ```
-
-   One refinement pass per invocation — do not loop.
-
-### Gate #1 — exit of interrogate (HITL STOP)
-
-One operator confirmation folds every interrogate outcome: the one-pager (or
-the refined-body diff), the scope-triage verdict, the duplicate candidates,
-and the re-plan decision. Display them together and **STOP**. Do not enter
-step 2 until the operator explicitly confirms.
-
-> **`--yes` (headless) auto-proceed.** Under `--yes` this gate does **not**
-> STOP: the confirm resolves as **approved**, and a `story` / `borderline`
-> triage verdict resolves to its **Recommended** branch. 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. See
-> [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
-
-## Step 2 — Author
-
-Read the envelope with the `Read` tool and write the planning artifacts to
-`temp/epic-[Epic_ID]/` (ideation: the `temp/plan-ideation/<slug>/` tree).
-The single `plan-context.json` envelope supersedes the per-phase
-`planner-context.json` / `decomposer-context.json` files.
-
-**The envelope's `systemPrompts` ARE the authoring instructions on this
-path** (#4496 fix 4): `systemPrompts.spec` / `systemPrompts.acceptance`
-govern the Tech Spec, risk verdict, and Acceptance Spec;
-`systemPrompts.decompose` (with `ticketSchema` and `maxTickets`) governs
-the tickets. Do **not** read the
-[`epic-plan-spec-author`](../../skills/core/epic-plan-spec-author/SKILL.md)
-or
-[`epic-plan-decompose-author`](../../skills/core/epic-plan-decompose-author/SKILL.md)
-SKILL.md files here — they remain the reference source the prompts render
-from, but re-reading them double-pays instructions the envelope already
-carries.
-
-**Batched writes (#4496 fix 3).** Emit the artifact files as **parallel
-`Write` calls in ONE message** — `techspec.md`, `risk-verdict.json`,
-`acceptance-spec.md`, and `tickets.json` together (ideation: the one-pager
-markdown joins the same batch). Never write them one-per-turn.
-
-1. **`techspec.md`** — per `systemPrompts.spec`. The Tech Spec opens with
-   `## Delivery Slicing` and never restates the Epic's Context/Goal/Scope.
-2. **`risk-verdict.json`** — the schema-conformant verdict
-   **plus `deliveryShape: "fan-out"|"single"`** and a one-line rationale.
-   Seed the shape from the envelope's `deliveryShapeSignal` (advisory —
-   the operator vetoes it at gate #2). `"single"` means one-pass-sized or a
-   pure dependent chain: the plan ships as spec-only, with **no tickets**.
-3. **`acceptance-spec.md`** — per `systemPrompts.acceptance`; omit only
-   when the Epic carries the `acceptance::n-a` waiver label.
-4. **`tickets.json`** — fan-out shape only: author against the same
-   envelope (its `systemPrompts.decompose`, `ticketSchema`, and
-   `maxTickets` fields). In single-delivery shape author **no** tickets
-   file — the Delivery Slicing table is the plan.
-
-> **One-pass refinement contract (amend, don't regenerate).** When a critic
-> flags Stories or the step 3 persist rejects an artifact, apply **targeted
-> edits** to the existing files — fix only what was named — and re-run the
-> rejected step **once**. Never loop wholesale re-authoring.
-
-### Conditional critics (between authoring and gate #2)
-
-The dispatch decision is a **deterministic** function of the authored
-artifacts, evaluated in exactly one place — the evaluation is
-folded into `plan-persist.js` as a deterministic pre-write phase
-(#4496 fix 6). The persist prints both verdicts, returns them on its
-result envelope, and ledger-logs every skip: that fold is the
-single authoritative record, headless or attended. **Attended runs**
-apply the same deterministic conditions (below) to the authored
-artifacts before gate #2 so a `dispatch: true` critic runs and its
-findings fold into the gate's view; the persist fold then re-checks
-and ledger-logs the identical verdict. No separate CLI turn and zero
-GitHub reads — the conditions are mechanical thresholds over
-`techspec.md` / `risk-verdict.json` / `tickets.json`, and are
-never judged inline as an opinion. The verdict names each critic
-with `dispatch: true|false` and reasons.
-
-For each critic whose conditions hold (`dispatch: true`), dispatch a
-sub-agent; surface each skip as a one-line note. Every skip decision
-is appended to the plan-metrics ledger (`kind: "critic-skip"`, with
-reasons) so under-firing is auditable — the
-persist validators remain unchanged hard gates either way.
-
-> **`--yes` (headless).** Do **not** dispatch critic sub-agents: the
-> critics' findings would fold into a gate that auto-proceeds, so a report
-> nobody reviews is pure spend. The persist's folded pre-write evaluation is
-> the audit record — its verdicts print in the persist output, a
-> `dispatch: true` verdict surfaces as a one-line advisory note in the run
-> summary, and every skip still lands on the plan-metrics ledger.
-
-Both critics are **fresh-context sub-agents** (`Agent` tool,
-`subagent_type: general-purpose`) — never inline skill activations, so they
-cannot grade their own homework. Both are report-only: they never write to
-GitHub and never persist `tickets.json`; their findings fold into the gate #2
-view, and accepted findings get one targeted amend pass (above).
-
-- **Consolidation critic** (fan-out only): fires when the draft does NOT
-  already match the Tech Spec's Delivery Slicing table 1:1 in Story count
-  and dependency shape, AND the divergence is worth a dispatch — the draft
-  has more than 5 stories, or the mismatch is confirmed (a small draft
-  whose table is merely missing/unparseable skips: gate #2's single view
-  covers it). On dispatch the sub-agent reads the
-  [`epic-plan-consolidate`](../../skills/core/epic-plan-consolidate/SKILL.md)
-  skill and reconciles the draft against the slicing target. Its operations
-  are scope-preserving only — merge sibling Stories and rewire `depends_on`;
-  it MUST NOT add scope or invent tickets.
-- **Pre-mortem critic**: fires when the risk verdict's overall level is
-  high, OR the ticket count is at least half `maxTickets`, OR any
-  `planning.riskHeuristics` phrase matches the plan text. On dispatch the
-  sub-agent reads the
-  [`epic-plan-premortem`](../../skills/core/epic-plan-premortem/SKILL.md)
-  skill, reads the actual cited code surfaces, and emits predicted-rework
-  findings to `temp/epic-[Epic_ID]/premortem-report.md`.
-
-## Step 3 — Persist
-
-### Gate #2 — risk-routed review (HITL STOP, before any GitHub write)
-
-Present the whole plan in **one view**: the Tech Spec, the Acceptance Table,
-the tickets (or the Delivery Slicing table in single shape), the risk
-verdict, the `deliveryShape`, and any critic reports. This is the single
-seam where the operator vetoes single-vs-fan-out routing.
-
-- **High risk** (any risk axis high / `requiresReview`-shaped verdict) or
-  **operator override** (`--force-review`): **STOP** for explicit operator
-  approval before running the persist CLI.
-- **Low risk**: emit a one-line auto-proceed note and continue directly to
-  the persist call — no operator wait. (`--yes` is a no-op on this branch —
-  there is no STOP to suppress.)
-
-> **`--yes` (headless) auto-proceed.** Under `--yes` this review gate does
-> **not** STOP, even when the verdict is high-risk or `--force-review` was
-> passed: the review resolves as **approved** and the run continues to the
-> persist call. `--yes` does **not** alter risk routing or the review
-> criteria themselves — it only forces a proceed where this gate would
-> otherwise STOP. See
-> [`plan.md` § Headless / non-interactive mode](../plan.md#headless--non-interactive-mode---yes).
-
-### Run the persist CLI
-
-```bash
-# Normal persist (artifact paths default to temp/epic-[Epic_ID]/)
-node .agents/scripts/plan-persist.js --epic [Epic_ID]
-
-# Re-plan (overwrite managed sections in place; close + recreate the tree)
-node .agents/scripts/plan-persist.js --epic [Epic_ID] --force
-
-# Ideation (opens the Epic itself; artifact paths must be explicit)
-node .agents/scripts/plan-persist.js \
-  --one-pager temp/plan-ideation/<slug>/one-pager.md \
-  --tech-spec temp/plan-ideation/<slug>/techspec.md \
-  --risk-verdict temp/plan-ideation/<slug>/risk-verdict.json \
-  --acceptance-table temp/plan-ideation/<slug>/acceptance-spec.md \
-  --tickets temp/plan-ideation/<slug>/tickets.json
-
-# Change-request delta (tickets carry op: add|modify|keep|close;
-# close ops additionally require --explicit-delete after the dry-run diff)
-node .agents/scripts/plan-persist.js --epic [Epic_ID] --amend
-```
-
-The CLI runs every deterministic step in one ordered, fail-closed pass:
-section gate (`## Delivery Slicing` required) → risk-verdict validation +
-mode-coherence hard error (`deliveryShape: "single"` with tickets, or
-fan-out without them, refuses) → `validateAndNormalizeTickets` +
-file-assumption gate + DAG + sizing/budget (fan-out and amend) → ideation
-Epic creation → Epic lease (`--steal` transfers a confirmed-dead claim) →
-managed sections + `risk-verdict` comment + spec-freshness advisory → story
-tree via the structural reconciler (single shape: the `delivery::single`
-routing marker and a zero-ticket checkpoint instead) → inline healthcheck
-(the **blocking** `agent::ready` exit condition; waive only via the
-`planning::healthcheck-waived` label) → one terminal `agent::ready` flip (no
-intermediate `agent::review-spec`) → checkpoint v2 + a single `plan-summary`
-comment carrying the dry-run wave table → temp cleanup **only at terminal
-success**, so a failed run leaves the artifacts in place for `--force` /
-`--resume` reuse.
-
-Two deterministic softenings ride the gate list:
-
-- The file-assumption gate **auto-normalizes** a `refactors-existing`
-  declaration on a base-untracked path to `creates` with a logged warning
-  (#4496 fix 5) — a refactor of a path that does not exist is
-  deterministically a create, so no amend cycle is forced. Genuine
-  mismatches (an absent read dependency, a clobbering `creates`, a missing
-  `deletes` target) still reject.
-- Every auto-waiver the persist derives is printed **with its reason** in
-  the `plan-summary` comment and the result JSON (#4496 fix 2) — e.g. the
-  no-BDD-runner acceptance-disposition waiver.
-
-> **`--yes` (headless): persist outcomes are authoritative.** Read the
-> persist's result JSON and `plan-summary` receipts as the final word — do
-> **not** re-derive a waiver, disposition, or routing decision from
-> framework source. If a summary line seems surprising, its reason is on
-> the line itself; spend zero turns re-verifying it.
-
-### Persist rejections and soft failures
-
-Each rejection names the artifact and the gap; apply the one-pass amend
-contract (step 2) and re-run the persist once:
-
-- **Section gate / validator / file-assumption / DAG errors** — targeted
-  edit to `techspec.md` or `tickets.json`.
-- **Reachability orphans** (deterministic route-glob vs `navRegistry` check;
-  a silent no-op when `planning.navigation` is unconfigured) — a named
-  **soft failure** (exit 3, before any GitHub write) listing the orphaned
-  surfaces: apply one targeted amend adding a navigation owner
-  (at most one reachability Story per plan), then re-persist.
-- **Over budget** (`maxTickets`) — re-scope, or re-run with
-  `--allow-over-budget` after confirming the rationale on the Epic.
-- **Rate-limit abort on a large Epic** — resume with `--resume`; see
-  [`plan-epic-reference.md` § `--resume` recovery](plan-epic-reference.md#persist----resume-recovery-secondary-rate-limit).
-
-### Handoff
-
-> "Planning is complete. Run `/deliver #[Epic_ID]` to start the wave loop,
-> or pick a single Story from Wave 0 (the `plan-summary` comment's wave
-> table) and run `/deliver #[Story_ID]` to drive it directly."
-
-## Troubleshooting & recovery
-
-Edge-case procedures live in the reference companion:
-
-- [`plan-epic-reference.md` § Troubleshooting](plan-epic-reference.md#troubleshooting)
-- [`plan-epic-reference.md` § Persist guards — background rationale](plan-epic-reference.md#persist-guards--background-rationale)
-- [`plan-epic-reference.md` § `--resume` recovery](plan-epic-reference.md#persist----resume-recovery-secondary-rate-limit)