Fail closed when a generated scenes.py label or run_time drifts from a fresh compile.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jmjava

AGENTS.md

@@ -73,7 +73,7 @@ Commands registered on the **`docgen`** CLI include:
 - **`image-generate`** — render scene-spec **image elements** (`image:` + `prompt:` boxes) via OpenAI Images or xAI Imagine into the bundle (also runs for missing assets inside `generate-all`).
 - **`manim`** — render Manim scenes declared in config.
 - **`compose`** — mux narration audio with visual sources via ffmpeg.
-- **`validate`** / **`validate --pre-push`** — drift, narration lint, Manim hints, **`timing_sync`**, **`story_end`** (last paced reveal vs audio end; hard fail), **`scene_assets`** (pre-render: stuck-board cadence, frame-budget overlaps, `MANIM_FONT` consistency, stale helpers / stale compiled class — hard fail; also a `generate-all` gate before Manim), **`av_sync`** (hard fail on `--pre-push` / `generate-all`; prefers scene-spec labels as OCR anchors), **`subject_beat_coverage`** (declarative specs vs narration topic beats; hard fail when enabled), and related visual-sync checks (`ocr_scan`, `layout`, `freeze_ratio` — hard fail on `--pre-push` / `generate-all`). Missing tesseract fails `ocr_scan` / `av_sync` / `layout` (not skip-PASS). Missing audio or an LFS pointer fails `timing_sync` and recording media gates (`stream_presence`, `av_drift`, `ocr_scan`, `av_sync`) (not skip-PASS). Missing `*.scene.yaml` fails `story_end` / `subject_beat_coverage` for `type: manim` (not skip-PASS).
+- **`validate`** / **`validate --pre-push`** — drift, narration lint, Manim hints, **`timing_sync`**, **`story_end`** (last paced reveal vs audio end; hard fail), **`scene_assets`** (pre-render: stuck-board cadence, frame-budget overlaps, `MANIM_FONT` consistency, stale helpers / stale compiled class including hand-edited generated-region labels and `run_time` — hard fail; also a `generate-all` gate before Manim), **`av_sync`** (hard fail on `--pre-push` / `generate-all`; prefers scene-spec labels as OCR anchors), **`subject_beat_coverage`** (declarative specs vs narration topic beats; hard fail when enabled), and related visual-sync checks (`ocr_scan`, `layout`, `freeze_ratio` — hard fail on `--pre-push` / `generate-all`). Missing tesseract fails `ocr_scan` / `av_sync` / `layout` (not skip-PASS). Missing audio or an LFS pointer fails `timing_sync` and recording media gates (`stream_presence`, `av_drift`, `ocr_scan`, `av_sync`) (not skip-PASS). Missing `*.scene.yaml` fails `story_end` / `subject_beat_coverage` for `type: manim` (not skip-PASS).
 - **`lint`** — narration lint helper.
 - **`narration-generate`** — LLM-assisted narration from hints and repo context; optional **`--revise --revision-notes`** for in-place edits (same contract as the wizard Revise button).
 - **`scene-spec-generate`** — LLM emits declarative **`*.scene.yaml`**; enforces frame budget + **subject-beat coverage** (dwell OK; cover topic shifts; reject invented labels).

README.md

@@ -67,7 +67,9 @@ If you still need the legacy behaviour, pin a pre-removal commit
   Missing audio or an LFS pointer fails `timing_sync` and recording media gates
   (`stream_presence`, `av_drift`, `ocr_scan`, `av_sync`) instead of skip-PASS.
   Missing `*.scene.yaml` fails `story_end` / `subject_beat_coverage` for
-  `type: manim` instead of skip-PASS.
+  `type: manim` instead of skip-PASS. A hand-edited generated-region label
+  or `run_time` in `scenes.py` fails `scene_assets` compile_sync (clock /
+  benchmark still execute a fresh `compile_scene_class`, not the on-disk file).
 - **GitHub Pages** — auto-generate `index.html`, deploy workflow, LFS rules,
   `.gitignore`.
 - **Wizard** — local web GUI to bootstrap narration scripts from existing project

src/docgen/scene_asset_validate.py

@@ -14,7 +14,9 @@
   ``MANIM_FONT``.
 * **Stale helpers / stale compile** — ``scenes.py`` still has center-to-center
   arrows or a ``_box`` that cannot take ``shape=``, or the generated class
