yadflow 4.0.0-next.3 → 4.0.0

package/cli/epic-state.mjs

@@ -7,8 +7,8 @@ import fs from 'node:fs';
 import { isPlainObject, readJSON, readJSONStrict, writeJSON, fileSha } from './lib.mjs';
 import { err } from './errors.mjs';
 import {
-  ADVANCE_FROM_AUTOMATION, AUTOMATION_FROM_ADVANCE, DRIVER_FROM_ASSISTANCE, epicFiles, preferring,
-  PROJECT_FILES, SCHEMA_VERSION, stepAdvance,
+  ADVANCE_FROM_AUTOMATION, AUTOMATION_FROM_ADVANCE, DRIVER_FROM_ASSISTANCE, epicFiles, mirrorDrift, preferring,
+  productDrift, PROJECT_FILES, SCHEMA_VERSION, stepAdvance,
 } from './manifest.mjs';
 
 const RISK_ESCALATORS = ['contract', 'auth', 'payments'];
@@ -37,7 +37,7 @@ const RISK_ESCALATORS = ['contract', 'auth', 'payments'];
 // `short` is measured against the capped ask and printed, and never enforced.
 //
 // WHEN THE COUNT IS UNKNOWN (`active: null`) no cap is computed at all: an unknown is never a small
-// number (E71). Product CI is usually that case — it checks out only the hub, so connected repos are
+// number (E71). Product CI is usually that case — it checks out only the Product, so connected repos are
 // not on disk — and the surfaces say so.
 //
 // Until E62 the base was not what held a gate either: a ROLE rule read from the roster did (1 owner,
