@drafthq/draft 3.0.0 → 3.2.0

package/scripts/tools/graph-snapshot.sh

@@ -1,19 +1,23 @@
 #!/usr/bin/env bash
-# graph-snapshot.sh — materialize a lightweight, committed knowledge-graph snapshot.
+# graph-snapshot.sh — index the repo into the local graph engine and write the
+# committed gate marker (schema.yaml).
 #
-# In the codebase-memory-mcp model, Claude Code skills query the engine live
-# (on-demand indexing into ~/.cache). This snapshot exists for the two cases
-# that cannot run the engine: PR-reviewable graph state, and the Copilot/Gemini
-# integrations (which read committed files, not MCP). It is small and derived —
-# git remains the source of truth.
+# Draft is engine-only and opinionated: structural truth lives in the local
+# codebase-memory-mcp engine, queried on demand via the `graph-*.sh` wrappers
+# (which shell out to `codebase-memory-mcp cli <tool>`). There is no committed
+# machine-readable mirror of the graph — no architecture.json, hotspots.jsonl,
+# *.mermaid, or okf/ bundle. Those were lossy, went stale on the next commit, and
+# duplicated what the engine serves precisely and live. Git remains the source of
+# truth; the engine is the structural index over it.
 #
-# Writes under <repo>/draft/graph/:
-#   schema.yaml          engine + project metadata + counts (gates skill graph use)
-#   architecture.json    raw get_architecture(all) output
-#   hotspots.jsonl       fan-in-ranked symbols, one JSON object per line
-#   module-deps.mermaid  co-change coupling diagram
-#   proto-map.mermaid    detected-route diagram
-#   okf/                 Open Knowledge Format bundle (portable markdown mirror)
+# Writes one file under <repo>/draft/graph/:
+#   schema.yaml   engine + project metadata + index counts. Its presence is the
+#                 GATE that tells skills the graph engine is wired for this repo
+#                 (see core/shared/graph-query.md Pre-Check). It carries no graph
+#                 data — every structural query goes to the live engine.
+#
+# Re-running on a repo that still has an old fat snapshot prunes the stale
+# committed artifacts, migrating it to the thin model.
 #
 # Usage: scripts/tools/graph-snapshot.sh [--repo DIR] [--out DIR]
 # Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
@@ -28,17 +32,21 @@ OUT_DIR=""
 
 usage() {
     cat <<'EOF'
-graph-snapshot.sh — write a committed knowledge-graph snapshot to draft/graph/.
+graph-snapshot.sh — index the repo and write the draft/graph/ gate marker.
+
+Indexes the repository into the local graph engine and writes draft/graph/schema.yaml
+(the gate + provenance marker). It writes NO committed graph data — structural
+queries run live against the engine via the graph-*.sh wrappers.
 
 Usage:
   scripts/tools/graph-snapshot.sh [--repo DIR] [--out DIR]
 
 Flags:
   --repo DIR  Repository root (default: cwd).
-  --out DIR   Snapshot dir (default: <repo>/draft/graph).
+  --out DIR   Gate-marker dir (default: <repo>/draft/graph).
   --help      Show this help.
 
-Exit 0 on success, 2 when the graph engine is unavailable (no snapshot written).
+Exit 0 on success, 2 when the graph engine is unavailable (nothing written).
 EOF
 }
 
