yadflow 3.18.0 → 3.19.0-next.2

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

@@ -1,6 +1,6 @@
 ---
 name: yad-pair-review
-description: 'The guided, two-way, teaching pair-review walkthrough for the SDLC review gates — the AI-driven companion face. The human opens a PR/MR with an AI session and the AI walks them through the change ONE STOP AT A TIME (highest-risk first), giving comprehensive context per change, then asking the human a Socratic question about it; the human answers and asks back, and both keep going until BOTH declare satisfied. The session doubles as a learning session: it demonstrates a transferable review method, scores the engineer against it, and records their review-skill growth in the local-only yad-learn ledger (rolled up by yad status). Works on the back-half code PR/MR (yad review) and the front-half artifact-review PR/MR (yad gate). Soft and additive — it NEVER blocks a merge or gate; it rides the existing engagement signal and surfaces genuine concerns as normal blocking comments. Use when the user says "pair review this", "walk me through the PR/MR", "review with me", "co-review", or "teach me to review".'
+description: 'The guided, two-way, teaching pair-review walkthrough for the SDLC review gates — the AI-driven companion face. The human opens a PR/MR with an AI session and the AI walks them through the change ONE STOP AT A TIME (highest-risk first), giving comprehensive context per change, then asking the human a Socratic question about it; the human answers and asks back, and both keep going until BOTH declare satisfied. The session doubles as a learning session: it demonstrates a transferable review method, scores the engineer against it, and records their review-skill growth in the local-only yad-learn ledger (rolled up by yad status). Works on the Build code PR/MR (yad review) and the Shape artifact-review PR/MR (yad gate). Soft and additive — it NEVER blocks a merge or gate; it rides the existing engagement signal and surfaces genuine concerns as normal blocking comments. Use when the user says "pair review this", "walk me through the PR/MR", "review with me", "co-review", or "teach me to review".'
 ---
 
 # SDLC — Pair Review (the guided, two-way, teaching walkthrough)
@@ -27,8 +27,8 @@ platform.**
 ## Conventions
 
 - `{project-root}` resolves from the project working directory — the **product hub**.
-- Back half (code PR/MR): grounded by `yad review walkthrough --repo <r> --pr <n>`.
-- Front half (artifact-review PR/MR): grounded by `yad gate walkthrough <epic> [artifact]`.
+- Build (code PR/MR): grounded by `yad review walkthrough --repo <r> --pr <n>`.
+- Shape (artifact-review PR/MR): grounded by `yad gate walkthrough <epic> [artifact]`.
 - The transferable review method + scorecard live in `references/review-rubric.md`.
 - The session-record comment shape, the dual sign-off, and the learning record this writes live in
   `references/session-state.md` (it reuses [`yad-learn`](../yad-learn/SKILL.md)'s ledger + gitignore
@@ -38,7 +38,7 @@ platform.**
 
 ## Inputs
 
-- Back half: `repo` + `pr`. Front half: `epic` + `artifact`.
+- Build: `repo` + `pr`. Shape: `epic` + `artifact`.
 - `member` — the learner being paired with (default: the invoking user). Used for the learning record.
 - `action` — `walkthrough` (the full session, default) | `record` (just write the session comment +
   learning record from an already-finished session) | `rubric` (print the review method and stop).
@@ -47,9 +47,9 @@ platform.**
 
 ### Step 1 — Get the ordered stops (the grounding)
 Run the walkthrough grounding for the half you're on:
-- Back half: `yad review walkthrough --repo <r> --pr <n>` → prints the grounding bundle **plus an ordered
+- Build: `yad review walkthrough --repo <r> --pr <n>` → prints the grounding bundle **plus an ordered
   `stops[]`** (the code diff parsed into hunk-anchored, risk-tagged review stops, highest-risk first).
-- Front half: `yad gate walkthrough <epic> [artifact]` → the same, over the artifact's review diff.
+- Shape: `yad gate walkthrough <epic> [artifact]` → the same, over the artifact's review diff.
 
 **Read the real material yourself** — run the bundle's `diffCmd`, and read the named `codeMap` / `pack` /
 `contract` / `artifactPath` / `specs/<story>/` files. Never invent content. If a stop's material isn't
@@ -87,8 +87,8 @@ After the last stop:
   concern remains*.
 - **Human sign-off.** The human decides: **approve** or **request changes**. When they approve through
   this session, submit the approval carrying the engagement marker so the gate records
-  `engagement: verified` — back half: `gh pr review <n> --approve --body "<note>\n\n<!-- yad:engagement verified -->"`
-  (GitLab: `glab mr approve <n>` then a note with the marker); front half: the human approves via
+  `engagement: verified` — Build: `gh pr review <n> --approve --body "<note>\n\n<!-- yad:engagement verified -->"`
+  (GitLab: `glab mr approve <n>` then a note with the marker); Shape: the human approves via
   [`yad-review-gate`](../yad-review-gate/SKILL.md) the normal way.
 
 "**Both satisfied**" = the human approved **and** your verdict holds no unresolved blocking concern. If
@@ -101,7 +101,7 @@ addresses them) — nothing advances on a half-finished session.
    never holds the gate): the transcript summary, the **review-skill scorecard**, your AI verdict, and
    both sign-offs. Post it with the platform CLI (`gh pr comment` / `glab mr note`).
 2. **Learning record (local-only).** Append a `yad-learn` record for the `member`: `concept` =
