Close Milestone 4 with adapter adoption evidence

DEVELOPMENT_NOTES.md

@@ -784,3 +784,108 @@ proof. Gitleaks 8.30.1 found no findings across the six Milestone 3 commits or c
 Milestone 3 is complete. No tag, release, production integration repointing, WorldForge change,
 ScrapeStation change, storage rewrite, or self-hosting dependency was introduced. Milestone 4
 remains directional and has not started.
+
+## Milestone 4 — complete: adapter SDK and product documentation
+
+Milestone 4 activated from the verified Milestone 3 closeout. Its scope was deliberately additive:
+freeze an adapter-authoring boundary, prove narrow language references, make heavy frontends
+optional, generate command and client integration evidence, and document adoption. WorldForge,
+ScrapeStation, the legacy repository, production bindings, self-hosting, storage replacement, and
+release publication remained excluded.
+
+### Adapter SDK and conformance
+
+`docforge.adapter_sdk` is now the public authoring facade for typed projections, manifests, source
+contributions, complete assemblies, incremental loaders, project bindings, core graph models, and
+conformance reports. Complete evidence includes primary graph and function Logic. An incremental
+adapter that publishes Logic must provide an independent `load_complete_assembly()` oracle.
+
+The conformance helper repeats complete loading for determinism, compares the complete assembly
+with `load_projection()`, and proves exact complete/incremental graph-plus-Logic parity. It does not
+pretend to replace separate confinement, restart, no-AST, corrupt-cache, or retrieval tests.
+
+An adversarial review found that extraction caches and adapter assemblies lacked aggregate
+boundaries. Version-1 cache reads and writes are now regular-file-only, identity-checked, capped at
+64,000,000 bytes and 10,000 sources, and fail safely to a miss. Adapter projects enforce primary
+node limits and deterministic edge and Logic multipliers before publication.
+
+### Reference language evidence
+
+The Python reference uses the standard-library AST and publishes files, modules, classes,
+functions, arguments, local static imports, and function Logic. Its manifest uses tokenization
+rather than AST parsing, so unchanged warm builds perform no syntax parse.
+
+JavaScript and TypeScript use separate pinned optional Tree-sitter grammars. They publish files,
+modules, classes, functions/methods, static project-relative imports/re-exports, and function
+Logic. Their manifests use a closed comment/string-aware ESM scan and do not load Tree-sitter.
+
+C++ uses explicit non-overlapping source roots and one confined `compile_commands.json` as
+translation-unit inventory and fingerprint evidence. It validates entries but never executes a
+command, compiler, response file, or project program. It publishes syntax and directly resolvable
+project-local quoted includes. Its manifest currently parses for include discovery, so no
+zero-warm-parser claim is made.
+
+None of the references claim compiler-resolved calls, inheritance, types, symbol references,
+compiler include semantics, macro semantics, runtime behavior, or semantic ownership.
+
+The first packaging proof exposed that language parsers were inherited as mandatory dependencies.
+The base wheel now depends only on Markdown and MCP packages. Python works in the base wheel;
+JavaScript, TypeScript, C++, and all-language extras install their respective Tree-sitter
+frontends. Missing extras return a closed error with the exact install target.
+
+### Fixed reference MCP and launchers
+
+A strict `.docforge/reference-adapter.toml` selects one fixed reference language, project
+identity, and explicit source roots. C++ additionally requires the compilation database. The fixed
+`python -m docforge.reference_mcp` binding constructs only repository-owned providers and exposes
+the 21 read tools.
+
+The initial launcher design generated `python -I -m` for arbitrary project module names without
+proving that isolated Python could resolve them. The corrected `AdapterLauncherV1` accepts only an
+installed project-confined top-level module or the exact trusted `docforge.reference_mcp`
+exception. A fixed bounded `find_spec` probe runs under isolated Python without importing project
+code. Tests then launch both a real project module and the real reference MCP process.
+
+Generated Codex, Claude, and OpenClaw fragments bind the exact launcher, descriptor, source
+availability, effective and projection policy, interpreter, canonical arguments, empty
+environment, artifact bytes, and hashes. There is no arbitrary command, argument list, working
+directory, environment, discovery, or callable selector.
+
+### Generated reference and documentation gates
+
+CLI tables are derived from the real argparse subcommands. MCP tables are derived from a real
+application-enabled server's `list_tools()` registrations, including capability surface,
+arguments, descriptions, and input-schema hashes. The generated artifact contains 28 CLI rows and
+36 MCP rows.
+
+An adversarial review found a target-change race between the generator's identity check and
+replacement. Publication now locks cooperating generators, uses no-clobber publication for a
+missing target, and uses Linux atomic exchange plus displaced-byte and file-identity verification
+for an existing target. Raced data is restored or retained for recovery rather than discarded.
+
+`docs-check` validates generated drift, local files and anchors, one H1 per page, README-rooted
+reachability, required Milestone 4 inventory, the generated notice, and every documented
+reference-adapter TOML example against the packaged schema.
+
+### Candidate, adoption, and scale evidence
+
+Frozen executable candidate `95271dcf2e48045b9d3aed9b9ea09c7fc155692c` passed formatting,
+Python and web lint, strict Pyright, compilation, 142 contract tests and 268 subtests, 347 total
+tests and 402 subtests, three accessibility flows, lock and dependency checks, package builds,
+offline wheel adoption, and every maintained smoke benchmark.
+
+The offline adoption proof installed the base wheel from the lock without network access. It
+proved no Tree-sitter package or module was installed, built and checked a real Python reference
+project, performed isolated MCP bootstrap/search/get-node over the exact 21 read tools, and proved
+that base-only C++ fails with `optional_dependency_missing` and `docforge[cpp]` remediation.
+
+The clean 334-source benchmark produced 1,002 primary nodes, 1,001 primary edges, 334 Logic
+projections, 2,338 Logic nodes, and 2,338 Logic edges. Complete and incremental output matched
+exactly. Warm build p95 was 1,265.387 ms with zero `ast.parse` and zero `extract_source` calls.
+Complete equivalence, corrupt cache recovery, and corrupt index recovery were all below 1.9
+seconds. The largest per-operation traced peak was 69,997,166 bytes and process high-water was
+78,798,848 bytes. Exact hashes and method are recorded in
+`benchmarks/milestone4-2026-07-29.json` and `docs/MILESTONE_4_BASELINE.md`.
+
+Milestone 4 is complete. No tag or release was created. Milestone 5 remains unstarted until its own
+active-slice contract is frozen.