@drafthq/draft 3.2.0 → 3.2.1

package/package.json

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

@@ -186,6 +186,7 @@ TOOLS=(
     "verify-citations.sh"
     "verify-doc-anchors.sh"
     "verify-graph-binary.sh"
+    "resolve-tools.sh"
 )
 
 # ─────────────────────────────────────────────────────────

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).

package/skills/implement/SKILL.md

@@ -133,9 +133,21 @@ If one of these applies, route directly to the specialist workflow and stop this
    - Keep matching invariants as **active constraints** for this task — these govern code generation, not just review
    - If invariants reference lock ordering, fail-closed behavior, or data integrity rules: these are non-negotiable during implementation
 9. **Load graph context** (if `draft/graph/schema.yaml` exists):
-   - Run `scripts/tools/hotspot-rank.sh --repo .` — check if any files this task will modify appear as hotspots
+
+   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"
+   ```
+
+   - Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — check if any files this task will modify appear as hotspots
    - If modifying a hotspot file (high fanIn), warn: "This task modifies {file} (fanIn={N}). Changes here affect many downstream files. Consider running a graph impact query."
-   - Query `scripts/tools/graph-impact.sh`/`graph-callers.sh` for the module(s) being modified — gives file-level dependency context
+   - Query `"$DRAFT_TOOLS/graph-impact.sh"`/`"$DRAFT_TOOLS/graph-callers.sh"` for the module(s) being modified — gives file-level dependency context
    - See `core/shared/graph-query.md` for on-demand query subroutines (callers, impact)
 10. Update the track's entry in `draft/tracks.md` from `[ ]` to `[~]` In Progress
 
@@ -625,9 +637,13 @@ After a phase passes review, refresh `metadata.json.impact` so future tracks can
    ```
    That is the `files_touched` list. Derive `modules_touched` as the unique top-level path segments (e.g. `auth/login.go` → `auth`).
 
-2. **Compute downstream blast radius (graph-aware, optional):** If `draft/graph/schema.yaml` exists, for each file in `files_touched` query:
+2. **Compute downstream blast radius (graph-aware, optional):** If `draft/graph/schema.yaml` exists, for each file in `files_touched` query (this runs in its own Bash session — re-resolve the helpers):
    ```bash
-   scripts/tools/graph-impact.sh --repo . --file <path>
+   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/graph-impact.sh" --repo . --file <path>
    ```
    Aggregate across all files: `downstream_files` = total unique downstream files (deduped), `downstream_modules` = union of `affected_modules`, `max_depth` = max across queries, `by_category` = sum of each query's `by_category`. If the graph is absent, leave these fields as zeros / empty arrays — the snapshot still records the directly-touched files.
 

package/skills/init/SKILL.md

@@ -491,8 +491,15 @@ The knowledge-graph engine `codebase-memory-mcp` is Draft's **default** capabili
 One command resolves ROOT, ensures the engine, builds the whole-repo spine, and — in a sub-module — builds the module snapshot and writes the `root-link.json` pointer:
 
 ```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"
+
 # Add --module-only to skip touching the root (link marked "pending").
-if scripts/tools/graph-init.sh --scope .; then
+if "$DRAFT_TOOLS/graph-init.sh" --scope .; then
     echo "Graph memory ready under draft/graph/ (the root spine is the structural source of truth)."
 else
     echo "Graph engine unavailable — proceeding with degraded manual discovery. Downstream skills degrade gracefully."
@@ -506,7 +513,7 @@ fi
 Optionally record which engine was selected (usage-report contract):
 
 ```bash
-scripts/tools/verify-graph-binary.sh --repo . --json 2>/dev/null || true
+"$DRAFT_TOOLS/verify-graph-binary.sh" --repo . --json 2>/dev/null || true
 ```
 
 See `core/shared/graph-query.md` and `bin/README.md` for the query contract and engine resolution.
@@ -518,13 +525,13 @@ If indexing succeeds, `draft/graph/schema.yaml` is written and later steps query
 Pull the architecture view once and reuse it across phases:
 
 ```bash
