yadflow 3.18.1 → 4.0.0-next.1

package/skills/yad-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-status
-description: 'Read-only view of an SDLC epic: prints the current step, each step''s dials (assistance/automation) and status, and which approvals are still required at the active gate. For stories in the build half it also prints each back-half step''s automation dial, status, and trust record (runs / % approved-unchanged / whether it clears the threshold to be earned), plus the system-wide kill-switch state — so the team can see WHY a step is automated and reverse it with evidence. Also prints the cross-cutting personal skills-log roll-up from the LOCAL-ONLY learning ledger (gitignored, never committed/pushed — the local learner''s own learning, by stage). Surfaces the Phase 5 instrumentation signals: per-step "earned but manual" (nudge cost) and, across multiple epics, a fleet roll-up (scale of read). Use when the user says "yad status", "where is epic EP-...", "what is blocking the gate", "show the trust record", "team skills", or "fleet status".'
+description: 'Read-only view of an SDLC epic: prints the current step, each step''s dials (driver/advance, under either spelling) and status, and which approvals are still required at the active gate. For stories in Build it also prints each Build step''s automation dial, status, and run record (runs / % approved-unchanged, as advice), plus the kill switch and the Shape author dials from .sdlc/automation.json — so the team can see WHY a step is automated and reverse it. Also prints the cross-cutting personal skills-log roll-up from the LOCAL-ONLY learning ledger (gitignored, never committed/pushed — the local learner''s own learning, by stage). Across multiple epics, prints a fleet roll-up (scale of read). Use when the user says "yad status", "where is epic EP-...", "what is blocking the gate", "show the trust record", "team skills", or "fleet status".'
 ---
 
 # SDLC — Status (read-only)
@@ -10,7 +10,8 @@ reads `.sdlc/` and `reviews/` and reports.
 
 ## Conventions
 - `{project-root}` resolves from the project working directory.
-- Operate on one epic: `{project-root}/epics/EP-<slug>/`.
+- Operate on one epic: `{project-root}/epics/EP-<slug>/`. The Product level is the exception:
+  `EP-foundation` lives at `{project-root}/foundation/` (its `.sdlc/` and `reviews/` are there).
 
 ## On Activation
 
@@ -20,14 +21,16 @@ report all if the user asked for an overview).
 
 ### Step 2 — Read state
 Read `.sdlc/state.json`, `.sdlc/approvals.json`, `epic.md` frontmatter (for `repos`), and — if present
-— `.sdlc/contract-lock.json`. For the build half (Phase 4), also read — if present — every
+— `.sdlc/contract-lock.json`. For Build (Phase 4), also read — if present — every
 `.sdlc/build-state/<story-id>.json`, and the trust ledger read as the **union** of the folded
 `.sdlc/trust-log.json` `runs` PLUS every loose `.sdlc/trust-log/` shard (concatenate — every shard is a
 distinct run; never dedup by story/repo/step — but DO skip a shard whose full identity
 `(story,repo,step,uid)` already appears in the folded `runs`, i.e. a half-applied `yad tidy up`). All are committed by `yad checkpoint` (so a fresh clone
 or another machine sees current evidence; `yad tidy up` folds finished shards into `trust-log.json`).
 Also read the `automation` block of
-`skills/sdlc/config.yaml` (`back_steps`, `trust_threshold`, `locked_steps`, `kill_switch`). For the
+`.sdlc/config.yaml` (`back_steps`), and `.sdlc/automation.json` if present — the kill switch and the
+Shape author steps set to auto (absent = the switch off, every Shape step human). The effective dial of any
+step is `yad dial … --json`, which applies the kill switch and gates for you. For the
 cross-cutting learning layer, also read — if present — the **local-only** `.sdlc/learning-records.json`
 (the per-epic learning ledger, gitignored) and the project-wide `{project-root}/.sdlc/learning-records.json`.
 Do not modify any of them.
@@ -35,72 +38,127 @@ Do not modify any of them.
 ### Step 3 — Report
 Print, in this order:
 
-1. **Header:** render the kind noun from `epic.md` frontmatter `kind` — **Change request** (`change`),
-   **Defect** (`defect`), **Hotfix** (`hotfix`), or **Epic** (`feature`, and the default when `kind` is
-   absent) — followed by `epicId`, then `status` from `epic.md` frontmatter, `currentStep`, and `repos`
+1. **Header:** render the type noun from the `epic.md` frontmatter work-item type. Two names carry it,
+   `kind:` and `type:`; read `kind:` first, then `type:`. **Change request** (`change`),
+   **Defect** (`defect`), **Hotfix** (`hotfix`), **Chore** (`chore`), or **Epic** (`feature`, and the default when neither is
+   present) — followed by `epicId`, then `status` from `epic.md` frontmatter, `currentStep`, and `repos`
    (the touched domains). Example: `Defect EP-checkout-queue-filter — draft @ stories`. A bug is a defect
