yadflow 3.18.1 → 4.0.0-next.1

package/skills/yad-sync-repos/SKILL.md

@@ -5,7 +5,7 @@ description: 'Brings every connected code repo up to date in one shot: switches
 
 # SDLC — Sync Connected Repos (one command, every repo on its default branch)
 
-**Goal:** Before front/build work starts, get every connected code repo onto its default branch at the
+**Goal:** Before Shape/Build work starts, get every connected code repo onto its default branch at the
 latest commit, so nobody implements on a stale or wrong branch. This is the deterministic counterpart to
 the `sync-before-implementation` discipline: one command instead of N manual `git checkout && git pull`.
 
@@ -15,7 +15,7 @@ tree (branch + fast-forward). It writes **nothing** back to the registry.
 
 ## Conventions
 
-- `{project-root}` resolves from the project working directory (the **product hub**).
+- `{project-root}` resolves from the project working directory (the **Product**).
 - Registry: `{project-root}/.sdlc/repos.json` (project-wide; the same file `yad-connect-repos` writes).
   Each repo entry supplies `path` (local path, relative to `{project-root}` or absolute) and
   `default_branch` (the branch to land on).
@@ -64,7 +64,7 @@ Per repo: `switched to <branch>, pulled (ff)` / `already current` / `SKIPPED (..
 so any repo whose `HEAD` now differs from its registry `syncedHead` has a **stale code-context pack** —
 the command ends by pointing the human at `yad repo refresh` to repack (that is a separate human
 decision; this skill never repacks or writes the registry). After the repack + AI code-map
-regeneration, `yad repo refresh --push` publishes the refreshed code-maps + registry to the hub's
+regeneration, `yad repo refresh --push` publishes the refreshed code-maps + registry to the Product's
 default branch as a `chore(hub): sync code-context … [skip ci]` audit commit.
 
 ## Hard rules

package/skills/yad-test-cases/SKILL.md

@@ -1,24 +1,23 @@
 ---
 name: yad-test-cases
-description: 'Front state 9 of the gated SDLC — a PARALLEL, non-blocking track. Opens when the stories gate passes (the epic is already ready-for-build, so the build half can start at the same time) and runs alongside implementation. With the test architect (Murat), author test-cases.md for the approved stories, and — when a testing tool is connected — generate/link the actual automation tests in it; otherwise produce the test-case artifact only. Reads epic + architecture + contract + UI + stories as input. Never auto-advances — hands off to the team review gate. Use when the user says "author the test cases" or after the stories gate passes.'
+description: 'Shape step 9 of the gated SDLC — a PARALLEL, non-blocking track. Opens when the stories gate passes (the epic is already ready-for-build, so Build can start at the same time) and runs alongside implementation. With the test architect, author test-cases.md for the approved stories, and — when a testing tool is connected — generate/link the actual automation tests in it; otherwise produce the test-case artifact only. Reads epic + architecture + contract + UI + stories as input. Never auto-advances — hands off to the team review gate. Use when the user says "author the test cases" or after the stories gate passes.'
 ---
 
-# SDLC — Author Test Cases (front state 9 — parallel, non-blocking)
+# SDLC — Author Test Cases (Shape step 9 — parallel, non-blocking)
 
 **Goal:** Produce a human-authored, AI-assisted `test-cases.md` for an approved epic — the risk-based
 test cases that cover the stories' acceptance criteria — **and**, when a testing tool is connected, the
 **actual automation tests** inside the connected code repo(s), linked back from the artifact. This is a
-**front state**: human-authored with AI assist, **never auto-advances**. When the test cases are
-drafted, control passes to `yad-review-gate` (base rule: owner + 1 reviewer).
+**Shape step**: human-authored with AI assist, **never auto-advances**. When the test cases are
+drafted, control passes to `yad-review-gate` (base rule: 1 distinct approver, who should not be the author).
 
-**This step does NOT block the build half.** It opens when the **stories** gate passes — at which point
+**This step does NOT block Build.** It opens when the **stories** gate passes — at which point
 the epic is already `ready-for-build`, so implementation (`yad-spec` → `yad-implement` → …) can start
 **at the same time** the tester works here. The test-cases track is driven by its own step `status`
 (it opens to `in_progress` when `stories-review` passes) and its review **never moves `currentStep`
 away from `ready-for-build`**, so the two run in parallel.
 
-Test work is shaped by the **test architect** lens — **Murat** (`bmad-tea`), driving
-`bmad-testarch-test-design` for the cases and `bmad-testarch-automate` for the automation. The
+Test work is shaped by the **test architect** lens, which designs the cases and writes the automation. The
 automation is materialized in the **testing tool connected via `yad-connect-testing`**
 (`.sdlc/testing.json`), reached through its MCP. When a tool is connected the lens **generates** tests
 into it (or **links** an existing suite and reads it back); when none is connected, the step degrades to
@@ -31,7 +30,7 @@ the Markdown artifact only — the testing tool is additive, exactly like the de
 - The connected testing tool is recorded in `{project-root}/.sdlc/testing.json` (`config.yaml`
   `testing`), written by `yad-connect-testing`. The per-epic case→test map is `test-links.json`
   (Step 4b).
-- 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
 
@@ -44,14 +43,14 @@ it passes. The check is track-aware: it keys off the `test-cases` step's predece
 `currentStep` (this is a parallel track — `currentStep` stays at `ready-for-build`).
 
 This passes once the `test-cases` step is runnable — its predecessor `stories-review` is `done` (so the
-step has opened to `in_progress`) and `test-cases` is not already `done`. While it is still `blocked`,
-the stories review has not passed.
+step has opened to `in_progress`) and `test-cases` is not already `done`. While it is still `todo` (or
+`blocked`, in a file written before shape 7), the stories review has not passed.
 
 ### Step 1b — Open the authoring branch
 Open the test-cases authoring branch `test-cases/EP-<slug>` per the shared procedure
 (`../yad-epic/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 `test-cases.md` on it. This is **distinct** from the bridge's
