DocForge2/docs/MILESTONE_5_BASELINE.md

Milestone 5 baseline

Status and method

This baseline records the frozen DocForge 1.4.0 release lineage and the evidence used to publish annotated tag v1.4.0.

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. Documentation-bearing candidate 49e1a87c138cdc63fb5abb85fc6eb2cf9f4a9d73 passed the complete clean local release gate. The annotated tag points to its final documentation-only descendant after the exact 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. The final clean clone reruns 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:

.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.

Final release evidence

The documentation-bearing candidate passed 378 tests plus 422 subtests and all three accessibility flows. The final documentation-only descendant is synchronized across main, dev, origin/main, and origin/dev, then passes the maintained anonymous fresh-clone rehearsal at that exact commit. Annotated tag v1.4.0 and the Forgejo release identify that commit.

Final artifact checksums are generated from the tagged source and recorded in the attached machine-readable release-identity evidence. The release includes the wheel and source distribution. It does not publish to PyPI.