-   (`kind: defect`) — there is no separate noun. This is presentation only; the artifact is still an epic.
-2. **Steps table** — for every front step in `steps[]` order (10, or 12 when the optional analysis step
-   was run): `id`, `type`, `status`, `assistance`, `automation`, `locked`, and `risk_tags`. Mark the
-   `currentStep` with `→`. The gating chain is `[analysis → analysis-review →] epic → epic-review →
-   architecture → architecture-review → ui-design → ui-design-review → stories → stories-review` →
-   **`ready-for-build`** (the bracketed `analysis` prefix is present only when `yad-analysis` seeded it).
+   (type `defect`) — there is no separate noun. This is presentation only; the artifact is still an epic.
+2. **Steps table** — for every Shape step in `steps[]` order, however many there are: `id`, `type`,
+   `status`, the two dials (`driver`/`assistance` and `advance`/`automation` — read whichever the step carries, the OLD name wins), `locked`, and `risk_tags`. Mark the
+   `currentStep` with `→`. **The chain length is a fact about the epic's ROUTE, never a constant** —
+   read `profile` from `state.json`: `classic` is 10 steps, `analysis-first` 12, and the short lanes
+   `chore` 4 and `spike` 6 (E40). On `classic` the gating chain is `[analysis → analysis-review →]
+   epic → epic-review → architecture → architecture-review → ui-design → ui-design-review → stories →
+   stories-review` → **`ready-for-build`** (the bracketed `analysis` prefix is not on `classic`: it is
+   what makes `analysis-first`, the route `yad-analysis` seeds). A short lane runs `epic → epic-review → stories → stories-review` →
+   **`ready-for-build`**, with `analysis` in front on `spike`, and has no architecture, UI-design or
+   test-case rows at all — render what `steps[]` holds and never a step it lacks.
    `test-cases → test-cases-review` is a **parallel, non-blocking track**: it opens when `stories-review`
-   passes and runs alongside the build half, so when `currentStep` is `ready-for-build` the `test-cases`
+   passes and runs alongside Build, so when `currentStep` is `ready-for-build` the `test-cases`
    step may still be `in_progress`/`in_review` — show its status, and note "parallel" so it is clear it
    does not gate the build. Always render exactly the steps present in `steps[]`.
