yadflow 3.16.3 → 3.17.0

package/CHANGELOG.md

@@ -1,3 +1,22 @@
+# [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/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/plan.mjs

@@ -5,10 +5,11 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { err } from './errors.mjs';
 import {
-  asset, exists, copyDir, copyFile, dirMatches, sameContent, readJSON, readJSONStrict, writeJSON, fileSha,
+  asset, exists, copyDir, copyFile, dirMatches, sameContent, readJSON, readJSONStrict, writeJSON, fileSha, warn,
 } from './lib.mjs';
 import {
-  VERSION, SKILLS, IDE_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES,
+  VERSION, SKILLS, IDE_TARGETS, IDE_OPENCODE_DIR, MODULE_FILES, wiringFor, HUB_WIRING, PROJECT_FILES, isBridgeHub,
+  HOOK_WIRING, HOOK_SETTINGS, HOOK_TOOL_MATCHER, HOOK_COMMAND, HOOK_COMMAND_LEGACY,
   LEGACY_SKILLS, REMOVED_SKILLS, LEGACY_MARKER, LEGACY_REPO_FILES, LEGACY_HUB_FILES, MANAGED_LEDGER, BACKUP_SUFFIX,
 } from './manifest.mjs';
 
@@ -441,7 +442,7 @@ export function legacyRepoActions(root, repo) {
 
 export function legacyHubActions(root) {
   const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig));
-  if (!hub?.platform || !(hub.bridge_enabled === true || hub.bridge === true)) return [];
+  if (!isBridgeHub(hub)) return [];
   const wiring = [...HUB_WIRING.common, ...(HUB_WIRING[hub.platform] || [])];
   return legacyFileActions('hub', root, LEGACY_HUB_FILES[hub.platform], wiring);
 }
@@ -460,14 +461,168 @@ export function repoActions(root, repo) {
 export function hubActions(root) {
   const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig));
   // `bridge_enabled` is the canonical flag (the documented hub-config schema); older setup versions
-  // wrote `bridge` — accept an explicit true in either spelling, wire nothing otherwise.
-  if (!hub?.platform || !(hub.bridge_enabled === true || hub.bridge === true)) return [];
+  // wrote `bridge` — `isBridgeHub` accepts an explicit true in either spelling, and is the one
+  // predicate the CLI, the wiring, and the ledger hook all read (#186). Wire nothing otherwise.
+  if (!isBridgeHub(hub)) return [];
   const ledger = readManagedLedger(root);
   return [...HUB_WIRING.common, ...(HUB_WIRING[hub.platform] || [])].map((w) =>
     wiredFileAction('hub', w.dest, asset(w.src), path.join(root, w.dest), { root, exec: !!w.exec, ledger }),
   );
 }
 
