@drawbridge/drawbridge-agents 0.0.11 → 0.1.1

package/README.md

@@ -9,37 +9,50 @@ Before this package, every drawbridge-* repo carried a byte-identical copy of th
 ## Layout
 
 ```
-conventions/                ← canonical, agent-neutral content
-  rules.md
-  javascript-formatting.md
-  nested-objects.md
-  jsx-fragments.md
-  transactions.md
-  property-shorthand.md
+conventions/                ← canonical, agent-neutral content (@-imported into CLAUDE.md)
+  rules.md, javascript-formatting.md, ...
+  ecosystem.md              ← always-loaded architecture map of the 16 repos
+  cross-repo-contracts.md   ← load-bearing invariants that break across repos
+  docs-linkage.md           ← consult the spec + @story/@doc code anchors
+  graphify.md               ← query the family knowledge graph before grepping
 
 claude/
   CLAUDE.md                 ← aggregator — @-imports every conventions/*.md
 
 .claude-template/           ← mirrored into each consumer repo's .claude/
   settings.json             ← shared permissions/env
-  hooks/
-  agents/
-  commands/
+  hooks/  agents/  commands/
 
 .root-template/             ← mirrored into each consumer repo's root
-  .mcp.json                 ← project-level MCP servers (e.g. Sentry)
+  .mcp.json                 ← project-level MCP servers (e.g. Sentry) — gitignored in consumers
   .editorconfig             ← family-wide editor defaults (tabs, lf, utf-8)
 
 bin/
-  sync-claude.js            ← drawbridge-agents-sync — mirrors templates into consumer repo
+  sync-claude.js            ← drawbridge-agents-sync — mirrors templates + installs hook/skills + graphify preflight
+  graph.js                  ← drawbridge-agents-graph — builds the merged family knowledge graph
+  preflight-graphify.js     ← ensures the graphify runtime is installed (called by sync)
+
+scripts/
+  check-doc-links.js        ← drawbridge-agents-check-docs — validates @story/@doc tags resolve
+
+hooks/
+  drift-check.js            ← Stop hook — blocks on unresolved doc tags, nudges on stale graph
+
+skills/                     ← shared skills, installed to user-level ~/.claude/skills on sync
+  drawbridge-asana-ship-handoff/  drawbridge-ship-feature/
+  drawbridge-explore-ecosystem/   drawbridge-record-contract/
+
+graph/                      ← generated (gitignored) merged.json + manifest.json; see graph/README.md
 ```
 
 ## Consuming from a drawbridge-* repo
 
-1. Install:
+1. Install as a **devDependency** (this package is agent-tooling only — no app-runtime imports —
+   so it must not ship to production / DigitalOcean):
    ```bash
-   npm install --save-exact @drawbridge/drawbridge-agents
+   npm install --save-exact --save-dev @drawbridge/drawbridge-agents
    ```
