@drafthq/draft 3.5.3 → 3.7.1

package/scripts/tools/check-track-hygiene.sh

@@ -74,6 +74,29 @@ record() {
     violation_count=$((violation_count + 1))
 }
 
+# Numeric reader for metadata.json:hygiene_budget.* (read_json_str is string-only).
+read_json_num() {
+    local file="$1" key="$2"
+    [[ -f "$file" ]] || return 0
+    grep -oE "\"$key\"[[:space:]]*:[[:space:]]*-?[0-9]+" "$file" 2>/dev/null \
+        | head -1 | grep -oE '\-?[0-9]+$' || true
+}
+
+# TBD budget for every top-level doc of one track; cap < 0 means unlimited.
+check_tbd_budget() {
+    local track_dir="$1" rel_track="$2" cap="$3" kind="$4" detail_suffix="$5"
+    (( cap >= 0 )) || return 0
+    while IFS= read -r f; do
+        local rel_file="${f#"$track_dir/"}"
+        local count
+        count="$(grep -oE "$TBD_RE" "$f" 2>/dev/null | wc -l | tr -d ' ' || true)"
+        if (( count > cap )); then
+            record "$rel_track" "$kind" "$rel_file" "0" \
+                "$count TBD sentinel(s) $detail_suffix"
+        fi
+    done < <(find "$track_dir" -maxdepth 1 -type f -name '*.md')
+}
+
 scan_one_track() {
     local track_dir="$1"
     local rel_track="${track_dir#"$REPO_ROOT/"}"
@@ -138,31 +161,28 @@ scan_one_track() {
         done < "$f"
     done < <(find "$track_dir" -maxdepth 1 -type f -name '*.md')
 
-    # 4. TBD budget per-doc.
+    # 4. TBD budget per-doc. Caps come from metadata.json:hygiene_budget when
+    # present (draft_tbd_cap / ready_for_review_tbd_cap; -1 = unlimited),
+    # falling back to the historical defaults.
     case "$meta_status" in
-        draft|archived) ;;
+        archived) ;;
+        draft)
+            local draft_cap
+            draft_cap="$(read_json_num "$meta" "draft_tbd_cap")"
+            [[ "$draft_cap" =~ ^-?[0-9]+$ ]] || draft_cap=-1
+            check_tbd_budget "$track_dir" "$rel_track" "$draft_cap" "tbd-over-cap" \
+                "(cap $draft_cap at status=$meta_status)"
+            ;;
         ready-for-review|in_progress)
-            local tbd_cap=3
-            while IFS= read -r f; do
-                local rel_file="${f#"$track_dir/"}"
-                local count
-                count="$(grep -oE "$TBD_RE" "$f" 2>/dev/null | wc -l | tr -d ' ')"
-                if (( count > tbd_cap )); then
-                    record "$rel_track" "tbd-over-cap" "$rel_file" "0" \
-                        "$count TBD sentinel(s) (cap $tbd_cap at status=$meta_status)"
-                fi
-            done < <(find "$track_dir" -maxdepth 1 -type f -name '*.md')
+            local tbd_cap
+            tbd_cap="$(read_json_num "$meta" "ready_for_review_tbd_cap")"
+            [[ "$tbd_cap" =~ ^-?[0-9]+$ ]] || tbd_cap=3
+            check_tbd_budget "$track_dir" "$rel_track" "$tbd_cap" "tbd-over-cap" \
+                "(cap $tbd_cap at status=$meta_status)"
             ;;
         completed)
-            while IFS= read -r f; do
-                local rel_file="${f#"$track_dir/"}"
-                local count
-                count="$(grep -oE "$TBD_RE" "$f" 2>/dev/null | wc -l | tr -d ' ')"
-                if (( count > 0 )); then
-                    record "$rel_track" "tbd-in-completed" "$rel_file" "0" \
-                        "$count TBD sentinel(s) at status=completed"
-                fi
-            done < <(find "$track_dir" -maxdepth 1 -type f -name '*.md')
+            check_tbd_budget "$track_dir" "$rel_track" 0 "tbd-in-completed" \
+                "at status=completed"
             ;;
     esac
 