+// ---- harness hooks (#171) --------------------------------------------------------------------
+// The desired hook entry, in the shape a harness reads it.
+export const hookEntry = () => ({
+  matcher: HOOK_TOOL_MATCHER,
+  hooks: [{ type: 'command', command: HOOK_COMMAND }],
+});
+
+// Ours is a hook command EXACTLY equal to one we have written — the current spelling or a
+// documented past one. Never "the entry at index N", never "the entry with our matcher", and
+// deliberately never a substring test: `includes('hooks/ledger-guard.sh')` would also claim a team's
+// own wrapper at `.claude/hooks/ledger-guard.sh` and silently rewrite it to ours, on the `outdated`
+// path that takes no backup. Matching exactly means the worst case is a second entry (the guard runs
+// twice — harmless) instead of someone else's hook disappearing.
+const OWNED_COMMANDS = new Set([HOOK_COMMAND, ...HOOK_COMMAND_LEGACY]);
+const OURS = (h) => typeof h?.command === 'string' && OWNED_COMMANDS.has(h.command);
+
+// Additive merge of our PreToolUse entry into a parsed settings object. Returns
+// `{ settings, changed }`; `settings` is a new object, so a caller can compare without mutating.
+// A matcher the team NARROWED is left alone (only the command is normalised) — the same respect for
+// a local edit that `modified` gives a managed file. Widening it back would silently undo their choice.
+export function mergeHookSettings(input) {
+  const settings = { ...(input && typeof input === 'object' && !Array.isArray(input) ? input : {}) };
+  const hooks = { ...(settings.hooks && typeof settings.hooks === 'object' && !Array.isArray(settings.hooks) ? settings.hooks : {}) };
+  const pre = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse.map((e) => ({ ...e })) : [];
+  let changed = false;
+  let found = false;
+  for (const entry of pre) {
+    if (!Array.isArray(entry.hooks)) continue;
+    entry.hooks = entry.hooks.map((h) => {
+      if (!OURS(h)) return h;
+      found = true;
+      if (h.command === HOOK_COMMAND && h.type === 'command') return h;
+      changed = true;
+      return { ...h, type: 'command', command: HOOK_COMMAND };
+    });
+  }
+  if (!found) { pre.push(hookEntry()); changed = true; }
+  hooks.PreToolUse = pre;
+  settings.hooks = hooks;
+  return { settings, changed };
+}
+
+// Does the installed entry still select at least one file-editing tool? The merge deliberately
+// leaves a narrowed `matcher` alone — it is the team's — but a matcher narrowed to nothing (blanked,
+// or pointed at `Bash`) means the guard is installed and never fires, which must not read as healthy.
+// The matcher is a regex the harness tests tool names against, so test it as one; an invalid regex
+// cannot fire either.
+export function hookMatcherFires(settings) {
+  const pre = settings?.hooks?.PreToolUse;
+  if (!Array.isArray(pre)) return false;
+  const tools = HOOK_TOOL_MATCHER.split('|');
+  for (const entry of pre) {
+    if (!Array.isArray(entry?.hooks) || !entry.hooks.some(OURS)) continue;
+    let re;
+    try { re = new RegExp(entry.matcher ?? ''); } catch { continue; }
+    // An empty matcher matches every tool name in Claude Code, so it is armed, not blank.
+    if (!entry.matcher || tools.some((t) => re.test(t))) return true;
+  }
+  return false;
+}
+
+// One harness's settings file as an action. Not a `wiredFileAction`: there is no template to compare
+// bytes against — the file belongs to the team and we own exactly one entry inside it. So it is also
+// deliberately NOT recorded in `.sdlc/managed.json` (recordManagedWrites only records a dest that
+// byte-matches its src); the marker above is its provenance instead.
+function hookSettingsAction(root, ide, relDest) {
+  const dest = path.join(root, relDest);
+  const raw = exists(dest) ? fs.readFileSync(dest, 'utf8') : null;
+  let parsed = null;
+  let unreadable = false;
+  if (raw !== null) {
+    try { parsed = JSON.parse(raw); } catch { unreadable = true; }
+    if (!unreadable && (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))) unreadable = true;
+  }
+  // Scope is the IDE target, item the file under it, so the report reads `.claude/settings.json`
+  // once — the same scope the skills for that target are grouped under.
+  //
+  // `paths` is EMPTY, unlike every other action's: it is the pathspec `yad update --push` stages, and
+  // every other entry in that allowlist is a file yad wrote in full. This one the team co-owns, so
+  // staging it wholesale would sweep their unrelated working-tree edits into a `chore(yad-update)`
+  // commit pushed straight to the default branch, bypassing review. The entry is theirs to commit.
+  const base = { scope: ide, item: path.basename(relDest), root, paths: [] };
+  // A settings file we cannot READ is never rewritten — not even by `--overwrite-local`.
+  //
+  // For a managed file, `--overwrite-local` restores the shipped template, which is coherent. Here
+  // there is no template: only the parse failed, and everything the file holds — permissions, env,
+  // other hooks — is the team's. Synthesizing a replacement from an empty object would discard all of
+  // it, and `--overwrite-local` is a generic recovery command someone runs for an unrelated drifted
+  // gate script. So this reports `modified` forever and writes nothing; the human fixes the JSON.
+  //
+  // Warned at PLAN time, not from apply(): reconcile only reaches a `modified` action's apply() with
+  // `--overwrite-local`, so a plain `yad check --fix` would print nothing but the generic drift
+  // hand — "replace them with `yad update --overwrite-local`" — advice that can never clear this,
+  // since this action deliberately writes nothing. The specific reason has to surface either way.
+  if (unreadable) {
+    warn(`${relDest} does not parse — the ledger guard cannot be wired; fix the JSON, then re-run \`yad check --fix\``);
+    return { ...base, status: 'modified', apply: () => {} };
+  }
+  const { changed } = mergeHookSettings(parsed);
+  return {
+    ...base,
+    status: raw === null ? 'missing' : changed ? 'outdated' : 'ok',
+    // Re-read at apply() time rather than closing over the merge computed above: setup and reconcile
+    // build every action before applying any, so the file may have been written since.
+    //
+    // A no-op when the entry is already there. `yad setup` re-applies with force:true, which reaches
+    // an `ok` action — and an unconditional write would reformat a team's hand-formatted (but valid)
+    // settings.json to writeJSON's style on every re-run. Nothing is lost, but the diff noise lands
+    // in a committed file we only own one entry of.
+    //
+    // The re-read is STRICT. `readJSON`'s swallow-and-default would turn a file that became
+    // unparseable between plan and apply into `{}` and write the team's whole config away — with no
+    // backup, since that is the branch above. Re-check instead, and refuse the same way.
+    apply: () => {
+      if (!changed && raw !== null) return;
+      if (exists(dest)) {
+        let current;
+        try { current = JSON.parse(fs.readFileSync(dest, 'utf8')); } catch { /* unreadable — refused below */ }
+        if (!current || typeof current !== 'object' || Array.isArray(current)) {
+          warn(`${relDest} does not parse — left untouched; fix the JSON, then re-run \`yad check --fix\``);
+          return;
+        }
+        writeJSON(dest, mergeHookSettings(current).settings);
+        return;
+      }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      writeJSON(dest, mergeHookSettings({}).settings);
+    },
+  };
+}
+
+// Harness-hook wiring on the hub: the guard script plus, per IDE target that defines a hook protocol,
+// the entry that invokes it. Bridge-gated exactly like `hubActions` — with no bridge the ledger is
+// locally owned, the hand-edit the authoring skills describe is CORRECT, and a guard would be wrong.
+export function hookActions(root, ideTargets = ideTargetsFor(root)) {
+  const hub = readJSON(path.join(root, PROJECT_FILES.hubConfig));
+  if (!isBridgeHub(hub)) return [];
+  const ledger = readManagedLedger(root);
+  const actions = HOOK_WIRING.map((w) =>
+    wiredFileAction('hub', w.dest, asset(w.src), path.join(root, w.dest), { root, exec: !!w.exec, ledger }),
+  );
+  for (const ide of safeIdeTargetsFor(root, ideTargets)) {
+    const relDest = HOOK_SETTINGS[ide];
+    if (relDest) actions.push(hookSettingsAction(root, ide, relDest));
+  }
+  // The two halves must land TOGETHER, so `missing` is relabelled `new` — the same relabel a new
+  // first-party skill gets, and for the same reason: `yad update` (--scope=changed) excludes only
+  // the literal 'missing'. Without it, an upgrade on a hub that already has a settings.json applies
+  // the entry (`outdated`) while skipping the script (`missing`), leaving every file edit firing a
+  // PreToolUse command that does not exist — a hook error per edit, and no guarding at all.
+  return actions.map(asNewSkill);
+}
+
 // Every email the verified-commits gate should accept as a known author: the hub roster's `email`
 // (or `emails`) fields plus hub.json's free-form `verified_authors` list. Lower-cased, deduped,
 // sorted — deterministic so the generated file is drift-checkable like any wired file.

