@drafthq/draft 2.8.3 → 3.1.5

package/package.json

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

@@ -24,7 +24,6 @@ TOOLS_DIR="$ROOT_DIR/scripts/tools"
 SKILL_ORDER=(
     draft
     init
-    index
     graph
     new-track
     decompose
@@ -158,8 +157,10 @@ TOOLS=(
     "manage-symlinks.sh"
     "mermaid-from-graph.sh"
     "graph-snapshot.sh"
+    "graph-init.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

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+# graph-init.sh — scope-aware, root-first knowledge-graph builder for /draft:init.
+#
+# Ensures the whole-repo "code graph knowledge memory" exists at the repository
+# ROOT (the spine — the single structural source of truth), then builds a
+# scope-local snapshot and links a sub-module's graph up to the root.
+#
+# Model:
+#   - ROOT resolution: nearest ancestor ABOVE scope containing draft/ (bounded by
+#     the git toplevel)  →  git toplevel  →  scope itself (no git / module-local).
+#   - The engine is the default capability tier. If the codebase-memory-mcp binary
+#     is missing it is fetched (blocking) unless --no-fetch or DRAFT_MEMORY_DISABLE.
+#   - Root init (scope == root): build the whole-repo snapshot at <root>/draft/graph/.
+#   - Module init (scope != root): unless --module-only, (re)build the root snapshot
+#     first (the spine — index time is accepted, incremental once warm), then build
+#     <scope>/draft/graph/ and write root-link.json pointing up to the root snapshot.
+#
+# The committed snapshot (draft/graph/) is the git-tracked memory; the engine's
+# ~/.cache index is a disposable accelerator and is never committed.
+#
+# Usage: scripts/tools/graph-init.sh [--scope DIR] [--module-only] [--no-fetch] [--json]
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=_lib.sh
+source "$TOOLS_DIR/_lib.sh"
+
+SCOPE="."
+MODULE_ONLY=0
+NO_FETCH=0
+EMIT_JSON=0
+
+usage() {
+    cat <<'EOF'
+graph-init.sh — scope-aware, root-first knowledge-graph builder.
+
+Usage:
+  scripts/tools/graph-init.sh [--scope DIR] [--module-only] [--no-fetch] [--json]
+
+Flags:
+  --scope DIR    Directory init was invoked in (default: cwd).
+  --module-only  Do not touch the root; build only the module snapshot and mark
+                 its root link "pending".
+  --no-fetch     Never download the engine; degrade if it is absent (CI/tests).
+  --json         Emit a machine-readable summary instead of a human report.
+  --help         Show this help.
+
+Exit 0 on success, 2 when the graph engine is unavailable (no snapshot built).
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --scope) SCOPE="$2"; shift 2;;
+        --module-only) MODULE_ONLY=1; shift;;
+        --no-fetch) NO_FETCH=1; shift;;
+        --json) EMIT_JSON=1; shift;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$SCOPE" ]] || { echo "ERROR: --scope '$SCOPE' is not a directory" >&2; exit 1; }
+SCOPE_ABS="$(cd "$SCOPE" && pwd)"
+SELF_REPO="$(cd "$TOOLS_DIR/../.." && pwd)"
+
+# --- Resolve ROOT (bounded by the git toplevel; never escapes the repo) ---
+GIT_TOP="$(git -C "$SCOPE_ABS" rev-parse --show-toplevel 2>/dev/null || true)"
+resolve_root() {
+    if [[ -z "$GIT_TOP" ]]; then printf '%s' "$SCOPE_ABS"; return; fi   # no git → module-local
+    local d="$SCOPE_ABS"
+    while [[ "$d" != "$GIT_TOP" && "$d" != "/" ]]; do
+        d="$(dirname "$d")"
+        if [[ "$d" != "$SCOPE_ABS" && -d "$d/draft" ]]; then printf '%s' "$d"; return; fi
+    done
+    printf '%s' "$GIT_TOP"
+}
+ROOT_ABS="$(resolve_root)"
+IS_ROOT=0
+[[ "$SCOPE_ABS" == "$ROOT_ABS" ]] && IS_ROOT=1
+
+# --- Ensure the engine (the default tier); fetch when missing unless told not to ---
+ensure_engine() {
+    [[ -z "${DRAFT_MEMORY_DISABLE:-}" ]] || return 1
+    find_memory_bin "$SCOPE_ABS" "$SELF_REPO" && return 0
+    [[ "$NO_FETCH" -eq 0 ]] || return 1
+    echo "Graph engine not found — fetching it (one-time download; this may take a while)..." >&2
+    "$SELF_REPO/scripts/fetch-memory-engine.sh" >&2 2>&1 || true
+    find_memory_bin "$SCOPE_ABS" "$SELF_REPO"
+}
+
+engine_unavailable() {
+    if [[ "$EMIT_JSON" -eq 1 ]]; then
+        printf '{"status":"unavailable","root":"%s","scope":"%s","is_root":%s}\n' \
+            "$ROOT_ABS" "$SCOPE_ABS" "$IS_ROOT"
+    else
+        echo "WARNING: knowledge-graph engine (codebase-memory-mcp) is unavailable — no graph built." >&2
+        echo "  The engine is Draft's default capability tier. Install it with:" >&2
+        echo "    scripts/fetch-memory-engine.sh" >&2
+        echo "  or put codebase-memory-mcp on PATH. Set DRAFT_MEMORY_DISABLE=1 to silence this." >&2
+        echo "  Committed draft/graph/ snapshots (if present) still provide structural context." >&2
+    fi
+    exit 2
+}
+
+# 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=$?
+    return "$rc"
+}
+
+# Path from <module>/draft/graph back to <root>/draft/graph (module is under root).
+root_link_relpath() {
+    local sub="${SCOPE_ABS#"$ROOT_ABS"/}"
+    local ups=2 seg
+    IFS='/' read -ra seg <<< "$sub"
+    ups=$(( ${#seg[@]} + 2 ))
+    local i out=""
+    for ((i = 0; i < ups; i++)); do out+="../"; done
+    printf '%sdraft/graph' "$out"
+}
+
+write_root_link() {
+    local status="$1"
+    local mod_graph="$SCOPE_ABS/draft/graph"
+    mkdir -p "$mod_graph"
+    local rel root_project="unknown" root_commit ts schema="$ROOT_ABS/draft/graph/schema.yaml"
+    rel="$(root_link_relpath)"
+    if [[ -f "$schema" ]]; then
+        root_project="$(grep -m1 '^project:' "$schema" 2>/dev/null | sed 's/^project:[[:space:]]*//; s/^"//; s/"$//' || true)"
+        [[ -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 -u +%Y-%m-%dT%H:%M:%SZ)"
+    cat > "$mod_graph/root-link.json" <<EOF
+{
+  "root_graph": "$rel",
+  "root_abs": "$ROOT_ABS/draft/graph",
+  "root_project": "${root_project:-unknown}",
+  "root_commit": "$root_commit",
+  "status": "$status",
+  "linked_at": "$ts",
+  "linked_by": "graph-init.sh",
+  "note": "Root is the authoritative whole-repo graph. Follow root_graph for cross-module understanding."
+}
+EOF
+}
+
+ensure_engine || engine_unavailable
+
+ROOT_BUILT=0
+MODULE_BUILT=0
+LINK_STATUS="none"
+
+if [[ "$IS_ROOT" -eq 1 ]]; then
+    build_snapshot "$ROOT_ABS" && ROOT_BUILT=1
+else
+    if [[ "$MODULE_ONLY" -eq 0 ]]; then
+        echo "Sub-module of $ROOT_ABS — ensuring the root code-graph spine first..." >&2
+        build_snapshot "$ROOT_ABS" && ROOT_BUILT=1
+    fi
+    build_snapshot "$SCOPE_ABS" && MODULE_BUILT=1
+    if [[ -f "$ROOT_ABS/draft/graph/schema.yaml" ]]; then
+        LINK_STATUS="linked"
+    else
+        LINK_STATUS="pending"
+    fi
+    write_root_link "$LINK_STATUS"
+fi
+
+if [[ "$EMIT_JSON" -eq 1 ]]; then
+    printf '{"status":"ok","root":"%s","scope":"%s","is_root":%s,"root_built":%s,"module_built":%s,"link_status":"%s"}\n' \
+        "$ROOT_ABS" "$SCOPE_ABS" "$IS_ROOT" "$ROOT_BUILT" "$MODULE_BUILT" "$LINK_STATUS"
+else
+    echo "--- graph-init ---"
+    echo "Root:  $ROOT_ABS$([[ $IS_ROOT -eq 1 ]] && echo '  (this scope is the root)')"
+    [[ "$IS_ROOT" -eq 1 ]] && echo "Built whole-repo spine: $ROOT_ABS/draft/graph/"
+    if [[ "$IS_ROOT" -eq 0 ]]; then
+        [[ "$ROOT_BUILT" -eq 1 ]] && echo "Root spine: refreshed $ROOT_ABS/draft/graph/"
+        echo "Module:    $SCOPE_ABS/draft/graph/"
+        echo "Root link: $LINK_STATUS ($SCOPE_ABS/draft/graph/root-link.json)"
+    fi
+fi
+exit 0

package/scripts/tools/graph-snapshot.sh

@@ -1,18 +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
+# 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.
@@ -27,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
 }
 
@@ -56,47 +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. 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
+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/skill-caps.conf

@@ -19,6 +19,5 @@ status       1300
 bughunt     1200
 new-track   1100
 review      1000
-index        900
 implement    900
 decompose    700

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")",