yadflow 3.16.2 → 3.17.0

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/platform.mjs

@@ -378,6 +378,94 @@ export function branchExists(cwd, branch) {
   return remote.code === 2 ? false : null;
 }
 
+// ---- default branch -----------------------------------------------------------------------------
+// The REMOTE's own default branch, asked of the platform. This is the branch the platform (and the
+// tooling that keys off it — CodeRabbit's auto-review eligibility, branch protection, "compare"
+// defaults) considers the trunk, so it is the only authoritative answer to "what should a PR target?".
+// `runner` is injectable so the read is unit-testable without shelling out (mirrors searchIssues).
+// Returns { ok, branch, reason }; never throws — an absent/unauthenticated CLI is just `ok:false`.
+// It is a READ of the remote's own config, so it costs one API round-trip; callers that only need a
+// base branch get it folded into resolveBaseBranch below rather than calling this twice.
+export function platformDefaultBranch(platform, { cwd, runner = run } = {}) {
+  // No `platformReady` probe: an absent CLI already surfaces as a failed spawn, and skipping the probe
+  // keeps the read a pure function of `runner` (so a test never depends on gh/glab being installed).
+  if (!cliFor(platform)) return { ok: false, reason: 'no platform (github/gitlab) to ask' };
+  // This is a live network round-trip on a SYNCHRONOUS command path, so it carries the same ceiling
+  // branchExists documents for its own remote probe: "cannot ask" has to be fast, or a black-holed
+  // host / wedged credential helper turns `yad open-pr` into a hang. A timeout surfaces as ok:false,
+  // which the caller already treats as "the platform could not tell me".
+  const opts = { cwd, timeout: 10_000 };
+  if (platform === 'gitlab') {
+    // `:id` is glab's own placeholder for the project the cwd resolves to (same form as readPrGitLab).
+    const r = runner('glab', ['api', 'projects/:id'], opts);
+    if (!r.ok) return { ok: false, reason: r.stderr || 'glab api projects/:id failed' };
+    try {
+      const branch = JSON.parse(r.stdout)?.default_branch;
+      return branch ? { ok: true, branch } : { ok: false, reason: 'project has no default_branch' };
+    } catch { return { ok: false, reason: 'unreadable glab api response' }; }
+  }
+  const r = runner('gh', ['repo', 'view', '--json', 'defaultBranchRef', '-q', '.defaultBranchRef.name'], opts);
+  if (!r.ok) return { ok: false, reason: r.stderr || 'gh repo view failed' };
+  return r.stdout ? { ok: true, branch: r.stdout } : { ok: false, reason: 'gh returned no defaultBranchRef' };
+}
+
+// The branch a PR/MR should target, resolved rather than assumed (issue #168: open-pr hardcoded
+// 'main', so every task PR on a `staging`-trunk repo was mis-based — and CodeRabbit, which decides
+// auto-review eligibility at PR-OPEN time from the base, silently skipped every one of them).
+//
+// Order — most explicit first, and configuration outranks the remote: the same
+// configuration-outranks-the-remote order `yad repo sync` (repo.mjs) and the contract-check gate use,
+// though only this chain has a platform rung — they stop at the local `origin/HEAD`:
+//   1 flag        — an explicit --base; the human said so
+//   2 registry    — the repo's `default_branch` in .sdlc/repos.json
+//   3 hub         — hub.json's `default_branch`, for a PR against the product hub itself
+//   4 platform    — what the remote says (see platformDefaultBranch)
+//   5 origin-head — local `refs/remotes/origin/HEAD`, the same read repo.mjs/hubcommit.mjs use.
+//                   Deliberately NOT `ls-remote`: see branchExists above for why a network probe on
+//                   this path is a hang hazard.
+//   6 fallback    — 'main'
+//
+// `probe` decides WHEN the platform is asked, and exists because the two callers want different things:
+//   true  (default) — ask up front, so `platformDefault` rides along even when an earlier rung won.
+//                     `yad open-pr` needs that to warn about a base that is not the remote's trunk,
+//                     and it is about to shell out to gh/glab anyway.
+//   false           — ask only if the config rungs all miss. A caller that just wants a base (the
+//                     review companion) would otherwise pay a live round-trip — up to the full 10s
+//                     timeout on a slow/unreachable host — for a `platformDefault` it discards.
+// Either way the probe runs AT MOST once. Returns { base, source, platformDefault }; with `probe:false`
+// and an early rung winning, `platformDefault` is null because it was never asked, not because the
+// platform had no answer.
+export function resolveBaseBranch(platform, {
+  cwd, explicit = null, meta = null, hub = null, runner = run, probe = true,
+} = {}) {
+  let platformDefault = null;
+  let asked = false;
+  const askPlatform = () => {
+    if (asked) return platformDefault;
+    asked = true;
+    const remote = platformDefaultBranch(platform, { cwd, runner });
+    platformDefault = remote.ok ? remote.branch : null;
+    return platformDefault;
+  };
+  if (probe) askPlatform();
+  const originHead = () => {
+    const r = runner('git', ['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], { cwd });
+    return r.ok && r.stdout ? r.stdout.replace(/^origin\//, '') : null;
+  };
+  const chain = [
+    ['flag', explicit],
+    ['registry', meta?.default_branch],
+    ['hub', hub?.default_branch],
+    ['platform', askPlatform],
+    ['origin-head', originHead],
+  ];
+  for (const [source, value] of chain) {
+    const branch = typeof value === 'function' ? value() : value;
+    if (branch) return { base: branch, source, platformDefault };
+  }
+  return { base: 'main', source: 'fallback', platformDefault };
+}
+
 // ---- create a PR/MR -----------------------------------------------------------------------------
 // `assignees` = the committer/PR-opener (always set, so the PR is owned by whoever pushed it);
 // `reviewers` = the scope's reviewers + domain-owners (computed by reviewersForScopes). On GitHub an

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/review.mjs

@@ -12,6 +12,7 @@ import { updateShip } from './ledger.mjs';
 import { epicRoot } from './epic-state.mjs';
 import {
   detectPlatform, readPr, mapApprovers, getPrBody, editPrBody, postComment, prNumberFromUrl,
+  resolveBaseBranch,
 } from './platform.mjs';
 import { upsertTrailerBlock, nudgeMessage, parseEngagement } from './companion.mjs';
 import { sequenceDiff } from './walkthrough.mjs';
@@ -40,12 +41,16 @@ function platformOf(root, repoRoot, meta) {
 // Build (but don't print) the back-half grounding bundle. Shared by `context` and `walkthrough` so the
 // pair walkthrough adds an ordered stop-list on top of the exact same grounding the companion uses.
 // Returns { error } on a bad --repo, else { bundle, repoRoot, base }.
-function contextBundle(root, { repo, dir, pr } = {}) {
+function contextBundle(root, { repo, dir, pr, runner = run } = {}) {
   const rr = resolveRepo(root, { repo, dir });
   if (rr.error) return { error: rr.error };
   const { repoRoot, meta } = rr;
   const platform = platformOf(root, repoRoot, meta);
-  const base = meta?.default_branch || 'main';
+  // Same resolution as `yad open-pr` (#168): without it a repo whose trunk is not `main` grounded the
+  // companion on the wrong diff range — or on a branch that does not exist at all. `probe: false`
+  // because this caller only wants the base: a configured `default_branch` must answer locally and
+  // instantly, never behind a live gh/glab round-trip that could stall for the full timeout.
+  const { base } = resolveBaseBranch(platform, { cwd: repoRoot, meta, runner, probe: false });
   const bundle = {
     repo: meta?.name || null,
     repoRoot,
@@ -66,8 +71,8 @@ function contextBundle(root, { repo, dir, pr } = {}) {
 
 // `yad review context --repo <r> --pr <n>` — print the grounding bundle the companion uses to generate
 // the trailer / cards and run the chat over the CODE diff (grounded in the repo code-map + the PR).
-export async function reviewContext(root, { repo, dir, pr } = {}) {
-  const r = contextBundle(root, { repo, dir, pr });
+export async function reviewContext(root, { repo, dir, pr, runner = run } = {}) {
+  const r = contextBundle(root, { repo, dir, pr, runner });
   if (r.error) { fail(r.error); process.exitCode = 1; return; }
   log(JSON.stringify(r.bundle, null, 2));
   return r.bundle;
@@ -78,7 +83,7 @@ export async function reviewContext(root, { repo, dir, pr } = {}) {
 // first). The CLI sequences deterministically; the skill (yad-pair-review) walks the stops, generates
 // the per-stop briefing + Socratic question, and runs the two-way session. No LLM here, no ledger write.
 export async function reviewWalkthrough(root, { repo, dir, pr, runner = run } = {}) {
-  const r = contextBundle(root, { repo, dir, pr });
+  const r = contextBundle(root, { repo, dir, pr, runner });
   if (r.error) { fail(r.error); process.exitCode = 1; return; }
   const { bundle, repoRoot, base } = r;
   const diff = runner('git', ['-C', repoRoot, 'diff', `${base}...HEAD`]);

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.2",
+  "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/sdlc/module-help.csv

@@ -20,8 +20,8 @@ SDLC Workflow,yad-implement,Implement Task,IM,"Build-half Step B: with the dev l
 SDLC Workflow,yad-checks,Check Gates,CK,"Build-half Step C: wire and run the production-safety CI gates on a code repo (and product hub) — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (signed + roster-known authors), and the pattern gates commit-message / pr-title / pr-template (profile-aware code|hub). CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire|run} {base: target branch},3-build,yad-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/yad-checks.yml .gitlab-ci.yml
 SDLC Workflow,yad-pr-template,PR/MR Template,PT,"Build-half Step D: detect a code repo's platform and commit the matching PR/MR template (.github/pull_request_template.md or .gitlab/merge_request_templates/Default.md) with an Impact & Risk block. A high risk level (or a touched contract/auth/payments surface) routes the review to domain owners — the same escalation yad-review-gate applies. Ships the routing helper risk-route.sh plus the pattern-gate scripts pr-title.sh and pr-template.sh (used by yad-checks). Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire|route} {body: PR description file},3-build,yad-checks,,false,demo-repos/<repo>/,.github/pull_request_template.md .gitlab/merge_request_templates/Default.md checks/risk-route.sh checks/pr-title.sh checks/pr-template.sh
 SDLC Workflow,yad-commit,Commit by Convention,CM,"Build-half helper: commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer block (Task -> Contract-Change -> Co-Authored-By), and the <=3-file atomic guard. The human git author owns the commit; an assisting AI is recorded only as a Co-Authored-By footer chosen per-commit with --ai (claude|copilot|cursor|coderabbit|none, default none). Drives the yad commit CLI. Never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {task: <id>} {contract-change: true|false},3-build,yad-implement,,false,<repo>/,one commit
-SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build-half helper: open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the task branch, create the PR/MR with the body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Auto-assigns from the hub roster (assignee = committer, reviewers = repo reviewers + domain-owners); high risk / contract surface routes to domain owners (risk-route.sh). Drives the yad open-pr CLI. Never merges; never auto-advances.",,{repo: <name>} {risk: low|medium|high} {contract-change: true|false},3-build,yad-commit,,false,<repo>/,one PR/MR
-SDLC Workflow,yad-ship,Commit + Open PR/MR,SP2,"Build-half helper: commit AND open the task PR/MR in one step — a thin orchestration over yad-commit then yad-open-pr. Commits the staged atomic change by the conventions, then pushes the branch and opens the PR/MR from the committed template with the roster auto-assigned. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the yad ship CLI. Never merges; never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {repo: <name>} {risk: low|medium|high} {contract-change: true|false},3-build,yad-pr-template,,false,<repo>/,one commit + one PR/MR
+SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build-half helper: open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the task branch, create the PR/MR with the body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Auto-assigns from the hub roster (assignee = committer, reviewers = repo reviewers + domain-owners); high risk / contract surface routes to domain owners (risk-route.sh). Bases the PR on the repo's RESOLVED default branch (repos.json default_branch, else the platform's own default, else origin/HEAD, else main) instead of a hardcoded main, and warns when the base is not the platform default — that loses the AI first pass irreversibly. Drives the yad open-pr CLI. Never merges; never auto-advances.",,{repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-commit,,false,<repo>/,one PR/MR
+SDLC Workflow,yad-ship,Commit + Open PR/MR,SP2,"Build-half helper: commit AND open the task PR/MR in one step — a thin orchestration over yad-commit then yad-open-pr. Commits the staged atomic change by the conventions, then pushes the branch and opens the PR/MR from the committed template with the roster auto-assigned. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the yad ship CLI. Never merges; never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-pr-template,,false,<repo>/,one commit + one PR/MR
 SDLC Workflow,yad-hub-bridge,Hub Review Bridge,HB,"The templated PR/MR bridge for the front-half review gate: when the product hub has a platform (.sdlc/hub.json), open a review PR/MR on the hub for an authored artifact, set required reviewers/labels from the routing rule, and provide the read-only gh/glab recipes yad-review-gate's sync uses to pull platform comments + approvals into the file ledger. Local-user auth, no stored tokens; file ledger stays the source of truth; degrades to file-only when no platform/CLI. Never auto-advances.",,{epic: EP-<slug>} {artifact: epic.md|architecture.md|ui-design.md|stories/} {action: open|route},1-front,yad-review-gate,yad-review-gate,false,epics/EP-<slug>/.sdlc/,hub-prs.json
 SDLC Workflow,yad-engineer-review,Engineer Review & Merge,ER,"Build-half Step E: wire an advisory AI first-pass (CodeRabbit) on the PR, record the human engineer review with the same human_approve discipline as the front gates (owner + 1 reviewer, escalating to domain owners on high risk / contract / auth / payments), and on merge record the ship in epics/<epic>/.sdlc/build-log.json and update the story state. AI review is advisory, never the authority; the human owns the merge. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {task: T0N} {repo: <repo>} {action: ai-review|approve|ship},3-build,yad-ship,,false,epics/EP-<slug>/.sdlc/,build-log.json story-status
 SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build-half Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse yad-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. The promote action flips a brownfield stub epic (yad-stub) to a real, verified feature epic once its backfill spec is approved. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate|promote} {epic: EP-<slug> (promote)},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh

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