@drafthq/draft 3.5.3 → 3.7.1

package/core/shared/context-verify.md

@@ -23,7 +23,9 @@ Referenced by: every skill that starts with a `Verify Draft Context` step.
    |---|---|
    | Directory exists | Proceed to step 3. |
    | Directory missing AND skill requires context (`/draft:learn`, `/draft:deep-review`, `/draft:tech-debt`, `/draft:implement`) | **STOP** — print `No Draft context found. Run /draft:init first.` and exit. |
-   | Directory missing AND skill is context-optional (`/draft:debug`, `/draft:quick-review`, `/draft:bughunt`, `/draft:deploy-checklist`, `/draft:documentation`, `/draft:testing-strategy`) | Proceed with reduced-context mode; record `draft_context: absent` in the report header. |
+   | Directory missing AND skill is context-optional (`/draft:review`, `/draft:debug`, `/draft:quick-review`, `/draft:bughunt`, `/draft:deploy-checklist`, `/draft:documentation`, `/draft:testing-strategy`) | Proceed with reduced-context mode; record `draft_context: absent` in the report header. |
+
+   `/draft:review` is deliberately in the context-optional row: it is the command a new user runs first, so requiring `/draft:init` would put the expensive step ahead of the demonstration. Its degraded contract is `skills/review/references/zero-setup-mode.md`.
 
 3. **Load context** by following [draft-context-loading.md](draft-context-loading.md). Honor the **selective guardrail matrix** in that file's Layer 0.5 — do not load all guardrails just because they are available.
 

package/core/shared/cross-skill-dispatch.md

@@ -22,11 +22,13 @@ Execute without user confirmation. Used for passive context enrichment and estab
 Present a choice with a recommended default. Used when the skill adds significant value but the user may want to skip.
 
 Format:
-```
+
+```text
 "Run /draft:<skill> to <benefit>? [Y/n]"
 ```
 
 Examples:
+
 - "Run `/draft:debug` to investigate before writing the spec? [Y/n]" — bug tracks in new-track
 - "Run full three-stage review or `/draft:quick-review` for lightweight check? [full]" — phase boundaries in implement
 - "Run `/draft:tech-debt` to scope this refactor? [Y/n]" — refactor tracks in new-track
@@ -38,11 +40,13 @@ Examples:
 Announce availability at completion without blocking. Used for optional follow-up actions.
 
 Format:
-```
+
+```text
 "Consider running `/draft:<skill>` to <benefit>."
 ```
 
 Examples:
+
 - "Consider running `/draft:tech-debt` to catalog debt found during review."
 - "Consider running `/draft:documentation api` to document new endpoints."
 - "Consider running `/draft:adr` to record this design decision."
@@ -119,7 +123,7 @@ At this point, check for dispatch opportunities:
 Applies to: `/draft:debug`, `/draft:implement` (bug tracks), auto-triage pipeline, `/draft:bughunt`
 Does NOT apply to: Feature tracks with TDD enabled, `/draft:coverage`
 
-```
+```text
 If track type is "bugfix" OR current context is debug/RCA:
   BEFORE writing any test file:
     ASK: "Want me to write [regression/unit] tests for [description]? [Y/n]"

package/core/shared/draft-context-loading.md

@@ -101,6 +101,7 @@ If `draft/.state/facts.json` exists, it provides granular fact-level context:
 Facts are NOT loaded in full for every command — use relevance filtering (see below).
 
 Additional state files used by refresh operations (not loaded during normal context loading):
+
 - `draft/.state/freshness.json` — SHA-256 hashes for file-level staleness detection
 - `draft/.state/signals.json` — signal classification for structural drift detection
 
@@ -111,6 +112,7 @@ Not all context is equally relevant to every task. When a specific track or task
 ### When to Apply
 
 Apply relevance scoring when ALL of these conditions are true:
+
 1. A specific track or task is active (has `spec.md` and/or `plan.md`)
 2. `draft/.ai-context.md` exists and is above tier-1 minimum (100 lines)
 3. The command benefits from focused context (`/draft:implement`, `/draft:bughunt`, `/draft:review`)
