128 lines
6.8 KiB
Markdown
128 lines
6.8 KiB
Markdown
# 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.
|