Changelog — Draft

v4.0.0 2026-09-03 Latest Graph Security

Changed

Graph wrappers fail loud on shapeless JSON. Queries require a .rows array; impact, callers, and diagram tools require their tool-shaped object. A bare {} is now unavailable with a non-zero exit, not a measured empty result. A failed snapshot refresh no longer rewrites schema.yaml.
draft install help matches host default scopes. --global for Claude Code and Cursor; --project for Codex and opencode. Missing-binary detection treats Windows status 127 as absent.
Docs, website, and book aligned. Author Mayur Pise. 53 helpers, ~25,300 Copilot lines, 66 core files, 7 tech-debt dimensions, 81 test suites, REV 4.0.0.

Fixed

Engine fetch pins curl redirects to HTTPS. A compromised redirect cannot downgrade the download to HTTP.
OKF viewer XSS. Table cells are escaped; javascript: markdown links are dropped. Catalog concept IDs and path-index values cannot escape the bundle.
Hygiene and packaging. Marker scans parse paths that contain :; package.sh refuses --out / and versions with ..; chapter pages are written atomically; architecture render no longer swallows link-fix failures.

v3.7.2 2026-08-19 Graph

Fixed

Hotspot ranking reported unmeasured complexity as zero. When the property query failed, every symbol came back with complexity and cognitive scores of 0, those zeros were summed into the ranking score, and the result still claimed the graph had answered — a fan-in-only ranking was indistinguishable from a fully measured one. The run now records whether enrichment loaded, and omits what it could not measure.
Diagram generation could not tell a broken engine from an empty graph. Both rendered "graph not built", so a repo with genuinely no cross-file imports looked like a failed index. The two now render distinctly.

v3.7.1 2026-08-19 Graph

Fixed

Cycle detection reported a clean result from a query that never ran. A failed graph query was swallowed and the tool carried on, emitting source:"memory-graph" with zero cycles — the one failure mode a caller cannot detect. A failed query now reports unavailable, as every sibling tool already did.
Two-node cycle detection had never worked. The query compared one property against another, which the graph engine's parser rejects, so it failed on every call — hidden by the bug above. Mutual recursion went undetected while the tool reported success. The comparison is gone and the de-duplication it was doing now happens after the query.

v3.7.0 2026-08-19 Review Security CI Releases

Added

/draft:review runs with zero setup. A missing draft/ directory is now a supported mode rather than an error. The review resolves scope from git, runs automated validation plus the four code-quality dimensions against the plugin guardrails, renders the report in the conversation without writing into your repo, and closes by naming the specific structural checks — blast radius, downstream callers, dependency cycles, module boundaries — that /draft:init would have added. Indexing is now the upgrade, not the entry fee.
Continuous integration. Test suites, lint, an integrations-freshness check, and — new — the install path itself now run on every push and pull request.
check-repo-size.sh fails the build when the tree at HEAD exceeds a size cap. This is the test that would have caught the v2.8.3 install hang, where ~670 MB of audio in HEAD stalled the first install step with no error message.
install-smoke-test.sh reproduces a new user's first install on a throwaway shallow clone: manifest discovery, skill frontmatter validation, and a --dry-run writer pass per host against an empty HOME.
A GitHub Release per tag. Every vX.Y.Z tag now publishes a Release with notes extracted from the changelog, so the release history matches the changelog automatically.
DRAFT_STRICT_VERIFY=1 makes an unverifiable graph-engine download fatal instead of a warning. The engine's trust story — what is and is not guaranteed, and the contingency if the upstream project stalls — is now documented explicitly.
Efficacy benchmark harness. A published protocol plus tooling to measure whether /draft:review catches defects that reached production: pre-merge worktree preparation that refuses any corpus entry whose fix is reachable from the reviewed tree, review-before-fix grading, and catch-rate / precision / graph-delta reporting. Corpus collection is next.

Security

The graph query hatch enforced read-only on one path of two. graph-query.sh scanned --cypher for write verbs but not --tool query_graph, which takes raw Cypher in its payload — so a delete reached the engine unchecked and could wipe the index. One guard now covers both entry points, and any tool payload carrying a query field.
Any repository could hijack which scripts Draft executes. resolve-tools.sh returned $PWD/scripts/tools ahead of the install marker and the plugin registry, so a repo shipping that path captured execution — and reviewing unfamiliar code is a primary use case. The installed plugin now wins; the working directory is a last resort gated on Draft's own manifest. Work on Draft itself with DRAFT_PLUGIN_ROOT="$PWD".
Atomic rewrites widened file permissions. Writing a temp file and renaming it over the target discards the target's mode, so a deliberately 0600 ~/.claude/settings.json came back 0644, and normalised documents came back owner-only. Every rewrite now carries the destination's mode across.

