Release plan: what it takes to finish

The work between here and a 1.0 that matches the documented architecture. Ordered by dependency, not by preference. Every item names its exit condition, because "done" without one is how the last four days went.

Where this actually stands

Measured 2026-10-26. Regenerate the counts before quoting them: the previous version of this table survived fifty-five commits past the point it stopped being true, and then did it again — an audit on 2026-08-26 found it still naming 0.7.0 as the last tag while v0.9.1 was shipped and 26 further commits sat on the branch, and a v1.0 readiness audit on 2026-08-31 found the counts stale a third time. Three times now, in the paperwork of the project that exists to catch drift.

v1.1.0 shipped C, v1.2.0 C++, v1.3.0 C# and v1.4.0 free-form Fortran — five languages over one shared walk in _ranges_core, where a language is a module and a row. Fortran is the first with no braces, so the walk now takes its bounding rule as an argument. The row above names the last tagged version and is compared verbatim against git tag, so it moves in the same step that creates the tag, not before. Committed before the tag, with the tag pointing at that commit — tagging first fails the release build, which checks out the tag, finds the older row and refuses. That is how v2.11.0 was tagged and never published, and it happened again at v3.0.0; that tag was moved onto the corrected commit because no artifact had shipped.

A release is not finished until the operator's own install is on it. Written down 2026-09-09 because it was not being done. The local editable install was made on 2026-08-30 at 0.9.1 and never refreshed, so its metadata sat 0.9.1 through every release up to 3.0.2 — twenty-odd tags. The code was current, since an editable install follows the working tree, and --version reads the source, so the tool never reported the wrong number. What was wrong is subtler and worse for UAT: the installed distribution and the tree disagreed about what was installed, importlib.metadata.version("maintainability-agent") answered 0.9.1 to anything that asked, and the environment being tested was not a state any user could reproduce. A UAT run against an install nobody can name is not a test result.

So the last step of every release, after the tag and the publish:

python3 -m pip install -e ".[dev,mcp]"     # or the published wheel
python3 -m maintainability_audit --version # must equal the tag
python3 -c "from importlib.metadata import version; print(version('maintainability-agent'))"

Both must print the version just tagged. Then restart any editor holding the MCP server, because it keeps the old process. This cannot be checked in CI — it is a property of a machine, not of the repository — which is exactly why it belongs written here rather than remembered.

This table is a navigation summary, not a second implementation register. Phase completion follows the exit conditions below; the 8.8–8.10 release gates closed on 2026-09-01. Work after 1.0 is tracked on the roadmap and in the decision register, not by adding phases here.

Two things are deliberately open rather than done:

• The calibration constant is 5.8843 (2.6279 → 2.2658 on 2026-08-14, then 2.2658 → 5.8843 on 2026-08-31). The 08-31 re-fit followed a corpus re-measure: the stored measurements had gone stale, and plan-81dc6870 Class 4's clone-grouping had dropped the built-in duplication reading roughly fourteenfold, so every report scored duplication against a reference ~14x too high. All 40 pinned repos were re-measured --with-analyzers; the duplication reference moved 3.8644 → 0.28 and declarations 0.0860 → 0.1005. Corpus median still rolls up to 4.0 (a well-run codebase earns a B). Old and new values are recorded in _calibration.py, and a scanner-counting guard now fails if a change like Class 4 silently invalidates the reference again.
• ADR 007 §4's rename is refused, and the deviation is recorded there and in standard.md: the ownership aspect measures the share of settled files one person owns, which is not the bus factor, and adopting the name would claim a measurement the tool never makes.

Versions that never reached PyPI

Checked against PyPI and this repository's release runs on 2026-09-23. Every version below has a changelog section and no published package. None is to be re-tagged or republished. Each one's changes shipped inside a later release, and publishing an old number now would put a stale package beside the current one for no reader's benefit.

Two checks now close the two ways this happened. A version that is never tagged fails the next version's pull request (tests/test_the_previous_release_was_tagged.py). A version that is tagged but never published fails the next version's release build (tools/check_previous_release_published.py, run by release.yml), which asks PyPI directly because the suite has no network. Both look one version back, deliberately: the gaps above are recorded, not repaired.

Phase 0 — Land what exists, fix what is broken

Small, independent, and blocking later phases. Nothing here needs the analyzer work.

Phase 0 has landed. Identity shipped as function:{path}:{name}#{ordinal}, not a content hash. 0.4 is the migration note and the version-2 baseline rejection. 0.7.0 is tagged on main.

0.2 and 0.3 are prerequisites for ADR 005 and ADR 009 respectively. They are also the only user-visible bug fixes available without the larger build, so they justify a release on their own.

Phase 1 — Population floors and honest withholding

Implements ADR 005. No external tools required, so it can land before the runner.

Exit for the phase: the fixture that started all of this reports "practice level 1, condition unmeasured" rather than 5.0/A+.

Phase 2 — The analyzer runner and the first adapters

Implements the executable half of ADR 006. The largest phase and the one that changes the product.

The exit-condition tests for 2.6 and 2.8 have landed. The latter compares recorded tool versions after removing terminal paint; it does not claim every consumer pins analyzer versions in CI. Their rows remain here as the historical definition of the work.

Watch item: P1 weakens here from "deterministic" to "deterministic given pinned analyzer versions." Product intent must be edited in the same commit that makes it true.

Phase 3 — Translation: bands, combination, the seam

Implements ADR 008's normalization half. Depends on Phase 2.

