yadflow 3.18.1 → 4.0.0-next.1

package/skills/yad-epic/SKILL.md

@@ -1,29 +1,31 @@
 ---
 name: yad-epic
-description: 'Front state for the epic in the gated SDLC. Shape a feature idea with the analyst (or read analysis.md when the optional analysis step already ran), then write the epic with the pm, into epic.md. The entry point when analysis is skipped: assigns the EP-<slug> ID and seeds .sdlc/ state. Never auto-advances — hands off to the team review gate. Use when the user says "start a new feature/epic" or "author an epic".'
+description: 'Shape step for the epic in the gated SDLC. Shape a feature idea with the analyst (or read analysis.md when the optional analysis step already ran), then write the epic with the pm, into epic.md. The entry point when analysis is skipped: assigns the EP-<slug> ID and seeds .sdlc/ state. Never auto-advances — hands off to the team review gate. Use when the user says "start a new feature/epic" or "author an epic".'
 ---
 
-# SDLC — Author Epic (front state)
+# SDLC — Author Epic (Shape step)
 
 **Goal:** Produce a human-authored, AI-assisted `epic.md` for a new feature, and — when the epic is the
 entry point — assign its stable `EP-<slug>` ID and initialise the per-epic state machine in `.sdlc/`.
-This is a **front state**: human-authored with AI assist and **never auto-advances**. When the epic is
+This is a **Shape step**: human-authored with AI assist and **never auto-advances**. When the epic is
 drafted, control passes to `yad-review-gate`.
 
-**Two entry modes** (the optional `yad-analysis` step decides which):
-- **Analysis ran** — `.sdlc/state.json` already exists with `currentStep == "epic"`. The epic **reads
-  `analysis.md`** as its shaped input and does not re-seed state.
-- **Analysis skipped** (the default) — no `state.json` yet. The epic is the entry point: it shapes the
-  idea inline with the analyst, assigns `EP-<slug>`, and seeds the **10-step** chain.
+**Two entry modes**, decided by one question: does `.sdlc/state.json` already exist?
+- **Chain already seeded** — `state.json` exists with `currentStep == "epic"`. Two things put it there:
+  the optional `yad-analysis` step (which also wrote `analysis.md`, and the epic **reads** it as its
+  shaped input), or `yad epic new <slug>`, which seeds the same chain and writes no artifact. Either
+  way this skill does **not** re-seed state.
+- **Nothing seeded** (the default) — no `state.json`. The epic is the entry point: it shapes the idea
+  inline with the analyst, assigns `EP-<slug>`, and seeds the **10-step** chain.
 
 This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
-engine (never typed by hand); front steps are locked to `human_approve`.
+engine (never typed by hand); Shape steps are locked to `advance: human`.
 
 ## Conventions
 
 - `{project-root}` resolves from the project working directory.
 - Epic artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
-- Speak in the configured `communication_language`; write documents in `document_output_language`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
 
 ## On Activation
 
@@ -31,23 +33,27 @@ engine (never typed by hand); front steps are locked to `human_approve`.
 Read `{project-root}/epics/EP-<slug>/.sdlc/state.json` if an epic is named, otherwise check whether one
 exists for the idea.
 
-- **Analysis ran** — `state.json` exists with `currentStep == "epic"` and the `epic` step
-  `status == "in_progress"` (the analysis review already passed). Skip **Step 3** (the ID is already
-  assigned) and **Step 5** (state is already seeded); take the *analysis-ran* branch of Step 2 (read
-  `analysis.md`) and run Step 5b to advance the authoring step.
-- **Analysis skipped** (the default) — no `state.json`. The epic is the entry point: run Steps 2–5
-  (inline analyst shaping + ID assignment + seed) and **skip Step 5b**.
+- **Chain already seeded** — `state.json` exists with `currentStep == "epic"`. Skip **Step 3** (the ID
+  is already assigned) and **Step 5** (the chain is already there — re-seeding is refused anyway). For
+  Step 2, read `analysis.md` when it is there (the analysis ran); when it is not, the chain came from
+  `yad epic new` and no analysis exists, so shape the idea inline with the analyst exactly as the
+  greenfield branch does.
+- **Nothing seeded** (the default) — no `state.json`. The epic is the entry point: run Steps 2–5
+  (inline analyst shaping + ID assignment + seed).
+
+**Step 5b runs on both paths.** It is what closes the authoring step and opens its gate, and nothing
+else does it.
 
 Either mode runs Step 3b (branch), Step 4 (write the epic), and Step 6 (stop at the gate).
 
