@drafthq/draft 3.0.0 → 3.1.5

package/skills/init/SKILL.md

@@ -52,7 +52,7 @@ Initialize a Draft project for Context-Driven Development.
 
 ## Graph Fidelity & Diagram-First Priority (MANDATORY)
 
-The knowledge graph in `draft/graph/` (architecture.json with packages, languages, routes, and fan-in/out; hotspots.jsonl) is the **deterministic structural ground truth** for the system's actual architecture.
+The knowledge graph — served live by the local `codebase-memory-mcp` engine (packages, languages, routes, fan-in/out, hotspots) and queried via the `graph-*.sh` wrappers — is the **deterministic structural ground truth** for the system's actual architecture. Draft is engine-only: `draft/graph/` holds only the `schema.yaml` gate marker; all graph data comes from live queries.
 
 **You are running inside a powerful agentic coding environment** (Cursor, Claude Code, Copilot, Windsurf, etc.) that maintains its own rich, continuously updated index of the entire codebase. **Use that indexed knowledge aggressively** in addition to the explicit graph data and direct source reads. Your environment's index often captures higher-level intent, naming patterns, cross-file workflows, and architectural signals that the static graph may not fully express yet. Combine both sources:
 - Graph = authoritative modules, edges, public surfaces, hotspots, call relationships.
@@ -499,9 +499,9 @@ else
 fi
 ```
 
-- **Root init** writes `<root>/draft/graph/` — the committed, git-tracked whole-repo memory.
+- **Root init** writes `<root>/draft/graph/schema.yaml` — the committed gate marker. Draft is engine-only: graph data is served live by the engine, never committed.
 - **Module init** also writes `draft/graph/root-link.json` (module→root); follow `root_graph` for cross-module understanding. The root spine is rebuilt first so the link is live.
-- Only `draft/graph/` is committed. The engine's `~/.cache` index is a disposable accelerator — never commit it; it rebuilds deterministically from source.
+- Only `schema.yaml` (and `root-link.json` in a module) is committed. The engine's `~/.cache` index is the live structural store — never commit it; it rebuilds deterministically from source.
 
 Optionally record which engine was selected (usage-report contract):
 
@@ -511,15 +511,20 @@ scripts/tools/verify-graph-binary.sh --repo . --json 2>/dev/null || true
 
 See `core/shared/graph-query.md` and `bin/README.md` for the query contract and engine resolution.
 
-If the build succeeds, `draft/graph/` is populated and later steps consume the always-load artifacts + injection slots.
+If indexing succeeds, `draft/graph/schema.yaml` is written and later steps query the engine live for structure + populate the injection slots.
 
-### 2. If graph build succeeds, load the always-load artifacts
+### 2. If indexing succeeds, query the engine for structural context
 
-Read these files to get structural context for all subsequent phases:
-- `draft/graph/schema.yaml` — module count, file count, edge count, language stats per module
-- `draft/graph/architecture.json` — module list (`.packages`) with fan-in/out
-- `draft/graph/architecture.json` `.routes` — detected service endpoints
-- `draft/graph/hotspots.jsonl` — all complexity hotspots (files ranked by lines + fanIn * 50)
+Pull the architecture view once and reuse it across phases:
+
+```bash
+ARCH=$(scripts/tools/graph-arch.sh --repo .)
+```
+
+- `$ARCH | jq '.packages'` — module list with fan-in/out
+- `$ARCH | jq '.routes'` — detected service endpoints
+- `$ARCH | jq '.languages, .node_labels, .layers, .boundaries'` — language mix, node shape, layering
+- `scripts/tools/hotspot-rank.sh --repo . --top 20` — complexity/fan-in hotspots (live)
 
 ### 3. Use graph data to accelerate Step 1.5
 
@@ -533,10 +538,10 @@ Read these files to get structural context for all subsequent phases:
 ### 4. Compute codebase tier and module priority
 
 **Step 1.4.5 — Compute Codebase Tier:**
-Read `draft/graph/schema.yaml`. Extract:
-- `M = stats.modules`
-- `F = stats.go_functions + stats.py_functions`
-- `P = stats.proto_rpcs`
+From the live `$ARCH` (above), extract:
+- `M = $ARCH | jq '.packages | length'` (modules)
+- `F = $ARCH | jq '[.node_labels[] | select(.label=="Function" or .label=="Method") | .count] | add // 0'` (functions+methods)
+- `P = $ARCH | jq '.routes | length'` (routes / RPCs)
 
 Apply tier table:
 
@@ -551,8 +556,8 @@ Apply tier table:
 Hold tier in memory. This governs: architecture.md length minimum, .ai-context.md budget, and module deep-dive depth.
 
 **Step 1.4.6 — Build Module Priority List:**
-From `draft/graph/hotspots.jsonl`: count hotspot files per module (group by `module` field).
-From `draft/graph/architecture.json` `.packages[]`: read `fan_in` per module.
+From `scripts/tools/hotspot-rank.sh --repo .`: count hotspot symbols per module.
+From `$ARCH | jq '.packages[]'`: read `fan_in` per module.
 Rank modules by: `(hotspot_count × 2) + fan_in_count`.
 Top-ranked modules drive Section 6 deep-dive ordering and depth. Modules ranked zero on both: summary treatment only.
 Hold ranked list in memory — it replaces directory scanning for module discovery.
@@ -572,7 +577,7 @@ The tool emits a ready-to-inject ` ```mermaid ``` ` block (or an empty stub on e
 ```
 
 For Section 20 (hotspots slot):
