yadflow 3.18.1 → 3.19.0-next.2

package/skills/yad-review-companion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-review-companion
-description: 'The fun, easy, transparent review companion for the SDLC review gates. Generates a 60-second AI "trailer" of what changed and where the risk is, deals a swipe-through deck of small review "cards", and runs a grounded chat where a reviewer asks anything and their questions become the review record — then records an engagement signal on the approval (verified vs none) and posts a friendly public nudge on a bare rubber-stamp. Works on the front-half artifact-review PR/MR (yad gate) and the back-half code PR/MR (yad review). Use when the user says "review this", "run the companion", "give me the trailer/cards", or wants reviewing to be less of a chore.'
+description: 'The fun, easy, transparent review companion for the SDLC review gates. Generates a 60-second AI "trailer" of what changed and where the risk is, deals a swipe-through deck of small review "cards", and runs a grounded chat where a reviewer asks anything and their questions become the review record — then records an engagement signal on the approval (verified vs none) and posts a friendly public nudge on a bare rubber-stamp. Works on the Shape artifact-review PR/MR (yad gate) and the Build code PR/MR (yad review). Use when the user says "review this", "run the companion", "give me the trailer/cards", or wants reviewing to be less of a chore.'
 ---
 
 # SDLC — Review Companion (fun & easy, transparent review)
@@ -14,8 +14,8 @@ reviewers skip, and it makes review *quality* visible to the whole team.
 > raises the cost of a bare rubber-stamp and shines a light on it; it never claims certainty. State that
 > openly — do not oversell it.
 
-This companion is the AI layer on top of [`yad-review-gate`](../yad-review-gate/SKILL.md) (front half)
-and [`yad-engineer-review`](../yad-engineer-review/SKILL.md) (back half). The **gate** still owns the
+This companion is the AI layer on top of [`yad-review-gate`](../yad-review-gate/SKILL.md) (Shape)
+and [`yad-engineer-review`](../yad-engineer-review/SKILL.md) (Build). The **gate** still owns the
 predicate and advancement; the companion only enriches the *input* and records the *engagement* field.
 The CLI never calls an LLM — **you** (this skill) generate the text and post it via the platform.
 
@@ -46,12 +46,12 @@ The CLI never calls an LLM — **you** (this skill) generate the text and post i
 
 ## On activation
 
-Inputs: `epic` + `artifact` (front half) **or** `repo` + `pr` (back half); and the `action`
+Inputs: `epic` + `artifact` (Shape) **or** `repo` + `pr` (Build); and the `action`
 (`trailer` | `cards` | `chat` | `approve` | `nudge`, default the full flow).
 
-1. **Get the grounding bundle.** Front half: `yad gate review <epic> [artifact]` prints JSON with the
+1. **Get the grounding bundle.** Shape: `yad gate review <epic> [artifact]` prints JSON with the
    artifact path, risk tags, PR number, contract path, touched domains, repo code-map paths, and
-   `requireEngagement`. Back half: `yad review chat --repo <r>` (see `yad-engineer-review`) provides the
+   `requireEngagement`. Build: `yad review chat --repo <r>` (see `yad-engineer-review`) provides the
    diff + code-map grounding. Read the named files yourself — never invent content.
 2. **Trailer.** Generate ≤6 lines (what / risk / read-time), grounded only in the bundle. Post it:
    `yad gate trailer <epic> <artifact> --body "<text>" [--pr <n>]` (idempotent; re-run after edits).
@@ -81,7 +81,7 @@ Inputs: `epic` + `artifact` (front half) **or** `repo` + `pr` (back half); and t
   proof. The strict-mode switch is `hub.review.requireEngagement` (off by default).
 - **The companion never approves on a human's behalf and never merges.** It assists; the human acts.
 
-## File-only mode (no platform)
+## local mode (no platform)
 
 With no hub platform, there is no PR to post to: write the trailer to
 `reviews/<artifact-base>--<date>--trailer.md` and the card/chat notes alongside the existing

package/skills/yad-review-gate/SKILL.md

