@drafthq/draft 3.3.0 → 3.4.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
       "name": "draft",
       "source": "./",
       "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-      "version": "3.3.0",
+      "version": "3.4.0",
       "author": {
         "name": "mayurpise"
       },

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.3.0",
+  "version": "3.4.0",
   "author": {
     "name": "mayurpise"
   },

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "draft",
   "displayName": "Draft",
   "description": "Context-Driven Development: draft specs and plans before implementation. Structured workflows for features and fixes.",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "skills": "./skills/",
   "agents": "./core/agents/",
   "author": {

package/README.md

@@ -67,7 +67,7 @@ Each host installs the way that host actually loads extensions — no manual ste
 | Host | `draft install …` | What it does |
 |------|-------------------|--------------|
 | **Claude Code** | `claude-code` | Registers the plugin via `claude plugin marketplace add` + `claude plugin install` (user scope). Restart Claude Code. |
-| **Cursor** | `cursor` | Copies the plugin into `~/.cursor/plugins/local/draft/`, writes `.cursor-plugin/plugin.json`, registers `draft@draft-plugins` in Cursor's plugin registry, and enables it. Restart Cursor (or Developer: Reload Window). |
+| **Cursor** | `cursor` | Copies the plugin into `~/.cursor/plugins/local/draft/`, writes `.cursor-plugin/plugin.json`, registers `draft@draft-plugins` in Cursor's plugin registry, and enables it. Restart Cursor (or Developer: Reload Window). Existing installs upgrade with `draft install cursor --force`. |
 | **Codex** | `codex` | Writes `./AGENTS.md`, which Codex reads automatically. |
 | **opencode** | `opencode` | Writes `./AGENTS.md` + `~/.agents/skills/draft/`, both auto-discovered. |
 
@@ -223,6 +223,24 @@ Skills also call into **shell helpers** under `scripts/tools/` for mechanical wo
                                    files with changed hashes
 ```
 
+### Context output modes (`/draft:init`)
+
+`/draft:init` packages your architecture context in one of two modes, selected
+automatically by repo size (override with `DRAFT_INIT_MODE`):
+
+- **`monolith`** (default for small repos, tiers 1–2) — a single
+  graph-primary `architecture.md` is the source of truth; `.ai-context.md` is
+  the token-optimized AI view derived from it.
+- **`okf`** (default for larger repos, tiers 3+) — an **OKF concept taxonomy**
+  under `draft/wiki/` is the source of truth (one concept per file, cross-links
+  form the graph), `.ai-context.md` becomes the navigable index root
+  (Synopsis + Concept Map), and `architecture.md` is demoted to a generated
+  rendered view. An optional self-contained offline HTML viewer ships under
+  `draft/wiki/web/`.
+
+Both modes produce the same `product.md`, `tech-stack.md`, `workflow.md`,
+`guardrails.md`, tracks, and `.state/` — only the architecture packaging differs.
+
 [Full workflow →](core/methodology.md#core-workflow)
 
 ---

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

@@ -117,6 +117,15 @@ Apply relevance scoring when ALL of these conditions are true:
 
 Do NOT apply relevance scoring for commands that need full context (`/draft:init`, `/draft:deep-review`, `/draft:decompose`).
 
+### Retrieval Path Selection (okf vs monolith)
+
+Relevance scoring has two implementations; pick by output mode:
+
+- **okf mode** — if `draft/wiki/` exists, use **tree-search retrieval** (`core/shared/okf-retrieval.md`): navigate the OKF Concept Map by reasoning over each concept's routing `description`, descending only the matching subtrees. This is the vectorless, reasoning-based path (PageIndex-style) and supersedes the static section table below for okf bundles.
+- **monolith mode** — if `draft/wiki/` does not exist, use the static **Scoring Procedure** below against `.ai-context.md` sections.
+
+The minimum context floor (`META`, `INVARIANTS`, `TEST`, `FILES`) applies to both paths.
+
 ### Scoring Procedure
 
 1. **Extract key concepts** from the active task:

package/core/shared/okf-retrieval.md

@@ -0,0 +1,94 @@
+# OKF Tree-Search Retrieval
+
+Reasoning-based retrieval over the OKF knowledge bundle. When a project was emitted in `okf` mode (`draft/wiki/` exists), agents locate relevant context by **navigating the concept tree** — reading routing descriptions and descending only the matching subtrees — instead of loading sections by a static heuristic. No embeddings, no chunking, no similarity search: relevance is decided by reasoning over the tree, the same way a human expert scans a table of contents.
+
+Referenced by: `core/shared/draft-context-loading.md` (Relevance-Scored Context Loading). Applies to every command that loads focused project context (`/draft:implement`, `/draft:bughunt`, `/draft:review`, `/draft:debug`, `/draft:change`).
+
+> **Prior art.** This adapts the navigation model of [PageIndex](https://github.com/VectifyAI/PageIndex) (vectorless, reasoning-based RAG) to Draft's self-authored artifacts. Draft already builds the tree — the OKF bundle (`index.md` → section indexes → concept pages) is a table-of-contents whose `description` frontmatter is the per-node routing key. What this procedure adds is the **retrieval loop**: a reasoning descent over that tree. Draft does not need PageIndex's tree-*generation* engine (it authors the tree itself) and stays vectorless by design.
+
+## When this applies
+
+Apply tree-search retrieval when ALL of these hold:
+
+1. `draft/wiki/` exists (project emitted in `okf` mode) **and** `draft/wiki/index.md` carries a populated `<!-- CONCEPT-MAP:START -->…:END -->` block.
+2. A specific track or task is active (focused retrieval — broad tasks terminate at the Synopsis, see below).
+3. The command benefits from focused context (the relevance-scoring conditions in `draft-context-loading.md`).
+
+If `draft/wiki/` does **not** exist (monolith mode), skip this procedure entirely and use the static section-scoring table in `draft-context-loading.md`. The two are mutually exclusive: tree-search is the okf-mode retrieval path; section-scoring is the monolith path.
+
+## The retrieval loop
+
+The bundle is a tree: `.ai-context.md` (index root: Synopsis + Concept Map) → section indexes (`systems/`, `features/`, `reference/`, `entrypoints/`, `overview/`) → concept pages. Each node advertises a `description` routing key. Navigate it, do not flatten it.
+
+```
+1. Frame the query
+   Extract routing terms from the active task: domain nouns from spec.md
+   acceptance criteria, file paths / module names / tech terms from plan.md,
+   and the primary concern (data flow, API, security, perf, config, …).
+
+2. Enter at the root
+   Read draft/.ai-context.md. The Synopsis is the cheap broad-context path —
+   for a BROAD task (onboarding, architecture overview, "how does X work
+   end-to-end") it is sufficient: TERMINATE here, do not descend.
+   For a FOCUSED task, read the Concept Map (the root routing table).
+
+3. Select subtrees (reason, don't match strings)
+   For each Concept Map row, judge the `description` as a ROUTING DECISION:
+   "does opening this concept help THIS task?" Score each candidate:
+     - strong   — description names the task's responsibility or its own terms
+     - possible — adjacent/depends-on the task area
+     - skip     — unrelated
+   Descend `strong` first; hold `possible` as a frontier for step 5.
+
+4. Descend to leaves
+   For a selected section, open its index.md and repeat step 3 against the
+   section's concept rows (one routing description per concept). Open the
+   matching concept page(s). A concept page is a LEAF — its `x-grounded-paths`
+   are the exact source files the task should open; `Used by` / `x-callers`
+   give the next hop if the task spans callers.
+
+5. Expand only if under-covered
+   If the opened leaves do not cover the task's routing terms, expand the
+   highest-scored `possible` frontier node (step 3) and recurse. Otherwise stop.
+```
+
+## Routing decision criteria
+
+The `description` frontmatter is load-bearing — it is written as a routing decision, not a summary (`core/templates/okf/concept.md`). Judge each node by:
+
+| Signal | Descend when… |
+|--------|---------------|
+| Responsibility match | The description names the capability/module the task changes |
+| Term overlap | Task's domain nouns / file paths appear in the description or `x-grounded-paths` |
+| Caller/blast-radius reach | Task modifies a symbol whose `x-callers` / `Used by` point at this node |
+| Concern alignment | Task's primary concern (security, perf, data flow) is this node's stated focus |
+
+Reason about relevance — do not keyword-match. A concept whose description does not justify opening it for the task at hand is skipped even if a term coincidentally overlaps (similarity ≠ relevance).
+
+## Termination & budget
+
+- **Broad task** → terminate at the Synopsis (step 2). Do not open concept pages.
+- **Focused task** → terminate when opened leaves cover the task's routing terms, or when **≤ 5 concept pages** have been opened (default budget; raise only if the task explicitly spans many subsystems, e.g. a cross-cutting refactor).
+- **Depth** → the tree is shallow by construction (root → section → concept ≈ 2 hops). If a descent has not reached a leaf in 3 hops, stop and open the best leaf seen so far.
+- **No match** → if no Concept Map row scores above `skip`, fall back to the Synopsis plus `## INVARIANTS` / `## FILES` / `## TEST` floor from `draft-context-loading.md`.
+
+The minimum context floor from `draft-context-loading.md` (`META`, `INVARIANTS`, `TEST`, `FILES`) still applies and is always loaded regardless of the descent.
+
+## Output contract (traceability)
+
+Tree-search retrieval is explainable by construction — record the path taken, mirroring PageIndex's node-ID grounding:
+
+- **Opened concepts** — the leaf pages selected, each with the one-line reason it was opened.
+- **Grounded paths** — the union of `x-grounded-paths` across opened leaves: the precise source files the task will read or modify.
+- **Skipped frontier** — `possible` nodes held but not expanded (so a follow-up task can resume from them).
+
+Surface this trace when the command reports which context it loaded (e.g. `/draft:implement` plan preamble, `/draft:review` scope note). It replaces "loaded sections A, B, C" with "navigated to concepts X, Y because …".
+
+## Degradation
+
+| Scenario | Behavior |
+|----------|----------|
+| `draft/wiki/` missing | Skip; use monolith section-scoring in `draft-context-loading.md` |
+| Concept Map markers empty/absent | Fall back to reading `wiki/*/index.md` section tables directly; if those are missing, use the Synopsis + floor |
+| Routing descriptions thin/uninformative | Open the section `index.md` and skim concept titles; flag for `/draft:init refresh` to regenerate descriptions |
+| Task is broad | Terminate at Synopsis — descending is over-fetch (a Red Flag per `red-flags.md`) |

package/integrations/agents/AGENTS.md

@@ -455,7 +455,11 @@ If the user runs `draft init refresh`:
 
 1. **Tech Stack Refresh**: Re-scan `package.json`, `go.mod`, etc. Compare with `draft/tech-stack.md`. Propose updates.
 
-2. **Architecture Refresh**: If `draft/architecture.md` exists, use metadata-based incremental analysis. If freshness state is available from step 0b, use file-level deltas to scope the refresh more precisely than git-diff alone:
+2. **Architecture Refresh**:
+
+   **Mode detection (do this first).** If `draft/wiki/` exists, the bundle was generated in **`okf` mode** and `architecture.md` is a *generated rendered view*, not the source of truth. In that case **follow `references/okf-emitter.md` §"Incremental refresh at concept granularity (M5)"** instead of the monolith steps below: diff `hashes.json` → map changed source paths to affected concepts → regenerate only those concepts (carry the rest forward from cache) → always re-render `.ai-context.md`, `architecture.md`, and `log.md` via `okf-render-views.sh` → re-run `okf-validate.sh` so cross-links still resolve. Do **not** hand-edit `architecture.md` in this mode — it is overwritten by the renderer. Then skip to step 3.
+
+   Otherwise (**`monolith` mode** — `draft/architecture.md` is the source of truth and no `draft/wiki/` exists), use metadata-based incremental analysis. If freshness state is available from step 0b, use file-level deltas to scope the refresh more precisely than git-diff alone:
 
    **a. Read synced commit from metadata:**
    ```bash
@@ -16270,6 +16274,15 @@ Apply relevance scoring when ALL of these conditions are true:
 
 Do NOT apply relevance scoring for commands that need full context (`draft init`, `draft deep-review`, `draft decompose`).
 
+### Retrieval Path Selection (okf vs monolith)
+
+Relevance scoring has two implementations; pick by output mode:
+
+- **okf mode** — if `draft/wiki/` exists, use **tree-search retrieval** (`core/shared/okf-retrieval.md`): navigate the OKF Concept Map by reasoning over each concept's routing `description`, descending only the matching subtrees. This is the vectorless, reasoning-based path (PageIndex-style) and supersedes the static section table below for okf bundles.
+- **monolith mode** — if `draft/wiki/` does not exist, use the static **Scoring Procedure** below against `.ai-context.md` sections.
+
+The minimum context floor (`META`, `INVARIANTS`, `TEST`, `FILES`) applies to both paths.
+
 ### Scoring Procedure
 
 1. **Extract key concepts** from the active task:
@@ -17643,6 +17656,109 @@ The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159
 
 ---
 
+## core/shared/okf-retrieval.md
+
+<core-file path="core/shared/okf-retrieval.md">
+
+# OKF Tree-Search Retrieval
+
+Reasoning-based retrieval over the OKF knowledge bundle. When a project was emitted in `okf` mode (`draft/wiki/` exists), agents locate relevant context by **navigating the concept tree** — reading routing descriptions and descending only the matching subtrees — instead of loading sections by a static heuristic. No embeddings, no chunking, no similarity search: relevance is decided by reasoning over the tree, the same way a human expert scans a table of contents.
+
+Referenced by: `core/shared/draft-context-loading.md` (Relevance-Scored Context Loading). Applies to every command that loads focused project context (`draft implement`, `draft bughunt`, `draft review`, `draft debug`, `draft change`).
+
+> **Prior art.** This adapts the navigation model of [PageIndex](https://github.com/VectifyAI/PageIndex) (vectorless, reasoning-based RAG) to Draft's self-authored artifacts. Draft already builds the tree — the OKF bundle (`index.md` → section indexes → concept pages) is a table-of-contents whose `description` frontmatter is the per-node routing key. What this procedure adds is the **retrieval loop**: a reasoning descent over that tree. Draft does not need PageIndex's tree-*generation* engine (it authors the tree itself) and stays vectorless by design.
+
+## When this applies
+
+Apply tree-search retrieval when ALL of these hold:
+
+1. `draft/wiki/` exists (project emitted in `okf` mode) **and** `draft/wiki/index.md` carries a populated `<!-- CONCEPT-MAP:START -->…:END -->` block.
+2. A specific track or task is active (focused retrieval — broad tasks terminate at the Synopsis, see below).
+3. The command benefits from focused context (the relevance-scoring conditions in `draft-context-loading.md`).
+
+If `draft/wiki/` does **not** exist (monolith mode), skip this procedure entirely and use the static section-scoring table in `draft-context-loading.md`. The two are mutually exclusive: tree-search is the okf-mode retrieval path; section-scoring is the monolith path.
+
+## The retrieval loop
+
+The bundle is a tree: `.ai-context.md` (index root: Synopsis + Concept Map) → section indexes (`systems/`, `features/`, `reference/`, `entrypoints/`, `overview/`) → concept pages. Each node advertises a `description` routing key. Navigate it, do not flatten it.
+
+```
+1. Frame the query
+   Extract routing terms from the active task: domain nouns from spec.md
+   acceptance criteria, file paths / module names / tech terms from plan.md,
+   and the primary concern (data flow, API, security, perf, config, …).
+
+2. Enter at the root
+   Read draft/.ai-context.md. The Synopsis is the cheap broad-context path —
+   for a BROAD task (onboarding, architecture overview, "how does X work
+   end-to-end") it is sufficient: TERMINATE here, do not descend.
+   For a FOCUSED task, read the Concept Map (the root routing table).
+
+3. Select subtrees (reason, don't match strings)
+   For each Concept Map row, judge the `description` as a ROUTING DECISION:
+   "does opening this concept help THIS task?" Score each candidate:
+     - strong   — description names the task's responsibility or its own terms
+     - possible — adjacent/depends-on the task area
+     - skip     — unrelated
+   Descend `strong` first; hold `possible` as a frontier for step 5.
+
+4. Descend to leaves
+   For a selected section, open its index.md and repeat step 3 against the
+   section's concept rows (one routing description per concept). Open the
+   matching concept page(s). A concept page is a LEAF — its `x-grounded-paths`
+   are the exact source files the task should open; `Used by` / `x-callers`
+   give the next hop if the task spans callers.
+
+5. Expand only if under-covered
+   If the opened leaves do not cover the task's routing terms, expand the
+   highest-scored `possible` frontier node (step 3) and recurse. Otherwise stop.
+```
+
+## Routing decision criteria
+
+The `description` frontmatter is load-bearing — it is written as a routing decision, not a summary (`core/templates/okf/concept.md`). Judge each node by:
+
+| Signal | Descend when… |
+|--------|---------------|
+| Responsibility match | The description names the capability/module the task changes |
+| Term overlap | Task's domain nouns / file paths appear in the description or `x-grounded-paths` |
+| Caller/blast-radius reach | Task modifies a symbol whose `x-callers` / `Used by` point at this node |
+| Concern alignment | Task's primary concern (security, perf, data flow) is this node's stated focus |
+
+Reason about relevance — do not keyword-match. A concept whose description does not justify opening it for the task at hand is skipped even if a term coincidentally overlaps (similarity ≠ relevance).
+
+## Termination & budget
+
+- **Broad task** → terminate at the Synopsis (step 2). Do not open concept pages.
+- **Focused task** → terminate when opened leaves cover the task's routing terms, or when **≤ 5 concept pages** have been opened (default budget; raise only if the task explicitly spans many subsystems, e.g. a cross-cutting refactor).
+- **Depth** → the tree is shallow by construction (root → section → concept ≈ 2 hops). If a descent has not reached a leaf in 3 hops, stop and open the best leaf seen so far.
+- **No match** → if no Concept Map row scores above `skip`, fall back to the Synopsis plus `## INVARIANTS` / `## FILES` / `## TEST` floor from `draft-context-loading.md`.
+
+The minimum context floor from `draft-context-loading.md` (`META`, `INVARIANTS`, `TEST`, `FILES`) still applies and is always loaded regardless of the descent.
+
+## Output contract (traceability)
+
+Tree-search retrieval is explainable by construction — record the path taken, mirroring PageIndex's node-ID grounding:
+
+- **Opened concepts** — the leaf pages selected, each with the one-line reason it was opened.
+- **Grounded paths** — the union of `x-grounded-paths` across opened leaves: the precise source files the task will read or modify.
+- **Skipped frontier** — `possible` nodes held but not expanded (so a follow-up task can resume from them).
+
+Surface this trace when the command reports which context it loaded (e.g. `draft implement` plan preamble, `draft review` scope note). It replaces "loaded sections A, B, C" with "navigated to concepts X, Y because …".
+
+## Degradation
+
+| Scenario | Behavior |
+|----------|----------|
+| `draft/wiki/` missing | Skip; use monolith section-scoring in `draft-context-loading.md` |
+| Concept Map markers empty/absent | Fall back to reading `wiki/*/index.md` section tables directly; if those are missing, use the Synopsis + floor |
+| Routing descriptions thin/uninformative | Open the section `index.md` and skim concept titles; flag for `draft init refresh` to regenerate descriptions |
+| Task is broad | Terminate at Synopsis — descending is over-fetch (a Red Flag per `red-flags.md`) |
+
+</core-file>
+
+---
+
 ## core/shared/parallel-analysis.md
 
 <core-file path="core/shared/parallel-analysis.md">

package/integrations/copilot/.github/copilot-instructions.md

@@ -455,7 +455,11 @@ If the user runs `draft init refresh`:
 
 1. **Tech Stack Refresh**: Re-scan `package.json`, `go.mod`, etc. Compare with `draft/tech-stack.md`. Propose updates.
 
-2. **Architecture Refresh**: If `draft/architecture.md` exists, use metadata-based incremental analysis. If freshness state is available from step 0b, use file-level deltas to scope the refresh more precisely than git-diff alone:
+2. **Architecture Refresh**:
+
+   **Mode detection (do this first).** If `draft/wiki/` exists, the bundle was generated in **`okf` mode** and `architecture.md` is a *generated rendered view*, not the source of truth. In that case **follow `references/okf-emitter.md` §"Incremental refresh at concept granularity (M5)"** instead of the monolith steps below: diff `hashes.json` → map changed source paths to affected concepts → regenerate only those concepts (carry the rest forward from cache) → always re-render `.ai-context.md`, `architecture.md`, and `log.md` via `okf-render-views.sh` → re-run `okf-validate.sh` so cross-links still resolve. Do **not** hand-edit `architecture.md` in this mode — it is overwritten by the renderer. Then skip to step 3.
+
+   Otherwise (**`monolith` mode** — `draft/architecture.md` is the source of truth and no `draft/wiki/` exists), use metadata-based incremental analysis. If freshness state is available from step 0b, use file-level deltas to scope the refresh more precisely than git-diff alone:
 
    **a. Read synced commit from metadata:**
    ```bash
@@ -16270,6 +16274,15 @@ Apply relevance scoring when ALL of these conditions are true:
 
 Do NOT apply relevance scoring for commands that need full context (`draft init`, `draft deep-review`, `draft decompose`).
 
+### Retrieval Path Selection (okf vs monolith)
+
+Relevance scoring has two implementations; pick by output mode:
+
+- **okf mode** — if `draft/wiki/` exists, use **tree-search retrieval** (`core/shared/okf-retrieval.md`): navigate the OKF Concept Map by reasoning over each concept's routing `description`, descending only the matching subtrees. This is the vectorless, reasoning-based path (PageIndex-style) and supersedes the static section table below for okf bundles.
+- **monolith mode** — if `draft/wiki/` does not exist, use the static **Scoring Procedure** below against `.ai-context.md` sections.
+
+The minimum context floor (`META`, `INVARIANTS`, `TEST`, `FILES`) applies to both paths.
+
 ### Scoring Procedure
 
 1. **Extract key concepts** from the active task:
@@ -17643,6 +17656,109 @@ The engine indexes C/C++, Go, Python, TypeScript/JS, and more (tree-sitter, 159
 
 ---
 
+## core/shared/okf-retrieval.md
+
+<core-file path="core/shared/okf-retrieval.md">
+
+# OKF Tree-Search Retrieval
+
+Reasoning-based retrieval over the OKF knowledge bundle. When a project was emitted in `okf` mode (`draft/wiki/` exists), agents locate relevant context by **navigating the concept tree** — reading routing descriptions and descending only the matching subtrees — instead of loading sections by a static heuristic. No embeddings, no chunking, no similarity search: relevance is decided by reasoning over the tree, the same way a human expert scans a table of contents.
+
+Referenced by: `core/shared/draft-context-loading.md` (Relevance-Scored Context Loading). Applies to every command that loads focused project context (`draft implement`, `draft bughunt`, `draft review`, `draft debug`, `draft change`).
+
+> **Prior art.** This adapts the navigation model of [PageIndex](https://github.com/VectifyAI/PageIndex) (vectorless, reasoning-based RAG) to Draft's self-authored artifacts. Draft already builds the tree — the OKF bundle (`index.md` → section indexes → concept pages) is a table-of-contents whose `description` frontmatter is the per-node routing key. What this procedure adds is the **retrieval loop**: a reasoning descent over that tree. Draft does not need PageIndex's tree-*generation* engine (it authors the tree itself) and stays vectorless by design.
+
+## When this applies
+
+Apply tree-search retrieval when ALL of these hold:
+
+1. `draft/wiki/` exists (project emitted in `okf` mode) **and** `draft/wiki/index.md` carries a populated `<!-- CONCEPT-MAP:START -->…:END -->` block.
+2. A specific track or task is active (focused retrieval — broad tasks terminate at the Synopsis, see below).
+3. The command benefits from focused context (the relevance-scoring conditions in `draft-context-loading.md`).
+
+If `draft/wiki/` does **not** exist (monolith mode), skip this procedure entirely and use the static section-scoring table in `draft-context-loading.md`. The two are mutually exclusive: tree-search is the okf-mode retrieval path; section-scoring is the monolith path.
+
+## The retrieval loop
+
+The bundle is a tree: `.ai-context.md` (index root: Synopsis + Concept Map) → section indexes (`systems/`, `features/`, `reference/`, `entrypoints/`, `overview/`) → concept pages. Each node advertises a `description` routing key. Navigate it, do not flatten it.
+
+```
+1. Frame the query
+   Extract routing terms from the active task: domain nouns from spec.md
+   acceptance criteria, file paths / module names / tech terms from plan.md,
+   and the primary concern (data flow, API, security, perf, config, …).
+
+2. Enter at the root
+   Read draft/.ai-context.md. The Synopsis is the cheap broad-context path —
+   for a BROAD task (onboarding, architecture overview, "how does X work
+   end-to-end") it is sufficient: TERMINATE here, do not descend.
+   For a FOCUSED task, read the Concept Map (the root routing table).
+
+3. Select subtrees (reason, don't match strings)
+   For each Concept Map row, judge the `description` as a ROUTING DECISION:
+   "does opening this concept help THIS task?" Score each candidate:
+     - strong   — description names the task's responsibility or its own terms
+     - possible — adjacent/depends-on the task area
+     - skip     — unrelated
+   Descend `strong` first; hold `possible` as a frontier for step 5.
+
+4. Descend to leaves
+   For a selected section, open its index.md and repeat step 3 against the
+   section's concept rows (one routing description per concept). Open the
+   matching concept page(s). A concept page is a LEAF — its `x-grounded-paths`
+   are the exact source files the task should open; `Used by` / `x-callers`
+   give the next hop if the task spans callers.
+
+5. Expand only if under-covered
+   If the opened leaves do not cover the task's routing terms, expand the
+   highest-scored `possible` frontier node (step 3) and recurse. Otherwise stop.
+```
+
+## Routing decision criteria
+
+The `description` frontmatter is load-bearing — it is written as a routing decision, not a summary (`core/templates/okf/concept.md`). Judge each node by:
+
+| Signal | Descend when… |
+|--------|---------------|
+| Responsibility match | The description names the capability/module the task changes |
+| Term overlap | Task's domain nouns / file paths appear in the description or `x-grounded-paths` |
+| Caller/blast-radius reach | Task modifies a symbol whose `x-callers` / `Used by` point at this node |
+| Concern alignment | Task's primary concern (security, perf, data flow) is this node's stated focus |
+
+Reason about relevance — do not keyword-match. A concept whose description does not justify opening it for the task at hand is skipped even if a term coincidentally overlaps (similarity ≠ relevance).
+
+## Termination & budget
+
+- **Broad task** → terminate at the Synopsis (step 2). Do not open concept pages.
+- **Focused task** → terminate when opened leaves cover the task's routing terms, or when **≤ 5 concept pages** have been opened (default budget; raise only if the task explicitly spans many subsystems, e.g. a cross-cutting refactor).
+- **Depth** → the tree is shallow by construction (root → section → concept ≈ 2 hops). If a descent has not reached a leaf in 3 hops, stop and open the best leaf seen so far.
+- **No match** → if no Concept Map row scores above `skip`, fall back to the Synopsis plus `## INVARIANTS` / `## FILES` / `## TEST` floor from `draft-context-loading.md`.
+
+The minimum context floor from `draft-context-loading.md` (`META`, `INVARIANTS`, `TEST`, `FILES`) still applies and is always loaded regardless of the descent.
+
+## Output contract (traceability)
+
+Tree-search retrieval is explainable by construction — record the path taken, mirroring PageIndex's node-ID grounding:
+
+- **Opened concepts** — the leaf pages selected, each with the one-line reason it was opened.
+- **Grounded paths** — the union of `x-grounded-paths` across opened leaves: the precise source files the task will read or modify.
+- **Skipped frontier** — `possible` nodes held but not expanded (so a follow-up task can resume from them).
+
+Surface this trace when the command reports which context it loaded (e.g. `draft implement` plan preamble, `draft review` scope note). It replaces "loaded sections A, B, C" with "navigated to concepts X, Y because …".
+
+## Degradation
+
+| Scenario | Behavior |
+|----------|----------|
+| `draft/wiki/` missing | Skip; use monolith section-scoring in `draft-context-loading.md` |
+| Concept Map markers empty/absent | Fall back to reading `wiki/*/index.md` section tables directly; if those are missing, use the Synopsis + floor |
+| Routing descriptions thin/uninformative | Open the section `index.md` and skim concept titles; flag for `draft init refresh` to regenerate descriptions |
+| Task is broad | Terminate at Synopsis — descending is over-fetch (a Red Flag per `red-flags.md`) |
+
+</core-file>
+
+---
+
 ## core/shared/parallel-analysis.md
 
 <core-file path="core/shared/parallel-analysis.md">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Context-Driven Development for AI coding agents — install Draft into Claude Code, Cursor, Codex, or opencode.",
   "bin": {
     "draft": "cli/bin/draft.js"

package/scripts/lib.sh

@@ -73,6 +73,7 @@ CORE_FILES=(
     "shared/cross-skill-dispatch.md"
     "shared/jira-sync.md"
     "shared/graph-query.md"
+    "shared/okf-retrieval.md"
     "shared/parallel-analysis.md"
     # Foundations additions (Phase 0)
     "shared/context-verify.md"

package/skills/init/SKILL.md

@@ -335,7 +335,11 @@ If the user runs `/draft:init refresh`:
 
 1. **Tech Stack Refresh**: Re-scan `package.json`, `go.mod`, etc. Compare with `draft/tech-stack.md`. Propose updates.
 
-2. **Architecture Refresh**: If `draft/architecture.md` exists, use metadata-based incremental analysis. If freshness state is available from step 0b, use file-level deltas to scope the refresh more precisely than git-diff alone:
+2. **Architecture Refresh**:
+
+   **Mode detection (do this first).** If `draft/wiki/` exists, the bundle was generated in **`okf` mode** and `architecture.md` is a *generated rendered view*, not the source of truth. In that case **follow `references/okf-emitter.md` §"Incremental refresh at concept granularity (M5)"** instead of the monolith steps below: diff `hashes.json` → map changed source paths to affected concepts → regenerate only those concepts (carry the rest forward from cache) → always re-render `.ai-context.md`, `architecture.md`, and `log.md` via `okf-render-views.sh` → re-run `okf-validate.sh` so cross-links still resolve. Do **not** hand-edit `architecture.md` in this mode — it is overwritten by the renderer. Then skip to step 3.
+
+   Otherwise (**`monolith` mode** — `draft/architecture.md` is the source of truth and no `draft/wiki/` exists), use metadata-based incremental analysis. If freshness state is available from step 0b, use file-level deltas to scope the refresh more precisely than git-diff alone:
 
    **a. Read synced commit from metadata:**
    ```bash