-Read `draft/graph/hotspots.jsonl` (or run `scripts/tools/hotspot-rank.sh --repo . --top 10`), take the top 10 by fanIn, build a markdown table:
+Run `scripts/tools/hotspot-rank.sh --repo . --top 10`, take the top 10 by fanIn, build a markdown table:
 ```
 <!-- GRAPH:hotspots:START -->
 | Symbol | fanIn |
@@ -631,7 +636,7 @@ Perform a **one-time, exhaustive analysis** of the existing codebase. This is NO
 
 If the codebase is large (200+ files), focus on the module boundaries but still enumerate exhaustively within each module.
 
-> **Large codebase guardrail:** If the codebase exceeds 500 source files, limit Section 7 deep dives to the top 20 most-imported modules and summarize others in a table. Rank modules by the number of unique files that import/reference them (descending) — use `draft/graph/architecture.json` `.packages[].fan_in` if graph data is available. For dynamic languages where static import counting is impractical, rank by file count within each module directory (larger modules first). **Even for summarized modules, enumerate immediate sub-directories with file counts** (one-line per sub-dir) — this is cheap with graph data and provides essential navigation context.
+> **Large codebase guardrail:** If the codebase exceeds 500 source files, limit Section 7 deep dives to the top 20 most-imported modules and summarize others in a table. Rank modules by the number of unique files that import/reference them (descending) — use the engine's `.packages[].fan_in` (`get_architecture`, captured as `$ARCH` in Step 1.4.2) if the engine is available. For dynamic languages where static import counting is impractical, rank by file count within each module directory (larger modules first). **Even for summarized modules, enumerate immediate sub-directories with file counts** (one-line per sub-dir) — this is cheap with graph data and provides essential navigation context.
 
 ### Parallel Analysis Protocol (Tiers 3–5)
 
@@ -658,16 +663,16 @@ For tier 3+, readers run simultaneously; wall clock = slowest reader, not the su
 
 #### Phase 0: Graph Data (already done in Step 1.4)
 
-The graph binary has already run. Use its output throughout this protocol:
-- `draft.tmp/graph/schema.yaml` — module list, file counts, tier metrics
-- `draft.tmp/graph/architecture.json` — `.packages[].fan_in` per module (for grouping)
-- `draft.tmp/graph/hotspots.jsonl` — top hotspot files per module (feed to readers)
+The engine is already indexed. Query it live throughout this protocol (reuse `$ARCH` from Step 1.4.2):
+- `$ARCH | jq '.packages'` — module list with `.fan_in`/`.fan_out` (for grouping)
+- `$ARCH | jq '.languages, .node_labels'` — file/symbol counts, tier metrics
+- `scripts/tools/hotspot-rank.sh --repo .` — top hotspot symbols per module (feed to readers)
 
 #### Phase 1: Spawn Parallel Module Readers
 
 **Step 1: Group modules.**
 
-From `draft.tmp/graph/architecture.json` `.packages[]`, extract all module names and their `fan_in` counts.
+From `$ARCH | jq '.packages[]'`, extract all module names and their `fan_in` counts.
 Apply dependency-aware grouping (see `core/shared/parallel-analysis.md`).
 Use the modules-per-agent count from the tier table above (4 for tier 4/5; all modules in one agent for tier 1):
 - Assign highest fan-in modules to separate readers (tier 3+)
@@ -683,7 +688,7 @@ Hotspot files:
   execution/engine.go (847 lines, fanIn=12)
   execution/router.go (412 lines, fanIn=8)
   fill_processor/handler.go (623 lines, fanIn=5)
-Module edges (from architecture.json .packages fan-in/out):
+Module edges (from $ARCH .packages fan-in/out):
   execution → [risk, data, services]
   fill_processor → [execution, persistence]
 ```
@@ -788,7 +793,7 @@ If any reader agent fails to produce valid JSON after one retry:
 When the Agent tool is unavailable or reader agents fail after retry, write `draft/architecture.md` using the **10-section graph-primary structure** (checklist above + `core/templates/architecture.md`). Do not use legacy 28-section or Pass 1/2/3 volume protocols.
 
 1. Use the ranked module list from Step 1.4.6 (graph-first — do not re-scan by directory if Phase 0 succeeded).
