@drafthq/draft 3.7.2 → 5.0.1

package/.claude-plugin/marketplace.json

@@ -1,7 +1,8 @@
 {
   "name": "draft-plugins",
   "owner": {
-    "name": "mayurpise",
+    "name": "Mayur Pise",
+    "email": "mayur@getdraft.dev",
     "url": "https://github.com/mayurpise"
   },
   "metadata": {
@@ -12,9 +13,11 @@
       "name": "draft",
       "source": "./",
       "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-      "version": "3.7.2",
+      "version": "5.0.1",
       "author": {
-        "name": "mayurpise"
+        "name": "Mayur Pise",
+        "email": "mayur@getdraft.dev",
+        "url": "https://github.com/mayurpise"
       },
       "homepage": "https://github.com/drafthq/draft",
       "license": "MIT",

package/.claude-plugin/plugin.json

@@ -1,9 +1,11 @@
 {
   "name": "draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.7.2",
+  "version": "5.0.1",
   "author": {
-    "name": "mayurpise"
+    "name": "Mayur Pise",
+    "email": "mayur@getdraft.dev",
+    "url": "https://github.com/mayurpise"
   },
   "homepage": "https://github.com/drafthq/draft",
   "license": "MIT",

package/.cursor-plugin/plugin.json

@@ -2,11 +2,13 @@
   "name": "draft",
   "displayName": "Draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.7.2",
+  "version": "5.0.1",
   "skills": "./skills/",
   "agents": "./core/agents/",
   "author": {
-    "name": "mayurpise"
+    "name": "Mayur Pise",
+    "email": "mayur@getdraft.dev",
+    "url": "https://github.com/mayurpise"
   },
   "homepage": "https://github.com/drafthq/draft",
   "license": "MIT",

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Mayur Pise
+Copyright (c) 2025-2026 Mayur Pise
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -68,12 +68,12 @@ Each host installs the way that host actually loads extensions — no manual ste
 
 | Host | `draft install …` | What it does |
 |------|-------------------|--------------|
-| **Claude Code** | `claude-code` | Registers the plugin via `claude plugin marketplace add` + `claude plugin install` (user scope). Restart Claude Code. |
-| **Cursor** | `cursor` | Copies the plugin into `~/.cursor/plugins/local/draft/`, writes `.cursor-plugin/plugin.json`, registers `draft@draft-plugins` in Cursor's plugin registry, and enables it. Restart Cursor (or Developer: Reload Window). Existing installs upgrade with `draft install cursor --force`. |
-| **Codex** | `codex` | Writes `./AGENTS.md`, which Codex reads automatically. |
-| **opencode** | `opencode` | Writes `./AGENTS.md` + `~/.agents/skills/draft/`, both auto-discovered. |
+| **Claude Code** | `claude-code` | Registers the plugin via `claude plugin marketplace add` + `claude plugin install` (default `--global` / user scope). Restart Claude Code. |
+| **Cursor** | `cursor` | Default `--global`. Copies the plugin into `~/.cursor/plugins/local/draft/`, writes `.cursor-plugin/plugin.json`, registers `draft@draft-plugins` in Cursor's plugin registry, and enables it. Restart Cursor (or Developer: Reload Window). Existing installs upgrade with `draft install cursor --force`. |
+| **Codex** | `codex` | Default `--project`. Writes `./AGENTS.md`, which Codex reads automatically. |
+| **opencode** | `opencode` | Default `--project`. Writes `./AGENTS.md` + `~/.agents/skills/draft/`, both auto-discovered. |
 
-Flags: `--global` / `--project` to pick scope, `--dry-run` to preview, `--force` to overwrite, `--no-graph` to skip the graph-engine fetch.
+Flags: `--global` / `--project` to pick scope (`--global` is the default for `claude-code` and `cursor`; `--project` is the default for `codex` and `opencode`), `--dry-run` to preview, `--force` to overwrite, `--no-graph` to skip the graph-engine fetch.
 
 Then, in Claude Code (after restarting):
 
@@ -164,7 +164,7 @@ The graph powers `/draft:graph` and `/draft:impact`, enriches `/draft:bughunt` a
 
 ### Deterministic helper tools
 
-Skills also call into **shell helpers** under `scripts/tools/` for mechanical work — git metadata, file classification, test-framework detection, hotspot ranking, freshness checks, ADR indexing, and live graph queries (`graph-callers.sh`, `graph-impact.sh`, `hotspot-rank.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh`). All emit JSON or markdown, follow a uniform exit-code contract, and degrade gracefully when their input source is unavailable.
+Skills also call into **shell helpers** under `scripts/tools/` for mechanical work — git metadata, file classification, test-framework detection, hotspot ranking, freshness checks, ADR indexing, and live graph queries (`graph-callers.sh`, `graph-impact.sh`, `hotspot-rank.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh`). All emit JSON or markdown and follow a uniform exit-code contract. Graph wrappers fail loud: shapeless `{}` (no `.rows` array) is `source:"unavailable"` with a non-zero exit, not a measured empty result.
 
 ---
 
@@ -270,7 +270,7 @@ Each layer narrows the solution space. By the time AI writes code, decisions are
 
 ---
 
-<p align="center">MIT License &middot; Graph engine: <a href="https://github.com/DeusData/codebase-memory-mcp" target="_blank" rel="noopener noreferrer">codebase-memory-mcp</a> by <a href="https://github.com/DeusData" target="_blank" rel="noopener noreferrer">DeusData</a></p>
+<p align="center">MIT License &middot; Created &amp; maintained by <a href="https://www.linkedin.com/in/mayurpise/" target="_blank" rel="noopener noreferrer">Mayur Pise</a> &middot; Graph engine: <a href="https://github.com/DeusData/codebase-memory-mcp" target="_blank" rel="noopener noreferrer">codebase-memory-mcp</a> by <a href="https://github.com/DeusData" target="_blank" rel="noopener noreferrer">DeusData</a></p>
 
 <p align="center">
   <strong>Credits:</strong> Inspired by <a href="https://github.com/gemini-cli-extensions/conductor">gemini-cli-extensions/conductor</a>

package/bin/README.md

@@ -17,7 +17,7 @@ This installs the binary to the **Draft-managed location**:
 ~/.cache/draft/bin/codebase-memory-mcp
 ```
 
-The fetch script picks the right release archive for the host OS/arch, verifies its SHA-256 against the published `checksums.txt`, extracts it, and installs it there. `draft install claude-code` / `draft install cursor` run this automatically (best-effort, network-gated); skip it with `--no-graph`.
+The fetch script picks the right release archive for the host OS/arch, verifies its SHA-256 (against hashes pinned in the script for the default version, else against the release's `checksums.txt`), extracts it, and installs it there. An existing install is kept only when its version matches the requested one, so a pin bump upgrades it. Downloads pin `curl --proto '=https' --proto-redir '=https'` so a compromised redirect cannot downgrade to HTTP. `draft install claude-code` / `draft install cursor` run this automatically (best-effort, network-gated); skip it with `--no-graph`.
 
 ## Resolution order
 
@@ -39,10 +39,10 @@ Set `DRAFT_MEMORY_DISABLE=1` to force the engine off. All graph-backed skills an
 ## How tools use it
 
 Shell helpers under `scripts/tools/` drive the engine via its CLI
-(`codebase-memory-mcp cli <tool> '<json>'`) and shape results into Draft's
+(`codebase-memory-mcp cli <tool>`, JSON args on stdin) and shape results into Draft's
 contracts — see `hotspot-rank.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh`,
 and `verify-graph-binary.sh`. The shared wrappers (`memory_cli`,
-`memory_ensure_index`, `memory_project_for_repo`) live in `_lib.sh`.
+`memory_ensure_index`, `memory_index_bounded`) live in `_lib.sh`.
 
 ## Snapshot artifacts
 
@@ -50,9 +50,9 @@ and `verify-graph-binary.sh`. The shared wrappers (`memory_cli`,
 
 | Artifact | Content |
 |----------|---------|
-| `schema.yaml` | Engine + project metadata, node/edge counts, point-of-index counts (gates graph use). |
+| `schema.yaml` | Engine metadata and point-of-index node/edge counts (gates graph use). No machine- or run-specific fields, so it only changes when the engine or the codebase does. |
 
-Structural graph data (architecture, hotspots, module deps, service routes) is queried **live** from the `codebase-memory-mcp` engine — either via the wrapper scripts under `scripts/tools/` (`graph-callers.sh`, `graph-impact.sh`, `hotspot-rank.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh`) or directly with `codebase-memory-mcp cli <tool> '<json>'`.
+Structural graph data (architecture, hotspots, module deps, service routes) is queried **live** from the `codebase-memory-mcp` engine — either via the wrapper scripts under `scripts/tools/` (`graph-callers.sh`, `graph-impact.sh`, `hotspot-rank.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh`), or, for any other read-only engine tool, `graph-query.sh --tool <name> --json '{...}'`.
 
 ## Offline / air-gapped distributions
 
@@ -68,22 +68,23 @@ Draft's differentiator depends on a binary published by a third party ([DeusData
 
 | Property | Status |
 |---|---|
-| Version pinned | Yes — `DEFAULT_VERSION` in `scripts/fetch-memory-engine.sh`. Bumps are deliberate commits, never floating. `CMM_VERSION` overrides per-install. |
-| SHA-256 verified | Yes when the release publishes `checksums.txt` and lists the archive. A **mismatch is always fatal.** |
-| Missing checksum | **Warns and installs by default.** Set `DRAFT_STRICT_VERIFY=1` to make an unverifiable download fatal instead. |
+| Version pinned | Yes — `DEFAULT_VERSION` in `scripts/fetch-memory-engine.sh`. Bumps are deliberate commits, never floating. `CMM_VERSION` overrides per-install. An install at another version is replaced on the next fetch, and `verify-graph-binary.sh` / `graph-preflight.sh` warn when the resolved engine (e.g. one on `$PATH`) is off-pin. |
+| SHA-256 verified | Yes. The default version's four platform archives are checked against hashes **pinned in the script** (a replaced release asset fails even if the release's own `checksums.txt` agrees). Other versions are checked against the release's `checksums.txt` when it lists the archive. A **mismatch is always fatal.** |
+| Missing checksum | Applies only to non-default versions: **warns and installs by default.** Set `DRAFT_STRICT_VERIFY=1` to make an unverifiable download fatal instead. |
 | Signature / attestation | **No.** There is no code signing or SLSA provenance today. Verification is checksum-only. |
 | Source available | Yes — the engine is open source at [DeusData/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp). |
 | Reproducible build | Not verified by Draft. We check the archive matches the publisher's checksum, not that the checksum matches the source. |
 
-Be explicit about the residual risk: a checksum proves the download matches what the publisher released. It does not prove the publisher released what the source says.
+Be explicit about the residual risk: a pinned checksum proves the download matches what the publisher released when Draft pinned it. It does not prove the publisher released what the source says.
 
 ### What the engine does at runtime
 
 - Reads the repository you point it at and writes a SQLite graph under its own cache.
-- Runs entirely locally. No API key, no telemetry endpoint, no outbound calls during indexing or querying.
-- Network is used exactly once, by `fetch-memory-engine.sh`, to download the release archive.
+- Runs entirely locally as Draft invokes it (`cli` mode). No API key, no telemetry endpoint, no outbound calls during indexing or querying — verified under `strace` for `index_repository` and queries on 0.9.0 (zero `connect()` calls, no spawned `curl`).
+- The binary does embed an update checker (`api.github.com/.../releases/latest`) and `update` / `install` subcommands for its own MCP-server workflow. Draft never runs the server or those subcommands.
+- Draft uses the network exactly once, in `fetch-memory-engine.sh`, to download the release archive.
 
-Draft invokes it only through `codebase-memory-mcp cli <tool> '<json>'` (see `_lib.sh:memory_cli`). It is never given credentials and never writes into your source tree.
+Draft invokes it only through `codebase-memory-mcp cli <tool>` with JSON args on stdin (see `_lib.sh:memory_cli`). It is never given credentials and never writes into your source tree.
 
 ### If you cannot run an unvetted binary
 
@@ -97,7 +98,7 @@ Three supported postures, in increasing strictness:
 
 The dependency is bounded by design, which is what makes this survivable:
 
-- **The interface is small.** Draft consumes a documented CLI (`cli <tool> '<json>'`), not a library. The entire coupling lives in `scripts/tools/_lib.sh` (`memory_cli`, `memory_ensure_index`, `memory_project_for_repo`) and `_graph_queries.sh`. Swapping engines means reimplementing those, not rewriting skills.
+- **The interface is small.** Draft consumes a documented CLI (`cli <tool>`, JSON on stdin), not a library. The entire coupling lives in `scripts/tools/_lib.sh` (`memory_cli`, `memory_ensure_index`, `memory_index_bounded`) and `_graph_queries.sh`. Swapping engines means reimplementing those, not rewriting skills.
 - **Skills never call the engine directly.** They call `graph-*.sh` wrappers, all of which already fail loud with `source: "unavailable"`. An engine that disappears degrades the product; it does not break it.
 - **Pinning buys time.** A stalled upstream keeps working at the pinned version; only new language support would be lost.
 - **The graph contract is replaceable.** The queries are ordinary Cypher-shaped structural lookups (callers, callees, fan-in, cycles, routes) over a tree-sitter/LSP index — reproducible on another indexer.

package/cli/src/cli.js

@@ -47,8 +47,8 @@ Usage:
 Hosts: ${hosts.map((h) => h.id).join(', ')}
 
 Flags:
-  --global        Install to the user-level location (default for cursor)
-  --project       Install into the current project (default for claude-code, codex, opencode)
+  --global        Install to the user-level location (default for claude-code, cursor)
+  --project       Install into the current project (default for codex, opencode)
   --dry-run       Print planned writes without touching disk
   --no-graph      Skip the knowledge-graph engine fetch
   --force         Overwrite an existing target

package/cli/src/installer.js

@@ -15,9 +15,11 @@ const CHECK_TIMEOUT_MS = 10000;
 const USE_SHELL = process.platform === 'win32';
 
 function hasBinary(name) {
-  // ENOENT on the error means the binary is not on PATH.
+  // Windows `.cmd` shims (shell: true) report a missing binary as status 127
+  // with no `error`. Treat any spawn error or non-zero status as absent.
   const r = spawnSync(name, ['--version'], { stdio: 'ignore', timeout: CHECK_TIMEOUT_MS, shell: USE_SHELL });
-  return !(r.error && r.error.code === 'ENOENT');
+  if (r.error) return false;
+  return r.status === 0;
 }
 
 // Per-step ceiling so a stalled network op (e.g. the `git clone` behind

package/cli/src/lib/cursor-registry.js

@@ -78,7 +78,7 @@ function registerCursorPlugin(opts) {
   // --- installed_plugins.json: merge our key, preserve installedAt on upgrade. ---
   const ip = readJson(paths.ipPath, { version: 2, plugins: {} });
   if (typeof ip.version !== 'number') ip.version = 2;
-  if (!ip.plugins || typeof ip.plugins !== 'object') ip.plugins = {};
+  if (!ip.plugins || typeof ip.plugins !== 'object' || Array.isArray(ip.plugins)) ip.plugins = {};
   const existing = Array.isArray(ip.plugins[PLUGIN_KEY]) ? ip.plugins[PLUGIN_KEY][0] : null;
   const installedAt = existing && existing.installedAt ? existing.installedAt : now;
   ip.plugins[PLUGIN_KEY] = [
@@ -93,7 +93,7 @@ function registerCursorPlugin(opts) {
 
   // --- settings.json: flip our enabledPlugins flag, preserve everything else. ---
   const settings = readJson(paths.settingsPath, {});
-  if (!settings.enabledPlugins || typeof settings.enabledPlugins !== 'object') {
+  if (!settings.enabledPlugins || typeof settings.enabledPlugins !== 'object' || Array.isArray(settings.enabledPlugins)) {
     settings.enabledPlugins = {};
   }
   settings.enabledPlugins[PLUGIN_KEY] = true;

package/cli/src/lib/graph.js

@@ -14,7 +14,8 @@ function fetchGraph() {
     return;
   }
   log.note('Fetching knowledge-graph engine (best-effort)...');
-  const result = spawnSync('bash', [script], { stdio: 'inherit' });
+  const timeout = Number(process.env.DRAFT_INSTALL_TIMEOUT_MS) || 300000;
+  const result = spawnSync('bash', [script], { stdio: 'inherit', timeout });
   if (result.status !== 0) {
     log.warn('Graph engine fetch skipped (offline or unsupported platform) — features degrade gracefully.');
   }

package/core/shared/condensation.md

@@ -24,7 +24,7 @@ Any skill that mutates `architecture.md` should execute this subroutine afterwar
 | Input | Path | Description |
 |-------|------|-------------|
 | architecture.md | `draft/architecture.md` | Comprehensive human-readable engineering reference (source of truth) |
-| schema.yaml | `draft/graph/schema.yaml` | Graph metrics for tier computation (optional — skip if absent) |
+| Architecture view | `scripts/tools/graph-arch.sh --repo .` | Live graph metrics for tier computation (optional — skip when `draft/graph/schema.yaml` is absent) |
 
 ## Outputs
 
@@ -37,11 +37,12 @@ Any skill that mutates `architecture.md` should execute this subroutine afterwar
 
 ## Target Size
 
-Compute tier from `draft/graph/schema.yaml` after graph build:
+Compute tier from the live architecture view (the same metrics as `/draft:init` Step 1.4.5 — `schema.yaml` carries only counts, not these):
 
-  M = stats.modules
-  F = stats.go_functions + stats.py_functions
-  P = stats.proto_rpcs
+  ARCH=$("$DRAFT_TOOLS/graph-arch.sh" --repo .)                       (DRAFT_TOOLS: resolver below)
+  M = $ARCH | jq '.packages | length'                                                              (modules)
+  F = $ARCH | jq '[.node_labels[] | select(.label=="Function" or .label=="Method") | .count] | add // 0'  (functions + methods)
+  P = $ARCH | jq '.routes | length'                                                                (routes / RPCs)
 
 | Tier | Label | Condition | Budget |
 |------|--------|----------------------------------------|---------------|
@@ -51,7 +52,7 @@ Compute tier from `draft/graph/schema.yaml` after graph build:
 | 4 | large | M≤100 AND F≤5000 AND P≤500 | 400–600 lines |
 | 5 | XL | M>100 OR F>5000 OR P>500 | 600–900 lines |
 
-If `schema.yaml` does not exist: default to tier 2 (180–280 lines).
+If `schema.yaml` does not exist (no graph) or `graph-arch.sh` reports `source: unavailable`: default to tier 2 (180–280 lines).
 
 - Below tier minimum: incomplete condensation — ensure all sections are represented
 - Above tier maximum: insufficient compression — apply prioritization rules below
@@ -171,7 +172,7 @@ Before writing `draft/.ai-context.md`, verify:
 - [ ] No references to `architecture.md` (file must be self-contained)
 - [ ] All invariants from architecture.md are preserved
 - [ ] Extension cookbooks are complete (an agent can follow them without other files)
-- [ ] Output is within tier budget bounds (compute from schema.yaml or default tier 2)
+- [ ] Output is within tier budget bounds (compute from `graph-arch.sh` or default tier 2)
 - [ ] GRAPH:HOTSPOTS present (or note "No hotspot data available" if graph absent)
 - [ ] GRAPH:CYCLES present ("None ✓" or cycle list; or note if graph absent)
 - [ ] GRAPH:MODULE-HOTSPOTS present for tier ≥ 3 (or note if no hotspot data)

package/core/shared/draft-context-loading.md

@@ -71,7 +71,7 @@ If `draft/graph/schema.yaml` exists, the project has automated graph analysis da
 
 | File | Purpose | Content |
 |------|---------|---------|
-| `draft/graph/schema.yaml` | Gate marker (engine + project metadata + point-of-index counts); presence gates graph use | YAML, ~15 lines |
+| `draft/graph/schema.yaml` | Gate marker (engine metadata + point-of-index counts); presence gates graph use | YAML, ~10 lines |
 
 Note: `.ai-context.md` embeds a condensed graph summary (`GRAPH:MODULES`, `GRAPH:HOTSPOTS`, `GRAPH:CYCLES`) for first-pass structural ground truth. Deep structural data is queried live from the engine (see Live structural queries below).
 

package/core/shared/graph-query.md

@@ -103,7 +103,7 @@ DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}
 |---|---|---|
 | `bash "$DRAFT_TOOLS/hotspot-rank.sh" [--top N]` | complexity-weighted hotspots | Emits `{hotspots:[],source:"unavailable"}` and exits 2 |
 | `bash "$DRAFT_TOOLS/cycle-detect.sh"` | call cycles | Emits `{cycles:[],source:"unavailable"}` and exits 2 |
-| `bash "$DRAFT_TOOLS/mermaid-from-graph.sh" [--diagram module-deps\|co-change\|proto-map]` | diagram text | Emits an empty mermaid block and exits 2 |
+| `bash "$DRAFT_TOOLS/mermaid-from-graph.sh" [--diagram module-deps\|co-change\|proto-map]` | diagram text | Unavailable stub (`graph not built`) vs empty-graph stub (`no edges`); both exit 2 |
 | `bash "$DRAFT_TOOLS/graph-callers.sh" --symbol N [--transitive[=N]] [--prod-only] [--qualified]` | callers | `{callers:[],status:"unavailable",source:"unavailable"}`, exit 2 |
 | `bash "$DRAFT_TOOLS/graph-snippet.sh" --qualified N` | verified source + caller/callee counts | `{status:"unavailable",source:"unavailable"}`, exit 2 |
 | `bash "$DRAFT_TOOLS/graph-search.sh" --query "STR" [--limit N]` | semantic/ranked search | `{results:[],source:"unavailable"}`, exit 2 |
@@ -115,7 +115,7 @@ DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}
 | `bash "$DRAFT_TOOLS/graph-query.sh" (--cypher STR \| --tool NAME --json '{...}')` | generic read-only passthrough | `{source:"unavailable"}`, exit 2 |
 | `bash "$DRAFT_TOOLS/graph-traces.sh" ingest --file F --experimental` | runtime traces (experimental write) | `{source:"unavailable"}`, exit 2 |
 
-For lower-level modes, call the engine directly: `codebase-memory-mcp cli <tool> '<json>'` (see the tool list in [bin/README.md](../../bin/README.md)).
+For an engine tool without a dedicated wrapper, use the read-only passthrough `graph-query.sh --repo . --tool <name> --json '{...}'` (project injected, write tools refused, `source:"unavailable"` on failure). Never call the engine binary directly — that skips engine resolution, the index refresh before each query, and the fail-loud contract.
 
 ### Capability wrappers & dialect limits (graph-tooling-v2)
 
@@ -123,8 +123,9 @@ All Cypher lives in `scripts/tools/_graph_queries.sh` (the single source of quer
 truth). Wrappers are thin arg-parse → builder → fail-loud JSON. Three contracts
 matter when consuming them:
 
-**Fail-loud status.** Symbol-scoped wrappers (`graph-callers`, `graph-snippet`,
-`graph-tests --symbol`, `graph-hierarchy --symbol/--derived`, `graph-errors`)
+**Fail-loud status.** Symbol-scoped wrappers (`graph-callers`, `graph-impact`,
+`graph-snippet`, `graph-tests --symbol`, `graph-hierarchy --symbol/--derived`,
+`graph-errors`)
 emit a `status` field that distinguishes the three real outcomes — never read a
 bare `[]` as a confirmed true negative:
 
@@ -133,9 +134,11 @@ bare `[]` as a confirmed true negative:
 | `ok` | node found, edges returned |
 | `no-edges` | node exists but has no matching edge (a *real* negative) |
 | `no-match` | the named symbol was not found at all (check the name / try `--qualified`) |
-| `unavailable` | engine could not be resolved (exit 2) |
+| `unavailable` | engine could not be resolved, or engine returned shapeless/non-row JSON (exit 2) |
 
-**Verified engine param shapes** (engine v0.8.x — the runtime source of truth is
+**Shapeless JSON is unavailable.** `gq_run` requires `has("rows") and (.rows|type=="array")`. A bare `{}` (or any object without a `.rows` array) is not a measured empty result — wrappers emit `source:"unavailable"` and a non-zero exit. Do not read `{}` as "no callers / no cycles / no edges". `graph-impact`, `graph-callers`, and `mermaid-from-graph` also require their tool-shaped object; a failed snapshot refresh does not rewrite `schema.yaml`.
+
+**Verified engine param shapes** (engine v0.9.0 — the runtime source of truth is
 `get_graph_schema`; do not hardcode a property set):
 
 ```bash
@@ -148,13 +151,18 @@ get_graph_schema '{"project":P}'    # → {node_labels:[{label,count,properties}
 
 **Cypher dialect — keep queries inside the SAFE set:**
 
-- ✅ SAFE: fixed-length patterns, single/multi-hop explicit patterns, `=`, `<`,
-  `STARTS WITH`, `NOT x STARTS WITH`, `AND`, `OR`, relationship-type alternation
-  `[:A|B]`, simple `count(x)`.
-- ❌ UNSAFE (rejected or silently empty): `coalesce()`, `<>` / `!=` / `<=` / `>=`,
-  `NOT EXISTS(...)`, `NOT (pattern)`, `WITH`-grouping aggregation, multi-pattern
-  joins. `graph-query.sh --cypher` returns the engine's raw error, not a silent
+- ✅ SAFE: `=`, `<>`/`!=`, `<`, `>`, `<=`, `>=` against a literal; `STARTS WITH`,
+  `NOT x STARTS WITH`, `AND`, `OR`; explicit and variable-length patterns
+  (`[:R*1..3]`, fixed depth `[:R*2..2]`); relationship-type alternation `[:A|B]`;
+  `coalesce()`; `DISTINCT`; `count(x)`, `count(DISTINCT x)`; `WITH`-grouping
+  aggregation.
+- ❌ UNSAFE: comparing one property against another (`a.x < b.x`), `NOT EXISTS(...)`,
+  `NOT (pattern)`, path variables (`p=(...)`, `length(p)`) — all rejected; and
+  multi-pattern joins (`MATCH (a)…, (b)…`), which parse but ignore `RETURN` and
+  `LIMIT`. `graph-query.sh --cypher` returns the engine's raw error, not a silent
   empty — but the builders never emit these forms.
+- ⚠️ `LIMIT` applies before `DISTINCT`: `RETURN DISTINCT … LIMIT n` can return
+  fewer than n rows while more exist. Judge truncation on raw rows.
 
 **Caveats consumers must respect:**
 
@@ -189,22 +197,22 @@ The only committed file is the gate marker:
 
 | File | Role |
 |------|------|
-| `draft/graph/schema.yaml` | Engine + project metadata and point-of-index counts (provenance, not authoritative). Carries **no graph data**. Its presence is the **gate** (see Pre-Check) — it signals the engine is wired for this repo. Written by `scripts/tools/graph-snapshot.sh`. |
+| `draft/graph/schema.yaml` | Engine metadata and point-of-index counts (provenance, not authoritative). Carries **no graph data**. Its presence is the **gate** (see Pre-Check) — it signals the engine is wired for this repo. Written by `scripts/tools/graph-snapshot.sh`. |
 
-All structural data is obtained live by shelling out to the engine — either through the query-tool wrappers under `scripts/tools/` or directly via `codebase-memory-mcp cli <tool> '<json>'`. The shell tools auto-index the repo into the engine's own cache on demand, so no committed files are required.
+All structural data is obtained live through the query-tool wrappers under `scripts/tools/`; `graph-query.sh --tool` covers every read-only engine tool that has no dedicated wrapper. The wrappers refresh the repo's index in the engine's own cache before each query, so no committed files are required.
 
 ### How skills query (engine is the interface; jq is optional)
 
-- **The engine is the query.** `codebase-memory-mcp cli <tool> '<json>'` (and the wrappers that call it) is how you ask — it takes JSON args and returns JSON. There is no other query surface.
+- **The engine is the query; the wrappers are the interface.** Every wrapper drives the engine's CLI and returns JSON. There is no other query surface.
 - **Prefer the wrappers — they resolve the engine for you.** `graph-arch.sh` (architecture view: packages/routes/layers/hotspots), `graph-callers.sh`, `hotspot-rank.sh`, `graph-impact.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh` return already-shaped JSON. The engine binary is usually **not on `$PATH`** (it lives under `~/.cache/draft/bin/`); the wrappers locate it via `_lib.sh:find_memory_bin`, so a skill using a wrapper needs no resolution step.
-- **Raw `codebase-memory-mcp cli` requires resolving the binary first** (it is not on `$PATH`): `CM="${DRAFT_MEMORY_BIN:-$HOME/.cache/draft/bin/codebase-memory-mcp}"; "$CM" cli <tool> '<json>'`. Reach for this only for tools without a wrapper (`search_graph`, `search_code`, `trace_path`).
+- **Tools without a dedicated wrapper go through `graph-query.sh`:** `"$DRAFT_TOOLS/graph-query.sh" --repo . --tool search_code --json '{"pattern":"..."}'` (likewise `trace_path`, `get_graph_schema`, `index_status`). `search_graph` has its own wrapper, `graph-search.sh`.
 - **`jq` is not a query tool — it only trims output.** Reach for it solely to slice a *large* response (chiefly the `get_architecture` blob) down to the field you need, for token economy. The agent can read raw JSON directly; jq is an optimization, not a requirement. Don't pipe wrapper output through jq unless you genuinely need a sub-field.
 
 The engine uses a **unified, language-agnostic** node model — `Function`, `Method`, `Class`, `Module`, `File`, `Folder`, `Route`, `Section`, `Variable` (language is inferred from file extension) — and edges `CALLS`, `DEFINES`, `CONTAINS_FILE`, `IMPORTS`, `HTTP_CALLS`, `FILE_CHANGES_WITH`, `SEMANTICALLY_RELATED`, `SIMILAR_TO`. Each node carries `file_path` + `start_line`/`end_line` and rich `properties` (complexity, signature, parent_class), and the engine exposes full-text (`search_code`) and semantic search — none of which a committed snapshot reproduced.
 
 ## Query Tools
 
-Live queries go through the shell tools under `scripts/tools/`, which drive the engine and shape results into stable JSON. Each tool resolves the engine (see Finding the Engine), indexes the repo on demand, and emits `source: "memory-graph"` on success or `source: "unavailable"` (non-zero exit) when the engine cannot be resolved. Set `DRAFT_MEMORY_DISABLE=1` to force the engine off; all tools then degrade gracefully.
+Live queries go through the shell tools under `scripts/tools/`, which drive the engine and shape results into stable JSON. Each tool resolves the engine (see Finding the Engine), indexes the repo on demand, and emits `source: "memory-graph"` on success or `source: "unavailable"` (non-zero exit) when the engine cannot be resolved **or returns shapeless JSON** (missing `.rows` array). Set `DRAFT_MEMORY_DISABLE=1` to force the engine off; all tools then degrade to `unavailable` rather than inventing empty results.
 
 ### Callers — who calls this function?
 
@@ -217,11 +225,11 @@ Output: `{symbol, callers[{name, file}], source}`. Use when enumerating call sit
 ### Impact — blast radius of a file or symbol
 
 ```bash
-"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>      # changed-file impact (working-tree diff)
-"$DRAFT_TOOLS/graph-impact.sh" --repo . --symbol <name>    # transitive callers of a function
+"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>      # dependents of a file: its symbols' callers + its importers
+"$DRAFT_TOOLS/graph-impact.sh" --repo . --symbol <name>    # dependents (transitive callers) of a function
 ```
 
-Output: `{target, kind, impacted[{name, file, hop}], source}`. Use when sizing risk before modifying a file or symbol, especially high-fan-in hotspots.
+Output: `{target, kind, impacted[{name, file, qualified, hop}], downstream_files, affected_modules, max_depth, by_category{code,test}, status, truncated, source}`. `impacted` lists each dependent once at its nearest hop (default depth 3), capped at 200 with `truncated:true`; the aggregates always cover the full set. `status` is `ok`, `no-edges` (target known, nothing depends on it), or `no-match` (target unknown to the graph — check the path). Use when sizing risk before modifying a file or symbol, especially high-fan-in hotspots.
 
 ### Hotspots — fan-in ranking
 
@@ -332,7 +340,7 @@ Unlocks any edge type or node property without a purpose-built wrapper. Write ve
 "$DRAFT_TOOLS/graph-snapshot.sh" --repo .
 ```
 
-Indexes the repo into the engine and writes the `draft/graph/schema.yaml` gate marker (now including the `detect_changes` delta: `changed_files`/`impacted_symbols`). It writes **no** graph data. Run during `/draft:init` and `/draft:graph`, or whenever the index should be refreshed.
+Indexes the repo into the engine and writes the `draft/graph/schema.yaml` gate marker, and prints the `detect_changes` delta (`changed_files`/`impacted_symbols`) without committing it. It writes **no** graph data. Run during `/draft:init` and `/draft:graph`, or whenever the index should be refreshed.
 
 ## Finding the Engine (Resolution + Usage Report)
 
@@ -371,6 +379,6 @@ The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159
 | Scenario | Behavior |
 |----------|----------|
 | No engine resolvable (or `DRAFT_MEMORY_DISABLE=1`) | Skip graph indexing in init; all skills proceed without graph data; tools emit `source: unavailable` |
-| Engine present but a query fails | Warn and proceed; skills work without graph data |
+| Engine present but a query fails, or returns shapeless `{}` | Treat as unavailable — never as a true-negative empty result; skills proceed without graph data |
 | `draft/graph/schema.yaml` exists | Engine is wired — use live query tools as needed during the run |
-| Engine index out of date | The engine indexes incrementally (content-based, git-aware) on each query, so it self-freshens. Re-run `graph-snapshot.sh` (or init) to force a reindex and refresh the marker. |
+| Engine index out of date | Every wrapper re-indexes incrementally (content-based, git-aware) before it queries — ~0.1 s on an unchanged repo — so live answers track the working tree, including the run's own edits. `graph-snapshot.sh` (or init) also refreshes the `schema.yaml` marker. |

package/core/templates/architecture.md

@@ -29,7 +29,7 @@ graph:
     cpp: "{high}"
     go: "{approximate | high}"
   stats:
-    modules: "{N from schema.yaml}"
+    modules: "{N from engine: get_architecture .packages}"
     edges: "{total_edges from engine: get_architecture .edges}"
     hotspots: "{N}"
   notes: "{explicit fidelity summary from engine: get_architecture .languages/.packages}"