@drawbridge/drawbridge-agents 0.1.0 → 0.1.1

package/README.md

@@ -86,12 +86,14 @@ Beyond the conventions, this package gives agents cross-repo visibility and keep
 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` extracts every
-  `drawbridge-*` repo plus `drawbridge-docs` and the shared packages into one queryable graph.
-  Agents query it (via the graphify MCP) instead of grepping. The runtime is a per-machine
-  Python tool — `npm run sync` installs it automatically (`bin/preflight-graphify.js`); set
-  `DRAWBRIDGE_SKIP_GRAPHIFY=1` to skip in CI/headless. First-run note: confirm graphify's exact
-  `extract` / `merge-graphs` / `install` flags against the installed tool (see `bin/graph.js`).
+- **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
@@ -107,7 +109,8 @@ reaches consumers without committing anything to them (see "Isolation").
 ### Isolation (nothing ships to DigitalOcean)
 
 - The package is a **devDependency** → not installed in production.
-- The graphify MCP is delivered via the consumer's `.mcp.json` (already gitignored).
+- 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.

package/bin/graph.js

@@ -1,18 +1,19 @@
 #!/usr/bin/env node
-// Builds the family knowledge graph: extracts every drawbridge-* repo (plus drawbridge-docs and
-// the shared @drawbridge/* packages) into graphify's registry, merges them into
-// graph/merged.json, and writes graph/manifest.json (which the drift hook reads for staleness).
-// Requires the graphify runtime (npm run sync installs it). See conventions/graphify.md.
+// 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.
 //
-// NOTE: the exact graphify subcommand flags (extract/merge-graphs) should be confirmed against
-// the installed tool the first time this runs; adjust if graphify's CLI differs.
+// 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 graphDir = path.join(packageRoot, 'graph')
 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'))
@@ -34,7 +35,7 @@ if (!hasGraphify()) {
   process.exit(1)
 }
 
-fs.mkdirSync(graphDir, { recursive: true })
+fs.mkdirSync(buildDir, { recursive: true })
 
 const built = []
 for (const name of repos) {
@@ -44,17 +45,17 @@ for (const name of repos) {
     continue
   }
   console.log(`  extract ${ name }`)
-  execFileSync('graphify', [ 'extract', repoPath, '--global', '--as', name ], { stdio: 'inherit' })
+  // --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 mergedPath = path.join(graphDir, 'merged.json')
-console.log('  merge -> graph/merged.json')
-execFileSync('graphify', [ 'merge-graphs', '--global', '--out', mergedPath ], { stdio: 'inherit' })
-
-const manifest = {
-  builtAt: new Date().toISOString(),
-  repos: built
-}
-fs.writeFileSync(path.join(graphDir, 'manifest.json'), JSON.stringify(manifest, null, 2) + '\n')
-console.log(`drawbridge-agents-graph: built graph from ${ built.length } repo(s)`)
+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

@@ -48,11 +48,7 @@ if (!has('graphify')) {
   }
 }
 
-// Register the MCP server with the local assistant (idempotent).
-try {
-  execFileSync('graphify', [ 'install' ], { stdio: 'inherit' })
-} catch (error) {
-  console.warn('drawbridge-agents-sync: `graphify install` (MCP registration) failed — run it manually.')
-}
-
-console.log('drawbridge-agents-sync: graphify runtime ready')
+// 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/conventions/graphify.md

@@ -6,17 +6,18 @@ shared packages — built by [Graphify](https://github.com/Graphify-Labs/graphif
 ## 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**. It
-is exposed as an MCP server; you can also use the CLI:
+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?"
-graphify path "drawbridge-app-web" "drawbridge-stripe"
-graphify explain "closeDraw"
+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 plus `drawbridge-docs` and the `@drawbridge/*` packages, so a
-query resolves across the code **and** the specs/contracts layer.
+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
 
@@ -27,11 +28,15 @@ rebuild it:
 npx drawbridge-agents-graph
 ```
 
-This re-extracts every repo and rebuilds the merged graph. The drift-check hook will remind you
-when tracked source has changed since the last build.
+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). If it is ever missing, the drift hook blocks with install instructions — the runtime
-is required, not optional (set `DRAWBRIDGE_SKIP_GRAPHIFY=1` only in CI/headless environments).
+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

@@ -1,13 +1,10 @@
 # Family knowledge graph
 
-Generated artifacts — do not edit by hand. Produced by `npx drawbridge-agents-graph`
-(`bin/graph.js`), which extracts every `drawbridge-*` repo plus `drawbridge-docs` and the shared
-`@drawbridge/*` packages into a single [Graphify](https://github.com/Graphify-Labs/graphify)
-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).
 
-- `merged.json` — the merged, queryable graph (served via the graphify MCP).
-- `manifest.json` — `{ builtAt, repos }`; the drift-check hook reads `builtAt` to tell when the
-  graph is stale relative to changed source.
-
-Both are regenerated by the build script; they are gitignored until the first build populates
-them. See `conventions/graphify.md` for how agents query and refresh the graph.
+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

@@ -3,6 +3,7 @@
 // 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')
 
@@ -69,14 +70,12 @@ const run = () => {
   // 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 manifestPath = path.join(packageRoot, 'graph', 'manifest.json')
+    const globalGraph = path.join(os.homedir(), '.graphify', 'global-graph.json')
     let builtAt = 0
-    if (fs.existsSync(manifestPath)) {
-      try {
-        builtAt = Date.parse(JSON.parse(fs.readFileSync(manifestPath, 'utf8')).builtAt) || 0
-      } catch (error) {
-        builtAt = 0
-      }
+    try {
+      builtAt = fs.statSync(globalGraph).mtimeMs
+    } catch (error) {
+      builtAt = 0
     }
     const stale = changedSource.some((file) => {
       try {

package/package.json

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