@drafthq/draft 2.8.3 → 3.1.5

package/skills/GRAPH.md

@@ -55,7 +55,6 @@ graph TD
     subgraph "Architecture"
         decompose["/draft:decompose"]
         adr["/draft:adr"]
-        index["/draft:index"]
         tech-debt["/draft:tech-debt"]
         impact["/draft:impact"]
     end
@@ -96,7 +95,6 @@ graph TD
     init --> learn
     init --> adr
     init --> bughunt
-    init --> index
     init --> status
     init --> deep-review
     init --> debug
@@ -124,7 +122,6 @@ graph TD
     discover --> coverage
     discover --> testing-strategy
     discover --> learn
-    discover --> index
     discover --> tour
     discover --> impact
     discover --> assist-review
@@ -178,8 +175,7 @@ graph TD
     impact -.->|reads graph| new-track
     impact -.->|reads graph| implement
 
-    %% Monorepo chain
-    init -.->|per-service| index
+    %% Monorepo: init is scope-aware — root build + module→root graph link (no separate index command)
 ```
 
 ## Dependency Matrix
@@ -193,7 +189,7 @@ graph TD
 | `implement` | init, new-track | review (triggers at phase boundaries) | Modifies source code; regenerates .ai-context.md |
 | `review` | init, new-track | implement (called at phase boundaries) | review-report-latest.md |
 | `quick-review` | init | review (fast alternative) | quick-review-report.md |
-| `bughunt` | init | review (optional), index (optional), jira (optional) | bughunt-report-latest.md |
+| `bughunt` | init | review (optional), jira (optional) | bughunt-report-latest.md |
 | `deep-review` | init | -- | deep-review audit report |
 | `coverage` | init, new-track | -- | Regenerates .ai-context.md |
 | `testing-strategy` | init | coverage (informs), bughunt (informs) | testing-strategy.md |
@@ -248,7 +244,8 @@ deep-review ──→ tech-debt ──→ new-track (prioritized items)
 
 ### Monorepo Flow
 ```
