yadflow 3.18.1 → 3.19.0-next.2

package/cli/epic-state.mjs

@@ -191,7 +191,7 @@ function validateState(state, file) {
   return state;
 }
 
-// Every build-state/<story>.json under the epic, story-sorted. Missing dir = the build half hasn't
+// Every build-state/<story>.json under the epic, story-sorted. Missing dir = Build hasn't
 // started yet, a normal state → []. The per-story files drive `yad next`'s build sub-step guidance —
 // advisory, read-only hints, NOT a source-of-truth ledger. So a corrupt file is skipped (non-throwing
 // `readJSON`), not fatal: `yad next` (and especially the all-epics roll-up) must still orient the user
@@ -259,7 +259,7 @@ const uniqueBy = (arr, key) => {
 // PURE gate predicate. Given the step, its approvals, the current content hash, the PR thread/merge
 // state and the touched domains, decide whether the gate passes — and exactly what is missing.
 // `currentHash` drops any approval bound to a different hash (revoke-on-change). `merged` /
-// `threadsResolved` come from the platform; with no bridge they default to the "advance" intent.
+// `threadsResolved` come from the platform; with a local ledger they default to the "advance" intent.
 export function gatePredicate({
   step,
   approvals,
@@ -353,8 +353,8 @@ export function gatePredicate({
 // Advance the step in state.json once the predicate passes. Mirrors yad-review-gate Step 3:
 // mark this review step done, unblock the next step, or set `ready-for-build` for the last one.
 //
-// `test-cases` is a PARALLEL, non-blocking track so the build half can start while the tester works:
-// approving `stories-review` makes the epic `ready-for-build` (the build half keys off this) AND opens
+// `test-cases` is a PARALLEL, non-blocking track so Build can start while the tester works:
+// approving `stories-review` makes the epic `ready-for-build` (Build keys off this) AND opens
 // `test-cases` for the tester; completing `test-cases-review` never pulls `currentStep` back from
 // `ready-for-build`. Both rules degrade safely for an old chain that has no test-cases steps.
 export function advanceState(state, step) {
@@ -374,9 +374,9 @@ export function advanceState(state, step) {
     state.currentStep = 'ready-for-build';
     return state;
   }
-  // Discovery is the project front-zero ("epic zero"): it has no build half, so its review terminates
+  // Discovery is the project front-zero ("epic zero"): it has no Build part, so its review terminates
   // at a `discovery-done` sentinel rather than `ready-for-build` (which would make `yad next` claim the
-  // build half can run). The roadmap it approved is the input the real feature epics read.
+  // Build can run). The roadmap it approved is the input the real feature epics read.
   if (step.id === 'discovery-review') {
     state.currentStep = 'discovery-done';
     return state;
@@ -396,7 +396,7 @@ export function advanceState(state, step) {
   return state;
 }
 
-// The front steps that may be marked N/A ("skipped") for an epic that does not need them. Only the
+// The Shape steps that may be marked N/A ("skipped") for an epic that does not need them. Only the
 // UI-design step is optional today: an epic with no user-facing surface (backend/API, data, infra)
 // can skip it. A skip carries a recorded reason and stays VISIBLE in the chain (both the author step
 // and its review gate pre-marked `done`, short-circuited by `gatePredicate`) — the auditable,
@@ -508,7 +508,7 @@ export function unskipStep(state, stepId) {
 }
 
 // Mark a step in-review (idempotent) and point currentStep at it — EXCEPT once the epic is
-// `ready-for-build`: the parallel `test-cases` track must not pull currentStep back (the build half
+// `ready-for-build`: the parallel `test-cases` track must not pull currentStep back (Build
 // runs alongside the tester, and only the test-cases review is in flight at that point).
 export function markInReview(state, step) {
   const i = state.steps.findIndex((s) => s.id === step.id);
@@ -520,7 +520,7 @@ export function markInReview(state, step) {
   return state;
 }
 
-// The front authoring step a `yad next` action maps to — the skill the user invokes for that step.
+// The Shape authoring step a `yad next` action maps to — the skill the user invokes for that step.
 // Review (review+approve) steps are driven by the `yad gate` CLI, not a skill, so they are not here.
 export const STEP_SKILL = {
   discovery: 'yad-discovery',
@@ -532,7 +532,7 @@ export const STEP_SKILL = {
   'test-cases': 'yad-test-cases',
 };
 
-// The skill that runs each BACK-half (build) step — the build-state analogue of STEP_SKILL. `spec`
+// The skill that runs each Build (build) step — the build-state analogue of STEP_SKILL. `spec`
 // and `tasks` are the two legs of the SAME yad-spec ceremony (run-loop.md), so both map to yad-spec;
 // the chain renderer collapses the consecutive duplicate. `engineer-review` is the human merge gate.
 export const BUILD_STEP_SKILL = {
@@ -543,12 +543,12 @@ export const BUILD_STEP_SKILL = {
   'engineer-review': 'yad-engineer-review',
 };
 
-// The fixed back-half order. Used to derive the "remaining chain" from the active step onward even if a
+// The fixed Build order. Used to derive the "remaining chain" from the active step onward even if a
 // repo's `steps` array is partial or out of order.
 const BUILD_STEP_ORDER = ['spec', 'tasks', 'implement', 'checks', 'engineer-review'];
 
 // Collapse consecutive identical skills (spec+tasks → one yad-spec) so the rendered chain reads
-// yad-spec → yad-implement → yad-checks → yad-engineer-review, matching the build-half mental model.
+// yad-spec → yad-implement → yad-checks → yad-engineer-review, matching the Build mental model.
 // Folds against the last KEPT element (not the raw neighbor) so a dropped null between duplicates can't
 // reintroduce one.
 function dedupeConsecutive(skills) {
@@ -621,8 +621,8 @@ export function preconditionsMet(state, stepId) {
     const ok = stepId === 'epic' || stepId === 'analysis' || stepId === 'discovery';
     return { ok, blockedBy: null, reason: ok ? 'entry step (no state seeded yet)' : `start with yad-epic — no epic state for '${stepId}'` };
   }
-  // A stub anchor (backfill-pending) or a light-promoted anchor (backfill-done) has NO runnable front
-  // step: its front chain is intentionally left `blocked`. It evolves via `yad-backfill promote` / a
+  // A stub anchor (backfill-pending) or a light-promoted anchor (backfill-done) has NO runnable Shape
+  // step: its Shape chain is intentionally left `blocked`. It evolves via `yad-backfill promote` / a
   // threaded `yad-change`, never by authoring `epic` against the anchor itself — so the precondition
   // guard must not green-light one (its blocked steps would otherwise read as "entry step ready").
   const anchorKind = backfillAnchorKind(state);
@@ -681,17 +681,17 @@ export function repairState(state) {
 // PURE next-action resolver for ONE epic's ledger — what `yad next <epic>` prints. Reads state + the
 // recorded review PRs only. kind:
 //   'new'         — no epic state yet (seed one with yad-epic)
-//   'author'      — invoke a front authoring skill (STEP_SKILL)
+//   'author'      — invoke a Shape authoring skill (STEP_SKILL)
 //   'review-open' — open the review PR/MR (`yad gate open`)
 //   'review-sync' — a review PR/MR is open; sync its state (`yad gate sync`)
-//   'build'       — front half approved (ready-for-build); the build half can run
+//   'build'       — Shape approved (ready-for-build); Build can run
 export function nextAction(ledger, { epic } = {}) {
   const state = ledger?.state;
   const epicId = epic || state?.epicId || null;
   if (!state) return { epicId, kind: 'new', skill: 'yad-epic', why: 'no epic state yet — seed it with yad-epic' };
 
-  // EP-discovery ("epic zero") is the project front-zero: a 2-step author→review chain with no build
-  // half and no parallel track. Resolve its action in isolation so the feature-epic logic below never
+  // EP-discovery ("epic zero") is the project front-zero: a 2-step author→review chain with no Build
+  // part and no parallel track. Resolve its action in isolation so the feature-epic logic below never
   // applies to it.
   if (state.kind === 'discovery') {
     if (state.currentStep === 'discovery-done') {
@@ -721,17 +721,17 @@ export function nextAction(ledger, { epic } = {}) {
   // atomically (see state-schema.md), keeping this sentinel in step with `isStubEpic` (frontmatter).
   const anchorKind = backfillAnchorKind(state);
   if (anchorKind === 'stub') {
-    // No build half until backfilled + promoted — route to yad-backfill (not to authoring the epic),
+    // No Build until backfilled + promoted — route to yad-backfill (not to authoring the epic),
     // and remind that bugs can thread off it now with yad-change.
     return { epicId, kind: 'backfill-pending', step: 'backfill-pending', status: 'stub',
       why: 'stub epic (backfill pending) — document the code with yad-backfill then `yad-backfill promote` to make it real; thread bugs now with yad-change' };
   }
   if (anchorKind === 'documented') {
-    // `yad-backfill promote` documented the feature (verified) but did NOT wake the front chain (its docs
-    // live in the backfill spec). Terminal like `discovery-done` — no build half runs directly; the
+    // `yad-backfill promote` documented the feature (verified) but did NOT wake the Shape chain (its docs
+    // live in the backfill spec). Terminal like `discovery-done` — Build never runs directly; the
     // feature evolves by threading a change/defect off it.
     return { epicId, kind: 'backfill-done', step: 'backfill-done', status: 'documented',
-      why: 'backfilled anchor (documented) — no build half runs directly; evolve it by threading a change/defect with yad-change' };
+      why: 'backfilled anchor (documented) — Build never runs directly; evolve it by threading a change/defect with yad-change' };
   }
 
   // The parallel test-cases track stays workable even once the epic is ready-for-build.
@@ -740,20 +740,20 @@ export function nextAction(ledger, { epic } = {}) {
   const parallel = tcOpen ? { step: 'test-cases', skill: STEP_SKILL['test-cases'], artifact: tc.artifact } : null;
 
   if (state.currentStep === 'ready-for-build') {
-    // Once stories enter the build half, surface each story/repo's CONCRETE next sub-step (spec →
-    // implement → checks → engineer-review) from build-state, not one static "run the build half" hint.
+    // Once stories enter Build, surface each story/repo's CONCRETE next sub-step (spec →
+    // implement → checks → engineer-review) from build-state, not one static "run Build" hint.
     const builds = buildNextActions(ledger?.buildStates || []);
     const lanes = builds.flatMap((b) => b.repos);
     const open = lanes.filter((r) => !r.shipped);
     if (builds.length) {
       let why;
-      if (!lanes.length) why = 'build half started — no repo lanes recorded yet';
-      else if (!open.length) why = 'build half — every story/repo lane is shipped';
-      else why = `build half in progress — ${open.length} story/repo lane(s) still moving`;
+      if (!lanes.length) why = 'Build started — no repo lanes recorded yet';
+      else if (!open.length) why = 'Build — every story/repo lane is shipped';
+      else why = `Build in progress — ${open.length} story/repo lane(s) still moving`;
       return { epicId, kind: 'build', step: 'ready-for-build', status: 'ready-for-build', parallel, builds, why };
     }
     return { epicId, kind: 'build', step: 'ready-for-build', status: 'ready-for-build', parallel,
-      why: 'front half approved — the build half can run' };
+      why: 'Shape approved — Build can run' };
   }
 
   const step = state.steps.find((s) => s.id === state.currentStep)
@@ -761,7 +761,7 @@ export function nextAction(ledger, { epic } = {}) {
   if (!step) {
     const builds = buildNextActions(ledger?.buildStates || []);
     return { epicId, kind: 'build', step: 'ready-for-build', parallel,
-      builds: builds.length ? builds : undefined, why: 'all front steps are done' };
+      builds: builds.length ? builds : undefined, why: 'all Shape steps are done' };
   }
 
   if (step.type === 'author') {

package/cli/errors.mjs

@@ -21,7 +21,7 @@ export const CODES = {
   'YAD-STATE-003': 'a registered repo path is missing or not a git repository',
   'YAD-STATE-004': 'an epic step cannot be skipped / un-skipped in its current state',
   'YAD-STATE-005': 'an authoring step is stranded behind its completed review gate',
-  'YAD-STATE-006': 'a back-half ledger is locked by another yad process that is writing it',
+  'YAD-STATE-006': 'a Build ledger is locked by another yad process that is writing it',
   'YAD-CFG-001': 'hub.json names an unknown platform (expected github, gitlab, or null)',
   'YAD-CFG-002': 'design.json names an unknown design tool (expected one of config.yaml design.tools, or none)',
   'YAD-CFG-003': 'testing.json names an unknown testing tool (expected one of config.yaml testing.tools, or none)',

package/cli/gate.mjs

@@ -1,13 +1,13 @@
-// `yad gate open|sync|comments|status` — the PR/MR-driven front-half review gate.
+// `yad gate open|sync|comments|status` — the PR/MR-driven Shape review gate.
 // The platform PR/MR is the review UI; this command syncs its state into the file ledger and, when
 // the gate passes (approvals satisfied + all comment threads resolved + PR merged), auto-advances the
-// step. The merge click is the human approval act, so front steps still never machine_advance.
+// step. The merge click is the human approval act, so Shape steps still never machine_advance.
 import fs from 'node:fs';
 import path from 'node:path';
 import {
   c, log, ok, info, warn, hand, fail, note, readJSONStrict, writeJSON, run, pushWithRebase,
 } from './lib.mjs';
-import { PROJECT_FILES, isBridgeHub } from './manifest.mjs';
+import { PROJECT_FILES, isVerifiedLedger } from './manifest.mjs';
 import {
   epicRoot, loadLedger, findReviewStep, artifactBase, artifactHash, gatePredicate,
   advanceState, markInReview, isEscalated, parseReviewBranch, artifactFromBase,
@@ -84,12 +84,12 @@ function warnIncompleteDiscovery(epicDir, artifact) {
 }
 
 // Fail fast on a corrupt or wrong-shape hub config: a silently-defaulted hub.json would degrade
-// every gate to file-only without anyone noticing, and a typo'd platform would read as "no bridge".
+// every gate to local without anyone noticing, and a typo'd platform would read as a local ledger.
 export function loadHub(root) {
   const hubFile = path.join(root, PROJECT_FILES.hubConfig);
   const regFile = path.join(root, PROJECT_FILES.reposRegistry);
-  // Distinguish an ABSENT hub.json (null default → fine, file-only gate) from one that exists but
-  // holds literal `null` (malformed — must not silently downgrade to file-only).
+  // Distinguish an ABSENT hub.json (null default → fine, local gate) from one that exists but
+  // holds literal `null` (malformed — must not silently downgrade to local).
   const hub = readJSONStrict(hubFile, null);
   if (hub === null && fs.existsSync(hubFile)) {
     throw err('YAD-STATE-002', `${hubFile}: contains \`null\` — expected a config object`, 'fix the file or re-run `yad setup`');
@@ -113,10 +113,9 @@ export function loadHub(root) {
 // merge advances the step). Recorded per-project in hub.json by `yad setup`.
 export const isSolo = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
 
-// Bridge mode: CI is the sole ledger writer, so `gate open`/`sync` stay hands-off. The predicate is
-// defined once in manifest.mjs (`isBridgeHub`) and shared with plan.mjs's wiring and the ledger
+// Verified mode: CI is the sole ledger writer, so `gate open`/`sync` stay hands-off. The predicate is
+// defined once in manifest.mjs (`isVerifiedLedger`) and shared with plan.mjs's wiring and the ledger
 // hook, so no two readers can disagree about who owns the ledger (#186).
-const isBridge = isBridgeHub;
 
 // requireEngagement (config `hub.review.requireEngagement`): when on, the predicate counts only
 // approvals carrying a verified engagement signal. Soft-off by default — a bare approve still counts
@@ -246,7 +245,7 @@ function recordComments(comments, { artifact, stepId, today, roster, blocking })
 
 // ---- actions ------------------------------------------------------------------------------------
 
-// The review PR/MR(s) to sync. Normally the ledger's own pointer — but under the bridge the ledger
+// The review PR/MR(s) to sync. Normally the ledger's own pointer — but with a verified ledger the record
 // records that pointer only at merge (CI is the sole writer), so a review a human needs to push
 // through by hand has NO recorded pointer at all. Fall back to the PR number the caller named
 // (`--pr`), else resolve it from the review branch on the platform. Without this, `gate sync` reported
@@ -298,18 +297,18 @@ function resolveTargets(hubPrs, { epic, artifact, state, platform, number, finde
 
 export async function gateSync(root, { epic, artifact, today, reader = readPr, finder = findPrForBranch, branchOf = prBranch, poster = postComment, number = null, local = false, dryRun = false } = {}) {
   const { hub, repos } = loadHub(root);
-  if (!hub?.platform) { warn('no hub platform configured (.sdlc/hub.json) — file-only gate, nothing to sync'); return { synced: 0 }; }
+  if (!hub?.platform) { warn('no hub platform configured (.sdlc/hub.json) — local gate, nothing to sync'); return { synced: 0 }; }
   const platform = hub.platform;
   const roster = hub.roster || [];
   const defaultReviewers = 1;
   const solo = isSolo(hub);
   const reqEng = requireEngagement(hub);
-  // Local invocation in bridge mode is ADVISORY: CI is the sole ledger writer, so a human run reads
+  // Local invocation in verified mode is ADVISORY: CI is the sole ledger writer, so a human run reads
   // the platform and prints the predicate but writes nothing. CI calls gateSync with local=false.
-  // Without the bridge (platform but no gate-sync CI) the local command stays the writer.
-  // dryRun forces the same read-only behavior regardless of bridge — used for the Path B pre-merge
+  // With a local ledger (platform but no gate-sync CI) the local command stays the writer.
+  // dryRun forces the same read-only behavior regardless of the ledger — used for the Path B pre-merge
   // evaluation, which must persist nothing (gateCi passes dryRun for a held branch event).
-  const readOnly = (local && isBridge(hub)) || dryRun;
+  const readOnly = (local && isVerifiedLedger(hub)) || dryRun;
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
   if (!ledger.state) { fail(`no epic state at ${epicDir}/.sdlc/state.json`); process.exitCode = 1; return { synced: 0 }; }
@@ -343,7 +342,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
     return { synced: 0 };
   }
   // A pointer resolved from the platform is adopted into the ledger on the WRITER path only. In
-  // bridge mode this run is advisory and writes nothing, so the human never ends up with a gate-state
+  // verified mode this run is advisory and writes nothing, so the human never ends up with a gate-state
   // file in their working tree for the ledger-guard check to reject.
   if (resolved.discovered && !readOnly) hubPrs = upsertHubPr(hubPrs, targets[0]);
 
@@ -357,7 +356,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
     const step = findReviewStep(state, pr.artifact);
     if (!step) { warn(`no review step for ${pr.artifact}`); continue; }
     // A step that already advanced is never advanced AGAIN (that would reset the next step's status /
-    // currentStep backward) — the gate is one-way per step. But it is still SYNCED: in bridge mode
+    // currentStep backward) — the gate is one-way per step. But it is still SYNCED: in verified mode
     // nothing ever moves a step back to in_review (CI is the sole ledger writer), so a re-opened
     // review — surface re-locked, fresh PR, fresh approvals, merged — used to hit a blanket skip here
     // and write nothing but the PR pointer. The step then read `done` while its approvals were all
@@ -367,7 +366,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
     const pull = reader(platform, pr.number, { cwd: root });
     // A failed platform read must not pass as a green no-op: flag the run non-zero so CI surfaces it
     // (the wired workflow's reconcile/sweep aggregates this exit) instead of silently not advancing.
-    if (!pull.ok) { warn(`${pr.artifact}: ${pull.reason} — skipping (file-only)`); process.exitCode = 1; continue; }
+    if (!pull.ok) { warn(`${pr.artifact}: ${pull.reason} — skipping (local)`); process.exitCode = 1; continue; }
 
     const curHash = artifactHash(epicDir, pr.artifact);
     warnUnlockedContract(epicDir, pr.artifact);
@@ -444,7 +443,7 @@ export async function gateSync(root, { epic, artifact, today, reader = readPr, f
   }
 
   if (readOnly) {
-    info('bridge mode: advisory view — CI owns the ledger, nothing written locally');
+    info('verified mode: advisory view — CI owns the ledger, nothing written locally');
     return { synced, advanced };
   }
   // Belt-and-braces: the upserts above already return canonical order, but a ledger this run only
@@ -782,7 +781,7 @@ export async function gateOpen(root, { epic, artifact, head, creator = createPr,
   warnUnlockedContract(epicDir, artifact);
   warnIncompleteDiscovery(epicDir, artifact);
 
-  const bridge = isBridge(hub);
+  const verified = isVerifiedLedger(hub);
   // The review branch must exist ON ORIGIN: this command opens a PR against it, it never creates or
   // pushes it, and `gh pr create --head` explicitly does NOT push either — so a branch that is only
   // local still fails inside the platform CLI, which is the opaque error this guard exists to replace.
@@ -804,21 +803,21 @@ export async function gateOpen(root, { epic, artifact, head, creator = createPr,
     if (present === null) warn(`could not verify that '${branch}' is on origin — opening the PR against it anyway`);
   }
 
-  // Outside bridge mode (file-only, OR a platform with no gate-sync CI) there is no CI to write the
-  // ledger, so the local command marks the step in_review. In bridge mode CI is the sole writer.
-  if (!bridge) {
+  // Outside verified mode (local, OR a platform with no gate-sync CI) there is no CI to write the
+  // ledger, so the local command marks the step in_review. In verified mode CI is the sole writer.
+  if (!verified) {
     ledger.state = markInReview(ledger.state, step);
     writeJSON(ledger.files.state, ledger.state);
   }
   if (!hub?.platform) {
-    warn('no hub platform — marked in_review file-only (no PR opened)');
+    warn('no hub platform — marked in_review locally (no PR opened)');
     ok(`${step.id} → in_review`);
     return;
   }
 
-  // Open the PR. In bridge mode CI records the hub-prs entry (and advances) on the default branch at
+  // Open the PR. In verified mode CI records the hub-prs entry (and advances) on the default branch at
   // merge — `yad gate open` never commits gate-state files (the ledger-guard check enforces that), and
-  // CI writes nothing pre-merge. Without the bridge, the local command records the PR itself (no CI will).
+  // CI writes nothing pre-merge. With a local ledger the local command records the PR itself (no CI will).
   const body = fillHubTemplate({ epic, artifact, step, owner: ownerOf(epicDir), domains });
   // Assignee = whoever opens the review PR (the committer); reviewers = the hub's reviewers +
   // domain-owners of the touched repos, minus the committer (the owner/author is recorded, not asked
@@ -829,18 +828,18 @@ export async function gateOpen(root, { epic, artifact, head, creator = createPr,
   const labels = isEscalated(step) ? domains.map((d) => `domain:${d}`) : [];
   info(`opening review ${hub.platform === 'gitlab' ? 'MR' : 'PR'} on branch ${branch} …`);
   const r = creator(hub.platform, { title: `review: ${artifact} (${epic})`, body, base: hub.default_branch || 'main', head: branch, reviewers, assignees, labels, cwd: root });
-  if (!r.ok) { warn(`could not open PR (${r.reason || 'unknown'})${bridge ? ' — open it manually; CI records the gate on merge' : '; step is in_review file-only'}`); return; }
+  if (!r.ok) { warn(`could not open PR (${r.reason || 'unknown'})${verified ? ' — open it manually; CI records the gate on merge' : '; step is in_review locally'}`); return; }
   // Surface routing: who was assigned as a reviewer, who was @-mentioned (GitLab field cap), and any
   // login the platform could not add (dropped) so a partial roster is visible, not silent.
   if (r.mentioned?.length) info(`@-mentioned (GitLab single-reviewer field): ${r.mentioned.join(', ')}`);
   if (r.dropped?.length) warn(`could not request as reviewer (unknown/non-collaborator login): ${r.dropped.join(', ')}`);
 
-  if (!bridge) {
+  if (!verified) {
     ledger.hubPrs = upsertHubPr(ledger.hubPrs, { step: step.id, artifact, platform: hub.platform, number: Number((r.url.match(/\/(\d+)(?:[/?#]|$)/) || [])[1]) || null, url: r.url, branch, lastSyncedAt: null });
     writeJSON(ledger.files.hubPrs, ledger.hubPrs);
   }
   ok(`opened ${r.url}`);
-  hand(bridge
+  hand(verified
     ? 'reviewers approve/comment there; CI advances the gate on the default branch when it is merged'
     : `reviewers approve/comment there; then run \`yad gate sync ${epic} ${artifact}\``);
   return { url: r.url };
@@ -850,7 +849,7 @@ export async function gateOpen(root, { epic, artifact, head, creator = createPr,
 // to generate the 60-sec trailer / swipe cards and to run the grounded chat (artifact + risk tags +
 // contract + PR + repo code-maps). The CLI never calls an LLM; the skill (yad-review-companion)
 // consumes this JSON, generates, and posts back via the platform (trailer/comments/approval).
-// Build (but don't print) the front-half grounding bundle. Shared by `review` and `walkthrough` so the
+// Assemble (but don't print) the Shape grounding bundle. Shared by `review` and `walkthrough` so the
 // pair walkthrough adds an ordered stop-list on top of the exact same grounding the companion uses.
 // Returns { error } when there is no epic state, else { bundle, epicDir, hub }.
 function reviewBundle(root, { epic, artifact } = {}) {
@@ -890,7 +889,7 @@ export async function gateReview(root, { epic, artifact } = {}) {
   return r.bundle;
 }
 
-// `yad gate walkthrough <epic> [artifact]` — the front-half pair-review grounding: the same bundle PLUS
+// `yad gate walkthrough <epic> [artifact]` — the Shape pair-review grounding: the same bundle PLUS
 // an ordered `stops[]` from the artifact's review diff (highest-risk first). The skill (yad-pair-review)
 // walks the stops and runs the two-way teaching session. Deterministic sequencing only — no LLM here.
 export async function gateWalkthrough(root, { epic, artifact, runner = run } = {}) {
@@ -920,13 +919,13 @@ export async function gateWalkthrough(root, { epic, artifact, runner = run } = {
 // delimited block, so regenerating on every artifact change never duplicates it. A platform write only.
 export async function gateTrailer(root, { epic, artifact, body, number, getBody = getPrBody, editBody = editPrBody } = {}) {
   const { hub } = loadHub(root);
-  if (!hub?.platform) { warn('no hub platform configured — the trailer posts to the PR/MR (file-only has none)'); return; }
+  if (!hub?.platform) { warn('no hub platform configured — the trailer posts to the PR/MR (local has none)'); return; }
   if (!body || !String(body).trim()) { fail('trailer body is required: `yad gate trailer <epic> <artifact> --body <text>` (the companion generates it)'); process.exitCode = 1; return; }
   const epicDir = epicRoot(root, epic);
   const ledger = loadLedger(epicDir);
   const pr = (ledger.hubPrs || []).find((p) => !artifact || p.artifact === artifact) || null;
   const n = number || pr?.number;
-  if (!n) { warn('no PR number — pass `--pr <n>` (in bridge mode the PR is recorded in the ledger only at merge)'); return; }
+  if (!n) { warn('no PR number — pass `--pr <n>` (in verified mode the PR is recorded in the ledger only at merge)'); return; }
   const cur = getBody(hub.platform, n, { cwd: root });
   if (!cur.ok) { fail(`could not read PR #${n} description: ${cur.reason || 'unknown'}`); process.exitCode = 1; return; }
   const r = editBody(hub.platform, n, upsertTrailerBlock(cur.body, String(body).trim()), { cwd: root });

package/cli/hook.mjs

@@ -1,6 +1,6 @@
 // `yad hook ledger-guard` — the harness-side half of the ledger rule (#171).
 //
-// In BRIDGE mode the gate ledger is CI-owned: `templates/checks/ledger-guard.sh` rejects any non-bot
+// In verified mode the gate ledger is CI-owned: `templates/checks/ledger-guard.sh` rejects any non-bot
 // commit that changes `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or `epics/*/reviews/*.md`.
 // That gate is the authority, but it only speaks at CI time — an agent that hand-edits `state.json`
 // learns twenty minutes later, from a failed pipeline with nothing connecting cause to effect. This
@@ -21,7 +21,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { note, readJSON, run } from './lib.mjs';
-import { PROJECT_FILES, isBridgeHub } from './manifest.mjs';
+import { PROJECT_FILES, isVerifiedLedger } from './manifest.mjs';
 
 // The CI-owned files, exactly as `templates/checks/ledger-guard.sh` lists them. NOT `contract-lock.json`
 // (artifact-side: the architect commits it with the architecture) and NOT `change.json` — both are a
@@ -148,7 +148,7 @@ export function denyMessage({ epic, rel, hubRoot }) {
   return [
     `[yad] Blocked: ${rel} is CI-owned gate state.`,
     '',
-    'This hub runs in bridge mode, where CI is the sole writer of the gate ledger. The `ledger-guard`',
+    'This hub runs in verified mode, where CI is the sole writer of the gate ledger. The `ledger-guard`',
     'check rejects any non-bot commit that changes it, so this edit cannot reach the default branch —',
     'it would fail the review PR/MR and have to be reverted.',
     '',
@@ -180,7 +180,7 @@ export function ledgerGuardDecision(paths, { env = process.env, runner = run } =
     // Non-strict on purpose: a hub.json that does not parse is a real problem, but refusing every
     // edit in the repo is not this hook's way of reporting it (`yad doctor` says so properly).
     const hub = readJSON(path.join(hubRoot, PROJECT_FILES.hubConfig), null);
-    if (!isBridgeHub(hub)) continue;
+    if (!isVerifiedLedger(hub)) continue;
     const rel = path.relative(hubRoot, abs).split(path.sep).join('/');
     const hit = protectedLedgerPath(rel);
     if (!hit) continue;

package/cli/hubcommit.mjs

@@ -1,4 +1,4 @@
-// Shared machinery for committing the machine-written back-half ledgers to the hub — used by both
+// Shared machinery for committing the machine-written Build ledgers to the hub — used by both
 // `yad checkpoint` (sync new state) and `yad tidy up` (fold finished shards). Both must commit ONLY on
 // the default branch, so their `[skip ci]` commit never enters a PR's base..HEAD range (where it would
 // strand required checks and fail verified-commits). This module is the single home of that guard.

package/cli/ledger.mjs

@@ -1,4 +1,4 @@
-// Shard-then-fold storage for the two append-only back-half ledgers (trust-log, build-log).
+// Shard-then-fold storage for the two append-only Build ledgers (trust-log, build-log).
 //
 // The problem: both ledgers were ONE file per epic, so two people driving different stories of the
 // SAME epic both appended to the same file → git merge conflict on push. The fix ("loose objects +
@@ -93,7 +93,7 @@ export const buildShardName = (e) => `${safe(e.story)}-${safe(e.task)}-${safe(e.
 // `schemaVersion` is dropped here on purpose. It describes the shape of a FILE, and a shard file has
 // one — but `fold()` copies these objects into the folded log's `ships`/`runs` array, where they stop
 // being files and become records inside one. Carrying the stamp across that boundary would bake a
-// per-record version into an append-only ledger for good: after SCHEMA_VERSION moves to 2, a
+// per-record version into an append-only ledger for good: once the shape moves — as it has, to 2 — a
 // build-log.json stamped 2 would hold entries stamped 1 from shards folded today. The folded file
 // states its own shape; its rows do not have one.
 function readShardDir(dir) {
@@ -147,7 +147,7 @@ export function readShips(epicDir) {
   return [...byKey.values()];
 }
 
-// Record a RETROACTIVE ship for a pre-tracking story — one merged & shipped before the back-half
+// Record a RETROACTIVE ship for a pre-tracking story — one merged & shipped before the Build
 // ledger existed, so it has no build-log ship and `yad checkpoint` can't carry its `status:` flip
 // (issue #142). Writes ONE minimal ship shard, marked `retroactive: true`, so `readShips` now proves
 // the story shipped and checkpoint carries the human's already-made flip. It is NOT a fabricated real

package/cli/lib.mjs

@@ -132,16 +132,30 @@ const underSdlcDir = (p) => {
 const carriesShape = (p, v) => isPlainObject(v) && underSdlcDir(p);
 
 // Always FIRST in the serialized object. A stamp that moved around between writers would change the
-// bytes without changing the meaning. An existing version is preserved, never forced back to 1, so a
-// file already on a newer shape survives being read and written by this release.
-const withShape = (p, v) =>
-  (carriesShape(p, v) ? { schemaVersion: v.schemaVersion ?? SCHEMA_VERSION, ...v } : v);
+// bytes without changing the meaning. An existing version is preserved, never forced back or forward,
+// so a file already on another shape survives being read and written by this release.
+//
+// Reading and writing do NOT default the same way, and the difference is load-bearing:
+//
+//   read  — a file with no version IS shape 1 (rule 1). Defaulting it to the engine's current shape
+//           would be the engine telling itself an old file is already current. Everything downstream
+//           believes it: `yad doctor` stops reporting drift, and a plain read-modify-write stamps the
+//           engine's shape onto content that was never migrated — after which `yad migrate` skips the
+//           file forever, because its own claim says there is nothing to do. Silent, permanent, and
+//           invisible until someone asks why a field never got renamed.
+//   write — a NEW object, one that was never read from disk and so has no version of its own, is
+//           written by this engine and therefore has this engine's shape.
+//
+// This was harmless while SCHEMA_VERSION was 1, because the two defaults were the same number. It
+// stops being harmless the moment the shape moves, which is why it is fixed in the commit that moves it.
+const readShape  = (p, v) => (carriesShape(p, v) ? { schemaVersion: v.schemaVersion ?? 1, ...v } : v);
+const writeShape = (p, v) => (carriesShape(p, v) ? { schemaVersion: v.schemaVersion ?? SCHEMA_VERSION, ...v } : v);
 
 export function readJSON(p, def = null) {
   try {
     // "Read old, write new" (rule 2): an unstamped file reads back as shape 1, so a caller never has
     // to ask whether the file it just loaded predates the stamp.
-    return withShape(p, JSON.parse(fs.readFileSync(p, 'utf8')));
+    return readShape(p, JSON.parse(fs.readFileSync(p, 'utf8')));
   } catch {
     // The caller's own default is returned untouched: it is not a file, and stamping it would invent
     // a shape for something that was never read from disk.
@@ -154,7 +168,7 @@ export function readJSON(p, def = null) {
 export function readJSONStrict(p, def = null) {
   if (!fs.existsSync(p)) return def;
   try {
-    return withShape(p, JSON.parse(fs.readFileSync(p, 'utf8')));
+    return readShape(p, JSON.parse(fs.readFileSync(p, 'utf8')));
   } catch (e) {
     throw err('YAD-STATE-001', `corrupt JSON in ${p}: ${e.message}`, 'fix the file or restore it from git — never delete a ledger blindly');
   }
@@ -163,7 +177,7 @@ export function readJSONStrict(p, def = null) {
 // then rename over the target. A killed process can never leave a truncated ledger
 // file, and a failed rename never leaves a stray .tmp for `git add -A` to pick up.
 export function writeJSON(p, obj) {
-  const data = JSON.stringify(withShape(p, obj), null, 2) + '\n';
+  const data = JSON.stringify(writeShape(p, obj), null, 2) + '\n';
   // Byte-identical content is not a write. The ledger writers are unconditional — they re-serialize
   // whether or not anything changed — so this keeps an unchanged sync from touching the file at all
   // (no mtime churn, nothing for a watcher or a `git add -A` to notice). A backstop, not the fix: the
@@ -196,8 +210,8 @@ export function run(cmd, args = [], opts = {}) {
 }
 export const has = (cmd) => run(process.platform === 'win32' ? 'where' : 'which', [cmd]).ok;
 
-// Push HEAD to origin/<target>, rebasing onto it and retrying on rejection — both the front-half gate
-// sync and the back-half checkpoint push append-only ledgers to the default branch, so a concurrent
+// Push HEAD to origin/<target>, rebasing onto it and retrying on rejection — both the Shape gate
+// sync and the Build checkpoint push append-only ledgers to the default branch, so a concurrent
 // push is a normal race, not an error. Returns { ok } after up to `attempts` tries; logs each retry.
 // A failed `pull --rebase` is aborted so we never leave a wedged rebase for the next command.
 export function pushWithRebase(cwd, target, { attempts = 3 } = {}) {