-  no longer matches ``compile_scene_class`` (missing Indicate, old FadeIn).
+  no longer matches a fresh ``compile_scene_class`` (missing Indicate, old
+  FadeIn, hand-edited box/title label, or ``run_time``). Clock / benchmark
+  still execute that fresh compile, not the on-disk ``scenes.py``.
 """
 
 from __future__ import annotations
@@ -117,6 +119,63 @@ def _first_arg_id(call: ast.Call) -> str | None:
     return None
 
 
+def _const_value(node: ast.AST) -> object | None:
+    if isinstance(node, ast.Constant):
+        return node.value
+    return None
+
+
+def _construct_calls(source: str) -> list[ast.Call]:
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return []
+    for node in tree.body:
+        if not isinstance(node, ast.ClassDef):
+            continue
+        for item in node.body:
+            if isinstance(item, ast.FunctionDef) and item.name == "construct":
+                return [c for c in ast.walk(item) if isinstance(c, ast.Call)]
+    return []
+
+
+def generated_labels_from_source(source: str) -> list[str]:
+    """Ordered ``_box`` / ``Text`` string labels from a compiled ``construct``."""
+    labels: list[str] = []
+    for call in _construct_calls(source):
+        if _call_name(call) not in {"_box", "Text"} or not call.args:
+            continue
+        val = _const_value(call.args[0])
+        if isinstance(val, str):
+            labels.append(val)
+    return labels
+
+
+def play_run_times_from_source(source: str) -> list[object]:
+    """Ordered ``timed_play(..., run_time=)`` constants from ``construct``."""
+    times: list[object] = []
+    for call in _construct_calls(source):
+        if _call_name(call) != "timed_play":
+            continue
+        for kw in call.keywords:
+            if kw.arg != "run_time":
+                continue
+            val = _const_value(kw.value)
+            if val is not None:
+                times.append(val)
+            break
+    return times
+
+
+def _sync_fingerprint(source: str) -> tuple[list[str], list[str], list[object]]:
+    """Motion tokens plus the label / run_time text ``motion_plan`` ignores."""
+    return (
+        motion_plan_from_source(source),
+        generated_labels_from_source(source),
+        play_run_times_from_source(source),
+    )
+
+
 def motion_plan_from_source(source: str) -> list[str]:
     """Ordered reveal / dwell / wait tokens from a compiled ``construct`` body."""
     try:
@@ -242,8 +301,8 @@ def compiled_scene_sync_violations(
         expected_src = compile_scene_class(spec, words=words or None)
     except SceneSpecError as exc:
         return [f"compile_sync: cannot compile spec ({exc})"]
-    expected = motion_plan_from_source(expected_src)
-    got = motion_plan_from_source(actual)
+    expected = _sync_fingerprint(expected_src)
+    got = _sync_fingerprint(actual)
     if expected == got:
         return []
     return [

tests/test_scene_asset_validate.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import re
 from pathlib import Path
 
 import pytest
@@ -15,9 +16,11 @@
     bundle_scene_asset_violations,
     compiled_scene_sync_violations,
     dwell_overshoot_violations,
+    generated_labels_from_source,
     helper_api_violations,
     hold_idle_violations,
     motion_plan_from_source,
+    play_run_times_from_source,
     scene_asset_violations_for_segment,
 )
 from docgen.scene_spec import (
@@ -285,6 +288,67 @@ def test_compiled_sync_fails_when_class_missing() -> None:
     assert any("not in scenes.py" in i for i in issues)
 
 
+def test_compiled_sync_fails_when_generated_label_changed() -> None:
+    """Leftover #11: motion_plan ignores label text; compile_sync must not."""
+    spec = _spec([_box("Alpha", wait_word=0), _box("Beta", wait_word=1)])
+    words = _wide_words()
+    class_src = compile_scene_class(spec, words=words)
+    tampered = class_src.replace("'Alpha'", "'Hacked'", 1)
+    assert "'Hacked'" in tampered
+    assert motion_plan_from_source(class_src) == motion_plan_from_source(tampered)
+    assert generated_labels_from_source(class_src) != generated_labels_from_source(tampered)
+    issues = compiled_scene_sync_violations(spec, words, BOOTSTRAP_HEADER + "\n" + tampered)
+    assert issues
+    assert any("compile_sync" in i and "stale" in i for i in issues)
+
+
+def test_compiled_sync_fails_when_run_time_changed() -> None:
+    """Leftover #11: motion_plan ignores timed_play run_time; compile_sync must not."""
+    spec = _spec([_box("Alpha", wait_word=0), _box("Beta", wait_word=1)])
+    words = _wide_words()
+    class_src = compile_scene_class(spec, words=words)
+    tampered, n = re.subn(r"run_time=\d+(?:\.\d+)?", "run_time=9.99", class_src, count=1)
+    assert n == 1
+    assert motion_plan_from_source(class_src) == motion_plan_from_source(tampered)
+    assert play_run_times_from_source(class_src) != play_run_times_from_source(tampered)
+    issues = compiled_scene_sync_violations(spec, words, BOOTSTRAP_HEADER + "\n" + tampered)
+    assert issues
+    assert any("compile_sync" in i and "stale" in i for i in issues)
+
+
+def test_scene_assets_fails_when_generated_label_changed(tmp_path: Path) -> None:
+    """Change a generated-region label in scenes.py; scene_assets must fail."""
+    cfg = _bundle(tmp_path)
+    specs = cfg.animations_dir / "specs"
+    specs.mkdir(parents=True)
+    spec = _spec([_box("Alpha", wait_word=0), _box("Beta", wait_word=1)])
+    (specs / "01-x.scene.yaml").write_text(yaml.dump(spec), encoding="utf-8")
+    words = _wide_words()
+    (cfg.animations_dir / "timing.json").write_text(
+        json.dumps(
+            {
+                "01-x": {
+                    "text": "Alpha Beta tail",
+                    "words": words,
+                    "segments": [{"start": 1.2, "end": 16.4, "text": "Alpha Beta tail"}],
+                }
+            }
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    class_src = compile_scene_class({**spec, "timing_key": "01-x"}, words=words)
+    tampered = class_src.replace("'Alpha'", "'Hacked'", 1)
+    (cfg.animations_dir / "scenes.py").write_text(
+        BOOTSTRAP_HEADER + "\n" + tampered, encoding="utf-8"
+    )
+    issues = scene_asset_violations_for_segment(cfg, "01")
+    assert any("compile_sync" in i and "stale" in i for i in issues)
+    check = Validator(cfg)._check_scene_assets("01")
+    assert not check.passed
+    assert any("compile_sync" in d for d in check.details)
+
+
 def test_layout_budget_is_reported_as_overlap(tmp_path: Path) -> None:
     cfg = _bundle(tmp_path)
     specs = cfg.animations_dir / "specs"