@drafthq/draft 2.8.1 → 3.0.0

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

@@ -0,0 +1,91 @@
+# 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.ww33Ly

@@ -0,0 +1,91 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drafthq/draft",
-  "version": "2.8.1",
+  "version": "3.0.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

@@ -24,7 +24,6 @@ TOOLS_DIR="$ROOT_DIR/scripts/tools"
 SKILL_ORDER=(
     draft
     init
-    index
     graph
     new-track
     decompose
@@ -158,6 +157,10 @@ TOOLS=(
     "manage-symlinks.sh"
     "mermaid-from-graph.sh"
     "graph-snapshot.sh"
+    "graph-init.sh"
+    "okf-emit.sh"
+    "okf-bundle.sh"
+    "okf-check.sh"
     "graph-impact.sh"
     "graph-callers.sh"
     "validate-frontmatter.sh"

package/scripts/tools/graph-init.sh

@@ -0,0 +1,187 @@
+#!/usr/bin/env bash
+# graph-init.sh — scope-aware, root-first knowledge-graph builder for /draft:init.
+#
+# Ensures the whole-repo "code graph knowledge memory" exists at the repository
+# ROOT (the spine — the single structural source of truth), then builds a
+# scope-local snapshot and links a sub-module's graph up to the root.
+#
+# Model:
+#   - ROOT resolution: nearest ancestor ABOVE scope containing draft/ (bounded by
+#     the git toplevel)  →  git toplevel  →  scope itself (no git / module-local).
+#   - The engine is the default capability tier. If the codebase-memory-mcp binary
+#     is missing it is fetched (blocking) unless --no-fetch or DRAFT_MEMORY_DISABLE.
+#   - Root init (scope == root): build the whole-repo snapshot at <root>/draft/graph/.
+#   - Module init (scope != root): unless --module-only, (re)build the root snapshot
+#     first (the spine — index time is accepted, incremental once warm), then build
+#     <scope>/draft/graph/ and write root-link.json pointing up to the root snapshot.
+#
+# The committed snapshot (draft/graph/) is the git-tracked memory; the engine's
+# ~/.cache index is a disposable accelerator and is never committed.
+#
+# Usage: scripts/tools/graph-init.sh [--scope DIR] [--module-only] [--no-fetch] [--json]
+# Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
+set -euo pipefail
+
+TOOLS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=_lib.sh
+source "$TOOLS_DIR/_lib.sh"
+
+SCOPE="."
+MODULE_ONLY=0
+NO_FETCH=0
+EMIT_JSON=0
+
+usage() {
+    cat <<'EOF'
+graph-init.sh — scope-aware, root-first knowledge-graph builder.
+
+Usage:
+  scripts/tools/graph-init.sh [--scope DIR] [--module-only] [--no-fetch] [--json]
+
+Flags:
+  --scope DIR    Directory init was invoked in (default: cwd).
+  --module-only  Do not touch the root; build only the module snapshot and mark
+                 its root link "pending".
+  --no-fetch     Never download the engine; degrade if it is absent (CI/tests).
+  --json         Emit a machine-readable summary instead of a human report.
+  --help         Show this help.
+
+Exit 0 on success, 2 when the graph engine is unavailable (no snapshot built).
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --scope) SCOPE="$2"; shift 2;;
+        --module-only) MODULE_ONLY=1; shift;;
+        --no-fetch) NO_FETCH=1; shift;;
+        --json) EMIT_JSON=1; shift;;
+        --help|-h) usage; exit 0;;
+        *) echo "Unknown flag: $1" >&2; usage >&2; exit 1;;
+    esac
+done
+
+[[ -d "$SCOPE" ]] || { echo "ERROR: --scope '$SCOPE' is not a directory" >&2; exit 1; }
+SCOPE_ABS="$(cd "$SCOPE" && pwd)"
+SELF_REPO="$(cd "$TOOLS_DIR/../.." && pwd)"
+
+# --- Resolve ROOT (bounded by the git toplevel; never escapes the repo) ---
+GIT_TOP="$(git -C "$SCOPE_ABS" rev-parse --show-toplevel 2>/dev/null || true)"
+resolve_root() {
+    if [[ -z "$GIT_TOP" ]]; then printf '%s' "$SCOPE_ABS"; return; fi   # no git → module-local
+    local d="$SCOPE_ABS"
+    while [[ "$d" != "$GIT_TOP" && "$d" != "/" ]]; do
+        d="$(dirname "$d")"
+        if [[ "$d" != "$SCOPE_ABS" && -d "$d/draft" ]]; then printf '%s' "$d"; return; fi
+    done
+    printf '%s' "$GIT_TOP"
+}
+ROOT_ABS="$(resolve_root)"
+IS_ROOT=0
+[[ "$SCOPE_ABS" == "$ROOT_ABS" ]] && IS_ROOT=1
+
+# --- Ensure the engine (the default tier); fetch when missing unless told not to ---
+ensure_engine() {
+    [[ -z "${DRAFT_MEMORY_DISABLE:-}" ]] || return 1
+    find_memory_bin "$SCOPE_ABS" "$SELF_REPO" && return 0
+    [[ "$NO_FETCH" -eq 0 ]] || return 1
+    echo "Graph engine not found — fetching it (one-time download; this may take a while)..." >&2
+    "$SELF_REPO/scripts/fetch-memory-engine.sh" >&2 2>&1 || true
+    find_memory_bin "$SCOPE_ABS" "$SELF_REPO"
+}
+
+engine_unavailable() {
+    if [[ "$EMIT_JSON" -eq 1 ]]; then
+        printf '{"status":"unavailable","root":"%s","scope":"%s","is_root":%s}\n' \
+            "$ROOT_ABS" "$SCOPE_ABS" "$IS_ROOT"
+    else
+        echo "WARNING: knowledge-graph engine (codebase-memory-mcp) is unavailable — no graph built." >&2
+        echo "  The engine is Draft's default capability tier. Install it with:" >&2
+        echo "    scripts/fetch-memory-engine.sh" >&2
+        echo "  or put codebase-memory-mcp on PATH. Set DRAFT_MEMORY_DISABLE=1 to silence this." >&2
+        echo "  Committed draft/graph/ snapshots (if present) still provide structural context." >&2
+    fi
+    exit 2
+}
+
+# Build a committed snapshot for a repo dir; returns graph-snapshot's exit code.
+# Snapshot progress goes to stderr so stdout stays clean for --json consumers.
+build_snapshot() {
+    local rc=0
+    "$TOOLS_DIR/graph-snapshot.sh" --repo "$1" 1>&2 || rc=$?
+    return "$rc"
+}
+
+# Path from <module>/draft/graph back to <root>/draft/graph (module is under root).
+root_link_relpath() {
+    local sub="${SCOPE_ABS#"$ROOT_ABS"/}"
+    local ups=2 seg
+    IFS='/' read -ra seg <<< "$sub"
+    ups=$(( ${#seg[@]} + 2 ))
+    local i out=""
+    for ((i = 0; i < ups; i++)); do out+="../"; done
+    printf '%sdraft/graph' "$out"
+}
+
+write_root_link() {
+    local status="$1"
+    local mod_graph="$SCOPE_ABS/draft/graph"
+    mkdir -p "$mod_graph"
+    local rel root_project="unknown" root_commit ts schema="$ROOT_ABS/draft/graph/schema.yaml"
+    rel="$(root_link_relpath)"
+    if [[ -f "$schema" ]]; then
+        root_project="$(grep -m1 '^project:' "$schema" 2>/dev/null | sed 's/^project:[[:space:]]*//; s/^"//; s/"$//' || true)"
+        [[ -n "$root_project" ]] || root_project="unknown"
+    fi
+    root_commit="$(git -C "$ROOT_ABS" rev-parse --verify --quiet HEAD 2>/dev/null || echo none)"
+    ts="$(date -Iseconds 2>/dev/null || date)"
+    cat > "$mod_graph/root-link.json" <<EOF
+{
+  "root_graph": "$rel",
+  "root_abs": "$ROOT_ABS/draft/graph",
+  "root_project": "${root_project:-unknown}",
+  "root_commit": "$root_commit",
+  "status": "$status",
+  "linked_at": "$ts",
+  "linked_by": "graph-init.sh",
+  "note": "Root is the authoritative whole-repo graph. Follow root_graph for cross-module understanding."
+}
+EOF
+}
+
+ensure_engine || engine_unavailable
+
+ROOT_BUILT=0
+MODULE_BUILT=0
+LINK_STATUS="none"
+
+if [[ "$IS_ROOT" -eq 1 ]]; then
+    build_snapshot "$ROOT_ABS" && ROOT_BUILT=1
+else
+    if [[ "$MODULE_ONLY" -eq 0 ]]; then
+        echo "Sub-module of $ROOT_ABS — ensuring the root code-graph spine first..." >&2
+        build_snapshot "$ROOT_ABS" && ROOT_BUILT=1
+    fi
+    build_snapshot "$SCOPE_ABS" && MODULE_BUILT=1
+    if [[ -f "$ROOT_ABS/draft/graph/schema.yaml" ]]; then
+        LINK_STATUS="linked"
+    else
+        LINK_STATUS="pending"
+    fi
+    write_root_link "$LINK_STATUS"
+fi
+
+if [[ "$EMIT_JSON" -eq 1 ]]; then
+    printf '{"status":"ok","root":"%s","scope":"%s","is_root":%s,"root_built":%s,"module_built":%s,"link_status":"%s"}\n' \
+        "$ROOT_ABS" "$SCOPE_ABS" "$IS_ROOT" "$ROOT_BUILT" "$MODULE_BUILT" "$LINK_STATUS"
+else
+    echo "--- graph-init ---"
+    echo "Root:  $ROOT_ABS$([[ $IS_ROOT -eq 1 ]] && echo '  (this scope is the root)')"
+    [[ "$IS_ROOT" -eq 1 ]] && echo "Built whole-repo spine: $ROOT_ABS/draft/graph/"
+    if [[ "$IS_ROOT" -eq 0 ]]; then
+        [[ "$ROOT_BUILT" -eq 1 ]] && echo "Root spine: refreshed $ROOT_ABS/draft/graph/"
+        echo "Module:    $SCOPE_ABS/draft/graph/"
+        echo "Root link: $LINK_STATUS ($SCOPE_ABS/draft/graph/root-link.json)"
+    fi
+fi
+exit 0

package/scripts/tools/graph-snapshot.sh

@@ -13,6 +13,7 @@
 #   hotspots.jsonl       fan-in-ranked symbols, one JSON object per line
 #   module-deps.mermaid  co-change coupling diagram
 #   proto-map.mermaid    detected-route diagram
+#   okf/                 Open Knowledge Format bundle (portable markdown mirror)
 #
 # Usage: scripts/tools/graph-snapshot.sh [--repo DIR] [--out DIR]
 # Exit codes: 0 OK, 1 invocation error, 2 graph engine unavailable.
@@ -76,7 +77,10 @@ echo "$ARCH" | jq '.' > "$OUT/architecture.json"
 "$TOOLS_DIR/mermaid-from-graph.sh" --repo "$REPO_ABS" --diagram module-deps > "$OUT/module-deps.mermaid" 2>/dev/null || true
 "$TOOLS_DIR/mermaid-from-graph.sh" --repo "$REPO_ABS" --diagram proto-map  > "$OUT/proto-map.mermaid"  2>/dev/null || true
 
-# 4. schema.yaml — metadata + gate for skill graph use
+# 4. OKF bundle (best-effort) — portable Open Knowledge Format mirror of the graph.
+"$TOOLS_DIR/okf-emit.sh" --repo "$REPO_ABS" --snapshot "$OUT" --out "$OUT/okf" >/dev/null 2>&1 || true
+
+# 5. schema.yaml — metadata + gate for skill graph use
 NODES="$(echo "$ARCH" | jq -r '.total_nodes // 0')"
 EDGES="$(echo "$ARCH" | jq -r '.total_edges // 0')"
 HOTN="$(wc -l < "$OUT/hotspots.jsonl" | tr -d ' ')"
@@ -96,6 +100,7 @@ artifacts:
   - hotspots.jsonl
   - module-deps.mermaid
   - proto-map.mermaid
+  - okf/
 EOF
 
 echo "Snapshot written to $OUT (nodes=$NODES edges=$EDGES hotspots=$HOTN)"

package/scripts/tools/okf-bundle.sh

@@ -0,0 +1,141 @@
+#!/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