package/scripts/tools/classify-files.sh

@@ -34,14 +34,14 @@ Output (per file): {path, lang, category, is_test, is_generated, loc, module}
 
 Language is inferred from extension and shebang. A file is classified as a
 test when its path or basename matches common test patterns. It is flagged
-generated when the first 5 lines contain "Code generated" or "DO NOT EDIT".
-Module is the first path segment under root.
+generated when the first 5 lines contain "Code generated", "DO NOT EDIT",
+"@generated", or "autogenerated". Module is the first path segment under root.
 EOF
 }
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --root) ROOT="$2"; shift 2;;
+        --root) ROOT="${2:?--root requires a value}"; shift 2;;
         --json) FORMAT="json"; shift;;
         --jsonl) FORMAT="jsonl"; shift;;
         --help|-h) usage; exit 0;;

package/scripts/tools/cycle-detect.sh

@@ -40,7 +40,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -51,32 +51,33 @@ if [[ ! -d "$REPO" ]]; then
     exit 1
 fi
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() { echo '{"cycles":[],"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
+graph_bootstrap "$REPO" || unavailable
 
 # 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 '{}')"
-
-# 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='{}'
+#
+# A failed query is not an empty result. Substituting `{}` and carrying on
+# reported `source:"memory-graph"` with zero cycles — a clean bill of health
+# derived from a query that never ran, which is exactly the true-negative
+# confusion Guardrail 4 exists to prevent, and the one failure mode a caller
+# cannot detect. Both queries must land for the sample to mean anything, so
+# either failure routes to `unavailable`. gq_run only ever echoes validated
+# JSON, so nothing downstream needs a second shape guard.
+R2="$(gq_run "$PROJECT" "$(gq_q_cycles2)")" || unavailable
+R3="$(gq_run "$PROJECT" "$(gq_q_cycles3)")" || unavailable
 
+# Self-loops and duplicate orderings are filtered here rather than in Cypher:
+# the engine rejects `a.x < b.x`, which is what the query used to rely on.
+# A 2-cycle comes back twice (A,B and B,A), hence the doubled LIMIT upstream.
 jq -n --argjson r2 "$R2" --argjson r3 "$R3" '
-    ( ((($r2.rows) // []) | length) >= 100
+    ( ((($r2.rows) // []) | length) >= 200
       or ((($r3.rows) // []) | length) >= 100 ) as $trunc
+    | ( ($r2.rows // []) | map(select(.[0] != .[1])) | unique_by(sort) ) as $two
     | {
-        cycles: (((($r2.rows) // []) + (($r3.rows) // []))),
+        cycles: ($two + ($r3.rows // [])),
         truncated: $trunc,
         source: "memory-graph"
       }'

package/scripts/tools/detect-test-framework.sh

@@ -39,7 +39,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --root) ROOT="$2"; shift 2;;
+        --root) ROOT="${2:?--root requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac

package/scripts/tools/emit-skill-metrics.sh

@@ -37,8 +37,13 @@ LOCK_FILE="${METRICS_DIR}/metrics.lock"
 
 payload="${1:-}"
 
-# Validate that a payload was provided
-if [[ -z "${payload}" ]]; then
+# Trim trailing whitespace/newlines so the closing-brace strip below matches
+# even when the caller passes a payload with a stray trailing newline.
+payload="${payload%"${payload##*[![:space:]]}"}"
+
+# Validate that a payload was provided and looks like a JSON object — a
+# payload not ending in '}' would corrupt the NDJSON file, so drop it.
+if [[ -z "${payload}" || "${payload}" != *\} ]]; then
   exit 0
 fi
 

package/scripts/tools/fix-whitespace.sh

@@ -83,6 +83,9 @@ fix_file() {
         return 1 # already clean — no change on disk
     fi
 
+    # mktemp creates 0600 and `mv` swaps the inode — carry the destination's mode
+    # across, or an atomic rewrite silently strips the file's permissions.
+    apply_dest_mode "$_tmp" "$file"
     mv -f "$_tmp" "$file"
     return 0
 }

package/scripts/tools/freshness-check.sh

@@ -46,8 +46,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --state) STATE_FILE="$2"; shift 2;;
-        --root) ROOT="$2"; shift 2;;
+        --state) STATE_FILE="${2:?--state requires a value}"; shift 2;;
+        --root) ROOT="${2:?--root requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac

package/scripts/tools/git-metadata.sh

@@ -66,12 +66,12 @@ while [[ $# -gt 0 ]]; do
         --yaml) FORMAT="yaml"; shift;;
         --json) FORMAT="json"; shift;;
         --project-metadata) WRITE_PROJECT_METADATA=1; shift;;
-        --project) PROJECT="$2"; shift 2;;
-        --module) MODULE="$2"; shift 2;;
-        --track-id) TRACK_ID="$2"; shift 2;;
-        --generated-by) GENERATED_BY="$2"; shift 2;;
-        --base) BASE_BRANCH="$2"; shift 2;;
-        --output-dir) OUTPUT_DIR="$2"; shift 2;;
+        --project) PROJECT="${2:?--project requires a value}"; shift 2;;
+        --module) MODULE="${2:?--module requires a value}"; shift 2;;
+        --track-id) TRACK_ID="${2:?--track-id requires a value}"; shift 2;;
+        --generated-by) GENERATED_BY="${2:?--generated-by requires a value}"; shift 2;;
+        --base) BASE_BRANCH="${2:?--base requires a value}"; shift 2;;
+        --output-dir) OUTPUT_DIR="${2:?--output-dir requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -127,6 +127,8 @@ if (( WRITE_PROJECT_METADATA )); then
     fi
     CMD="${GENERATED_BY:-draft:init}"
     _tmp="$(mktemp "${META_FILE}.XXXXXX")"
