@drafthq/draft 3.0.0 → 3.1.5

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.0.0",
+  "version": "3.1.5",
   "author": {
     "name": "mayurpise"
   },

package/README.md

@@ -129,7 +129,7 @@ curl -o .gemini.md https://raw.githubusercontent.com/drafthq/draft/main/integrat
 | **`/draft:docs`** | Router for authoring and documentation workflows |
 | **`/draft:discover`** | Router for discovery, debugging, investigation, and quality |
 | **`/draft:init`** | Analyze codebase, create context files + state tracking |
-| **`/draft:index`** | Aggregate monorepo service contexts |
+| **`/draft:graph`** | Build / refresh the knowledge-graph snapshot |
 | **`/draft:new-track`** | Collaborative spec + plan with AI |
 | **`/draft:decompose`** | Module decomposition with dependency mapping |
 | **`/draft:implement`** | TDD workflow with checkpoints |
@@ -187,7 +187,7 @@ The graph powers `/draft:graph` and `/draft:impact`, enriches `/draft:bughunt` a
 
 ### Deterministic helper tools
 
-Skills also call into **34 shell helpers** under `scripts/tools/` for mechanical work — git metadata, file classification, test-framework detection, hotspot ranking, freshness checks, ADR indexing, and Open Knowledge Format emission/validation (`okf-emit.sh`, `okf-bundle.sh`, `okf-check.sh`). All emit JSON or markdown, follow a uniform exit-code contract, and degrade gracefully when their input source is unavailable.
+Skills also call into **shell helpers** under `scripts/tools/` for mechanical work — git metadata, file classification, test-framework detection, hotspot ranking, freshness checks, ADR indexing, and live graph queries (`graph-callers.sh`, `graph-impact.sh`, `hotspot-rank.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh`). All emit JSON or markdown, follow a uniform exit-code contract, and degrade gracefully when their input source is unavailable.
 
 ---
 