@@ -57,51 +65,56 @@ REPO_ABS="$(cd "$REPO" && pwd)"
 SELF_REPO="$(cd "$TOOLS_DIR/../.." && pwd)"
 OUT="${OUT_DIR:-$REPO_ABS/draft/graph}"
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || { echo "graph engine unavailable — no snapshot written" >&2; exit 2; }
-command -v jq >/dev/null 2>&1 || { echo "jq required for snapshot" >&2; exit 2; }
+find_memory_bin "$REPO_ABS" "$SELF_REPO" || { echo "graph engine unavailable — nothing written" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || { echo "jq required" >&2; exit 2; }
 
+# Index on demand; this is the valuable side-effect — it ensures the engine holds
+# a current index of the repo so live queries resolve.
 PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || { echo "could not index repo — no snapshot written" >&2; exit 2; }
+[[ -n "$PROJECT" ]] || { echo "could not index repo — nothing written" >&2; exit 2; }
 
 mkdir -p "$OUT"
 
-# 1. architecture.json (full get_architecture)
-ARCH="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"all\"]}" || echo '{}')"
-echo "$ARCH" | jq '.' > "$OUT/architecture.json"
-
-# 2. hotspots.jsonl (one object per line)
-"$TOOLS_DIR/hotspot-rank.sh" --repo "$REPO_ABS" 2>/dev/null \
-    | jq -c '.hotspots[]?' > "$OUT/hotspots.jsonl" || true
-
-# 3. mermaid diagrams (best-effort; tools emit a stub + exit 2 if empty)
-"$TOOLS_DIR/mermaid-from-graph.sh" --repo "$REPO_ABS" --diagram module-deps > "$OUT/module-deps.mermaid" 2>/dev/null || true
-"$TOOLS_DIR/mermaid-from-graph.sh" --repo "$REPO_ABS" --diagram proto-map  > "$OUT/proto-map.mermaid"  2>/dev/null || true
+# Prune any stale fat-snapshot artifacts from a prior (pre-engine-only) run so a
+# re-index migrates the repo to the thin model.
+rm -f "$OUT/architecture.json" "$OUT/hotspots.jsonl" \
+      "$OUT/module-deps.mermaid" "$OUT/proto-map.mermaid" 2>/dev/null || true
+rm -rf "$OUT/okf" 2>/dev/null || true
+
+# schema.yaml — provenance + gate. Counts are point-of-index provenance only;
+# the live engine is authoritative.
+STATUS_JSON="$(memory_cli index_status "{\"project\":\"$PROJECT\"}" || echo '{}')"
+# Tolerate field-name variation AND non-JSON output across engine versions;
+# counts are provenance only and must never abort the gate-marker write.
+NODES="$(echo "$STATUS_JSON" | jq -r '.nodes // .node_count // .total_nodes // 0' 2>/dev/null || echo 0)"
+EDGES="$(echo "$STATUS_JSON" | jq -r '.edges // .edge_count // .total_edges // 0' 2>/dev/null || echo 0)"
+VER="$("$MEMORY_BIN" --version 2>/dev/null | awk '{print $NF}' || echo unknown)"
 
-# 4. OKF bundle (best-effort) — portable Open Knowledge Format mirror of the graph.
-"$TOOLS_DIR/okf-emit.sh" --repo "$REPO_ABS" --snapshot "$OUT" --out "$OUT/okf" >/dev/null 2>&1 || true
+# Incremental-refresh provenance (graph-tooling-v2 Phase 5): the engine indexes
+# incrementally (content-based, git-aware), so re-indexing only touches changed
+# files. detect_changes reports that working-tree delta — recorded as provenance
+# and echoed so a refresh shows what moved. Best-effort: never aborts the write.
+CHANGES_JSON="$(memory_cli detect_changes "{\"project\":\"$PROJECT\"}" 2>/dev/null || echo '{}')"
+echo "$CHANGES_JSON" | jq -e . >/dev/null 2>&1 || CHANGES_JSON='{}'
+CHANGED_FILES="$(echo "$CHANGES_JSON" | jq -r '.changed_count // (.changed_files | length?) // 0' 2>/dev/null || echo 0)"
+IMPACTED="$(echo "$CHANGES_JSON" | jq -r '(.impacted_symbols | length?) // 0' 2>/dev/null || echo 0)"
 
-# 5. schema.yaml — metadata + gate for skill graph use
-NODES="$(echo "$ARCH" | jq -r '.total_nodes // 0')"
-EDGES="$(echo "$ARCH" | jq -r '.total_edges // 0')"
-HOTN="$(wc -l < "$OUT/hotspots.jsonl" | tr -d ' ')"
-VER="$("$MEMORY_BIN" --version 2>/dev/null | awk '{print $NF}' || echo unknown)"
 cat > "$OUT/schema.yaml" <<EOF