-   - **Skipped (N/A) steps:** the optional `ui-design` step may be marked N/A for an epic with no
-     user-facing surface. **Both** the `ui-design` author step **and** its `ui-design-review` gate stay
-     in `steps[]`, each carrying `skipped: true`, `status: "done"`, and a `skipReason`. Render **each**
-     as `<id> — SKIPPED (N/A: <skipReason>)` (with `skippedBy`/`skippedAt` if present) instead of the
-     plain status, so the deliberate skip and its reason are visible and the gate does not appear to
-     vanish. The chain then reads `… architecture-review → ui-design (N/A) → ui-design-review (N/A) →
+   - **Skipped (N/A) steps:** a step the epic's route marks optional — `ui-design`, on the routes that
+     ship — may be marked N/A with `yad skip`. **Both** the author step **and** its `-review` gate stay
+     in `steps[]`, each with `status: "skipped"` and a `record` (`{ reason, by, date }`). A file from
+     before shape 7 spells the same thing `status: "done"` with `skipped: true` and a `skipReason`
+     beside it; read either. Render **each** as `<id> — SKIPPED (N/A: <reason>)` (with who and when if
+     present) instead of the plain status, so the deliberate skip and its reason are visible and the
+     gate does not appear to vanish. The chain then reads `… architecture-review → ui-design (N/A) → ui-design-review (N/A) →
      stories → …`; the review gate never needs approvals.
+   - **Deferred steps:** `yad defer` sets an optional step aside to come back to later. Both the author
+     step and its `-review` gate carry `status: "deferred"` and a `record`. Render each as
+     `<id> — DEFERRED (later: <reason>)`, with who and when if present. A deferred step is still owed:
+     never render it as done or as N/A.
+   - **Debt:** a step carrying `"debt": true` (written by `yad defer … --debt`) is owed back and must be
+     reminded until paid. Add `· DEBT` to its line, and list every debt in a short **Owed** block under
+     the chain with the command that pays it: `yad undefer <epic> <id>` while it is still `deferred` (on a verified Product,
+     say that verb is refused once the ledger is on the default branch), or
+     "being paid back — clears when `<id>-review` passes" once it is back in progress. The flag is
+     removed only when that review passes. `yad doctor` reports the same list as `step:debt`.
+   - **Closed steps:** a `done` step may carry `closed` (E18) — `{ by, date, via, pr?, … }`. Add
+     `(closed <date>, via <via>, PR #<pr>)` to its line when it is there, and nothing when it is not: a
+     step closed before this release has none, and that is not a fault.
+   - **Re-opened steps:** an unfinished step with a later step `done` (not its own `-review` gate) was
+     put back after the chain built past it — a late `yad undefer`. Render it as
+     `<id> — RE-OPENED (beside finished work)`: it does not block the finished steps after it, and
+     `currentStep` stays where it is. `yad next <epic>` prints it as a `re-opened lane`.
+   - **Blocked steps:** a step with `status: "blocked"` **and** a `record` is waiting on someone outside
+     the workflow. Render it as `<id> — BLOCKED (<reason>)`, with who recorded it and when, and say it is
+     cleared with `yad unblock <epic> <id>` once the wait is over — on a verified Product that verb refuses
+     once the ledger is on the default branch, so say so. A `blocked` with no record is the older
+     word for `todo`: render it as not started.
 3. **Active gate** — for the `currentStep` (if it is a `review+approve` step), compute and show:
-   - the reviewer rule in force — **base** (`owner + 1 reviewer`), **escalated** (list the required
-     domains), or **per-repo** for `stories-review` (list each repo needing sign-off),
-   - approvals **recorded so far** (from `approvals.json`), and
-   - approvals **still required** to pass the gate (name the missing domains/repos).
+   - the count in force — **distinct approvers** recorded, against the **base** (1, enforced) and the
+     **full count** from the step's risk tags (advisory),
+   - approvals **recorded so far** (from `approvals.json`, one line per approver), and
+   - approvals **still required** to pass the gate (`1 approval(s)`, or none).
    Do not advance — just state whether the gate would pass right now.
 
    Apply the same predicate `yad-review-gate` uses (restated here so this skill is
    self-contained). From the `approved` records in `approvals.json` for the current step:
-   - `owners` = records with `role == "owner"`; `reviewers` = distinct `role == "reviewer"`;
-     `domainOwners` = `role == "domain-owner"`, grouped by `domain`.
-   - **Base pass:** `|owners| >= 1` AND `|reviewers| >= 1` (the configured `default_reviewers`).
-   - **Escalated pass** (step `risk_tags` ∩ `{contract, auth, payments}` ≠ ∅): base pass AND, for
-     every touched domain, `|domainOwners[domain]| >= 1`. Touched domains = `epic.repos` for
-     `architecture-review`; the union of every story's `repos` for `stories-review`.
-   - Approvals are **stale** (gate fails) if the artifact was edited after the newest `approved`
-     record. For `architecture-review`, also flag staleness if the contract-surface hash no longer
-     matches `.sdlc/contract-lock.json`.
+   - `approvers` = the distinct, non-empty `approver` values of the approvals that are not stale (below).
+     A record that names nobody counts as nobody. When `requireEngagement` is on in the Product config,
+     only approvals with `engagement: verified` count. There are no roles; a `role` or `domain` an older
+     record carries is legacy data, and it counts for nothing.
+   - **Pass (team mode):** `|approvers| >= 1` — the base — plus, with a platform, resolved review threads and a merged
+     review PR/MR. Solo mode waives approvals entirely.
+   - **The full count, reported on every step that is not inherited, skipped or deferred:** `needed = base 1 + risk step` — plus `2` when the
+     step's `risk_tags` carry `contract`, or `1` when they carry `auth`/`payments` (the highest tag,
+     never the sum). The engine **caps** that ask at `active − 1` (floor 1) and prints it (E72) — for
+     example a contract gate asks 3, and with 2 active people the capped ask is 1. The risk step is
+     ADVISORY, capped or not — it never decides whether the gate would pass, because the count
+     of people can read high (a git name and a platform login are two people until proven one). When the
+     people could not be counted, no cap is shown. `yad gate status` prints the sum and the shortfall
+     (`; count: 3 approvers = base 1 + contract risk 2 — capped to 1: 2 active people, less one seat
+     for the author — base enforced, risk step advisory — 1 short`, or without the `capped to …` part
+     when the cap lowered nothing) — read it from there rather than recomputing it, and say "short N"
+     rather than "blocked" when it is short. A closed team gate whose ask was lowered says
+     `count capped from 3 to 1 (2 active people)`. In solo mode it prints no shortfall.
+   - **A gate that may not pass (E73):** under a team gate that has not passed, `yad gate status` can
+     print a warning line. Relay it as stated, as a warning and never as "blocked": it holds nothing.
+     A line starting `! may not be met:` means there is no approval in the counting window and the one
+     required approval may have nobody but the author to give it; another person's approval settles it.
+     A line starting `! if the risk step were enforced:` is a what-if: the extra approvals that risk
+     tags add could not all be given by the people counted. The gate can still pass today, and the line
+     says so.
+   - **How many people there are to ask (E71), printed once per epic and not per step:** `active people:
+     4 in the last 90 days — caps each gate's count at 3 approvers (one seat is left for the author);
+     reported, only the base is enforced`, with the window's basis on the line under it. It is
+     the count the cap (E72) uses, so never report a step as blocked by it. A source that could not be
+     read prints `active people: NOT COUNTED — <which source> — no cap can be shown, and only the base
+     holds each gate`: report that wording as it stands and NEVER as a number or as "no people" — an
+     unreadable input is not a small team.
+   - **Solo mode may be wrong (E74):** in solo mode, under the `active people:` line, `yad gate status`
+     can print `! solo mode is on, but … so more than one person may work on this Product`. Relay it as
+     a suggestion to run `yad mode team`, never as a fault and never as switched: nothing changes until
+     a person runs it. It never suggests solo mode.
+   - Touched domains (`epic.repos` for a step with a risk tag; the union of every story's `repos` for
+     `stories-review`) only label the review. They add no approvals.
+   - An approval is **stale** (it no longer counts) when the `artifactHash` it recorded no longer
+     matches the artifact's current fingerprint — the content changed after that person approved. For
+     `architecture-review` the fingerprint is the contract surface in `contract.md`. An approval with no
+     `artifactHash` is never stale. `yad gate status` prints the stale count. For `architecture-review`,
+     also flag when the contract-surface hash no longer matches `.sdlc/contract-lock.json`.
 4. **Contract lock** — if `.sdlc/contract-lock.json` exists, show the locked hash and `lockedAt`
    (and, when at/after `architecture-review`, whether the current surface still matches it).
 5. **Stories** — if `stories/` has files, list each story `id` and its `repos` tags.
 6. **Files** — list the review records present under `reviews/` for the current artifact.