@@ -234,7 +234,7 @@ AI tools are fast but unstructured. Draft applies Context-Driven Development to
 ```
 product.md       →  "Build a task manager"
 tech-stack.md    →  "React, TypeScript, Tailwind"
-architecture.md  →  Comprehensive: 28 sections + 5 appendices, Mermaid diagrams (source of truth). Mature brownfield projects with strong existing agent docs (CLAUDE.md, INVARIANTS.md, etc.) receive early Context Quality Audit, graph fidelity dashboard, and explicit Relationship + Gaps sections (no blind duplication).
+architecture.md  →  Comprehensive: 10-section graph-primary engineering reference, Mermaid diagrams (source of truth). Mature brownfield projects with strong existing agent docs (CLAUDE.md, INVARIANTS.md, etc.) receive early Context Quality Audit, graph fidelity dashboard, and explicit Relationship + Gaps sections (no blind duplication).
 .ai-context.md   →  200-400 lines: condensed from architecture.md (token-optimized AI context)
 .state/          →  freshness hashes, signal classification, run memory (incremental refresh)
 spec.md          →  "Add drag-and-drop reordering"

package/bin/README.md

@@ -46,16 +46,13 @@ and `verify-graph-binary.sh`. The shared wrappers (`memory_cli`,
 
 ## Snapshot artifacts
 
-`scripts/tools/graph-snapshot.sh` writes a small, committed, PR-reviewable snapshot under `<repo>/draft/graph/`:
+`draft/graph/` holds a single committed file:
 
 | Artifact | Content |
 |----------|---------|
-| `schema.yaml` | Engine + project metadata, node/edge counts, artifact list (gates graph use). |
-| `architecture.json` | `get_architecture(all)`: node labels, edge types, languages, packages (fan-in/out), entry points, routes, hotspots. |
-| `hotspots.jsonl` | Fan-in-ranked symbols, one JSON object per line. |
-| `module-deps.mermaid` | File co-change coupling diagram. |
-| `proto-map.mermaid` | Detected service-route diagram. |
-| `okf/` | Open Knowledge Format v0.1 bundle (`index.md` + cross-linked `modules/<name>.md`), emitted by default — a portable markdown mirror of the graph. Validate with `okf-check.sh`. |
+| `schema.yaml` | Engine + project metadata, node/edge counts, point-of-index counts (gates graph use). |
+
+Structural graph data (architecture, hotspots, module deps, service routes) is queried **live** from the `codebase-memory-mcp` engine — either via the wrapper scripts under `scripts/tools/` (`graph-callers.sh`, `graph-impact.sh`, `hotspot-rank.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh`) or directly with `codebase-memory-mcp cli <tool> '<json>'`.
 
 ## Offline / air-gapped distributions
 

package/core/shared/condensation.md

@@ -88,16 +88,16 @@ Transform each `architecture.md` section into machine-optimized format using thi
 
 #### Step 3.5: Generate Graph Summary Sections
 
-If `draft/graph/schema.yaml` exists, generate these sections from the snapshot (`draft/graph/architecture.json`, `draft/graph/hotspots.jsonl`) and the live query tools:
+If `draft/graph/schema.yaml` exists, generate these sections via live engine queries.
 
 **GRAPH:MODULES** (tier ≥ 2 only):
-- Read `draft/graph/architecture.json` → `.packages[]` (each has `name`, `node_count`, `fan_in`, `fan_out`)
+- Query: `scripts/tools/graph-arch.sh --repo . | jq '.packages[]'` (each has `name`, `node_count`, `fan_in`, `fan_out`)
 - Format: `{name}|{node_count} nodes|fan_in:{fan_in} fan_out:{fan_out}`
 - Order by `node_count` descending
 - Omit this section entirely for tier-1 codebases (≤5 modules) where Component Graph is sufficient
 
 **GRAPH:HOTSPOTS** (all tiers):
-- Read `draft/graph/hotspots.jsonl` (already fan-in-ranked), take top 10
+- Query: `scripts/tools/hotspot-rank.sh --repo . --top 10`; take top 10 results
 - Format: `{name}|fanIn:{fanIn}` (use `id` for disambiguation when names collide)
 - Always include regardless of tier
 
@@ -108,20 +108,20 @@ If `draft/graph/schema.yaml` exists, generate these sections from the snapshot (
 - Always include — absence is positive signal that the call graph is acyclic
 
 **GRAPH:MODULE-HOTSPOTS** (tier ≥ 3 only):
-- Read `draft/graph/hotspots.jsonl`; group by the package segment of each `id` (the qualified name minus the leaf symbol)
+- Query: `scripts/tools/hotspot-rank.sh --repo .`; group results by the package segment of each `id` (the qualified name minus the leaf symbol)
 - For each module: take its top 3 symbols by `fanIn`, format as indented lines under the module name
 - Format: `{module}: {name}|fanIn:{N}` with subsequent symbols indented to align
 - Order modules by their highest-fanIn symbol, descending
 - Omit modules with no hotspot entries; omit entire section for tier 1–2 (covered by global GRAPH:HOTSPOTS)
 
 **GRAPH:FAN-IN** (tier ≥ 3 only):
-- Read `architecture.json` → `.packages[]`, use the `fan_in` field per module
+- Query: `scripts/tools/graph-arch.sh --repo . | jq '.packages[]'`, use the `fan_in` field per module
 - Format: `{name}|fanIn:{fan_in}|fanOut:{fan_out}`
 - Order by `fan_in` descending; include only modules with `fan_in ≥ 2`; cap at 15 rows
 - Omit entire section for tier 1–2 (trivially small graph)
 
-**GRAPH:PROTO-MAP** (only when `architecture.json` `.routes` is non-empty):
-- Read `architecture.json` → `.routes[]` (each has `method`, `path`, `handler`)
+**GRAPH:PROTO-MAP** (only when routes are non-empty):
+- Query: `scripts/tools/graph-arch.sh --repo . | jq '.routes[]'` (each has `method`, `path`, `handler`)
 - Format: `{method} {path} → {handler}`
 - One line per route
 - Omit entire section if `.routes` is empty — do not write an empty section
@@ -168,7 +168,7 @@ Before writing `draft/.ai-context.md`, verify:
 - [ ] GRAPH:CYCLES present ("None ✓" or cycle list; or note if graph absent)
 - [ ] GRAPH:MODULE-HOTSPOTS present for tier ≥ 3 (or note if no hotspot data)
 - [ ] GRAPH:FAN-IN present for tier ≥ 3
-- [ ] GRAPH:PROTO-MAP present when `stats.proto_rpcs > 0` (omit entirely if no protos)
+- [ ] GRAPH:PROTO-MAP present when engine reports non-empty routes (omit entirely if no protos)
 - [ ] YAML frontmatter metadata is present at the top
 
 #### Step 7: Write Output

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

@@ -71,13 +71,9 @@ If `draft/graph/schema.yaml` exists, the project has automated graph analysis da
 
 | 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 |
+| `draft/graph/schema.yaml` | Gate marker (engine + project metadata + point-of-index counts); presence gates graph use | YAML, ~15 lines |
 
-The snapshot also includes `draft/graph/okf/` — an Open Knowledge Format v0.1 bundle (`index.md` + `modules/*.md`) emitted by default. It is a portable mirror of the graph, not an always-load target.
-
-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: `.ai-context.md` embeds a condensed graph summary (`GRAPH:MODULES`, `GRAPH:HOTSPOTS`, `GRAPH:CYCLES`) for first-pass structural ground truth. Deep structural data is queried live from the engine (see Live structural queries below).
 
 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:init`. For current data, regenerate via `scripts/tools/mermaid-from-graph.sh`.
 
@@ -151,12 +147,12 @@ Do NOT apply relevance scoring for commands that need full context (`/draft:init
 | `## FILES` | Always (need file locations) |
 | `## VOCAB` | Domain-specific tasks |
 
-3. **Score graph files** (if `draft/graph/` exists) against the task concepts:
+3. **Score graph queries** (if `draft/graph/schema.yaml` 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-arch.sh --repo .` | Module boundary changes, cross-module work, architecture analysis, API/route surface |
+| `scripts/tools/hotspot-rank.sh --repo .` | 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 |

package/core/shared/graph-query.md

@@ -10,7 +10,7 @@ Referenced by: `/draft:init`, `/draft:implement`, `/draft:bughunt`, `/draft:revi
 
 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`).
+1. **Graph first** — live engine queries via the query tools (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, `cycle-detect.sh`, `hotspot-rank.sh`, `mermaid-from-graph.sh`), which drive the local `codebase-memory-mcp` engine on demand. Draft is **engine-only**: there is no committed machine-readable graph to read — `draft/graph/` holds only `schema.yaml` (the gate marker).
 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.
@@ -55,10 +55,10 @@ A single "no" / "list" answer is a halt — fix and re-check before output.
 
 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.
+1. **Concept → modules** — query the engine for the package list (`scripts/tools/graph-arch.sh --repo . | jq -r '.packages[].name'`) and cross-reference `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.
+3. **Modules → risk ranking** — rank with `scripts/tools/hotspot-rank.sh --repo . [--top N]`. High-fanIn symbols are the most likely entry points for impact.
+4. **Concept → public API** — for API-shaped concepts, read the engine's `.routes` (`get_architecture` output, 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)
@@ -68,7 +68,7 @@ Every code-touching skill output MUST end with this footer block. The lint check
 ```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>
+- Graph files queried: <comma-separated list of query tools invoked, e.g. `graph-callers.sh, hotspot-rank.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`>
@@ -106,7 +106,7 @@ DRAFT_TOOLS="${DRAFT_PLUGIN_ROOT:-$HOME/.claude/plugins/draft}/scripts/tools"
 | `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.
+For lower-level modes, call the engine directly: `codebase-memory-mcp cli <tool> '<json>'` (see the tool list in [bin/README.md](../../bin/README.md)).
 
 ## Pre-Check
 
@@ -118,27 +118,26 @@ 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
+## Engine model (engine-only)
 
-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:
+The graph is produced by the **codebase-memory-mcp** engine (a single binary; see [bin/README.md](../../bin/README.md)). Draft is **engine-only and opinionated**: the engine is the one structural source of truth, queried live. There is **no committed machine-readable mirror** of the graph — no `architecture.json`, `hotspots.jsonl`, `*.mermaid`, or `okf/`. Those were lossy, went stale on the next commit, and duplicated what the engine serves precisely on demand.
 
-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.
+The only committed file is the gate marker:
 
-When `draft/graph/` exists, the snapshot contains:
+| File | Role |
+|------|------|
+| `draft/graph/schema.yaml` | Engine + project metadata and point-of-index counts (provenance, not authoritative). Carries **no graph data**. Its presence is the **gate** (see Pre-Check) — it signals the engine is wired for this repo. Written by `scripts/tools/graph-snapshot.sh`. |
 
-| 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). |
-| `okf/` | On demand | Open Knowledge Format v0.1 bundle (emitted by default): `index.md` (reserved bundle root, no frontmatter) + cross-linked `modules/<name>.md` concept pages. Portable, vendor-neutral mirror of the graph; validate with `okf-check.sh`. |
+All structural data is obtained live by shelling out to the engine — either through the query-tool wrappers under `scripts/tools/` or directly via `codebase-memory-mcp cli <tool> '<json>'`. The shell tools auto-index the repo into the engine's own cache on demand, so no committed files are required.
 
-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.
+### How skills query (engine is the interface; jq is optional)
 
-**Always-load files** are compact and should be read during context loading for any task that touches code structure.
+- **The engine is the query.** `codebase-memory-mcp cli <tool> '<json>'` (and the wrappers that call it) is how you ask — it takes JSON args and returns JSON. There is no other query surface.
+- **Prefer the wrappers — they resolve the engine for you.** `graph-arch.sh` (architecture view: packages/routes/layers/hotspots), `graph-callers.sh`, `hotspot-rank.sh`, `graph-impact.sh`, `cycle-detect.sh`, `mermaid-from-graph.sh` return already-shaped JSON. The engine binary is usually **not on `$PATH`** (it lives under `~/.cache/draft/bin/`); the wrappers locate it via `_lib.sh:find_memory_bin`, so a skill using a wrapper needs no resolution step.
+- **Raw `codebase-memory-mcp cli` requires resolving the binary first** (it is not on `$PATH`): `CM="${DRAFT_MEMORY_BIN:-$HOME/.cache/draft/bin/codebase-memory-mcp}"; "$CM" cli <tool> '<json>'`. Reach for this only for tools without a wrapper (`search_graph`, `search_code`, `trace_path`).
+- **`jq` is not a query tool — it only trims output.** Reach for it solely to slice a *large* response (chiefly the `get_architecture` blob) down to the field you need, for token economy. The agent can read raw JSON directly; jq is an optimization, not a requirement. Don't pipe wrapper output through jq unless you genuinely need a sub-field.
+
+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`. Each node carries `file_path` + `start_line`/`end_line` and rich `properties` (complexity, signature, parent_class), and the engine exposes full-text (`search_code`) and semantic search — none of which a committed snapshot reproduced.
 
 ## Query Tools
 
@@ -179,7 +178,14 @@ Output: `{cycles[[a,b],[a,b,c]], source}` — fixed-length 2- and 3-node `CALLS`
 
 ### 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 .`.
+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 . \
+  | jq '{packages, node_labels, edge_types, routes, layers, boundaries}'
+```
+
+`.packages` gives module fan-in/out, `.node_labels`/`.edge_types` the shape, `.routes` the service surface, `.layers`/`.boundaries` the dependency direction.
 
 ### Mermaid — diagram text
 
@@ -188,15 +194,15 @@ scripts/tools/mermaid-from-graph.sh --repo . --diagram module-deps   # co-change
 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`.
+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.
 
-### Building / refreshing the snapshot
+### Indexing / refreshing the gate marker
 
 ```bash
 scripts/tools/graph-snapshot.sh --repo .
 ```
 
-Writes the committed `draft/graph/` snapshot (`schema.yaml`, `architecture.json`, `hotspots.jsonl`, `*.mermaid`, plus the Open Knowledge Format bundle under `okf/`). Run during `/draft:init` and `/draft:graph`, or whenever the reviewable graph state should be refreshed.
+Indexes the repo into the engine and writes the `draft/graph/schema.yaml` gate marker. It writes **no** graph data. Run during `/draft:init` and `/draft:graph`, or whenever the index should be refreshed.
 
 ## Finding the Engine (Resolution + Usage Report)
 
@@ -220,7 +226,7 @@ ENGINE_INFO="$(scripts/tools/verify-graph-binary.sh --repo . --json 2>/dev/null
 
 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
+## Indexing the Repo
 
 Run during `draft:init` / `draft:graph`, or manually:
 
@@ -228,13 +234,13 @@ Run during `draft:init` / `draft:graph`, or manually:
 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.
+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.
 
 ## 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` |
+| No engine resolvable (or `DRAFT_MEMORY_DISABLE=1`) | Skip graph indexing in init; all skills proceed without graph data; tools emit `source: unavailable` |
 | Engine present but a query fails | Warn and proceed; skills work without graph data |
-| `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. |
+| `draft/graph/schema.yaml` exists | Engine is wired — use live query tools as needed during the run |
+| Engine index out of date | The engine indexes incrementally (content-based, git-aware) on each query, so it self-freshens. Re-run `graph-snapshot.sh` (or init) to force a reindex and refresh the marker. |

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

@@ -12,7 +12,7 @@ See [graph-query.md](graph-query.md) §Graph Usage Report (Mandatory Footer) for
 ```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>
+- Graph files queried: <comma-separated list, e.g. `get_architecture, hotspot-rank.sh` 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`>

package/core/shared/pattern-learning.md

@@ -109,11 +109,11 @@ Append under `## Learned Anti-Patterns`:
 - **Suggested fix:** [Brief description of the correct approach]
 ```
 
-`graph_severity` derivation rules (from `draft/graph/hotspots.jsonl` fanIn values):
+`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`
-- fanIn 0 or file not in hotspots.jsonl → `low`
+- fanIn 0 or file not returned by hotspot query → `low`
 - Graph data absent → `unresolved`
 
 When `graph_severity` differs from `severity`, use `graph_severity` as the enforcement priority — it is objective and graph-derived.

package/core/shared/red-flags.md

@@ -12,7 +12,7 @@ Referenced by: `/draft:decompose`, `/draft:implement`, `/draft:review`, `/draft:
 ## Universal Red Flags (STOP if any apply)
 
 - **Ran `grep`/`find`/`rg` for symbol or file discovery before consulting the graph** (when `draft/graph/schema.yaml` exists).
-- **Read more than 50 lines of source before consulting `draft/graph/hotspots.jsonl`** to know whether the file is a hotspot.
+- **Read more than 50 lines of source before querying hotspot rank** (`scripts/tools/hotspot-rank.sh --repo .`) to know whether the file is a hotspot.
 - **Omitted the Graph Usage Report footer** from the final output (see [graph-query.md](graph-query.md) §Mandatory Lookup Contract).
 - **Used a `grep` fallback without an explicit graph-miss statement** in the form: `Graph returned no match for <X>; falling back to grep.`
 - **Loaded full Layer 0.5 guardrails when the command type does not require them** (see selective-loading matrix in [draft-context-loading.md](draft-context-loading.md) §Layer 0.5).
@@ -24,7 +24,7 @@ Referenced by: `/draft:decompose`, `/draft:implement`, `/draft:review`, `/draft:
 These enforce [graph-query.md](graph-query.md) §Ground-Truth Discipline. Graph identifies candidates; Read confirms them. Shipping unread claims is the dominant correctness failure mode observed in Draft output.
 
 - **Wrote a `path:line` / `func()` / `symbol` reference into a deliverable without opening the file in this run.** Graph hit ≠ Read. (G1)
-- **Declared something in-scope or out-of-scope without Reading at least one file in that path.** Module names from `architecture.json` are a candidate set, not proof that the candidate contains the named cost. (G2)
+- **Declared something in-scope or out-of-scope without Reading at least one file in that path.** Module names from the live engine (`get_architecture`) are a candidate set, not proof that the candidate contains the named cost. (G2)
 - **Shipped `Citation: TBD` / `Path: TBD` / `Symbol: TBD` on a row whose Status is `Modified` or `Existing`.** TBD is reserved for `Status: New` rows with a planned path filled in. (G3)
 - **Claimed code behavior (writes / blocks / loops / fails / is the only path) from graph metadata alone.** Fan-in / fan-out / complexity scores are necessary signal, not sufficient evidence. (G4)
 - **Promoted a spec / generated an HLD or LLD / closed a review without checking that the in-scope file set covers every cost term in the problem statement.** Silent scope narrowing that excludes the named cost is the highest-impact failure class. (G5)
@@ -34,7 +34,7 @@ When in doubt, prefer "not yet validated against source" over an unbacked assert
 
 ## Graph-First Lookup Order (non-negotiable)
 
-1. **Graph first** — the committed snapshot (`draft/graph/architecture.json`, `draft/graph/hotspots.jsonl`) and the live query tools (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, `cycle-detect.sh`, `hotspot-rank.sh`).
+1. **Graph first** — wrapper scripts (`scripts/tools/graph-arch.sh`, `graph-callers.sh`, `graph-impact.sh`, `cycle-detect.sh`, `hotspot-rank.sh`) and direct engine queries (`search_graph`, `search_code`). The gate marker `draft/graph/schema.yaml` (present = engine available) is the only committed graph file.
 2. **Generated context second** — `draft/.ai-context.md`, relevant `draft/architecture.md` slices, track-level `hld.md`/`lld.md`.
 3. **Source file reads third** — only narrowed targets identified via graph or generated context.
 4. **Filesystem `grep`/`find` last** — only after a graph miss, with the explicit fallback sentence above.

package/core/templates/ai-context.md

@@ -49,7 +49,7 @@ generated_at: "{ISO_TIMESTAMP}"
 ```
 
 > Include immediate sub-directories for all major modules (not just top-level).
-> Use graph data (`draft/graph/modules/*.jsonl`) for exhaustive sub-module enumeration.
+> Use live engine queries (`get_architecture .packages[]` or `graph-callers.sh`) for exhaustive sub-module enumeration.
 > Show file counts per sub-module to indicate relative size/importance.
 
 ## GRAPH:MODULES

package/core/templates/architecture.md

@@ -30,9 +30,9 @@ graph:
     go: "{approximate | high}"
   stats:
     modules: "{N from schema.yaml}"
-    edges: "{total_edges from architecture.json}"
+    edges: "{total_edges from engine: get_architecture .edges}"
     hotspots: "{N}"
-  notes: "{explicit fidelity summary from architecture.json languages/packages}"
+  notes: "{explicit fidelity summary from engine: get_architecture .languages/.packages}"
 generation_notes: "{High existing context detected via audit — see §10 Relationship for deference | Standard graph-primary generation}"
 ---
 
@@ -114,7 +114,7 @@ Each backed by:
 
 ## 4. Module & Dependency Map (Primarily Graph-Derived)
 
-- Module dependency graph rendered from `draft/graph/architecture.json` (`.packages`) + `module-deps.mermaid`
+- Module dependency graph rendered from live engine query `scripts/tools/graph-arch.sh --repo . | jq '.packages'` + `scripts/tools/mermaid-from-graph.sh --repo . --diagram module-deps` (generated live, never committed)
 - High fan-in / fan-out modules highlighted
 - Cyclic dependencies called out
 - Cross-language boundaries (FFI, RPC, shared memory) explicitly surfaced with coverage notes