# V5 Context-Subset Geometry Consistency 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:** Add a detachable training-only V5 context-subset geometry consistency loss with strict configuration, reproducible view deletion, auditable telemetry, and no model or inference changes. **Architecture:** The normal four-view V5 forward remains the supervised path. A second shared V5 encoder call removes one context view, then inserts only its density residual into the detached four-view evidence base. The unchanged fixed renderer compares counterfactual depth and visibility against the detached four-view prediction on an evidence-defined overlap. **Tech Stack:** Python 3.11, PyTorch 2.7+, pytest, Ruff, YAML, existing MCSS typed states and fixed measurement renderer. ## Global Constraints - Preserve `context RGB + calibrated cameras -> V5 typed state -> 2x appearance -> fixed renderer`. - Add no learned module, model parameter, state-dict key, inference branch, or target-conditioned state input. - Weight zero must skip the complete subset path. - Nonzero use is restricted to fixed-mode, four-context V5 evidence-residual training. - Do not add RGB, normal, point, target-label, or residual-magnitude losses. - Do not run Hypersim training or tune the weight on validation scenes. - This source directory has no `.git`; do not claim a branch, commit, or worktree. --- ### Task 1: Strict opt-in configuration and deterministic subset selection **Files:** - Modify: `src/mcss/config.py` - Create: `src/mcss/context_subset_consistency.py` - Modify: `tests/test_config.py` - Create: `tests/test_context_subset_consistency.py` **Interfaces:** - Produces: `TrainingConfig.context_subset_geometry_weight: float = 0.0`. - Produces: `drop_context_view(context_rgb, cameras, dropped_index) -> ContextSubset`. - Produces: `ramped_context_subset_geometry_weight(max_weight, optimizer_step, warmup_steps)`. - [ ] Add config tests proving the default is zero, `0.1` parses, negative values fail, and nonzero use fails outside fixed four-context `evidence_residual` experiments. - [ ] Run the focused config tests and verify they fail because the new field is rejected. - [ ] Add subset tests proving RGB and camera selection preserve retained order and reject an invalid deletion index. - [ ] Run the subset tests and verify import failure because the new module is absent. - [ ] Implement the strict field, cross-section validation, subset selection, and update-based ramp. - [ ] Run both focused test files and require zero failures. ### Task 2: Counterfactual geometry and detached consistency loss **Files:** - Modify: `src/mcss/context_subset_consistency.py` - Modify: `tests/test_context_subset_consistency.py` **Interfaces:** - Produces: `compute_context_subset_geometry(full_state, subset_state, full_predictions, target_cameras, renderer, residual_saturation_threshold, collect_audit_diagnostics=True) -> ContextSubsetGeometryResult`. - `ContextSubsetGeometryResult` exposes `loss`, tensor `terms`, lightweight scalar `diagnostics`, log-step-only `audit_diagnostics`, and per-sample diagnostics for scene-aware logging. - [ ] Add a failing real-renderer test proving a changed subset residual creates positive finite depth/visibility consistency loss, gradients reach only the subset residual, and deterministic evidence tensors receive no gradient. - [ ] Add a failing zero-overlap test proving finite zero loss and zero subset gradient. - [ ] Implement the shared/stable mask, four-view evidence-base counterfactual, detached teacher, metric-voxel-normalized Smooth L1 depth, Smooth L1 visibility, quantiles, saturation, and per-sample diagnostics. - [ ] Run the focused tests and require zero failures. ### Task 3: Training integration, reproducibility, and telemetry **Files:** - Modify: `src/mcss/engine.py` - Modify: `tests/test_context_subset_consistency.py` - Modify: `tests/test_cli_smoke.py` **Interfaces:** - Consumes: the Task 1 subset and ramp helpers and Task 2 geometry result. - Produces: an independent CPU `torch.Generator`, conditional subset encoder/render path, weighted loss, JSONL context metadata, and checkpointed subset-generator state for enabled runs only. - [ ] Add a failing trainer test proving weight zero never calls the subset helper and enabled mode logs the raw loss, effective weight, dropped/retained indices, and per-scene diagnostics. - [ ] Implement the conditional training path without changing evaluation or model forward. - [ ] Store and restore the independent generator state only when the mechanism is enabled. - [ ] Use the next optimizer-update index for ramping so all micro-steps in one accumulated update share one effective weight. - [ ] Run focused engine and CLI tests and require zero failures. ### Task 4: Frozen runnable configurations and operator boundary **Files:** - Create: `configs/synthetic_er_v5_context_subset_geometry_smoke.yaml` - Create: `configs/hypersim_er_v5_context_subset_geometry_train_v1.yaml` - Modify: `README.md` **Interfaces:** - Produces: a two-step CPU verification config and a V5-matched, unexecuted Hypersim proposal with weight `0.1`, warmup `3000`, four context views, and a new output directory. - [ ] Add the synthetic smoke config with four context views and no real-data dependency. - [ ] Add the Hypersim config by changing only output directory and the one new weight relative to `hypersim_er_v5_phase0_pilot_train_v3.yaml`. - [ ] Document that the smoke is software verification, the Hypersim config is unexecuted, and V5 remains the comparator until all empirical gates in the design pass. - [ ] Load both configs through the strict parser. ### Task 5: Verification and scope audit **Files:** - Verify all files named above. **Interfaces:** - Consumes: all previous task outputs. - Produces: fresh test, lint, compilation, smoke, and compatibility evidence. - [ ] Run focused context/config tests. - [ ] Run the enabled two-step CPU training smoke and inspect JSONL/checkpoint metadata. - [ ] Run the full pytest suite and require zero failures. - [ ] Run Ruff over `src`, `tests`, and `scripts` and require zero errors; record existing `third_party` and `backups` failures separately rather than modifying vendor/history code. - [ ] Compile every Python source in memory. - [ ] Compare `MeasurementCompleteSystem` and model state-dict keys before and after; confirm neither the model file nor its keys changed. - [ ] Audit changed files against the design and report that no Hypersim experiment was started.