yadflow 3.18.1 → 4.0.0-next.1

package/skills/yad-analysis/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: yad-analysis
-description: 'Optional front state 1 of the gated SDLC. With the analyst, pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP-<slug> ID and seeds .sdlc/ state (the 12-step chain that puts analysis before epic). Never auto-advances — hands off to the team review gate. Optional: if skipped, the epic step does this shaping inline. Use when the user says "analyse the idea", "start with analysis", or "author the analysis".'
+description: 'Optional Shape step 1 of the gated SDLC. With the analyst, pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP-<slug> ID and seeds .sdlc/ state (the 12-step chain that puts analysis before epic). Never auto-advances — hands off to the team review gate. Optional: if skipped, the epic step does this shaping inline. Use when the user says "analyse the idea", "start with analysis", or "author the analysis".'
 ---
 
-# SDLC — Author Analysis (optional front state 1)
+# SDLC — Author Analysis (optional Shape step 1)
 
 **Goal:** Produce a human-authored, AI-assisted `analysis.md` — the analyst's discovery brief that
 shapes the feature **before** the epic — assign its stable `EP-<slug>` ID, and initialise the per-epic
-state machine in `.sdlc/`. This is a **front state**: human-authored with AI assist and **never
+state machine in `.sdlc/`. This is a **Shape step**: human-authored with AI assist and **never
 auto-advances**. When the analysis is drafted, control passes to `yad-review-gate`.
 
 This step is **optional**. When it runs, it is the entry point: it assigns the ID and seeds the
@@ -15,26 +15,33 @@ This step is **optional**. When it runs, it is the entry point: it assigns the I
 analyst shaping inline and seeds the **10-step** chain — no behaviour change for teams that skip it.
 
 This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
-engine (never typed by hand); front steps are locked to `human_approve`.
+engine (never typed by hand); Shape steps are locked to `advance: human`.
 
 ## Conventions
 
 - `{project-root}` resolves from the project working directory.
 - Analysis artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
-- Speak in the configured `communication_language`; write documents in `document_output_language`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
 
 ## On Activation
 
 ### Step 1 — Get the idea
 Ask the user for a one-line feature idea if not provided.
 
-**Precondition gate (rail):** analysis is the optional first entry point and seeds state exactly once.
-If `.sdlc/state.json` already exists for the target epic, run `yad next EP-<slug> --check analysis`; if it
-exits non-zero, **STOP** and point the user at `yad next EP-<slug>` (the epic is past analysis). If it
-exits zero, resume analysis for that epic. When no `state.json` exists yet, proceed and seed state.
+**Precondition gate (rail):** the chain is seeded exactly once, and this skill is no longer the only
+thing that can have done it — `yad epic new <slug> --profile analysis-first` seeds the same 12-step
+chain from the CLI. So the question is whether `.sdlc/state.json` exists, not who wrote it:
+
+- **A chain already exists** — run `yad next EP-<slug> --check analysis`. If it exits non-zero, **STOP**
+  and point the user at `yad next EP-<slug>` (the epic is past analysis). If it exits zero, resume
+  analysis for that epic and **skip Step 6** (the chain is already there — re-seeding is refused anyway).
+- **No `state.json`** — this is the entry point. Run Step 6 to seed the chain.
+
+**Step 6b runs on both paths.** It is what closes the authoring step and opens its gate, and nothing
+else does it.
 
 ### Step 2 — Shape the idea (assist: analyst)
-Adopt the **analyst** lens (`bmad-agent-analyst`, Mary) to pressure-test the idea in depth: who is the
+Adopt the **analyst** lens to pressure-test the idea in depth: who is the
 user, what problem, what already exists, what options are on the table, what signals success, what is
 out of scope, and what the recommendation to the epic is. This is the discovery the epic will build on.
 
