Close Milestone 1 fast core

docs/MILESTONE_1_CLOSEOUT.md

@@ -0,0 +1,99 @@
+# DocForge2 Milestone 1 closeout
+
+Milestone 1 establishes a fast, observable core without changing graph meaning, canonical
+authority, the supported `docforge` identity, or the legacy adapter boundary.
+
+## Completed contracts
+
+- Generic projects publish a versioned source-generation receipt only after complete stable
+  verification.
+- Routine reads validate file and membership-directory identities without parsing canonical
+  sources.
+- Every indexed read uses one immutable read-only SQLite transaction pinned between source and
+  index identity checks.
+- Dependency validation is linear in nodes and edges and uses an iterative deterministic cycle
+  check.
+- Search, filtering, backlinks, dependency, impact, context, and changeset review results are
+  bounded independently of project size.
+- Version-1 cursors bind the project, adapter, canonical generation, query, collection, and
+  position. Corrupt and stale cursors fail closed.
+- Mutation tools preflight their minimum receipt and never report `result_too_large` after a
+  committed operation.
+- Render status uses a publication receipt and performs no hidden render, source parse, index
+  rebuild, or repair.
+- Visualization status separates lifecycle from source and index freshness and performs no hidden
+  SQLite validation or source parse.
+- Request-local diagnostics expose fixed bounded stage timings and work counters without recording
+  source text, paths, node IDs, queries, or SQL.
+
+Complete loading, deep index checking, deep render status, and full adapter projection remain the
+recovery and equivalence oracles.
+
+## Compatibility
+
+The distribution, import package, three executable names, existing CLI commands, existing MCP tool
+names, and required arguments remain supported. New limits, cursors, deep-status switches, and
+diagnostics are additive.
+
+A one-method `load_projection()` adapter remains supported. Incremental behavior remains optional.
+The no-AST binding continues to reject Logic publication and every Logic retrieval surface,
+including application refresh and live visualization.
+
+The disposable SQLite index schema is version 3. Version 2 indexes rebuild automatically. No
+canonical source or stored proposal is migrated to satisfy the new index.
+
+## Verification
+
+The complete repository gate passed at clean commit
+`6253c45a5eca01efa8c73ea3dfe4d85c55878ada`:
+
+- Ruff formatting and lint.
+- HTML, rendered-manual HTML, CSS, and JavaScript lint.
+- Pyright with zero diagnostics.
+- Python compilation.
+- Public-contract and no-AST checks.
+- 138 tests and 77 subtests under warnings-as-errors.
+- Lock and JavaScript dependency-tree checks.
+- Wheel and source-distribution builds.
+- Milestone 0 benchmark smoke.
+- Milestone 1 counter and latency smoke.
+
+The maintained clean 1,000-node benchmark passed every latency and work-counter threshold. Exact
+retrieval measured 18.577 ms p95. Paged 32,000-token context measured 25.867 ms p95. Warm no-change
+synchronization measured 9.324 ms p95. Render receipt status measured 19.613 ms p95.
+Visualization status measured 10.836 ms p95.
+
+Detailed evidence is in
+[`MILESTONE_1_BASELINE.md`](MILESTONE_1_BASELINE.md) and
+[`benchmarks/milestone1-2026-07-29.json`](../benchmarks/milestone1-2026-07-29.json).
+
+## Measured decisions
+
+SQLite remains the derived retrieval store. The benchmark demonstrates that whole-source
+validation around SQLite, not SQLite retrieval itself, caused the inherited latency. No speculative
+storage rewrite was made.
+
+Receipt caches remain disposable and fail closed. A missing, corrupt, incompatible, foreign, or
+changed receipt falls back to the complete oracle or reports an explicit unverified state according
+to the operation's safety contract.
+
+Pagination is transport state, not project authority. It adds no database and grants no
+authorization.
+
+## Remaining weaknesses
+
+- Context selection is bounded but not yet streaming internally.
+- Scaled incremental-adapter performance remains unmeasured.
+- Generic cheap generation proof uses filesystem identity rather than content hashing on every
+  read.
+- Legacy adapters without incremental state cannot always prove current identity cheaply.
+- One oversized context entry requires targeted retrieval after an explicit omission.
+- Operation-local and detached-worker memory need a maintained isolated harness.
+- Tree-sitter and its JavaScript and C++ grammars remain mandatory package dependencies.
+- `ManualRenderPlan`, `GraphViewPlan`, and independent renderer packages remain Milestone 3 work.
+
+## Scope confirmation
+
+Milestone 1 did not self-host DocForge2, change WorldForge or ScrapeStation, repoint a production
+MCP integration, modify the legacy Forgejo repository, create a tag, or create a release.
+