-init (per-service) → index (at root) → aggregated context
+init (root)       → whole-repo code-graph spine + sparse root map
+init (sub-module) → module snapshot + root-link.json → cross-module context via the root spine
 ```
 
 ### Quality Audit Flow
@@ -280,15 +277,15 @@ init → learn → (updates guardrails.md)
 
 | Subroutine | Defined In | Called By |
 |------------|-----------|----------|
-| Condensation Subroutine (.ai-context.md regeneration) | `core/shared/condensation.md` | implement, decompose, coverage, index |
+| Condensation Subroutine (.ai-context.md regeneration) | `core/shared/condensation.md` | implement, decompose, coverage |
 | Standard File Metadata (YAML frontmatter) | `init` | All skills that generate draft/ files |
 | Three-Stage Review | `review` | implement (at phase boundaries) |
-| Signal Classification | `init` | init refresh, index (future) |
+| Signal Classification | `init` | init refresh |
 | Pattern Learning | `core/shared/pattern-learning.md` | learn, bughunt, review, deep-review (updates guardrails.md) |
 | Context Loading | `core/shared/draft-context-loading.md` | All skills requiring draft/ context |
 | Cross-Skill Dispatch | `core/shared/cross-skill-dispatch.md` | bughunt, deep-review, implement, review |
 | Jira Sync | `core/shared/jira-sync.md` | bughunt, review, implement (when ticket linked) |
-| Graph Query | `core/shared/graph-query.md` | init, implement, bughunt, review, debug, decompose, index, impact |
+| Graph Query | `core/shared/graph-query.md` | init, implement, bughunt, review, debug, decompose, impact |
 | Graph Mermaid | `scripts/tools/mermaid-from-graph.sh` | init (injects module-deps + proto-map into architecture.md) |
 
 ## Artifact Flow
@@ -304,8 +301,8 @@ init → learn → (updates guardrails.md)
   init ──────────►  │  architecture.md ──► .ai-context.md         │
                     │  product.md  tech-stack.md  guardrails.md   │
                     │  workflow.md  tracks.md  tech-debt.md       │
-                    │  graph/ (module-graph, hotspots, proto,      │
-                    │         module-deps.mermaid, proto-map..)   │
+                    │  graph/ (schema.yaml gate; all data queried  │
+                    │         live via codebase-memory-mcp engine) │
                     └──────────────────┬──────────────────────────┘
                                        │ read by all skills
            ┌───────────────────────────┼───────────────────────┐

package/skills/bughunt/SKILL.md

@@ -68,7 +68,7 @@ Read and follow the base procedure in `core/shared/draft-context-loading.md`.
 - **Leverage Storage Topology** — Identify data loss risks at each tier (cache eviction without writeback, event log gaps, missing archive)
 - **Leverage Consistency Boundaries** — Find bugs at eventual consistency seams (stale reads, lost events, missing reconciliation)
 - **Leverage Failure Recovery Matrix** — Verify idempotency claims, check for partial failure states without recovery paths
-- **Leverage Graph Data** (if `draft/graph/` exists) — Read `architecture.json` (`.packages`) for dependency awareness. Flag dependencies on unexpected modules. Flag code in modules involved in dependency cycles as higher risk. Use `hotspots.jsonl` to prioritize analysis of high-complexity, high-fanIn files. See `core/shared/graph-query.md`.
+- **Leverage Graph Data** (if `draft/graph/` exists) — Query `scripts/tools/graph-arch.sh --repo .` for dependency awareness. Flag dependencies on unexpected modules. Flag code in modules involved in dependency cycles as higher risk. Run `scripts/tools/hotspot-rank.sh --repo .` to prioritize analysis of high-complexity, high-fanIn files. See `core/shared/graph-query.md`.
 - **Leverage Learned Anti-Patterns** — If `draft/guardrails.md` exists, read the `## Learned Anti-Patterns` section. During the bug sweep, when a bug matches a learned anti-pattern, prefix the report entry with `[KNOWN-ANTI-PATTERN: {pattern name}]`. This distinguishes recurring documented patterns from newly discovered bugs, and signals that a systemic fix may be needed rather than a one-off patch.
 
 ### 2. Confirm Scope
@@ -94,6 +94,19 @@ Use track context to:
 
 If no Draft context exists, proceed with code-only analysis.
 
+## Multi-Directory Mode (monorepo)
+
+`/draft:bughunt` can sweep multiple sub-projects in one run — useful at a monorepo root. Trigger it with an explicit directory list (`bughunt <dir1> <dir2> ...`) or no list (auto-discover).
+
+1. **Resolve targets:**
+   - **Explicit list** → use the given directories; verify each exists; skip (with a warning) any that lack a `draft/` directory.
+   - **Auto-discover** → immediate child directories containing a `draft/` folder, excluding `node_modules/`, `vendor/`, `.git/`, `draft/`, and dotfiles.
+2. **Run sequentially** (not in parallel — avoids context conflicts): for each target, run the full single-target bug hunt below scoped to that directory. Each writes its own `<dir>/draft/bughunt-report-latest.md`.
+3. **Aggregate** into `draft/bughunt-summary.md` at the invocation root: a table of `dir | Critical | High | Medium | Low | Total | report link`, a grand total, and a "directories with Critical issues" callout.
+4. Report skipped directories (no `draft/`) and suggest running `/draft:init` in them first.
+
+For a single target (the common case), skip this section and proceed.
+
 ## Dimension Applicability Check
 
 Before analyzing all 14 dimensions, determine which apply to this codebase:

package/skills/debug/SKILL.md

@@ -11,10 +11,10 @@ You are conducting a structured debugging session following systematic investiga
 
 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. During Steps 3–4 (Isolate, Diagnose):
 
-1. Locate the suspect file's module via `draft/graph/architecture.json` (`.packages`) before tracing data flow.
+1. Locate the suspect file's module via `scripts/tools/graph-arch.sh --repo .` before tracing data flow.
 2. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to enumerate call sites of suspect functions — not `grep`.
 3. Use `scripts/tools/graph-impact.sh --repo . --file <path>` to size the blast radius before proposing a fix.