Order within this phase is forced. 3.1–3.6 have landed: the band matrix drives declaration and file-size pressure; the interval contains the other source's rollup and widens with per-concept analyzer spread.

Measured across the corpus, and it corrected an earlier claim. This document previously reported the swap as "roughly 4x on declaration pressure", from a single measurement on this repository. Running all 40 corpus repositories gives a median ratio of 0.3x — the analyzers see less pressure than the built-in detectors on most of them, not more.

The split is by language, and it was a defect rather than a finding:

complexipy and radon are Python-only, so a Python repository's declarations dimension averaged lizard's cyclomatic complexity with complexipy's cognitive complexity while a TypeScript one used lizard alone — and the two were then compared as though they measured the same thing. analyzer_pressures now composes a dimension only from its full concept set and reports None otherwise, for the same reason two reports with different analyzer coverage are not comparable.

The 4x figure came from this repository being Python-heavy. Generalizing from n=1 is the mistake this plan warns against two sections down, and it survived a commit message and this document before forty repositories caught it.

What the corpus run settled. Every reference and the curve constant reproduced exactly except risk, which moved 0.0726 to 0.0733 — traced to this release adding three Python-only default risk patterns that fire on the 13 Python repositories. Both values and the cause are recorded in _calibration.py. Corpus median still rolls up to 4.0.

3.6 was the risk item and is done. Replacing homegrown detectors with external tools moved the corpus scores. The constant was re-derived, studies.md records the shift, and the old and new numbers are both in _calibration.py.

This is how Go, C, C++, C# and Rust get a declaration population. Java already has a zero-install fallback in _ranges; there will not be another language clone. See the register on ADR 006.

What 3.6 did (2026-08-14)

The 2026-08-12 block was real: widening include_extensions without provenance would have fitted material-ui's 10,759 generated icon wrappers into the scale. Provenance now excludes generated/vendored files from the scored population, and the point estimate uses analyzer declaration pressure where the full concept set was measured.

Re-measured the 40 pinned repos with --with-analyzers. The fit replays the shipped mix (_derive.primary_declarations). 13 of 40 (the Python members) supplied an analyzer declaration pressure; 27 fell back because lizard alone cannot compose the three-criterion set. Constants moved:

Corpus median rollup is 4.0. Previous values remain in _calibration.py.

Phase 4 — Pillars, practice level, work order

Implements ADR 007 and the actionable half of ADR 008.

Phase 5 — Scan history and trends

Implements ADR 009. Needs 0.3 (identity) and Phase 3 (stable score semantics), or the series records numbers that later change meaning.

5.4 is Miles's feature and the sharpest differentiator: the accumulated-friction signal a language model structurally cannot hold.

Deferred, deliberately — a calibration profile for small repositories

An organization whose whole estate is small services needs a scale fitted to that, not a lowered floor on a scale fitted to mature repositories. That means a calibration profile: a corpus, the constant fitted to it, floors from its minima, bands from its percentiles — distinct from the evidence profile (default-v1), which declares what must be measured.

Sequencing is forced, not preferred. The shipped constant is the 2026-08-14 analyzer-primary fit. A second profile still waits on a sampling frame; it must not be fitted until that frame is written down. The order was: build, test, audit, re-derive the primary (3.6), then gather the small-repository data using the finished instrument — which is also the first real exercise of it at scale.

The sampling frame is the hard part, and it is a study-design decision. The existing corpus has a defensible frame: mature OSS, standing in for "what good looks like". A small-repository corpus does not inherit that justification. A random sample of small public repositories is mostly abandoned toys, and fitting to those would anchor the scale to "typical small repository" — a materially weaker claim than the current one, and one nobody asked for. The frame likely needs to be small repositories from organizations with demonstrated practice: a real service from a team that ships, not a weekend project. Whatever is chosen changes what the resulting scale means, so it is decided and written down before any repository is cloned, under the Tier 3 bar in product intent — pinned inputs, a stated frame, stated limits.

Until that exists, a small repository gets path 2: a complete audit, every finding, and no score.

Phase 6 — Entry points

Phase 7 — Release 1.0

Phase 8 — 1.0 presentations and scoring continuity

Decided in ADR 011 and the schema-2 close of ADR 009. 7.5 and the tag wait on this. The acceptance test is the last human gate; if it fails, this phase is reopened, not papered over.

Sequencing constraints

0.2 --------> Phase 1 (ADR 005)
0.3 --------------------------------> Phase 5 (ADR 009)
Phase 2 (runner) --> Phase 3 (translation) --> Phase 4 (pillars, work order)
                                  \--> Phase 5 (history)
Phases 1-5 --> Phase 6 --> Phase 7

Phase 0 is independent and shippable now. Phase 1 needs no external tools. Everything from Phase 3 onward waits on the runner.

What could be cut

If the finish line has to move nearer, these can be deferred without making the tool dishonest:

• Phase 5 backfill (5.5) — history still accumulates going forward.
• Phase 6 MCP (6.2, 6.3) — the CLI covers CI, which is the load-bearing entry point.
• Adapters beyond the ten baseline ones (2.7) — the pool grows over time by design; all already reports honestly what it could not run.
• 2.5c environment work order — shipped: the install-command artifact now rides beside coverage. Acquisition remains opt-in in user-tier configuration; the audited tree cannot enable it.

What cannot be cut without the tool lying: population floors (Phase 1), coverage reporting (2.5), and rubric-driven tool configuration (2.6). Those three are what stop the score from being fiction.