DocForge2/docs/MILESTONE_5_BASELINE.md

# Milestone 5 baseline

## Status and method

This baseline records the frozen DocForge `1.4.0` release candidate. It is release-candidate
evidence, not a claim that the tag or Forgejo release already exists.

The executable implementation freeze is
`d2bb95fe6190e659cf66ba57c78be53b63b53240`. Fresh-clone legacy-tag verification was added in
`97f3b6b1ae303c972387508557a3d54ea621a702`, and the maintained aggregate recovery proofs were
completed in
`2b98059b44f4d46b4d4cce776f163e893c647c76`. The final tag must point to the later
documentation-bearing commit after its clean fresh-clone gate.

The clean executable candidate used:

- Linux 7.1.3-200.nobara.fc44.x86_64 with glibc 2.43.
- CPython 3.14.6 on x86_64.
- The repository lockfile and offline wheel inputs.
- Maintained repository-native gates rather than a self-hosted DocForge development loop.

No WorldForge, ScrapeStation, legacy repository, production binding, or production MCP
configuration was changed.

## Quality and compatibility gates

The clean executable candidate passed:

- Ruff formatting and lint, web lint, strict Pyright with zero diagnostics, and compilation.
- 142 contract tests plus 272 subtests.
- 371 complete tests plus 419 subtests.
- Three Playwright and axe accessibility flows covering the manual, portable graph, and live
  viewer.
- Lockfile, dependency-tree, wheel, source-distribution, generated-reference, and documentation
  checks.
- 116 compatibility tests plus 263 subtests.
- 29 concurrency tests plus 2 subtests.
- Offline fresh-wheel adoption, exact version identity, reproducible artifact, and secret-scan
  gates.
- The complete maintained Milestone 0 through Milestone 4 benchmark sequence.

The later maintained recovery proof adds four tests without changing executable product code. Its
aggregate recovery gate passes 72 tests plus 62 subtests. A final clean clone must rerun the
complete totals from the documentation-bearing commit before tagging.

Compatibility remains additive:

- The `docforge` distribution and imports, CLI, generic MCP executable, MCP tool names, generic
  project descriptor, result envelopes, legacy one-method adapter, and no-AST behavior remain.
- Effective policy version 1, projection policy version 2, descriptor schema version 1, and index
  schema version 3 remain the current authorities.
- Complete and incremental maintained adapters produce exact primary-graph and Logic equivalence.

## Version and artifact identity

One source file owns version `1.4.0`. The following executable surfaces reported that exact
version:

- `docforge`
- `docforge-mcp`
- `docforge-viewer-manager`
- `python -m docforge.reference_mcp`

The package metadata also reported `docforge 1.4.0`, Python 3.12 or newer, the MIT license
expression, the public Forgejo repository, and its issues URL. Generated client bindings include
the version in their validated, hash-bound identity.

Two independent builds from the executable candidate and the same source-date epoch produced
identical artifacts:

| Artifact | Bytes | Executable-candidate SHA-256 |
|---|---:|---|
| Wheel | 315,811 | `c3b9bfa320d00d827154e0f858a6b970459ae0eba6ab14e1cd4f6ba470e33b6a` |
| Source distribution | 685,891 | `bb5f9333e5fa2365cf0f8ac12d7920122315b4835c9f81b7aa457eb05f1702f5` |

Both contained the license and version authority. These identify the executable freeze only.
Documentation changes alter the final release artifacts, so final checksums must be generated from
the exact tagged documentation-bearing commit.

The release channel is Forgejo only. PyPI is excluded because the `docforge` name is occupied by an
unrelated project.

## Exact migration evidence

The migration gate archives and executes the real annotated `v1.0.0` lineage:

- Tag object: `2d7d306a37da89f1c860c7f0be161c45386acf61`.
- Peeled commit: `593c173b453236a6872d0a4e88e7a51a67a21cde`.
- Canonical byte hash before and after:
  `9fde91b6b08669177d690cdf9f91b162120baee1f7e24b05fec67f56617f286a`.
- Snapshot hash before and after:
  `45bef8b0e1a4dac976e096dcf8f9048e1268211cd7f7638cdf99951428ec0500`.
- Active proposal hash:
  `2c055dfae45443b4a4d9d4087ef70959e7293beae8d27acb14ffffe52eca7111`.
- Active proposal file hash:
  `4658d494b43bd7c6cc3e3f5933a2c878c817b52bc4566e9e8429e7b8e43ca007`.

