@drawbridge/drawbridge-agents 0.1.19 → 0.1.21

package/.claude-template/hooks/README.md

@@ -1,5 +1,12 @@
 # Managed by @drawbridge/drawbridge-agents
 
-Hook scripts placed here are mirrored into every consumer repo's `.claude/hooks/` on `npm run sync`. To add a shared hook: drop it in this directory in `drawbridge-agents`, bump the package version, publish, then `npm run sync` in each consumer.
+Shared hook scripts are mirrored into every consumer repo's `.claude/hooks/` on `npm run sync`,
+from the package's `hooks/` directory (the single source). They are **tracked** in each consumer
+and invoked by `.claude/settings.json` via `node ./.claude/hooks/<name>.js` — never through
+`node_modules` — so they keep working in fresh git worktrees that haven't run `npm install`.
 
-Consumer-local hooks should be added directly to the consumer's `.claude/hooks/` with a different filename — the sync mirror only overwrites paths that exist in this template.
+To add or change a shared hook: edit it in `drawbridge-agents/hooks/`, bump the package version,
+publish, then `npm run sync` in each consumer and commit the mirrored `.claude/` changes.
+
+Consumer-local hooks can be added directly to the consumer's `.claude/hooks/` with a different
+filename — the sync mirror only overwrites paths that exist in the package.

package/.claude-template/settings.json

@@ -41,7 +41,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ./node_modules/@drawbridge/drawbridge-agents/hooks/guard-superpowers-docs.js"
+            "command": "node ./.claude/hooks/guard-superpowers-docs.js"
           }
         ]
       }
@@ -52,7 +52,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node ./node_modules/@drawbridge/drawbridge-agents/hooks/drift-check.js"
+            "command": "node ./.claude/hooks/drift-check.js"
           }
         ]
       }

package/bin/sync-claude.js

