yadflow 3.16.3 → 3.17.1

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.1",
   "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/config.yaml

@@ -94,7 +94,7 @@ build:
   spec_layout: speckit          # follow Spec Kit's native spec/plan/tasks layout
   speckit_ceremony: [specify, clarify, plan, analyze, checklist, tasks]   # heavy run, once per story per repo
   # Step B (yad-implement) — the light per-task loop. One atomic task = one branch = one PR/MR.
-  branch_convention: "feat/<story-id>-<task-id>-<short-slug>"   # e.g. feat/EP-istifta-inquiries-S01-T01-create-inquiry
+  branch_convention: "feat/<story-id>-<task-id>-<short-slug>"   # e.g. feat/EP-checkout-S01-T01-create-order
   commit_task_trailer: "Task: <story-id>-<task-id>"             # final commit trailer; anchors the spec-link check (Step C)
   contract_change_trailer: "Contract-Change: yes"              # ONLY when the locked contract surface is touched (routes back to architecture gate)
   # Commit subject + PR/MR title style (Conventional Commits — see CONTRIBUTING.md). PRs are squash-merged,

package/skills/yad-analysis/SKILL.md

@@ -62,7 +62,7 @@ roadmap. **Optional & non-blocking:** if there is no discovery, or it has not ye
 
 ### Step 3 — Generate the Epic ID (engine-assigned, never by hand)
 Derive `EP-<slug>` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea
-(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. `EP-discovery` is **reserved**
+(e.g. `EP-checkout`). Lowercase except the fixed `EP` prefix. `EP-discovery` is **reserved**
 for the project front-zero — never use it for a feature. **The ID is assigned once and
 never renamed** — renaming breaks every downstream link (build plan §6b). Check
 `{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word.

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
@@ -383,15 +489,15 @@ bash checks/commit-message.sh --profile code master
 # pr-title / pr-template validate the actual PR/MR metadata (in CI they come from the event payload).
 # By hand, pass the title, and a FILE holding the PR/MR description (the rendered/filled body, not the
 # template source):
-bash checks/pr-title.sh --profile code "feat: add the inquiry endpoint"
+bash checks/pr-title.sh --profile code "feat: add the order endpoint"
 # save the PR/MR description to a file first (e.g. `gh pr view <n> --json body -q .body > /tmp/pr-body.md`)
 bash checks/pr-template.sh --profile code /tmp/pr-body.md
 ```
 
-## Proven behavior (demo: `demo-repos/backend`, story EP-istifta-inquiries-S01)
+## Proven behavior (demo: `demo-repos/backend`, story EP-checkout-S01)
 
 - **Good PR** (task branch with a `Task:` trailer, no surface change, passing tests) → all three **PASS**.
 - **Bad PR A** (a code change committed with **no** `Task:` trailer) → spec-link **FAILS**.
-- **Bad PR B** (edits `specs/.../contracts/inquiries.md` to widen the surface, with a `Task:` trailer
+- **Bad PR B** (edits `specs/.../contracts/orders.md` to widen the surface, with a `Task:` trailer
   but **no** `Contract-Change`) → spec-link passes, contract-check **FAILS** and routes back to the
   architecture gate.

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-connect-learning/references/learning-registry.md

@@ -17,7 +17,7 @@ root, not under any `epics/EP-<slug>/.sdlc/`.
   "tool": "deeptutor",                               // deeptutor | <adapter id> | none (harness-native)
   "provider": "deeptutor-cli",                       // the concrete CLI: deeptutor-cli | null
   "version": "1.4.5",                                // CLI version reported at detect time; null if absent
-  "kb": "yadflow-istifta",                           // grounded knowledge-base name; null if not built
+  "kb": "yadflow-checkout",                           // grounded knowledge-base name; null if not built
   "kb_sources": ["epic.md", "architecture.md", "contract.md", "ui-design.md", "stories/", "code-context/*/code-map.md"],
   "auth": "user",                                    // ALWAYS the user's own DeepTutor config / LLM keys — never a token
   "connectedAt": "2026-06-14",                       // first connect (YYYY-MM-DD)

package/skills/yad-engineer-review/references/ship-and-record.md

@@ -36,13 +36,13 @@ without the `{ epic, ships }` wrapper):
 
 ```json
 {
-  "epic": "EP-istifta-inquiries",
+  "epic": "EP-checkout",
   "ships": [
     {
-      "story": "EP-istifta-inquiries-S01",
+      "story": "EP-checkout-S01",
       "task": "T01",
       "repo": "backend",
-      "branch": "feat/EP-istifta-inquiries-S01-T01-create-inquiry",
+      "branch": "feat/EP-checkout-S01-T01-create-order",
       "pr": "<url|#|local>",
       "mergeCommit": "<sha>",
       "gates": ["spec-link", "contract-check", "build-test-lint"],

package/skills/yad-epic/SKILL.md

@@ -83,7 +83,7 @@ unchanged — do not consume an unapproved roadmap. After seeding the epic, the
 ### Step 3 — Generate the Epic ID (engine-assigned, never by hand) — analysis-skipped only
 *(Skip when analysis ran — the ID was already assigned by `yad-analysis`.)*
 Derive `EP-<slug>` where `slug` is **2–4 lowercase words joined by hyphens**, drawn from the idea
-(e.g. `EP-istifta-inquiries`). Lowercase except the fixed `EP` prefix. `EP-discovery` is **reserved**
+(e.g. `EP-checkout`). Lowercase except the fixed `EP` prefix. `EP-discovery` is **reserved**
 for the project front-zero — never use it for a feature. **The ID is assigned once and
 never renamed** — renaming breaks every downstream link (build plan §6b).
 Check `{project-root}/epics/` for collisions; if the slug exists, append a distinguishing word.

package/skills/yad-epic/references/state-schema.md

@@ -416,7 +416,7 @@ only re-authored steps run. The seeder sets `currentStep` to the first re-author
 ```json
 { "id": "architecture", "type": "author", "artifact": "architecture.md",
   "assistance": "review", "automation": "human_approve", "locked": true,
-  "status": "done", "inherited": true, "inheritedFrom": "EP-istifta-inquiries",
+  "status": "done", "inherited": true, "inheritedFrom": "EP-checkout",
   "boundHash": "sha256:…", "risk_tags": [] }
 ```
 
@@ -432,7 +432,7 @@ only re-authored steps run. The seeder sets `currentStep` to the first re-author
 
 ```json
 { "artifact": "architecture.md", "step": "architecture-review", "status": "inherited",
-  "from": "EP-istifta-inquiries", "boundHash": "sha256:…", "date": "<YYYY-MM-DD>" }
+  "from": "EP-checkout", "boundHash": "sha256:…", "date": "<YYYY-MM-DD>" }
 ```
 
 ## The pointer-lock — `contract-lock.json` in a change-epic
@@ -443,7 +443,7 @@ no `contract.md` in the child to edit, so the surface physically cannot drift.
 
 ```json
 { "artifact": "contract.md", "hash": "sha256:<parent hash, verbatim>", "lockedAt": "<date>",
-  "inheritedFrom": "EP-istifta-inquiries", "ref": "../../EP-istifta-inquiries/.sdlc/contract-lock.json" }
+  "inheritedFrom": "EP-checkout", "ref": "../../EP-checkout/.sdlc/contract-lock.json" }
 ```
 
 Omitting `architecture` from `inherits` (depth `contract-surface`) is what triggers a **real re-lock**:
@@ -455,9 +455,9 @@ architecture gate" with "open a contract-surface change-epic" — one mechanism,
 Intake + triage record, one per change/defect/hotfix epic (sibling of `approvals.json`).
 
 ```json
