Milestone 4 closeout

Outcome

Milestone 4 is complete. New projects can adopt a public adapter SDK or one of four narrow repository reference integrations, attach a fixed read-only MCP server, and follow maintained product documentation without reading core implementation.

Implemented contracts:

Stable docforge.adapter_sdk authoring imports.
Independent complete primary-graph-plus-Logic oracle and exact incremental equivalence.
Bounded adapter assemblies and version-1 extraction caches.
Base Python, optional JavaScript, optional TypeScript, and optional C++ reference integrations.
Closed .docforge/reference-adapter.toml and fixed docforge.reference_mcp read-only binding.
Immutable, project-bound, launchable AdapterLauncherV1 declarations and generated Codex, Claude, and OpenClaw fragments for custom adapters.
Live implementation-derived CLI and MCP reference tables with race-safe publication and drift checking.
Strict documentation graph, link, anchor, H1, reachability, required-page, generated-notice, and documented-reference-config checks.
Offline fresh-wheel adoption and maintained 1,002-node scale/recovery gates.

Candidate evidence

The frozen executable candidate is 95271dcf2e48045b9d3aed9b9ea09c7fc155692c.

Its complete executable gate passed:

Ruff formatting and Python lint.
HTML, rendered-manual HTML, portable-graph HTML, CSS, and JavaScript checks.
Pyright with zero diagnostics.
Warning-strict compilation.
142 contract tests and 268 subtests.
347 complete tests and 402 subtests.
Three Playwright and axe accessibility flows for the manual, portable graph, and live viewer.
Lock and npm dependency-tree checks.
Wheel and source-distribution builds.
Offline fresh-wheel adoption.
Milestone 0, 1, 2, 3, and 4 smoke benchmarks.

The clean full benchmark passed exact graph-plus-Logic equivalence, warm zero Python parser and extraction work, corrupt-cache recovery, corrupt-index recovery, response, memory, and latency gates. Exact results are in the Milestone 4 baseline and benchmarks/milestone4-2026-07-29.json.

Gitleaks 8.30.1 scanned the Milestone 4 commit range and candidate tree with no findings. The SSH remote syntax prevents Gitleaks from constructing finding hyperlinks; it does not affect scanning.

Reference scope

Python uses the standard-library AST and publishes syntax plus local imports.
JavaScript and TypeScript use distinct optional Tree-sitter grammars and publish syntax plus project-local static relative imports and re-exports.
C++ uses a confined compile_commands.json as inert translation-unit inventory and publishes syntax plus directly resolvable project-local quoted includes.
The references do not claim resolved calls, inheritance, types, symbol references, compiler include semantics, macro semantics, runtime behavior, or semantic ownership.

The C++ reference never executes a compiler or compilation-database command. It is not a Clang semantic adapter.

Preserved boundaries

The docforge distribution, Python package, CLI, MCP executable, and tool names remain.
Generic projects and one-method load_projection() adapters remain supported.
Descriptor schema version 1, index schema version 3, effective policy version 1, and no-AST behavior remain.
Heavy language frontends are optional. Base generic and Python operation installs no Tree-sitter distribution.
Reference MCP is read-only. Proposal and application remain explicit project-owned gates.
No language adapter was separately published.
No WorldForge, ScrapeStation, legacy-repository, production-binding, storage, or self-hosting change was made.
No tag or Forgejo release was created for Milestone 4.

Later work

Milestone 5 owns stabilization and the first DocForge2 release. Release identity, compatibility matrix, migration and recovery proofs, comparative real-task evidence, versioning, tagging, and publication must be validated there. Remote adapters, render farms, third-party renderers, cross-project graphs, storage replacement, and self-hosting remain deferred without measured need.

4.1 KiB Raw Blame History