+Product's default branch. Author and commit `test-cases.md` on it. This is **distinct** from the verified ledger's
 `review/…` branch.
 
 ### Step 2 — Read inputs
@@ -62,7 +61,9 @@ for the cases — the test cases must collectively verify every story's criteria
 
 - **UI-optional-safe:** `ui-design.md` may be absent — the `ui-design` step is optional and can be
   marked N/A for a UI-less epic (state.json shows it `skipped`). When there is no UI design, there are
-  simply no screens to exercise; the stories' acceptance criteria remain the source of truth.
+  simply no screens to exercise; the stories' acceptance criteria remain the source of truth. If it
+  shows `deferred`, the screens are still to be designed: cover the stories' criteria now, and leave the
+  screen-level cases for when the UI design lands.
 
 ### Step 2b — Load existing-code context (make the brain code-aware)
 Read the registry `{project-root}/.sdlc/repos.json` (`config.yaml` `code_context`). For **each repo in
@@ -77,11 +78,11 @@ inventing parallel ones.
 - **Traceability:** record the loaded maps in the `test-cases.md` `code-context:` frontmatter field.
 
 ### Step 3 — Author the test cases (assist: test architect)
-Adopt the **test architect** lens (`bmad-tea`, Murat), driving `bmad-testarch-test-design`. For each
+Adopt the **test architect** lens. For each
 story / user flow shape risk-based test cases:
 
 - **Risk assessment** — categorize and score what can fail (probability × impact); depth scales with
-  impact (Murat's "risk-based testing" principle).
+  impact (risk-based testing).
 - **Coverage plan** — assign each case a priority **P0 (critical) / P1 (high) / P2 (medium) / P3 (low)**
   and a level, preferring the lowest useful level (unit > integration > E2E).
 - **Entry/exit criteria** and any **NFR** thresholds (security, performance, reliability) in scope.
@@ -95,8 +96,8 @@ Read `{project-root}/.sdlc/testing.json` (`config.yaml` `testing.registry`). Dec
   (mirrors the `design: none` degrade). Skip to Step 4.
 - **A tool is connected and its MCP is available:** adopt the `test architect` lens and, using the
   provider recorded in `testing.json` (Playwright via a Playwright MCP, Cypress/pytest/Maestro via
-  theirs — Maestro authors mobile flows where Playwright has no reach) drive
-  `bmad-testarch-automate`:
+  theirs — Maestro authors mobile flows where Playwright has no reach) write the
+  automation:
   - **Generate** — when the provider is write-capable, author one automation test per high-priority
     (P0/P1) case into the connected code repo(s) for the repos in `epic.repos`, reusing the code-maps
     (Step 2b) and existing fixtures so tests target built endpoints/components, then run them via the MCP
@@ -163,10 +164,10 @@ degraded (`testing: none`), do **not** write `test-links.json`.
 
 ### Step 5 — Advance the authoring step (NOT the 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
@@ -174,21 +175,27 @@ is pushed around the gate. Commit the artifact set — **`test-cases.md` and, wh
 tool was used, `.sdlc/test-links.json`** (artifact-side, not ledger; generated tests live in their
 own code repo, not here) — then hand off to `yad-review-gate`.
 
