# Milestone state

```text
Last completed milestone: 3 — independent projections
Evidence: d6d9f47672c513c4927c5c42ad97a175ed651a74 is merged and pushed on main and dev.
Active milestone: 4 — adapter SDK and product documentation.
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.
Status: Active. The first gate freezes and proves the adapter SDK before language references.
Next directional milestone: 5 — stabilization and first DocForge2 release.
```

## Milestone 4 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.