@@ -11,15 +11,15 @@ UI, stories, test-cases) uses this exact gate. **No step advances until its revi
 recorded as a file. The `analysis-review`, `epic`/`ui-design`, and `test-cases` reviews use the **base**
 rule (owner + 1 reviewer); escalation applies only where `risk_tags` or per-repo routing call for it.
 
-This gate is **swappable and file-driven**: it talks only through files. A front step advances only on a
-human act — recording an approval and `advance`, or (with the bridge) **merging the approved,
+This gate is **swappable and file-driven**: it talks only through files. A Shape step advances only on a
+human act — recording an approval and `advance`, or (with a verified ledger) **merging the approved,
 fully-resolved review PR/MR**. It works the same whether a human or the `yad gate` CLI triggers it — the
 trigger is a parameter, not a hardcoded human.
 
 ## Conventions
 - `{project-root}` resolves from the project working directory.
 - Operate on one epic: `{project-root}/epics/EP-<slug>/`.
-- State files: `.sdlc/state.json`, `.sdlc/approvals.json`, `.sdlc/comments.json`, and (when the bridge is
+- State files: `.sdlc/state.json`, `.sdlc/approvals.json`, `.sdlc/comments.json`, and (when the verified ledger is
   used) `.sdlc/hub-prs.json`. Review records: `reviews/`.
 - The artifact base name drops the extension (`epic.md` → `epic`; story `stories/...S01.md` → `stories-S01`).
 
@@ -54,13 +54,13 @@ touched `repos` — never a forked or copied gate.
 
 ### Step 2 — Dispatch on `action`
 
-> **Check the mode first — in bridge mode you write nothing to the ledger.** Read `.sdlc/hub.json`:
-> **bridge mode** is `platform` set AND `bridge_enabled` (or legacy `bridge`) `true`. Under the bridge
+> **Check the mode first — in verified mode you write nothing to the ledger.** Read `.sdlc/hub.json`:
+> **verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present. Under the verified ledger
 > the ledger is CI-owned — `ledger-guard` rejects any non-bot commit touching
 > `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or `epics/*/reviews/*.md`, local `yad gate
 > sync` is advisory, and `yad gate ci --merged` writes the whole transition when the review PR merges.
-> So every "set / append / write" instruction below is the **file-only, or a platform with no
-> gate-sync CI** path. In bridge mode do the human-facing half — present the artifact, route the
+> So every "set / append / write" instruction below is the **local, or a platform with no
+> gate-sync CI** path. In verified mode do the human-facing half — present the artifact, route the
 > required reviewers, help the owner address comments — and let the platform PR/MR carry the review
 > state; the approvals, comments, review records and the advance all land through CI at merge.
 
@@ -68,13 +68,13 @@ touched `repos` — never a forked or copied gate.
 the rule above, and tell reviewers how to comment/approve. Set the step `status` to `in_review` and
 `currentStep` to this step in `state.json` if not already. Do not advance.
 
-If `.sdlc/hub.json` has a non-null `platform` and `bridge_enabled: true` (or legacy `bridge: true` —
-`.sdlc/hub.json` is the only source the CLI reads, see `isBridge` in `cli/gate.mjs`), and `gh`/`glab`
+If `.sdlc/hub.json` has a non-null `platform` and `ledger: "verified"` (or, before `yad migrate`, `bridge_enabled: true` / legacy `bridge: true` —
+`.sdlc/hub.json` is the only source the CLI reads, see `isVerifiedLedger` in `cli/manifest.mjs`), and `gh`/`glab`
 is authenticated, **also open a review PR/MR on the hub** by invoking `yad-hub-bridge action: open`
 (epic + artifact), and report the URL + required reviewers. **CI records the PR** in
 `epics/<epic>/.sdlc/hub-prs.json` (`{step, artifact, platform, number, url, branch, lastSyncedAt}`) —
-write that file yourself only on the file-only path. Otherwise (no platform / disabled / no CLI)
-proceed **file-only** exactly as before — no error. Opening the PR records no approvals and never
+write that file yourself only on the local path. Otherwise (no platform / disabled / no CLI)
+proceed **local** exactly as before — no error. Opening the PR records no approvals and never
 advances.
 
 **`comment`** — Capture reviewer feedback. Append/create a review file
@@ -156,7 +156,7 @@ gate sync`), `sync` advances the step when Step 3 passes on a **merged**, fully-
 
 ### Step 3 — Gate predicate (the only path that advances)
 The step may advance **iff ALL hold**:
-1. `automation` is `human_approve` (it always is for front steps) and the required approvals exist:
+1. `automation` is `human_approve` (it always is for Shape steps) and the required approvals exist:
    ≥1 `owner` AND ≥`review_gate.default_reviewers` (1) distinct non-owner `reviewer`, AND — if the
    step is escalated — ≥1 `domain-owner` for each touched domain.
 2. The artifact has not changed since the latest approval round (no newer authored edit than the
@@ -172,10 +172,10 @@ If the predicate **passes**:
 - Mark this review step `status: "done"`.
 - **`stories-review`** is the end of the gating chain: set `currentStep: "ready-for-build"` (the Phase 3
   handoff sentinel; intentionally not a `steps[]` entry) **and** open the parallel **`test-cases`** track
-  (set its step `blocked` → `in_progress`). The build half can now start **and** the tester can work
+  (set its step `blocked` → `in_progress`). Build can now start **and** the tester can work
   `test-cases` at the same time.
 - **`test-cases-review`** is the parallel track's gate: mark it `done` but **leave `currentStep` at
-  `ready-for-build`** — completing test cases must never pull the epic back from the build half.
+  `ready-for-build`** — completing test cases must never pull the epic back from Build.
 - Any **other** review step: set the next step in `steps[]` from `blocked` to `in_progress` (authoring)
   or `in_review`, and set `currentStep` to that next step.
 - Write `state.json`. Report the advance and what the next authored artifact is (or that the epic is
@@ -187,7 +187,7 @@ PR only — against the `review/<epic>/<artifact>` branch, which must already ex
 `yad open-pr` from it, which pushes it first). CI (`yad gate ci`) writes the `.sdlc/` + `reviews/`
 records this skill describes. The skill's
 job is the human half: presenting the artifact, helping the owner address comments, and narrating the
-gate. Local `yad gate sync` is advisory in bridge mode (reads the platform, prints status, writes
+gate. Local `yad gate sync` is advisory in verified mode (reads the platform, prints status, writes
 nothing); a human must never commit gate-state files (the `ledger-guard` check rejects it, and the
 `hooks/ledger-guard.sh` harness hook refuses an agent the edit up front, naming `yad gate open`
 instead — see `yad-checks`). The single
@@ -210,11 +210,11 @@ platform PR/MR is the source of truth (native approvals + threads), and CI never
 branch (so an in-flight approval is never dismissed and required checks never strand). On the human
 **merge** CI re-reads approvals, advances the step, and flips the artifact `status:` on the **default
 branch**. After a merge, `git checkout <default> && git pull` to see it. The predicate and the human
-merge are unchanged — CI never approves and never merges. File-only mode (no platform) keeps the local
+merge are unchanged — CI never approves and never merges. Local mode (no platform) keeps the local
 write path.
 
 ### Hard rules (build plan §1, §5)
-- **The merge click is the human approval act.** A front step advances only when a human merges the
+- **The merge click is the human approval act.** A Shape step advances only when a human merges the
   approved, fully-resolved review PR — there is no machine-driven advance. A step `locked: true` may not
   be switched to `machine_advance`; refuse such a request.
 - **Approvals are revoked when the reviewed artifact changes.** `sync` re-hashes the artifact (the locked
@@ -223,7 +223,7 @@ write path.
 - The gate talks only through `.sdlc/` and `reviews/` files — never hidden state.
 - **The platform is an input path only.** `open`/`sync` use the local user's own `gh`/`glab` (no stored
   tokens), and the **file ledger remains the source of truth** — the Step 3 predicate is unchanged
-  whether approvals arrive manually or via `sync`. With no hub platform / no CLI, the gate runs file-only
+  whether approvals arrive manually or via `sync`. With no hub platform / no CLI, the gate runs local
   with no error (record approvals manually and `advance`).
 
 ## Reference

package/skills/yad-review-gate/references/gating.md

@@ -77,8 +77,8 @@ marker, and the gate **excludes marked threads** from the unresolved-thread bloc
 not "resolve to pass" — it ignores them). A reviewer's *genuine* concern is posted **without** the
 marker and blocks normally, exactly as a `CHANGES_REQUESTED` or any unresolved human thread does.
 
-## Platform-backed input (the bridge)
-When the hub has a platform (`.sdlc/hub.json`) and the bridge is enabled, reviewers can approve/comment
+## Platform-backed input (the verified ledger)
+When the hub has a platform (`.sdlc/hub.json`) and the ledger is verified, reviewers can approve/comment
 on a real PR/MR instead of (or as well as) the skill recording it directly. `action: sync`
 (`yad-hub-bridge`) reads that platform state with the reviewer's own `gh`/`glab` and writes the **same**
 `approvals.json` / `comments.json` / `reviews/*.md` records the manual path writes — bridge approvals
@@ -99,7 +99,7 @@ approvals regardless of how they were recorded.
   new ones (see `../yad-hub-bridge/references/bridge.md` → "Idempotent re-sync").
 - The architecture+contract staleness rule applies to bridge approvals too: a re-lock discards bridge
   approvals dated before the new lock.
-- No platform / no CLI → the gate runs file-only with no error. Detail: `../yad-hub-bridge/references/bridge.md`.
+- No platform / no CLI → the gate runs local with no error. Detail: `../yad-hub-bridge/references/bridge.md`.
 
 ## Why this shape
 - Owner + 1 reviewer keeps review load low on a small team (design priority 2) while still requiring

package/skills/yad-run/SKILL.md

@@ -1,19 +1,19 @@
 ---
 name: yad-run
-description: 'Phase 4 (automation) — the orchestrator that makes the second dial real. Drives a story''s back-half loop (spec → tasks → implement → checks) in one code repo, reading each step''s automation dial from build-state: on machine_advance it advances on its own, on human_approve it stops for a human. Records every run in the trust log (the evidence base for earning automation). Realizes Step B: when checks is earned, a clean gate pass auto-advances to engineer-review; any failure, scope overrun, or contract-surface touch HALTS and pulls in a human. Also sets a step''s dial (gated by trust evidence) and flips the system-wide kill switch. Never advances a front state or the engineer review. Use when the user says "run the build half", "advance story <id>", "set the checks dial", or "kill switch".'
+description: 'Phase 4 (automation) — the orchestrator that makes the second dial real. Drives a story''s Build loop (spec → tasks → implement → checks) in one code repo, reading each step''s automation dial from build-state: on machine_advance it advances on its own, on human_approve it stops for a human. Records every run in the trust log (the evidence base for earning automation). Realizes Step B: when checks is earned, a clean gate pass auto-advances to engineer-review; any failure, scope overrun, or contract-surface touch HALTS and pulls in a human. Also sets a step''s dial (gated by trust evidence) and flips the system-wide kill switch. Never advances a Shape step or the engineer review. Use when the user says "run Build", "advance story <id>", "set the checks dial", or "kill switch".'
 ---
 
 # SDLC — Run (Phase 4 orchestrator)
 
 **Goal:** Be the **engine** that the `automation` dial finally drives. Until Phase 4 the dial was inert
-config; this skill reads it and acts. For ONE story in ONE code repo, walk the back-half steps —
+config; this skill reads it and acts. For ONE story in ONE code repo, walk the Build steps —
 `spec → tasks → implement → checks → engineer-review` — and at each step either **advance on its own**
 (dial `machine_advance`, step succeeded) or **stop for a human** (dial `human_approve`, or any halt
 condition). Every run is recorded in the **trust log**, the evidence that earns a step its automation.
 
 This is the most dangerous skill in the system, so it is built to **halt-and-escalate over guess**:
 a failing check, ambiguity, a scope overrun, or a contract-surface touch stops the loop and pulls in a
-human regardless of any dial. The **front states and the engineer review never auto-advance** — they
+human regardless of any dial. The **Shape steps and the engineer review never auto-advance** — they
 are not in `automation.back_steps` and `engineer-review` is `locked`.
 
 Earned so far: **`checks`** (Step B, Phase 4a — safest, a gate's pass/fail was never human judgment)
@@ -30,14 +30,14 @@ signal to seed them from, so they are earned only on real runs.
   (`config.yaml` `build.code_repos_root`). Operate inside them with absolute paths.
 - Automation config is `skills/sdlc/config.yaml` → `automation:` (`back_steps`, `default`,
   `trust_threshold`, `locked_steps`, `kill_switch`).
-- Per-story build-half state: `epics/<epic>/.sdlc/build-state/<story-id>.json` (per repo).
+- Per-story Build state: `epics/<epic>/.sdlc/build-state/<story-id>.json` (per repo).
 - Trust ledger: **shard-then-fold** — each run is its own shard file
   `epics/<epic>/.sdlc/trust-log/<story>-<repo>-<step>-<uid>.json` (a fresh `uid` per run, so concurrent
   writers never conflict); readers UNION the folded `trust-log.json` with every loose shard, and
   `yad tidy up` folds finished shards back into `trust-log.json`. Schemas:
   `../yad-epic/references/state-schema.md`.
-- These machine-written back-half files (`build-state/<story>.json`, the `trust-log/` shards) are
-  committed by **`yad checkpoint`** — the back-half analogue of the front-half `yad gate` sync; the loop
+- These machine-written Build files (`build-state/<story>.json`, the `trust-log/` shards) are
+  committed by **`yad checkpoint`** — the Build analogue of the Shape `yad gate` sync; the loop
   calls it each iteration so the state is durable and shared without a human commit. (`yad checkpoint`
   stages the shard dirs; `yad tidy up` later folds finished shards — loose objects + `git gc`.)
 - The orchestrator **calls the existing step skills unchanged** — `yad-spec` (A), `yad-implement`
@@ -86,7 +86,7 @@ Walk the steps for `repo` starting at `from`/`currentStep`. For each step:
 
 **Commit the machine-written state.** After each iteration's writes (the trust-log shard in 2 and the
 build-state change in 4), run `yad checkpoint --push` from `{project-root}`. It commits *only* the
-`trust-log/` shards + `build-state/<story>.json` (never a front-half gate file) as one `chore(hub): …`
+`trust-log/` shards + `build-state/<story>.json` (never a Shape gate file) as one `chore(hub): …`
 audit-trail commit, and only ever on the default branch. It is a safe no-op when nothing changed, so
 call it every iteration — teammates don't review these machine writes, but CI and `yad status` on
 other machines must see current trust evidence. Never run it off the default branch (it will refuse):
@@ -94,8 +94,8 @@ an unpushed or branch-stranded trust log quietly undermines the "earned automati
 
 ### `action: set-dial` — earn (or revert) a step's automation
 Flip `step`'s `automation` to `to` in build-state. Enforce, in order:
-- **Refuse** if `step` is in `automation.locked_steps` or is a front state or `engineer-review` —
-  these can never be `machine_advance` (front-state lock, build plan §E). Report the refusal reason.
+- **Refuse** if `step` is in `automation.locked_steps` or is a Shape step or `engineer-review` —
+  these can never be `machine_advance` (Shape step lock, build plan §E). Report the refusal reason.
 - For `to: machine_advance`, **refuse unless the trust threshold is met**: the step's slice of the trust
   ledger — the **union** of the folded `trust-log.json` `runs` PLUS every `trust-log/` shard, filtered to
   this step (and repo) — has `>= trust_threshold.min_runs` entries AND the fraction with
@@ -117,7 +117,7 @@ reversible (build plan §Safety). Report the new state and that `yad-status` wil
   one command and no code change.
 - **Halt-and-escalate beats guess.** A failing check, ambiguity, scope overrun, or contract-surface
   touch halts the loop and pulls in a human, regardless of the dial.
-- **Front states and the engineer review never auto-advance.** They are not in `back_steps`;
+- **Shape steps and the engineer review never auto-advance.** They are not in `back_steps`;
   `engineer-review` is `locked`; the kill switch and locks always override the dial.
 - **The orchestrator never changes what a step does** — it calls the existing skills and owns only the
   advance decision and the trust record.

package/skills/yad-run/references/run-loop.md

@@ -4,7 +4,7 @@ This is the detail behind `SKILL.md`. It restates the orchestration so the skill
 and pins down the two judgments the skill makes: **what trust verdict to record** and **when a step
 has earned `machine_advance`**.
 
-## The back-half steps
+## The Build steps
 
 From `config.yaml` `automation.back_steps` plus the human merge gate:
 
@@ -23,7 +23,7 @@ cfg   = config.yaml.automation
 bs    = build-state/<story>.json.repos[<repo>]        # create from defaults if absent
 step  = from or bs.currentStep
 
-while step is a back step (not engineer-review):
+while step is a Build step (not engineer-review):
     result = run_step_skill(step)                     # yad-spec | yad-implement | yad-checks
 
     signals = derive_signals(step, result)            # see "Deriving signals"
@@ -50,14 +50,14 @@ nudge; otherwise `human`. Persist build-state after every transition so a halt l
 resumable record.
 
 `checkpoint` = run `yad checkpoint --push` from `{project-root}`. It commits the machine-written
-back-half ledgers (in this loop, the loose `trust-log/` shards this run wrote + `build-state/<story>.json`;
+Build ledgers (in this loop, the loose `trust-log/` shards this run wrote + `build-state/<story>.json`;
 also the `build-log/` shards at engineer-review) — the shard dirs are what checkpoint stages, the same
 way `git gc` folds loose objects later (`yad tidy up` folds finished shards into the folded
 `trust-log.json` / `build-log.json`) — plus any story `status:` flip (→ in-build/shipped) once that
 story has a build-log ship (#112) — as one
-`chore(hub): sync back-half state — <epic>/<story> by @<login> [skip ci]`
+`chore(hub): sync Build state — <epic>/<story> by @<login> [skip ci]`
 audit-trail commit, on the default branch only,
-staging *only* those files by an explicit allowlist (never a front-half gate file — so `ledger-guard`
+staging *only* those files by an explicit allowlist (never a Shape gate file — so `ledger-guard`
 never trips). It is idempotent (a no-op when nothing changed), so calling it after every transition —
 including a halt — is safe and keeps the shared trust evidence current for CI, teammates, and
 `yad status` on other machines. It refuses to run off the default branch (an unsigned `[skip ci]`
@@ -73,7 +73,7 @@ if step in cfg.locked_steps:       eff = "human_approve"
 ```
 
 So a kill switch, a `locked` flag, or membership in `locked_steps` forces a stop no matter what the
-per-step dial says. `engineer-review` and the five front states are covered by `locked` / `locked_steps`.
+per-step dial says. `engineer-review` and the five Shape steps are covered by `locked` / `locked_steps`.
 
 ## Deriving signals & the provisional verdict
 
@@ -93,7 +93,7 @@ finalizes the entry — a human always has the last word on the trust signal.
 - `contract_touch` — `true` if the diff touched the locked contract surface without an upstream
   re-lock (routes back to the architecture gate).
 
-`derive_verdict(signals)` — the same three-way shape for every back step:
+`derive_verdict(signals)` — the same three-way shape for every Build step:
 ```
 edited = human_edited_diff or human_edited_spec or task_rescoped
 if checks == "fail" or scope_overrun or contract_touch:   verdict = "rejected"
@@ -134,7 +134,7 @@ Reverting (`to: human_approve`) is never gated — automation must be reversible
 ## What stays human, always
 
 - `engineer-review` — the merge gate. `yad-run` always stops here and hands to `yad-engineer-review`.
-- The five front states (`epic`, `architecture`, `ui-design`, `stories`, `test-cases`) — not in
+- The five Shape steps (`epic`, `architecture`, `ui-design`, `stories`, `test-cases`) — not in
   `back_steps`, in `locked_steps`; the dial-setter refuses them.
 - Any contract-surface change — halts the loop and routes back to the architecture gate, regardless of
   the dial.

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`.