-**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
-`test-cases.status: "done"` and set `test-cases-review.status: "in_review"`. **Leave `currentStep` at
-`ready-for-build`** — this is the parallel track; moving `currentStep` would pull it back from the
-build half. Write `state.json`. Do **not** touch `approvals.json`. On this branch `yad gate open`
-makes the same edit — `markInReview` leaves `currentStep` alone once it is `ready-for-build`
-(`cli/epic-state.mjs`) — so it is a no-op once the gate has run.
+**Otherwise — local, or a platform with no gate-sync CI — the engine makes this edit, not you.**
+`yad gate open <epic> test-cases.md` marks `test-cases-review` `in_review`, closes `test-cases` as `done`, and **leaves `currentStep` at `ready-for-build`** — this is the parallel track, and moving it would pull the epic back from Build
+— 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>/test-cases` 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
+(or run `yad open-pr` from that branch: it pushes the branch, then delegates).
+
+Do **not** hand-edit `state.json`, and do **not** touch `approvals.json` — only real reviewers approve,
+through the gate.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: the path to `test-cases.md`, the connected testing tool and what it produced (e.g. "Playwright —
 6 tests generated", the suite path + `test-links.json` path, or "no testing tool — artifacts-only"), that
-the build half may already be underway in parallel, and that the next action is **review** via
-`yad-review-gate` (base rule: owner + 1 reviewer). **Never record approval here.** 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.
+Build may already be underway in parallel, and that the next action is **review** via
+`yad-review-gate` (base rule: 1 distinct approver, who should not be the author). **Never record approval here.** 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
 - Test-cases frontmatter, body template, and the `test-links.json` schema: `references/test-cases-schema.md`.

package/skills/yad-test-cases/references/test-cases-schema.md

@@ -1,6 +1,6 @@
 # Test-cases schema
 
-The test cases authored at front state 9 are one Markdown file under `epics/EP-<slug>/`, named
+The test cases authored at Shape step 9 are one Markdown file under `epics/EP-<slug>/`, named
 `test-cases.md` (one per epic — mirrors `ui-design.md`, not a per-story folder). The optional automation
 linkage is a sibling `test-links.json`.
 
@@ -56,15 +56,18 @@ Written by `yad-test-cases` Step 4b. Absent when the step ran artifacts-only (`t
 - **Cover every story.** The "Coverage & traceability" section must map each story's acceptance criteria
   to at least one case — an unmapped criterion is a gap the reviewer should catch.
 - **Priorities are risk-based.** P0 = critical (run on every commit) … P3 = low (on-demand); depth
