@drafthq/draft 3.1.5 → 3.2.1

package/scripts/tools/hotspot-rank.sh

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

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

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

package/scripts/tools/resolve-tools.sh

@@ -0,0 +1,78 @@
+#!/usr/bin/env bash
+# resolve-tools.sh — print the absolute path to Draft's bundled scripts/tools dir.
+#
+# Skills run with cwd = the user's project, and ${CLAUDE_PLUGIN_ROOT} is NOT exported
+# into skill-driven Bash, so a bare `scripts/tools/foo.sh` invocation fails. This
+# resolver finds the plugin's helper directory regardless of how Draft was installed.
+# See core/shared/tool-resolver.md for the canonical procedure and the inline preamble
+# skills embed (this script is the single source of truth for the resolution order).
+#
+# Usage:
+#   DRAFT_TOOLS="$(scripts/tools/resolve-tools.sh)"   # prints the dir, exit 0 if found
+#   scripts/tools/resolve-tools.sh || echo "tools not found"   # exit 1 if none exist
+set -euo pipefail
+
+case "${1:-}" in
+  -h|--help)
+    sed -n '2,13p' "$0" | sed 's/^# \{0,1\}//'
+    exit 0
+    ;;
+esac
+
+newest() {
+  # Echo the lexically-newest existing match of a glob (by version sort), or nothing.
+  # shellcheck disable=SC2086
+  ls -d $1 2>/dev/null | sort -V | tail -1
+}
+
+resolve() {
+  local d
+
+  # 1. Explicit override (testing / pinned installs).
+  d="${DRAFT_PLUGIN_ROOT:-}/scripts/tools"
+  [ -n "${DRAFT_PLUGIN_ROOT:-}" ] && [ -d "$d" ] && { printf '%s' "$d"; return 0; }
+
+  # 1b. Dev / dogfooding: cwd IS the draft repo. Guarded by this script's own
+  # presence so it can never misfire in a user project (which has no resolve-tools.sh).
+  [ -f "$PWD/scripts/tools/resolve-tools.sh" ] && { printf '%s' "$PWD/scripts/tools"; return 0; }
+
+  # 2. Install marker written by `draft install` (authoritative).
+  local marker="$HOME/.cache/draft/plugin-root"
+  if [ -f "$marker" ]; then
+    d="$(cat "$marker" 2>/dev/null)/scripts/tools"
+    [ -d "$d" ] && { printf '%s' "$d"; return 0; }
+  fi
+
+  # 3. ${CLAUDE_PLUGIN_ROOT} — set in hook/MCP contexts; harmless to probe.
+  d="${CLAUDE_PLUGIN_ROOT:-}/scripts/tools"
+  [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -d "$d" ] && { printf '%s' "$d"; return 0; }
+
+  # 4. Claude Code's own registry (authoritative installPath; needs jq).
+  local reg="$HOME/.claude/plugins/installed_plugins.json"
+  if command -v jq >/dev/null 2>&1 && [ -f "$reg" ]; then
+    local ip
+    ip="$(jq -r '.plugins | to_entries[] | select(.key|startswith("draft@")) | .value[0].installPath' \
+          "$reg" 2>/dev/null | head -1)"
+    [ -n "$ip" ] && [ -d "$ip/scripts/tools" ] && { printf '%s' "$ip/scripts/tools"; return 0; }
+  fi
+
+  # 5. Newest cache install (glob).
+  d="$(newest "$HOME/.claude/plugins/cache/*/draft/*/scripts/tools")"
+  [ -n "$d" ] && [ -d "$d" ] && { printf '%s' "$d"; return 0; }
+
+  # 6. Marketplace clone.
+  d="$(newest "$HOME/.claude/plugins/marketplaces/*draft*/scripts/tools")"
+  [ -n "$d" ] && [ -d "$d" ] && { printf '%s' "$d"; return 0; }
+
+  # 7. Cursor local install.
+  d="$HOME/.cursor/plugins/local/draft/scripts/tools"
+  [ -d "$d" ] && { printf '%s' "$d"; return 0; }
+
+  # 8. Dev / dogfooding (running inside the draft repo itself).
+  d="$PWD/scripts/tools"
+  [ -d "$d" ] && { printf '%s' "$d"; return 0; }
+
+  return 1
+}
+
+resolve

package/skills/adr/SKILL.md

