Add structured compiler diagnostics

DEVELOPMENT_NOTES.md

@@ -207,6 +207,40 @@ version 3, so existing version-2 indexes rebuild without changing canonical sour
 Frontier cursors are streamed and stop immediately on the first omitted unique result. A focused
 core, CLI, MCP, Ruff, and Pyright gate passes for this work-in-progress slice.
 
+#### Structured profiling and zero-work gates
+
+DocForge now has an opt-in, request-local diagnostics collector backed by `ContextVar`. It emits
+one bounded version-1 aggregate with a fixed operation name, outcome, total elapsed nanoseconds,
+fixed stage timing keys, and fixed integer counters. It never records paths, node IDs, queries,
+source text, or SQL. Disabled mode reads no clock and adds no response field, preserving the
+existing CLI and MCP payloads.
+
+The generic loader, adapter projection and extraction paths, source-generation checks, index
+checks/synchronization/build/read transactions, render status/preparation/output hashing, MCP
+runtime validation, and viewer-manager requests now expose direct proof counters. A warm
+incremental adapter cache hit still counts the enclosing project load, so the counters cannot hide
+full adapter assembly merely because extraction was reused.
+
+MCP servers and the CLI accept the additive `--diagnostics` startup option. Diagnostics are
+attached to structured successes and errors only when the complete MCP response still fits its
+configured output budget; they are discarded before any primary result or compact mutation
+receipt. Warm generic error decoration now reads the persisted source generation before falling
+back to complete loading. Render- and visualization-status error paths explicitly disable both
+recovery synchronization and complete identity loading.
+
+Context isolation tests cover threads, concurrent async tasks, repeated stages, nested collectors,
+exceptions, and disabled collection. Repository tests assert that warm success and error reads,
+render status, and visualization status perform zero project loads, source parses, adapter
+projection/extraction, index builds, render preparation, output construction, and output hashing.
+The result JSON schema contains the same closed operation, stage, and counter sets as the
+implementation.
+
+The maintained `tools/milestone1_benchmark.py` harness adds hard counter and p95 latency gates to a
+disposable generic project. The smoke target is part of `make gate`; the 1,000-node evidence run
+will be recorded only from a clean committed revision. The historical Milestone 0 harness remains
+behaviorally unchanged as comparison evidence; it only exposes shared fixture and measurement
+helpers to the Milestone 1 harness.
+
 ### Initial design constraints
 
 - Full rebuild remains the recovery and equivalence oracle.
@@ -225,5 +259,10 @@ These are notes, not commitments:
   generic project and one incremental adapter prove the same boundary.
 - Profiling receipts could eventually feed the human-facing project control panel, but Milestone 1
   should expose structured data before adding UI.
+- A durable telemetry exporter remains deliberately deferred. Request-local bounded aggregates are
+  enough to prove compiler work in Milestone 1 without adding persistence, cardinality, or privacy
+  risks.
+- Visualization freshness needs a separate source/index snapshot contract. Lifecycle health alone
+  must not be relabeled as current documentation state.
 - Large context and changeset payloads may need cursor pagination or compact immutable receipts.
   The choice should follow actual client workflows rather than generic pagination machinery.