@drafthq/draft 3.7.2 → 5.0.1

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.
 
@@ -9604,7 +9604,7 @@ Prefer `draft docs` going forward for all authoring requests. The legacy direct
 
 ## Discover Router
 
-When user says "discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, index, etc.):
+When user says "discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, tour, impact, etc.):
 
 `draft discover` is the single front door for all investigation, auditing, pattern learning, and quality exploration activities.
 
@@ -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)
@@ -18204,7 +18205,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 |
@@ -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:
 
@@ -18234,9 +18236,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
@@ -18249,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:**
 
@@ -18290,22 +18299,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?
 
@@ -18318,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
 
@@ -18433,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)
 
@@ -18472,9 +18481,9 @@ 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. |
 
 </core-file>
 
@@ -20431,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}"

package/integrations/copilot/.github/copilot-instructions.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.
 
@@ -9604,7 +9604,7 @@ Prefer `draft docs` going forward for all authoring requests. The legacy direct
 
 ## Discover Router
 
-When user says "discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, index, etc.):
+When user says "discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, tour, impact, etc.):
 
 `draft discover` is the single front door for all investigation, auditing, pattern learning, and quality exploration activities.
 
@@ -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)
@@ -18204,7 +18205,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 |
@@ -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:
 
@@ -18234,9 +18236,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
@@ -18249,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:**
 
@@ -18290,22 +18299,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?
 
@@ -18318,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
 
@@ -18433,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)
 
@@ -18472,9 +18481,9 @@ 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. |
 
 </core-file>
 
@@ -20431,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}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "3.7.2",
+  "version": "5.0.1",
   "description": "Context-Driven Development for AI coding agents — install Draft into Claude Code, Cursor, Codex, or opencode.",
   "bin": {
     "draft": "cli/bin/draft.js"
@@ -25,7 +25,7 @@
   ],
   "scripts": {
     "test": "bash tests/test-cli.sh",
-    "version": "bash scripts/sync-version.sh && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json .cursor-plugin/plugin.json",
+    "version": "bash scripts/sync-version.sh --stage",
     "prepublishOnly": "bash scripts/build-integrations.sh"
   },
   "repository": {
@@ -37,7 +37,11 @@
     "url": "https://github.com/drafthq/draft/issues"
   },
   "license": "MIT",
-  "author": "mayurpise",
+  "author": {
+    "name": "Mayur Pise",
+    "email": "mayur@getdraft.dev",
+    "url": "https://github.com/mayurpise"
+  },
   "publishConfig": {
     "access": "public"
   },

package/scripts/fetch-memory-engine.sh

@@ -3,8 +3,9 @@
 #
 # The engine is the codebase-memory-mcp single static binary. This script fetches
 # the release archive for the host OS/arch from GitHub Releases, verifies its
-# SHA-256 against the published checksums.txt, extracts it, and installs the
-# binary to the Draft-managed location (~/.cache/draft/bin/codebase-memory-mcp),
+# SHA-256 (against hashes pinned below for the default version, else against the
+# release's checksums.txt), extracts it, and installs the binary to the
+# Draft-managed location (~/.cache/draft/bin/codebase-memory-mcp),
 # which scripts/tools/_lib.sh:find_memory_bin resolves.
 #
 # Pinned by default for reproducibility; override with CMM_VERSION (a tag, e.g.