-7. **Build half (per story, per repo)** — if any `.sdlc/build-state/<story-id>.json` exists, then for
-   each such story and each of its repos print the back-half chain
+7. **Build (per story, per repo)** — if any `.sdlc/build-state/<story-id>.json` exists, then for
+   each such story and each of its repos print the Build chain
    `spec → tasks → implement → checks → engineer-review`, marking each step's `status`, its
-   `automation` dial, and `locked`. Mark that repo's `currentStep` with `→`. This shows, at a glance,
-   which back steps are automated and where a run is waiting. (For the single *next* build sub-step to
+   `advance` dial (or `automation`, whichever the step carries), and `locked`. Mark that repo's `currentStep` with `→`. A repo whose lane is `status: skipped` (a whole lane set aside with `yad skip <epic> <story> --repo <repo>`, E39) prints `skipped (N/A)` and its `record.reason` instead of the chain. This shows, at a glance,
+   which Build steps are automated and where a run is waiting. (For the single *next* build sub-step to
    take per story/repo — rather than this full status view — point the user at `yad next <epic>`, which
    reads the same `build-state` files.)
-8. **Automation & trust** — print the system-wide **kill switch** state from `config.yaml`
-   `automation.kill_switch` (when `on`, note that every step is forced to `human_approve`). Then, for
-   each back-half step that has entries in the trust ledger — the **union** of the folded
-   `.sdlc/trust-log.json` `runs` plus every loose `.sdlc/trust-log/` shard — print its **trust record**:
-   number of runs, the fraction with `verdict == "approved-unchanged"`, and whether that clears
-   `automation.trust_threshold` (`min_runs`, `min_approved_unchanged`) — i.e. whether the step is
-   **earned** (eligible to be flipped to `machine_advance`) or still **gathering evidence**. Restate
-   the predicate (self-contained): `earned = runs >= min_runs AND unchanged/runs >= min_approved_unchanged`.
-   Never recommend flipping a locked step or a front state — those can never be `machine_advance`.
-
-   **Nudge-cost signal (Phase 5 instrumentation).** For each back step that is **earned but its dial
-   is still `human_approve`** (and it is not locked / not a front state), flag it:
-   `⚠ earned but manual — could be machine_advance`. This is the *nudge cost* the Phase 5 trigger
-   watches: automation that is proven safe but still hand-started. It is a read-only observation, not a
-   recommendation to flip — earning the evidence and flipping the dial stay deliberate human acts
-   (`yad-run action: set-dial`). See `docs/phase-5-build-plan.md` §"What to instrument now".
+8. **Automation & run record** — print the **kill switch** from `.sdlc/automation.json` (when on, who
+   turned it on, when and why, and that every step is held at `advance: human`), and the Shape author
+   steps the project set to `auto` — noting that a Shape `auto` is recorded only: nothing drives a Shape
+   step on its own yet. Then, for each Build step that has entries in the trust ledger — the **union** of
+   the folded `.sdlc/trust-log.json` `runs` plus every loose `.sdlc/trust-log/` shard — print its **run
+   record**: number of runs and the fraction with `verdict == "approved-unchanged"`. It is **advice**:
+   there is no threshold and nothing is "earned" (E34). Do not recommend flipping a dial; the team sets
+   dials with `yad dial`. A review gate is never auto.
 
 9. **My skills (the learning layer — local-only).** If `.sdlc/learning-records.json` exists for the epic
    (or the project-wide ledger does), print the **personal skills-log** roll-up from it — read-only. These
@@ -117,10 +175,10 @@ Print, in this order:
 
 10. **Fleet roll-up (overview only).** When the user asked for an overview, or more than one epic exists
     under `{project-root}/epics/`, print a one-line-per-epic roll-up across the fleet: each epic's
-    `currentStep` (front gate) and, for stories in the build half, a count of back-half steps **waiting
-    at a human gate** and of steps flagged **earned-but-manual**, plus a **local skills-log** count (records
+    `currentStep` (Shape gate) and, for stories in Build, a count of Build steps **waiting
+    at a human gate**, plus a **local skills-log** count (records
     in the local-only `learning-records.json`: learned / in-progress). Close with fleet totals (epics at
-    each front gate; total earned-but-manual back steps; total concepts learned locally across the fleet).
+    each Shape gate; total concepts learned locally across the fleet).
     This is the
     *scale-of-read* signal the Phase 5 trigger watches — when this roll-up stops fitting in one glance,
     that is the measured bottleneck. Still strictly read-only; it only scans the per-epic files.

package/skills/yad-stories/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: yad-stories
-description: 'Front state 7 of the gated SDLC. With the pm, break the approved epic into user stories, each tagged with the repos that must implement it. Assigns zero-padded EP-<slug>-S0N IDs and writes one file per story under stories/. Reads epic + architecture + contract + UI as input. Never auto-advances — hands off to the team review gate (per-repo reviewer routing). Use when the user says "author the stories" or after the UI gate passes.'
+description: 'Shape step 7 of the gated SDLC. With the pm, break the approved epic into user stories, each tagged with the repos that must implement it. Assigns zero-padded EP-<slug>-S0N IDs and writes one file per story under stories/. Reads epic + architecture + contract + UI as input. Never auto-advances — hands off to the team review gate (an ordinary approval-count gate). Use when the user says "author the stories" or after the UI gate passes.'
 ---
 
-# SDLC — Author Stories (front state 7)
+# SDLC — Author Stories (Shape step 7)
 
 **Goal:** Break an approved epic into human-authored, AI-assisted user stories, each with a stable
-`EP-<slug>-S0N` ID and a `repos` tag listing which repos must implement it. This is a **front state**:
+`EP-<slug>-S0N` ID and a `repos` tag listing which repos must implement it. This is a **Shape step**:
 human-authored with AI assist, **never auto-advances**. When the stories are drafted, control passes
-to `yad-review-gate`, which routes **per-repo reviewers** (each repo's engineer reviews the stories
-touching their repo).
+to `yad-review-gate`, an ordinary count gate: at least 1 distinct approver, who should not be the author. The stories'
+`repos` tags still say which repos a story touches, and the review PR is labelled with those repos.
 
 There is **no `sm` agent** (Phase 0 Deviation 1): the `pm` lens breaks down the epic; the `pm` or
 `architect` lens prepares each story's detail. IDs are engine-assigned and never renamed.
@@ -19,7 +19,7 @@ There is **no `sm` agent** (Phase 0 Deviation 1): the `pm` lens breaks down the
 - `{project-root}` resolves from the project working directory.
 - Stories live under `{project-root}/epics/EP-<slug>/stories/` (build plan §6).
 - Story files are named `EP-<slug>-S0N.md` (zero-padded, e.g. `EP-checkout-S01.md`).
-- 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
 
@@ -37,8 +37,8 @@ This passes when `stories` is the next runnable step per the state sequence —
 Open the stories authoring branch `stories/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 the story files under `stories/` on it. This is **distinct**
-from the bridge's `review/…` branch.
+Product's default branch. Author and commit the story files under `stories/` on it. This is **distinct**
+from the verified ledger's `review/…` branch.
 
 ### Step 2 — Read inputs
 Read `epic.md` (scope, acceptance signals, `repos`), `architecture.md` (components by repo, flows),
@@ -48,7 +48,18 @@ must collectively satisfy the epic's acceptance signals and stay within the cont
 - **UI-optional-safe:** `ui-design.md` may be absent — the `ui-design` step is optional and can be
   marked N/A for an epic with no user-facing surface (state.json shows it `skipped`). When there is no
   UI design, proceed without UI screens; the epic's acceptance signals + contract remain the source of
-  truth for the stories.
+  truth for the stories. If state.json shows it `deferred` instead, the UI **will** come later: write the
+  stories so they do not assume there are no screens, and note in each story that touches the UI that
+  its screens are still to be designed.
+- **Short-lane-safe:** `architecture.md` and `contract.md` may BOTH be absent, and on the `chore` and
+  `spike` routes they always are — those lanes carry no architecture step, so there is no locked
+  contract for this epic. Read `state.json`'s `profile` key first — an epic seeded before file shape 6
+  has no such key, so fall back to what its `steps[]` actually contains, which is the real answer
+  either way. On a short lane, write the stories
+  from `epic.md` alone and say so in each story's "Contract & design touchpoints" section. Because
+  there is no lock, a story on a short lane **must not change the shared cross-repo surface**: if the
+  work turns out to need that, stop and say so — the epic belongs on `classic`, which has the
+  architecture gate that locks the surface.
 
 ### 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
@@ -63,7 +74,7 @@ Phase 3 build (Spec Kit per repo) accurate anchors instead of invented ones.
 - **Traceability:** record the loaded maps in each story's `code-context:` frontmatter field.
 
 ### Step 3 — Break down the epic (assist: pm)
-Adopt the **pm** lens (`bmad-agent-pm`, John). Decompose the epic into the smallest set of
+Adopt the **pm** lens. Decompose the epic into the smallest set of
 independently reviewable, independently buildable stories. For each story decide which repos it touches
 (must be a subset of the epic's `repos`). Prefer stories scoped to a clear slice of user value.
 
@@ -102,36 +113,40 @@ As a <role>, I want <capability>, so that <outcome>.
 
 ### Step 6 — 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
 is pushed around the gate. Commit **the story files under `stories/` only** — nothing else
 under `.sdlc/` — then hand off to `yad-review-gate`.
 
-**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
-`stories.status: "done"`, set `stories-review.status: "in_review"`, and set
-`currentStep: "stories-review"`. Write `state.json`. Do **not** touch `approvals.json`.
+**Otherwise — local, or a platform with no gate-sync CI — the engine makes this edit, not you.**
+`yad gate open <epic> stories/` marks `stories-review` `in_review`, closes `stories` 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.
 
-> **File-only branch only.** Since 3.11 the CLI also closes the authoring step when its review gate
-> opens or advances, so this edit is a no-op once `yad gate open` has run. A `stories` step left
-> `in_progress` behind a passed `stories-review` used to block the parallel `test-cases` track
-> (`YAD-STATE-005`). In bridge mode `gate open` writes nothing and local `gate sync` is advisory —
-> `gate ci` closes the step at merge.
+**With no platform configured** it writes the ledger and simply opens no PR, so this works offline.
+**With a platform** the `review/EP-<slug>/stories` 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 7 — Stop at the gate (do NOT advance)
 Report: the story IDs created, the repos each touches, and that the next action is **review** via
-`yad-review-gate`. Note that this review routes **per-repo reviewers**: owner + 1 reviewer **plus**, for
-each repo appearing in any story's `repos`, a `domain-owner` approval for that repo. When this gate
-passes the epic becomes **`ready-for-build`** — the build half can start **and** the parallel
+`yad-review-gate`. This review is an ordinary count gate: it passes with at least 1 distinct approver (who
+should not be the author) and, with a platform, resolved threads and a merged review PR. It is not routed per repo, and it requests no
+reviewers — the team asks them on the review PR itself. When this gate
+passes the epic becomes **`ready-for-build`** — Build can start **and** the parallel
 **`test-cases`** track opens for the tester (`yad-test-cases`); the two run at the same time. **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`, with a `domain:<repo>` label per touched repo) and