-2. For each top module (up to 20 by fan-in), read `draft/graph/modules/{name}.jsonl`, hotspot files, and 3–5 key sources; embed graph blocks and at least one workflow/state diagram per significant module inside §4–§8 as appropriate.
+2. For each top module (up to 20 by fan-in), query the engine for its symbols/callers (`scripts/tools/graph-callers.sh`, `graph-impact.sh`, or `$ARCH | jq '.packages[] | select(.name=="<m>")'`), read the hotspot files and 3–5 key sources; embed graph blocks and at least one workflow/state diagram per significant module inside §4–§8 as appropriate.
 3. Always include §9 Graph Coverage Gaps and §10 Relationship when the Context Audit requires them.
 4. Run Completion Verification (defined later in this skill) before condensation. Fidelity, provenance, and gap honesty block completion — not line counts.
 
@@ -911,11 +916,11 @@ Follow these steps in order. The specific files to look for depend on the langua
 
 #### Phase 1: Discovery (Broad Scan)
 
-1. **Map the directory tree**: Recursively list the project to understand the file layout. Note subdirectory groupings. (If Step 1.4 graph analysis succeeded, use `draft.tmp/graph/schema.yaml` module list instead — it is exhaustive and includes file counts.)
+1. **Map the directory tree**: Recursively list the project to understand the file layout. Note subdirectory groupings. (If Step 1.4 graph analysis succeeded, use the engine's `$ARCH | jq '.packages, .file_tree'` instead — it is exhaustive and includes file counts.)
 
 2. **Read build / dependency files**: These reveal the module structure, dependencies, and targets. (See language guide above for which files.)
 
-3. **Read API definition files**: These define the module's data model and service interfaces. (See language guide above for which files. If Step 1.4 succeeded, `draft.tmp/graph/architecture.json` `.routes` already has all detected service endpoints.)
+3. **Read API definition files**: These define the module's data model and service interfaces. (See language guide above for which files. If Step 1.4 succeeded, the engine's `$ARCH | jq '.routes'` already has all detected service endpoints.)
 
 4. **Read interface / type definition files**: Class declarations, interface definitions, and type annotations reveal the public API and design intent.
 