-4. Cross-check `draft/graph/hotspots.jsonl` to know whether the file is high-fanIn (any fix needs extra caution).
+4. Run `scripts/tools/hotspot-rank.sh --repo .` to know whether the file is high-fanIn (any fix needs extra caution).
 
 Filesystem `grep` is reserved for source-text scans (literal error strings, stack-trace symbols when the graph misses). Use the fallback sentence on graph miss.
 
@@ -62,7 +62,7 @@ Key context for debugging:
 - `.ai-context.md` — Module boundaries, data flows, invariants (crucial for tracing)
 - `tech-stack.md` — Language-specific debugging tools and techniques
 - `guardrails.md` — Known anti-patterns that may be causing the issue
-- `draft/graph/` (MANDATORY when present) — Load `architecture.json` for dependency/module context and `hotspots.jsonl` for complexity awareness. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to find all callers, and `scripts/tools/graph-impact.sh --repo . --file <path>` to size blast radius before any fix. See [core/shared/graph-query.md](../../core/shared/graph-query.md).
+- `draft/graph/` (MANDATORY when present) — Query `scripts/tools/graph-arch.sh --repo .` for dependency/module context and `scripts/tools/hotspot-rank.sh --repo .` for complexity awareness. Use `scripts/tools/graph-callers.sh --repo . --symbol <fn>` to find all callers, and `scripts/tools/graph-impact.sh --repo . --file <path>` to size blast radius before any fix. See [core/shared/graph-query.md](../../core/shared/graph-query.md).
 
 ## Step 1: Parse Arguments
 

package/skills/decompose/SKILL.md

@@ -11,8 +11,8 @@ You are decomposing a project or track into modules with clear responsibilities,
 
 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. Module identification (Step 3) and dependency mapping (Step 4) **start from the graph**:
 
-1. Load `draft/graph/architecture.json` (`.packages`) for the authoritative module list and fan-in/out.
-2. Load `draft/graph/hotspots.jsonl` to identify candidate modules to split.
+1. Query `scripts/tools/graph-arch.sh --repo .` for the authoritative module list and fan-in/out.
+2. Run `scripts/tools/hotspot-rank.sh --repo .` to identify candidate modules to split.
 3. Use `scripts/tools/graph-callers.sh`/`graph-impact.sh` on demand for symbols/callers inside a candidate module.
 4. Run `scripts/tools/cycle-detect.sh --repo .` to enumerate existing cycles before proposing new boundaries.
 
@@ -156,10 +156,10 @@ ls -d src/*/ lib/*/ app/*/ packages/*/ 2>/dev/null
 
 When graph data is available, the graph is the **primary** (not optional) source for module discovery — manual scanning above is reserved for the graph-miss fallback path:
 
-- **Module boundaries**: Read `draft/graph/architecture.json` (`.packages`, `.languages`) — module list with node counts and per-language file counts
+- **Module boundaries**: Query `scripts/tools/graph-arch.sh --repo .` — module list with node counts and per-language file counts
 - **Dependency edges**: Weighted inter-module dependencies with exact include counts — replaces manual import tracing
 - **Cycle detection**: Circular dependency paths already computed — use for identifying tight coupling and decomposition candidates
-- **Hotspots**: Load `draft/graph/hotspots.jsonl` — high-complexity files that may need further decomposition
+- **Hotspots**: Run `scripts/tools/hotspot-rank.sh --repo .` — high-complexity files that may need further decomposition
 - **Per-module detail**: query `scripts/tools/graph-callers.sh`/`graph-impact.sh` for symbol/call detail within modules of interest
 
 This data is deterministic and exhaustive. The manual scanning recipes above only run **after** the graph misses on the concept the user named — and the miss must be reported in the Graph Usage Report footer. See [core/shared/graph-query.md](../../core/shared/graph-query.md) §Concept-to-Files Recipe.
