83 lines
4.1 KiB
Markdown
83 lines
4.1 KiB
Markdown
# 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.
|