-  scales with impact (Murat's principle).
+  scales with impact.
 - **Prefer the lowest useful level.** unit > integration > E2E when a case can be verified lower.
 - **`repos` is a subset of `epic.repos`.** Automation cannot target a repo the epic does not declare.
 - **Single-file, not a folder.** `test-cases.md` resolves through the gate's default content-hash path
-  (the file's bytes), so the review gate, revoke-on-change, and review-PR machinery work unchanged.
+  (the file without its frontmatter `status:` line), so the review gate, revoke-on-change, and review-PR machinery work unchanged.
 - **Automation is additive.** When no testing tool is connected, the step still produces a complete
   `test-cases.md`; `testing: none` and no `test-links.json`.
 
 ## Review routing (the test-cases gate)
 
-The test-cases gate uses the **base rule** (owner + 1 reviewer) — it is not escalated. The natural
-reviewer is the test architect / QA owner, but the gate predicate requires only owner + 1.
+The test-cases gate uses the **base rule**: at least 1 distinct approver, who should not be the author.
+The step carries no risk tags, so its full count is also 1. The natural reviewer is the test architect /
+QA owner, but the gate names no role — any approver counts. yadflow does not itself check that the
+approver is not the author (see `yad-review-gate`). The review PR requests no reviewers; the team asks
+them on the PR itself.

package/skills/yad-timeline/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-timeline
-description: 'Phase 6 output enrichment (never a gate) — render a feature THREAD as an evolution view AND resolve its current truth. Walks the thread (genesis -> changes -> defects, linked by parent: frontmatter), renders the evolution as the vendored React/Vite/Tailwind shell HTML + a TIMELINE.md summary (each node: kind, what it re-authored vs inherited, ship events, contract re-lock history, open debt), and emits thread-resolved.md — the composed CURRENT-TRUTH map (the latest epic that owns each artifact + the resolved contract-lock hash). That resolved map is the source-of-truth AI/humans read to plan the next change, instead of a stale genesis epic. Degrades to markdown-only when no docs target is connected. Use when the user says "show the feature timeline", "how did this feature evolve", "resolve the current truth", or "render the thread".'
+description: 'Phase 6 output enrichment (never a gate) — render a feature THREAD as an evolution view AND resolve its current truth. Walks the thread (genesis -> changes -> defects, linked by parent: frontmatter), renders the evolution as the vendored React/Vite/Tailwind shell HTML + a TIMELINE.md summary (each node: type, what it re-authored vs inherited, ship events, contract re-lock history, open debt), and emits thread-resolved.md — the composed CURRENT-TRUTH map (the latest epic that owns each artifact + the resolved contract-lock hash). That resolved map is the source-of-truth AI/humans read to plan the next change, instead of a stale genesis epic. Degrades to markdown-only when no docs target is connected. Use when the user says "show the feature timeline", "how did this feature evolve", "resolve the current truth", or "render the thread".'
 ---
 
 # SDLC — Feature Timeline + Current-Truth Resolver (Phase 6, output enrichment)
@@ -14,9 +14,9 @@ It is an **output enrichment**, exactly like `yad-docs` — **never a gate**: it
 
 ## Conventions
 
-- `{project-root}` resolves from the product hub.
+- `{project-root}` resolves from the Product.
 - Reuses the **`yad-docs` shell** verbatim (`../yad-docs/templates/app/`) — generated `src/data/*.ts`,
-  themed, deployed via `yad docs deploy`; build-only / markdown-only when no docs target
+  themed; build-only / markdown-only (`yad docs deploy` does not build `timeline-site/` yet)
   (`.sdlc/docs.json`). The resolver part drives the **`yad thread` CLI** (`cli/thread.mjs`).
 - The thread is **derived** from `parent:` frontmatter (no registry). The thread report lives under the
   **genesis** epic (`thread == genesis id`).
@@ -32,7 +32,8 @@ It is an **output enrichment**, exactly like `yad-docs` — **never a gate**: it
 
 ### Step 1 — Resolve the thread
 Run `yad thread <thread> --json` (`resolveThread` + `threadEpics` + `resolveCurrentArtifacts`). This
-gives the genesis-first chain, each epic's lineage (`kind`, `parent`, `inherits`), the resolved
+gives the genesis-first chain, each epic's lineage (`type`, and `kind` holding the same value under
+the older name, plus `parent` and `inherits`), the resolved
 current-truth map, and any open reconcile debt. **STOP** and report if the lineage is broken (point at
 `yad doctor` / `yad-reconcile`).
 
@@ -54,9 +55,9 @@ deterministically; theme from the design system). The thread maps onto the shell
   = what it re-authored, its side-effects = the ships it produced + any contract re-lock.
 - **System components** = the artifacts (epic/architecture/contract/ui/stories/test-cases), each labelled
   with the epic that currently **owns** it (from the resolved map).
-- Label and colour nodes by `kind` — render each node's kind noun (**Change request** / **Defect** /
+- Label and colour nodes by `type` — render each node's type noun (**Change request** / **Defect** /
   **Hotfix** / **Epic** for feature) alongside its id, not the generic word "epic"; mark sealed epics and
