@drafthq/draft 3.7.2 → 4.0.0

package/.claude-plugin/marketplace.json

@@ -1,7 +1,8 @@
 {
   "name": "draft-plugins",
   "owner": {
-    "name": "mayurpise",
+    "name": "Mayur Pise",
+    "email": "mayur@getdraft.dev",
     "url": "https://github.com/mayurpise"
   },
   "metadata": {
@@ -12,9 +13,11 @@
       "name": "draft",
       "source": "./",
       "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-      "version": "3.7.2",
+      "version": "4.0.0",
       "author": {
-        "name": "mayurpise"
+        "name": "Mayur Pise",
+        "email": "mayur@getdraft.dev",
+        "url": "https://github.com/mayurpise"
       },
       "homepage": "https://github.com/drafthq/draft",
       "license": "MIT",

package/.claude-plugin/plugin.json

@@ -1,9 +1,11 @@
 {
   "name": "draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.7.2",
+  "version": "4.0.0",
   "author": {
-    "name": "mayurpise"
+    "name": "Mayur Pise",
+    "email": "mayur@getdraft.dev",
+    "url": "https://github.com/mayurpise"
   },
   "homepage": "https://github.com/drafthq/draft",
   "license": "MIT",

package/.cursor-plugin/plugin.json

@@ -2,11 +2,13 @@
   "name": "draft",
   "displayName": "Draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.7.2",
+  "version": "4.0.0",
   "skills": "./skills/",
   "agents": "./core/agents/",
   "author": {
-    "name": "mayurpise"
+    "name": "Mayur Pise",
+    "email": "mayur@getdraft.dev",
+    "url": "https://github.com/mayurpise"
   },
   "homepage": "https://github.com/drafthq/draft",
   "license": "MIT",

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Mayur Pise
+Copyright (c) 2025-2026 Mayur Pise
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -68,12 +68,12 @@ Each host installs the way that host actually loads extensions — no manual ste
 
 | Host | `draft install …` | What it does |
 |------|-------------------|--------------|
-| **Claude Code** | `claude-code` | Registers the plugin via `claude plugin marketplace add` + `claude plugin install` (user scope). Restart Claude Code. |
-| **Cursor** | `cursor` | Copies the plugin into `~/.cursor/plugins/local/draft/`, writes `.cursor-plugin/plugin.json`, registers `draft@draft-plugins` in Cursor's plugin registry, and enables it. Restart Cursor (or Developer: Reload Window). Existing installs upgrade with `draft install cursor --force`. |
-| **Codex** | `codex` | Writes `./AGENTS.md`, which Codex reads automatically. |
-| **opencode** | `opencode` | Writes `./AGENTS.md` + `~/.agents/skills/draft/`, both auto-discovered. |
+| **Claude Code** | `claude-code` | Registers the plugin via `claude plugin marketplace add` + `claude plugin install` (default `--global` / user scope). Restart Claude Code. |
+| **Cursor** | `cursor` | Default `--global`. Copies the plugin into `~/.cursor/plugins/local/draft/`, writes `.cursor-plugin/plugin.json`, registers `draft@draft-plugins` in Cursor's plugin registry, and enables it. Restart Cursor (or Developer: Reload Window). Existing installs upgrade with `draft install cursor --force`. |
+| **Codex** | `codex` | Default `--project`. Writes `./AGENTS.md`, which Codex reads automatically. |
+| **opencode** | `opencode` | Default `--project`. Writes `./AGENTS.md` + `~/.agents/skills/draft/`, both auto-discovered. |
 
-Flags: `--global` / `--project` to pick scope, `--dry-run` to preview, `--force` to overwrite, `--no-graph` to skip the graph-engine fetch.
+Flags: `--global` / `--project` to pick scope (`--global` is the default for `claude-code` and `cursor`; `--project` is the default for `codex` and `opencode`), `--dry-run` to preview, `--force` to overwrite, `--no-graph` to skip the graph-engine fetch.
 
 Then, in Claude Code (after restarting):
 
@@ -164,7 +164,7 @@ The graph powers `/draft:graph` and `/draft:impact`, enriches `/draft:bughunt` a
 
 ### Deterministic helper tools
 
-Skills also call into **shell helpers** under `scripts/tools/` for mechanical work — git metadata, file classification, test-framework detection, hotspot ranking, freshness checks, ADR indexing, and live graph queries (`graph-callers.sh`, `graph-impact.sh`, `hotspot-rank.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh`). All emit JSON or markdown, follow a uniform exit-code contract, and degrade gracefully when their input source is unavailable.
+Skills also call into **shell helpers** under `scripts/tools/` for mechanical work — git metadata, file classification, test-framework detection, hotspot ranking, freshness checks, ADR indexing, and live graph queries (`graph-callers.sh`, `graph-impact.sh`, `hotspot-rank.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh`). All emit JSON or markdown and follow a uniform exit-code contract. Graph wrappers fail loud: shapeless `{}` (no `.rows` array) is `source:"unavailable"` with a non-zero exit, not a measured empty result.
 
 ---
 
@@ -270,7 +270,7 @@ Each layer narrows the solution space. By the time AI writes code, decisions are
 
 ---
 
-<p align="center">MIT License &middot; Graph engine: <a href="https://github.com/DeusData/codebase-memory-mcp" target="_blank" rel="noopener noreferrer">codebase-memory-mcp</a> by <a href="https://github.com/DeusData" target="_blank" rel="noopener noreferrer">DeusData</a></p>
+<p align="center">MIT License &middot; Created &amp; maintained by <a href="https://www.linkedin.com/in/mayurpise/" target="_blank" rel="noopener noreferrer">Mayur Pise</a> &middot; Graph engine: <a href="https://github.com/DeusData/codebase-memory-mcp" target="_blank" rel="noopener noreferrer">codebase-memory-mcp</a> by <a href="https://github.com/DeusData" target="_blank" rel="noopener noreferrer">DeusData</a></p>
 
 <p align="center">
   <strong>Credits:</strong> Inspired by <a href="https://github.com/gemini-cli-extensions/conductor">gemini-cli-extensions/conductor</a>

package/bin/README.md

@@ -17,7 +17,7 @@ This installs the binary to the **Draft-managed location**:
 ~/.cache/draft/bin/codebase-memory-mcp
 ```
 
-The fetch script picks the right release archive for the host OS/arch, verifies its SHA-256 against the published `checksums.txt`, extracts it, and installs it there. `draft install claude-code` / `draft install cursor` run this automatically (best-effort, network-gated); skip it with `--no-graph`.
+The fetch script picks the right release archive for the host OS/arch, verifies its SHA-256 against the published `checksums.txt`, extracts it, and installs it there. Downloads pin `curl --proto '=https' --proto-redir '=https'` so a compromised redirect cannot downgrade to HTTP. `draft install claude-code` / `draft install cursor` run this automatically (best-effort, network-gated); skip it with `--no-graph`.
 
 ## Resolution order
 

package/cli/src/cli.js

@@ -47,8 +47,8 @@ Usage:
 Hosts: ${hosts.map((h) => h.id).join(', ')}
 
 Flags:
-  --global        Install to the user-level location (default for cursor)
-  --project       Install into the current project (default for claude-code, codex, opencode)
+  --global        Install to the user-level location (default for claude-code, cursor)
+  --project       Install into the current project (default for codex, opencode)
   --dry-run       Print planned writes without touching disk
   --no-graph      Skip the knowledge-graph engine fetch
   --force         Overwrite an existing target

package/cli/src/installer.js

@@ -15,9 +15,11 @@ const CHECK_TIMEOUT_MS = 10000;
 const USE_SHELL = process.platform === 'win32';
 
 function hasBinary(name) {
-  // ENOENT on the error means the binary is not on PATH.
+  // Windows `.cmd` shims (shell: true) report a missing binary as status 127
+  // with no `error`. Treat any spawn error or non-zero status as absent.
   const r = spawnSync(name, ['--version'], { stdio: 'ignore', timeout: CHECK_TIMEOUT_MS, shell: USE_SHELL });
-  return !(r.error && r.error.code === 'ENOENT');
+  if (r.error) return false;
+  return r.status === 0;
 }
 
 // Per-step ceiling so a stalled network op (e.g. the `git clone` behind

package/cli/src/lib/cursor-registry.js

@@ -78,7 +78,7 @@ function registerCursorPlugin(opts) {
   // --- installed_plugins.json: merge our key, preserve installedAt on upgrade. ---
   const ip = readJson(paths.ipPath, { version: 2, plugins: {} });
   if (typeof ip.version !== 'number') ip.version = 2;
-  if (!ip.plugins || typeof ip.plugins !== 'object') ip.plugins = {};
+  if (!ip.plugins || typeof ip.plugins !== 'object' || Array.isArray(ip.plugins)) ip.plugins = {};
   const existing = Array.isArray(ip.plugins[PLUGIN_KEY]) ? ip.plugins[PLUGIN_KEY][0] : null;
   const installedAt = existing && existing.installedAt ? existing.installedAt : now;
   ip.plugins[PLUGIN_KEY] = [
@@ -93,7 +93,7 @@ function registerCursorPlugin(opts) {
 
   // --- settings.json: flip our enabledPlugins flag, preserve everything else. ---
   const settings = readJson(paths.settingsPath, {});
-  if (!settings.enabledPlugins || typeof settings.enabledPlugins !== 'object') {
+  if (!settings.enabledPlugins || typeof settings.enabledPlugins !== 'object' || Array.isArray(settings.enabledPlugins)) {
     settings.enabledPlugins = {};
   }
   settings.enabledPlugins[PLUGIN_KEY] = true;

package/cli/src/lib/graph.js

@@ -14,7 +14,8 @@ function fetchGraph() {
     return;
   }
   log.note('Fetching knowledge-graph engine (best-effort)...');
-  const result = spawnSync('bash', [script], { stdio: 'inherit' });
+  const timeout = Number(process.env.DRAFT_INSTALL_TIMEOUT_MS) || 300000;
+  const result = spawnSync('bash', [script], { stdio: 'inherit', timeout });
   if (result.status !== 0) {
     log.warn('Graph engine fetch skipped (offline or unsupported platform) — features degrade gracefully.');
   }

package/core/shared/graph-query.md

@@ -103,7 +103,7 @@ DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}
 |---|---|---|
 | `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/mermaid-from-graph.sh" [--diagram module-deps\|co-change\|proto-map]` | diagram text | Unavailable stub (`graph not built`) vs empty-graph stub (`no edges`); both exit 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 |
@@ -133,7 +133,9 @@ bare `[]` as a confirmed true negative:
 | `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) |
+| `unavailable` | engine could not be resolved, or engine returned shapeless/non-row JSON (exit 2) |
+
+**Shapeless JSON is unavailable.** `gq_run` requires `has("rows") and (.rows|type=="array")`. A bare `{}` (or any object without a `.rows` array) is not a measured empty result — wrappers emit `source:"unavailable"` and a non-zero exit. Do not read `{}` as "no callers / no cycles / no edges". `graph-impact`, `graph-callers`, and `mermaid-from-graph` also require their tool-shaped object; a failed snapshot refresh does not rewrite `schema.yaml`.
 
 **Verified engine param shapes** (engine v0.8.x — the runtime source of truth is
 `get_graph_schema`; do not hardcode a property set):
@@ -204,7 +206,7 @@ The engine uses a **unified, language-agnostic** node model — `Function`, `Met
 
 ## Query Tools
 
-Live queries go through the shell tools under `scripts/tools/`, which drive the engine and shape results into stable JSON. Each tool resolves the engine (see Finding the Engine), indexes the repo on demand, and emits `source: "memory-graph"` on success or `source: "unavailable"` (non-zero exit) when the engine cannot be resolved. Set `DRAFT_MEMORY_DISABLE=1` to force the engine off; all tools then degrade gracefully.
+Live queries go through the shell tools under `scripts/tools/`, which drive the engine and shape results into stable JSON. Each tool resolves the engine (see Finding the Engine), indexes the repo on demand, and emits `source: "memory-graph"` on success or `source: "unavailable"` (non-zero exit) when the engine cannot be resolved **or returns shapeless JSON** (missing `.rows` array). Set `DRAFT_MEMORY_DISABLE=1` to force the engine off; all tools then degrade to `unavailable` rather than inventing empty results.
 
 ### Callers — who calls this function?
 
@@ -371,6 +373,6 @@ The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159
 | Scenario | Behavior |
 |----------|----------|
 | No engine resolvable (or `DRAFT_MEMORY_DISABLE=1`) | Skip graph indexing in init; all skills proceed without graph data; tools emit `source: unavailable` |
-| Engine present but a query fails | Warn and proceed; skills work without graph data |
+| Engine present but a query fails, or returns shapeless `{}` | Treat as unavailable — never as a true-negative empty result; skills proceed without graph data |
 | `draft/graph/schema.yaml` exists | Engine is wired — use live query tools as needed during the run |
 | Engine index out of date | The engine indexes incrementally (content-based, git-aware) on each query, so it self-freshens. Re-run `graph-snapshot.sh` (or init) to force a reindex and refresh the marker. |

package/integrations/agents/AGENTS.md

@@ -9604,7 +9604,7 @@ Prefer `draft docs` going forward for all authoring requests. The legacy direct
 
 ## Discover Router
 
-When user says "discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, index, etc.):
+When user says "discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, tour, impact, etc.):
 
 `draft discover` is the single front door for all investigation, auditing, pattern learning, and quality exploration activities.
 
@@ -18204,7 +18204,7 @@ DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}
 |---|---|---|
 | `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/mermaid-from-graph.sh" [--diagram module-deps\|co-change\|proto-map]` | diagram text | Unavailable stub (`graph not built`) vs empty-graph stub (`no edges`); both exit 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 |
@@ -18234,7 +18234,9 @@ bare `[]` as a confirmed true negative:
 | `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) |
+| `unavailable` | engine could not be resolved, or engine returned shapeless/non-row JSON (exit 2) |
+
+**Shapeless JSON is unavailable.** `gq_run` requires `has("rows") and (.rows|type=="array")`. A bare `{}` (or any object without a `.rows` array) is not a measured empty result — wrappers emit `source:"unavailable"` and a non-zero exit. Do not read `{}` as "no callers / no cycles / no edges". `graph-impact`, `graph-callers`, and `mermaid-from-graph` also require their tool-shaped object; a failed snapshot refresh does not rewrite `schema.yaml`.
 
 **Verified engine param shapes** (engine v0.8.x — the runtime source of truth is
 `get_graph_schema`; do not hardcode a property set):
@@ -18305,7 +18307,7 @@ The engine uses a **unified, language-agnostic** node model — `Function`, `Met
 
 ## Query Tools
 
-Live queries go through the shell tools under `scripts/tools/`, which drive the engine and shape results into stable JSON. Each tool resolves the engine (see Finding the Engine), indexes the repo on demand, and emits `source: "memory-graph"` on success or `source: "unavailable"` (non-zero exit) when the engine cannot be resolved. Set `DRAFT_MEMORY_DISABLE=1` to force the engine off; all tools then degrade gracefully.
+Live queries go through the shell tools under `scripts/tools/`, which drive the engine and shape results into stable JSON. Each tool resolves the engine (see Finding the Engine), indexes the repo on demand, and emits `source: "memory-graph"` on success or `source: "unavailable"` (non-zero exit) when the engine cannot be resolved **or returns shapeless JSON** (missing `.rows` array). Set `DRAFT_MEMORY_DISABLE=1` to force the engine off; all tools then degrade to `unavailable` rather than inventing empty results.
 
 ### Callers — who calls this function?
 
@@ -18472,7 +18474,7 @@ The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159
 | Scenario | Behavior |
 |----------|----------|
 | No engine resolvable (or `DRAFT_MEMORY_DISABLE=1`) | Skip graph indexing in init; all skills proceed without graph data; tools emit `source: unavailable` |
-| Engine present but a query fails | Warn and proceed; skills work without graph data |
+| Engine present but a query fails, or returns shapeless `{}` | Treat as unavailable — never as a true-negative empty result; skills proceed without graph data |
 | `draft/graph/schema.yaml` exists | Engine is wired — use live query tools as needed during the run |
 | Engine index out of date | The engine indexes incrementally (content-based, git-aware) on each query, so it self-freshens. Re-run `graph-snapshot.sh` (or init) to force a reindex and refresh the marker. |
 

package/integrations/copilot/.github/copilot-instructions.md

@@ -9604,7 +9604,7 @@ Prefer `draft docs` going forward for all authoring requests. The legacy direct
 
 ## Discover Router
 
-When user says "discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, index, etc.):
+When user says "discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, tour, impact, etc.):
 
 `draft discover` is the single front door for all investigation, auditing, pattern learning, and quality exploration activities.
 
@@ -18204,7 +18204,7 @@ DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(cat ~/.cache/draft/plugin-root 2>/dev/null)}
 |---|---|---|
 | `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/mermaid-from-graph.sh" [--diagram module-deps\|co-change\|proto-map]` | diagram text | Unavailable stub (`graph not built`) vs empty-graph stub (`no edges`); both exit 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 |
@@ -18234,7 +18234,9 @@ bare `[]` as a confirmed true negative:
 | `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) |
+| `unavailable` | engine could not be resolved, or engine returned shapeless/non-row JSON (exit 2) |
+
+**Shapeless JSON is unavailable.** `gq_run` requires `has("rows") and (.rows|type=="array")`. A bare `{}` (or any object without a `.rows` array) is not a measured empty result — wrappers emit `source:"unavailable"` and a non-zero exit. Do not read `{}` as "no callers / no cycles / no edges". `graph-impact`, `graph-callers`, and `mermaid-from-graph` also require their tool-shaped object; a failed snapshot refresh does not rewrite `schema.yaml`.
 
 **Verified engine param shapes** (engine v0.8.x — the runtime source of truth is
 `get_graph_schema`; do not hardcode a property set):
@@ -18305,7 +18307,7 @@ The engine uses a **unified, language-agnostic** node model — `Function`, `Met
 
 ## Query Tools
 
-Live queries go through the shell tools under `scripts/tools/`, which drive the engine and shape results into stable JSON. Each tool resolves the engine (see Finding the Engine), indexes the repo on demand, and emits `source: "memory-graph"` on success or `source: "unavailable"` (non-zero exit) when the engine cannot be resolved. Set `DRAFT_MEMORY_DISABLE=1` to force the engine off; all tools then degrade gracefully.
+Live queries go through the shell tools under `scripts/tools/`, which drive the engine and shape results into stable JSON. Each tool resolves the engine (see Finding the Engine), indexes the repo on demand, and emits `source: "memory-graph"` on success or `source: "unavailable"` (non-zero exit) when the engine cannot be resolved **or returns shapeless JSON** (missing `.rows` array). Set `DRAFT_MEMORY_DISABLE=1` to force the engine off; all tools then degrade to `unavailable` rather than inventing empty results.
 
 ### Callers — who calls this function?
 
@@ -18472,7 +18474,7 @@ The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159
 | Scenario | Behavior |
 |----------|----------|
 | No engine resolvable (or `DRAFT_MEMORY_DISABLE=1`) | Skip graph indexing in init; all skills proceed without graph data; tools emit `source: unavailable` |
-| Engine present but a query fails | Warn and proceed; skills work without graph data |
+| Engine present but a query fails, or returns shapeless `{}` | Treat as unavailable — never as a true-negative empty result; skills proceed without graph data |
 | `draft/graph/schema.yaml` exists | Engine is wired — use live query tools as needed during the run |
 | Engine index out of date | The engine indexes incrementally (content-based, git-aware) on each query, so it self-freshens. Re-run `graph-snapshot.sh` (or init) to force a reindex and refresh the marker. |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "3.7.2",
+  "version": "4.0.0",
   "description": "Context-Driven Development for AI coding agents — install Draft into Claude Code, Cursor, Codex, or opencode.",
   "bin": {
     "draft": "cli/bin/draft.js"
@@ -37,7 +37,11 @@
     "url": "https://github.com/drafthq/draft/issues"
   },
   "license": "MIT",
-  "author": "mayurpise",
+  "author": {
+    "name": "Mayur Pise",
+    "email": "mayur@getdraft.dev",
+    "url": "https://github.com/mayurpise"
+  },
   "publishConfig": {
     "access": "public"
   },

package/scripts/fetch-memory-engine.sh

@@ -80,7 +80,7 @@ TMP="$(mktemp -d)"
 trap 'rm -rf "$TMP"' EXIT
 
 echo "Fetching ${ARCHIVE} (${VERSION})..."
-if ! curl -fSL --max-time 300 -o "$TMP/$ARCHIVE" "$BASE/$ARCHIVE"; then
+if ! curl -fSL --proto '=https' --proto-redir '=https' --max-time 300 -o "$TMP/$ARCHIVE" "$BASE/$ARCHIVE"; then
   echo "error: download failed: $BASE/$ARCHIVE" >&2
   exit 2
 fi
@@ -98,7 +98,7 @@ unverified() {
   echo "  warning: $1 — skipping verification (set DRAFT_STRICT_VERIFY=1 to make this fatal)" >&2
 }
 
-if curl -fsSL --max-time 60 -o "$TMP/checksums.txt" "$BASE/checksums.txt" 2>/dev/null; then
+if curl -fsSL --proto '=https' --proto-redir '=https' --max-time 60 -o "$TMP/checksums.txt" "$BASE/checksums.txt" 2>/dev/null; then
   expected="$(grep "  $ARCHIVE\$" "$TMP/checksums.txt" 2>/dev/null | awk '{print $1}' | head -1 || true)"
   if [[ -n "$expected" ]]; then
     if command -v sha256sum >/dev/null 2>&1; then

package/scripts/lib.sh

@@ -84,7 +84,7 @@ SKILL_META=(
     'plan|Plan Router|"plan feature" or "draft plan <intent>" (new-track, decompose, adr, tech-debt, change)'
     'ops|Ops Router|"ops deploy" or "draft ops <intent>" (deploy-checklist, incident, standup, status, revert)'
     'docs|Docs Router|"write docs" or "draft docs <intent>" (documentation)'
-    'discover|Discover Router|"discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, index, etc.)'
+    'discover|Discover Router|"discover debug" or "draft discover <intent>" (debug, bughunt, reviews, coverage, learn, tour, impact, etc.)'
     'jira|Jira Router|"jira preview", "jira create", or "jira review <ID>"'
     'integrations|Integrations Router|"integrations", "integrations jira-preview", or "integrations jira-create"'
     'quick-review|Quick Review Command|"quick review" or "draft quick-review [file|pr <number>]"'

package/scripts/tools/_graph_queries.sh

@@ -83,7 +83,9 @@ gq_run() {
     payload="$(jq -n --arg p "$project" --arg q "$query" '{project:$p, query:$q}')" || return 3
     res="$(memory_cli query_graph "$payload" 2>/dev/null || true)"
     [[ -n "$res" ]] || return 3
-    printf '%s' "$res" | jq -e . >/dev/null 2>&1 || return 3
+    # Shapeless JSON (`{}`) is not an empty result — it is a failed query.
+    # Callers must not treat it as a measured true-negative.
+    printf '%s' "$res" | jq -e 'has("rows") and (.rows | type == "array")' >/dev/null 2>&1 || return 3
     printf '%s' "$res"
 }
 

package/scripts/tools/check-repo-size.sh

@@ -109,7 +109,11 @@ else
         # `head` lets head close the pipe early, which under `pipefail` surfaces
         # sort's SIGPIPE as a hard failure — non-deterministically, depending on
         # whether the output fit in the pipe buffer.
-        largest="$(awk '$4 ~ /^[0-9]+$/ { printf "  %8.2f MB  %s\n", $4 / 1048576, $5 }' <<< "$listing" | sort -rn)"
+        # git ls-tree -l: "mode type sha size<TAB>path" — path may contain spaces.
+        largest="$(awk -F '\t' '$1 ~ / [0-9]+$/ {
+            n = split($1, a, " ")
+            printf "  %8.2f MB  %s\n", a[n] / 1048576, $2
+        }' <<< "$listing" | sort -rn)"
         head -n "$TOP" <<< "$largest"
     fi
 fi

package/scripts/tools/cycle-detect.sh

@@ -64,8 +64,8 @@ graph_bootstrap "$REPO" || unavailable
 # derived from a query that never ran, which is exactly the true-negative
 # confusion Guardrail 4 exists to prevent, and the one failure mode a caller
 # cannot detect. Both queries must land for the sample to mean anything, so
-# either failure routes to `unavailable`. gq_run only ever echoes validated
-# JSON, so nothing downstream needs a second shape guard.
+# either failure routes to `unavailable`. gq_run requires a `.rows` array, so
+# shapeless JSON (`{}`) is unavailable, not an empty sample.
 R2="$(gq_run "$PROJECT" "$(gq_q_cycles2)")" || unavailable
 R3="$(gq_run "$PROJECT" "$(gq_q_cycles3)")" || unavailable
 

package/scripts/tools/graph-callers.sh

@@ -88,7 +88,7 @@ if [[ "$TRANSITIVE" -eq 1 ]]; then
     PAYLOAD="$(jq -n --arg p "$PROJECT" --arg f "$SYMBOL" --argjson d "$DEPTH" \
         '{project:$p, function_name:$f, depth:$d, direction:"both"}')"
     RES="$(memory_cli trace_path "$PAYLOAD" 2>/dev/null || true)"
-    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable
+    echo "$RES" | jq -e 'has("callers") and (.callers | type == "array")' >/dev/null 2>&1 || unavailable
     N="$(echo "$RES" | jq -r '(.callers // []) | length' 2>/dev/null || echo 0)"
     if [[ "$N" -gt 0 ]]; then STATUS="ok"; else
         STATUS="$(gq_symbol_status "$PROJECT" "$SYM_ESC" '{"rows":[]}')"

package/scripts/tools/graph-impact.sh

@@ -77,7 +77,8 @@ if [[ -n "$SYMBOL" ]]; then
     PAYLOAD="$(jq -n --arg p "$PROJECT" --arg f "$SYMBOL" --argjson d "$DEPTH" \
         '{project:$p, function_name:$f, depth:$d, direction:"both"}')"
     RES="$(memory_cli trace_path "$PAYLOAD" 2>/dev/null || true)"
-    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
+    echo "$RES" | jq -e 'has("callers") and (.callers | type == "array")' >/dev/null 2>&1 \
+        || unavailable "$TARGET" "$KIND"
     echo "$RES" | jq --arg t "$TARGET" '
         {target:$t, kind:"symbol",
          impacted: [ (.callers // [])[] | {name:.name, file:(.file_path // ""), qualified:(.qualified_name // ""), hop:(.hop // 1)} ],
@@ -86,7 +87,8 @@ else
     # File impact: detect_changes maps the working-tree diff to impacted symbols.
     PAYLOAD="$(jq -n --arg p "$PROJECT" '{project:$p}')"
     RES="$(memory_cli detect_changes "$PAYLOAD" 2>/dev/null || true)"
-    echo "$RES" | jq -e . >/dev/null 2>&1 || unavailable "$TARGET" "$KIND"
+    echo "$RES" | jq -e 'has("impacted_symbols") and (.impacted_symbols | type == "array")' >/dev/null 2>&1 \
+        || unavailable "$TARGET" "$KIND"
     echo "$RES" | jq --arg t "$TARGET" '
         {target:$t, kind:"file",
          impacted: [ (.impacted_symbols // [])[]

package/scripts/tools/graph-snapshot.sh

@@ -80,7 +80,11 @@ PROJECT="$(memory_ensure_index "$REPO_ABS" || true)"
 # one never appeared, and nothing in the output said so. Refreshing is this tool's
 # entire job. The engine indexes incrementally, so the repeat call is cheap.
 REFRESHED="$(memory_index_bounded "$REPO_ABS" 2>/dev/null | jq -r '.project // empty' 2>/dev/null || true)"
-[[ -n "$REFRESHED" ]] && PROJECT="$REFRESHED"
+if [[ -z "$REFRESHED" ]]; then
+    echo "index refresh failed — nothing written" >&2
+    exit 2
+fi
+PROJECT="$REFRESHED"
 
 mkdir -p "$OUT"
 

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

@@ -108,7 +108,7 @@ render_co_change() {
 render_proto_map() {
     local res; res="$(memory_cli get_architecture \
         "$(jq -n --arg p "$PROJECT" '{project:$p, aspects:["routes"]}')" || true)"
-    [[ -n "$res" ]] && echo "$res" | jq -e . >/dev/null 2>&1 || return 2
+    [[ -n "$res" ]] && echo "$res" | jq -e 'has("routes") and (.routes | type == "array")' >/dev/null 2>&1 || return 2
     local edges; edges="$(echo "$res" | jq -r '(.routes // [])[] | "    \"" + ((.method // "")|tostring) + " " + ((.path // "")|tostring) + "\" --> \"" + ((.handler // "?")|tostring) + "\""' 2>/dev/null || true)"
     if [[ -z "$edges" ]]; then return 1; fi
     printf '```mermaid\nflowchart LR\n%s\n```\n' "$edges"

package/scripts/tools/okf-emit-catalog.sh

@@ -82,6 +82,9 @@ sniff_desc() {
 
 write_page() {
     local cid="$1" ctype="$2" resource="$3" fan_in="$4"
+    case "$cid" in
+        ''|/*|*..*) echo "ERROR: concept_id escapes bundle: $cid" >&2; return 1 ;;
+    esac
     local out="$BUNDLE/$cid"
     mkdir -p "$(dirname "$out")"
     if [[ -f "$out" && $FORCE -eq 0 ]]; then

package/scripts/tools/okf-render-views.sh

@@ -226,7 +226,7 @@ render_architecture() {
     if [[ -x "$SCRIPT_DIR/okf-fix-links.sh" ]]; then
         draft_dir="$(cd "$(dirname "$out")" && pwd)"
         if [[ -d "$draft_dir/wiki" || "$(basename "$BUNDLE")" == "wiki" ]]; then
-            "$SCRIPT_DIR/okf-fix-links.sh" --file "$out" --wiki "$BUNDLE" --fix >/dev/null 2>&1 || true
+            "$SCRIPT_DIR/okf-fix-links.sh" --file "$out" --wiki "$BUNDLE" --fix >/dev/null 2>&1 || exit 1
         fi
     fi
     echo "rendered architecture view → $out ($(ordered_pages | grep -c . ) pages)"
@@ -411,13 +411,15 @@ function resolve(base, href){
     if(p==='..') out.pop(); else if(p!=='.'&&p!=='') out.push(p); }
   return out.join('/');
 }
+function escAttr(s){return esc(s).replace(/"/g,'"');}
 function inline(s, base){
   s = s.replace(/`([^`]+)`/g, function(m,c){return '<code>'+esc(c)+'</code>';});
   s = s.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, function(m,t,u){
-    if(/^[a-z]+:\/\//.test(u)) return '<a href="'+u+'" target="_blank" rel="noopener">'+t+'</a>';
+    if(/^(https?|mailto):/i.test(u)) return '<a href="'+escAttr(u)+'" target="_blank" rel="noopener">'+t+'</a>';
+    if(/^[a-z][a-z0-9+.-]*:/i.test(u)) return t;
     var key=resolve(base,u);
     if(PAGES[key]) return '<a href="#'+key+'" data-nav="'+key+'">'+t+'</a>';
-    return '<span title="'+esc(u)+'">'+t+'</span>';
+    return '<span title="'+escAttr(u)+'">'+t+'</span>';
   });
   s = s.replace(/\*\*([^*]+)\*\*/g,'<strong>$1</strong>');
   s = s.replace(/(^|[^*])\*([^*\n]+)\*/g,'$1<em>$2</em>');
@@ -438,7 +440,7 @@ function render(md, base){
     out+='<table>';
     rows.forEach(function(r,ri){
       var cells=r.replace(/^\||\|$/g,'').split('|');
-      out+='<tr>'+cells.map(function(c){var t=ri===0?'th':'td';return '<'+t+'>'+inline(c.trim(),base)+'</'+t+'>';}).join('')+'</tr>';
+      out+='<tr>'+cells.map(function(c){var t=ri===0?'th':'td';return '<'+t+'>'+inline(esc(c.trim()),base)+'</'+t+'>';}).join('')+'</tr>';
     });
     out+='</table>'; tbl=[];
   }

package/scripts/tools/okf-validate.sh

@@ -252,6 +252,11 @@ if [[ -n "$PATH_INDEX" ]]; then
         # span lines and a line-oriented match would silently skip them.
         while IFS= read -r ref; do
             [[ -z "$ref" ]] && continue
+            case "$ref" in
+                /*|*..*)
+                    add_error "path-index escapes the bundle: $ref"
+                    continue ;;
+            esac
             if [[ ! -f "$BUNDLE/$ref" ]]; then
                 add_error "path-index references missing concept page: $ref"
             fi

package/scripts/tools/resolve-tools.sh

@@ -53,8 +53,10 @@ resolve() {
   # 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; }
+    local root
+    root="$(cat "$marker" 2>/dev/null || true)"
+    d="${root}/scripts/tools"
+    [ -n "$root" ] && [ -d "$d" ] && { printf '%s' "$d"; return 0; }
   fi
 
   # 3. ${CLAUDE_PLUGIN_ROOT} — set in hook/MCP contexts; harmless to probe.
@@ -66,7 +68,7 @@ resolve() {
   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)"
+          "$reg" 2>/dev/null | head -1 || true)"
     [ -n "$ip" ] && [ -d "$ip/scripts/tools" ] && { printf '%s' "$ip/scripts/tools"; return 0; }
   fi
 

package/scripts/tools/scan-markers.sh

@@ -78,7 +78,15 @@ emit_array() {
     local first=true
     printf '['
     while IFS= read -r _ln; do
-        path="${_ln%%:*}"; rest="${_ln#*:}"; linenum="${rest%%:*}"; rest="${rest#*:}"
+        # Path may contain colons (e.g. src/foo:bar.js). The line number is the
+        # last :<digits>: separator git-grep/rg -n emit.
+        if [[ "$_ln" =~ ^(.+):([0-9]+):(.*)$ ]]; then
+            path="${BASH_REMATCH[1]}"
+            linenum="${BASH_REMATCH[2]}"
+            rest="${BASH_REMATCH[3]}"
+        else
+            continue
+        fi
         [[ -z "$path" || -z "$linenum" ]] && continue
         # Skip binaries or tool's own output directory.
         [[ "$path" == */.git/* ]] && continue

package/skills/draft/intent-mapping.md

@@ -27,7 +27,7 @@ Draft commands can be invoked using natural language. If you describe your goal
 | "debug this issue", "investigate test failure", "fix crash" | `/draft:debug` | Structured 4-stage debugging workflow |
 | "deploy checklist", "release checks", "pre-flight checks" | `/draft:deploy-checklist` | Pre-deployment verification checklist |
 | "test strategy", "design test suite", "testing targets" | `/draft:testing-strategy` | Design standard testing plan |
-| "tech debt analysis", "catalog debt", "code debt" | `/draft:tech-debt` | Technical debt audit across 6 dimensions |
+| "tech debt analysis", "catalog debt", "code debt" | `/draft:tech-debt` | Technical debt audit across 7 dimensions |
 | "weekly standup", "what did I do today", "activity summary" | `/draft:standup` | Summarize recent Git and file contributions |
 | "incident", "production outage", "mitigate bug" | `/draft:incident-response` | Triage, mitigation, and postmortem incident flow |
 | "write docs", "create readme", "api documentation" | `/draft:documentation` | Generate professional, structured docs |