@@ -615,7 +615,7 @@ When decomposition involves breaking a monolith, choosing module boundaries, or
 
 Before printing the completion announcement, internally verify and report:
 
-1. **Graph files queried** — which JSONL files were loaded (e.g. `architecture.json, hotspots.jsonl` and tools like `cycle-detect.sh`).
+1. **Graph data queried** — which live-engine tools were invoked (e.g. `get_architecture`, `hotspot-rank.sh`, `cycle-detect.sh`).
 2. **Layer 1 files deliberately skipped** — list any `.ai-context.md` sections, `tech-stack.md`, `product.md`, `workflow.md` you skipped as irrelevant to this decomposition. Be explicit; do not silently skip.
 3. **Filesystem grep fallback justification** — for every `grep`/`find` run, state the concept it searched for and quote the graph-miss sentence.
 4. **Citation Gate audit** — scan every Citation column in the generated component table, dependencies table, and LLD class table. Report:

package/skills/deep-review/SKILL.md

@@ -11,10 +11,10 @@ Perform an exhaustive end-to-end lifecycle review of a service, component, or mo
 
 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. Deep-review uses the graph to **narrow review scope** — a key 30–50% scope reduction:
 
-1. Use `scripts/tools/graph-impact.sh`/`graph-callers.sh` and `architecture.json` for the audited module's structure — do not enumerate via `find`.
+1. Use `scripts/tools/graph-impact.sh`/`graph-callers.sh` and `scripts/tools/graph-arch.sh --repo .` for the audited module's structure — do not enumerate via `find`.
 2. Run `scripts/tools/graph-impact.sh --repo . --file <each-changed-file>` per file in the diff (or per file in the module if no diff) to obtain the affected module set deterministically.
 3. Run `scripts/tools/cycle-detect.sh --repo .` and flag any cycle that includes the audited module as Architecture Resilience finding.
-4. Cross-check `draft/graph/hotspots.jsonl` to identify high-fanIn files inside the module — these get deeper inspection.
+4. Run `scripts/tools/hotspot-rank.sh --repo .` to identify high-fanIn files inside the module — these get deeper inspection.
 
 Filesystem `grep` is reserved for source-text scans (API contract strings, secret patterns, log message audits). Module enumeration and caller tracing go through the graph.
 

package/skills/deploy-checklist/SKILL.md

@@ -12,8 +12,8 @@ You are generating a pre-deployment verification checklist customized to this pr
 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 validate module boundaries before the deploy:
 
 1. For each file in the deploy diff, run `scripts/tools/graph-impact.sh --repo . --file <path>` to enumerate the modules affected — flag any module **not** declared in `hld.md` §Detailed Design as a deployment-scope miss.
