@drafthq/draft 3.0.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Context-Driven Development for AI coding agents — install Draft into Claude Code, Cursor, Codex, or opencode.",
   "bin": {
     "draft": "cli/bin/draft.js"
@@ -24,6 +24,7 @@
   ],
   "scripts": {
     "test": "bash tests/test-cli.sh",
+    "version": "bash scripts/sync-version.sh && git add .claude-plugin/plugin.json .claude-plugin/marketplace.json web/index.html",
     "prepublishOnly": "bash scripts/build-integrations.sh"
   },
   "repository": {

package/scripts/lib.sh

@@ -158,11 +158,19 @@ TOOLS=(
     "mermaid-from-graph.sh"
     "graph-snapshot.sh"
     "graph-init.sh"
-    "okf-emit.sh"
-    "okf-bundle.sh"
-    "okf-check.sh"
     "graph-impact.sh"
     "graph-callers.sh"
+    "graph-arch.sh"
+    # graph-tooling-v2: generic passthrough + purpose-built capability wrappers
+    "graph-query.sh"
+    "graph-snippet.sh"
+    "graph-search.sh"
+    "graph-tests.sh"
+    "graph-deps.sh"
+    "graph-hierarchy.sh"
+    "graph-errors.sh"
+    "graph-risk.sh"
+    "graph-traces.sh"
     "validate-frontmatter.sh"
     # Foundations hygiene/verification tools
     "check-graph-usage-report.sh"

package/scripts/tools/_graph_queries.sh

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# _graph_queries.sh — canonical Cypher builders + fail-loud runner for the
+# codebase-memory-mcp engine. Sourced by the graph-*.sh wrappers; never executed.
+#
+# Single source of query truth (graph-tooling-v2 Guardrail 2): no Cypher literal
+# should live in a wrapper entrypoint. A label or dialect fix is a one-line edit
+# 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.
+#            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
+# edges only connect callables, so dropping the label stays precise.
+
+# shellcheck shell=bash
+
+# Pull in memory_cli / find_memory_bin / MEMORY_BIN if a wrapper sourced only us.
+_GQ_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ "$(type -t memory_cli 2>/dev/null)" != function ]]; then
+    # shellcheck source=_lib.sh
+    source "$_GQ_DIR/_lib.sh"
+fi
+
+# Escape single quotes for embedding inside a Cypher single-quoted string literal.
+gq_escape() {
+    local s="$1"
+    printf '%s' "${s//\'/\\\'}"
+}
+
+# ── Cypher builders. Each echoes one query string. $1 = pre-escaped symbol. ──
+
+gq_q_exists()            { printf "MATCH (f {name:'%s'}) RETURN f.name AS name LIMIT 1" "$1"; }
+gq_q_callers()           { printf "MATCH (c)-[:CALLS]->(f {name:'%s'}) RETURN c.name AS caller, c.file_path AS file LIMIT 200" "$1"; }
+gq_q_callers_prod()      { printf "MATCH (c)-[:CALLS]->(f {name:'%s'}) WHERE c.is_test=false AND NOT c.file_path STARTS WITH 'tests/' RETURN c.name AS caller, c.file_path AS file LIMIT 200" "$1"; }
+gq_q_callers_qualified() { printf "MATCH (c)-[:CALLS]->(f {qualified_name:'%s'}) RETURN c.name AS caller, c.file_path AS file LIMIT 200" "$1"; }
+gq_q_cycles2()           { printf "MATCH (a)-[:CALLS]->(b)-[:CALLS]->(a) WHERE a.qualified_name < b.qualified_name RETURN a.qualified_name AS a, b.qualified_name AS b LIMIT 100"; }
+gq_q_cycles3()           { printf "MATCH (a)-[:CALLS]->(b)-[:CALLS]->(c)-[:CALLS]->(a) RETURN a.qualified_name AS a, b.qualified_name AS b, c.qualified_name AS c LIMIT 100"; }
+gq_q_tests()             { printf "MATCH (t)-[:TESTS]->(f {name:'%s'}) RETURN t.qualified_name AS test, t.file_path AS file LIMIT 200" "$1"; }
+gq_q_tested_all()        { printf "MATCH (t)-[:TESTS]->(f) RETURN f.qualified_name AS symbol LIMIT 2000"; }
+gq_q_exported()          { printf "MATCH (f) WHERE f.is_exported=true RETURN f.qualified_name AS symbol, f.file_path AS file LIMIT 2000"; }
+gq_q_imports()           { printf "MATCH (a)-[:IMPORTS]->(b) RETURN a.file_path AS src, b.file_path AS dst LIMIT 1000"; }
+gq_q_co_change()         { printf "MATCH (a:File)-[r:FILE_CHANGES_WITH]->(b:File) RETURN a.name AS src, b.name AS dst, r.coupling_score AS score ORDER BY r.coupling_score DESC LIMIT 40"; }
+gq_q_inherits()          { printf "MATCH (c)-[:INHERITS]->(p) RETURN c.qualified_name AS child, p.qualified_name AS parent LIMIT 500"; }
+gq_q_inherits_sym()      { printf "MATCH (c)-[:INHERITS]->(p) WHERE c.name='%s' RETURN c.qualified_name AS child, p.qualified_name AS parent LIMIT 200" "$1"; }
+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_writes()            { printf "MATCH (f {name:'%s'})-[:WRITES]->(v) RETURN v.name AS target, v.file_path AS file 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"; }
+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 ──
+
+# gq_run <project> <cypher>
+# Runs query_graph and echoes the validated raw engine JSON. Builds the JSON
+# payload with jq so a quote/backslash in the query can never produce invalid
+# JSON. Requires MEMORY_BIN (set by find_memory_bin) and jq. Returns:
+#   0  valid JSON emitted on stdout
+#   3  engine unavailable / no binary / non-JSON output  (FAIL-LOUD: the caller
+#      must NOT treat this as an empty true-negative result)
+gq_run() {
+    local project="$1" query="$2"
+    [[ -n "${MEMORY_BIN:-}" ]] || return 3
+    command -v jq >/dev/null 2>&1 || return 3
+    local payload res
+    payload="$(jq -n --arg p "$project" --arg q "$query" '{project:$p, query:$q}')" || return 3
+    res="$(memory_cli query_graph "$payload" 2>/dev/null || true)"
+    [[ -n "$res" ]] || return 3
+    printf '%s' "$res" | jq -e . >/dev/null 2>&1 || return 3
+    printf '%s' "$res"
+}
+
+# gq_rows_len <json> -> integer row count (0 on parse failure).
+gq_rows_len() {
+    printf '%s' "$1" | jq -r '(.rows // []) | length' 2>/dev/null || printf '0'
+}
+
+# gq_symbol_status <project> <sym_esc> <result_json> -> ok | no-edges | no-match
+# Fail-loud disambiguation (Guardrail 4): an empty result is only a true negative
+# ("no-edges") when the node actually exists; otherwise it is "no-match". An
+# existence probe runs only when the primary result is empty (hot path stays one
+# query).
+gq_symbol_status() {
+    local project="$1" sym="$2" result="$3"
+    if [[ "$(gq_rows_len "$result")" -gt 0 ]]; then
+        printf 'ok'; return
+    fi
+    local ex
+    ex="$(gq_run "$project" "$(gq_q_exists "$sym")" || true)"
+    if [[ -n "$ex" && "$(gq_rows_len "$ex")" -gt 0 ]]; then
+        printf 'no-edges'
+    else
+        printf 'no-match'
+    fi
+}