+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`, with a `domain:<repo>` label per touched repo) and
 `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
-is recorded file-only.
+is recorded local.
 
 ## Reference
 - Story frontmatter and body template: `references/story-schema.md`.

package/skills/yad-stories/references/story-schema.md

@@ -1,6 +1,6 @@
 # Story schema
 
-Each story authored at front state 7 is one Markdown file under `epics/EP-<slug>/stories/`, named
+Each story authored at Shape step 7 is one Markdown file under `epics/EP-<slug>/stories/`, named
 `EP-<slug>-S0N.md` (zero-padded, never renamed).
 
 ## Frontmatter
@@ -9,10 +9,10 @@ Each story authored at front state 7 is one Markdown file under `epics/EP-<slug>
 |-------|--------|---------|
 | `id` | `EP-<slug>-S0N` | Stable story ID. Engine-assigned, zero-padded, never renamed. |
 | `epic` | `EP-<slug>` | Parent epic ID — the unbroken link back to the epic. |
-| `owner` | name | Inherited from `epic.md` `owner` (the single source — not retyped per story). Carries the responsible owner through to the build half. |
+| `owner` | name | Inherited from `epic.md` `owner` (the single source — not retyped per story). Carries the responsible owner through to Build. |
 | `status` | `draft` \| `in_review` \| `approved` | Story lifecycle within the stories gate. |
-| `repos` | subset of the epic's `repos` | Which repos must implement this story. **Drives per-repo review routing now and (Phase 3) where specs are scaffolded.** |
-| `code-context` | `{ repos: [<name@sha>], loaded: <date> }` | Optional. Which connected-repo code-maps anchored "Notes for build" (front state 7 Step 2b). The `@sha` (a repo's `syncedHead`) is recommended so freshness is recorded but may be omitted; the SKILL templates show the empty placeholder `{ repos: [], loaded: <date or none> }`. `none` / `[]` when no repos are connected. |
+| `repos` | subset of the epic's `repos` | Which repos must implement this story. **Labels the stories review PR with the touched repos now and (Phase 3) decides where specs are scaffolded.** |
+| `code-context` | `{ repos: [<name@sha>], loaded: <date> }` | Optional. Which connected-repo code-maps anchored "Notes for build" (Shape step 7 Step 2b). The `@sha` (a repo's `syncedHead`) is recommended so freshness is recorded but may be omitted; the SKILL templates show the empty placeholder `{ repos: [], loaded: <date or none> }`. `none` / `[]` when no repos are connected. |
 
 ## Body
 
@@ -38,9 +38,10 @@ As a <role>, I want <capability>, so that <outcome>.
 - **Stay within the contract surface.** "Notes for build" should reference the contract elements a
   story touches; a story may not invent cross-repo surface that `contract.md` does not define.
 
-## Per-repo review routing (the stories gate)
+## Review (the stories gate)
 
-`yad-review-gate` treats each repo's engineer as the `domain-owner` for the stories touching that repo.
-The gate passes only when, in addition to the base rule (owner + 1 reviewer), **every repo appearing in
-any story's `repos`** has at least one `domain-owner` approval scoped to that repo (`domain` = repo
-name). The gate's `approved.md` lists which repos still lack sign-off.
+The stories gate is an ordinary count gate. It passes with at least 1 distinct approver (who should not
+be the author) and, with a platform, resolved threads and a merged review PR. It is **not** routed per repo: no repo needs its own
+sign-off, and no role is checked. The union of every story's `repos` still names the touched repos, and
+the review PR carries a `domain:<repo>` label for each. The review PR requests no reviewers; the team
+asks them on the PR itself.

package/skills/yad-stub/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-stub
-description: 'Phase 6 brownfield helper — mint a STUB genesis epic for an already-built feature that has no epic in the hub, so a defect/change can thread off it TODAY. In a brownfield repo not every feature has an epic; yad-change requires a real parent and dead-ends without one. This skill creates the smallest real thread anchor — a tiny epic.md (kind:feature, thread:self, verified:false, stub:backfill-pending) + a seeded state.json + empty ledgers — never inventing behaviour. Defects thread off it immediately (gates pass, the bug list is derived by the thread rollup), and yad-backfill + its promote step later fill/flip it into a real feature epic. Never auto-advances. Use when the user says "there is no epic for this feature", "file a bug on a legacy feature", "anchor a brownfield feature", or when yad-change / yad-reconcile point here because a parent epic is missing.'
+description: 'Phase 6 brownfield helper — mint a STUB genesis epic for an already-built feature that has no epic in the Product, so a defect/change can thread off it TODAY. In a brownfield repo not every feature has an epic; yad-change requires a real parent and dead-ends without one. This skill creates the smallest real thread anchor — a tiny epic.md (type feature under both names, thread:self, verified:false, stub:backfill-pending) + a seeded state.json + empty ledgers — never inventing behaviour. Defects thread off it immediately (gates pass, the bug list is derived by the thread rollup), and yad-backfill + its promote step later fill/flip it into a real feature epic. Never auto-advances. Use when the user says "there is no epic for this feature", "file a bug on a legacy feature", "anchor a brownfield feature", or when yad-change / yad-reconcile point here because a parent epic is missing.'
 ---
 
 # SDLC — Stub Genesis Epic (Phase 6, the brownfield thread anchor)
@@ -13,19 +13,19 @@ stub is a **thread anchor, not a spec**: it invents no behaviour. It stays `veri
 
 This is the missing connective tissue in a brownfield adoption: `yad-backfill` produces a *draft spec in
 the code repo*, and `yad-reconcile` *detects* shipped code with no owning epic — but neither mints the
