@dalzoubi/dev-agents-sync 2.0.28 → 2.1.0

package/README.md

@@ -101,7 +101,7 @@ npx --yes @dalzoubi/dev-agents-sync@1 status
 
 ## Steering and hooks
 
-For the `claude` target, `init` and `update` set up two extra pieces of project memory and automation.
+For the `claude` target, `init` and `update` set up two extra pieces of project memory and automation: a consumer-owned steering scaffold, and managed hook scripts that are auto-wired into `.claude/settings.json`.
 
 ### Steering scaffold (consumer-owned)
 
@@ -111,19 +111,53 @@ The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions
 
 ### Hook scripts (managed)
 
-`init` and `update` install three hook scripts into `.claude/hooks/` as marker-managed, lockfile-tracked, executable files:
+`init` and `update` install the toolkit's hook scripts into `.claude/hooks/` as marker-managed, lockfile-tracked, executable files. Most are **warning** hooks: they print one line to stderr and always exit 0. Three are **blocking** hooks that can deny a tool call outright.
 
-| Script | Claude Code event | Purpose |
-|---|---|---|
-| `steering-injector.sh` | `SessionStart` | Surfaces steering context at the start of a session. |
-| `managed-file-guard.sh` | `PostToolUse` | Guards managed files against unexpected edits. |
-| `uncommitted-check.sh` | `Stop` | Flags uncommitted work when a session ends. |
+| Script | Event | Matcher | Mode | What it does |
+|---|---|---|---|---|
+| `steering-injector.sh` | `SessionStart` | `.*` | warning | Surfaces steering context at the start of a session. |
+| `managed-file-guard.sh` | `PostToolUse` | `.*` | warning | Guards managed files against unexpected edits. |
+| `uncommitted-check.sh` | `Stop` | `.*` | warning | Flags uncommitted work when a session ends. |
+| `force-push-guard.sh` | `PreToolUse` | `Bash` | **blocking** | Denies `git push` carrying `--force` / `-f` / `--force-with-lease` at `main` or `master` (by explicit refspec, or by the checked-out branch when the push names no ref). Force-pushing a feature branch, and a plain push to `main`, both pass. |
+| `spec-approval-gate.sh` | `PreToolUse` | `Edit\|Write` | **blocking** | Denies an edit that sets a spec to `Status: Approved` while an unresolved clarification marker — a bare bracketed `NEEDS CLARIFICATION` token — remains in prose. Occurrences inside code spans or fenced blocks are documentation and never match. |
+| `handoff-state-guard.sh` | `PreToolUse` | `Write` | **blocking** | Denies a write to `.claude/state/*.json` whose `handoff.status`, `from_agent`, or `to_agent` is outside the vocabulary `.claude/rules/handoff.md` defines. |
+| `spec-drift-warn.sh` | `PostToolUse` | `Edit\|Write` | warning | After an edit to `spec.md` / `plan.md` / `tasks.md` under `docs/specs/`, warns when that folder's `spec.md` has already moved past `Draft`. Draft folders stay silent. |
+| `pre-pr-preflight.sh` | `PreToolUse` | `Bash` | warning | On a command containing `gh pr create`, prints `reminder: run /deliver-preflight before opening a PR — it checks the branch is clean, rebased, and green`. Never blocks. |
 
 Hook scripts use the shell-comment marker form `# managed-by: dev-agents-sync vX.Y.Z`. Like other managed files, the CLI overwrites them on `update` and `check` reports drift (exit 1) if one is deleted or locally modified.
 