@@ -263,10 +263,10 @@ export const gateRuleEnforced = (rule, cap = null) => {
 //
 // It sat in cli/gate.mjs until E71, which needs it in the active-people reader that gate.mjs prints —
 // a cycle. It is pure and data-only, so it belongs here beside `gateRuleFor`; gate.mjs re-exports it.
-export function legacyLogins(hub) {
+export function legacyLogins(productConfig) {
   const out = new Map();
   const clash = new Set();
-  for (const e of Array.isArray(hub?.roster) ? hub.roster : []) {
+  for (const e of Array.isArray(productConfig?.roster) ? productConfig.roster : []) {
     if (!e || typeof e.name !== 'string' || !e.name || typeof e.login !== 'string' || !e.login) continue;
     if (out.has(e.name) && out.get(e.name) !== e.login) clash.add(e.name);
     out.set(e.name, e.login);
@@ -347,6 +347,29 @@ export function epicIds(root) {
   return ids.sort();
 }
 
+// E122: a renamed file whose two names say different things (MIRRORED_FILES, cli/manifest.mjs). No
+// command picks one of them, so each refuses with this — `yad doctor` and `yad migrate` excepted: one
+// reports the drift, the other ends it. `pairs` is what `productDrift` found, project-relative.
+export const driftError = (pairs) => err(
+  'YAD-STATE-008',
+  `${pairs.map((p) => `${p.canonical} and ${p.legacy}`).join('; ')} say different things — they are one file under two names until v5, so yad reads neither`,
+  'run `yad migrate` to see the difference, then `yad migrate --apply` to choose the copy to keep (or `--apply --keep product` / `--keep hub`)',
+);
+
+// The drift under a Product root, as the error to throw, or null. Listing `epics/` can fail on a broken
+// tree; that is left to the command, which reports it in its own words.
+export function productDriftError(root) {
+  const pairs = productDriftPairs(root);
+  return pairs.length ? driftError(pairs) : null;
+}
+// The drifted pairs themselves: the one lookup the refusal, `yad doctor` and `yad migrate` all use, so what
+// doctor names and what the commands refuse on cannot differ (E124 follow-up review).
+export function productDriftPairs(root) {
+  let dirs = [];
+  try { dirs = epicIds(root).map(epicRel); } catch { /* the settings file is still checked */ }
+  return productDrift(root, dirs);
+}
+
 // The folders under `epics/` that hold a `.sdlc/` but that `epicIds` did not name: a name that is not a
 // valid id, a symlinked epic (`Dirent.isDirectory()` is false for a symlink), and `epics/EP-foundation`.
 // That guard is right for an enumerator that turns a name into a path segment, and wrong for anything
@@ -455,12 +478,12 @@ export const canonicalApprovals = (approvals = []) => canonical(approvals, (a) =
 export const canonicalComments = (comments = []) => canonical(comments, (cm) =>
   [cm.step, String(cm.round ?? '').padStart(6, '0'), cm.commenter, cm.role, cm.date].map(field).join('|'));
 
-export const canonicalHubPrs = (hubPrs = []) => canonical(hubPrs, (p) =>
+export const canonicalProductPrs = (productPrs = []) => canonical(productPrs, (p) =>
   [p.artifact, p.step].map(field).join('|'));
 
 // Replace-not-append upsert into hub-prs.json, keyed by artifact (one live review PR per artifact).
-export function upsertHubPr(hubPrs = [], rec) {
-  return canonicalHubPrs([...hubPrs.filter((p) => p.artifact !== rec.artifact), rec]);
+export function upsertProductPr(productPrs = [], rec) {
+  return canonicalProductPrs([...productPrs.filter((p) => p.artifact !== rec.artifact), rec]);
 }
 
 // SHA-256 of the contract surface block (architecture only). Byte-for-byte identical to the recipe
@@ -1444,12 +1467,12 @@ export function loadLedger(epicDir) {
     state: validateState(readJSONStrict(f.state, null), f.state),
     approvals: requireArray(readJSONStrict(f.approvals, []), f.approvals),
     comments: requireArray(readJSONStrict(f.comments, []), f.comments),
-    // Read the OLD name while it exists, the new one otherwise — the same tie-break as the settings
-    // file (`preferring`, cli/manifest.mjs). Both are written on every
-    // save (see gateSync / gateOpen), so they agree unless someone edited one by hand — which
-    // `yad doctor` reports rather than leaving to be discovered.
-    hubPrs: (() => {
-      const f2 = preferring(f.productPrs, f.hubPrs);
+    // Read the new name when it exists, the old one otherwise — the same rule as the settings file
+    // (`preferring`, cli/manifest.mjs). Both are written on every save (see gateSync / gateOpen), so
+    // they agree unless something outside yad edited one; then neither is read (E122).
+    productPrs: (() => {
+      if (mirrorDrift(f.productPrs, f.productPrsLegacy)) throw driftError([{ canonical: f.productPrs, legacy: f.productPrsLegacy }]);
+      const f2 = preferring(f.productPrs, f.productPrsLegacy);
       return requireArray(readJSONStrict(f2, []), f2);
     })(),
     contractLock: readJSONStrict(f.contractLock, null),
@@ -1691,7 +1714,7 @@ export function gatePredicate({
   const stale = forStep.filter((a) => isStaleHash(a.artifactHash, accepted));
   const live = forStep.filter((a) => !stale.includes(a));
 
-  // requireEngagement (config `hub.review.requireEngagement`, soft-off by default): only an approval
+  // requireEngagement (config `review.requireEngagement` in the Product settings, soft-off by default): only an approval
   // carrying a verified engagement signal counts. The signal is gameable by design — this raises the
   // cost of a bare rubber-stamp, it does not claim to prove a human read the artifact.
   const counted = requireEngagement ? live.filter((a) => a.engagement === 'verified') : live;
@@ -3328,7 +3351,7 @@ function reopenedLanes(ledger, { epicId, currentStep, bindings }) {
     .map((s) => {
       if (stepStatus(s) === 'blocked') return { step: s.id, kind: 'blocked', status: 'blocked', record: s.record || null };
       if (s.type === 'author') return { step: s.id, kind: 'author', status: s.status, ...skillFields(stepSkills(s.id, bindings)), artifact: s.artifact };
-      const pr = (ledger.hubPrs || []).find((p) => artifactBase(p.artifact) === artifactBase(s.artifact));
+      const pr = (ledger.productPrs || []).find((p) => artifactBase(p.artifact) === artifactBase(s.artifact));
       return { step: s.id, kind: pr ? 'review-sync' : 'review-open', status: s.status, artifact: s.artifact, pr: pr ? pr.number : null,
         command: `yad gate ${pr ? 'sync' : 'open'} ${epicId} ${s.artifact}` };
     });
@@ -3366,7 +3389,7 @@ function shapeNextAction(ledger, { epic, bindings = null } = {}) {
         ...skillFields(stepSkills(dstep.id, bindings)), artifact: dstep.artifact,
         why: `${dstep.id} is ${dstep.status} — author ${dstep.artifact}` };
     }
-    const dpr = (ledger.hubPrs || []).find((p) => artifactBase(p.artifact) === artifactBase(dstep.artifact));
+    const dpr = (ledger.productPrs || []).find((p) => artifactBase(p.artifact) === artifactBase(dstep.artifact));
     const dverb = dpr ? 'sync' : 'open';
     return { epicId, kind: dpr ? 'review-sync' : 'review-open', step: dstep.id, status: dstep.status,
       artifact: dstep.artifact, pr: dpr ? dpr.number : null,
@@ -3450,7 +3473,7 @@ function shapeNextAction(ledger, { epic, bindings = null } = {}) {
   }
 
   // review+approve: open the review PR if none is recorded yet, else sync the open one.
-  const pr = (ledger.hubPrs || []).find((p) => artifactBase(p.artifact) === artifactBase(step.artifact));
+  const pr = (ledger.productPrs || []).find((p) => artifactBase(p.artifact) === artifactBase(step.artifact));
   const verb = pr ? 'sync' : 'open';
   return { epicId, kind: pr ? 'review-sync' : 'review-open', step: step.id, status: step.status,
     artifact: step.artifact, pr: pr ? pr.number : null, parallel,

package/cli/errors.mjs

@@ -23,11 +23,12 @@ export const CODES = {
   'YAD-STATE-005': 'an authoring step is stranded behind its completed review gate',
   'YAD-STATE-006': 'a Build ledger is locked by another yad process that is writing it',
   'YAD-STATE-007': 'an epic cannot be seeded — the profile, the type or the existing ledger refuses it',
-  'YAD-CFG-001': 'hub.json names an unknown platform (expected github, gitlab, or null)',
+  'YAD-STATE-008': 'a file kept under two names (product.json + hub.json, or product-prs.json + hub-prs.json) says different things under each',
+  'YAD-CFG-001': 'the Product settings (product.json, or hub.json on a Product that has only that name) name 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)',
   'YAD-CFG-004': 'learning.json names an unknown learning tool (expected one of config.yaml learning.tools, or none)',
-  'YAD-CFG-005': 'hub.json sets a platform but is missing git_url (required to scope auth + open PRs)',
+  'YAD-CFG-005': 'the Product settings (product.json, or hub.json on a Product that has only that name) set a platform but are missing git_url (required to scope auth + open PRs)',
   'YAD-CFG-006': 'skills.json binds a step to something that is not a skill name (expected a string, or a non-empty list of strings)',
   'YAD-CLI-001': 'a --json run needed an answer that only a prompt could give',
 };

package/cli/find-product.mjs

@@ -0,0 +1,197 @@
+// Find the Product from wherever yad runs (E80).
+//
+// A WORKSPACE is the folder that holds the Product and the code repos side by side (E79):
+//
+//   acme/
+//     .yad-workspace.json   { "version": 1, "product": "product" }
+//     product/              <- the Product
+//     backend/  web/        <- code repos
+//
+// `findProduct(start)` walks up from `start` and stops at the FIRST of:
+//   - a folder that is a Product (it has `.sdlc/hub.json` or `.sdlc/product.json`) — so any subfolder of
+//     the Product finds it;
+//   - a folder holding `.yad-workspace.json` — its `product` names the Product folder beside the repos.
+//     It is used ONLY when `start` is inside a repo that Product registers in its `repos.json`. A
+//     workspace can be a shared folder (`~/Projects`, holding many teams' repos — setup always allowed
+//     that), and a file there must not send an unrelated repo's `yad epic new` or `yad kill` to this
+//     Product (E80 review 1). Anywhere else in the workspace there is no Product.
+//
+// The workspace file is per machine: the workspace folder is not a git repo (`yad new`, `init` and `join`
+// refuse to make one inside a repo). So a `.yad-workspace.json` found INSIDE a git work tree is not used
+// — a code repo could commit one, pointing yad at a Product folder of its own making — nor one in the
+// home or temp folder. The walk STOPS there with the reason, rather than going on up to whatever
+// Product lies above.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { exists, readJSON, writeJSON } from './lib.mjs';
+import { productConfigPath, PROJECT_FILES } from './manifest.mjs';
+
+export const WORKSPACE_FILE = '.yad-workspace.json';
+export const WORKSPACE_VERSION = 1;
+
+// The Product folder a workspace file may name: one folder, beside the file — never a path.
+const PRODUCT_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
+
+// Is `dir`, or any folder above it, a git work tree? A `.git` folder or file (a worktree, a submodule)
+// is enough — no git run needed.
+function insideGitTree(dir) {
+  for (let d = path.resolve(dir); ; d = path.dirname(d)) {
+    if (fs.existsSync(path.join(d, '.git'))) return true;
+    if (path.dirname(d) === d) return false;
+  }
+}
+
+// On disk, as the disk spells it: `.native` returns the stored case (APFS and NTFS ignore case, and the JS
+// realpath keeps whatever case it was given) and Windows' long names for 8.3 short ones — the same rule
+// as `samePath` in lib.mjs. Windows compares without case, too.
+const real = (p) => { try { return fs.realpathSync.native(p); } catch { return null; } };
+const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+const within = (child, parent) => fold(child) === fold(parent) || fold(child).startsWith(fold(parent) + path.sep);
+
+// Read one workspace file. `{ product }` (an absolute Product root) or `{ problem }`.
+export function readWorkspace(workspaceDir) {
+  const file = path.join(workspaceDir, WORKSPACE_FILE);
+  const rec = readJSON(file, null);
+  if (!rec || typeof rec !== 'object' || Array.isArray(rec)) return { problem: `${file} cannot be read` };
+  if (rec.version !== WORKSPACE_VERSION) return { problem: `${file} is version ${JSON.stringify(rec.version ?? null)}, and this yadflow reads version ${WORKSPACE_VERSION}` };
+  if (typeof rec.product !== 'string' || !PRODUCT_NAME_RE.test(rec.product)) return { problem: `${file}: "product" must be one folder name beside it` };
+  const product = path.join(workspaceDir, rec.product);
+  if (!exists(productConfigPath(product))) return { problem: `${file} names ${rec.product}/, which is not a Product` };
+  return { product };
+}
+
+export const hasProduct = (dir) => exists(productConfigPath(dir));
+
+// The Product a folder's own workspace file names, when the file is there and usable; else null.
+export function workspaceProduct(dir) {
+  if (!fs.existsSync(path.join(dir, WORKSPACE_FILE)) || insideGitTree(dir)) return null;
+  return readWorkspace(dir).product || null;
+}
+
+// → { root, via: 'here' | 'above' | 'workspace', workspace?, repo? } | { problem } | { elsewhere } | null
+//   `repo`       the registry entry of the code repo `start` is in, when there is one;
+//   `elsewhere`  a workspace's Product, found from a folder that is not in one of its repos (the workspace
+//                folder itself, say) — not used, but worth naming to the person.
+export function findProduct(start) {
+  const from = path.resolve(start);
+  // Crossing a git repo's top on the way up: the Product above is some OTHER repo's (E80 review 2). It is
+  // used only when it registers the repo `start` is in — the same rule as the workspace file's, so an
+  // unrelated repo nested in the Product's folder (`vendor/lib`) never writes to it.
+  let crossedRepo = false;
+  for (let d = from; ; d = path.dirname(d)) {
+    if (exists(productConfigPath(d))) {
+      if (d === from) return { root: d, via: 'here' };
+      const repo = registeredRepoHolding(d, from);
+      if (crossedRepo && !repo) return null;
+      return { root: d, via: 'above', ...(repo ? { repo } : {}) };
+    }
+    if (fs.existsSync(path.join(d, WORKSPACE_FILE))) {
+      const file = path.join(d, WORKSPACE_FILE);
+      if (insideGitTree(d)) return { problem: `${file} is inside a git repo, so it is not used (a repo could commit one)` };
+      if (sharedFolder(d)) return { problem: `${file} is in your home or temp folder, so it is not used` };
+      const ws = readWorkspace(d);
+      if (ws.problem) return { problem: ws.problem };
+      // Only for a repo this Product registers — never for any folder that happens to sit beside it.
+      const repo = registeredRepoHolding(ws.product, from);
+      return repo ? { root: ws.product, via: 'workspace', workspace: d, repo } : { elsewhere: ws.product };
+    }
+    if (fs.existsSync(path.join(d, '.git'))) crossedRepo = true;
+    if (path.dirname(d) === d) return null;
+  }
+}
+
+// The registry entry whose folder holds `dir` — the repo itself or any folder inside it — compared on
+// disk (a link or a different spelling of the same folder still matches). The deepest one wins; the
+// Product's own entry (a monorepo, `.`) never does.
+export function registeredRepoHolding(productRoot, dir) {
+  const at = real(dir);
+  const productAt = real(productRoot);
+  if (!at || !productAt) return null;
+  const reg = readJSON(path.join(productRoot, PROJECT_FILES.reposRegistry), null);
+  let best = null;
+  let bestAt = '';
+  for (const r of Array.isArray(reg?.repos) ? reg.repos : []) {
+    if (typeof r?.path !== 'string') continue;
+    const repoAt = real(path.resolve(productRoot, r.path));
+    if (!repoAt || fold(repoAt) === fold(productAt) || !within(at, repoAt) || repoAt.length <= bestAt.length) continue;
+    best = r;
+    bestAt = repoAt;
+  }
+  return best;
+}
+
+// Folders a workspace file is never written into: the home folder, the temp folder and the top of a disk.
+// A file there would be found from every folder below it — every project, every test's temp folder.
+function sharedFolder(dir) {
+  const onDisk = (p) => fold(real(p) ?? path.resolve(p));
+  const d = onDisk(dir);
+  return path.dirname(d) === d || d === onDisk(os.homedir()) || d === onDisk(os.tmpdir());
+}
+
+// Does a registered repo live BESIDE the Product (not inside it)? Only then does a workspace file help
+// from a code repo — `yad check --fix` writes one only for such a Product (E80).
+export function hasSiblingRepo(productRoot) {
+  const root = path.resolve(productRoot);
+  const workspace = path.dirname(root);
+  const reg = readJSON(path.join(root, PROJECT_FILES.reposRegistry), null);
+  return (Array.isArray(reg?.repos) ? reg.repos : []).some((r) => {
+    if (typeof r?.path !== 'string') return false;
+    const at = path.resolve(root, r.path);
+    // …and is on this machine: a teammate who cloned the Product alone gains nothing from the file.
+    return !(at === root || at.startsWith(root + path.sep)) && at.startsWith(workspace + path.sep) && fs.existsSync(at);
+  });
+}
+
+// The workspace file for this Product: 'ok' | 'missing' | 'other: <why>' (another file there, or a
+// folder a file is never written into). Read by `yad doctor` and `yad check`.
+export function workspaceFileState(productRoot) {
+  const root = path.resolve(productRoot);
+  const workspace = path.dirname(root);
+  const name = path.basename(root);
+  if (path.dirname(root) === root || sharedFolder(workspace)) return 'other: the folder above the Product is your home folder, the temp folder or the top of the disk — move the Product into a folder of its own';
+  if (!PRODUCT_NAME_RE.test(name)) return `other: the Product folder's name (${name}) is not one a workspace file can hold`;
+  if (insideGitTree(workspace)) return 'other: the folder above the Product is inside a git repo';
+  const cur = readJSON(path.join(workspace, WORKSPACE_FILE), null);
+  if (cur && cur.product === name && cur.version === WORKSPACE_VERSION) return 'ok';
+  if (cur && cur.product === name) return `other: ${WORKSPACE_FILE} there is version ${JSON.stringify(cur.version ?? null)}, not ${WORKSPACE_VERSION}`;
+  if (cur) return `other: ${WORKSPACE_FILE} there names ${typeof cur.product === 'string' ? `${cur.product}/` : 'no Product'}`;
+  return 'missing';
+}
+
+// Write the workspace file beside the Product: `{ version, product }`, the Product folder's own name.
+// Only where `workspaceFileState` says it is missing — never over another file, never inside a git work
+// tree (it would be committed to someone's repo, and is ignored there — see above), never into a shared
+// folder. Returns 'written' | 'ok' | 'skipped: <why>'.
+export function writeWorkspaceFile(productRoot) {
+  const state = workspaceFileState(productRoot);
+  if (state === 'ok') return 'ok';
+  if (state !== 'missing') return `skipped: ${state.replace(/^other: /, '')}`;
+  const root = path.resolve(productRoot);
+  writeJSON(path.join(path.dirname(root), WORKSPACE_FILE), { version: WORKSPACE_VERSION, product: path.basename(root) });
+  return 'written';
+}
+
+// The top of the git checkout `dir` is in: the nearest folder holding `.git` (a folder, or the file a
+// worktree or submodule has). Null outside any checkout.
+export function gitTopOf(dir) {
+  for (let d = path.resolve(dir); ; d = path.dirname(d)) {
+    if (fs.existsSync(path.join(d, '.git'))) return d;
+    if (path.dirname(d) === d) return null;
+  }
+}
+
+// The registry entry for the code repo a code-repo command runs in (E80), with the folder to work in.
+// It is the CHECKOUT that must be the registered repo — not merely a folder inside it: a worktree or a
+// repo nested in `backend/` is another checkout, on another branch, and must never be swapped for
+// backend's own (E80 review 3). → { meta, top } or null. Never the Product's own entry.
+export function registryEntryFor(productRoot, dir) {
+  if (!productRoot) return null;
+  const top = gitTopOf(dir);
+  if (!top) return null;
+  const meta = registeredRepoHolding(productRoot, top);
+  if (!meta) return null;
+  const at = real(path.resolve(productRoot, meta.path));
+  const topAt = real(top);
+  return at && topAt && fold(at) === fold(topAt) ? { meta, top } : null;
+}

package/cli/fold.mjs

@@ -32,7 +32,7 @@ import { ok, info, warn, fail, hand, readJSON } from './lib.mjs';
 import { productConfigPath, isVerifiedLedger } from './manifest.mjs';
 import { STEPS, FOUNDATION_EPIC, FOUNDATION_DIR, DISCOVERY_EPIC, artifactBase, artifactPaths, epicRoot } from './epic-state.mjs';
 import { capturedEpic, gitIn, isOwnerPath, statusEntries, wipName, wipBranch, runCapture } from './capture.mjs';
-import { resolveDefaultBranch, preflightGuardReadiness } from './hubcommit.mjs';
+import { resolveDefaultBranch, preflightGuardReadiness } from './productcommit.mjs';
 
 // The authoring steps a fold can close: every catalogue step of kind `author` that writes a Shape artifact.
 // The Build steps (spec, tasks, implement, checks) write code in another repo and have no artifact here.
@@ -125,8 +125,8 @@ export async function runFold(root, { epic, step, env = process.env, capture = r
   if (!fs.existsSync(productConfigPath(root))) return refuse('not a Product (no .sdlc/hub.json or product.json here)', 'run it from the Product root, or pass --dir');
   if (!fs.existsSync(epicRoot(root, epic))) return refuse(`no ${epicRel(epic)}/ in this Product`);
 
-  const hub = readJSON(productConfigPath(root), {}) || {};
-  const verified = isVerifiedLedger(hub);
+  const productConfig = readJSON(productConfigPath(root), {}) || {};
+  const verified = isVerifiedLedger(productConfig);
   const branchR = git(['symbolic-ref', '--short', '-q', 'HEAD']);
   const branch = branchR.ok ? branchR.out.trim() : null;
   if (verified && !branch) {
@@ -140,7 +140,7 @@ export async function runFold(root, { epic, step, env = process.env, capture = r
     .find((f) => { const r = git(['rev-parse', '--git-path', f]); return r.ok && fs.existsSync(path.resolve(root, r.out.trim())); });
   if (busy) return refuse(`a ${IN_PROGRESS[busy]} is in progress — finish or abort it first, then run yad fold again`);
   if (verified) {
-    const def = resolveDefaultBranch((...a) => { const r = git(a); return { ok: r.ok, stdout: r.out.trim() }; }, hub);
+    const def = resolveDefaultBranch((...a) => { const r = git(a); return { ok: r.ok, stdout: r.out.trim() }; }, productConfig);
     if (branch === def) {
       return refuse(`on the default branch '${def}' — with a verified ledger, artifacts reach it only through the review PR`,
         `switch to the step's authoring branch first (git switch -c ${step}/${epic}), then run yad fold again`);

package/cli/gate-local.mjs

@@ -43,12 +43,12 @@ export function reviewerName(v) {
 function localGate(root, { epic, artifact, verb }) {
   const usage = `yad gate ${verb} <epic> <artifact>${verb === 'advance' ? '' : ' --by <name>'}`;
   if (!artifact) { fail(`usage: ${usage}`); process.exitCode = 1; return null; }
-  const { hub } = loadProduct(root);
+  const { productConfig } = loadProduct(root);
   // One check covers both refusals: a verified ledger needs a platform (`isVerifiedLedger`), so any
   // platform at all means the approvals live on the PR/MR, not here.
-  if (hub?.platform) {
-    fail(`\`yad gate ${verb}\` is for a Product with no platform — this one reviews on ${printable(String(hub.platform)) ?? 'a platform'}, so nothing is written`);
-    if (isVerifiedLedger(hub)) hand('CI owns this ledger: approvals, comments and the advance land from the review PR/MR when it merges (`yad gate ci`)');
+  if (productConfig?.platform) {
+    fail(`\`yad gate ${verb}\` is for a Product with no platform — this one reviews on ${printable(String(productConfig.platform)) ?? 'a platform'}, so nothing is written`);
+    if (isVerifiedLedger(productConfig)) hand('CI owns this ledger: approvals, comments and the advance land from the review PR/MR when it merges (`yad gate ci`)');
     else hand(`review on the PR/MR, then run \`yad gate sync ${epic} ${artifact}\` — it reads the approvals and advances the step when the PR merges`);
     process.exitCode = 1;
     return null;
@@ -58,7 +58,7 @@ function localGate(root, { epic, artifact, verb }) {
   if (!ledger.state) { fail(`no epic state at ${epicRel(epic)}/.sdlc/state.json`); process.exitCode = 1; return null; }
   const step = findReviewStep(ledger.state, artifact);
   if (!step) { fail(`${epic} has no review step for ${artifact}`); process.exitCode = 1; return null; }
-  return { hub, epicDir, ledger, step, solo: isSolo(hub), reqEng: requireEngagement(hub) };
+  return { productConfig, epicDir, ledger, step, solo: isSolo(productConfig), reqEng: requireEngagement(productConfig) };
 }
 
 // A gate is recorded against only while it is OPEN. A step not reached yet has no review to approve:
@@ -98,8 +98,8 @@ const peopleOnStep = (g) => [
 
 // The one count every verb reports, read once per command (E71) — or handed in by a test, which must not
 // walk git from inside a fixture.
-function countPeople(root, hub, today, headCount) {
-  return headCount || activePeople(root, { today: today || undefined, aliases: legacyLogins(hub) });
+function countPeople(root, productConfig, today, headCount) {
+  return headCount || activePeople(root, { today: today || undefined, aliases: legacyLogins(productConfig) });
 }
 
 function judge(g, epicDir, people) {
@@ -162,7 +162,7 @@ export async function gateApprove(root, { epic, artifact, by, engagement = null,
   const { epicDir, ledger, step } = g;
   const hash = artifactHash(epicDir, step.artifact);
   const eng = engagement || 'none';
-  // Filter-then-push, keyed on (step, approver), as `upsertHubPr` does: one record per person. A bridge
+  // Filter-then-push, keyed on (step, approver), as `upsertProductPr` does: one record per person. A bridge
   // record (from a platform the Product once had) is left alone — it is another source's history.
   // The same person approving the same content again keeps the record as it was, date included, so a
   // repeat is a byte-identical no-op rather than a new line in the ledger's history.
@@ -180,12 +180,12 @@ export async function gateApprove(root, { epic, artifact, by, engagement = null,
     // approvers, commenters, what is still required): writing the short `gate sync` list here would erase
     // it on every approval of the day (E112 review).
     writeJSON(ledger.files.approvals, g.ledger.approvals);
-    refreshIndexAfterWrite(root, g.hub);
+    refreshIndexAfterWrite(root, g.productConfig);
   }
   if (same) info(`${name} had already approved this content of ${step.artifact} — nothing changed`);
   else ok(`${name} approved ${step.artifact} (${step.id})${was ? ' — their earlier approval is replaced' : ''}`);
 
-  const people = countPeople(root, g.hub, today, headCount);
+  const people = countPeople(root, g.productConfig, today, headCount);
   log(`  ${c.dim(activeSum(people))}`);
   note(c.dim(activeBasis(people)));
   const pred = judge(g, epicDir, people);
@@ -247,7 +247,7 @@ export async function gateComment(root, { epic, artifact, by, count = null, newR
   ledger.comments = canonicalComments([...ledger.comments.filter((cm) => !mine(cm)), record]);
   if (!same) {
     writeJSON(ledger.files.comments, ledger.comments);
-    refreshIndexAfterWrite(root, g.hub);
+    refreshIndexAfterWrite(root, g.productConfig);
   }
   if (same) info(`${name}'s round ${round} on ${step.artifact} already says ${n} comment(s) — nothing changed`);
   else ok(`${name}: ${n} comment(s) on ${step.artifact}, round ${round}${was ? ` (was ${was.count})` : ''}`);
@@ -270,7 +270,7 @@ export async function gateAdvance(root, { epic, artifact, today, headCount = nul
     return;
   }
   if (refuseUnopened(g, { epic, artifact, verb: 'advance' })) return;
-  const people = countPeople(root, g.hub, today, headCount);
+  const people = countPeople(root, g.productConfig, today, headCount);
   log(`  ${c.dim(activeSum(people))}`);
   note(c.dim(activeBasis(people)));
   const pred = judge(g, epicDir, people);
@@ -290,7 +290,7 @@ export async function gateAdvance(root, { epic, artifact, today, headCount = nul
     capped: pred.rule === 'count' && pred.cap?.capped ? { needed: pred.gateRule.needed, to: pred.cap.to, active: pred.cap.active } : null,
   });
   writeState(ledger.files.state, state);
-  refreshIndexAfterWrite(root, g.hub);
+  refreshIndexAfterWrite(root, g.productConfig);
   ok(`gate PASSED — ${step.id} → done; next: ${state.currentStep}`);
   return { epic, advanced: true, currentStep: state.currentStep ?? null, gate };
 }