@dalzoubi/dev-agents-sync 3.0.4 → 3.0.5

package/README.md

@@ -126,6 +126,8 @@ The CLI seeds a blank steering scaffold under `.claude/steering/` — `decisions
 | `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` / `design.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. |
+| `main-sync-fetch.sh` | `SessionStart` | `.*` | warning | Resolves the default branch (`origin/HEAD`, fallback local `main` then `master`) and runs `git fetch origin <default>` once per session, printing the fetched ref+sha or a one-line skip reason to session context. Never blocks. |
+| `worktree-guard.sh` | `PreToolUse` | `Bash`, `Edit\|Write` | **blocking** | Denies an `Edit`/`Write` or a `git commit` landing in the main checkout when its current branch is also checked out in an existing `/deliver`-managed worktree under `.deliver/worktrees/<slug>/`, naming the worktree path to use instead. Exempts `docs/specs/`, `.agents/state/`, and `.deliver/` itself. Fails open on no git repo, no worktree entries, or no branch match. |
 
 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.
 
@@ -141,6 +143,7 @@ A blocking hook runs on `PreToolUse`, where exiting 2 denies the tool call and t
 | `EHOOK_DIRECT_PUSH` | `direct-push-guard.sh` | `blocked: EHOOK_DIRECT_PUSH — direct push to protected branch 'main' — open a pull request instead; to override, set DEV_AGENTS_HOOKS_BYPASS=direct-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` |