+    # errexit on a failed write would otherwise leave metadata.json.XXXXXX behind.
+    trap 'rm -f "$_tmp"' EXIT
     cat > "$_tmp" <<EOF
 {
   "\$schema": "Draft Project Metadata Schema",
@@ -150,7 +152,11 @@ if (( WRITE_PROJECT_METADATA )); then
   "synced_to_commit": "$FULL_SHA"
 }
 EOF
+    # mktemp creates 0600 and `mv` swaps the inode — carry the destination's mode
+    # across, or an atomic rewrite silently strips the file's permissions.
+    apply_dest_mode "$_tmp" "$META_FILE"
     mv -f "$_tmp" "$META_FILE"
+    trap - EXIT
     echo "Written: $META_FILE (synced_to_commit=$FULL_SHA)"
     exit 0
 fi

package/scripts/tools/graph-arch.sh

@@ -42,7 +42,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -53,20 +53,14 @@ if [[ ! -d "$REPO" ]]; then
     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
+graph_bootstrap "$REPO" || unavailable
 
-ARCH_JSON="$(memory_cli get_architecture "{\"project\":\"$PROJECT\",\"aspects\":[\"all\"]}" || true)"
+ARCH_JSON="$(memory_cli get_architecture "$(jq -n --arg p "$PROJECT" '{project:$p, aspects:["all"]}')" || true)"
 [[ -n "$ARCH_JSON" ]] || unavailable
 
 # Validate it parses and looks like an architecture object before emitting.
+# Tag with source like every other graph-*.sh wrapper (universal contract).
 echo "$ARCH_JSON" | jq -e '.total_nodes != null' >/dev/null 2>&1 || unavailable
-echo "$ARCH_JSON" | jq '.'
+echo "$ARCH_JSON" | jq '. + {source:"memory-graph"}'

package/scripts/tools/graph-callers.sh

@@ -9,7 +9,10 @@
 #   scripts/tools/graph-callers.sh --repo DIR --symbol NAME
 #                                  [--transitive[=N]] [--prod-only] [--qualified]
 #
