yadflow 3.18.0 → 3.19.0-next.2

package/skills/yad-epic/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: yad-epic
-description: 'Front state for the epic in the gated SDLC. Shape a feature idea with the analyst (or read analysis.md when the optional analysis step already ran), then write the epic with the pm, into epic.md. The entry point when analysis is skipped: assigns the EP-<slug> ID and seeds .sdlc/ state. Never auto-advances — hands off to the team review gate. Use when the user says "start a new feature/epic" or "author an epic".'
+description: 'Shape step for the epic in the gated SDLC. Shape a feature idea with the analyst (or read analysis.md when the optional analysis step already ran), then write the epic with the pm, into epic.md. The entry point when analysis is skipped: assigns the EP-<slug> ID and seeds .sdlc/ state. Never auto-advances — hands off to the team review gate. Use when the user says "start a new feature/epic" or "author an epic".'
 ---
 
-# SDLC — Author Epic (front state)
+# SDLC — Author Epic (Shape step)
 
 **Goal:** Produce a human-authored, AI-assisted `epic.md` for a new feature, and — when the epic is the
 entry point — assign its stable `EP-<slug>` ID and initialise the per-epic state machine in `.sdlc/`.
-This is a **front state**: human-authored with AI assist and **never auto-advances**. When the epic is
+This is a **Shape step**: human-authored with AI assist and **never auto-advances**. When the epic is
 drafted, control passes to `yad-review-gate`.
 
 **Two entry modes** (the optional `yad-analysis` step decides which):
@@ -17,7 +17,7 @@ drafted, control passes to `yad-review-gate`.
   idea inline with the analyst, assigns `EP-<slug>`, and seeds the **10-step** chain.
 
 This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
-engine (never typed by hand); front steps are locked to `human_approve`.
+engine (never typed by hand); Shape steps are locked to `human_approve`.
 
 ## Conventions
 