-  open debt. (A bug is a defect — `kind: defect`. Presentation only; every node is still an epic.)
+  open debt. (A bug is a defect — type `defect`. Presentation only; every node is still an epic.)
 
 ### Step 4 — Emit `thread-resolved.md` (the current-truth map — derived, non-authoritative)
 Write `epics/<thread>/thread-resolved.md`: for each artifact base, the **owning epic** (the latest in the
@@ -66,7 +67,7 @@ is the file the next `yad-change` / `yad-epic` reads as "the feature's current t
 
 ### Step 5 — Emit `TIMELINE.md` + (optional) deploy
 Write a short `epics/<thread>/TIMELINE.md` (the chain, what each node changed, ships, open debt) for a
-plain-text read — head each node with its kind noun (Change request / Defect / Hotfix / Epic) + id. On `action: deploy`, `yad docs deploy` the site (build-only when no target).
+plain-text read — head each node with its type noun (Change request / Defect / Hotfix / Chore / Epic) + id. On `action: deploy`, note that `yad docs deploy` does not build this folder yet (it builds only the epic `docs-site/` and the overview) — build it with `npm ci` (or `npm install` when it has no lockfile) and `npm run build` inside the folder, and report it as build-only; a failed npm build is reported as a failure, never as a deploy.
 
 ## Hard rules
 

package/skills/yad-ui/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: yad-ui
-description: 'Front state 5 of the gated SDLC. With the ux-designer, author ui-design.md and DESIGN.md for an approved architecture, driving Impeccable as harness slash-commands (document/extract/craft) when installed, or authoring directly when not. Reads epic + architecture as input. Never auto-advances — hands off to the team review gate. Use when the user says "author the UI design" or after the architecture gate passes.'
+description: 'Shape step 5 of the gated SDLC. With the ux-designer, author ui-design.md and DESIGN.md for an approved architecture, driving Impeccable as harness slash-commands (document/extract/craft) when installed, or authoring directly when not. Reads epic + architecture as input. Never auto-advances — hands off to the team review gate. Use when the user says "author the UI design" or after the architecture gate passes.'
 ---
 
-# SDLC — Author UI Design (front state 5)
+# SDLC — Author UI Design (Shape step 5)
 
 **Goal:** Produce a human-authored, AI-assisted `ui-design.md` and `DESIGN.md` for an approved
 architecture **and**, when a design tool is connected, the **actual feature design** — the mobile
 screens and/or web pages — inside that tool (e.g. Figma), linked back from the artifacts. This is a
-**front state**: human-authored with AI assist, **never auto-advances**. When the UI is drafted, control
-passes to `yad-review-gate` (base rule: owner + 1 reviewer).
+**Shape step**: human-authored with AI assist, **never auto-advances**. When the UI is drafted, control
+passes to `yad-review-gate` (base rule: 1 distinct approver, who should not be the author).
 
 UI work is shaped by **Impeccable**, invoked as **harness slash-commands** (not a subprocess CLI) per
 the Phase 0 deviation. If Impeccable is not installed, the `ux-designer` lens authors the same outputs
@@ -28,7 +28,7 @@ like Impeccable.
 - `DESIGN.md` is Impeccable's conventional root design-system file (RESEARCH-NOTES §4).
 - The connected design tool is recorded in `{project-root}/.sdlc/design.json` (`config.yaml` `design`),
   written by `yad-connect-design`. The per-epic screen→frame map is `design-links.json` (Step 4b).
-- 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
 
@@ -45,22 +45,34 @@ This passes when `ui-design` is the next runnable step per the state sequence
 **This step is OPTIONAL.** If the epic has no user-facing surface (a backend/API service, a data
 pipeline, infra work), it does not need a UI design. Two signals to watch for:
 
-- **Already skipped:** if `ui-design.status` is `done` with `skipped: true` in `state.json` (the
-  `--check` above will report `ui-design is already done`), the step was marked N/A — **STOP**, there
-  is nothing to author; point the user at `yad next EP-<slug>` (the next step is `stories`).
+- **Already skipped or deferred:** if `ui-design.status` is `skipped` in `state.json` — or, in a file
+  from before shape 7, `done` with `skipped: true` beside it — the step was marked N/A. If it is
+  `deferred`, the team set it aside to come back to later. Either way the `--check` above refuses it
+  (`ui-design is already skipped`, or `already deferred`). **STOP**, there is nothing to author now;
+  point the user at `yad next EP-<slug>` (the next step is `stories`). To pick a deferred UI back up,
+  run `yad undefer EP-<slug> ui-design` first.
 - **Should be skipped:** if you reach this step and the epic clearly produces no screens, do **not**
   invent a hollow UI artifact. Offer to mark it N/A instead:
-  `yad skip EP-<slug> ui-design --reason "<why, e.g. backend-only service>"`. That pre-marks both the
-  `ui-design` and `ui-design-review` steps `done` (recorded reason + actor), short-circuits the review
-  gate, and advances to `stories`. It is reversible with `yad skip EP-<slug> ui-design --undo` until the
+  `yad skip EP-<slug> ui-design --reason "<why, e.g. backend-only service>"`. That marks both the
+  `ui-design` and `ui-design-review` steps `skipped` (recorded reason + actor), short-circuits the review
+  gate, and advances to `stories`. It is reversible with `yad unskip EP-<slug> ui-design` until the
   stories review opens. See `../yad-epic/references/state-schema.md` → "ui-design is optional".
+- **Will have screens, just not yet:** if the epic does need a UI but the team wants to design it later,
+  offer `yad defer EP-<slug> ui-design --reason "<why, and who is waiting for it>"` instead of a skip.
+  It passes the step for now and keeps it visibly owed. If the team is setting it aside under pressure
+  and owes it back, add `--debt`: `yad next` and `yad doctor` then remind them until its review passes.
+  It can be picked back up with `yad undefer EP-<slug> ui-design` at any time — after the stories are
+  finished, the UI re-opens beside them and the stories stay done.
+- **On a verified Product (the mode check below), none of these verbs works here:** by this step the
+  epic's ledger is on the default branch, so `yad skip`, `yad defer` and `yad undefer` refuse (CI owns
+  `state.json`, and has no step for them yet). Tell the user that, and do not edit the ledger by hand.
 
 ### Step 1b — Open the authoring branch
 Open the UI authoring branch `ui-design/EP-<slug>` per the shared procedure
 (`../yad-epic/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 `ui-design.md` / `DESIGN.md` on it. This is **distinct** from
-the bridge's `review/…` branch.
+Product's default branch. Author and commit `ui-design.md` / `DESIGN.md` on it. This is **distinct** from
+the verified ledger's `review/…` branch.
 
 ### Step 2 — Read inputs
 Read `epic.md` (user-level acceptance signals, scope) and `architecture.md` (flows, components by
@@ -80,7 +92,7 @@ Impeccable is absent, the code-map is the brain's view of what UI/components alr
 - **Traceability:** record the loaded maps in the `ui-design.md` `code-context:` frontmatter field.
 
 ### Step 3 — Shape the UI (assist: ux-designer + Impeccable slash-commands)
-Adopt the **ux-designer** lens (`bmad-agent-ux-designer`, Sally). Drive Impeccable as slash-commands:
+Adopt the **ux-designer** lens. Drive Impeccable as slash-commands:
 
 - **Existing project** (a codebase/design system already exists): `/impeccable document` → then
   `/impeccable extract` → then `/impeccable craft`.
@@ -92,7 +104,7 @@ components/tokens into the design system; `/impeccable craft` is shape-then-buil
 **Graceful degradation:** if Impeccable is not installed (no `/impeccable …` commands available), the
 `ux-designer` lens authors `ui-design.md` and `DESIGN.md` directly, and you **note in `ui-design.md`
 that Impeccable was not used**. Do not run `npx impeccable skills install` as part of this step — tool
-installation is out of scope for the front half.
+installation is out of scope for Shape.
 
 ### Step 3b — Materialize the design in the connected tool (generate or link)
 Read `{project-root}/.sdlc/design.json` (`config.yaml` `design.registry`). Decide the path:
@@ -172,10 +184,10 @@ Keep the `## Design (<tool>)` section of `ui-design.md` in step with this file.
 
 ### Step 5 — Advance the authoring step (NOT the 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
@@ -183,18 +195,27 @@ is pushed around the gate. Commit the artifact set — **`ui-design.md`, `DESIGN
 design tool was used, `.sdlc/design-links.json`** (artifact-side, not ledger) — then hand off to
 `yad-review-gate`.
 
-**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
-`ui-design.status: "done"`, set `ui-design-review.status: "in_review"`, and set
-`currentStep: "ui-design-review"`. Write `state.json`. Do **not** touch `approvals.json`. On this
-branch `yad gate open` makes the same edit, so it is a no-op once the gate has run.
+**Otherwise — local, or a platform with no gate-sync CI — the engine makes this edit, not you.**
+`yad gate open <epic> ui-design.md` marks `ui-design-review` `in_review`, closes `ui-design` as `done`, and moves `currentStep` to the gate
+— unless the chain is already past it: a `ui-design` re-opened with a late `yad undefer` runs beside the
+finished stories, and opening its review leaves `currentStep` where it is — 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>/ui-design` 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
+(or run `yad open-pr` from that branch: it pushes the branch, then delegates).
+
+Do **not** hand-edit `state.json`, and do **not** touch `approvals.json` — only real reviewers approve,
+through the gate.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: the paths to `ui-design.md` and `DESIGN.md`, whether Impeccable was used, the connected design
 tool and what it produced (e.g. "Figma — 4 screens generated", the file URL + `design-links.json` path,
 or "no design tool — markdown-only"), and that the next action is **review** via `yad-review-gate` (base
-rule: owner + 1 reviewer). **Never record approval here.** 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.
+rule: 1 distinct approver, who should not be the author). **Never record approval here.** 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
 - Impeccable commands and the slash-command-vs-CLI deviation: `RESEARCH-NOTES.md` §4 + Deviation 3.