@@ -1653,22 +1658,37 @@ For **brownfield** projects, run `/draft:learn` (no arguments — full codebase
 
 ## Completion
 
-**Finalize OKF bundle:** After all `draft/` files are written, run the bundle tool
-to (re)generate the Open Knowledge Format root index so the whole `draft/` tree is
-a portable, vendor-neutral OKF bundle. This is the default — no flag required.
+**Finalize the context index:** After all `draft/` files are written, author (or refresh)
+`draft/index.md` — a plain, navigable index over the context bundle. No OKF framing, no
+special frontmatter; it is a human- and agent-readable table of contents.
 
-```bash
-scripts/tools/okf-bundle.sh --dir draft   # writes the bundle-root draft/index.md
-scripts/tools/okf-check.sh  --dir draft   # OKF v0.1 conformance (advisory, non-fatal)
+Write `draft/index.md` with this structure (omit rows whose files were not generated):
+
+```md
+# <project> — Draft Context
+
+Start here. This indexes the Draft context for this repo.
+
+## Context
+- [Architecture](architecture.md) — module map, dependencies, hotspots (graph-grounded)
+- [Product](product.md) — what this system does and for whom
+- [Tech Stack](tech-stack.md) — languages, frameworks, infra
+- [Workflow](workflow.md) — how work flows through the repo
+- [Guardrails](guardrails.md) — learned conventions and anti-patterns
+- [AI Context Map](.ai-context.md) — condensed orientation for agents
+- [AI Profile](.ai-profile.md) — repo profile + tiering
+
+## Tracks
+- [Track Index](tracks.md) — active, completed, and archived tracks
+
+## Knowledge graph
+- Engine-only (`codebase-memory-mcp`). Structural data is queried live via the
+  `graph-*.sh` wrappers; `draft/graph/schema.yaml` is the gate marker. There is no
+  committed graph mirror to browse.
 ```
 
-`okf-bundle.sh` links every concept file present (`.ai-profile.md`, `.ai-context.md`,
-`architecture.md`, `product.md`, `tech-stack.md`, `workflow.md`, `guardrails.md`), the
-tracks, and the graph sub-bundle (`graph/okf/`). Concept `type:` frontmatter comes from
-the templates; `okf-check.sh` validates §9 conformance (frontmatter + `type` on every
-concept; reserved `index.md`/`log.md` structure). It is advisory — report the result,
-do not fail init. Note: operational reports later written into `draft/` (e.g.
-`deep-review-report.md`) are not OKF concepts and will be flagged.
+Keep one-line descriptions accurate to what each file actually contains. This index is
+the single committed entry point to the `draft/` bundle.
 
 **Finalize run memory:** Update `draft/.state/run-memory.json`:
 - `status`: `"completed"`
@@ -1679,7 +1699,7 @@ For **Brownfield** projects, announce:
 "Draft initialized successfully with comprehensive analysis!
 
 Created:
-- draft/index.md (Open Knowledge Format bundle root — cross-links every concept)
+- draft/index.md (plain docs index — navigable table of contents for the draft/ bundle)
 - draft/.ai-profile.md (20-50 lines — ultra-compact always-injected profile, Tier 0)
 - draft/.ai-context.md (200-400 lines — token-optimized AI context, self-contained, Tier 1)
 - draft/architecture.md (comprehensive human-readable engineering reference, Tier 2)
@@ -1714,7 +1734,7 @@ For **Greenfield** projects, announce:
 "Draft initialized successfully!
 
 Created:
-- draft/index.md (Open Knowledge Format bundle root — cross-links every concept)
+- draft/index.md (plain docs index — navigable table of contents for the draft/ bundle)
 - draft/product.md
 - draft/tech-stack.md
 - draft/workflow.md

package/skills/init/references/architecture-spec.md

@@ -275,13 +275,13 @@ Only when material: authentication/authorization checkpoints, distributed transa
 
 **Core rule:** The graph is the source of truth for structure. LLM synthesis exists only to interpret the graph into actionable design understanding — primarily via one accurate workflow or state diagram per module — plus tiny supporting notes. The previous volume-oriented deep-dive expectations are superseded.
 
-For each module in `draft/graph/architecture.json` (`.packages[]`), produce a subsection whose **primary content** is the deterministic graph block followed by one synthesized behavioral diagram. Every module gets a slot; do not sample. The block's fan-in/out and node counts come from `.packages[]`; public API and key call edges come from live per-package queries (`scripts/tools/graph-callers.sh`, `graph-impact.sh`) and `hotspots.jsonl`.
+For each module returned by `scripts/tools/graph-arch.sh --repo . | jq '.packages[]'`, produce a subsection whose **primary content** is the deterministic graph block followed by one synthesized behavioral diagram. Every module gets a slot; do not sample. The block's fan-in/out and node counts come from `.packages[]`; public API and key call edges come from live per-package queries (`scripts/tools/graph-callers.sh`, `graph-impact.sh`) and `scripts/tools/hotspot-rank.sh --repo .`.
 
 #### 7.{N} {module-name}
 
 <!-- GRAPH:module-deep/{module-name}:START -->
 <!-- Rendered deterministic block: package name, node count, public API list, fan-in/fan-out (from
-     architecture.json .packages), hotspot fan-in (from hotspots.jsonl), key call edges (from
+     get_architecture .packages), hotspot fan-in (from hotspot-rank.sh), key call edges (from
      graph-callers.sh/graph-impact.sh), entry points if known. No LLM prose inside fence. -->
 <!-- GRAPH:module-deep/{module-name}:END -->
 
@@ -300,7 +300,7 @@ Synthesize a single, accurate Mermaid diagram (`stateDiagram-v2`, `sequenceDiagr
 
 #### Sub-Module Guidance (when graph justifies recursion)
 
-When a module has clear internal structure visible in `draft/graph/architecture.json` (`.packages` fan-in/out) or live per-package queries:
+When a module has clear internal structure visible in live engine query `get_architecture .packages` (fan-in/out) or live per-package queries:
 - Create `##### 7.X.Y {Parent}/{Child}` subsections only for children that have their own meaningful public surface or high internal fan-in.
 - Each sub-module subsection follows the same compact pattern: graph facts + **one mandatory workflow/state diagram** + ≤60 words Design Notes.
 - Do not descend further unless the child itself shows additional clear boundaries in the graph data.
@@ -362,7 +362,7 @@ Regardless of tier, any directory whose name contains `ops`, `handlers`, `execut
 | ... | (enumerate ALL — no sampling, no "and others") | | | |
 ```
 
-Use `draft/graph/modules/{module}.jsonl` to get the complete file list with line counts. Use `draft/graph/hotspots.jsonl` to flag high-complexity operations.
+Use `scripts/tools/graph-callers.sh --symbol <module>` or `scripts/tools/graph-arch.sh --repo .` to get the complete file list. Use `scripts/tools/hotspot-rank.sh --repo .` to flag high-complexity operations.
 
 #### Example: Full Sub-Module Treatment for `icebox/` (917 files)
 
@@ -409,7 +409,7 @@ stateDiagram-v2
 After writing Section 7, run these checks before proceeding. **If any check fails, STOP and fix.**
 
 **Check 1 — Graph block present and faithful for every module:**
-Every top-level module from `draft/graph/architecture.json` (`.packages`) has its `<!-- GRAPH:module-deep/...:START --> ... <!-- GRAPH:module-deep/...:END -->` fence rendered verbatim. No LLM prose inside the fence. No modules missing.
+Every top-level module from the live engine (`get_architecture .packages`) has its `<!-- GRAPH:module-deep/...:START --> ... <!-- GRAPH:module-deep/...:END -->` fence rendered verbatim. No LLM prose inside the fence. No modules missing.
 
 **Check 2 — One mandatory workflow/state diagram per module:**
 Every `#### 7.X` (and every `##### 7.X.Y` that the graph justified) contains exactly one high-signal `Primary Workflow / State` Mermaid diagram (`stateDiagram-v2`, `sequenceDiagram`, or clear `flowchart`). The diagram must reflect facts from the module's graph record (entry points, public symbols, call targets). Generic placeholder diagrams fail this check.
@@ -513,12 +513,13 @@ Include architecturally significant implementations (high fan-in, core extension
 |---|-----------|-------------|-------|-------------|
 | 1 | ArchiveFilesOp | `icebox/master/ops/archive_files_op.cc` | 2100 | Archives files to cloud vault |
 | 2 | CancelJobOp | `icebox/master/ops/cancel_job_op.cc` | 450 | Cancels running archive job |
-| (enumerate ALL — use graph hotspots.jsonl and per-module JSONL for file list and line counts) |
+| (enumerate ALL — use hotspot-rank.sh and graph-callers.sh / get_architecture for file list and line counts) |
 ```
 
-> **MANDATORY (graph data)**: Read `draft/graph/modules/{module}.jsonl` to get the complete file
-> list with line counts. Filter for files in operation sub-directories (paths containing `/ops/`,
-> `/handlers/`, `/executors/`, `/workers/`). Use `draft/graph/hotspots.jsonl` to flag
+> **MANDATORY (graph data)**: Query `scripts/tools/graph-arch.sh --repo .` or
+> `scripts/tools/graph-callers.sh --symbol <module>` to get the complete file list with line counts.
+> Filter for files in operation sub-directories (paths containing `/ops/`,
+> `/handlers/`, `/executors/`, `/workers/`). Use `scripts/tools/hotspot-rank.sh --repo .` to flag
 > high-complexity operations (high line count or fanIn). Do NOT skip this step — incomplete
 > catalogs cause AI agents to reinvent existing functionality.
 
@@ -1209,11 +1210,11 @@ Fix: Add actual payload descriptions on arrows, `alt`/`opt` blocks for condition
 
 **FAILURE 3 — Empty Appendices:**
 Detection: Appendix B, C, or D tables have fewer than 10 data rows.
-Fix: Cross-reference ALL data sources (Appendix B), ALL implementation outputs (Appendix C), and add 2-3 detailed sequence diagrams to Appendix D. Use graph data (`architecture.json` `.packages`/`.routes`) to enumerate exhaustively.
+Fix: Cross-reference ALL data sources (Appendix B), ALL implementation outputs (Appendix C), and add 2-3 detailed sequence diagrams to Appendix D. Use live engine queries (`get_architecture .packages`/`.routes`) to enumerate exhaustively.
 
 **FAILURE 4 — Missing Sub-Modules:**
 Detection: A module with 100+ source files (check graph data) has no Sub-Module Structure table.
-Fix: Read `draft/graph/modules/{name}.jsonl`, group files by immediate sub-directory, and generate the table with file counts and one-line role descriptions per sub-directory.
+Fix: Query `scripts/tools/graph-arch.sh --repo .` or `scripts/tools/graph-callers.sh --symbol <name>`, group results by immediate sub-directory, and generate the table with file counts and one-line role descriptions per sub-directory.
 
 **FAILURE 4b — Shallow Sub-Module Treatment:**
 Detection: Large sub-modules (50+ files) listed only as table rows with no dedicated deep-dive subsection. Or ops/handler directories have no operation catalog.

package/skills/learn/SKILL.md

@@ -11,8 +11,8 @@ Scan the codebase to discover recurring coding patterns and update `draft/guardr
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Use the graph to:
 
-1. Enumerate a module's symbols/files via `scripts/tools/graph-callers.sh`/`graph-impact.sh` and `architecture.json` (preferred over `find`).
-2. Prioritize hotspots from `draft/graph/hotspots.jsonl` — patterns in high-fanIn files are more impactful when learned.
+1. Enumerate a module's symbols/files via `scripts/tools/graph-callers.sh`/`graph-impact.sh` and `scripts/tools/graph-arch.sh --repo .` (preferred over `find`).
+2. Prioritize hotspots via `scripts/tools/hotspot-rank.sh --repo .` — patterns in high-fanIn files are more impactful when learned.
 3. For TS/Python/Go/C/C++, use `*-index.jsonl` to identify class/function definitions rather than re-discovering them via regex.
 
 Filesystem `find` for source discovery (Step 2.1) is permitted **as a complement** to the graph for languages not covered by indexes (e.g. Ruby, Java without ctags). Record the rationale in the Graph Usage Report.
@@ -246,15 +246,15 @@ git log --follow --oneline -1 -- {file_containing_pattern}
 
 ### 2.7: Graph-Aware Severity Enrichment
 
-If `draft/graph/hotspots.jsonl` exists, derive objective severity for all anti-pattern candidates based on the fanIn of files where the pattern was found.
+If `draft/graph/schema.yaml` exists (engine live), derive objective severity for all anti-pattern candidates based on the fanIn of files where the pattern was found via `scripts/tools/hotspot-rank.sh --repo .`.
 
 For each anti-pattern candidate from Step 2.2:
-1. Check if any evidence files appear in `draft/graph/hotspots.jsonl`
+1. Check if any evidence files appear in the hotspot output from `scripts/tools/hotspot-rank.sh --repo .`
 2. Take the highest fanIn value across all evidence files:
    - fanIn ≥ 10 → `graph_severity: critical` (breakage propagates to many callers)
    - fanIn 5–9 → `graph_severity: high`
    - fanIn 1–4 → `graph_severity: medium`
-   - fanIn 0 or file not in hotspots.jsonl → `graph_severity: low`
+   - fanIn 0 or file not in hotspot output → `graph_severity: low`
 3. If no graph data exists → `graph_severity: unresolved`
 
 Collect all evidence files with fanIn ≥ 5 for the `high_fanin_files` field.

package/skills/quick-review/SKILL.md

@@ -11,7 +11,7 @@ You are performing a lightweight, ad-hoc code review. This is the fast alternati
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Quick-review keeps the graph load light:
 
-1. Always check `draft/graph/hotspots.jsonl` for every changed file (Step 2 blast-radius pre-check below).
+1. Always run `scripts/tools/hotspot-rank.sh --repo .` for every changed file (Step 2 blast-radius pre-check below).
 2. If a finding spans more than one file, run `scripts/tools/graph-callers.sh --repo . --symbol <name>` to enumerate the call sites before claiming "no other usages".
 
 Filesystem `grep` is reserved for source-text scans (literal strings, regex patterns). Symbol and caller discovery go through the graph.
@@ -68,9 +68,9 @@ Determine the diff to review:
 3. If commit range: `git diff <range>`
 4. Default: `git diff HEAD~1..HEAD` (last commit)
 
-## Step 2: Blast Radius Pre-check (if `draft/graph/hotspots.jsonl` exists)
+## Step 2: Blast Radius Pre-check (if `draft/graph/schema.yaml` exists)
 
-Before the four-dimension review, check if any files in scope appear in `draft/graph/hotspots.jsonl`. If any file has a `fanIn` in the top 20% of the list, add this warning at the top of the review report:
+Before the four-dimension review, run `scripts/tools/hotspot-rank.sh --repo .` and check if any files in scope appear in the output. If any file has a `fanIn` in the top 20% of the list, add this warning at the top of the review report:
 
 ```
 ⚠ HIGH IMPACT: {file} is a high-fanIn hotspot (fanIn={N}). Changes here propagate to many callers — review with extra care.

package/skills/review/SKILL.md

@@ -11,7 +11,7 @@ You are conducting a code review using Draft's Context-Driven Development method
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Stage 1 (Automated Validation) **starts from the graph**:
 
-1. Run blast-radius assessment from `draft/graph/hotspots.jsonl` and `scripts/tools/graph-impact.sh` (see Stage 1).
+1. Run blast-radius assessment via `scripts/tools/hotspot-rank.sh --repo .` and `scripts/tools/graph-impact.sh` (see Stage 1).
 2. For each changed file with non-trivial diff size, run `scripts/tools/graph-impact.sh --repo . --file <path>` to obtain the affected module set deterministically.
 3. For each public symbol modified, run `scripts/tools/graph-callers.sh --repo . --symbol <name>` to enumerate downstream callers before judging breaking-change severity.
 
@@ -370,18 +370,18 @@ For the files changed in the diff, perform static checks using `grep` or similar
 
 - **Blast Radius Assessment** (if the `draft/graph/` snapshot exists):
    - List all changed files from the diff
-   - For each changed file, check if it appears in `hotspots.jsonl` — if yes, record its `fanIn` value
-   - Classify: files with fanIn in the top 20% of the hotspots list = **HIGH IMPACT**; top 21–50% = **MEDIUM**; below 50% or not in list = **STANDARD**
-   - For any file in a HIGH or MEDIUM module, check `architecture.json` `.packages[].fan_in` (how many modules depend on this module)
+   - For each changed file, check if it appears in `scripts/tools/hotspot-rank.sh --repo .` output — if yes, record its `fanIn` value
+   - Classify: files with fanIn in the top 20% of the hotspot output = **HIGH IMPACT**; top 21–50% = **MEDIUM**; below 50% or not in output = **STANDARD**
+   - For any file in a HIGH or MEDIUM module, query `scripts/tools/graph-arch.sh --repo . | jq '.packages[].fan_in'` (how many modules depend on this module)
    - Include a `Blast Radius` line in the Stage 1 report summary: `Blast Radius: HIGH | MEDIUM | STANDARD — <N> changed files affect high-fanIn modules: [file list]`
    - If any changed file is HIGH IMPACT: escalate Stage 3 thoroughness (check all callers of changed functions) and note this in the report header
 - **Architecture Conformance:** Search for pattern violations documented in `draft/.ai-context.md`. (e.g. `import * from 'database'` in a React component).
 - **Dead Code:** Check for newly exported functions/classes in the diff that have 0 references across the codebase.
 - **Dependency Cycles:** Trace the import chains for new imports to ensure no circular dependencies (e.g., A → B → C → A) are introduced.
-- **Graph Boundary Check** (if `draft/graph/architecture.json` exists) `[RC-013]`:
+- **Graph Boundary Check** (if `draft/graph/schema.yaml` exists) `[RC-013]`:
    - For each changed file, identify its module from the graph
    - Check if any new cross-module includes were added in the diff
-   - Verify they follow the established dependency direction from `architecture.json` package fan-in/out
+   - Verify they follow the established dependency direction from `scripts/tools/graph-arch.sh --repo .` package fan-in/out
    - Flag reverse-direction dependencies (module A now depends on module B, but only B→A existed before) as "Potential architecture violation — new dependency direction"
    - Check if changes introduce files in modules listed in graph cycles — flag as higher risk
 - **Security Scan** `[RC-001, RC-002, RC-003, RC-011]`:
@@ -1075,7 +1075,7 @@ If Jira ticket linked, sync via `core/shared/jira-sync.md`:
 
 Before printing the final verdict, internally verify and report:
 
-1. **Graph files queried** — which JSONL files were loaded (e.g. `architecture.json, hotspots.jsonl`) plus any live graph query-tool invocations (impact, callers, cycles).
+1. **Graph data queried** — which live-engine tools were invoked (e.g. `get_architecture`, `hotspot-rank.sh`, `graph-impact.sh`, `graph-callers.sh`, `cycle-detect.sh`).
 2. **Layer 1 files deliberately skipped** — list any context sections skipped as irrelevant to the diff under review.
 3. **Filesystem grep fallback justification** — for every `grep`/`find` run, state the concept it searched for. Source-text scans (string literals, regex matches in code) are exempt — they are not symbol/file discovery.
 

package/skills/tech-debt/SKILL.md

@@ -11,8 +11,8 @@ You are conducting a technical debt analysis to catalog, prioritize, and plan re
 
 When `draft/graph/schema.yaml` exists, this skill **must** follow the graph-first lookup contract in [core/shared/graph-query.md](../../core/shared/graph-query.md) §Mandatory Lookup Contract. Tech-debt prioritization is fundamentally driven by graph data:
 
-1. Load `draft/graph/hotspots.jsonl` — **rank candidates by `fanIn × complexity`** to surface high-leverage debt first.
-2. Read `draft/graph/architecture.json` (`.packages`) and run `scripts/tools/cycle-detect.sh --repo .` — flag debt in modules involved in cycles as higher priority.
+1. Run `scripts/tools/hotspot-rank.sh --repo .` — **rank candidates by `fanIn × complexity`** to surface high-leverage debt first.
+2. Query `scripts/tools/graph-arch.sh --repo .` and run `scripts/tools/cycle-detect.sh --repo .` — flag debt in modules involved in cycles as higher priority.
 3. Run `scripts/tools/cycle-detect.sh --repo .` to enumerate dependency cycles — every cycle is a candidate architecture-debt entry.
 4. For each catalogued finding, run `scripts/tools/graph-impact.sh --repo . --file <path>` so the remediation plan includes blast-radius.
 

package/scripts/tools/okf-bundle.sh

@@ -1,141 +0,0 @@
-#!/usr/bin/env bash
-# okf-bundle.sh — make a draft/ context directory an Open Knowledge Format bundle.
-#
-# OKF (Google Cloud, open spec) treats a directory of markdown files with YAML
-# frontmatter as a knowledge bundle: one file per concept, the file path is the
-# concept's identity, concepts cross-link with markdown links, and index.md is
-# the navigable root. Draft's project-doc files already carry the required
-# `type` frontmatter (architecture.md, .ai-context.md, product.md, ...); this
-# tool writes the bundle's root index.md so the whole draft/ tree is a portable,
-# vendor-neutral OKF bundle.
-# https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing
-#
-# Writes <dir>/index.md (the OKF bundle-root index, §6/§11) linking every concept
-# file present, the tracks, and the graph sub-bundle (graph/okf/). Validate the
-# result with okf-check.sh (the OKF v0.1 conformance checker).
-#
-# Usage: scripts/tools/okf-bundle.sh [--dir DIR]
-# Exit codes: 0 OK, 1 invocation error, 2 dir missing.
-set -euo pipefail
-
-DIR="draft"
-
-usage() {
-    cat <<'EOF'
-okf-bundle.sh — write the OKF bundle-root index.md for a draft/ context bundle.
-
-Usage:
-  scripts/tools/okf-bundle.sh [--dir DIR]
-
-Flags:
-  --dir DIR  Bundle root (default: draft).
-  --help     Show this help.
-
-Writes <dir>/index.md cross-linking every concept present, the tracks, and the
-graph sub-bundle. Validate conformance with `okf-check.sh --dir <dir>`.
-Exit 0 OK, 1 invocation error, 2 when <dir> is absent.
-EOF
-}
-
-while [[ $# -gt 0 ]]; do
-    case "$1" in
-        --dir) DIR="$2"; shift 2;;
-        --help|-h) usage; exit 0;;
-        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
-        *) echo "Unexpected arg: $1" >&2; usage >&2; exit 1;;
-    esac
-done
-
-[[ -d "$DIR" ]] || { echo "ERROR: --dir '$DIR' is not a directory" >&2; exit 2; }
-
-# Canonical Draft concepts, ordered: "filename|label|expected-type".
-# Each present file is linked from index.md and checked for `type:` under --check.
-CONCEPTS=(
-    ".ai-profile.md|AI Profile|Profile"
-    ".ai-context.md|AI Context Map|ContextMap"
-    "architecture.md|Architecture|Architecture"
-    "product.md|Product|Product"
-    "tech-stack.md|Tech Stack|TechStack"
-    "workflow.md|Workflow|Workflow"
-    "guardrails.md|Guardrails|Guardrails"
-    "service-index.md|Service Index|ServiceIndex"
-)
-
-# read_fm_field FILE FIELD — print a top-level frontmatter scalar (quotes stripped).
-read_fm_field() {
-    awk -v field="$2" '
-        NR==1 { if ($0 != "---") exit; next }
-        /^---[[:space:]]*$/ { exit }
-        {
-            if (index($0, field ":") == 1) {
-                sub("^" field ":[[:space:]]*", "")
-                gsub(/^"|"$/, "")
-                print
-                exit
-            }
-        }
-    ' "$1"
-}
-
-# --- write the bundle root index.md ---
-PROJECT=""
-for probe in architecture.md .ai-context.md product.md .ai-profile.md; do
-    if [[ -f "$DIR/$probe" ]]; then
-        PROJECT="$(read_fm_field "$DIR/$probe" project)"
-        [[ -n "$PROJECT" ]] && break
-    fi
-done
-[[ -n "$PROJECT" && "$PROJECT" != "{PROJECT_NAME}" ]] || PROJECT="$(basename "$(cd "$DIR/.." && pwd)")"
-
-INDEX="$DIR/index.md"
-{
-    # Bundle-root index.md: frontmatter is permitted only to declare okf_version (§11).
-    printf -- '---\n'
-    printf 'okf_version: "0.1"\n'
-    printf -- '---\n\n'
-    printf '# %s — Draft Context Bundle\n\n' "$PROJECT"
-    printf 'Open Knowledge Format (OKF) bundle root. Each concept below is a markdown file with a `type` frontmatter field; the links form the navigable knowledge graph.\n'
-
-    # Context concepts (only if at least one is present)
-    context=""
-    for entry in "${CONCEPTS[@]}"; do
-        IFS='|' read -r fname label expected <<< "$entry"
-        [[ -f "$DIR/$fname" ]] || continue
-        t="$(read_fm_field "$DIR/$fname" type)"
-        [[ -n "$t" ]] || t="$expected"
-        d="$(read_fm_field "$DIR/$fname" description)"
-        desc="${d:-$t concept}"
-        context+="$(printf -- '* [%s](%s) - %s' "$label" "$fname" "$desc")"$'\n'
-    done
-    if [[ -n "$context" ]]; then
-        printf '\n# Context\n\n%s' "$context"
-    fi
-
-    # Tracks
-    if [[ -f "$DIR/tracks.md" || -d "$DIR/tracks" ]]; then
-        printf '\n# Tracks\n\n'
-        [[ -f "$DIR/tracks.md" ]] && printf -- '* [Track Index](tracks.md) - active, completed, and archived tracks\n'
-        if [[ -d "$DIR/tracks" ]]; then
-            for td in "$DIR"/tracks/*/; do
-                [[ -d "$td" ]] || continue
-                id="$(basename "$td")"
-                [[ -f "$td/spec.md" ]] || continue
-                title="$id"
-                if command -v jq >/dev/null 2>&1 && [[ -f "$td/metadata.json" ]]; then
-                    mt="$(jq -r '.title // empty' "$td/metadata.json" 2>/dev/null || true)"
-                    [[ -n "$mt" ]] && title="$mt"
-                fi
-                printf -- '* [%s](tracks/%s/spec.md) - track %s\n' "$title" "$id" "$id"
-            done
-        fi
-    fi
-
-    # Knowledge graph sub-bundle
-    if [[ -f "$DIR/graph/okf/index.md" ]]; then
-        printf '\n# Knowledge graph\n\n'
-        printf -- '* [Graph bundle](graph/okf/index.md) - structural knowledge graph (modules, dependencies, hotspots)\n'
-    fi
-} > "$INDEX"
-
-echo "OKF bundle root written to $INDEX"
-exit 0