yadflow 4.0.0-next.3 → 4.0.0

package/cli/migrate.mjs

@@ -17,16 +17,17 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { c, exists, fail, hand, info, isPlainObject, log, ok, readJSON, warn, writeJSON, writeProductConfig, emitJSON, collectWarning } from './lib.mjs';
+import { ask, c, exists, fail, hand, info, isPlainObject, log, ok, readJSON, warn, writeFileAtomic, writeJSON, writeProductConfig, emitJSON, collectWarning } from './lib.mjs';
+import { err } from './errors.mjs';
 import {
   ADVANCE_FROM_AUTOMATION, BACKUP_SUFFIX, DRIVER_FROM_ASSISTANCE, epicFiles, isVerifiedLedger,
-  MANAGED_LEDGER, MIRRORED_FILES, PROJECT_FILES, preferring, productConfigPath, SCHEMA_VERSION,
+  MANAGED_LEDGER, MIRRORED_FILES, PRODUCT_RENAME_GUIDE_URL, PROJECT_FILES, preferring, productConfigPath, SCHEMA_VERSION,
   VERSION,
 } from './manifest.mjs';
 import { backupPathFor } from './plan.mjs';
 import { refreshIndexAfterWrite } from './product-index.mjs';
 import {
-  artifactHash, canonicalApprovals, canonicalComments, canonicalHubPrs, DISCOVERY_EPIC, epicIds, epicRel,
+  artifactHash, canonicalApprovals, canonicalComments, canonicalProductPrs, DISCOVERY_EPIC, epicIds, epicRel, productDriftPairs,
   epicRoot, FOUNDATION_DIR, FOUNDATION_EPIC, isGateStep, isPassed, stampProfile, stampStepStates, stampWorkItemType, writeState,
 } from './epic-state.mjs';
 
@@ -77,6 +78,7 @@ export const MIGRATIONS = [
       ? { ...obj, ledger: isVerifiedLedger(obj) ? 'verified' : 'local' }
       : obj),
   },
+  // hub-keep:start shape-3-step
   {
     from: 2,
     to: 3,
@@ -117,6 +119,7 @@ export const MIGRATIONS = [
       };
     },
   },
