Add deterministic client integration diagnostics

DEVELOPMENT_NOTES.md

@@ -523,3 +523,63 @@ fell from 272.06 ms p95 to 56.617 ms p95, while full traversal fell from roughly
 203.55 ms p95. Regression tests require one receipt validation and at most 15 response encodes for
 1,000 page candidates. Final independent publication, contract, and performance audits approve
 the slice for commit.
+
+### Deterministic client configuration and read-only doctor
+
+Client integration remains an explicit machine-local boundary rather than canonical project
+content. `docforge configure {codex,claude,openclaw} --project PATH` previews a deterministic
+version-1 fragment by default. An optional output path publishes only a standalone fragment into
+an existing real directory. Publication is create-only, private-mode, no-follow, bounded, and
+conflict-aware. Existing differing client configuration is never merged, replaced, or silently
+overwritten.
+
+Generated commands use the exact current virtual-environment Python executable with isolated
+module startup. The binding records explicit read, proposal, or application mode, no-AST policy,
+render policy, empty environment, and bounded timeouts. Proposal and application generation fail
+closed unless the descriptor declares the required writer and matching applier identity. A generic
+CLI cannot reconstruct project-owned adapter composition, so custom adapters return an explicit
+unavailable result instead of generating a misleading command.
+
+Codex and OpenClaw fragments include their verified timeout fields. Claude JSON fragment syntax is
+supported, while its timeout representation remains an explicit warning. The configuration result
+has a strict JSON schema and canonical plan hash. Diagnostics are additive and remain disabled by
+default.
+
+`docforge doctor --client CLIENT` performs bounded, non-mutating inspection only. It reads the
+project descriptor and selected client file through stable, directory-bound, no-follow handles;
+parses at most 1 MiB and 256 server entries; selects at most one exact project binding; validates
+the closed server argument set; checks executable, capability, declared authority, no-AST,
+timeouts, environment-key names, and tool-filter presence; and performs only a stat-level index
+presence check. It never loads canonical sources, opens SQLite, starts MCP, executes the configured
+command, synchronizes, builds, renders, starts a viewer, or writes client configuration.
+
+Doctor reports healthy, degraded, or unhealthy with stable process exit codes 0, 1, and 2. Secret
+environment values are parsed only to enforce bounded string limits and are never returned.
+Unknown or unverified client tool filtering, Claude timeout representation, implicit legacy
+capability mode, shadowed authority, and missing disposable indexes are warnings. Unsafe paths,
+malformed matching entries, unexpected executables, wrong project roots, invalid authorities, and
+missing configuration are failures.
+
+The first benchmark smoke failed for the correct product reason: its disposable doctor fragment
+used the shared path `/tmp/doctor-codex.toml`, where a previous run had left different content. The
+harness now creates a project subdirectory inside one unique temporary root and places the client
+fragment beside it. This preserves create-only conflict safety and makes every run disposable.
+
+The final pre-commit 1,000-node audit sample passes every provisional Milestone 2 gate. Task
+context reconstructs 1,000 candidates as 108 cited evidence records and 892 explicit bounded
+omissions across 11 pages in 703.808 ms. Generation diff reconstructs 1,000 changed details across
+10 pages in 427.450 ms. Maximum pages remain below the 200,000-byte MCP budget; generation diff
+uses 199,566 bytes and proves that diagnostics are discarded before the primary result. Isolated
+peak RSS is 86,168 KiB.
+
+Configuration preview now includes a bounded real import probe of the exact isolated interpreter,
+so its provisional single-sample latency is about 315 ms rather than the earlier sub-millisecond
+derivation-only figure. Doctor remains below 1 ms on generated disposable configurations.
+Every configuration and doctor hidden-work counter is zero.
+
+The aggregate `make gate` includes the Milestone 2 smoke benchmark. The frozen candidate passes
+205 tests and 120 schema subtests, strict warnings, Ruff, formatting, Pyright, web checks,
+compilation, lock and dependency checks, package builds, and all three milestone smoke benchmarks.
+Three independent final audits approve client publication and policy binding, doctor fail-closed
+behavior, and benchmark/contract coverage. Clean-revision benchmark evidence is still required
+before closeout.