-# Draft knowledge-graph snapshot — generated by scripts/tools/graph-snapshot.sh
-# Derived from the codebase-memory-mcp engine; git remains source of truth.
+# Draft graph gate marker — written by scripts/tools/graph-snapshot.sh
+# Draft is engine-only: this file carries NO graph data. Its presence signals that
+# the local codebase-memory-mcp engine is wired for this repo. Query the engine
+# live via the graph-*.sh wrappers (or \`codebase-memory-mcp cli <tool>\`).
+# Counts below are point-of-index provenance; the live engine is authoritative.
 engine: codebase-memory-mcp
 engine_version: "$VER"
 project: "$PROJECT"
-generated_at: "$(date -Iseconds 2>/dev/null || date)"
-nodes: $NODES
-edges: $EDGES
-hotspots: $HOTN
-artifacts:
-  - architecture.json
-  - hotspots.jsonl
-  - module-deps.mermaid
-  - proto-map.mermaid
-  - okf/
+generated_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+indexed_nodes: $NODES
+indexed_edges: $EDGES
+changed_files: $CHANGED_FILES
+impacted_symbols: $IMPACTED
+access: engine-live
 EOF
 
-echo "Snapshot written to $OUT (nodes=$NODES edges=$EDGES hotspots=$HOTN)"
+echo "Indexed $PROJECT and wrote gate marker to $OUT/schema.yaml (nodes=$NODES edges=$EDGES, changed_files=$CHANGED_FILES impacted_symbols=$IMPACTED)"
 exit 0