@@ -44,9 +45,15 @@ while [[ $# -gt 0 ]]; do
 done
 
 BIN_PATH="$DEST/codebase-memory-mcp"
+# Keep an existing install only at the requested version, so a pin bump upgrades
+# it. "latest" cannot be compared offline; any existing binary satisfies it.
 if [[ -x "$BIN_PATH" && $FORCE -eq 0 ]]; then
-  echo "codebase-memory-mcp already installed at $BIN_PATH ($("$BIN_PATH" --version 2>/dev/null || echo unknown))"
-  exit 0
+  have="$("$BIN_PATH" --version 2>/dev/null | awk '{print $NF}' || true)"
+  if [[ "$VERSION" == "latest" || "$have" == "${VERSION#v}" ]]; then
+    echo "codebase-memory-mcp already installed at $BIN_PATH (${have:-unknown})"
+    exit 0
+  fi
+  echo "Installed engine is ${have:-unknown}; replacing it with ${VERSION}."
 fi
 
 # --- Detect OS / arch (mirrors the engine's own install.sh naming) ---
@@ -80,7 +87,7 @@ TMP="$(mktemp -d)"
 trap 'rm -rf "$TMP"' EXIT
 
 echo "Fetching ${ARCHIVE} (${VERSION})..."
-if ! curl -fSL --max-time 300 -o "$TMP/$ARCHIVE" "$BASE/$ARCHIVE"; then
+if ! curl -fSL --proto '=https' --proto-redir '=https' --max-time 300 -o "$TMP/$ARCHIVE" "$BASE/$ARCHIVE"; then
   echo "error: download failed: $BASE/$ARCHIVE" >&2
   exit 2
 fi
@@ -89,6 +96,28 @@ fi
 # A mismatch is always fatal. An *absent* checksum is fatal only under
 # DRAFT_STRICT_VERIFY=1 — otherwise it warns, so that a release without a
 # checksums.txt does not brick the install for everyone.
+#
+# checksums.txt ships in the same release as the archive, so it proves only that
+# the download is intact: a replaced release asset passes it. The pinned
+# version's archives are checked against SHA-256 values recorded here instead
+# (copied from its checksums.txt when the pin was bumped) — update them with
+# DEFAULT_VERSION.
+pinned_sha256() {
+  [[ "$VERSION" == "$DEFAULT_VERSION" ]] || return 0
+  case "$1" in
+    codebase-memory-mcp-darwin-amd64.tar.gz) echo 6af3d02a27f589901fa763d3971089337bc8c9838bbed5d0cf543ca9f1a9e543 ;;
+    codebase-memory-mcp-darwin-arm64.tar.gz) echo faa02f0404230c451a9812230394481948f80183801fa5bf67044b41c2f25ed4 ;;
+    codebase-memory-mcp-linux-amd64-portable.tar.gz) echo 8459d5c9d1457f2c82de3de307ffc7641ecbba2dde893427be1e62eca8ef9b25 ;;
+    codebase-memory-mcp-linux-arm64-portable.tar.gz) echo b0a43fdaf534073c16707d72726b73b149d4c1212034b281ee8b7b2dac755107 ;;
+  esac
+}
+sha256_of() {
+  if command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+  else
+    shasum -a 256 "$1" | awk '{print $1}'
+  fi
+}
 STRICT="${DRAFT_STRICT_VERIFY:-0}"
 unverified() {
   if [[ "$STRICT" == "1" ]]; then
@@ -98,14 +127,18 @@ unverified() {
   echo "  warning: $1 — skipping verification (set DRAFT_STRICT_VERIFY=1 to make this fatal)" >&2
 }
 
-if curl -fsSL --max-time 60 -o "$TMP/checksums.txt" "$BASE/checksums.txt" 2>/dev/null; then
+pinned="$(pinned_sha256 "$ARCHIVE")"
+if [[ -n "$pinned" ]]; then
+  actual="$(sha256_of "$TMP/$ARCHIVE")"
+  if [[ "$pinned" != "$actual" ]]; then
+    echo "error: $ARCHIVE does not match the SHA-256 pinned for $VERSION (expected $pinned, got $actual)" >&2
+    exit 2
+  fi
+  echo "  checksum OK (pinned $pinned)"
+elif curl -fsSL --proto '=https' --proto-redir '=https' --max-time 60 -o "$TMP/checksums.txt" "$BASE/checksums.txt" 2>/dev/null; then
   expected="$(grep "  $ARCHIVE\$" "$TMP/checksums.txt" 2>/dev/null | awk '{print $1}' | head -1 || true)"
   if [[ -n "$expected" ]]; then
-    if command -v sha256sum >/dev/null 2>&1; then
-      actual="$(sha256sum "$TMP/$ARCHIVE" | awk '{print $1}')"
-    else
-      actual="$(shasum -a 256 "$TMP/$ARCHIVE" | awk '{print $1}')"
-    fi
+    actual="$(sha256_of "$TMP/$ARCHIVE")"
     if [[ "$expected" != "$actual" ]]; then
       echo "error: checksum mismatch for $ARCHIVE (expected $expected, got $actual)" >&2
       exit 2

package/scripts/lib.sh

@@ -84,7 +84,7 @@ SKILL_META=(
     'plan|Plan Router|"plan feature" or "draft plan <intent>" (new-track, decompose, adr, tech-debt, change)'
     'ops|Ops Router|"ops deploy" or "draft ops <intent>" (deploy-checklist, incident, standup, status, revert)'
     'docs|Docs Router|"write docs" or "draft docs <intent>" (documentation)'
-    'discover|Discover Router|"discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, index, etc.)'
+    'discover|Discover Router|"discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, tour, impact, etc.)'
     'jira|Jira Router|"jira preview", "jira create", or "jira review <ID>"'
     'integrations|Integrations Router|"integrations", "integrations jira-preview", or "integrations jira-create"'
     'quick-review|Quick Review Command|"quick review" or "draft quick-review [file|pr <number>]"'