Skip to content

Official Codebase of 3DCodeVerse

Python

docs: the 2026-08-26 backend code review — 19 verified findings, an ordered cleanup plan, and what to leave alone

gaoypeng2242282a8aa9
diff --git a/harness/docs/REVIEW_2026-08-26.md b/harness/docs/REVIEW_2026-08-26.md
new file mode 100644
index 00000000..90306490
--- /dev/null
+++ b/harness/docs/REVIEW_2026-08-26.md
@@ -0,0 +1,497 @@
+# Harness backend — reorganisation plan
+
+Scope: `~/3dcodeverse/harness` (`codeverse/`, `bench/`, `runtime_js/`, `tests/`, `docs/`).
+Inputs: 19 verified findings (each survived an adversarial re-check), 1 refuted, 28 unverified,
+four reader do-not-touch lists, the god-file inventory. Every item below cites the verdict's
+evidence, not the original claim; where the verdict narrowed a proposal, the narrowed version is
+what is written here. All line numbers are as of 2026-08-26.
+
+## 1. Verdict
+
+The codebase is in good shape for its age: the seven laws are visibly enforced (typed contracts,
+`TRACK_INFO` as single source, the `_<family>.py` shared-helper pattern, a test that pins the
+package map to `docs/ARCHITECTURE.md`), and almost every oddity a reviewer flags turns out to
+carry a dated measurement or an ADR — of ~1,000 removable lines, fewer than 300 are in
+production paths; the rest is stranded scaffolding. The real mess is **wave residue**: things
+built in parallel that were never reconciled once the siblings landed — a second HTML gallery
+(`flywheel/gallery.py`) that the CLI already abandoned, `call_adaptive` silently dropping
+kwargs to signatures that now exist, a compat shim with its own delete-me TODO, a headless
+Blender renderer with zero callers, a `material_pass` no command runs, and the same tolerant
+JSON/JSONL read loop written eight times because `proc.py` never grew the helper. What is NOT
+mess despite the look: `storm.py` shipped OFF, `cost/caching.py`'s measurement-only helpers,
+`budget.charge/add` both forwarding to `spend`, the StopPolicy ordering, `plan_features.py`'s
+dead switch, the wrapper helper twins under `languages/*/wrappers` (Blender's python cannot
+import `codeverse`), and `tracks/common.Services` forwarders — every one is a documented,
+measured decision (see §3), and the one "duplication" finding that targeted a documented corpus
+definition (`complexity_report.iter_runs`) was refuted for exactly that reason.
+
+## 2. The plan (ordered: low-risk deletions → shared helpers → behaviour-touching dedupes → package moves)
+
+Convention: **T** = the exact command that must be green before and after. Unless stated, run
+with `-p no:cacheprovider -m "not live"`. After every deletion item also run `ruff check codeverse bench`
+(F401 orphans are called out per item). Items marked **[land together]** share a file or a helper.
+
+### Wave A — pure deletions (no behaviour change, no new code)
+
+**A1. Delete nine dead public defs** · `dead-public-defs` · risk low · ~−45 LOC
+- Files: `codeverse/cli/_common.py:121-124` (`echo_json`), `codeverse/judges/images.py:55-66` (`view_label`),
+ `codeverse/gallery/labels.py:82-91` (`verdict_label/verdict_class/verdict_title`), `codeverse/gallery/paths.py:46`
+ (`is_inside`), `codeverse/gallery/server.py:383-387` (`free_port`), `bench/report.py:183-184` (`report_dict`),
+ `codeverse/flywheel/gallery.py:239-240` (`gallery_dict` — whole file goes in D2; delete now or then),
+ `bench/run_bench.py:162-164` (`_select`), `bench/run_bench.py:177-178` (`_default_run`),
+ `tests/compare_bench/test_bench_shared.py:33` (drop the `rb._select(...) ==` assertion; line 34 keeps the test's meaning).
+- Why: extension-agnostic grep over the whole tree plus `dataset/`/`finetune/` finds each name only at its def;
+ `cards.py:49`, `page.py:40`, `compare.py:136` index `VERDICT_META` directly; `serve()` handles `--port 0` via
+ `httpd.server_address[1]` so `free_port`'s docstring is stale; none is in a `__all__`, entry point or doc.
+- Fallout: drop now-orphaned `socket` in `gallery/server.py`, `Any` in `bench/report.py` if ruff flags them.
+- T: `python -m pytest tests/gallery/test_server.py tests/gallery/test_triage.py tests/compare_bench/test_bench_shared.py -q` (62 passed today).
+
+**A2. Delete six dead track/orchestrator helpers** · `tracks-dead-helpers` · risk low · ~−24 LOC
+- Files: `codeverse/tracks/static_object.py:447-449` (`refine_task_lines` + the empty `# --- helpers` marker),
+ `codeverse/tracks/graphics_steps.py:180-181` (`refine_lines`), `codeverse/tracks/steps.py:484-486` (`describe_round`),
+ `codeverse/tracks/lifecycle.py:713-714` (`generator_label`), `codeverse/tracks/scene_asset_gen.py:330-332`
+ (`asset_variant_call`), `codeverse/orchestrator/runner.py:129-134` (`StageRunner.invalidate`).
+- Why: `grep -w` over codeverse/tests/bench/docs/runtime_js/scripts returns only the def lines; `runner.py:97`'s own
+ comment says "invalidate has no caller and no flag"; the two inline `[t.line() for t in tasks]` callers
+ (`lifecycle.py:286`, `graphics.py:126`) never used the helpers.
+- Fallout (ruff F401): remove `Sequence` import `graphics_steps.py:14`, `Any` from `steps.py:28`, `is_single_shot`
+ from `lifecycle.py:54`. Reword `runner.py:92-98` so it no longer names `invalidate`.
+- T: `python -m pytest tests/orchestrator_tracks tests/core -q` (345 passed today) + `ruff check codeverse`.
+
+**A3. Delete five dead cost helpers** · `cost-dead-helpers` · risk low · ~−23 LOC
+- Files: `codeverse/cost/ledger.py:387-388` (`totals_by`), `codeverse/cost/types.py:55-56` (`FREE_STAGES`),
+ `types.py:267-269` (`Summary.share`), `types.py:272-280` (`usage_to_tokens`) **and** its now-orphaned
+ `from codeverse.contracts.common import Usage` at `types.py:17`; `codeverse/cost/audit.py:223-224` (`audit_dir`)
+ plus its import/`__all__` entry at `cost/__init__.py:20,89`.
+- Why: whole-tree grep incl. quoted/getattr forms hits only the defs; `report.py:48/131/135` computes the share
+ inline. Keep the `Stage` members SKELETON/ASSEMBLE/GATES/RENDER (used by `report.STAGE_ORDER`,
+ `audit.stage_latency`); move the "kept so latency can be attributed" note onto those members.
+- T: `python -m pytest tests/cost tests/install/test_docs.py -q` (136 passed today).
+
+**A4. Delete five dead/test-only spatial defs and their tests** · `spatial-dead-and-test-only-twins` · risk low · ~−85 LOC
+- Files: `codeverse/spatial/tool_common.py:40-47` (`unavailable_obs`, + its `__all__` entry at :27; keep the
+ `#: ToolUnavailable now lives in registry` comment), `codeverse/spatial/frame_stats.py:181-183` (`stats_table`),
+ `runtime_js/lib/census.mjs:74-77` (`hasNonFinitePositions`), `codeverse/spatial/render_scene.py:299-334`
+ (`frame_table`), `codeverse/spatial/silhouette.py:257-287` (`silhouette_series`);
+ tests: delete `tests/scene_runtime/test_render_scene.py:209-235` (two `frame_table` tests) and
+ `tests/spatial_tools/test_silhouette.py:61-68` (`test_series_picks_best_view`) + the import at :9.
+- Why: zero callers by grep; the production twins are already tested directly — `frame_summary_text`
+ (`tests/scene_gates/test_frame_metrics.py:143-149`), `best_view_match` (`tests/reference/test_silhouette_best_view.py:31-51`),
+ `metrics_path_for` (`tests/scene_gates/test_judge_views.py:58-81`). No retargeting needed.
+- T: `python -m pytest tests/scene_runtime/test_render_scene.py tests/spatial_tools/test_silhouette.py tests/scene_gates/test_frame_metrics.py tests/reference/test_silhouette_best_view.py -q` (verdict could not run these — run before deleting).
+
+**A5. Delete the standalone `render_bpy.py` renderer** · `languages-two-blender-renderers` · risk low · ~−200 LOC
+- Files: delete `codeverse/languages/blender/wrappers/render_bpy.py`, the `RENDER_WRAPPER` constant
+ (`codeverse/languages/blender/runtime.py:34`), and `tests/blender_cadquery/test_blender_runtime.py::test_live_native_render` (:160-167).
+ **Keep** `urdf/wrappers/render_glb_bpy.py` + `spatial/joints_export.blender_render_glb` (public in
+ `spatial/joints.__all__`, the only non-three.js `Renderer` impl, documented in `urdf/__init__.py:5`).
+- Why: `RENDER_WRAPPER` referenced only by that one blender-marked test; no CLI/track/doctor/prompt reaches it;
+ `docs/INSTALL.md:87` states there is no Blender-render fallback by design; camera math at
+ `render_bpy.py:154-157` is token-identical to `render_glb_bpy.py:75-81`.
+- T: `python -m pytest tests/blender_cadquery/test_blender_runtime.py tests/urdf_joints/test_live_blender.py tests/install/test_docs.py -q -p no:cacheprovider` (needs `~/.local/bin/blender-5.0`; not run by the verifier).
+
+**A6. Delete `material_pass` and collapse `_verify`** · `texturing-dead-material-pass` · risk low · ~−95 LOC · **[land together with A7]**
+- Files: `codeverse/texturing/normalise.py:241-324` (`MATERIALS_GLB`, `MaterialPassReport`, `material_pass`,
+ `_gate_judge`), `__all__` at :327-328, docstring :22-24 (it still promises `artifacts/object_materials.glb` +
+ a judge gate; real output is `textures/object_normalised.glb` inside `texture_pass`, `run.py:218`);
+ replace `normalise._verify` body (:227-238) with `return verify_textured_glb(glb_in, glb_out, expected_textured=0)`
+ (only delta: GlbLoadError now carries the "textured GLB verification failed" prefix).
+- Why: grep for the names and their string forms (`material.normalised`, `materials_gate`, `object_materials`)
+ hits only normalise.py; `texture_cmd.py` exposes pass/show/scene-pack only; `_gate_judge` is `run._make_judge`
+ minus a log line; the two `_verify` checks are byte-identical f-strings to `apply.verify_textured_glb:187-208`.
+- Do NOT touch the `judge=<object>` shim at `run.py:188-191`: `tests/texturing/test_run.py:81-88` pins it as a
+ one-wave deprecation window. Retiring it is a policy call (delete shim + those 8 test lines together).
+- T: `python -m pytest tests/texturing/test_normalise.py tests/texturing/test_apply.py tests/texturing/test_run.py -q` (not run by the verifier).
+
+**A7. Delete the unshipped `cookbook_block`** · `texturing-two-family-tables` (narrowed) · risk low · ~−65 LOC
+- Files: `codeverse/texturing/materials.py:336-396` (`_HEAD`, `cookbook_row`, `cookbook_block`) + `__all__`;
+ fix docstring :20-21 ("used three ways" → two) and the dangling "see not_done" at :363;
+ delete `tests/texturing/test_materials.py:99-105` and the `cookbook_block` import at :11.
+- Why: only caller is that shape test; no prompt/cookbook/`prompts/__init__` imports `texturing.materials`;
+ no `not_done` file exists anywhere. Brings materials.py from 436 to ~375 lines (Law 4).
+ **The resolver-merge half of this finding was refuted** — `plan.family_from_text` (11 coarse tile families,
+ VLM schema + tile sizes) and `materials.family_for` (20 fine PBR families, substrate×finish) have different
+ output domains, `COARSE_TO_FINE` is non-injective, and a merge flips 128/185 keyword outcomes incl. the
+ test-pinned `family_from_text("oiled") == "other"`. Leave both tables.
+- Alternative (behaviour change, needs judge A/B): wire `cookbook_block()` into the blender/threejs cookbook.
+- T: `python -m pytest tests/texturing/test_plan.py tests/texturing/test_materials.py tests/texturing/test_normalise.py -q` (36 passed today).
+
+**A8. Delete three legacy re-export shims** · `tracks-dead-legacy-reexport-shims` · risk low · ~−20 LOC
+- Files: `codeverse/tracks/common.py:237-247` (`__getattr__` + `_PROMPTING`), `codeverse/tracks/static_object.py:33`
+ (`MAX_SKELETON_CHARS # noqa: F401`), delete `codeverse/orchestrator/fanout.py`; redirect
+ `tracks/steps.py:36`, `tracks/candidates.py:38`, `tracks/scene.py:41`, `tracks/scene_assets.py:33`,
+ `tests/orchestrator_tracks/test_orchestrator.py:17` to `from codeverse.fanout import fan_out, split_results`.
+- Docs: **move** the `fanout.py` token from the orchestrator row (`docs/ARCHITECTURE.md:145`) to the top-level
+ `codeverse/` row (~line 85, beside `proc.py`) — dropping it alone fails
+ `tests/install/test_docs.py::test_architecture_package_map_covers_every_module`. Drop the "(lazy re-exports keep
+ old imports working)" parenthetical at `docs/INTERFACES.md:334` and "fan-out" from `orchestrator/__init__.py`'s docstring.
+- Why: no importer pulls any of the 12 prompting names via `tracks.common`; `MAX_SKELETON_CHARS` is used only in
+ `prompting.py`; the shim forwards identical objects; judges/cost/bench already import `codeverse.fanout`.
+- T: `python -m pytest tests/orchestrator_tracks tests/install/test_docs.py tests/prompts -q` (243 + 50 passed today).
+
+**A9. Delete the `gl_build` shim** · `languages-gl-build-shim` · risk low · ~−13 LOC
+- Files: delete `codeverse/languages/glsl_shader/gl_build.py`; flip `codeverse/tracks/graphics.py:22`,
+ `codeverse/tracks/graphics_steps.py:22`, `tests/graphics/test_track.py:21` to `codeverse.languages._gl_common`;
+ in `tests/languages/test_gl_common_entry.py` delete only `test_gl_build_shim_reexports_gl_common` and the
+ `gl_build` name in the :7 import (keep the other three tests); `docs/ARCHITECTURE.md:100` → "glsl_shader/ (wrap.py header+line-map)".
+- Why: the file is a 7-line `import *` with its own "TODO: delete this shim"; spatial already imports `_gl_common`
+ directly (`tool_common.py:215`); nothing monkeypatches via the tracks binding.
+- T: `python -m pytest tests/graphics tests/languages tests/spatial_tools tests/install/test_docs.py -q` (43 passed today on the subset).
+
+### Wave B — one shared helper replaces N copies (mechanical, behaviour-preserving)
+
+**B1. `BoundedCache[T]` in `models/parts.py`** · `models-dup-lru-cache` · risk low · ~−22 LOC
+- Files: `codeverse/models/gemini_convert.py:39-63` (`_SignatureCache`), `codeverse/models/anthropic_convert.py:65-89`
+ (`_ThinkingCache` — the finding's 301-325 citation is wrong, file is 242 lines), new class in `codeverse/models/parts.py`.
+- What: `put(key, value)` (skip falsy; locked `move_to_end` + `popitem(last=False)` loop), `get(key) -> T | None`.
+ `SIGNATURES: BoundedCache[bytes] = BoundedCache(4096)`; `THINKING_BLOCKS: BoundedCache[list[dict]] = BoundedCache(2048)`
+ and `anthropic_convert.py:138` becomes `list(THINKING_BLOCKS.get(id) or []) + blocks` to keep the copy/empty-default
+ semantics. Keep the names — `tests/models/test_gemini.py:24`, `tests/models/test_anthropic.py:21` import them.
+- Why: identical `__init__/put/get` bodies; D23 justifies the cache, not two copies; `parts.py` is "shared by the provider backends" (ARCHITECTURE:87).
+- T: `python -m pytest tests/models/test_gemini.py tests/models/test_anthropic.py -q` (39 passed today).
+
+**B2. `proc.read_json_or_none`** · `tolerant-read-json-copies` · risk low · ~−25 LOC · **[land together with B3 — both edit `proc.py` and ARCHITECTURE:85]**
+- Add to `codeverse/proc.py` (stdlib-only, 164 lines): `read_json_or_none(path, *, errors=None) -> dict | None`
+ (None on OSError/ValueError or non-dict top level).
+- Replace: `codeverse/flywheel/telemetry.py:303-308`, `bench/complexity_report.py:58-62` (`_read_json` — keep a
+ 1-line alias, `tests/flywheel_cli/test_complexity_record.py` references it via `CR`), `codeverse/gallery/index.py:198-202`
+ and `:259-263` (`or {}`), `codeverse/cli/main.py:741-748`, `codeverse/runlock.py:62-65`,
+ `codeverse/languages/threejs/lint.py:157-162`, `codeverse/cost/reconstruct.py:49-54` (`errors="replace"`);
+ `codeverse/spatial/_render_common.py:43-50` becomes `return read_json_or_none(path) or {}`;
+ `codeverse/cli/_judge.py:50-57` → `data = read_json_or_none(ws.plan_path); return plan_digest(data) if data else ""`.
+- **Leave strict**: `judges/calibration._read_json:156` (a corrupt calibration input must raise) and `Workspace.read_json`.
+ `_judge.py:123-127` keeps its try (it also guards `model_validate`).
+- Why: the verifier found eight copies, not seven, and three existing helpers of the same shape; `proc.py` is
+ the documented "atomic-JSON primitives shared by languages/spatial/cli" home with no codeverse imports.
+- T: `python -m pytest tests/flywheel_cli/test_run_layout_cli.py tests/gallery/test_index.py tests/flywheel_cli/test_complexity_record.py tests/judges/test_calibration.py tests/spatial_tools/test_render_common.py tests/core/test_runlock.py tests/cost/test_reconstruct.py -q` (70 passed today).
+
+**B3. `proc.iter_jsonl_lines` / `read_jsonl_lenient` / `append_jsonl_line`** · `core-inconsistent-jsonl-io` · risk low · ~−30 LOC
+- Add to `codeverse/proc.py`: `iter_jsonl_lines(path) -> Iterator[tuple[int, str]]` (missing file → nothing,
+ `read_text(encoding="utf-8", errors="replace")`, skips blanks); `read_jsonl_lenient(path, *, log=None, dicts_only=False)`;
+ `append_jsonl_line(path, rec, lock)` (`json.dumps(ensure_ascii=False, default=str)` + newline under lock).
+- Readers → `read_jsonl_lenient`: `codeverse/events.py:44-50`, `codeverse/cost/reconstruct.py:57-70` (dicts_only),
+ `codeverse/flywheel/trajectories.py:118-127`, `codeverse/cli/skills_cmd.py:132-136`,
+ `codeverse/agents/transcript.py:80-83` (becomes tolerant; its only caller is `tests/agents/test_cli_common.py:139`).
+ `cost/ledger.load_ledger:358-365` and `bench/_jsonl.read_jsonl` keep `model_validate_json(line)` but iterate via `iter_jsonl_lines`.
+- Writers → `append_jsonl_line`: `events.py:28-31`, `transcript.py:69-72` only. **Leave `CostLedger.append`
+ (`ledger.py:79-88`)** — mkdir + flush + OSError-swallow is a different, documented contract ("flushed on write").
+- Update `docs/ARCHITECTURE.md:85` to list the new names.
+- T: `python -m pytest tests/core/test_events.py tests/cost/test_ledger.py tests/cost/test_reconstruct.py tests/agents/test_cli_common.py tests/core/test_proc.py tests/skills/test_hook.py tests/install/test_docs.py -q` (not run by the verifier).
+
+**B4. `cli_common.invoke` for the four CLI agent backends** · `agents-dup-cli-invoke` · risk low · ~−35 LOC
+- Files: `codeverse/agents/cli_common.py` (+`IDLE_GRACE_S = 300.0`, `invoke(...)`, `watchdog_error(proc)`);
+ callers `claude_code.py:155-173`, `codex.py:171-192`, `antigravity.py:163-184`, `gemini_cli.py:216-244`; drop the
+ four per-module `IDLE_GRACE_S` (claude_code:43, codex:37, antigravity:45, gemini_cli:55).
+- Signature: `invoke(s, argv, env, *, prompt, stdout_name="stdout.json", on_stdout=None, stdin=None, attempt=1,
+ idle_grace_s=None, **invoke_extra) -> CompletedProc` — masks the prompt in the 'invoke' line, forwards
+ `invoke_extra` (gemini's `model`/`key_tail`, codex's stdin flag), reads `cli_common.IDLE_GRACE_S` at call time,
+ writes `stdout{suffix}.<ext>` / `stderr{suffix}.log` with suffix `''` or `.{attempt}`.
+- Must keep: `tests/agents/test_gemini_cli.py:143` monkeypatches `codeverse.agents.gemini_cli.IDLE_GRACE_S` → retarget
+ to `cli_common.IDLE_GRACE_S`; `test_gemini_cli.py:92/107` assert `key_tail` on invoke lines; `test_codex.py:99/127` assert `stdout.jsonl`.
+- Why: the four blocks are the same expression set verbatim (argv mask, watchdog kwargs, file writes, error line);
+ `cli_common.py` is documented as "shared plumbing for subprocess backends" and stays under 400 (297+~30).
+ Tests run real fake binaries through the real watchdog (`tests/agents/conftest.py:23`), which is strong coverage.
+ `bench/_oneshot.py` and `api_tools.py` stay — different shapes.
+- T: `python -m pytest tests/agents/test_claude_code.py tests/agents/test_codex.py tests/agents/test_antigravity.py tests/agents/test_gemini_cli.py tests/agents/test_cli_common.py -q` (not run by the verifier).
+
+**B5. Kill `render.render_scene` forwarder and `call_adaptive`** · `spatial-forwarders-and-call-adaptive` · risk low · ~−30 LOC
+- (a) Delete `codeverse/spatial/render.py:241-253`, the :28 import, `__all__` entry :256, docstring line :8;
+ point `tracks/common.py:98`, `cli/main.py:578`, `spatial/tools_scene.py:98` at `codeverse.spatial.render_scene`;
+ delete vestigial `tests/threejs_render/test_render.py:39-45`; retarget the monkeypatch at
+ `tests/core/test_cli_render_size.py:54` to `codeverse.spatial.render_scene.render_scene`; fix `docs/INTERFACES.md:212`
+ (it already documents the real signature with `bounds=`/`sheet_max_views=` the forwarder never accepted).
+- (b) Replace all **five** `call_adaptive` sites with direct calls: `tools_scene.py:55` (drop phantom `n_samples=`,
+ `round_index=`), `:70` and `:78` (drop `round_index=`), `:109`, `tools.py:119`, `tool_common.py:194`; delete
+ `call_adaptive` (`tool_common.py:62-75`) + `__all__` entry + unused `inspect` import. Widen the fakes in
+ `tests/spatial_tools/test_tools.py:286-298` to real signatures (`fake_check_shaders(ws, *, module=None, timeout_s=90.0)`,
+ `fake_joint_sweep(..., joints=None)`).
+- (c) The nine "package C1/C2/E/F" comments (render.py:8, tools_render.py:4, tools_scene.py:54, joints_export.py:191,
+ joints.py:1, urdf/__init__.py:1, tracks/articulated_object.py:106, tracks/generation.py:215, tracks/common.py:207): sweep all or none.
+- Why: `call_adaptive` drops kwargs silently against signatures that now exist (`joint_sweep_observation` has no
+ `n_samples`/`round_index`); the forwarder contradicts the binding INTERFACES doc.
+- T: `python -m pytest tests/spatial_tools tests/scene_runtime/test_render_scene.py tests/core/test_cli_render_size.py tests/threejs_render/test_render.py -q` (not run by the verifier).
+
+**B6. URDF runtime uses `_common` plumbing** · `languages-urdf-runtime-bypasses-common` · risk low · ~−10 LOC
+- Files: `codeverse/languages/urdf/runtime.py` — `_run_blender` (:172-179) returns the `ProcResult` it already has;
+ use `remove_stale(art/"build.json", art/"census.json")` and `read_json_file` from `_common` (:105-117); move the
+ `codeverse.prompts` imports at :67/:74 to module level (no cycle). Update the three fake `_run_blender` returns in
+ `tests/urdf_joints/test_runtime_offline.py:38,44,116` to `ProcResult(...)`.
+- Decide explicitly: keep `_tail` (test :78 pins `"built\n"`) or adopt `proc.tail` and change that assertion.
+- **Do NOT** swap the whitelist env for `blender_env()` (it is stricter: no inherited PYTHONPATH, pins
+ `BLENDER_USER_CONFIG` into artifacts) — just add `"PYTHONNOUSERSITE": "1"`. Leave `"Timeout"` (threejs uses it too).
+ `compose_build_result` is out of scope (URDF has no `object.glb` at wrapper time).
+- Why: `_common.py:1` names urdf as a consumer; the dict unpack was a minimal-diff seam from commit 35acb0c.
+- T: `python -m pytest tests/urdf_joints/test_runtime_offline.py tests/blender_cadquery/test_common.py -q` (15 passed today).
+
+### Wave C — dedupes that touch agent-facing text or shared policy (need a pin first)
+
+**C1. Spatial tool report formatting** · `spatial-tools-report-formatting-twice` · risk **medium** · ~−25 LOC
+- Verbatim/same-algorithm trio (do first, low risk): move `NoArgs` to `codeverse/spatial/registry.py` next to `tool`
+ (NOT `from tools import NoArgs` — `tools.py:230-235` imports `tools_scene` at file bottom); add
+ `reference_path(ctx, index, *, tool) -> tuple[Path, dict]` to `tool_common.py` and call from
+ `tools_render.py:107-115` and `tools_reference.py:53-65`; `mcp_server.build_context:38-44` builds the `ToolContext`
+ first then `spec_dict(ctx)`.
+- Format unification (do second): `observe.py` gains `lint_lines(report, root, *, errors_only)` and
+ `build_failure_lines(br, root, lint_warns, *, tail_n)` replacing `tools.py:50-63,122-131` and
+ `tools_graphics.py:49-68`. The shared version MUST keep (i) the tools line format pinned by
+ `tests/spatial_tools/test_tools.py:137`, (ii) graphics' relative-`error_file` guard (`"src/shader.frag"` would
+ print as `shader.frag` via `rel_path` from any cwd ≠ workspace — this also fixes `blender/runtime.py:122`'s
+ relative ENTRY_REL branch), (iii) the `tail not in br.error_message` dedupe. Build on `observe._SEV_TAG`.
+ **Before refactoring, add a pin** in `tests/graphics/test_gl_runtime.py` for
+ `"BUILD FAILED: GlslCompileError: … at src/shader.frag:N"`.
+- T: `python -m pytest tests/spatial_tools/test_tools.py tests/spatial_tools/test_observe.py tests/spatial_tools/test_mcp_server.py tests/reference tests/graphics/test_gl_runtime.py -q` (83 passed today).
+
+**C2. `languages/_js_lint.py`** · `languages-js-lint-duplication` · risk low · ~−20 LOC (not 45)
+- New private module (exempt from the package-map test), modelled on `_ast_lint.py`:
+ `node_check_syntax(path, node_bin) -> SyntaxProblem | None` (line, message, stderr_tail — fixes threejs's
+ list-not-str fallback), `import_specs(src)` using the threejs regexes (superset: side-effect imports, `export * from`),
+ `classify_import(spec, path, src_root) -> ImportVerdict` deciding escape-before-exists with `Path.is_relative_to`
+ (closes scene's `startswith` prefix hole where `src2/` passes).
+- Callers: `codeverse/languages/threejs/lint.py:84-127` (keep a module-level `check_syntax` name —
+ `tests/threejs_render/test_lint.py:19` monkeypatches it), `codeverse/languages/scene_threejs/lint.py:55-96`.
+ Message text stays per-caller via a `make_finding` callback (test strings differ: "package 'lodash'" vs
+ "import 'gsap' is not allowed"). Note in scene lint's docstring that bare `import './x.js'` is now flagged.
+ Drop the glsl `_line_of` part (2 lines, not JS).
+- T: `python -m pytest tests/threejs_render/test_lint.py tests/scene_runtime/test_lint.py tests/languages/test_ast_lint.py tests/install/test_docs.py -q` (needs node; not run by the verifier).
+
+**C3. Judge replay: kill `TRACK_RUBRIC`, share `plan_digest`/`resolve_paths`/`judged_subset`** · `judge-replay-two-builders` · risk low · ~−15 LOC
+- (1) Delete `codeverse/judges/calibration.py:40` `TRACK_RUBRIC`; line 177 uses `TRACK_INFO[spec.track].rubric`
+ (`contracts/common.py:46` already calls itself "THE single source for what used to be restated as TRACK_RUBRIC");
+ add a calibration pin for `Track.GRAPHICS -> shader_v1` beside `tests/flywheel_cli/test_cli.py:171`
+ (today a graphics run with no stored judgment silently gets `static_object_v1`).
+- (2) Move `plan_digest` (calibration.py:100-155) plus the pure helpers `resolve_paths`/`judged_subset` out of
+ `cli/_judge.py` into `codeverse/judges/replay_input.py` (no cli/tracks/flywheel imports; add it to the
+ ARCHITECTURE map for `test_docs`). `load_run_cases` applies `judged_subset(resolve_paths(Workspace(run_dir), rec.renders))`
+ so a moved run and the in-run view subset match `3dcv judge`. Update `tests/judges/test_calibration.py:8`,
+ the re-export used by `tests/orchestrator_tracks/test_refactor_batch2.py:127`, docstring `judges/reference.py:291`.
+- (3) **Leave** `load_round/rubric_for/previous_judgment/extra_context_for/build_judge_input` in `cli/_judge.py`:
+ they need `RunRecord`, `tracks.get_track`, `flywheel.record`, and nothing in `judges/` imports those today (tracks/
+ flywheel import judges — moving would invert every edge). If calibration should see `previous`/`extra_context`,
+ make it an explicit option: it changes the EVAL §6 / D30 numbers.
+- T: `python -m pytest tests/judges/test_calibration.py tests/flywheel_cli/test_cli.py tests/orchestrator_tracks/test_refactor_batch2.py tests/core/test_run_layout.py tests/reference/test_judge_diff.py tests/install/test_docs.py -q` (57 passed today).
+
+### Wave D — package-level move (last; visible output changes)
+
+**D1 + D2. Retire `flywheel/gallery.py`; `bench/report.py` renders through `codeverse/gallery`** · `gallery-two-renderers` · risk **medium** · ~−200 LOC net (240 deleted, ~40 added) · **[land together; A1's `gallery_dict` falls out here]**
+- Prep in `codeverse/gallery/` (~+35 LOC): (a) `page.render_index` / `static_site.render_static` gain
+ `extra_html: str = ""` inserted after the summary strip (today only `note`, escaped text, exists — page.py:149-151,172);
+ (b) either `model.RunEntry.group: str = ""` rendered in `cards.render_card`, or bench builds one `RootSection`
+ per tier via `entry_from_record(tier, Workspace(ws_path), load_record(ws_path))` (`build_index` scans roots
+ and cannot); (c) `index.entry_links:134-172` emits `RunLink(label="deliverable/", rel="deliverable", kind="dir")`
+ when the dir exists (or port the assertion at `tests/flywheel_cli/test_run_layout_cli.py:261` to the glb rel path).
+- `bench/report.py:114-180`: build the sections above, construct a `RunEntry` directly for the no-record fallback
+ card (`battery=tier, slug=r.id, path=r.workspace or "", state="ok", score/baseline/passed/cost/minutes` from
+ the bench row — `entry_for_dir` would yield a pending/broken card without them), call `render_static(..., extra_html=stats_tables)`.
+ `report.html` changes appearance (theme.py shell, hero view) — `tests/flywheel_cli/test_bench.py:83-84` only
+ asserts a `data:image/jpeg` URI and the run id, so keep `embed=True`.
+- Delete `codeverse/flywheel/gallery.py`; port `tests/flywheel_cli/test_quality_gallery.py:128-140` and
+ `tests/flywheel_cli/test_run_layout_cli.py:255-262` (`gallery_items→build_index`, `item_from_run→entry_from_record`,
+ `render_gallery→render_static`).
+- Docs: `docs/ARCHITECTURE.md:162,180` and §11 lines 435-436, `docs/INTERFACES.md:398`, `docs/RUN_LAYOUT.md:173`,
+ `codeverse/flywheel/__init__.py:13`, `bench/report.py:1-7`.
+- Why: `thumbnail_data_uri` bodies are identical modulo a comment; `item_from_run` vs `entry_from_record` run the
+ same pipeline with `entry_from_record` a strict superset; `3dcv flywheel gallery` (`flywheel_cmd.py:172-187`)
+ already calls `gallery.static_site.build_static`, so the module's docstring and ARCHITECTURE's "shared renderer"
+ are stale since commit 8f3149d; no DECISIONS entry covers it.
+- T: `python -m pytest tests/flywheel_cli/test_quality_gallery.py tests/flywheel_cli/test_run_layout_cli.py tests/gallery tests/flywheel_cli/test_bench.py tests/install/test_docs.py -q` (154 passed today).
+
+### Dependency / ordering notes
+- A1 before D1/D2 is fine either way (`gallery_dict` deleted twice is a no-op); do not delete `report_dict` and then
+ forget D2 touches the same file — one PR per wave keeps the diffs reviewable.
+- B2 and B3 both add to `proc.py` and both edit `docs/ARCHITECTURE.md:85`: one PR.
+- A6 and A7 are the same package; one PR titled "texturing: drop unshipped material_pass/cookbook".
+- C1's `NoArgs`/`reference_path`/`build_context` trio can ship with Wave B if the format unification is deferred.
+- Every wave ends with `ruff check codeverse bench` and the full offline suite:
+ `python -m pytest tests -q -p no:cacheprovider -m "not live and not blender and not node"`.
+
+## 3. Leave alone (justified shapes — do not re-litigate)
+
+Cited by the readers' do-not-touch lists with their doc reference; the review agrees with all of them.
+
+**models / agents / cost**
+- `codeverse/models/storm.py` (156 lines, wired only when `Rate.storm_gate=True`) — shipped OFF, kept reproducible: `config.py Rate.storm_gate`, docs/COST.md §21, ARCHITECTURE §2.
+- `codeverse/cost/caching.py` Block/order_blocks/prefix_report/cache_efficiency — measurement-only after the reorder was reverted: module docstring table, docs/COST.md §13, ARCHITECTURE §2.
+- `cost/guard.py CostGuard/cheapest_affordable`, `cost/routing.py samples_for_precision/pro_break_even/default_route` — tested public API (`tests/cost/test_guard_caching_routing.py`, `cost/__init__` docstring).
+- `models/health.py sibling_processes()` — test infra (`tests/models/test_health.py:115`, docs/COST.md:1047); all constants are dated measurements.
+- `models/keypool.py MAX_WAIT_S=5`, `retry.py` storm branch / `RETRY_DEADLINE_S` — house rule 2026-08-24 (keypool.py:41-47, retry.py:23-30, COST.md Part III).
+- `models/gemini.py shared_pool` keyed by (keys, rpm, tpm, cap) + lazy config imports — COST.md:858; lazy imports avoid a models→config cycle.
+- `config.py _legacy_gemini_keys/_LEGACY_KEYS_FILE` — CLAUDE.md "Environment"; `_deep_merge`, `_FLAT_ALIASES`, `apply_profile.put_section` — each fixes a dated failure (config.py:140-147, 239-248, 310-321).
+- `cost/ledger.py LEDGER_NAME` symlink alias + `existing_ledger_path` — docs/RUN_LAYOUT.md telemetry bucket; ledger.py:52-56. (Also `CostLedger.append`'s own writer — see B3.)
+- `cost/instrument.py IN_PROCESS_AGENT_KINDS` + double bookkeeping — instrument.py:51-59, 81-88 document the measured double-count/drop bugs.
+- `cost/billing.py SUBSCRIPTION_BACKENDS` excluding gemini-cli — COST.md §25.
+- `models/pricing.py` (391) and `keypool.py` (381) — under the cap, single responsibility.
+- `agents/api_tools.py FileTools.edit_only` rule — measured 2026-08-25 over 128 refine rounds (api_tools.py:109-115).
+- `agents/api_skills.py SkillTools` as a tool — measured 0/5 vs 5/5 reads (docstring, ARCHITECTURE §2).
+- `claude_code.py primary_served_model`, `codex.py CodexEvents.usage` reasoning subtraction — measured mis-billing (claude_code.py:88-100, codex.py:108-112).
+- `runlock.py` PID file + fixed `.lock.tmp` — module docstring; race acknowledged at :120.
+- `workspace.py _git` retry loop + `WorkspaceGitError` — DECISIONS "Rejected / deferred".
+- `cost/profiles.py` per-field values — recorded A/Bs in COST.md §14/§17.
+- `models/health.py _bare_model / GeminiModel(storm_attempts=0)` — gemini.py:190-193.
+
+**tracks / orchestrator / prompts**
+- `tracks/generation.py:68-75 DEFAULT_AGENT_MAX_TURNS=0` + turn-cap/wrap-up machinery — COST.md §17.
+- `orchestrator/rounds.py StopPolicy` ordering and `judge_sigma/JUDGE_NOISE` — COST.md §5 + docstring replay numbers.
+- `orchestrator/budget.py charge()/add()` both forwarding to `spend()` — "one door for every dollar", COST.md §6; the enforce flag is load-bearing.
+- `orchestrator/runner.py:94-105` cache-miss-on-unreadable-result — D7 resume fix.
+- `tracks/steps.py skip_judge_reason / rejudge_round` asymmetry — COST.md §5/§17 "never pay for a verdict you will not use".
+- `tracks/scene.py _deliver_skills/_record_skills` — docstring (scene stages bypass run_round; measured 0/30 opens).
+- `tracks/lifecycle.py plan_stage_inputs` hashing a spec subset — D7 resume-overwrites-src comment.
+- `tracks/planner.py plan_tokens / TRUNCATION_GROWTH`, `plan_budget.py _CRAFT` regex (on free text, not ids) — measured comments.
+- `tracks/plan_features.py` — self-documented DEAD switch that `bench/ab_plan.py` and `tests/orchestrator_tracks/test_plan_features.py` depend on; deleting is a product decision.
+- `tracks/candidates.py quick_render` fallback — measured 2026-08-25 (docstring).
+- `tracks/scene_assets.py` single-shot-first + `is_model_outage` skip — scene_asset_gen docstring (45% of run cost).
+- `contracts/agent.py _lift_legacy_extra` + `run_agent_task` mirroring into `extra` — D11; backends still read `job.extra`.
+- `contracts/plan.py` importing `conventions.to_snake` — allowed under L2.
+- `orchestrator/candidates.py` vs `tracks/candidates.py` split (pure decision vs I/O) — ARCHITECTURE map.
+- `tracks/common.py Services` lazy forwarders — THE test seam (module docstring; `tests/orchestrator_tracks/fakes.py`).
+- `tracks/generation.py` envelope re-exports — imported by `bench/_oneshot.py:47`, `bench/compare_backends.py:88`, tests.
+- `StopPolicy.decide`, `StageRunner.is_done` — test infra / one real caller.
+
+**spatial / languages / runtime**
+- `blender/wrappers/run_bpy.py` (358→418 by some counts) and `runtime_js/lib/scene_host.mjs` (417-426) — DECISIONS L4 "two wrappers exceed it by design".
+- Wrapper helper twins `write_json_atomic/apply_rlimit/src_relative/map_exception` in `run_bpy.py:64-188` vs `run_cq.py:44-111` vs `run_bpy_links.py` — DECISIONS L1: wrappers cannot import codeverse (Blender's python).
+- `reference/spec_text.py brief_text` vs `tracks/prompting.constraints_text`; `reference/prompts.py` outside `codeverse/prompts/` — docstring decision (prompt hashes feed the cache key, reference/cache.py:30-36). Wave-coordination rationale, not measured: revisit once waves settle (see §4).
+- `runtime_js/lib/resolve_three*.mjs` + `three_redirect.mjs` two loader-hook shapes — CLAUDE.md "Supported versions", runtime_js/README.md (node 20.6 vs 22.15 hooks).
+- `spatial/render.py RIG_FILES` hashing page-side files only — render.py:53-58, `tests/threejs_render/test_studio_rig.py`.
+- `spatial/measure.py _stat_key` LRU — module docstring :10-13.
+- `spatial/connectivity.py penetration_depth` via `joints_collide.inside_island`, support/lowest-component rules — post-mortems in docstrings 150-164, 286-311.
+- `spatial/complexity.py` constants/weights — docs/COMPLEXITY.md + comments 67-71, 180-185, 193-201.
+- `spatial/joints_export.joint_sweep_observation` `joints` narrowing — measured 2026-08-25 (docstring 193-199).
+- `spatial/frame_metrics.py LOWKEY_MIN_STD / _glb_findings` WARN — docstring 30-38, 57-62, 253-266.
+- `spatial/silhouette.py _MAX_BBOX_COVER` — measured over 21 photos (41-49).
+- `runtime_js/lib/browser/studio.js`, `studio_env.js` constants — measured over 96 frames; render cache keys on them.
+- `runtime_js/lib/host_page.mjs requestFailureLine` ignoring `net::ERR_ABORTED` — measured ~10% phantom failures (40-47).
+- `runtime_js/lib/scene_host.mjs raceCreateScene / runUpdate` — documented failure modes (50-55, 249-256).
+- `texturing/run.py texture_requested` + `TEXTURE_TRACKS` — COST.md §15, comment block 114-149. Also the `judge=<object>` shim (pinned by test_run.py:81-88) until its wave ends.
+- `glsl_shader/wrap.py` re-exporting from `_gl_common` — `_gl_common` docstring 11-14.
+- `spatial/tool_common.lazy()` ToolUnavailable path — registry.py:12-14; keep even after `call_adaptive` goes.
+- `scene_threejs/runtime.py` single-boot probe+preflight — ARCHITECTURE §2/§7.
+- `languages/*/CONTRACT.md` fallbacks — `tests/skills/test_contract_agreement.py:36-38`, `tests/scene_runtime/test_runtime.py:26`.
+- `texturing/plan.family_from_text` and `materials.family_for` as two tables — refuted merge (see A7).
+
+**flywheel / judges / skills / cli / bench**
+- `cli/_common.py:lazy` — `tests/flywheel_cli/test_cli.py:85`, `tests/spatial_tools/test_tools.py:297`; main.py docstring.
+- `cli/_common.py:resolve_dial` — ARCHITECTURE:127 THE resolver; `tests/cost/test_profiles.py`.
+- `bench/_compare_report.py:load_jsonl` vs `bench/_jsonl.py:read_jsonl` — not duplication (per-natural_key dedup with a measured 0.400-vs-0.800 bug, lines 87-99; ARCHITECTURE:189-190).
+- `flywheel/record.py:find_run_dirs` BFS with `RUN_SEARCH_DEPTH=7` + `BATTERY_MARKERS` — record.py:286-296, 343-352; `tests/flywheel_cli/test_flywheel.py`. And its non-adoption by `complexity_report.iter_runs` (docs/COMPLEXITY.md §2 corpus definition), `ab_gate_rates`, `skill_targets` — finding refuted.
+- `skills/materialize.py` writing bundles twice + control bundle — module docstring; ARCHITECTURE:117-119.
+- `skills/config.py` reading `os.environ` at call time — docstring; docs/PLAN_LOOP.md LIVE_SWITCHES.
+- `skills/prompting.py NATIVE_LOADERS` re-export — prompting.py:752-754; `delivery.py` is the ONE policy table.
+- `bench/ab_plan.py`, `bench/compare_backends.py` sys.path + `_assert_local_codeverse` — two 2026-08-25 incidents (ab_plan.py:64-75).
+- `bench/ab_plan.py` 781 lines — one driver, docstring 1-45; nothing duplicated elsewhere.
+- `cli/flywheel_cmd.py:gallery_cmd` alias — CLAUDE.md commands, ARCHITECTURE §11 (10-line forwarder).
+- `judges/vlm_judge.py` per-sample retry vs `flywheel/captions.py` validate-and-fix loop — different shapes on purpose.
+- `flywheel/export.py` exact dedupe beside `3dcv flywheel dedupe` — ARCHITECTURE §11, D25.
+- `gallery/model.py + labels.py` four-bucket VERDICTS — model.py:112-121, page.py:9-13, `tests/gallery/test_triage.py`.
+- `bench/skill_targets.py` 419 lines — docs/SKILLS_LEDGER.md, EVAL.md §8 single readout.
+
+## 4. Structural observations (not cleanups)
+
+1. **`codeverse/proc.py` is the de-facto stdlib utility layer but never grew with the tree.** Eight tolerant
+ JSON reads, five tolerant JSONL reads and two JSONL writers exist because the documented "shared primitives"
+ module offers only `write_json_atomic`/`run_subprocess`/`tail`. B2+B3 fix the instances; the recommendation is a
+ rule in CLAUDE.md or ARCHITECTURE:85 — "any stdlib-only file/JSON/JSONL helper lives in `proc.py`; grep it
+ before writing a try/except read" — and to keep `proc.py` under ~250 lines so it stays a leaf. Cost: one doc line.
+
+2. **`codeverse/flywheel/` has quietly become two packages.** Records/telemetry/export/dedupe (the data flywheel)
+ and gallery/captions/quality (presentation) drifted apart when `codeverse/gallery/` was born in 8f3149d; D2
+ removes the stale half, but `flywheel/captions.py` and `quality.py` are consumed by `gallery/index.py`
+ (`quality_tier`, captions) as much as by export. Recommendation: after D2, decide whether `gallery` depends on
+ `flywheel` (current, fine) or the shared bits move to `flywheel/record.py`'s neighbours — write the arrow into
+ ARCHITECTURE §11 either way. Cost: a doc paragraph now; a small move later if wanted.
+
+3. **The `judges/` ↔ `cli/_judge.py` boundary is right but unwritten.** `judges/` imports nothing from
+ tracks/flywheel/workspace/orchestrator while all of those import `judges/` — that is a real, valuable layering,
+ and it is why C3 stops short of moving `build_judge_input`. It is enforced by nobody: `test_docs.py` checks the
+ package map, not import direction. Recommendation: a ~20-line import-direction test (parse `import` statements
+ under `codeverse/judges`, `codeverse/contracts`, `codeverse/proc.py`, assert no edge into tracks/flywheel/cli/
+ orchestrator). Cost: one test file; catches the next wave's inversion before review.
+
+4. **Wave-marker comments outlived the waves.** Nine "package C1/C2/E/F" comments, "written in parallel" docstrings
+ (`call_adaptive`), "for one wave" shims (`texture_pass` judge union), "TODO(follow-up wave)" (`gl_build`) and
+ `reference/prompts.py`'s "must not couple to files another wave edits" are the trace of the parallel-authoring
+ process, not of the design. Recommendation: after Waves A-B, one sweep that either deletes each marker or
+ converts it into an ADR line in DECISIONS.md; then adopt "no wave names in code — put the reason in DECISIONS".
+ `reference/spec_text.py` vs `tracks/prompting.constraints_text` is the one remaining pair whose only justification
+ is wave coordination; re-evaluate it in that sweep (cost: a half-day, risk low, cache-key change means one
+ reference-cache invalidation).
+
+5. **Fifteen files exceed the ~400-line law and only two are exempted (DECISIONS L4: `run_bpy.py`, `scene_host.mjs`).**
+ The tracks package carries seven of them, and three (`lifecycle.py` 714, `generation.py` 675, `rounds.py` 598) have
+ clean internal seams the unverified god-file findings describe (texture hook + refine scaffold; agent-session
+ strategy; refine-task compilation). `cli/main.py` (788) is the same — `layout_cmd.py`/`texture_cmd.py` show the
+ established split. Recommendation: do not split as part of this plan (0 LOC saved, medium risk, and every one of
+ these files is heavily pinned); instead either extend DECISIONS L4 with a per-file justification or schedule one
+ split per wave, starting with `rounds.py` (importers already split cleanly: lifecycle uses both halves, static_object/
+ scene/reference use only the refine half). Cost per split: ~1 day incl. re-export shim + doc row.
+
+6. **Three Blender environments.** After A5 there are still `blender/runtime.blender_env()`, urdf's whitelist env
+ (B6 keeps it, adds PYTHONNOUSERSITE) and `joints_export.blender_render_glb` passing no env at all. Not a bug today
+ (INSTALL.md:87 says Blender never renders in production), but if a no-node render fallback is ever wired,
+ `blender_env(user_config=...)` should be the single owner. Cost: ~15 lines when that feature lands, none now.
+
+7. **Verification gaps to close before merging.** The verifier could not execute pytest for A4, A5, A6, B3, B4, B5, C2
+ (sandbox classifier rate-limited); their "T" commands are the pre-condition, not a formality. Everything else was
+ run green on 2026-08-26.
+
+## 5. Totals
+
+| | LOC removed (net) | files touched (src + tests + docs) |
+|---|---|---|
+| Wave A (deletions, low risk) | ~570 | 34 |
+| Wave B (shared helpers, low risk) | ~150 | 33 |
+| Wave C (pinned dedupes; C1 medium) | ~60 | 18 |
+| Wave D (gallery move, medium) | ~200 | 14 |
+| **Low-risk total (A+B+C2+C3)** | **~755** | |
+| **All verified findings** | **~980** | **~95 distinct files** (about 60 in `codeverse/`+`bench/`+`runtime_js/`, 25 tests, 8 docs) |
+
+(Per-item figures are the verifiers' adjusted estimates; the original findings summed to ~1,150 and were
+over-stated on `languages-js-lint-duplication` (45→20), `spatial-tools-report-formatting-twice` (40→25),
+`judge-replay-two-builders` (30→15) and `languages-urdf-runtime-bypasses-common` (25→10).)
+
+**God files: 15** (law 4 ≤ ~400; DECISIONS L4 exempts only `run_bpy.py` and `scene_host.mjs`, neither in this list):
+- tracks/orchestrator: `codeverse/tracks/lifecycle.py` (714), `codeverse/tracks/generation.py` (675),
+ `codeverse/orchestrator/rounds.py` (598), `codeverse/tracks/scene.py` (518), `codeverse/tracks/steps.py` (486),
+ `codeverse/tracks/static_object.py` (449), `codeverse/tracks/scene_assets.py` (409)
+- cli/bench: `codeverse/cli/main.py` (788), `bench/ab_plan.py` (781, justified by its docstring), `bench/compare_backends.py` (497),
+ `bench/skill_targets.py` (419, justified by SKILLS_LEDGER/EVAL §8)
+- models/agents/cost: `codeverse/cost/reconstruct.py` (494), `codeverse/agents/api_tools.py` (463)
+- spatial/texturing: `codeverse/texturing/materials.py` (436 → ~375 after A7, leaves the list), `codeverse/spatial/measure.py` (427)
+
+None of the god files is split by this plan (see §4.5); A7 retires one by deletion alone.
+
+## Appendix — unverified lower-value findings (not adversarially checked; include at your own risk)
+
+| id | shape | files | LOC | note |
+|---|---|---|---|---|
+| gallery-rel-fmt-dup | `_rel` twice, `fmt` three times | gallery/index.py:52-61, detail.py:78-87, cards.py:27, page.py:34, detail.py:65 | 20 | fold into D2 if convenient |
+| version-probe-dup | doctor re-implements record's `--version` / node pkg probes | flywheel/record.py:39-46,72-79; cli/doctor.py:42-53,95-102 | 20 | |
+| core-dead-workspace-transcript | `Workspace.stages/diff/snapshot_src`, `Trajectory.stdout_path/stderr_path` unreferenced | workspace.py:171-173,360-367; agents/transcript.py:39-46 | 18 | grep looked clean; verify `snapshot_src` in flywheel export |
+| tracks-dup-fanout-exception-unpack | post-`fan_out` BudgetExceeded unpack ×4 with local imports | tracks/steps.py:125-138, scene.py:281-292, scene_assets.py:143-152, candidates.py:78-92 | 15 | check `codeverse.fanout.split_results` first |
+| languages-urdf-lint-own-ast-helpers | urdf lint bypasses `_ast_lint`, not in drift test; `PASCAL_RE` ×2 | urdf/lint.py:39,268-275; blender/lint.py:70; cadquery/lint.py:42 | 15 | |
+| spatial-union-find-twice | identical path-compressing union-find | spatial/connectivity.py:189-203, joints_sweep.py:83-101 | 15 | |
+| cost-dup-gemini-cli-stats | reconstruct re-implements gemini_cli usage mapping | cost/reconstruct.py:149-167, agents/gemini_cli.py:101-128 | 14 | medium risk; import direction cost→agents to check |
+| tracks-dup-mcp-argv-materialize | hard-coded `"python"` MCP argv ×3 vs D9 `sys.executable` | tracks/lifecycle.py:437-449, candidates.py:138-144, scene_assets.py:253-258 | 12 | may be a real D9 violation — worth verifying first |
+| tracks-dup-gitignore-appenders | two hand-rolled .gitignore appenders vs `Workspace.ensure_gitignore` | tracks/candidates.py:276-281, scene_assets.py:405-410, workspace.py:49-54 | 12 | `_cand/` missing from `_GITIGNORE_LINES` |
+| agents-dup-compose-prompt | `_compose_prompt` copied verbatim | agents/gemini_cli.py:261-265, codex.py:207-211 (+antigravity variant) | 10 | fold into B4 |
+| agents-inconsistent-gemini-cli-keypool | gemini-cli bypasses `shared_pool` quota/cooldown | agents/gemini_cli.py:60-69, models/gemini.py:52-79 | 10 | medium; behaviour change (COST.md:858) |
+| models-dup-image-price-table | `IMAGE_USD` duplicates pricing.py with a drift test | models/gemini_image.py:59-63,99-103; pricing.py:235-240,347-357 | 10 | COST.md:292 records it |
+| scene-dup-jsonable | `scene._jsonable` re-applies `runner._jsonable` | tracks/scene.py:509-518, orchestrator/runner.py:47-56 | 10 | |
+| spatial-measure-god-file | measure.py 427 lines / 4 subjects; material-count dup with complexity.py | spatial/measure.py, complexity.py:317-325 | 10 | |
+| bench-gate-kind-regex | ab_gate_rates re-implements `finding_kind` (ARCHITECTURE:114 "the ONE place") | bench/ab_gate_rates.py:16-40 | 10 | script has no tests |
+| sample-deprecated-aliases | three `#: deprecated aliases` + `export_samples(best_round=)` that only raises | flywheel/sample.py:46-50, export.py:122-143 | 10 | test is a drift guard that passes when absent |
+| steps-inconsistent-judgeinput-construction | `JudgeInput` hand-built ×3 | tracks/steps.py:404-408, candidates.py:218-221, scene_assets.py:334-336 | 8 | |
+| cli-record-state-raw-reads | raw `json.loads(record/state)` beside typed loaders | cli/main.py:741-748,467-475 | 8 | partly absorbed by B2 |
+| tracks-dup-pairwise-note-accounting | pairwise accounting block ×2 | tracks/candidates.py:240-248,302-309 | 6 | |
+| cost-cmd-untyped-getattr | `run: object` + getattr on typed objects | cli/cost_cmd.py:163-183,216-226 | 6 | law 4 hygiene |
+| agents-inconsistent-atomic-write | `Trajectory.write_json` fixed `.tmp` vs `proc.write_json_atomic` | agents/transcript.py:59-64 | 5 | fold into B3 |
+| tracks-dup-find-urdf | `_find_urdf` ×2 identical | tracks/articulated_object.py:139-143, motion.py:143-147 | 5 | |
+| agents-god-file-api-tools | 463 lines: file tools + shell policy + SpatialTools | agents/api_tools.py | 0 | see §4.5 |
+| cost-god-file-reconstruct | 494 lines: RunLedger + run walk + cells + find_runs | cost/reconstruct.py | 0 | see §4.5 |
+| lifecycle-god-file-texture-hook | 714 lines; texture hook trio + refine scaffold | tracks/lifecycle.py:572-660 | 0 | medium; see §4.5 |
+| generation-god-file-two-strategies | 675 lines; single-shot vs agent-session strategies | tracks/generation.py | 0 | medium; see §4.5 |
+| rounds-god-file-two-subjects | 598 lines; StopPolicy vs refine-task compilation at :363 | orchestrator/rounds.py | 0 | best first split candidate |
+| cli-main-god-file | 788 lines; render/judge/status not split like `*_cmd.py` | cli/main.py | 0 | see §4.5 |
+
+Refuted and excluded: `flywheel-run-dir-walks` (no `_cand/` double count exists; `complexity_report --recursive`
+defines the documented 67-run corpus in docs/COMPLEXITY.md §2 and `find_run_dirs` would silently add 78 A/B-rig runs).