-**Precondition gate (rail):** if `state.json` already exists (analysis-ran or re-entry), run
+**Precondition gate (rail):** if `state.json` already exists (seeded, or a re-entry), run
 `yad next EP-<slug> --check epic` — if it exits non-zero, **STOP** and surface the blocker, pointing the
 user at `yad next EP-<slug>`. When no `state.json` exists yet, this is the greenfield entry point — the
 check is not applicable, so proceed and seed state.
 
 ### Step 2 — Shape the idea (assist: analyst) — or read the analysis
 - **Analysis skipped:** ask the user for a one-line feature idea if not provided, then adopt the
-  **analyst** lens (`bmad-agent-analyst`, Mary) to pressure-test it: who is the user, what problem, what
+  **analyst** lens to pressure-test it: who is the user, what problem, what
   signals success, what is out of scope. Keep it brief — this is shaping, not a PRD.
 - **Analysis ran:** read `{project-root}/epics/EP-<slug>/analysis.md` (the analyst's discovery brief)
   and carry its Recommendation / Scope framing forward — do not re-shape from scratch.
@@ -68,40 +74,86 @@ and let it inform which `repos` the epic should touch.
 - For depth on a specific area not in the map, do a live on-demand read (see `yad-connect-repos`
   `references/code-context.md`) — do not block on it.
 
-### Step 2c — Read the project roadmap (project context, only once discovery is APPROVED)
-Consume the project front-zero (`yad-discovery`) **only after its review gate has passed** — never a
-draft or in-review roadmap (that would bypass `discovery-review`). Gate on the **state**, not file
-existence: read `{project-root}/epics/EP-discovery/.sdlc/state.json` and proceed **only when
-`currentStep == "discovery-done"`**. When it is, read its `roadmap.md` and sibling `requirements.md`
-for the project framing: which phase (MVP / later) this feature belongs to, the functional/non-functional
-requirements it carries, and how it fits the wider plan — so the epic's **Goal / Scope / Acceptance
-signals** stay consistent with the approved roadmap. **Optional & non-blocking:** if there is no
-discovery, or it has not yet reached `discovery-done` (absent / still draft / in-review), proceed
-unchanged — do not consume an unapproved roadmap. After seeding the epic, the matching roadmap row's
-`status:` can be bumped `planned → epic-started` by hand (a human edit; discovery never auto-seeds epics).
+### Step 2c — Read the Foundation (product context, only once it is APPROVED)
+Consume the Product level (written by `yad-discovery`) **only after its review gate has passed** — never
+a draft or in-review one (that would bypass its gate). Gate on the **state**, not file existence:
+- **The Foundation:** read `{project-root}/foundation/.sdlc/state.json` and proceed **only when
+  `currentStep == "foundation-done"`**. Then read `foundation/purpose.md`, `scope.md`, `mvp.md` and
+  `roadmap.md` (and `stack.md` / `repos.md` for the technical frame).
+- **The old spelling**, only when there is no Foundation: read
+  `{project-root}/epics/EP-discovery/.sdlc/state.json` and proceed **only when
+  `currentStep == "discovery-done"`**. Then read its `roadmap.md` and sibling `requirements.md`.
+
+Use it for: which phase (MVP / later) this feature belongs to, what the product explicitly is **not**,
+the requirements it carries, and how it fits the wider plan — so the epic's **Goal / Scope / Acceptance
+signals** stay consistent with the approved product. **Optional & non-blocking:** if there is no product
+level, or it has not passed its gate yet (absent / still draft / in-review), proceed unchanged — do not
+consume an unapproved one. (`yad next` reports feature work that goes ahead of an unapproved Foundation;
+it never blocks it.) Prefer the roadmap row's **proposed epic id** when you assign the id (Step 3), so
+the feature and its epic stay linked. **Do not edit the roadmap row's `Status` after seeding** (the
+Foundation never auto-seeds epics, and nothing needs the row changed): the roadmap table is part of what
+the Foundation's reviewers approved, so the edit makes `yad doctor` report their approvals as stale.
+`yad foundation status` reads how far each feature has got from the epic ledgers instead.
 
 ### Step 3 — Generate the Epic ID (engine-assigned, never by hand) — analysis-skipped only