Changed

The lint gate blocks. markdownlint ran advisory against a backlog too large to enforce against; the backlog is cleared — 1,691 violations to zero — so anything it reports now came from the change under review. CI installs a pinned, checksum-verified shellcheck instead of apt-installing it, after the package step stalled twice and left both blocking checks skipped.
The funnel is inverted. Documentation now orders the flow review → init → review, and the README leads with five commands instead of thirty-three; the full reference moved to a dedicated page.
Marketing copy replaced with output. The "Maturity Level 4/5 / on par with Staff Engineer practices at FAANG" framing is gone, replaced by three real defects /draft:review found in Draft's own codebase and the graph query that scopes them.

v3.6.0 2026-07-15 Review Hardening

Fixed

Full-codebase review release. A ten-angle review with per-finding adversarial verification produced 37 confirmed findings, all fixed.
Validators no longer crash on clean input. check-track-hygiene.sh (zero TBD markers) and verify-doc-anchors.sh aborted under set -euo pipefail with no output; both now pass clean tracks.
Validators no longer silently pass bad input. okf-validate.sh skipped pretty-printed path-index arrays; verify-citations.sh truncated file:LO-HI ranges to LO, so drifted range ends were never checked.
Graph tooling hardening. gq_escape now escapes backslashes (Cypher string-literal breakout); graph-impact.sh reports engine failures as source:"unavailable" instead of fabricating empty results.

v3.5.0 – v3.5.3 2026-06-20 → 2026-06-25 Wiki Init

Added

Deterministic wiki completeness gates (v3.5.0) — okf-plan-concepts.sh and okf-coverage-check.sh enforce that a wiki-mode bundle covers the full module surface before an init or refresh is accepted.

Fixed

Init indexing is memory-bounded (v3.5.1) — the engine index run is wrapped in a cgroup scope capped at 25% of system RAM, so indexing a large repo can no longer exhaust the machine.
Wiki completeness is enforced (v3.5.2) — /draft:init now requires a concept page for every module, rejects empty or shallow pages, and fails on broken index links.
Bundle conforms to the OKF v0.1 spec (v3.5.3) — the emitted draft/wiki/ bundle carries the spec-required index frontmatter and generates coverage.md, so downstream consumers can validate its shape.

Changed

User-facing prose says "wiki" instead of "OKF" throughout the docs.

v3.4.0 2026-06-20 Retrieval Wiki

Added

Tree-search retrieval over the wiki bundle (PageIndex-style). Agents locate context by navigating the Concept Map tree — reading each node's routing description and descending only matching subtrees — instead of loading sections by a static heuristic. No embeddings, no chunking: relevance is decided by reasoning over the tree, with a budget of roughly five pages and two hops. Wiki-mode projects route to tree-search; monolith mode keeps static section-scoring.

Changed

Website, book, and blog refresh: new "Drafting Table" hero identity, refreshed social and meta copy, professionalized footer, and two new blog posts on vectorless retrieval.

v3.3.1 2026-06-19 Init Docs

Fixed

/draft:init refresh never regenerated the wiki bundle. Refresh Mode described only the monolith path, so running refresh on a wiki-initialized repo treated the generated architecture.md as the source of truth and never re-narrated the concept taxonomy. Refresh now detects wiki mode and regenerates only the concepts grounded in changed files, carrying the rest forward from cache.

Changed

Documentation, website, and book synced to v3.3.0; stale counts corrected across the docs.

v3.3.0 2026-06-19 Init OKF Cursor

Added

/draft:init OKF taxonomy emitter (tier-gated default) — an init output mode that replaces the monolithic architecture.md with an OKF v0.1 concept bundle under draft/wiki/ (one concept per file, cross-links form the graph), repurposes .ai-context.md as the index root (Synopsis + Concept Map), and demotes architecture.md to a generated rendered view. DRAFT_INIT_MODE defaults to tier-gated auto (tiers 1–2 → monolith, tiers 3–5 → okf); an explicit monolith/okf overrides. All other draft/ files are produced in both modes — only the architecture packaging differs.
scripts/tools/okf-validate.sh — the one new deterministic helper: fails the build on dangling cross-links, missing/invalid frontmatter, out-of-vocab concept type, or an incomplete path-to-concept.json index. Verified against the call graph (ground truth), not heuristics.
scripts/tools/okf-render-views.sh — deterministic renderer for the demoted views: architecture.md becomes a generated linear concat of the bundle (canonical section order, banner + TOC), and the Concept Map routing table is injected into the index roots. --web additionally emits a self-contained offline HTML viewer (single file, inlined pages, built-in markdown renderer, sidebar + search; no server/CDN).
Cursor-native plugin manifest — .cursor-plugin/plugin.json (source of truth for Cursor discovery, version-synced alongside the Claude manifests), plus cli/src/lib/cursor-registry.js and cli/src/lib/plugin-manifest.js helpers.