+   Ensure the app's deploy install step omits devDependencies (`npm ci --omit=dev`).
 
 2. Replace the repo's `CLAUDE.md` with a thin import file:
    ```markdown
@@ -67,6 +80,43 @@ bin/
 
 Claude Code's `@` imports cascade — one import line resolves the whole tree under `claude/CLAUDE.md`.
 
+## Ecosystem knowledge, graph, and drift checks
+
+Beyond the conventions, this package gives agents cross-repo visibility and keeps code, docs,
+and the knowledge graph from drifting. Everything below is committed **only in this repo** and
+reaches consumers without committing anything to them (see "Isolation").
+
+- **Family knowledge graph (Graphify).** `npx drawbridge-agents-graph` runs code-only AST
+  extraction over every `drawbridge-*` repo and merges them into the cross-repo graph at
+  `~/.graphify/global-graph.json`. Agents query it with the `graphify` CLI (e.g.
+  `graphify query "…" --graph ~/.graphify/global-graph.json`) instead of grepping. The runtime is
+  a per-machine Python tool — `npm run sync` installs it (`bin/preflight-graphify.js`); set
+  `DRAWBRIDGE_SKIP_GRAPHIFY=1` to skip in CI/headless. We deliberately do **not** run
+  `graphify install` (it would rewrite `CLAUDE.md`); the optional `graphify-mcp` server is
+  available if you prefer MCP.
+- **Docs linkage + validator.** Feature code carries `@story <domain>/<slug>` / `@doc
+  reference/<file>#<anchor>` anchors (see `conventions/docs-linkage.md`).
+  `npx drawbridge-agents-check-docs` scans every repo and fails if any anchor no longer resolves
+  against `drawbridge-docs`.
+- **Drift-check Stop hook.** `hooks/drift-check.js` runs at each task-turn end (installed into the
+  consumer's gitignored `.claude/settings.local.json`). It **blocks** on an unresolved doc
+  anchor, and **nudges** (non-blocking) when the graph looks stale or docs may need updating. It
+  skips plan-mode and turns with no source changes.
+- **Shared skills.** Installed to user-level `~/.claude/skills/` on sync:
+  `drawbridge-ship-feature` (verify → docs → graph → handoff), `drawbridge-asana-ship-handoff`,
+  `drawbridge-explore-ecosystem`, `drawbridge-record-contract`.
+
+### Isolation (nothing ships to DigitalOcean)
+
+- The package is a **devDependency** → not installed in production.
+- The graph and CLI are per-machine (`~/.graphify/`); nothing graph-related is written into the
+  consumer repo, and `graphify install` (which edits `CLAUDE.md`) is never run.
+- The Stop hook is merged into `.claude/settings.local.json` (gitignored).
+- Skills install to `~/.claude/skills/` (per-machine, outside any repo).
+- The only in-repo footprint in consumers is inert `@story`/`@doc` source comments.
+
+After `npm run sync`, `git status` in a consumer should show **no new tracked files**.
+
 ## Updating a rule or shared `.claude/` file
 
 1. Edit the relevant `conventions/<file>.md` or `.claude-template/<path>`.

package/bin/graph.js

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Builds the family knowledge graph: runs graphify's headless AST extraction over every
+// drawbridge-* repo (plus drawbridge-docs and the shared @drawbridge/* packages) and merges
+// each into the global cross-repo graph at ~/.graphify/global-graph.json — which is what agents
+// query. Code-only (local AST, no API key). See conventions/graphify.md.
+//
+// A semantic build (adds doc/paper content + INFERRED edges) needs an LLM backend: drop
+// --code-only and set an API key (e.g. ANTHROPIC_API_KEY) — slower and costs LLM calls.
+const fs = require('fs')
+const os = require('os')
+const path = require('path')
+const { execFileSync } = require('child_process')
+
+const packageRoot = path.resolve(__dirname, '..')
+const familyRoot = path.resolve(packageRoot, '..')
+const buildDir = path.join(os.homedir(), '.graphify', 'build')
+
+// The canonical family list lives in the shared settings template — single source of truth.
+const settings = JSON.parse(fs.readFileSync(path.join(packageRoot, '.claude-template', 'settings.json'), 'utf8'))
+const repos = settings.permissions.additionalDirectories
+  .map((entry) => path.basename(entry))
+  .filter((name) => name !== 'drawbridge-agents')
+
+const hasGraphify = () => {
+  try {
+    execFileSync('graphify', [ '--version' ], { stdio: 'ignore' })
+    return true
+  } catch (error) {
+    return false
+  }
+}
+
+if (!hasGraphify()) {
+  console.error('drawbridge-agents-graph: graphify runtime not found. Install it first: uv tool install graphifyy')
+  process.exit(1)
+}
+
+fs.mkdirSync(buildDir, { recursive: true })
+
+const built = []
+for (const name of repos) {
+  const repoPath = path.join(familyRoot, name)
+  if (!fs.existsSync(repoPath)) {
+    console.warn(`  skip ${ name } (not found at ${ repoPath })`)
+    continue
+  }
+  console.log(`  extract ${ name }`)
+  // --out redirects the per-repo graphify-out/ away from the repo (keeps it clean);
+  // --global merges the result into ~/.graphify/global-graph.json under the --as tag.
+  execFileSync(
+    'graphify',
+    [ 'extract', repoPath, '--out', path.join(buildDir, name), '--global', '--as', name, '--code-only' ],
+    { stdio: 'inherit' }
+  )
+  built.push(name)
+}
+
+const globalGraph = path.join(os.homedir(), '.graphify', 'global-graph.json')
+console.log(`drawbridge-agents-graph: built cross-repo graph from ${ built.length } repo(s)`)
+console.log(`  global graph: ${ globalGraph }`)
+console.log('  query it:     graphify query "<question>" --graph ' + globalGraph)

package/bin/preflight-graphify.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+// Ensures the graphify runtime is installed (required for the family knowledge graph) and
+// registers its MCP server with the local assistant. Called by drawbridge-agents-sync.
+// Set DRAWBRIDGE_SKIP_GRAPHIFY=1 to skip in CI / headless environments.
+const { execFileSync } = require('child_process')
+
+if (process.env.DRAWBRIDGE_SKIP_GRAPHIFY === '1') {
+  console.log('drawbridge-agents-sync: DRAWBRIDGE_SKIP_GRAPHIFY set — skipping graphify preflight')
+  process.exit(0)
+}
+
+const has = (cmd) => {
+  try {
+    execFileSync(cmd, [ '--version' ], { stdio: 'ignore' })
+    return true
+  } catch (error) {
+    return false
+  }
+}
+
+if (!has('graphify')) {
+  console.log('drawbridge-agents-sync: graphify runtime not found, attempting install...')
+  const attempts = [
+    [ 'uv', [ 'tool', 'install', 'graphifyy' ] ],
+    [ 'pipx', [ 'install', 'graphifyy' ] ],
+    [ 'pip', [ 'install', '--user', 'graphifyy' ] ],
+    [ 'pip3', [ 'install', '--user', 'graphifyy' ] ]
+  ]
+  for (const [ cmd, args ] of attempts) {
+    if (!has(cmd)) continue
+    try {
+      execFileSync(cmd, args, { stdio: 'inherit' })
+      break
+    } catch (error) {
+      // try the next installer
+    }
+  }
+  if (!has('graphify')) {
+    console.error([
+      'drawbridge-agents-sync: could not install the graphify runtime automatically.',
+      'Install it, then re-run npm run sync:',
+      '  uv tool install graphifyy   (recommended)',
+      '  pipx install graphifyy',
+      '  pip install --user graphifyy',
+      'Or set DRAWBRIDGE_SKIP_GRAPHIFY=1 to skip (CI / headless only).'
+    ].join('\n'))
+    process.exit(1)
+  }
+}
+
+// Note: we deliberately do NOT run `graphify install` — it writes a graphify section into the
+// repo's CLAUDE.md and a PreToolUse hook, which would mutate a committed file and clash with the
+// shared CLAUDE.md. Agents use the graphify CLI directly (see conventions/graphify.md).
+console.log('drawbridge-agents-sync: graphify runtime ready (run `npx drawbridge-agents-graph` to build the graph)')

package/bin/sync-claude.js

@@ -1,15 +1,12 @@
 #!/usr/bin/env node
 const fs = require('fs')
+const os = require('os')
 const path = require('path')
+const { execFileSync } = require('child_process')
 
 const consumerRoot = process.env.INIT_CWD || process.cwd()
 const packageRoot = path.resolve(__dirname, '..')
 
-const targets = [
-  { src: path.join(packageRoot, '.claude-template'), dst: path.join(consumerRoot, '.claude'), required: true },
-  { src: path.join(packageRoot, '.root-template'), dst: consumerRoot, required: false },
-]
-
 const copied = []
 
 const mirror = (src, dst) => {
@@ -26,16 +23,80 @@ const mirror = (src, dst) => {
   }
 }
 
-for (const { src, dst, required } of targets) {
-  if (!fs.existsSync(src)) {
-    if (required) {
-      console.error(`drawbridge-agents-sync: template not found at ${src}`)
-      process.exit(1)
+// 1. Mirror the committed template dirs into the consumer (existing behaviour).
+const mirrorTemplates = () => {
+  const targets = [
+    { src: path.join(packageRoot, '.claude-template'), dst: path.join(consumerRoot, '.claude'), required: true },
+    { src: path.join(packageRoot, '.root-template'), dst: consumerRoot, required: false }
+  ]
+  for (const { src, dst, required } of targets) {
+    if (!fs.existsSync(src)) {
+      if (required) {
+        console.error(`drawbridge-agents-sync: template not found at ${ src }`)
+        process.exit(1)
+      }
+      continue
+    }
+    mirror(src, dst)
+  }
+  console.log(`drawbridge-agents-sync: ${ copied.length } file(s) mirrored`)
+  for (const p of copied) console.log(`  ${ p }`)
+}
+
+// 2. Merge the drift-check Stop hook into the consumer's gitignored .claude/settings.local.json,
+//    so nothing is committed to the consumer repo (see conventions/docs-linkage.md).
+const installStopHook = () => {
+  const command = 'node ./node_modules/@drawbridge/drawbridge-agents/hooks/drift-check.js'
+  const settingsPath = path.join(consumerRoot, '.claude', 'settings.local.json')
+
+  let settings = {}
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'))
+    } catch (error) {
+      console.warn('drawbridge-agents-sync: could not parse .claude/settings.local.json — leaving Stop hook uninstalled')
+      return
     }
-    continue
   }
-  mirror(src, dst)
+
+  settings.hooks = settings.hooks || {}
+  settings.hooks.Stop = settings.hooks.Stop || []
+
+  const already = settings.hooks.Stop.some((entry) =>
+    (entry.hooks || []).some((hook) => typeof hook.command === 'string' && hook.command.includes('drawbridge-agents/hooks/drift-check.js'))
+  )
+  if (already) return
+
+  settings.hooks.Stop.push({
+    matcher: '',
+    hooks: [ { type: 'command', command } ]
+  })
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true })
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n')
+  console.log('drawbridge-agents-sync: drift-check Stop hook installed in .claude/settings.local.json')
+}
+
+// 3. Install the shared skills to the user-level ~/.claude/skills/ (per-machine, so nothing is
+//    committed to any consumer repo). Only drawbridge-* skills are managed.
+const installSkills = () => {
+  const src = path.join(packageRoot, 'skills')
+  if (!fs.existsSync(src)) return
+  const dst = path.join(os.homedir(), '.claude', 'skills')
+  let count = 0
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !entry.name.startsWith('drawbridge-')) continue
+    mirror(path.join(src, entry.name), path.join(dst, entry.name))
+    count += 1
+  }
+  if (count > 0) console.log(`drawbridge-agents-sync: ${ count } shared skill(s) installed to ~/.claude/skills/`)
+}
+
+// 4. Ensure the graphify runtime is present + MCP registered (hard-fails if it can't be).
+const graphifyPreflight = () => {
+  execFileSync('node', [ path.join(packageRoot, 'bin', 'preflight-graphify.js') ], { stdio: 'inherit' })
 }
 