-   `review <repo> PR #<n> — <title>` (front half: `review <artifact> (<epic>)`), `stage` =
+   `review <repo> PR #<n> — <title>` (Shape: `review <artifact> (<epic>)`), `stage` =
    `engineer-review` (back) / `<artifact>-review` (front), `mode` = `deep` (or `quiz` when you scored
    comprehension), `comprehension` = the scorecard roll-up, `tutorial` = a rendered
    `learning/<member>--review-<pr>.md` capturing the method as applied to this PR + the engineer's gaps.
@@ -125,7 +125,7 @@ addresses them) — nothing advances on a half-finished session.
   or push the records/tutorials, and never write them into a code repo.
 - **You never approve for the human and never merge.** You pair and teach; 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 session record to
 `reviews/<base>--<date>--pair-session.md` alongside the existing `reviews/*.md`, and the human records
@@ -138,7 +138,7 @@ the posting surface differs.
 - The transferable review method + scorecard schema: `references/review-rubric.md`.
 - The session comment shape, dual sign-off, and learning record: `references/session-state.md`.
 - The four skim faces this complements: [`yad-review-companion`](../yad-review-companion/SKILL.md).
-- The back-half merge gate it enriches: [`yad-engineer-review`](../yad-engineer-review/SKILL.md).
-- The front-half gate it enriches: [`yad-review-gate`](../yad-review-gate/SKILL.md).
+- The Build merge gate it enriches: [`yad-engineer-review`](../yad-engineer-review/SKILL.md).
+- The Shape gate it enriches: [`yad-review-gate`](../yad-review-gate/SKILL.md).
 - The learning layer it records into: [`yad-learn`](../yad-learn/SKILL.md) and its
   `references/learning-state.md`.

package/skills/yad-pair-review/references/session-state.md

@@ -22,7 +22,7 @@ Sections (you generate the prose; the helper composes them):
 - **humanSignoff / aiSignoff** — the two satisfaction statements ("both satisfied").
 
 Post it with the platform CLI (`gh pr comment <n> -b "<body>"` / `glab mr note <n> -m "<body>"`). In
-file-only mode write it to `reviews/<base>--<date>--pair-session.md` instead.
+local mode write it to `reviews/<base>--<date>--pair-session.md` instead.
 
 ## 2. The learning record (local-only, reuses yad-learn)
 