-hub epic a defect must thread from. `yad-stub` does exactly that, and only that.
+Product epic a defect must thread from. `yad-stub` does exactly that, and only that.
 
 ## Conventions
 
-- `{project-root}` resolves from the product hub. Epic artifacts live under
+- `{project-root}` resolves from the Product. Epic artifacts live under
   `{project-root}/epics/EP-<slug>/` (build plan §6), exactly like a normal genesis epic.
 - **A stub is NOT a reserved-empty id.** An epic in yad *is* a directory + `epic.md`; the tooling skips
   any epic dir lacking `epic.md` (`threadEpics`) and `lineage-check` rejects a parent that is not a real
   `epic.md`. So the stub is a real (if minimal) genesis — that is what makes it a valid parent.
-- The stub is a **genesis** (`kind: feature`, `thread == id`, no `parent`) — the root of a new thread.
+- The stub is a **genesis** (type `feature` under both names, `thread == id`, no `parent`) — the root of a new thread.
   Lineage frontmatter, the sentinel state, and the `stub`/`verified` fields are defined in
   `../yad-epic/references/state-schema.md` (Phase 6 section).
-- 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`.
 
 ## Inputs
 
@@ -44,26 +44,43 @@ not a stub case either. Confirm the brownfield-no-epic situation with the human
 
 ### Step 2 — Derive the stub epic id (engine-assigned, never by hand)
 Derive `EP-<slug>` where `slug` is **2–4 lowercase words** from the feature name (e.g.
-`EP-legacy-billing`). `EP-discovery` is **reserved** — never use it. Check `epics/` for collisions;
+`EP-legacy-billing`). `EP-foundation` and `EP-discovery` are **reserved** (the Product level) — never use either. Check `epics/` for collisions;
 append a distinguishing word if the slug exists. **The id is assigned once and never renamed** (a rename
 breaks every downstream link) — so pick from the best-known feature name and accept it as permanent.
 
 ### Step 3 — Open the authoring branch
 Open `epic/EP-<slug>` per the shared "Authoring branches" procedure
 (`../yad-epic/references/state-schema.md`): git-safe (skip with a note if `{project-root}` is not a git
-work tree), check out if it exists, else create from the hub's default branch.
+work tree), check out if it exists, else create from the Product's default branch.
 
 ### Step 4 — Write the stub `epic.md` (thread anchor — never invent behaviour)
 Write `{project-root}/epics/EP-<slug>/epic.md` using EXACTLY this shape:
 
+**Every key below is read by a machine, so write them BARE — no trailing `#` comment.** The
+frontmatter readers keep the whole rest of the line, so a comment becomes part of the value: a
+commented `stub:` stops `yad thread` and `yad-status` seeing the stub at all, and a commented `kind:`
+makes `lineage-check` refuse every commit that links a story to this epic. What they mean:
+
+| Key | Why it is here |
+|---|---|
+| `title` | the feature's one-line name, as the code shows it (such as `Order checkout`) — the name a list of work items shows for this stub. No invented behaviour. One line; no `#` comment; no YAML block (`>` or `\|`); quotes are optional. A title that begins with `[` and ends with `]` goes in double quotes (write an inner `"` as `\"`), or it is read as a list. The full rules are the `title` row of the `epic.md` frontmatter table in `../yad-epic/references/state-schema.md`. Leave it empty if you cannot name it from the code: the stub is then shown by its id |
+| `kind` + `type` | the work-item type, the same value under both names — `feature`, because a stub is a genesis / thread root and a valid parent for `lineage-check` |
+| `thread` | `thread == id` for a genesis |
+| `theme` | the optional grouping tag — one word or short phrase, in any language, shared by every epic in the group. Usually **empty here**: a stub is minted from code that already exists, not shaped in conversation, so there is normally nobody to say which group it is in. Fill it only if the user names one, and then copy an existing spelling exactly — `yad doctor` reports one theme spelled two ways, because two spellings group as two. One tag, never a list, and no `#` (the readers keep the whole rest of the line; the `#` the commands print is decoration on the screen) |
+| `verified` | `false` — not a real, human-authored epic yet, a stub awaiting backfill |
+| `stub` | `backfill-pending` — the honest marker; cleared on promote |
+
 ```markdown
 ---
 id: EP-<slug>
+title: <the feature's one-line name>
 status: draft
-kind: feature            # genesis / thread root — a valid parent for lineage-check + threads
-thread: EP-<slug>        # thread == id for a genesis
-verified: false          # not a real, human-authored epic yet — a stub awaiting backfill
-stub: backfill-pending   # the honest marker; cleared on promote
+kind: feature
+type: feature
+thread: EP-<slug>
+theme:
+verified: false
+stub: backfill-pending
 origin: brownfield
 owner:
 repos: [<the code repos this feature lives in>]
@@ -84,53 +101,47 @@ created: <YYYY-MM-DD>
 
 Leave `owner` for the human to set. Set `repos` to the code repo(s) the feature lives in.
 
-### Step 5 — Seed the stub `state.json` (a `backfill-pending` sentinel)
-Create `{project-root}/epics/EP-<slug>/.sdlc/state.json`. It carries the top-level marker
-`kind: "stub"` and the sentinel `currentStep: "backfill-pending"`, and the **same 10-step front chain**
-as a normal epic (`yad-epic` Step 5) but with **every step `status: "blocked"`** — so the state is valid
-(`validateState` needs a non-empty `steps` + a string `currentStep`) and `promote` can later "wake" it
-into normal authoring with zero re-seeding.
-
-```json
-{
-  "schemaVersion": 1,
-  "epicId": "EP-<slug>",
-  "createdAt": "<YYYY-MM-DD>",
-  "kind": "stub",
-  "currentStep": "backfill-pending",
-  "steps": [
-    { "id": "epic",               "type": "author",         "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "risk_tags": [] },
-    { "id": "epic-review",        "type": "review+approve", "artifact": "epic.md",          "assistance": "review", "automation": "human_approve", "locked": true,  "status": "blocked", "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": [] }
-  ]
-}
-```
+### Step 5 — Seed the stub ledger (a `backfill-pending` sentinel)
 
-Also create the empty ledgers `{.sdlc/approvals.json}` and `{.sdlc/comments.json}` (each `[]`) and the
-`reviews/` directory. **Do NOT** write a `contract-lock.json` — a stub has no locked surface yet.
+**Run the engine. Do not hand-write the chain.**
+
+```bash
+yad epic new EP-<slug> --stub
+```
 
-Commit the seed on this step's authoring branch; it reaches the hub's default branch through the
-epic's **first** review PR/MR (or, for a stub, the PR that carries the stub itself). In bridge mode
-`ledger-guard` exempts a new epic's ledger — creation, not mutation (#162) — while every later change
-to it stays CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
+That writes `{project-root}/epics/EP-<slug>/.sdlc/state.json` with the **same 10-step `classic` chain**
+a normal epic walks, but with **every step `todo`** (nobody is running it yet), the top-level marker
+`kind: "stub"`, and
+`currentStep: "backfill-pending"`. It also writes the empty `approvals.json` and `comments.json` and
+the `reviews/` directory. It writes no `epic.md`, no branch and no commit, and it refuses an epic that
+already has a `state.json`.
+
+**Do NOT** write a `contract-lock.json` — a stub has no locked surface yet.
+
+Notes:
+- **`kind` and `type` are different things and a stub carries both.** `kind: "stub"` is the lifecycle
+  marker the engine keys off; `type: "feature"` is the work-item type, copied from `epic.md`. A stub is
+  always a `feature` and always `classic` — `--type` and `--profile` are refused here, because
+  `yad-backfill promote` wakes the chain at its `epic` step and upkeep leaves nothing to backfill.
+- The blocked chain is what makes the state valid (`validateState` needs a non-empty `steps` and a
+  string `currentStep`) and what lets `promote` **wake** it into normal authoring with zero re-seeding.
+- Nothing in the chain is runnable until then: `preconditionsMet` refuses every step of an anchor, and
+  `yad next` routes the epic to `yad-backfill` rather than to authoring.
+- Commit the seed on this step's authoring branch; it reaches the Product's default branch through the
+  epic's **first** review PR/MR (or, for a stub, the PR that carries the stub itself). In verified mode
+  `ledger-guard` exempts a new epic's ledger — creation, not mutation (#162) — while every later change
+  to it stays CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
 
 ### Step 6 — Stop; hand off (NO auto-advance)
 Report the new `EP-<slug>`, that it is a **stub (backfill pending)**, and the two next moves:
-- **File bugs now:** `yad-change` (`--parent EP-<slug>`, `kind: defect|change`) — the defect threads off
+- **File bugs now:** `yad-change` (`--parent EP-<slug>`, type `defect|change`) — the defect threads off
   the stub, its gates pass, and `yad thread EP-<slug>` lists it. A defect off a stub inherits only what
   exists (the stub `epic.md`), re-authors its own stories/test-cases, and locks no contract (there is no
   surface yet — see `../yad-change/SKILL.md`).
 - **Make it real later:** `yad-backfill` for the code repo, then `yad-backfill promote EP-<slug>` to flip
   the stub to `verified: true`.
 
-Front states do not auto-advance. Suggest `yad next EP-<slug>` (prints the backfill-pending guidance) and
+Shape steps do not auto-advance. Suggest `yad next EP-<slug>` (prints the backfill-pending guidance) and
 `yad thread EP-<slug>` to see the anchor and everything threaded off it.
 
 ## Hard rules
@@ -143,7 +154,7 @@ Front states do not auto-advance. Suggest `yad next EP-<slug>` (prints the backf
 - **You never implement directly against a stub.** It owns no `stories/`, so there is nothing to
   implement against directly — real work threads off it as a change/defect epic (which has its own
   stories). (This is a convention of the empty stub, not a hard gate: `lineage-check` passes a
-  `kind: feature` genesis and `epic-open` treats a story-less epic as un-sealed, so neither blocks a
+  `feature`-type genesis and `epic-open` treats a story-less epic as un-sealed, so neither blocks a
   story mistakenly linked to the stub — keep the stub story-less.)
 - **Never auto-advances.** This skill seeds the anchor and stops; humans thread changes and run backfill.