+Every hook runs entirely locally: no network calls, no files written, nothing logged anywhere but your own stderr.
+
+#### Blocking hooks: deny messages and error codes
+
+A blocking hook runs on `PreToolUse`, where exiting 2 denies the tool call and the message is fed back to the model. Each deny is a single stderr line carrying a **stable code** and a next action. The codes are append-only:
+
+| Code | Raised by | Example message |
+|---|---|---|
+| `EHOOK_FORCE_PUSH` | `force-push-guard.sh` | `blocked: EHOOK_FORCE_PUSH — force-push to protected branch 'main' — push without a force flag or open a pull request; to override, set DEV_AGENTS_HOOKS_BYPASS=force-push-guard` |
+| `EHOOK_SPEC_APPROVAL` | `spec-approval-gate.sh` | `blocked: EHOOK_SPEC_APPROVAL — <path> sets Status: Approved while an unresolved clarification marker (a bare bracketed NEEDS CLARIFICATION token) remains in prose — resolve it via /define-analyze or /define before approving; to override, set DEV_AGENTS_HOOKS_BYPASS=spec-approval-gate` |
+| `EHOOK_HANDOFF_STATE` | `handoff-state-guard.sh` | `blocked: EHOOK_HANDOFF_STATE — handoff.status "done" is outside the status enum — fix the value in the state file before writing, or re-run with DEV_AGENTS_HOOKS_BYPASS=handoff-state-guard` |
+
+**A blocker denies only on a positive match, and fails open on everything else.** An unreadable payload, an unextractable path, or JSON it cannot parse with confidence produces at most one stderr note (for example `warning: handoff-state-guard stood down — <reason>`) and exit 0. A hook is never the reason a session breaks.
+
+#### Bypassing a blocking hook
+
+Set `DEV_AGENTS_HOOKS_BYPASS` to a comma-separated list of **exact** hook names to stand those blockers down for the run:
+
+```bash
+DEV_AGENTS_HOOKS_BYPASS=force-push-guard,handoff-state-guard claude
+```
+
+- Matching is an exact token match on the name — `force-push-guard-x` or a substring never matches.
+- A bypass is **never silent**: the named hook prints exactly one line, `bypassed: <hook-name>`, to stderr and exits 0.
+- Only the named hooks stand down; every other blocker still blocks.
+- The variable applies to blocking hooks only — warning hooks have nothing to bypass.
+
+> **Known gap.** `pre-pr-preflight.sh` matches on Bash command text (`gh pr create`), so a pull request opened through an MCP tool rather than the shell never reaches the hook and gets no reminder. There is no coverage for that path today.
+
 ### settings.json auto-wiring
 
-By default, `init` and `update` also register the three hooks in `.claude/settings.json` so Claude Code runs them. The merge is:
+By default, `init` and `update` also register each installed hook in `.claude/settings.json` so Claude Code runs them. Registrations come from the CLI's own table, so a consumer only ever gets registrations for scripts that actually shipped in the resolved version. The merge is:
 
 - **Additive** — every existing setting and every consumer-authored hook is preserved untouched.
 - **Idempotent** — running `update` twice produces no duplicate entries.
@@ -140,6 +174,17 @@ npx --yes @dalzoubi/dev-agents-sync@1 update --no-hooks-wiring
 
 With `--no-hooks-wiring`, the hook scripts are still installed under `.claude/hooks/`, but `settings.json` is neither created nor modified — wire the hooks yourself if you want them active. Note that the flag skips the whole merge, **including the self-cleaning de-registration above**: a registration for a retired hook stays in your `settings.json` until you run without the flag or remove it yourself.
 
+### What `init` / `update` report
+
+A run that installs hook scripts reports both halves on stderr, alongside the `steering/ …` line:
+
+```text
+info: dev-agents-sync: hooks/ installed (8 scripts)
+info: dev-agents-sync: hooks/ wired into .claude/settings.json (8 registrations)
+```
+
+Both counts are derived from what the **resolved version actually shipped**, not from a fixed number — an older content tag that carries fewer scripts reports fewer. With `--no-hooks-wiring` the second line reads `hooks/ settings.json wiring skipped (--no-hooks-wiring)` instead. `--dry-run` prints neither line: it installs nothing and wires nothing. Neither line affects an exit code.
+
 ## Agents
 
 Syncing installs the `define`/`deliver` agent topology: two user-facing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "2.0.28",
+  "version": "2.1.0",
   "type": "module",
   "description": "CLI that syncs managed dev-agent prompts into consumer repos (.claude/ and/or .cursor/).",
   "license": "UNLICENSED",

package/src/commands/init.mjs

@@ -17,7 +17,13 @@ import { resolveConsumerPath, writeManagedFile, normalizeFileMap } from '../writ
 import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
 import { injectClaudeMd } from '../claudeMd.mjs';
 import { seedSteering, steeringSummary } from '../steering.mjs';
