Close Milestone 2 with measured evidence

docs/MILESTONE_2_CLOSEOUT.md

@@ -0,0 +1,68 @@
+# Milestone 2 closeout
+
+## Outcome
+
+Milestone 2 is complete. One project-bound server can expose an explicit effective policy and
+return compact, task-shaped, explainable context. Users can generate deterministic client
+fragments and inspect their bindings without hidden runtime work.
+
+Implemented contracts:
+
+- Version-1 effective policy and capability-aware bootstrap.
+- Version-1 retrieval plans and context capsules.
+- Bounded task-context pagination with evidence gaps and explicit omissions.
+- One disposable latest-generation transition receipt and paged read surface.
+- Deterministic Codex, Claude, and OpenClaw standalone configuration fragments.
+- Fixed-inventory read-only doctor results.
+- Dedicated configuration and doctor JSON schemas.
+- Repository-native Milestone 2 contract, smoke, scale, response-size, counter, and memory gates.
+
+## Candidate evidence
+
+The frozen implementation candidate is
+`fb0df5e4a1c591c2a84788fd4814d98550f11863`.
+
+The complete repository gate passed:
+
+- Ruff formatting and lint.
+- HTML, rendered-manual HTML, CSS, and JavaScript checks.
+- Pyright with zero diagnostics.
+- Warning-strict compilation and tests.
+- 205 tests and 120 subtests.
+- Lock and npm dependency-tree checks.
+- Wheel and source-distribution builds.
+- Milestone 0, 1, and 2 smoke benchmarks.
+
+Three independent read-only adversarial audits covered client publication and policy binding,
+doctor race and malformed-input behavior, and benchmark/contract evidence. Reproduced descriptor,
+parent, target, filesystem, policy, secret-redaction, ambiguity, parser, response-size, and hidden
+work defects were fixed and regression-tested before the candidate was frozen.
+
+The clean ten-sample 1,000-node benchmark passed every threshold. Exact measurements and counter
+ranges are recorded in
+[`MILESTONE_2_BASELINE.md`](MILESTONE_2_BASELINE.md) and
+[`benchmarks/milestone2-2026-07-29.json`](../benchmarks/milestone2-2026-07-29.json).
+
+## Preserved boundaries
+
+- The `docforge` package, imports, CLI executable, MCP executable, and existing tool names remain.
+- Legacy one-method `load_projection()` adapters remain supported.
+- The no-AST shorthand and legacy adapter-policy payload remain compatible.
+- Project descriptor schema version 1 remains unchanged.
+- No storage replacement was introduced.
+- No legacy DocForge MCP or DocForge2 self-hosting was used.
+- WorldForge and ScrapeStation were not touched.
+- No production MCP integration was repointed.
+- The legacy Forgejo repository and `legacy` remote were not changed.
+- No tag, release, release announcement, or visibility change was created.
+
+## Known follow-up work
+
+The next active milestone may improve projection independence. It must not silently absorb these
+separate future ideas:
+
+- Avoid recomputing a complete task capsule for every continuation page.
+- Add authenticated cursors only if a stronger threat model requires them.
+- Verify Claude's native timeout representation.
+- Add versioned adapter-owned launcher metadata before generating custom-adapter configurations.
+- Keep doctor read-only; a live connection test must be an explicit separate operation.