fix(docs): one row per bug id in state.md, and a gate that keeps it that way by lusoris · Pull Request #1322 · VMAFx/vmafx

lusoris · 2026-09-05T15:55:12Z

Summary

Five bug ids appeared twice in docs/state.md. Two of them — T-CUDA-INIT-SUBMIT-LEAKS-2026-06-19 (fixed by #1279) and T-UPSTREAM-1564-ADM-CM-GPU-BORDER-AND-ROUNDING-2026-09-03 (fixed by #1224) — sat in both "Open bugs", with the stale present-tense wording, and "Recently closed", with the past-tense wording the fixing PR added. Two bugs that are fixed on master therefore read as open in every audit and in every "what is left for 1.0.0" count. Three more rows (T-SPEED-GPU-REGISTRY-ORPHAN-2026-06-19, T-SIMD-BIT-EXACT-ROUND2-2026-05-30, T-SIMD-ICX-FP-CONTRACT-2026-05-30) were duplicated inside "Recently closed".

The cause is the keep-both conflict resolution that the merge train and the agent worktrees use for the append-only doc sections. It is right when two PRs each append a row and wrong when one PR is moving a row between sections, and the result is invisible in a diff hunk. So the duplicates are removed and scripts/ci/check-state-md-rows.sh now rejects any id that appears more than once, in pre-commit, in make lint-sh and in the Rules workflow, with a hermetic self-test for both shapes. Open-bug rows drop from 17 to 15.

Type

fix — bug-ledger correctness + a new gate

Checklist

Commits follow Conventional Commits.
make format && make lint is green locally (pre-commit on every touched file; shellcheck/shfmt; actionlint clean).
Unit tests: scripts/ci/tests/test-check-state-md-rows.sh (5 cases).
Docs — no docs needed: the gate's own header documents both failure shapes, and docs/rebase-notes.md tells the next rebaser to run it.
SIMD/GPU, twins, new C sources, breaking change, ADR — all n/a.

Bug-status hygiene (ADR-0165)

docs/state.md — the five duplicates removed; T-STATE-MD-DUPLICATE-ROWS-2026-09-05 added to Recently closed.

Netflix golden-data gate (ADR-0024)

I did not modify any assertAlmostEqual(...) score in the Netflix golden Python tests.

Deep-dive deliverables (ADR-0108)

Research digest — no digest needed: trivial. The duplicate list and its cause are in the state.md row and the commit body.
Decision matrix — no alternatives: only-one-way fix. A bug id has one state; the gate is the only way to keep the keep-both shortcut from silently breaking it again.
AGENTS.md invariant note — no rebase-sensitive invariants: the coupling is recorded in docs/rebase-notes.md because it is a rebase note (run the gate after any keep-both resolution).
Reproducer / smoke-test command — below.
CHANGELOG fragment — changelog.d/fixed/state-md-duplicate-rows.md.
Rebase note — docs/rebase-notes.md entry.

Reproducer

bash scripts/ci/check-state-md-rows.sh                       # OK (302 rows, no duplicate ids)
bash scripts/ci/tests/test-check-state-md-rows.sh            # 5 ok lines
git show origin/master:docs/state.md > /tmp/before.md
bash scripts/ci/check-state-md-rows.sh /tmp/before.md; echo $?   # 1 — lists the five ids and their line numbers

🤖 Generated with Claude Code

…hat way Five bug ids appeared twice. T-CUDA-INIT-SUBMIT-LEAKS-2026-06-19 and T-UPSTREAM-1564-ADM-CM-GPU-BORDER-AND-ROUNDING-2026-09-03 sat in BOTH "Open bugs" (the stale present-tense row) and "Recently closed" (the past-tense row the fixing PR added), so two bugs that are fixed on master read as open in every audit and in every "what is left for 1.0.0" count. Three more rows were duplicated inside "Recently closed". The cause is the keep-both conflict resolution that the merge train and the agent worktrees use for the append-only doc sections: it is correct when two PRs each append a row, and wrong when one PR is MOVING a row between sections. scripts/ci/check-state-md-rows.sh now rejects any id that appears more than once, wired into pre-commit, `make lint-sh` and the Rules workflow, with a hermetic self-test covering both shapes (same id in two sections, same id twice in one section) and the clean/missing-file cases.

The first version of this gate anchored row ids on `^\| \*\*(T-[A-Z0-9-]+)\*\* \|`, which only matches a row whose first cell is the bold id and nothing else. The majority shape in docs/state.md is `| **T-ID** -- one-line description | ...`, so 30 of 335 rows were invisible to the gate, and its character class excluded `.`, hiding every dotted id. Two real duplicate pairs survived the first sweep because of exactly those two holes, and the gate reported OK over them: - T-SYCL-DMABUF-IMPORT-WIN32-ENOSYS was filed once under "Confirmed not-affected (by design)" and again under "Deferred (waiting on external trigger)" while its own text says "no action required". Kept the not-affected row, which is the accurate verdict, and folded in the ADR-0374 disabled-interface citation the deferred row carried. - T-VK-VIF-1.4-RESIDUAL was filed twice under "Recently closed". Kept the verified row citing PR #511 (merged 2026-05-09) and dropped the earlier one, whose provenance cell still read "this PR" -- a placeholder the ADR-0165 touch gate rejects. The matcher now anchors on the bold token that opens the first cell and admits `.` in ids. Two regression cases cover the shapes that slipped through; both are detected by the new matcher and invisible to the old one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Every merge to master appends to docs/rebase-notes.md, docs/adr/README.md, docs/adr/_index_fragments/_order.txt and CHANGELOG.md, so every other open PR conflicted on them and had to be rebased by hand. Across three batch rebases on 2026-09-05 that was 32 conflicts — 17 in rebase-notes.md, 7 in the ADR index, 7 in _order.txt, 1 in CHANGELOG.md — and the resolution was always the same: keep both sides. merge=union does exactly that, automatically. docs/state.md is deliberately NOT included. Its rows move between 'Open bugs' and 'Recently closed', so keeping both sides duplicates a row and a fixed bug reads as open forever — the defect PR #1322 removes and gates. Those conflicts stay manual so whoever moves a row has to think about it. Verified on this repo: two branches each prepending a section to docs/rebase-notes.md rebase onto each other with 0 conflicts and both entries present. Caveat, stated in the rebase note: git reads a merge driver from the merge base, so branches already open when this lands conflict once more and are clean from then on.

Every merge to master appends to docs/rebase-notes.md, docs/adr/README.md, docs/adr/_index_fragments/_order.txt and CHANGELOG.md, so every other open PR conflicted on them and had to be rebased by hand. Across three batch rebases on 2026-09-05 that was 32 conflicts — 17 in rebase-notes.md, 7 in the ADR index, 7 in _order.txt, 1 in CHANGELOG.md — and the resolution was always the same: keep both sides. merge=union does exactly that, automatically. docs/state.md is deliberately NOT included. Its rows move between 'Open bugs' and 'Recently closed', so keeping both sides duplicates a row and a fixed bug reads as open forever — the defect PR #1322 removes and gates. Those conflicts stay manual so whoever moves a row has to think about it. Verified on this repo: two branches each prepending a section to docs/rebase-notes.md rebase onto each other with 0 conflicts and both entries present. Caveat, stated in the rebase note: git reads a merge driver from the merge base, so branches already open when this lands conflict once more and are clean from then on. Co-authored-by: Lusoris <lusoris@pm.me>

lusoris added this to the 1.0.0 — First release milestone Sep 5, 2026

lusoris mentioned this pull request Sep 5, 2026

fix(ci): build the clang-tidy lanes without LTO so the gate can pass at all #1326

Merged

11 of 14 tasks

lusoris force-pushed the fix/state-md-duplicate-rows branch from 53eb403 to dbb03a2 Compare September 5, 2026 21:02

lusoris mentioned this pull request Sep 5, 2026

build(git): union-merge the append-only bookkeeping files #1327

Merged

9 of 14 tasks

lusoris marked this pull request as ready for review September 5, 2026 23:03

lusoris merged commit ce7ff4f into master Sep 5, 2026
68 checks passed

lusoris deleted the fix/state-md-duplicate-rows branch September 5, 2026 23:49

This was referenced Sep 6, 2026

docs(state): de-duplicate the closed T-SPEED-GPU-REGISTRY-ORPHAN row #1328

Closed

docs(state): close the stale T-CUDA-INIT-SUBMIT-LEAKS-2026-06-19 open row #1329

Closed

lusoris mentioned this pull request Sep 6, 2026

docs(state): close T-SYCL-ARC-SSIMULACRA2-PARITY-2026-06-03 (fixed by 8b7ae731a) #1332

Closed

5 of 9 tasks

This was referenced Sep 7, 2026

feat(dev): add a docs/state.md rebase-conflict resolver #1389

Merged

chore(master): release 1.0.0-rc.1 #1213

Merged

lusoris added the type:bug Something isn't working label Sep 7, 2026

Navigation Menu

Repository navigation

fix(docs): one row per bug id in state.md, and a gate that keeps it that way - #1322

fix(docs): one row per bug id in state.md, and a gate that keeps it that way#1322
lusoris merged 2 commits into
masterfrom
fix/state-md-duplicate-rows

lusoris commented Sep 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

lusoris commented Sep 5, 2026

Summary

Type

Checklist

Bug-status hygiene (ADR-0165)

Netflix golden-data gate (ADR-0024)

Deep-dive deliverables (ADR-0108)

Reproducer

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant