yadflow 3.18.1 → 3.19.0-next.2

package/skills/yad-discovery/SKILL.md

@@ -10,12 +10,12 @@ requirement-gathering for the whole product — under the reserved `EP-discovery
 hand off to `yad-review-gate`. The output `roadmap.md` is the menu of features; each feature is later
 taken into the normal `yad-epic` flow, which reads the roadmap for project context.
 
-This is a **front state**: human-authored with AI assist and **never auto-advances**. It runs **once
+This is a **Shape step**: human-authored with AI assist and **never auto-advances**. It runs **once
 per project** and is **optional** — a team that already knows what to build can skip it and start at
 `yad-epic`. It supports **both greenfield and brownfield**, and produces a **competitor study in both**.
 
 This skill enforces the build plan's core rules: all state lives in files; IDs are engine-assigned
-(the reserved `EP-discovery`, never a typed feature slug); front steps are locked to `human_approve`.
+(the reserved `EP-discovery`, never a typed feature slug); Shape steps are locked to `human_approve`.
 
 ## Conventions
 
@@ -63,7 +63,7 @@ roadmap extends the real system rather than re-proposing it.
 Open the discovery authoring branch `discovery/EP-discovery` per the shared procedure
 (`../yad-epic/references/state-schema.md` → "Authoring branches"): git-safe (skip with a note if
 `{project-root}` is not a git work tree), check out the branch if it exists, else create it from the
-hub's default branch. Author and commit the discovery set on it. Distinct from the bridge's
+hub's default branch. Author and commit the discovery set on it. Distinct from the verified ledger's
 `review/EP-discovery/discovery` branch.
 
 ### Step 4 — Write the discovery set
@@ -113,7 +113,7 @@ Notes:
 - Also create an empty approvals ledger `.sdlc/approvals.json` and comments ledger
   `.sdlc/comments.json`, each containing `[]`, and the `reviews/` directory.
 - Commit the seed on the `discovery/EP-discovery` branch, and cut `review/EP-discovery/discovery` from
-  it so the **first** review PR/MR carries the ledger to the default branch. In bridge mode
+  it so the **first** review PR/MR carries the ledger to the default branch. In verified mode
   `ledger-guard` exempts a new epic's ledger (creation, not mutation, #162); every later change to it
   is CI's. See `../yad-epic/references/state-schema.md`, "Authoring branches".
 
@@ -121,11 +121,11 @@ Notes:
 Report: the path to the discovery set, and that the next action is **review** via `yad-review-gate`
 (base rule: owner + 1 reviewer) on the virtual artifact `discovery/`. **Never mark discovery-review
 approved here** — only real reviewers do that through the gate. When the discovery gate passes, the
-state moves to the `discovery-done` sentinel (not `ready-for-build` — discovery has no build half); the
+state moves to the `discovery-done` sentinel (not `ready-for-build` — discovery has no Build); the
 roadmap is now the input that each `yad-epic` reads (its "Step 2c — read the roadmap"). When the hub
 has a platform, the gate opens a review PR on the hub (via `yad-hub-bridge`) and
 `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
-is recorded file-only.
+is recorded local.
 
 ## Reference
 - Discovery artifact templates + the 2-step state shape: `references/discovery-schema.md`.

package/skills/yad-discovery/references/discovery-schema.md

@@ -29,7 +29,7 @@ object and the 2-step chain.
   `yad gate open` / `yad gate sync` warn with the missing filenames. Write all six (in greenfield,
   `current-state.md` is a short clean-slate note) before handing off to the gate.
 - On approval the gate sets `currentStep: "discovery-done"` (a terminal sentinel — discovery has **no**
-  build half, so it never becomes `ready-for-build`).
+  Build, so it never becomes `ready-for-build`).
 - The discovery files (relative to the epic dir) the gate commits on the review branch and re-hashes at
   merge are: `market-research.md`, `competitor-analysis.md`, `current-state.md`, `feasibility.md`,
   `requirements.md`, `roadmap.md` (the `DISCOVERY_FILES` list).

