yadflow 3.16.3 → 3.17.1

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [3.17.1](https://github.com/abdelrahmannasr/yadflow/compare/v3.17.0...v3.17.1) (2026-09-02)
+
+# [3.17.0](https://github.com/abdelrahmannasr/yadflow/compare/v3.16.3...v3.17.0) (2026-08-12)
+
+
+### Bug Fixes
+
+* **check:** leave an already-wired settings.json byte-identical ([1d50ed4](https://github.com/abdelrahmannasr/yadflow/commit/1d50ed4b173f7de2350344fc5facb1de19bd9c61))
+* **check:** stop the hook wiring from damaging a file the team owns ([a348c99](https://github.com/abdelrahmannasr/yadflow/commit/a348c997ba3b87406addef4e5868bdd14406fa49))
+* **doctor:** give an unparseable settings file its own advice ([0862875](https://github.com/abdelrahmannasr/yadflow/commit/08628750a3c8e8642075db0fc0712d217dacdeb4))
+* **doctor:** report the ledger guard against what actually arms it ([a1ec4ba](https://github.com/abdelrahmannasr/yadflow/commit/a1ec4bafec8441b6bf8c0515bf4f1bd68cb00ef7))
+* **hook:** read the seeded set the way the CI gate reads it ([38cd206](https://github.com/abdelrahmannasr/yadflow/commit/38cd206fc94256782a074a309fe6dbc2ae3ce135)), closes [#171](https://github.com/abdelrahmannasr/yadflow/issues/171)
+* **hook:** resolve the command before suppressing the update notice ([44d8768](https://github.com/abdelrahmannasr/yadflow/commit/44d87683abbc8acff02b011b6ce47d140e8075d3))
+* **hook:** survive an empty command array on bash 3.2 ([7fd6984](https://github.com/abdelrahmannasr/yadflow/commit/7fd698412d8229f312f62c2a21f299dad445700b))
+
+
+### Features
+
+* **check:** install and report the agent ledger guardrail ([8251d9f](https://github.com/abdelrahmannasr/yadflow/commit/8251d9f92740690ca7b3e27a0280f999593793f3))
+* **hook:** refuse an agent the CI-owned ledger write, at the edit ([15291ce](https://github.com/abdelrahmannasr/yadflow/commit/15291ce2d73167cebeb5aba52920bdb078d6d0aa))
+
 ## [3.16.3](https://github.com/abdelrahmannasr/yadflow/compare/v3.16.2...v3.16.3) (2026-08-12)
 
 

package/README.md

@@ -89,6 +89,10 @@ In one pass it produces:
   push-on-main **`yad-update-guard`** (which re-checks any direct-to-default commit — e.g. from
   `yad update --push` — with just `verified-commits` + `commit-message`), shipped as CI-agnostic bash
   under `checks/`.
+- **An agent guardrail** on a bridge hub — `hooks/ledger-guard.sh`, a harness hook that refuses an
+  agent the CI-owned gate-ledger write at the moment it tries it and names the command that owns the
+  transition, instead of letting it surface as a CI failure twenty minutes later. Harness-agnostic
+  (stdin payload, exit 0 allows / 2 denies) and fails open — the CI gate stays the authority.
 - **PR/MR templates** and an opt-in CodeRabbit config.
 
 Your first `yad-epic` seeds the `epics/EP-<slug>/` ledger — state, approvals, and the contract lock —

package/bin/yad.mjs

@@ -22,6 +22,7 @@ import { syncStatuses } from '../cli/artifact-status.mjs';
 import { runThread, runReconcile } from '../cli/thread.mjs';
 import { runReport } from '../cli/report.mjs';
 import { runUsage } from '../cli/usage.mjs';
+import { runLedgerGuardHook } from '../cli/hook.mjs';
 import { maybeNotifyUpdate } from '../cli/update-notice.mjs';
 
 const HELP = `${c.bold('yad')} — setup, review-gate & build helpers for the SDLC Workflow module  ${c.dim('v' + VERSION)}
@@ -51,6 +52,11 @@ ${c.bold('Setup & maintenance')}
   yad report [-m <text>]   File a bug in the yadflow repo with auto-scrubbed diagnostics
                        (no paths/hosts/repo names/logins/flag values). Also offered
                        automatically after an unexpected failure. YAD_NO_REPORT=1 disables.
+  yad hook ledger-guard    ${c.dim('harness-invoked, not typed')} — refuse an agent's edit to the
+                       CI-owned gate ledger in bridge mode and name the command that owns
+                       the transition. Reads a tool-call payload on stdin (or --path <p>);
+                       exit 0 allows, exit 2 denies with the reason on stderr. Wired into
+                       .claude/settings.json by setup / check --fix. YAD_HOOK_DISABLE=1 skips.
 
 ${c.bold('Reviewer roster')}
   yad roster list                      Show every member + their roles per scope (hub + each repo)
@@ -179,7 +185,7 @@ ${c.bold('Environment')}
   YAD_NO_UPDATE_NOTIFIER=1   Silence the "update available" notice (also off in CI)
   YAD_NO_REPORT=1            Never offer to file a bug report after a failure`;
 
-const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason', '--retro-ship', '--merge-commit']);
+const VALUE_FLAGS = new Set(['--dir', '--type', '--message', '--task', '--ai', '--risk', '--repo', '--platform', '--base', '--title', '--scope', '--branch', '--pr', '--epic', '--name', '--email', '--roles', '--team', '--body', '--out', '--since', '--until', '--member', '--format', '--reason', '--retro-ship', '--merge-commit', '--path']);
 
 function parseArgs(argv) {
   const o = { _: [], dir: process.cwd(), fix: false, force: false, scope: 'all' };
@@ -254,6 +260,18 @@ async function main() {
     case 'doctor':
       await runDoctor(o.dir, { json: o.json });
       break;
+    // Harness-invoked, not typed by a human: a tool-call payload arrives on stdin and the exit code
+    // is the verdict (0 allow, 2 deny). See cli/hook.mjs for the contract.
+    case 'hook': {
+      const [, action] = o._;
+      if (action !== 'ledger-guard') {
+        log(c.red(`unknown hook: ${action ?? '(none)'} (ledger-guard)`));
+        process.exitCode = 1;
+        break;
+      }
+      runLedgerGuardHook({ paths: o.path ? [o.path] : [] });
+      break;
+    }
     case 'report':
       await runReport(o.dir, { message: o.message });
       break;
@@ -415,7 +433,11 @@ main()
   // the readline handle open so the process never exits.
   .finally(async () => {
     try {
-      await maybeNotifyUpdate();
+      // Never on `yad hook`: it runs on every agent tool call, and its stderr is the channel the
+      // block reason travels on — an update banner there would land in front of a model.
+      // Resolved the way main() resolves it, NOT from argv[2]: that is the first raw argument, so
+      // `yad --dir <path> hook ledger-guard` puts `--dir` there and the banner slips through.
+      if (parseArgs(process.argv.slice(2))._[0] !== 'hook') await maybeNotifyUpdate();
     } catch { /* the notice is never worth failing or hanging a command over */ } finally {
       closePrompts();
     }

package/cli/commit.mjs

@@ -38,7 +38,7 @@ export function buildCommitMessage({ type, subject, task, contractChange = false
   return parts.join('\n');
 }
 
-// feat/EP-istifta-inquiries-S01-T01-create-inquiry -> EP-istifta-inquiries-S01-T01
+// feat/EP-checkout-S01-T01-create-order -> EP-checkout-S01-T01
 export function taskFromBranch(branch = '') {
   const m = branch.match(/(.+-S\d+-T\d+)(?:-|$)/i);
   return m ? m[1].replace(/^[a-z]+\//i, '') : null;

package/cli/doctor.mjs

@@ -5,7 +5,8 @@
 import path from 'node:path';
 import fs from 'node:fs';
 import { c, log, ok, info, warn, fail, hand, run, has, exists, readJSON, readJSONStrict } from './lib.mjs';
-import { VERSION, PROJECT_FILES, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS } from './manifest.mjs';
+import { VERSION, PROJECT_FILES, DESIGN_TOOLS, TESTING_TOOLS, LEARNING_TOOLS, HOOK_SETTINGS, HOOK_TOOL_MATCHER, isBridgeHub } from './manifest.mjs';
+import { mergeHookSettings, hookMatcherFires, ideTargetsFor } from './plan.mjs';
 import { loadLedger, epicRoot, isValidEpicId, epicLineage, resolveThread, stateInvariants, contractSurfaceHash, artifactHash } from './epic-state.mjs';
 import { loadDebt } from './thread.mjs';
 import { gitHead, insideWorkspace } from './setup.mjs';
@@ -150,6 +151,59 @@ export function projectChecks(checks, root) {
     }
   }
 
+  // The harness ledger guard (#171). Only meaningful in bridge mode: there the ledger is CI-owned and
+  // an agent's hand-edit is always rejected later by `ledger-guard`, so the local hook that refuses it
+  // up front should be installed. Without the bridge the ledger is locally owned and the hand-edit the
+  // authoring skills describe is correct — nothing to report, so the check is silent rather than `ok`.
+  const hubForHooks = readJSON(hubPath, null);
+  if (isBridgeHub(hubForHooks)) {
+    const unwired = [];
+    const broken = [];
+    if (!exists(path.join(root, 'hooks', 'ledger-guard.sh'))) unwired.push('hooks/ledger-guard.sh');
+    // The SAME target list `hookActions` wires — the persisted `ideTargets`, not "does the directory
+    // exist". Keyed on the directory, a project whose targets are `['.agents']` but which also has a
+    // stray `.claude/` would be told to run `yad check --fix` forever, while that command builds no
+    // action for `.claude` and correctly reports "already up to date". Never name a remedy that
+    // cannot reach the thing being reported.
+    const unreadable = [];
+    for (const ide of ideTargetsFor(root)) {
+      const relDest = HOOK_SETTINGS[ide];
+      if (!relDest) continue;
+      const settingsPath = path.join(root, relDest);
+      // A file that exists but does not parse is its OWN report. `readJSON` returns null for both
+      // "absent" and "broken", and null merges as "not wired" — which would send the human to
+      // `yad check --fix`, a command that (correctly) refuses to rewrite a settings file it cannot
+      // parse. The warning would then repeat forever with advice that can never apply.
+      // Read ONCE and reuse: parsing the same file twice lets `unreadable` and the merge check
+      // describe different content if it changes in between.
+      let settings = null;
+      if (exists(settingsPath)) {
+        let parsed;
+        try { parsed = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch { /* reported below */ }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) { unreadable.push(relDest); continue; }
+        settings = parsed;
+      }
+      if (mergeHookSettings(settings).changed) { unwired.push(relDest); continue; }
+      // Present is not the same as armed. The entry's matcher is the team's to narrow (the merge
+      // deliberately leaves it alone), but one that no longer selects any file-editing tool means
+      // nothing is intercepted — and reporting that as `ok` is how a disarmed guard passes for
+      // healthy until a ledger edit fails in CI.
+      if (!hookMatcherFires(settings)) broken.push(relDest);
+    }
+    if (unreadable.length) {
+      check(checks, 'hooks', 'project', 'warn', `agent ledger guard cannot be wired — ${unreadable.join(', ')} does not parse [YAD-STATE-001]`,
+        'fix the JSON by hand, then run `yad check --fix` — yad never rewrites a settings file it cannot parse, so nothing else can clear this');
+    } else if (unwired.length) {
+      check(checks, 'hooks', 'project', 'warn', `agent ledger guard not wired: ${unwired.join(', ')}`,
+        'run `yad check --fix` — until then an agent can hand-edit the CI-owned ledger and only find out when the review PR/MR fails');
+    } else if (broken.length) {
+      check(checks, 'hooks', 'project', 'warn', `agent ledger guard installed but its matcher no longer selects file edits: ${broken.join(', ')}`,
+        `restore the matcher to \`${HOOK_TOOL_MATCHER}\` — as it stands the hook is wired but never fires`);
+    } else {
+      check(checks, 'hooks', 'project', 'ok', 'agent ledger guard wired (hooks/ledger-guard.sh)');
+    }
+  }
+
   // design.json: parse + shape + tool + MCP confirmation (absent is the normal markdown-only default —
   // pre-feature projects have none, so silence rather than warn when the file does not exist).
   const designPath = path.join(root, PROJECT_FILES.designConfig);

package/cli/gate.mjs

@@ -7,7 +7,7 @@ import path from 'node:path';
 import {
   c, log, ok, info, warn, hand, fail, note, readJSONStrict, writeJSON, run, pushWithRebase,
 } from './lib.mjs';
-import { PROJECT_FILES } from './manifest.mjs';
+import { PROJECT_FILES, isBridgeHub } from './manifest.mjs';
 import {
   epicRoot, loadLedger, findReviewStep, artifactBase, artifactHash, gatePredicate,
   advanceState, markInReview, isEscalated, parseReviewBranch, artifactFromBase,
@@ -113,11 +113,10 @@ export function loadHub(root) {
 // merge advances the step). Recorded per-project in hub.json by `yad setup`.
 const isSolo = (hub) => !!(hub && (hub.solo === true || hub.review_gate?.solo === true));
 
-// Bridge mode: a platform AND the gate-sync CI explicitly enabled (the canonical `bridge_enabled`,
-// or the older `bridge`). ONLY then is CI the sole ledger writer — so `gate open`/`sync` stay
-// hands-off. A platform without the bridge (no gate-sync CI installed) keeps the local write path,
-// or reviews could never advance. Mirrors plan.mjs hubActions.
-const isBridge = (hub) => !!(hub?.platform && (hub.bridge_enabled === true || hub.bridge === true));
+// Bridge mode: CI is the sole ledger writer, so `gate open`/`sync` stay hands-off. The predicate is
+// defined once in manifest.mjs (`isBridgeHub`) and shared with plan.mjs's wiring and the ledger
+// hook, so no two readers can disagree about who owns the ledger (#186).
+const isBridge = isBridgeHub;
 
 // requireEngagement (config `hub.review.requireEngagement`): when on, the predicate counts only
 // approvals carrying a verified engagement signal. Soft-off by default — a bare approve still counts

package/cli/hook.mjs

@@ -0,0 +1,224 @@
+// `yad hook ledger-guard` — the harness-side half of the ledger rule (#171).
+//
+// In BRIDGE mode the gate ledger is CI-owned: `templates/checks/ledger-guard.sh` rejects any non-bot
+// commit that changes `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or `epics/*/reviews/*.md`.
+// That gate is the authority, but it only speaks at CI time — an agent that hand-edits `state.json`
+// learns twenty minutes later, from a failed pipeline with nothing connecting cause to effect. This
+// hook says the same thing at the moment of the edit, and names the command that owns the transition.
+//
+// HARNESS-AGNOSTIC CONTRACT — the reason this is a `yad` subcommand and not Claude-Code-shaped code:
+//   stdin   a harness tool-call payload as JSON (optional; `--path <p>` works instead)
+//   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; another harness needs only
+// the same two exit codes.
+//
+// FAIL-OPEN, deliberately. No hub, 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 fs from 'node:fs';
+import path from 'node:path';
+import { note, readJSON, run } from './lib.mjs';
+import { PROJECT_FILES, isBridgeHub } from './manifest.mjs';
+
+// The CI-owned files, exactly as `templates/checks/ledger-guard.sh` lists them. NOT `contract-lock.json`
+// (artifact-side: the architect commits it with the architecture) and NOT `change.json` — both are a
+// human's to write, and both are exempt in the gate too.
+const LEDGER_FILES = new Set(['state.json', 'approvals.json', 'comments.json', 'hub-prs.json']);
+
+// `epics/<epic>/.sdlc/<ledger>.json` or `epics/<epic>/reviews/<name>.md` → { epic, rel }; else null.
+// Takes a hub-relative POSIX path.
+//
+// Depth is matched the way the CI gate matches it, not more strictly. Its arms are bash `case`
+// globs — `epics/*/.sdlc/state.json` — and a bash glob's `*` spans `/`, so the gate ALSO rejects
+// `epics/EP-a/nested/.sdlc/state.json`. Requiring exactly four segments here would have let a path
+// through locally that CI blocks, in a guard whose whole claim is that its scope is the gate's.
+// The slug is the second segment either way (the gate's `${f#epics/}` / `${_slug%%/*}`).
+export function protectedLedgerPath(rel) {
+  if (!rel.startsWith('epics/')) return null;
+  const epic = rel.slice('epics/'.length).split('/')[0];
+  if (!epic || epic === '.' || epic === '..') return null;
+  const ledgers = [...LEDGER_FILES].map((f) => f.replace('.', '\\.')).join('|');
+  if (new RegExp(`/\\.sdlc/(?:${ledgers})$`).test(rel)) return { epic, rel, kind: 'state' };
+  if (/\/reviews\/.*\.md$/.test(rel)) return { epic, rel, kind: 'review' };
+  return null;
+}
+
+// Every path a tool call would write. Covers the shapes harnesses actually send: a single
+// `file_path` (Edit/Write), `notebook_path` (NotebookEdit), and a `MultiEdit`-style `edits[]` array.
+// An unrecognised payload yields nothing, which allows — see the fail-open note above.
+export function payloadPaths(payload) {
+  const out = [];
+  const input = payload?.tool_input;
+  if (!input || typeof input !== 'object') return out;
+  for (const key of ['file_path', 'notebook_path', 'path']) {
+    if (typeof input[key] === 'string' && input[key]) out.push(input[key]);
+  }
+  if (Array.isArray(input.edits)) {
+    for (const edit of input.edits) if (typeof edit?.file_path === 'string' && edit.file_path) out.push(edit.file_path);
+  }
+  return [...new Set(out)];
+}
+
+// The hub a path belongs to: the nearest ancestor holding `.sdlc/hub.json`.
+//
+// Resolved from the PATH, never from the session. The documented layout puts code repos BESIDE the
+// hub (`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) {
+  let dir = path.dirname(path.resolve(abs));
+  for (;;) {
+    if (fs.existsSync(path.join(dir, PROJECT_FILES.hubConfig))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+// Where a RELATIVE path in the payload is anchored. Only used to make such a path absolute, so the
+// hub walk-up above has somewhere to start.
+export function baseDirFor(env = process.env, runner = run) {
+  if (env.CLAUDE_PROJECT_DIR) return env.CLAUDE_PROJECT_DIR;
+  const top = runner('git', ['rev-parse', '--show-toplevel']);
+  return top.ok && top.stdout ? top.stdout : process.cwd();
+}
+
+// Case-folded, exactly as the CI gate folds (`tr '[:upper:]' '[:lower:]'`).
+const fold = (s) => s.toLowerCase();
+
+// The base ref, resolved in the CI gate's own order: `origin/<default_branch>`, then the remote's
+// published default, then `origin/main`. Returns null when none resolves.
+//
+// ORIGIN refs only — never a bare local branch. A local trunk is whatever the developer last pulled,
+// 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(hubRoot, hub, runner = run) {
+  const cfg = hub?.default_branch || '';
+  const head = runner('git', ['-C', hubRoot, '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;
+    if (runner('git', ['-C', hubRoot, 'rev-parse', '--verify', '--quiet', `${base}^{commit}`]).ok) return base;
+  }
+  return null;
+}
+
+// Every epic whose ledger is already on the base ref, case-folded. The #162 carve-out, mirrored from
+// the gate's `is_seeding`: no CI path can CREATE a ledger (`gate ci` only advances an existing chain,
+// at merge, on the default branch), so a brand-new epic's seed is legitimately a human's write and
+// rides the first review PR/MR. Mutating a ledger that is already on the base is what only the bot
+// may do.
+//
+// Read with `ls-tree` from the hub, never with a `<rev>:<path>` probe: a rev:path spec is always
+// resolved from the repository TOP LEVEL and `-C` does not re-anchor it, so a hub sitting in a
+// subdirectory of its repo (a monorepo, or a workspace that is itself a repo) would miss on every
+// probe and the guard would allow everything, silently. `ls-tree` run with `-C hubRoot` takes a
+// cwd-relative pathspec and prints cwd-relative paths, so both halves stay hub-relative.
+//
+// Slugs are FOLDED because the gate folds them: on a case-insensitive filesystem `epics/ep-x/…` and
+// `epics/EP-X/…` are the same file, so a byte-exact compare lets a mutation be laundered as a
+// creation — the vector the gate's own header names.
+//
+// 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(hubRoot, hub, runner = run) {
+  const base = resolveHookBase(hubRoot, hub, runner);
+  if (!base) return null;
+  const tree = runner('git', [
+    '-C', hubRoot, '-c', 'core.quotePath=false', 'ls-tree', '-r', '--name-only', '-z', base, '--', 'epics',
+  ]);
+  if (!tree.ok) return null;
+  const slugs = new Set();
+  for (const p of tree.stdout.split('\0')) {
+    const m = /^epics\/([^/]+)\/\.sdlc\/state\.json$/.exec(p);
+    if (m) slugs.add(fold(m[1]));
+  }
+  return slugs;
+}
+
+
+// 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, hubRoot }) {
+  return [
+    `[yad] Blocked: ${rel} is CI-owned gate state.`,
+    '',
+    'This hub runs in bridge mode, where CI is the sole writer of the gate ledger. The `ledger-guard`',
+    '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.',
+    '',
+    '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}`,
+    '',
+    'Commit the ARTIFACT only (the .md you authored) and hand off to `yad-review-gate`; the ledger',
+    'follows on merge.',
+    '',
+    `hub: ${hubRoot}   ·   override for one command: YAD_HOOK_DISABLE=1`,
+  ].join('\n');
+}
+
+// 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 } = {}) {
+  if (env.YAD_HOOK_DISABLE) return { allow: true, skipped: 'YAD_HOOK_DISABLE' };
+  if (!paths.length) return { allow: true };
+  const base = baseDirFor(env, runner);
+  // One `ls-tree` per hub, not one per candidate path: a MultiEdit carries many paths and this runs
+  // inside the agent's tool loop.
+  const seededByHub = new Map();
+  for (const candidate of paths) {
+    const abs = path.resolve(base, candidate);
+    const hubRoot = hubRootFor(abs);
+    if (!hubRoot) 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(path.join(hubRoot, PROJECT_FILES.hubConfig), null);
+    if (!isBridgeHub(hub)) continue;
+    const rel = path.relative(hubRoot, abs).split(path.sep).join('/');
+    const hit = protectedLedgerPath(rel);
+    if (!hit) continue;
+    if (!seededByHub.has(hubRoot)) seededByHub.set(hubRoot, seededSlugs(hubRoot, hub, runner));
+    const seeded = seededByHub.get(hubRoot);
+    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, hubRoot }) };
+  }
+  return { allow: true };
+}
+
+// Read the harness payload off stdin. Absent, empty, or unparseable all mean "nothing to inspect" —
+// never an error, and never a block.
+function readPayload() {
+  try {
+    if (process.stdin.isTTY) return null;
+    const raw = fs.readFileSync(0, 'utf8').trim();
+    if (!raw) return null;
+    return JSON.parse(raw);
+  } catch {
+    note('yad hook: could not read a JSON tool payload on stdin — allowing');
+    return null;
+  }
+}
+
+// The `yad hook ledger-guard` entry point. `paths` (from `--path`) is additive to the payload, so
+// a harness with no JSON contract can call the guard directly.
+export function runLedgerGuardHook({ paths = [] } = {}) {
+  // Only read stdin when there is nothing else to go on. `readFileSync(0)` blocks until EOF, and a
+  // caller that passes `--path` (the documented stdin-free alternative) may well have inherited an
+  // open pipe from a long-lived parent — `isTTY` is false there, so the TTY guard does not trip and
+  // the hook would hang forever. A hang is strictly worse for an agent than a block.
+  const payload = paths.length ? null : readPayload();
+  const all = [...new Set([...payloadPaths(payload), ...paths])];
+  const verdict = ledgerGuardDecision(all);
+  if (verdict.allow) return 0;
+  console.error(verdict.message);
+  process.exitCode = 2;
+  return 2;
+}

package/cli/manifest.mjs

@@ -158,6 +158,18 @@ export const PROJECT_FILES = {
   version: '.sdlc/cli-version.json',
 };
 
+// Bridge mode: a platform AND the gate-sync CI explicitly enabled (the canonical `bridge_enabled`,
+// or the older `bridge`). ONLY then is CI the sole ledger writer — so `gate open`/`sync` stay
+// hands-off, `hubActions` wires the hub CI, and the ledger guards (the `ledger-guard` check gate and
+// the `yad hook ledger-guard` harness hook) are live. A platform without the bridge keeps the local
+// write path, or reviews could never advance.
+//
+// ONE definition, imported by every JS caller. Copies that drift are how #186 happened — a hub that
+// one reader called bridge and another called file-only had no permitted ledger writer at all.
+// `templates/checks/ledger-guard.sh` re-implements it in bash because the check gates are standalone
+// by design; that copy is the only one, and its header says so.
+export const isBridgeHub = (hub) => !!(hub?.platform && (hub.bridge_enabled === true || hub.bridge === true));
+
 // ---- `yad commit` conventions (mirror skills/sdlc/config.yaml `build`) ----
 // Conventional-commit types (config.yaml commit_subject_style).
 export const COMMIT_TYPES = ['feat', 'fix', 'docs', 'refactor', 'test', 'perf', 'build', 'ci', 'chore', 'revert'];
@@ -275,3 +287,31 @@ export const HUB_WIRING = {
     { src: 'skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml', dest: '.gitlab/ci/yad-update-guard.yml' },
   ],
 };
+
+// Harness hooks: the LOCAL half of the ledger rule, installed on the hub beside the CI gates and
+// active under the same bridge predicate (#171). Kept out of `HUB_WIRING` because a hook is not a
+// CI gate — it is advisory, fails open, and its adapter (below) is per-harness, not per-platform.
+export const HOOK_WIRING = [
+  { src: 'skills/yad-checks/templates/hooks/ledger-guard.sh', dest: 'hooks/ledger-guard.sh', exec: true },
+];
+
+// Per-harness adapter config: which IDE target gets a hook entry written, and where.
+// `.claude` alone — it is the only supported target with a defined hook protocol (`.agents`,
+// `.zencoder` and `.opencode` carry skills only). The others simply get the script and no wiring;
+// the contract in the script header is what they would wire by hand.
+export const HOOK_SETTINGS = { '.claude': '.claude/settings.json' };
+// The tools that can write a file. A `Bash` call (`sed -i epics/…`) is deliberately NOT matched:
+// matching it would mean parsing shell, and CI's ledger-guard already fails closed on the result.
+export const HOOK_TOOL_MATCHER = 'Edit|Write|MultiEdit|NotebookEdit';
+// `$CLAUDE_PROJECT_DIR` so the entry works whatever the harness's working directory is — QUOTED,
+// because the harness runs this through a shell: unquoted, a project path containing a space
+// word-splits, the command is not found, and the guard is silently off while `check` and `doctor`
+// both still report it wired.
+export const HOOK_COMMAND = '"$CLAUDE_PROJECT_DIR/hooks/ledger-guard.sh"';
+// Spellings a previous yadflow wrote for the SAME hook. An installed entry matching one of these is
+// ours to normalise; anything else is the team's, even if it names a similar path. Never widen this
+// to a substring test — a team keeping its own wrapper at `.claude/hooks/ledger-guard.sh` would have
+// their hook silently rewritten to ours.
+export const HOOK_COMMAND_LEGACY = Object.freeze([
+  '$CLAUDE_PROJECT_DIR/hooks/ledger-guard.sh', // 3.16.x, pre-quoting
+]);

package/cli/next.mjs

@@ -46,7 +46,7 @@ const actionFor = (root, id) => ({
   lineageKind: epicLineage(root, id).kind,
 });
 
-// EP-istifta-inquiries-S03 → S03 (the compact lane label for the roll-up). Falls back to the full id.
+// EP-checkout-S03 → S03 (the compact lane label for the roll-up). Falls back to the full id.
 const shortStory = (s) => (s && s.match(/S\d+$/i)?.[0]) || s || '(story)';
 
 // Every per-repo lane across the build, flattened with its story id attached.