+| `EHOOK_WORKTREE_GUARD` | `worktree-guard.sh` | `blocked: EHOOK_WORKTREE_GUARD — <branch> is also checked out at <worktree-path> — make this change there instead; to override, set DEV_AGENTS_HOOKS_BYPASS=worktree-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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dalzoubi/dev-agents-sync",
-  "version": "3.0.4",
+  "version": "3.0.5",
   "type": "module",
   "description": "CLI that syncs managed dev-agent workflows into Claude Code, Cursor, Copilot, and Codex projects.",
   "license": "UNLICENSED",

package/src/hook-manifest.mjs

@@ -15,6 +15,9 @@ export const HOOK_MANIFEST = Object.freeze([
   { event: 'PostToolUse', matcher: 'Edit|Write', file: 'spec-drift-warn.sh' },
   { event: 'PreToolUse', matcher: 'Bash', file: 'pre-pr-preflight.sh' },
   { event: 'Stop', matcher: '.*', file: 'ui-verification-reminder.sh' },
+  { event: 'SessionStart', matcher: '.*', file: 'main-sync-fetch.sh' },
+  { event: 'PreToolUse', matcher: 'Bash', file: 'worktree-guard.sh' },
+  { event: 'PreToolUse', matcher: 'Edit|Write', file: 'worktree-guard.sh' },
 ]);
 
 export function hookPathFor(target, file) {

package/src/settings.mjs

@@ -11,7 +11,11 @@
  *     preserved untouched. We only append our own registrations — and remove
  *     our own registrations for RETIRED_HOOK_SCRIPTS, never anyone else's.
  *   - Idempotent (§9): a second merge adds no duplicates. Identity is the
- *     installed command path, so re-running is a no-op.
+ *     (event, matcher, command) triple, so re-running is a no-op. Matcher is
+ *     part of identity because one script can need two independent
+ *     registrations under the SAME event with DIFFERENT matchers (e.g. a
+ *     guard that fires on both `Bash` and `Edit|Write`); command alone would
+ *     make the second registration look "already wired" and silently drop it.
  *   - Tagged (§4): each injected hook entry carries `HOOK_TAG: true` so it is
  *     identifiable and removable later (update/uninstall) without touching
  *     consumer-authored entries. Consumer entries never receive the tag.
@@ -123,10 +127,23 @@ function managedCommandsIn(entry) {
   return hookList.filter((h) => h && typeof h.command === 'string').map((h) => h.command);
 }
 
-/** True if `event` already has a CLI-managed entry whose command targets `command`. */
-function hasManagedCommand(eventEntries, command) {
+/**
+ * True if `event` already has a CLI-managed entry with THIS `matcher` whose
+ * command targets `command`.
+ *
+ * Matcher is part of the identity check, not just command: a single script can
+ * legitimately need two registrations under the same event with different
+ * matchers (worktree-guard.sh registers on both `PreToolUse`/`Bash` and
+ * `PreToolUse`/`Edit|Write`). Matching on command alone would find the first
+ * registration's entry, conclude the second is "already wired," and silently
+ * never append it — each managed entry already carries its own `matcher` via
+ * `buildManagedEntry`, so filtering on it here costs nothing extra.
+ */
+function hasManagedCommand(eventEntries, matcher, command) {
   if (!Array.isArray(eventEntries)) return false;
-  return eventEntries.some((entry) => managedCommandsIn(entry).includes(command));
+  return eventEntries.some(
+    (entry) => entry?.matcher === matcher && managedCommandsIn(entry).includes(command),
+  );
 }
 
 /**
@@ -242,8 +259,10 @@ function appendMissingEntries(hooks, hookScripts) {
   let added = false;
   for (const { event, matcher, command } of hookScripts) {
     const existing = Array.isArray(hooks[event]) ? hooks[event] : [];
-    // Already wired — idempotent no-op for this registration (§9).
-    if (hasManagedCommand(existing, command)) continue;
+    // Already wired under THIS matcher — idempotent no-op for this
+    // registration (§9). A different matcher on the same event/command is a
+    // distinct registration and must still be appended below.
+    if (hasManagedCommand(existing, matcher, command)) continue;
     hooks[event] = [...existing, buildManagedEntry({ matcher, command })];
     added = true;
   }
@@ -496,9 +515,26 @@ export const RETIRED_HOOK_SCRIPTS = [
   // or by a future regression, and pruning it is always correct since that form
   // is never in DEFAULT_HOOK_SCRIPTS.
   { event: 'Stop', matcher: '.*', command: '.claude/hooks/ui-verification-reminder.sh' },
+  // main-sync-fetch.sh ships only in the `bash …` form — same reasoning as
+  // ui-verification-reminder.sh above: it never shipped bare, but the
+  // bare-path form is pruned defensively so a hand-edit or regression can't
+  // register it live alongside the real one. (Gap found by running the full
+  // package test suite while fixing the worktree-guard.sh matcher-dedup bug —
+  // this hook shipped in an earlier slice on the same branch (S4) without this
+  // entry and C3a caught it.)
+  { event: 'SessionStart', matcher: '.*', command: '.claude/hooks/main-sync-fetch.sh' },
   // direct-push-guard.sh ships only in the `bash …` form — same reasoning as
   // ui-verification-reminder.sh above: it never shipped bare, but the
   // bare-path form is pruned defensively so a hand-edit or regression can't
   // register it live alongside the real one.
   { event: 'PreToolUse', matcher: 'Bash', command: '.claude/hooks/direct-push-guard.sh' },
+  // worktree-guard.sh ships only in the `bash …` form, under TWO matchers
+  // (PreToolUse/Bash and PreToolUse/Edit|Write) — same defensive reasoning as
+  // ui-verification-reminder.sh and direct-push-guard.sh above: it never
+  // shipped bare, but pruning the bare-path form guards against a hand-edit or
+  // regression registering it live alongside the real ones. One entry covers
+  // both matchers: the prune matches on COMMAND alone (never matcher) and
+  // scans every event bucket, so this single row de-registers a stray bare
+  // entry under either matcher.
+  { event: 'PreToolUse', matcher: 'Bash', command: '.claude/hooks/worktree-guard.sh' },
 ];

package/tests/hooks-command-form.test.mjs

@@ -20,8 +20,11 @@
  *
  *  C1. No registered command is a bare `.sh` path; each names an interpreter
  *      and points at its `script`.
- *  C2. `script` and `command` stay consistent: one row per shipped script, and
- *      the command is derived from the path rather than typed twice.
+ *  C2. `script` and `command` stay consistent, and the command is derived from
+ *      the path rather than typed twice. A script may carry more than one row
+ *      (e.g. worktree-guard.sh registers under both PreToolUse/Bash and
+ *      PreToolUse/Edit|Write) but never two rows on the identical
+ *      (event, matcher) — that would run it twice per matched call.
  *  C3. The pre-fix bare-path form of every shipped script is retired, so a
  *      consumer's stale registration is de-registered rather than left live
  *      alongside the new one.
@@ -240,13 +243,17 @@ describe('C2 — script and command are consistent across the table', () => {
     }
   });
 
-  it('C2c: each shipped script has exactly one row', () => {
-    const scripts = DEFAULT_HOOK_SCRIPTS.map((h) => h.script);
-    const duplicated = scripts.filter((s, i) => scripts.indexOf(s) !== i).sort();
+  it('C2c: no script is registered twice under the identical (event, matcher)', () => {
+    // A script CAN need more than one row — worktree-guard.sh legitimately
+    // registers under both PreToolUse/Bash and PreToolUse/Edit|Write — but
+    // never two rows sharing the SAME (event, matcher): that would run it
+    // twice per matched call.
+    const keys = DEFAULT_HOOK_SCRIPTS.map((h) => `${h.event}::${h.matcher}::${h.script}`);
+    const duplicated = keys.filter((k, i) => keys.indexOf(k) !== i).sort();
     assert.deepEqual(
       duplicated,
       [],
-      `a script registered twice runs twice per matched call: ${duplicated.join(', ')}`,
+      `a script registered twice under the same event+matcher runs twice per matched call: ${duplicated.join(', ')}`,
     );
   });
 });

package/tests/hooks-summary-line.test.mjs

@@ -74,9 +74,25 @@ function collectFiles(baseDir, currentDir, map, prefix) {
   }
 }
 
-/** Every hook script name the CLI's registration table knows about. */
+/**
+ * Every hook script name the CLI's registration table knows about, ONE PER
+ * REGISTRATION ROW — so it legitimately repeats a name for a script carrying
+ * more than one row (worktree-guard.sh registers under both PreToolUse/Bash
+ * and PreToolUse/Edit|Write). Use this where the assertion is about
+ * REGISTRATIONS (the wiring line's count).
+ */
 const REGISTERED_HOOK_NAMES = DEFAULT_HOOK_SCRIPTS.map((h) => path.basename(h.command));
 
+/**
+ * The DISTINCT hook script file names — deduped, since a fetched FileMap and
+ * an installed `.claude/hooks/` directory each carry one FILE per script
+ * regardless of how many registration rows that script has. Use this where the
+ * assertion is about INSTALLED SCRIPTS (the "hooks/ installed (N scripts)"
+ * line), never REGISTERED_HOOK_NAMES.length directly — that would over-count
+ * by the number of scripts carrying more than one row.
+ */
+const INSTALLED_HOOK_FILE_NAMES = [...new Set(REGISTERED_HOOK_NAMES)];
+
 function hookBody(name) {
   return `#!/bin/sh\n# managed-by: dev-agents-sync v9.9.9\n# ${name}\nexit 0\n`;
 }
