yadflow 3.19.0-next.2 → 4.0.0-next.3

package/skills/yad-stories/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-stories
-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 (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 (Shape step 7)
@@ -8,8 +8,8 @@ description: 'Shape step 7 of the gated SDLC. With the pm, break the approved ep
 **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 **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,7 +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**
+Product's default branch. Author the story files under `stories/` on it, and end the step with `yad fold EP-<slug> stories` — the
+one commit the step keeps (E44). This is **distinct**
 from the verified ledger's `review/…` branch.
 
 ### Step 2 — Read inputs
@@ -48,7 +49,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 +75,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.
 
@@ -105,31 +117,35 @@ As a <role>, I want <capability>, so that <outcome>.
 **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: the `ledger-guard` check rejects
-any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+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`.
+under `.sdlc/` (`yad fold EP-<slug> stories` takes exactly these) — then hand off to `yad-review-gate`.
 
-**Otherwise — local, 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.
 
-> **local 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 verified 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
+`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.** Shape steps 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 local.
 

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

@@ -11,7 +11,7 @@ Each story authored at Shape step 7 is one Markdown file under `epics/EP-<slug>/
 | `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 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.** |
+| `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,46 +101,40 @@ 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 Shape 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 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".
+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`).
@@ -143,7 +154,7 @@ Shape steps do not auto-advance. Suggest `yad next EP-<slug>` (prints the backfi
 - **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.
 

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

@@ -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,6 +1,6 @@
 ---
 name: yad-test-cases
-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 (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 (Shape step 9 — parallel, non-blocking)
@@ -9,7 +9,7 @@ description: 'Shape step 9 of the gated SDLC — a PARALLEL, non-blocking track.
 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
 **Shape step**: 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).
+drafted, control passes to `yad-review-gate` (base rule: 1 distinct approver, who should not be the author).
 
 **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
@@ -17,8 +17,7 @@ the epic is already `ready-for-build`, so implementation (`yad-spec` → `yad-im
 (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,15 @@ 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 verified ledger's
+Product's default branch. Author `test-cases.md` on it, and end the step with `yad fold EP-<slug> test-cases` — the one commit the
+step keeps (E44). This is **distinct** from the verified ledger's
 `review/…` branch.
 
 ### Step 2 — Read inputs
@@ -62,7 +62,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 +79,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 +97,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
@@ -166,27 +168,34 @@ degraded (`testing: none`), do **not** write `test-links.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: the `ledger-guard` check rejects
-any non-bot commit touching `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or
+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 — **`test-cases.md` and, when a testing
-tool was used, `.sdlc/test-links.json`** (artifact-side, not ledger; generated tests live in their
+tool was used, `.sdlc/test-links.json`** (artifact-side, not ledger; `yad fold EP-<slug> test-cases` takes exactly these; generated tests live in their
 own code repo, not here) — then hand off to `yad-review-gate`.
 
-**Otherwise — local, 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 Build. 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
 Build 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.** Shape steps 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
+`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

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

@@ -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