yadflow 4.0.0-next.3 → 4.0.0

package/cli/history.mjs

@@ -204,13 +204,13 @@ export function readState(root, id) {
   return Array.isArray(r.value?.steps) ? { state: r.value, steps: r.value.steps } : { why: 'it has no list of steps' };
 }
 
-// The Product's settings, strictly: { hub } or { why }. A file that does not parse is said, never read
+// The Product's settings, strictly: { productConfig } or { why }. A file that does not parse is said, never read
 // as "team mode, no engagement rule" — that would print a confident count the gate itself refuses.
-function readHub(root) {
+function readProductConfig(root) {
   const r = readJsonFile(productConfigPath(root));
-  if (r.missing) return { hub: null };
+  if (r.missing) return { productConfig: null };
   if (r.why) return { why: r.why };
-  return isPlainObject(r.value) ? { hub: r.value } : { why: 'it is not an object' };
+  return isPlainObject(r.value) ? { productConfig: r.value } : { why: 'it is not an object' };
 }
 
 // Why a recorded approval does not count, in the order the gate asks — or null when it counts:
@@ -227,15 +227,15 @@ function notCountedReason(a, { approved, stale, named, reqEng }) {
 const NOT_JUDGED = { stale: null, counted: null, notCounted: null };
 
 // The whole story of one item, for `show`. Throws nothing: every part that cannot be read says why.
-// `hub` / `hubWhy`: the Product's settings, or why they could not be read.
-export function itemHistory(root, item, { hub = null, hubWhy = null } = {}) {
+// `productConfig` / `productConfigWhy`: the Product's settings, or why they could not be read.
+export function itemHistory(root, item, { productConfig = null, productConfigWhy = null } = {}) {
   const epicDir = epicRoot(root, item.id);
   const stateRead = readState(root, item.id);
   const approvalsRead = readJsonFile(path.join(epicDir, '.sdlc', 'approvals.json'));
   const approvals = approvalsRead.missing ? [] : Array.isArray(approvalsRead.value) ? approvalsRead.value : null;
   const approvalsWhy = approvals ? null : approvalsRead.why || 'it is not a list';
-  const reqEng = requireEngagement(hub);
-  const solo = isSolo(hub);
+  const reqEng = requireEngagement(productConfig);
+  const solo = isSolo(productConfig);
   // The steps THIS item's route lets be skipped — what `gatePredicate` asks before it honours a skip.
   const optional = stateRead.state ? optionalStepsFor(stateRead.state) : [];
   const out = [];
@@ -302,7 +302,7 @@ export function itemHistory(root, item, { hub = null, hubWhy = null } = {}) {
         };
         if (notJudged) return { ...fields, ...NOT_JUDGED };
         const stale = !approved ? null : accepted === null ? null : isStaleHash(a.artifactHash, accepted);
-        if (approved && (stale === null || solo || hubWhy)) return { ...fields, stale, counted: null, notCounted: null };
+        if (approved && (stale === null || solo || productConfigWhy)) return { ...fields, stale, counted: null, notCounted: null };
         // Named by the gate's own test (`gatePredicate`): any text that is not blank, even text with
         // nothing printable in it — the gate counts that record, so this must too.
         const named = typeof a.approver === 'string' && a.approver.trim() !== '';
@@ -327,7 +327,7 @@ export function itemHistory(root, item, { hub = null, hubWhy = null } = {}) {
     steps: stateRead.steps ? out : null,
     stepsWhy: stateRead.steps ? null : stateRead.why,
     approvalsWhy,
-    hubWhy,
+    productConfigWhy,
   };
 }
 
@@ -451,8 +451,8 @@ function showCmd(root, read, id, { json }) {
   if (bad) return refuse(json, `${id} could not be read — ${printable(bad.why)}`, 'fix or restore its files — `yad doctor` checks them');
   const item = read.items.find((i) => i.id === id);
   if (!item) return refuse(json, `no work item ${id} in this Product`, '`yad history` lists the work items');
-  const hubRead = readHub(root);
-  const story = itemHistory(root, item, { hub: hubRead.hub ?? null, hubWhy: hubRead.why ?? null });
+  const productConfigRead = readProductConfig(root);
+  const story = itemHistory(root, item, { productConfig: productConfigRead.productConfig ?? null, productConfigWhy: productConfigRead.why ?? null });
   // Steps that cannot be read are a failure in both forms: a script reading `--json` must see it too.
   if (!story.steps) process.exitCode = 1;
   if (json) {
@@ -474,7 +474,7 @@ function showCmd(root, read, id, { json }) {
     ['shape', isShapeDone(item) ? 'done (Build is not shown here)' : null],
   ].filter(([, v]) => v);
   for (const [k, v] of facts) log(`    ${c.dim(`${k}:`)} ${v}`);
-  if (story.hubWhy) warn(`the Product's settings could not be read — ${story.hubWhy}; whether an approval counts is not told`);
+  if (story.productConfigWhy) warn(`the Product's settings could not be read — ${story.productConfigWhy}; whether an approval counts is not told`);
   if (story.approvalsWhy) {
     warn(`.sdlc/approvals.json could not be read — ${story.approvalsWhy}; no approvals are shown`);
     hand('restore it from git — `yad doctor` checks it');

package/cli/hook.mjs

@@ -11,22 +11,23 @@
 //   exit 0  allow
 //   exit 2  deny — the reason is on stderr, for the agent to read
 // Claude Code's `PreToolUse` protocol is exactly that — exit 2 blocks the call and feeds stderr back
-// to the model — so `hooks/ledger-guard.sh` wires it with no adapter logic.
+// to the model — so `hooks/ledger-guard.mjs` wires it with no adapter logic.
 //
 // Cursor's `preToolUse` is NOT that. It is a permission hook: it wants a JSON verdict on stdout and
 // treats an empty or off-schema answer as a refusal, so the contract above would block every write.
-// `--format cursor` below answers in that protocol instead, and `hooks/ledger-guard-cursor.sh` is
+// `--format cursor` below answers in that protocol instead, and `hooks/ledger-guard-cursor.mjs` is
 // what Cursor's entry points at. Check which kind a harness is before wiring a new one.
 //
 // FAIL-OPEN, deliberately. No Product, unreadable config, an unparseable payload, no git — every one of
 // those ALLOWS, with a note on stderr. This is a local guardrail, and one that failed closed would
 // brick an agent's ability to edit anything the moment a config went sideways. The asymmetry is the
 // design: `ledger-guard` in CI fails closed and is what actually protects the ledger.
+import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { note, readJSON, run } from './lib.mjs';
-import { isVerifiedLedger , productConfigPath, HOOK_PROJECT_DIR_ENVS } from './manifest.mjs';
+import { isVerifiedLedger, mirrorDrift, productConfigPath, HOOK_PROJECT_DIR_ENVS, PROJECT_FILES } from './manifest.mjs';
 import { DISCOVERY_EPIC, FOUNDATION_DIR, FOUNDATION_EPIC } from './epic-state.mjs';
 
 // The CI-owned files, exactly as `templates/checks/ledger-guard.sh` lists them. NOT `contract-lock.json`
@@ -155,14 +156,14 @@ export function payloadPaths(payload) {
   return [...new Set(out)];
 }
 
-// The Product a path belongs to: the nearest ancestor holding `.sdlc/hub.json`.
+// The Product a path belongs to: the nearest ancestor holding `.sdlc/product.json` or `.sdlc/hub.json`.
 //
 // Resolved from the PATH, never from the session. The documented layout puts code repos BESIDE the
 // Product (`project/{product,backend,mobile}` — see `insideWorkspace` in setup.mjs), so a session opened
 // at the workspace has no `hub.json` under its root, and a session-rooted lookup would find nothing
 // and silently allow a mutation inside `project/product/epics/…` — the multi-repo, parallel-agent
 // setup this hook was reported from.
-export function hubRootFor(abs) {
+export function productRootFor(abs) {
   let dir = path.dirname(path.resolve(abs));
   for (;;) {
     if (fs.existsSync(productConfigPath(dir))) return dir;
@@ -196,7 +197,7 @@ export function baseDirFor(env = process.env, runner = run, payloadCwd = null) {
   if (typeof payloadCwd === 'string' && payloadCwd) return payloadCwd;
   // `process.cwd()` BEFORE the git toplevel, which is the opposite of the old order and fixes a real
   // miss: the documented layout puts the Product in a subdirectory of its repo, so the toplevel is the
-  // repo, `hubRootFor` walks up from there, finds no `hub.json`, and ALLOWS a ledger edit it must
+  // repo, `productRootFor` walks up from there, finds no `hub.json`, and ALLOWS a ledger edit it must
   // refuse. Anchoring too deep still tends to resolve into the Product and deny; anchoring too
   // shallow misses entirely, so the shallower guess goes last.
   if (process.cwd()) return process.cwd();
@@ -214,8 +215,8 @@ const fold = (s) => s.toLowerCase();
 // and `git fetch` never fast-forwards it, so probing `main` would report an epic whose review PR has
 // already merged as absent from the base and wave a real mutation straight through. That is the
 // stale-clone case, and it is the common one, not an edge.
-export function resolveHookBase(productRoot, hub, runner = run) {
-  const cfg = hub?.default_branch || '';
+export function resolveHookBase(productRoot, productConfig, runner = run) {
+  const cfg = productConfig?.default_branch || '';
   const head = runner('git', ['-C', productRoot, 'symbolic-ref', '--short', '--quiet', 'refs/remotes/origin/HEAD']);
   for (const base of [cfg ? `origin/${cfg}` : '', head.ok ? head.stdout : '', 'origin/main']) {
     if (!base || base === 'origin/') continue;
@@ -243,8 +244,8 @@ export function resolveHookBase(productRoot, hub, runner = run) {
 // null means the base could not be read at all — "unknown", which ALLOWS. The working tree cannot
 // stand in for the base ref: a seed writes `state.json` first, so using that as proof would deny
 // every remaining file of the same seed.
-export function seededSlugs(productRoot, hub, runner = run) {
-  const base = resolveHookBase(productRoot, hub, runner);
+export function seededSlugs(productRoot, productConfig, runner = run) {
+  const base = resolveHookBase(productRoot, productConfig, runner);
   if (!base) return null;
   const tree = runner('git', [
     '-C', productRoot, '-c', 'core.quotePath=false', 'ls-tree', '-r', '--name-only', '-z', base, '--', 'epics', FOUNDATION_DIR,
@@ -264,6 +265,35 @@ export function seededSlugs(productRoot, hub, runner = run) {
 }
 
 
+// The door, as the AGENT is told it (E49). Committing past the guard is a person's decision, so the
+// agent is told the command exists and that it is not the agent's to run. The commit refusal names the
+// same command to the person (`commitDenyMessage`) — change the two together.
+const PERSON_DOOR = [
+  'If a person decides this change must land anyway, they commit it with',
+  '`yad commit --manual --reason "<why>"` — their call, not the agent\'s. The check on the pull request',
+  'still fails it.',
+  '',
+];
+
+// The settings a guard decision reads. Non-strict on purpose: a hub.json that does not parse is a real
+// problem, but refusing every edit in the repo is not this hook's way of reporting it (`yad doctor`
+// says so properly).
+//
+// E122: when `product.json` and `hub.json` say different things, every other command refuses; the hook
+// cannot — it runs inside the agent's tool loop — so it GUARDS: the Product is verified when EITHER copy
+// says so. A drift must never disarm the guard; the worst it can do is refuse an edit a local Product
+// would have allowed, and the message then says why and what ends it.
+export function guardConfig(productRoot) {
+  const product = path.join(productRoot, PROJECT_FILES.productConfig);
+  const legacy = path.join(productRoot, PROJECT_FILES.productConfigLegacy);
+  if (!mirrorDrift(product, legacy)) return { productConfig: readJSON(productConfigPath(productRoot), null), drift: false };
+  const both = [readJSON(product, null), readJSON(legacy, null)];
+  return { productConfig: both.find(isVerifiedLedger) ?? both[0], drift: true };
+}
+
+const driftLine = (productRoot) =>
+  `note: ${path.join(productRoot, PROJECT_FILES.productConfig)} and ${PROJECT_FILES.productConfigLegacy} say different things, and one of them is verified, so this edit is guarded — run \`yad migrate\` to choose the copy to keep`;
+
 // What the agent is told when the edit is refused. Names the command that owns each transition —
 // the whole point of #171 was that the ledger write had no command behind it.
 export function denyMessage({ epic, rel, productRoot }) {
@@ -271,18 +301,19 @@ export function denyMessage({ epic, rel, productRoot }) {
     `[yad] Blocked: ${rel} is CI-owned gate state.`,
     '',
     'This Product runs in verified mode, where CI is the sole writer of the gate ledger. The `ledger-guard`',
-    'check rejects any non-bot commit that changes it, so this edit cannot reach the default branch —',
-    'it would fail the review PR/MR and have to be reverted.',
+    'check on the review PR/MR rejects any non-bot commit that changes it, so this edit would fail that',
+    'check and have to be reverted.',
     '',
     'Use the command that owns the transition instead:',
     `  author step done → review opened   yad gate open ${epic} <artifact>`,
     '  the full advance at merge          CI runs `yad gate ci --merged` — nothing to do locally',
-    `  a genuinely broken ledger          yad gate repair ${epic}`,
+    `  a genuinely broken ledger          yad gate repair ${epic} --push`,
     '',
     'Commit the ARTIFACT only (the .md you authored) and hand off to `yad-review-gate`; the ledger',
     'follows on merge.',
     '',
-    `hub: ${productRoot}   ·   override for one command: YAD_HOOK_DISABLE=1`,
+    ...PERSON_DOOR,
+    `product: ${productRoot}   ·   a person can skip this hook for one command: YAD_HOOK_DISABLE=1`,
   ].join('\n');
 }
 
@@ -297,38 +328,178 @@ export function indexDenyMessage({ rel, productRoot }) {
     'To read it as the files say it is now:   yad index --json',
     'To see whether the committed one is behind:   yad doctor',
     '',
-    `hub: ${productRoot}   ·   override for one command: YAD_HOOK_DISABLE=1`,
+    ...PERSON_DOOR,
+    `product: ${productRoot}   ·   a person can skip this hook for one command: YAD_HOOK_DISABLE=1`,
   ].join('\n');
 }
 
+// A Windows path some harnesses send in URL form: `/c:/Users/…`. Cursor has been reported sending exactly
+// that, and `path.resolve` reads it as `C:\c:\Users\…` — a path under no Product, so a ledger edit would
+// be allowed. The leading slash before a drive letter is dropped on Windows; everywhere else a path is
+// left as it came (E113).
+export const windowsPath = (p, platform = process.platform) => (platform === 'win32' && /^\/[A-Za-z]:[\\/]/.test(p) ? p.slice(1) : p);
+
 // The decision, with git injectable so the tests can drive every branch. Returns
 // `{ allow: true }` or `{ allow: false, message, epic, rel }`.
-export function ledgerGuardDecision(paths, { env = process.env, runner = run, payloadCwd = null } = {}) {
+//
+// `all` keeps going after the first refused path and returns every one of them in `hits` (E48). An
+// agent's tool call writes one file, so the first is the answer; a commit carries many, and a message
+// naming only the first would send the person round the refuse-unstage-retry loop once per file.
+// The message is then the caller's to build — `{ allow: false, hits }` with no `message`.
+export function ledgerGuardDecision(paths, { env = process.env, runner = run, payloadCwd = null, all = false } = {}) {
   if (env.YAD_HOOK_DISABLE) return { allow: true, skipped: 'YAD_HOOK_DISABLE' };
   if (!paths.length) return { allow: true };
   const base = baseDirFor(env, runner, payloadCwd);
   // One `ls-tree` per Product, not one per candidate path: a MultiEdit carries many paths and this runs
   // inside the agent's tool loop.
-  const seededByHub = new Map();
+  const seededByProduct = new Map();
+  const hits = [];
   for (const candidate of paths) {
-    const abs = path.resolve(base, candidate);
-    const productRoot = hubRootFor(abs);
+    const abs = path.resolve(base, windowsPath(candidate));
+    const productRoot = productRootFor(abs);
     if (!productRoot) continue;
-    // Non-strict on purpose: a hub.json that does not parse is a real problem, but refusing every
-    // edit in the repo is not this hook's way of reporting it (`yad doctor` says so properly).
-    const hub = readJSON(productConfigPath(productRoot), null);
-    if (!isVerifiedLedger(hub)) continue;
+    const { productConfig, drift } = guardConfig(productRoot);
+    if (!isVerifiedLedger(productConfig)) continue;
     const rel = path.relative(productRoot, abs).split(path.sep).join('/');
     const hit = protectedLedgerPath(rel);
     if (!hit) continue;
-    if (hit.kind === 'index') return { allow: false, epic: null, rel, message: indexDenyMessage({ rel, productRoot }) };
-    if (!seededByHub.has(productRoot)) seededByHub.set(productRoot, seededSlugs(productRoot, hub, runner));
-    const seeded = seededByHub.get(productRoot);
-    if (seeded === null) continue;                      // base unreadable — unknown allows
-    if (!seeded.has(fold(hit.epic))) continue;          // creation, not mutation (#162)
-    return { allow: false, epic: hit.epic, rel, message: denyMessage({ epic: hit.epic, rel, productRoot }) };
+    if (hit.kind !== 'index') {
+      if (!seededByProduct.has(productRoot)) seededByProduct.set(productRoot, seededSlugs(productRoot, productConfig, runner));
+      const seeded = seededByProduct.get(productRoot);
+      if (seeded === null) continue;                      // base unreadable — unknown allows
+      if (!seeded.has(fold(hit.epic))) continue;          // creation, not mutation (#162)
+    }
+    if (!all) {
+      const message = hit.kind === 'index' ? indexDenyMessage({ rel, productRoot }) : denyMessage({ epic: hit.epic, rel, productRoot });
+      return { allow: false, epic: hit.epic, rel, message: drift ? `${message}\n${driftLine(productRoot)}` : message };
+    }
+    hits.push({ ...hit, abs, productRoot, drift });
   }
-  return { allow: true };
+  return hits.length ? { allow: false, hits } : { allow: true };
+}
+
+// ---- the git pre-commit half (E48) ---------------------------------------------------------------
+//
+// The same rule as the harness hook, asked by git instead of by an agent: `yad hook ledger-guard
+// --staged` reads the files the commit is about to record and refuses the commit when one of them is a
+// CI-owned file the `ledger-guard` check in CI would refuse. It catches a PERSON's hand commit, which the
+// harness hook never sees. Installed per clone by `yad check --fix` as `.git/hooks/pre-commit` (see
+// `gitHookActions` in plan.mjs); verified mode only, exactly like the harness hook.
+//
+// PARITY WITH THE CI CHECK is the whole claim, so each rule below is one the CI script already has:
+//   - A MERGE commit passes. CI lists a commit's files with `git diff-tree`, which prints nothing for a
+//     merge, so CI never judges one. Without this, a `git pull` that merges the bot's ledger commits
+//     into a person's branch would be refused here while CI accepts it.
+//   - The yad-gate-sync BOT passes, matched the way CI's `trusted_bot` matches it (the name or email
+//     holds `yad-gate-sync`). CI then also checks the platform-Verified signature, which only the
+//     platform can answer — a commit that claims the name without it still fails there.
+//   - A DELETION counts: CI fails a deleted `state.json` (delete-then-re-seed would reset the carve-out).
+//   - A RENAME is two paths, the old and the new (`--no-renames`), as E114 settled for every changed list.
+// Known limit: `git commit --amend` is judged by what it changes against the commit it replaces — git does
+// not tell a pre-commit hook it is an amend. So amending a commit that ALREADY changed the ledger passes
+// here, and amending one to UNDO that change is refused; the message names the way through for the second.
+// The pull request's check judges both correctly.
+//
+// The list is read with `-z` and spawned directly: `run()` trims its output, which would cut a leading
+// space off the first name.
+export const GIT_BOT = 'yad-gate-sync';
+// The environment yad's OWN ledger commits run git with (`yad gate ci` / `gate sync`, `yad gate repair`).
+// They are the commands the refusal names, so the hook must not refuse them — the CI check never judges
+// them either: it runs on pull requests, and these commits land on the default branch.
+export const OWNING_COMMIT_ENV = () => ({ ...process.env, YAD_HOOK_DISABLE: '1' });
+function gitRaw(args, cwd) {
+  const r = spawnSync('git', args, { cwd, encoding: 'utf8', windowsHide: true });
+  return { ok: r.status === 0, stdout: r.stdout || '' };
+}
+export function stagedLedgerCandidates(cwd = process.cwd(), git = gitRaw) {
+  const top = git(['rev-parse', '--show-toplevel'], cwd);
+  if (!top.ok) return { paths: [], skipped: 'not inside a git repository' };
+  const root = top.stdout.replace(/\r?\n$/, '');
+  if (git(['rev-parse', '-q', '--verify', 'MERGE_HEAD'], root).ok) return { paths: [], skipped: 'a merge commit — the CI check does not judge merges either' };
+  const ident = git(['var', 'GIT_AUTHOR_IDENT'], root);
+  if (ident.ok && ident.stdout.includes(GIT_BOT)) return { paths: [], skipped: `the ${GIT_BOT} bot's commit` };
+  const names = git(['-c', 'core.quotePath=false', 'diff', '--cached', '--name-only', '--no-renames', '-z'], root);
+  if (!names.ok) return { paths: [], skipped: 'could not list the staged files' };
+  return { root, paths: names.stdout.split('\0').filter(Boolean).map((p) => path.join(root, p)) };
+}
+
+// What the person is told when the commit is refused. It names every refused file, how to take them
+// back out of the commit, the command that owns each change, and the door.
+//
+// THE DOOR IS HONEST ABOUT WHAT IT OPENS. `yad commit --manual --reason` (E49 — it sets
+// `YAD_HOOK_DISABLE=1` for its own `git commit` and records the reason as a `Ledger-Override:` trailer),
+// the bare `YAD_HOOK_DISABLE=1`, or git's own `--no-verify` lets the commit through on this machine, and
+// nothing more: the `ledger-guard` check still judges it on the pull request (and only there — a direct
+// push to an unprotected default branch meets no check, which is why the message says "pull request").
+// A door that implied more would be a lie about what protects the ledger.
+export function commitDenyMessage({ hits, top }) {
+  const from = (h) => path.relative(top, h.abs).split(path.sep).join('/');
+  const files = hits.map(from);
+  const epics = [...new Set(hits.filter((h) => h.kind !== 'index').map((h) => h.epic))];
+  const epic = epics.length === 1 ? epics[0] : '<epic>';
+  const index = hits.some((h) => h.kind === 'index');
+  const roots = [...new Set(hits.map((h) => h.productRoot))];
+  const quote = (f) => (/^[\w./@+-]+$/.test(f) ? f : `'${f.replace(/'/g, `'\\''`)}'`);
+  return [
+    `[yad] Commit refused: it changes ${files.length === 1 ? 'a file' : `${files.length} files`} only CI may change on this Product.`,
+    ...files.map((f) => `  ${f}`),
+    '',
+    'This Product runs in verified mode, where CI is the sole writer of the gate ledger and the Product',
+    'index. The `ledger-guard` check on a pull request rejects any commit that changes those files unless',
+    `it is a Verified commit by the ${GIT_BOT} bot, so this commit would fail that check.`,
+    '',
+    `Take ${files.length === 1 ? 'it' : 'them'} out of this commit (run from the top of the repo):`,
+    `  git restore --staged -- ${files.map(quote).join(' ')}`,
+    `and commit without \`-a\`, and without ${files.length === 1 ? 'that path' : 'those paths'} after \`git commit\`.`,
+    '',
+    'Then use the command that owns the change:',
+    ...(epics.length ? [
+      `  author step done → review opened   yad gate open ${epic} <artifact>`,
+      '  the full advance at merge          CI runs `yad gate ci --merged` — nothing to do locally',
+      `  a genuinely broken ledger          yad gate repair ${epic} --push`,
+    ] : []),
+    ...(index ? ['  the Product index                  CI rebuilds it at merge; read it with `yad index --json`'] : []),
+    '',
+    ...[...new Set(hits.filter((h) => h.drift).map((h) => h.productRoot))].map((r) => `${driftLine(r)}\n`),
+    'Amending a commit to UNDO a ledger change it made? `git commit --amend` is compared with the commit it',
+    'replaces, so this hook cannot tell. Run it as `YAD_HOOK_DISABLE=1 git commit --amend`; the check on the',
+    'pull request judges the result against its parent.',
+    'To commit anyway, with the reason recorded in the commit (it adds a `Ledger-Override:` line):',
+    '  yad commit --manual --reason "<why>" --type <type> -m "<subject>"   (add --force above 3 files)',
+    'The check on the pull request still fails it, and quotes the reason.',
+    `product: ${roots.join(', ')}`,
+  ].join('\n');
+}
+
+// The `--staged` entry point, for the git pre-commit hook. It never reads stdin: git gives a
+// pre-commit hook nothing there, and a caller with an open pipe would hang on it (the note at
+// `runLedgerGuardHook`). Exit 0 allows, exit 2 refuses; the wrapper git runs turns only a 2 into a
+// refusal, so a crash here allows (fail-open, as the harness hook does).
+// Git exports GIT_DIR (absolute, in a linked worktree), GIT_WORK_TREE and friends to a hook. The base
+// read runs `git -C <productRoot> ls-tree … -- epics`, and with GIT_DIR set git takes `-C`'s directory
+// as the top of the work tree — so a Product in a subfolder listed nothing, every epic read as a seed,
+// and the mutation was allowed. Git finds the repo from the directory alone, worktrees included.
+const REPO_ENV = /^GIT_(DIR|WORK_TREE|PREFIX|INDEX_FILE|COMMON_DIR|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES)$/;
+export const cleanGitRunner = (env = process.env) => {
+  const clean = Object.fromEntries(Object.entries(env).filter(([k]) => !REPO_ENV.test(k)));
+  return (cmd, args = [], opts = {}) => run(cmd, args, { ...opts, env: clean });
+};
+// What the hook would refuse in the staged commit: `{ root, hits }`, `hits` empty when it would allow.
+// `yad commit --manual` (E49) asks the same question, so an override is only recorded when there is
+// something to override.
+export function stagedLedgerHits({ env = process.env, cwd = process.cwd(), git = gitRaw, runner = cleanGitRunner(env) } = {}) {
+  const staged = stagedLedgerCandidates(cwd, git);
+  if (!staged.paths.length) return { root: staged.root, hits: [] };
+  const verdict = ledgerGuardDecision(staged.paths, { env, runner, payloadCwd: staged.root, all: true });
+  return { root: staged.root, hits: verdict.allow ? [] : verdict.hits };
+}
+export function runStagedLedgerGuard({ env = process.env, cwd = process.cwd(), git = gitRaw, runner = cleanGitRunner(env) } = {}) {
+  if (env.YAD_HOOK_DISABLE) return 0;
+  const { root, hits } = stagedLedgerHits({ env, cwd, git, runner });
+  if (!hits.length) return 0;
+  console.error(commitDenyMessage({ hits, top: root }));
+  process.exitCode = 2;
+  return 2;
 }
 
 // Read the harness payload off stdin. Absent, empty, or unparseable all mean "nothing to inspect" —

package/cli/index-command.mjs

@@ -13,9 +13,9 @@
 // It never commits: the index rides the commit that carries the change, like the ledger it summarizes.
 import { c, log, ok, info, warn, fail, hand, exists, emitJSON } from './lib.mjs';
 import path from 'node:path';
-import { productConfigPath, isVerifiedLedger, SCHEMA_VERSION } from './manifest.mjs';
+import { productConfigPath, isVerifiedLedger, SCHEMA_VERSION, settingsEditHint } from './manifest.mjs';
 import { loadProduct } from './gate.mjs';
-import { productGit, resolveDefaultBranch } from './hubcommit.mjs';
+import { productGit, resolveDefaultBranch } from './productcommit.mjs';
 import { buildIndex, writeIndex, indexFreshness, INDEX_FILE } from './product-index.mjs';
 import { printable } from './epic-state.mjs';
 
@@ -40,11 +40,11 @@ export async function runIndex(root, { json = false } = {}) {
   if (json) return emitJSON({ schemaVersion: SCHEMA_VERSION, ...built.index });
 
   log(c.bold('\nyad index'));
-  const { hub } = loadProduct(root);
+  const { productConfig } = loadProduct(root);
   const items = built.index.items;
   const unreadable = items.filter((i) => i.unreadable);
   const summary = `${items.length} work item${items.length === 1 ? '' : 's'}${unreadable.length ? `, ${unreadable.length} unreadable` : ''}`;
-  if (isVerifiedLedger(hub)) {
+  if (isVerifiedLedger(productConfig)) {
     const fresh = indexFreshness(root, built);
     info(`this Product's ledger is verified: CI rebuilds ${INDEX_FILE} when it records a merge on the default branch, and a local write could not be committed — nothing written`);
     if (fresh.state === 'current') ok(`${INDEX_FILE} is current (${summary})`);
@@ -59,10 +59,10 @@ export async function runIndex(root, { json = false } = {}) {
   }
   const git = productGit(root);
   const branch = git('rev-parse', '--abbrev-ref', 'HEAD').stdout;
-  const defaultBranch = resolveDefaultBranch(git, hub);
+  const defaultBranch = resolveDefaultBranch(git, productConfig);
   if (branch !== defaultBranch) {
     fail(`on '${branch}', not the default branch '${defaultBranch}' — ${INDEX_FILE} is written on the default branch only, so a branch never carries it`);
-    hand(`switch to '${defaultBranch}' and re-run (set default_branch in .sdlc/product.json if '${defaultBranch}' is wrong); \`yad index --json\` prints it here without writing`);
+    hand(`switch to '${defaultBranch}' and re-run (if '${defaultBranch}' is wrong, set default_branch in ${settingsEditHint(root)}); \`yad index --json\` prints it here without writing`);
     process.exitCode = 1;
     return;
   }