-console.log(`drawbridge-agents-sync: ${copied.length} file(s) mirrored`)
-for (const p of copied) console.log(`  ${p}`)
+mirrorTemplates()
+installStopHook()
+installSkills()
+graphifyPreflight()

package/claude/CLAUDE.md

@@ -1,3 +1,5 @@
+@../conventions/ecosystem.md
+@../conventions/cross-repo-contracts.md
 @../conventions/karpathy-guidelines.md
 @../conventions/rules.md
 @../conventions/javascript-formatting.md
@@ -10,3 +12,5 @@
 @../conventions/drawbridge-packages.md
 @../conventions/sentry-sdk.md
 @../conventions/app-web-forms.md
+@../conventions/docs-linkage.md
+@../conventions/graphify.md

package/conventions/cross-repo-contracts.md

@@ -0,0 +1,46 @@
+# Cross-repo contracts
+
+Invariants that only break when you touch two repos at once. Know these **before** a
+cross-repo change. Each is a one-liner; fuller detail lives in `drawbridge-docs/reference/`
+and the graph. When you discover a new one, record it here (see the `drawbridge-record-contract`
+skill) so it stops living only in tribal memory.
+
+## Shared secrets must match across services
+
+- `OAUTH_TOKEN_HMAC_KEY` must be identical in **drawbridge-api** and **drawbridge-sync** — both
+  `assertEnv` it at boot. A mismatch silently breaks realtime token verification.
+
+## Sync owns reactive side effects
+
+- All socket emits from sync go through `drawbridge-sync/lib/emit.js` — never call
+  `io.to().emit()` directly from a worker.
+- Cascade cleanup of dependent rows belongs in a sync change-stream listener, not inline in the
+  API route that triggered the delete (see `cascade-cleanup.md`).
+- A collection with no `queue/<collection>.js` handler is watched but its events are **silently
+  dropped**. Adding a reactive collection means wiring `stream/index.js`, `lib/queue.js`, and
+  `queue/index.js` together.
+- BullMQ jobs are keyed on the change-stream resume token as `jobId` for HA dedup across sync
+  replicas. Reusing a static `jobId` with `removeOnComplete` makes re-enqueues no-op silently.
+
+## Billing / metering
+
+- Meter events are **single-writer**: true-ups are `billing.trueup` ledger rows, never meter
+  events. A true-up written as a meter event in-window corrupts the reflection poll and strands
+  units unbillable.
+- Every `$inc` on a `totals.*` counter needs a matching entry in `drawbridge-sync/lib/totals.js`
+  `SOURCES` — that map is the only drift backstop.
+
+## `@drawbridge/*` package coordination
+
+- Pins are version-exact across the whole family; bumping one package means auditing every
+  sibling's `peerDependencies` for a stale pin (see `drawbridge-packages.md`).
+- `stripe`/`shopify` externalise `utils`; a pin mismatch spawns a nested duplicate copy of utils
+  in the tree. Keep the pins aligned.
+- Shared packages that wrap a stateful SDK (Sentry, redis, mongodb) must direct-dep it at an
+  exact pin, never a loose peer range (see `sentry-sdk.md`).
+
+## Import surfaces
+
+- Import names against a package's **actual exports** — a missing export resolves to `undefined`
+  and throws at call time, not at import. Check `drawbridge-docs/reference/packages.md` (the
+  generated export surface) when unsure.