@@ -212,6 +214,7 @@ If analyzing a specific track, also load:
 | `draft/tracks/<id>/plan.md` | Implementation tasks, phases, dependencies |
 
 Use track context to:
+
 - Verify implemented features match spec requirements
 - Check edge cases listed in spec are handled
 - Focus analysis on files modified/created by the track

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

@@ -5,6 +5,7 @@ Shared procedure for gathering git metadata and generating YAML frontmatter in D
 Referenced by: All skills that generate Draft reports — including `/draft:bughunt`, `/draft:deep-review`, `/draft:review`, `/draft:quick-review`, `/draft:tech-debt`, `/draft:deploy-checklist`, `/draft:incident-response`, `/draft:debug`, `/draft:standup`, `/draft:testing-strategy`
 
 > **Two-tier metadata pattern:**
+>
 > - **Project-level artifacts** (`draft/architecture.md`, `.ai-context.md`, `.ai-profile.md`, `product.md`, `workflow.md`, etc.): git state lives in `draft/metadata.json` only. Per-file frontmatter carries only `project`, `module`, `generated_by`, `generated_at`. Skills read `synced_to_commit` from `draft/metadata.json`.
 > - **Session/report artifacts** (`draft/bughunt-report-*.md`, `draft/review-*.md`, etc.): embed full git frontmatter using the template below — these are point-in-time snapshots, not refreshable docs.
 > - **Track artifacts** (`tracks/<id>/spec.md`, `hld.md`, etc.): git state lives in `tracks/<id>/metadata.json`. Per-file frontmatter carries only stable fields.
@@ -16,7 +17,7 @@ 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="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(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/graph-query.md