@@ -50,28 +57,37 @@ connected repo** (the epic's `repos` are not chosen yet), load the lightweight c
   stamp `code-context: stale` in the frontmatter.
 - **Traceability:** record which maps you loaded in the analysis frontmatter `code-context:` field.
 
-### Step 2c — Read the project roadmap (project context, only once discovery is APPROVED)
-Consume the project front-zero (`yad-discovery`) **only after its review gate has passed** — never a
-draft or in-review roadmap (that would bypass `discovery-review`). Gate on the **state**, not file
-existence: read `{project-root}/epics/EP-discovery/.sdlc/state.json` and proceed **only when
-`currentStep == "discovery-done"`**. When it is, read its `roadmap.md` and sibling `requirements.md`
-for the project framing: which phase (MVP / later) this feature belongs to and the requirements it
-carries — so the analysis's **Problem / Options / Recommendation** stay consistent with the approved
-roadmap. **Optional & non-blocking:** if there is no discovery, or it has not yet reached
-`discovery-done`, proceed unchanged — do not consume an unapproved roadmap.
+### Step 2c — Read the Foundation (product context, only once it is APPROVED)
+Consume the Product level (written by `yad-discovery`) **only after its review gate has passed** — never
+a draft or in-review one (that would bypass its gate). Gate on the **state**, not file existence:
+- **The Foundation:** read `{project-root}/foundation/.sdlc/state.json` and proceed **only when
+  `currentStep == "foundation-done"`**. Then read `foundation/purpose.md`, `scope.md`, `mvp.md` and
+  `roadmap.md` for the product framing.
+- **The old spelling**, only when there is no Foundation: read
+  `{project-root}/epics/EP-discovery/.sdlc/state.json` and proceed **only when
+  `currentStep == "discovery-done"`**. Then read its `roadmap.md` and sibling `requirements.md`.
+
+Use it for: which phase (MVP / later) this feature belongs to, what the product explicitly is **not**,
+and the requirements it carries — so the analysis's **Problem / Options / Recommendation** stay
+consistent with the approved product. **Optional & non-blocking:** if there is no product level, or it
+has not passed its gate yet, proceed unchanged — do not consume an unapproved one. (`yad next` reports
+feature work that goes ahead of an unapproved Foundation; it never blocks it.)
 
 ### Step 3 — Generate the Epic ID (engine-assigned, never by hand)
+*(Skip when `state.json` already exists — the id was assigned by whatever seeded the chain.)*
 Derive `EP-<slug>` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea
-(e.g. `EP-checkout`). Lowercase except the fixed `EP` prefix. `EP-discovery` is **reserved**
-for the project front-zero — never use it for a feature. **The ID is assigned once and
+(e.g. `EP-checkout`). Lowercase except the fixed `EP` prefix. `EP-foundation` and `EP-discovery` are
+**reserved** for the Product level — never use either for a feature. **The ID is assigned once and
 never renamed** — renaming breaks every downstream link (build plan §6b). Check
-`{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word.
+`{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word. When the
+Foundation's `roadmap.md` has a row for this feature, prefer that row's **proposed epic id**, so
+`yad foundation status` can match the feature to its epic.
 
 ### Step 4 — Open the authoring branch
 Open the analysis authoring branch `analysis/EP-<slug>` per the shared procedure
-(`references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if `{project-root}`
-is not a git work tree), check out the branch if it exists, else create it from the hub's default
-branch. Author and commit `analysis.md` on it. This is **distinct** from the bridge's `review/…` branch.
+(`../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 Product's default
+branch. Author and commit `analysis.md` on it. This is **distinct** from the verified ledger's `review/…` branch.
 
 ### Step 5 — Write the analysis (assist: analyst)
 Write `{project-root}/epics/EP-<slug>/analysis.md` using EXACTLY this template:
@@ -101,57 +117,101 @@ code-context: { repos: [], loaded: <YYYY-MM-DD or none> }   # which code-maps in
 
 Fill the body with the user; leave `owner` for the user to set.
 
-### Step 6 — Seed the state machine
-Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **12-step** front-state
-sequence (analysis before epic), all steps defaulting to `automation: human_approve`, with every
-authoring step **locked**. Use this exact shape (see `references/state-schema.md`):
-
-```json
-{
-  "schemaVersion": 1,
-  "epicId": "EP-<slug>",
-  "createdAt": "<YYYY-MM-DD>",
-  "currentStep": "analysis-review",
-  "steps": [
-    { "id": "analysis",           "type": "author",         "artifact": "analysis.md",      "assistance": "review", "automation": "human_approve", "locked": true,  "status": "done",        "risk_tags": [] },
-    { "id": "analysis-review",    "type": "review+approve", "artifact": "analysis.md",      "assistance": "review", "automation": "human_approve", "locked": true,  "status": "in_review",   "risk_tags": [] },
-    { "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 6 — Seed the state machine — only when nothing is seeded
+*(Skip when `state.json` already exists — `yad epic new --profile analysis-first` seeded it. Go to
+Step 6b. Re-seeding would overwrite a ledger, and in verified mode that is the mutation
+`ledger-guard` rejects.)*
+
+**Run the engine. Do not hand-write the chain.**
+
+```bash
+yad epic new EP-<slug> --profile analysis-first --type <feature|chore>
+yad epic new EP-<slug> --profile spike --type <feature|chore>   # a timeboxed investigation
 ```
 
+That writes `{project-root}/epics/EP-<slug>/.sdlc/state.json`, the empty `approvals.json` and
+`comments.json`, and the `reviews/` directory. With `--profile analysis-first` the chain is the full
+**12-step** route (`analysis` before `epic`). Every step is `advance: human` and locked; `analysis` is
+open and the rest are `todo`. The chain comes from the step catalogue and the lifecycle profile in
+the engine (`../yad-epic/references/state-schema.md`), so there is one definition of it and no copy
+here to drift from it.
+
+**Ask whether this is a spike before you seed.** `analysis-first` is the right answer when the
+analysis is the front of a real feature. When the work IS the investigation — a timeboxed question
+whose output is a finding and a throwaway prototype — `--profile spike` seeds a **6-step** lane
+instead: `analysis → analysis-review → epic → epic-review → stories → stories-review`, with no
+architecture, UI-design or test-case steps. `analysis` is still the open first step either way, so
+every step below this one is unchanged.
+
+A spike has **no architecture gate, so no `contract.md` and no lock**, and no step on it is optional —
+`yad skip` is refused. **Choose the route before you seed, because the choice is final:** there is no
+re-seed. If the investigation concludes that the shared cross-repo surface has to move, the follow-up
+belongs on `classic` — the spike records the finding, and a NEW epic builds it.
+
+It writes no `analysis.md`, no branch and no commit, and it refuses an epic that already has a
+`state.json`. There is no `epic.md` at this point, so pass `--type` (it defaults to `feature`).
+
 Notes:
-- `analysis-review` carries no `risk_tags` — it is the **base** rule (owner + 1 reviewer).
-- `architecture-review` carries `risk_tags: ["contract"]` so the gate escalates it by default
-  (build plan §4): the contract review needs domain owners, not just owner + 1.
-- `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `blocked` and open
-  when `stories-review` passes — the epic is already `ready-for-build` by then, so the build half runs
-  alongside the tester (see `../yad-epic/references/state-schema.md`).
-- Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
-  and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
-  `[]`, and the `reviews/` directory.
+- **Then advance the authoring step.** The seed leaves `analysis` open, which is truthful: the command
+  runs before the artifact exists. Closing it is Step 6b's job, and on the local path `yad gate open`
+  does it — so after writing `analysis.md`, take Step 6b.
+- `analysis-review` carries no `risk_tags` — it is the **base** rule (1 distinct approver, who
+  should not be the author). The catalogue sets that; there is nothing to type.
+- `architecture-review` carries `risk_tags: ["contract"]` by default (build plan §4): the tag raises
+  the step's full approver count to 3 (base 1 + contract risk 2). Only the base holds the
+  gate; the risk step is advisory, reported as a shortfall against the count capped at the
+  active people less one (E72).
+- `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `todo` and open
+  when `stories-review` passes — the epic is already `ready-for-build` by then, so Build
+  runs alongside the tester (see `../yad-epic/references/state-schema.md`).
 - Commit the seed on the `analysis/EP-<slug>` branch, and cut `review/EP-<slug>/analysis` from it so the
-  epic's **first** review PR/MR carries the ledger to the default branch. In bridge mode `ledger-guard`
+  epic's **first** review PR/MR carries the ledger to the default branch. In verified mode `ledger-guard`
   exempts a new epic's ledger (creation, not mutation, #162); every later change to it is CI's. See
   `../yad-epic/references/state-schema.md`, "Authoring branches".
+- **No UI, on a verified Product?** The analysis review PR is this epic's first, so until it merges is the
+  only time `yad skip` can write the ledger. If the idea clearly has no user-facing surface, offer
+  `yad skip EP-<slug> ui-design --reason "<why>"` now; after that PR merges, CI owns `state.json` and the
+  skip is refused. On a local ledger there is no hurry: `yad-ui` offers the same skip later.
+
+### Step 6b — Open the analysis review gate
+*(**Always run this**, on both entry modes. The chain is seeded by now either way — by `yad epic new`
+in Step 6, or by `yad epic new` before this skill was invoked — and `analysis.md` is written. This is
+the step that closes the authoring step and opens its gate.)*
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**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.
+
+**verified mode — do NOT write `state.json`.** The ledger is CI-owned and advancing a step is a
+mutation: `ledger-guard` rejects any non-bot commit that changes one, and `yad gate ci --merged`
+performs the whole transition when the review PR merges.
+
+**Do not EDIT the ledger — but do COMMIT it when it is untracked.** Those are two different acts.
+Commit `analysis.md`, and also `.sdlc/state.json`, `.sdlc/approvals.json` and `.sdlc/comments.json`
+when `git status` shows them **untracked** — an engine-seeded ledger has never been reviewed, so it is
+still off the base ref and `ledger-guard` exempts it (creation, not mutation, #162). It rides this
+epic's first review PR exactly as a Step 6 seed does. Leave their contents alone.
+
+**Otherwise — local, or a platform with no gate-sync CI — the engine makes this edit, not you.**
+`yad gate open <epic> analysis.md` marks `analysis-review` `in_review`, closes `analysis` as `done`,
+and moves `currentStep` to the gate — the same transition, from the one function that owns it (`markInReview`, `cli/epic-state.mjs`).
+`yad-review-gate action: open` runs that command; hand off to it rather than editing the ledger here.
+
+**With no platform configured** it writes the ledger and simply opens no PR, so this works offline.
+**With a platform** the `review/EP-<slug>/analysis` branch must already be **on origin** — the command refuses
+and writes nothing otherwise. Cut it from the authoring branch and push it before handing off
+(`yad open-pr` does both, then delegates).
+
+Do **not** hand-edit `state.json`, do **not** re-seed, and do **not** touch `approvals.json` — only real
+reviewers approve, through the gate.
 
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: epic ID, the path to `analysis.md`, and that the next action is **review** via
-`yad-review-gate` (base rule: owner + 1 reviewer). **Never mark the analysis-review step approved
-here** — only real reviewers do that through the gate. Front states do not auto-advance. When the
+`yad-review-gate` (base rule: 1 distinct approver, who should not be the author). **Never mark the analysis-review step approved
+here** — only real reviewers do that through the gate. Shape steps do not auto-advance. When the
 analysis gate passes, control moves to `yad-epic`, which reads `analysis.md` as input. When the
-hub has a platform, the gate opens a review PR on the hub (via `yad-hub-bridge`) and
+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 file-only.
+is recorded local.
 
 ## Reference
 - State schema, the two chain shapes, and the authoring-branch procedure:

package/skills/yad-architecture/SKILL.md

@@ -1,24 +1,24 @@
 ---
 name: yad-architecture
-description: 'Front state 3 of the gated SDLC. With the architect, author architecture.md and the locked contract.md (the shared cross-repo surface), then hash-lock the contract surface into .sdlc/contract-lock.json. Reads epic.md as input. Never auto-advances — hands off to the team review gate (which escalates on the contract risk tag). Use when the user says "author the architecture" or after the epic gate passes.'
+description: 'Shape step 3 of the gated SDLC. With the architect, author architecture.md and the locked contract.md (the shared cross-repo surface), then hash-lock the contract surface into .sdlc/contract-lock.json. Reads epic.md as input. Never auto-advances — hands off to the team review gate (the contract risk tag raises its approver count). Use when the user says "author the architecture" or after the epic gate passes.'
 ---
 
-# SDLC — Author Architecture + Contract (front state 3)
+# SDLC — Author Architecture + Contract (Shape step 3)
 
 **Goal:** Produce a human-authored, AI-assisted `architecture.md` and the **locked** `contract.md`
 for an approved epic, then record a hash-lock of the contract surface so a later contract-check can
-detect drift. This is a **front state**: human-authored with AI assist, **never auto-advances**.
-When both artifacts are drafted, control passes to `yad-review-gate`, which **escalates** this review
-by default (the architecture step carries `risk_tags: ["contract"]`).
+detect drift. This is a **Shape step**: human-authored with AI assist, **never auto-advances**.
+When both artifacts are drafted, control passes to `yad-review-gate`. The architecture step carries
+`risk_tags: ["contract"]` by default, which raises the review's (advisory) approver count.
 
 This skill enforces the build plan's core rules: all state lives in files; the contract holds only the
-shared cross-repo surface at charter altitude; front steps stay locked to `human_approve`.
+shared cross-repo surface at charter altitude; Shape steps stay locked to `advance: human`.
 
 ## Conventions
 
 - `{project-root}` resolves from the project working directory.
 - Artifacts live under `{project-root}/epics/EP-<slug>/` (build plan §6).
-- Speak in the configured `communication_language`; write documents in `document_output_language`.
+- Speak in the `communication_language` set in `{project-root}/.sdlc/config.yaml`; write documents in `document_output_language`.
 
 ## On Activation
 
@@ -36,8 +36,8 @@ This passes when `architecture` is the next runnable step per the state sequence
 Open the architecture authoring branch `architecture/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 `architecture.md` / `contract.md` / `contract-lock.json` on it.
-This is **distinct** from the bridge's `review/…` branch.
+Product's default branch. Author and commit `architecture.md` / `contract.md` / `contract-lock.json` on it.
+This is **distinct** from the verified ledger's `review/…` branch.
 
 ### Step 2 — Read the epic as input context
 Read `epic.md`. Note `repos` (the touched domains), the goal, scope, and acceptance signals. The
@@ -63,7 +63,7 @@ is always present.)
   `references/code-context.md`).
 
 ### Step 3 — Author the architecture (assist: architect)
-Adopt the **architect** lens (`bmad-agent-architect`, Winston) and write
+Adopt the **architect** lens and write
 `{project-root}/epics/EP-<slug>/architecture.md` using EXACTLY this template:
 
 ```markdown
@@ -179,30 +179,41 @@ awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
 
 ### 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 artifact set — **`architecture.md`, `contract.md`, and
 `.sdlc/contract-lock.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
-`architecture.status: "done"`, set `architecture-review.status: "in_review"`, and set
-`currentStep: "architecture-review"`. Write `state.json`. Do **not** touch `approvals.json` — only
-real reviewers approve, through the gate. 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> architecture.md` marks `architecture-review` `in_review`, closes `architecture` as `done`, and moves `currentStep` to the gate
+— the same transition, from the one function that owns it (`markInReview`, `cli/epic-state.mjs`).
+`yad-review-gate action: open` runs that command; hand off to it rather than editing the ledger here.
+
+**With no platform configured** it writes the ledger and simply opens no PR, so this works offline.
+**With a platform** the `review/EP-<slug>/architecture` 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 paths to `architecture.md`, `contract.md`, and `contract-lock.json`; the contract hash;
-and that the next action is **review** via `yad-review-gate`. Note that this review **escalates**
-(risk tag `contract`): it needs owner + 1 reviewer **plus a domain owner for each touched repo**.
-**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`, labelled per touched repo) and
+and that the next action is **review** via `yad-review-gate`. Because of the risk tag `contract`, the
+step's full approver count is 3 distinct people (base 1 + contract risk 2), none of whom should be the
+author. Only the base (1 distinct approver) holds the gate; the risk step is advisory. The engine caps
+the count at the active people less one, floor 1, and prints it (E72) — with 2 active people the capped
+ask is 1, with 3 it is 2, with 4 or more all 3 — and a shortfall never holds the gate. When the people
+cannot be counted (as in Product CI with connected repos), no cap is shown. The review PR requests no reviewers; the team asks them on the PR itself.
+**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`, labelled per touched repo) and
 `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; a contract re-lock