+  // hub-keep:end
   {
     from: 3,
     to: 4,
@@ -494,8 +497,8 @@ export function applyProductMove(root, move, { migrations = MIGRATIONS, copy = f
     };
     relabel(f.approvals, canonicalApprovals);
     relabel(f.comments, canonicalComments);
-    relabel(f.productPrs, canonicalHubPrs);
-    relabel(f.hubPrs, canonicalHubPrs);
+    relabel(f.productPrs, canonicalProductPrs);
+    relabel(f.productPrsLegacy, canonicalProductPrs);
     for (const rel of move.reshape || []) {
       const file = path.join(root, rel);
       const { obj, version } = applyMigrations(JSON.parse(fs.readFileSync(file, 'utf8')), migrations, { base: path.basename(file), rel: path.join(...rel.split('/')), root });
@@ -689,7 +692,7 @@ export function projectJsonFiles(root) {
   for (const epic of epicIds(root)) {
     const epicDir = epicRoot(root, epic);
     const f = epicFiles(epicDir);
-    files.push(f.state, f.approvals, f.comments, preferring(f.productPrs, f.hubPrs), f.contractLock,
+    files.push(f.state, f.approvals, f.comments, preferring(f.productPrs, f.productPrsLegacy), f.contractLock,
       f.buildLog, f.trustLog, f.change, f.reconcileDebt);
     files.push(...shardFiles(f.buildLogDir), ...shardFiles(f.trustLogDir), ...shardFiles(f.buildStateDir));
     // The docs-build cache (cli/docs.mjs) lives in the same directory and is written by the engine,
@@ -717,8 +720,8 @@ export function projectJsonFiles(root) {
 // ANY reason (a hand re-indent, say), and `ci-owned`/`ahead`/`list` short-circuit before the byte
 // comparison happens at all.
 export function planMigration(root, { migrations = MIGRATIONS } = {}) {
-  const hub = readJSON(productConfigPath(root), null);
-  const verified = isVerifiedLedger(hub);
+  const productConfig = readJSON(productConfigPath(root), null);
+  const verified = isVerifiedLedger(productConfig);
   // On a verified Product 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.
@@ -733,8 +736,10 @@ export function planMigration(root, { migrations = MIGRATIONS } = {}) {
 
   const rows = [];
   for (const file of projectJsonFiles(root)) {
-    const rel = path.relative(root, file);
-    if (moving && rel.split(path.sep).join('/').startsWith(moving)) continue;
+    // Forward slashes on every OS: the mirrored-pair, state-file and drift-repair checks all compare
+    // project-relative paths spelled that way, and on Windows `path.relative` says `.sdlc\product.json`.
+    const rel = path.relative(root, file).split(path.sep).join('/');
+    if (moving && rel.startsWith(moving)) continue;
     const raw = readRaw(file);
     if (!raw.ok) {
       rows.push({ file: rel, from: null, to: null, action: 'unreadable', changes: false, stamped: false, detail: raw.error });
@@ -857,6 +862,147 @@ function printProductMove(p, { apply }) {
   log(`    ${c.dim(`a full copy stays at ${p.backup}/`)}`);
 }
 
+// ---- two names that say different things (E122) -----------------------------------------------
+//
+// `.sdlc/product.json` + `.sdlc/hub.json`, and each epic's `product-prs.json` + `hub-prs.json`, are one
+// file under two names until v5. When they disagree every other command refuses (YAD-STATE-008), and
+// this is the command that ends it. It runs whatever shape the project is on: the drift is not a shape
+// step, it is a repair — like the product-level move above, work outside the per-file rows.
+//
+// Only a person knows which copy they meant, so nothing is chosen for them: the preview shows the
+// difference, and `--apply` asks — or, with no terminal or under `--json` (where a command never asks,
+// E1), takes `--keep product` / `--keep hub` and refuses without it. The copy kept is written over the
+// other one byte for byte, after the other one is backed up beside itself as `<file>.yad-orig`.
+export const KEEP_CHOICES = ['product', 'hub'];
+
+// What differs, in words a person can check against the files: the top-level keys of an object, the
+// positions of an array. Never the values — they can be long, and the files are right there.
+export function describeDrift(aPath, bPath) {
+  let a; let b;
+  try { a = JSON.parse(fs.readFileSync(aPath, 'utf8')); } catch { return [`${path.basename(aPath)} does not parse`]; }
+  try { b = JSON.parse(fs.readFileSync(bPath, 'utf8')); } catch { return [`${path.basename(bPath)} does not parse`]; }
+  const same = (x, y) => JSON.stringify(x) === JSON.stringify(y);
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const keys = [...new Set([...Object.keys(a), ...Object.keys(b)])].sort();
+    const out = keys.filter((k) => !same(a[k], b[k])).map((k) => (!(k in a) ? `\`${k}\` only in ${path.basename(bPath)}` : !(k in b) ? `\`${k}\` only in ${path.basename(aPath)}` : `\`${k}\` differs`));
+    // Same keys and values in another order, or only the spacing differs: still two different files.
+    return out.length ? out : ['the same settings, written differently (spacing or key order)'];
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    const n = Math.max(a.length, b.length);
+    const at = [];
+    for (let i = 0; i < n; i++) if (!same(a[i], b[i])) at.push(i + 1);
+    const count = a.length === b.length ? '' : `${path.basename(aPath)} has ${a.length} entries, ${path.basename(bPath)} ${b.length}; `;
+    return at.length ? [`${count}entries ${at.join(', ')} differ`] : ['the same entries, written differently (spacing or key order)'];
+  }
+  return ['the two files hold different kinds of value'];
+}
+
+const bytesOrNull = (abs) => { try { return fs.readFileSync(abs); } catch { return null; } };
+
+// Every drifted pair under `root`, project-relative, with what differs.
+export function driftedPairs(root) {
+  return productDriftPairs(root).map(({ canonical, legacy }) => {
+    const pair = { canonical, legacy, differences: describeDrift(path.join(root, canonical), path.join(root, legacy)) };
+    // What each name held when the difference was shown — not part of the report (not enumerable), but
+    // `checkDrift` refuses a pair that has changed since, because it is not the pair the person chose for.
+    Object.defineProperty(pair, 'seen', { value: [canonical, legacy].map((rel) => bytesOrNull(path.join(root, rel))) });
+    return pair;
+  });
+}
+
+// Settle each pair on the copy `keep` names, in two steps: `checkDrift` first, which writes nothing and
+// refuses if any pair cannot be settled, so a refusal leaves every pair — and `.gitignore` — as it was;
+// then `settleDrift`, which writes.
+//   - a name that is a symbolic link is refused. The kept copy's bytes are copied into a committed file,
+//     and a link would copy whatever file it points at on this machine (E115 refuses links in the same
+//     spirit). The file itself is checked, not the folders above it: a linked `.sdlc/` holds both names,
+//     so nothing from outside it can reach a committed file through it;
+//   - a kept copy that does not parse is refused: settling on it would leave two broken files, and every
+//     command refusing them for another reason;
+//   - a name that is not a plain readable file (a folder, a file yad cannot read) is refused;
+//   - a name that has gone, or changed, since the difference was found (while the question waited) is
+//     refused too: the pair is not the one the person chose for.
+function settlePlan(root, pairs, keep) {
+  return pairs.map(({ canonical, legacy }) => {
+    const [from, to] = keep === 'product' ? [canonical, legacy] : [legacy, canonical];
+    return { from, to, src: path.join(root, from), dst: path.join(root, to) };
+  });
+}
+
+function checkDrift(root, pairs, keep) {
+  const plan = settlePlan(root, pairs, keep);
+  for (const [i, { from, to, src }] of plan.entries()) {
+    for (const rel of [from, to]) {
+      let st;
+      try { st = fs.lstatSync(path.join(root, rel)); } catch (e) {
+        if (e.code !== 'ENOENT') throw e;
+        throw err('YAD-STATE-008', `${rel} is gone since the difference was found — nothing was written`, 'run `yad migrate` again to see the pair as it is now');
+      }
+      if (st.isSymbolicLink()) {
+        throw err('YAD-STATE-008', `${rel} is a symbolic link — yad does not settle a pair through one, and nothing was written`, 'replace it with the file itself (or delete it and keep the other name), then run `yad migrate --apply` again');
+      }
+      if (!st.isFile()) throw err('YAD-STATE-008', `${rel} is not a file — nothing was written`, `make ${rel} a file again (restore it from git), then run \`yad migrate --apply\` again`);
+    }
+    const seen = pairs[i].seen;
+    const now = [pairs[i].canonical, pairs[i].legacy].map((rel) => bytesOrNull(path.join(root, rel)));
+    if (now.some((b) => b === null)) throw err('YAD-STATE-008', `${from} or ${to} cannot be read — nothing was written`, 'check the two files can be read, then run `yad migrate --apply` again');
+    if (seen && seen.some((b, j) => !b || !b.equals(now[j]))) {
+      throw err('YAD-STATE-008', `${pairs[i].canonical} or ${pairs[i].legacy} changed since the difference was shown — nothing was written`, 'run `yad migrate` again to see the pair as it is now');
+    }
+    try { JSON.parse(fs.readFileSync(src, 'utf8')); } catch {
+      throw err('YAD-STATE-001', `${from} does not parse, so it cannot be the copy kept — nothing was written`, `fix it or restore it from git, or keep the other copy (--keep ${keep === 'product' ? 'hub' : 'product'})`);
+    }
+  }
+}
+
+// Returns the paths written (the losing names). Only after `checkDrift` has passed.
+function settleDrift(root, pairs, keep) {
+  const written = [];
+  for (const { to, src, dst } of settlePlan(root, pairs, keep)) {
+    writeFileAtomic(backupPathFor(dst), fs.readFileSync(dst));
+    // The kept copy's exact bytes — the gates compare with `cmp -s` — written through a temporary file
+    // and a rename, so a crash never leaves a half file.
+    writeFileAtomic(dst, fs.readFileSync(src));
+    written.push(to);
+  }
+  return written;
+}
+
+// Which copy wins: the flag, else the person at the terminal. `choose` stands in for the prompt in tests.
+async function chooseKeep(pairs, { keep, json, choose }) {
+  if (keep) return keep;
+  const flagHint = 'pass `--keep product` to keep .sdlc/product.json (and each product-prs.json), or `--keep hub` to keep the old names — `yad migrate` shows the difference first';
+  if (json) throw err('YAD-CLI-001', 'a --json run cannot ask which copy to keep', flagHint);
+  if (!choose && (!process.stdin.isTTY || process.env.SDLC_NONINTERACTIVE)) throw err('YAD-STATE-008', 'there is no terminal to ask which copy to keep', flagHint);
+  const question = `${pairs.length === 1 ? 'Two copies disagree' : `${pairs.length} pairs disagree`} — keep which: product (the new name) or hub (the old name)? Enter to stop`;
+  const answer = String(await (choose ? choose(question) : ask(question, ''))).trim().toLowerCase();
+  if (!answer) throw err('YAD-STATE-008', 'stopped — nothing was written', flagHint);
+  if (!KEEP_CHOICES.includes(answer)) throw err('YAD-STATE-008', `"${answer}" is not product or hub — nothing was written`, flagHint);
+  return answer;
+}
+
+function printDrift(pairs) {
+  log('');
+  log(c.bold('  two names that disagree'));
+  for (const p of pairs) {
+    log(`  ${p.canonical}  ≠  ${p.legacy}`);
+    for (const d of p.differences) log(`    ${c.dim(d)}`);
+  }
+}
+
+// What this command does NOT rename, said once, so nobody takes a finished migrate for a finished
+// rename. Printed only while the old settings name is still on disk.
+function printNotRenamedHere(root) {
+  if (!exists(path.join(root, PROJECT_FILES.productConfigLegacy))) return;
+  log('');
+  log(c.bold('  hub → Product'));
+  log(`  ${PROJECT_FILES.productConfig} is the name read; ${PROJECT_FILES.productConfigLegacy} is still written beside it for check gates an older yadflow installed, and v5 deletes it`);
+  log(`  ${c.dim('not done here:')}`);
+  log(`    ${c.dim('the names installed into your repos (the yad-hub-checks workflow → yad-product-checks, the yad-hub-bridge skill → yad-product-bridge, the GitLab yad-hub-* jobs → yad-product-*) — `yad update` renames those')}`);
+  log(`    ${c.dim('your own CI settings and scripts that name .sdlc/hub.json, hub-prs.json or SDLC_HUB_CONFIG — they work until v5; change them to .sdlc/product.json, product-prs.json and SDLC_PRODUCT_CONFIG by hand')}`);
+}
+
 // ---- the command ---------------------------------------------------------------------------
 // `.sdlc/cli-version.json` is migrated as an ordinary row, like every other project file — it is in
 // PROJECT_FILES, so it is previewed, backed up and stamped along with the rest. Nothing here writes it
@@ -864,7 +1010,10 @@ function printProductMove(p, { apply }) {
 // which means no backup, no row in the report, and a preview that under-reports what an apply does. It
 // would also be free to overwrite the one file the same run had just declared corrupt or newer than
 // this engine. What shape a file is in is recorded in that file, which is the whole point of rule 1.
-export async function runMigrate(root, { apply = false, json = false } = {}, { migrations = MIGRATIONS, copy = fs.cpSync } = {}) {
+export async function runMigrate(root, { apply = false, json = false, keep = null } = {}, { migrations = MIGRATIONS, copy = fs.cpSync, choose = null } = {}) {
+  if (keep != null && !KEEP_CHOICES.includes(keep)) {
+    throw err('YAD-STATE-008', `--keep takes product or hub, not "${keep}"`, '`--keep product` keeps .sdlc/product.json (and each product-prs.json); `--keep hub` keeps the old names');
+  }
   if (!exists(path.join(root, PROJECT_FILES.version)) && !exists(productConfigPath(root))) {
     const message = 'no yad project here (.sdlc/ not initialised)';
     if (json) { emitJSON({ ok: false, error: message }); }
@@ -873,20 +1022,40 @@ export async function runMigrate(root, { apply = false, json = false } = {}, { m
     return { ok: false };
   }
 
+  // E122: settled first, so the plan below reads the copy that was kept.
+  const drift = driftedPairs(root);
+  let kept = null;
+  let ignored = false;
+  const settledFiles = [];
+  if (drift.length && apply) {
+    if (!json) printDrift(drift);
+    kept = await chooseKeep(drift, { keep, json, choose });
+    checkDrift(root, drift, kept);
+    // Before the backup is made, as below — and after every check, so a refusal changes nothing.
+    ignored = ensureBackupsIgnored(root);
+    settledFiles.push(...settleDrift(root, drift, kept));
+  }
+
   const plan = planMigration(root, { migrations });
+  // On a verified Product an epic's PR ledger is CI's to write, and `ledger-guard` refuses a person's
+  // commit of it. The repair is still made — the pair has to agree before any command runs — and the
+  // way to commit it is named: a drift there came from a hand edit that got past the guard already.
+  const ciOwnedSettled = plan.verified ? settledFiles.filter((f) => !f.startsWith('.sdlc/')) : [];
+  if (ciOwnedSettled.length) {
+    warn(`${ciOwnedSettled.join(', ')} ${ciOwnedSettled.length === 1 ? 'is' : 'are'} CI-owned on this verified Product: the ledger-guard check refuses a hand commit of ${ciOwnedSettled.length === 1 ? 'it' : 'them'} — commit the repair with \`yad commit --manual --reason "<why>" --type chore -m "<subject>"\`, which records the reason the check quotes`);
+  }
   const move = plan.product?.action === 'move' ? plan.product : null;
   const pending = plan.rows.filter((r) => r.changes);
   const blocked = plan.rows.filter((r) => r.action === 'ahead' || r.action === 'unreadable');
   // An unreadable product-level ledger blocks like an unreadable file. The other refusals do not: the
   // project stays on the old spelling, which this release reads correctly, so nothing is broken.
   const productBlocked = plan.product?.action === 'unreadable';
-  const written = [];
+  const written = [...settledFiles];
 
-  let ignored = false;
   if (apply) {
     // Before the first backup exists, not after — otherwise a gate advance racing this run could stage
     // one. A no-op when the line is already there.
-    if (pending.length || move) ignored = ensureBackupsIgnored(root);
+    if (pending.length || move) ignored = ensureBackupsIgnored(root) || ignored;
     if (move) {
       // Reported through `fail`, never as a stack trace, and before any per-file write: a move that did
       // not happen leaves the project exactly as it was, so the rest of this run must not half-proceed.
@@ -906,7 +1075,9 @@ export async function runMigrate(root, { apply = false, json = false } = {}, { m
       // Back up first, always. Unlike the wiring copies in plan.mjs — which skip the backup when the
       // 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));
+      // A file the drift repair above already backed up keeps THAT backup: it is the copy the person did
+      // not keep, and its only record. Its bytes now are the kept copy's, backed up under the other name.
+      if (!settledFiles.includes(row.file)) fs.copyFileSync(file, backupPathFor(file));
       // A mirrored row writes its partner too, so the partner needs a backup of its OWN pre-migration
       // bytes — taken here, before either write. Backing up only the row's file leaves the other name
       // rewritten with no way back, and on the NEXT shape bump its `.yad-orig` would be overwritten
@@ -914,7 +1085,7 @@ export async function runMigrate(root, { apply = false, json = false } = {}, { m
       const partnerRel = isMirroredPath(row.file) ? mirrorPartner(row.file) : null;
       if (partnerRel) {
         const partnerFile = path.join(root, partnerRel);
-        if (exists(partnerFile)) fs.copyFileSync(partnerFile, backupPathFor(partnerFile));
+        if (exists(partnerFile) && !settledFiles.includes(partnerRel)) fs.copyFileSync(partnerFile, backupPathFor(partnerFile));
       }
       // 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
@@ -947,7 +1118,11 @@ export async function runMigrate(root, { apply = false, json = false } = {}, { m
       // The preview names each row's mirror partner too (`creates` / `rewrites`), exactly as the text
       // report does: the apply writes the product config under BOTH names, so leaving the partner out
       // made this list shorter than the apply's `written` — a preview that under-reports.
+      // A drifted pair names BOTH its names on a preview: which one the apply rewrites depends on the
+      // copy the person keeps, and a preview may over-report, never under-report. Its `rows` are planned
+      // from the copy read now (the new name); an apply that keeps the old copy plans from that one.
       changed: apply ? written : [...new Set([
+        ...drift.flatMap((d) => [d.canonical, d.legacy]),
         ...(move ? productMoveFiles(move) : []),
         ...pending.flatMap((r) => [r.file, ...(r.creates ?? []), ...(r.rewrites ?? [])]),
       ])],
@@ -955,15 +1130,28 @@ export async function runMigrate(root, { apply = false, json = false } = {}, { m
       rows: plan.rows,
       // The product-level move (shape 8), or null when the project has no old-spelling product level.
       product: plan.product,
+      // E122: the pairs whose two names disagreed, and which copy was kept (null on a preview).
+      drift,
+      kept,
     });
   } else {
     log(c.bold(`\nyad migrate  ${c.dim(`shape ${plan.engine}`)}`));
     log(c.dim(`target: ${root}\n`));
     printRows(plan.rows);
     if (plan.product) printProductMove(plan.product, { apply });
+    if (drift.length) {
+      if (apply) ok(`kept the ${kept === 'product' ? 'new' : 'old'} name's copy of ${drift.length === 1 ? 'the pair' : `${drift.length} pairs`} — the other is backed up beside itself as <file>${BACKUP_SUFFIX}`);
+      else printDrift(drift);
+    }
+    printNotRenamedHere(root);
     log('');
+    if (drift.length && !apply) {
+      info('every other yad command refuses until one copy is chosen');
+      hand('run `yad migrate --apply` to choose which copy to keep (or `--apply --keep product` / `--keep hub`)');
+    }
     if (!pending.length && !move) {
-      ok(`nothing to do — this project is already on shape ${plan.engine}`);
+      if (!drift.length) ok(`nothing to do — this project is already on shape ${plan.engine}`);
+      else if (apply) ok(`nothing else to do — this project is already on shape ${plan.engine}`);
     } else if (apply) {
       if (move) ok(`the product level moved to ${move.to}/ as ${FOUNDATION_EPIC} — the original is kept whole at ${move.backup}/`);
       ok(`${written.length} file(s) updated — a copy of each is beside it as <file>${BACKUP_SUFFIX}`);
@@ -983,6 +1171,9 @@ export async function runMigrate(root, { apply = false, json = false } = {}, { m
       if (r.action === 'unreadable') hand(`${r.file} does not parse — restore it from git before migrating`);
     }
     if (blocked.length) warn('some files were left untouched — see above');
+    if (apply && written.length) hand('then run `yad update`, which refreshes the check gates installed in your repos');
+    // E124: the last line, for as long as the old settings name is on disk — the changes no command makes.
+    if (exists(path.join(root, PROJECT_FILES.productConfigLegacy))) info(`the hub → Product changes only you can make (your own CI settings, scripts, badges), and the order to run things in: ${PRODUCT_RENAME_GUIDE_URL}`);
   }
 
   if (blocked.length || productBlocked) process.exitCode = 1;

package/cli/mode.mjs

@@ -29,7 +29,7 @@ export const MODES = ['solo', 'team'];
 const isObj = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 
 // The mode the gates act on today. Read from `solo` (and the older `review_gate.solo`), never from `mode`.
-export const modeOf = (hub) => (isSolo(hub) ? 'solo' : 'team');
+export const modeOf = (productConfig) => (isSolo(productConfig) ? 'solo' : 'team');
 
 // PURE. The fields a write of mode `to` puts on the Product config, given what is there now. Shared by this
 // command and `yad setup`, so the two writers can never spell the switch differently (staged-rename trap 1).
@@ -37,8 +37,8 @@ export const modeOf = (hub) => (isSolo(hub) ? 'solo' : 'team');
 //   review_gate   `review_gate.solo: true` also switches solo on, so switching to team turns it off too;
 //                 otherwise the old flag would keep the gates waived under a file that says `team`.
 //   mode_set      only when the mode the gates act on actually changes: who, when, why, and from what.
-export function modeFields(hub, to, { by = null, date = null, reason = null } = {}) {
-  const cur = isObj(hub) ? hub : {};
+export function modeFields(productConfig, to, { by = null, date = null, reason = null } = {}) {
+  const cur = isObj(productConfig) ? productConfig : {};
   const from = modeOf(cur);
   const fields = { solo: to === 'solo', mode: to };
   if (to === 'team' && isObj(cur.review_gate) && cur.review_gate.solo === true) {
@@ -52,11 +52,11 @@ export function modeFields(hub, to, { by = null, date = null, reason = null } =
 //   changed: false          the file already says it both ways — nothing to write.
 //   flipped: true           the gates act differently from the next sync; `mode_set` records it.
 //   flipped: false, changed the gates act the same, and the new name is added beside the old one.
-export function planMode(hub, { to, reason = null, by = null, date = null } = {}) {
+export function planMode(productConfig, { to, reason = null, by = null, date = null } = {}) {
   if (!MODES.includes(to)) {
     return { ok: false, message: `unknown mode: ${to ?? '(none)'}`, hint: 'usage: yad mode [solo --reason "<why>" | team [--reason "<why>"]]' };
   }
-  const cur = isObj(hub) ? hub : {};
+  const cur = isObj(productConfig) ? productConfig : {};
   const from = modeOf(cur);
   const why = typeof reason === 'string' ? reason.trim() : '';
   if (from !== to && to === 'solo' && !why) {
@@ -69,7 +69,7 @@ export function planMode(hub, { to, reason = null, by = null, date = null } = {}
   const fields = modeFields(cur, to, { by, date, reason: why || null });
   const next = { ...cur, ...fields };
   const changed = Object.keys(fields).some((k) => JSON.stringify(cur[k]) !== JSON.stringify(fields[k]));
-  return { ok: true, from, to, flipped: from !== to, changed, hub: next };
+  return { ok: true, from, to, flipped: from !== to, changed, productConfig: next };
 }
 
 // Every review gate that is open right now, across the feature epics and the Foundation. These are the ones
@@ -113,22 +113,22 @@ export async function runMode(root, { to = null, reason = null, json = false, to
   const bail = makeBail(json);
   const file = productConfigPath(root);
   const rel = path.relative(root, file).split(path.sep).join('/');
-  let hub;
+  let productConfig;
   try {
-    hub = readJSONStrict(file, null);
+    productConfig = readJSONStrict(file, null);
   } catch {
     return bail(`${rel} does not parse — nothing is written over it`, 'fix the JSON or restore it from git, then run this again');
   }
-  if (hub !== null && !isObj(hub)) return bail(`${rel} has the wrong shape — nothing is written over it`, 'expected a JSON object; fix it or re-run `yad setup`');
+  if (productConfig !== null && !isObj(productConfig)) return bail(`${rel} has the wrong shape — nothing is written over it`, 'expected a JSON object; fix it or re-run `yad setup`');
 
   if (to === null) {
-    const mode = modeOf(hub);
-    const name = isObj(hub) && hub.mode !== undefined ? hub.mode : null;
-    const set = isObj(hub) && isObj(hub.mode_set) ? hub.mode_set : null;
-    const hint = soloTeamHint(root, hub, { solo: mode === 'solo', headCount, today });
+    const mode = modeOf(productConfig);
+    const name = isObj(productConfig) && productConfig.mode !== undefined ? productConfig.mode : null;
+    const set = isObj(productConfig) && isObj(productConfig.mode_set) ? productConfig.mode_set : null;
+    const hint = soloTeamHint(root, productConfig, { solo: mode === 'solo', headCount, today });
     if (json) return emitJSON({ ok: true, mode, name, agrees: name === null || name === mode, set, suggest: hint });
     ok(`mode: ${mode} — ${MEANING[mode]}`);
-    if (!hub) info('no Product config yet — team mode is the default; `yad setup` records it');
+    if (!productConfig) info('no Product config yet — team mode is the default; `yad setup` records it');
     if (set) info(setLine(set));
     if (name !== null && name !== mode) warn(`the file also says mode: ${JSON.stringify(name)}, but the old \`solo\` flag is the one read — run \`yad mode ${mode}\` to make them agree`);
     printTeamHint(hint, { unknown: true });
@@ -137,26 +137,26 @@ export async function runMode(root, { to = null, reason = null, json = false, to
 
   // The word is checked first, so a typo on a fresh directory is named as a typo, not as a missing setup.
   if (!MODES.includes(to)) return bail(`unknown mode: ${to}`, 'usage: yad mode [solo --reason "<why>" | team [--reason "<why>"]]');
-  if (!hub) return bail(`no Product config at ${rel}`, 'run `yad setup` first — it records the mode with everything else');
-  const plan = planMode(hub, { to, reason, by: recordActor(root), date: today });
+  if (!productConfig) return bail(`no Product config at ${rel}`, 'run `yad setup` first — it records the mode with everything else');
+  const plan = planMode(productConfig, { to, reason, by: recordActor(root), date: today });
   if (!plan.ok) return bail(plan.message, plan.hint);
-  if (plan.changed) writeProductConfig(root, plan.hub);
+  if (plan.changed) writeProductConfig(root, plan.productConfig);
   // On a verified Product CI writes the ledger only at a merge, so an open review is never `in_review` in
   // state.json — the platform's open PRs are the list. Say so, rather than print nothing and read as "none".
-  const verified = isVerifiedLedger(hub);
+  const verified = isVerifiedLedger(productConfig);
   const open = plan.flipped && !verified ? openReviews(root) : [];
   if (json) {
-    return emitJSON({ ok: true, mode: to, changed: plan.changed, flipped: plan.flipped, set: plan.flipped ? plan.hub.mode_set : null, openReviews: open, openReviewsKnown: !verified });
+    return emitJSON({ ok: true, mode: to, changed: plan.changed, flipped: plan.flipped, set: plan.flipped ? plan.productConfig.mode_set : null, openReviews: open, openReviewsKnown: !verified });
   }
   if (!plan.changed) return ok(`already ${to} — nothing changed`);
   if (!plan.flipped) {
     // Reached two ways: `mode` was absent (a Product set up before E10), or a hand edit left it saying the
     // other mode — which is where `mode:disagree` sends people. Say which one happened.
-    const what = hub.mode === undefined ? 'the new name `mode` was added beside `solo`' : '`mode` now matches `solo`';
+    const what = productConfig.mode === undefined ? 'the new name `mode` was added beside `solo`' : '`mode` now matches `solo`';
     ok(`already ${to} — ${what}; the gates act exactly as before`);
   } else {
     ok(`mode: ${to} — ${MEANING[to]}`);
-    if (plan.hub.mode_set.reason) info(`reason: ${plan.hub.mode_set.reason}`);
+    if (plan.productConfig.mode_set.reason) info(`reason: ${plan.productConfig.mode_set.reason}`);
     if (verified) {
       info(`this Product's ledger is verified, so its open reviews live on the platform, not in state.json — every open review PR/MR follows the ${to} rule from its next CI run`);
     } else if (open.length) {
@@ -166,5 +166,5 @@ export async function runMode(root, { to = null, reason = null, json = false, to
     if (to === 'solo') info(c.dim('`yad doctor` warns if branch protection still requires an approval you cannot give yourself'));
   }
   const back = to === 'solo' ? 'yad mode team' : 'yad mode solo --reason "<why>"';
-  hand(`commit ${PROJECT_FILES.productConfig} and ${PROJECT_FILES.hubConfig} so every machine and CI run sees it  (reverse with \`${back}\`)`);
+  hand(`commit ${PROJECT_FILES.productConfig} and ${PROJECT_FILES.productConfigLegacy} so every machine and CI run sees it  (reverse with \`${back}\`)`);
 }

package/cli/next.mjs

@@ -19,7 +19,7 @@ import { dedupeConsecutive, epicIds, isGateStep, killSwitchOn, loadAutomation, e
 
 // Is solo mode on? Persisted in hub.json by setup (Phase C/D); default false. Read defensively so a
 // missing/old hub.json never breaks the driver.
-const soloOf = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
+const soloOf = (productConfig) => !!(productConfig && (productConfig.solo === true || productConfig.review_gate?.solo === true));
 function isSolo(root) {
   return soloOf(readJSON(productConfigPath(root), null));
 }
@@ -354,22 +354,22 @@ function generalNext(root, { all, headCount = null } = {}) {
     return;
   }
   // The Product config, read ONCE for this view.
-  const hub = readJSON(productConfigPath(root), null);
-  const solo = soloOf(hub);
+  const productConfig = readJSON(productConfigPath(root), null);
+  const solo = soloOf(productConfig);
   // E74: in solo mode, suggest `yad mode team` when the count shows more than one person may work here.
   // Printed first, so it is not lost under a long list of epics. An unknown count is not said here —
   // `yad doctor` and `yad mode` say it (the user's choice, 2026-09-22). `headCount` is for tests.
-  printTeamHint(soloTeamHint(root, hub, { solo, headCount }));
+  printTeamHint(soloTeamHint(root, productConfig, { solo, headCount }));
   // `profile` here is the SETUP profile `yad setup` records (codebase / repo_layout / team_size), not the
   // lifecycle profile an epic walks (`LIFECYCLE_PROFILES`, E5): two things share the word.
-  const brownfield = hub?.profile?.codebase === 'brownfield';
+  const brownfield = productConfig?.profile?.codebase === 'brownfield';
   // The PRODUCT level (the Foundation, or a ledger still in its old `discovery` spelling) is not a
   // feature epic — split it out so it is surfaced on its own line and never mixed into the roll-up.
   const allEpics = listEpics(root);
   // One read of `.sdlc/skills.json` for the whole roll-up, not one per epic.
   const bindings = loadSkillBindings(root);
   const automation = loadAutomation(root);
-  const verified = isVerifiedLedger(hub);
+  const verified = isVerifiedLedger(productConfig);
   // The Foundation wins when both exist. Two product levels is a fault `yad doctor` fails on; until it
   // is fixed the new spelling is the one worth acting on, and the old one is named so it is not lost.
   const productIds = PRODUCT_EPICS.filter((id) => allEpics.includes(id));