Appearance Ceiling Diagnostic Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Measure whether native color optimization, spatial appearance resolution, or target direction dependence explains the V4 one-window RGB ceiling.

Architecture: A reusable AppearanceOracle owns only optimizable color logits while borrowing fixed density, variance, bounds, cameras, and the existing parameter-free renderer. A standalone script loads the accepted V4 checkpoint, evaluates all three registered variants, and writes one provenance-complete JSON report.

Tech Stack: Python 3.11, PyTorch 2.7+, pytest, existing MCSS dataset/config/checkpoint APIs.

Global Constraints

• Use only data/hypersim_prepared/train/ai_001_001 through the existing overfit config.
• Never pass target RGB to MeasurementCompleteSystem.forward or the state encoder.
• Never read validation, diagnostic-test, or final-holdout data.
• Keep the renderer parameter-free and accepted outputs immutable.
• The directory has no Git repository; create a timestamped backup before modifying existing files.

Task 1: Oracle Variant Contract

Files: - Create: src/mcss/appearance_oracle.py - Create: tests/test_appearance_oracle.py

Interfaces: - Produces: OracleVariant, AppearanceOracle(reference_state, target_views, variant). - Produces: AppearanceOracle.render_rgb(renderer, cameras) -> Tensor.

• [ ] Write tests proving native/shared, doubled/shared, and native/per-view parameter shapes; the reference state stays unchanged; per-view colors are routed to the matching cameras; and every variant backpropagates finite RGB gradients.
• [ ] Run uv run pytest tests/test_appearance_oracle.py -q and verify collection fails because mcss.appearance_oracle does not exist.
• [ ] Implement strict variant validation, detached fixed geometry buffers, logit initialization, high-resolution resampling, and per-view rendering through Cameras.select_views.
• [ ] Run uv run pytest tests/test_appearance_oracle.py -q and require all tests to pass.

Task 2: Reproducible Oracle Runner

Files: - Create: src/mcss/oracle_runner.py - Create: scripts/run_appearance_oracle.py - Modify: README.md

Interfaces: - Consumes: --config, --checkpoint, --output-dir, --steps, --learning-rate, and --seed. - Produces: oracle.json, oracle.jsonl, checkpoint/config SHA-256 values, and per-variant metrics.

• [ ] Add a CLI-level synthetic test that runs one step for all variants and asserts the report schema, source hashes, finite metrics, and distinct parameter counts.
• [ ] Run the CLI-level test and verify it fails because the runner is absent.
• [ ] Implement deterministic first-item loading, masked RGB MSE, best-state restoration, metric calculation through compute_metrics, atomic JSON output, and append-only progress records.
• [ ] Document the exact accepted-checkpoint command and diagnostic-only target-label boundary.
• [ ] Run the focused oracle tests and require them to pass.

Task 3: Real V4 Diagnostic And Branch Decision

Files: - Create: outputs/appearance_oracle_v1/oracle.json - Create: outputs/appearance_oracle_v1/oracle.jsonl - Create after measurement: docs/superpowers/specs/2026-08-11-typed-appearance-state-design.md - Create after measurement: docs/superpowers/plans/2026-08-11-typed-appearance-state.md

Interfaces: - Consumes: configs/hypersim_er_overfit.yaml and outputs/hypersim_er_v4_scale4_overfit/checkpoints/step_005000.pt. - Produces: one selected production branch with measured justification.

• [ ] Run all three variants for enough steps that the last 20 percent does not improve best MSE by more than one percent, extending the run if this convergence check fails.
• [ ] Compare best PSNR/MSE against native_shared; select one branch using the design rule rather than inspecting any held-out data.
• [ ] Write the exact selected architecture, compatibility contract, telemetry, tests, smoke config, and overfit gate into the typed-appearance spec and plan.
• [ ] Self-review both documents for placeholders, contradictory tensor shapes, target leakage, and missing legacy compatibility.

Task 4: Diagnostic Verification

Files: - Verify all files created or modified above.

Interfaces: - Produces: a measured and reproducible input to the next production implementation.

• [ ] Run uv run pytest -q and require zero failures.
• [ ] Run uv run ruff check . and require zero errors.
• [ ] Compile every Python file below src and scripts with compile().
• [ ] Confirm git status reports that the directory is not a repository and report backup paths instead of claiming a commit.