@drafthq/draft 2.7.0

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

@@ -0,0 +1,282 @@
+# Draft Context Loading
+
+Standard procedure for loading Draft project context. All Draft commands that read project context follow this procedure before analysis or execution.
+
+Referenced by: All skills that load Draft project context — including `/draft:bughunt`, `/draft:review`, `/draft:deep-review`, `/draft:quick-review`, `/draft:learn`, `/draft:tech-debt`, `/draft:deploy-checklist`, `/draft:incident-response`, `/draft:documentation`, `/draft:adr`, `/draft:testing-strategy`, `/draft:standup`, `/draft:debug`
+
+## Context Loading Layers
+
+Draft uses a layered context system inspired by memory tiering — compact, always-available context at the top, with progressively deeper context loaded on demand.
+
+### Layer 0: Project Profile (Always Loaded)
+
+If `draft/.ai-profile.md` exists, **always** read it first. This ultra-compact file (20-50 lines) provides the minimum context every command needs: language, framework, database, auth, API style, critical invariants, safety rules, active tracks, and recent changes.
+
+- **Always loaded** regardless of task complexity
+- **Purpose**: Enables simple tasks (quick edits, config changes, small fixes) without loading full context
+- **Fallback**: If `.ai-profile.md` does not exist, proceed to Layer 1
+
+### Layer 0.5: Plugin Guardrails (Selective Loading)
+
+Layer 0.5 files live in the Draft plugin (`core/guardrails/`) and provide numbered, versioned baseline rules. **Project-level `draft/guardrails.md` always takes precedence** — if a project rule conflicts with a plugin rule, the project rule wins. See `core/guardrails/README.md` for vocabulary and full precedence order. (Portable improvement merged per manifest §2.1.)
+
+| File | Rules | Scope |
+|------|-------|-------|
+| `core/guardrails/README.md` | (index) | Vocabulary, ID prefixes, precedence rules |
+| `core/guardrails/code-quality.md` | CQ-001…CQ-012 | Code authoring, naming, error messages, structure |
+| `core/guardrails/design-norms.md` | DN-001…DN-010 | HLD/LLD depth split, diagrams, traceability, secrets |
+| `core/guardrails/review-checks.md` | RC-001…RC-015 | Cross-cutting review baseline (security, tests, observability) |
+| `core/guardrails/security.md` | SEC-01…SEC-10 | Hard security red lines + reasoning chain |
+| `core/guardrails/secure-patterns.md` | (cross-cites SEC) | Per-language enforcement of SEC rules |
+| `core/guardrails/dependency-triage.md` | RC-014 | Third-party dependency vulnerability handling |
+| `core/guardrails/language-standards.md` | Per-stack sections | Language-specific style, safety, test standards |
+| `core/guardrails.md` *(existing)* | G1…G8 | C++ systems guardrails — always enforced for C++ code (conditioned on language signals for public language-agnostic use) |
+
+#### Selective Loading Matrix (binding)
+
+This matrix is the **single source of truth** for which Layer 0.5 files load per command. Skills MUST honor it — over-loading is a Red Flag (see red-flags.md) and costs tokens per invocation.
+
+| Command type | Commands | Guardrails loaded |
+|---|---|---|
+| **Read-only** | `/draft:status`, `/draft:standup`, `/draft:tour`, `/draft:index`, `/draft:coverage` | **none** |
+| **Spec / Plan** | `/draft:new-track`, `/draft:decompose`, `/draft:adr`, `/draft:testing-strategy`, `/draft:documentation` | `design-norms.md` only (architecture-shaped rules) |
+| **Code-touching (generation)** | `/draft:implement`, `/draft:debug`, `/draft:change`, `/draft:revert` | `code-quality.md` + `security.md` + `secure-patterns.md` + `language-standards.md` (detected stack) |
+| **Review** | `/draft:review`, `/draft:quick-review`, `/draft:deep-review`, `/draft:assist-review`, `/draft:bughunt`, `/draft:tech-debt` | `review-checks.md` + `security.md` + `language-standards.md` (detected stack); deep-review also loads `code-quality.md` + `design-norms.md` |
+| **Deploy** | `/draft:deploy-checklist`, `/draft:incident-response` | `security.md` + `dependency-triage.md` |
+| **Pattern / Meta** | `/draft:learn`, `/draft:init` | `code-quality.md` + `security.md` (baseline only — pattern discovery uses project-level guardrails as primary signal) |
+
+**Sensitive-task escalation:** Even when the matrix says "none" or a narrow set, code-touching tasks whose title/spec mentions authentication, authorization, login, token, session, password, SQL, database query, subprocess, exec, crypto, encryption, hash, file upload, or external API input MUST additionally load `security.md` + `secure-patterns.md` and treat `[SEC-*]` violations as Critical.
+
+**Citation requirement:** When a rule is enforced or violated, cite the ID inline — `[SEC-03]`, `[CQ-007]`, `[RC-012]`, `[DN-004]`.
+
+**Fallback**: If `core/guardrails/` files are not present (older plugin installation), skip gracefully — no degradation.
+
+### Layer 1: Base Context Files
+
+If `draft/` directory exists, read and internalize these files in order:
+
+| Priority | File | Purpose | Fallback |
+|----------|------|---------|----------|
+| 1 | `draft/.ai-context.md` | Module boundaries, dependencies, critical invariants, concurrency model, error handling, data flows | `draft/architecture.md` (legacy projects) |
+| 2 | `draft/tech-stack.md` | Frameworks, libraries, constraints, **Accepted Patterns** | — |
+| 3 | `draft/product.md` | Product vision, user flows, requirements, **Guidelines** | — |
+| 4 | `draft/workflow.md` | Team conventions, testing preferences | — |
+| 5 | `draft/guardrails.md` | Hard guardrails, **Learned Conventions**, **Learned Anti-Patterns** | `draft/workflow.md` `## Guardrails` (legacy) |
+
+### Layer 1.5: Graph Context (When Available)
+
+If `draft/graph/schema.yaml` exists, the project has automated graph analysis data. This provides precise, deterministic structural context that complements the AI-generated `.ai-context.md`.
+
+**Always-load files** (compact, read alongside Layer 1):
+
+| File | Purpose | Content |
+|------|---------|---------|
+| `draft/graph/schema.yaml` | Snapshot metadata (engine, project, node/edge counts) | YAML, ~15 lines |
+| `draft/graph/architecture.json` | Node labels, edge types, languages, packages (fan-in/out), entry points, routes, hotspots | JSON |
+| `draft/graph/hotspots.jsonl` | Fan-in-ranked symbols, one object per line: `{id, name, fanIn}` | JSONL |
+
+Note: `.ai-context.md` embeds a condensed graph summary (`GRAPH:MODULES`, `GRAPH:HOTSPOTS`, `GRAPH:CYCLES`) for first-pass structural ground truth. `architecture.json` is authoritative for deep structure.
+
+Note: The canonical embedded mermaid diagrams are in architecture.md injection slots (`<!-- GRAPH:module-deps:START/END -->`, `<!-- GRAPH:proto-map:START/END -->`), refreshed by `draft:index`. For current data, regenerate via `scripts/tools/mermaid-from-graph.sh`.
+
+**Live structural queries** (run on demand — no per-language index files; the engine's model is unified):
+
+| Tool | Use When... |
+|------|-------------|
+| `scripts/tools/graph-callers.sh --symbol <name>` | Enumerating callers of a function |
+| `scripts/tools/graph-impact.sh --file <path>` / `--symbol <name>` | Sizing blast radius before a change |
+| `scripts/tools/cycle-detect.sh` | Checking for call cycles |
+| `scripts/tools/hotspot-rank.sh` | Fan-in ranking (live) |
+
+See `core/shared/graph-query.md` for the full query contract.
+
+**Fallback**: If `draft/graph/` does not exist, skip — no degradation.
+
+### Layer 2: Fact Registry (When Available)
+
+If `draft/.state/facts.json` exists, it provides granular fact-level context:
+
+- **For refresh operations**: Load facts sourced from changed files to enable contradiction detection
+- **For quality commands**: Load facts by category relevant to the current analysis dimension
+- **For implementation**: Load facts related to files being modified (match via `source_files`)
+
+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
+
+## Relevance-Scored Context Loading
+
+Not all context is equally relevant to every task. When a specific track or task is active, apply relevance scoring to prioritize which context sections are most useful.
+
+### 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`)
+
+Do NOT apply relevance scoring for commands that need full context (`/draft:init`, `/draft:deep-review`, `/draft:decompose`).
+
+### Scoring Procedure
+
+1. **Extract key concepts** from the active task:
+   - Read `spec.md` acceptance criteria and extract domain terms
+   - Read `plan.md` current task description and extract file paths, module names, technology terms
+   - Identify the primary concern: data flow, UI, API, security, performance, configuration, etc.
+
+2. **Score `.ai-context.md` sections** against the task concepts:
+
+| Section | Load When Task Involves... |
+|---------|--------------------------|
+| `## META` | Always (baseline) |
+| `## GRAPH:COMPONENTS` | Module boundary changes, new components |
+| `## GRAPH:MODULES`    | Module boundary changes, new components, cross-module work |
+| `## GRAPH:HOTSPOTS`   | Performance work, refactoring, changes to high-complexity files |
+| `## GRAPH:CYCLES`     | Dependency restructuring, module boundary decisions |
+| `## GRAPH:DEPENDENCIES` | Integration work, new external dependencies |
+| `## GRAPH:DATAFLOW` | Data pipeline changes, new flows |
+| `## INVARIANTS` | Always (safety critical) |
+| `## INTERFACES` | API changes, new implementations |
+| `## CATALOG:*` | Implementation work matching the category |
+| `## THREADS` | Concurrency-related tasks |
+| `## CONFIG` | Configuration changes |
+| `## ERRORS` | Error handling tasks |
+| `## CONCURRENCY` | Any async/parallel work |
+| `## EXTEND:*` | Adding new implementations of existing patterns |
+| `## TEST` | Always (need test commands) |
+| `## FILES` | Always (need file locations) |
+| `## VOCAB` | Domain-specific tasks |
+
+3. **Score graph files** (if `draft/graph/` exists) against the task concepts:
+
+| Graph source | Use When Task Involves... |
+|------------|--------------------------|
+| `architecture.json` | Module boundary changes, cross-module work, architecture analysis, API/route surface |
+| `hotspots.jsonl` | Performance work, refactoring, changes to high-fanIn symbols |
+| `scripts/tools/graph-callers.sh --symbol <name>` | Enumerating callers before a change |
+| `scripts/tools/graph-impact.sh --file <path>` / `--symbol <name>` | Tracing call paths, root cause analysis, function-level impact |
+| `scripts/tools/cycle-detect.sh` | Checking for call cycles |
+
+4. **Always include**: `META`, `INVARIANTS`, `TEST`, `FILES` (minimum context floor)
+5. **Include if relevant**: All other sections scored against task concepts
+6. **Result**: A focused subset of `.ai-context.md` that maximizes signal-to-noise for the current task
+
+### Fact Registry Relevance
+
+When `draft/.state/facts.json` exists, also load relevant facts:
+
+1. **By file overlap**: Facts whose `source_files` overlap with files the current task will modify
+2. **By category**: Facts in categories matching the task's primary concern
+3. **By recency**: Prefer facts with recent `last_active_at` timestamps (active code areas)
+4. **Limit**: Load at most 20 relevant facts per task to stay within token budget
+
+## Special Sections to Honor
+
+### Accepted Patterns (`tech-stack.md` → `## Accepted Patterns`)
+
+Patterns listed here are **intentional design decisions**. Do NOT flag these as bugs, issues, or violations. They represent deliberate trade-offs documented by the team.
+
+### Guardrails (`draft/guardrails.md`)
+
+Project-level `draft/guardrails.md` has three sections with different enforcement behavior:
+
+| Section | Behavior |
+|---------|----------|
+| **Hard Guardrails** (checked `[x]`) | Always flag violations as issues |
+| **Learned Conventions** | Skip these patterns during analysis — they are verified intentional patterns |
+| **Learned Anti-Patterns** | Always flag these patterns — they are verified problematic patterns |
+| **Hard Guardrails** (unchecked `[ ]`) | Ignore (not enforced) |
+
+**Legacy fallback:** If `draft/guardrails.md` does not exist, check `draft/workflow.md` for a `## Guardrails` section and enforce checked items there. Suggest running `/draft:learn migrate` to move to the new format.
+
+### Critical Invariants (`.ai-context.md` → `## Critical Invariants`)
+
+Invariants covering data safety, security, concurrency, ordering, and idempotency. Check for violations across all relevant code paths.
+
+## Track Context (when scoped to a track)
+
+If analyzing a specific track, also load:
+
+| File | Purpose |
+|------|---------|
+| `draft/tracks/<id>/spec.md` | Requirements, acceptance criteria, edge cases |
+| `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
+
+## Toolchain & MCP Auto-Connect
+
+After loading Layer 1 context, check `draft/workflow.md` → `## Toolchain` section. Draft uses standard `git` for VCS — see `core/shared/vcs-commands.md` for the command conventions.
+
+### MCP Auto-Connect (optional)
+
+If MCP integrations are checked in `draft/workflow.md`, verify availability at context-load time:
+
+| Server | Verification Call | On Success | On Failure |
+|--------|-------------------|------------|------------|
+| Jira MCP | `get_issue(key="TEST-1", prune_mode="minimal")` — expect error, confirms server responds | Record: `jira_mcp=available` | Record: `jira_mcp=unavailable`, degrade gracefully |
+| Confluence MCP | Check for Confluence tools in environment (e.g., `search_confluence`, `get_page`) | Record: `confluence_mcp=available` | Record: `confluence_mcp=unavailable`, degrade gracefully |
+| GitHub MCP | Check for GitHub tools in environment (e.g., `gh_pr_create`, `gh_issue_get`) | Record: `github_mcp=available` | Record: `github_mcp=unavailable`, fall back to `gh` CLI |
+
+MCP availability status is passed to downstream skills. Skills that can leverage MCPs will automatically use them when available, falling back to local-only analysis when unavailable.
+
+### Confluence Integration Points
+
+When Confluence MCP is available, skills can leverage it for documentation lookup:
+
+| Skill | Confluence Use |
+|-------|---------------|
+| `/draft:init` | Search for existing design documents, architecture docs related to the project |
+| `/draft:new-track` | Search for relevant RFCs, design docs, or prior art before starting a track |
+
+## Degradation Behavior
+
+| Scenario | Behavior |
+|----------|----------|
+| No `draft/` directory | Proceed with code-only analysis (no context enrichment) |
+| `.ai-profile.md` missing | Skip Layer 0; proceed directly to Layer 1 context loading |
+| `.ai-context.md` missing | Fall back to `draft/architecture.md` if it exists |
+| `tech-stack.md` missing | Skip framework-specific checks |
+| `product.md` missing | Skip product requirement verification |
+| `workflow.md` missing | Skip workflow preferences |
+| `guardrails.md` missing | Fall back to `workflow.md ## Guardrails`; if neither exists, skip guardrail enforcement |
+| `draft/graph/` missing | Skip Layer 1.5; no structural graph data available |
+| `facts.json` missing | Skip Layer 2; no fact-level context available |
+| Track files missing | Warn and proceed with project-level scope |
+
+## Context-Enriched Analysis
+
+Once loaded, Draft context enables analysis that pure code reading cannot:
+
+- **Architecture violations** — Coupling or boundary violations against intended module structure
+- **Framework-specific checks** — Anti-patterns for the specific frameworks in tech-stack.md
+- **Product requirement bugs** — Behavior that contradicts product.md user flows
+- **Invariant violations** — Data safety, security, concurrency, ordering, idempotency violations
+- **Concurrency analysis** — Race conditions and deadlocks informed by the documented concurrency model
+- **Error handling gaps** — Missing failure modes against documented failure recovery matrix
+- **State machine violations** — Invalid transitions, missing guards, states with no exit
+- **Consistency boundary bugs** — Stale reads, lost events at eventual-consistency seams
+- **Guardrail violations** — Checked hard guardrails and learned anti-patterns from guardrails.md
+- **False positive suppression** — Learned conventions and accepted patterns are skipped during analysis
+- **Precise dependency analysis** — Module boundaries, weighted edges, and cycle detection from graph data (Layer 1.5)
+- **Impact assessment** — Blast radius of file changes using graph callers/impact queries
+- **Hotspot awareness** — High-complexity, high-fanIn files flagged before modification
+
+## Future MCP Extensions
+
+The following MCP integrations are planned but not yet available. Skills referencing these should use graceful fallback (manual input or skip).
+
+| MCP Server | Purpose | Used By | Status |
+|---|---|---|---|
+| Monitoring MCP | Metrics dashboards, alert history, SLO status | `incident-response`, `deploy-checklist` | Planned |
+| CI/CD MCP | Build status, pipeline triggers, deployment history | `deploy-checklist` | Planned |
+| Chat MCP | Slack/Teams notifications, war room creation | `incident-response` | Planned |
+| Incident Management MCP | PagerDuty/OpsGenie integration, on-call schedules | `incident-response` | Planned |
+| APM MCP | Distributed traces, error tracking, performance profiles | `debug`, `incident-response` | Planned |
+
+When these MCPs become available, update the corresponding skills to auto-connect using the standard MCP auto-connect pattern defined above.

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

@@ -0,0 +1,106 @@
+# Git Report Metadata
+
+Shared procedure for gathering git metadata and generating YAML frontmatter in Draft reports.
+
+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.
+>
+> This doc covers session/report artifacts. For project-level artifacts see `core/templates/draft-metadata.json`.
+
+## Preferred: Deterministic Script
+
+Use `git-metadata.sh` from the plugin install, resolved via the canonical tool resolver (see [tool-resolver.md](tool-resolver.md)):
+
+```bash
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+bash "$DRAFT_TOOLS/git-metadata.sh" --yaml \
+    --project "$PROJECT" --module "$MODULE" \
+    --track-id "$TRACK_ID" --generated-by "draft:bughunt"
+```
+
+The script emits the full YAML frontmatter block shown below, including `commits_ahead_base` / `commits_behind_base` vs. `--base main`. Use `--json` for a machine-readable object with the same fields. Exits nonzero outside a git work tree.
+
+The manual commands below remain the specification and a fallback for environments where the script is not present.
+
+## Git Metadata Commands
+
+Gather git info before writing the report:
+
+```bash
+git branch --show-current # LOCAL_BRANCH
+git rev-parse --abbrev-ref @{upstream} 2>/dev/null || echo "none" # REMOTE/BRANCH
+git rev-parse HEAD # FULL_SHA
+git rev-parse --short HEAD # SHORT_SHA
+git log -1 --format=%ci HEAD # COMMIT_DATE
+git log -1 --format=%s HEAD # COMMIT_MESSAGE
+[ -n "$(git status --porcelain)" ] && echo "true" || echo "false" # dirty check
+```
+
+## YAML Frontmatter Template
+
+Every Draft report MUST include this frontmatter block at the top of the file. Replace placeholders with values from the commands above.
+
+```yaml
+---
+project: "{PROJECT_NAME}"
+module: "{MODULE_NAME or 'root'}"
+track_id: "{TRACK_ID or null}"
+generated_by: "{COMMAND_NAME}"
+generated_at: "{ISO_TIMESTAMP}"
+git:
+  branch: "{LOCAL_BRANCH}"
+  remote: "{REMOTE/BRANCH}"
+  commit: "{FULL_SHA}"
+  commit_short: "{SHORT_SHA}"
+  commit_date: "{COMMIT_DATE}"
+  commit_message: "{COMMIT_MESSAGE}"
+  dirty: {true|false}
+synced_to_commit: "{FULL_SHA}"
+---
+```
+
+### Field Notes
+
+- `project` — Derive from the repository name or `draft/product.md` title
+- `module` — Use `"root"` for project-level reports; use the module name/path for module-level reports
+- `track_id` — Set to the track ID if scoped to a track; `null` otherwise
+- `generated_by` — The Draft command that produced this report (e.g., `"draft:bughunt"`, `"draft:deep-review"`, `"draft:review"`)
+- `synced_to_commit` — Use the full SHA of HEAD at report time; or read from `draft/metadata.json:synced_to_commit` if available
+
+## Report Header Table
+
+Include this summary table immediately after the frontmatter for human readability:
+
+```markdown
+| Field | Value |
+|-------|-------|
+| **Branch** | `{LOCAL_BRANCH}` → `{REMOTE/BRANCH}` |
+| **Commit** | `{SHORT_SHA}` — {COMMIT_MESSAGE} |
+| **Generated** | {ISO_TIMESTAMP} |
+| **Synced To** | `{FULL_SHA}` |
+```
+
+## Timestamped File Naming
+
+Reports use timestamped filenames with a `-latest.md` symlink:
+
+```bash
+# Generate timestamp
+TIMESTAMP=$(date +%Y-%m-%dT%H%M)
+
+# Write report to timestamped file
+# Example: draft/bughunt-report-2026-03-15T1430.md
+
+# Refresh the "-latest.md" symlink deterministically (resolver as above):
+[ -x "$DRAFT_TOOLS/manage-symlinks.sh" ] && bash "$DRAFT_TOOLS/manage-symlinks.sh" draft/ bughunt
+# (Fallback when the script is unavailable:)
+# ln -sf <report-filename> <report-dir>/<report-type>-latest.md
+```
+
+Previous timestamped reports are preserved. The `-latest.md` symlink always points to the most recent report.

package/core/shared/graph-query.md

@@ -0,0 +1,239 @@
+# Graph Query Subroutine
+
+Shared procedure for querying the knowledge graph from any skill. The graph provides precise, deterministic structural data about the codebase — module boundaries, dependency edges, hotspots, proto API surface, and symbol indexes.
+
+This is the **single source of truth** for graph lookup procedure. Consumer skills MUST reference this file rather than inlining their own lookup logic.
+
+Referenced by: `/draft:init`, `/draft:implement`, `/draft:bughunt`, `/draft:review`, `/draft:deep-review`, `/draft:quick-review`, `/draft:debug`, `/draft:decompose`, `/draft:new-track`, `/draft:tech-debt`, `/draft:deploy-checklist`, `/draft:learn`, `/draft:index`
+
+## Mandatory Lookup Contract
+
+Any code-touching skill that needs to discover files, modules, symbols, callers, or blast-radius **MUST** follow this lookup order whenever `draft/graph/schema.yaml` exists:
+
+1. **Graph first** — the committed snapshot (`architecture.json`, `hotspots.jsonl`) and the live query tools (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, `cycle-detect.sh`, `hotspot-rank.sh`).
+2. **Generated context second** — `draft/.ai-context.md`, relevant `draft/architecture.md` slices, track-level `hld.md`/`lld.md`.
+3. **Source file reads third** — narrow via tiers 1–2, then **Read** the candidate files. Reading is **not optional**: see §Ground-Truth Discipline below.
+4. **Filesystem `grep`/`find`/`rg` last** — only after an explicit graph miss.
+
+**If a lower tier is used before a higher tier, that is a Red Flag** ([red-flags.md](red-flags.md)). The skill must report it in its Graph Usage Report footer (see below) with justification.
+
+**Required fallback sentence format** (verbatim) before any filesystem search after a graph miss:
+
+> `Graph returned no match for <X>; falling back to grep.`
+
+If `draft/graph/schema.yaml` is **absent**, the graph contract is satisfied — proceed directly to tier 2/3/4 as needed and record `Graph files queried: NONE — graph data unavailable` in the report footer.
+
+## Ground-Truth Discipline (mandatory)
+
+The graph is the **index**, not the **territory**. Graph hits identify candidates; **Read** validates them. Skills that ship claims about code behavior, scope coverage, hotspot status, or risk **without opening the cited files** routinely produce confidently-wrong output (e.g. citations marked `TBD` for files that were "found via graph but never opened"; scope statements that exclude the actual code path the problem statement names).
+
+The following rules apply to every code-touching skill output. They are non-negotiable for `criticality: standard | high | mission-critical` work; `criticality: low` (quick) tracks may skip rule **G3** only.
+
+**G1. Read before you cite.** Any `file:line`, `func()`, or `symbol` reference written into a deliverable (spec / hld / lld / plan / review / audit / debug report) must come from a file the skill has actually opened in this run. The graph tells you *which* file; Read confirms the line is what you claim it is.
+
+**G2. Read before you scope.** A track / phase / audit / review may not declare a code path **in-scope** or **out-of-scope** without at least one Read on a representative file in that path. The graph's module list is a candidate set — it does not establish that the candidate contains the cost the problem names.
+
+**G3. No `TBD` citations on `Modified` or `Existing` modules.** When a deliverable's Component / Class / Symbol table marks a module `Status: Modified` or `Status: Existing`, every Citation cell must resolve to a real `path:line` from a file read in this run. `TBD` is reserved for `Status: New` modules whose source files have not been authored yet, and even then the planned file path must be filled (`Citation: path/to/new_file.h (planned)`).
+
+**G4. No claim about code behavior from graph metadata alone.** Statements of the form "*X writes to disk*", "*Y blocks on Z*", "*this is the hotspot*", "*this is the only path*" must be backed by a Read. Graph fan-in / fan-out / complexity scores are necessary signal, not sufficient evidence. If you have only graph data, write *"graph signal suggests X; not yet validated against source"* rather than asserting X.
+
+**G5. Scope-vs-problem coverage check before promote.** Before promoting `spec-draft.md` → `spec.md`, before generating `hld.md` / `lld.md`, and before declaring a review / audit complete: enumerate the cost / behavior / risk terms in the problem statement, and confirm that the in-scope file set (per G2) covers each. If any term is not covered, surface the gap before commit — do not silently ship a scope that excludes the named cost.
+
+### Self-check (run before emitting the Graph Usage Report)
+
+Append the answers to your scratch notes; the skill output need not include them unless asked.
+
+1. Did I open every file whose `path:line` appears in this output? (yes / list misses)
+2. Are any `Modified` / `Existing` modules carrying `Citation: TBD`? (no / list)
+3. Did I declare anything in-scope or out-of-scope? If yes, did I Read at least one file in that path? (yes / list)
+4. Did I make a claim about what code does (writes / blocks / loops / fails) based only on graph metadata? (no / list)
+5. Does the in-scope set cover every cost term in the problem statement? (yes / list gaps)
+
+A single "no" / "list" answer is a halt — fix and re-check before output.
+
+## Concept-to-Files Recipe
+
+Use this recipe whenever the user names a concept, feature, or domain term ("in-memory shuffle", "auth flow", "ingest pipeline") and you need to locate the implementing files. **Run it before any filesystem search.**
+
+1. **Concept → modules** — `grep` the concept token against `draft/graph/architecture.json` (`.packages[].name`) and `draft/.ai-context.md` (module headings). Record the candidate module list.
+2. **Concept → symbols/callers** — for a named function, run `scripts/tools/graph-callers.sh --repo . --symbol <name>` to find call sites, and `scripts/tools/graph-impact.sh --repo . --symbol <name>` for transitive dependents. These are the authoritative structural answers.
+3. **Modules → risk ranking** — cross-reference `draft/graph/hotspots.jsonl` (or `scripts/tools/hotspot-rank.sh`). High-fanIn symbols are the most likely entry points for impact.
+4. **Concept → public API** — for API-shaped concepts, consult `architecture.json` `.routes` (detected HTTP/gRPC/GraphQL routes) for matching service surface.
+5. **Graph miss → grep fallback** — only if steps 1–4 return nothing relevant, emit the fallback sentence and use `grep`/`find`. Narrow the search by file extension and exclude `node_modules`, `vendor`, `dist`, `build`, `.git`.
+
+## Graph Usage Report (Mandatory Footer)
+
+Every code-touching skill output MUST end with this footer block. The lint check `scripts/tools/check-graph-usage-report.sh` rejects outputs missing the section.
+
+```md
+## Graph Usage Report
+
+- Graph files queried: <comma-separated list, e.g. `architecture.json, hotspots.jsonl` and/or query tools like `graph-callers.sh` — or `NONE` with justification below>
+- Modules identified via graph: <comma-separated module names, or `none`>
+- Files identified via graph: <integer count>
+- Filesystem grep fallbacks: <list of `<pattern>` searches with one-line justification each, or `none`>
+- 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.
+
+## Telemetry Fields (graph adherence)
+
+Skills that emit telemetry via [emit-skill-metrics.sh](../../scripts/tools/emit-skill-metrics.sh) MUST include these fields in the JSON payload so contract adherence and token-floor trends can be monitored:
+
+| Field | Type | Description |
+|---|---|---|
+| `graph_queries` | int | Number of graph artifacts loaded plus live graph query-tool invocations during the run |
+| `fallback_grep_count` | int | Number of `grep`/`find` fallbacks invoked after an explicit graph miss |
+
+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:
+
+```bash
+DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$HOME/.cursor/plugins/local/draft/scripts/tools"
+[ -d "$DRAFT_TOOLS" ] || DRAFT_TOOLS="$PWD/scripts/tools"
+```
+
+| Wrapper | Graph mode | Behavior on missing graph |
+|---|---|---|
+| `bash "$DRAFT_TOOLS/hotspot-rank.sh" [--top N] [--module NAME]` | `--mode hotspots` | Emits `{hotspots:[],source:"unavailable"}` and exits 2 |
+| `bash "$DRAFT_TOOLS/cycle-detect.sh"` | `--mode cycles` | Emits `{cycles:[],source:"unavailable"}` and exits 2 |
+| `bash "$DRAFT_TOOLS/mermaid-from-graph.sh" [--diagram module-deps\|proto-map]` | `--mode mermaid` | Emits an empty mermaid block and exits 2 |
+
+Use the raw `graph` CLI directly for the lower-level modes documented below.
+
+## Pre-Check
+
+Verify graph data exists before any graph operation:
+
+```bash
+ls draft/graph/schema.yaml 2>/dev/null
+```
+
+If absent, **skip all graph operations silently**. Graph enriches analysis — it never gates it. All skills must work identically without graph data.
+
+## Engine + snapshot model
+
+The graph is produced by the **codebase-memory-mcp** engine (a single binary; see [bin/README.md](../../bin/README.md)). There are two ways skills consume it:
+
+1. **Live queries** (preferred when the engine is resolvable) — the shell tools under `scripts/tools/` drive the engine on demand (it auto-indexes into its own cache). No committed files required.
+2. **Committed snapshot** (`draft/graph/`) — a small, derived, PR-reviewable snapshot written by `scripts/tools/graph-snapshot.sh`. It exists for reviewability and for the Copilot/Gemini integrations, which cannot run the engine but can read committed files. Git remains the source of truth.
+
+When `draft/graph/` exists, the snapshot contains:
+
+| File | Load | Content |
+|------|------|---------|
+| `schema.yaml` | Always | Engine + project metadata, node/edge counts, artifact list. Its presence **gates** graph use (see Pre-Check). |
+| `architecture.json` | Always | `get_architecture(all)` output: node labels, edge types, languages, packages (with fan-in/out), entry points, routes, hotspots. |
+| `hotspots.jsonl` | Always | Fan-in-ranked symbols, one JSON object per line: `{id, name, fanIn}`. |
+| `module-deps.mermaid` | Diagram injection | File co-change coupling diagram (`FILE_CHANGES_WITH`). |
+| `proto-map.mermaid` | Diagram injection | Detected service-route diagram (`Route` nodes). |
+
+The engine uses a **unified, language-agnostic** node model — `Function`, `Method`, `Class`, `Module`, `File`, `Folder`, `Route`, `Section`, `Variable` (language is inferred from file extension) — and edges `CALLS`, `DEFINES`, `CONTAINS_FILE`, `IMPORTS`, `HTTP_CALLS`, `FILE_CHANGES_WITH`, `SEMANTICALLY_RELATED`, `SIMILAR_TO`. There are **no** per-language index files and no `ctags-sym` fallback; that detail is served by live queries against the unified model.
+
+**Always-load files** are compact and should be read during context loading for any task that touches code structure.
+
+## 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.
+
+### Callers — who calls this function?
+
+```bash
+scripts/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.
+
+### 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
+```
+
+Output: `{target, kind, impacted[{name, file, hop}], source}`. Use when sizing risk before modifying a file or symbol, especially high-fan-in hotspots.
+
+### Hotspots — fan-in ranking
+
+```bash
+scripts/tools/hotspot-rank.sh --repo . [--top N]
+```
+
+Output: `{hotspots[{id, name, fanIn}], source}` (server-computed by the engine).
+
+### Cycles — call-cycle detection
+
+```bash
+scripts/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).
+
+### Modules — dependency overview
+
+Read `draft/graph/architecture.json` (`.packages` for module fan-in/out, `.node_labels`/`.edge_types` for shape, `.routes` for service surface), or regenerate it with `scripts/tools/graph-snapshot.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
+```
+
+Emits a ready-to-inject ` ```mermaid ``` ` block, or an empty stub (exit 2) when the engine is unavailable. The committed `draft/graph/*.mermaid` snapshots are written by `graph-snapshot.sh`.
+
+### Building / refreshing the snapshot
+
+```bash
+scripts/tools/graph-snapshot.sh --repo .
+```
+
+Writes the committed `draft/graph/` snapshot (`schema.yaml`, `architecture.json`, `hotspots.jsonl`, `*.mermaid`). Run during `/draft:init` and `/draft:index`, or whenever the reviewable graph state should be refreshed.
+
+## Finding the Engine (Resolution + Usage Report)
+
+The engine is the `codebase-memory-mcp` binary. Resolution order (implemented by `scripts/tools/_lib.sh:find_memory_bin`):
+
+1. `DRAFT_MEMORY_BIN` — explicit override (pinned installs, testing).
+2. `codebase-memory-mcp` on `$PATH` — global/dev installs.
+3. `~/.cache/draft/bin/codebase-memory-mcp` — the Draft-managed location (`scripts/fetch-memory-engine.sh` installs it here; `draft install claude-code`/`draft install cursor` run that on install unless `--no-graph`).
+4. `bin/<os>-<arch>/codebase-memory-mcp` under the plugin/repo root — optional vendored fallback (air-gapped only).
+
+`DRAFT_MEMORY_DISABLE=1` forces the engine off. There is **no** legacy `graph`/`graph-clang` fallback.
+
+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)"
+# {"status":"ok","engine_bin":"...","source":"managed|path|bundled:<arch>|override","arch":"..."}
+```
+
+## Usage Report Contract
+
+After successful detection, `draft/.graph-binary-report.json` contains: `detected_at`, `engine_bin`, `source` (`path` | `managed` | `bundled:<arch>` | `override`), `arch`, `status`. It is a derived artifact (safe to prune), regenerated by each graph-using command that calls the verifier.
+
+## Building the Snapshot
+
+Run during `draft:init` / `draft:index`, or manually:
+
+```bash
+scripts/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); the snapshot is re-derived on each run.
+
+## Graceful Degradation
+
+| Scenario | Behavior |
+|----------|----------|
+| No engine resolvable (or `DRAFT_MEMORY_DISABLE=1`) | Skip graph build 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 |
+| `draft/graph/` snapshot exists | Load always-load files during context loading; use live query tools as needed |
+| Stale snapshot | Still useful — structural changes are infrequent. Re-run `graph-snapshot.sh` (or init) to refresh. |

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

@@ -0,0 +1,22 @@
+---
+shared: graph-usage-report
+applies_to: quality + init + graph skills
+---
+
+# Graph Usage Report (Canonical Footer)
+
+Every code-touching skill output that performs graph or filesystem discovery MUST end with this footer block. The lint hook `scripts/tools/check-graph-usage-report.sh` validates the section on save.
+
+See [graph-query.md](graph-query.md) §Graph Usage Report (Mandatory Footer) for the full lookup contract. Emit this block verbatim:
+
+```md
+## Graph Usage Report
+
+- Graph files queried: <comma-separated list, e.g. `architecture.json, hotspots.jsonl` and/or query tools like `graph-callers.sh` — or `NONE` with justification below>
+- Modules identified via graph: <comma-separated module names, or `none`>
+- Files identified via graph: <integer count>
+- Filesystem grep fallbacks: <list of `<pattern>` searches with one-line justification each, or `none`>
+- 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.