-invalidates prior platform approvals too. Otherwise the review is recorded file-only.
+invalidates prior platform approvals too. Otherwise the review is recorded local.
 
 ## Reference
 - Contract surface, altitude rule, and hashing recipe: `references/contract-format.md`.

package/skills/yad-architecture/references/contract-format.md

@@ -1,8 +1,8 @@
 # Contract surface — format, altitude, and hash-lock
 
-The `contract.md` produced at front state 3 is the **single source of truth for the shared cross-repo
-surface** of an epic. Phase 3's contract-check (not built yet) fails a PR when a repo drifts from this
-surface. To make that check possible, the surface is delimited and hash-locked now.
+The `contract.md` produced at Shape step 3 is the **single source of truth for the shared cross-repo
+surface** of an epic. The contract-check gate (`yad-checks`) fails a code-repo PR that changes its copy of
+this surface without a `Contract-Change: yes` trailer and a re-locked contract. To make that check possible, the surface is delimited and hash-locked now.
 
 ## What goes in the surface (altitude rule)
 
@@ -62,14 +62,16 @@ awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
 
 ## Interaction with the review gate
 
-- The `architecture-review` step carries `risk_tags: ["contract"]`, so `yad-review-gate` **escalates**
-  it: owner + 1 reviewer **plus** one `domain-owner` approval per repo in the epic's `repos`.
+- The `architecture-review` step carries `risk_tags: ["contract"]`. The tag sets the step's approver
+  count — 3 distinct people (base 1 + contract risk 2). `yad-review-gate` enforces only the base (1
+  distinct approver, who should not be the author); the risk step is reported as a shortfall
+  against the count capped at the active people less one (E72), and does not hold the gate. No per-repo or role approval is required. The review PR names
+  and labels the epic's `repos`.
 - **Staleness:** if the surface block is edited after approvals are recorded, the recomputed hash will
   not match the lock — approvals are stale and the gate drops back to `comment`. Re-lock (Step 5 of the
   skill) and re-approve.
 
 ## Why a hash (vs structured diff)
 
