@drafthq/draft 3.2.0 → 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.2.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.2.0",
+  "version": "3.2.1",
   "author": {
     "name": "mayurpise"
   },

package/cli/src/installer.js

@@ -4,6 +4,7 @@ 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.
@@ -107,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

@@ -92,11 +92,12 @@ 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"
 ```
 

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