Scored scene-timing benchmark on the real clock

[jmjava]

Why

Past timing fixes passed unit tests (string checks on compiled source, a Python simulator) and still failed in production. Those tests never ran the compiled construct() against the real _TimedScene clock.

What

A standard corpus plus a scorer you can re-run after every clock / compile change:

docgen benchmark
# or
./scripts/benchmark-scenes.sh

No bundle, no Manim, no OpenAI. The harness execs compiled construct() with stub mobjects and the actual _TimedScene methods from BOOTSTRAP_HEADER.

Case	Role
issue66_tight_clamped	Tight words must not skip waits
issue66_tight_unclamped	Control — unclamped compile still dumps (scorer is not blind)
early_title	0.55s first label vs title Write
wide_hold	Long holds pulse more than once
emphasis_none	Author opt-out stays still
paged_slide	Slide transition does not skip the next wait
flow_edges	Grow + edge-to-edge arrow still paces
audio_tail	Last box keeps moving through a long tail

Scores are diffed against src/docgen/benchmark_data/baseline.json. Exit 1 if defect_points rise, quality_points / mid_hold_pulses fall, or the control case stops failing.

validate / generate-all preflight also execute the compiled clock when timing.json words exist (clock: issues).

After an intentional improvement: docgen benchmark --update-baseline and review the JSON diff.

Required for future changes

This is now a hard gate, not a suggestion:

• CI job benchmark in .github/workflows/ci.yml runs docgen benchmark
• tests/test_scene_benchmark.py fails if that job is removed
• AGENTS.md Required gate section + .cursor/rules/docgen-benchmark.mdc (alwaysApply: true)

Tests

• ruff check src/ tests/
• pytest tests/ -q --tb=short — 404 passed
• docgen benchmark meets the committed baseline (quality average 100; control still reports the BUG: scene-spec wait_until_word clock overshoot dumps first page then freezes (validate false green) #66 dump)

  

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.