-{ "epicId": "EP-istifta-queue-filter", "thread": "EP-istifta-inquiries", "parent": "EP-istifta-inquiries",
+{ "epicId": "EP-checkout-queue-filter", "thread": "EP-checkout", "parent": "EP-checkout",
   "kind": "defect", "depth": "defect-fix", "intakeBy": "alice", "intakeDate": "<YYYY-MM-DD>",
-  "title": "Pending queue returns answered inquiries", "description": "…",
+  "title": "Pending queue returns fulfilled orders", "description": "…",
   "affectedArtifacts": ["stories", "test-cases"],
   "reauthors": ["stories", "test-cases"], "inherits": ["epic", "architecture", "contract", "ui-design"],
   "defect": { "origin": "production", "severity": "sev2", "escape_stage": "test-cases",
@@ -476,7 +476,7 @@ sharing `thread` and read each `change.json`; there is no duplicated thread regi
 Append-only ledger of hotfix ship-first debt (a hotfix shipped code before its front gates approved).
 
 ```json
-[ { "thread": "EP-istifta-inquiries", "epicId": "EP-istifta-hotfix-x", "openedDate": "<date>",
+[ { "thread": "EP-checkout", "epicId": "EP-checkout-hotfix-x", "openedDate": "<date>",
     "reason": "prod outage", "requires": ["artifacts-updated", "regression-test"],
     "status": "open", "paidDate": null, "paidBy": null,
     "evidence": { "artifacts": [], "regressionTest": "" } } ]

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