package/scripts/tools/graph-snippet.sh

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+# graph-snippet.sh — verified source + caller/callee counts for a symbol.
+#
+# Wraps the engine's get_code_snippet (graph-tooling-v2 Phase 3). Replaces the
+# grep-then-Read dance with the engine's own attributed source plus its
+# pre-computed caller/callee counts and loop-depth risk signal.
+#
+# Usage:
+#   scripts/tools/graph-snippet.sh --repo DIR --qualified NAME
+#
+# NAME is a fully qualified_name (e.g. pkg.module.Class.method). Use
+# graph-search.sh or `graph-arch.sh | jq` to discover qualified names.
+#
+# Output: JSON {qualified_name, file, start_line, end_line, callers, callees,
+#               transitive_loop_depth, complexity, code, status, source}.
+#   status = "ok" | "no-match" | "unavailable"
+#
+# 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="."
+QNAME=""
+
+usage() {
+    cat <<'EOF'
+graph-snippet.sh — verified source + caller/callee counts for a symbol.
+
+Usage:
+  scripts/tools/graph-snippet.sh --repo DIR --qualified NAME
+
+Flags:
+  --repo DIR       Repository root (default: cwd).
+  --qualified NAME Fully qualified symbol name (required).
+  --help           Show this help.
+
+Output: JSON {qualified_name, file, start_line, end_line, callers, callees,
+transitive_loop_depth, complexity, code, status, source}. Exit 2 when engine
+unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --qualified|--symbol) QNAME="$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; }
+[[ -n "$QNAME" ]] || { echo "ERROR: --qualified is required" >&2; usage >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() {
+    jq -n --arg q "$QNAME" '{qualified_name:$q, status:"unavailable", source:"unavailable"}' 2>/dev/null \
+        || echo '{"status":"unavailable","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
+
+ARGS="$(jq -n --arg p "$PROJECT" --arg q "$QNAME" '{project:$p, qualified_name:$q}')"
+RES="$(memory_cli get_code_snippet "$ARGS" 2>/dev/null || true)"
+[[ -n "$RES" ]] || unavailable
+echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable
+
+# The engine field `source` carries the code text; rename to `code` to avoid
+# colliding with our provenance `source`. no-match when the engine returns an
+# object without a qualified_name/source for the requested symbol.
+echo "$RES" | jq --arg q "$QNAME" '
+    (.qualified_name // .name // null) as $found
+    | {qualified_name: ($found // $q),
+       file: (.file_path // ""),
+       start_line: (.start_line // null),
+       end_line: (.end_line // null),
+       callers: (.callers // null),
+       callees: (.callees // null),
+       transitive_loop_depth: (.transitive_loop_depth // null),
+       complexity: (.complexity // null),
+       code: (.source // ""),
+       status: (if ($found != null or (.source // "") != "") then "ok" else "no-match" end),
+       source: "memory-graph"}'

package/scripts/tools/graph-tests.sh

@@ -0,0 +1,112 @@
+#!/usr/bin/env bash
+# graph-tests.sh — test→symbol coverage from the knowledge graph (TESTS edges).
+#
+# graph-tooling-v2 Phase 3. Two modes:
+#   --symbol NAME  tests that cover a symbol (who tests this?).
+#   --untested     exported symbols with NO TESTS edge (what's untested?).
+#
+# The engine dialect has no anti-join (NOT EXISTS / NOT(pattern) are rejected), so
+# --untested is computed as a set difference in jq: exported symbols minus the
+# set of TESTS targets. Honest about partiality — TESTS coverage depends on the
+# engine resolving test→symbol links, which varies by language/framework.
+#
+# Usage:
+#   scripts/tools/graph-tests.sh --repo DIR --symbol NAME
+#   scripts/tools/graph-tests.sh --repo DIR --untested
+#
+# Output (--symbol):   {symbol, tests:[{test,file}], status, source}
+# Output (--untested): {untested:[{symbol,file}], total, truncated, source}
+#
+# 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="."
+SYMBOL=""
+UNTESTED=0
+
+usage() {
+    cat <<'EOF'
+graph-tests.sh — test coverage edges from the knowledge graph.
+
+Usage:
+  scripts/tools/graph-tests.sh --repo DIR --symbol NAME
+  scripts/tools/graph-tests.sh --repo DIR --untested
+
+Flags:
+  --repo DIR     Repository root (default: cwd).
+  --symbol NAME  List tests covering this symbol.
+  --untested     List exported symbols with no TESTS edge.
+  --help         Show this help.
+
+Output: --symbol → {symbol, tests, status, source}; --untested →
+{untested, total, truncated, source}. Exit 2 when engine unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --repo) REPO="$2"; shift 2;;
+        --symbol) SYMBOL="$2"; shift 2;;
+        --untested) UNTESTED=1; shift;;
+        --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; }
+[[ -n "$SYMBOL" || "$UNTESTED" -eq 1 ]] || { echo "ERROR: provide --symbol or --untested" >&2; usage >&2; exit 1; }
+
+REPO_ABS="$(cd "$REPO" && pwd)"
+SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
+
+unavailable() {
+    if [[ "$UNTESTED" -eq 1 ]]; then
+        echo '{"untested":[],"total":0,"source":"unavailable"}'
+    else
+        jq -n --arg s "$SYMBOL" '{symbol:$s, tests:[], status:"unavailable", source:"unavailable"}' 2>/dev/null \
+            || echo '{"tests":[],"status":"unavailable","source":"unavailable"}'
+    fi
+    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
+
+if [[ "$UNTESTED" -eq 1 ]]; then
+    EXP="$(gq_run "$PROJECT" "$(gq_q_exported)" || true)"
+    [[ -n "$EXP" ]] || unavailable
+    TST="$(gq_run "$PROJECT" "$(gq_q_tested_all)" || echo '{"rows":[]}')"
+    echo "$TST" | jq -e . >/dev/null 2>&1 || TST='{"rows":[]}'
+    # Pass results via temp files, not argv: the exported set can exceed the
+    # ARG_MAX limit for --argjson on large repos.
+    TMP_EXP="$(mktemp)"; TMP_TST="$(mktemp)"
+    trap 'rm -f "$TMP_EXP" "$TMP_TST"' EXIT
+    printf '%s' "$EXP" > "$TMP_EXP"
+    printf '%s' "$TST" > "$TMP_TST"
+    jq -n --slurpfile exp "$TMP_EXP" --slurpfile tst "$TMP_TST" '
+        ($exp[0] // {}) as $e | ($tst[0] // {}) as $t
+        | ((($t.rows) // []) | map(.[0])) as $tested
+        | [ (($e.rows) // [])[]
+            | select(((.[0]) as $q | $tested | index($q)) | not)
+            | {symbol:.[0], file:.[1]} ] as $u
+        | {untested: $u, total: ($u | length),
+           truncated: (((($e.rows) // []) | length) >= 2000),
+           source:"memory-graph"}'
+    exit 0
+fi
+
+SYM_ESC="$(gq_escape "$SYMBOL")"
+RES="$(gq_run "$PROJECT" "$(gq_q_tests "$SYM_ESC")" || true)"
+[[ -n "$RES" ]] || unavailable
+STATUS="$(gq_symbol_status "$PROJECT" "$SYM_ESC" "$RES")"
+
+echo "$RES" | jq --arg s "$SYMBOL" --arg st "$STATUS" '
+    {symbol:$s,
+     tests: [ (.rows // [])[] | {test:.[0], file:.[1]} ],
+     status:$st, source:"memory-graph"}'

package/scripts/tools/graph-traces.sh

@@ -0,0 +1,83 @@
+#!/usr/bin/env bash
+# graph-traces.sh — fold runtime call traces into the knowledge graph (EXPERIMENTAL).
+#
+# graph-tooling-v2 Phase 6. Wraps the engine's ingest_traces to close the
+# static/dynamic gap — dynamic dispatch the static graph misses (e.g. closures,
+# reflection, virtual calls). This is a WRITE path and is gated behind
+# --experimental. NOTE: in engine v0.8.x ingest_traces is accepted but runtime
+# edge creation is "not yet implemented" — the engine returns its status verbatim.
+#
+# Usage:
+#   scripts/tools/graph-traces.sh ingest --repo DIR --file TRACES.json --experimental
+#
+# TRACES.json is a JSON array of trace records (engine-defined shape).
+#
+# Output: the engine's raw ingest_traces JSON; {"source":"unavailable"} (exit 2)
+# when the engine is unavailable; exit 1 on invocation error or missing
+# --experimental.
+set -euo pipefail
+
+# shellcheck source=_graph_queries.sh
+source "$(dirname "${BASH_SOURCE[0]}")/_graph_queries.sh"
+
+REPO="."
+FILE=""
+ACTION=""
+EXPERIMENTAL=0
+
+usage() {
+    cat <<'EOF'
+graph-traces.sh — fold runtime traces into the graph (EXPERIMENTAL, write path).
+
+Usage:
+  scripts/tools/graph-traces.sh ingest --repo DIR --file TRACES.json --experimental
+
+Flags:
+  ingest          The action (currently the only one).
+  --repo DIR      Repository root (default: cwd).
+  --file PATH     JSON array of trace records (required for ingest).
+  --experimental  Required acknowledgement — this is a write/experimental path.
+  --help          Show this help.
+
+NOTE: engine v0.8.x accepts traces but runtime edge creation is not yet
+implemented; the engine's status is returned verbatim.
+
+Output: raw engine JSON; {"source":"unavailable"} (exit 2) when unavailable.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        ingest) ACTION="ingest"; shift;;
+        --repo) REPO="$2"; shift 2;;
+        --file) FILE="$2"; shift 2;;
+        --experimental) EXPERIMENTAL=1; shift;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown argument: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ "$ACTION" == "ingest" ]] || { echo "ERROR: action 'ingest' is required" >&2; usage >&2; exit 1; }
+[[ "$EXPERIMENTAL" -eq 1 ]] || { echo "ERROR: --experimental is required (this writes to the graph)" >&2; exit 1; }
+[[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
+[[ -n "$FILE" ]] || { echo "ERROR: --file is required" >&2; usage >&2; exit 1; }
+[[ -f "$FILE" ]] || { echo "ERROR: --file '$FILE' does not exist" >&2; exit 1; }
+
+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
+
+jq -e . "$FILE" >/dev/null 2>&1 || { echo "ERROR: --file is not valid JSON" >&2; exit 1; }
+
+PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+[[ -n "$PROJECT" ]] || unavailable
+
+ARGS="$(jq -n --arg p "$PROJECT" --slurpfile t "$FILE" '{project:$p, traces:($t[0])}')"
+RES="$(memory_cli ingest_traces "$ARGS" 2>/dev/null || true)"
+[[ -n "$RES" ]] || unavailable
+echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable
+printf '%s\n' "$RES"

package/scripts/tools/hotspot-rank.sh

@@ -1,27 +1,33 @@
 #!/usr/bin/env bash
-# hotspot-rank.sh — emit complexity/fan-in-ranked symbols from the knowledge graph.
+# hotspot-rank.sh — complexity-weighted hotspot ranking from the knowledge graph.
 #
-# Backed by the codebase-memory-mcp engine (get_architecture, server-computed
-# hotspot ranking by fan-in). Indexes the repo on demand if needed.
+# Backed by the codebase-memory-mcp engine. Fan-in alone is skewed by
+# name-collision generics (e.g. a logger `info` with fan_in 1022 but complexity 0),
+# so graph-tooling-v2 Phase 4 blends the engine's pre-computed complexity and
+# cognitive scores into the rank: score = fanIn + complexity + cognitive. Entry
+# points are annotated. fan_in still comes from the engine's server-computed
+# hotspot ranking; the per-symbol complexity/cognitive/is_entry_point come from a
+# node-property query and are merged in.
 #
 # Usage:
 #   scripts/tools/hotspot-rank.sh [--repo DIR] [--top N]
 #
-# Output: JSON {hotspots:[{id, name, fanIn}], source}.
+# Output: JSON {hotspots:[{id, name, fanIn, complexity, cognitive, score,
+#               isEntryPoint}], source}.
 #   source = "memory-graph" | "unavailable"
 #
 # 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="."
 TOP=0
 
 usage() {
     cat <<'EOF'
-hotspot-rank.sh — fan-in-ranked symbols from the knowledge graph.
+hotspot-rank.sh — complexity-weighted hotspot ranking from the knowledge graph.
 
 Usage:
   scripts/tools/hotspot-rank.sh [--repo DIR] [--top N]
@@ -31,8 +37,8 @@ Flags:
   --top N     Keep only top N hotspots (default: 0 = all).
   --help      Show this help.
 
-Output: JSON {hotspots:[{id, name, fanIn}], source}.
-  source = "memory-graph" | "unavailable"
+Output: JSON {hotspots:[{id, name, fanIn, complexity, cognitive, score,
+isEntryPoint}], source}. Ranked by score = fanIn + complexity + cognitive.
 
 Exit 0 with results, exit 2 with {"hotspots":[],"source":"unavailable"} when the
 graph engine is unavailable.
@@ -48,6 +54,8 @@ while [[ $# -gt 0 ]]; do
     esac
 done
 
+[[ "$TOP" =~ ^[0-9]+$ ]] || { echo "ERROR: --top must be a non-negative integer" >&2; exit 1; }
+
 if [[ ! -d "$REPO" ]]; then
     echo "ERROR: --repo '$REPO' is not a directory" >&2
     exit 1
@@ -66,10 +74,31 @@ PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
 
 ARCH_JSON="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"hotspots\"]}" || true)"
 [[ -n "$ARCH_JSON" ]] || unavailable
+echo "$ARCH_JSON" | jq -e . >/dev/null 2>&1 || unavailable
+
+# Pre-computed complexity/cognitive/is_entry_point per symbol (merged onto fan-in).
+PROPS_JSON="$(gq_run "$PROJECT" "$(gq_q_node_props)" || echo '{"rows":[]}')"
+echo "$PROPS_JSON" | jq -e . >/dev/null 2>&1 || PROPS_JSON='{"rows":[]}'
+
+# Merge via temp files (the props row set can exceed argv limits on large repos).
+TMP_ARCH="$(mktemp)"; TMP_PROPS="$(mktemp)"
+trap 'rm -f "$TMP_ARCH" "$TMP_PROPS"' EXIT
+printf '%s' "$ARCH_JSON" > "$TMP_ARCH"
+printf '%s' "$PROPS_JSON" > "$TMP_PROPS"
 
-echo "$ARCH_JSON" | jq --argjson top "$TOP" '
-    {
-      hotspots: ([ (.hotspots // [])[] | {id: .qualified_name, name: .name, fanIn: .fan_in} ]
-                 | if $top > 0 then .[0:$top] else . end),
-      source: "memory-graph"
-    }'
+jq -n --slurpfile arch "$TMP_ARCH" --slurpfile props "$TMP_PROPS" --argjson top "$TOP" '
+    (($props[0].rows) // []) as $prows
+    | (reduce $prows[] as $r ({};
+          .[$r[0]] = {c:((($r[1]) // "0") | tonumber? // 0),
+                      cog:((($r[2]) // "0") | tonumber? // 0),
+                      ep:((($r[3]) | tostring) == "true")})) as $pmap
+    | [ (($arch[0].hotspots) // [])[]
+        | (.qualified_name) as $q
+        | ($pmap[$q] // {c:0, cog:0, ep:false}) as $p
+        | {id:$q, name:.name, fanIn:(.fan_in // 0),
+           complexity:$p.c, cognitive:$p.cog,
+           score:((.fan_in // 0) + $p.c + $p.cog),
+           isEntryPoint:$p.ep} ]
+    | sort_by(-.score)
+    | (if $top > 0 then .[0:$top] else . end) as $h
+    | {hotspots:$h, source:"memory-graph"}'

package/scripts/tools/manage-symlinks.sh

@@ -74,7 +74,7 @@ while IFS= read -r -d '' f; do
     # File-only (not symlink we already manage)
     if [[ -L "$f" ]]; then continue; fi
     newest="$base"
-done < <(find "$DIR" -maxdepth 1 -name "$pattern" -print0 | sort -z)
+done < <(find "$DIR" -maxdepth 1 -name "$pattern" | sort | tr '\n' '\0')
 
 if [[ -z "$newest" ]]; then
     echo "No matching $pattern files in $DIR" >&2

package/scripts/tools/mermaid-from-graph.sh

@@ -1,21 +1,27 @@
 #!/usr/bin/env bash
 # mermaid-from-graph.sh — emit Mermaid diagrams from the knowledge graph.
 #
-# Backed by the codebase-memory-mcp engine. Two diagrams:
-#   module-deps : file co-change coupling (FILE_CHANGES_WITH edges) as a flowchart.
+# Backed by the codebase-memory-mcp engine. Diagrams:
+#   module-deps : real file/module dependency graph (IMPORTS edges) as a flowchart.
+#                 This is the auto-derived dependency diagram for architecture.md
+#                 §9 (graph-tooling-v2 Phase 4) — it replaces the prior co-change
+#                 proxy with actual import edges.
+#   co-change   : file co-change coupling (FILE_CHANGES_WITH edges) — the hidden,
+#                 git-history dependency proxy (the prior module-deps behavior,
+#                 still available explicitly).
 #   proto-map   : detected service routes (Route nodes) as a flowchart.
 #
 # When the engine is unavailable, emits an empty diagram stub and exits 2 so
 # consuming skills can degrade gracefully.
 #
 # Usage:
-#   scripts/tools/mermaid-from-graph.sh [--repo DIR] [--diagram module-deps|proto-map]
+#   scripts/tools/mermaid-from-graph.sh [--repo DIR] [--diagram module-deps|co-change|proto-map]
 #
 # 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="."
 DIAGRAM="module-deps"
@@ -25,11 +31,12 @@ usage() {
 mermaid-from-graph.sh — emit Mermaid diagrams from the knowledge graph.
 
 Usage:
-  scripts/tools/mermaid-from-graph.sh [--repo DIR] [--diagram module-deps|proto-map]
+  scripts/tools/mermaid-from-graph.sh [--repo DIR] [--diagram module-deps|co-change|proto-map]
 
 Flags:
   --repo DIR      Repository root (default: cwd).
-  --diagram NAME  module-deps (default) or proto-map.
+  --diagram NAME  module-deps (default, IMPORTS edges), co-change
+                  (FILE_CHANGES_WITH coupling), or proto-map (routes).
   --help          Show this help.
 
 Exit 0 with diagram output, exit 2 with an empty stub when the engine is unavailable.
@@ -70,9 +77,22 @@ command -v jq >/dev/null 2>&1 || stub
 PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
 [[ -n "$PROJECT" ]] || stub
 
+# module-deps: real IMPORTS edges (the auto-derived dependency graph). Self-imports
+# (src == dst) are dropped so the diagram is a true cross-file graph. Capped at 40
+# edges for readability.
 render_module_deps() {
-    local q="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"
-    local res; res="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$q\"}" || echo '{}')"
+    local res; res="$(gq_run "$PROJECT" "$(gq_q_imports)" || echo '{}')"
+    local edges; edges="$(echo "${res:-{\}}" | jq -r '
+        [ (.rows // [])[] | {s:(.[0]|tostring), d:(.[1]|tostring)}
+          | select(.s != "" and .d != "" and .s != .d) ]
+        | unique | .[0:40][] | "    \"" + .s + "\" --> \"" + .d + "\""' 2>/dev/null || true)"
+    if [[ -z "$edges" ]]; then return 1; fi
+    printf '```mermaid\nflowchart LR\n%s\n```\n' "$edges"
+}
+
+# co-change: FILE_CHANGES_WITH coupling (the prior module-deps proxy).
+render_co_change() {
+    local res; res="$(gq_run "$PROJECT" "$(gq_q_co_change)" || echo '{}')"
     local edges; edges="$(echo "${res:-{\}}" | jq -r '(.rows // [])[] | "    \"" + (.[0]|tostring) + "\" --> \"" + (.[1]|tostring) + "\""' 2>/dev/null || true)"
     if [[ -z "$edges" ]]; then return 1; fi
     printf '```mermaid\nflowchart LR\n%s\n```\n' "$edges"
@@ -87,6 +107,7 @@ render_proto_map() {
 
 case "$DIAGRAM" in
     module-deps) render_module_deps || stub ;;
+    co-change)   render_co_change || stub ;;
     proto-map)   render_proto_map || stub ;;
-    *) echo "Unknown --diagram '$DIAGRAM' (expected module-deps|proto-map)" >&2; exit 1 ;;
+    *) echo "Unknown --diagram '$DIAGRAM' (expected module-deps|co-change|proto-map)" >&2; exit 1 ;;
 esac

package/scripts/tools/parse-reports.sh

@@ -105,7 +105,7 @@ while IFS= read -r -d '' file; do
         "$([[ -n "$track_id" ]] && echo "\"$(json_escape "$track_id")\"" || echo "null")" \
         "$(json_escape "$generated_at")" \
         "${crit:-0}" "${high:-0}" "${med:-0}" "${low:-0}" "${info:-0}"
-done < <(find "$ROOT" -type f -name '*-report-*.md' -print0 2>/dev/null | sort -z)
+done < <(find "$ROOT" -type f -name '*-report-*.md' 2>/dev/null | sort | tr '\n' '\0')
 
 if $first; then
     printf ']\n'