package/conventions/docs-linkage.md

@@ -0,0 +1,51 @@
+# Docs linkage — keep code and specs in sync
+
+`drawbridge-docs` is the product spec. Every user-facing behaviour has a user story with a
+**stable ID** (`<domain>/<slug>`, e.g. `auth/email-sign-up`, `campaigns/create-draw`), and
+developer lookups live in `reference/<file>.md` keyed by stable filename + heading anchor.
+Story IDs never change; only the `NN-`/`01-` file-name numbers shift, so never cite those.
+
+## Before you change a documented behaviour
+
+1. Find the matching story by its **ID** (the story-index table in each
+   `user-stories/NN-<domain>/README.md` maps ID → file) or the relevant `reference/` doc, and
+   read it first.
+2. Implement **to match the spec**.
+3. If your change would diverge from the spec, **STOP and flag the drift** — do not silently
+   diverge. Offer to update the doc in the same change set (use the `write-user-stories` skill
+   for a new/edited story), or state explicitly that the doc needs updating.
+4. Keep docs and code linked in one change: a behaviour change edits the story / reference doc
+   alongside the code.
+
+## Back-reference tags in code
+
+Feature-implementing code carries a stable back-reference to the doc it upholds, so a reader
+(and the link validator) can trace code → spec:
+
+```js
+// @story campaigns/create-draw
+// Draw close is idempotent: re-entry after payout must not re-run winner selection.
+const closeDraw = async ( draw ) => {
+```
+
+- Use `// @story <domain>/<slug>` for user-story behaviour, or
+  `// @doc reference/<file>.md#<anchor>` for a developer-reference invariant.
+- Follow the tag with a brief line stating the invariant or spec it upholds. The tag is the
+  machine anchor; the sentence is the meaning.
+- Anchor **where behaviour maps to a documented story** — not on every function. Match the
+  surrounding comment density (see `karpathy-guidelines.md`); this is not a licence for
+  blanket verbose comments.
+
+## When a doc is renamed or an anchor changes
+
+Story IDs are stable by design, so the fragile case is a `reference/` file rename or a heading
+(anchor) change. When one happens, grep every sibling repo for the old `@doc`/`@story` tag and
+update every hit in the same change:
+
+```sh
+grep -rn "@doc reference/<old-file>" /Users/darrenshea/Projects/drawbridge-* --include="*.js"
+```
+
+The `drawbridge-agents-check-docs` validator scans all repos and fails when any `@story`/`@doc`
+tag no longer resolves to a real story ID or reference anchor — run it (or let the drift hook
+run it) before finishing a change.

package/conventions/ecosystem.md

