@drafthq/draft 3.2.1 → 3.3.1

package/scripts/tools/okf-validate.sh

@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+# okf-validate.sh — validate an OKF (Open Knowledge Format) taxonomy bundle.
+#
+# This is the deterministic ground-truth verifier for the `/draft:init` OKF
+# emitter (DRAFT_INIT_MODE=okf). It fails the build on dangling cross-links,
+# missing/invalid frontmatter, and an incomplete path→concept index, so a
+# page-by-page generation pass cannot ship a structurally broken bundle.
+#
+# Checks:
+#   1. BUNDLE_DIR exists and contains a root index.md.
+#   2. Every concept page (any *.md whose frontmatter declares `type:`) carries
+#      all required OKF frontmatter keys: type, title, description, resource.
+#   3. Every declared `type` is in the frozen code-repo vocabulary (§4 of HLD).
+#   4. Every relative markdown cross-link ( ](path.md) ) resolves to a file that
+#      exists inside the bundle. External (http/https/mailto) and pure-anchor
+#      (#frag) links are ignored.
+#   5. (optional) --path-index FILE: every concept page referenced by the
+#      path→concept index exists in the bundle (no dangle, no stale rename).
+#
+# Usage:
+#   scripts/tools/okf-validate.sh <BUNDLE_DIR> [--path-index FILE] [--json]
+#
+# Exit codes: 0 valid, 1 invalid (diagnostics to stderr), 2 bundle not found.
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=scripts/tools/_lib.sh
+source "$SCRIPT_DIR/_lib.sh"
+
+# Frozen concept `type` vocabulary for code repos. Changing this churns every
+# generated file, so it is versioned in the bundle (index.md: okf_types_version).
+OKF_TYPES="Subsystem Module Feature Entrypoint API DataModel Dependency ADR Runbook"
+
+BUNDLE=""
+PATH_INDEX=""
+JSON=0
+
+usage() {
+    cat <<'EOF'
+okf-validate.sh — validate an OKF taxonomy bundle (the /draft:init OKF emitter output).
+
+Usage:
+  scripts/tools/okf-validate.sh <BUNDLE_DIR> [--path-index FILE] [--json]
+
+Flags:
+  --path-index FILE  Validate a path→concept index (JSON): every concept page it
+                     names must exist in the bundle.
+  --json             Emit a JSON summary instead of human diagnostics.
+  --help             Show this help.
+
+Exit 0 valid, 1 invalid, 2 bundle directory not found.
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --path-index) PATH_INDEX="$2"; shift 2;;
+        --json) JSON=1; shift;;
+        --help|-h) usage; exit 0;;
+        -*) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+        *)
+            if [[ -z "$BUNDLE" ]]; then BUNDLE="$1"
+            else echo "Unexpected arg: $1" >&2; exit 1
+            fi
+            shift
+            ;;
+    esac
+done
+
+if [[ -z "$BUNDLE" ]]; then
+    usage >&2
+    exit 1
+fi
+
+if [[ ! -d "$BUNDLE" ]]; then
+    echo "ERROR: bundle directory not found: $BUNDLE" >&2
+    exit 2
+fi
+
+BUNDLE="${BUNDLE%/}"
+
+ERRORS=()
+PAGE_COUNT=0
+CONCEPT_COUNT=0
+
+add_error() { ERRORS+=("$1"); }
+
+# Does the frozen vocabulary contain $1?
+is_known_type() {
+    local t="$1"
+    [[ " $OKF_TYPES " == *" $t "* ]]
+}
+
+# --- 1. Root index ---
+if [[ ! -f "$BUNDLE/index.md" ]]; then
+    add_error "missing bundle root: $BUNDLE/index.md"
+fi
+
+# --- 2/3. Per-page frontmatter + type vocabulary ---
+while IFS= read -r -d '' page; do
+    PAGE_COUNT=$((PAGE_COUNT + 1))
+    rel="${page#"$BUNDLE/"}"
+
+    # A page is a "concept" only if its frontmatter declares a type.
+    type_val="$(get_yaml_field "$page" "type")"
+    [[ -z "$type_val" ]] && continue
+    CONCEPT_COUNT=$((CONCEPT_COUNT + 1))
+
+    for key in title description resource; do
+        if [[ -z "$(get_yaml_field "$page" "$key")" ]]; then
+            add_error "$rel: concept missing required frontmatter field '$key'"
+        fi
+    done
+
+    if ! is_known_type "$type_val"; then
+        add_error "$rel: unknown concept type '$type_val' (frozen vocab: $OKF_TYPES)"
+    fi
+done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z)
+
+# --- 4. Cross-link resolution ---
+# Scan every markdown page for relative links of the form ](target.md[#frag]).
+# Resolve targets relative to the linking file's directory; flag dangles.
+# Use a temp file (outside the bundle) because the scan runs in a pipeline
+# subshell where add_error would not persist.
+DANGLE_FILE="$(mktemp)"
+trap 'rm -f "$DANGLE_FILE"' EXIT
+while IFS= read -r -d '' page; do
+    pdir="$(dirname "$page")"
+    prel="${page#"$BUNDLE/"}"
+    # Extract link targets: text inside ]( ... ) up to a space or closing paren.
+    grep -oE '\]\([^) ]+\)' "$page" 2>/dev/null | sed -E 's/^\]\(//; s/\)$//' | while IFS= read -r target; do
+        [[ -z "$target" ]] && continue
+        # Skip external schemes and pure anchors.
+        case "$target" in
+            http://*|https://*|mailto:*|\#*) continue;;
+        esac
+        # Strip any #anchor and ?query.
+        target="${target%%#*}"
+        target="${target%%\?*}"
+        [[ -z "$target" ]] && continue
+        # Only resolve intra-bundle markdown/asset links (relative paths).
+        case "$target" in
+            /*) continue;;  # absolute path — out of scope for bundle integrity
+        esac
+        resolved="$pdir/$target"
+        if [[ ! -e "$resolved" ]]; then
+            printf '%s\t%s\n' "$prel" "$target"
+        fi
+    done || true   # inner pipeline returns non-zero at EOF; don't trip set -e
+done < <(find "$BUNDLE" -type f -name '*.md' -print0 | sort -z) >>"$DANGLE_FILE"
+
+if [[ -s "$DANGLE_FILE" ]]; then
+    while IFS=$'\t' read -r prel target; do
+        add_error "$prel: dangling cross-link → '$target'"
+    done < "$DANGLE_FILE"
+fi
+
+# --- 5. path→concept index completeness (optional) ---
+if [[ -n "$PATH_INDEX" ]]; then
+    if [[ ! -f "$PATH_INDEX" ]]; then
+        add_error "path-index not found: $PATH_INDEX"
+    else
+        # The index maps source path → array of concept page(s), bundle-relative:
+        #   { "src/auth/login.go": ["systems/auth.md"], ... }
+        # Validate the array VALUES (the pages) only. Keys are source paths and may
+        # themselves end in .md (e.g. grounding to docs/INVARIANTS.md) — those are
+        # not bundle pages, so we extract strings *inside* the [ ... ] value arrays
+        # and ignore keys entirely. Each page must exist in the bundle.
+        while IFS= read -r ref; do
+            [[ -z "$ref" ]] && continue
+            if [[ ! -f "$BUNDLE/$ref" ]]; then
+                add_error "path-index references missing concept page: $ref"
+            fi
+        done < <(grep -oE '\[[^]]*\]' "$PATH_INDEX" 2>/dev/null \
+                   | grep -oE '"[^"]+\.md"' | tr -d '"' | sort -u)
+    fi
+fi
+
+# --- Report ---
+if [[ $JSON -eq 1 ]]; then
+    valid=true
+    [[ ${#ERRORS[@]} -eq 0 ]] || valid=false
+    printf '{"valid":%s,"bundle":"%s","pages":%d,"concepts":%d,"errors":[' \
+        "$valid" "$(json_escape "$BUNDLE")" "$PAGE_COUNT" "$CONCEPT_COUNT"
+    if [[ ${#ERRORS[@]} -gt 0 ]]; then
+        for i in "${!ERRORS[@]}"; do
+            [[ $i -gt 0 ]] && printf ','
+            printf '"%s"' "$(json_escape "${ERRORS[$i]}")"
+        done
+    fi
+    printf ']}\n'
+else
+    if [[ ${#ERRORS[@]} -gt 0 ]]; then
+        echo "OKF bundle INVALID: $BUNDLE ($PAGE_COUNT pages, $CONCEPT_COUNT concepts)" >&2
+        for e in "${ERRORS[@]}"; do
+            echo "  - $e" >&2
+        done
+    else
+        echo "OKF bundle valid: $BUNDLE ($PAGE_COUNT pages, $CONCEPT_COUNT concepts)"
+    fi
+fi
+
+[[ ${#ERRORS[@]} -eq 0 ]] || exit 1
+exit 0

package/skills/init/SKILL.md

@@ -199,6 +199,23 @@ Check for arguments:
 
 > `/draft:init` is the **single entry point** for building context — there is no separate `index` command. Init is scope-aware (root vs sub-module); see **Scope Detection** below.
 
+### Output Mode (`DRAFT_INIT_MODE`)
+
+Init has two output modes. The default is **tier-gated (`auto`)** — resolved from the codebase tier computed in Step 1.4.5 — and the `DRAFT_INIT_MODE` environment variable overrides it:
+
+```bash
+DRAFT_INIT_MODE="${DRAFT_INIT_MODE:-auto}"
+# auto  → resolved AFTER tier is known (Step 1.4.5):
+#           tier 1–2 (micro/small)     → monolith
+#           tier 3–5 (medium/large/XL) → okf
+# monolith / okf → explicit override; honored as-is.
+```
+
+- **`monolith`** — the standard path documented in this skill: a single `architecture.md` (10-section graph-primary) + derived `.ai-context.md` / `.ai-profile.md`. The default for **small repos (tier 1–2)**, where one linear document beats a taxonomy with little to navigate. Also the A/B baseline and the over-fetch fallback.
+- **`okf`** — emit an OKF-conformant concept taxonomy bundle (`draft/wiki/`) with `.ai-context.md` as the index root and `architecture.md` demoted to a generated rendered view. The default for **tier 3+ repos**, where navigation + maintainability pay off. When active, follow `references/okf-emitter.md` for the decomposition + serialization + validation stage; all shared phases (5-phase analysis, graph snapshot, `.state/` hashing, scope detection, atomic staging) are reused unchanged.
+
+The tier-gated default rests on **maintainability/readability** (one navigable concept per file, cleaner PRs, a generated `architecture.md` preserved for linear onboarding) — not on the A/B benchmark, which was accuracy-parity (`docs/audit/okf-benchmark.md`). `monolith` is **retained, not retired**: it is the tier-1/2 default, the A/B baseline, and the fallback. If `DRAFT_INIT_MODE` is unset, do not commit to a mode until **Step 1.4.5** has computed the tier.
+
 ### Route Explicit Modes Before Initialization
 
 If the user explicitly invoked a specialist mode, route directly:
@@ -318,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
@@ -562,6 +583,8 @@ Apply tier table:
 
 Hold tier in memory. This governs: architecture.md length minimum, .ai-context.md budget, and module deep-dive depth.
 
+**Resolve the output mode now (if `auto`).** If `DRAFT_INIT_MODE` is unset/`auto`, finalize it from the tier just computed: **tier 1–2 → `monolith`**, **tier 3–5 → `okf`** (see **Output Mode** in Pre-Check). An explicit `DRAFT_INIT_MODE=monolith|okf` always wins and skips this resolution. Announce the resolved mode, e.g. `Tier 4 (large) → okf mode (wiki taxonomy bundle).` If `okf`, switch to `references/okf-emitter.md` for the decomposition + serialization + render-views + validate stage from here on; all the shared analysis above is reused unchanged.
+
 **Step 1.4.6 — Build Module Priority List:**
 From `"$DRAFT_TOOLS/hotspot-rank.sh" --repo .`: count hotspot symbols per module.
 From `$ARCH | jq '.packages[]'`: read `fan_in` per module.

package/skills/init/references/okf-emitter.md

@@ -0,0 +1,223 @@
+## Init — OKF Taxonomy Emitter (DRAFT_INIT_MODE=okf)
+
+> Progressive-disclosure reference for `/draft:init`. Covers the OKF emitter:
+> type vocabulary, frontmatter contract, generation pipeline, render views,
+> incremental refresh, and the `okf-validate.sh` gate. Authoritative HLD:
+> `hld-draft-init-okf-taxonomy.md` at the repo root.
+
+This is the `/draft:init` output mode for **tier 3+ repos**, where it is the
+**tier-gated default** (`DRAFT_INIT_MODE` unset → tier 1–2 `monolith`, tier 3–5
+`okf`; an explicit `DRAFT_INIT_MODE=monolith|okf` overrides). `monolith` is
+retained — the tier-1/2 default, the A/B baseline, and the over-fetch fallback.
+The default rests on maintainability/readability, not the benchmark (parity).
+
+```bash
+# Mode gate — default is tier-gated 'auto', finalized after Step 1.4.5 (tier):
+DRAFT_INIT_MODE="${DRAFT_INIT_MODE:-auto}"
+case "$DRAFT_INIT_MODE" in
+  monolith|okf) : ;;             # explicit override — honored as-is
+  auto) : ;;                     # resolve from tier: 1–2 → monolith, 3–5 → okf
+  *) echo "Unknown DRAFT_INIT_MODE='$DRAFT_INIT_MODE' (monolith|okf|auto); using auto" >&2
+     DRAFT_INIT_MODE=auto ;;
+esac
+```
+
+Everything else in `/draft:init` (5-phase analysis, graph snapshot, `.state/`
+hashing, scope detection, atomic staging) is **reused unchanged**. This mode adds
+a decomposition + serialization stage. It introduces **no new LLM analysis
+engine** and exactly **one** new deterministic helper, `okf-validate.sh`.
+
+## Target layout
+
+`okf` mode changes **only** the `architecture.md` / `.ai-context.md` packaging
+and adds `wiki/`. **Every other standard `/draft:init` file is still produced**
+— `product.md`, `tech-stack.md`, `workflow.md`, `guardrails.md`, `index.md`,
+`.ai-profile.md`, `tracks/` + `tracks.md`, `.state/`, `graph/` — exactly as in
+`monolith` mode. Do **not** skip them: emitting only the bundle is a regression.
+
+```
+draft/
+├── .ai-context.md         # INDEX ROOT: synopsis (150–250 lines) + Concept Map
+├── architecture.md        # RENDERED VIEW (generated from bundle; not source of truth)
+├── .ai-profile.md         # always-injected profile (derived from .ai-context.md)  [SAME AS MONOLITH]
+├── product.md             # [SAME AS MONOLITH]
+├── tech-stack.md          # [SAME AS MONOLITH]
+├── workflow.md            # [SAME AS MONOLITH]
+├── guardrails.md          # [SAME AS MONOLITH]
+├── index.md               # docs index — lists prose files + wiki/  [SAME AS MONOLITH, +wiki link]
+├── tracks.md  +  tracks/  # [SAME AS MONOLITH]
+├── wiki/                   # OKF bundle (source of truth) — okf-mode ONLY
+│   ├── index.md            # bundle root + Concept Map
+│   ├── overview/{index,architecture,getting-started,glossary}.md
+│   ├── systems/{index,<subsystem>}.md
+│   ├── features/{index,<feature>}.md
+│   ├── reference/{index,<ref>}.md      # config, deps, data models, ADRs, runbooks
+│   ├── entrypoints/<app>.md
+│   ├── web/index.html      # optional offline viewer (okf-render-views.sh --web)
+│   └── log.md              # chronological change history (from .state run memory)
+├── graph/schema.yaml       # [SAME AS MONOLITH] engine gate marker
+└── .state/
+    ├── hashes.json             # file → content hash  [SAME AS MONOLITH]
+    ├── path-to-concept.json    # NEW: source path → concept page(s) it grounds
+    └── signals.json            # [SAME AS MONOLITH]
+```
+
+The standard project files come from the same generators as `monolith` mode
+(intake questions → `product.md`; tech detection → `tech-stack.md`; `/draft:learn`
+→ `guardrails.md`; templates → `workflow.md`, `index.md`, `tracks.md`,
+`.ai-profile.md`). The OKF emitter only *replaces the architecture packaging*; it
+never owns or removes the rest of the context directory.
+
+Templates for each bundle page live in `core/templates/okf/` (`index.md`,
+`concept.md`, `section-index.md`, `ai-context-index.md`).
+
+## Frozen `type` vocabulary
+
+Every concept carries a `type` from this frozen set (changing it churns every
+file; versioned via `index.md` frontmatter `okf_types_version`):
+
+| type | Maps to | Home |
+|------|---------|------|
+| `Subsystem` | major graph cluster / package boundary | `systems/` |
+| `Module` | single package/dir, cohesive responsibility | `systems/` |
+| `Feature` | user-facing capability spanning modules | `features/` |
+| `Entrypoint` | binary / main / CLI / handler root | `entrypoints/` |
+| `API` | public interface, route group, RPC surface | `reference/` |
+| `DataModel` | schema, table, core struct/type | `reference/` |
+| `Dependency` | notable external dep + how it's used | `reference/` |
+| `ADR` | architecture decision record | `reference/` |
+| `Runbook` | operational procedure | `reference/` |
+
+`okf-validate.sh` enforces this set as ground truth — an out-of-vocab `type`
+fails the build.
+
+## Frontmatter contract
+
+Per concept page (see `core/templates/okf/concept.md`). Required OKF keys:
+`type`, `title`, `description`, `resource`. **`description` is the load-bearing
+routing key** — write it as a routing decision ("should the agent open this for
+the task at hand?"), never a summary. Draft extensions are namespaced `x-` and
+ignored by generic OKF consumers: `x-grounded-paths`, `x-hotspot-score`,
+`x-callers`.
+
+## Concept granularity (resolves open decision 1)
+
+Derive concepts from the graph, not by hand:
+
+- A **Subsystem** = a graph cluster (package/dir boundary) with `fan_in ≥ 2` from
+  other clusters, OR a top-ranked module from `hotspot-rank.sh`.
+- A **Module** = a cohesive package/dir below a subsystem that is *not* itself a
+  cluster boundary but has its own hotspot or public surface.
+- A **Feature** = a capability the graph shows spanning ≥2 modules (shared
+  callers / a route group touching multiple packages).
+- Default cap: one page per package boundary; do not split a package into
+  multiple concept pages unless it has >1 distinct public surface. This keeps
+  page count ≈ module count and navigation depth shallow.
+
+## Generation pipeline (M3)
+
+```
+1. Survey        → existing /draft:init 5-phase + graph snapshot (graph-snapshot.sh)
+2. Plan          → derive the concept list (above) from graph clusters +
+                   entrypoints + features. Topo-sort by dependency so pages that
+                   others link to (overview, core subsystems) generate FIRST —
+                   forward cross-links resolve.
+3. Generate      → per concept, pull grounding from the graph and write the page:
+                     x-callers        ← graph-callers.sh --symbol <c>
+                     x-grounded-paths  ← graph-impact.sh  --symbol <c>  (blast radius)
+                     x-hotspot-score   ← hotspot-rank.sh
+                     overview diagrams ← mermaid-from-graph.sh
+                   Record each source path → page in .state/path-to-concept.json.
+4. Render views  → ai-context.md (synopsis + Concept Map), architecture.md
+                   (concatenated view), wiki/log.md  (see M4).
+5. Validate      → okf-validate.sh draft/wiki \
+                     --path-index draft/.state/path-to-concept.json
+                   FAIL the build (do not atomic-rename) on any dangle, missing
+                   field, bad type, or path-index gap.
+6. Emit          → mv draft.tmp/ draft/ ; update .state/.
+```
+
+Page bodies are LLM-narrated for readability **but** the graph-derived
+frontmatter and the `Blast radius`/`Used by` sections are deterministic. To keep
+incremental carry-forward byte-identical (open decision 2), cache the narrated
+prose keyed by the source hash of `x-grounded-paths` — unchanged sources reuse
+the cached narration verbatim.
+
+## Render views (M4)
+
+Both are produced by the deterministic helper `okf-render-views.sh` (no LLM) —
+regenerated on every init/refresh so they never drift from the bundle:
+
+```bash
+okf-render-views.sh draft/wiki \
+  --arch-out draft/architecture.md \
+  --concept-map-into draft/wiki/index.md \
+  --concept-map-into draft/.ai-context.md \
+  --web draft/wiki/web/index.html
+```
+
+- `--arch-out` renders the linear `architecture.md` (banner + TOC + every concept
+  page in canonical section order, frontmatter stripped, Mermaid preserved).
+- `--concept-map-into` rebuilds the routing table between the
+  `<!-- CONCEPT-MAP:START -->` / `:END` markers from each concept's `title` +
+  `type` + `description` (section `index.md` pages excluded).
+- `--web` writes a **self-contained offline HTML viewer** (single file: all pages
+  inlined as JSON + a built-in markdown renderer + sidebar nav + search). Works by
+  double-click — no server, no internet, no CDN. Optional, human-facing; regenerate
+  on refresh like the other views. (Mermaid blocks render as labeled source since a
+  graphical engine can't be inlined offline.)
+
+All views write into `draft/` (the OKF emitter never creates a separate output
+dir): `draft/wiki/` is the bundle, `draft/architecture.md` + `draft/.ai-context.md`
+are the rendered views, `draft/wiki/web/index.html` is the optional viewer.
+
+The two views:
+
+- **`ai-context.md`** (index root) — from `core/templates/okf/ai-context-index.md`:
+  the Synopsis preserves the prior `.ai-context.md` content shape (so existing
+  downstream consumers keep working); the Concept Map is built from each
+  concept's `description`. Broad tasks terminate here.
+- **`architecture.md`** (rendered view) — TOC + per-concept section concat +
+  Mermaid, in topo order. Demoted, not deleted: the brownfield Context Quality
+  Audit and any command grepping `architecture.md` keep working (§9 of the HLD).
+- **`wiki/log.md`** — appended from `.state/` run memory.
+
+The `<!-- CONCEPT-MAP:START -->` / `:END` markers in `wiki/index.md` and the
+section `index.md` tables are the injection slots for the routing tables.
+
+## Incremental refresh at concept granularity (M5)
+
+`/draft:init refresh` under `okf` mode:
+
+```
+1. Diff hashes.json vs working tree     → changed source paths
+2. path-to-concept.json                 → affected concept pages
+3. Regenerate ONLY affected concepts; carry the rest verbatim (cached narration)
+4. Re-render ai-context.md / architecture.md / log.md (cheap; always regenerated)
+5. Re-validate: okf-validate.sh on the bundle + path-index (cross-links touching
+   changed concepts must still resolve)
+6. Append log.md; update hashes.json + path-to-concept.json
+```
+
+A 1-file change regenerates only the concept(s) that file grounds. Unchanged
+concepts are byte-identical across runs.
+
+## Backward compatibility (§9)
+
+- `architecture.md` is retained as a rendered view (brownfield audit + grep keep
+  working).
+- `ai-context.md`'s Synopsis preserves the prior content shape; the Concept Map
+  is additive.
+- `/draft:review` and downstream command contracts are unchanged — they consume
+  `architecture.md` / `ai-context.md`, both of which still exist.
+
+## Default policy & retirement of `monolith`
+
+`okf` is the **tier-gated default** (tier 3+); `monolith` is the tier-1/2 default
+and remains in place as the A/B baseline + over-fetch fallback. Full retirement of
+`monolith` is deferred until **both**: (1) the large-monolith A/B run shows `okf` ≥
+baseline on tokens at parity accuracy (the regime the §12 benchmark flagged), and
+(2) a human-onboarding eval confirms the wiki + generated `architecture.md` covers
+linear onboarding. Note: retiring `monolith` would not remove `architecture.md` —
+it is generated from the bundle regardless — so there is no readability gain from
+deletion, only lost optionality.

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

@@ -1,91 +0,0 @@
-# Draft - Context-Driven Development
-
-You are operating with the Draft methodology for Context-Driven Development.
-
-**Measure twice, code once.**
-
-## Core Workflow
-
-**Context -> Spec & Plan -> Implement**
-
-Every feature follows this lifecycle:
-1. **Setup** - Initialize project context (once per project)
-2. **New Track** - Create specification and plan
-3. **Implement** - Execute tasks with TDD workflow
-4. **Verify** - Confirm acceptance criteria met
-
-## Project Context Files
-
-When `draft/` exists in the project, always consider:
-- `draft/.ai-context.md` - Source of truth for AI agents (dense codebase understanding)
-- `draft/architecture.md` - Human-readable engineering guide (derived from .ai-context.md)
-- `draft/product.md` - Product vision and goals
-- `draft/tech-stack.md` - Technical constraints
-- `draft/workflow.md` - TDD and commit preferences
-- `draft/tracks.md` - Active work items
-
-## Available Commands
-
-| Command | Purpose |
-|---------|---------|
-| `draft` | Show overview and available commands |
-| `draft init` | Initialize project (run once) |
-| `draft index [--init-missing]` | Aggregate monorepo service contexts |
-| `draft new-track <description>` | Create feature/bug track |
-| `draft decompose` | Module decomposition with dependency mapping |
-| `draft implement` | Execute tasks from plan |
-| `draft coverage` | Code coverage report (target 95%+) |
-| `draft bughunt [--track <id>]` | Systematic bug discovery |
-| `draft review [--track <id>]` | Three-stage code review |
-| `draft deep-review [module]` | Exhaustive production-grade module audit |
-| `draft learn [promote\|migrate]` | Discover coding patterns, update guardrails |
-| `draft adr [title]` | Architecture Decision Records |
-| `draft status` | Show progress overview |
-| `draft revert` | Git-aware rollback |
-| `draft change <description>` | Handle mid-track requirement changes |
-| `draft jira-preview [track-id]` | Generate jira-export.md for review |
-| `draft jira-create [track-id]` | Create Jira issues from export via MCP |
-
-## Intent Mapping
-
-Recognize these natural language patterns:
-
-| User Says | Action |
-|-----------|--------|
-| "set up the project" | Run init |
-| "index services", "aggregate context" | Run index |
-| "new feature", "add X" | Create new track |
-| "break into modules", "decompose" | Run decompose |
-| "start implementing" | Execute implement |
-| "check coverage", "test coverage" | Run coverage |
-| "hunt bugs", "find bugs" | Run bug hunt |
-| "review code", "review track", "check quality" | Run review |
-| "deep review", "production audit", "module audit" | Run deep-review |
-| "learn patterns", "update guardrails", "discover conventions" | Run learn |
-| "what's the status" | Show status |
-| "undo", "revert" | Run revert |
-| "requirements changed", "scope changed", "update the spec" | Run change |
-| "preview jira", "export to jira" | Run jira-preview |
-| "create jira", "push to jira" | Run jira-create |
-| "document decision", "create ADR" | Create architecture decision record |
-| "help", "what commands" | Show draft overview |
-| "the plan" | Read active track's plan.md |
-| "the spec" | Read active track's spec.md |
-
-## Tracks
-
-A **track** is a high-level unit of work (feature, bug fix, refactor). Each track contains:
-- `spec.md` - Requirements and acceptance criteria
-- `plan.md` - Phased task breakdown
-- `metadata.json` - Status and timestamps
-
-Located at: `draft/tracks/<track-id>/`
-
-## Status Markers
-
-Recognize and use these throughout plan.md:
-- `[ ]` - Pending
-- `[~]` - In Progress
-- `[x]` - Completed
-- `[!]` - Blocked
-

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

@@ -1,91 +0,0 @@
-# Draft - Context-Driven Development
-
-You are operating with the Draft methodology for Context-Driven Development.
-
-**Measure twice, code once.**
-
-## Core Workflow
-
-**Context -> Spec & Plan -> Implement**
-
-Every feature follows this lifecycle:
-1. **Setup** - Initialize project context (once per project)
-2. **New Track** - Create specification and plan
-3. **Implement** - Execute tasks with TDD workflow
-4. **Verify** - Confirm acceptance criteria met
-
-## Project Context Files
-
-When `draft/` exists in the project, always consider:
-- `draft/.ai-context.md` - Source of truth for AI agents (dense codebase understanding)
-- `draft/architecture.md` - Human-readable engineering guide (derived from .ai-context.md)
-- `draft/product.md` - Product vision and goals
-- `draft/tech-stack.md` - Technical constraints
-- `draft/workflow.md` - TDD and commit preferences
-- `draft/tracks.md` - Active work items
-
-## Available Commands
-
-| Command | Purpose |
-|---------|---------|
-| `draft` | Show overview and available commands |
-| `draft init` | Initialize project (run once) |
-| `draft index [--init-missing]` | Aggregate monorepo service contexts |
-| `draft new-track <description>` | Create feature/bug track |
-| `draft decompose` | Module decomposition with dependency mapping |
-| `draft implement` | Execute tasks from plan |
-| `draft coverage` | Code coverage report (target 95%+) |
-| `draft bughunt [--track <id>]` | Systematic bug discovery |
-| `draft review [--track <id>]` | Three-stage code review |
-| `draft deep-review [module]` | Exhaustive production-grade module audit |
-| `draft learn [promote\|migrate]` | Discover coding patterns, update guardrails |
-| `draft adr [title]` | Architecture Decision Records |
-| `draft status` | Show progress overview |
-| `draft revert` | Git-aware rollback |
-| `draft change <description>` | Handle mid-track requirement changes |
-| `draft jira-preview [track-id]` | Generate jira-export.md for review |
-| `draft jira-create [track-id]` | Create Jira issues from export via MCP |
-
-## Intent Mapping
-
-Recognize these natural language patterns:
-
-| User Says | Action |
-|-----------|--------|
-| "set up the project" | Run init |
-| "index services", "aggregate context" | Run index |
-| "new feature", "add X" | Create new track |
-| "break into modules", "decompose" | Run decompose |
-| "start implementing" | Execute implement |
-| "check coverage", "test coverage" | Run coverage |
-| "hunt bugs", "find bugs" | Run bug hunt |
-| "review code", "review track", "check quality" | Run review |
-| "deep review", "production audit", "module audit" | Run deep-review |
-| "learn patterns", "update guardrails", "discover conventions" | Run learn |
-| "what's the status" | Show status |
-| "undo", "revert" | Run revert |
-| "requirements changed", "scope changed", "update the spec" | Run change |
-| "preview jira", "export to jira" | Run jira-preview |
-| "create jira", "push to jira" | Run jira-create |
-| "document decision", "create ADR" | Create architecture decision record |
-| "help", "what commands" | Show draft overview |
-| "the plan" | Read active track's plan.md |
-| "the spec" | Read active track's spec.md |
-
-## Tracks
-
-A **track** is a high-level unit of work (feature, bug fix, refactor). Each track contains:
-- `spec.md` - Requirements and acceptance criteria
-- `plan.md` - Phased task breakdown
-- `metadata.json` - Status and timestamps
-
-Located at: `draft/tracks/<track-id>/`
-
-## Status Markers
-
-Recognize and use these throughout plan.md:
-- `[ ]` - Pending
-- `[~]` - In Progress
-- `[x]` - Completed
-- `[!]` - Blocked
-