@drafthq/draft 3.0.0 → 3.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "3.0.0",
+  "version": "3.1.5",
   "description": "Context-Driven Development for AI coding agents — install Draft into Claude Code, Cursor, Codex, or opencode.",
   "bin": {
     "draft": "cli/bin/draft.js"

package/scripts/lib.sh

@@ -158,11 +158,9 @@ 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"
     "validate-frontmatter.sh"
     # Foundations hygiene/verification tools
     "check-graph-usage-report.sh"

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

@@ -68,7 +68,11 @@ Q3="MATCH (a:Function)-[:CALLS]->(b:Function)-[:CALLS]->(c:Function)-[:CALLS]->(
 R2="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$Q2\"}" || echo '{}')"
 R3="$(memory_cli query_graph "{\"project\":\"$PROJECT\",\"query\":\"$Q3\"}" || echo '{}')"
 
-jq -n --argjson r2 "${R2:-{\}}" --argjson r3 "${R3:-{\}}" '
+# 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"

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-impact.sh

@@ -54,6 +54,7 @@ done
 
 [[ -d "$REPO" ]] || { echo "ERROR: --repo '$REPO' is not a directory" >&2; exit 1; }
 [[ -n "$FILE" || -n "$SYMBOL" ]] || { echo "ERROR: provide --file or --symbol" >&2; usage >&2; exit 1; }
+[[ "$DEPTH" =~ ^[0-9]+$ ]] || { echo "ERROR: --depth must be a non-negative integer" >&2; exit 1; }
 
 REPO_ABS="$(cd "$REPO" && pwd)"
 SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"

package/scripts/tools/graph-init.sh

@@ -104,8 +104,8 @@ engine_unavailable() {
     exit 2
 }
 