@@ -0,0 +1,46 @@
+# Ecosystem map
+
+Drawbridge is ~16 `drawbridge-*` repos that communicate **through MongoDB**, not by calling
+each other. This is the baseline; query the graphify MCP (`graphify query`, see
+`graphify.md`) for anything deeper, and see `drawbridge-docs/diagrams/01-system-map.md` for
+the full diagram.
+
+## The core rule
+
+The API mutates documents; **sync reacts**. Reactive side effects (cache busts, notifications,
+downstream enqueues, counter maintenance beyond the request's own totals) live in
+`drawbridge-sync/queue/<collection>.js`, **not** in API route handlers. All inter-service
+communication is mediated through MongoDB via change streams.
+
+## Services (deployed)
+
+- **drawbridge-api** — Express HTTP API + Socket.io. Reads/writes MongoDB. Owns route handlers,
+  not background workers.
+- **drawbridge-webhooks** — separate Express service; ingests third-party webhooks (Shopify,
+  Stripe) and writes `buffer` documents to MongoDB.
+- **drawbridge-sync** — subscribes to MongoDB change streams for ~40 collections
+  (`stream/index.js`), routes events to per-collection BullMQ queues (Redis), and runs the
+  workers that do all reactive work. Also owns the centralised socket emitter (`lib/emit.js`).
+- **drawbridge-app-web / share / website** — Next.js apps that call the API over HTTPS and
+  listen on Socket.io for live updates. `share` serves the public campaign pages.
+- **drawbridge-shopify-app** — hosted embedded Shopify admin app.
+
+## Shared libraries (`@drawbridge/*` packages)
+
+Consumed by the services; published to npm. **utils** (`@drawbridge/drawbridge-utils`),
+**components** (shared UI + icons), **mongodb**, **redis**, **stripe**, **shopify**,
+**telemetry**, **emails**. Pins are version-exact and must be aligned family-wide when bumped
+(see `drawbridge-packages.md`).
+
+## Data + infra
+
+- **MongoDB** — single source of truth (~50 collections). Change streams drive sync.
+- **Redis** — backs BullMQ queues (`@drawbridge/drawbridge-redis`, connection `sync:shared`).
+- **drawbridge-docs** — the product spec (user stories + reference). Not deployed.
+- **drawbridge-agents** — this package: the single source of shared agent instructions.
+
+## Where to go deeper
+
+The load-bearing invariants that break *across* repos are in `cross-repo-contracts.md`. The
+generated `drawbridge-docs/reference/collections.md`, `queues.md`, `packages.md`, and
+`versions.md` are the freshest structural facts. Trace anything else with the graph.

package/conventions/graphify.md

@@ -0,0 +1,42 @@
+# The family knowledge graph (Graphify)
+
+There is a queryable knowledge graph of the whole `drawbridge-*` family — code, docs, and the
+shared packages — built by [Graphify](https://github.com/Graphify-Labs/graphify).
+
+## Query the graph before grepping across repos
+
+When you need to trace behaviour that spans repos (api ↔ sync ↔ stripe ↔ app-web, who emits an
+event, what depends on a package), **query the graph instead of grepping 16 directories**. The
+cross-repo graph lives at `~/.graphify/global-graph.json`; point the CLI at it with `--graph`:
+
+```sh
+graphify query "what connects sync change streams to the billing meter?" --graph ~/.graphify/global-graph.json
+graphify path "drawbridge-app-web" "drawbridge-stripe" --graph ~/.graphify/global-graph.json
+graphify explain "closeDraw" --graph ~/.graphify/global-graph.json
+graphify affected "closeDraw" --graph ~/.graphify/global-graph.json
+```
+
+The graph spans all sibling repos (code, via local AST). A semantic build additionally pulls in
+`drawbridge-docs` and richer INFERRED edges — see "Refreshing it".
+
+## Refreshing it
+
+The graph is as fresh as the last build. After a change that alters cross-repo structure,
+rebuild it:
+
+```sh
+npx drawbridge-agents-graph
+```
+
+This re-extracts every repo (code-only, no API key) and merges them into the global graph. The
+drift-check hook nudges when tracked source has changed since the last build. For a semantic
+build that also indexes docs, run `graphify extract <repo> --global --as <repo>` with an LLM
+backend / API key set (slower, costs LLM calls).
+
+## Runtime
+
+Graphify is a per-machine Python tool; `npm run sync` installs it automatically (see the sync
+preflight — `uv tool install graphifyy`). Set `DRAWBRIDGE_SKIP_GRAPHIFY=1` to skip in CI/headless
+environments. The MCP server (`graphify-mcp <graph.json>`) is available if you prefer it, but is
+**not** auto-registered — `graphify install` would rewrite CLAUDE.md, which we keep managed by
+this package.

package/graph/README.md

@@ -0,0 +1,10 @@
+# Family knowledge graph
+
+The cross-repo knowledge graph is built by `npx drawbridge-agents-graph` (`bin/graph.js`), which
+runs [Graphify](https://github.com/Graphify-Labs/graphify) headless AST extraction over every
+`drawbridge-*` repo and merges each into the **global** graph at
+`~/.graphify/global-graph.json` (per machine, not committed).
+
+That global graph is what agents query — see `conventions/graphify.md`. There are no committed
+artifacts in this directory; it holds this README only. Per-repo extraction output is redirected
+to `~/.graphify/build/` so it never litters the source repos.

package/hooks/drift-check.js

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// Stop hook: at the end of a task turn, check that docs and the knowledge graph haven't drifted.
+// Blocks (must fix) on unresolved @story/@doc tags; nudges (non-blocking) on a stale graph or
+// likely doc drift. Gated so it never fires on trivial turns. See conventions/docs-linkage.md.
+const fs = require('fs')
+const os = require('os')
+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, '..')
+
+const block = (reason) => {
+  process.stdout.write(JSON.stringify({ decision: 'block', reason }))
+  process.exit(0)
+}
+
+const nudge = (additionalContext) => {
+  process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: 'Stop', additionalContext } }))
+  process.exit(0)
+}
+
+const readStdin = () => {
+  try {
+    return JSON.parse(fs.readFileSync(0, 'utf8') || '{}')
+  } catch (error) {
+    return {}
+  }
+}
+
+// Files changed in the working tree (staged, unstaged, untracked), relative to cwd.
+const changedFiles = (cwd) => {
+  try {
+    const out = execFileSync('git', [ 'status', '--porcelain', '-uall' ], { cwd, encoding: 'utf8' })
+    return out.split('\n')
+      .map((line) => line.slice(3).trim())
+      .filter(Boolean)
+      .map((rel) => path.join(cwd, rel))
+  } catch (error) {
+    return []
+  }
+}
+
+const run = () => {
+  const input = readStdin()
+
+  // Final loop-safety escape: if we've already blocked repeatedly, let the turn end.
+  if (input.stop_hook_active) process.exit(0)
+
+  // Nothing to enforce on planning turns.
+  if (input.permission_mode === 'plan') process.exit(0)
+
+  const cwd = input.cwd || process.cwd()
+  const changed = changedFiles(cwd)
+  const changedSource = changed.filter((file) => SOURCE_EXTENSIONS.has(path.extname(file)))
+
+  // 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.`)
+  }
+
+  const skipGraph = process.env.DRAWBRIDGE_SKIP_GRAPHIFY === '1'
+
+  // 2. Graph freshness (non-blocking nudge) — a full re-extract is expensive, so alert rather
+  //    than block on every edit turn. Flip to block() if you want it enforced hard.
+  if (!skipGraph) {
+    const globalGraph = path.join(os.homedir(), '.graphify', 'global-graph.json')
+    let builtAt = 0
+    try {
+      builtAt = fs.statSync(globalGraph).mtimeMs
+    } catch (error) {
+      builtAt = 0
+    }
+    const stale = changedSource.some((file) => {
+      try {
+        return fs.statSync(file).mtimeMs > builtAt
+      } catch (error) {
+        return false
+      }
+    })
+    if (stale) {
+      nudge('Source changed since the family knowledge graph was last built. If this change alters cross-repo structure, regenerate it: npx drawbridge-agents-graph')
+    }
+  }
+
+  // 3. Docs staleness (non-blocking heuristic) — code under a @story-anchored area changed but no
+  //    drawbridge-docs change is in the working tree.
+  const touchedAnchoredCode = changedSource.some((file) => {
+    try {
+      return /@story\s+[a-z0-9]/.test(fs.readFileSync(file, 'utf8'))
+    } catch (error) {
+      return false
+    }
+  })
+  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.')
+  }
+
+  process.exit(0)
+}
+
+try {
+  run()
+} catch (error) {
+  // Never fail a user's turn because of a hook bug.
+  process.exit(0)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.0.11",
+  "version": "0.1.1",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {
@@ -11,7 +11,9 @@
     "build": "npm publish"
   },
   "bin": {
-    "drawbridge-agents-sync": "bin/sync-claude.js"
+    "drawbridge-agents-sync": "bin/sync-claude.js",
+    "drawbridge-agents-graph": "bin/graph.js",
+    "drawbridge-agents-check-docs": "scripts/check-doc-links.js"
   },
   "files": [
     "claude",
@@ -19,6 +21,10 @@
     ".claude-template",
     ".root-template",
     "bin",
+    "hooks",
+    "scripts",
+    "skills",
+    "graph",
     "README.md"
   ],
   "repository": {

package/scripts/check-doc-links.js

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+// Validates @story / @doc back-reference tags in the drawbridge-* repos against drawbridge-docs.
+// @story tags must resolve to a stable user-story ID; @doc tags to a reference file (+ anchor).
+// Exits non-zero (naming file:line) when any tag no longer resolves. See conventions/docs-linkage.md.
+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' ])
+
+// The family root is the directory that contains drawbridge-docs. Walk up from cwd to find it.
+const findFamilyRoot = () => {
+  let dir = process.env.INIT_CWD || process.cwd()
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, 'drawbridge-docs', 'user-stories'))) return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return null
+}
+
+const walk = (dir, onFile) => {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue
+      walk(path.join(dir, entry.name), onFile)
+    } else {
+      onFile(path.join(dir, entry.name))
+    }
+  }
+}
+
+// GitHub-style heading anchor.
+const slug = (text) => text.toLowerCase().replace(/[^\w\s-]/g, '').trim().replace(/\s+/g, '-')
+
+const buildDocIndex = (docsRoot) => {
+  const storyIds = new Set()
+  const docTargets = new Set()
+
+  const storiesRoot = path.join(docsRoot, 'user-stories')
+  walk(storiesRoot, (file) => {
+    if (path.extname(file) !== '.md') return
+    const text = fs.readFileSync(file, 'utf8')
+    const re = /\*\*ID\*\*\s*`([^`]+)`/g
+    let match
+    while ((match = re.exec(text)) !== null) storyIds.add(match[1].trim())
+  })
+
+  const referenceRoot = path.join(docsRoot, 'reference')
+  if (fs.existsSync(referenceRoot)) {
+    for (const name of fs.readdirSync(referenceRoot)) {
+      if (path.extname(name) !== '.md') continue
+      const rel = `reference/${ name }`
+      docTargets.add(rel)
+      const text = fs.readFileSync(path.join(referenceRoot, name), 'utf8')
+      for (const line of text.split('\n')) {
+        const heading = line.match(/^#+\s+(.*)$/)
+        if (heading) docTargets.add(`${ rel }#${ slug(heading[1]) }`)
+      }
+    }
+  }
+
+  return { storyIds, docTargets }
+}
+
+const familyRoot = findFamilyRoot()
+if (!familyRoot) {
+  console.error('drawbridge-agents-check-docs: could not locate drawbridge-docs; run from within the drawbridge-* family')
+  process.exit(1)
+}
+
+const { storyIds, docTargets } = buildDocIndex(path.join(familyRoot, 'drawbridge-docs'))
+const unresolved = []
+
+for (const name of fs.readdirSync(familyRoot, { withFileTypes: true })) {
+  if (!name.isDirectory() || !name.name.startsWith('drawbridge-')) continue
+  // drawbridge-agents is the meta-tooling repo (this script, the hook, the convention docs all
+  // contain the literal tag strings) — tags live in the app repos, so skip it.
+  if (name.name === 'drawbridge-agents') continue
+  const repoRoot = path.join(familyRoot, name.name)
+  walk(repoRoot, (file) => {
+    if (!SOURCE_EXTENSIONS.has(path.extname(file))) return
+    const lines = fs.readFileSync(file, 'utf8').split('\n')
+    lines.forEach((line, index) => {
+      // @story <domain>/<slug>  (stable kebab-case id)
+      const story = line.match(/@story\s+([a-z0-9][a-z0-9/-]*)/)
+      if (story && !storyIds.has(story[1])) {
+        unresolved.push({ file, line: index + 1, tag: `@story ${ story[1] }` })
+      }
+      // @doc reference/<file>.md#<anchor>
+      const doc = line.match(/@doc\s+(reference\/\S+)/)
+      if (doc) {
+        const target = doc[1].replace(/[.,;)]+$/, '')
+        if (!docTargets.has(target)) unresolved.push({ file, line: index + 1, tag: `@doc ${ target }` })
+      }
+    })
+  })
+}
+
+if (unresolved.length === 0) {
+  console.log(`drawbridge-agents-check-docs: all @story / @doc tags resolve (${ storyIds.size } story IDs, ${ docTargets.size } doc targets indexed)`)
+  process.exit(0)
+}
+
+console.error(`drawbridge-agents-check-docs: ${ unresolved.length } unresolved doc reference(s):`)
+for (const item of unresolved) {
+  console.error(`  ${ path.relative(familyRoot, item.file) }:${ item.line }  ${ item.tag }`)
+}
+process.exit(1)