-# Output: JSON {symbol, callers:[{name,file[,hop]}], status, source}.
+# Output: JSON {symbol, callers:[{name,file,qualified[,hop]}], status, source}.
+#   `file` is always a path (empty when the engine does not carry one — the
+#   trace_path expander behind --transitive returns no file_path); the symbol's
+#   qualified name is in `qualified`, never smuggled into `file`.
 #   source = "memory-graph" | "unavailable"
 #   status = "ok" | "no-edges" | "no-match" | "unavailable"
 #            (fail-loud: distinguishes node-not-found from node-has-no-callers
@@ -54,8 +57,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --symbol) SYMBOL="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --symbol) SYMBOL="${2:?--symbol requires a value}"; shift 2;;
         --transitive) TRANSITIVE=1; shift;;
         --transitive=*) TRANSITIVE=1; DEPTH="${1#*=}"; shift;;
         --prod-only) PROD_ONLY=1; shift;;
@@ -69,20 +72,13 @@ done
 [[ -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:[], status:"unavailable", source:"unavailable"}' 2>/dev/null \
         || echo '{"callers":[],"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
+graph_bootstrap "$REPO" || unavailable
 
 SYM_ESC="$(gq_escape "$SYMBOL")"
 
@@ -95,12 +91,11 @@ if [[ "$TRANSITIVE" -eq 1 ]]; then
     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
+        STATUS="$(gq_symbol_status "$PROJECT" "$SYM_ESC" '{"rows":[]}')"
     fi
     echo "$RES" | jq --arg s "$SYMBOL" --arg st "$STATUS" '
         {symbol:$s,
-         callers: [ (.callers // [])[] | {name:.name, file:(.qualified_name // ""), hop:(.hop // 1)} ],
+         callers: [ (.callers // [])[] | {name:.name, file:(.file_path // ""), qualified:(.qualified_name // ""), hop:(.hop // 1)} ],
          status:$st, source:"memory-graph"}'
     exit 0
 fi
@@ -121,5 +116,5 @@ 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]} ],
+     callers: [ (.rows // [])[] | {name:.[0], file:(.[1] // ""), qualified:""} ],
      status:$st, source:"memory-graph"}'

package/scripts/tools/graph-deps.sh

@@ -43,8 +43,8 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --file) FILE="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --file) FILE="${2:?--file requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -52,16 +52,9 @@ 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
+graph_bootstrap "$REPO" || unavailable
 
 RES="$(gq_run "$PROJECT" "$(gq_q_imports)" || true)"
 [[ -n "$RES" ]] || unavailable

package/scripts/tools/graph-errors.sh

@@ -42,9 +42,9 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --symbol) SYMBOL="$2"; shift 2;;
-        --type) TYPE="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --symbol) SYMBOL="${2:?--symbol requires a value}"; shift 2;;
+        --type) TYPE="${2:?--type requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -56,9 +56,6 @@ if [[ -n "$SYMBOL" && -n "$TYPE" ]]; then
 fi
 [[ -n "$SYMBOL" || -n "$TYPE" ]] || { echo "ERROR: provide --symbol or --type" >&2; usage >&2; exit 1; }
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() {
     if [[ -n "$TYPE" ]]; then
         jq -n --arg t "$TYPE" '{type:$t, raisers:[], status:"unavailable", source:"unavailable"}' 2>/dev/null \
@@ -70,11 +67,7 @@ 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
+graph_bootstrap "$REPO" || unavailable
 
 if [[ -n "$TYPE" ]]; then
     SYM_ESC="$(gq_escape "$TYPE")"

package/scripts/tools/graph-hierarchy.sh

@@ -43,9 +43,9 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --symbol) SYMBOL="$2"; shift 2;;
-        --derived) DERIVED="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --symbol) SYMBOL="${2:?--symbol requires a value}"; shift 2;;
+        --derived) DERIVED="${2:?--derived requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -56,16 +56,9 @@ if [[ -n "$SYMBOL" && -n "$DERIVED" ]]; then
     echo "ERROR: use either --symbol or --derived, not both" >&2; exit 1
 fi
 