@@ -92,7 +92,7 @@ Check `{project-root}/epics/` for collisions; if the slug exists, append a disti
 Open the epic authoring branch `epic/EP-<slug>` per the shared procedure
 (`references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if `{project-root}`
 is not a git work tree), check out the branch if it exists, else create it from the hub's default
-branch. Author and commit `epic.md` on it. This is **distinct** from the bridge's `review/…` branch.
+branch. Author and commit `epic.md` on it. This is **distinct** from the verified ledger's `review/…` branch.
 
 ### Step 4 — Write the epic (assist: pm)
 Adopt the **pm** lens (`bmad-agent-pm`, John) and write `{project-root}/epics/EP-<slug>/epic.md`
@@ -122,7 +122,7 @@ Fill the body with the user; leave `owner` / `technical_product_owner` for the u
 
 ### Step 5 — Seed the state machine — analysis-skipped only
 *(Skip when analysis ran — `yad-analysis` already seeded the 12-step chain. Go to Step 5b.)*
-Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **10-step** front-state
+Create `{project-root}/epics/EP-<slug>/.sdlc/state.json` describing the full **10-step** Shape step
 sequence (no analysis), all steps defaulting to `automation: human_approve`, with the five authoring
 steps **locked**. Use this exact shape (see `references/state-schema.md`):
 
@@ -151,11 +151,11 @@ Notes:
 - `architecture-review` carries `risk_tags: ["contract"]` so the gate escalates it by default
   (build plan §4): the contract review needs domain owners, not just owner + 1.
 - `test-cases` / `test-cases-review` are a **parallel, non-blocking track**: they seed `blocked` and open
-  when `stories-review` passes — at which point the epic is already `ready-for-build`, so the build half
+  when `stories-review` passes — at which point the epic is already `ready-for-build`, so Build
   runs alongside the tester. They never gate `ready-for-build` (see `references/state-schema.md`).
 - Commit the seed on this step's authoring branch. It reaches the hub's default branch through the
   epic's **first** review PR/MR — cut `review/EP-<slug>/epic` from the authoring branch so it carries
-  the seed. In bridge mode `ledger-guard` exempts a new epic's ledger (creation, not mutation, #162);
+  the seed. In verified mode `ledger-guard` exempts a new epic's ledger (creation, not mutation, #162);
   every later change to it is CI's. See `references/state-schema.md`, "Authoring branches".
 - Also create an empty approvals ledger `{project-root}/epics/EP-<slug>/.sdlc/approvals.json`
   and an empty comments ledger `{project-root}/epics/EP-<slug>/.sdlc/comments.json`, each containing
@@ -171,9 +171,9 @@ Notes:
 ### Step 5b — Advance the authoring step — analysis-ran only
 *(Only when analysis ran — `state.json` already exists from `yad-analysis`.)*
 **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
+**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
 `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
@@ -185,23 +185,23 @@ to `yad-review-gate`.
 > (creation, not mutation, #162). On this path `state.json` already exists from `yad-analysis` and
 > reached the base ref through the analysis review — so the guard is absolute here.
 
-**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+**Otherwise — local, or a platform with no gate-sync CI — write it.** In `state.json`: set
 `epic.status: "done"`, set `epic-review.status: "in_review"`, and set `currentStep: "epic-review"`.
 Write `state.json`. Do **not** re-seed and do **not** touch `approvals.json` — only real reviewers
 approve, through the gate.
 
-> **File-only branch only.** Since 3.11 the CLI closes the authoring step itself whenever its review
+> **local branch only.** Since 3.11 the CLI closes the authoring step itself whenever its review
 > gate opens or advances (`yad gate open` / `sync`), so this edit is a no-op when the gate has already
 > run. It keeps `state.json` truthful before the gate opens, but it is no longer load-bearing: an epic
-> whose author step is left `in_progress` used to strand forever (`YAD-STATE-005`). In bridge mode
+> whose author step is left `in_progress` used to strand forever (`YAD-STATE-005`). In verified mode
 > `gate open` writes nothing and local `gate sync` is advisory — `gate ci` closes the step at merge.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: epic ID, the path to `epic.md`, and that the next action is **review** via
 `yad-review-gate`. **Never mark the epic-review step approved here** — only real reviewers do that
-through the gate. Front states do not auto-advance. When the hub has a platform, the gate opens a review
+through the gate. 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 into the ledger; otherwise the review is recorded file-only.
+comments into the ledger; otherwise the review is recorded local.
 
 ## Reference
 - State schema and field meanings: `references/state-schema.md`.

package/skills/yad-epic/references/state-schema.md

@@ -44,7 +44,7 @@ The per-epic state machine.
 | `epicId` | The stable `EP-<slug>` ID. Never renamed. |
 | `createdAt` | ISO date the epic was created. |
 | `currentStep` | `id` of the step the workflow is waiting on right now. |
-| `steps[]` | Ordered list of every front-state step. |
+| `steps[]` | Ordered list of every Shape step step. |
 
 Each `steps[]` entry:
 
@@ -99,8 +99,8 @@ skippable today (engine `SKIPPABLE_STEPS`).
 ### `test-cases` is a parallel, non-blocking track
 
 `test-cases` (and its `test-cases-review` gate) sit in `steps[]` after `stories-review`, but they are a
-**parallel track that does not gate the build half**. When `stories-review` passes, `advanceState`:
-- sets `currentStep` to the **`ready-for-build`** sentinel — so the build half (`yad-spec` → … keyed off
+**parallel track that does not gate Build**. When `stories-review` passes, `advanceState`:
+- sets `currentStep` to the **`ready-for-build`** sentinel — so Build (`yad-spec` → … keyed off
   `currentStep == "ready-for-build"`) can start **immediately**, and
 - opens `test-cases` (`blocked` → `in_progress`) so the tester can work **in parallel**.
 
@@ -116,7 +116,7 @@ unchanged.)
 
 Each front **authoring** step opens its own git branch at the start of the step, named
 `<step>/EP-<slug>` where `<step>` ∈ `analysis | epic | architecture | ui-design | stories | test-cases`
-(`config.yaml` `defaults.front_authoring_branch`). This is **distinct** from the review branch
+(`config.yaml` `defaults.shape_authoring_branch`). This is **distinct** from the review branch
 `review/EP-<slug>/<artifact-base>` that `yad-hub-bridge` opens later for the review PR/MR.
 
 The shared procedure (run once the `EP-<slug>` is known):
@@ -125,7 +125,7 @@ The shared procedure (run once the `EP-<slug>` is known):
    tree — no error.
 2. Branch name = `<step>/EP-<slug>`. If it already exists, check it out; otherwise create it from the
    hub's default branch (`git checkout -b <step>/EP-<slug>`).
-3. Author and commit the step's artifact(s) on that branch. The bridge's `review/…` branch is created
+3. Author and commit the step's artifact(s) on that branch. The verified ledger's `review/…` branch is created
    separately at review time and is untouched by this step.
 
 **How the seed reaches the default branch.** The `.sdlc/` ledger is seeded once, by hand, on the
@@ -133,7 +133,7 @@ The shared procedure (run once the `EP-<slug>` is known):
 path creates one (`yad gate ci` only *advances* an existing chain, at merge, on the default branch).
 So for the **first** gate of an epic, cut `review/EP-<slug>/<artifact-base>` from that authoring
 branch: the review PR/MR then carries the seed alongside the artifact, and the ledger lands on the
-default branch when it merges. In bridge mode `ledger-guard` exempts exactly this case — **creation,
+default branch when it merges. In verified mode `ledger-guard` exempts exactly this case — **creation,
 not mutation** (#162) — so no direct push to a protected default branch is needed. For every **later**
 gate the ledger is already on the default branch: cut the review branch from there, commit the
 artifact only, and leave `.sdlc/{state,approvals,comments,hub-prs}.json` and `reviews/*.md` to CI.
@@ -141,7 +141,7 @@ artifact only, and leave `.sdlc/{state,approvals,comments,hub-prs}.json` and `re
 | `artifact` | filename or folder | The file/folder this step produces or gates. |
 | `assistance` | `none` \| `review` \| `heavy` | Dial 1 — how much AI helps (build plan §2). |
 | `automation` | `human_approve` \| `machine_advance` | Dial 2 — who advances (build plan §2). |
-| `locked` | `true` \| `false` | Front steps are `true`: may NOT be set to `machine_advance` in this version. |
+| `locked` | `true` \| `false` | Shape steps are `true`: may NOT be set to `machine_advance` in this version. |
 | `status` | `blocked` \| `in_progress` \| `in_review` \| `done` | Lifecycle. `blocked` = upstream step not yet approved. |
 | `risk_tags` | subset of `contract`, `auth`, `payments` | Drives review escalation (build plan §4). |
 
@@ -178,7 +178,7 @@ Append-only ledger (an array), the machine-readable counterpart to the `reviews/
 ```
 
 ## `hub-prs.json`
-Present only when the front-half review runs through the platform bridge. Per review step, the review
+Present only when the Shape review runs through the platform bridge. Per review step, the review
 PR/MR opened on the hub (sibling of `approvals.json`, so the locked `state.json` step shape is untouched):
 
 ```json
@@ -219,29 +219,29 @@ and `<artifact-base>` is the artifact without extension (e.g. `epic`, `architect
 
 ## Dial defaults & locks
 - Every step defaults to `automation: human_approve` (build plan §2).
-- The five authoring front steps and their reviews are `locked: true` — the engine refuses to set
+- The five authoring Shape steps and their reviews are `locked: true` — the engine refuses to set
   them to `machine_advance` in this version (build plan §1, §8.7). Only back states (build pipeline,
   steps 9–14) may move toward machine-advance in a later iteration.
 
 ---
 
-# Phase 4 build-half state (the back half made dial-bearing)
+# Phase 4 Build state (Build made dial-bearing)
 
-Phase 3 recorded build progress only *after the fact* in `build-log.json`. Phase 4 needs the back
+Phase 3 recorded build progress only *after the fact* in `build-log.json`. Phase 4 needs the Build
 steps to carry their own `automation` dial so the orchestrator (`yad-run`) can read it and decide
 whether to advance on its own. Two new files under `.sdlc/` do this.
 
 > **Who commits these.** `build-state/<story-id>.json`, `trust-log.json`, and `build-log.json` are
-> **machine-written** by the back half (`yad-run`, `yad-engineer-review`) and committed by
-> **`yad checkpoint`** — the back-half analogue of the front-half `yad gate ci` sync. It lands them as
-> one `chore(hub): sync back-half state — <epic>/<story> by @<login>` audit-trail commit, on the
-> default branch, staging **only** these three ledgers by an explicit allowlist (never a front-half
+> **machine-written** by Build (`yad-run`, `yad-engineer-review`) and committed by
+> **`yad checkpoint`** — the Build analogue of the Shape `yad gate ci` sync. It lands them as
+> one `chore(hub): sync Build state — <epic>/<story> by @<login>` audit-trail commit, on the
+> default branch, staging **only** these three ledgers by an explicit allowlist (never a Shape
 > gate file — `state/approvals/comments/hub-prs.json`, `reviews/*.md` — so `ledger-guard` never trips).
 > Teammates don't review these machine writes; the commit exists so CI, `yad status`, and other
 > machines always see current trust evidence.
 
 ## `build-state/<story-id>.json`
-One file per story that has entered the build half. The build half is **per-story, per-repo**, so the
+One file per story that has entered Build. Build is **per-story, per-repo**, so the
 steps live under each repo (mirrors the per-repo shape of `build-log.json`).
 
 ```json
@@ -266,22 +266,22 @@ Each `steps[]` entry:
 
 | Field | Values | Meaning |
 |-------|--------|---------|
-| `id` | `spec`, `tasks`, `implement`, `checks`, `engineer-review` | Back-half step identity (the `back_steps` from `config.yaml` + the human merge gate). |
+| `id` | `spec`, `tasks`, `implement`, `checks`, `engineer-review` | Build step identity (the `back_steps` from `config.yaml` + the human merge gate). |
 | `automation` | `human_approve` \| `machine_advance` | Dial 2. Defaults to `human_approve`; flipped to `machine_advance` only after the trust threshold is met (and never for `locked` steps). |
 | `locked` | `true` \| `false` | `engineer-review` is `true` — it never auto-advances (build plan §E). |
 | `status` | `blocked` \| `in_progress` \| `in_review` \| `done` | Lifecycle. `yad-run` advances `done` steps and `blocked`s on a halt. |
 
 `currentStep` is the `id` the orchestrator is waiting on / about to run for that repo. The file is
-created when a story enters the build half; all dials start `human_approve` (the `config.yaml`
+created when a story enters Build; all dials start `human_approve` (the `config.yaml`
 `automation.default`).
 
 `yad next` reads these files too: once an epic is `ready-for-build`, `yad next <epic>` resolves each
 story/repo's `currentStep` into the next build sub-step (`spec`/`tasks` → `yad-spec`, `implement` →
 `yad-implement`, `checks` → `yad-checks`, `engineer-review` → `yad-engineer-review`) and prints it with
-the remaining chain and the step's automation dial — so the build half is guided, not just hinted at.
+the remaining chain and the step's automation dial — so Build is guided, not just hinted at.
 
 ## `trust-log.json` (shard-then-fold)
-Append-only ledger, the back-half analogue of `approvals.json`. **This is the evidence base** that
+Append-only ledger, the Build analogue of `approvals.json`. **This is the evidence base** that
 decides when a step is safe to automate (build plan Step A). One entry per step run.
 
 **Storage — loose shards + a folded file (the "loose objects + `git gc`" model).** Two people driving
@@ -302,7 +302,7 @@ back:
   the folded file and no shard dir still reads correctly — nothing to union.
 - **`yad tidy up`** (manual, one person) folds a SHIPPED story's finished shards into the folded file's
   `runs` and deletes them. Writers never fold — they only add shards; `yad checkpoint` commits the shard
-  dir, and `yad tidy up` is the back-half analogue of `git gc` folding loose objects.
+  dir, and `yad tidy up` is the Build analogue of `git gc` folding loose objects.
 - The **threshold slice** (below) reads this same union, filtered to the step (and repo).
 
 ```json
@@ -377,7 +377,7 @@ storage layout is noted here (it mirrors `trust-log.json`):
 After the contract locks and code ships, a change must not **mutate** a locked artifact (that destroys
 the lock + the audit trail). Instead every change request becomes a **new epic, threaded to its parent**
 (`config.yaml` `change:`). A feature is a **thread** of linked epics (genesis → change → defect → …); a
-change-epic **inherits** unchanged front artifacts from its parent by reference and only **re-authors**
+change-epic **inherits** unchanged Shape artifacts from its parent by reference and only **re-authors**
 what it changes. So artifacts are never stale, only *superseded*; the feature's current truth is the
 head of the thread, composed by the resolver (`yad-timeline`). `yad-change` seeds a change-epic;
 `yad-defects` / `yad-timeline` render the thread; `yad-reconcile` flags drift; three CI gates enforce it.
@@ -411,7 +411,7 @@ A stub is a normal genesis (`kind: feature`, `thread == id`, no `parent`) whose
 `stub: backfill-pending` + `verified: false` and whose `state.json` uses a **sentinel**, mirroring
 `EP-discovery` / `discovery-done`:
 - top-level `kind: "stub"` and `currentStep: "backfill-pending"`;
-- the **same 10-step front chain** as a normal epic, every step `status: "blocked"` (so `validateState`
+- the **same 10-step Shape chain** as a normal epic, every step `status: "blocked"` (so `validateState`
   passes and `promote` can "wake" the chain into normal authoring with no re-seed);
 - empty `approvals.json` / `comments.json`; **no** `contract-lock.json` (no surface locked yet).
 
@@ -433,17 +433,17 @@ approved backfill spec, **and** rewrites `state.json` — removing `kind: "stub"
 off the sentinel:
 - **light promote (default)** → `currentStep: "backfill-done"`, a **terminal sentinel** (like
   `discovery-done`): the feature is a real, verified anchor documented by its backfill spec; `nextAction`
-  reports "documented anchor — evolve it by threading a change/defect", never a pending stub, and no build
-  half runs directly against it;
-- **full promote (opt-in)** → `currentStep: "epic"`, `epic.status: "in_progress"`, to run the normal front
-  half and lock a real contract.
+  reports "documented anchor — evolve it by threading a change/defect", never a pending stub, and Build
+  never runs directly against it;
+- **full promote (opt-in)** → `currentStep: "epic"`, `epic.status: "in_progress"`, to run the normal Shape
+  part and lock a real contract.
 
 From promotion on, the thread's contract protection is live.
 
 ## Inherited steps in `state.json`
 
 A change-epic's `state.json` is structurally identical (so `advanceState` / `nextAction` / `gatePredicate`
-/ the bridge run unchanged), but **inherited** steps are pre-marked `done` with two extra fields, and
+/ the verified ledger run unchanged), but **inherited** steps are pre-marked `done` with two extra fields, and
 only re-authored steps run. The seeder sets `currentStep` to the first re-authored step.
 
 ```json
@@ -506,7 +506,7 @@ Thread-level rollups (`yad-timeline` / `yad-defects`) are **derived** — walk e
 sharing `thread` and read each `change.json`; there is no duplicated thread registry.
 
 ## `reconcile-debt.json`
-Append-only ledger of hotfix ship-first debt (a hotfix shipped code before its front gates approved).
+Append-only ledger of hotfix ship-first debt (a hotfix shipped code before its Shape gates approved).
 
 ```json
 [ { "thread": "EP-checkout", "epicId": "EP-checkout-hotfix-x", "openedDate": "<date>",
@@ -516,5 +516,5 @@ Append-only ledger of hotfix ship-first debt (a hotfix shipped code before its f
 ```
 
 `status: "open"` blocks the **next** normal change on the thread (`reconcile-debt-check.sh`) until it is
-`"paid"` (evidence: the front artifacts updated **and** a regression test added). The debt lets a hotfix
+`"paid"` (evidence: the Shape artifacts updated **and** a regression test added). The debt lets a hotfix
 jump the queue once, but freezes new thread work until the SDLC again describes production.

package/skills/yad-hub-bridge/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: yad-hub-bridge
-description: 'The templated PR/MR bridge for the front-half review gate. When the product hub has a platform (.sdlc/hub.json), it opens a review PR/MR on the hub for an authored artifact (the optional analysis / epic / architecture+contract / ui-design / stories / test-cases), sets the required reviewers/labels from the routing rule, and provides the read-only gh/glab recipes that yad-review-gate uses to pull platform comments + approvals back into the file ledger. Can also wire merge-time sync on the hub: a CI workflow that runs `yad gate ci` when a human merges a review PR/MR — CI is the sole ledger writer and writes only at merge, on the default branch (during review the platform PR/MR is the source of truth; CI never touches the review branch). Local-user auth only — no stored tokens. The file ledger stays the source of truth; degrades to the file-only gate when there is no platform / no CLI. Use when the user says "open the review PR", "route the review", "wire the gate sync", or it is invoked by yad-review-gate open/sync.'
+description: 'The templated PR/MR bridge for the Shape review gate. When the product hub has a platform (.sdlc/hub.json), it opens a review PR/MR on the hub for an authored artifact (the optional analysis / epic / architecture+contract / ui-design / stories / test-cases), sets the required reviewers/labels from the routing rule, and provides the read-only gh/glab recipes that yad-review-gate uses to pull platform comments + approvals back into the file ledger. Can also wire merge-time sync on the hub: a CI workflow that runs `yad gate ci` when a human merges a review PR/MR — CI is the sole ledger writer and writes only at merge, on the default branch (during review the platform PR/MR is the source of truth; CI never touches the review branch). Local-user auth only — no stored tokens. The file ledger stays the source of truth; degrades to the local gate when there is no platform / no CLI. Use when the user says "open the review PR", "route the review", "wire the gate sync", or it is invoked by yad-review-gate open/sync.'
 ---
 
 # SDLC — Hub Review Bridge (the templated PR/MR bridge)
 
-**Goal:** Run the front-half review/comment/approval cycle through a **real PR/MR on the product hub**,
-without changing the gate's predicate or making the file ledger optional. The bridge is an **alternate
+**Goal:** Run the Shape review/comment/approval cycle through a **real PR/MR on the product hub**,
+without changing the gate's predicate or making the file ledger optional. The verified ledger is an **alternate
 input path** into `yad-review-gate`: it opens a review PR for an artifact, reviewers approve/comment on
 the platform with **their own** `gh`/`glab` auth, and the gate's `sync` action (which calls this skill's
 read recipes) maps that platform state into `approvals.json` / `comments.json` / `reviews/*.md`, then
@@ -24,7 +24,7 @@ keeps platform mechanics out of the gate). `yad-review-gate` *calls* it; it neve
 - The review-PR body is the hub template from `yad-pr-template` (`templates/hub/<platform>/…`).
 - Branch per artifact: `review/EP-<slug>/<artifact-base>` (`config.yaml` `hub.artifact_branch`).
 - **Local-user auth only; store no tokens.** Use the user's own `gh`/`glab`. If neither is installed/
-  authenticated, STOP this path and tell the gate to fall back to file-only — never embed a credential.
+  authenticated, STOP this path and tell the gate to fall back to local — never embed a credential.
 
 ## Inputs
 
@@ -33,11 +33,11 @@ keeps platform mechanics out of the gate). `yad-review-gate` *calls* it; it neve
 - `action`   — `open` | `route` | `wire` (default `route`). (`sync`'s ledger writes live in
   `yad-review-gate`; this skill provides the read recipes `sync` calls — see `references/bridge.md`.)
 
-## Preconditions (the bridge runs only when all hold)
+## Preconditions (the verified ledger runs only when all hold)
 
-`.sdlc/hub.json` exists with a non-null `platform`, `bridge_enabled: true`, `config.yaml` `hub.bridge:
+`.sdlc/hub.json` exists with a non-null `platform`, `ledger: "verified"` (or, before `yad migrate`, `bridge_enabled: true`), `config.yaml` `hub.bridge:
 true`, and `gh` (GitHub) / `glab` (GitLab) installed **and authenticated**. If any fails, report that the
-gate proceeds **file-only** (no error) and stop.
+gate proceeds **local** (no error) and stop.
 
 ## On Activation
 
@@ -70,7 +70,7 @@ each required domain-owner to a platform `login` via the roster (a roster `name`
    ```
    A human commit touching the gate-state files (`.sdlc/{state,approvals,comments,hub-prs}.json` or
    `reviews/*.md`; `.sdlc/contract-lock.json` is artifact-side and allowed) on a review PR is rejected
-   by the `ledger-guard` check. (The `yad gate open` CLI behaves the same: in bridge mode it opens the
+   by the `ledger-guard` check. (The `yad gate open` CLI behaves the same: in verified mode it opens the
    PR only and writes no ledger.) The **one** exception is a brand-new epic's **seed** — no CI path can
    create a ledger, so an epic whose `.sdlc/state.json` is absent from the base ref may be created by a
    human on this first PR/MR (#162). Every later change to it is CI's alone.
@@ -94,10 +94,10 @@ Revoke-on-change is enforced at merge: on **GitHub** in code (an approval whose
 head is dropped — no setting needed); on **GitLab** it has no per-approval commit SHA, so enabling the
 platform's **"remove all approvals when commits are added to the source branch"** is **required** for
 the guarantee. Either way it is safe because CI never pushes the review branch — only the owner's own
-artifact pushes dismiss approvals. In bridge mode `yad gate sync` is advisory (read-only) and is **not**
+artifact pushes dismiss approvals. In verified mode `yad gate sync` is advisory (read-only) and is **not**
 a recovery path; if a merge-time run fails, the scheduled reconcile job re-advances it automatically, or
 a maintainer can force it with `yad gate ci --branch <review-branch> --pr <n> --merged` locally on the
-default branch. (File-only mode keeps `yad gate sync` as the local writer.)
+default branch. (local mode keeps `yad gate sync` as the local writer.)
 
 1. Run `yad check --fix` (the wiring is manifest-driven, like `yad-checks`): with a platform +
    enabled bridge in `.sdlc/hub.json` it installs
@@ -139,16 +139,16 @@ default branch. (File-only mode keeps `yad gate sync` as the local writer.)
 ## Hard rules
 
 - **Local-user auth only; store no tokens.** Reviewers use their own `gh`/`glab`.
-- **The bridge is an input path, never the authority.** It opens PRs and reads state; the **file ledger
+- **the verified ledger is an input path, never the authority.** It opens PRs and reads state; the **file ledger
   is the source of truth** and the gate predicate (in `yad-review-gate`) is unchanged.
-- **The bridge never approves on a reviewer's behalf.** Reviewers approve/merge with their own auth. The
+- **the verified ledger never approves on a reviewer's behalf.** Reviewers approve/merge with their own auth. The
   step advances when a human **merges** the approved, fully-resolved review PR (the merge is that human
   act) — `yad gate sync` records the approvals + resolution + merged state and advances; unresolved
   comments or a changed artifact hold it `in_review`. The mechanical sync is the `yad gate` CLI.
 - **CI never approves and never merges.** The wired workflow only runs `gate ci` — the same sync +
   unchanged predicate. It does **nothing pre-merge** (the platform PR/MR holds the review state); at
   merge it re-reads approvals from the platform, advances the step, and flips the artifact status on
-  the **default branch** (the only place CI ever commits). CI is the sole ledger writer; front gates
+  the **default branch** (the only place CI ever commits). CI is the sole ledger writer; Shape gates
   stay permanently human.
 - **The CI tokens are the one documented bend of "no stored tokens".** GitHub uses the platform's own
   ephemeral `github.token` (nothing stored). GitLab requires a stored masked `SDLC_GATE_TOKEN`
@@ -159,7 +159,7 @@ default branch. (File-only mode keeps `yad gate sync` as the local writer.)
   delayed reconcile could advance on an out-of-band post-merge artifact change (see `references/bridge.md`,
   "Known limitation"). Safe to require: a new epic's `.sdlc/` seed rides its first review PR/MR, so
   nobody needs a direct push to the default branch to start an epic (#162).
-- **Degrade gracefully.** No platform / disabled bridge / no CLI → the gate runs file-only with no error.
+- **Degrade gracefully.** No platform / disabled bridge / no CLI → the gate runs local with no error.
 
 ## Reference
 - PR-body→ledger mapping, the read-only gh/glab recipes, idempotent re-sync, contract re-lock handling:

package/skills/yad-hub-bridge/references/bridge.md

@@ -1,7 +1,7 @@
-# The bridge — PR/MR ↔ ledger mapping, read recipes, idempotency
+# the verified ledger — PR/MR ↔ ledger mapping, read recipes, idempotency
 
-The bridge maps platform review state onto the **same file records** the manual gate writes, so the gate
-predicate (`../yad-review-gate/references/gating.md`) runs unchanged. The bridge only changes the
+the verified ledger maps platform review state onto the **same file records** the manual gate writes, so the gate
+predicate (`../yad-review-gate/references/gating.md`) runs unchanged. The verified ledger only changes the
 *input path*; it never changes what passing the gate means.
 
 ## State mapping (platform → ledger)
@@ -12,7 +12,7 @@ predicate (`../yad-review-gate/references/gating.md`) runs unchanged. The bridge
 | GitHub `COMMENTED` / `CHANGES_REQUESTED`; GitLab discussions/notes | a line under `## <name> (<role>)` in `reviews/<artifact>--<date>--comments.md` + a `comments.json` record; **never** an approval. `CHANGES_REQUESTED` is also flagged as blocking in the comments file |
 | GitHub review dismissed / GitLab approval revoked | the prior bridge `approved` record for that approver is removed on re-sync **while the step is open**; once the step is `done` the record is kept as the audit trail of why it passed (see idempotency) |
 
-`approvals.json` records from the bridge carry `"source": "bridge"`; **manual** approvals have no such
+`approvals.json` records from the verified ledger carry `"source": "bridge"`; **manual** approvals have no such
 tag and are **never** touched by `sync` — the two coexist.
 
 ## Read recipes (read-only, local-user auth — no tokens)
@@ -32,8 +32,8 @@ glab api projects/:id/merge_requests/:iid/approvals     # approved_by[].user.use
 glab api projects/:id/merge_requests/:iid/notes          # discussion notes (comments)
 ```
 
-All commands run as the **local user**; the bridge stores no tokens. If the CLI is missing/unauthenticated
-or the remote is unreachable, the bridge stops and the gate falls back to file-only (no error).
+All commands run as the **local user**; the verified ledger stores no tokens. If the CLI is missing/unauthenticated
+or the remote is unreachable, the verified ledger stops and the gate falls back to local (no error).
 
 > **GitLab read parity (GAP-6).** `readPrGitLab` reads approvals (`approved_by[]`) and discussions but
 > does **not** map a "Request changes" reviewer state to `CHANGES_REQUESTED` — on GitLab the blocking
@@ -118,7 +118,7 @@ deliberate act: `yad update` (which re-stamps `.sdlc/cli-version.json`), or a `g
 ## Contract re-lock invalidates prior platform approvals too
 
 For the **architecture+contract** review, the gate already drops approvals when the contract-surface hash
-no longer matches `.sdlc/contract-lock.json`. The bridge extends this to platform-sourced approvals:
+no longer matches `.sdlc/contract-lock.json`. The verified ledger extends this to platform-sourced approvals:
 `sync` discards bridge `approved` records for the architecture step dated **before** the new lock, and
 posts a comment on the review PR noting "contract re-locked — re-approval required". The escalation
 (`risk_tags: ["contract"]` → a domain-owner per repo) is unchanged.
@@ -219,18 +219,18 @@ each `artifactHash` against the merged content, so revoke-on-change still holds.
 commit — the advance plus the `draft → approved` status flip — lands on the **default branch** with
 `[skip ci]`.
 
-**The ledger is CI-owned (bridge mode only).** Humans never commit gate-state files: the `ledger-guard`
+**The ledger is CI-owned (verified mode only).** Humans never commit gate-state files: the `ledger-guard`
 check (yad-checks) FAILs any commit on a review PR that touches `.sdlc/{state,approvals,comments,hub-prs}
-.json` or `reviews/*.md` (`.sdlc/contract-lock.json` is artifact-side and allowed). "Bridge mode" there
-means the same thing it means everywhere else — a `platform` **and** the bridge flag, `isBridge`'s
+.json` or `reviews/*.md` (`.sdlc/contract-lock.json` is artifact-side and allowed). "verified mode" there
+means the same thing it means everywhere else — a `platform` **and** the verified ledger flag, `isVerifiedLedger`'s
 predicate. The gate used to enable itself on the flag alone, which let a platform-less hub reject the
 human's ledger write while the CLI still expected one (#186). Under Path B **no
 CI commit lands in a review PR at all**, so the only ledger change the guard can see there is a human
 edit — which it rejects, with one carve-out for a new epic's seed (below). (The `verified-commits`
 gate still vets every commit's signature + author;
 its gate-bot exemption is now vestigial in-PR because CI no longer commits there.) `yad gate open`
-opens the PR only; local `yad gate sync` is advisory in bridge mode (writes nothing). After a merge,
-everyone `git checkout <default> && git pull`. (Without the bridge, humans own the ledger locally and
+opens the PR only; local `yad gate sync` is advisory in verified mode (writes nothing). After a merge,
+everyone `git checkout <default> && git pull`. (with a local ledger, humans own the ledger locally and
 these guards are no-ops.)
 
 **The one sanctioned human ledger write *in a review PR*: the seed of a new epic.** `gate ci` only
@@ -269,12 +269,12 @@ push retries with a rebase.
 - Protected default branch (GitHub): the merge advance needs to push it — prefer a ruleset bypass for
   Actions, else a fine-grained PAT as `SDLC_GATE_TOKEN` on the mergesync checkout.
 
-**Manual sync & recovery.** In bridge mode `yad gate sync` is **advisory** (read-only) — it prints the
+**Manual sync & recovery.** In verified mode `yad gate sync` is **advisory** (read-only) — it prints the
 predicate but writes nothing, so it is **not** a recovery path when CI fails. If a merge-time run fails
 (can't push, API hiccup), recovery is the scheduled **reconcile** job (automatic; it re-advances merged
 reviews not yet `done`). To force it immediately, a maintainer runs the same command CI runs, locally on
 the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged` (this writes + pushes,
-unlike advisory `yad gate sync`). File-only mode (no platform) keeps `yad gate sync` as the local writer.
+unlike advisory `yad gate sync`). Local mode (no platform) keeps `yad gate sync` as the local writer.
 The file ledger is still the source of truth.
 
 Because CI records the `hub-prs.json` pointer only at merge, a review the ledger has never seen still
@@ -283,17 +283,17 @@ recorded pointer, `yad gate sync <epic> <artifact>` resolves the PR/MR from the
 (`review/<epic>/<artifact>`) itself, and `--pr <n>` names it outright:
 
 ```bash
-yad gate sync EP-x architecture.md --pr 42   # advisory in bridge mode; the writer without the bridge
+yad gate sync EP-x architecture.md --pr 42   # advisory in verified mode; the writer with a local ledger
 ```
 
 An explicit `--pr` also **overrides** a recorded pointer, since a re-opened review is a new PR the
 ledger has not seen. Before its reviewers are bound to the artifact's hash, the number is confirmed to
 be the PR for that artifact's review branch — a mismatch is refused, and a platform that cannot answer
-warns and proceeds. The bridge rule is unchanged: the resolved pointer is adopted into the ledger only
+warns and proceeds. The verified ledger rule is unchanged: the resolved pointer is adopted into the ledger only
 on the writer path, so a human never leaves a gate-state file in their working tree for `ledger-guard`
 to reject.
 
-**In bridge mode `gate sync` stays advisory even with `--pr`** — it prints the predicate and writes
+**In verified mode `gate sync` stays advisory even with `--pr`** — it prints the predicate and writes
 nothing, because CI owns the ledger. The recovery that actually writes is the command CI itself runs,
 on the default branch: `yad gate ci --branch <review-branch> --pr <n> --merged`.
 

package/skills/yad-hub-bridge/references/login-roster.md

@@ -2,7 +2,7 @@
 
 The roster lives in `.sdlc/hub.json` (`roster: [...]`) and is the only thing that turns a platform
 **login** into an SDLC **name + role** for the ledger. Schema and the no-tokens rule are documented once
-in `../../yad-connect-repos/references/hub-config.md`; this file covers how the bridge *uses* it.
+in `../../yad-connect-repos/references/hub-config.md`; this file covers how the verified ledger *uses* it.
 It is populated/edited any time with the `yad roster` CLI command (see that reference).
 
 ## Entry
@@ -34,7 +34,7 @@ It is populated/edited any time with the `yad roster` CLI command (see that refe
 1. **login → name + roles** from the roster. The `hub` roles map straight to records; each touched
    domain `R` contributes the roles in `roles[R]` (a `domain-owner` role carries `domain: R`).
 2. **Legacy domain-owner fallback:** if the resolved `name` equals a repo's `domain_owner` in
-   `repos.json`, and that repo is a **touched domain** for the step under review, the bridge also emits a
+   `repos.json`, and that repo is a **touched domain** for the step under review, the verified ledger also emits a
    `domain-owner` approval scoped to that repo (`domain: <repo>`). One person owning several repos yields
    several `domain-owner` records with different `domain` values — exactly what the gate predicate allows.
 3. **Unmapped login → reviewer (flagged).** A login not in the roster maps to `name: <login>`,
@@ -58,7 +58,7 @@ When a review PR/MR is opened (hub `yad gate open`, or a code-repo `yad open-pr`
 ## Per-repo routing (stories review, and any escalated step)
 
 The stories review needs a `domain-owner` per repo in the **union of every story's `repos`**. On the
-review PR the bridge makes this legible and enforceable:
+review PR the verified ledger makes this legible and enforceable:
 
 - Add a `domain:<repo>` **label** per touched repo.
 - **Request** each touched repo's `domain_owner` login as a reviewer (resolved via the roster).

package/skills/yad-hub-bridge/templates/checks/hub-route.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Hub review routing — the front-half analogue of yad-pr-template's risk-route.sh. Reads a hub review
+# Hub review routing — the Shape analogue of yad-pr-template's risk-route.sh. Reads a hub review
 # PR/MR description's "Impact & Risk (front-half)" block and prints the required reviewers, reusing
 # yad-review-gate's rule: base = owner + 1 reviewer; if a risk tag (contract|auth|payments) is set OR
 # the artifact is the stories set, ALSO a domain-owner per touched repo. Advisory: it ROUTES the human

package/skills/yad-hub-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml

@@ -34,7 +34,7 @@
 # default branch — the merge advance pushes there) and store it as a masked CI/CD variable
 # SDLC_GATE_TOKEN. Without it the job fails visibly; recover by setting the token, then re-run the
 # pipeline or run `yad gate ci --branch <review-branch> --pr <iid> --merged` locally on the default
-# branch (advisory `yad gate sync` is read-only in bridge mode and cannot recover a stuck gate).
+# branch (advisory `yad gate sync` is read-only in verified mode and cannot recover a stuck gate).
 #
 # Which yadflow this job runs: an EXACT version resolved from the repo at run time — see the `yad-pin`
 # block in the script below for the precedence. It no longer floats on the major, because floating let a

package/skills/yad-implement/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: yad-implement
-description: 'Build-half Step B of the gated SDLC. With the dev lens, implement ONE atomic task from a story''s Spec Kit tasks.md as a small diff (≤3 files) on its own branch in the code repo. The diff stays inside the files the task declared — flag and STOP if it would grow beyond them. Commit per convention, ending with the task ID; add Contract-Change: yes only if the diff touches the locked contract surface (which routes back to the architecture gate). The step never advances itself; it produces a committed branch and hands off to the check gates, which the orchestrator (yad-run) may auto-run once `implement` is earned to machine_advance (Phase 4b Step D) — the merge still needs the gates and the engineer review. Use when the user says "implement task <id>" or after a story is spec''d.'
+description: 'Build Step B of the gated SDLC. With the dev lens, implement ONE atomic task from a story''s Spec Kit tasks.md as a small diff (≤3 files) on its own branch in the code repo. The diff stays inside the files the task declared — flag and STOP if it would grow beyond them. Commit per convention, ending with the task ID; add Contract-Change: yes only if the diff touches the locked contract surface (which routes back to the architecture gate). The step never advances itself; it produces a committed branch and hands off to the check gates, which the orchestrator (yad-run) may auto-run once `implement` is earned to machine_advance (Phase 4b Step D) — the merge still needs the gates and the engineer review. Use when the user says "implement task <id>" or after a story is spec''d.'
 ---
 
-# SDLC — Implement Task (build-half Step B)
+# SDLC — Implement Task (Build Step B)
 
 **Goal:** Turn ONE atomic task from a story's `tasks.md` (produced by Step A `yad-spec`) into a small,
 reviewable diff on its own branch in the code repo. **One atomic task = one branch = one PR/MR**
@@ -103,7 +103,7 @@ never on the AI's own initiative. Keep all trailers in one contiguous block. Do
 ### Step 7 — Report; the advance decision belongs to the dial (Phase 4)
 Report: the branch name, the files changed, how the change satisfies the task's acceptance criterion,
 the result of any test/smoke run, and the next action — the **check gates** (Step C — `yad-checks`)
-then the PR and review (Steps D–E). Do **not** open a PR, merge, or hand-edit the epic's front-half
+then the PR and review (Steps D–E). Do **not** open a PR, merge, or hand-edit the epic's Shape
 `state.json`. Step B ends at a committed task branch.
 
 - **Run standalone:** stop here; a human triggers the gates.

package/skills/yad-open-pr/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: yad-open-pr
-description: 'Build-half helper of the gated SDLC. Open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the current task branch, and create the PR/MR with the template body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Auto-assigns from the hub roster: assignee = the committer, reviewers = the repo''s reviewers + domain-owners. High risk / contract surface routes to domain owners (risk-route.sh). Drives the `yad open-pr` CLI; never merges. Use when the user says "open the PR", "open the MR", or "raise the merge request".'
+description: 'Build helper of the gated SDLC. Open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the current task branch, and create the PR/MR with the template body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Auto-assigns from the hub roster: assignee = the committer, reviewers = the repo''s reviewers + domain-owners. High risk / contract surface routes to domain owners (risk-route.sh). Drives the `yad open-pr` CLI; never merges. Use when the user says "open the PR", "open the MR", or "raise the merge request".'
 ---
 
-# SDLC — Open Task PR/MR (build-half helper)
+# SDLC — Open Task PR/MR (Build helper)
 
 **Goal:** Open the PR/MR for the current task branch from the repo's committed PR/MR template
 (installed by `yad-pr-template`, Step D), with the body prefilled and the right reviewers requested.
 This is the standalone open-PR step; it **never merges** — the engineer review (`yad-engineer-review`,
-Step E) owns the merge. Distinct from `yad gate open`, which opens a front-half artifact-review PR on
+Step E) owns the merge. Distinct from `yad gate open`, which opens a Shape artifact-review PR on
 the product hub.
 
 ## Conventions
@@ -23,7 +23,7 @@ the product hub.
   touched:`, and `Domains` prefilled; the rest is left for the author. This satisfies the `pr-template`
   gate.
 - **Stage-aware on the product hub** — `open-pr` mirrors the `--head` split the hub gates apply:
-  - a **`review/EP-*/<artifact>`** branch is a front-half artifact-review PR → it **delegates to
+  - a **`review/EP-*/<artifact>`** branch is a Shape artifact-review PR → it **delegates to
     `yad gate open`** (artifact-review title `review: <artifact> (EP-<slug>)`, the hub artifact-review
     body, and the gate ledger bookkeeping all in one place). Any `--title`/`-m` is ignored here.
   - any **other hub branch** is a tooling/CI change → it uses the bundled **code-task** template