check-doc-checkpoint cannot see PARTIAL or ANCHOR-BACKFILL, so 188 rows can change lifecycle state with no gate

[localai-bot]

scripts/check-doc-checkpoint.py enforces CLAUDE.md's rule that docs/STATUS.md, docs/BENCHMARKS.md and the moved row spec's ## Now are owed when a row changes lifecycle state (CLAUDE.md:409-414). It recognises the state by matching a backticked token against a fixed tuple (:56-66):

STATES = ("TODO", "READY", "ACTIVE", "GATING", "BLOCKED", "DONE", "DROPPED", "N/A")
STATE_CELL = re.compile(r"`(" + "|".join(re.escape(s) for s in STATES) + r")`")

PARTIAL and ANCHOR-BACKFILL are not in that tuple, and both are lifecycle states in active use.

.agents/feature-matrix.md:20 declares them explicitly: "PARTIAL, BLOCKED, and ANCHOR-BACKFILL as explicit non-done states." BLOCKED is in the tuple. The other two are not.

Scale

Counting backticked state cells across .agents/*-matrix.md, using the checker's own STATE_CELL shape:

state	cells	in STATES?
PARTIAL	115	no
ANCHOR-BACKFILL	73	no
DONE	73	yes
BLOCKED	9	yes

PARTIAL — 115 cells across six matrices (engine 30, model 28, feature 25, quantization 14, backend 11, kernel 7) — is more used than DONE, and it is the one the gate cannot see. Together the two unguarded states cover 188 rows.

The consequence

A row moving into or out of PARTIAL or ANCHOR-BACKFILL owes docs/STATUS.md and its spec's ## Now under the prose rule, and no gate can observe that it moved. The state cell never matches STATE_CELL, so the change is not a lifecycle change as far as the checker is concerned, and the projection surfaces silently go stale.

This is not hypothetical. It surfaced during the fresh review of LOAD-GGUF-MMPROJ (#821 W1), whose row moves READY → PARTIAL. The reviewer proved the instrument was live — flipping the row to DONE in a scratch commit reds it (rc 1, naming docs/BENCHMARKS.md and the spec's ## Now) — then reverted docs/STATUS.md, then docs/USAGE.md, then all of docs/, and got rc 0 every time. The green was honest (no checker was weakened, and no scripts/ change was in that diff) but vacuous: the row owed the checker nothing because its destination state is invisible.

That is the shape CLAUDE.md's "Changing the rules or a checker" section warns about — the checker's behaviour and the prose rule diverging, with no gate over the divergence.

Why this is filed rather than fixed in flow

Adding two strings to a tuple is a one-line edit, but it is a semantic checker change: it moves 188 rows into the population the gate enforces against, and the first change to touch any of them then owes STATUS/BENCHMARKS/## Now where it previously did not. That needs a spec, a red-before test, and a decision about whether ANCHOR-BACKFILL — which reads more like a maintenance marker than a lifecycle state — belongs in the same tuple as PARTIAL at all.

It is also exactly the ratchet situation that has already reddened main once: .agents/issue-index.md records #1376, where filling a spec's ## Gates moved a row into the runnable population and RUNNABLE_BASELINE was not re-pinned in the same change. Widening STATES has the same shape and wants the same care.

Suggested check when this is fixed

Take a row currently in PARTIAL, move it to ACTIVE in a scratch commit without touching docs/STATUS.md, and confirm the checker reds. Today it does not.

Verified at 63d87805c.

[localai-bot]

Partly fixed in 4c193bd55 (#1577): PARTIAL is now in STATES. Three parts remain, and one correction is owed to this issue's own text.

Correction: the suggested reproduction in this issue does not reproduce

The issue proposed taking a row in PARTIAL, moving it to ACTIVE without touching docs/STATUS.md, and confirming the checker reds — "today it does not". It already did red, but for the wrong reason: it reported added as ACTIVE for a row absent from the BEFORE map, which is a right verdict from a wrong mechanism.

The transitions that genuinely expose the gap are READY -> PARTIAL (the LOAD-GGUF-MMPROJ case that surfaced this) and PARTIAL -> READY — both rc 0 before the fix and rc 1 after.

That distinction matters for anyone reading this issue later: a check that reds for an unrelated reason is not evidence the gate works, and taken at face value it would have masked the defect.

ANCHOR-BACKFILL is deliberately NOT added — a ruling, not an omission

STATES is not the feature-matrix.md:20 sentence. It is the trigger for REQUIRED["lifecycle"] = (STATUS, BENCHMARKS), which carries all its surfaces or none, so the test is what docs/STATUS.md can truthfully project.

• PARTIAL is a public term: docs/STATUS.md:39 carries it verbatim, and :53/:57 use that exact cell value.
• ANCHOR-BACKFILL is a property of the record, not the capability — feature-matrix.md:14-17 defines it as a legacy implemented row lacking exact anchors. docs/STATUS.md has no matching term, so a DONE <-> ANCHOR-BACKFILL move would demand a public-doc edit with nothing true to write.

That is exactly the failure check-doc-checkpoint.py:4-17 records as why the file was rewritten — 16 of 20 red CI runs and six escape hatches. The ## Now obligation ANCHOR-BACKFILL genuinely does owe is filed as remaining work, not dropped.

A second gap this surfaced

.agents/sglang-matrix.md is a keyed row table with State cells and is absent from ROW_TABLES entirely, so none of its rows are observed by this gate at all. ROW_TABLES lists seven files and that is not one of them, while the file carries three DONE cells.

Still open under this issue

1. ANCHOR-BACKFILL's ## Now-only obligation, which REQUIRED cannot express today (all surfaces or none).
2. .agents/sglang-matrix.md missing from ROW_TABLES.
3. Rows that leave the matched set entirely, e.g. READY -> INVENTORIED.
4. A new row added directly as PARTIAL.

All four are recorded in .agents/specs/doc-checkpoint-lifecycle-states.md under ## Owed.

Scale, re-derived at 947e5f648

PARTIAL is 118 cells — more than DONE at 77 — across engine 31, model 28, feature 25, quantization 16, backend 11, kernel 7. Adding it moved the resolved-row population over the seven tables ROW_TABLES reads from 153 to 226 (+47.7%).

One real repair fell out: KV-BLOCK-POOL (.agents/engine-matrix.md:97) writes a parenthesised PARTIAL (not DONE) in its evidence prose, and the last-match heuristic believed the parenthesis and resolved DONE. It now resolves PARTIAL — the only flip in the tree.

[localai-bot]

Closing as moot: the gate this issue describes no longer exists.

1db7e59cf (#1714) retired docs/STATUS.md and deleted scripts/check-doc-checkpoint.py, deliberately. Its commit body says so directly:

Remove the shared public status ledger and make README the sole compact public project overview. Git, row-owned specs, and matrices remain the source for detailed lifecycle state. […] Retire the repository-specific documentation projection gates that made ordinary pull requests update shared prose.

Verified on main: neither docs/STATUS.md nor scripts/check-doc-checkpoint.py exists.

That is the better fix, at a level this issue could not reach

This issue asked why a checker could not see PARTIAL. The deeper answer is that the surface it enforced should not have existed. AGENTS.md ## Records says it plainly:

Do not create a surface that every pull request must write. If N concurrent pull requests edit file F, that file is a lock.

docs/STATUS.md was that lock, and the projection gate was the mechanism that made every ordinary pull request take it. #1714 removed the lock and the gate together. The checker's own header already recorded the symptom — 16 of 20 red CI runs and six escape hatches — which is what a lock looks like from inside.

What landed against it, and is now moot

commit	wave
4c193bd55 (#1577)	PARTIAL added to STATES — 118 cells, more used than DONE, moving the observed population 153 → 226
ba4634204 (#1609)	the record states resolve, population 226 → 793, transitions() splitting CLAIM from RECORD
52e328789 (#1621)	the destination decides the move class, repairing a loosening W2 introduced

All three remain ancestors of main as history; the file they modified is gone.

What survives, because it was never really about this checker

Two findings outlast the code:

A replay of already-gated history cannot detect a removed obligation. W2 priced itself over 400 commits and reported "1 newly red, 0 newly green", and that was accepted — including by me — as proof it only tightened. It could not have been anything else: the old gate enforced the obligation W2 removed, so no commit exposing the removal could ever have landed. The corpus was selected by the rule under test. Nine transitions had in fact gone from red to green, three of them real commits on main, and only constructed transitions found them. A historical replay prices what a change adds; only construction prices what it removes.

A test anchored to the first literal match can be a tautology that hides a live regression. test_anchor_backfill_stays_out_of_the_tuple split on an inline ## Owed at line 59 rather than the section at 479, so it scanned 420 lines and could not fail. Re-anchored, it immediately went red — W2 had rewritten that section without ANCHOR-BACKFILL, and the broken test had hidden it.

I also merged W2 without an independent review, substituting my own gate rerun, which AGENTS.md is explicit is an input and never a gate result. The review dispatched afterwards found the loosening in one pass.

The residuals are moot with it

The four items recorded under .agents/specs/doc-checkpoint-lifecycle-states.md's ## Owed — ANCHOR-BACKFILL's ## Now-only obligation, .agents/sglang-matrix.md's absence from ROW_TABLES, rows leaving the matched set, and a row added directly as PARTIAL — all describe behaviour of a checker that no longer runs. If lifecycle projection is ever re-introduced, that spec still records what was measured about each: the state-cell census, the 400-commit transition replay, and the phantom-row measurement showing sglang-matrix.md carries a classification rather than a lifecycle state.

One item is not moot and is tracked elsewhere: spec_for_row takes the first linked spec, and 97 of 793 rows link more than one. That belongs to whatever reads row-to-spec links next.