package/skills/drawbridge-asana-ship-handoff/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: drawbridge-asana-ship-handoff
+description: Use when a feature has shipped (merged to develop) against an Asana task — reassigns the task back to its last commenter, posts a concise summary of what changed plus retest/verify steps, and sets the due date to now.
+---
+
+# Asana ship handoff
+
+Hand a shipped feature back to whoever last commented on its Asana task, with everything they
+need to retest. Use this right after merging the work to `develop` (which deploys to dev).
+
+## Inputs
+
+- The Asana task URL or ID for the shipped work. Ask the user for it if it isn't obvious from
+  the branch, PR, or conversation — do not guess.
+- The change you shipped (from the diff / PR).
+
+## Steps
+
+1. **Load the task.** `asana_get_task` with the task gid (extract it from the URL).
+2. **Find the last commenter.** `asana_get_stories_for_task`, filter to comment stories
+   (`type` / `resource_subtype` is a comment, not a system story), take the **most recent**
+   one's `created_by`. This is the reassignee — do not hardcode a person. If there are no
+   comments, ask the user who to assign to.
+3. **Draft the comment.** A concise summary of what changed (not a changelog dump), then an
+   explicit **Retest & verify** section: the exact steps and expected results to confirm the
+   fix, and any data/setup needed. Ground the retest steps in the actual behaviour that
+   changed.
+4. **Confirm before writing.** This posts to an external system. Show the user the chosen
+   assignee and the drafted comment and get a go-ahead, unless they've told you to proceed
+   without asking.
+5. **Apply** (on approval):
+   - `asana_update_task` — set `assignee` to the last commenter's gid and `due_at` to the
+     current date/time (ISO 8601).
+   - `asana_create_task_story` — post the comment.
+6. **Report** the task URL, who it was assigned to, and confirm the due date was updated.
+
+## Notes
+
+- If the Asana MCP isn't connected, stop and tell the user to authorize it — don't fabricate a
+  handoff.
+- Keep the comment user/QA-facing: what to test and expect, not internal implementation detail.
+- Consider running `drawbridge-ship-feature` instead if docs/graph updates for this ship
+  haven't been done yet — this skill is the final step of that flow.