-A hash is the smallest representation that proves "did the agreed surface change?" — which is all the
-front half needs. A field-by-field structured diff is a Phase 3 concern (it tells you *what* drifted in
-a failing PR); the lock established here is what that future check compares against.
+A hash is the smallest representation that proves "did the agreed surface change?" — which is all Shape needs. A field-by-field structured diff is a Phase 3 concern (it tells you *what* drifted in
+a failing PR); the lock established here is what the contract-check compares against.

package/skills/yad-backfill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-backfill
-description: 'Build-half Step G of the gated SDLC — backfill: generate specs for already-built features in an existing repo so new work does not break them. Confirm Repomix (the one true CLI subprocess: npx repomix), pack ONE feature at a time (compress + git logs, secret-scan), feed it to AI with a "describe what exists, do not invent" prompt, and write a DRAFT spec marked unverified. Require human approval (reuse yad-review-gate) before the spec counts as real. Boundary is auto-proposed from the project convention and human-confirmed. A change is blocked only until the features IT touches have approved specs. The `promote` action flips a brownfield stub epic (minted by yad-stub, so defects could thread off it) to a real, verified feature epic once its backfill spec is approved. Use when the user says "backfill specs", "document an existing feature", "spec the legacy code", or "promote the stub epic".'
+description: 'Build Step G of the gated SDLC — backfill: generate specs for already-built features in an existing repo so new work does not break them. Confirm Repomix (the one true CLI subprocess: npx repomix), pack ONE feature at a time (compress + git logs, secret-scan), feed it to AI with a "describe what exists, do not invent" prompt, and write a DRAFT spec marked unverified. Require human approval (reuse yad-review-gate) before the spec counts as real. Boundary is auto-proposed from the project convention and human-confirmed. A change is blocked only until the features IT touches have approved specs. The `promote` action flips a brownfield stub epic (minted by yad-stub, so defects could thread off it) to a real, verified feature epic once its backfill spec is approved. Use when the user says "backfill specs", "document an existing feature", "spec the legacy code", or "promote the stub epic".'
 ---
 
 # SDLC — Backfill (existing-code specs)