@@ -62,7 +62,7 @@ cross-project), using yad-learn's exact field shape:
 ```
 
 Field notes:
-- `stage` = `engineer-review` (back half) or `<artifact>-review` (front half, e.g. `architecture-review`).
+- `stage` = `engineer-review` (Build) or `<artifact>-review` (Shape, e.g. `architecture-review`).
 - `mode` = `deep` for a walkthrough that didn't score, `quiz` when you captured a comprehension roll-up.
 - `comprehension` = the scorecard roll-up string (null when `mode: deep`).
 - `tool` = `harness-native` (or `deeptutor` if a DeepTutor session backed the tutoring).
@@ -74,7 +74,7 @@ engineer's specific gaps and how to close them. Both files are **local-only, git
 or pushed, and never written into a code repo** — they are a private personal skills log. `yad status`
 rolls them up by stage (e.g. "engineer-review: 3").
 
-## Optional: stamp the build-log (back half)
+## Optional: stamp the build-log (Build)
 
 When the task later ships, [`yad-engineer-review`](../../yad-engineer-review/SKILL.md) may record on the
 ship record's `companion` block that a pair session ran: `"companion": { "trailer": true, "cards": false,

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

@@ -1,14 +1,14 @@
 ---
 name: yad-pr-template
-description: 'Build-half Step D of the gated SDLC. Detect a code repo''s platform and commit the matching PR/MR template — .github/pull_request_template.md (GitHub) or .gitlab/merge_request_templates/Default.md (GitLab). The template carries an Impact & Risk block; a high risk level (or a touched contract/auth/payments surface) routes the review to domain owners, reusing yad-review-gate''s escalation. Includes risk-route.sh to print the required reviewers from a PR body. Never auto-advances. Use when the user says "add the PR template" or "set up the MR template" for a repo.'
+description: 'Build Step D of the gated SDLC. Detect a code repo''s platform and commit the matching PR/MR template — .github/pull_request_template.md (GitHub) or .gitlab/merge_request_templates/Default.md (GitLab). The template carries an Impact & Risk block; a high risk level (or a touched contract/auth/payments surface) routes the review to domain owners, reusing yad-review-gate''s escalation. Includes risk-route.sh to print the required reviewers from a PR body. Never auto-advances. Use when the user says "add the PR template" or "set up the MR template" for a repo.'
 ---
 
-# SDLC — PR/MR Template (build-half Step D)
+# SDLC — PR/MR Template (Build Step D)
 
 **Goal:** Commit the platform-correct PR/MR template into a code repo so every PR/MR carries an
 **Impact & Risk** block and a checklist tied to the check gates. A **high** risk level (or a touched
 contract/auth/payments surface) **routes the review to domain owners** — the same escalation
-`yad-review-gate` applies on the front-half gates (owner + 1 reviewer, plus one domain-owner per
+`yad-review-gate` applies on the Shape gates (owner + 1 reviewer, plus one domain-owner per
 touched domain). This step **never auto-advances**; it sets up the template and the routing helper.
 
 ## Conventions
@@ -21,7 +21,7 @@ touched domain). This step **never auto-advances**; it sets up the template and
   - `templates/gitlab/merge_request_templates/Default.md` → installs to
     `<repo>/.gitlab/merge_request_templates/Default.md`
   - `templates/checks/risk-route.sh` → installs to `<repo>/checks/risk-route.sh` (advisory routing helper)
-  - **Hub variants** (`repo: hub`) — front-half artifact-review PR/MR bodies:
+  - **Hub variants** (`repo: hub`) — Shape artifact-review PR/MR bodies:
     `templates/hub/github/pull_request_template.md` → `{project-root}/.github/pull_request_template.md`;
     `templates/hub/gitlab/merge_request_templates/Default.md` →
     `{project-root}/.gitlab/merge_request_templates/Default.md`. The hub body carries no `Task:` trailer

package/skills/yad-pr-template/references/risk-routing.md

@@ -2,7 +2,7 @@
 
 The PR/MR template (Phase 3 build plan §D) carries an **Impact & Risk** block so every change states
 its blast radius before review, and so high-risk changes pull in the right reviewers automatically —
-reusing the escalation `yad-review-gate` already applies on the front-half gates.
+reusing the escalation `yad-review-gate` already applies on the Shape gates.
 
 ## The Impact & Risk block
 

package/skills/yad-pr-template/templates/checks/pr-template.sh

@@ -5,12 +5,12 @@
 # that bypassed the template.
 #   --profile code (default) — the code-repo task template (yad-pr-template templates/<platform>/):
 #     requires `## Summary`, `## Impact & Risk`, `## Checklist`, and a filled `Risk level:` (low|medium|high).
-#   --profile hub — the front-half artifact-review template (templates/hub/<platform>/):
-#     requires `## Artifact under review`, `## Impact & Risk (front-half)`, `## Checklist`, and a `Risk tags:` line.
+#   --profile hub — the Shape artifact-review template (templates/hub/<platform>/):
+#     requires `## Artifact under review`, `## Impact & Risk (front-half)` (or `(Shape)`), `## Checklist`, and a `Risk tags:` line.
 #     BUT only for review/EP-* head branches. Every other hub PR is a tooling/code change to the hub
 #     itself and uses the code task template instead; pass the head ref via --head so the gate knows
 #     which template to require. With no --head, the hub profile stays strict (artifact-review template).
-#     Branch name is not enough on its own: a non-review head that actually changes front-half
+#     Branch name is not enough on its own: a non-review head that actually changes Shape
 #     artifacts (epics/**) would otherwise slip past the review workflow with only the code template.
 #     Pass the PR's changed paths via --changed <file> (one path per line); when they touch epics/**
 #     on a non-review head the gate FAILS — artifact changes must go through a review/EP-* PR.
@@ -35,7 +35,7 @@ while [ $# -gt 0 ]; do
 done
 case "$PROFILE" in code|hub) ;; *) echo "FAIL [pr-template]: unknown --profile '$PROFILE' (code|hub)."; exit 1 ;; esac
 
