@drafthq/draft 3.5.3 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "3.5.3",
+  "version": "3.6.0",
   "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/fetch-memory-engine.sh

@@ -26,7 +26,7 @@ VERSION="${CMM_VERSION:-$DEFAULT_VERSION}"
 DEST="$HOME/.cache/draft/bin"
 FORCE=0
 
-usage() { sed -n '2,22p' "$0" | sed 's/^# \{0,1\}//'; }
+usage() { sed -n '2,20p' "$0" | sed 's/^# \{0,1\}//'; }
 
 while [[ $# -gt 0 ]]; do
   case "$1" in

package/scripts/lib.sh

@@ -57,6 +57,76 @@ SKILL_ORDER=(
     assist-review
 )
 
+# ─────────────────────────────────────────────────────────
+# Skill metadata: one row per skill — "<name>|<display header>|<copilot trigger>"
+# The name and header never contain "|"; the trigger may (e.g. "[file|pr N]"),
+# so lookups split on the FIRST TWO pipes only. Coverage against SKILL_ORDER is
+# enforced by tests/test-trigger-functions.sh.
+# ─────────────────────────────────────────────────────────
+
+SKILL_META=(
+    'draft|Draft Overview|"help" or "draft"'
+    'init|Init Command|"init draft", "build the code graph", or "draft init [refresh] [--graph-only] [--module-only]"'
+    'graph|Graph Command|"build graph", "refresh graph", or "draft graph [path]"'
+    'new-track|New Track Command|"new feature" or "draft new-track <description>"'
+    'decompose|Decompose Command|"break into modules" or "draft decompose"'
+    'implement|Implement Command|"implement" or "draft implement"'
+    'coverage|Coverage Command|"check coverage" or "draft coverage"'
+    'deploy-checklist|Deploy Checklist Command|"deploy checklist" or "draft deploy-checklist [track <id>]"'
+    'bughunt|Bug Hunt Command|"hunt bugs" or "draft bughunt [--track <id>]"'
+    'review|Review Command|"review code" or "draft review [--track <id>] [--full]"'
+    'upload|Upload Command|"upload for review" or "draft upload [track <id>]"'
+    'plan|Plan Router|"plan feature" or "draft plan <intent>" (new-track, decompose, adr, tech-debt, change)'
+    'ops|Ops Router|"ops deploy" or "draft ops <intent>" (deploy-checklist, incident, standup, status, revert)'
+    'docs|Docs Router|"write docs" or "draft docs <intent>" (documentation)'
+    'discover|Discover Router|"discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, index, etc.)'
+    'jira|Jira Router|"jira preview", "jira create", or "jira review <ID>"'
+    'integrations|Integrations Router|"integrations", "integrations jira-preview", or "integrations jira-create"'
+    'quick-review|Quick Review Command|"quick review" or "draft quick-review [file|pr <number>]"'
+    'deep-review|Deep Review Command|"deep review" or "draft deep-review [module]"'
+    'testing-strategy|Testing Strategy Command|"test strategy" or "draft testing-strategy [track <id>|path]"'
+    'learn|Learn Command|"learn patterns" or "draft learn [promote|migrate|path]"'
+    'adr|ADR Command|"document decision" or "draft adr [title]"'
+    'debug|Debug Command|"debug bug" or "draft debug [description|track <id>]"'
+    'standup|Standup Command|"standup" or "draft standup [date|week|save]"'
+    'tech-debt|Tech Debt Command|"tech debt" or "draft tech-debt [path|track <id>]"'
+    'incident-response|Incident Response Command|"incident" or "draft incident-response [new|update|postmortem]"'
+    'documentation|Documentation Command|"write docs" or "draft documentation [readme|runbook|api|onboarding]"'
+    'status|Status Command|"status" or "draft status"'
+    'revert|Revert Command|"revert" or "draft revert"'
+    'change|Change Command|"handle change" or "draft change <description>"'
+    'tour|Tour Command|"tour" or "draft tour"'
+    'impact|Impact Command|"impact" or "draft impact"'
+    'assist-review|Assist Review Command|"assist review" or "draft assist-review"'
+)
+
+# get_skill_header <skill> — display header for integration sections.
+get_skill_header() {
+    local skill="$1" row rest
+    for row in "${SKILL_META[@]}"; do
+        if [[ "${row%%|*}" == "$skill" ]]; then
+            rest="${row#*|}"
+            printf '%s\n' "${rest%%|*}"
+            return 0
+        fi
+    done
+    printf '%s\n' "$(echo "${skill:0:1}" | tr '[:lower:]' '[:upper:]')${skill:1} Command"
+}
+
+# get_copilot_trigger <skill> — natural-language trigger for the Copilot header.
+get_copilot_trigger() {
+    local skill="$1" row rest
+    for row in "${SKILL_META[@]}"; do
+        if [[ "${row%%|*}" == "$skill" ]]; then
+            rest="${row#*|}"
+            printf '%s\n' "${rest#*|}"
+            return 0
+        fi
+    done
+    printf '"draft %s"\n' "$skill"
+}
+
+
 # ─────────────────────────────────────────────────────────
 # Core reference files (inlined by Claude plugin at runtime)
 # ─────────────────────────────────────────────────────────
@@ -91,7 +161,6 @@ CORE_FILES=(
     "templates/ai-context.md"
     "templates/ai-profile.md"
     "templates/architecture.md"
-    "templates/track-architecture.md"
     "templates/jira.md"
     "templates/product.md"
     "templates/tech-stack.md"
@@ -202,6 +271,8 @@ TOOLS=(
     "okf-validate-quality.sh"
     "okf-coverage-check.sh"
     "okf-validate-all.sh"
+    "okf-emit-catalog.sh"
+    "okf-fix-links.sh"
 )
 
 # ─────────────────────────────────────────────────────────
@@ -264,12 +335,18 @@ extract_body() {
 }
 
 # Validate body format: line 1 blank, line 2 starts with #, line 3 blank.
+# $3 (optional): pre-extracted body — skips a second extract_body parse when
+# the caller already has it.
 validate_skill_body_format() {
     local skill="$1"
     local skill_file="$2"
 
     local body_head line1 line2 line3
-    body_head=$(extract_body "$skill_file" | sed -n '1,3p' || true)
+    if (( $# >= 3 )); then
+        body_head=$(printf '%s\n' "$3" | sed -n '1,3p')
+    else
+        body_head=$(extract_body "$skill_file" | sed -n '1,3p' || true)
+    fi
     line1=$(echo "$body_head" | sed -n '1p')
     line2=$(echo "$body_head" | sed -n '2p')
     line3=$(echo "$body_head" | sed -n '3p')

package/scripts/tools/_graph_queries.sh

@@ -28,9 +28,12 @@ if [[ "$(type -t memory_cli 2>/dev/null)" != function ]]; then
     source "$_GQ_DIR/_lib.sh"
 fi
 
-# Escape single quotes for embedding inside a Cypher single-quoted string literal.
+# Escape for embedding inside a Cypher single-quoted string literal.
+# Backslashes must be doubled BEFORE quotes are escaped, otherwise an input
+# ending in `\` yields `\'` — an escaped quote that never closes the literal.
 gq_escape() {
     local s="$1"
+    s="${s//\\/\\\\}"
     printf '%s' "${s//\'/\\\'}"
 }
 
@@ -82,19 +85,23 @@ gq_rows_len() {
     printf '%s' "$1" | jq -r '(.rows // []) | length' 2>/dev/null || printf '0'
 }
 
-# gq_symbol_status <project> <sym_esc> <result_json> -> ok | no-edges | no-match
+# gq_symbol_status <project> <sym_esc> <result_json>
+#   -> ok | no-edges | no-match | probe-failed
 # Fail-loud disambiguation (Guardrail 4): an empty result is only a true negative
 # ("no-edges") when the node actually exists; otherwise it is "no-match". An
 # existence probe runs only when the primary result is empty (hot path stays one
-# query).
+# query). If the probe itself errors, that is NOT a true negative — report
+# "probe-failed" so callers never mistake an engine failure for absence.
 gq_symbol_status() {
     local project="$1" sym="$2" result="$3"
     if [[ "$(gq_rows_len "$result")" -gt 0 ]]; then
         printf 'ok'; return
     fi
     local ex
-    ex="$(gq_run "$project" "$(gq_q_exists "$sym")" || true)"
-    if [[ -n "$ex" && "$(gq_rows_len "$ex")" -gt 0 ]]; then
+    if ! ex="$(gq_run "$project" "$(gq_q_exists "$sym")")"; then
+        printf 'probe-failed'; return
+    fi
+    if [[ "$(gq_rows_len "$ex")" -gt 0 ]]; then
         printf 'no-edges'
     else
         printf 'no-match'

package/scripts/tools/_lib.sh

@@ -113,6 +113,47 @@ get_yaml_field() {
 # Sets MEMORY_BIN globally; returns 0 if found, 1 otherwise.
 # Preference: PATH > Draft-managed install (~/.cache/draft/bin) > vendored bin/<arch> under known roots.
 # No legacy fallbacks: the Aether `graph`/`graph-clang` binaries are retired.
+
+# GitHub-flavored-markdown-ish heading id (shared by TOC, anchors, link fixers).
+# Keeps underscores; strips other punctuation; collapses whitespace to '-'.
+gfm_slug() {
+    local s="${1:-}"
+    # shellcheck disable=SC2001
+    s="$(printf '%s' "$s" | tr '[:upper:]' '[:lower:]')"
+    s="$(printf '%s' "$s" | sed -E 's/[^[:alnum:]_[:space:]-]+//g; s/[[:space:]]+/-/g; s/-+/-/g; s/^-+//; s/-+$//')"
+    printf '%s' "$s"
+}
+
+# Count entries in an x-grounded-paths frontmatter field.
+# Supports both inline (`x-grounded-paths: ["a", "b"]`) and block lists:
+#   x-grounded-paths:
+#     - "a"
+#     - "b"
+grounded_paths_count() {
+    local file="$1"
+    [[ -f "$file" ]] || { echo 0; return; }
+    awk '
+        NR==1 && /^---$/ { fm=1; next }
+        fm && /^---$/ { exit }
+        fm && /^x-grounded-paths:[[:space:]]*\[/ {
+            line=$0
+            sub(/^x-grounded-paths:[[:space:]]*\[/, "", line)
+            sub(/\].*$/, "", line)
+            gsub(/[[:space:]]/, "", line)
+            if (line=="") { print 0; exit }
+            n=split(line, a, ",")
+            print n
+            exit
+        }
+        fm && /^x-grounded-paths:[[:space:]]*$/ { collect=1; next }
+        fm && collect {
+            if ($0 ~ /^[[:space:]]*-[[:space:]]*/) { n++; next }
+            if ($0 ~ /^[A-Za-z0-9_-]+:/) { print n+0; exit }
+        }
+        END { if (collect) print n+0 }
+    ' "$file"
+}
+
 find_memory_bin() {
     local repo_abs="$1"
     local self_repo="$2"
@@ -157,14 +198,6 @@ find_memory_bin() {
     local roots=()
     [[ -n "$repo_abs" && -d "$repo_abs" ]] && roots+=("$repo_abs")
     [[ -n "$self_repo" && -d "$self_repo" ]] && roots+=("$self_repo")
-    for bc in \
-        "$HOME/.cursor/plugins/local/draft/.draft-install-path" \
-        "$HOME/.claude/plugins/draft/.draft-install-path"; do
-        if [[ -f "$bc" ]]; then
-            local pr; pr="$(cat "$bc" 2>/dev/null || true)"
-            [[ -n "$pr" && -d "$pr" ]] && roots+=("$pr")
-        fi
-    done
 
     for pr in "${roots[@]}"; do
         local cand="$pr/bin/$ARCH/$bin_name"
@@ -177,6 +210,21 @@ find_memory_bin() {
     return 1
 }
 
+# graph_bootstrap <repo-dir>
+# Shared engine bootstrap for the graph-*.sh wrappers: resolves the repo path,
+# locates the engine binary, checks jq, and ensures the index. Sets the globals
+# REPO_ABS and PROJECT. Returns 1 on any failure so each wrapper routes it to
+# its own unavailable-JSON shape (the shapes differ per tool).
+graph_bootstrap() {
+    local repo="$1" self_repo
+    REPO_ABS="$(cd "$repo" 2>/dev/null && pwd)" || return 1
+    self_repo="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+    find_memory_bin "$REPO_ABS" "$self_repo" || return 1
+    command -v jq >/dev/null 2>&1 || return 1
+    PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
+    [[ -n "$PROJECT" ]] || return 1
+}
+
 # Run a codebase-memory-mcp CLI tool. Echoes the JSON result (stdout); the engine's
 # `level=...` log lines go to stderr and are discarded unless DRAFT_MEMORY_DEBUG is set.
 # Usage: memory_cli <tool> [json-args]

package/scripts/tools/adr-index.sh

@@ -32,7 +32,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/check-skill-line-caps.sh

@@ -51,8 +51,8 @@ while (($#)); do
         -h|--help) USAGE_HELP_MODE=1 usage ;;
         --enforce) ENFORCE=1; shift ;;
         --json) EMIT_JSON=1; shift ;;
-        --caps) CAPS_CONF="$2"; shift 2 ;;
-        --skills-dir) SKILLS_DIR="$2"; shift 2 ;;
+        --caps) CAPS_CONF="${2:?--caps requires a value}"; shift 2 ;;
+        --skills-dir) SKILLS_DIR="${2:?--skills-dir requires a value}"; shift 2 ;;
         -*) printf 'Unknown flag: %s\n' "$1" >&2; usage ;;
         *) printf 'Unexpected arg: %s\n' "$1" >&2; usage ;;
     esac

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

@@ -41,7 +41,7 @@ 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,16 +51,9 @@ 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

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

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

@@ -54,8 +54,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 +69,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,8 +88,7 @@ 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,

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"