-REPO_ABS="$(cd "$REPO" && pwd)"
-SELF_REPO="$(cd "$(dirname "$0")/../.." && pwd)"
-
 unavailable() { echo '{"edges":[],"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
+graph_bootstrap "$REPO" || unavailable
 
 if [[ -n "$SYMBOL" ]]; then
     SYM_ESC="$(gq_escape "$SYMBOL")"; Q="$(gq_q_inherits_sym "$SYM_ESC")"; PROBE="$SYM_ESC"

package/scripts/tools/graph-impact.sh

@@ -9,7 +9,9 @@
 # Usage:
 #   scripts/tools/graph-impact.sh --repo DIR (--file PATH | --symbol NAME) [--depth N]
 #
-# Output: JSON {target, kind, impacted:[{name,file,hop}], source}.
+# Output: JSON {target, kind, impacted:[{name,file,qualified,hop}], source}.
+#   `file` is always a path (empty when the engine carries none); the qualified
+#   name has its own field rather than being emitted as if it were a path.
 #   source = "memory-graph" | "unavailable"
 #
 # Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
@@ -43,10 +45,10 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --repo) REPO="$2"; shift 2;;
-        --file) FILE="$2"; shift 2;;
-        --symbol) SYMBOL="$2"; shift 2;;
-        --depth) DEPTH="$2"; shift 2;;
+        --repo) REPO="${2:?--repo requires a value}"; shift 2;;
+        --file) FILE="${2:?--file requires a value}"; shift 2;;
+        --symbol) SYMBOL="${2:?--symbol requires a value}"; shift 2;;
+        --depth) DEPTH="${2:?--depth requires a value}"; shift 2;;
         --help|-h) usage; exit 0;;
         *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
     esac