package/skills/yad-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-docs
-description: 'Generates the per-epic interactive documentation site — a vendored React/Vite/Tailwind SPA with an animated flow canvas and role-based stakeholder doc pages — from the epic''s approved artifacts (epic, architecture, the locked contract, UI design, stories, code-context, test cases). Themes it from the design tokens, wires the docs.json base path, and drives `yad docs build/deploy` to publish to Pages (or build-only when no target). This is an OUTPUT ENRICHMENT, never a gated front state: it never mutates state.json steps, approvals, or the contract lock. Use when the user says "generate the docs site", "build the interactive docs", or "deploy the epic docs".'
+description: 'Generates the per-epic interactive documentation site — a vendored React/Vite/Tailwind SPA with an animated flow canvas and role-based stakeholder doc pages — from the epic''s approved artifacts (epic, architecture, the locked contract, UI design, stories, code-context, test cases). Themes it from the design tokens, wires the docs.json base path, and drives `yad docs build/deploy` to publish to Pages (or build-only when no target). This is an OUTPUT ENRICHMENT, never a gated Shape step: it never mutates state.json steps, approvals, or the contract lock. Use when the user says "generate the docs site", "build the interactive docs", or "deploy the epic docs".'
 ---
 
 # SDLC — Author the Interactive Docs Site (per-epic, output enrichment)
@@ -12,7 +12,7 @@ stakeholder doc pages** (each lens → a set of doc sections). The shell is gene
 generated entirely into `src/data/*.ts` and the theme into `src/index.css`.
 
 This is an **output enrichment**, exactly like `design-links.json` / `test-links.json` — **NOT a gated
-front state.** It **never** mutates `.sdlc/state.json` `steps[]`, `approvals.json`, or
+Shape step.** It **never** mutates `.sdlc/state.json` `steps[]`, `approvals.json`, or
 `contract-lock.json`, and it never adds a `state.json` step. It reads the *approved* shape and renders
 it; it never decides approval. When a docs target is connected (`yad-connect-docs` → `.sdlc/docs.json`)
 the site is built + deployed; when none is, it is npm-built to a local `dist/` (build-only).
@@ -152,7 +152,7 @@ the default-theme degrade), the **deploy URL** or "build-only", and the **stalen
 - The connected docs target + base-path resolution: `../yad-connect-docs/SKILL.md`.
 - The design tokens this themes from: `../yad-connect-design/SKILL.md`.
 - The code-context the data enriches: `../yad-connect-repos/SKILL.md`.
-- The authoring pattern (front-state author that writes link artifacts without gating):
+- The authoring pattern (Shape step author that writes link artifacts without gating):
   `../yad-ui/SKILL.md`.
 - State schema + the "Authoring branches" procedure: `../yad-epic/references/state-schema.md`.
 - The project overview site + the staleness/CI reconciler: `../yad-docs-overview/SKILL.md`,

package/skills/yad-docs-overview/SKILL.md

@@ -7,7 +7,7 @@ description: 'Generates the project-level SDLC-overview interactive site — the
 
 **Goal:** Render the **whole yadflow pipeline** — every stage from setup → ship — as an interactive site,
 reusing the same shell as the per-epic docs (`skills/yad-docs/templates/app/`). Where `yad-docs`
-animates one epic's flows, this animates the **workflow itself**: the front gates, the build half, the
+animates one epic's flows, this animates the **workflow itself**: the Shape gates, Build, the
 automation dial, the setup connectors. The hand-maintained overview report stays the **main
 documentation at the Pages root** (`<base>/`, served from `public/report.html` and `public/index.html`);
 this interactive SPA mounts under `<base>/app/` and is reached from the report — the report links
