@drafthq/draft 3.1.5 → 3.2.1

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "draft",
       "source": "./",
       "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-      "version": "3.0.0",
+      "version": "3.2.1",
       "author": {
         "name": "mayurpise"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.1.5",
+  "version": "3.2.1",
   "author": {
     "name": "mayurpise"
   },

package/cli/src/hosts/claude-code.js

@@ -56,7 +56,10 @@ module.exports = {
       ],
       graph: true, // fetch the graph engine at install time (/draft:init also fetches on first use as a fallback)
       done: 'Installed/updated draft. Restart Claude Code (or start a new session), then run /draft:init.',
-      fallbackTitle: 'Claude Code CLI not found. Run these in Claude Code instead:',
+      // Shown when the `claude` CLI is absent OR a step fails: the in-session
+      // /plugin commands work without the terminal CLI on PATH.
+      onFailHint: 'If that failed with "unknown command", your Claude Code is too old for the `claude plugin` command — run "claude update" (or upgrade the app), then re-run.',
+      fallbackTitle: 'Run these inside a Claude Code session instead (or put the `claude` CLI on your PATH and re-run):',
       fallback: [
         '/plugin marketplace add drafthq/draft',
         '/plugin marketplace update draft-plugins',

package/cli/src/installer.js

@@ -4,10 +4,15 @@ const { spawnSync } = require('child_process');
 const fsx = require('./lib/fsx');
 const log = require('./lib/log');
 const { fetchGraph } = require('./lib/graph');
+const { writePluginRootMarker } = require('./lib/marker');
+
+// A short ceiling so a wedged `claude --version` can't hang the installer
+// before we even reach the real (separately-timed) install steps.
+const CHECK_TIMEOUT_MS = 10000;
 
 function hasBinary(name) {
   // ENOENT on the error means the binary is not on PATH.
-  const r = spawnSync(name, ['--version'], { stdio: 'ignore' });
+  const r = spawnSync(name, ['--version'], { stdio: 'ignore', timeout: CHECK_TIMEOUT_MS });
   return !(r.error && r.error.code === 'ENOENT');
 }
 
@@ -59,12 +64,14 @@ function install(host, ctx) {
   const plan = host.plan(ctx);
   log.step(`Installing Draft -> ${host.label}  [${plan.targetSummary}]${ctx.dryRun ? '  (dry run)' : ''}`);
 
-  // A plan may require an external CLI (e.g. claude). If it's missing, print
-  // the manual fallback and stop — but only when actually installing; a
-  // dry run still shows the planned commands.
+  // A plan may require an external CLI (e.g. claude). If it's missing, say so
+  // loudly, print the manual fallback, and exit non-zero — a no-op must never
+  // read as success. Only enforced on a real install; a dry run still shows the
+  // planned commands.
   if (plan.requires && !ctx.dryRun && !hasBinary(plan.requires)) {
+    log.error(`Cannot auto-install: the "${plan.requires}" CLI is not on your PATH. Nothing was installed.`);
     printFallback(plan);
-    return 0;
+    return 1;
   }
 
   // Pre-flight: for file copies, every bundled source must exist and guarded
@@ -88,6 +95,7 @@ function install(host, ctx) {
       const code = execAction(act, ctx);
       if (code !== 0) {
         log.error(`Step failed (exit ${code}): ${act.label || act.cmd}`);
+        if (plan.onFailHint) log.error(plan.onFailHint);
         if (plan.fallback) printFallback(plan);
         return code;
       }
@@ -100,6 +108,13 @@ function install(host, ctx) {
     fetchGraph(ctx);
   }
 
+  // Record the install path so skills can locate scripts/tools/ from the user's
+  // project cwd (best-effort; graph skills glob-fallback if the marker is absent).
+  if (!ctx.dryRun) {
+    const root = writePluginRootMarker(host.id);
+    if (root) log.note(`Recorded plugin path for graph tooling: ${root}`);
+  }
+
   (plan.notes || []).forEach((n) => log.note(n));
 
   if (ctx.dryRun) {

package/cli/src/lib/marker.js

@@ -0,0 +1,93 @@
+'use strict';
+
+// Write the install-path marker (~/.cache/draft/plugin-root) so a draft skill can
+// locate its bundled scripts/tools/ from the user's project cwd. Skills run with
+// cwd = the user's project and ${CLAUDE_PLUGIN_ROOT} is NOT exported into skill Bash,
+// so without this marker resolution falls back to globbing the plugin cache. The
+// marker is the fast, authoritative path; see core/shared/tool-resolver.md.
+//
+// Best-effort: any failure is swallowed — graph skills still resolve via the glob
+// fallback, so a missing marker is never fatal.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Resolve the installed draft plugin root for a given host, or null if unknown.
+function resolvePluginRoot(hostId) {
+  const home = os.homedir();
+
+  if (hostId === 'claude-code') {
+    // 1. Claude Code's own registry holds the authoritative installPath.
+    const reg = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
+    try {
+      const data = JSON.parse(fs.readFileSync(reg, 'utf8'));
+      const key = Object.keys(data.plugins || {}).find((k) => k.startsWith('draft@'));
+      const ip = key && data.plugins[key] && data.plugins[key][0] && data.plugins[key][0].installPath;
+      if (ip && fs.existsSync(path.join(ip, 'scripts', 'tools'))) return ip;
+    } catch {
+      /* registry missing or unparseable — fall through to the cache scan */
+    }
+    // 2. Fallback: newest versioned dir under the plugin cache.
+    return newestCacheRoot(path.join(home, '.claude', 'plugins', 'cache'));
+  }
+
+  if (hostId === 'cursor') {
+    const p = path.join(home, '.cursor', 'plugins', 'local', 'draft');
+    return fs.existsSync(path.join(p, 'scripts', 'tools')) ? p : null;
+  }
+
+  return null;
+}
+
+// Newest <cache>/<marketplace>/draft/<version> dir that carries scripts/tools.
+function newestCacheRoot(cacheDir) {
+  try {
+    const candidates = [];
+    for (const mkt of fs.readdirSync(cacheDir)) {
+      const draftDir = path.join(cacheDir, mkt, 'draft');
+      let versions;
+      try {
+        versions = fs.readdirSync(draftDir);
+      } catch {
+        continue;
+      }
+      for (const v of versions) {
+        const root = path.join(draftDir, v);
+        if (fs.existsSync(path.join(root, 'scripts', 'tools'))) candidates.push({ v, root });
+      }
+    }
+    if (!candidates.length) return null;
+    candidates.sort((a, b) => compareVersions(a.v, b.v));
+    return candidates[candidates.length - 1].root;
+  } catch {
+    return null;
+  }
+}
+
+// Numeric-aware version compare (no semver dependency).
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map((n) => parseInt(n, 10) || 0);
+  const pb = String(b).split('.').map((n) => parseInt(n, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d;
+  }
+  return 0;
+}
+
+// Write ~/.cache/draft/plugin-root for the host. Returns the path written, or null.
+function writePluginRootMarker(hostId) {
+  try {
+    const root = resolvePluginRoot(hostId);
+    if (!root) return null;
+    const dest = path.join(os.homedir(), '.cache', 'draft', 'plugin-root');
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.writeFileSync(dest, root + '\n');
+    return root;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { writePluginRootMarker, resolvePluginRoot };

package/core/shared/condensation.md

@@ -180,8 +180,9 @@ Write the completed content to `draft/.ai-context.md`.
 After writing both output files, strip trailing whitespace and blank lines at EOF to prevent GitHub upload failures. Resolve the script via the canonical tool resolver (see [tool-resolver.md](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/fix-whitespace.sh" ] && bash "$DRAFT_TOOLS/fix-whitespace.sh" draft/architecture.md draft/.ai-context.md draft/.ai-profile.md 2>/dev/null || true
 ```

package/core/shared/git-report-metadata.md

@@ -16,8 +16,9 @@ Referenced by: All skills that generate Draft reports — including `/draft:bugh
 Use `git-metadata.sh` from the plugin install, resolved via the canonical tool resolver (see [tool-resolver.md](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"
 bash "$DRAFT_TOOLS/git-metadata.sh" --yaml \
     --project "$PROJECT" --module "$MODULE" \

package/core/shared/graph-query.md

@@ -55,7 +55,7 @@ A single "no" / "list" answer is a halt — fix and re-check before output.
 
 Use this recipe whenever the user names a concept, feature, or domain term ("in-memory shuffle", "auth flow", "ingest pipeline") and you need to locate the implementing files. **Run it before any filesystem search.**
 
-1. **Concept → modules** — query the engine for the package list (`scripts/tools/graph-arch.sh --repo . | jq -r '.packages[].name'`) and cross-reference `draft/.ai-context.md` (module headings). Record the candidate module list.
+1. **Concept → modules** — query the engine for the package list (`scripts/tools/graph-arch.sh --repo . | jq -r '.packages[].name'`) and cross-reference `draft/.ai-context.md` (module headings). Record the candidate module list. For an **intent/concept** name (not an exact symbol), start with semantic search: `scripts/tools/graph-search.sh --repo . --query "<concept>"` returns ranked candidate symbols directly.
 2. **Concept → symbols/callers** — for a named function, run `scripts/tools/graph-callers.sh --repo . --symbol <name>` to find call sites, and `scripts/tools/graph-impact.sh --repo . --symbol <name>` for transitive dependents. These are the authoritative structural answers.
 3. **Modules → risk ranking** — rank with `scripts/tools/hotspot-rank.sh --repo . [--top N]`. High-fanIn symbols are the most likely entry points for impact.
 4. **Concept → public API** — for API-shaped concepts, read the engine's `.routes` (`get_architecture` output, detected HTTP/gRPC/GraphQL routes) for matching service surface.
@@ -92,22 +92,87 @@ These fields are appended to `~/.draft/metrics.jsonl` along with the existing sk
 
 ## Tooling Wrappers
 
-For common query modes, prefer the deterministic wrappers that ship with the plugin. Resolve their location via the canonical tool resolver (see [tool-resolver.md](tool-resolver.md)) before invoking:
+For common query modes, prefer the deterministic wrappers that ship with the plugin. Resolve their location via the canonical tool resolver (see [tool-resolver.md](tool-resolver.md)) before invoking. Skills run with cwd = the user's project and `${CLAUDE_PLUGIN_ROOT}` is **not** exported into skill Bash, so a bare `scripts/tools/foo.sh` fails — establish `DRAFT_TOOLS` once before the first helper call, in the same Bash session as your tool calls (re-establish it if you split helper calls into a separate, later Bash block):
 
 ```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"
 ```
 
 | Wrapper | Graph mode | Behavior on missing graph |
 |---|---|---|
-| `bash "$DRAFT_TOOLS/hotspot-rank.sh" [--top N] [--module NAME]` | `--mode hotspots` | Emits `{hotspots:[],source:"unavailable"}` and exits 2 |
-| `bash "$DRAFT_TOOLS/cycle-detect.sh"` | `--mode cycles` | Emits `{cycles:[],source:"unavailable"}` and exits 2 |
-| `bash "$DRAFT_TOOLS/mermaid-from-graph.sh" [--diagram module-deps\|proto-map]` | `--mode mermaid` | Emits an empty mermaid block and exits 2 |
+| `bash "$DRAFT_TOOLS/hotspot-rank.sh" [--top N]` | complexity-weighted hotspots | Emits `{hotspots:[],source:"unavailable"}` and exits 2 |
+| `bash "$DRAFT_TOOLS/cycle-detect.sh"` | call cycles | Emits `{cycles:[],source:"unavailable"}` and exits 2 |
+| `bash "$DRAFT_TOOLS/mermaid-from-graph.sh" [--diagram module-deps\|co-change\|proto-map]` | diagram text | Emits an empty mermaid block and exits 2 |
+| `bash "$DRAFT_TOOLS/graph-callers.sh" --symbol N [--transitive[=N]] [--prod-only] [--qualified]` | callers | `{callers:[],status:"unavailable",source:"unavailable"}`, exit 2 |
+| `bash "$DRAFT_TOOLS/graph-snippet.sh" --qualified N` | verified source + caller/callee counts | `{status:"unavailable",source:"unavailable"}`, exit 2 |
+| `bash "$DRAFT_TOOLS/graph-search.sh" --query "STR" [--limit N]` | semantic/ranked search | `{results:[],source:"unavailable"}`, exit 2 |
+| `bash "$DRAFT_TOOLS/graph-tests.sh" (--symbol N \| --untested)` | test→symbol coverage | `{tests:[]/untested:[],source:"unavailable"}`, exit 2 |
+| `bash "$DRAFT_TOOLS/graph-deps.sh" [--file PATH]` | real IMPORTS graph | `{imports:[],source:"unavailable"}`, exit 2 |
+| `bash "$DRAFT_TOOLS/graph-hierarchy.sh" [--symbol N \| --derived N]` | INHERITS tree | `{edges:[],source:"unavailable"}`, exit 2 |
+| `bash "$DRAFT_TOOLS/graph-errors.sh" (--symbol N \| --type N)` | RAISES/THROWS | `{raises:[]/raisers:[],source:"unavailable"}`, exit 2 |
+| `bash "$DRAFT_TOOLS/graph-risk.sh" [--min-complexity N]` | pre-computed risk flags | `{risky:[],source:"unavailable"}`, exit 2 |
+| `bash "$DRAFT_TOOLS/graph-query.sh" (--cypher STR \| --tool NAME --json '{...}')` | generic read-only passthrough | `{source:"unavailable"}`, exit 2 |
+| `bash "$DRAFT_TOOLS/graph-traces.sh" ingest --file F --experimental` | runtime traces (experimental write) | `{source:"unavailable"}`, exit 2 |
 
 For lower-level modes, call the engine directly: `codebase-memory-mcp cli <tool> '<json>'` (see the tool list in [bin/README.md](../../bin/README.md)).
 
+### Capability wrappers & dialect limits (graph-tooling-v2)
+
+All Cypher lives in `scripts/tools/_graph_queries.sh` (the single source of query
+truth). Wrappers are thin arg-parse → builder → fail-loud JSON. Three contracts
+matter when consuming them:
+
+**Fail-loud status.** Symbol-scoped wrappers (`graph-callers`, `graph-snippet`,
+`graph-tests --symbol`, `graph-hierarchy --symbol/--derived`, `graph-errors`)
+emit a `status` field that distinguishes the three real outcomes — never read a
+bare `[]` as a confirmed true negative:
+
+| `status` | Meaning |
+|---|---|
+| `ok` | node found, edges returned |
+| `no-edges` | node exists but has no matching edge (a *real* negative) |
+| `no-match` | the named symbol was not found at all (check the name / try `--qualified`) |
+| `unavailable` | engine could not be resolved (exit 2) |
+
+**Verified engine param shapes** (engine v0.8.x — the runtime source of truth is
+`get_graph_schema`; do not hardcode a property set):
+
+```bash
+get_code_snippet '{"project":P,"qualified_name":"pkg.Mod.Class.method"}'   # → source + callers/callees counts + transitive_loop_depth
+search_graph     '{"project":P,"query":"order submission to broker","limit":5}'  # → {results:[{name,qualified_name,label,file_path,rank}]}
+trace_path       '{"project":P,"function_name":"submit_order","depth":3,"direction":"both"}'  # depth-bounded caller EXPANDER, not an A→B pathfinder
+detect_changes   '{"project":P}'    # → {changed_files, changed_count, impacted_symbols, depth}
+get_graph_schema '{"project":P}'    # → {node_labels:[{label,count,properties}], edge_types:[{type,count}]}
+```
+
+**Cypher dialect — keep queries inside the SAFE set:**
+
+- ✅ SAFE: fixed-length patterns, single/multi-hop explicit patterns, `=`, `<`,
+  `STARTS WITH`, `NOT x STARTS WITH`, `AND`, `OR`, relationship-type alternation
+  `[:A|B]`, simple `count(x)`.
+- ❌ UNSAFE (rejected or silently empty): `coalesce()`, `<>` / `!=` / `<=` / `>=`,
+  `NOT EXISTS(...)`, `NOT (pattern)`, `WITH`-grouping aggregation, multi-pattern
+  joins. `graph-query.sh --cypher` returns the engine's raw error, not a silent
+  empty — but the builders never emit these forms.
+
+**Caveats consumers must respect:**
+
+- **`--prod-only` is best-effort.** It filters `is_test=false AND NOT file_path
+  STARTS WITH 'tests/'`. `is_test` is partially populated by the engine, so test
+  helpers/mocks can leak through. Treat it as a heuristic, not a guarantee.
+- **`--transitive` uses the `trace_path` expander** (a depth-bounded caller
+  expansion from one symbol), not a from→to pathfinder. "Path between A and B"
+  still needs an explicit fixed-length `graph-query.sh --cypher` pattern.
+- **Honest caps.** `cycle-detect`, `graph-deps`, `graph-risk`, `graph-tests
+  --untested` cap their output and report `"truncated": true` when the cap is
+  hit — results are a sample, not exhaustive.
+- **`graph-tests --untested`** is a set difference (exported symbols minus TESTS
+  targets) because the dialect has no anti-join; coverage depends on the engine
+  resolving test→symbol links, which varies by language/framework.
+
 ## Pre-Check
 
 Verify graph data exists before any graph operation:
@@ -196,13 +261,80 @@ scripts/tools/mermaid-from-graph.sh --repo . --diagram proto-map     # detected
 
 Emits a ready-to-inject ` ```mermaid ``` ` block on the fly (computed live by the engine), or an empty stub (exit 2) when the engine is unavailable. Diagrams are generated at the moment of use — they are never committed.
 
+### Snippet — verified source + caller/callee counts
+
+```bash
+scripts/tools/graph-snippet.sh --repo . --qualified <pkg.Mod.Class.method>
+```
+
+Output: `{qualified_name, file, start_line, end_line, callers, callees, transitive_loop_depth, complexity, code, status, source}`. Prefer this over grep+Read when you have a qualified name — it returns the engine's attributed source plus pre-computed counts.
+
+### Search — semantic / ranked symbol lookup
+
+```bash
+scripts/tools/graph-search.sh --repo . --query "auth token refresh" [--limit N]
+```
+
+Output: `{query, results[{name, qualified_name, label, file, rank}], total, source}`. Use when the user names an **intent/concept** rather than an exact symbol — this is the first move in the Concept-to-Files recipe.
+
+### Tests — coverage edges and untested surface
+
+```bash
+scripts/tools/graph-tests.sh --repo . --symbol <name>     # tests covering a symbol
+scripts/tools/graph-tests.sh --repo . --untested          # exported symbols with no TESTS edge
+```
+
+Output: `{symbol, tests[{test,file}], status, source}` or `{untested[{symbol,file}], total, truncated, source}`. Feeds coverage gaps for `init`/`testing-strategy`/`coverage`.
+
+### Deps — real module/file import graph
+
+```bash
+scripts/tools/graph-deps.sh --repo . [--file PATH]
+```
+
+Output: `{imports[{src,dst}], total, truncated, source}` from actual `IMPORTS` edges (self-imports filtered). This is the auto-derived dependency graph behind `mermaid-from-graph.sh --diagram module-deps` and `architecture.md §9`.
+
+### Hierarchy — class inheritance
+
+```bash
+scripts/tools/graph-hierarchy.sh --repo . [--symbol <Class> | --derived <Base>]
+```
+
+Output: `{edges[{child,parent}], status, source}`. `--derived` gives the blast radius of changing a base class.
+
+### Errors — error-propagation paths
+
+```bash
+scripts/tools/graph-errors.sh --repo . --symbol <name>   # what it raises/throws
+scripts/tools/graph-errors.sh --repo . --type <ErrType>  # who raises/throws that type
+```
+
+Output: `{symbol, raises[...], status, source}` or `{type, raisers[...], status, source}`. `--type` drives fail-closed audits.
+
+### Risk — pre-computed risk hotspots
+
+```bash
+scripts/tools/graph-risk.sh --repo . [--min-complexity N]
+```
+
+Output: `{risky[{symbol, file, complexity, flags}], total, truncated, source}` from the engine's pre-computed flags (`unguarded_recursion`, `recursion_in_loop`, `alloc_in_loop`, `linear_scan_in_loop`). High-signal input for `bughunt`/`deep-review` — the engine already found these.
+
+### Generic — read-only escape hatch (all 20 edges / ~30 properties)
+
+```bash
+scripts/tools/graph-query.sh --repo . --cypher 'MATCH (f)-[:WRITES]->(v) RETURN f.name, v.name LIMIT 50'
+scripts/tools/graph-query.sh --repo . --tool get_graph_schema --json '{}'
+```
+
+Unlocks any edge type or node property without a purpose-built wrapper. Write verbs are rejected; stay inside the SAFE dialect set (above). Emits raw engine JSON.
+
 ### Indexing / refreshing the gate marker
 
 ```bash
 scripts/tools/graph-snapshot.sh --repo .
 ```
 
-Indexes the repo into the engine and writes the `draft/graph/schema.yaml` gate marker. It writes **no** graph data. Run during `/draft:init` and `/draft:graph`, or whenever the index should be refreshed.
+Indexes the repo into the engine and writes the `draft/graph/schema.yaml` gate marker (now including the `detect_changes` delta: `changed_files`/`impacted_symbols`). It writes **no** graph data. Run during `/draft:init` and `/draft:graph`, or whenever the index should be refreshed.
 
 ## Finding the Engine (Resolution + Usage Report)
 

package/core/shared/tool-resolver.md

@@ -1,10 +1,77 @@
 ---
 shared: tool-resolver
-applies_to: quality + init + graph skills
+applies_to: every skill that invokes scripts/tools/*
 ---
 
-# tool-resolver (Foundations Stub)
+# tool-resolver
 
-Portable generalized stub per manifest §2.1. Full content will be expanded in later agent tranche or manual follow-up.
+Canonical procedure for locating Draft's bundled shell helpers (`scripts/tools/*.sh`)
+from inside a skill.
 
-See verification-gates.md and template-hygiene.md for usage contracts.
+## Why this exists
+
+When Claude runs a draft skill, the shell's **working directory is the user's
+project**, not the plugin. The helpers live inside the plugin install directory,
+which on a marketplace/npm install is `~/.claude/plugins/cache/<marketplace>/draft/<version>/`
+— never the cwd. `${CLAUDE_PLUGIN_ROOT}` is **not** exported into skill-driven Bash
+(it is only set for hooks, MCP/LSP servers, and monitor commands), so a bare
+`scripts/tools/foo.sh` or `${CLAUDE_PLUGIN_ROOT}/...` invocation silently fails.
+
+Every skill MUST resolve `DRAFT_TOOLS` and invoke helpers as `"$DRAFT_TOOLS/<tool>.sh"`.
+
+## Resolution order
+
+`DRAFT_TOOLS` resolves to the first directory that exists, in this order:
+
+1. `${DRAFT_PLUGIN_ROOT}/scripts/tools` — explicit override (testing / pinned installs)
+2. `$(cat ~/.cache/draft/plugin-root)/scripts/tools` — install marker written by `draft install` (authoritative)
+3. `${CLAUDE_PLUGIN_ROOT}/scripts/tools` — set in hook/MCP contexts; harmless to probe
+4. `installed_plugins.json → installPath` for `draft@*` — Claude Code's own registry (needs `jq`)
+5. `~/.claude/plugins/cache/*/draft/*/scripts/tools` — newest cache install (glob, `sort -V`)
+6. `~/.claude/plugins/marketplaces/*draft*/scripts/tools` — marketplace clone
+7. `~/.cursor/plugins/local/draft/scripts/tools` — Cursor local install
+8. `$PWD/scripts/tools` — dev / dogfooding (running inside the draft repo itself)
+
+The marker (step 2) is the fast, authoritative path; steps 5–6 are the glob fallback
+that keeps resolution working on installs predating the marker (no reinstall required).
+
+## Skill preamble (copy verbatim)
+
+Establish `DRAFT_TOOLS` once, before the first helper call, in the **same Bash
+session** that runs your tool calls — exactly as skills already define `REPO_ABS`
+once and reuse it. Env vars do not persist across **separate** Bash tool
+invocations (only the cwd does), so if you split helper calls into a later, separate
+Bash block, re-establish `DRAFT_TOOLS` there too:
+
+```bash
+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"
+```
+
+Then invoke helpers through the variable:
+
+```bash
+"$DRAFT_TOOLS/hotspot-rank.sh" --repo . --top 5
+"$DRAFT_TOOLS/graph-arch.sh"   --repo .
+```
+
+The four-line inline preamble is self-contained and is the recommended form for
+skills — it needs no marker file and no prior `source`. The full 8-step resolver
+(adding the `${DRAFT_PLUGIN_ROOT}` override, `${CLAUDE_PLUGIN_ROOT}`, the jq-registry
+lookup, and the Cursor path) is shipped as `scripts/tools/resolve-tools.sh` for tests
+and for callers that prefer a single source of truth:
+
+```bash
+DRAFT_TOOLS="$("$PWD/scripts/tools/resolve-tools.sh" 2>/dev/null)"   # dev/dogfood
+# installed: "$(cat ~/.cache/draft/plugin-root)/scripts/tools/resolve-tools.sh"
+```
+
+## The engine binary is separate
+
+`DRAFT_TOOLS` locates the **wrapper scripts**. Each wrapper then resolves the
+`codebase-memory-mcp` **engine binary** itself via `_lib.sh:find_memory_bin`
+(`DRAFT_MEMORY_BIN` → `$PATH` → `~/.cache/draft/bin/` → vendored). Do not conflate
+the two: a wrapper that runs but reports `source: unavailable` means the engine
+binary is missing, not the wrapper.

package/core/templates/plan.md

@@ -111,8 +111,9 @@ validator chain via the canonical resolver pattern (see
 [core/shared/verification-gates.md](../../core/shared/verification-gates.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"
 "$DRAFT_TOOLS/check-track-hygiene.sh" .; "$DRAFT_TOOLS/verify-citations.sh" .
 "$DRAFT_TOOLS/verify-doc-anchors.sh" .; "$DRAFT_TOOLS/check-graph-usage-report.sh" .