@drafthq/draft 4.0.0 → 5.0.1

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.
 
@@ -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}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "4.0.0",
+  "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": {

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) ---
@@ -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 --proto '=https' --proto-redir '=https' --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/tools/_graph_queries.sh

@@ -7,16 +7,20 @@
 # here, not a hunt across N scripts (the Phase 0 :Function bug was duplicated
 # across two files precisely because the Cypher was inlined).
 #
-# Dialect notes (engine v0.8.x, verified live against this engine):
-#   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 : coalesce(), `<>` / `!=` / `<=` / `>=`, `NOT EXISTS(...)`,
-#            `NOT (pattern)`, `WITH`-grouping aggregation, multi-pattern joins,
-#            and comparing one property against another (`a.x < b.x` — the
-#            parser wants a literal on the right and fails with "expected value
-#            at pos N"). `<` against a literal is fine.
-#            Every builder below stays inside the SAFE set.
+# Dialect notes (engine v0.9.0, verified live against this engine):
+#   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`, `a.x = b.x` —
+#            the parser wants a literal on the right: "expected value at pos N"),
+#            `NOT EXISTS(...)`, `NOT (pattern)`, path variables (`p=(...)`,
+#            `length(p)`), and multi-pattern joins (`MATCH (a)…, (b)…` parse but
+#            ignore RETURN and LIMIT).
+#   GOTCHA : LIMIT applies before DISTINCT, so `RETURN DISTINCT … LIMIT n` can
+#            return fewer than n rows while more exist — judge truncation on raw
+#            rows. Every builder below stays inside the SAFE set.
 #
 # Label-agnostic on name matches: code units are :Method ⪢ :Function in OO repos;
 # pinning :Function silently returns [] (the graph-tooling-v2 Phase 0 bug). CALLS
