Close Milestone 4 with adapter adoption evidence

docs/MILESTONE_4_CLOSEOUT.md

@@ -0,0 +1,83 @@
+# 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](MILESTONE_4_BASELINE.md) and
+[`benchmarks/milestone4-2026-07-29.json`](../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.