yadflow 3.18.1 → 3.19.0-next.2

package/cli/manifest.mjs

@@ -147,21 +147,26 @@ export const TESTING_PRIMARY = 'playwright';
 export const LEARNING_TOOLS = ['deeptutor'];
 export const LEARNING_PRIMARY = 'deeptutor';
 
-// The shape (schema version) every file the engine writes declares, as `"schemaVersion": 1`.
+// The shape (schema version) every file the engine writes declares, as `"schemaVersion": <n>`.
 //
 // Rule 1 of the change-safety rules (docs/roadmap-idea-1.md, Part 2): every file states its shape,
 // and a file with no version counts as 1.
 //
-// Today the stamp is written and read back, and nothing yet acts on it: raising this number would move
-// what new files say without upgrading existing ones. The two halves that make it usable are the next
-// tasks on the roadmap — `yad migrate` (E14), which moves a project from one shape to the next, and a
-// `yad doctor` report (E16) for a project whose files disagree with the engine. Do NOT raise this
-// number before both exist.
+// Raising this number is not a one-line change. Three things move together, or a project is left
+// holding files it cannot upgrade:
+//   1. a step appended to MIGRATIONS (cli/migrate.mjs) taking a file from the old shape to the new
+//      one — the chain from 1 upwards must have no gap, which cli/test-migrate.mjs asserts;
+//   2. `docs/migrations/shape-<n>.md`, which scripts/shape-guide-check.sh REFUSES to release without;
+//   3. every writer of the changed file taught to write the new shape's fields.
+// `yad doctor` reports a project whose files disagree with this number, and `yad migrate` is what
+// closes the gap.
+//
+// 2 — `.sdlc/hub.json` records who writes the ledger as `ledger: verified | local` (E104).
 //
 // Deliberately NOT the same thing as `VERSION` above. That is which release of the CLI you are
 // running and moves on every publish; this is what the files on disk look like and moves only when
 // their shape actually changes.
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
 
 // Project-level files setup produces (used by `check` to spot missing setup).
 export const PROJECT_FILES = {
@@ -174,17 +179,31 @@ export const PROJECT_FILES = {
   version: '.sdlc/cli-version.json',
 };
 
-// Bridge mode: a platform AND the gate-sync CI explicitly enabled (the canonical `bridge_enabled`,
-// or the older `bridge`). ONLY then is CI the sole ledger writer — so `gate open`/`sync` stay
-// hands-off, `hubActions` wires the hub CI, and the ledger guards (the `ledger-guard` check gate and
-// the `yad hook ledger-guard` harness hook) are live. A platform without the bridge keeps the local
-// write path, or reviews could never advance.
+// Who writes the ledger. Two values, and the switch lives in `.sdlc/hub.json`:
+//
+//   ledger: "verified"  CI only, with a platform-Verified signature. A local `gate open` is
+//                       advisory and writes nothing; `ledger-guard` rejects any non-bot commit.
+//   ledger: "local"     your machine. Works offline, no CI needed, guarded by nothing.
+//
+// `verified` is the old "bridge mode" renamed. The old name described a mechanism; this one
+// describes what you get, and it is the word the platform shows next to the commits.
 //
-// ONE definition, imported by every JS caller. Copies that drift are how #186 happened — a hub that
-// one reader called bridge and another called file-only had no permitted ledger writer at all.
-// `templates/checks/ledger-guard.sh` re-implements it in bash because the check gates are standalone
-// by design; that copy is the only one, and its header says so.
-export const isBridgeHub = (hub) => !!(hub?.platform && (hub.bridge_enabled === true || hub.bridge === true));
+// READ ORDER, and it matters (rule 2 — read old, write new):
+//   1. `ledger`, if the file carries it — shape 2 and later.
+//   2. otherwise the old booleans `bridge_enabled` (canonical) or `bridge` (older still).
+// A platform is required either way. Without one there is no Verified badge to read, so CI cannot
+// be the sole writer and the local path has to stay open — otherwise a hub has no permitted writer
+// at all and no gate can ever advance (issue #186).
+//
+// ONE definition, imported by every JS caller. `templates/checks/ledger-guard.sh` re-implements the
+// SAME order in bash because the check gates are standalone by design; that copy is the only one,
+// its header says so, and cli/test-checks.mjs runs a table of hub.json variants through both and
+// asserts they agree on every row. Three keys is three ways for two readers to drift.
+export const isVerifiedLedger = (hub) => {
+  if (!hub?.platform) return false;
+  if (typeof hub.ledger === 'string') return hub.ledger === 'verified';
+  return hub.bridge_enabled === true || hub.bridge === true;
+};
 
 // ---- `yad commit` conventions (mirror skills/sdlc/config.yaml `build`) ----
 // Conventional-commit types (config.yaml commit_subject_style).
@@ -216,14 +235,14 @@ export const epicFiles = (epicRoot) => ({
   comments: `${epicRoot}/.sdlc/comments.json`,
   hubPrs: `${epicRoot}/.sdlc/hub-prs.json`,
   contractLock: `${epicRoot}/.sdlc/contract-lock.json`,
-  // The two append-only back-half ledgers use shard-then-fold storage (cli/ledger.mjs): writers add
+  // The two append-only Build ledgers use shard-then-fold storage (cli/ledger.mjs): writers add
   // one loose shard per entry under the *Dir path (conflict-free concurrent writes); `yad tidy up`
   // folds finished shards back into the single *Log file. Readers union the folded file + loose shards.
   buildLog: `${epicRoot}/.sdlc/build-log.json`,         // folded ships (also the legacy single file)
   buildLogDir: `${epicRoot}/.sdlc/build-log`,           // one <story>-<task>-<repo>.json per ship
   trustLog: `${epicRoot}/.sdlc/trust-log.json`,         // folded runs (also the legacy single file)
   trustLogDir: `${epicRoot}/.sdlc/trust-log`,           // one <story>-<repo>-<step>-<uid>.json per run
-  buildStateDir: `${epicRoot}/.sdlc/build-state`,       // Phase 4 — per-story, per-repo back-half state
+  buildStateDir: `${epicRoot}/.sdlc/build-state`,       // Phase 4 — per-story, per-repo Build state
 
   change: `${epicRoot}/.sdlc/change.json`,             // Phase 6 — change/defect intake + triage
   reconcileDebt: `${epicRoot}/.sdlc/reconcile-debt.json`, // Phase 6 — hotfix ship-first debt
@@ -235,6 +254,8 @@ export const REPO_WIRING = {
   common: [
     { src: 'skills/yad-checks/templates/checks/spec-link.sh', dest: 'checks/spec-link.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/contract-check.sh', dest: 'checks/contract-check.sh', exec: true },
+    { src: 'skills/yad-checks/templates/checks/package-manager.sh', dest: 'checks/package-manager.sh', exec: true },
+    { src: 'skills/yad-checks/templates/checks/install-deps.sh', dest: 'checks/install-deps.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/build-test-lint.sh', dest: 'checks/build-test-lint.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/lineage-check.sh', dest: 'checks/lineage-check.sh', exec: true },
     { src: 'skills/yad-checks/templates/checks/epic-open.sh', dest: 'checks/epic-open.sh', exec: true },
@@ -275,7 +296,7 @@ export const wiringFor = (platform) => [
 ];
 
 // Hub wiring: CI installed on the PRODUCT HUB itself (dest is the project root — the hub IS the
-// root). Installed only when hub.json has a platform and the bridge is enabled. Carries the
+// root). Installed only when hub.json has a platform and the ledger is verified. Carries the
 // event-driven gate sync (approvals/change requests/the merge trigger `yad gate ci`) and the
 // verified-commits gate (no unverified commits from unverified users reach merge on the hub).
 export const HUB_WIRING = {
@@ -305,7 +326,7 @@ export const HUB_WIRING = {
 };
 
 // Harness hooks: the LOCAL half of the ledger rule, installed on the hub beside the CI gates and
-// active under the same bridge predicate (#171). Kept out of `HUB_WIRING` because a hook is not a
+// active under the same verified-ledger predicate (#171). Kept out of `HUB_WIRING` because a hook is not a
 // CI gate — it is advisory, fails open, and its adapter (below) is per-harness, not per-platform.
 export const HOOK_WIRING = [
   { src: 'skills/yad-checks/templates/hooks/ledger-guard.sh', dest: 'hooks/ledger-guard.sh', exec: true },

package/cli/migrate.mjs

@@ -18,7 +18,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 import { c, exists, fail, hand, info, log, ok, readJSON, warn, writeJSON } from './lib.mjs';
-import { BACKUP_SUFFIX, epicFiles, isBridgeHub, MANAGED_LEDGER, PROJECT_FILES, SCHEMA_VERSION, VERSION } from './manifest.mjs';
+import { BACKUP_SUFFIX, epicFiles, isVerifiedLedger, MANAGED_LEDGER, PROJECT_FILES, SCHEMA_VERSION, VERSION } from './manifest.mjs';
 import { backupPathFor } from './plan.mjs';
 import { isValidEpicId } from './epic-state.mjs';
 
@@ -37,6 +37,36 @@ export const MIGRATIONS = [
     title: 'baseline — every file states its shape',
     apply: (obj) => obj,
   },
+  {
+    from: 1,
+    to: 2,
+    title: 'hub.json — record who writes the ledger as `ledger: verified | local`',
+    // "bridge mode" is renamed to `ledger: verified`, and the switch becomes a named value instead
+    // of a boolean. Only .sdlc/hub.json carries it; every other file passes through untouched and
+    // simply moves to shape 2 with the rest of the project.
+    //
+    // Two things this deliberately does NOT do:
+    //
+    // 1. It does not DELETE `bridge_enabled`. `templates/checks/ledger-guard.sh` is committed inside
+    //    the user's own repo and is refreshed only by `yad update` — which is a separate act from
+    //    `yad migrate`. A hub running yesterday's guard against a migrated hub.json would read no
+    //    flag, conclude the ledger is local, and stop rejecting human commits to it. That is the one
+    //    guarantee verified mode exists to provide, so removing the old key here would silently
+    //    disarm the audit trail. Add before you remove (rule 3): both keys are written, the new one
+    //    wins, and the old one goes in a later major — once nothing on either side still reads it.
+    //
+    // 2. It does not copy the flag. `bridge_enabled: true` on a hub with NO platform is `local`
+    //    today, because the reader has always required a platform — there is no Verified badge to
+    //    read without one. Writing `verified` there would change what the engine does to a project
+    //    during an upgrade. So the value is computed from the reader's own answer, which means no
+    //    project's behaviour moves: whatever it was before the migration, it is after.
+    // Matched on the exact project-relative path, not the basename. `hub.json` is a name a
+    // connected repo or a nested folder could also use, and injecting `ledger` into some other
+    // file is precisely the silent rewrite that passing a context was meant to prevent.
+    apply: (obj, ctx) => (ctx?.rel === PROJECT_FILES.hubConfig
+      ? { ...obj, ledger: isVerifiedLedger(obj) ? 'verified' : 'local' }
+      : obj),
+  },
 ];
 
 // ---- reading a file's shape ---------------------------------------------------------------
@@ -58,15 +88,24 @@ const isPlainObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 const shapeOf = (v) => (isPlainObject(v) && Number.isInteger(v.schemaVersion) ? v.schemaVersion : 1);
 
 // Walk the migration list once. Returns the migrated object, the shape it ended on, and which steps ran.
-function applyMigrations(obj, migrations) {
+// `ctx` is `{ base, rel }` — the file's basename and its project-relative path. A step that only
+// concerns one kind of file (the 1 → 2 hub switch below is the first) needs to know which file it is
+// holding; every other step ignores the argument. Passing it is what keeps such a step from having
+// to guess from the object's own fields, which would mean a hub-shaped ledger got silently rewritten.
+function applyMigrations(obj, migrations, ctx) {
   let out = obj;
   let version = shapeOf(obj);
   const applied = [];
   for (const m of migrations) {
     if (version !== m.from) continue;
-    out = m.apply({ ...out });
+    const next = m.apply({ ...out }, ctx);
+    // A step that does not apply to this file returns it unchanged — but the file's SHAPE still
+    // moves, because the shape describes the whole project's file format, not this one file's
+    // fields. Only steps that actually changed something are named in the report.
+    const moved = JSON.stringify(next) !== JSON.stringify(out);
+    out = next;
     version = m.to;
-    applied.push(m.title);
+    if (moved) applied.push(m.title);
   }
   return { obj: out, version, applied };
 }
@@ -161,7 +200,7 @@ export function projectJsonFiles(root) {
 //   unchanged         already on the engine's shape, bytes identical
 //   list              a top-level JSON array: shape 1 by rule 1, and it cannot carry a key
 //   ahead             the file's shape is NEWER than this engine — never touched, always reported
-//   ci-owned          a verified (bridge) hub's ledger file: CI is its only writer
+//   ci-owned          a verified hub's ledger file: CI is its only writer
 //   unreadable        does not parse — reported, never rewritten
 //
 // Each row also carries `stamped`: whether the file literally holds a `schemaVersion` key. That is a
@@ -171,7 +210,7 @@ export function projectJsonFiles(root) {
 // comparison happens at all.
 export function planMigration(root, { migrations = MIGRATIONS } = {}) {
   const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), null);
-  const bridge = isBridgeHub(hub);
+  const verified = isVerifiedLedger(hub);
   // On a verified hub the ledger guard refuses a human commit to these, so rewriting them locally
   // would produce a change that cannot be committed. Of the four the guard names, only state.json is
   // an object; the rest are arrays and would be skipped anyway.
@@ -197,11 +236,11 @@ export function planMigration(root, { migrations = MIGRATIONS } = {}) {
       rows.push({ file: rel, from, to: from, action: 'ahead', changes: false, stamped: isStamped });
       continue;
     }
-    if (bridge && ciOwned.has(path.basename(file))) {
+    if (verified && ciOwned.has(path.basename(file))) {
       rows.push({ file: rel, from, to: from, action: 'ci-owned', changes: false, stamped: isStamped });
       continue;
     }
-    const { obj, version, applied } = applyMigrations(raw.value, migrations);
+    const { obj, version, applied } = applyMigrations(raw.value, migrations, { base: path.basename(file), rel });
     const next = serialize(stamped(obj, version));
     const current = fs.readFileSync(file, 'utf8');
     const changes = next !== current;
@@ -210,7 +249,7 @@ export function planMigration(root, { migrations = MIGRATIONS } = {}) {
     // every file by design and moves nothing, so naming it on every row would be noise reported as work.
     rows.push({ file: rel, from, to: version, action, changes, stamped: isStamped, ...(version !== from ? { steps: applied } : {}) });
   }
-  return { engine: SCHEMA_VERSION, bridge, rows };
+  return { engine: SCHEMA_VERSION, verified, rows };
 }
 
 // ---- the report ----------------------------------------------------------------------------
@@ -268,7 +307,10 @@ export async function runMigrate(root, { apply = false, json = false } = {}, { m
       // file's bytes are provably ours — a ledger has no provenance record, so there is nothing to
       // prove and the copy is unconditional.
       fs.copyFileSync(file, backupPathFor(file));
-      const { obj, version } = applyMigrations(raw.value, migrations);
+      // The SAME ctx the preview used. Passing it in one place and not the other is how a preview
+      // promises one thing and an apply writes another — the single worst failure this command can
+      // have, because the preview is the reason anyone trusts it enough to run --apply.
+      const { obj, version } = applyMigrations(raw.value, migrations, { base: path.basename(file), rel: row.file });
       writeJSON(file, stamped(obj, version));
       written.push(row.file);
     }
@@ -280,7 +322,7 @@ export async function runMigrate(root, { apply = false, json = false } = {}, { m
       ok: blocked.length === 0,
       engine: plan.engine,
       applied: apply,
-      bridge: plan.bridge,
+      verified: plan.verified,
       changed: apply ? written : pending.map((r) => r.file),
       ...(ignored ? { gitignored: BACKUP_IGNORE_GLOB } : {}),
       rows: plan.rows,
@@ -302,7 +344,7 @@ export async function runMigrate(root, { apply = false, json = false } = {}, { m
       info(`${pending.length} file(s) would change — nothing has been written`);
       hand('run `yad migrate --apply` to make the change (each file is backed up first)');
     }
-    if (plan.bridge && plan.rows.some((r) => r.action === 'ci-owned')) {
+    if (plan.verified && plan.rows.some((r) => r.action === 'ci-owned')) {
       info('this project is in verified mode: CI owns some ledger files and stamps them on its next gate sync');
     }
     for (const r of blocked) {

package/cli/next.mjs

@@ -1,9 +1,9 @@
 // `yad next` — the unified next-step driver. Read-only: it never writes state or acts. It reads the
 // file ledger and prints the ONE concrete, copy-pasteable next action (and a one-line why), so a user
 // never has to remember which of the 38 skills / gate commands comes next. "Guide, don't act" — the
-// front half still never auto-advances. Once an epic is `ready-for-build`, it reads each story's
+// Shape still never auto-advances. Once an epic is `ready-for-build`, it reads each story's
 // build-state and prints the next BUILD sub-step per repo (spec → tasks → implement → checks → engineer-review)
-// plus the remaining chain — so the build half is guided too, not just hinted at.
+// plus the remaining chain — so Build is guided too, not just hinted at.
 //
 //   yad next                  general orientation across the whole project
 //   yad next <epic>           the single next action for one epic
@@ -87,10 +87,10 @@ function actionLine(a, { solo } = {}) {
     case 'review-sync':
       return `${c.bold(a.command)}${solo ? c.dim('   (solo: no approval needed — just merge your own PR)') : ''}`;
     case 'build': {
-      // In the build half: compact the lanes to "N lane(s) in build — next: <skill> @ <story>/<repo>".
+      // In Build: compact the lanes to "N lane(s) in build — next: <skill> @ <story>/<repo>".
       if (a.builds?.length) {
         const open = buildLanes(a.builds).filter((r) => !r.shipped);
-        if (!open.length) return c.dim('build half — every lane shipped');
+        if (!open.length) return c.dim('Build — every lane shipped');
         // Headline the first lane with a resolvable next skill; if none, the half is started but unspecced.
         const first = open.find((r) => r.skill);
         if (!first) return c.dim(`${open.length} lane(s) in build — not specced yet`);
@@ -115,7 +115,7 @@ function printAction(a, { solo } = {}) {
   // kind of work this is. The discovery front-zero is not a feature epic — leave it un-prefixed.
   const noun = a.lineageKind && a.epicId !== DISCOVERY_EPIC ? `${kindNoun(a.lineageKind)} ` : '';
   log(`\n  ${c.bold(`${noun}${a.epicId || '(epic)'}`)} ${c.dim(`— ${a.why}`)}`);
-  // In the build half with live lanes, print each story/repo's next sub-step + remaining chain instead
+  // In Build with live lanes, print each story/repo's next sub-step + remaining chain instead
   // of the single static hint; otherwise the one actionable line.
   if (a.kind === 'build' && a.builds?.length) printBuildLanes(a.builds);
   else hand(actionLine(a, { solo }));

package/cli/openpr.mjs

@@ -1,6 +1,6 @@
-// `yad open-pr` — open a code-repo task PR/MR from the repo's platform template (build half).
+// `yad open-pr` — open a code-repo task PR/MR from the repo's platform template (Build).
 // Detects the platform, pushes the current branch, and creates the PR/MR with Summary / Story-task /
-// Impact & Risk prefilled. Distinct from `yad gate open`, which opens a front-half artifact-review PR
+// Impact & Risk prefilled. Distinct from `yad gate open`, which opens a Shape artifact-review PR
 // on the product hub.
 import path from 'node:path';
 import fs from 'node:fs';
@@ -26,7 +26,7 @@ function resolveRepo(root, { repo, dir }) {
 // Which SDLC stage is this PR? The hub serves two vehicles; a code repo only one. Mirrors the
 // `--head` split the hub pattern gates (pr-title.sh/pr-template.sh) already apply:
 //   code-repo    — NOT the product hub (a registry repo via --repo, or root is not a hub).
-//   hub-front    — the hub itself AND head is a review/EP-* branch (artifact-review PR).
+//   hub-shape    — the hub itself AND head is a review/EP-* branch (artifact-review PR).
 //   hub-tooling  — the hub itself AND head is anything else (a tooling/CI change to the hub).
 // `meta` (truthy when resolved from the repos registry via --repo) is a connected code repo, so it is
 // never the hub regardless of its path. Otherwise "is the hub" = repoRoot resolves to root AND root
@@ -36,7 +36,7 @@ export function detectStage(root, repoRoot, head, meta) {
   const isHub = path.resolve(repoRoot) === path.resolve(root)
     && exists(path.join(root, PROJECT_FILES.hubConfig));
   if (!isHub) return 'code-repo';
-  return /^review\/EP-[a-z0-9-]+\//.test(head || '') ? 'hub-front' : 'hub-tooling';
+  return /^review\/EP-[a-z0-9-]+\//.test(head || '') ? 'hub-shape' : 'hub-tooling';
 }
 
 // The bundled code-task template — the same file `REPO_WIRING` installs into code repos, resolved
@@ -108,11 +108,11 @@ export async function runOpenPr(root, opts = {}) {
   const branch = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoRoot }).stdout;
   const stage = detectStage(root, repoRoot, branch, meta);
 
-  // hub-front: this is a front-half artifact-review PR (review/EP-*/<artifact> head on the hub). The
+  // hub-shape: this is a Shape artifact-review PR (review/EP-*/<artifact> head on the hub). The
   // artifact-review title, body, and ledger bookkeeping all live in `yad gate open` — delegate to it
   // rather than emit the code-task shape (which the hub gate would reject). Push first (gateOpen does
   // not push), then hand off; any --title/--message is dropped (gateOpen sets `review: …`).
-  if (stage === 'hub-front') {
+  if (stage === 'hub-shape') {
     const parsed = parseReviewBranch(branch);
     if (!parsed) { fail(`could not parse review branch '${branch}' (expected review/EP-<slug>/<artifact>)`); process.exitCode = 1; return; }
     info(`pushing ${branch} …`);
@@ -121,7 +121,7 @@ export async function runOpenPr(root, opts = {}) {
     // Pass the branch we just pushed as the head so gateOpen opens the PR against it (its own
     // recompute would collapse a per-story base). gateOpen signals failure by returning no url —
     // mirror open-pr's own error contract so `ship` sees the non-zero exit and never reports success.
-    // (On a platform-less hub gateOpen marks the step in_review file-only and returns no url; open-pr's
+    // (On a platform-less hub gateOpen marks the step in_review locally and returns no url; open-pr's
     // job is to open a PR, so "no PR opened" is a non-zero outcome here, unlike `yad gate open`.)
     const res = await gateOpen(root, { epic: parsed.epic, artifact: artifactFromBase(parsed.base), head: branch });
     if (!res?.url) process.exitCode = 1;
@@ -130,7 +130,7 @@ export async function runOpenPr(root, opts = {}) {
 
   // The hub roster + its default_branch. The latter only applies when the PR targets the hub ITSELF
   // (a hub-tooling branch) — for a connected code repo the hub's trunk belongs to a different repo and
-  // must never leak in. Resolved AFTER the hub-front hand-off above, which delegates its own base to
+  // must never leak in. Resolved AFTER the hub-shape hand-off above, which delegates its own base to
   // `yad gate open`: resolving before it would spend a platform round-trip and print a base that the
   // delegated path then ignores.
   const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig), { roster: [] });

package/cli/plan.mjs

@@ -8,7 +8,7 @@ import {
   asset, exists, copyDir, copyFile, dirMatches, sameContent, readJSON, readJSONStrict, writeJSON, fileSha, warn,
 } from './lib.mjs';
 import {
-  VERSION, SKILLS, IDE_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES, isBridgeHub,
+  VERSION, SKILLS, IDE_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES, isVerifiedLedger,
   HOOK_WIRING, HOOK_SETTINGS, HOOK_TOOL_MATCHER, HOOK_COMMAND, HOOK_COMMAND_LEGACY,
   LEGACY_SKILLS, REMOVED_SKILLS, LEGACY_MARKER, LEGACY_REPO_FILES, LEGACY_HUB_FILES, MANAGED_LEDGER, BACKUP_SUFFIX,
 } from './manifest.mjs';
@@ -442,7 +442,7 @@ export function legacyRepoActions(root, repo) {
 
 export function legacyHubActions(root) {
   const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig));
-  if (!isBridgeHub(hub)) return [];
+  if (!isVerifiedLedger(hub)) return [];
   const wiring = [...HUB_WIRING.common, ...(HUB_WIRING[hub.platform] || [])];
   return legacyFileActions('hub', root, LEGACY_HUB_FILES[hub.platform], wiring);
 }
@@ -451,19 +451,38 @@ export function legacyHubActions(root) {
 export function repoActions(root, repo) {
   const repoRoot = path.resolve(root, repo.path);
   const ledger = readManagedLedger(repoRoot);
-  return wiringFor(repo.platform).map((w) =>
+  const actions = wiringFor(repo.platform).map((w) =>
     wiredFileAction(repo.name, w.dest, asset(w.src), path.join(repoRoot, w.dest), { root: repoRoot, exec: !!w.exec, ledger }),
   );
+  // A repo that already carries ANY of its wiring is a wired repo, and a template a later release
+  // ADDED to the wiring is `new` there, not `missing` — the same relabel a new first-party skill
+  // gets, for the same reason: `yad update` (--scope=changed) excludes only the literal 'missing'.
+  // Without it an upgrade rewrites the files that CALL the new template (`outdated`) while skipping
+  // the template itself, and every PR fails the gate with "file not found" until someone runs
+  // `yad check --fix`. The ledger tells the two absences apart: a file yad RECORDED writing and
+  // someone since removed stays `missing` (the team's deletion is respected, as before), while one
+  // yad never wrote is the new template. A repo with none of its wiring stays `missing` throughout:
+  // update never does one-time setup.
+  //
+  // "Wired" means yad wired it: the ledger has records, or (an install from before the ledger) a
+  // gate script under checks/ is present. A team-owned file that merely occupies a wired path — a
+  // hand-written PR template reads as `outdated` — is not evidence, or update would perform the
+  // whole one-time setup on a repo that never asked for it.
+  const wired = Object.keys(ledger).length > 0
+    || actions.some((a) => a.status !== 'missing' && a.item.startsWith('checks/'));
+  if (!wired) return actions;
+  const neverWritten = (a) => !ledger[rel(a.managed.root, a.managed.dest)];
+  return actions.map((a) => (a.status === 'missing' && neverWritten(a) ? { ...a, status: 'new' } : a));
 }
 
 // Hub wiring (gate-sync + verified-commits CI on the product hub itself). Only when the hub has a
-// platform and the bridge is explicitly enabled — a file-only hub stays file-only, with no error.
+// platform and the verified ledger is explicitly enabled — a local hub stays local, with no error.
 export function hubActions(root) {
   const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig));
-  // `bridge_enabled` is the canonical flag (the documented hub-config schema); older setup versions
-  // wrote `bridge` — `isBridgeHub` accepts an explicit true in either spelling, and is the one
+  // `ledger` is the canonical switch and `bridge_enabled` its older spelling (the documented hub-config schema); older setup versions
+  // wrote `bridge` — `isVerifiedLedger` accepts an explicit true in either spelling, and is the one
   // predicate the CLI, the wiring, and the ledger hook all read (#186). Wire nothing otherwise.
-  if (!isBridgeHub(hub)) return [];
+  if (!isVerifiedLedger(hub)) return [];
   const ledger = readManagedLedger(root);
   return [...HUB_WIRING.common, ...(HUB_WIRING[hub.platform] || [])].map((w) =>
     wiredFileAction('hub', w.dest, asset(w.src), path.join(root, w.dest), { root, exec: !!w.exec, ledger }),
@@ -602,11 +621,11 @@ function hookSettingsAction(root, ide, relDest) {
 }
 
 // Harness-hook wiring on the hub: the guard script plus, per IDE target that defines a hook protocol,
-// the entry that invokes it. Bridge-gated exactly like `hubActions` — with no bridge the ledger is
+// the entry that invokes it. Verified-only exactly like `hubActions` — with a local ledger it is
 // locally owned, the hand-edit the authoring skills describe is CORRECT, and a guard would be wrong.
 export function hookActions(root, ideTargets = ideTargetsFor(root)) {
   const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig));
-  if (!isBridgeHub(hub)) return [];
+  if (!isVerifiedLedger(hub)) return [];
   const ledger = readManagedLedger(root);
   const actions = HOOK_WIRING.map((w) =>
     wiredFileAction('hub', w.dest, asset(w.src), path.join(root, w.dest), { root, exec: !!w.exec, ledger }),

package/cli/platform.mjs

@@ -299,7 +299,7 @@ export function readPr(platform, n, opts = {}) {
 }
 
 // ---- find the PR/MR for a branch ----------------------------------------------------------------
-// The review PR/MR opened for `review/EP-<slug>/<artifact>`, by HEAD/source branch. Under the bridge
+// The review PR/MR opened for `review/EP-<slug>/<artifact>`, by HEAD/source branch. Under the verified ledger
 // the ledger records that pointer only at merge (CI is the sole writer), so without this a human has
 // no way to name the review a merged PR belongs to — `gate sync` would just report "no open review PR
 // recorded" for a PR that is sitting merged on the platform (issue #158).

package/cli/report.mjs

@@ -73,7 +73,7 @@ export function sanitizeArgv(argv = []) {
 // state but keeps just the booleans, never the raw checks (which carry names + paths).
 export function sanitizeContext(dir, { error = null, argv = process.argv.slice(2) } = {}) {
   const hub = readJSON(path.join(dir, PROJECT_FILES.hubConfig), null);
-  const platform = hub && ['github', 'gitlab'].includes(hub.platform) ? hub.platform : 'file-only';
+  const platform = hub && ['github', 'gitlab'].includes(hub.platform) ? hub.platform : 'local';
   // Derive tool auth from doctor's checks without keeping any check text.
   const toolState = (cli, p) => (has(cli) ? (platformAuthed(p) ? 'present + authenticated' : 'present, not authenticated') : 'not installed');
   const ctx = {

package/cli/review.mjs

@@ -1,6 +1,6 @@
-// `yad review trailer|context|nudge|reconcile` — the BACK-HALF Review Companion + bridge for code
-// PR/MRs (the analogue of `yad gate …` for the front half). The fun process (trailer/cards/chat/nudge)
-// makes the engineer review easy and visible; the bridge process (reconcile) maps the code PR's review
+// `yad review trailer|context|nudge|reconcile` — the Build Review Companion + bridge for code
+// PR/MRs (the analogue of `yad gate …` for Shape). The fun process (trailer/cards/chat/nudge)
+// makes the engineer review easy and visible; the bridge to code PR/MRs (reconcile) maps the code PR's review
 // state — including the engagement signal — into the build ledger (build-log.json) at merge.
 //
 // The CLI never calls an LLM: the skill (yad-review-companion / yad-engineer-review) generates the
@@ -38,7 +38,7 @@ function platformOf(root, repoRoot, meta) {
   return detectPlatform(remote) || readJSON(path.join(root, PROJECT_FILES.hubConfig), {}).platform || null;
 }
 
-// Build (but don't print) the back-half grounding bundle. Shared by `context` and `walkthrough` so the
+// Assemble (but don't print) the Build grounding bundle. Shared by `context` and `walkthrough` so the
 // pair walkthrough adds an ordered stop-list on top of the exact same grounding the companion uses.
 // Returns { error } on a bad --repo, else { bundle, repoRoot, base }.
 function contextBundle(root, { repo, dir, pr, runner = run } = {}) {
@@ -136,7 +136,7 @@ export async function reviewNudge(root, { repo, dir, pr, reader = readPr, poster
   return { nudged };
 }
 
-// `yad review reconcile --epic <id> --repo <r> --pr <n>` — the back-half BRIDGE: read the code PR's
+// `yad review reconcile --epic <id> --repo <r> --pr <n>` — the Build BRIDGE: read the code PR's
 // approvals (with the engagement signal) and stamp them onto the matching build-log.json ship record,
 // so the build ledger reflects who actually engaged. The first CLI to write build-log.json. Matches the
 // ship record by its `pr` field (url or number); if none exists yet, prints the engineer_review block

package/cli/setup.mjs

@@ -152,7 +152,7 @@ export function buildReconfiguredHub(cur, fields) {
 export function upsertRosterEntry(root, { login, name, email, roles = {}, platform } = {}) {
   if (!login) { warn('roster upsert needs a login — skipped'); return { entry: null, created: false }; }
   const hubPath = path.join(root, PROJECT_FILES.hubConfig);
-  const hub = readJSON(hubPath, null) || { platform: platform && platform !== 'none' ? platform : null, bridge_enabled: false, bridge: false, default_branch: 'main', roster: [] };
+  const hub = readJSON(hubPath, null) || { platform: platform && platform !== 'none' ? platform : null, ledger: 'local', bridge_enabled: false, bridge: false, default_branch: 'main', roster: [] };
   if (!Array.isArray(hub.roster)) hub.roster = [];
   let entry = hub.roster.find((e) => e.login === login);
   const created = !entry;
@@ -484,7 +484,7 @@ export async function runSetup(root, opts = {}) {
   S(solo ? 'Hub platform (solo — no roster)' : 'Hub platform & reviewer roster');
   guide(solo
     ? [
-      'Your hub is this repo on GitHub/GitLab (or none for a file-only gate).',
+      'Your hub is this repo on GitHub/GitLab (or none for a local gate).',
       'Solo: no roster needed — you review by merging your own PR (approval waived).',
     ]
     : [
@@ -501,7 +501,7 @@ export async function runSetup(root, opts = {}) {
     let platform = detectPlatform(remote.ok ? remote.stdout : '');
     platform = (await ask('Hub platform (github/gitlab/none)', platform || 'none')).toLowerCase();
     if (!['github', 'gitlab', 'none'].includes(platform)) {
-      warn(`unknown platform '${platform}' — using none (file-only gate)`);
+      warn(`unknown platform '${platform}' — using none (local gate)`);
       platform = 'none';
     }
     const roster = [];
@@ -528,10 +528,13 @@ export async function runSetup(root, opts = {}) {
       }
     }
     const default_branch = platform === 'none' ? 'main' : await ask('Hub default branch', 'main');
-    // `bridge_enabled` is the canonical flag (hub-config schema); keep the legacy `bridge` spelling
-    // for anything that still reads it.
+    // `ledger` is the canonical switch (shape 2): "verified" = CI writes the ledger, "local" = this
+    // machine does. The two booleans below say the same thing in the older spelling and are written
+    // ALONGSIDE it, not instead of it — add before you remove (rule 3). They are what a check gate
+    // that has not been refreshed by `yad update` yet still reads, and what a hub that is rolled back
+    // to a 3.x CLI would fall back to. They go in a later major, once nothing on either side reads them.
     const enabled = platform !== 'none';
-    // Record git_url — doctor needs it to scope the auth probe (YAD-CFG-005) and the bridge/PR flow
+    // Record git_url — doctor needs it to scope the auth probe (YAD-CFG-005) and the verified ledger/PR flow
     // needs it to open PRs. Derived from the origin remote already resolved above; null when local-only.
     const git_url = enabled ? ((remote.ok && remote.stdout.trim()) || null) : null;
     // Merge into the existing file, never clobber: roster + verified_authors are user-owned identity
@@ -540,8 +543,17 @@ export async function runSetup(root, opts = {}) {
     // Read strict so a corrupt hub aborts here (YAD-STATE-001) rather than fail-open to `{}` and rewrite
     // the file with identity stripped — the same silent-loss hole, just triggered by a parse failure.
     const cur = readJSONStrict(hubPath, {}) || {};
+    // `ledger` belongs to shape 2. On a project still on shape 1 — one that has not run
+    // `yad migrate` yet — writing it would leave a file DECLARING shape 1 while carrying a shape-2
+    // field, which is rule 1 read backwards and makes `yad doctor`'s drift report a lie about the
+    // one file this shape change is about. The old booleans below say the same thing and are what
+    // the reader falls back to when `ledger` is absent, so nothing is lost by waiting: `yad migrate`
+    // adds the key, and the setting it computes is the one these booleans just recorded.
+    const onNewShape = (cur.schemaVersion ?? 1) >= 2 || !Object.keys(cur).length;
     const next = buildReconfiguredHub(cur, {
-      platform: enabled ? platform : null, git_url, bridge_enabled: enabled, bridge: enabled,
+      platform: enabled ? platform : null, git_url,
+      ...(onNewShape ? { ledger: enabled ? 'verified' : 'local' } : {}),
+      bridge_enabled: enabled, bridge: enabled,
       default_branch, roster, solo, profile: { codebase, repo_layout, team_size },
     });
     if (!roster.length && Array.isArray(cur.roster) && cur.roster.length) {
@@ -653,12 +665,12 @@ export async function runSetup(root, opts = {}) {
   guide(repo_layout === 'monorepo'
     ? [
       'One repo holds all the code; the contract lives in the hub and stories tag this single repo.',
-      codebase === 'greenfield' ? 'Greenfield: no code yet — the repomix code-pack step is skipped.' : 'Brownfield: the repo is packed so the front phases see what already exists.',
+      codebase === 'greenfield' ? 'Greenfield: no code yet — the repomix code-pack step is skipped.' : 'Brownfield: the repo is packed so the Shape phases see what already exists.',
     ]
     : [
       'Register each code repo the feature touches; stories get tagged with the repos that implement them.',
       'Per repo: name → path (inside this project) → platform → domain owner(s).',
-      codebase === 'greenfield' ? 'Greenfield: no code yet — the repomix code-pack step is skipped.' : 'Brownfield: each repo is packed so the front phases see what already exists.',
+      codebase === 'greenfield' ? 'Greenfield: no code yet — the repomix code-pack step is skipped.' : 'Brownfield: each repo is packed so the Shape phases see what already exists.',
     ]);
   const regPath = path.join(root, PROJECT_FILES.reposRegistry);
   const registry = readJSON(regPath, { repos: [] });
@@ -735,7 +747,7 @@ export async function runSetup(root, opts = {}) {
   }
   applyActions(legacyHubActions(root), { force: true });
   // the hub, locally: the harness ledger guard, so an agent is refused the CI-owned ledger write at
-  // the moment it tries it rather than by a failed pipeline later (#171). Bridge-gated like the CI
+  // the moment it tries it rather than by a failed pipeline later (#171). Verified-only like the CI
   // above — with no bridge the ledger is locally owned and the guard would be wrong.
   const hookWiring = hookActions(root, ideTargets);
   if (hookWiring.length) {

package/cli/ship.mjs

@@ -1,4 +1,4 @@
-// `yad ship` — commit the staged atomic change AND open its task PR/MR, in one step (build half).
+// `yad ship` — commit the staged atomic change AND open its task PR/MR, in one step (Build).
 // A thin orchestration over the two existing engines: `yad commit` then `yad open-pr`. It holds no
 // commit/PR logic of its own — it reuses runCommit/runOpenPr so the conventions stay in one place.
 // The PR step runs ONLY when the commit actually lands: a failed commit, a tripped atomic guard, or a

package/cli/skip.mjs

@@ -1,4 +1,4 @@
-// `yad skip <epic> <step> --reason "<why>"` (and `--undo`) — mark an OPTIONAL front step N/A for one
+// `yad skip <epic> <step> --reason "<why>"` (and `--undo`) — mark an OPTIONAL Shape step N/A for one
 // epic. Today only `ui-design` is skippable: an epic with no user-facing surface (backend/API, data,
 // infra) does not need a UI-design artifact + review gate. The skip stays VISIBLE and auditable — the
 // step is pre-marked `done` with a recorded reason (and actor/date), short-circuited at the gate — and

package/cli/thread.mjs

@@ -24,7 +24,7 @@ export const loadBuildLog = (root, epic) => ({ epic, ships: readShips(epicRoot(r
 
 // An epic is SEALED once every authored story is `shipped` (config.yaml change.seal_on). A sealed epic
 // refuses new behaviour (epic-open.sh) — a further change must open a new threaded change-epic, which is
-// what keeps the front artifacts from going stale. An epic with no stories is NOT sealed (nothing built).
+// what keeps the Shape artifacts from going stale. An epic with no stories is NOT sealed (nothing built).
 export function sealedEpic(root, epic) {
   const dir = path.join(epicRoot(root, epic), 'stories');
   if (!exists(dir)) return false;

package/cli/tidy.mjs

@@ -1,4 +1,4 @@
-// `yad tidy up` — fold FINISHED back-half shards back into their single folded ledger, on demand.
+// `yad tidy up` — fold FINISHED Build shards back into their single folded ledger, on demand.
 //
 // The two logs are shard-then-fold (cli/ledger.mjs): writers drop one loose file per entry so
 // concurrent writers never conflict. Left alone they accumulate; `yad tidy up` is the "pack it up"
@@ -72,7 +72,7 @@ export async function runTidy(root, opts = {}) {
 
   const author = checkpointAuthor(resolveCommitterLogin(root, hub?.roster || []), git('config', 'user.name').stdout);
   const label = touched.length === 1 ? touched[0] : `${touched.length} epics`;
-  const message = `chore(hub): tidy back-half ledgers — ${label} by ${author} [skip ci]`;
+  const message = `chore(hub): tidy Build ledgers — ${label} by ${author} [skip ci]`;
 
   if (opts.dryRun) {
     log('\n' + c.dim(message) + '\n');