-# Build a committed snapshot for a repo dir; returns graph-snapshot's exit code.
-# Snapshot progress goes to stderr so stdout stays clean for --json consumers.
+# Index a repo dir and write its schema.yaml gate marker; returns graph-snapshot's exit code.
+# Progress goes to stderr so stdout stays clean for --json consumers.
 build_snapshot() {
     local rc=0
     "$TOOLS_DIR/graph-snapshot.sh" --repo "$1" 1>&2 || rc=$?
@@ -134,7 +134,7 @@ write_root_link() {
         [[ -n "$root_project" ]] || root_project="unknown"
     fi
     root_commit="$(git -C "$ROOT_ABS" rev-parse --verify --quiet HEAD 2>/dev/null || echo none)"
-    ts="$(date -Iseconds 2>/dev/null || date)"
+    ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
     cat > "$mod_graph/root-link.json" <<EOF
 {
   "root_graph": "$rel",

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,44 @@ 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
-
-# 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
-
-# 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 ' ')"
+# 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)"
 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
+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)"
 exit 0

package/scripts/tools/hotspot-rank.sh

@@ -48,6 +48,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

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/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'

package/scripts/tools/verify-doc-anchors.sh

@@ -177,7 +177,7 @@ emit() {
     if ((EMIT_JSON)); then
         printf '{"violation_count": %d, "violations": [\n' "$violation_count"
         local first=1 v track kind file line detail
-        for v in "${violations[@]}"; do
+        for v in ${violations[@]+"${violations[@]}"}; do
             IFS='|' read -r track kind file line detail <<< "$v"
             if ((first)); then first=0; else printf ',\n'; fi
             printf ' {"track":"%s","kind":"%s","file":"%s","line":%s,"detail":"%s"}' \
@@ -192,7 +192,7 @@ emit() {
             printf 'ANCHORS: %d violation(s) across %d track(s).\n' \
                 "$violation_count" "${#TRACK_PATHS[@]}" >&2
             local v track kind file line detail
-            for v in "${violations[@]}"; do
+            for v in ${violations[@]+"${violations[@]}"}; do
                 IFS='|' read -r track kind file line detail <<< "$v"
                 printf ' [%s] %s/%s:%s — %s\n' "$kind" "$track" "$file" "$line" "$detail" >&2
             done

package/scripts/tools/verify-graph-binary.sh

@@ -141,7 +141,7 @@ if [[ -d "$REPO/draft" ]]; then
   mkdir -p "$REPO/draft"
   cat > "$REPO/draft/.graph-binary-report.json" <<EOF
 {
-  "detected_at": "$(date -Iseconds 2>/dev/null || date)",
+  "detected_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
   "engine_bin": "$(json_escape "$MEMORY_BIN")",
   "source": "$(json_escape "$SOURCE")",
   "arch": "$(json_escape "$ARCH")",

package/skills/GRAPH.md

@@ -301,8 +301,8 @@ init → learn → (updates guardrails.md)
   init ──────────►  │  architecture.md ──► .ai-context.md         │
                     │  product.md  tech-stack.md  guardrails.md   │
                     │  workflow.md  tracks.md  tech-debt.md       │
-                    │  graph/ (module-graph, hotspots, proto,      │
-                    │         module-deps.mermaid, proto-map..)   │
+                    │  graph/ (schema.yaml gate; all data queried  │
+                    │         live via codebase-memory-mcp engine) │
                     └──────────────────┬──────────────────────────┘
                                        │ read by all skills
            ┌───────────────────────────┼───────────────────────┐

package/skills/bughunt/SKILL.md

@@ -68,7 +68,7 @@ Read and follow the base procedure in `core/shared/draft-context-loading.md`.
 - **Leverage Storage Topology** — Identify data loss risks at each tier (cache eviction without writeback, event log gaps, missing archive)
 - **Leverage Consistency Boundaries** — Find bugs at eventual consistency seams (stale reads, lost events, missing reconciliation)
 - **Leverage Failure Recovery Matrix** — Verify idempotency claims, check for partial failure states without recovery paths
-- **Leverage Graph Data** (if `draft/graph/` exists) — Read `architecture.json` (`.packages`) for dependency awareness. Flag dependencies on unexpected modules. Flag code in modules involved in dependency cycles as higher risk. Use `hotspots.jsonl` to prioritize analysis of high-complexity, high-fanIn files. See `core/shared/graph-query.md`.
+- **Leverage Graph Data** (if `draft/graph/` exists) — Query `scripts/tools/graph-arch.sh --repo .` for dependency awareness. Flag dependencies on unexpected modules. Flag code in modules involved in dependency cycles as higher risk. Run `scripts/tools/hotspot-rank.sh --repo .` to prioritize analysis of high-complexity, high-fanIn files. See `core/shared/graph-query.md`.
 - **Leverage Learned Anti-Patterns** — If `draft/guardrails.md` exists, read the `## Learned Anti-Patterns` section. During the bug sweep, when a bug matches a learned anti-pattern, prefix the report entry with `[KNOWN-ANTI-PATTERN: {pattern name}]`. This distinguishes recurring documented patterns from newly discovered bugs, and signals that a systemic fix may be needed rather than a one-off patch.
 
 ### 2. Confirm Scope

package/skills/debug/SKILL.md

@@ -11,10 +11,10 @@ You are conducting a structured debugging session following systematic investiga
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. During Steps 3–4 (Isolate, Diagnose):
 
-1. Locate the suspect file's module via `draft/graph/architecture.json` (`.packages`) before tracing data flow.
+1. Locate the suspect file's module via `scripts/tools/graph-arch.sh --repo .` before tracing data flow.
 2. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to enumerate call sites of suspect functions — not `grep`.
 3. Use `scripts/tools/graph-impact.sh --repo . --file <path>` to size the blast radius before proposing a fix.
-4. Cross-check `draft/graph/hotspots.jsonl` to know whether the file is high-fanIn (any fix needs extra caution).
+4. Run `scripts/tools/hotspot-rank.sh --repo .` to know whether the file is high-fanIn (any fix needs extra caution).
 
 Filesystem `grep` is reserved for source-text scans (literal error strings, stack-trace symbols when the graph misses). Use the fallback sentence on graph miss.
 
@@ -62,7 +62,7 @@ Key context for debugging:
 - `.ai-context.md` — Module boundaries, data flows, invariants (crucial for tracing)
 - `tech-stack.md` — Language-specific debugging tools and techniques
 - `guardrails.md` — Known anti-patterns that may be causing the issue
-- `draft/graph/` (MANDATORY when present) — Load `architecture.json` for dependency/module context and `hotspots.jsonl` for complexity awareness. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to find all callers, and `scripts/tools/graph-impact.sh --repo . --file <path>` to size blast radius before any fix. See [core/shared/graph-query.md](../../core/shared/graph-query.md).
+- `draft/graph/` (MANDATORY when present) — Query `scripts/tools/graph-arch.sh --repo .` for dependency/module context and `scripts/tools/hotspot-rank.sh --repo .` for complexity awareness. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to find all callers, and `scripts/tools/graph-impact.sh --repo . --file <path>` to size blast radius before any fix. See [core/shared/graph-query.md](../../core/shared/graph-query.md).
 
 ## Step 1: Parse Arguments
 

package/skills/decompose/SKILL.md

@@ -11,8 +11,8 @@ You are decomposing a project or track into modules with clear responsibilities,
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Module identification (Step 3) and dependency mapping (Step 4) **start from the graph**:
 
-1. Load `draft/graph/architecture.json` (`.packages`) for the authoritative module list and fan-in/out.
-2. Load `draft/graph/hotspots.jsonl` to identify candidate modules to split.
+1. Query `scripts/tools/graph-arch.sh --repo .` for the authoritative module list and fan-in/out.
+2. Run `scripts/tools/hotspot-rank.sh --repo .` to identify candidate modules to split.
 3. Use `scripts/tools/graph-callers.sh`/`graph-impact.sh` on demand for symbols/callers inside a candidate module.
 4. Run `scripts/tools/cycle-detect.sh --repo .` to enumerate existing cycles before proposing new boundaries.
 
@@ -156,10 +156,10 @@ ls -d src/*/ lib/*/ app/*/ packages/*/ 2>/dev/null
 
 When graph data is available, the graph is the **primary** (not optional) source for module discovery — manual scanning above is reserved for the graph-miss fallback path:
 
-- **Module boundaries**: Read `draft/graph/architecture.json` (`.packages`, `.languages`) — module list with node counts and per-language file counts
+- **Module boundaries**: Query `scripts/tools/graph-arch.sh --repo .` — module list with node counts and per-language file counts
 - **Dependency edges**: Weighted inter-module dependencies with exact include counts — replaces manual import tracing
 - **Cycle detection**: Circular dependency paths already computed — use for identifying tight coupling and decomposition candidates
-- **Hotspots**: Load `draft/graph/hotspots.jsonl` — high-complexity files that may need further decomposition
+- **Hotspots**: Run `scripts/tools/hotspot-rank.sh --repo .` — high-complexity files that may need further decomposition
 - **Per-module detail**: query `scripts/tools/graph-callers.sh`/`graph-impact.sh` for symbol/call detail within modules of interest
 
 This data is deterministic and exhaustive. The manual scanning recipes above only run **after** the graph misses on the concept the user named — and the miss must be reported in the Graph Usage Report footer. See [core/shared/graph-query.md](../../core/shared/graph-query.md) §Concept-to-Files Recipe.
@@ -615,7 +615,7 @@ When decomposition involves breaking a monolith, choosing module boundaries, or
 
 Before printing the completion announcement, internally verify and report:
 
-1. **Graph files queried** — which JSONL files were loaded (e.g. `architecture.json, hotspots.jsonl` and tools like `cycle-detect.sh`).
+1. **Graph data queried** — which live-engine tools were invoked (e.g. `get_architecture`, `hotspot-rank.sh`, `cycle-detect.sh`).
 2. **Layer 1 files deliberately skipped** — list any `.ai-context.md` sections, `tech-stack.md`, `product.md`, `workflow.md` you skipped as irrelevant to this decomposition. Be explicit; do not silently skip.
 3. **Filesystem grep fallback justification** — for every `grep`/`find` run, state the concept it searched for and quote the graph-miss sentence.
 4. **Citation Gate audit** — scan every Citation column in the generated component table, dependencies table, and LLD class table. Report:

package/skills/deep-review/SKILL.md

@@ -11,10 +11,10 @@ Perform an exhaustive end-to-end lifecycle review of a service, component, or mo
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Deep-review uses the graph to **narrow review scope** — a key 30–50% scope reduction:
 
-1. Use `scripts/tools/graph-impact.sh`/`graph-callers.sh` and `architecture.json` for the audited module's structure — do not enumerate via `find`.
+1. Use `scripts/tools/graph-impact.sh`/`graph-callers.sh` and `scripts/tools/graph-arch.sh --repo .` for the audited module's structure — do not enumerate via `find`.
 2. Run `scripts/tools/graph-impact.sh --repo . --file <each-changed-file>` per file in the diff (or per file in the module if no diff) to obtain the affected module set deterministically.
 3. Run `scripts/tools/cycle-detect.sh --repo .` and flag any cycle that includes the audited module as Architecture Resilience finding.
-4. Cross-check `draft/graph/hotspots.jsonl` to identify high-fanIn files inside the module — these get deeper inspection.
+4. Run `scripts/tools/hotspot-rank.sh --repo .` to identify high-fanIn files inside the module — these get deeper inspection.
 
 Filesystem `grep` is reserved for source-text scans (API contract strings, secret patterns, log message audits). Module enumeration and caller tracing go through the graph.
 

package/skills/deploy-checklist/SKILL.md

@@ -12,8 +12,8 @@ You are generating a pre-deployment verification checklist customized to this pr
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Use the graph to validate module boundaries before the deploy:
 
 1. For each file in the deploy diff, run `scripts/tools/graph-impact.sh --repo . --file <path>` to enumerate the modules affected — flag any module **not** declared in `hld.md` §Detailed Design as a deployment-scope miss.
-2. Run `scripts/tools/cycle-detect.sh --repo .` (and read `draft/graph/architecture.json` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off.
-3. Load `draft/graph/hotspots.jsonl` — any hotspot in the diff escalates the Resiliency row of Phase 0.
+2. Run `scripts/tools/cycle-detect.sh --repo .` (and query `scripts/tools/graph-arch.sh --repo .` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off.
+3. Run `scripts/tools/hotspot-rank.sh --repo .` — any hotspot in the diff escalates the Resiliency row of Phase 0.
 
 Filesystem `grep` is reserved for source-text scans (migration file names, flag-key strings). Module/impact discovery goes through the graph.
 

package/skills/graph/SKILL.md

@@ -55,7 +55,7 @@ echo "Engine: $ENGINE"
 
 ## Step 3: Build / refresh the snapshot
 
-One call resolves the engine, indexes the repo (incrementally on refresh), and writes the committed snapshot under `<repo>/draft/graph/` — `schema.yaml`, `architecture.json`, `hotspots.jsonl`, `module-deps.mermaid`, `proto-map.mermaid`, and an Open Knowledge Format bundle under `okf/` (a portable, vendor-neutral markdown mirror of the graph — `index.md` + one cross-linked `modules/<name>.md` concept per module).
+One call resolves the engine, indexes the repo (incrementally on refresh), and updates the gate marker `<repo>/draft/graph/schema.yaml` (engine metadata + point-of-index counts; `access: engine-live`). All structural graph data is queried live from the engine — no snapshot files are committed beyond `schema.yaml`.
 
 ```bash
 scripts/tools/graph-snapshot.sh --repo "$REPO_ABS"

package/skills/implement/SKILL.md

@@ -133,7 +133,7 @@ If one of these applies, route directly to the specialist workflow and stop this
    - Keep matching invariants as **active constraints** for this task — these govern code generation, not just review
    - If invariants reference lock ordering, fail-closed behavior, or data integrity rules: these are non-negotiable during implementation
 9. **Load graph context** (if `draft/graph/schema.yaml` exists):
-   - Read `draft/graph/hotspots.jsonl` — check if any files this task will modify appear as hotspots
+   - Run `scripts/tools/hotspot-rank.sh --repo .` — check if any files this task will modify appear as hotspots
    - If modifying a hotspot file (high fanIn), warn: "This task modifies {file} (fanIn={N}). Changes here affect many downstream files. Consider running a graph impact query."
    - Query `scripts/tools/graph-impact.sh`/`graph-callers.sh` for the module(s) being modified — gives file-level dependency context
    - See `core/shared/graph-query.md` for on-demand query subroutines (callers, impact)