Align implementation guides with the current cohort and CI registry #71

Completion — 2026-09-28

Completed by PR #78, docs: align implementation guides with registry and published results, squash-merged as c1d8e81b959e2c0ee0e5c4a1d8a7491790479f93. This issue remains closed/completed.

The checked acceptance criteria below describe the implementation diff from eba127e65761ced4d0fef06a6c52cc2dc1fdb6ab to that merge commit. A fresh comparison confirms exactly five public guides and tests/test_benchmark_implementation_docs.py changed; no registry, application, measurement, workflow, README or results/** files changed in this PR.

Verification evidence: final-head CI 36329214231, post-merge main CI 36329994147, and automatic ordinary Pages 36330588841 succeeded. PR #78 retains the TDD and local-versus-CI limitations. These are existing CI/deployment results, not a newly executed local test suite or proof of publicly served byte equality.

The maintainer's later authorization for a new official benchmark/publication is tracked separately in #59. This documentation issue neither performs that operation nor proves the producer-to-Pages verification complete.

Priority and purpose

P2 — small documentation-correctness follow-up. Remove current-state contradictions without rewriting historical decisions or introducing a large documentation generator.

Verified baseline

Rechecked main on 2026-09-18: 9b92c74cba34bd5a4bfc389075b9bef135131034. Refresh the repository state when implementation starts.

The registry registers nine implementations, with eight-stack-v1 active and Java outside both existing official cohorts. The published eight-stack report includes Axum and Flask.

The following implementation guides still describe earlier rollout states as current:

• docs/FLASK.md, Publication boundary: says active_cohort remains four-stack-v1.
• docs/AXUM.md, Status and comparison boundary: describes active four-stack-v1 and Axum as excluded; Normal CI integration describes a six-implementation matrix.

These statements can be accurate as dated implementation history, but not as unqualified descriptions of current main.

Scope

1. Correct the verified Axum/Flask inconsistencies and inspect other public implementation/status guides for equivalent current-versus-historical ambiguity.
2. Distinguish registration, official-cohort membership, verified publication and release snapshots explicitly. Preserve the original meaning of historical four-stack-v1 reports and v0.1.0.
3. Keep a canonical current-state explanation in the registry guide (docs/IMPLEMENTATIONS.md) backed by benchmark/implementations.json; prefer links from implementation-specific guides instead of repeated counts and membership claims.
4. Retain implementation-specific runtime choices, validation commands and diagnostic limitations. Rewrite historical statements as dated/contextual history where useful rather than deleting evidence.
5. Add proportionate regression coverage for critical current-state claims and internal links. Avoid tests coupled to exact paragraphs or a hard-coded implementation count that must be changed in many places.

Acceptance criteria

• Axum and Flask guides no longer imply that they are excluded from the active cohort at the implemented snapshot.
• Java remains clearly registered/CI-covered but not officially measured, unless a separately approved later change has altered that state.
• No current-state guide contradicts the authoritative registry; historical descriptions are explicitly historical.
• Relevant documentation/link checks, registry checks, site tests and README-generation checks pass.
• Published JSON/history/charts and generated numeric README blocks are unchanged.
• Application code, pinned versions, measurement conditions and workflow behavior are unchanged.

Dependencies and boundaries

No hard dependency on #70; this small fix can proceed independently. It is distinct from the broader README information-architecture cleanup. #52 remains deferred and #59 remains a live verification follow-up, not a documentation task to close here.

No benchmark execution, publication, cohort activation, release/tag update or settings change is included. Follow AGENTS.md: investigation notes and Superpowers plans remain untracked under docs/investigations/ and docs/superpowers/; durable public guides remain versioned.