@@ -39,7 +39,7 @@ It only reads the pipeline definition and writes a project-level site. When a do
 There is no epic; the inputs are the workflow's own config + manifest (full mapping in
 `references/pipeline-model.md`):
 
-- `skills/sdlc/config.yaml` — the front/back steps, the **two dials** (assistance, automation),
+- `skills/sdlc/config.yaml` — the Shape/Build steps, the **two dials** (assistance, automation),
   defaults, the review-gate rule, the build conventions, the automation/trust thresholds.
 - `skills/sdlc/module-help.csv` — the **canonical skill manifest**: each skill's `phase`,
   `preceded-by` / `followed-by`, and `outputs`. This is the ordering source of truth.
@@ -56,7 +56,7 @@ git work tree). Generate and commit on it.
 Map the pipeline onto the same data structures `yad-docs` uses (concrete mapping in
 `references/pipeline-model.md`):
 
-- **Flow paths** = the **phases** — `Setup`, `Front-zero` (discovery), `Front half`, `Build half`, `Automation`, `Change management` (feature threads).
+- **Flow paths** = the **phases** — `Setup`, `Front-zero` (discovery), `Shape`, `Build`, `Automation`, `Change management` (feature threads).
 - **Flow steps** = the **skills/gates in order** (from `module-help.csv` `preceded-by`/`followed-by`),
   each step's `messages` = the skill's `outputs`, and `sideEffects` = the `.sdlc/` files it writes.
 - **System components** = the **durable state objects** — the product hub, each `.sdlc/*.json`

package/skills/yad-docs-overview/references/pipeline-model.md