Fixed

Cursor install never surfaced /draft:* commands — draft install cursor copied the plugin tree to ~/.cursor/plugins/local/draft/ but never registered or enabled it, so skills and slash commands never appeared in Cursor chat. The installer now ships the Cursor-native manifest and registers + enables draft@draft-plugins in the shared Claude plugin registry that current Cursor builds read. Registry writes are atomic and non-destructive. Existing installs upgrade with draft install cursor --force.

v3.2.1 2026-06-15 Tooling Fix

Fixed

Graph tooling unreachable on Claude Code marketplace / npm installs — skills invoked the bundled scripts/tools/*.sh helpers by bare, cwd-relative paths. Because a skill's shell runs with the cwd set to the user's project — not the plugin — and ${CLAUDE_PLUGIN_ROOT} is not exported into skill-driven Bash, every graph wrapper silently failed and the knowledge-graph engine appeared unavailable. Skills now resolve a DRAFT_TOOLS directory (install marker → plugin cache glob → marketplace clone → cwd) and invoke helpers as "$DRAFT_TOOLS/<tool>.sh".

Added

scripts/tools/resolve-tools.sh — canonical resolver that locates the bundled scripts/tools/ dir regardless of install layout (Claude Code cache, marketplace clone, Cursor, or in-repo dev). Documented in core/shared/tool-resolver.md.
draft install writes ~/.cache/draft/plugin-root — an authoritative install-path marker so skills resolve the helper directory on the fast path (best-effort; resolution falls back to globbing the plugin cache if absent).

v3.2.0 2026-06-14 Knowledge Graph Tooling

Added

Full codebase-memory-mcp capability adoption (graph tooling v2) — Draft now uses the whole graph engine instead of a thin ~3-edge slice. All Cypher is centralized in a new sourced module scripts/tools/_graph_queries.sh (single source of query truth), so a label/dialect fix is a one-line edit. New wrappers: graph-query.sh (read-only passthrough), graph-snippet.sh (verified source + caller/callee counts), graph-search.sh (semantic/ranked search), graph-tests.sh (TESTS coverage / --untested), graph-deps.sh (real IMPORTS graph), graph-hierarchy.sh (INHERITS), graph-errors.sh (RAISES/THROWS), graph-risk.sh (engine-precomputed risk flags), and graph-traces.sh. graph-callers.sh gains --transitive[=N], --prod-only, and --qualified. Symbol-scoped wrappers emit a fail-loud status so an empty result is never mistaken for a confirmed true negative.
Richer architecture/refresh data — hotspot-rank.sh now ranks by fanIn + complexity + cognitive and annotates entry points; mermaid-from-graph.sh --diagram module-deps derives the dependency diagram from real IMPORTS edges (with the prior co-change proxy preserved as --diagram co-change); graph-snapshot.sh records the detect_changes delta in the gate marker.
Single-source-of-truth version sync — package.json is now the canonical version; scripts/sync-version.sh propagates it into .claude-plugin/plugin.json, .claude-plugin/marketplace.json, and the web/index.html release labels. It runs automatically via the npm version lifecycle hook, and tests/test-version-sync.sh fails CI if any file drifts.

v3.1.5 2026-06-14 Breaking Knowledge Graph

Changed

The knowledge graph is now engine-only — Draft no longer commits a machine-readable mirror of the graph. scripts/tools/graph-snapshot.sh indexes the repo into the local codebase-memory-mcp engine and writes one committed file: draft/graph/schema.yaml, a gate marker carrying no graph data (access: engine-live). All structural data is queried live via the graph-*.sh wrappers, so it can't go stale between commits.
draft/index.md is a plain docs index — it lists the prose context files and tracks with one-line descriptions, with no OKF framing or okf_version frontmatter.

Removed

Open Knowledge Format (OKF) emission — deleted okf-emit.sh, okf-bundle.sh, okf-check.sh (and their tests). No more draft/graph/okf/ bundle.
Committed graph snapshot files — architecture.json, hotspots.jsonl, module-deps.mermaid, and proto-map.mermaid are no longer generated. They were lossy, went stale on the next commit, and duplicated what the engine serves live.

v3.0 2026-06-14 Breaking Knowledge Graph

Changed

One scope-aware /draft:init — Draft now has a single entry point for building context. Run /draft:init at the repo root or inside any sub-module; it figures out the scope automatically.
Root-first code-graph memory — init always builds the whole-repo knowledge graph (the spine) first. A sub-module gets its own snapshot plus a root-link.json pointing up to the root graph, so any module has full cross-module understanding regardless of where you ran init.
--graph-only and --module-only flags — --graph-only rebuilds just the code-graph memory (no markdown); --module-only skips touching the root.

Removed

/draft:index removed (breaking) — folded into the scope-aware /draft:init. Monorepo context now comes from running init at the root (sparse root map + graph spine) and in each sub-module (detailed context + root link). The multi-directory bug sweep moved to /draft:bughunt. Total surface: 33 skills.

v2.8 2026-06-14 Install Knowledge Graph

Fixed

v2.8.3 — install claude-code no longer hangs — claude plugin marketplace add git-clones the repo, and ~670 MB of audiobook .m4a files in HEAD made even the shallow clone download everything, stalling the install on its first step. The audio now ships as a GitHub Release asset (removed from the repo), shrinking the marketplace clone from ~535 MB to under 2 MB. The installer also gained a per-step timeout so a stalled network op prints the manual fallback instead of hanging forever.
v2.8.2 — routers, upload & integrations now in the README — the command reference previously listed only specialist leaf commands; it now documents the 4 top-tier routers (/draft:plan, /draft:ops, /draft:docs, /draft:discover), the /draft:upload handoff gate, and the /draft:integrations parent command.
Counts corrected site-wide — the total surface is 34 skills (4 primary + 5 routers + 25 specialists). Stale "33 commands / 22 specialists" copy is now aligned to the actual count.

Knowledge Graph

v2.8.1 — graph engine fetch no longer 404s — scripts/fetch-memory-engine.sh pinned codebase-memory-mcp to v0.7.0, which publishes no binary assets, so every fetch failed with a 404 and graph features stayed unavailable. Bumped the pin to v0.8.1 (current release with published darwin/linux assets and a verified checksums.txt).

Installation

v2.8.0 — graph engine fetched on every install — draft install now downloads the codebase-memory-mcp engine for all hosts (claude-code, codex, opencode), not just cursor. The download stays best-effort and network-gated, and remains opt-out via --no-graph.
v2.8.0 — claude-code install upgrades existing plugins — re-running the installer now runs four idempotent claude plugin steps (marketplace add, marketplace update, install, update), so existing users are bumped to the latest version instead of short-circuiting on "already installed".

v2.7 2026-06-13 Install

Installation

One-command npm install — draft install <host> — Installation is now an npm CLI (@drafthq/draft). Run npx @drafthq/draft install <host> (or npm install -g @drafthq/draft then draft install <host>), where <host> is claude-code, cursor, codex, or opencode. draft list shows every host and where it installs.
Self-contained installs — the CLI bundles all assets, so there is no runtime git clone. Flags: --global/--project for scope, --dry-run to preview, --force to overwrite, --no-graph to skip the engine fetch.
New cross-host AGENTS.md — the build pipeline now also generates integrations/agents/AGENTS.md (full inlined methodology, native agent names preserved), used by the Codex and opencode installers.
Retired scripts/install.sh — the curl | bash universal installer is removed. GitHub Copilot and Gemini are no longer installable hosts; copy their committed instructions file directly.

v2.6 2026-06-11 Knowledge Graph

Knowledge Graph

New graph engine — codebase-memory-mcp — Draft's knowledge graph now runs on codebase-memory-mcp: tree-sitter + LSP-grade resolution across 159 languages, 100% local, no API key. The previous in-house Node.js + tree-sitter-WASM engine is retired.
Fetch-on-install — the engine is downloaded and checksum-verified into ~/.cache/draft/bin at install time (scripts/fetch-memory-engine.sh) instead of being vendored. Resolution order: DRAFT_MEMORY_BIN › PATH › managed cache › vendored. Opt out with DRAFT_MEMORY_DISABLE=1.
New /draft:graph command — initialize or refresh the draft/graph/ snapshot for any repo, ensure the engine is present, then report module counts, hotspots, and cycles.
Lightweight committed snapshot — draft/graph/ now holds schema.yaml, architecture.json, hotspots.jsonl, and *.mermaid instead of the per-language JSONL indexes. Live structural queries run on demand against the engine.

Tooling

New graph tools — graph-snapshot.sh (committed snapshot), graph-impact.sh (file/symbol blast radius), graph-callers.sh (caller enumeration), plus fetch-memory-engine.sh (pinned, checksum-verified install).
New test suites for the graph tools; all 25+ suites plus make build and make lint pass clean.

Infrastructure

Hardened the GitHub Pages deploy — added web/CNAME and web/.nojekyll and pinned actions/configure-pages to a full-length commit SHA to unblock the custom-domain deploy.

v2.5 2026-05-17

Workflow & Architecture

Command Reduction Plan — Introduced canonical parent commands (/draft:plan, /draft:ops, /draft:docs, /draft:integrations) to logically group and reduce surface-level command sprawl. Specialist commands are intelligently routed through these entry points.
Phase 0 Graph Build — The knowledge graph build is now officially Phase 0 of the /draft:init workflow, providing exact module boundaries before analysis begins.
Universal Install Script — A single scripts/install.sh script unifies onboarding across Claude Code, Cursor, Copilot, Gemini, and Antigravity.

v2.4 2026-04-26

Code Intelligence

Knowledge graph engine — tree-sitter + LSP-grade resolution across 159 languages, 100% local. Query tools: callers, impact, hotspots, modules, cycles, mermaid.
Confidence-tagged call edges — every call edge marked direct (bare identifier) or inferred (member call) so review/bughunt can weight findings.
Atomic incremental builds via per-module SHA-256 hashing — only changed modules re-extract.
Track impact memory in metadata.json — each completed track records files touched, modules affected, downstream count, by-category breakdown. /draft:new-track surfaces overlap warnings during context load.

Tooling

14 deterministic shell helpers under scripts/tools/ — git metadata, file classification, hotspot ranking, cycle detection, freshness checks, ADR indexing, test-framework detection, more. Uniform JSON output and exit-code contract; graceful degradation.
16 new tool tests bringing the suite to 25 total.
make build and make lint Makefile targets added.

Methodology

Refreshed all 28 skills with deeper guidance and "Red Flags — STOP if you're..." preambles.
architecture.md template expanded from 25 sections to 28 sections + 5 appendices with tier-based output minimums for large codebases.
New shared procedures: graph-query.md, parallel-analysis.md (Map/Reduce IR — ~60% wall-clock cut at XL tier).

Fixes

Hardened Copilot syntax transform: kebab-case skill names only, email-shaped tokens preserved.
TS module-edge resolution correctly resolves multi-segment relative imports.
JSON escape helper strips ASCII control characters.
Glob exclude patterns anchored to full-string match.
16 stale TOC anchors fixed in methodology.md.

v1.2 2026-04-05

Book & Audiobook

Audiobook player with integrated playback and dedicated audio page
Share buttons and deep-link support on chapter pages and audiobook player
NotebookLM audio sources for audiobook generation

Plugin

Expanded to 28 commands with restructured book for progressive disclosure
Fixed directory path handling for skills in plugin manifest
Gitignore and cleanup of 34 stale build temp files

v1.1 2026-03

Website

Full website redesign with light theme and SVG illustrations
24-chapter online book covering the full CDD methodology
Migrated book from hash-based SPA to static path-based pages for SEO
Comprehensive SEO: structured data, OG tags, hreflang, sitemaps
Mobile-friendly responsive layout for website and book
Improved text contrast and readability across all cards

Plugin

v2.2.0 release — 8 new specialist commands, Draft book, website redesign
Skill enhancements and bug fixes
Deep review fixes across /draft:init, /draft:new-track, and /draft:implement
Defensive reads, SHA delimiters, session recovery improvements

Infrastructure

GitHub Pages deployment scoped to web/ directory only
GA4 analytics integration across all pages

v1.0 2026-02

Core

Initial release of the Context-Driven Development plugin
25 slash commands organized in a two-tier architecture: 4 primary workflow commands with auto-invocation, plus 21 specialist commands
7 specialized agents: architect, debugger, planner, RCA, reviewer, ops, writer
Multi-IDE support: Claude Code, GitHub Copilot, Google Gemini, Cursor

Build Pipeline

Build script processing 28 skills with YAML frontmatter validation
Syntax transforms for platform-specific integration files
10 test suites with custom bash test framework

Features

Signal detection across 11 categories for adaptive analysis
Incremental refresh with file-level freshness tracking
Cross-session continuity with run memory and resumable checkpoints
Skill dependency graph with execution chains
Auto-learning guardrails with pattern promotion
Jira integration with epic qualification pipeline
Hybrid integration model for Copilot and Gemini
Enterprise-grade quality skills and agent protocols