@@ -88,14 +88,12 @@ Skills that emit telemetry via [emit-skill-metrics.sh](../../scripts/tools/emit-
 
 These fields are appended to `~/.draft/metrics.jsonl` along with the existing skill fields (`skill`, `track_id`, etc.) — no new state file is needed. Run `tail -100 ~/.draft/metrics.jsonl | jq -s 'group_by(.skill) | map({skill: .[0].skill, runs: length, avg_graph_queries: ([.[].graph_queries] | add / length), avg_grep_fallbacks: ([.[].fallback_grep_count] | add / length)})'` to monitor adherence per skill.
 
-
-
 ## 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. 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):
+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/git-metadata.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="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(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"
@@ -211,7 +209,7 @@ Live queries go through the shell tools under `scripts/tools/`, which drive the
 ### Callers — who calls this function?
 
 ```bash
-scripts/tools/graph-callers.sh --repo . --symbol <name>
+"$DRAFT_TOOLS/graph-callers.sh" --repo . --symbol <name>
 ```
 
 Output: `{symbol, callers[{name, file}], source}`. Use when enumerating call sites before claiming "no other usages" or judging breaking-change severity.
@@ -219,8 +217,8 @@ Output: `{symbol, callers[{name, file}], source}`. Use when enumerating call sit
 ### Impact — blast radius of a file or symbol
 
 ```bash
-scripts/tools/graph-impact.sh --repo . --file <path>      # changed-file impact (working-tree diff)
-scripts/tools/graph-impact.sh --repo . --symbol <name>    # transitive callers of a function
+"$DRAFT_TOOLS/graph-impact.sh" --repo . --file <path>      # changed-file impact (working-tree diff)
+"$DRAFT_TOOLS/graph-impact.sh" --repo . --symbol <name>    # transitive callers of a function
 ```
 
 Output: `{target, kind, impacted[{name, file, hop}], source}`. Use when sizing risk before modifying a file or symbol, especially high-fan-in hotspots.
@@ -228,7 +226,7 @@ Output: `{target, kind, impacted[{name, file, hop}], source}`. Use when sizing r
 ### Hotspots — fan-in ranking
 
 ```bash
-scripts/tools/hotspot-rank.sh --repo . [--top N]
+"$DRAFT_TOOLS/hotspot-rank.sh" --repo . [--top N]
 ```
 
 Output: `{hotspots[{id, name, fanIn}], source}` (server-computed by the engine).
@@ -236,7 +234,7 @@ Output: `{hotspots[{id, name, fanIn}], source}` (server-computed by the engine).
 ### Cycles — call-cycle detection
 
 ```bash
-scripts/tools/cycle-detect.sh --repo .
+"$DRAFT_TOOLS/cycle-detect.sh" --repo .
 ```
 
 Output: `{cycles[[a,b],[a,b,c]], source}` — fixed-length 2- and 3-node `CALLS` cycles (mutual recursion / tight coupling).
@@ -246,7 +244,7 @@ Output: `{cycles[[a,b],[a,b,c]], source}` — fixed-length 2- and 3-node `CALLS`
 Query the engine's architecture view live with the `graph-arch.sh` wrapper (it resolves the engine, indexes on demand, and auto-resolves the project):
 
 ```bash
-scripts/tools/graph-arch.sh --repo . \
+"$DRAFT_TOOLS/graph-arch.sh" --repo . \
   | jq '{packages, node_labels, edge_types, routes, layers, boundaries}'
 ```
 
@@ -255,8 +253,8 @@ scripts/tools/graph-arch.sh --repo . \
 ### Mermaid — diagram text
 
 ```bash
-scripts/tools/mermaid-from-graph.sh --repo . --diagram module-deps   # co-change coupling
-scripts/tools/mermaid-from-graph.sh --repo . --diagram proto-map     # detected routes
+"$DRAFT_TOOLS/mermaid-from-graph.sh" --repo . --diagram module-deps   # co-change coupling
+"$DRAFT_TOOLS/mermaid-from-graph.sh" --repo . --diagram proto-map     # detected routes
 ```
 
 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.
@@ -264,7 +262,7 @@ Emits a ready-to-inject ` ```mermaid ``` ` block on the fly (computed live by th
 ### Snippet — verified source + caller/callee counts
 
 ```bash
-scripts/tools/graph-snippet.sh --repo . --qualified <pkg.Mod.Class.method>
+"$DRAFT_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.
@@ -272,7 +270,7 @@ Output: `{qualified_name, file, start_line, end_line, callers, callees, transiti
 ### Search — semantic / ranked symbol lookup
 
 ```bash
-scripts/tools/graph-search.sh --repo . --query "auth token refresh" [--limit N]
+"$DRAFT_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.
@@ -280,8 +278,8 @@ Output: `{query, results[{name, qualified_name, label, file, rank}], total, sour
 ### 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
+"$DRAFT_TOOLS/graph-tests.sh" --repo . --symbol <name>     # tests covering a symbol
+"$DRAFT_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`.
@@ -289,7 +287,7 @@ Output: `{symbol, tests[{test,file}], status, source}` or `{untested[{symbol,fil
 ### Deps — real module/file import graph
 
 ```bash
-scripts/tools/graph-deps.sh --repo . [--file PATH]
+"$DRAFT_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`.
@@ -297,7 +295,7 @@ Output: `{imports[{src,dst}], total, truncated, source}` from actual `IMPORTS` e
 ### Hierarchy — class inheritance
 
 ```bash
-scripts/tools/graph-hierarchy.sh --repo . [--symbol <Class> | --derived <Base>]
+"$DRAFT_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.
@@ -305,8 +303,8 @@ Output: `{edges[{child,parent}], status, source}`. `--derived` gives the blast r
 ### 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
+"$DRAFT_TOOLS/graph-errors.sh" --repo . --symbol <name>   # what it raises/throws
+"$DRAFT_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.
@@ -314,7 +312,7 @@ Output: `{symbol, raises[...], status, source}` or `{type, raisers[...], status,
 ### Risk — pre-computed risk hotspots
 
 ```bash
-scripts/tools/graph-risk.sh --repo . [--min-complexity N]
+"$DRAFT_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.
@@ -322,8 +320,8 @@ Output: `{risky[{symbol, file, complexity, flags}], total, truncated, source}` f
 ### 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 '{}'
+"$DRAFT_TOOLS/graph-query.sh" --repo . --cypher 'MATCH (f)-[:WRITES]->(v) RETURN f.name, v.name LIMIT 50'
+"$DRAFT_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.
@@ -331,7 +329,7 @@ Unlocks any edge type or node property without a purpose-built wrapper. Write ve
 ### Indexing / refreshing the gate marker
 
 ```bash
-scripts/tools/graph-snapshot.sh --repo .
+"$DRAFT_TOOLS/graph-snapshot.sh" --repo .
 ```
 
 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.
@@ -350,7 +348,7 @@ The engine is the `codebase-memory-mcp` binary. Resolution order (implemented by
 The canonical verifier is `scripts/tools/verify-graph-binary.sh` (`--json --verbose --strict`). It resolves and liveness-checks the engine and, in a `draft/` context, writes the usage-report side-effect:
 
 ```bash
-ENGINE_INFO="$(scripts/tools/verify-graph-binary.sh --repo . --json 2>/dev/null || true)"
+ENGINE_INFO="$("$DRAFT_TOOLS/verify-graph-binary.sh" --repo . --json 2>/dev/null || true)"
 # {"status":"ok","engine_bin":"...","source":"managed|path|bundled:<arch>|override","arch":"..."}
 ```
 
@@ -363,7 +361,7 @@ After successful detection, `draft/.graph-binary-report.json` contains: `detecte
 Run during `draft:init` / `draft:graph`, or manually:
 
 ```bash
-scripts/tools/graph-snapshot.sh --repo .
+"$DRAFT_TOOLS/graph-snapshot.sh" --repo .
 ```
 
 The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159 languages) plus LSP-assisted resolution for the major ones, and detects HTTP/gRPC/GraphQL routes. Indexing is incremental in the engine (content-based, git-aware). This refreshes the engine index and rewrites the `schema.yaml` gate marker; it produces no committed graph data.

package/core/shared/graph-usage-report.md

@@ -19,4 +19,4 @@ See [graph-query.md](graph-query.md) §Graph Usage Report (Mandatory Footer) for
 - Justification (only when `Graph files queried: NONE`): <required — `graph data unavailable` | `non-code task` | `<explicit reason>`>
 ```
 
-**Gate:** `Graph files queried: NONE` without a populated justification line is a hard failure.
+**Gate:** `Graph files queried: NONE` without a populated justification line is a hard failure.

package/core/shared/jira-sync.md

@@ -28,7 +28,7 @@ All Jira content written by Draft (comments and descriptions) MUST include a sig
 
 Append this signature block at the end of every Jira comment:
 
-```
+```text
 ─────────────────────────────
 🤖 Generated by Draft
 ```
@@ -37,7 +37,7 @@ Append this signature block at the end of every Jira comment:
 
 Append this signature line inside `{noformat}` blocks at the end of every Jira description:
 
-```
+```yaml
 ---
 🤖 Generated by Draft
 Branch: [branch-name] | Commit: [short-hash]
@@ -63,7 +63,7 @@ On every sync operation, after posting the comment or attachment:
 
 All Jira comments from Draft follow this format for consistency and scannability:
 
-```
+```json
 [draft] {action}: {1-line summary}
 ─────────────────────────────
 • {key detail 1}
@@ -77,7 +77,8 @@ Attachment: {filename} (if applicable)
 ```
 
 Examples:
-```
+
+```json
 [draft] spec-complete: Specification and plan generated for track add-user-auth
 ─────────────────────────────
 • 3 phases, 12 tasks planned
@@ -90,7 +91,7 @@ Attachments: spec.md, plan.md
 🤖 Generated by Draft
 ```
 
-```
+```json
 [draft] rca-complete: Root cause identified for login timeout
 ─────────────────────────────
 • Root cause: connection pool exhaustion under concurrent load
@@ -118,7 +119,7 @@ Attachment: rca.md
 
 ## Sync Procedure
 
-```
+```text
 1. Verify Jira MCP is available (from context loading state)
    - If unavailable: queue to .jira-sync-queue.json, return
 
@@ -152,8 +153,10 @@ Attachment: rca.md
 ## Failure Handling
 
 If MCP operation fails:
+
 1. Do NOT fail the parent skill
 2. Save pending sync to `draft/tracks/<id>/.jira-sync-queue.json`:
+
    ```json
    {
      "pending": [
@@ -166,5 +169,6 @@ If MCP operation fails:
      ]
    }
    ```
+
 3. On next successful MCP connection, retry queued items
 4. Warn user: "Jira sync queued (MCP unavailable). Will retry on next connection."

package/core/shared/okf-retrieval.md

@@ -20,7 +20,7 @@ If `draft/wiki/` does **not** exist (monolith mode), skip this procedure entirel
 
 The bundle is a tree: `.ai-context.md` (index root: Synopsis + Concept Map) → section indexes (`systems/`, `features/`, `reference/`, `entrypoints/`, `overview/`) → concept pages. Each node advertises a `description` routing key. Navigate it, do not flatten it.
 
-```
+```text
 1. Frame the query
    Extract routing terms from the active task: domain nouns from spec.md
    acceptance criteria, file paths / module names / tech terms from plan.md,

package/core/shared/parallel-analysis.md

@@ -8,7 +8,7 @@
 
 ## Architecture
 
-```
+```text
 Phase 1 (Map) N parallel reader agents bounded scope per agent (4 modules each)
                  each agent reads source files in its assigned modules
                  each agent outputs (A) IR JSON array — structured metadata for tables/diagrams
@@ -97,7 +97,7 @@ Large modules with deep sub-module hierarchies (e.g., 500+ files with 5+ sub-mod
 Use this verbatim as the `prompt` field when spawning each reader agent via the `Agent` tool.
 Replace `{MODULE_LIST}`, `{REPO_ROOT}`, and `{GRAPH_DATA_SUMMARY}` before sending.
 
-```
+```text
 You are a module reader agent. You have two jobs for each assigned module:
 (A) Extract structured IR JSON — metadata for tables and diagrams
 (B) Write a full §7 deep-dive section in Markdown — prose the synthesis agent will paste verbatim into architecture.md
@@ -206,7 +206,7 @@ Only when the graph shows clear internal structure with its own public surface o
 Use this as the prompt for the single synthesis agent in Phase 2.
 Replace `{CONCATENATED_IRS}`, `{GRAPH_DEPENDENCY_DIAGRAM}`, and `{ARCHITECTURE_TEMPLATE_STRUCTURE}`.
 
-```
+```text
 You are the synthesis agent. Your job is to assemble draft/architecture.md from reader outputs.
 
 ## Inputs
@@ -305,7 +305,7 @@ For tier 1–2, skip parallelism — one reader agent handles all modules sequen
 
 When assigning modules to reader agents (tier 3+), apply this priority ordering:
 
-```
+```text
 Rule 1: Assign high fan-in modules to separate readers
         (modules with many callers produce IRs that many other IRs reference)
 
@@ -319,7 +319,8 @@ Rule 4: Use tier table above for modules-per-agent target
 ```
 
 Example grouping heuristic (adapt to actual fan-in data from graph):
-```
+
+```yaml
 reader_A: [highest fan-in module alone] — never share high-fan-in with others
 reader_B: [coupled pair: module_X + module_Y] — modules that call each other
 reader_C: [data layer modules] — shared persistence/cache modules together
@@ -332,24 +333,30 @@ reader_E: [infra/bootstrap modules] — low fan-in, foundational
 ## Failure Modes and Recovery
 
 ### Reader produces prose instead of IR
+
 **Detection:** Output doesn't start with `[` or fails JSON.parse.
 **Recovery:** Retry that reader with stricter constraint:
-```
+
+```text
 RETRY INSTRUCTION: Your previous output was not valid JSON. Output ONLY the JSON array.
 The first character of your response MUST be `[`. No preamble. No explanation.
 ```
+
 **Fallback:** If retry fails, run those modules through the standard sequential analysis.
 
 ### IR is too sparse AND deep-dive is too short
+
 **Detection:** IR `token_budget_used < 150` for a module with >20 files AND deep-dive < 100 lines.
 **Recovery:** Re-run that reader with explicit instruction to read more source files and expand the deep-dive.
 If only the IR is sparse but the deep-dive is substantive, no action needed — prose is the primary output.
 
 ### Synthesis agent re-reads source outside policy
+
 **Detection:** Tool calls to Read for files not in the permitted-sections list during synthesis.
 **Prevention:** The synthesis prompt lists exactly which sections permit source reads. Outside those, synthesis derives from reader prose and IR.
 
 ### One reader agent fails entirely
+
 **Detection:** Agent returns error or times out.
 **Recovery:** Run the failed module group through standard sequential analysis.
 The other readers' IRs are still valid — only the failed group needs re-work.
@@ -359,7 +366,7 @@ This is the blast-radius advantage over single-agent: a reader failure is a part
 
 ## Token Budget Model
 
-```
+```text
 Phase 1 readers (parallel, ceil(M/4) agents):
   Per agent: 4 modules × ~4K source tokens = ~16K input
                  IR output: ~2K tokens/agent

package/core/shared/pattern-learning.md

@@ -11,6 +11,7 @@ Referenced by: `/draft:bughunt`, `/draft:deep-review`, `/draft:review`, `/draft:
 Execute this phase **after** the main analysis and report generation are complete. This phase updates `draft/guardrails.md` with newly discovered patterns.
 
 **Skip this phase if:**
+
 - `draft/` directory does not exist (no Draft context)
 - Analysis found zero findings to learn from
 - Running in a read-only or preview mode
@@ -110,6 +111,7 @@ Append under `## Learned Anti-Patterns`:
 ```
 
 `graph_severity` derivation rules (from live hotspot query `scripts/tools/hotspot-rank.sh --repo .` fanIn values):
+
 - fanIn ≥ 10 in any evidence file → `critical`
 - fanIn 5–9 → `high`
 - fanIn 1–4 → `medium`

package/core/shared/template-contract.md

@@ -19,4 +19,4 @@ See [verification-gates.md](verification-gates.md) for the canonical WS-9 gate c
 
 **Required track artifacts (2.0):** `spec.md`, `plan.md`, `hld.md`, `lld.md`, `metadata.json`, `discovery.md`.
 
-**Scope fields:** `metadata.json:scope_includes` / `scope_excludes` (or spec frontmatter fallback) define track footprint; conflicts block parallel work without explicit exclusion.
+**Scope fields:** `metadata.json:scope_includes` / `scope_excludes` (or spec frontmatter fallback) define track footprint; conflicts block parallel work without explicit exclusion.

package/core/shared/tool-resolver.md

@@ -15,7 +15,7 @@ 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.
+`scripts/tools/git-metadata.sh` or `${CLAUDE_PLUGIN_ROOT}/...` invocation silently fails.
 
 Every skill MUST resolve `DRAFT_TOOLS` and invoke helpers as `"$DRAFT_TOOLS/<tool>.sh"`.
 
@@ -24,16 +24,20 @@ Every skill MUST resolve `DRAFT_TOOLS` and invoke helpers as `"$DRAFT_TOOLS/<too
 `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).
+2. `$PWD/scripts/tools` — dev / dogfooding when cwd IS the draft repo (guarded by
+   `resolve-tools.sh`'s own presence, so it can never misfire in a user project;
+   deliberately beats the install marker so a repo checkout always wins)
+3. `$(cat ~/.cache/draft/plugin-root)/scripts/tools` — install marker written by `draft install` (authoritative for installs)
+4. `${CLAUDE_PLUGIN_ROOT}/scripts/tools` — set in hook/MCP contexts; harmless to probe
+5. `installed_plugins.json → installPath` for `draft@*` — Claude Code's own registry (needs `jq`)
+6. `~/.claude/plugins/cache/*/draft/*/scripts/tools` — newest cache install (glob, `sort -V`)
+7. `~/.claude/plugins/marketplaces/*draft*/scripts/tools` — marketplace clone
+8. `~/.cursor/plugins/local/draft/scripts/tools` — Cursor local install
+9. `$PWD/scripts/tools` — last-resort cwd fallback (unguarded)
+
+The marker (step 3) is the fast, authoritative path for installs; steps 6–7 are the
+glob fallback that keeps resolution working on installs predating the marker (no
+reinstall required).
 
 ## Skill preamble (copy verbatim)
 
@@ -44,7 +48,7 @@ invocations (only the cwd does), so if you split helper calls into a later, sepa
 Bash block, re-establish `DRAFT_TOOLS` there too:
 
 ```bash
-DRAFT_TOOLS="$(cat ~/.cache/draft/plugin-root 2>/dev/null)/scripts/tools"
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$(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"
@@ -58,9 +62,10 @@ Then invoke helpers through the variable:
 ```
 
 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
+skills — it needs no marker file and no prior `source`. The full resolver
+(adding the `${DRAFT_PLUGIN_ROOT}` override, the guarded dogfood short-circuit,
+`${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

package/core/shared/vcs-commands.md

@@ -38,7 +38,7 @@ git rev-list [range]             # Commit listing
 
 Draft uses [Conventional Commits](https://www.conventionalcommits.org/) for traceability:
 
-```
+```text
 <type>(<track_id>): <description>
 
 [optional body]
@@ -49,11 +49,13 @@ Draft uses [Conventional Commits](https://www.conventionalcommits.org/) for trac
 Common `<type>` values: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`.
 
 Footer fields (when applicable):
+
 - `Refs: <issue or PR number>` — link to issue tracker
 - `Co-Authored-By: <name> <email>` — for AI-assisted commits
 
 If a Jira ticket is linked in `spec.md`, include it in the body or footer:
-```
+
+```text
 feat(add-auth): implement OAuth2 callback
 
 Refs: ENG-1234
@@ -78,6 +80,7 @@ git push -u origin <branch>
 ```
 
 Then open a PR via the `gh` CLI or the GitHub web UI:
+
 ```bash
 gh pr create --title "<title>" --body "<description>"
 ```

package/core/templates/ai-context.md

@@ -35,7 +35,7 @@ generated_at: "{ISO_TIMESTAMP}"
 
 ## Component Graph
 
-```
+```json
 {project_root}/
 ├── {module1}/ ← {5-10 word description}
 │ ├── {submod1}/ ← {description} ({Ncc} cc, {Nh} h)
@@ -114,6 +114,7 @@ None ✓
 {One paragraph or bullets explaining how components find each other.}
 
 Key injection points:
+
 - `{token1}`: {what it provides}
 - `{token2}`: {what it provides}
 - `{token3}`: {what it provides}
@@ -144,7 +145,7 @@ interface {ServiceName} {
 
 ## Dependency Graph
 
-```
+```json
 [{Component}] -> (HTTP) -> [{ExternalService}]
 [{Component}] -> (SQL) -> [{Database}]
 [{Component}] -> (gRPC) -> [{PeerService}]

package/core/templates/ai-profile.md

@@ -9,12 +9,14 @@ generated_at: "{ISO_TIMESTAMP}"
 # {PROJECT_NAME} Profile
 
 ## Project
+
 - Name: {PROJECT_NAME}
 - One-liner: {ONE_LINE_PRODUCT_DESCRIPTION}
 - Primary users: {USER_TYPES}
 - Repository layout: {monorepo|polyrepo|single-service}
 
 ## Stack
+
 - Language: {LANGUAGE}
 - Framework: {FRAMEWORK}
 - Database: {DATABASE}
@@ -26,17 +28,22 @@ generated_at: "{ISO_TIMESTAMP}"
 - Entry: {ENTRY_POINT}
 
 ## INVARIANTS
+
 {Top 3-5 critical invariants from .ai-context.md, one per line, with file:line refs}
 
 ## NEVER
+
 {2-3 safety rules — things that must never happen}
 
 ## Key Operational Models (from §6 / GRAPH:OPERATIONAL)
+
 - {Most critical flow 1 — one line}
 - {Most critical flow 2 (if space allows)}
 
 ## Active Tracks
+
 {List of active track IDs and one-line descriptions, or "none"}
 
 ## Recent Changes
+
 {Last 3-5 significant commits or changes, one per line}