package/skills/drawbridge-explore-ecosystem/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: drawbridge-explore-ecosystem
+description: Use when tracing a behaviour that spans multiple drawbridge-* repos, or onboarding to how the ecosystem connects — drives the Graphify knowledge graph to answer cross-repo questions instead of grepping 16 directories.
+---
+
+# Explore the ecosystem
+
+Answer "how does X connect across the repos?" using the family knowledge graph rather than
+grepping every sibling directory. Use it to trace a cross-repo flow (api ↔ sync ↔ stripe ↔
+app-web), find what depends on a package, or orient someone new to the system.
+
+## Steps
+
+1. **Frame the question** as an entry point or a pair of endpoints: a function, collection,
+   event, package, or repo.
+2. **Query the graph** (graphify MCP, or the CLI):
+   - `graphify query "<natural-language question>"` — semantic subgraph.
+   - `graphify path "<A>" "<B>"` — how two things connect.
+   - `graphify explain "<name>"` — what a symbol is and what touches it.
+3. **Verify against source.** The graph tags edges `EXTRACTED` vs `INFERRED`; confirm the
+   load-bearing hops in the actual files before relying on them.
+4. **Summarise** the flow for the user — the repos and hops involved, and where the detail
+   lives. Cross-check `conventions/cross-repo-contracts.md` for any invariant on the path.
+
+## Notes
+
+- If the graph is stale (the drift hook nudged, or it's been a while), rebuild first:
+  `npx drawbridge-agents-graph`.
+- Start broad (`query`) to locate, then narrow (`path` / `explain`) to trace. The graph spans
+  code, `drawbridge-docs`, and the `@drawbridge/*` packages.

package/skills/drawbridge-record-contract/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: drawbridge-record-contract
+description: Use when you discover a load-bearing invariant that spans two or more drawbridge-* repos (a shared env key, a centralized side-effect path, a coordination rule) — records it in the canonical cross-repo-contracts convention so it stops living only in memory.
+---
+
+# Record a cross-repo contract
+
+When you find (or get burned by) an invariant that only holds if two repos agree, capture it in
+the canonical place so the next agent inherits it. This is how tribal knowledge becomes a rule
+every agent loads.
+
+## When to use
+
+A rule where changing one repo silently breaks another: a shared secret both services read, a
+centralized emitter/handler that must be the only writer, a version-pin or peer-dep coordination
+requirement, a schema/enum shared by copy across repos.
+
+## Steps
+
+1. **Confirm it's real and cross-repo.** Verify the invariant in the actual source of both
+   sides (not just a symptom). If it's single-repo, it belongs in that repo's docs, not here.
+2. **Write it into the convention.** Edit `conventions/cross-repo-contracts.md` in
+   `drawbridge-agents`: add a one-liner under the right heading — what must hold, which repos,
+   and the failure mode if it's violated. Point to fuller detail in `drawbridge-docs/reference/`
+   if it warrants a longer write-up (create/extend a reference doc there).
+3. **Flag the siblings.** If the invariant implies other repos need checking or updating, list
+   them for the user.
+4. **Ship the convention change** through the normal `drawbridge-agents` publish flow (bump
+   version, build, hand the `npm publish --otp` to the user, then bump the pin + `npm run sync`
+   in consumers).
+
+## Notes
+
+- Keep entries terse — this file is always loaded into every agent's context. One line + a
+  pointer, not an essay.
+- Don't duplicate an existing entry; extend it if the nuance is new.

package/skills/drawbridge-ship-feature/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: drawbridge-ship-feature
+description: Use when finishing and shipping a Drawbridge feature (merging to develop) — the closing checklist that verifies the change, keeps drawbridge-docs and the knowledge graph in sync, and hands the Asana task back for retest.
+---
+
+# Ship a feature
+
+The closing workflow for a Drawbridge change. Run it once the implementation is complete and
+you're about to (or just did) merge to `develop`. It ties together verification, docs, the
+knowledge graph, and the Asana handoff so nothing drifts at ship time.
+
+## Steps
+
+1. **Verify it works.** Run the project's verification (the `verify` skill / build / lint /
+   manual smoke — there's no unit-test framework in api/sync/app-web). Confirm the behaviour
+   end-to-end, not just that it compiles.
+2. **Reconcile the spec.** Find the matching `drawbridge-docs` user story by its
+   `<domain>/<slug>` ID (or the relevant `reference/` doc). If behaviour changed, update the
+   story in the same change (use `write-user-stories` for a new/edited story). If you can't,
+   flag the drift explicitly. See `conventions/docs-linkage.md`.
+3. **Confirm doc anchors resolve.** Run `npx drawbridge-agents-check-docs`; fix any unresolved
+   `@story` / `@doc` tag. Add an anchor to newly-added feature code where it maps to a story.
+4. **Refresh the graph** if the change altered cross-repo structure: `npx drawbridge-agents-graph`.
+5. **Hand off the task.** Invoke `drawbridge-asana-ship-handoff` with the Asana task to reassign
+   to the last commenter, post the change summary + retest steps, and set the due date.
+
+## Notes
+
+- Steps 2–4 are what the drift-check Stop hook enforces; running them here means you won't get
+  blocked at turn end.
+- "Shipped" in this family means merged to `develop` (that's the deployed dev environment).