-import { collectHookPaths, hookScriptsForInstalled, wireHookSettings } from '../hooks.mjs';
+import {
+  collectHookPaths,
+  hookScriptsForInstalled,
+  hooksSummary,
+  hooksWiringSummary,
+  wireHookSettings,
+} from '../hooks.mjs';
 
 const _require = createRequire(import.meta.url);
 const CLI_VERSION = _require('../../package.json').version;
@@ -152,6 +158,7 @@ export async function runInit(consumerCwd, opts = {}) {
     const plannedPrunedRetired =
       claudeTargetActive && !noHooksWiring
         ? wireHookSettings(consumerCwd, hookScriptsForInstalled(plannedKeys), { dryRun: true })
+            .prunedRetired
         : [];
 
     return {
@@ -214,11 +221,28 @@ export async function runInit(consumerCwd, opts = {}) {
   // additive + idempotent and fails loud (ESETTINGS_PARSE) on a malformed file.
   const installedHookKeys = plannedWrites.map(({ relKey }) => relKey);
   const hookPaths = collectHookPaths(installedHookKeys);
+  const hookRegistrations = hookScriptsForInstalled(installedHookKeys);
+  // Report the install BEFORE wiring, so the pair reads in the order it happened
+  // (scripts on disk, then registrations) with any retired-prune line from
+  // wireHookSettings between them. Both lines are suppressed when this run
+  // installed no hook scripts at all — there is nothing to report — and they
+  // never appear under --dry-run, which returns above (planning is not doing).
+  if (hookPaths.length > 0) {
+    process.stderr.write(`info: dev-agents-sync: ${hooksSummary(hookPaths)}\n`);
+  }
   let prunedRetired = [];
   if (claudeTargetActive && !noHooksWiring) {
     // Unconditional on the spec being non-empty: the prune half needs no spec,
     // and `init` over an existing .claude/ can meet a pre-retirement settings.json.
-    prunedRetired = wireHookSettings(consumerCwd, hookScriptsForInstalled(installedHookKeys));
+    ({ prunedRetired } = wireHookSettings(consumerCwd, hookRegistrations));
+  }
+  if (hookPaths.length > 0) {
+    process.stderr.write(
+      `info: dev-agents-sync: ${hooksWiringSummary({
+        registrationCount: hookRegistrations.length,
+        skipped: noHooksWiring,
+      })}\n`,
+    );
   }
 
   writeLockfile(consumerCwd, {

package/src/commands/update.mjs

@@ -16,7 +16,13 @@ import { hasMarker, hasMarkerOnFirstLine } from '../marker.mjs';
 import { injectClaudeMd } from '../claudeMd.mjs';
 import { seedSteering, steeringSummary } from '../steering.mjs';
 import { DEFAULT_HOOK_SCRIPTS } from '../settings.mjs';
-import { collectHookPaths, hookScriptsForInstalled, wireHookSettings } from '../hooks.mjs';
+import {
+  collectHookPaths,
+  hookScriptsForInstalled,
+  hooksSummary,
+  hooksWiringSummary,
+  wireHookSettings,
+} from '../hooks.mjs';
 
 const _require = createRequire(import.meta.url);
 const CLI_VERSION = _require('../../package.json').version;
@@ -151,9 +157,29 @@ export async function runUpdate(consumerCwd, opts = {}) {
       );
       // Unconditional on hookSpec.length: the prune needs no spec, so a consumer
       // with no hook scripts on disk still gets retired registrations removed.
-      prunedRetired = wireHookSettings(consumerCwd, hookSpec, { dryRun });
+      const wiring = wireHookSettings(consumerCwd, hookSpec, { dryRun });
+      prunedRetired = wiring.prunedRetired;
+      // Wiring edits consumer-owned state, so it is never silent (§6) — and for a
+      // consumer already pinned to the latest tag who never had hooks wired, the
+      // merge above is a genuine FIRST-TIME write to settings.json. Gated on the
+      // merge's own "did it write" signal rather than on reaching this branch, so
+      // a repeat no-op `update` stays quiet: we report what this run actually did.
+      // Not reached under --dry-run (planning is not doing); `merged` there only
+      // describes what would change.
+      if (!dryRun && wiring.merged) {
+        process.stderr.write(
+          `info: dev-agents-sync: ${hooksWiringSummary({
+            registrationCount: hookSpec.length,
+          })}\n`,
+        );
+      }
     }
 
+    // No hooks summary line here on purpose: this branch installs nothing, and
+    // the summary reports what THIS run installed. Claiming "hooks/ installed
+    // (N scripts)" for scripts an earlier run wrote would be a count the run
+    // did not earn. Only the wiring half above is reported, and only when the
+    // merge actually wrote.
     return {
       upToDate: true,
       resolvedVersion: lock.resolvedVersion,
@@ -199,6 +225,7 @@ export async function runUpdate(consumerCwd, opts = {}) {
     const plannedPrunedRetired =
       claudeTargetActive && !noHooksWiring
         ? wireHookSettings(consumerCwd, hookScriptsForInstalled(plannedKeys), { dryRun: true })
+            .prunedRetired
         : [];
     return {
       dryRun: true,
@@ -250,10 +277,25 @@ export async function runUpdate(consumerCwd, opts = {}) {
   // on a malformed settings.json, leaving it byte-identical.
   const installedHookKeys = plannedWrites.map(({ relKey }) => relKey);
   const hookPaths = collectHookPaths(installedHookKeys);
+  const hookRegistrations = hookScriptsForInstalled(installedHookKeys);
+  // Same pairing as init: install line, then any retired-prune line emitted by
+  // wireHookSettings, then the wiring line. Suppressed entirely when this run
+  // installed no hook scripts, and never reached under --dry-run (returns above).
+  if (hookPaths.length > 0) {
+    process.stderr.write(`info: dev-agents-sync: ${hooksSummary(hookPaths)}\n`);
+  }
   let prunedRetired = [];
   if (claudeTargetActive && !noHooksWiring) {
     // Unconditional on the spec being non-empty: the prune half needs no spec.
-    prunedRetired = wireHookSettings(consumerCwd, hookScriptsForInstalled(installedHookKeys));
+    ({ prunedRetired } = wireHookSettings(consumerCwd, hookRegistrations));
+  }
+  if (hookPaths.length > 0) {
+    process.stderr.write(
+      `info: dev-agents-sync: ${hooksWiringSummary({
+        registrationCount: hookRegistrations.length,
+        skipped: noHooksWiring,
+      })}\n`,
+    );
   }
 
   // Prune orphans: marker-bearing managed files no longer shipped. Delete in

package/src/hooks.mjs

@@ -73,19 +73,66 @@ export function hookScriptsForInstalled(relKeys) {
  * command registered under two event buckets is two registrations gone from the
  * consumer's file; saying "1" there would under-report the edit we just made.
  *
- * @returns {string[]} the DISTINCT retired commands de-registered (or, in
+ * @returns {{ prunedRetired: string[], merged: boolean }}
+ *   `prunedRetired` — the DISTINCT retired commands de-registered (or, in
  *   dry-run, that would be de-registered) by this call. Always an array. Callers
  *   match on it ("was X pruned?"); the user-facing count stays inside this
  *   function, which is the toolkit's single reporting site for the prune.
+ *   `merged` — mergeHookSettings's own "did this change settings.json?" signal,
+ *   surfaced rather than dropped so a caller can tell a real write apart from an
+ *   idempotent no-op and keep the §6 "wiring is never silent" promise without
+ *   printing a line on every repeat run. In dry-run it reports what WOULD change
+ *   (nothing is written), so callers must still gate their own output on dryRun.
  */
 export function wireHookSettings(consumerCwd, hookScripts, { dryRun = false } = {}) {
-  const { prunedRetired, prunedRetiredCount } = mergeHookSettings(consumerCwd, hookScripts, {
-    dryRun,
-  });
+  const { merged, prunedRetired, prunedRetiredCount } = mergeHookSettings(
+    consumerCwd,
+    hookScripts,
+    { dryRun },
+  );
   if (!dryRun && prunedRetiredCount > 0) {
     process.stderr.write(
       `info: dev-agents-sync: pruned ${prunedRetiredCount} retired hook registration(s)\n`,
     );
   }
-  return prunedRetired;
+  return { prunedRetired, merged };
+}
+
+/** `1 script` / `2 scripts` — keeps the summary lines readable at n === 1. */
+function plural(n, word) {
+  return `${n} ${word}${n === 1 ? '' : 's'}`;
+}
+
+/**
+ * Human-readable summary of the hook scripts this run installed, in the same
+ * style as steering.mjs's steeringSummary (its sibling on the same output line
+ * family).
+ *
+ * The count is DERIVED from the paths that were actually installed — never a
+ * literal. That is load-bearing: a hard-coded number silently lies the moment a
+ * hook is added or retired, and it lies loudest for a consumer resolving an
+ * older content tag that shipped fewer scripts than the CLI knows about.
+ *
+ * @param {string[]} hookPaths consumer-relative paths from collectHookPaths.
+ */
+export function hooksSummary(hookPaths) {
+  return `hooks/ installed (${plural(hookPaths.length, 'script')})`;
+}
+
+/**
+ * Human-readable summary of the settings.json half of the install: whether the
+ * installed scripts were registered, or the merge was skipped by
+ * --no-hooks-wiring. Wiring edits consumer-owned state, so it is never silent
+ * (§6) — and a consumer who passed --no-hooks-wiring gets told the scripts are
+ * on disk but inert.
+ *
+ * The registration count is derived from the spec hookScriptsForInstalled built
+ * for this run, so it can never claim registrations the CLI did not make.
+ *
+ * @param {{ registrationCount?: number, skipped?: boolean }} state
+ */
+export function hooksWiringSummary({ registrationCount = 0, skipped = false } = {}) {
+  if (skipped) return 'hooks/ settings.json wiring skipped (--no-hooks-wiring)';
+  if (registrationCount === 0) return 'hooks/ nothing to wire into .claude/settings.json';
+  return `hooks/ wired into .claude/settings.json (${plural(registrationCount, 'registration')})`;
 }

package/src/settings.mjs

@@ -394,11 +394,28 @@ export function removeHookSettings(consumerCwd, opts = {}) {
 /**
  * The default hook registration spec — maps each installed hook script to its
  * Claude Code event. Kept here so init/update share one source of truth.
+ *
+ * The matcher is the tool-name filter Claude Code applies before running the
+ * hook. Session-scoped events (`SessionStart`, `Stop`) take `.*`; tool-scoped
+ * events name the tools they inspect, so a hook that only ever reads a Bash
+ * command or a written file path is not spawned on every unrelated tool call.
+ *
+ * `PreToolUse` hooks can DENY the tool call (exit 2). Two of them share the
+ * `Bash` matcher — one blocking, one warning — which the merge handles as two
+ * independent registrations keyed by command.
  */
 export const DEFAULT_HOOK_SCRIPTS = [
   { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/steering-injector.sh' },
   { event: 'PostToolUse', matcher: '.*', command: '.claude/hooks/managed-file-guard.sh' },
   { event: 'Stop', matcher: '.*', command: '.claude/hooks/uncommitted-check.sh' },
+  // Added by docs/specs/260805-hooks-wave-2/ — the toolkit's first blocking
+  // hooks plus two warning hooks. Blockers deny only on a positive violation
+  // match, fail open otherwise, and honor DEV_AGENTS_HOOKS_BYPASS.
+  { event: 'PreToolUse', matcher: 'Bash', command: '.claude/hooks/force-push-guard.sh' },
+  { event: 'PreToolUse', matcher: 'Edit|Write', command: '.claude/hooks/spec-approval-gate.sh' },
+  { event: 'PreToolUse', matcher: 'Write', command: '.claude/hooks/handoff-state-guard.sh' },
+  { event: 'PostToolUse', matcher: 'Edit|Write', command: '.claude/hooks/spec-drift-warn.sh' },
+  { event: 'PreToolUse', matcher: 'Bash', command: '.claude/hooks/pre-pr-preflight.sh' },
 ];
 
 /**

package/tests/e2e/steering-hooks-flow.test.mjs

@@ -63,6 +63,7 @@ import { fileURLToPath } from 'node:url';
 import { runInit } from '../../src/commands/init.mjs';
 import { runUpdate } from '../../src/commands/update.mjs';
 import { runCheck } from '../../src/commands/check.mjs';
+import { DEFAULT_HOOK_SCRIPTS } from '../../src/settings.mjs';
 
 // ---------------------------------------------------------------------------
 // Paths
@@ -78,22 +79,27 @@ const README_PATH = path.join(__dirname, '..', '..', 'README.md');
 
 const STEERING_FILES = ['decisions.md', 'glossary.md', 'architecture.md'];
 
-const HOOK_FILES = [
-  'steering-injector.sh',
-  'managed-file-guard.sh',
-  'uncommitted-check.sh',
-];
+/**
+ * The hook script files this flow expects, DERIVED from the CLI's registration
+ * table rather than pinned.
+ *
+ * The e2e flow's claim is "every hook the toolkit ships installs and wires end
+ * to end" — so the expected set has to BE the shipped set. A pinned roster
+ * silently shrinks that claim to whichever hooks existed when it was written:
+ * the 260805 wave added five hooks that a pinned list of three would not have
+ * covered at all. Deriving keeps the flow honest for every future wave.
+ */
+const HOOK_FILES = DEFAULT_HOOK_SCRIPTS.map((h) => path.basename(h.command));
 
 /**
  * Events paired with the hook script that handles each one. Used to assert
  * that settings.json wiring is complete without hard-coding the internal
  * shape (the implement agent owns that).
  */
-const HOOK_EVENT_PAIRS = [
-  { event: 'SessionStart', script: 'steering-injector.sh' },
-  { event: 'PostToolUse', script: 'managed-file-guard.sh' },
-  { event: 'Stop', script: 'uncommitted-check.sh' },
-];
+const HOOK_EVENT_PAIRS = DEFAULT_HOOK_SCRIPTS.map((h) => ({
+  event: h.event,
+  script: path.basename(h.command),
+}));
 
 const AVAILABLE_TAGS = ['v1.0.0', 'v1.1.0', 'v1.2.0', 'v2.0.0'];
 const LOCKFILE_NAME = '.dev-agents-sync.json';
@@ -117,7 +123,8 @@ function collectFiles(baseDir, currentDir, map, prefix) {
 
 /**
  * Builds a fixture file map from the release-v1.0.0 fixture directory,
- * extended with the three hook scripts that S3's build.mjs would emit.
+ * extended with the hook scripts build.mjs would emit — one per registration,
+ * so the fetched set and the wiring table cannot drift apart in this flow.
  * These use the shell-comment marker format for .sh files.
  */
 function buildFixtureFileMap(targets = ['claude']) {
@@ -128,14 +135,15 @@ function buildFixtureFileMap(targets = ['claude']) {
     collectFiles(targetDir, targetDir, map, target);
   }
 
-  // Hook scripts injected as if emitted by S3's build pipeline.
-  // They carry the shell-comment marker (POSIX-sh format, not HTML).
-  map['claude/hooks/steering-injector.sh'] =
-    '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# SessionStart: surface steering context.\n[ -d .claude/steering ] && cat .claude/steering/*.md 2>/dev/null >&2\nexit 0\n';
-  map['claude/hooks/managed-file-guard.sh'] =
-    '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# PostToolUse: warn on managed-file edits.\nexit 0\n';
-  map['claude/hooks/uncommitted-check.sh'] =
-    '#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# Stop: remind about uncommitted work.\nexit 0\n';
+  // Hook scripts injected as if emitted by the build pipeline, one per
+  // registration. They carry the shell-comment marker (POSIX-sh, not HTML).
+  // Bodies are stand-ins: this flow proves install + wiring + drift, never a
+  // hook's own behavior (that lives in the content repo's tests/hooks-*.mjs).
+  for (const { event, command } of DEFAULT_HOOK_SCRIPTS) {
+    const key = command.replace(/^\.claude\//, 'claude/');
+    map[key] =
+      `#!/bin/sh\n# managed-by: dev-agents-sync v2.0.16\n# ${event}: fixture stand-in for ${path.basename(command)}.\nexit 0\n`;
+  }
 
   return map;
 }