# Milestone state

```text
Last completed milestone: 4 — adapter SDK and product documentation.
Baseline: 6d06195950d33bcd2d712f8819bbfb3d6652ad03 on main, dev, origin/main, and origin/dev.
Active milestone: 5 — stabilization and first DocForge2 release.
Outcome: Compatibility, determinism, recovery, security, performance, and representative task advantage are proven for the first successor release.
Status: Active.
Release candidate: 1.4.0, subject to every gate below.
```

## Authority

This contract activates Milestone 5 from the clean, merged, and pushed Milestone 4 closeout. The
roadmap in `/home/andraxion/.openclaw/workspace/DocForgeOutline.md` supplies direction; this file
freezes the executable scope and acceptance criteria.

`main` remains the Milestone 4 baseline until the complete Milestone 5 release candidate passes.
Implementation occurs on `dev`.

## Required release evidence

The release candidate must prove all of the following from maintained, reproducible gates:

1. Legacy one-method adapter compatibility and the frozen package, CLI, MCP, schema, rendering,
   descriptor, result-envelope, and no-AST surfaces.
2. Exact complete/incremental primary-graph and Logic equivalence for maintained incremental
   adapters.
3. Deterministic adapter, worker, renderer, command-reference, configuration, and publication
   output.
4. Detection of concurrent source mutation without publishing or serving a mixed or stale
   generation.
5. Atomic, crash-safe derived publication and exact recovery from interrupted publication.
6. Corrupt extraction-cache, index, attestation, receipt, fragment, and projection recovery using
   canonical sources as the authority.
7. No stale reads after source or policy change, including generation-pinned retrieval and viewer
   behavior.
8. Exact-hash canonical application with project-owned serialization, stale-proposal rejection,
   and post-application resynchronization.
9. Closed policy precedence across process capability, descriptor policy, `--no-ast`, projection
   policy, worker enforcement, and viewer enforcement.
10. Manual and portable-graph isolation, immutable package verification, bounded detached workers,
    rendering-policy enforcement, viewer-policy enforcement, and accessibility.
11. Comparative representative task evidence with fixed questions, answer keys, provenance,
    latency, and response-size accounting for both graph-assisted and source-only workflows.
12. A fresh-wheel and fresh-clone release rehearsal, full quality and browser gates, maintained
    benchmarks, secret scans, exact version identity, signed-off release notes, and reproducible
    release artifacts.

## Deliverables

- A maintained Milestone 5 compatibility matrix and aggregate release gate.
- Reproducible migration, recovery, concurrency, and comparative-task evidence.
- One authoritative package version shared by package metadata, Python, CLI, MCP, viewer manager,
  reference MCP, generated configuration, and release documentation.
- A standard project license file, changelog or release notes, release baseline, closeout record,
  and machine-readable evidence.
- A clean `main` merge, synchronized `main` and `dev`, annotated `v1.4.0` tag, and Forgejo release
  only after the final documentation-bearing commit passes a fresh-clone gate.

## Fixed boundaries

- Preserve the `docforge` package, `docforge` CLI, `docforge-mcp`, MCP tool names, schema version 1
  surfaces, effective policy version 1, projection policy version 2, and legacy adapter entry point.
- Preserve canonical project sources. Migration may rebuild disposable state but may not rewrite
  canonical content merely to satisfy the release.
- Full rebuild remains the recovery and equivalence oracle.
- Derived artifacts must fail closed on malformed, foreign, stale, oversized, or incompatible
  state.
- Version `1.4.0` is additive relative to `1.0.0`; breaking a frozen contract requires a separately
  justified major-version decision.

## Exclusions

- No WorldForge change or benchmark.
- No ScrapeStation change, production binding change, or production migration.
- No legacy-repository mutation.
- No production MCP repointing.
- No remote render service, render farm, third-party renderer ecosystem, graph federation, or
  dedicated graph database.
- No arbitrary adapter command execution, compiler execution, remote execution, or expanded
  launcher authority.
- No PyPI publication unless it is separately verified as an intended existing release channel.

## Release sequence

1. Freeze and implement the compatibility, migration, recovery, concurrency, and task-evidence
   gates.
2. Stabilize version identity, packaging, license, security, and release automation.
3. Freeze one clean executable candidate and run the full repository, browser, benchmark,
   fresh-wheel, fresh-clone, and secret-scan gates.
4. Close documentation atomically against that candidate and rerun documentation-only validation.
5. Merge and push the final candidate.
6. Rehearse from a fresh anonymous clone at the exact commit.
7. Create and push the annotated `v1.4.0` tag and publish the Forgejo release from the verified
   artifacts.

The completed Milestone 4 contract and exclusions remain preserved in `SLICE_HISTORY.md`.

## Release-candidate evidence — 2026-07-29

The executable implementation is frozen at
`d2bb95fe6190e659cf66ba57c78be53b63b53240`. The proof-bearing candidate base is
`2b98059b44f4d46b4d4cce776f163e893c647c76`; it includes exact legacy-tag verification for the
fresh-clone gate and four maintained aggregate derived-recovery tests.

The clean executable release gate passed formatting, Python and web lint, strict Pyright,
compilation, lock and dependency checks, builds, generated documentation, three accessibility
flows, fresh-wheel adoption, artifact reproducibility, secret scans, and the full Milestone 0
through Milestone 4 benchmark sequence. Its exact test evidence was:

- 142 contract tests plus 272 subtests.
- 371 complete tests plus 419 subtests.
- 116 compatibility tests plus 263 subtests.
- 29 concurrency tests plus 2 subtests.
- 68 recovery tests plus 62 subtests.

The real migration gate preserves exact canonical and proposal bytes from the annotated `v1.0.0`
lineage while rebuilding the disposable index from schema 1 to schema 3. The real-package task
gate uses the lock-pinned `markdown-it-py 4.2.0` tree and proves exact graph-assisted and
source-only answers for all reviewed tasks.

The later proof-only recovery commit adds four maintained tests without changing executable
product code. The current recovery aggregate passes 72 tests plus 62 subtests.

Milestone 5 remains active. Documentation closeout, final branch synchronization, a fresh
anonymous clone at the exact documentation-bearing remote commit, final artifact checksums, the
annotated `v1.4.0` tag, and the Forgejo release are still pending. No PyPI publication is planned.