-*(Skip when analysis ran — the ID was already assigned by `yad-analysis`.)*
+*(Skip when `state.json` already exists — the ID was assigned by whatever seeded the chain.)*
 Derive `EP-<slug>` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea
-(e.g. `EP-checkout`). Lowercase except the fixed `EP` prefix. `EP-discovery` is **reserved**
-for the project front-zero — never use it for a feature. **The ID is assigned once and
+(e.g. `EP-checkout`). Lowercase except the fixed `EP` prefix. `EP-foundation` and `EP-discovery` are
+**reserved** for the Product level — never use either for a feature. **The ID is assigned once and
 never renamed** — renaming breaks every downstream link (build plan §6b).
 Check `{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word.
 
 ### Step 3b — Open the authoring branch
 Open the epic authoring branch `epic/EP-<slug>` per the shared procedure
 (`references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if `{project-root}`
-is not a git work tree), check out the branch if it exists, else create it from the hub's default
-branch. Author and commit `epic.md` on it. This is **distinct** from the bridge's `review/…` branch.
+is not a git work tree), check out the branch if it exists, else create it from the Product's default
+branch. Author and commit `epic.md` on it. This is **distinct** from the verified ledger's `review/…` branch.
 
 ### Step 4 — Write the epic (assist: pm)
-Adopt the **pm** lens (`bmad-agent-pm`, John) and write `{project-root}/epics/EP-<slug>/epic.md`
-using EXACTLY this template (build plan §6b):
+Adopt the **pm** lens and write `{project-root}/epics/EP-<slug>/epic.md`
+using EXACTLY this template (build plan §6b).
+
+**Five of these keys are read by machines, so write them BARE — no trailing `#` comment.** The
+frontmatter readers (`readFrontmatter` in the CLI, `fm_val` in the check gates) keep the whole rest of
+the line, so a comment becomes part of the value and the gates stop recognising it:
+
+- `title` is the epic's **one-line name** — the name a list of work items shows for it (E111; it is carried in `.sdlc/index.json`). Plain words,
+  such as `Checkout from the mobile app`, on ONE line. Quotes are optional: a title quoted the YAML way
+  (`"…"` or `'…'`) is read without them. If the title begins with `[` and ends with `]` (such as
+  `[Mobile] Checkout [v2]`), wrap it in double quotes, writing an inner `"` as `\"` — otherwise it is
+  read as a list, which is not a title. The full rules are the `title` row of the frontmatter table in
+  `references/state-schema.md`. Never end it with a `#` comment (the comment becomes part of the title), and never use a YAML
+  block (`>` or `|`): only one line is read. Set it NOW, for the same reason as the theme below: the epic review gate is bound to a hash of
+  the file, so a title added or reworded after that gate is approved drops the approval as stale. An
+  epic with no title is shown by its id.
+- `kind` and `type` are the **work-item type**, and both carry the same value. `kind:` is the name
+  every reader still uses; `type:` is the name from shape 5 on. Write both. Use `feature` for new
+  value, or `chore` for upkeep with no user-visible change — those are the two types allowed to stand
+  alone with no `parent:`. Everything else (`change`, `defect`, `hotfix`) is authored by `yad-change`.
+- `thread` is the thread id. A genesis epic is the root of its own thread, so `thread == id` and there
+  is no `parent:`.
+- `theme` is an optional **grouping tag**: one word or short phrase shared by every epic that belongs
+  together, such as `checkout-revamp`. It is what this method has instead of a rung above the Epic —
+  the ladder stays Product → Epic → Story → Task, and grouping is a label. Nothing has to be
+  registered first and no list of allowed themes exists. Ask the user whether this epic belongs to a
+  group; if one already exists, **copy its spelling exactly** (`yad doctor` reports a theme spelled
+  two ways, because two spellings group as two themes). Leave the key empty when there is no group.
+  Write ONE tag, never a list — `theme: [a, b]` is read as no theme at all — and never write a `#`:
+  `yad next` and `yad thread` PRINT the tag as `#checkout-revamp`, but the `#` is decoration on the
+  screen, and anything from a `#` onward is kept as part of the value, so the epic then groups only
+  with epics carrying that exact text. Any language is fine. Set it NOW, while the epic
+  is being written: the epic review gate is bound to a hash of the file (all of it except the `status:` line), so adding a theme after
+  that gate is approved drops the approval as stale and the step has to be approved again.
 
 ```markdown
 ---
 id: EP-<slug>
+title: <one line: what this epic delivers>
 status: draft
+kind: feature
+type: feature
+thread: EP-<slug>
+theme:
 owner:
 technical_product_owner:
 repos: [backend, mobile, dashboard]
@@ -118,90 +170,116 @@ code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # which code-maps in
 ```
 
 Fill the body with the user; leave `owner` / `technical_product_owner` for the user to set. Set