@@ -56,9 +58,6 @@ done
 [[ -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)"
-
 unavailable() {
     local t="$1" k="$2"
     jq -n --arg t "$t" --arg k "$k" '{target:$t, kind:$k, impacted:[], source:"unavailable"}' 2>/dev/null \
@@ -68,24 +67,27 @@ unavailable() {
 
 if [[ -n "$SYMBOL" ]]; then TARGET="$SYMBOL"; KIND="symbol"; else TARGET="$FILE"; KIND="file"; fi
 
-find_memory_bin "$REPO_ABS" "$SELF_REPO" || unavailable "$TARGET" "$KIND"
-command -v jq >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
-
-PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
-[[ -n "$PROJECT" ]] || unavailable "$TARGET" "$KIND"
+graph_bootstrap "$REPO" || unavailable "$TARGET" "$KIND"
 
 if [[ -n "$SYMBOL" ]]; then
     # direction:"both" is the reliable form (the "callers" value returns empty in this engine);
-    # we read the .callers array from it.
-    RES="$(memory_cli trace_path "{\"project\":\"$PROJECT\",\"function_name\":\"$SYMBOL\",\"depth\":$DEPTH,\"direction\":\"both\"}" || echo '{}')"
-    echo "${RES:-{\}}" | jq --arg t "$TARGET" '
+    # we read the .callers array from it. Payload built with jq so a quote in
+    # --symbol can never corrupt the JSON; an engine failure is unavailable,
+    # never a fabricated empty-impact success.
+    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 "$TARGET" "$KIND"
+    echo "$RES" | jq --arg t "$TARGET" '
         {target:$t, kind:"symbol",
-         impacted: [ (.callers // [])[] | {name:.name, file:(.qualified_name // ""), hop:(.hop // 1)} ],
+         impacted: [ (.callers // [])[] | {name:.name, file:(.file_path // ""), qualified:(.qualified_name // ""), hop:(.hop // 1)} ],
          source:"memory-graph"}'
 else
     # File impact: detect_changes maps the working-tree diff to impacted symbols.
-    RES="$(memory_cli detect_changes "{\"project\":\"$PROJECT\"}" || echo '{}')"
-    echo "${RES:-{\}}" | jq --arg t "$TARGET" '
+    PAYLOAD="$(jq -n --arg p "$PROJECT" '{project:$p}')"
+    RES="$(memory_cli detect_changes "$PAYLOAD" 2>/dev/null || true)"
+    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
+    echo "$RES" | jq --arg t "$TARGET" '
         {target:$t, kind:"file",
          impacted: [ (.impacted_symbols // [])[]
                      | select((.file // "") | endswith($t) or (. == $t))

package/scripts/tools/graph-init.sh

@@ -52,7 +52,7 @@ EOF
 
 while [[ $# -gt 0 ]]; do
     case "$1" in
-        --scope) SCOPE="$2"; shift 2;;
+        --scope) SCOPE="${2:?--scope requires a value}"; shift 2;;
         --module-only) MODULE_ONLY=1; shift;;
         --no-fetch) NO_FETCH=1; shift;;
         --json) EMIT_JSON=1; shift;;
@@ -93,7 +93,7 @@ ensure_engine() {
 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"
+            "$(json_escape "$ROOT_ABS")" "$(json_escape "$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
@@ -115,7 +115,7 @@ build_snapshot() {
 # 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
+    local ups seg
     IFS='/' read -ra seg <<< "$sub"
     ups=$(( ${#seg[@]} + 2 ))
     local i out=""
@@ -135,13 +135,16 @@ write_root_link() {
     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)"
+    # Every interpolated value goes through json_escape: a repo path or engine
+    # project name carrying a quote or backslash would otherwise emit a
+    # root-link.json that no consumer can parse.
     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",
+  "root_graph": "$(json_escape "$rel")",
+  "root_abs": "$(json_escape "$ROOT_ABS/draft/graph")",
+  "root_project": "$(json_escape "${root_project:-unknown}")",
+  "root_commit": "$(json_escape "$root_commit")",
+  "status": "$(json_escape "$status")",
   "linked_at": "$ts",
   "linked_by": "graph-init.sh",
   "note": "Root is the authoritative whole-repo graph. Follow root_graph for cross-module understanding."
@@ -173,7 +176,8 @@ 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"
+        "$(json_escape "$ROOT_ABS")" "$(json_escape "$SCOPE_ABS")" \
+        "$IS_ROOT" "$ROOT_BUILT" "$MODULE_BUILT" "$(json_escape "$LINK_STATUS")"
 else
     echo "--- graph-init ---"
     echo "Root:  $ROOT_ABS$([[ $IS_ROOT -eq 1 ]] && echo '  (this scope is the root)')"

package/scripts/tools/graph-preflight.sh

@@ -168,9 +168,12 @@ if find_memory_bin "$REPO_ABS" "$SELF_REPO"; then
   ENGINE_FOUND=true
   VER="$("$ENGINE" --version 2>/dev/null | head -1 || echo '?')"
   ok "Engine: $ENGINE ($VER)"
+  # Numeric-only: the value is emitted bare into the --json report, so a
+  # non-numeric field (engine output format drift) would produce invalid JSON.
   LIMIT="$("$ENGINE" config list 2>/dev/null | awk '/auto_index_limit/{print $3}' || true)"
+  [[ "$LIMIT" =~ ^[0-9]+$ ]] || LIMIT=""
   [[ -n "$LIMIT" ]] && info "auto_index_limit: $LIMIT (governs AUTO-index only; explicit index_repository should bypass)" || true
-  if [[ "$GIT_OK" -eq 1 && -n "${LIMIT:-}" && "$TRACKED" -gt "$LIMIT" ]]; then
+  if [[ "$GIT_OK" -eq 1 && "${LIMIT:-}" =~ ^[0-9]+$ && "$TRACKED" -gt "$LIMIT" ]]; then
     warn "Tracked files ($TRACKED) > auto_index_limit ($LIMIT) — confirm the explicit index isn't truncated near $LIMIT."
   fi
 else