@@ -10,7 +10,7 @@ ordering source of truth is `skills/sdlc/module-help.csv` (`phase`, `preceded-by
 
 | Shell primitive | Overview meaning |
 |-----------------|------------------|
-| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front-zero (discovery), Front half, Build half, Automation, Change management (feature threads). |
+| `FlowPath` (`paths.ts`) | a **phase**: Setup, Front-zero (discovery), Shape, Build, Automation, Change management (feature threads). |
 | `FlowStep` (within a path) | a **skill or gate** in order; `messages` = its `outputs`; `sideEffects` = the `.sdlc/` files it writes; `status`/`bookingStatus` annotate gated vs. enrichment vs. earned. |
 | `SystemComponent` (`components.ts`) | a **durable state object** (the hub, each `.sdlc/*.json`, code repos, the design/testing/learning tools, the platform). |
 | `RoleConfig` (`roles.ts`) | a **lens** → its relevant sections + paths. |
@@ -35,7 +35,7 @@ and never gates.
 ### Path: Front-zero (`phase: 0-front`)
 The OPTIONAL once-per-project discovery phase, modelled as the reserved "epic zero" `EP-discovery`.
 Greenfield AND brownfield; a 2-step author→review chain whose review binds to the whole artifact set
-and terminates at `discovery-done` (no build half).
+and terminates at `discovery-done` (no Build).
 
 | Step (skill) | Gate | Outputs / sideEffects |
 |--------------|------|------------------------|
@@ -44,7 +44,13 @@ and terminates at `discovery-done` (no build half).
 `roadmap.md` is the menu of features each `yad-epic` reads (Step 2c) — reference-only, never
 auto-seeds epics.
 
-### Path: Front half (`phase: 1-front`)
+<!-- `1-front` and `3-build` are DATA — the `phase` column in skills/sdlc/module-help.csv, which
+     the overview build reads. The Shape/Build/Run rename deliberately left them alone: change-safety
+     rule 3 says a release may add but never rename, so a stored value moves in a major with a
+     migration, not in a wording sweep. The display names below are the new vocabulary; the ids are
+     the old one, on purpose. -->
+
+### Path: Shape (`phase: 1-front`)
 The gated authoring chain + the reusable review gate (10 steps, or 12 with the optional analysis).
 
 | Step (skill) | Gate | Outputs / sideEffects |
@@ -59,7 +65,7 @@ The gated authoring chain + the reusable review gate (10 steps, or 12 with the o
 | `yad-review-companion` | the fun/visible review layer (trailer/cards/chat + engagement) | `approvals.json` `engagement`, platform trailer/cards |
 | `yad-hub-bridge` | the platform PR/MR bridge | `hub-prs.json` |
 
-### Path: Build half (`phase: 3-build`)
+### Path: Build (`phase: 3-build`)
 Per-story, per-repo: `spec → tasks → implement → checks → engineer-review`, plus the commit/PR helpers.
 
 | Step (skill) | Outputs / sideEffects |
@@ -78,7 +84,7 @@ node classes from the diagram.
 
 | Step (skill) | Outputs / sideEffects |
 |--------------|------------------------|
-| `yad-run` | drives the back-half loop; `build-state/<story>.json`, `trust-log.json`, kill switch |
+| `yad-run` | drives the Build loop; `build-state/<story>.json`, `trust-log.json`, kill switch |
 | `yad-learn` | tutoring; `learning-records.json` (LOCAL-ONLY, gitignored) |
 | `yad-status` | read-only view (no writes) |
 | `yad-docs` / `yad-docs-overview` / `yad-docs-sync` | the docs sites + their `docs-build.json` manifests |
@@ -86,9 +92,9 @@ node classes from the diagram.
 ### Path: Change management — feature threads (`phase: 6-change`)
 The post-lock evolution layer. Once an epic is **sealed** (all stories shipped), behaviour can no longer
 be mutated in place — a change request becomes a **new epic threaded to its parent** (genesis → change →
-defect), inheriting unchanged front artifacts **by reference** and re-authoring only what changes, so
+defect), inheriting unchanged Shape artifacts **by reference** and re-authoring only what changes, so
 locked artifacts are never mutated and never go stale, only superseded. Three CI gates enforce the thread
-(`lineage-check`, `epic-open`, `reconcile-debt`). This path never gates the front chain; `yad-change` is
+(`lineage-check`, `epic-open`, `reconcile-debt`). This path never gates the Shape chain; `yad-change` is
 the intake, then it hands off to the normal authoring skills + the review gate.
 
 | Step (skill) | Outputs / sideEffects |
@@ -99,7 +105,7 @@ the intake, then it hands off to the normal authoring skills + the review gate.
 | `yad-reconcile` | advisory drift / orphan / debt sweep (read-only; mirrors `yad-docs-sync`) |
 
 CLI: `yad thread [<epic>]` prints a thread + its resolved current truth + open debt; `yad reconcile`
-runs the sweep. The three thread gates ride in the build-half `yad-checks` set above.
+runs the sweep. The three thread gates ride in the Build `yad-checks` set above.
 
 ## System components = the durable state objects
 
@@ -121,11 +127,11 @@ The eight yadflow lenses, each to its relevant phase sections + paths:
 
 | Lens | Relevant phases / sections |
 |------|----------------------------|
-| analyst | Setup intent, project discovery (front-zero), analysis step, front-half discovery |
-| pm | project discovery (market/feasibility/roadmap), epic, stories; the front gates |
+| analyst | Setup intent, project discovery (front-zero), analysis step, Shape discovery |
+| pm | project discovery (market/feasibility/roadmap), epic, stories; the Shape gates |
 | architect | architecture + the locked contract; escalation |
 | ux | UI design, design tool connection, the design system |
-| dev | build half: spec → implement, the per-repo loop |
+| dev | Build: spec → implement, the per-repo loop |
 | tester | test-cases (parallel track), the testing tool, checks |
 | reviewer | the review gate, comments, the hub bridge |
 | engineer | engineer review + ship, the merge gate, automation dial/trust |

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

@@ -1,14 +1,14 @@
 ---
 name: yad-engineer-review
-description: 'Build-half Step E of the gated SDLC — AI review, engineer review, then merge. Wire an advisory AI first-pass (CodeRabbit) on the PR/MR; record the human engineer review with the same human_approve discipline as the front gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments — the Step D routing); and on merge, record the ship in the epic build-log and update the story state so the epic → story → task → PR chain is traceable. Never auto-advances — the human owns the merge. Use when the user says "record the engineer review", "merge this task", or "wire the AI review". (To commit + open the PR/MR, use yad-ship.)'
+description: 'Build Step E of the gated SDLC — AI review, engineer review, then merge. Wire an advisory AI first-pass (CodeRabbit) on the PR/MR; record the human engineer review with the same human_approve discipline as the Shape gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments — the Step D routing); and on merge, record the ship in the epic build-log and update the story state so the epic → story → task → PR chain is traceable. Never auto-advances — the human owns the merge. Use when the user says "record the engineer review", "merge this task", or "wire the AI review". (To commit + open the PR/MR, use yad-ship.)'
 ---
 
-# SDLC — Engineer Review & Merge (build-half Step E)
+# SDLC — Engineer Review & Merge (Build Step E)
 
 **Goal:** Take a task PR/MR that has passed the **check gates** (Step C) through two sets of eyes and
 out to production: an **AI first-pass** (advisory) and a **human engineer review** (the authority),
-then **ship** — merge, record the ship, and update the story state. This is the last build-half step
-(build plan §E). It is a **human gate**, the same `human_approve` discipline as the front states:
+then **ship** — merge, record the ship, and update the story state. This is the last Build step
+(build plan §E). It is a **human gate**, the same `human_approve` discipline as the Shape steps:
 **nothing auto-advances**; the engineer owns the merge.
 
 ## Conventions
@@ -66,7 +66,7 @@ approve); `yad review reconcile --epic <id> --repo <r> --pr <n>` stamps it onto
 platform (mutating the ship's shard where it lives, or its folded entry if already tidied). Soft by default (both count; a bare approve draws `yad review nudge`); only gates when
 `hub.review.requireEngagement: true`. The signal is gameable by design and sits **beside** the CI gates,
 never above them.
-Recording an approval does **not** ship — shipping is a separate, explicit step. Front-half discipline:
+Recording an approval does **not** ship — shipping is a separate, explicit step. Shape discipline:
 the gate talks only through files; refuse to treat AI review as a human approval.
 
 ### Step 3 — `ship` (merge + record + update state)
@@ -94,18 +94,18 @@ engineer-review rule is satisfied (Step 2). Then:
   a rejected one is `rejected`. This is the evidence that later earns a step its `machine_advance`
   (it never weakens the merge gate — the engineer still owns the merge).
 - **Commit the machine-written ledgers.** Run `yad checkpoint --push` from `{project-root}` to commit
-  the back-half ledgers just written (the `build-log/` shard, and the `trust-log/` shard /
+  the Build ledgers just written (the `build-log/` shard, and the `trust-log/` shard /
   `build-state/<story>.json` if the story ran through `yad-run`) as one `chore(hub): …` audit-trail
   commit — default branch only, staging the shard dirs (`yad tidy up` folds finished shards later),
-  never a front-half gate file. It is the back-half analogue of the front-half `yad gate` sync. The
+  never a Shape gate file. It is the Build analogue of the Shape `yad gate` sync. The
   same commit also **carries the story `status:` flip** you just wrote (`approved → in-build/shipped`,
   #112) — because that story now has a build-log ship, checkpoint stages `stories/<story>.md` alongside
   the ledgers, so the artifact never drifts from build-log and you never fall back to a raw git-to-main
   push. (The code-repo `tasks.md` is committed in its own repo as usual.)
 
 ### Step 4 — Stop
-Report what shipped and the story's state. Do not advance anything else; the front-half `state.json`
-stays as it was (`ready-for-build`). The build half is recorded in `build-log.json` + the story status.
+Report what shipped and the story's state. Do not advance anything else; the Shape `state.json`
+stays as it was (`ready-for-build`). Build is recorded in `build-log.json` + the story status.
 
 ## Hard rules (build plan §E, Cross-cutting)
 

package/skills/yad-engineer-review/references/ship-and-record.md

@@ -1,6 +1,6 @@
 # Ship — the build ledger and the story state
 
-Step E (`yad-engineer-review`) closes the build half: AI review (advisory) → engineer review (the human gate) →
+Step E (`yad-engineer-review`) closes Build: AI review (advisory) → engineer review (the human gate) →
 ship. Shipping records the merge and updates the story state so the whole chain is traceable.
 
 ## Two sets of eyes
@@ -59,16 +59,16 @@ without the `{ epic, ships }` wrapper):
 }
 ```
 
-This is the back-half analogue of the front half's `approvals.json` — files only, no hidden state, so a
+This is the Build analogue of Shape's `approvals.json` — files only, no hidden state, so a
 future service can drive ship by writing the same records. Like the trust log and build-state, it is a
-machine-written ledger committed by **`yad checkpoint`** (the back-half analogue of `yad gate` sync),
+machine-written ledger committed by **`yad checkpoint`** (the Build analogue of `yad gate` sync),
 not by hand: after recording the ship, `yad checkpoint --push` lands the new `build-log/` shard as a
-`chore(hub): …` audit-trail commit on the default branch (allowlist-scoped to the back-half ledgers,
-never a front-half gate file); `yad tidy up` folds finished shards into `build-log.json` later.
+`chore(hub): …` audit-trail commit on the default branch (allowlist-scoped to the Build ledgers,
+never a Shape gate file); `yad tidy up` folds finished shards into `build-log.json` later.
 
 ### Retroactive ship — a pre-tracking story (#142)
 
-A story that was merged and shipped **before** the back-half ledger existed has no build-log ship, so
+A story that was merged and shipped **before** the Build ledger existed has no build-log ship, so
 `yad checkpoint` can't carry its `status: shipped` flip (the flip is only carried when a ship backs it,
 #112) — leaving a raw `git push origin main` as the only way to land it, against the never-raw-git
 convention. To reconcile it through yad, record a **retroactive** ship, then checkpoint carries the flip
@@ -83,7 +83,7 @@ It writes ONE minimal ship shard marked `retroactive: true` (`task` defaults to
 the normal checkpoint so the story's already-made `status:` flip rides along in the **same** commit. It
 refuses when the story already has a ship **in that repo** (then it isn't pre-tracking there — use the
 normal flow). It does **not** author the story frontmatter — and to keep evidence and the flip atomic (the no-drift
-invariant), it **refuses** unless you have already set a back-half `status:` (`in-build` or `shipped`) in
+invariant), it **refuses** unless you have already set a Build `status:` (`in-build` or `shipped`) in
 `stories/<story>.md`, so a ship shard is never committed while the artifact still says `approved`.
 
 **Where the record lands — it is a shard, not an append to `build-log.json`.** Like every other ship, a
@@ -129,7 +129,7 @@ a bare approve draws a friendly `yad review nudge`); it only gates ship when
 `hub.review.requireEngagement: true`. `yad review reconcile --epic <id> --repo <r> --pr <n>` reads the
 code PR's approvals (with the engagement signal) and stamps them onto the matching ship record — writing
 back into the ship's shard where it lives (or its folded entry if the story was already tidied) — the
-back-half **bridge**, the analogue of `yad gate sync`. The signal is gameable by design ("visible, not
+Build **bridge**, the analogue of `yad gate sync`. The signal is gameable by design ("visible, not
 impossible"): it makes engineer-review quality visible, it does not prove a human read the diff. It sits
 **beside** the CI gates (build/test/lint/contract/verified-commits) — never above them; CI still
 decides machine safety, the merge is still the human act.

package/skills/yad-epic/SKILL.md

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

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

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