package/scripts/tools/adr-index.sh

@@ -84,7 +84,7 @@ while IFS= read -r -d '' file; do
 
     # If no title in frontmatter, fallback to first H1.
     if [[ -z "$title" ]]; then
-        title="$(grep -m1 '^# ' "$file" 2>/dev/null | sed 's/^#\s*//' || true)"
+        title="$(grep -m1 '^# ' "$file" 2>/dev/null | sed 's/^#[[:space:]]*//' || true)"
     fi
 
     tracks=()
@@ -108,7 +108,7 @@ while IFS= read -r -d '' file; do
         "$(json_escape "$status")" \
         "$(json_escape "$file")" \
         "$tr_json"
-done < <(find "$ROOT" -maxdepth 2 -type f -name '*.md' -print0 2>/dev/null | sort -z)
+done < <(find "$ROOT" -maxdepth 2 -type f -name '*.md' 2>/dev/null | sort | tr '\n' '\0')
 
 if $first; then
     printf ']}\n'

package/scripts/tools/check-scope-conflicts.sh

@@ -112,7 +112,7 @@ emit() {
     if ((EMIT_JSON)); then
         printf '{"conflict_count": %d, "conflicts": [\n' "$conflict_count"
         local first=1 c track kind detail
-        for c in "${conflicts[@]}"; do
+        for c in ${conflicts[@]+"${conflicts[@]}"}; do
             IFS='|' read -r track kind detail <<< "$c"
             if ((first)); then first=0; else printf ',\n'; fi
             printf ' {"track":"%s","kind":"%s","detail":"%s"}' \
@@ -127,7 +127,7 @@ emit() {
             printf 'SCOPE: %d conflict(s) across %d track(s).\n' \
                 "$conflict_count" "${#TRACK_PATHS[@]}" >&2
             local c track kind detail
-            for c in "${conflicts[@]}"; do
+            for c in ${conflicts[@]+"${conflicts[@]}"}; do
                 IFS='|' read -r track kind detail <<< "$c"
                 printf ' [%s] %s — %s\n' "$kind" "$track" "$detail" >&2
             done

package/scripts/tools/check-skill-line-caps.sh

@@ -78,7 +78,7 @@ emit() {
         printf '{"over_cap_count": %d, "global_cap": %d, "findings": [\n' \
             "$over_count" "$GLOBAL_CAP"
         local first=1 v name lines cap
-        for v in "${findings[@]}"; do
+        for v in ${findings[@]+"${findings[@]}"}; do
             IFS='|' read -r name lines cap <<< "$v"
             if ((first)); then first=0; else printf ',\n'; fi
             printf ' {"skill":"%s","lines":%d,"cap":%d}' \
@@ -100,7 +100,7 @@ emit() {
                 "$over_count" "$mode"
         fi
         local v name lines cap
-        for v in "${findings[@]}"; do
+        for v in ${findings[@]+"${findings[@]}"}; do
             IFS='|' read -r name lines cap <<< "$v"
             if ((ENFORCE)); then
                 printf ' %s: %d lines (cap %d)\n' "$name" "$lines" "$cap" >&2

package/scripts/tools/cycle-detect.sh

@@ -15,8 +15,8 @@
 # Exit codes: 0 OK, 1 invocation error, 2 graph engine/data unavailable.
 set -euo pipefail
 
-# shellcheck source=_lib.sh
-source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
 
 REPO="."
 
@@ -31,8 +31,10 @@ Flags:
   --repo DIR  Repository root (default: cwd).
   --help      Show this help.
 
-Output: JSON {cycles:[[a,b],[a,b,c]], source}. Fallback when the engine is
-unavailable: {"cycles":[],"source":"unavailable"}, exit 2.
+Output: JSON {cycles:[[a,b],[a,b,c]], truncated, source}. `truncated` is true
+when either cycle query hit its LIMIT (results are a sample, not exhaustive).
+Fallback when the engine is unavailable: {"cycles":[],"source":"unavailable"},
+exit 2.
 EOF
 }
 
@@ -60,16 +62,21 @@ command -v jq >/dev/null 2>&1 || unavailable
 PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
 [[ -n "$PROJECT" ]] || unavailable
 
-# 2-cycles: a -> b -> a (dedup with a.qualified_name < b.qualified_name).
-Q2="MATCH (a:Function)-[:CALLS]->(b:Function)-[:CALLS]->(a) WHERE a.qualified_name < b.qualified_name RETURN a.qualified_name AS a, b.qualified_name AS b LIMIT 100"
-# 3-cycles: a -> b -> c -> a.
-Q3="MATCH (a:Function)-[:CALLS]->(b:Function)-[:CALLS]->(c:Function)-[:CALLS]->(a) RETURN a.qualified_name AS a, b.qualified_name AS b, c.qualified_name AS c LIMIT 100"
+# 2- and 3-node CALLS cycles. Cypher lives in _graph_queries.sh (label-agnostic;
+# the Phase 0 fix — code units are mostly :Method, and CALLS only connects
+# callables). LIMIT 100 caps each, so results are a sample, not exhaustive.
+R2="$(gq_run "$PROJECT" "$(gq_q_cycles2)" || echo '{}')"
+R3="$(gq_run "$PROJECT" "$(gq_q_cycles3)" || echo '{}')"
 
-R2="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$Q2\"}" || echo '{}')"
-R3="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$Q3\"}" || echo '{}')"
+# Guard against empty/non-JSON engine output so --argjson never aborts the script.
+echo "$R2" | jq -e . >/dev/null 2>&1 || R2='{}'
+echo "$R3" | jq -e . >/dev/null 2>&1 || R3='{}'
 
-jq -n --argjson r2 "${R2:-{\}}" --argjson r3 "${R3:-{\}}" '
-    {
-      cycles: (((($r2.rows) // []) + (($r3.rows) // []))),
-      source: "memory-graph"
-    }'
+jq -n --argjson r2 "$R2" --argjson r3 "$R3" '
+    ( ((($r2.rows) // []) | length) >= 100
+      or ((($r3.rows) // []) | length) >= 100 ) as $trunc
+    | {
+        cycles: (((($r2.rows) // []) + (($r3.rows) // []))),
+        truncated: $trunc,
+        source: "memory-graph"
+      }'

package/scripts/tools/diff-templates-vs-tracks.sh

@@ -146,7 +146,7 @@ emit_records() {
     if ((EMIT_JSON)); then
         printf '{"drift_count": %d, "records": [\n' "$drift_count"
         local first=1
-        for r in "${drift_records[@]}"; do
+        for r in ${drift_records[@]+"${drift_records[@]}"}; do
             local track kind detail
             IFS='|' read -r track kind detail <<< "$r"
             if ((first)); then first=0; else printf ',\n'; fi
@@ -163,7 +163,7 @@ emit_records() {
             printf 'DRIFT: %d defect(s) across %d track(s).\n' \
                 "$drift_count" "${#TRACK_PATHS[@]}" >&2
             local r track kind detail
-            for r in "${drift_records[@]}"; do
+            for r in ${drift_records[@]+"${drift_records[@]}"}; do
                 IFS='|' read -r track kind detail <<< "$r"
                 printf ' [%s] %s — %s\n' "$kind" "$track" "$detail" >&2
             done

package/scripts/tools/fix-whitespace.sh

@@ -54,6 +54,11 @@ fix_file() {
         return 2
     fi
 
+    # Empty file: nothing to normalize (avoid writing a spurious newline).
+    if [[ ! -s "$file" ]]; then
+        return 1
+    fi
+
     local original
     original="$(cat "$file")"
 
@@ -66,18 +71,19 @@ fix_file() {
         | sed -e :a -e '/^\n*$/{$d;N;ba}'
     )"$'\n'
 
-    if [[ "$fixed" == "$original" ]]; then
-        return 1 # already clean
-    fi
-
+    # Compare the bytes we would write against the file on disk — NOT the
+    # command-substitution copies (which strip then re-add the trailing newline,
+    # so they could never compare equal). This keeps fix_file idempotent.
     local _tmp
     _tmp="$(mktemp "${file}.XXXXXX")"
-    if printf '%s' "$fixed" > "$_tmp"; then
-        mv -f "$_tmp" "$file"
-    else
+    printf '%s' "$fixed" > "$_tmp" || { rm -f "$_tmp"; return 2; }
+
+    if cmp -s "$_tmp" "$file"; then
         rm -f "$_tmp"
-        return 2
+        return 1 # already clean — no change on disk
     fi
+
+    mv -f "$_tmp" "$file"
     return 0
 }
 
@@ -109,7 +115,7 @@ case "$1" in
         fi
         while IFS= read -r -d '' f; do
             TARGETS+=("$f")
-        done < <(find "$TRACK_DIR" -maxdepth 1 -name "*.md" -print0 | sort -z)
+        done < <(find "$TRACK_DIR" -maxdepth 1 -name "*.md" | sort | tr '\n' '\0')
         ;;
     --draft)
         REPO_ROOT="${2:-$(pwd)}"

package/scripts/tools/graph-arch.sh

@@ -0,0 +1,72 @@
+#!/usr/bin/env bash
+# graph-arch.sh — emit the architecture view from the knowledge graph.
+#
+# The engine-only replacement for the old committed architecture.json. Resolves
+# the codebase-memory-mcp engine, indexes the repo on demand, auto-resolves the
+# project, and prints the full get_architecture(all) JSON to stdout — node labels,
+# edge types, languages, packages (fan-in/out), entry points, routes, hotspots,
+# boundaries, layers, clusters, file tree. Pipe to jq to slice the field you need:
+#
+#   scripts/tools/graph-arch.sh --repo . | jq '.packages'
+#   scripts/tools/graph-arch.sh --repo . | jq '.routes'
+#
+# The engine binary is usually NOT on $PATH; this wrapper resolves it (via
+# _lib.sh:find_memory_bin) so callers never invoke `codebase-memory-mcp` directly.
+#
+# Usage: scripts/tools/graph-arch.sh [--repo DIR]
+# Output: the architecture JSON object on success; {"source":"unavailable"} on failure.
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine/data unavailable.
+set -euo pipefail
+
+# shellcheck source=_lib.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+
+REPO="."
+
+usage() {
+    cat <<'EOF'
+graph-arch.sh — architecture view (packages, routes, layers, hotspots) from the graph.
+
+Usage:
+  scripts/tools/graph-arch.sh [--repo DIR]
+
+Flags:
+  --repo DIR  Repository root (default: cwd).
+  --help      Show this help.
+
+Output: the get_architecture(all) JSON object on success. Pipe to jq to slice it
+(`| jq '.packages'`, `| jq '.routes'`, …). Emits {"source":"unavailable"} and exits 2
+when the graph engine is unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+if [[ ! -d "$REPO" ]]; then
+    echo "ERROR: --repo '$REPO' is not a directory" >&2
+    exit 1
+fi
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() { echo '{"source":"unavailable"}'; exit 2; }
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+ARCH_JSON="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"all\"]}" || true)"
+[[ -n "$ARCH_JSON" ]] || unavailable
+
+# Validate it parses and looks like an architecture object before emitting.
+echo "$ARCH_JSON" | jq -e '.total_nodes != null' >/dev/null 2>&1 || unavailable
+echo "$ARCH_JSON" | jq '.'

package/scripts/tools/graph-callers.sh

@@ -1,38 +1,54 @@
 #!/usr/bin/env bash
-# graph-callers.sh — enumerate direct callers of a function, from the knowledge graph.
+# graph-callers.sh — enumerate callers of a function, from the knowledge graph.
 #
 # Replaces `graph --query --symbol <name> --mode callers`. Backed by the
-# codebase-memory-mcp engine via a single-hop CALLS openCypher pattern (the
-# dialect handles fixed-length patterns reliably).
+# codebase-memory-mcp engine. All Cypher lives in _graph_queries.sh (single
+# source of query truth); this entrypoint only parses args and shapes JSON.
 #
 # Usage:
 #   scripts/tools/graph-callers.sh --repo DIR --symbol NAME
+#                                  [--transitive[=N]] [--prod-only] [--qualified]
 #
-# Output: JSON {symbol, callers:[{name,file}], source}.
+# Output: JSON {symbol, callers:[{name,file[,hop]}], status, source}.
 #   source = "memory-graph" | "unavailable"
+#   status = "ok" | "no-edges" | "no-match" | "unavailable"
+#            (fail-loud: distinguishes node-not-found from node-has-no-callers
+#             from engine-unavailable — never a bare [] that reads as a true
+#             negative).
 #
 # Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
 set -euo pipefail
 
-# shellcheck source=_lib.sh
-source "$(dirname "${BASH_SOURCE[0]}")/_lib.sh"
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
 
 REPO="."
 SYMBOL=""
+TRANSITIVE=0
+DEPTH=3
+PROD_ONLY=0
+QUALIFIED=0
 
 usage() {
     cat <<'EOF'
-graph-callers.sh — direct callers of a function.
+graph-callers.sh — callers of a function from the knowledge graph.
 
 Usage:
-  scripts/tools/graph-callers.sh --repo DIR --symbol NAME
+  scripts/tools/graph-callers.sh --repo DIR --symbol NAME [options]
 
 Flags:
-  --repo DIR     Repository root (default: cwd).
-  --symbol NAME  Function name to find callers of (required).
-  --help         Show this help.
+  --repo DIR      Repository root (default: cwd).
+  --symbol NAME   Function name to find callers of (required).
+  --transitive[=N] Transitive (upstream) callers via the trace_path expander,
+                  depth N (default 3). Adds a `hop` field per caller.
+  --prod-only     Best-effort exclude test/mock callers (is_test=false AND not
+                  under tests/). is_test is partial in the engine, so this is a
+                  heuristic, not a guarantee. Ignored with --transitive.
+  --qualified     Match SYMBOL against qualified_name instead of name (use to
+                  disambiguate same-named nodes). Ignored with --transitive.
+  --help          Show this help.
 
-Output: JSON {symbol, callers, source}. Exit 2 when engine unavailable.
+Output: JSON {symbol, callers, status, source}. Exit 2 when engine unavailable.
 EOF
 }
 
@@ -40,6 +56,10 @@ while [[ $# -gt 0 ]]; do
     case "$1" in
         --repo) REPO="$2"; shift 2;;
         --symbol) SYMBOL="$2"; shift 2;;
+        --transitive) TRANSITIVE=1; shift;;
+        --transitive=*) TRANSITIVE=1; DEPTH="${1#*=}"; shift;;
+        --prod-only) PROD_ONLY=1; shift;;
+        --qualified) QUALIFIED=1; shift;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -47,13 +67,14 @@ done
 
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 [[ -n "$SYMBOL" ]] || { echo "ERROR: --symbol is required" >&2; usage >&2; exit 1; }
+[[ "$DEPTH" =~ ^[0-9]+$ ]] || { echo "ERROR: --transitive depth must be a non-negative integer" >&2; exit 1; }
 
 REPO_ABS="$(cd "$REPO" && pwd)"
 SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
 
 unavailable() {
-    jq -n --arg s "$SYMBOL" '{symbol:$s, callers:[], source:"unavailable"}' 2>/dev/null \
-        || echo '{"callers":[],"source":"unavailable"}'
+    jq -n --arg s "$SYMBOL" '{symbol:$s, callers:[], status:"unavailable", source:"unavailable"}' 2>/dev/null \
+        || echo '{"callers":[],"status":"unavailable","source":"unavailable"}'
     exit 2
 }
 
@@ -63,12 +84,42 @@ command -v jq >/dev/null 2>&1 || unavailable
 PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
 [[ -n "$PROJECT" ]] || unavailable
 
-# Escape single quotes in the symbol for the Cypher string literal.
-SYM_ESC="${SYMBOL//\'/\\\'}"
-Q="MATCH (c)-[:CALLS]->(f:Function {name:'$SYM_ESC'}) RETURN c.name AS caller, c.file_path AS file LIMIT 200"
-RES="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$Q\"}" || echo '{}')"
+SYM_ESC="$(gq_escape "$SYMBOL")"
 
-echo "${RES:-{\}}" | jq --arg s "$SYMBOL" '
+if [[ "$TRANSITIVE" -eq 1 ]]; then
+    # Transitive upstream callers via the trace_path depth-bounded expander.
+    # direction:"both" is the reliable form; we read its .callers array.
+    PAYLOAD="$(jq -n --arg p "$PROJECT" --arg f "$SYMBOL" --argjson d "$DEPTH" \
+        '{project:$p, function_name:$f, depth:$d, direction:"both"}')"
+    RES="$(memory_cli trace_path "$PAYLOAD" 2>/dev/null || true)"
+    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable
+    N="$(echo "$RES" | jq -r '(.callers // []) | length' 2>/dev/null || echo 0)"
+    if [[ "$N" -gt 0 ]]; then STATUS="ok"; else
+        EX="$(gq_run "$PROJECT" "$(gq_q_exists "$SYM_ESC")" || true)"
+        if [[ -n "$EX" && "$(gq_rows_len "$EX")" -gt 0 ]]; then STATUS="no-edges"; else STATUS="no-match"; fi
+    fi
+    echo "$RES" | jq --arg s "$SYMBOL" --arg st "$STATUS" '
+        {symbol:$s,
+         callers: [ (.callers // [])[] | {name:.name, file:(.qualified_name // ""), hop:(.hop // 1)} ],
+         status:$st, source:"memory-graph"}'
+    exit 0
+fi
+
+# Direct (single-hop) callers. Pick the builder by mode.
+if [[ "$QUALIFIED" -eq 1 ]]; then
+    Q="$(gq_q_callers_qualified "$SYM_ESC")"
+elif [[ "$PROD_ONLY" -eq 1 ]]; then
+    Q="$(gq_q_callers_prod "$SYM_ESC")"
+else
+    Q="$(gq_q_callers "$SYM_ESC")"
+fi
+
+RES="$(gq_run "$PROJECT" "$Q" || true)"
+[[ -n "$RES" ]] || unavailable
+
+STATUS="$(gq_symbol_status "$PROJECT" "$SYM_ESC" "$RES")"
+
+echo "$RES" | jq --arg s "$SYMBOL" --arg st "$STATUS" '
     {symbol:$s,
      callers: [ (.rows // [])[] | {name:.[0], file:.[1]} ],
-     source:"memory-graph"}'
+     status:$st, source:"memory-graph"}'

package/scripts/tools/graph-deps.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# graph-deps.sh — real file/module import graph from the knowledge graph (IMPORTS).
+#
+# graph-tooling-v2 Phase 3/4. The authoritative module-dependency graph, derived
+# from actual IMPORTS edges — not the directory-stub `fan_in` heuristic. Feeds the
+# architecture.md §9 dependency diagram (mermaid-from-graph.sh module-deps) and
+# blast-radius reasoning.
+#
+# Self-imports (src == dst, an artifact of how some languages attribute a file's
+# own symbols) are filtered out so the result is a true cross-file graph.
+#
+# Usage:
+#   scripts/tools/graph-deps.sh --repo DIR [--file PATH]
+#
+# Output: JSON {imports:[{src,dst}], total, truncated, source}. With --file, only
+# edges whose src ends with PATH are kept (a file's outgoing dependencies).
+#
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+FILE=""
+
+usage() {
+    cat <<'EOF'
+graph-deps.sh — real module/file import graph (IMPORTS edges).
+
+Usage:
+  scripts/tools/graph-deps.sh --repo DIR [--file PATH]
+
+Flags:
+  --repo DIR   Repository root (default: cwd).
+  --file PATH  Keep only edges whose source file ends with PATH.
+  --help       Show this help.
+
+Output: JSON {imports:[{src,dst}], total, truncated, source}. Self-imports are
+filtered. Exit 2 when engine unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --file) FILE="$2"; shift 2;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() { echo '{"imports":[],"total":0,"source":"unavailable"}'; exit 2; }
+
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable
+command -v jq >/dev/null 2>&1 || unavailable
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+RES="$(gq_run "$PROJECT" "$(gq_q_imports)" || true)"
+[[ -n "$RES" ]] || unavailable
+
+echo "$RES" | jq --arg f "$FILE" '
+    [ (.rows // [])[]
+      | {src:.[0], dst:.[1]}
+      | select(.src != null and .dst != null and .src != .dst)
+      | select($f == "" or (.src | endswith($f))) ] as $e
+    | {imports: $e, total: ($e | length),
+       truncated: (((.rows // []) | length) >= 1000),
+       source:"memory-graph"}'