@@ -66,8 +66,8 @@ Mark every uncertain item explicitly (`<!-- unverified: ... -->`); do not fill g
 behaviour.
 
 ### Step 4 — `approve` (human approval — reuse the gate)
-A human reads the draft against the real code and approves it with the same `human_approve` discipline
-as `yad-review-gate` (owner + 1 reviewer). On approval set the frontmatter `verified: true` and record
+A human reads the draft against the real code and approves it with the same `advance: human` discipline
+as `yad-review-gate` (at least 1 approver who is not the author). On approval set the frontmatter `verified: true` and record
 the approver(s) + date. Only a `verified: true` backfill spec counts as real.
 
 ### Step 5 — `gate` (block changes per touched feature)
@@ -89,20 +89,26 @@ thread off it, `promote` is what makes that anchor real — run it once the feat
   and `yad thread` / `yad-status` (read `epic.md`) will disagree about whether the epic is still a stub.
   - **`epic.md`:** set `verified: true`, **remove** the `stub:` marker, and add a `backfill:` block linking
     the approved spec, e.g. `backfill: { spec: specs/backfill/<feature>/spec.md, promoted: <YYYY-MM-DD> }`.
+    Keep the stub's `title:`; set one now if it has none (the one-line name of the feature), by the
+    rules in the `title` row of the `epic.md` frontmatter table in `../yad-epic/references/state-schema.md`.
   - **`state.json`:** **remove** the top-level `kind: "stub"`, and move `currentStep` off the