-2. Run `scripts/tools/cycle-detect.sh --repo .` (and read `draft/graph/architecture.json` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off.
-3. Load `draft/graph/hotspots.jsonl` — any hotspot in the diff escalates the Resiliency row of Phase 0.
+2. Run `scripts/tools/cycle-detect.sh --repo .` (and query `scripts/tools/graph-arch.sh --repo .` for the module overview) to ensure no fresh cycles were introduced after HLD sign-off.
+3. Run `scripts/tools/hotspot-rank.sh --repo .` — any hotspot in the diff escalates the Resiliency row of Phase 0.
 
 Filesystem `grep` is reserved for source-text scans (migration file names, flag-key strings). Module/impact discovery goes through the graph.
 

package/skills/discover/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: discover
-description: "Primary router for discovery, debugging, investigation, quality, and exploration workflows. Analyzes user intent and dispatches to debug, bughunt, quick-review, deep-review, coverage, testing-strategy, learn, index, tour, impact, assist-review. The recommended entry point for any 'find out', 'check', 'review', or 'investigate' request."
+description: "Primary router for discovery, debugging, investigation, quality, and exploration workflows. Analyzes user intent and dispatches to debug, bughunt, quick-review, deep-review, coverage, testing-strategy, learn, tour, impact, assist-review. The recommended entry point for any 'find out', 'check', 'review', or 'investigate' request."
 ---
 
 # Discover - Investigation & Quality Router
@@ -13,7 +13,6 @@ description: "Primary router for discovery, debugging, investigation, quality, a
 - Code quality reviews (lightweight to exhaustive to architectural)
 - Coverage analysis and test strategy design
 - Discovering and codifying project conventions
-- Monorepo indexing and context aggregation
 - Project tours, impact analysis, or reviewer assistance
 
 ## Routing Logic
@@ -29,7 +28,6 @@ Strong keyword and phrase matching with fallback to a menu when intent is broad
 | coverage, code coverage, test coverage report | `/draft:coverage` | Coverage measurement and gap report |
 | test strategy, testing plan, coverage targets, pyramid | `/draft:testing-strategy` | Test approach design |
 | learn patterns, discover conventions, update guardrails, anti-patterns | `/draft:learn` | Pattern mining + guardrail evolution |
-| index services, aggregate context, monorepo index | `/draft:index` | Monorepo service context aggregation |
 | tour, walkthrough, onboard me, getting started tour | `/draft:tour` | Guided interactive project tour |
 | blast radius, code impact, affected modules, downstream callers | `/draft:review` or `scripts/tools/graph-impact.sh` | Graph-derived blast-radius before merge |
 | impact, delivery telemetry, track analytics, CDD effectiveness | `/draft:impact` | Project-wide track delivery telemetry |
@@ -55,7 +53,7 @@ User: "learn the coding patterns in this repo and tighten guardrails"
 
 User: "index the monorepo so agents see all services"
 
-→ dispatches to `/draft:index --init-missing`
+→ Monorepo context is a foundation task, not a discover route: run `/draft:init` at the repo root (it builds the whole-repo code graph + a sparse root map linking each module). Running `/draft:init` inside a sub-module links that module up to the same root graph.
 
 ## Auto-Chains & Recommendations
 

package/skills/draft/SKILL.md

@@ -39,7 +39,7 @@ The 5 router commands provide intent-based dispatch into the 20+ specialist comm
 | `/draft:plan` | Planning & architecture | new-track, decompose, adr, tech-debt, change |
 | `/draft:ops` | Operations & lifecycle | deploy-checklist, incident-response, standup, status, revert |
 | `/draft:docs` | Authoring | documentation |
-| `/draft:discover` | Investigation & quality | debug, bughunt, quick/deep-review, coverage, testing-strategy, learn, index, tour, impact, assist-review |
+| `/draft:discover` | Investigation & quality | debug, bughunt, quick/deep-review, coverage, testing-strategy, learn, tour, impact, assist-review |
 | `/draft:jira` | Jira integration (preview, create, review) | - |
 
 ### Specialist Commands (leaf skills, invoked via routers or directly)
@@ -74,7 +74,7 @@ These commands remain available for targeted, specialist execution outside paren
 
 #### 4. Setup & Documentation
 * `/draft` - Display this command overview and help reference
-* `/draft:index` - Aggregate multi-service context in monorepo structures
+* `/draft:init` - Single scope-aware entry point: builds the root-first code graph (`draft/graph/`) and project context; run at the repo root or inside any sub-module (monorepo context comes from running it at root)
 * `/draft:discover` - Phase 0 code-spike report (hotspots, mode flags, open questions) before spec freeze
 * `/draft:documentation` - Generate structured codebase documentation (API, Onboarding, Runbooks)
 * `/draft:tech-debt` - Audit technical debt across 6 key dimensions

package/skills/draft/intent-mapping.md

@@ -33,5 +33,6 @@ Draft commands can be invoked using natural language. If you describe your goal
 | "write docs", "create readme", "api documentation" | `/draft:documentation` | Generate professional, structured docs |
 | "preview jira", "export jira issues", "jira draft" | `/draft:jira-preview` | Generate Jira markdown export from plan |
 | "create jira", "push to jira board" | `/draft:jira-create` | Create actual Jira issues via MCP integrations |
-| "index services", "aggregate context", "monorepo setup" | `/draft:index` | Aggregate multi-service context at the root |
-| "build graph", "refresh graph", "rebuild the knowledge graph", "index this repo's structure" | `/draft:graph` | Initialize/refresh the `draft/graph/` snapshot (optionally `draft graph <path>`) |
+| "index services", "aggregate context", "monorepo setup" | `/draft:init` | Single entry point — run at the repo root to build the whole-repo code graph + sparse root map; run in a sub-module to link up to it |
+| "build the code graph", "index this repo's structure", "graph memory only" | `/draft:init --graph-only` | Scope-aware, root-first code-graph build with no markdown |
+| "build graph", "refresh graph", "rebuild the knowledge graph" | `/draft:graph` | Narrow refresh of the `draft/graph/` snapshot for one repo (optionally `draft graph <path>`) |

package/skills/graph/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize or refresh the knowledge-graph snapshot for a repository
 
 # Draft Graph
 
-Initialize or refresh the `draft/graph/` knowledge-graph snapshot for a repository. This is the narrow "give me a fresh structural graph" command — it does **not** generate `architecture.md`/`.ai-context.md` (that is `/draft:init`) and does **not** re-inject doc diagram slots (that is `/draft:index`).
+Initialize or refresh the `draft/graph/` knowledge-graph snapshot for a single repository. This is the narrow "give me a fresh structural graph" command — it does **not** generate `architecture.md`/`.ai-context.md` and does **not** re-inject doc diagram slots (both are `/draft:init`). For scope-aware, root-first graph memory across a monorepo (root spine + module→root links), use `/draft:init --graph-only`.
 
 ## Red Flags - STOP if you're:
 
@@ -55,7 +55,7 @@ echo "Engine: $ENGINE"
 
 ## Step 3: Build / refresh the snapshot
 
-One call resolves the engine, indexes the repo (incrementally on refresh), and writes the committed snapshot under `<repo>/draft/graph/` — `schema.yaml`, `architecture.json`, `hotspots.jsonl`, `module-deps.mermaid`, `proto-map.mermaid`.
+One call resolves the engine, indexes the repo (incrementally on refresh), and updates the gate marker `<repo>/draft/graph/schema.yaml` (engine metadata + point-of-index counts; `access: engine-live`). All structural graph data is queried live from the engine — no snapshot files are committed beyond `schema.yaml`.
 
 ```bash
 scripts/tools/graph-snapshot.sh --repo "$REPO_ABS"
@@ -92,7 +92,7 @@ Present a concise summary:
 
 Then point the user at the natural next steps:
 
-- To re-inject the refreshed diagrams/hotspot tables into `architecture.md` / `.ai-context.md`: run `/draft:index`.
+- To re-inject the refreshed diagrams/hotspot tables into `architecture.md` / `.ai-context.md`: run `/draft:init refresh` (or `/draft:init --graph-only` to rebuild just the graph memory).
 - For a first-time full context bootstrap (architecture + profiles): run `/draft:init`.
 
 ## Graceful Degradation

package/skills/implement/SKILL.md

@@ -133,7 +133,7 @@ If one of these applies, route directly to the specialist workflow and stop this
    - Keep matching invariants as **active constraints** for this task — these govern code generation, not just review
    - If invariants reference lock ordering, fail-closed behavior, or data integrity rules: these are non-negotiable during implementation
 9. **Load graph context** (if `draft/graph/schema.yaml` exists):
-   - Read `draft/graph/hotspots.jsonl` — check if any files this task will modify appear as hotspots
+   - Run `scripts/tools/hotspot-rank.sh --repo .` — check if any files this task will modify appear as hotspots
    - If modifying a hotspot file (high fanIn), warn: "This task modifies {file} (fanIn={N}). Changes here affect many downstream files. Consider running a graph impact query."
    - Query `scripts/tools/graph-impact.sh`/`graph-callers.sh` for the module(s) being modified — gives file-level dependency context
    - See `core/shared/graph-query.md` for on-demand query subroutines (callers, impact)