Stage 8 exit audit: close three criteria gaps, three stale documents

[AdamClemens]

Stage 8's end-of-stage exit audit, and the fixes it produced.

make ci was green throughout — 1200 tests, 144 scenarios, 99% coverage — and three of the nine Completion Criteria were marked Met against checks that did not test what the criterion said. None needed judgement to find; each is a sentence the criterion had already written down. This is docs/practices.md's own "An exit audit reads each criterion to its last sentence", recurring on the one stage whose previous audit is why Criteria 6-9 exist at all.

The three criteria gaps

Criterion	What it said	What checked it
6	"A keyboard seek and a mouse drag each change window.renderer.snapshot()'s content"	Neither scrub test calls snapshot(); both assert on PlaybackState.position, and one's docstring says so
8	"Checked directly against a real multi-hundred-frame pyflow record run"	The CLI test used --max-frames 20; TASK-049's by-hand check used 25
1	Recording "imports neither rendering nor anything that transitively imports it"	The criterion's own text admits this "was checked by hand at implementation time"

All three were true; none were gated. Each fix is mutation-tested.

The part worth reading

The Criterion 6 pair took three attempts, and the second one is the useful finding:

1. "The pixels changed after seeking" — worthless. The scrub thumb moves with the index, so any seek repaints something whether or not the field was rebuilt.
2. "A seek-reached frame matches an autoplay-reached frame at the same index" — the obvious repair, and it passed against a deliberately frozen field. Both sides of the comparison came from the same run, so freezing the field froze the reference too.
3. What works: the reference comes from a separate play() window launched at the target frame (where that frame is index 0, drawn by the initial scene build, never by the seek path), compared over the field region only, cropping away the scrub bar. Both halves then fail correctly — against a frozen field, and against an off-by-one field, checked separately.

Recorded as a standing rule in docs/practices.md: a reference the run under test produced proves consistency, not correctness.

Stale documentation, all in files no Stage 8 task opened

• docs/architecture/CLAUDE.md said Stage 8 was complete with "all five" criteria met — falsified two days after it was written by the reopening that added four more.
• docs/repository-manifest.md said TASK-046/047 were "still unbuilt" — stale from the day it was written, since both landed alongside the TASK-045 the same sentence credits.
• docs/architecture/sequences.md (Checked-by: stage-boundary) described only TASK-045/046/047, and still said playback had "no declared-field/scalar-colormap path yet" two days after TASK-051 built exactly that. All four reopening tasks landed without it being touched. Its Maintenance section now records why a task anchor cannot reach a task the file has never named.

Also

• pyflow play --help documented none of the controls the subcommand exists for — pause, speed, scrub. README was the only place to find them. Now in the epilog, pinned by a test, including the line saying seeking stops at the loaded window.
• Linux CI never ran the live-window tests. No DISPLAY, no xvfb, so all 8 display-guarded tests — every check Criterion 6 rests on — skipped there while passing on Windows. A green two-platform matrix was proving live-window behaviour on one platform. Now run under xvfb-run. This is the one change in this PR I could not verify locally; watching the Linux job is the point of the PR.
• 19 stray checkpoint_*.pt from a 2026-09-07 manual run removed from the repository root; .gitignore widened to match the files, not only the default directory.

Deliberately not done

The Goal's "scrubbed to any point" is still satisfied only within the window one pyflow play invocation loads. The maintainer was asked at the audit and chose to defer. That is now recorded as a standing exclusion under Criterion 6 — where a decision goes — rather than in a task's Design decisions, where it was hiding. Building it needs a new task and a new criterion, not a quiet widening of Criterion 6.

1200 → 1209 tests. make ci green locally.

🤖 Generated with Claude Code