@@ -54,8 +54,9 @@ Check for arguments:
 If argument is `list`:
 1. Prefer the deterministic `adr-index.sh` wrapper for the listing — it returns a structured JSON `{adrs:[{id,title,date,status,path,related_tracks}]}` derived from each ADR's frontmatter. Resolve via the canonical tool resolver (see [core/shared/tool-resolver.md](../../core/shared/tool-resolver.md)):
    ```bash
-   DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
-   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+   DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+   [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
    [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
    if [ -x "$DRAFT_TOOLS/adr-index.sh" ]; then
      bash "$DRAFT_TOOLS/adr-index.sh" --root draft/adrs

package/skills/bughunt/SKILL.md

@@ -68,7 +68,16 @@ 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) — 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 Graph Data** (if `draft/graph/` exists) — First resolve the bundled helpers:
+  ```bash
+  # Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
+  # is not exported into skill Bash). See core/shared/tool-resolver.md.
+  DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+  [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+  [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
+  [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+  ```
+  Query `"$DRAFT_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 `"$DRAFT_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/coverage/SKILL.md

@@ -33,8 +33,9 @@ If no active track and no argument provided:
 **Preferred:** use the deterministic `detect-test-framework.sh` wrapper — it emits JSON `{languages:[{language,framework,runner_command,test_globs,config_file}]}`. Resolve via the canonical tool resolver (see [core/shared/tool-resolver.md](../../core/shared/tool-resolver.md)):
 
 ```bash
-DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
-[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
 [ -x "$DRAFT_TOOLS/detect-test-framework.sh" ] && \
   bash "$DRAFT_TOOLS/detect-test-framework.sh" --root .
@@ -73,7 +74,11 @@ Build the coverage command with the appropriate scope/filter flags.
 **Preferred:** invoke the normalized `run-coverage.sh` dispatcher — it dispatches to the language-specific runner and emits a normalized JSON `{language,tool,total:{lines,branches},per_file:[{path,lines,branches,uncovered_lines}]}`. This avoids per-language ad-hoc parsing in Step 5.
 
 ```bash
-# DRAFT_TOOLS resolved in Step 2 above
+# Re-resolve helpers (this is a separate Bash session from Step 2).
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
 [ -x "$DRAFT_TOOLS/run-coverage.sh" ] && \
   bash "$DRAFT_TOOLS/run-coverage.sh" --root .
 ```

package/skills/debug/SKILL.md

@@ -9,12 +9,23 @@ You are conducting a structured debugging session following systematic investiga
 
 ## MANDATORY GRAPH LOOKUP (read before Isolate/Diagnose)
 
+First resolve the bundled helpers:
+
+```bash
+# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
+# is not exported into skill Bash). See core/shared/tool-resolver.md.
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+```
+
 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 `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. Run `scripts/tools/hotspot-rank.sh --repo .` to know whether the file is high-fanIn (any fix needs extra caution).
+1. Locate the suspect file's module via `"$DRAFT_TOOLS/graph-arch.sh" --repo .` before tracing data flow.
+2. Use `"$DRAFT_TOOLS/graph-callers.sh" --repo . --symbol <fn>` to enumerate call sites of suspect functions — not `grep`.
+3. Use `"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>` to size the blast radius before proposing a fix.
+4. Run `"$DRAFT_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 +73,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) — 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).
+- `draft/graph/` (MANDATORY when present) — Query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for dependency/module context and `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` for complexity awareness. Use `"$DRAFT_TOOLS/graph-callers.sh" --repo . --symbol <fn>` to find all callers, and `"$DRAFT_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

@@ -9,12 +9,23 @@ You are decomposing a project or track into modules with clear responsibilities,
 
 ## MANDATORY GRAPH LOOKUP (read before any analysis)
 
+First resolve the bundled helpers:
+
+```bash
+# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
+# is not exported into skill Bash). See core/shared/tool-resolver.md.
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+```
+
 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. 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.
+1. Query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for the authoritative module list and fan-in/out.
+2. Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` to identify candidate modules to split.
+3. Use `"$DRAFT_TOOLS/graph-callers.sh"`/`"$DRAFT_TOOLS/graph-impact.sh"` on demand for symbols/callers inside a candidate module.
+4. Run `"$DRAFT_TOOLS/cycle-detect.sh" --repo .` to enumerate existing cycles before proposing new boundaries.
 
 Filesystem `grep`/`find` for module discovery is only permitted **after** a documented graph miss, using the fallback sentence `Graph returned no match for <X>; falling back to grep.` and recorded in the Graph Usage Report.
 
@@ -156,11 +167,11 @@ 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**: Query `scripts/tools/graph-arch.sh --repo .` — module list with node counts and per-language file counts
+- **Module boundaries**: Query `"$DRAFT_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**: 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
+- **Hotspots**: Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — high-complexity files that may need further decomposition
+- **Per-module detail**: query `"$DRAFT_TOOLS/graph-callers.sh"`/`"$DRAFT_TOOLS/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.
 
@@ -404,8 +415,11 @@ After writing all generated files, strip trailing whitespace and blank lines at
 Resolve the script via the canonical tool resolver (see [core/shared/tool-resolver.md](../../core/shared/tool-resolver.md)):
 
 ```bash
-DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
-[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
+# is not exported into skill Bash). See core/shared/tool-resolver.md.
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
 # Fix all generated markdown for this track:
 [ -x "$DRAFT_TOOLS/fix-whitespace.sh" ] && bash "$DRAFT_TOOLS/fix-whitespace.sh" --track <id>
@@ -452,7 +466,7 @@ references, sunset criteria) survive every regenerate. After rewriting:
 2. Update plan.md `generated_at:` to the current ISO-8601 timestamp.
 3. Ensure plan.md `generated_at` ≥ sibling hld.md / lld.md `generated_at`
    (the hygiene validator fails on stale plan).
-4. Run `scripts/tools/check-track-hygiene.sh <track_dir>` and resolve any
+4. Run `"$DRAFT_TOOLS/check-track-hygiene.sh" <track_dir>` and resolve any
    findings before promoting status past `draft`.
 
 If the plan does not yet have the bracket markers (pre-2.0 track), insert
@@ -648,8 +662,11 @@ As the last step after the completion announcement, emit a metrics record. Best-
 
 **Emit call:**
 ```bash
-DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
-[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
+# is not exported into skill Bash). See core/shared/tool-resolver.md.
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
 [ -x "$DRAFT_TOOLS/emit-skill-metrics.sh" ] && bash "$DRAFT_TOOLS/emit-skill-metrics.sh" \
   '{"skill":"decompose","scope":"<scope>","track_id":"<id_or_null>","modules_count":<N>,"lld_generated":<bool>,"high_complexity_modules":<N>}'

package/skills/deep-review/SKILL.md

@@ -11,10 +11,20 @@ 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 `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. Run `scripts/tools/hotspot-rank.sh --repo .` to identify high-fanIn files inside the module — these get deeper inspection.
+First resolve the bundled helpers:
+```bash
+# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
+# is not exported into skill Bash). See core/shared/tool-resolver.md.
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+```
+
+1. Use `"$DRAFT_TOOLS/graph-impact.sh"`/`graph-callers.sh` and `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for the audited module's structure — do not enumerate via `find`.
+2. Run `"$DRAFT_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 `"$DRAFT_TOOLS/cycle-detect.sh" --repo .` and flag any cycle that includes the audited module as Architecture Resilience finding.
+4. Run `"$DRAFT_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.
 
@@ -318,8 +328,11 @@ As the last step after saving the deep-review report, emit a metrics record. Bes
 
 **Emit call:**
 ```bash
-DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
-[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
+# is not exported into skill Bash). See core/shared/tool-resolver.md.
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
 [ -x "$DRAFT_TOOLS/emit-skill-metrics.sh" ] && bash "$DRAFT_TOOLS/emit-skill-metrics.sh" \
   '{"skill":"deep-review","module":"<module>","phases_completed":<N>,"critical_count":<N>,"important_count":<N>,"sec_violations":<N>,"acid_violations":<N>,"graph_queries":<N>,"fallback_grep_count":<N>}'

package/skills/deploy-checklist/SKILL.md

@@ -11,9 +11,9 @@ 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 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.
+1. For each file in the deploy diff, run `"$DRAFT_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 `"$DRAFT_TOOLS/cycle-detect.sh" --repo .` (and query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off.
+3. Run `"$DRAFT_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.
 
@@ -67,8 +67,9 @@ by validator.
 ```bash
 TRACK_DIR="$1" # absolute path to track-under-deploy, or .
 
-DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
-[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
 [ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
 
 "$DRAFT_TOOLS/check-track-hygiene.sh" "$TRACK_DIR" || rc=$?

package/skills/graph/SKILL.md

@@ -33,6 +33,15 @@ if [ ! -d "$REPO" ]; then
 fi
 REPO_ABS="$(cd "$REPO" && pwd)"
 echo "Target repo: $REPO_ABS"
+
+# Locate Draft's bundled helpers. Skills run with cwd = the user's project and
+# ${CLAUDE_PLUGIN_ROOT} is not exported into skill Bash, so resolve DRAFT_TOOLS here
+# and call helpers as "$DRAFT_TOOLS/<tool>.sh". See core/shared/tool-resolver.md.
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+DRAFT_SCRIPTS="${DRAFT_TOOLS%/tools}"   # parent dir holds fetch-memory-engine.sh
 ```
 
 ## Step 2: Ensure the engine is present
@@ -40,12 +49,12 @@ echo "Target repo: $REPO_ABS"
 Resolve the engine; if it is missing, fetch it once, then re-check. If it is still unavailable (e.g. offline, opted out via `DRAFT_MEMORY_DISABLE`), report and stop gracefully — graph features are optional everywhere in Draft.
 
 ```bash
-if ! scripts/tools/verify-graph-binary.sh --repo "$REPO_ABS" --json 2>/dev/null | grep -q '"status":"ok"'; then
+if ! "$DRAFT_TOOLS/verify-graph-binary.sh" --repo "$REPO_ABS" --json 2>/dev/null | grep -q '"status":"ok"'; then
   echo "Graph engine not found — attempting to fetch it..."
-  scripts/fetch-memory-engine.sh || true
+  "$DRAFT_SCRIPTS/fetch-memory-engine.sh" || true
 fi
 
-ENGINE="$(scripts/tools/verify-graph-binary.sh --repo "$REPO_ABS" --json 2>/dev/null || true)"
+ENGINE="$("$DRAFT_TOOLS/verify-graph-binary.sh" --repo "$REPO_ABS" --json 2>/dev/null || true)"
 if ! echo "$ENGINE" | grep -q '"status":"ok"'; then
   echo "Graph engine unavailable — skipping. Install with scripts/fetch-memory-engine.sh, or unset DRAFT_MEMORY_DISABLE."
   exit 0
@@ -58,7 +67,7 @@ echo "Engine: $ENGINE"
 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"
+"$DRAFT_TOOLS/graph-snapshot.sh" --repo "$REPO_ABS"
 ```
 
 If this exits non-zero, the engine became unavailable mid-run — report it and stop; do not fabricate results.
@@ -72,10 +81,10 @@ echo "--- Snapshot ---"
 cat "$REPO_ABS/draft/graph/schema.yaml"
 
 echo "--- Top hotspots ---"
-scripts/tools/hotspot-rank.sh --repo "$REPO_ABS" --top 5
+"$DRAFT_TOOLS/hotspot-rank.sh" --repo "$REPO_ABS" --top 5
 
 echo "--- Cycles ---"
-scripts/tools/cycle-detect.sh --repo "$REPO_ABS"
+"$DRAFT_TOOLS/cycle-detect.sh" --repo "$REPO_ABS"
 
 echo "--- Snapshot state ---"
 git -C "$REPO_ABS" rev-parse --short HEAD 2>/dev/null \

package/skills/impact/SKILL.md

@@ -16,11 +16,22 @@ Generate a project-wide impact report measuring Context-Driven Development effec
 
 ## Execution Constraints
 
+First resolve the bundled helpers:
+
+```bash
+# Locate Draft's bundled helpers (cwd is the user's project; ${CLAUDE_PLUGIN_ROOT}
+# is not exported into skill Bash). See core/shared/tool-resolver.md.
+DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/cache/*/draft/*/scripts/tools 2>/dev/null | sort -V | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$(ls -d ~/.claude/plugins/marketplaces/*draft*/scripts/tools 2>/dev/null | tail -1)"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+```
+
 1. **Load Track State:**
    - Read all `draft/tracks.md` entries.
    - For each track, read `metadata.json` to extract: `created_at`, `updated`, `status`, phase counts, task counts, `scope_includes`, `scope_excludes`.
    - If no tracks exist, report "No tracks found. Run `/draft:new-track` to create your first track."
-   - Run `scripts/tools/check-scope-conflicts.sh` to surface adjacent
+   - Run `"$DRAFT_TOOLS/check-scope-conflicts.sh"` to surface adjacent
      tracks sharing scope tags — duplicate effort signals in impact
      reporting. Schema:
      [core/shared/template-contract.md](../../core/shared/template-contract.md).