yadflow 3.18.0 → 3.19.0-next.2

package/skills/yad-ship/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: yad-ship
-description: 'Build-half helper of the gated SDLC — commit AND open the task PR/MR in one step. A thin orchestration over yad-commit then yad-open-pr: commit the staged atomic change by the conventions (Conventional-Commits subject, Task → Contract-Change trailers, an OPTIONAL Co-Authored-By footer that is OFF by default and added only when --ai <id> is explicitly passed, ≤3-file atomic guard), then push the branch and open the PR/MR from the committed template with the roster auto-assigned. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the `yad ship` CLI; never merges. Use when the user says "ship this task", "commit and open the PR", or "commit and raise the MR". (For the engineer review + merge, use yad-engineer-review.)'
+description: 'Build helper of the gated SDLC — commit AND open the task PR/MR in one step. A thin orchestration over yad-commit then yad-open-pr: commit the staged atomic change by the conventions (Conventional-Commits subject, Task → Contract-Change trailers, an OPTIONAL Co-Authored-By footer that is OFF by default and added only when --ai <id> is explicitly passed, ≤3-file atomic guard), then push the branch and open the PR/MR from the committed template with the roster auto-assigned. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the `yad ship` CLI; never merges. Use when the user says "ship this task", "commit and open the PR", or "commit and raise the MR". (For the engineer review + merge, use yad-engineer-review.)'
 ---
 
-# SDLC — Commit + Open PR/MR (build-half helper)
+# SDLC — Commit + Open PR/MR (Build helper)
 
-**Goal:** Do the two routine build-half hand-actions for ONE atomic task in a single step — **commit by
+**Goal:** Do the two routine Build hand-actions for ONE atomic task in a single step — **commit by
 convention, then open the task PR/MR** — so an implemented diff becomes a reviewable PR/MR without two
 separate invocations. It is a thin wrapper over `yad-commit` and `yad-open-pr`; it holds no logic of
 its own and **never merges**. The engineer review + merge are Step E (`yad-engineer-review`).
