Research-0086: `docs/state.md` audit + backfill — 2026-05-08¶

Authors: Claude (Anthropic), Lusoris
Date: 2026-05-08
Tags: state-hygiene, audit, claude-rule, fork-local
Related: ADR-0165, CLAUDE.md §12 r13, Issue #20

TL;DR¶

Audited docs/state.md against the last 30 days of merged PRs (2026-04-08 — 2026-05-07, 80+ merged PRs). Per CLAUDE.md §12 r13 every PR that closes / opens / rules-out a bug must update docs/state.md in the same PR; the rule is reviewer-enforced, not CI-enforced.

Drift summary:

4 missing closure rows — bug-fix PRs that did not touch docs/state.md and are unambiguously in scope per ADR-0165.
3 stale rows — duplicate Netflix#955 entries (line 100 + 103), a stray |---|---|---|---| separator (line 102) breaking the Deferred-external-trigger table, and a "Deferred dataset access" row with TRIGGERED 2026-04-29 content sitting in the wrong section (should have moved to "Recently closed" or been retired).
2 needs-maintainer-disposition — items where the closure section / row text is ambiguous without owner context.

Most surprising drift: T-VK-1.4-BUMP is double-listed — present in Open bugs (line 29, since PR #346 partially closed Step A) and in Deferred (external trigger) (line 101). The Deferred row was added by PR #338 (2026-05-04) but never moved / deleted when PR #346's Step A landed and the row migrated to Open bugs by PR #346. The two rows tell contradictory stories about the same backlog item.

This audit + backfill is itself an in-PR exercise of CLAUDE.md §12 r13 — the audit row gets recorded so the next session does not have to re-derive it.

Method¶

PR punch list (last 30 days):

gh pr list --state merged --limit 200 --search "merged:>=2026-04-08" \
  --json number,title,mergedAt,body,files --jq '...'

state.md touch detection: cross-referenced each candidate PR's .files[].path against docs/state.md. PRs that did not touch state.md and whose body did not carry a no state delta: REASON opt-out were flagged.
Existing-row staleness audit: read each row in state.md; verified linked PRs / commits resolve, checked for duplicate bug IDs across sections, looked for table-rendering damage.
ADR cross-reference: every docs/adr/ row whose body says "fixes issue #X" or "closes Netflix#Y" was checked against state.md. Recent ADR-0309 / 0319 / 0321 chain (ensemble LOSO trainer + production flip) was already covered by the row PR #424 added at line 46.

Missing rows (PR-derived gaps)¶

PR	Title	Suggested section	Why missing
PR #391 (`fix(cuda): idempotent motion flush_fex on last frame`)	Recently closed	CUDA backend correctness bug — produced user-visible `libvmaf WARNING feature "VMAF_integer_feature_motion2_score" cannot be overwritten at index N` + `context could not be synchronized` on the last frame after PR #312 (T-GPU-OPT-1) reordered `flush_context_cuda`. Real regression introduced by a fork commit; ADR-0165 §Scope ("numerical-correctness / runtime / build defects") clearly applies. PR body has no `no state delta` opt-out.	merged 2026-05-05, ADR-bypass exemption: bug-fix only, no ADR per CLAUDE §12 r8
PR #389 (`fix(vmaf-tune): decode mp4 -> raw YUV in corpus score path`)	Recently closed	Phase A corpus pipeline (ADR-0237) was emitting `vmaf_score=NaN` + `exit_status=234` on every encoded clip — `run_score` handed `.mp4` directly to libvmaf CLI which only accepts raw YUV / Y4M. User-visible bug (every Phase A corpus row was unusable).	merged 2026-05-05; PR body has no `no state delta` opt-out
PR #390 (`fix(build,cuda): nvcc --std c++20 for gcc-16 host libstdc++`)	Recently closed	Build-time bug: every `.cu` failed to compile on dev hosts with gcc 16.x because nvcc's default C++17 host parser chokes on gcc 16's libstdc++ headers (`char8_t` undefined). Hosted CI runners on Ubuntu 24.04 + gcc 13 don't trip it, so the fix is silent on CI but affects every local CUDA build on a current rolling distro. ADR-0165 §Scope covers build defects.	merged 2026-05-05; no `no state delta` opt-out
PR #234 (`fix(ffmpeg-patches): dynamically load vkGetDeviceQueue (VK_NO_PROTOTYPES)`)	Recently closed	FFmpeg `vf_libvmaf` build break against `release/8.1` whenever libvmaf is built with Vulkan: `libvmaf.pc` exports `-DVK_NO_PROTOTYPES` and FFmpeg's build inherits it through pkg-config, suppressing `vkGetDeviceQueue` prototypes. Every fork-built FFmpeg + Vulkan failed to link. Real user-facing bug for the FFmpeg-integration path.	merged 2026-05-01; body called itself a "trivial CI fix" but the bug-class is build defect, not infra

Stale rows¶

Issue	Location	Suggested fix
Duplicate Netflix#955 entries	line 100 + line 103	The Deferred-external-trigger section has Netflix#955 listed twice — line 100 is the original entry; line 103 is a near-clone added by PR #352's 2026-05-03 refresh that updated the "last checked" stamp but didn't delete the original. Keep line 103 (carries the freshest `last checked 2026-05-03 — Netflix#1494 still state=OPEN` stamp); delete line 100.
Stray separator row mid-table	line 102 (`\\|---\\|---\\|---\\|---\\|`)	An extra Markdown table separator slipped in between the T-VK-1.4-BUMP deferred row and the duplicate Netflix#955 row. Most renderers will close + re-open the table at that boundary, breaking visual continuity. Delete the line.
T-VK-1.4-BUMP double-listed	line 29 (Open bugs) + line 101 (Deferred external trigger)	Same backlog item in two sections telling contradictory stories. Line 29 (Open bugs, post PR #346 Step A) is the current story; line 101 (Deferred-external, pre PR #346) was correct when added by PR #338 but should have moved when PR #346 promoted the item from Deferred to Open. Delete line 101 (the Deferred-external clone); the Open-bugs row at line 29 already cites the same ADR-0264 + research-0053 evidence and adds the post-Step-A residual-tail context.
Dataset-deferred row with TRIGGERED-but-still-listed semantics	line 36 (Deferred dataset access — Tiny-AI C1 baseline)	Row text says "TRIGGERED 2026-04-29 — dataset is locally available at `.workingdir2/netflix/`… T6-1a unblocked; training pipeline ready when scheduled." A triggered defer should have moved to Recently closed or been retired entirely; sitting in Deferred misleads future sessions into thinking it's still gated. Flagged for owner decision (see below) since the closure section depends on whether C1 baseline has actually trained.

Needs maintainer disposition¶

Item Why ambiguous

C1 baseline (T6-1a) defer-row triggered but still-listed (state.md line 36) The trigger fired (dataset is locally available) but the row says "training pipeline ready when scheduled" — i.e. the unblock is real, the actual baseline-train has not run yet. Closure section depends on owner intent: (a) baseline trained → move to Recently closed; (b) baseline still queued → drop the "Deferred (dataset access)" framing entirely and just leave the BACKLOG T6-1a row to track the work, since the dataset gate is gone. Not safe to backfill without owner direction — could land in either Recently-closed or Open.

Should pure upstream-port PRs (#301, #302, #303, #315) get state.md rows? PR #301 / #302 / #303 / #315 are pure Netflix/vmaf cherry-picks of upstream bug fixes (integer_motion dict leak, x86/adm 32-bit clang, libvmaf/predict chroma_from_luma correction, integer_vif vif_skip_scale0). None landed a state.md row. Per ADR-0108 upstream-sync clause they are exempt from the six deep-dive deliverables — but ADR-0165 itself does not carve out an upstream-port exemption. Convention question: do these belong in "Confirmed not-affected" (we don't track Netflix-side bugs since they're upstream's ledger), or "Recently closed" (the fork inherited the fix, so future sessions might want to know which upstream commit / fork PR landed it)? Flagged for owner — consistent treatment matters more than which way it goes.

Backfill applied in this PR¶

The four Missing rows items above are all unambiguous. Backfill lands a row each in "Recently closed":

PR #391 — CUDA motion duplicate-write warning regression
PR #389 — vmaf-tune Phase A corpus NaN scoring
PR #390 — CUDA build break on gcc-16 host libstdc++
PR #234 — FFmpeg vf_libvmaf build break under VK_NO_PROTOTYPES

Stale-row fixes applied:

Delete duplicate Netflix#955 row (keep newer line 103, delete older line 100).
Delete stray |---|---|---|---| separator at line 102.
Delete the T-VK-1.4-BUMP duplicate at line 101 (Deferred section); Open-bugs row at line 29 is the canonical version.

Stale-row fixes not applied (deferred to maintainer disposition):

The Tiny-AI C1 baseline T6-1a "TRIGGERED" row at line 36 stays put — auditor cannot confirm whether the baseline has trained vs. is still queued.

Assumptions, limitations, future work¶

30-day window: only PRs merged 2026-04-08 — 2026-05-07 audited. Older PRs are by ADR-0165 design rolling off into git log. A future audit may want to sweep the older "Recently closed" rows to roll off any past-90-day entries.
Title heuristic: PRs without fix|bug|... in the title that nonetheless closed a bug may have escaped detection. The body scan partially compensates but is not exhaustive.
Reviewer-enforced rule: the underlying drift exists because CLAUDE.md §12 r13 has no CI gate. Backlog idea: a scripts/ci/ state-md-touch-check.sh that flags PRs whose title-class is bug-fix and that don't touch docs/state.md (with explicit no state delta: REASON opt-out parsed from the body).

References¶

ADR-0165 — the rule.
CLAUDE.md §12 r13 — same rule, different surface.
Issue #20 — original ask (closed 2026-04-19 with the request paraphrased in ADR-0165 §Context).
req — user direction 2026-05-08 (paraphrased): conduct audit of state.md drift, surface missing rows from recent PRs, apply unambiguous backfills, flag ambiguous cases for disposition.

Research-0086: docs/state.md audit + backfill — 2026-05-08¶