@drafthq/draft 3.2.0 → 3.3.0

package/skills/init/references/okf-emitter.md

@@ -0,0 +1,223 @@
+## Init — OKF Taxonomy Emitter (DRAFT_INIT_MODE=okf)
+
+> Progressive-disclosure reference for `/draft:init`. Covers the OKF emitter:
+> type vocabulary, frontmatter contract, generation pipeline, render views,
+> incremental refresh, and the `okf-validate.sh` gate. Authoritative HLD:
+> `hld-draft-init-okf-taxonomy.md` at the repo root.
+
+This is the `/draft:init` output mode for **tier 3+ repos**, where it is the
+**tier-gated default** (`DRAFT_INIT_MODE` unset → tier 1–2 `monolith`, tier 3–5
+`okf`; an explicit `DRAFT_INIT_MODE=monolith|okf` overrides). `monolith` is
+retained — the tier-1/2 default, the A/B baseline, and the over-fetch fallback.
+The default rests on maintainability/readability, not the benchmark (parity).
+
+```bash
+# Mode gate — default is tier-gated 'auto', finalized after Step 1.4.5 (tier):
+DRAFT_INIT_MODE="${DRAFT_INIT_MODE:-auto}"
+case "$DRAFT_INIT_MODE" in
+  monolith|okf) : ;;             # explicit override — honored as-is
+  auto) : ;;                     # resolve from tier: 1–2 → monolith, 3–5 → okf
+  *) echo "Unknown DRAFT_INIT_MODE='$DRAFT_INIT_MODE' (monolith|okf|auto); using auto" >&2
+     DRAFT_INIT_MODE=auto ;;
+esac
+```
+
+Everything else in `/draft:init` (5-phase analysis, graph snapshot, `.state/`
+hashing, scope detection, atomic staging) is **reused unchanged**. This mode adds
+a decomposition + serialization stage. It introduces **no new LLM analysis
+engine** and exactly **one** new deterministic helper, `okf-validate.sh`.
+
+## Target layout
+
+`okf` mode changes **only** the `architecture.md` / `.ai-context.md` packaging
+and adds `wiki/`. **Every other standard `/draft:init` file is still produced**
+— `product.md`, `tech-stack.md`, `workflow.md`, `guardrails.md`, `index.md`,
+`.ai-profile.md`, `tracks/` + `tracks.md`, `.state/`, `graph/` — exactly as in
+`monolith` mode. Do **not** skip them: emitting only the bundle is a regression.
+
+```
+draft/
+├── .ai-context.md         # INDEX ROOT: synopsis (150–250 lines) + Concept Map
+├── architecture.md        # RENDERED VIEW (generated from bundle; not source of truth)
+├── .ai-profile.md         # always-injected profile (derived from .ai-context.md)  [SAME AS MONOLITH]
+├── product.md             # [SAME AS MONOLITH]
+├── tech-stack.md          # [SAME AS MONOLITH]
+├── workflow.md            # [SAME AS MONOLITH]
+├── guardrails.md          # [SAME AS MONOLITH]
+├── index.md               # docs index — lists prose files + wiki/  [SAME AS MONOLITH, +wiki link]
+├── tracks.md  +  tracks/  # [SAME AS MONOLITH]
+├── wiki/                   # OKF bundle (source of truth) — okf-mode ONLY
+│   ├── index.md            # bundle root + Concept Map
+│   ├── overview/{index,architecture,getting-started,glossary}.md
+│   ├── systems/{index,<subsystem>}.md
+│   ├── features/{index,<feature>}.md
+│   ├── reference/{index,<ref>}.md      # config, deps, data models, ADRs, runbooks
+│   ├── entrypoints/<app>.md
+│   ├── web/index.html      # optional offline viewer (okf-render-views.sh --web)
+│   └── log.md              # chronological change history (from .state run memory)
+├── graph/schema.yaml       # [SAME AS MONOLITH] engine gate marker
+└── .state/
+    ├── hashes.json             # file → content hash  [SAME AS MONOLITH]
+    ├── path-to-concept.json    # NEW: source path → concept page(s) it grounds
+    └── signals.json            # [SAME AS MONOLITH]
+```
+
+The standard project files come from the same generators as `monolith` mode
+(intake questions → `product.md`; tech detection → `tech-stack.md`; `/draft:learn`
+→ `guardrails.md`; templates → `workflow.md`, `index.md`, `tracks.md`,
+`.ai-profile.md`). The OKF emitter only *replaces the architecture packaging*; it
+never owns or removes the rest of the context directory.
+
+Templates for each bundle page live in `core/templates/okf/` (`index.md`,
+`concept.md`, `section-index.md`, `ai-context-index.md`).
+
+## Frozen `type` vocabulary
+
+Every concept carries a `type` from this frozen set (changing it churns every
+file; versioned via `index.md` frontmatter `okf_types_version`):
+
+| type | Maps to | Home |
+|------|---------|------|
+| `Subsystem` | major graph cluster / package boundary | `systems/` |
+| `Module` | single package/dir, cohesive responsibility | `systems/` |
+| `Feature` | user-facing capability spanning modules | `features/` |
+| `Entrypoint` | binary / main / CLI / handler root | `entrypoints/` |
+| `API` | public interface, route group, RPC surface | `reference/` |
+| `DataModel` | schema, table, core struct/type | `reference/` |
+| `Dependency` | notable external dep + how it's used | `reference/` |
+| `ADR` | architecture decision record | `reference/` |
+| `Runbook` | operational procedure | `reference/` |
+
+`okf-validate.sh` enforces this set as ground truth — an out-of-vocab `type`
+fails the build.
+
+## Frontmatter contract
+
+Per concept page (see `core/templates/okf/concept.md`). Required OKF keys:
+`type`, `title`, `description`, `resource`. **`description` is the load-bearing
+routing key** — write it as a routing decision ("should the agent open this for
+the task at hand?"), never a summary. Draft extensions are namespaced `x-` and
+ignored by generic OKF consumers: `x-grounded-paths`, `x-hotspot-score`,
+`x-callers`.
+
+## Concept granularity (resolves open decision 1)
+
+Derive concepts from the graph, not by hand:
+
+- A **Subsystem** = a graph cluster (package/dir boundary) with `fan_in ≥ 2` from
+  other clusters, OR a top-ranked module from `hotspot-rank.sh`.
+- A **Module** = a cohesive package/dir below a subsystem that is *not* itself a
+  cluster boundary but has its own hotspot or public surface.
+- A **Feature** = a capability the graph shows spanning ≥2 modules (shared
+  callers / a route group touching multiple packages).
+- Default cap: one page per package boundary; do not split a package into
+  multiple concept pages unless it has >1 distinct public surface. This keeps
+  page count ≈ module count and navigation depth shallow.
+
+## Generation pipeline (M3)
+
+```
+1. Survey        → existing /draft:init 5-phase + graph snapshot (graph-snapshot.sh)
+2. Plan          → derive the concept list (above) from graph clusters +
+                   entrypoints + features. Topo-sort by dependency so pages that
+                   others link to (overview, core subsystems) generate FIRST —
+                   forward cross-links resolve.
+3. Generate      → per concept, pull grounding from the graph and write the page:
+                     x-callers        ← graph-callers.sh --symbol <c>
+                     x-grounded-paths  ← graph-impact.sh  --symbol <c>  (blast radius)
+                     x-hotspot-score   ← hotspot-rank.sh
+                     overview diagrams ← mermaid-from-graph.sh
+                   Record each source path → page in .state/path-to-concept.json.
+4. Render views  → ai-context.md (synopsis + Concept Map), architecture.md
+                   (concatenated view), wiki/log.md  (see M4).
+5. Validate      → okf-validate.sh draft/wiki \
+                     --path-index draft/.state/path-to-concept.json
+                   FAIL the build (do not atomic-rename) on any dangle, missing
+                   field, bad type, or path-index gap.
+6. Emit          → mv draft.tmp/ draft/ ; update .state/.
+```
+
+Page bodies are LLM-narrated for readability **but** the graph-derived
+frontmatter and the `Blast radius`/`Used by` sections are deterministic. To keep
+incremental carry-forward byte-identical (open decision 2), cache the narrated
+prose keyed by the source hash of `x-grounded-paths` — unchanged sources reuse
+the cached narration verbatim.
+
+## Render views (M4)
+
+Both are produced by the deterministic helper `okf-render-views.sh` (no LLM) —
+regenerated on every init/refresh so they never drift from the bundle:
+
+```bash
+okf-render-views.sh draft/wiki \
+  --arch-out draft/architecture.md \
+  --concept-map-into draft/wiki/index.md \
+  --concept-map-into draft/.ai-context.md \
+  --web draft/wiki/web/index.html
+```
+
+- `--arch-out` renders the linear `architecture.md` (banner + TOC + every concept
+  page in canonical section order, frontmatter stripped, Mermaid preserved).
+- `--concept-map-into` rebuilds the routing table between the
+  `<!-- CONCEPT-MAP:START -->` / `:END` markers from each concept's `title` +
+  `type` + `description` (section `index.md` pages excluded).
+- `--web` writes a **self-contained offline HTML viewer** (single file: all pages
+  inlined as JSON + a built-in markdown renderer + sidebar nav + search). Works by
+  double-click — no server, no internet, no CDN. Optional, human-facing; regenerate
+  on refresh like the other views. (Mermaid blocks render as labeled source since a
+  graphical engine can't be inlined offline.)
+
+All views write into `draft/` (the OKF emitter never creates a separate output
+dir): `draft/wiki/` is the bundle, `draft/architecture.md` + `draft/.ai-context.md`
+are the rendered views, `draft/wiki/web/index.html` is the optional viewer.
+
+The two views:
+
+- **`ai-context.md`** (index root) — from `core/templates/okf/ai-context-index.md`:
+  the Synopsis preserves the prior `.ai-context.md` content shape (so existing
+  downstream consumers keep working); the Concept Map is built from each
+  concept's `description`. Broad tasks terminate here.
+- **`architecture.md`** (rendered view) — TOC + per-concept section concat +
+  Mermaid, in topo order. Demoted, not deleted: the brownfield Context Quality
+  Audit and any command grepping `architecture.md` keep working (§9 of the HLD).
+- **`wiki/log.md`** — appended from `.state/` run memory.
+
+The `<!-- CONCEPT-MAP:START -->` / `:END` markers in `wiki/index.md` and the
+section `index.md` tables are the injection slots for the routing tables.
+
+## Incremental refresh at concept granularity (M5)
+
+`/draft:init refresh` under `okf` mode:
+
+```
+1. Diff hashes.json vs working tree     → changed source paths
+2. path-to-concept.json                 → affected concept pages
+3. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
+4. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
+5. Re-validate: okf-validate.sh on the bundle + path-index (cross-links touching
+   changed concepts must still resolve)
+6. Append log.md; update hashes.json + path-to-concept.json
+```
+
+A 1-file change regenerates only the concept(s) that file grounds. Unchanged
+concepts are byte-identical across runs.
+
+## Backward compatibility (§9)
+
+- `architecture.md` is retained as a rendered view (brownfield audit + grep keep
+  working).
+- `ai-context.md`'s Synopsis preserves the prior content shape; the Concept Map
+  is additive.
+- `/draft:review` and downstream command contracts are unchanged — they consume
+  `architecture.md` / `ai-context.md`, both of which still exist.
+
+## Default policy & retirement of `monolith`
+
+`okf` is the **tier-gated default** (tier 3+); `monolith` is the tier-1/2 default
+and remains in place as the A/B baseline + over-fetch fallback. Full retirement of
+`monolith` is deferred until **both**: (1) the large-monolith A/B run shows `okf` ≥
+baseline on tokens at parity accuracy (the regime the §12 benchmark flagged), and
+(2) a human-onboarding eval confirms the wiki + generated `architecture.md` covers
+linear onboarding. Note: retiring `monolith` would not remove `architecture.md` —
+it is generated from the bundle regardless — so there is no readability gain from
+deletion, only lost optionality.

package/skills/learn/SKILL.md

@@ -9,10 +9,21 @@ Scan the codebase to discover recurring coding patterns and update `draft/guardr
 
 ## MANDATORY GRAPH LOOKUP (read before pattern scanning)
 
+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. Use the graph to:
 
-1. Enumerate a module's symbols/files via `scripts/tools/graph-callers.sh`/`graph-impact.sh` and `scripts/tools/graph-arch.sh --repo .` (preferred over `find`).
-2. Prioritize hotspots via `scripts/tools/hotspot-rank.sh --repo .` — patterns in high-fanIn files are more impactful when learned.
+1. Enumerate a module's symbols/files via `"$DRAFT_TOOLS/graph-callers.sh"`/`"$DRAFT_TOOLS/graph-impact.sh"` and `"$DRAFT_TOOLS/graph-arch.sh" --repo .` (preferred over `find`).
+2. Prioritize hotspots via `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — patterns in high-fanIn files are more impactful when learned.
 3. For TS/Python/Go/C/C++, use `*-index.jsonl` to identify class/function definitions rather than re-discovering them via regex.
 
 Filesystem `find` for source discovery (Step 2.1) is permitted **as a complement** to the graph for languages not covered by indexes (e.g. Ruby, Java without ctags). Record the rationale in the Graph Usage Report.
@@ -246,10 +257,10 @@ git log --follow --oneline -1 -- {file_containing_pattern}
 
 ### 2.7: Graph-Aware Severity Enrichment
 
-If `draft/graph/schema.yaml` exists (engine live), derive objective severity for all anti-pattern candidates based on the fanIn of files where the pattern was found via `scripts/tools/hotspot-rank.sh --repo .`.
+If `draft/graph/schema.yaml` exists (engine live), derive objective severity for all anti-pattern candidates based on the fanIn of files where the pattern was found via `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .`.
 
 For each anti-pattern candidate from Step 2.2:
-1. Check if any evidence files appear in the hotspot output from `scripts/tools/hotspot-rank.sh --repo .`
+1. Check if any evidence files appear in the hotspot output from `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .`
 2. Take the highest fanIn value across all evidence files:
    - fanIn ≥ 10 → `graph_severity: critical` (breakage propagates to many callers)
    - fanIn 5–9 → `graph_severity: high`

package/skills/quick-review/SKILL.md

@@ -11,8 +11,18 @@ You are performing a lightweight, ad-hoc code review. This is the fast alternati
 
 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. Quick-review keeps the graph load light:
 
-1. Always run `scripts/tools/hotspot-rank.sh --repo .` for every changed file (Step 2 blast-radius pre-check below).
-2. If a finding spans more than one file, run `scripts/tools/graph-callers.sh --repo . --symbol <name>` to enumerate the call sites before claiming "no other usages".
+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. Always run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` for every changed file (Step 2 blast-radius pre-check below).
+2. If a finding spans more than one file, run `"$DRAFT_TOOLS/graph-callers.sh" --repo . --symbol <name>` to enumerate the call sites before claiming "no other usages".
 
 Filesystem `grep` is reserved for source-text scans (literal strings, regex patterns). Symbol and caller discovery go through the graph.
 
@@ -70,7 +80,7 @@ Determine the diff to review:
 
 ## Step 2: Blast Radius Pre-check (if `draft/graph/schema.yaml` exists)
 
-Before the four-dimension review, run `scripts/tools/hotspot-rank.sh --repo .` and check if any files in scope appear in the output. If any file has a `fanIn` in the top 20% of the list, add this warning at the top of the review report:
+Before the four-dimension review, run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` and check if any files in scope appear in the output. If any file has a `fanIn` in the top 20% of the list, add this warning at the top of the review report:
 
 ```
 ⚠ HIGH IMPACT: {file} is a high-fanIn hotspot (fanIn={N}). Changes here propagate to many callers — review with extra care.

package/skills/review/SKILL.md

@@ -11,9 +11,19 @@ You are conducting a code review using Draft's Context-Driven Development method
 
 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. Stage 1 (Automated Validation) **starts from the graph**:
 
-1. Run blast-radius assessment via `scripts/tools/hotspot-rank.sh --repo .` and `scripts/tools/graph-impact.sh` (see Stage 1).
-2. For each changed file with non-trivial diff size, run `scripts/tools/graph-impact.sh --repo . --file <path>` to obtain the affected module set deterministically.
-3. For each public symbol modified, run `scripts/tools/graph-callers.sh --repo . --symbol <name>` to enumerate downstream callers before judging breaking-change severity.
+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. Run blast-radius assessment via `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` and `"$DRAFT_TOOLS/graph-impact.sh"` (see Stage 1).
+2. For each changed file with non-trivial diff size, run `"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>` to obtain the affected module set deterministically.
+3. For each public symbol modified, run `"$DRAFT_TOOLS/graph-callers.sh" --repo . --symbol <name>` to enumerate downstream callers before judging breaking-change severity.
 
 Filesystem `grep` is reserved for source-text scans (string literals, log messages, regex matches in code) — not for discovering modules, files, or callers when the graph can answer.
 
@@ -369,10 +379,21 @@ Load plugin guardrails before scanning: `core/guardrails/review-checks.md` (RC-#
 For the files changed in the diff, perform static checks using `grep` or similar tools:
 
 - **Blast Radius Assessment** (if the `draft/graph/` snapshot 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"
+   ```
+
    - List all changed files from the diff
-   - For each changed file, check if it appears in `scripts/tools/hotspot-rank.sh --repo .` output — if yes, record its `fanIn` value
+   - For each changed file, check if it appears in `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` output — if yes, record its `fanIn` value
    - Classify: files with fanIn in the top 20% of the hotspot output = **HIGH IMPACT**; top 21–50% = **MEDIUM**; below 50% or not in output = **STANDARD**
-   - For any file in a HIGH or MEDIUM module, query `scripts/tools/graph-arch.sh --repo . | jq '.packages[].fan_in'` (how many modules depend on this module)
+   - For any file in a HIGH or MEDIUM module, query `"$DRAFT_TOOLS/graph-arch.sh" --repo . | jq '.packages[].fan_in'` (how many modules depend on this module)
    - Include a `Blast Radius` line in the Stage 1 report summary: `Blast Radius: HIGH | MEDIUM | STANDARD — <N> changed files affect high-fanIn modules: [file list]`
    - If any changed file is HIGH IMPACT: escalate Stage 3 thoroughness (check all callers of changed functions) and note this in the report header
 - **Architecture Conformance:** Search for pattern violations documented in `draft/.ai-context.md`. (e.g. `import * from 'database'` in a React component).
@@ -381,7 +402,7 @@ For the files changed in the diff, perform static checks using `grep` or similar
 - **Graph Boundary Check** (if `draft/graph/schema.yaml` exists) `[RC-013]`:
    - For each changed file, identify its module from the graph
    - Check if any new cross-module includes were added in the diff
-   - Verify they follow the established dependency direction from `scripts/tools/graph-arch.sh --repo .` package fan-in/out
+   - Verify they follow the established dependency direction from `"$DRAFT_TOOLS/graph-arch.sh" --repo .` package fan-in/out
    - Flag reverse-direction dependencies (module A now depends on module B, but only B→A existed before) as "Potential architecture violation — new dependency direction"
    - Check if changes introduce files in modules listed in graph cycles — flag as higher risk
 - **Security Scan** `[RC-001, RC-002, RC-003, RC-011]`:
@@ -1106,8 +1127,11 @@ As the last step after saving the review report, emit a metrics record. Best-eff
 
 **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":"review","track_id":"<id_or_null>","stage_reached":"<stage>","verdict":"<v>","critical_count":<N>,"important_count":<N>,"blast_radius":"<br>","graph_queries":<N>,"fallback_grep_count":<N>}'

package/skills/standup/SKILL.md

@@ -54,8 +54,9 @@ Check for arguments:
 **Preferred:** invoke `parse-git-log.sh` — it parses conventional commits into structured JSONL `{sha,type,scope,track_id,subject,author,timestamp,files_changed}`, eliminating ambiguity in `type(track-id): subject` parsing. 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/parse-git-log.sh" ]; then
   bash "$DRAFT_TOOLS/parse-git-log.sh" --since "24 hours ago" --author "$(git config user.name)"

package/skills/status/SKILL.md

@@ -44,8 +44,9 @@ Display a comprehensive overview of project progress.
 If `parse-reports.sh` and `freshness-check.sh` are available, gather structured signals to enrich the status output (severity counts per track, stale `draft/` docs). 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"
 
 # Per-track report severity rollup (bughunt, review, tech-debt, etc.):

package/skills/tech-debt/SKILL.md

@@ -9,12 +9,23 @@ You are conducting a technical debt analysis to catalog, prioritize, and plan re
 
 ## MANDATORY GRAPH LOOKUP (read before debt scan)
 
+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. Tech-debt prioritization is fundamentally driven by graph data:
 
-1. Run `scripts/tools/hotspot-rank.sh --repo .` — **rank candidates by `fanIn × complexity`** to surface high-leverage debt first.
-2. Query `scripts/tools/graph-arch.sh --repo .` and run `scripts/tools/cycle-detect.sh --repo .` — flag debt in modules involved in cycles as higher priority.
-3. Run `scripts/tools/cycle-detect.sh --repo .` to enumerate dependency cycles — every cycle is a candidate architecture-debt entry.
-4. For each catalogued finding, run `scripts/tools/graph-impact.sh --repo . --file <path>` so the remediation plan includes blast-radius.
+1. Run `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .` — **rank candidates by `fanIn × complexity`** to surface high-leverage debt first.
+2. Query `"$DRAFT_TOOLS/graph-arch.sh" --repo .` and run `"$DRAFT_TOOLS/cycle-detect.sh" --repo .` — flag debt in modules involved in cycles as higher priority.
+3. Run `"$DRAFT_TOOLS/cycle-detect.sh" --repo .` to enumerate dependency cycles — every cycle is a candidate architecture-debt entry.
+4. For each catalogued finding, run `"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>` so the remediation plan includes blast-radius.
 
 Filesystem `grep` (e.g. `scan-markers.sh`) is still primary for TODO/FIXME marker discovery — markers are source-text, not graph-derived. The graph governs **prioritization**, the marker scan governs **discovery**.
 
@@ -82,8 +93,11 @@ Scan the codebase systematically across all seven categories. For each finding,
 For TODO/FIXME/HACK/XXX/DEPRECATED markers, prefer the deterministic `scan-markers.sh` wrapper — it emits JSON `[{path,line,marker,text,sha,author,introduced,age_days}]` with blame ages already computed. 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"
+# 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/scan-markers.sh" ] && bash "$DRAFT_TOOLS/scan-markers.sh" --root .
 # Fallback when script unavailable: grep -rn 'TODO\|FIXME\|HACK\|XXX\|DEPRECATED' .

package/skills/upload/SKILL.md

@@ -52,8 +52,9 @@ Run the WS-9 chain from [verification-gates.md](../../core/shared/verification-g
 
 ```bash
 TRACK_DIR="draft/tracks/<id>"
-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"

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

@@ -1,91 +0,0 @@
-# Draft - Context-Driven Development
-
-You are operating with the Draft methodology for Context-Driven Development.
-
-**Measure twice, code once.**
-
-## Core Workflow
-
-**Context -> Spec & Plan -> Implement**
-
-Every feature follows this lifecycle:
-1. **Setup** - Initialize project context (once per project)
-2. **New Track** - Create specification and plan
-3. **Implement** - Execute tasks with TDD workflow
-4. **Verify** - Confirm acceptance criteria met
-
-## Project Context Files
-
-When `draft/` exists in the project, always consider:
-- `draft/.ai-context.md` - Source of truth for AI agents (dense codebase understanding)
-- `draft/architecture.md` - Human-readable engineering guide (derived from .ai-context.md)
-- `draft/product.md` - Product vision and goals
-- `draft/tech-stack.md` - Technical constraints
-- `draft/workflow.md` - TDD and commit preferences
-- `draft/tracks.md` - Active work items
-
-## Available Commands
-
-| Command | Purpose |
-|---------|---------|
-| `draft` | Show overview and available commands |
-| `draft init` | Initialize project (run once) |
-| `draft index [--init-missing]` | Aggregate monorepo service contexts |
-| `draft new-track <description>` | Create feature/bug track |
-| `draft decompose` | Module decomposition with dependency mapping |
-| `draft implement` | Execute tasks from plan |
-| `draft coverage` | Code coverage report (target 95%+) |
-| `draft bughunt [--track <id>]` | Systematic bug discovery |
-| `draft review [--track <id>]` | Three-stage code review |
-| `draft deep-review [module]` | Exhaustive production-grade module audit |
-| `draft learn [promote\|migrate]` | Discover coding patterns, update guardrails |
-| `draft adr [title]` | Architecture Decision Records |
-| `draft status` | Show progress overview |
-| `draft revert` | Git-aware rollback |
-| `draft change <description>` | Handle mid-track requirement changes |
-| `draft jira-preview [track-id]` | Generate jira-export.md for review |
-| `draft jira-create [track-id]` | Create Jira issues from export via MCP |
-
-## Intent Mapping
-
-Recognize these natural language patterns:
-
-| User Says | Action |
-|-----------|--------|
-| "set up the project" | Run init |
-| "index services", "aggregate context" | Run index |
-| "new feature", "add X" | Create new track |
-| "break into modules", "decompose" | Run decompose |
-| "start implementing" | Execute implement |
-| "check coverage", "test coverage" | Run coverage |
-| "hunt bugs", "find bugs" | Run bug hunt |
-| "review code", "review track", "check quality" | Run review |
-| "deep review", "production audit", "module audit" | Run deep-review |
-| "learn patterns", "update guardrails", "discover conventions" | Run learn |
-| "what's the status" | Show status |
-| "undo", "revert" | Run revert |
-| "requirements changed", "scope changed", "update the spec" | Run change |
-| "preview jira", "export to jira" | Run jira-preview |
-| "create jira", "push to jira" | Run jira-create |
-| "document decision", "create ADR" | Create architecture decision record |
-| "help", "what commands" | Show draft overview |
-| "the plan" | Read active track's plan.md |
-| "the spec" | Read active track's spec.md |
-
-## Tracks
-
-A **track** is a high-level unit of work (feature, bug fix, refactor). Each track contains:
-- `spec.md` - Requirements and acceptance criteria
-- `plan.md` - Phased task breakdown
-- `metadata.json` - Status and timestamps
-
-Located at: `draft/tracks/<track-id>/`
-
-## Status Markers
-
-Recognize and use these throughout plan.md:
-- `[ ]` - Pending
-- `[~]` - In Progress
-- `[x]` - Completed
-- `[!]` - Blocked
-

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

@@ -1,91 +0,0 @@
-# Draft - Context-Driven Development
-
-You are operating with the Draft methodology for Context-Driven Development.
-
-**Measure twice, code once.**
-
-## Core Workflow
-
-**Context -> Spec & Plan -> Implement**
-
-Every feature follows this lifecycle:
-1. **Setup** - Initialize project context (once per project)
-2. **New Track** - Create specification and plan
-3. **Implement** - Execute tasks with TDD workflow
-4. **Verify** - Confirm acceptance criteria met
-
-## Project Context Files
-
-When `draft/` exists in the project, always consider:
-- `draft/.ai-context.md` - Source of truth for AI agents (dense codebase understanding)
-- `draft/architecture.md` - Human-readable engineering guide (derived from .ai-context.md)
-- `draft/product.md` - Product vision and goals
-- `draft/tech-stack.md` - Technical constraints
-- `draft/workflow.md` - TDD and commit preferences
-- `draft/tracks.md` - Active work items
-
-## Available Commands
-
-| Command | Purpose |
-|---------|---------|
-| `draft` | Show overview and available commands |
-| `draft init` | Initialize project (run once) |
-| `draft index [--init-missing]` | Aggregate monorepo service contexts |
-| `draft new-track <description>` | Create feature/bug track |
-| `draft decompose` | Module decomposition with dependency mapping |
-| `draft implement` | Execute tasks from plan |
-| `draft coverage` | Code coverage report (target 95%+) |
-| `draft bughunt [--track <id>]` | Systematic bug discovery |
-| `draft review [--track <id>]` | Three-stage code review |
-| `draft deep-review [module]` | Exhaustive production-grade module audit |
-| `draft learn [promote\|migrate]` | Discover coding patterns, update guardrails |
-| `draft adr [title]` | Architecture Decision Records |
-| `draft status` | Show progress overview |
-| `draft revert` | Git-aware rollback |
-| `draft change <description>` | Handle mid-track requirement changes |
-| `draft jira-preview [track-id]` | Generate jira-export.md for review |
-| `draft jira-create [track-id]` | Create Jira issues from export via MCP |
-
-## Intent Mapping
-
-Recognize these natural language patterns:
-
-| User Says | Action |
-|-----------|--------|
-| "set up the project" | Run init |
-| "index services", "aggregate context" | Run index |
-| "new feature", "add X" | Create new track |
-| "break into modules", "decompose" | Run decompose |
-| "start implementing" | Execute implement |
-| "check coverage", "test coverage" | Run coverage |
-| "hunt bugs", "find bugs" | Run bug hunt |
-| "review code", "review track", "check quality" | Run review |
-| "deep review", "production audit", "module audit" | Run deep-review |
-| "learn patterns", "update guardrails", "discover conventions" | Run learn |
-| "what's the status" | Show status |
-| "undo", "revert" | Run revert |
-| "requirements changed", "scope changed", "update the spec" | Run change |
-| "preview jira", "export to jira" | Run jira-preview |
-| "create jira", "push to jira" | Run jira-create |
-| "document decision", "create ADR" | Create architecture decision record |
-| "help", "what commands" | Show draft overview |
-| "the plan" | Read active track's plan.md |
-| "the spec" | Read active track's spec.md |
-
-## Tracks
-
-A **track** is a high-level unit of work (feature, bug fix, refactor). Each track contains:
-- `spec.md` - Requirements and acceptance criteria
-- `plan.md` - Phased task breakdown
-- `metadata.json` - Status and timestamps
-
-Located at: `draft/tracks/<track-id>/`
-
-## Status Markers
-
-Recognize and use these throughout plan.md:
-- `[ ]` - Pending
-- `[~]` - In Progress
-- `[x]` - Completed
-- `[!]` - Blocked
-