yadflow 3.18.1 → 3.19.0-next.2

package/CHANGELOG.md

@@ -1,3 +1,41 @@
+# [3.19.0-next.2](https://github.com/abdelrahmannasr/yadflow/compare/v3.19.0-next.1...v3.19.0-next.2) (2026-09-07)
+
+
+### Bug Fixes
+
+* **release:** let a pre-release publish past its own test suite ([70286ce](https://github.com/abdelrahmannasr/yadflow/commit/70286ce833b300d02d2781ac589d727481f5e7eb))
+
+# [3.19.0-next.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.18.1...v3.19.0-next.1) (2026-09-07)
+
+
+### Bug Fixes
+
+* **checks:** accept every integrity algorithm Corepack accepts in packageManager ([367947d](https://github.com/abdelrahmannasr/yadflow/commit/367947d8d9856138b531061e4b686057ee9f715f))
+* **checks:** cache the Corepack home alongside the dependency cache ([23d92bc](https://github.com/abdelrahmannasr/yadflow/commit/23d92bc8204063bbd7754bfd038585eeb6f705bb))
+* **checks:** close configurable CI review findings ([6d90018](https://github.com/abdelrahmannasr/yadflow/commit/6d900183bbee5785f4ff0d5c868a6a55ce01a9b7))
+* **checks:** fail with guidance when corepack is missing for a declared packageManager ([3a9f576](https://github.com/abdelrahmannasr/yadflow/commit/3a9f5760bcca050d87008e414b856d5b307f30b8))
+* **checks:** give the same guidance when Corepack is present but stale ([0cdf4d1](https://github.com/abdelrahmannasr/yadflow/commit/0cdf4d157946d9185bfcc286ebddcdfb5d65a6aa))
+* **checks:** keep a yarn/bun-declared repo with an npm lockfile on the npm path ([713e707](https://github.com/abdelrahmannasr/yadflow/commit/713e7074b6813de0e0fd6e12e970e8372a1309eb))
+* **checks:** keep the gate jobs' variables off the host GitLab pipeline ([7cb2c35](https://github.com/abdelrahmannasr/yadflow/commit/7cb2c35a3011dbd8bf8d048f7aa02578ac54a1db))
+* **checks:** keep the npm path when a repo carries both lockfiles ([67fbdb4](https://github.com/abdelrahmannasr/yadflow/commit/67fbdb4e2c82188b37b1d175260b48da17d5e051))
+* **checks:** make build-test-lint fail closed on a rejected package.json ([83241ee](https://github.com/abdelrahmannasr/yadflow/commit/83241eed61e4306853151e6105c0b7c8bdd06d55))
+* **checks:** pass the worker cap to jest/vitest under pnpm without npm's `--` ([55db7ee](https://github.com/abdelrahmannasr/yadflow/commit/55db7eed85173472a17e7591636d7fc830a5a5b6))
+* **checks:** read package.json the way npm does before judging it ([8021c78](https://github.com/abdelrahmannasr/yadflow/commit/8021c7850d4f7d0887923165adc585fc27da260a))
+* **checks:** require lowercase Corepack digests ([4750b8b](https://github.com/abdelrahmannasr/yadflow/commit/4750b8b597bfdd4d7d2739a0525f91a2002e41a3))
+* **checks:** restore dependency caching in the GitHub quality job, for pnpm too ([21c92f0](https://github.com/abdelrahmannasr/yadflow/commit/21c92f026aa590ec464eec7152af27ad2be9a49d))
+* **checks:** run the gate's lint/build/test through the pinned npm too ([8404da3](https://github.com/abdelrahmannasr/yadflow/commit/8404da326f8a19ae807c58808b6203572aadb9b4))
+* **checks:** support configurable CI toolchains ([30557e4](https://github.com/abdelrahmannasr/yadflow/commit/30557e419a9fec5adca06a3ecb8ca09469b2a58a))
+* **checks:** validate Corepack integrity metadata ([a6c3fd3](https://github.com/abdelrahmannasr/yadflow/commit/a6c3fd3d84a370f81477ed9b551bc29f5765296f))
+* **skills:** teach the skill layer that `ledger` is the switch ([d4622ab](https://github.com/abdelrahmannasr/yadflow/commit/d4622ab2293cfe49a36791f6cf51472b4d5701ad)), closes [#186](https://github.com/abdelrahmannasr/yadflow/issues/186)
+* **state:** read an unstamped file as shape 1, not as the engine's shape ([6d8c608](https://github.com/abdelrahmannasr/yadflow/commit/6d8c608215175fac98933ffee6f714471454a8d9))
+* **update:** install templates newly added to a wired repo on `yad update` ([8e8d92f](https://github.com/abdelrahmannasr/yadflow/commit/8e8d92f1265e2ed375bf0a53307270a25d8c33f3))
+* **update:** take only yad's own wiring as proof a repo is wired ([3c90134](https://github.com/abdelrahmannasr/yadflow/commit/3c90134985eebb3b7faa91be2c45387d54851324))
+
+
+### Features
+
+* **state:** record who writes the ledger as `ledger: verified | local` ([6623199](https://github.com/abdelrahmannasr/yadflow/commit/66231997156bb1ffa446ebb5edd28d8ebf8def91)), closes [#186](https://github.com/abdelrahmannasr/yadflow/issues/186)
+
 ## [3.18.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.18.0...v3.18.1) (2026-09-05)
 
 

package/README.md

@@ -38,11 +38,11 @@ one product hub + many code repos, solo or team.
 ## How the workflow looks
 
 <!-- Source: docs/diagrams/sdlc-overview.mmd — edit the .mmd and run `npm run diagrams` to regenerate -->
-![Yadflow SDLC overview — setup, human-gated front half, per-story build half, earned automation](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/sdlc-overview.svg)
+![Yadflow SDLC overview — setup, human-gated Shape, per-story Build, earned automation](https://raw.githubusercontent.com/abdelrahmannasr/yadflow/main/docs/diagrams/sdlc-overview.svg)
 
 **Legend:** 🟨 **artifact** (a step writes a file and stops) · 🟧 **gate** (a human review that must
-pass) · 🟦 **earns automation** (a back step that can later auto-advance once it proves itself) ·
-⬜ **locked** (the engineer review and every front state — permanently human).
+pass) · 🟦 **earns automation** (a Build step that can later auto-advance once it proves itself) ·
+⬜ **locked** (the engineer review and every Shape step — permanently human).
 
 ## Quickstart
 
@@ -56,7 +56,7 @@ Then, in your AI IDE, drive the lifecycle by invoking skills by name:
 
 ```text
 run yad-epic             # 2. author + gate the "thinking": epic → architecture → UI → stories
-run yad-spec   …         # 3. build half: spec → implement → checks → ship (per story, per repo)
+run yad-spec   …         # 3. Build: spec → implement → checks → ship (per story, per repo)
 ```
 
 Every step stops at a gate until a human approves. New here? **Walk it lesson-by-lesson in the
@@ -89,7 +89,7 @@ In one pass it produces:
   push-on-main **`yad-update-guard`** (which re-checks any direct-to-default commit — e.g. from
   `yad update --push` — with just `verified-commits` + `commit-message`), shipped as CI-agnostic bash
   under `checks/`.
-- **An agent guardrail** on a bridge hub — `hooks/ledger-guard.sh`, a harness hook that refuses an
+- **An agent guardrail** on a verified hub — `hooks/ledger-guard.sh`, a harness hook that refuses an
   agent the CI-owned gate-ledger write at the moment it tries it and names the command that owns the
   transition, instead of letting it surface as a CI failure twenty minutes later. Harness-agnostic
   (stdin payload, exit 0 allows / 2 denies) and fails open — the CI gate stays the authority.
@@ -109,21 +109,21 @@ setup → AI drafts an artifact → ⛔ gate waits → you approve → next step
 1. **`npx yadflow setup`** — the wizard installs skills, connects your repo, and wires the gates.
 2. **Run `yad-epic`** in your assistant — it drafts the epic, then **stops** and writes it to a file.
 3. **A gate waits.** Nothing advances until you review it.
-4. **You approve** — file-only, or by merging the review PR/MR.
+4. **You approve** — local, or by merging the review PR/MR.
 5. **The workflow continues** to the next step, which stops again.
 
 Every step is the same contract: *AI proposes → a human decides → the trail is recorded.*
 
 ## How it works (in five points)
 
-- **Front half = decide.** Once per epic, in the product hub: epic, architecture + a locked contract,
+- **Shape = decide.** Once per epic, in the product hub: epic, architecture + a locked contract,
   UI, stories, test cases. Always human-gated — nothing auto-advances.
-- **Build half = build.** Once per story per code repo: spec → implement → checks → ship.
-- **Every step stops at a gate.** A human moves it forward (file-only, or by merging a review PR/MR).
+- **Build = make it real.** Once per story per code repo: spec → implement → checks → ship.
+- **Every step stops at a gate.** A human moves it forward (local, or by merging a review PR/MR).
   <!-- IMAGE: docs/media/pr-gate.png — "The review gate rides a real PR/MR: approve to advance, comment to block." -->
-- **Automation is opt-in and earned.** A safe back-half step can earn auto-advance after it proves
+- **Automation is opt-in and earned.** A safe Build step can earn auto-advance after it proves
   itself — and a one-command kill switch reverts everything to manual. The engineer review and all
-  front states are never automatable.
+  Shape steps are never automatable.
 - **Everything is files.** State, approvals, the contract lock, the build log — all plain files under
   `epics/EP-<slug>/`. No database. The audit trail *is* the repo.
 

package/bin/yad.mjs

@@ -59,7 +59,7 @@ ${c.bold('Setup & maintenance')}
                        (no paths/hosts/repo names/logins/flag values). Also offered
                        automatically after an unexpected failure. YAD_NO_REPORT=1 disables.
   yad hook ledger-guard    ${c.dim('harness-invoked, not typed')} — refuse an agent's edit to the
-                       CI-owned gate ledger in bridge mode and name the command that owns
+                       CI-owned gate ledger in verified mode and name the command that owns
                        the transition. Reads a tool-call payload on stdin (or --path <p>);
                        exit 0 allows, exit 2 denies with the reason on stderr. Wired into
                        .claude/settings.json by setup / check --fix. YAD_HOOK_DISABLE=1 skips.
@@ -91,14 +91,14 @@ ${c.bold('Where am I / what next')}
                                        Stays visible & auditable (pre-done, gate short-circuited);
                                        --undo reverses it until the stories review opens
 
-${c.bold('Review gate (front half)')}
+${c.bold('Review gate (Shape)')}
   yad gate open <epic> <artifact>      Open the review PR/MR; mark the step in_review. The review
                                        branch must already be on origin (it is never created here)
   yad gate sync <epic> [artifact] [--pr <n>]
                                        Pull PR state -> ledger; advance on approved+resolved+merged.
                                        With no recorded PR, resolves it from the review branch; --pr
                                        names one (and overrides a stale recorded pointer). Advisory
-                                       in bridge mode — there, recover with 'yad gate ci' below
+                                       in verified mode — there, recover with 'yad gate ci' below
   yad gate comments <epic> [artifact]  Fetch unresolved review comments to address
   yad gate status <epic>               Show each review step + approvals
   yad gate repair <epic> [--push]      Close an author step stranded behind a passed review gate
@@ -117,11 +117,11 @@ ${c.bold('Build helpers')}
   yad commit --type <t> -m <subject>   Commit by convention (trailers, atomic guard)
   yad open-pr [--repo <name>]          Open a task PR/MR against the repo's DEFAULT branch (never a
                                        hardcoded main; --base overrides) — stage-aware on the hub: a
-                                       review/EP-* branch opens the front-half artifact-review PR
+                                       review/EP-* branch opens the Shape artifact-review PR
                                        (delegates to gate open), any other hub branch uses the
                                        code-task template
   yad ship --type <t> -m <subject>     Commit AND open the task PR/MR in one step (stage-aware)
-  yad checkpoint [--push]              Commit the machine-written back-half hub state
+  yad checkpoint [--push]              Commit the machine-written Build hub state
                                        (trust-log/build-log/build-state) — plus any story
                                        status: flip (→ in-build/shipped) backed by a build-log
                                        ship — as one audit-trail chore(hub) commit; default
@@ -131,7 +131,7 @@ ${c.bold('Build helpers')}
                                        (merged before ledger tracking), then carry its status: shipped
                                        flip in the same commit (--merge-commit <sha>, --task <t> opt.);
                                        one repo per run — re-run per --repo for a multi-repo story
-  yad tidy up [<epic>] [--push]        Fold FINISHED back-half shards (a shipped story's
+  yad tidy up [<epic>] [--push]        Fold FINISHED Build shards (a shipped story's
                                        trust-log/build-log entries) back into the single folded
                                        ledger, as one chore(hub) commit — the manual "pack it up"
                                        for the shard files; a no-op when nothing is foldable
@@ -320,9 +320,9 @@ async function main() {
       if (!epic) { log(c.red('usage: yad gate <open|sync|comments|status|repair|review|walkthrough|trailer|ci> <epic> [artifact]')); process.exitCode = 1; break; }
       // The epic id becomes a path segment under epics/ — reject anything but EP-<slug> outright.
       if (!isValidEpicId(epic)) { log(c.red(`invalid epic id: ${epic} (expected EP-<slug>, [a-z0-9-] only)`)); process.exitCode = 1; break; }
-      // In bridge mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
+      // In verified mode CI is the sole ledger writer: `open` only opens the PR, and local `sync` is
       // advisory (reads the platform, prints status, writes nothing). The artifact status flip is
-      // CI's job at merge — never wired into the local gate. File-only mode keeps local writes.
+      // CI's job at merge — never wired into the local gate. Local mode keeps local writes.
       if (action === 'open') await gateOpen(o.dir, { epic, artifact });
       else if (action === 'sync') await gateSync(o.dir, { epic, artifact, today, number: o.pr, local: true });
       else if (action === 'comments') await gateComments(o.dir, { epic, artifact, today });

package/cli/artifact-status.mjs

@@ -9,20 +9,20 @@ import { c, log, ok, info, readJSONStrict } from './lib.mjs';
 import { epicRoot, artifactBase, artifactFromBase, findReviewStep, DISCOVERY_FILES } from './epic-state.mjs';
 import { epicFiles } from './manifest.mjs';
 
-// The front-gate lifecycle this command manages. Forward-only: a status is only ever moved UP this
+// The Shape gate lifecycle this command manages. Forward-only: a status is only ever moved UP this
 // ladder, so a re-run never regresses anything.
 const RANK = { draft: 0, 'in-review': 1, approved: 2 };
 
 // Values owned by other parts of the workflow — left untouched. `locked` is the contract surface;
-// `in-build` / `shipped` are set by the build half (engineer-review) per story; `ready-for-build`,
-// `done`, `blocked` are roll-ups/states we must not overwrite from the front-gate view.
+// `in-build` / `shipped` are set by Build (engineer-review) per story; `ready-for-build`,
+// `done`, `blocked` are roll-ups/states we must not overwrite from the Shape gate view.
 const PRESERVE = new Set(['locked', 'in-build', 'shipped', 'ready-for-build', 'done', 'blocked']);
 
 // The per-epic artifact files this command considers (bases). Story files are handled separately
 // because they live under stories/ and all map to the single stories / stories-review step pair.
 const ARTIFACT_FILES = ['analysis.md', 'epic.md', 'architecture.md', 'contract.md', 'ui-design.md', 'test-cases.md'];
 
-// The desired front-gate status for an artifact base, derived purely from state.json. Returns null
+// The desired Shape gate status for an artifact base, derived purely from state.json. Returns null
 // when the chain has no steps for this base (nothing to manage) — e.g. contract has no own step.
 export function desiredStatus(state, base) {
   if (!state?.steps) return null;

package/cli/checkpoint.mjs

@@ -1,19 +1,19 @@
-// `yad checkpoint` — commit the machine-written back-half hub state (trust-log / build-log /
-// build-state) as one audit-trail commit. This is the back-half analogue of the front-half gate sync
-// (cli/gate.mjs): the SDLC back half (yad-run, yad-engineer-review) WRITES these ledgers into the
+// `yad checkpoint` — commit the machine-written Build hub state (trust-log / build-log /
+// build-state) as one audit-trail commit. This is the Build analogue of the Shape gate sync
+// (cli/gate.mjs): the SDLC's Build part (yad-run, yad-engineer-review) WRITES these ledgers into the
 // working tree but never commits them, so teammates/CI/`yad status` on other machines see stale trust
 // evidence. checkpoint lands them with a `chore(hub): ...` message.
 //
-// It also carries the back-half story `status:` flip (approved → in-build/shipped) that
+// It also carries the Build story `status:` flip (approved → in-build/shipped) that
 // yad-engineer-review writes into stories/<id>.md but no command committed — the #112 drift where
 // build-log said shipped while the story artifact still said approved. Only story files with build-log
 // ship evidence are carried (storyStatusPathspecs), AND only when their staged change is the `status:`
-// line alone (stagedStoryIsStatusOnly) — so it stays a back-half record, never a raw edit that would
+// line alone (stagedStoryIsStatusOnly) — so it stays a Build record, never a raw edit that would
 // slip prose onto the default branch under a `[skip ci]` commit that bypasses review.
 //
 // Two invariants keep it out of the gates' way:
-//   1. It stages ONLY the back-half ledgers + build-log-backed story flips by an explicit allowlist —
-//      never `git add -A`, which would sweep the CI-owned front-half ledger (state/approvals/
+//   1. It stages ONLY the Build ledgers + build-log-backed story flips by an explicit allowlist —
+//      never `git add -A`, which would sweep the CI-owned Shape ledger (state/approvals/
 //      comments/hub-prs.json, reviews/*.md) and trip the ledger-guard gate. (ledger-guard does NOT
 //      protect stories/*.md, and this commits to the default branch, never a PR range, so the carried
 //      story flip is safe.)
@@ -30,7 +30,7 @@ import { hubGit, resolveDefaultBranch, guardDefaultBranch } from './hubcommit.mj
 import { readShips, writeRetroShip } from './ledger.mjs';
 import { readFrontmatter } from './epic-state.mjs';
 
-// The machine-written back-half ledgers, relative to an epic's dir. The two append-only logs are
+// The machine-written Build ledgers, relative to an epic's dir. The two append-only logs are
 // shard-then-fold (cli/ledger.mjs): each is a folded file PLUS a shard dir of loose per-entry files —
 // both are allowlisted so a checkpoint commits new shards and any `yad tidy up` fold. `build-state` is
 // the whole dir (one JSON per story). Keep in sync with cli/manifest.mjs epicFiles.
@@ -40,9 +40,9 @@ const BACK_HALF = [
   '.sdlc/build-state',
 ];
 
-// PURE — the repo-relative pathspecs to stage: every back-half ledger that exists under any epic.
+// PURE — the repo-relative pathspecs to stage: every Build ledger that exists under any epic.
 // Explicit allowlist by design (see invariant 1 above).
-export function backHalfPathspecs(root) {
+export function buildLedgerPathspecs(root) {
   const epicsDir = path.join(root, 'epics');
   if (!fs.existsSync(epicsDir)) return [];
   const out = [];
@@ -55,17 +55,17 @@ export function backHalfPathspecs(root) {
   return out;
 }
 
-// The two back-half story statuses. `in-build` = some of a story's tasks shipped; `shipped` = all did.
-// Both are set ONLY by the build half (yad-engineer-review), never by the front-gate ladder
+// The two Build story statuses. `in-build` = some of a story's tasks shipped; `shipped` = all did.
+// Both are set ONLY by Build (yad-engineer-review), never by the Shape gate ladder
 // (cli/artifact-status.mjs PRESERVEs them). See #112.
 const BACK_HALF_STATUSES = new Set(['in-build', 'shipped']);
 
-// The repo-relative pathspecs for story files whose back-half `status:` flip we carry alongside the
+// The repo-relative pathspecs for story files whose Build `status:` flip we carry alongside the
 // ledgers (#112). The flip is authored by yad-engineer-review into the working tree but no command
 // committed it, so it drifted (build-log said shipped, stories/<id>.md still said approved) and the
 // only recovery was a raw git-to-main push. A story is a CANDIDATE iff BOTH hold:
-//   1. it has >=1 ship recorded in build-log (the build-half evidence), and
-//   2. its current frontmatter `status:` is a back-half value (in-build | shipped).
+//   1. it has >=1 ship recorded in build-log (the Build evidence), and
+//   2. its current frontmatter `status:` is a Build value (in-build | shipped).
 // A candidate is only actually carried when its staged diff is the `status:` line ALONE — runCheckpoint
 // drops any candidate whose working tree also changed prose/other frontmatter (stagedStoryIsStatusOnly),
 // so an unrelated edit can never ride into a `chore(hub) … [skip ci]` commit that bypasses review.
@@ -74,7 +74,7 @@ const BACK_HALF_STATUSES = new Set(['in-build', 'shipped']);
 //
 // A corrupt build-log in one epic must not block checkpointing every OTHER epic's ledgers, so a
 // readShips throw is caught per epic (that epic simply carries no story flip; its corrupt ledger is
-// still staged by backHalfPathspecs for a human to see).
+// still staged by buildLedgerPathspecs for a human to see).
 export function storyStatusPathspecs(root) {
   const epicsDir = path.join(root, 'epics');
   if (!fs.existsSync(epicsDir)) return [];
@@ -107,7 +107,7 @@ export function summarizeStaged(files = []) {
   const epics = new Set();
   const basenames = [];
   for (const f of files) {
-    // A back-half ledger (…/.sdlc/…) or a carried story-status flip (…/stories/<id>.md, #112).
+    // A Build ledger (…/.sdlc/…) or a carried story-status flip (…/stories/<id>.md, #112).
     const m = f.match(/^epics\/([^/]+)\/(?:\.sdlc\/(.+)|stories\/(.+\.md))$/);
     if (!m) continue;
     const [, epic] = m;
@@ -143,7 +143,7 @@ export function checkpointAuthor(login, name) {
 // Co-Authored-By footer: this is human-owned machine state, not an authored code change. `label` and
 // `author` are collapsed to one line so nothing can split the subject or forge a trailer.
 export function buildCheckpointMessage({ label, author, basenames = [] }) {
-  const subject = `chore(hub): sync back-half state — ${oneLine(label)} by ${oneLine(author)} [skip ci]`;
+  const subject = `chore(hub): sync Build state — ${oneLine(label)} by ${oneLine(author)} [skip ci]`;
   const body = basenames.length ? `Updated: ${basenames.join(', ')}` : '';
   return body ? `${subject}\n\n${body}` : subject;
 }
@@ -170,7 +170,7 @@ export function stagedStoryIsStatusOnly(git, file) {
 // normal checkpoint path carries the story's already-made `status:` flip. Returns { ok, file } — ok:false
 // (with a printed reason) aborts the commit; `file` is the shard just written, so a dry run can delete it
 // and leave no side effect. Does NOT author the story frontmatter — it only supplies the missing
-// evidence, and the human must have ALREADY flipped `status:` to a back-half value in the working tree.
+// evidence, and the human must have ALREADY flipped `status:` to a Build value in the working tree.
 //
 // ONE repo per run (#166). A story that shipped in several repos is backfilled by re-running with each
 // `--repo`; the second run finds the flip already committed, so it lands only the new ship shard.
@@ -201,7 +201,7 @@ export function recordRetroShip(root, { epic, story, repo, task, mergeCommit, to
   if (!exists(storyFile)) { fail(`no story ${story} under epics/${epic}/stories/`); return { ok: false }; }
 
   // Evidence and the flip must land TOGETHER — the #112 no-drift invariant. Refuse unless the human has
-  // already flipped the story frontmatter to a back-half status in the working tree; otherwise the ship
+  // already flipped the story frontmatter to a Build status in the working tree; otherwise the ship
   // shard would commit while the artifact still says e.g. `approved` — the very drift #112 prevents.
   const storyStatus = readFrontmatter(storyFile).status;
   if (!BACK_HALF_STATUSES.has(storyStatus)) {
@@ -290,7 +290,7 @@ export async function runCheckpoint(root, opts = {}) {
   log(c.bold('\nyad checkpoint'));
   if (!exists(path.join(root, '.git'))) { fail('not a git repo'); process.exitCode = 1; return; }
   if (!exists(path.join(root, PROJECT_FILES.hubConfig))) {
-    fail('no .sdlc/hub.json — checkpoint commits the hub back-half ledger; run it from the product hub');
+    fail('no .sdlc/hub.json — checkpoint commits the hub Build ledger; run it from the product hub');
     process.exitCode = 1;
     return;
   }
@@ -304,7 +304,7 @@ export async function runCheckpoint(root, opts = {}) {
   if (!guardDefaultBranch(branch, defaultBranch, { allowBranch: opts.allowBranch, cmd: 'yad checkpoint' })) return;
 
   // --retro-ship (#142): record a retroactive build-log ship for a PRE-TRACKING story (merged before
-  // the back-half ledger existed, so it has no ship and its `status:` flip can't be carried). Done
+  // the Build ledger existed, so it has no ship and its `status:` flip can't be carried). Done
   // AFTER the branch guard so we never leave a dangling shard on the wrong branch; the flip the human
   // already wrote is then carried by the normal storyStatusPathspecs path below — no raw git needed.
   let retroFile;
@@ -324,8 +324,8 @@ export async function runCheckpoint(root, opts = {}) {
 
   // The machine ledgers PLUS any build-log-backed story `status:` flip (#112) — one commit records
   // both, so the story artifact never drifts from build-log and no raw git-to-main push is needed.
-  const pathspecs = [...backHalfPathspecs(root), ...storyStatusPathspecs(root)];
-  if (!pathspecs.length) { rollbackRetro(); info('no back-half ledgers found — nothing to checkpoint'); return; }
+  const pathspecs = [...buildLedgerPathspecs(root), ...storyStatusPathspecs(root)];
+  if (!pathspecs.length) { rollbackRetro(); info('no Build ledgers found — nothing to checkpoint'); return; }
 
   // Stage the allowlist. `git add -- <spec>` picks up new + modified files, and deletions of tracked
   // files WITHIN a still-present spec (e.g. a removed build-state/<story>.json). A wholesale-deleted
@@ -348,7 +348,7 @@ export async function runCheckpoint(root, opts = {}) {
 
   if (git('diff', '--cached', '--quiet', '--', ...pathspecs).ok) {
     rollbackRetro();
-    info('back-half state unchanged — nothing to commit');
+    info('Build state unchanged — nothing to commit');
     return;
   }
   // The exact files staged from the allowlist — all known to git by construction, so they are the

package/cli/commit.mjs

@@ -62,7 +62,7 @@ export async function runCommit(root, opts = {}) {
   const task = opts.task || taskFromBranch(branch);
   if (!task) {
     // spec-link is a code-repo gate (REPO_WIRING.common), not a hub gate — so a missing Task trailer
-    // is expected on a hub PR (front-half artifact review or hub tooling) and only matters on a repo.
+    // is expected on a hub PR (Shape artifact review or hub tooling) and only matters on a repo.
     const onHub = exists(path.join(root, PROJECT_FILES.hubConfig));
     warn(onHub
       ? 'no Task trailer (none given and branch has no -S0N-T0N) — fine for a hub PR; required on code-repo tasks (spec-link gate)'

package/cli/companion.mjs

@@ -1,5 +1,5 @@
-// cli/companion.mjs — pure, perspective-neutral helpers for the Review Companion, shared by the front
-// half (yad gate …) and the back half (yad review …). The CLI never calls an LLM — generation happens
+// cli/companion.mjs — pure, perspective-neutral helpers for the Review Companion, shared by Shape
+// (yad gate …) and Build (yad review …). The CLI never calls an LLM — generation happens
 // in the skill/harness layer (like yad-learn/yad-docs). This module owns the platform MARKERS, the
 // engagement parsing, the trailer-block upsert, and the message text the skill and the gate share.
 //

package/cli/doctor.mjs

@@ -6,7 +6,7 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, hand, run, has, exists, readJSON, readJSONStrict } from './lib.mjs';
-import { VERSION, PROJECT_FILES, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS, HOOK_SETTINGS, HOOK_TOOL_MATCHER, isBridgeHub } from './manifest.mjs';
+import { VERSION, PROJECT_FILES, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS, HOOK_SETTINGS, HOOK_TOOL_MATCHER, isVerifiedLedger } from './manifest.mjs';
 import { mergeHookSettings, hookMatcherFires, ideTargetsFor } from './plan.mjs';
 import { planMigration } from './migrate.mjs';
 import { loadLedger, epicRoot, isValidEpicId, epicLineage, resolveThread, stateInvariants, contractSurfaceHash, artifactHash } from './epic-state.mjs';
@@ -67,7 +67,7 @@ export function projectChecks(checks, root) {
   // version stamp
   const ver = readJSON(verPath, null);
   if (!ver) check(checks, 'cli-version', 'project', 'warn', `${PROJECT_FILES.version} missing or unreadable`, 'run `yad check --fix`');
-  // The stamp is not only cosmetic: in bridge mode the wired gate-sync job resolves the yadflow it
+  // The stamp is not only cosmetic: in verified mode the wired gate-sync job resolves the yadflow it
   // RUNS from it — unless hub.json pins `gate_sync_version`, a YAD_VERSION variable overrides, or the
   // stamp is not an exact release of the current major (then the job skips it and floats). So a stale
   // stamp can mean CI is running an old gate; say so, or the warning reads as bookkeeping.
@@ -77,7 +77,7 @@ export function projectChecks(checks, root) {
   // hub.json: parse + shape
   let hub = null;
   if (!exists(hubPath)) {
-    check(checks, 'hub', 'project', 'warn', `${PROJECT_FILES.hubConfig} absent — file-only gate`, 'run `yad setup` to configure a platform + roster');
+    check(checks, 'hub', 'project', 'warn', `${PROJECT_FILES.hubConfig} absent — local gate`, 'run `yad setup` to configure a platform + roster');
   } else {
     let hubBroken = false;
     try {
@@ -92,13 +92,13 @@ export function projectChecks(checks, root) {
     // Mirror gate.mjs's roster shape check so doctor never reports "ok" on a hub the gate would reject.
     else if (hub.roster !== undefined && !Array.isArray(hub.roster)) check(checks, 'hub', 'project', 'fail', `${PROJECT_FILES.hubConfig}: \`roster\` must be an array [YAD-STATE-002]`, 'fix the file or re-run `yad setup`');
     else {
-      check(checks, 'hub', 'project', 'ok', `hub: ${hub.platform || 'file-only'}, ${(hub.roster || []).length} reviewer(s)`);
+      check(checks, 'hub', 'project', 'ok', `hub: ${hub.platform || 'local'}, ${(hub.roster || []).length} reviewer(s)`);
       if (isSolo(hub)) check(checks, 'solo', 'project', 'ok', 'mode: solo — approval waived; the PR merge + resolved threads gate the step');
       // platform CLI + auth (best-effort; auth probing is the user's own session)
       const cli = cliFor(hub.platform);
       if (cli) {
         // git_url is required whenever a platform is set — doctor needs it to scope the auth probe
-        // and the bridge/PR flow needs it to open PRs. Warn on its absence directly (not on the
+        // and the verified ledger/PR flow needs it to open PRs. Warn on its absence directly (not on the
         // resolved host), so it fires even when an origin remote can substitute: the field itself
         // is required regardless.
         if (!hostFromGitUrl(hub.git_url)) {
@@ -113,7 +113,7 @@ export function projectChecks(checks, root) {
         // rather than run the flaky unscoped form.
         const host = hostFromGitUrl(hub.git_url)
           || hostFromGitUrl(run('git', ['remote', 'get-url', 'origin'], { cwd: root }).stdout);
-        if (!has(cli)) check(checks, 'platform-cli', 'project', 'warn', `${cli} not found on PATH [YAD-ENV-002]`, `install ${cli} — the gate degrades to file-only without it`);
+        if (!has(cli)) check(checks, 'platform-cli', 'project', 'warn', `${cli} not found on PATH [YAD-ENV-002]`, `install ${cli} — the gate degrades to local without it`);
         else if (!host) check(checks, 'platform-cli', 'project', 'warn', 'auth check skipped — hub host unknown (no git_url / origin)', 'add git_url to hub.json so the auth probe can target the right host');
         else if (!run(cli, ['auth', 'status', '--hostname', host]).ok) check(checks, 'platform-cli', 'project', 'warn', `${cli} present but not authenticated for ${host} [YAD-ENV-002]`, `run \`${cli} auth login --hostname ${host}\``);
         else {
@@ -155,12 +155,12 @@ export function projectChecks(checks, root) {
     }
   }
 
-  // The harness ledger guard (#171). Only meaningful in bridge mode: there the ledger is CI-owned and
+  // The harness ledger guard (#171). Only meaningful in verified mode: there the ledger is CI-owned and
   // an agent's hand-edit is always rejected later by `ledger-guard`, so the local hook that refuses it
-  // up front should be installed. Without the bridge the ledger is locally owned and the hand-edit the
+  // up front should be installed. With a local ledger nothing guards it, and the hand-edit the
   // authoring skills describe is correct — nothing to report, so the check is silent rather than `ok`.
   const hubForHooks = readJSON(hubPath, null);
-  if (isBridgeHub(hubForHooks)) {
+  if (isVerifiedLedger(hubForHooks)) {
     const unwired = [];
     const broken = [];
     if (!exists(path.join(root, 'hooks', 'ledger-guard.sh'))) unwired.push('hooks/ledger-guard.sh');
@@ -322,7 +322,7 @@ export function ciTagsChecks(checks, root, hub, registry) {
     } catch { return false; } // absent fragment is not this check's concern
   };
   const fragments = [];
-  if (hub?.platform === 'gitlab' && (hub.bridge_enabled === true || hub.bridge === true)) {
+  if (hub?.platform === 'gitlab' && isVerifiedLedger(hub)) {
     fragments.push(
       { scope: 'hub', file: '.gitlab/ci/yad-gate-sync.yml', path: path.join(root, '.gitlab/ci/yad-gate-sync.yml') },
       { scope: 'hub', file: '.gitlab/ci/yad-verified-commits.yml', path: path.join(root, '.gitlab/ci/yad-verified-commits.yml') },