yadflow 3.18.1 → 3.19.0-next.2

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

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

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

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

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

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

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

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

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

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

package/skills/yad-implement/SKILL.md

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

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

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

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.