package/cli/roster.mjs

@@ -1,164 +0,0 @@
-// `yad roster` — manage the reviewer roster (.sdlc/hub.json) and per-repo roles at any time.
-// The roster maps a platform login -> SDLC name + a per-scope roles map; it is the only thing that lets
-// the review gate attribute approvals and route per-repo domain-owner reviewers. This is the standalone
-// counterpart of the `yad setup` roster step and the `yad-connect-repos action: roster` skill action.
-// Repo-driven: `add`/`edit` walks the connected repos from repos.json so roles are assigned against what
-// is actually connected, not against repo names the user has to remember. Granting/revoking a
-// `domain-owner` keeps repos.json `domain_owners` in sync so the gate never drifts from the roster.
-import path from 'node:path';
-import { c, log, ok, info, warn, hand, fail, ask, askYesNo, readJSON, writeJSON } from './lib.mjs';
-import { PROJECT_FILES } from './manifest.mjs';
-import { rolesForScope } from './platform.mjs';
-import { parseRolesSpec, upsertRosterEntry, addRepoRoles, removeRepoRole, setRepoDomainOwners, reconcileRepoRoles } from './setup.mjs';
-
-const ROLES = ['owner', 'reviewer', 'domain-owner'];
-
-const loadHub = (root) => readJSON(path.join(root, PROJECT_FILES.hubConfig), null);
-const loadRepos = (root) => readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] }).repos || [];
-const ownersOf = (repo) => (Array.isArray(repo.domain_owners) ? repo.domain_owners : (repo.domain_owner ? [repo.domain_owner] : []));
-
-// `list` — every member with their per-scope roles, plus a drift check between hub.json roles and
-// repos.json domain_owners (the two should agree; the sync on grant/revoke keeps them aligned).
-function rosterList(root) {
-  const hub = loadHub(root);
-  if (!hub || !Array.isArray(hub.roster) || !hub.roster.length) {
-    warn('no roster yet (.sdlc/hub.json) — add one with `yad roster add <login>` or `yad setup`');
-    return { members: 0 };
-  }
-  const repos = loadRepos(root);
-  log(c.bold('\nreviewer roster'));
-  for (const e of hub.roster) {
-    const flag = e.unverified ? c.yellow(' (unverified)') : '';
-    log(`  ${c.bold(e.name || e.login)} ${c.dim(`@${e.login}`)}${e.email ? c.dim(` <${e.email}>`) : ''}${flag}`);
-    const hubRoles = rolesForScope(e, 'hub');
-    log(`    hub: ${hubRoles.length ? hubRoles.join(', ') : c.dim('—')}`);
-    for (const r of repos) {
-      const rr = rolesForScope(e, r.name);
-      if (rr.length) log(`    ${r.name}: ${rr.join(', ')}`);
-    }
-  }
-  const drift = [];
-  for (const r of repos) {
-    const owners = ownersOf(r);
-    for (const nm of owners) {
-      const e = hub.roster.find((x) => x.name === nm);
-      if (!e || !rolesForScope(e, r.name).includes('domain-owner')) {
-        drift.push(`${nm} owns ${r.name} in repos.json but has no domain-owner role in hub.json`);
-      }
-    }
-    for (const e of hub.roster) {
-      if (rolesForScope(e, r.name).includes('domain-owner') && !owners.includes(e.name)) {
-        drift.push(`${e.name} has domain-owner for ${r.name} in hub.json but is missing from repos.json domain_owners`);
-      }
-    }
-  }
-  if (drift.length) { log(''); for (const d of drift) warn(d); }
-  return { members: hub.roster.length, repos: repos.length, drift: drift.length };
-}
-
-// The repo-driven walk: for each connected repo show the member's current role and offer to set it.
-async function repoWalk(root, entry) {
-  const repos = loadRepos(root);
-  if (!repos.length) { info('no connected repos to assign roles for (.sdlc/repos.json) — connect one with `yad setup`'); return; }
-  for (const r of repos) {
-    const cur = rolesForScope(entry, r.name);
-    if (!(await askYesNo(`  set ${entry.name}'s role on ${r.name}? (current: ${cur.length ? cur.join(', ') : 'none'})`, false))) continue;
-    const input = await ask('    roles (domain-owner/reviewer/owner, space-separated; blank = clear)', cur.join(' '));
-    const want = input.split(/\s+/).map((x) => x.trim()).filter(Boolean);
-    const invalid = want.filter((x) => !ROLES.includes(x));
-    if (invalid.length) warn(`ignoring unknown role(s): ${invalid.join(', ')} (allowed: ${ROLES.join(', ')})`);
-    reconcileRepoRoles(root, entry.name, r.name, cur, want.filter((x) => ROLES.includes(x)));
-  }
-}
-
-// Mirror any domain-owner scopes from a non-interactive `--roles` upsert into repos.json.
-function syncDomainOwners(root, entry) {
-  for (const [scope, list] of Object.entries(entry.roles || {})) {
-    if (scope !== 'hub' && Array.isArray(list) && list.includes('domain-owner')) setRepoDomainOwners(root, scope, entry.name, { add: true });
-  }
-}
-
-// `add`/`edit <login>` — upsert by login (from flags or interactive prompts), then either apply a
-// `--roles` spec directly (scriptable) or run the repo-driven walk (interactive default).
-async function rosterAdd(root, login, { name, email, roles } = {}) {
-  if (!login) { fail('usage: yad roster add <login> [--name N] [--email E] [--roles "hub=owner,reviewer backend=domain-owner"]'); process.exitCode = 1; return {}; }
-  const hub = loadHub(root);
-  const platform = hub ? hub.platform : null;
-  const existing = hub && Array.isArray(hub.roster) ? hub.roster.find((e) => e.login === login) : null;
-  const scripted = !!roles;
-  let nm = name;
-  let em = email;
-  let rolesMap;
-  if (scripted) {
-    rolesMap = parseRolesSpec(roles);
-  } else {
-    nm = nm || await ask('  yad name', (existing && existing.name) || login);
-    em = em || await ask('  commit email (blank to skip)', (existing && existing.email) || '');
-    const def = rolesForScope(existing, 'hub').join(' ') || 'reviewer';
-    const hubRoles = (await ask('  hub roles (owner/reviewer, space-separated)', def)).split(/\s+/).filter(Boolean);
-    rolesMap = hubRoles.length ? { hub: hubRoles } : {};
-  }
-  const { entry, created } = upsertRosterEntry(root, { login, name: nm, email: em || undefined, roles: rolesMap, platform });
-  if (!entry) return {};
-  ok(`${created ? 'added' : 'updated'} ${entry.name} (@${login})`);
-  if (scripted) syncDomainOwners(root, entry);
-  else await repoWalk(root, entry);
-  return { entry: entry.name, created };
-}
-
-// `grant <name> <repo> <role...>` — scriptable per-repo grant (member must already be in the roster).
-function rosterGrant(root, [name, repo, ...roles]) {
-  if (!name || !repo || !roles.length) { fail('usage: yad roster grant <name> <repo> <role...>'); process.exitCode = 1; return {}; }
-  const invalid = roles.filter((r) => !ROLES.includes(r));
-  if (invalid.length) { fail(`unknown role(s): ${invalid.join(', ')} (allowed: ${ROLES.join(', ')})`); process.exitCode = 1; return {}; }
-  const hub = loadHub(root);
-  if (!hub || !Array.isArray(hub.roster) || !hub.roster.some((e) => e.name === name)) {
-    fail(`'${name}' is not in the roster — add them first with \`yad roster add <login>\``); process.exitCode = 1; return {};
-  }
-  if (!loadRepos(root).some((r) => r.name === repo)) warn(`repo '${repo}' is not registered — the role is recorded and applies once it is connected`);
-  addRepoRoles(root, repo, Object.fromEntries(roles.map((r) => [r, [name]])));
-  if (roles.includes('domain-owner')) setRepoDomainOwners(root, repo, name, { add: true });
-  ok(`granted ${name} ${roles.join(', ')} on ${repo}`);
-  return { name, repo, roles };
-}
-
-// `revoke <name> <repo> <role...>` — scriptable per-repo revoke.
-function rosterRevoke(root, [name, repo, ...roles]) {
-  if (!name || !repo || !roles.length) { fail('usage: yad roster revoke <name> <repo> <role...>'); process.exitCode = 1; return {}; }
-  removeRepoRole(root, name, repo, roles);
-  if (roles.includes('domain-owner')) setRepoDomainOwners(root, repo, name, { add: false });
-  ok(`revoked ${name} ${roles.join(', ')} on ${repo}`);
-  return { name, repo, roles };
-}
-
-// `remove <login>` — delete a member; warn (do not cascade) if still a domain owner in repos.json.
-function rosterRemove(root, login) {
-  if (!login) { fail('usage: yad roster remove <login>'); process.exitCode = 1; return {}; }
-  const hubPath = path.join(root, PROJECT_FILES.hubConfig);
-  const hub = readJSON(hubPath, null);
-  if (!hub || !Array.isArray(hub.roster)) { warn('no roster to remove from (.sdlc/hub.json)'); return { removed: 0 }; }
-  const idx = hub.roster.findIndex((e) => e.login === login);
-  if (idx < 0) { warn(`no roster member with login '${login}'`); return { removed: 0 }; }
-  const [removed] = hub.roster.splice(idx, 1);
-  writeJSON(hubPath, hub);
-  ok(`removed ${removed.name} (@${login})`);
-  const refs = loadRepos(root).filter((r) => ownersOf(r).includes(removed.name)).map((r) => r.name);
-  if (refs.length) hand(`'${removed.name}' is still a domain owner in repos.json for: ${refs.join(', ')} — revoke with \`yad roster revoke ${removed.name} <repo> domain-owner\``);
-  return { removed: 1 };
-}
-
-export async function runRoster(root, { action = 'list', args = [], name, email, roles } = {}) {
-  switch (action) {
-    case 'list': return rosterList(root);
-    case 'add':
-    case 'edit': return rosterAdd(root, args[0], { name, email, roles });
-    case 'grant': return rosterGrant(root, args);
-    case 'revoke': return rosterRevoke(root, args);
-    case 'remove':
-    case 'rm': return rosterRemove(root, args[0]);
-    default:
-      fail(`unknown roster action: ${action} (list | add | edit | grant | revoke | remove)`);
-      process.exitCode = 1;
-      return {};
-  }
-}