-    `backfill-pending` sentinel (per the promote flavour below).
+    `backfill-pending` sentinel (per the promote flavour below). **Leave the top-level `type` exactly
+    as it is.** `kind` and `type` are two different things in this file: `kind: "stub"` is the
+    lifecycle marker you are clearing, and `type: "feature"` is the work-item type, which a promoted
+    stub still has. Nothing would report its loss — `yad doctor` only compares a `type` that is
+    there — so the ledger would quietly stop saying what kind of work it holds.
 - **Light promote (default):** the feature's documentation lives in the approved backfill spec — do NOT
-  wake the front chain. Set `state.json` `currentStep: "backfill-done"` (a terminal sentinel, like
+  wake the Shape chain. Set `state.json` `currentStep: "backfill-done"` (a terminal sentinel, like
   `discovery-done`): the epic is now a real, verified anchor and its later evolution threads normally with
   `yad-change`. `yad next` then reports it as a documented anchor, not a pending stub.
-- **Full promote (opt-in):** to bring the feature fully under the front half and lock a real contract,
+- **Full promote (opt-in):** to bring the feature fully under Shape and lock a real contract,
   "wake" the state chain — set `currentStep: "epic"`, `epic` step `status: "in_progress"` — then run
   `yad-epic` → `yad-architecture` → … the normal way. This re-locks a contract that subsequent thread
   changes will inherit.
-- **Bridge mode — promote is not wired.** The `state.json` edits above mutate an epic whose ledger is
+- **verified mode — promote is not wired.** The `state.json` edits above mutate an epic whose ledger is
   already on the base ref, so the `#162` seed exemption does not apply and `ledger-guard` rejects the
   commit; unlike the authoring steps there is no `yad backfill` CLI and no `gate ci` path that performs
-  the promotion instead. On a bridge hub, STOP and report this — the promotion needs the gate bot (or a
+  the promotion instead. On a verified Product, STOP and report this — the promotion needs the gate bot (or a
   maintainer landing it out of band). Only the `epic.md` half is safe to commit. Tracked as a gap; do
   **not** push the ledger edit around the guard.
 - Never auto-advances; a human confirms the promotion.

package/skills/yad-backfill/references/backfill.md

@@ -45,7 +45,7 @@ generated: <YYYY-MM-DD>
 ---
 ```
 
-`verified: false` until a human approves (the `yad-review-gate` discipline: owner + 1 reviewer). On
+`verified: false` until a human approves (the `yad-review-gate` discipline: at least 1 approver who is not the author). On
 approval, set `verified: true` and record the approver(s) + date. Only a `verified: true` backfill spec
 counts as real.