-# True when the PR changes a front-half artifact (anything under epics/**). Reads the --changed list
+# True when the PR changes a Shape artifact (anything under epics/**). Reads the --changed list
 # of paths CI computed from the PR diff; with no list (direct caller / test) it reports false.
 artifact_changed() { [ -n "$CHANGED" ] && [ -f "$CHANGED" ] && grep -qE '^epics/' "$CHANGED"; }
 
@@ -91,13 +91,21 @@ check_code_body() {
   fi
 }
 
-# The front-half artifact-review template.
+# The Shape artifact-review template.
 check_hub_body() {
   require_heading '## Artifact under review' '## Artifact under review'
-  require_heading '## Impact & Risk \(front-half\)' '## Impact & Risk (front-half)'
+  # Add before you remove (change-safety rule 3). `front-half` is the ORIGINAL spelling and it is
+  # still what `yad gate open` emits and what the shipped hub template carries; `Shape` is the
+  # replacement, accepted here first so that this script is lenient BEFORE anything starts writing
+  # the new wording. That ordering is the whole point: this file is refreshed by `yad update`
+  # (HUB_WIRING, cli/manifest.mjs), but the PR template beside it is NOT — it is installed only by
+  # the `yad-pr-template repo:hub action: wire` skill, which nothing runs automatically. So a hub
+  # WILL sit with a refreshed checker next to an old template, and the checker has to accept both.
+  # The emitter flips to `(Shape)` in the next major; only after that may `front-half` be dropped.
+  require_heading '## Impact & Risk \((front-half|Shape)\)' '## Impact & Risk (front-half)'
   require_heading '## Checklist' '## Checklist'
   if ! grep -qiE '(\*\*)?Risk tags:' "$BODY"; then
-    echo "FAIL [pr-template]: missing 'Risk tags:' line (front-half Impact & Risk)."
+    echo "FAIL [pr-template]: missing 'Risk tags:' line (Shape Impact & Risk)."
     rc=1
   fi
 }
@@ -107,11 +115,11 @@ if [ "$PROFILE" = hub ]; then
   case "$HEADREF" in
     review/EP-*|"") check_hub_body ;;            # artifact-review PR (or unknown head — stay strict)
     *)
-      # tooling/code change to the hub itself — UNLESS it changes front-half artifacts (epics/**),
+      # tooling/code change to the hub itself — UNLESS it changes Shape artifacts (epics/**),
       # which must go through a review/EP-* PR. Without this guard a non-review head could carry an
-      # artifact change past the front-half review with only the code template.
+      # artifact change past the Shape review with only the code template.
       if artifact_changed; then
-        echo "FAIL [pr-template]: head '${HEADREF}' changes front-half artifacts (epics/**) but is not a review/EP-* branch — artifact changes must go through a review PR."
+        echo "FAIL [pr-template]: head '${HEADREF}' changes Shape artifacts (epics/**) but is not a review/EP-* branch — artifact changes must go through a review PR."
         rc=1
       else
         check_code_body; KIND="hub-tooling"

package/skills/yad-pr-template/templates/checks/pr-title.sh

@@ -4,12 +4,12 @@
 #   --profile code (default) — a Conventional-Commits subject "<type>: <description>", no trailing
 #     period (config.yaml build.pr_title_style: same_as_commit_subject; one task = one PR, the title is
 #     the squash-merge subject). Keep <type> in sync with cli/manifest.mjs COMMIT_TYPES.
-#   --profile hub — a front-half artifact-review title "review: <artifact> (EP-<slug>)", the shape
+#   --profile hub — a Shape artifact-review title "review: <artifact> (EP-<slug>)", the shape
 #     `yad gate open` creates (cli/gate.mjs) — BUT only for review/EP-* head branches. Every other
 #     hub PR is a tooling/code change to the hub itself and follows the code convention; pass the
 #     head ref via --head so the gate can tell the two apart (a tooling PR has no EP artifact to
 #     review). With no --head, the hub profile stays strict (requires the review shape).
-#     Branch name is not enough on its own: a non-review head that actually changes front-half
+#     Branch name is not enough on its own: a non-review head that actually changes Shape
 #     artifacts (epics/**) would otherwise slip past the review workflow with a plain code title.
 #     Pass the PR's changed paths via --changed <file> (one path per line); when they touch epics/**
 #     on a non-review head the gate FAILS — artifact changes must go through a review/EP-* PR.
@@ -34,7 +34,7 @@ while [ $# -gt 0 ]; do
 done
 case "$PROFILE" in code|hub) ;; *) echo "FAIL [pr-title]: unknown --profile '$PROFILE' (code|hub)."; exit 1 ;; esac
 
