Activate Milestone 4 adapter SDK contract

ACTIVE_SLICE.md

@@ -2,12 +2,71 @@
 
 ```text
 Last completed milestone: 3 — independent projections
-Outcome: Manual output, portable graph artifacts, and the live viewer are independent generation-pinned consumers of the validated graph.
+Evidence: d6d9f47672c513c4927c5c42ad97a175ed651a74 is merged and pushed on main and dev.
-Evidence: Clean candidate f5dccb5e1c312121f1af63780162f593d9363b98; 281 tests and 272 subtests; 3 accessibility flows; clean 1,000-node ten-sample benchmark; isolated wheel proof; no secret-scan findings.
+Active milestone: 4 — adapter SDK and product documentation.
-Active milestone: None.
+Outcome: New projects can adopt DocForge incrementally, and users can understand the CLI, MCP server, policies, adapters, renderers, and agent integration without reading implementation code.
-Next directional milestone: 4 — adapter SDK and product documentation.
+Status: Active. The first gate freezes and proves the adapter SDK before language references.
-Status: Milestone 3 is closed. Milestone 4 has not started.
+Next directional milestone: 5 — stabilization and first DocForge2 release.
 ```
 
-Milestones 4–5 remain directional context. Do not begin Milestone 4 without a new active-slice
+## Milestone 4 contract
-contract.
+
+Milestone 4 closes only when all of the following are true:
+
+1. A typed public adapter SDK and repository-native conformance kit make complete, incremental,
+   Logic, confinement, restart, cache-recovery, no-AST, and retrieval contracts usable without
+   reading core implementation.
+2. Repository-owned runnable reference integrations exist for Python, JavaScript/TypeScript, and
+   C++. They declare their evidence authorities and unsupported facts. Syntax-only evidence never
+   claims compiler-resolved calls, inheritance, types, or ownership.
+3. Heavy language frontends are optional. A base wheel and no-AST operation work without them.
+   Missing optional features fail with closed, actionable errors.
+4. CLI and MCP reference tables are generated deterministically from implementation-owned
+   metadata and a repository gate rejects drift.
+5. Custom adapters can declare one versioned, immutable, project-bound launcher. Codex, Claude,
+   and OpenClaw client configuration is generated from that launcher without arbitrary discovery
+   or execution.
+6. Dedicated onboarding, authority, descriptor, policy, adapter, language, legacy/no-AST,
+   rendering, agent-integration, security, recovery/performance, and DocForge v1 migration
+   guidance passes a fresh-wheel adoption proof.
+7. Existing package, import, CLI, MCP, legacy-adapter, generic-project, no-AST, projection,
+   application, and recovery behavior remains additively compatible.
+
+## Fixed decisions
+
+- Milestone 4 provides stable in-repository SDK APIs and reference integrations. It does not
+  promise separately published language-adapter distributions.
+- Complete adapter evidence includes primary graph and function Logic. An incremental adapter that
+  publishes Logic must expose an independent complete Logic oracle before equivalence can pass.
+- Python reference evidence may use the standard-library AST. JavaScript/TypeScript and C++
+  reference evidence uses optional pinned parsing frontends for syntax plus declared build
+  inventory. It omits semantic facts that require a compiler, language server, or SCIP evidence.
+- C++ inventory is bound to a project-confined compilation database. WorldForge is not used or
+  changed.
+- JavaScript and TypeScript are both exercised. TypeScript support requires its own optional
+  pinned grammar; it is not silently parsed as JavaScript.
+- Adapter extraction caches remain disposable and may become safely ahead of the last published
+  SQLite index. The index remains the active validated generation. Recovery must prove this
+  behavior instead of claiming one joint cache-and-index transaction.
+- Generated references and templates are derived artifacts. Implementation metadata is their
+  authority.
+
+## Exclusions
+
+- No WorldForge, ScrapeStation, legacy-repository, or production-binding change.
+- No remote adapter execution, arbitrary adapter commands, renderer ecosystem, render farm,
+  storage rewrite, or cross-project graph.
+- No compiler or language-server installation by DocForge.
+- No self-hosting requirement.
+- No version, release tag, or Forgejo release before Milestone 5.
+
+## Slice order
+
+1. Freeze complete graph-plus-Logic equivalence, the SDK facade, conformance protocol, schemas, and
+   baseline measurements.
+2. Add deterministic command metadata, generated CLI/MCP references, and a drift gate.
+3. Add the Python reference integration and scaled complete/incremental benchmark.
+4. Add optional JavaScript/TypeScript and C++ reference integrations with bounded evidence.
+5. Add versioned adapter launcher metadata and generated agent configurations.
+6. Freeze the candidate, perform one documentation closeout, and run focused, complete,
+   fresh-wheel, adoption, benchmark, accessibility, build, and secret-scan gates.