@drafthq/draft 4.0.0 → 5.0.1

package/.claude-plugin/marketplace.json

@@ -13,7 +13,7 @@
       "name": "draft",
       "source": "./",
       "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-      "version": "4.0.0",
+      "version": "5.0.1",
       "author": {
         "name": "Mayur Pise",
         "email": "mayur@getdraft.dev",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "4.0.0",
+  "version": "5.0.1",
   "author": {
     "name": "Mayur Pise",
     "email": "mayur@getdraft.dev",

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "draft",
   "displayName": "Draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "4.0.0",
+  "version": "5.0.1",
   "skills": "./skills/",
   "agents": "./core/agents/",
   "author": {

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. 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`.
+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/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

@@ -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:
 
@@ -137,7 +138,7 @@ bare `[]` as a confirmed true negative:
 
 **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.8.x — the runtime source of truth is
+**Verified engine param shapes** (engine v0.9.0 — the runtime source of truth is
 `get_graph_schema`; do not hardcode a property set):
 
 ```bash
@@ -150,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:**
 
@@ -191,15 +197,15 @@ 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.
@@ -219,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
 
@@ -334,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)
 
@@ -375,4 +381,4 @@ The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159
 | 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, 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}"

package/integrations/agents/AGENTS.md

@@ -6025,7 +6025,7 @@ After a phase passes review, refresh `metadata.json.impact` so future tracks can
    "$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>
    ```
 
-   Aggregate across all files: `downstream_files` = total unique downstream files (deduped), `downstream_modules` = union of `affected_modules`, `max_depth` = max across queries, `by_category` = sum of each query's `by_category`. If the graph is absent, leave these fields as zeros / empty arrays — the snapshot still records the directly-touched files.
+   Aggregate across all files: `downstream_files` = count of the union of each query's `downstream_files` array, `downstream_modules` = union of `affected_modules`, `max_depth` = max across queries, `by_category` = sum of each query's `by_category`. If the graph is absent, leave these fields as zeros / empty arrays — the snapshot still records the directly-touched files.
 
 3. **Write metadata.json** with the populated `impact` block and `computed_at` set to the current timestamp.
 
@@ -17030,7 +17030,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).
 
@@ -17558,7 +17558,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
 
@@ -17571,11 +17571,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 |
 |------|--------|----------------------------------------|---------------|
@@ -17585,7 +17586,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
@@ -17705,7 +17706,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)
@@ -18216,7 +18217,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)
 
@@ -18224,8 +18225,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:
 
@@ -18238,7 +18240,7 @@ bare `[]` as a confirmed true negative:
 
 **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.8.x — the runtime source of truth is
+**Verified engine param shapes** (engine v0.9.0 — the runtime source of truth is
 `get_graph_schema`; do not hardcode a property set):
 
 ```bash
@@ -18251,13 +18253,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:**
 
@@ -18292,15 +18299,15 @@ 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.
@@ -18320,11 +18327,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
 
@@ -18435,7 +18442,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)
 
@@ -18476,7 +18483,7 @@ The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159
 | 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, 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. |
 
 </core-file>
 
@@ -20433,7 +20440,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}"