The version-1 disposable index rebuilt from schema 1 to schema 3. Canonical bytes, graph meaning,
and the active proposal remained exact. The current CLI is a 28-command superset of the version-1
20-command surface. The current generic MCP surface is a 36-tool superset of the version-1
25-tool surface.

The proof also preserves a real inherited version-1 inconsistency: package metadata reports
`1.0.0`, while its Python module and server report `0.15.0`. Migration evidence records that fact;
it does not rewrite history to make the old identities agree.

## Recovery and concurrency evidence

The maintained gates prove:

- Concurrent canonical-source changes fail closed without publishing or serving mixed
  generations.
- Exact-hash canonical application uses project-owned serialization and compare-and-swap
  publication, rejects stale proposals, and preserves raced source data.
- Extraction caches and SQLite indexes rebuild from canonical sources or complete adapter
  projections.
- Corrupt index attestations, manual render receipts, generation-diff receipts, and portable-graph
  manifests recover through their normal synchronize, rebuild, or render entry points.
- Recovery preserves exact canonical bytes, the canonical collection hash, the complete snapshot
  hash, and primary-graph-plus-Logic index identity.
- Derived publication uses durable atomic replacement and directory synchronization.

The release does not claim that a multi-file canonical application is process-death atomic. A
malicious same-UID process deliberately modifying the private mode-0700 transaction directory is
also outside the application race contract. Those limits do not weaken the maintained
concurrent-canonical-source compare-and-swap proof.

## Representative real-task evidence

The real-package track uses installed, lock-pinned `markdown-it-py 4.2.0`:

- 66 Python files.
- 225,945 source bytes.
- Source-tree SHA-256:
  `bd57c9f332fcf6507282ec2023e6804fce0cf844631696336ee17cbe46e63aad`.
- No network, production binding, installed-source mutation, or self-hosting.
- Python reference-adapter local-import projection for graph-assisted work.
- Independent standard-library AST import inspection for source-only work.

Both workflows returned the exact reviewed answer for all three tasks:

| Task | Graph inspected | Source inspected | Graph median | Source median |
|---|---:|---:|---:|---:|
| Renderer direct dependencies | 349 B | 10,628 B | 0.008 ms | 1.341 ms |
| Three-level HTML-block impact | 419 B | 225,945 B | 0.009 ms | 32.108 ms |
| CLI-to-core-state path | 212 B | 225,945 B | 0.013 ms | 32.142 ms |

Per-task latency excludes the separately reported one-time graph preparation. Graph-assisted
answers inspected substantially fewer agent-visible bytes and carried generation-bound
provenance. The source-only answers were smaller on the final response-size metric. The comparison
therefore records the measured tradeoff rather than claiming that every metric favors the graph.

The real-package semantic evidence SHA-256 is
`c8c19b2900fa47abdaff94f5b13fd9ca537241089edc97b30d32d9db8809a2c1`.
The combined real and generated-track evidence SHA-256 is
`45952883b47449eb4fd862b51854aa2001749928e0d37c5a6e58c2d3292fbee4`.

## Machine-readable evidence

The maintained evidence generators emit canonical compact JSON and can write it atomically with
their `--output` option:

```bash
.venv/bin/python tools/milestone5_migration.py --output /tmp/docforge-m5-migration.json
.venv/bin/python tools/milestone5_task_evidence.py \
  --mode full --output /tmp/docforge-m5-task-evidence.json
.venv/bin/python tools/check_release_identity.py \
  --mode full --require-clean --tag-state absent \
  --output /tmp/docforge-m5-release-identity.json
.venv/bin/python tools/milestone5_fresh_clone.py \
  --commit "$(git rev-parse HEAD)" \
  --output /tmp/docforge-m5-fresh-clone.json
```

Migration, task, release identity, artifact hashes, and the final anonymous-clone result therefore
remain reproducible machine evidence rather than prose-only claims. The final Forgejo release
attaches the release-identity JSON beside the wheel and source distribution.

## Remaining release gate

The baseline is complete for the release candidate. Milestone 5 remains active until:

1. The documentation closeout is committed.
2. `main` and `dev` are synchronized and pushed.
3. The exact final commit passes the maintained fresh anonymous clone gate.
4. Final artifacts and checksums are generated from that commit.
5. The annotated `v1.4.0` tag and Forgejo release are created and verified.