-`repos` to the repos this epic will touch.
-
-### Step 5 — Seed the state machine — analysis-skipped only
-*(Skip when analysis ran — `yad-analysis` already seeded the 12-step chain. Go to Step 5b.)*
-Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **10-step** front-state
-sequence (no analysis), all steps defaulting to `automation: human_approve`, with the five authoring
-steps **locked**. Use this exact shape (see `references/state-schema.md`):
-
-```json
-{
-  "schemaVersion": 1,
-  "epicId": "EP-<slug>",
-  "createdAt": "<YYYY-MM-DD>",
-  "currentStep": "epic-review",
-  "steps": [
-    { "id": "epic",               "type": "author",         "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "done",        "risk_tags": [] },
-    { "id": "epic-review",        "type": "review+approve", "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "in_review",   "risk_tags": [] },
-    { "id": "architecture",       "type": "author",         "artifact": "architecture.md",  "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
-    { "id": "architecture-review","type": "review+approve", "artifact": "architecture.md",  "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": ["contract"] },
-    { "id": "ui-design",          "type": "author",         "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
-    { "id": "ui-design-review",   "type": "review+approve", "artifact": "ui-design.md",     "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
-    { "id": "stories",            "type": "author",         "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
-    { "id": "stories-review",     "type": "review+approve", "artifact": "stories/",         "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
-    { "id": "test-cases",         "type": "author",         "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] },
-    { "id": "test-cases-review",  "type": "review+approve", "artifact": "test-cases.md",    "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked",     "risk_tags": [] }
-  ]
-}
+`repos` to the repos this epic will touch, and `theme` only if the user names a group.
+
+### Step 5 — Seed the state machine — only when nothing is seeded
+*(Skip when `state.json` already exists — `yad-analysis` seeded the 12-step chain, or `yad epic new`
+seeded the 10-step one. Go to Step 5b.)*
+
+**Run the engine. Do not hand-write the chain.**
+
+```bash
+yad epic new EP-<slug>                    # after Step 4: the type comes from epic.md
+yad epic new EP-<slug> --type chore       # only when there is no epic.md yet
+yad epic new EP-<slug> --profile chore    # the short upkeep lane — see below
 ```
 
+That writes `{project-root}/epics/EP-<slug>/.sdlc/state.json`, the empty `approvals.json` and
+`comments.json`, and the `reviews/` directory. Without `--profile` the chain is the full **10-step**
+`classic` route (no analysis). Every step is `advance: human` and locked; `epic` is open and the rest
+are blocked. The chain comes from the step catalogue and the lifecycle profile in the engine
+(`references/state-schema.md`), so there is one definition of it and no copy here to drift from it.
+
+**Ask which lane this work belongs on before you run it.** `classic` is the default and the right
+answer for a feature. For upkeep somebody has already decided on — a dependency bump, a CI move —
+`--profile chore` seeds a **4-step** lane instead: `epic → epic-review → stories → stories-review`,
+with no architecture, UI-design or test-case steps. `--profile spike` is the same lane with the
+analyst's brief in front, for a timeboxed question (start that one from `yad-analysis`, which owns the
+first step). Both are described in `references/state-schema.md`.
+
+A short lane has **no architecture gate, so no `contract.md` and no lock**, and no step on it is
+optional — `yad skip` is refused. **Choose the route before you seed, because the choice is final:**
+`yad epic new` refuses an epic that already has a `state.json` and there is no re-seed flag. If the
+work turns out to move the shared cross-repo surface, the short-lane epic records the finding and the
+surface change belongs to a NEW epic on `classic` — say that rather than trying to widen this one. The
+work-item type is a separate choice: `--type chore --profile classic` is right for large upkeep that
+does touch the contract.
+
+It writes no `epic.md`, no branch and no commit, and it refuses an epic that already has a
+`state.json`. Run it **after** Step 4 when `epic.md` exists, and it reads the type from that header —
+then `--type` is unnecessary and a contradicting one is refused.
+
 Notes:
-- `architecture-review` carries `risk_tags: ["contract"]` so the gate escalates it by default
-  (build plan §4): the contract review needs domain owners, not just owner + 1.
-- `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `blocked` and open
-  when `stories-review` passes — at which point the epic is already `ready-for-build`, so the build half
+- **Then advance the authoring step.** The seed leaves `epic` open, which is truthful: the command runs
+  before the artifact exists. Closing it is Step 5b's job, and on the local path `yad gate open` does it
+  — so after writing `epic.md`, take Step 5b.
+- `architecture-review` carries `risk_tags: ["contract"]` by default (build plan §4): the tag raises
+  the step's full approver count to 3 (base 1 + contract risk 2). Only the base holds the
+  gate; the risk step is advisory, reported as a shortfall against the count capped at the
+  active people less one (E72). The catalogue sets it;
+  there is nothing to type.
+- `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `todo` and open
+  when `stories-review` passes — at which point the epic is already `ready-for-build`, so Build
   runs alongside the tester. They never gate `ready-for-build` (see `references/state-schema.md`).
-- Commit the seed on this step's authoring branch. It reaches the hub's default branch through the
+- Commit the seed on this step's authoring branch. It reaches the Product's default branch through the
   epic's **first** review PR/MR — cut `review/EP-<slug>/epic` from the authoring branch so it carries
-  the seed. In bridge mode `ledger-guard` exempts a new epic's ledger (creation, not mutation, #162);
+  the seed. In verified mode `ledger-guard` exempts a new epic's ledger (creation, not mutation, #162);
   every later change to it is CI's. See `references/state-schema.md`, "Authoring branches".
-- Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
-  and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
-  `[]`, and the `reviews/` directory. (`comments.json` is the machine-readable counterpart to the
-  `reviews/*--comments.md` markdown — `yad-review-gate` appends to it on every `comment`.)
-- **No UI?** Seed the chain **as-is** (always include the two `ui-design` steps). If this epic has no
+- **No UI?** Seed the chain **as-is** (the two `ui-design` steps are always in it). If this epic has no
   user-facing surface (a backend/API service, data pipeline, infra), the `ui-design` step is optional
   and can be marked N/A now with `yad skip EP-<slug> ui-design --reason "<why>"` — it stays visible,
   short-circuits its gate, and advances straight to `stories` when architecture is approved. It is
-  reversible with `--undo` until the stories review opens. Don't hand-edit the seed to drop the steps;
+  reversible with `yad unskip EP-<slug> ui-design` until the stories review opens. **On a verified Product, now is the only time:** once this epic's first review PR merges, CI owns `state.json` and `yad skip` refuses. Don't hand-edit the chain to drop the steps;
   the skip is the single, auditable mechanism (see `references/state-schema.md` → "ui-design is optional").
 
-### Step 5b — Advance the authoring step — analysis-ran only
-*(Only when analysis ran — `state.json` already exists from `yad-analysis`.)*
+### Step 5b — Open the epic's review gate
+*(**Always run this**, on both entry modes. The chain is seeded by now either way — by `yad-analysis`,
+by `yad epic new` in Step 5, or by `yad epic new` before this skill was invoked — and `epic.md` is
+written. This is the step that closes the authoring step and opens its gate.)*
 **Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
-**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+**verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
 
-**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
-any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+**verified mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,product-prs,hub-prs}.json` or
 `epics/*/reviews/*.md`, `yad gate open` deliberately skips this write for the same reason, and
 `yad gate ci --merged` performs the whole transition when the review PR merges. Making the edit here
 fails the gate if it rides the review PR, and desynchronises the ledger CI is about to rewrite if it
-is pushed around the gate. Commit **`epic.md` only** — nothing else under `.sdlc/` — then hand off
-to `yad-review-gate`.
-
-> **This is not the Step 5 seed exemption.** `ledger-guard` exempts a *brand-new* epic's ledger
-> (creation, not mutation, #162). On this path `state.json` already exists from `yad-analysis` and
-> reached the base ref through the analysis review — so the guard is absolute here.
-
-**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
-`epic.status: "done"`, set `epic-review.status: "in_review"`, and set `currentStep: "epic-review"`.
-Write `state.json`. Do **not** re-seed and do **not** touch `approvals.json` — only real reviewers
-approve, through the gate.
-
-> **File-only branch only.** Since 3.11 the CLI closes the authoring step itself whenever its review
-> gate opens or advances (`yad gate open` / `sync`), so this edit is a no-op when the gate has already
-> run. It keeps `state.json` truthful before the gate opens, but it is no longer load-bearing: an epic
-> whose author step is left `in_progress` used to strand forever (`YAD-STATE-005`). In bridge mode
-> `gate open` writes nothing and local `gate sync` is advisory — `gate ci` closes the step at merge.
+is pushed around the gate.
+
+**Do not EDIT the ledger — but do COMMIT it when it is untracked.** Those are two different acts and
+the guard treats them differently. Commit `epic.md`, and also `.sdlc/state.json`, `.sdlc/approvals.json`
+and `.sdlc/comments.json` when `git status` shows them **untracked** — that is the case after
+`yad epic new`, whose seed has never been reviewed and so rides this epic's first review PR exactly as
+a Step 5 seed does. Leave their contents exactly as they are. When `git status` shows them tracked and
+unmodified (the `yad-analysis` path), commit `epic.md` alone. Then hand off to `yad-review-gate`.
+
+> **The Step 5 seed exemption may or may not still apply — read the base ref, not the calendar.**
+> `ledger-guard` exempts an epic whose ledger is absent from the BASE ref: that is creation, not
+> mutation (#162). After `yad-analysis` the ledger reached the base ref through the analysis review,
+> so the exemption is spent and the guard is absolute. After `yad epic new` the ledger has never been
+> reviewed, so it is still off the base ref and the seed rides this epic's first review PR exactly as
+> in Step 5. Either way the instruction above is the safe one: in verified mode, do not write
+> `state.json` here. Advancing a step is a mutation on any path, and CI performs it at merge.
+
+**Otherwise — local, or a platform with no gate-sync CI — the engine makes this edit, not you.**
+`yad gate open <epic> epic.md` marks `epic-review` `in_review`, closes `epic` as `done`, and moves
+`currentStep` to the gate — the same transition, from the one function that owns it (`markInReview`, `cli/epic-state.mjs`).
+`yad-review-gate action: open` runs that command; hand off to it rather than editing the ledger here.
+
+**With no platform configured** it writes the ledger and simply opens no PR, so this works offline.
+**With a platform** the `review/EP-<slug>/epic` branch must already be **on origin** — the command refuses
+and writes nothing otherwise. Cut it from the authoring branch and push it before handing off
+(`yad open-pr` does both, then delegates).
+
+Do **not** hand-edit `state.json`, do **not** re-seed, and do **not** touch `approvals.json` — only real
+reviewers approve, through the gate.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: epic ID, the path to `epic.md`, and that the next action is **review** via
 `yad-review-gate`. **Never mark the epic-review step approved here** — only real reviewers do that
-through the gate. Front states do not auto-advance. When the hub has a platform, the gate opens a review
-PR on the hub (via `yad-hub-bridge`) and `yad-review-gate action: sync` pulls platform approvals/
-comments into the ledger; otherwise the review is recorded file-only.
+through the gate. Shape steps do not auto-advance. When the Product has a platform, the gate opens a review
+PR on the Product (via `yad-hub-bridge`) and `yad-review-gate action: sync` pulls platform approvals/
+comments into the ledger; otherwise the review is recorded local.
 
 ## Reference
 - State schema and field meanings: `references/state-schema.md`.