@@ -63,7 +67,17 @@ gq_q_inherits_sym()      { printf "MATCH (c)-[:INHERITS]->(p) WHERE c.name='%s'
 gq_q_derived_sym()       { printf "MATCH (c)-[:INHERITS]->(p) WHERE p.name='%s' RETURN c.qualified_name AS child, p.qualified_name AS parent LIMIT 200" "$1"; }
 gq_q_raises()            { printf "MATCH (f {name:'%s'})-[:RAISES|THROWS]->(e) RETURN e.name AS error, e.qualified_name AS qualified LIMIT 200" "$1"; }
 gq_q_raisers()           { printf "MATCH (f)-[:RAISES|THROWS]->(e {name:'%s'}) RETURN f.qualified_name AS raiser, f.file_path AS file LIMIT 200" "$1"; }
-gq_q_node_props()        { printf "MATCH (f) RETURN f.qualified_name AS q, f.complexity AS c, f.cognitive AS cog, f.is_entry_point AS ep LIMIT 10000"; }
+# $1 = comma-separated list of pre-escaped, single-quoted qualified names.
+gq_q_node_props()        { printf "MATCH (f) WHERE f.qualified_name IN [%s] RETURN f.qualified_name AS q, f.complexity AS c, f.cognitive AS cog, f.is_entry_point AS ep LIMIT 1000" "$1"; }
+# Dependents at exactly $2 CALLS hops (one query per depth: path variables are
+# unsupported, so the hop count comes from the fixed depth). Raw rows, no
+# DISTINCT — LIMIT applies before DISTINCT, so only a raw row count at the limit
+# reveals truncation. The file form skips callers inside the target file itself.
+GQ_DEP_LIMIT=5000
+gq_q_dependents_file()   { printf "MATCH (a)-[:CALLS*%s..%s]->(b) WHERE b.file_path = '%s' AND a.file_path <> '%s' RETURN a.qualified_name AS q, a.name AS name, a.file_path AS file, a.is_test AS test LIMIT %s" "$2" "$2" "$1" "$1" "$GQ_DEP_LIMIT"; }
+gq_q_dependents_symbol() { printf "MATCH (a)-[:CALLS*%s..%s]->(b {name:'%s'}) WHERE a.name <> '%s' RETURN a.qualified_name AS q, a.name AS name, a.file_path AS file, a.is_test AS test LIMIT %s" "$2" "$2" "$1" "$1" "$GQ_DEP_LIMIT"; }
+gq_q_importers()         { printf "MATCH (a)-[:IMPORTS]->(b) WHERE b.file_path = '%s' AND a.file_path <> '%s' RETURN a.file_path AS file LIMIT %s" "$1" "$1" "$GQ_DEP_LIMIT"; }
+gq_q_file_exists()       { printf "MATCH (f) WHERE f.file_path = '%s' RETURN f.file_path AS file LIMIT 1" "$1"; }
 gq_q_risk()              { printf "MATCH (f) WHERE f.unguarded_recursion=true OR f.alloc_in_loop=true OR f.recursion_in_loop=true OR f.linear_scan_in_loop=true RETURN f.qualified_name AS symbol, f.file_path AS file, f.complexity AS complexity, f.unguarded_recursion AS unguarded_recursion, f.alloc_in_loop AS alloc_in_loop, f.recursion_in_loop AS recursion_in_loop, f.linear_scan_in_loop AS linear_scan_in_loop LIMIT 200"; }
 
 # ── Runner + classifier ──

package/scripts/tools/_lib.sh

@@ -235,7 +235,7 @@ find_memory_bin() {
 # its own unavailable-JSON shape (the shapes differ per tool).
 graph_bootstrap() {
     local repo="$1" self_repo
-    REPO_ABS="$(cd "$repo" 2>/dev/null && pwd)" || return 1
+    REPO_ABS="$(cd "$repo" 2>/dev/null && pwd -P)" || return 1
     self_repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
     find_memory_bin "$REPO_ABS" "$self_repo" || return 1
     command -v jq >/dev/null 2>&1 || return 1
@@ -245,6 +245,8 @@ graph_bootstrap() {
 
 # Run a codebase-memory-mcp CLI tool. Echoes the JSON result (stdout); the engine's
 # `level=...` log lines go to stderr and are discarded unless DRAFT_MEMORY_DEBUG is set.
+# Args travel on stdin: the engine deprecated positional raw JSON (0.9.0 warns it
+# "will be removed in a future release"), and that warning lands in the discarded stderr.
 # Usage: memory_cli <tool> [json-args]
 memory_cli() {
     local tool="$1"
@@ -253,22 +255,12 @@ memory_cli() {
         return 1
     fi
     if [[ -n "${DRAFT_MEMORY_DEBUG:-}" ]]; then
-        "$MEMORY_BIN" cli "$tool" "$args"
+        "$MEMORY_BIN" cli "$tool" <<< "$args"
     else
-        "$MEMORY_BIN" cli "$tool" "$args" 2>/dev/null
+        "$MEMORY_BIN" cli "$tool" <<< "$args" 2>/dev/null
     fi
 }
 
-# Resolve the engine's project name for a repository absolute path via list_projects.
-# Echoes the project name, or nothing if the repo has not been indexed yet.
-memory_project_for_repo() {
-    local repo_abs="$1"
-    command -v jq >/dev/null 2>&1 || return 1
-    memory_cli list_projects '{}' 2>/dev/null \
-        | jq -r --arg p "$repo_abs" '.projects[]? | select(.root_path == $p) | .name' 2>/dev/null \
-        | head -1
-}
-
 # Total physical RAM in MB (portable). Echoes a positive integer, or nothing.
 _total_ram_mb() {
     if [[ -r /proc/meminfo ]]; then
@@ -306,52 +298,69 @@ _can_cgroup_bound() {
 
 # Index a repository under a memory bound. The codebase-memory-mcp engine
 # self-budgets ~50% of *physical* RAM and is not cgroup-aware, so a first index
-# of a huge repo can exhaust the host (the original 30 GB hang). On Linux we
-# confine it to a transient cgroup scope sized to DRAFT_INDEX_MEM_PCT (default
-# 25) of total RAM; CBM_WORKERS caps the engine's parallel working set so the
-# throttle has less transient pressure to absorb. Where cgroup v2 + systemd-run
-# are unavailable (e.g. macOS) the worker cap is the only bound. Never falls back
+# of a huge repo can exhaust the host (the original 30 GB hang). The engine's
+# own budget (CBM_MEM_BUDGET_MB) is set to DRAFT_INDEX_MEM_PCT (default 25) of
+# total RAM unless the user chose one; on Linux the process is also confined to
+# a transient cgroup scope of that size. CBM_WORKERS caps the engine's parallel
+# working set so the throttle has less transient pressure to absorb. Where cgroup
+# v2 + systemd-run are unavailable (e.g. macOS) the budget and worker cap are the
+# bound. Never falls back
 # from a started scope to an unbounded run — a bounded OOM fails the index
 # cleanly (host stays alive) rather than re-triggering the hang.
 # Echoes the engine's JSON result on stdout (same contract as memory_cli).
+# Usage: memory_index_bounded <repo-abs> [project-name]
 memory_index_bounded() {
-    local repo_abs="$1"
+    local repo_abs="$1" name="${2:-}"
     # Payload built with jq (never string concatenation) so a repo path
     # containing a `"` or `\` can never corrupt the JSON sent to the engine.
     command -v jq >/dev/null 2>&1 || return 1
     local json
-    json="$(jq -n --arg r "$repo_abs" '{repo_path:$r}')" || return 1
+    json="$(jq -n --arg r "$repo_abs" --arg n "$name" \
+        '{repo_path:$r} + (if $n == "" then {} else {name:$n} end)')" || return 1
     export CBM_WORKERS="${CBM_WORKERS:-4}"
     local total pct
     total="$(_total_ram_mb)"
     pct="${DRAFT_INDEX_MEM_PCT:-25}"
+    [[ "${total:-0}" -gt 0 ]] && export CBM_MEM_BUDGET_MB="${CBM_MEM_BUDGET_MB:-$(( total * pct / 100 ))}"
     if [[ "${total:-0}" -gt 0 ]] && _can_cgroup_bound; then
         local high_arg max_arg
         read -r high_arg max_arg <<< "$(_mem_bound_args "$total" "$pct")"
         if [[ -n "${DRAFT_MEMORY_DEBUG:-}" ]]; then
             systemd-run --user --scope -q -p "$high_arg" -p "$max_arg" \
-                -- "$MEMORY_BIN" cli index_repository "$json"
+                -- "$MEMORY_BIN" cli index_repository <<< "$json"
         else
             systemd-run --user --scope -q -p "$high_arg" -p "$max_arg" \
-                -- "$MEMORY_BIN" cli index_repository "$json" 2>/dev/null
+                -- "$MEMORY_BIN" cli index_repository <<< "$json" 2>/dev/null
         fi
     else
         memory_cli index_repository "$json"
     fi
 }
 
-# Ensure a repository is indexed in the engine; echo its project name.
-# Indexes on demand when absent. Returns 1 if the engine is unavailable.
+# Bring a repository's engine index up to date; echo its project name.
+# Always re-indexes: the engine indexes incrementally (content-based, git-aware),
+# so an unchanged repo costs ~0.1 s. Indexing only when the project was absent
+# left every live query answering from the first index ever taken — a symbol
+# added since stayed invisible while the result still said status:"ok".
+#
+# The project is named explicitly: the engine derives names by flattening '/' to
+# '-', so /x/a-b/c and /x/a/b-c shared one DB and each index overwrote the other.
+# A repo the engine already knows keeps its name (no forced full re-index); a new
+# one gets <basename>-<sha8 of its path>, which no other path can derive.
+# Returns 1 if the engine is unavailable.
 memory_ensure_index() {
     local repo_abs="$1"
     [[ -n "${MEMORY_BIN:-}" ]] || return 1
     command -v jq >/dev/null 2>&1 || return 1
-    local proj
-    proj="$(memory_project_for_repo "$repo_abs" 2>/dev/null || true)"
-    if [[ -z "$proj" ]]; then
-        proj="$(memory_index_bounded "$repo_abs" \
-            | jq -r '.project // empty' 2>/dev/null || true)"
+    local proj name
+    name="$(memory_cli list_projects '{}' \
+        | jq -r --arg p "$repo_abs" 'first(.projects[]? | select(.root_path == $p) | .name) // empty' 2>/dev/null || true)"
+    if [[ -z "$name" ]]; then
+        name="$(printf '%s' "$repo_abs" | { sha256sum 2>/dev/null || shasum -a 256; } | cut -c1-8)"
+        name="$(basename "$repo_abs")-$name"
     fi
+    proj="$(memory_index_bounded "$repo_abs" "$name" \
+        | jq -r '.project // empty' 2>/dev/null || true)"
     [[ -n "$proj" ]] || return 1
     printf '%s' "$proj"
 }

package/scripts/tools/cycle-detect.sh

@@ -69,15 +69,19 @@ graph_bootstrap "$REPO" || unavailable
 R2="$(gq_run "$PROJECT" "$(gq_q_cycles2)")" || unavailable
 R3="$(gq_run "$PROJECT" "$(gq_q_cycles3)")" || unavailable
 
-# Self-loops and duplicate orderings are filtered here rather than in Cypher:
-# the engine rejects `a.x < b.x`, which is what the query used to rely on.
-# A 2-cycle comes back twice (A,B and B,A), hence the doubled LIMIT upstream.
+# Degenerate rows and duplicate rotations are filtered here rather than in
+# Cypher: the engine rejects `a.x < b.x`, which is what the query used to rely on.
+# A cycle comes back once per rotation (a 2-cycle as A,B and B,A — hence the
+# doubled LIMIT upstream), and a self-loop also matches both patterns with a
+# repeated node, e.g. (x, x, x). Drop rows that repeat a node, rotate each to
+# start at its smallest member, and keep one of each.
 jq -n --argjson r2 "$R2" --argjson r3 "$R3" '
+    def cycles: map(select((unique | length) == length)
+                    | (indices(min)[0]) as $i | .[$i:] + .[:$i]) | unique;
     ( ((($r2.rows) // []) | length) >= 200
       or ((($r3.rows) // []) | length) >= 100 ) as $trunc
-    | ( ($r2.rows // []) | map(select(.[0] != .[1])) | unique_by(sort) ) as $two
     | {
-        cycles: ($two + ($r3.rows // [])),
+        cycles: ((($r2.rows // []) | cycles) + (($r3.rows // []) | cycles)),
         truncated: $trunc,
         source: "memory-graph"
       }'