@@ -229,11 +245,13 @@ describe('AC-8 hooks summary line — count is derived, never a literal', () =>
 
   // Three shipped sets of DIFFERENT sizes. Any implementation that prints a
   // pinned number fails at least two of these — which is the whole point: this
-  // wave already burned three fixes on hard-coded hook counts.
+  // wave already burned three fixes on hard-coded hook counts. Deduped
+  // (INSTALLED_HOOK_FILE_NAMES), since this is about installed FILES, not
+  // registration rows — a script with two rows still installs one file.
   const shippedSets = [
-    REGISTERED_HOOK_NAMES.slice(0, 2),
-    REGISTERED_HOOK_NAMES.slice(0, 4),
-    REGISTERED_HOOK_NAMES,
+    INSTALLED_HOOK_FILE_NAMES.slice(0, 2),
+    INSTALLED_HOOK_FILE_NAMES.slice(0, 4),
+    INSTALLED_HOOK_FILE_NAMES,
   ];
 
   for (const hookNames of shippedSets) {
@@ -257,7 +275,7 @@ describe('AC-8 hooks summary line — count is derived, never a literal', () =>
 
   it('A3b: a hook script the registration table does not know about still counts as installed', async () => {
     // The count comes from what was INSTALLED, not from the registration table.
-    const hookNames = [...REGISTERED_HOOK_NAMES, 'future-unregistered-hook.sh'];
+    const hookNames = [...INSTALLED_HOOK_FILE_NAMES, 'future-unregistered-hook.sh'];
     const stderr = await captureStderr(() =>
       runInit(consumerDir, {
         targets: ['claude'],
@@ -365,7 +383,7 @@ describe('AC-8 wiring line', () => {
     );
 
     // Installed count includes it; registration count does not.
-    assert.equal(installedCountFrom(stderr), REGISTERED_HOOK_NAMES.length + 1);
+    assert.equal(installedCountFrom(stderr), INSTALLED_HOOK_FILE_NAMES.length + 1);
     assert.match(
       stderr,
       new RegExp(
@@ -425,7 +443,7 @@ describe('AC-8 wiring line', () => {
       '--no-hooks-wiring must not create settings.json',
     );
     // The install half still happened and is still reported.
-    assert.equal(installedCountFrom(stderr), REGISTERED_HOOK_NAMES.length);
+    assert.equal(installedCountFrom(stderr), INSTALLED_HOOK_FILE_NAMES.length);
   });
 
   it('A7b: update --no-hooks-wiring reports the skip too', async () => {

package/tests/hooks-wave2-registration.test.mjs

@@ -295,9 +295,10 @@ describe('W2 — init and update install and wire every registered hook', () =>
     }
   });
 
-  it('W2d: all three Bash PreToolUse hooks are wired (a shared event+matcher is not deduped)', async () => {
-    // force-push-guard, direct-push-guard, and pre-pr-preflight all share
-    // PreToolUse/Bash. Merge identity is the COMMAND, so all three must
+  it('W2d: all four Bash PreToolUse hooks are wired (a shared event+matcher is not deduped)', async () => {
+    // force-push-guard, direct-push-guard, pre-pr-preflight, and worktree-guard
+    // (its Bash half — see W6 for its second, Edit|Write, registration) all
+    // share PreToolUse/Bash. Merge identity is the COMMAND, so all four must
     // survive — collapsing on event+matcher would silently drop one.
     await runInit(consumerDir, {
       targets: ['claude'],
@@ -315,8 +316,9 @@ describe('W2 — init and update install and wire every registered hook', () =>
         expectedCommand('.claude/hooks/direct-push-guard.sh'),
         expectedCommand('.claude/hooks/force-push-guard.sh'),
         expectedCommand('.claude/hooks/pre-pr-preflight.sh'),
+        expectedCommand('.claude/hooks/worktree-guard.sh'),
       ],
-      'all three PreToolUse/Bash hooks must be wired independently',
+      'all four PreToolUse/Bash hooks must be wired independently',
     );
   });
 
@@ -367,15 +369,19 @@ describe('W3 — a second update is a no-op (twice == once)', () => {
     );
   });
 
-  it('W3b: no hook command is registered twice after two updates', async () => {
+  it('W3b: no (event, matcher, command) registration is duplicated after two updates', async () => {
+    // Keyed on the full (event, matcher, command) triple, not command alone:
+    // worktree-guard.sh legitimately registers the SAME command twice, under
+    // PreToolUse/Bash and PreToolUse/Edit|Write (see W6) — that is two
+    // distinct registrations, not a duplicate.
     setupPreWaveRepo(consumerDir);
     const opts = { fetcher: makeFixtureFetcher(), availableTags: AVAILABLE_TAGS };
 
     await runUpdate(consumerDir, opts);
     await runUpdate(consumerDir, opts);
 
-    const commands = managedRegistrations(consumerDir).map((w) => w.command);
-    const duplicated = commands.filter((c, i) => commands.indexOf(c) !== i);
+    const keys = managedRegistrations(consumerDir).map((w) => `${w.event}::${w.matcher}::${w.command}`);
+    const duplicated = keys.filter((k, i) => keys.indexOf(k) !== i);
     assert.deepEqual(duplicated, [], `duplicate registrations after two updates: ${duplicated}`);
   });
 
@@ -540,3 +546,86 @@ describe('W5 — check reports drift on a modified hook script', () => {
     );
   });
 });
+
+// ---------------------------------------------------------------------------
+// W6 — one script, one event, two matchers: docs/specs/260913-deliver-worktree-sync
+// ---------------------------------------------------------------------------
+//
+// worktree-guard.sh is the first HOOK_MANIFEST script to need two independent
+// PreToolUse registrations for itself — Bash (blocks a raw git write) and
+// Edit|Write (blocks a direct file edit) — same event, same command, different
+// matcher. `hasManagedCommand` used to dedupe on (event, command) alone, so the
+// merge saw the Bash row wired first and silently treated the Edit|Write row as
+// "already wired," and it never landed in settings.json. These tests pin that
+// both rows survive independently and would fail again if that regressed.
+
+describe('W6 — worktree-guard.sh registers independently under two matchers on PreToolUse', () => {
+  let consumerDir;
+
+  beforeEach(() => {
+    consumerDir = makeTmpDir();
+  });
+
+  afterEach(() => {
+    rmSync(consumerDir, { recursive: true, force: true });
+  });
+
+  it('W6a: init wires both the Bash and Edit|Write registrations for worktree-guard.sh', async () => {
+    await runInit(consumerDir, {
+      targets: ['claude'],
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const command = expectedCommand('.claude/hooks/worktree-guard.sh');
+    const matchers = managedRegistrations(consumerDir)
+      .filter((w) => w.event === 'PreToolUse' && w.command === command)
+      .map((w) => w.matcher)
+      .sort();
+    assert.deepEqual(
+      matchers,
+      ['Bash', 'Edit|Write'],
+      'worktree-guard.sh must be registered under BOTH PreToolUse/Bash and ' +
+        'PreToolUse/Edit|Write — same script, same event, two matchers is the ' +
+        'one case hasManagedCommand must not collapse',
+    );
+  });
+
+  it('W6b: update wires both worktree-guard.sh registrations onto a pre-wave lockfile', async () => {
+    setupPreWaveRepo(consumerDir);
+    await runUpdate(consumerDir, {
+      fetcher: makeFixtureFetcher(),
+      availableTags: AVAILABLE_TAGS,
+    });
+
+    const command = expectedCommand('.claude/hooks/worktree-guard.sh');
+    const matchers = managedRegistrations(consumerDir)
+      .filter((w) => w.event === 'PreToolUse' && w.command === command)
+      .map((w) => w.matcher)
+      .sort();
+    assert.deepEqual(
+      matchers,
+      ['Bash', 'Edit|Write'],
+      'update must wire both worktree-guard.sh registrations onto an upgrading consumer',
+    );
+  });
+
+  it('W6c: a second update does not duplicate or drop either worktree-guard.sh registration', async () => {
+    setupPreWaveRepo(consumerDir);
+    const opts = { fetcher: makeFixtureFetcher(), availableTags: AVAILABLE_TAGS };
+
+    await runUpdate(consumerDir, opts);
+    await runUpdate(consumerDir, opts);
+
+    const command = expectedCommand('.claude/hooks/worktree-guard.sh');
+    const rows = managedRegistrations(consumerDir).filter(
+      (w) => w.event === 'PreToolUse' && w.command === command,
+    );
+    assert.equal(
+      rows.length,
+      2,
+      `expected exactly one row per matcher (2 total) after two updates, got ${rows.length}: ` +
+        JSON.stringify(rows),
+    );
+  });
+});