-# True when the PR changes a front-half artifact (anything under epics/**). Reads the --changed list
+# True when the PR changes a Shape artifact (anything under epics/**). Reads the --changed list
 # of paths CI computed from the PR diff; with no list (direct caller / test) it reports false.
 artifact_changed() { [ -n "$CHANGED" ] && [ -f "$CHANGED" ] && grep -qE '^epics/' "$CHANGED"; }
 
@@ -62,7 +62,7 @@ check_code_title() {
 }
 
 if [ "$PROFILE" = hub ]; then
-  # review/EP-* head branch (or unknown head ref) => front-half artifact-review PR: 'review: <artifact> (EP-<slug>)'.
+  # review/EP-* head branch (or unknown head ref) => Shape artifact-review PR: 'review: <artifact> (EP-<slug>)'.
   case "$HEADREF" in
     review/EP-*|"")
       if printf '%s' "$TITLE" | grep -qE '^review: .+ \(EP-[a-z0-9-]+\)$'; then
@@ -73,11 +73,11 @@ if [ "$PROFILE" = hub ]; then
       exit 1
       ;;
     *)
-      # Any other hub PR is a tooling/code change to the hub itself — UNLESS it changes front-half
+      # Any other hub PR is a tooling/code change to the hub itself — UNLESS it changes Shape
       # artifacts (epics/**), which must go through a review/EP-* PR. Without this guard a non-review
-      # head could carry an artifact change past the front-half review with only a code title.
+      # head could carry an artifact change past the Shape review with only a code title.
       if artifact_changed; then
-        echo "FAIL [pr-title]: head '${HEADREF}' changes front-half artifacts (epics/**) but is not a review/EP-* branch — artifact changes must go through a review PR."
+        echo "FAIL [pr-title]: head '${HEADREF}' changes Shape artifacts (epics/**) but is not a review/EP-* branch — artifact changes must go through a review PR."
         exit 1
       fi
       # tooling only — fall through to the code convention.

package/skills/yad-pr-template/templates/hub/github/pull_request_template.md

@@ -1,4 +1,4 @@
-<!-- SDLC HUB PR template — front-half artifact review (epic / architecture+contract / ui-design / stories). -->
+<!-- SDLC HUB PR template — Shape artifact review (epic / architecture+contract / ui-design / stories). -->
 <!-- This PR is a REVIEW VEHICLE on the product hub, not a code merge. The file gate (yad-review-gate)
      advances the step; do NOT rely on merging this PR to advance. Reviewers approve/comment here, then a
      `yad-review-gate action: sync` pulls that into the file ledger. -->

package/skills/yad-pr-template/templates/hub/gitlab/merge_request_templates/Default.md

@@ -1,4 +1,4 @@
-<!-- SDLC HUB MR template — front-half artifact review (epic / architecture+contract / ui-design / stories). -->
+<!-- SDLC HUB MR template — Shape artifact review (epic / architecture+contract / ui-design / stories). -->
 <!-- This MR is a REVIEW VEHICLE on the product hub, not a code merge. The file gate (yad-review-gate)
      advances the step; do NOT rely on merging this MR to advance. Reviewers approve/comment here, then a
      `yad-review-gate action: sync` pulls that into the file ledger. -->

package/skills/yad-reconcile/SKILL.md

@@ -52,7 +52,7 @@ Writes nothing. This is the read-only sweep a human (or CI) runs to see the pict
 
 ### Step 2 — `refresh` (advisory, never silent)
 For each flagged thread, **point the human at the fix** — open a reconcile change-epic with `yad-change`
-(`kind: change`, threaded to the affected feature) to bring the front artifacts back in step with what
+(`kind: change`, threaded to the affected feature) to bring the Shape artifacts back in step with what
 shipped, and pay any open debt (update the artifacts + add a regression test, then set the
 `reconcile-debt.json` entry `status: paid`). It never seeds the epic itself — opening a change-epic is a
 human, triaged act (`yad-change` Step 2).

package/skills/yad-report/SKILL.md

@@ -19,7 +19,7 @@ hand-craft issues.
 Issues post to a **public** repo, so the reporter is **allowlist-first**. It sends ONLY:
 - `yadflow` version, Node version, OS platform;
 - tool state as booleans (`git` present; `gh` present + authenticated);
-- the hub **platform enum** (`github` / `gitlab` / `file-only`) — never the URL, host, or roster;
+- the hub **platform enum** (`github` / `gitlab` / `local`) — never the URL, host, or roster;
 - the `YadError` **code** + **hint**, and a **path-scrubbed** error message;
 - the failing **command name and flag names only** — never flag values.
 

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.