@@ -43,9 +43,13 @@ const mirror = (src, dst) => {
 // 1. Mirror the single source of truth into the consumer. .claude-template holds the entire
 //    shared .claude/ setup (settings.json incl. permissions + the drift-check Stop hook, plus
 //    agents/commands/hooks/skills); .root-template holds root files (.mcp.json, .editorconfig).
+//    The package's hooks/ scripts are mirrored into the consumer's tracked .claude/hooks/ so
+//    settings.json can invoke them without node_modules — a fresh worktree that hasn't run
+//    npm install would otherwise fail open and lose the guard.
 const mirrorTemplates = () => {
   const targets = [
     { src: path.join(packageRoot, '.claude-template'), dst: path.join(consumerRoot, '.claude'), required: true },
+    { src: path.join(packageRoot, 'hooks'), dst: path.join(consumerRoot, '.claude', 'hooks'), required: true },
     { src: path.join(packageRoot, '.root-template'), dst: consumerRoot, required: false }
   ]
   for (const { src, dst, required } of targets) {

package/conventions/cross-repo-contracts.md

@@ -40,7 +40,14 @@ skill) so it stops living only in tribal memory.
   Emitting first hands the client a stale menu nothing re-emits to correct (the stuck-dot bug).
   Workflow doc changes have **no** socket event, so app-web workflow status mutations
   (pause/resume/delete) invalidate the menu client-side themselves.
-- Scraped-asset file reuse keys on `organization + meta.origin + meta.element` **plus
+- Notification dedupe has two distinct mechanisms — pick by intent. `notification.coalesce`
+  is **last-write-wins supersede** (stream/notification.js deletes the prior doc sharing the
+  key); `notification.key` is **first-write-wins idempotency** — a partial unique index in
+  drawbridge-api `schema/notification.js` refuses the duplicate with E11000, which the writer
+  must swallow as already-notified (sync queue/connection.js rehydrate,
+  `ads-republishing.<connectionId>`). Never unique-index `coalesce` (superseding requires the
+  second insert to land), and writes that set `key` need the writer-side E11000 handler or a
+  replayed event logs a false error.
   `meta.render` for pipeline-rendered marks** (sync `resolveAsset` writes/queries it; the field
   and its index live in drawbridge-api `schema/file.js`). `origin` identifies the source asset,
   `render` content-hashes the rendered output — drop `render` from either side and a rendering

package/hooks/drift-check.js

@@ -7,7 +7,16 @@ const path = require('path')
 const { execFileSync } = require('child_process')
 
 const SOURCE_EXTENSIONS = new Set([ '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs' ])
-const packageRoot = path.resolve(__dirname, '..')
+
+// This file runs from two places: hooks/ inside the package (the
+// drawbridge-agents repo itself, or node_modules) where scripts/ is a sibling,
+// and the mirrored copy in a consumer's tracked .claude/hooks/, where it
+// isn't — there, resolve through the consumer's installed package.
+const resolvePackageRoot = (cwd) => {
+  const local = path.resolve(__dirname, '..')
+  if (fs.existsSync(path.join(local, 'scripts', 'check-doc-links.js'))) return local
+  return path.join(cwd, 'node_modules', '@drawbridge', 'drawbridge-agents')
+}
 
 const block = (reason) => {
   process.stdout.write(JSON.stringify({ decision: 'block', reason }))
@@ -51,17 +60,27 @@ const run = () => {
 
   const cwd = input.cwd || process.cwd()
   const changed = changedFiles(cwd)
-  const changedSource = changed.filter((file) => SOURCE_EXTENSIONS.has(path.extname(file)))
+
+  // .claude/ churn is sync-mirror tooling (including this hook's own mirrored
+  // copy), not project source — it must not trip the drift checks.
+  const changedSource = changed.filter((file) =>
+    SOURCE_EXTENSIONS.has(path.extname(file)) && !file.split(path.sep).includes('.claude')
+  )
 
   // Pure Q&A / non-source turns: nothing to check.
   if (changedSource.length === 0) process.exit(0)
 
-  // 1. Doc-link validity (blocking) — cheap, precise, quick to fix.
-  try {
-    execFileSync('node', [ path.join(packageRoot, 'scripts', 'check-doc-links.js') ], { cwd, encoding: 'utf8', stdio: 'pipe' })
-  } catch (error) {
-    const detail = ((error.stdout || '') + (error.stderr || '')).trim()
-    block(`Documentation drift: one or more @story / @doc tags no longer resolve.\n${ detail }\nFix the tag(s) to point at a real drawbridge-docs story ID / reference anchor before finishing.`)
+  // 1. Doc-link validity (blocking) — cheap, precise, quick to fix. A missing
+  //    checker (fresh worktree with no node_modules) is not drift — skip, never
+  //    block on it.
+  const checkDocLinks = path.join(resolvePackageRoot(cwd), 'scripts', 'check-doc-links.js')
+  if (fs.existsSync(checkDocLinks)) {
+    try {
+      execFileSync('node', [ checkDocLinks ], { cwd, encoding: 'utf8', stdio: 'pipe' })
+    } catch (error) {
+      const detail = ((error.stdout || '') + (error.stderr || '')).trim()
+      block(`Documentation drift: one or more @story / @doc tags no longer resolve.\n${ detail }\nFix the tag(s) to point at a real drawbridge-docs story ID / reference anchor before finishing.`)
+    }
   }
 
   const skipGraph = process.env.DRAWBRIDGE_SKIP_GRAPHIFY === '1'
@@ -100,7 +119,9 @@ const run = () => {
   })
   const touchedDocs = changed.some((file) => file.includes(`${ path.sep }drawbridge-docs${ path.sep }`))
   if (touchedAnchoredCode && !touchedDocs) {
-    nudge('You changed code that implements a documented behaviour (carries an @story anchor) without touching drawbridge-docs. Confirm the matching user story still matches, or update it in this change.')
+    // `@story` is backticked so doc-link scanners (including stale node_modules
+    // copies that don't skip .claude/) never read this sentence as a real tag.
+    nudge('You changed code that implements a documented behaviour (carries an `@story` anchor) without touching drawbridge-docs. Confirm the matching user story still matches, or update it in this change.')
   }
 
   process.exit(0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {

package/scripts/check-doc-links.js

@@ -6,7 +6,9 @@ const fs = require('fs')
 const path = require('path')
 
 const SOURCE_EXTENSIONS = new Set([ '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs' ])
-const SKIP_DIRS = new Set([ 'node_modules', '.git', '.next', 'dist', 'build', 'coverage', '.turbo', 'graphify-out' ])
+// .claude is skipped because the sync mirror places shared tooling there (the drift-check hook's
+// own source mentions the tag syntax) — it's not project source and must never be scanned.
+const SKIP_DIRS = new Set([ 'node_modules', '.git', '.next', 'dist', 'build', 'coverage', '.turbo', 'graphify-out', '.claude' ])
 
 // The family root is the directory that contains drawbridge-docs. Walk up from cwd to find it.
 const findFamilyRoot = () => {