package/cli/reconcile.mjs

@@ -12,7 +12,7 @@ const readFileSafe = (p) => { try { return fs.readFileSync(p, 'utf8'); } catch {
 import { preflightGuardReadiness } from './hubcommit.mjs';
 import { VERSION, PROJECT_FILES, MANAGED_LEDGER, BACKUP_SUFFIX } from './manifest.mjs';
 import {
-  moduleActions, repoActions, hubActions, authorsActions,
+  moduleActions, repoActions, hubActions, hookActions, authorsActions,
   legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
   ideTargetStateFor, recordManagedWrites,
 } from './plan.mjs';
@@ -48,7 +48,7 @@ export async function reconcile(root, { fix = false, scope = 'all', force = fals
   //     and purge of skills removed in a later release ('removed': delete the lingering install) ---
   const actions = [
     ...moduleActions(root, ideTargets), ...legacyModuleActions(root, ideTargets), ...removedModuleActions(root, ideTargets),
-    ...hubActions(root), ...legacyHubActions(root),
+    ...hubActions(root), ...legacyHubActions(root), ...hookActions(root, ideTargets),
     ...authorsActions(root, registry.repos),
   ];
   if (ideState.needsRepair) {

package/cli/setup.mjs

@@ -8,7 +8,7 @@ import {
 } from './lib.mjs';
 import { VERSION, IDE_TARGETS, PROJECT_FILES, DESIGN_TOOLS, DESIGN_PRIMARY, TESTING_TOOLS, TESTING_PRIMARY, LEARNING_TOOLS, LEARNING_PRIMARY } from './manifest.mjs';
 import {
-  moduleActions, repoActions, hubActions, authorsActions,
+  moduleActions, repoActions, hubActions, hookActions, authorsActions,
   legacyModuleActions, removedModuleActions, legacyRepoActions, legacyHubActions,
   safeIdeTargetsFor, detectedIdeTargetStateFor, recordManagedWrites,
 } from './plan.mjs';
@@ -734,6 +734,15 @@ export async function runSetup(root, opts = {}) {
     wired.push(...hubWiring);
   }
   applyActions(legacyHubActions(root), { force: true });
+  // the hub, locally: the harness ledger guard, so an agent is refused the CI-owned ledger write at
+  // the moment it tries it rather than by a failed pipeline later (#171). Bridge-gated like the CI
+  // above — with no bridge the ledger is locally owned and the guard would be wrong.
+  const hookWiring = hookActions(root, ideTargets);
+  if (hookWiring.length) {
+    log(`  ${c.bold('hub')} ${c.dim('(agent ledger guard)')}`);
+    applyActions(hookWiring, { force: true });
+    wired.push(...hookWiring);
+  }
   // After every write to a managed path has landed (including the legacy renames), so the recorded
   // sha is the file's final state.
   recordManagedWrites(wired);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yadflow",
-  "version": "3.16.3",
+  "version": "3.17.0",
   "description": "Yadflow — the gated, team, multi-repo SDLC: author → review → build with a PR-driven review gate and a zero-dependency `yad` CLI (setup, gate, commit, open-pr, ship, repo, thread, reconcile). A BMAD module + 38 yad-* skills.",
   "type": "module",
   "author": "AbdelRahman Nasr",

package/skills/yad-checks/SKILL.md

@@ -65,6 +65,11 @@ and GitLab CI. This step is **by hand** in Phase 3 — run the gates with the sk
     default branch the guard is absolute again. Runs in `yad-hub-checks`
     alongside `verified-commits` (which waives the allowlist for the bot but still requires its
     signature). See `yad-hub-bridge`.
+  - `templates/hooks/ledger-guard.sh` → **hub-only** agent guardrail, active **only in bridge mode**
+    (the same `isBridgeHub` predicate). Not a CI gate: it is a **harness hook** that refuses an agent's
+    edit to the CI-owned ledger at the moment it is attempted and names `yad gate open` instead — the
+    local half of `checks/ledger-guard.sh` (#171). Installed to `<hub>/hooks/ledger-guard.sh` with the
+    `PreToolUse` entry in `.claude/settings.json`. Fails OPEN; see "Step 2b" below.
   - `templates/github/yad-verified-commits.yml` + `templates/gitlab/yad-verified-commits.gitlab-ci.yml`
     → the standalone hub-side verified-commits CI (installed by `yad check --fix` with the hub wiring)
   - `templates/github/yad-checks.yml` → installs to `.github/workflows/yad-checks.yml` (marked `# yad-managed: yad-checks`)
@@ -142,6 +147,43 @@ Commit the wiring on the repo's default branch (it is shared infrastructure, not
 **The hub is wired the same way.** `repo: hub` wires the hub repo itself (platform from `.sdlc/hub.json`)
 with a hub-flavored gate set — see "Wiring the hub" in `references/check-gates.md`.
 
+**The hub also gets the agent guardrail** (see below): `templates/hooks/ledger-guard.sh` →
+`<hub>/hooks/ledger-guard.sh`, plus the `PreToolUse` entry in `.claude/settings.json`. `yad setup`
+and `yad check --fix` install both; there is nothing to do by hand.
+
+### Step 2b — the agent guardrail (harness hooks, bridge mode only)
+The CI gates speak at CI time. That is too late for one failure the field kept hitting (#171): in
+bridge mode the gate ledger is **CI-owned**, so an agent that hand-edits
+`epics/*/.sdlc/state.json` only finds out twenty minutes later, from a `ledger-guard` FAIL with
+nothing connecting cause to effect — and by then the write has to be reverted before the review
+PR/MR can go green.
+
+`hooks/ledger-guard.sh` is the local half of that same rule. It runs as a **harness hook** before a
+file-editing tool call and refuses the write up front, naming the command that owns the transition
+(`yad gate open`), so the agent corrects itself instead of failing a pipeline.
+
+- **Harness-agnostic by contract.** The script only locates `yad` and hands the tool payload to
+  `yad hook ledger-guard`: **stdin** is a JSON tool-call payload, **exit 0** allows, **exit 2**
+  denies with the reason on stderr. Claude Code's `PreToolUse` protocol is exactly that, so no
+  adapter logic is needed; another harness needs only those two exit codes.
+- **Same scope as the CI gate**, deliberately: guarded are `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json`
+  and `epics/*/reviews/*.md` (at the gate's own glob depth, which spans `/`); exempt are
+  `contract-lock.json`, `change.json`, and every artifact. A **new** epic's ledger is exempt too —
+  creation, not mutation (#162), decided by listing the epics the **base ref** carries (an
+  `origin/` ref, case-folded slugs), never by looking at the working tree.
+- **A no-op without the bridge.** There the ledger is locally owned and the hand-edit the authoring
+  skills describe is *correct*, so nothing is wired and nothing is blocked.
+- **It fails OPEN** — no `yad`, no hub, an unreadable config, an unparseable payload all ALLOW, with
+  a note on stderr. `ledger-guard` in CI fails *closed* and remains the authority. `YAD_HOOK_DISABLE=1`
+  skips one command.
+- **Known gaps** (both caught by the CI gate instead): a `Bash` tool call (`sed -i epics/…`) is not
+  intercepted — matching it would mean parsing shell; and the hook arms sessions **rooted at the
+  hub**, since a harness reads hooks from its own project root — a session opened at the workspace
+  above the hub never loads the hub's `.claude/settings.json`.
+
+`yad doctor` reports the guardrail as `agent ledger guard wired` / `not wired` on a bridge hub.
+See `references/check-gates.md` §"The agent guardrail".
+
 ### Step 3 — `run` (run the gates now)
 From inside the repo, run each gate against `base` and report PASS/FAIL per gate:
 ```

package/skills/yad-checks/references/check-gates.md

@@ -366,6 +366,112 @@ title + the code task template), so a PR that changes the hub's own workflows/ch
 `templates/gitlab/yad-hub-checks.gitlab-ci.yml` → `.gitlab/ci/yad-hub-checks.yml` + its one include
 line). Code repos run the same three with `--profile code` inside the main `yad-checks` workflow.
 
+## The agent guardrail (`templates/hooks/ledger-guard.sh` + `yad hook ledger-guard`)
+
+Not a CI gate — a **harness hook**, and the only piece of yadflow that runs *inside* an agent's tool
+loop. It exists because of the gap #171 reported: `checks/ledger-guard.sh` is correct and blocking,
+but it speaks at CI time. An agent that hand-edits `epics/*/.sdlc/state.json` in bridge mode learns
+twenty minutes later, from a FAIL with nothing connecting cause to effect, and by then the write must
+be reverted before the review PR/MR can go green.
+
+**Contract** — deliberately not Claude-Code-shaped:
+
+| | |
+|---|---|
+| 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 `.claude/settings.json` wires it with no adapter logic. Any harness that can run a
+command and read those two exit codes can use the same script.
+
+**Layering.** `hooks/ledger-guard.sh` is only the adapter: it locates `yad` (`$YAD_BIN` → the hub's
+`node_modules/yadflow` → `PATH` → `npx --no-install`) and passes the payload to `yad hook
+ledger-guard`, which holds the decision. So the wiring never hard-codes an install path, and the
+logic is unit-tested (`cli/hook.mjs`, `cli/test.mjs`) instead of living in bash.
+
+**Scope — identical to the CI gate, on purpose**, down to the details that decide the hard cases:
+
+- Guarded: `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` and `epics/*/reviews/*.md`.
+  Exempt: `contract-lock.json` (artifact-side), `change.json`, every artifact.
+- **Depth matches the gate's globs.** Its arms are bash `case` patterns, and a bash `*` spans `/`, so
+  `epics/EP-a/nested/.sdlc/state.json` is guarded there — and here. Being stricter locally would let
+  a path through that CI blocks.
+- **The seed carve-out reads the base ref, not the working tree** (#162): the epics whose
+  `state.json` the base carries are listed once with `ls-tree`, and an epic absent from that list is
+  a creation. Never a `<rev>:<path>` probe — that spec resolves from the repository top level and
+  `-C` does not re-anchor it, so a hub in a subdirectory of its repo would miss every time and the
+  guard would allow everything, silently.
+- **The base is an `origin/` ref** — `origin/<default_branch>`, then the remote's published default,
+  then `origin/main`, the gate's own order. Never a bare local branch: `git fetch` does not
+  fast-forward one, so a stale trunk would report a merged epic's ledger as absent and wave a real
+  mutation through. If none resolves, the answer is *unknown* and unknown allows.
+- **Slugs are case-folded**, as 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 would let a mutation be laundered as
+  a creation.
+- Bridge-gated by the same `isBridgeHub` predicate the CLI and the wiring read (#186): without the
+  bridge the ledger is locally owned, the hand-edit the authoring skills describe is correct, and
+  nothing is wired or blocked.
+
+**It fails OPEN, and that asymmetry is the design.** No `yad` on PATH, no hub above the edited path,
+an unreadable `hub.json`, an unparseable payload, a `yad` that errors — every one of them ALLOWS,
+with a note on stderr. A local guardrail that failed closed would brick an agent's ability to edit
+anything the moment an install went sideways. The CI gate fails **closed** and is what actually
+protects the ledger; this only shortens the feedback loop. `YAD_HOOK_DISABLE=1` skips one command.
+
+**Known gaps** — both fall through to the CI gate, which is why it stays the authority:
+
+- A `Bash` tool call (`sed -i epics/…`) is not intercepted; matching it would mean parsing shell for
+  write intent.
+- The hook arms sessions **rooted at the hub**. A harness loads hooks from its own project root, so a
+  session opened at the *workspace* (`project/`, with the hub at `project/product/`) never reads the
+  hub's `.claude/settings.json` and the guard does not fire there — even though the decision itself
+  resolves the hub correctly from any path. In that layout, open the session at the hub, or copy the
+  entry into the workspace's own settings (the command's `$CLAUDE_PROJECT_DIR` would then need the
+  hub-relative path).
+
+**Wiring** (installed by `yad setup` / `yad check --fix`, bridge hubs only):
+
+| Path | Owner |
+|---|---|
+| `<hub>/hooks/ledger-guard.sh` | fully managed — drift-checked and recorded in `.sdlc/managed.json` like any gate script |
+| `<hub>/.claude/settings.json` | **one entry**, merged additively into `hooks.PreToolUse`. See below. |
+
+The settings file is the team's, so the rules around that one entry are deliberately conservative:
+
+- **Ownership is an exact command match** — the current spelling or a documented past one — never a
+  substring. A team keeping its own wrapper at `.claude/hooks/ledger-guard.sh` would otherwise have
+  their hook silently rewritten to ours, on the `outdated` path that takes no backup. Matching
+  exactly means the worst case is a second entry (the guard runs twice, harmlessly).
+- **The command is quoted** (`"$CLAUDE_PROJECT_DIR/hooks/ledger-guard.sh"`) because the harness runs
+  it through a shell: unquoted, a project path containing a space word-splits and the guard is
+  silently off while `check` and `doctor` still call it wired.
+- **A file that does not parse is never rewritten** — not even by `--overwrite-local`. For a managed
+  file that flag restores a shipped template; here there is none, and everything in the file is the
+  team's. It reports `modified` until a human fixes the JSON.
+- **A `matcher` the team narrowed is left as they set it** — but `yad doctor` warns when it no longer
+  selects any file-editing tool, so an installed-but-dead guard cannot pass for healthy.
+- **It is never staged by `yad update --push`.** Every other path in that allowlist is a file yad
+  wrote in full; this one would sweep the team's unrelated edits into a `chore` commit pushed
+  straight to the default branch.
+- **Both halves land together.** The script and the entry ride `yad update` as one: applying the
+  entry without the script it points at would fire a missing command on every file edit.
+
+`.claude` is the only IDE target wired: it is the only one with a defined hook protocol. Other
+targets get the script, and the contract above is what they would wire by hand.
+
+`yad doctor` reports the guard on a bridge hub, and distinguishes the three states that matter — it
+reads the same persisted `ideTargets` the wiring reads, so every gap it names is one the command it
+names can actually close:
+
+| State | Report | Remedy |
+|---|---|---|
+| script + entry present, matcher live | `agent ledger guard wired` | — |
+| either half absent | `not wired: <what>` | `yad check --fix` |
+| present but the matcher no longer selects a file-editing tool | `installed but its matcher no longer selects file edits` | restore the matcher — it is wired and never fires |
+| the settings file does not parse | `cannot be wired — … does not parse` | fix the JSON by hand; yad never rewrites one it cannot parse, so nothing else clears it |
+
 ## Running by hand (Phase 3 is manual)
 
 From inside the code repo, against the PR/MR base (e.g. `master`). For the gates that take one, the

package/skills/yad-checks/templates/hooks/ledger-guard.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# ledger-guard HARNESS HOOK — the local half of the CI gate of the same name (#171).
+#
+# The gate ledger is CI-owned in bridge mode: `checks/ledger-guard.sh` rejects any non-bot commit
+# that changes `epics/*/.sdlc/{state,approvals,comments,hub-prs}.json` or `epics/*/reviews/*.md`.
+# This hook says so at the moment an agent tries the edit, instead of twenty minutes later in a
+# failed pipeline, and names the command that owns the transition (`yad gate open`).
+#
+# This file is only the ADAPTER. It locates `yad` and hands the tool-call payload to
+# `yad hook ledger-guard`, which holds the decision — so the wiring never hard-codes an install path
+# and the logic stays testable. The contract it passes through:
+#
+#   stdin   the harness's tool-call payload as JSON (optional)
+#   exit 0  allow
+#   exit 2  deny, reason on stderr
+#
+# Wired for Claude Code as a `PreToolUse` hook in `.claude/settings.json` (`yad check --fix` writes
+# that entry). Any harness that can run a command and read those two exit codes can use it.
+#
+# FAIL-OPEN: if no `yad` can be found, this ALLOWS and says why on stderr. A guardrail that blocked
+# every edit the moment an install went sideways would be worse than the problem. The CI gate fails
+# CLOSED and is what actually protects the ledger.
+set -uo pipefail
+
+# The hub root is this script's grandparent — hooks/ledger-guard.sh — so the resolution below does
+# not depend on the harness's working directory.
+HOOK_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+HUB_ROOT="$(dirname -- "$HOOK_DIR")"
+
+# Resolution order, cheapest and most specific first: an explicit override, then the copy installed
+# in this hub, then whatever is on PATH, then a network-free npx. `--no-install` matters — a hook
+# runs on every tool call and must never pause an agent to download a package.
+CMD=()
+_yad_bin="${YAD_BIN:-}"
+if [ -n "${_yad_bin//[[:space:]]/}" ]; then
+  # Split deliberately: YAD_BIN is commonly an interpreter + script ("node /path/to/yad.mjs").
+  # The whitespace-stripped test above matters: a YAD_BIN of only spaces would leave CMD empty, and
+  # macOS's bash 3.2 treats "${CMD[@]}" on an empty array as an unbound variable under `set -u` —
+  # aborting the script with a confusing 127 instead of taking one of the branches below.
+  read -r -a CMD <<< "$_yad_bin"
+elif [ -f "$HUB_ROOT/node_modules/yadflow/bin/yad.mjs" ] && command -v node >/dev/null 2>&1; then
+  CMD=(node "$HUB_ROOT/node_modules/yadflow/bin/yad.mjs")
+elif command -v yad >/dev/null 2>&1; then
+  CMD=(yad)
+elif command -v npx >/dev/null 2>&1; then
+  CMD=(npx --no-install yadflow)
+else
+  echo "  • yad hook: no \`yad\` on PATH and none installed in $HUB_ROOT — allowing (install yadflow to re-arm the ledger guard)" >&2
+  exit 0
+fi
+
+# Belt and braces for bash 3.2's empty-array-is-unbound rule: every branch above sets CMD, but an
+# unexpanded array under `set -u` would abort the script rather than allow, so check before using it.
+if [ "${#CMD[@]}" -eq 0 ]; then
+  echo "  • yad hook: could not resolve a \`yad\` to run — allowing" >&2
+  exit 0
+fi
+
+# Run it rather than `exec`, so the exit code can be mapped. ONLY an explicit deny (2) blocks: a
+# `yad` that is present but cannot run — an `npx --no-install` with no yadflow to find, a crash, a
+# broken install — must not read as a refusal. Fail-open is the whole stance of this hook; the CI
+# gate is what fails closed.
+"${CMD[@]}" hook ledger-guard "$@"
+rc=$?
+[ "$rc" -eq 2 ] && exit 2
+if [ "$rc" -ne 0 ]; then
+  echo "  • yad hook: \`${CMD[*]} hook ledger-guard\` exited $rc — allowing (run \`yad doctor\` to check the install)" >&2
+fi
+exit 0

package/skills/yad-hub-bridge/SKILL.md

@@ -87,7 +87,9 @@ Install the hub CI that turns the human **merge** into a `yad gate ci` run, with
 writer** of the ledger. There is no pre-merge CI write — during review the platform PR/MR is the
 source of truth (native approvals + threads). On merge, CI re-reads approvals from the platform,
 advances the step, and flips the artifact `status:` on the **default branch** (the only place CI ever
-commits). Also install the `ledger-guard` check (yad-checks) so humans cannot commit gate-state files.
+commits). Also install the `ledger-guard` check (yad-checks) so humans cannot commit gate-state files,
+and its local counterpart `hooks/ledger-guard.sh` — the harness hook that refuses an **agent** the
+same write at the moment it tries it, instead of letting it surface as a CI failure later (#171).
 Revoke-on-change is enforced at merge: on **GitHub** in code (an approval whose commit ≠ the merged
 head is dropped — no setting needed); on **GitLab** it has no per-approval commit SHA, so enabling the
 platform's **"remove all approvals when commits are added to the source branch"** is **required** for

package/skills/yad-review-gate/SKILL.md

@@ -188,7 +188,9 @@ PR only — against the `review/<epic>/<artifact>` branch, which must already ex
 records this skill describes. The skill's
 job is the human half: presenting the artifact, helping the owner address comments, and narrating the
 gate. Local `yad gate sync` is advisory in bridge mode (reads the platform, prints status, writes
-nothing); a human must never commit gate-state files (the `ledger-guard` check rejects it). The single
+nothing); a human must never commit gate-state files (the `ledger-guard` check rejects it, and the
+`hooks/ledger-guard.sh` harness hook refuses an agent the edit up front, naming `yad gate open`
+instead — see `yad-checks`). The single
 exception is an epic's **seed** — no CI path can create a ledger, so a brand-new epic's `.sdlc/` rides
 its **first** review PR/MR, cut from the authoring branch (creation, not mutation, #162).