@@ -23,7 +23,7 @@ its own and **never merges**. The engineer review + merge are Step E (`yad-engin
 - **Order matters:** the PR/MR is opened **only if the commit lands**. A failed commit, a tripped
   atomic guard, or `--dry-run` stops the step before anything is pushed.
 - **Stage-aware on the product hub** (via `yad-open-pr`): on a `review/EP-*` branch `ship` opens the
-  front-half **artifact-review** PR (delegating to `yad gate open` — `--title` is ignored); on any
+  Shape **artifact-review** PR (delegating to `yad gate open` — `--title` is ignored); on any
   other hub branch it opens the **code-task** PR from the bundled code-task template. In a code repo
   it is unchanged.
 

package/skills/yad-spec/SKILL.md

@@ -1,17 +1,17 @@
 ---
 name: yad-spec
-description: 'Build-half Step A of the gated SDLC. For one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony ONCE (specify → clarify → plan → analyze → checklist → tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit''s own layout. Drives /speckit.* as harness slash-commands when installed; authors the same files by hand and records speckit: not-installed when absent. References the locked contract — never re-invents the surface. Writes link.md back to the story. Never auto-advances. Use when the user says "spec story <id> in <repo>" or after a story is ready-for-build.'
+description: 'Build Step A of the gated SDLC. For one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony ONCE (specify → clarify → plan → analyze → checklist → tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit''s own layout. Drives /speckit.* as harness slash-commands when installed; authors the same files by hand and records speckit: not-installed when absent. References the locked contract — never re-invents the surface. Writes link.md back to the story. Never auto-advances. Use when the user says "spec story <id> in <repo>" or after a story is ready-for-build.'
 ---
 
-# SDLC — Author Spec (build-half Step A)
+# SDLC — Author Spec (Build Step A)
 
 **Goal:** Turn ONE `ready-for-build` story into a per-repo Spec Kit spec/plan/tasks inside that
 story's code repo. The heavy spec ceremony runs **once per story per repo**; the light
 tasks → implement loop is **Step B** (`yad-implement`). This step **never re-locks the contract** —
 the cross-repo surface is owned upstream by the architecture gate (build plan §A, Cross-cutting
-"Heavy spec once per story, light loop per task"). It does not advance the front-half state machine;
+"Heavy spec once per story, light loop per task"). It does not advance the Shape state machine;
 when driven by the orchestrator (`yad-run`, Phase 4) it records a `spec`/`tasks` trust signal
-(Step 8) — but it never auto-advances a contract change or a front state.
+(Step 8) — but it never auto-advances a contract change or a Shape step.
 
 Spec Kit is driven as **harness slash-commands** (`/speckit.*`), not a subprocess CLI (Phase 0
 Deviation 3). When Spec Kit is not installed, the same files are hand-authored in Spec Kit's exact
@@ -43,11 +43,10 @@ is the same graceful-degradation pattern `yad-ui` uses for Impeccable.
 
 ### Step 1 — Resolve the story and check readiness
 Read `{project-root}/epics/<epic>/.sdlc/state.json`. Proceed only when
-`currentStep == "ready-for-build"` (the gating front half — through the **stories** gate — is `done`).
-The **`test-cases` track may still be `in_progress`**: it is parallel and non-blocking, so the build
-half runs alongside it — its status does not affect readiness here. Read the story file
+`currentStep == "ready-for-build"` (the gating Shape — through the **stories** gate — is `done`).
+The **`test-cases` track may still be `in_progress`**: it is parallel and non-blocking, so Build runs alongside it — its status does not affect readiness here. Read the story file
 `epics/<epic>/stories/<story>.md`; confirm `repo` is in its `repos`. If the epic is not ready, STOP
-and point the user at `yad-status`. **Do not mutate front-half state** — `ready-for-build` semantics
+and point the user at `yad-status`. **Do not mutate Shape state** — `ready-for-build` semantics
 stay intact.
 
 ### Step 2 — Resolve the target code repo
@@ -87,13 +86,13 @@ frontmatter linking the spec back to the product repo: `story`, `epic`, `repo`,
 in the code repo), `speckit` (`installed | not-installed`), `generated` (date). This `link.md` plus the
 spec folder is the authoritative record that this story's spec exists.
 
-### Step 7 — Stop (front-half state untouched)
+### Step 7 — Stop (Shape state untouched)
 Report: the spec folder path, the files written, whether Spec Kit was used, the task count from
 `tasks.md`, and that the next action is **Step B — `yad-implement`**. Do **not** edit the epic's
-`state.json`, `approvals.json`, or `contract-lock.json`. Step A is a generation step, not a front gate.
+`state.json`, `approvals.json`, or `contract-lock.json`. Step A is a generation step, not a Shape gate.
 
 ### Step 8 — Record the `spec` trust signal (Phase 4b)
-When this step runs under the orchestrator (`yad-run`), the generated spec is a back-half run that the
+When this step runs under the orchestrator (`yad-run`), the generated spec is a Build run that the
 trust log measures (it is the evidence that could later earn the `spec` step a `machine_advance`). The
 verdict is **anchored to the human who accepts the spec**, never self-graded:
 - the human approves the generated `specs/<story>/` untouched → `approved-unchanged`;

package/skills/yad-status/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-status
-description: 'Read-only view of an SDLC epic: prints the current step, each step''s dials (assistance/automation) and status, and which approvals are still required at the active gate. For stories in the build half it also prints each back-half step''s automation dial, status, and trust record (runs / % approved-unchanged / whether it clears the threshold to be earned), plus the system-wide kill-switch state — so the team can see WHY a step is automated and reverse it with evidence. Also prints the cross-cutting personal skills-log roll-up from the LOCAL-ONLY learning ledger (gitignored, never committed/pushed — the local learner''s own learning, by stage). Surfaces the Phase 5 instrumentation signals: per-step "earned but manual" (nudge cost) and, across multiple epics, a fleet roll-up (scale of read). Use when the user says "yad status", "where is epic EP-...", "what is blocking the gate", "show the trust record", "team skills", or "fleet status".'
+description: 'Read-only view of an SDLC epic: prints the current step, each step''s dials (assistance/automation) and status, and which approvals are still required at the active gate. For stories in Build it also prints each Build step''s automation dial, status, and trust record (runs / % approved-unchanged / whether it clears the threshold to be earned), plus the system-wide kill-switch state — so the team can see WHY a step is automated and reverse it with evidence. Also prints the cross-cutting personal skills-log roll-up from the LOCAL-ONLY learning ledger (gitignored, never committed/pushed — the local learner''s own learning, by stage). Surfaces the Phase 5 instrumentation signals: per-step "earned but manual" (nudge cost) and, across multiple epics, a fleet roll-up (scale of read). Use when the user says "yad status", "where is epic EP-...", "what is blocking the gate", "show the trust record", "team skills", or "fleet status".'
 ---
 
 # SDLC — Status (read-only)
@@ -20,7 +20,7 @@ report all if the user asked for an overview).
 
 ### Step 2 — Read state
 Read `.sdlc/state.json`, `.sdlc/approvals.json`, `epic.md` frontmatter (for `repos`), and — if present
-— `.sdlc/contract-lock.json`. For the build half (Phase 4), also read — if present — every
+— `.sdlc/contract-lock.json`. For Build (Phase 4), also read — if present — every
 `.sdlc/build-state/<story-id>.json`, and the trust ledger read as the **union** of the folded
 `.sdlc/trust-log.json` `runs` PLUS every loose `.sdlc/trust-log/` shard (concatenate — every shard is a
 distinct run; never dedup by story/repo/step — but DO skip a shard whose full identity
@@ -40,13 +40,13 @@ Print, in this order:
    absent) — followed by `epicId`, then `status` from `epic.md` frontmatter, `currentStep`, and `repos`
    (the touched domains). Example: `Defect EP-checkout-queue-filter — draft @ stories`. A bug is a defect
    (`kind: defect`) — there is no separate noun. This is presentation only; the artifact is still an epic.
-2. **Steps table** — for every front step in `steps[]` order (10, or 12 when the optional analysis step
+2. **Steps table** — for every Shape step in `steps[]` order (10, or 12 when the optional analysis step
    was run): `id`, `type`, `status`, `assistance`, `automation`, `locked`, and `risk_tags`. Mark the
    `currentStep` with `→`. The gating chain is `[analysis → analysis-review →] epic → epic-review →
    architecture → architecture-review → ui-design → ui-design-review → stories → stories-review` →
    **`ready-for-build`** (the bracketed `analysis` prefix is present only when `yad-analysis` seeded it).
    `test-cases → test-cases-review` is a **parallel, non-blocking track**: it opens when `stories-review`
-   passes and runs alongside the build half, so when `currentStep` is `ready-for-build` the `test-cases`
+   passes and runs alongside Build, so when `currentStep` is `ready-for-build` the `test-cases`
    step may still be `in_progress`/`in_review` — show its status, and note "parallel" so it is clear it
    does not gate the build. Always render exactly the steps present in `steps[]`.
    - **Skipped (N/A) steps:** the optional `ui-design` step may be marked N/A for an epic with no
@@ -78,25 +78,25 @@ Print, in this order:
    (and, when at/after `architecture-review`, whether the current surface still matches it).
 5. **Stories** — if `stories/` has files, list each story `id` and its `repos` tags.
 6. **Files** — list the review records present under `reviews/` for the current artifact.
-7. **Build half (per story, per repo)** — if any `.sdlc/build-state/<story-id>.json` exists, then for
-   each such story and each of its repos print the back-half chain
+7. **Build (per story, per repo)** — if any `.sdlc/build-state/<story-id>.json` exists, then for
+   each such story and each of its repos print the Build chain
    `spec → tasks → implement → checks → engineer-review`, marking each step's `status`, its
    `automation` dial, and `locked`. Mark that repo's `currentStep` with `→`. This shows, at a glance,
-   which back steps are automated and where a run is waiting. (For the single *next* build sub-step to
+   which Build steps are automated and where a run is waiting. (For the single *next* build sub-step to
    take per story/repo — rather than this full status view — point the user at `yad next <epic>`, which
    reads the same `build-state` files.)
 8. **Automation & trust** — print the system-wide **kill switch** state from `config.yaml`
    `automation.kill_switch` (when `on`, note that every step is forced to `human_approve`). Then, for
-   each back-half step that has entries in the trust ledger — the **union** of the folded
+   each Build step that has entries in the trust ledger — the **union** of the folded
    `.sdlc/trust-log.json` `runs` plus every loose `.sdlc/trust-log/` shard — print its **trust record**:
    number of runs, the fraction with `verdict == "approved-unchanged"`, and whether that clears
    `automation.trust_threshold` (`min_runs`, `min_approved_unchanged`) — i.e. whether the step is
    **earned** (eligible to be flipped to `machine_advance`) or still **gathering evidence**. Restate
    the predicate (self-contained): `earned = runs >= min_runs AND unchanged/runs >= min_approved_unchanged`.
-   Never recommend flipping a locked step or a front state — those can never be `machine_advance`.
+   Never recommend flipping a locked step or a Shape step — those can never be `machine_advance`.
 
-   **Nudge-cost signal (Phase 5 instrumentation).** For each back step that is **earned but its dial
-   is still `human_approve`** (and it is not locked / not a front state), flag it:
+   **Nudge-cost signal (Phase 5 instrumentation).** For each Build step that is **earned but its dial
+   is still `human_approve`** (and it is not locked / not a Shape step), flag it:
    `⚠ earned but manual — could be machine_advance`. This is the *nudge cost* the Phase 5 trigger
    watches: automation that is proven safe but still hand-started. It is a read-only observation, not a
    recommendation to flip — earning the evidence and flipping the dial stay deliberate human acts
@@ -117,10 +117,10 @@ Print, in this order:
 
 10. **Fleet roll-up (overview only).** When the user asked for an overview, or more than one epic exists
     under `{project-root}/epics/`, print a one-line-per-epic roll-up across the fleet: each epic's
-    `currentStep` (front gate) and, for stories in the build half, a count of back-half steps **waiting
+    `currentStep` (Shape gate) and, for stories in Build, a count of Build steps **waiting
     at a human gate** and of steps flagged **earned-but-manual**, plus a **local skills-log** count (records
     in the local-only `learning-records.json`: learned / in-progress). Close with fleet totals (epics at
-    each front gate; total earned-but-manual back steps; total concepts learned locally across the fleet).
+    each Shape gate; total earned-but-manual Build steps; total concepts learned locally across the fleet).
     This is the
     *scale-of-read* signal the Phase 5 trigger watches — when this roll-up stops fitting in one glance,
     that is the measured bottleneck. Still strictly read-only; it only scans the per-epic files.

package/skills/yad-stories/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: yad-stories
-description: 'Front state 7 of the gated SDLC. With the pm, break the approved epic into user stories, each tagged with the repos that must implement it. Assigns zero-padded EP-<slug>-S0N IDs and writes one file per story under stories/. Reads epic + architecture + contract + UI as input. Never auto-advances — hands off to the team review gate (per-repo reviewer routing). Use when the user says "author the stories" or after the UI gate passes.'
+description: 'Shape step 7 of the gated SDLC. With the pm, break the approved epic into user stories, each tagged with the repos that must implement it. Assigns zero-padded EP-<slug>-S0N IDs and writes one file per story under stories/. Reads epic + architecture + contract + UI as input. Never auto-advances — hands off to the team review gate (per-repo reviewer routing). Use when the user says "author the stories" or after the UI gate passes.'
 ---
 
-# SDLC — Author Stories (front state 7)
+# SDLC — Author Stories (Shape step 7)
 
 **Goal:** Break an approved epic into human-authored, AI-assisted user stories, each with a stable
-`EP-<slug>-S0N` ID and a `repos` tag listing which repos must implement it. This is a **front state**:
+`EP-<slug>-S0N` ID and a `repos` tag listing which repos must implement it. This is a **Shape step**:
 human-authored with AI assist, **never auto-advances**. When the stories are drafted, control passes
 to `yad-review-gate`, which routes **per-repo reviewers** (each repo's engineer reviews the stories
 touching their repo).
@@ -38,7 +38,7 @@ Open the stories authoring branch `stories/EP-<slug>` per the shared procedure
 (`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note
 if `{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
 hub's default branch. Author and commit the story files under `stories/` on it. This is **distinct**
-from the bridge's `review/…` branch.
+from the verified ledger's `review/…` branch.
 
 ### Step 2 — Read inputs
 Read `epic.md` (scope, acceptance signals, `repos`), `architecture.md` (components by repo, flows),
@@ -102,9 +102,9 @@ As a <role>, I want <capability>, so that <outcome>.
 
 ### Step 6 — Advance the authoring step (NOT the gate)
 **Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
-**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+**verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
 
-**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+**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
@@ -112,26 +112,26 @@ fails the gate if it rides the review PR, and desynchronises the ledger CI is ab
 is pushed around the gate. Commit **the story files under `stories/` only** — nothing else
 under `.sdlc/` — then hand off to `yad-review-gate`.
 
-**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+**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`.
 
-> **File-only branch only.** Since 3.11 the CLI also closes the authoring step when its review gate
+> **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 bridge mode `gate open` writes nothing and local `gate sync` is advisory —
+> (`YAD-STATE-005`). In verified mode `gate open` writes nothing and local `gate sync` is advisory —
 > `gate ci` closes the step at merge.
 
 ### Step 7 — Stop at the gate (do NOT advance)
 Report: the story IDs created, the repos each touches, and that the next action is **review** via
 `yad-review-gate`. Note that this review routes **per-repo reviewers**: owner + 1 reviewer **plus**, for
 each repo appearing in any story's `repos`, a `domain-owner` approval for that repo. When this gate
-passes the epic becomes **`ready-for-build`** — the build half can start **and** the parallel
+passes the epic becomes **`ready-for-build`** — Build can start **and** the parallel
 **`test-cases`** track opens for the tester (`yad-test-cases`); the two run at the same time. **Never record
-approval here.** Front states do not auto-advance. When the hub has a platform, the gate opens a review
+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
 `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
-is recorded file-only.
+is recorded local.
 
 ## Reference
 - Story frontmatter and body template: `references/story-schema.md`.

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

@@ -1,6 +1,6 @@
 # Story schema
 
-Each story authored at front state 7 is one Markdown file under `epics/EP-<slug>/stories/`, named
+Each story authored at Shape step 7 is one Markdown file under `epics/EP-<slug>/stories/`, named
 `EP-<slug>-S0N.md` (zero-padded, never renamed).
 
 ## Frontmatter
@@ -9,10 +9,10 @@ Each story authored at front state 7 is one Markdown file under `epics/EP-<slug>
 |-------|--------|---------|
 | `id` | `EP-<slug>-S0N` | Stable story ID. Engine-assigned, zero-padded, never renamed. |
 | `epic` | `EP-<slug>` | Parent epic ID — the unbroken link back to the epic. |
-| `owner` | name | Inherited from `epic.md` `owner` (the single source — not retyped per story). Carries the responsible owner through to the build half. |
+| `owner` | name | Inherited from `epic.md` `owner` (the single source — not retyped per story). Carries the responsible owner through to Build. |
 | `status` | `draft` \| `in_review` \| `approved` | Story lifecycle within the stories gate. |
 | `repos` | subset of the epic's `repos` | Which repos must implement this story. **Drives per-repo review routing now and (Phase 3) where specs are scaffolded.** |
-| `code-context` | `{ repos: [<name@sha>], loaded: <date> }` | Optional. Which connected-repo code-maps anchored "Notes for build" (front state 7 Step 2b). The `@sha` (a repo's `syncedHead`) is recommended so freshness is recorded but may be omitted; the SKILL templates show the empty placeholder `{ repos: [], loaded: <date or none> }`. `none` / `[]` when no repos are connected. |
+| `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
 

package/skills/yad-stub/SKILL.md

@@ -86,7 +86,7 @@ Leave `owner` for the human to set. Set `repos` to the code repo(s) the feature
 
 ### Step 5 — Seed the stub `state.json` (a `backfill-pending` sentinel)
 Create `{project-root}/epics/EP-<slug>/.sdlc/state.json`. It carries the top-level marker
-`kind: "stub"` and the sentinel `currentStep: "backfill-pending"`, and the **same 10-step front chain**
+`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.
@@ -117,7 +117,7 @@ Also create the empty ledgers `{.sdlc/approvals.json}` and `{.sdlc/comments.json
 `reviews/` directory. **Do NOT** write a `contract-lock.json` — a stub has no locked surface yet.
 
 Commit the seed on this step's authoring branch; it reaches the hub's default branch through the
-epic's **first** review PR/MR (or, for a stub, the PR that carries the stub itself). In bridge mode
+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".
 
@@ -130,7 +130,7 @@ Report the new `EP-<slug>`, that it is a **stub (backfill pending)**, and the tw
 - **Make it real later:** `yad-backfill` for the code repo, then `yad-backfill promote EP-<slug>` to flip
   the stub to `verified: true`.
 
-Front states do not auto-advance. Suggest `yad next EP-<slug>` (prints the backfill-pending guidance) and
+Shape steps do not auto-advance. Suggest `yad next EP-<slug>` (prints the backfill-pending guidance) and
 `yad thread EP-<slug>` to see the anchor and everything threaded off it.
 
 ## Hard rules

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

@@ -5,7 +5,7 @@ description: 'Brings every connected code repo up to date in one shot: switches
 
 # SDLC — Sync Connected Repos (one command, every repo on its default branch)
 
-**Goal:** Before front/build work starts, get every connected code repo onto its default branch at the
+**Goal:** Before Shape/Build work starts, get every connected code repo onto its default branch at the
 latest commit, so nobody implements on a stale or wrong branch. This is the deterministic counterpart to
 the `sync-before-implementation` discipline: one command instead of N manual `git checkout && git pull`.
 

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

@@ -1,17 +1,17 @@
 ---
 name: yad-test-cases
-description: 'Front state 9 of the gated SDLC — a PARALLEL, non-blocking track. Opens when the stories gate passes (the epic is already ready-for-build, so the build half can start at the same time) and runs alongside implementation. With the test architect (Murat), author test-cases.md for the approved stories, and — when a testing tool is connected — generate/link the actual automation tests in it; otherwise produce the test-case artifact only. Reads epic + architecture + contract + UI + stories as input. Never auto-advances — hands off to the team review gate. Use when the user says "author the test cases" or after the stories gate passes.'
+description: 'Shape step 9 of the gated SDLC — a PARALLEL, non-blocking track. Opens when the stories gate passes (the epic is already ready-for-build, so Build can start at the same time) and runs alongside implementation. With the test architect (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.'
 ---
 
-# SDLC — Author Test Cases (front state 9 — parallel, non-blocking)
+# SDLC — Author Test Cases (Shape step 9 — parallel, non-blocking)
 
 **Goal:** Produce a human-authored, AI-assisted `test-cases.md` for an approved epic — the risk-based
 test cases that cover the stories' acceptance criteria — **and**, when a testing tool is connected, the
 **actual automation tests** inside the connected code repo(s), linked back from the artifact. This is a
-**front state**: human-authored with AI assist, **never auto-advances**. When the test cases are
+**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).
 
-**This step does NOT block the build half.** It opens when the **stories** gate passes — at which point
+**This step does NOT block Build.** It opens when the **stories** gate passes — at which point
 the epic is already `ready-for-build`, so implementation (`yad-spec` → `yad-implement` → …) can start
 **at the same time** the tester works here. The test-cases track is driven by its own step `status`
 (it opens to `in_progress` when `stories-review` passes) and its review **never moves `currentStep`
@@ -51,7 +51,7 @@ the stories review has not passed.
 Open the test-cases authoring branch `test-cases/EP-<slug>` per the shared procedure
 (`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if
 `{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
-hub's default branch. Author and commit `test-cases.md` on it. This is **distinct** from the bridge's
+hub's default branch. Author and commit `test-cases.md` on it. This is **distinct** from the verified ledger's
 `review/…` branch.
 
 ### Step 2 — Read inputs
@@ -163,9 +163,9 @@ degraded (`testing: none`), do **not** write `test-links.json`.
 
 ### Step 5 — Advance the authoring step (NOT the gate)
 **Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
-**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+**verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
 
-**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+**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
@@ -174,21 +174,20 @@ is pushed around the gate. Commit the artifact set — **`test-cases.md` and, wh
 tool was used, `.sdlc/test-links.json`** (artifact-side, not ledger; generated tests live in their
 own code repo, not here) — then hand off to `yad-review-gate`.
 
-**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+**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 the
-build half. Write `state.json`. Do **not** touch `approvals.json`. On this branch `yad gate open`
+`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.
 
 ### Step 6 — Stop at the gate (do NOT advance)
 Report: the path to `test-cases.md`, the connected testing tool and what it produced (e.g. "Playwright —
 6 tests generated", the suite path + `test-links.json` path, or "no testing tool — artifacts-only"), that
-the build half may already be underway in parallel, and that the next action is **review** via
-`yad-review-gate` (base rule: owner + 1 reviewer). **Never record approval here.** Front states do not
+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
-into the ledger; otherwise the review is recorded file-only.
+into the ledger; otherwise the review is recorded local.
 
 ## Reference
 - Test-cases frontmatter, body template, and the `test-links.json` schema: `references/test-cases-schema.md`.

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

@@ -1,6 +1,6 @@
 # Test-cases schema
 
-The test cases authored at front state 9 are one Markdown file under `epics/EP-<slug>/`, named
+The test cases authored at Shape step 9 are one Markdown file under `epics/EP-<slug>/`, named
 `test-cases.md` (one per epic — mirrors `ui-design.md`, not a per-story folder). The optional automation
 linkage is a sibling `test-links.json`.
 

package/skills/yad-ui/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: yad-ui
-description: 'Front state 5 of the gated SDLC. With the ux-designer, author ui-design.md and DESIGN.md for an approved architecture, driving Impeccable as harness slash-commands (document/extract/craft) when installed, or authoring directly when not. Reads epic + architecture as input. Never auto-advances — hands off to the team review gate. Use when the user says "author the UI design" or after the architecture gate passes.'
+description: 'Shape step 5 of the gated SDLC. With the ux-designer, author ui-design.md and DESIGN.md for an approved architecture, driving Impeccable as harness slash-commands (document/extract/craft) when installed, or authoring directly when not. Reads epic + architecture as input. Never auto-advances — hands off to the team review gate. Use when the user says "author the UI design" or after the architecture gate passes.'
 ---
 
-# SDLC — Author UI Design (front state 5)
+# SDLC — Author UI Design (Shape step 5)
 
 **Goal:** Produce a human-authored, AI-assisted `ui-design.md` and `DESIGN.md` for an approved
 architecture **and**, when a design tool is connected, the **actual feature design** — the mobile
 screens and/or web pages — inside that tool (e.g. Figma), linked back from the artifacts. This is a
-**front state**: human-authored with AI assist, **never auto-advances**. When the UI is drafted, control
+**Shape step**: human-authored with AI assist, **never auto-advances**. When the UI is drafted, control
 passes to `yad-review-gate` (base rule: owner + 1 reviewer).
 
 UI work is shaped by **Impeccable**, invoked as **harness slash-commands** (not a subprocess CLI) per
@@ -60,7 +60,7 @@ Open the UI authoring branch `ui-design/EP-<slug>` per the shared procedure
 (`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note
 if `{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
 hub's default branch. Author and commit `ui-design.md` / `DESIGN.md` on it. This is **distinct** from
-the bridge's `review/…` branch.
+the verified ledger's `review/…` branch.
 
 ### Step 2 — Read inputs
 Read `epic.md` (user-level acceptance signals, scope) and `architecture.md` (flows, components by
@@ -92,7 +92,7 @@ components/tokens into the design system; `/impeccable craft` is shape-then-buil
 **Graceful degradation:** if Impeccable is not installed (no `/impeccable …` commands available), the
 `ux-designer` lens authors `ui-design.md` and `DESIGN.md` directly, and you **note in `ui-design.md`
 that Impeccable was not used**. Do not run `npx impeccable skills install` as part of this step — tool
-installation is out of scope for the front half.
+installation is out of scope for Shape.
 
 ### Step 3b — Materialize the design in the connected tool (generate or link)
 Read `{project-root}/.sdlc/design.json` (`config.yaml` `design.registry`). Decide the path:
@@ -172,9 +172,9 @@ Keep the `## Design (<tool>)` section of `ui-design.md` in step with this file.
 
 ### Step 5 — Advance the authoring step (NOT the gate)
 **Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
-**bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`.
+**verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
 
-**Bridge mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
+**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
@@ -183,7 +183,7 @@ is pushed around the gate. Commit the artifact set — **`ui-design.md`, `DESIGN
 design tool was used, `.sdlc/design-links.json`** (artifact-side, not ledger) — then hand off to
 `yad-review-gate`.
 
-**Otherwise — file-only, or a platform with no gate-sync CI — write it.** In `state.json`: set
+**Otherwise — local, or a platform with no gate-sync CI — write it.** In `state.json`: set
 `ui-design.status: "done"`, set `ui-design-review.status: "in_review"`, and set
 `currentStep: "ui-design-review"`. Write `state.json`. Do **not** touch `approvals.json`. On this
 branch `yad gate open` makes the same edit, so it is a no-op once the gate has run.
@@ -192,9 +192,9 @@ branch `yad gate open` makes the same edit, so it is a no-op once the gate has r
 Report: the paths to `ui-design.md` and `DESIGN.md`, whether Impeccable was used, the connected design
 tool and what it produced (e.g. "Figma — 4 screens generated", the file URL + `design-links.json` path,
 or "no design tool — markdown-only"), and that the next action is **review** via `yad-review-gate` (base
-rule: owner + 1 reviewer). **Never record approval here.** Front states do not auto-advance. When the hub has a platform, the gate opens a review PR on the
+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 into
-the ledger; otherwise the review is recorded file-only.
+the ledger; otherwise the review is recorded local.
 
 ## Reference
 - Impeccable commands and the slash-command-vs-CLI deviation: `RESEARCH-NOTES.md` §4 + Deviation 3.