-ARCH=$(scripts/tools/graph-arch.sh --repo .)
+ARCH=$("$DRAFT_TOOLS/graph-arch.sh" --repo .)
 ```
 
 - `$ARCH | jq '.packages'` — module list with fan-in/out
 - `$ARCH | jq '.routes'` — detected service endpoints
 - `$ARCH | jq '.languages, .node_labels, .layers, .boundaries'` — language mix, node shape, layering
-- `scripts/tools/hotspot-rank.sh --repo . --top 20` — complexity/fan-in hotspots (live)
+- `"$DRAFT_TOOLS/hotspot-rank.sh" --repo . --top 20` — complexity/fan-in hotspots (live)
 
 ### 3. Use graph data to accelerate Step 1.5
 
@@ -556,7 +563,7 @@ Apply tier table:
 Hold tier in memory. This governs: architecture.md length minimum, .ai-context.md budget, and module deep-dive depth.
 
 **Step 1.4.6 — Build Module Priority List:**
-From `scripts/tools/hotspot-rank.sh --repo .`: count hotspot symbols per module.
+From `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .`: count hotspot symbols per module.
 From `$ARCH | jq '.packages[]'`: read `fan_in` per module.
 Rank modules by: `(hotspot_count × 2) + fan_in_count`.
 Top-ranked modules drive Section 6 deep-dive ordering and depth. Modules ranked zero on both: summary treatment only.
@@ -567,7 +574,7 @@ Query for diagram content and write into architecture.md slots using the standar
 
 For Section 4.4 (module-deps slot):
 ```bash
-scripts/tools/mermaid-from-graph.sh --repo . --diagram module-deps
+"$DRAFT_TOOLS/mermaid-from-graph.sh" --repo . --diagram module-deps
 ```
 The tool emits a ready-to-inject ` ```mermaid ``` ` block (or an empty stub on exit 2). Write between the markers:
 ```
@@ -577,7 +584,7 @@ The tool emits a ready-to-inject ` ```mermaid ``` ` block (or an empty stub on e
 ```
 
 For Section 20 (hotspots slot):
-Run `scripts/tools/hotspot-rank.sh --repo . --top 10`, take the top 10 by fanIn, build a markdown table:
+Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo . --top 10`, take the top 10 by fanIn, build a markdown table:
 ```
 <!-- GRAPH:hotspots:START -->
 | Symbol | fanIn |
@@ -589,7 +596,7 @@ Run `scripts/tools/hotspot-rank.sh --repo . --top 10`, take the top 10 by fanIn,
 
 For Appendix E (proto-map slot):
 ```bash
-scripts/tools/mermaid-from-graph.sh --repo . --diagram proto-map
+"$DRAFT_TOOLS/mermaid-from-graph.sh" --repo . --diagram proto-map
 ```
 The tool emits a ` ```mermaid ``` ` block from detected routes (empty stub if none). Write:
 ```
@@ -666,7 +673,7 @@ For tier 3+, readers run simultaneously; wall clock = slowest reader, not the su
 The engine is already indexed. Query it live throughout this protocol (reuse `$ARCH` from Step 1.4.2):
 - `$ARCH | jq '.packages'` — module list with `.fan_in`/`.fan_out` (for grouping)
 - `$ARCH | jq '.languages, .node_labels'` — file/symbol counts, tier metrics
-- `scripts/tools/hotspot-rank.sh --repo .` — top hotspot symbols per module (feed to readers)
+- `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — top hotspot symbols per module (feed to readers)
 
 #### Phase 1: Spawn Parallel Module Readers
 
@@ -793,7 +800,7 @@ If any reader agent fails to produce valid JSON after one retry:
 When the Agent tool is unavailable or reader agents fail after retry, write `draft/architecture.md` using the **10-section graph-primary structure** (checklist above + `core/templates/architecture.md`). Do not use legacy 28-section or Pass 1/2/3 volume protocols.
 
 1. Use the ranked module list from Step 1.4.6 (graph-first — do not re-scan by directory if Phase 0 succeeded).
-2. For each top module (up to 20 by fan-in), query the engine for its symbols/callers (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, or `$ARCH | jq '.packages[] | select(.name=="<m>")'`), read the hotspot files and 3–5 key sources; embed graph blocks and at least one workflow/state diagram per significant module inside §4–§8 as appropriate.
+2. For each top module (up to 20 by fan-in), query the engine for its symbols/callers (`"$DRAFT_TOOLS/graph-callers.sh"`, `"$DRAFT_TOOLS/graph-impact.sh"`, or `$ARCH | jq '.packages[] | select(.name=="<m>")'`), read the hotspot files and 3–5 key sources; embed graph blocks and at least one workflow/state diagram per significant module inside §4–§8 as appropriate.
 3. Always include §9 Graph Coverage Gaps and §10 Relationship when the Context Audit requires them.
 4. Run Completion Verification (defined later in this skill) before condensation. Fidelity, provenance, and gap honesty block completion — not line counts.