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, and still doesn't — I tried twice and reverted both attempts. No DISPLAY, no xvfb, so all 10 display-guarded tests — every check Criterion 6 rests on — skip on Linux and run only on Windows.
  • xvfb worked and was flaky. Linux skips went 29 → 18, matching a local run, so all 10 genuinely ran. But across three attempts on identical test code, two passed and one crashed an xdist worker with no Python traceback (GLFW aborts the process rather than raising) — and that attempt then passed on a plain re-run. A third of attempts failing, on a gating check.
  • Serialising them onto one worker (--dist loadgroup) was worse. It hung the Windows job for 5h45m until GitHub's 6-hour limit killed it, at 95% with ~6 tests outstanding and an orphaned python process at cleanup. It passed make ci locally in 183s, so nothing short of CI could have caught it.
  • Both point the same way from opposite directions: one raised concurrent window creation across processes, the other raised sequential creation within one process. What has always worked is 1–2 GLFW windows per process spread across workers, so a real fix has to reduce the window count rather than redistribute it. That's a task, not a polish item — it's now a backlog entry carrying both measurements, with the same warning in tests/integration/CLAUDE.md and the workflow itself.
  • CI is therefore back to exactly its prior behaviour. Criterion 6 is met; its evidence runs on one of the two platforms CI covers, and the roadmap says so rather than leaving it looking closed.
• 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