Restore consolidated workspace README

workspace/README.md

@@ -0,0 +1,660 @@
+# VLA / CIL-Atlas / Causal Tangent Transport
+
+This repository is the working codebase for a robot-learning research project
+around same-state counterfactual action charts and Causal Tangent Transport
+(CTT).
+
+The single spine of the project is:
+
+> Standard VLA training observes one demonstrated action per state. CIL-Atlas
+> restores the same state, executes multiple action chunks, and measures which
+> local action tangents causally improve, recover, fail, collide, or succeed.
+> CTT turns this measured local causal geometry into deployment-clean proposal
+> generation by transporting measured positive do-action tangents from
+> train-only neighboring charts into the target chart.
+
+The current evidence is intentionally written as a diagnostic method paper, not
+as an overclaimed final success. K=16 `env_clip` support is strong on held-out
+test (`proposal_oracle_success = 0.5694`, `OutcomePTR@16 = 0.5486`), while the
+selector/dominance side remains the bottleneck. The strongest current
+train-clean K=16 selector reaches `selected_success = 0.3542` against a
+`0.5694` proposal oracle, leaving a `0.2431` success selector gap. The
+score-source LCB dominance fallback is safe under action-bound labels but
+negative as a selector (`0.2778` auto, `0.2917` tau0).
+
+All other Markdown files were removed and consolidated into this README. The
+canonical paper is `latex/main.tex` plus `latex/main.pdf`; experiment evidence
+lives in JSON, TeX, logs, configs, and command files under `runs/`.
+
+## Research Goal
+
+The paper target is not "a bigger stack." The target is a clean method story:
+
+1. Same-state CIL charts define local do-action causal geometry.
+2. Causal Action Regret decomposes deployment failure into support gap plus
+   selector gap.
+3. CTT proposes candidates by transporting measured train positive tangents,
+   not by Gaussian noise or verifier optimization off support.
+4. Utility energy and calibrated dominance decide whether a transported tangent
+   should replace the base action.
+5. Every main claim must have a method, implemented script/module, metric table,
+   leakage audit, and reproducible run log.
+
+Current strategic diagnosis:
+
+| Area | Current status | Meaning |
+| --- | --- | --- |
+| Same-state chart data | Implemented and leakage-audited | Good scientific primitive |
+| Metrics | Implemented with measured/proxy separation | OutcomePTR and PPTC are not confused |
+| CTT residual transport | Implemented and measured | K=16 support is real |
+| Gated/residual proxy variants | Implemented | Mostly diagnostic |
+| `env_clip` execution convention | Implemented | Action-bound-clean current convention |
+| Learned dominance selectors | Implemented | Best current selector still leaves large gap |
+| LCB calibrated dominance | Implemented | Safe fallback diagnostic, not successful selector |
+| Object-layout hand features | Implemented | Negative measured result |
+| Theory notes/section | Implemented | Honest support-regret framing |
+| Paper | Implemented in LaTeX | Must remain diagnostic until selector improves |
+
+## High-Level Layout
+
+```text
+.
+|-- cil/                 Core CTT metrics, chart features, and small models.
+|-- dovla_cil/           Broader CIL/VLA framework: data, sims, models, eval.
+|-- configs/             YAML/JSON configs for baselines, CTT, large jobs, toy jobs.
+|-- data/                Exported CIL chart indexes and shards.
+|-- latex/               Main paper source, tables, references, and PDF.
+|-- paper/               Theory section used by the LaTeX paper.
+|-- scripts/             Training, export, audit, rollout, evaluation, HF sync.
+|-- manifests/           Job/run manifests and active templates.
+|-- runs/                Reproducible experiment artifacts and metrics.
+|-- logs/                Cluster/stdout/stderr logs and local sync logs.
+|-- outputs/             Scratch-like local outputs and HF sync manifests.
+|-- results/             Legacy non-Markdown result artifacts, if any remain.
+|-- tests/               Unit/regression tests.
+|-- Makefile             Convenience command entrypoint.
+```
+
+## Folder And File Inventory
+
+### Root
+
+- `README.md`: this file. The only Markdown document kept in the workspace.
+- `Makefile`: convenience wrapper for common commands.
+- `.env.example`: example environment variables; do not store secrets here.
+- `.gitignore`: ignored local artifacts, caches, and generated files.
+- `.claude/`, `.codex/`, `.agents/`, `.remember/`: local assistant/tool state.
+- `.pytest_cache/`, `.ruff_cache/`: local test/lint caches.
+
+### `cil/`
+
+Core research implementation for CTT and canonical metrics.
+
+- `cil/__init__.py`: package marker.
+- `cil/chart_features.py`: deployment-visible chart feature construction.
+  Feature modes include `base`, `base_context`, `base_context_obs`,
+  `base_context_obj`, and `base_context_obs_obj`. This file is important
+  because it controls what information the selector/generator may see.
+- `cil/metrics.py`: canonical metrics:
+  - BranchCAR / branch causal action regret.
+  - OutcomePTR@K for measured executed generated candidates.
+  - PPTC@K for distance-only proxy positive tangent coverage.
+  - SelectorRegret@K.
+  - SupportGap.
+  - ProxySupportDistance.
+  - NegativeNear.
+  - PosCloserThanNeg.
+  - Pairwise Causal Calibration Error.
+  - safety label coverage and unsafe-rate helpers.
+- `cil/models/__init__.py`: model package exports.
+- `cil/models/chart_encoder.py`: chart encoder used by CTT/utility energy.
+- `cil/models/tangent_encoder.py`: tangent encoder and normalization helpers.
+- `cil/models/ctt.py`: Causal Tangent Transport model definitions, including
+  residual/gated transport variants.
+- `cil/models/utility_energy.py`: utility energy scorer used by ranking and
+  dominance.
+
+### `dovla_cil/`
+
+General CIL/VLA framework code. This is older and broader than the compact
+`cil/` CTT layer.
+
+- `dovla_cil/config/defaults.yaml`: default project config.
+- `dovla_cil/config/schema.py`: config schema.
+- `dovla_cil/effects/extractors.py`: outcome/effect extraction utilities.
+- `dovla_cil/effects/failure_classifier.py`: failure classifier logic.
+- `dovla_cil/effects/rewards.py`: scalar reward/utility helpers.
+- `dovla_cil/eval/causalstress.py`: causal stress evaluation.
+- `dovla_cil/eval/external_vla_baseline.py`: external VLA baseline eval.
+- `dovla_cil/eval/lattice_eval.py`: CIL lattice evaluation.
+- `dovla_cil/eval/libero_eval.py`: LIBERO eval adapter.
+- `dovla_cil/eval/maniskill_eval.py`: ManiSkill eval adapter.
+- `dovla_cil/eval/maniskill_policy_rollout.py`: policy rollout harness.
+- `dovla_cil/eval/metrics.py`: legacy eval metrics.
+- `dovla_cil/eval/simpler_eval.py`: simpler eval adapter.
+- `dovla_cil/eval/smolvla_cil_baseline.py`: SmolVLA CIL baseline eval.
+- `dovla_cil/eval/smolvla_runtime.py`: SmolVLA runtime wrapper.
+- `dovla_cil/experiments/baselines.py`: baseline experiment definitions.
+- `dovla_cil/experiments/manifest.py`: manifest execution helpers.
+- `dovla_cil/experiments/reports.py`: legacy report generation helpers.
+- `dovla_cil/experiments/scaling.py`: scaling experiment helpers.
+- `dovla_cil/generation/distributed.py`: distributed generation utilities.
+- `dovla_cil/generation/maniskill_lattice.py`: ManiSkill lattice generation.
+- `dovla_cil/generation/maniskill_parallel.py`: parallel ManiSkill generation.
+- `dovla_cil/generation/maniskill_render.py`: rendering utilities.
+- `dovla_cil/generation/pipeline.py`: generation pipeline orchestration.
+- `dovla_cil/generation/tangent_chart_synthesis.py`: chart synthesis baseline.
+- `dovla_cil/generation/tangent_cvae.py`: raw/positive tangent CVAE baseline.
+- `dovla_cil/generation/tangent_local_atlas.py`: local atlas memory baseline.
+- `dovla_cil/generation/tangent_memory.py`: tangent memory utilities.
+- `dovla_cil/generation/tangent_spline_cvae.py`: spline-CVAE baseline.
+- `dovla_cil/generation/tangent_spline_flow.py`: spline flow baseline.
+- `dovla_cil/generation/tangent_spline_guided_flow.py`: guided spline flow.
+- `dovla_cil/generation/tangent_targets.py`: tangent target construction.
+- `dovla_cil/interventions/language_counterfactuals.py`: language CIL changes.
+- `dovla_cil/interventions/perturbations.py`: action/scene perturbations.
+- `dovla_cil/interventions/physics_counterfactuals.py`: physics interventions.
+- `dovla_cil/interventions/samplers.py`: intervention samplers.
+- `dovla_cil/interventions/schema.py`: intervention data schema.
+- `dovla_cil/models/action_encoder.py`: action encoder.
+- `dovla_cil/models/dovla.py`: base DOVLA model.
+- `dovla_cil/models/dovla_attention.py`: attention model variant.
+- `dovla_cil/models/dovla_attention_enhanced.py`: enhanced attention variant.
+- `dovla_cil/models/dovla_hybrid.py`: hybrid model variant.
+- `dovla_cil/models/dovla_transformer.py`: transformer model variant.
+- `dovla_cil/models/effect_heads.py`: effect prediction heads.
+- `dovla_cil/models/openvla_adapter.py`: OpenVLA adapter.
+- `dovla_cil/models/policy_heads.py`: policy output heads.
+- `dovla_cil/retrieval/embeddings.py`: retrieval embedding utilities.
+- `dovla_cil/retrieval/eval.py`: retrieval evaluation.
+- `dovla_cil/retrieval/index.py`: retrieval index.
+- `dovla_cil/retrieval/prompting.py`: retrieval prompt helpers.
+- `dovla_cil/retrieval/retriever.py`: retriever implementation.
+- `dovla_cil/sim/base.py`: simulator interface.
+- `dovla_cil/sim/genesis_backend.py`: Genesis simulator backend.
+- `dovla_cil/sim/maniskill_backend.py`: ManiSkill backend.
+- `dovla_cil/sim/registry.py`: simulator registry.
+- `dovla_cil/sim/toy_backend.py`: toy backend.
+- `dovla_cil/tasks/library.py`: task library.
+- `dovla_cil/tasks/predicates.py`: task predicates.
+- `dovla_cil/tasks/schema.py`: task schema.
+- `dovla_cil/tasks/validators.py`: task validation.
+- `dovla_cil/training/collate.py`: data collation.
+- `dovla_cil/training/losses.py`: training losses.
+- `dovla_cil/training/metrics.py`: training metrics.
+- `dovla_cil/training/trainer.py`: trainer implementation.
+- `dovla_cil/transfercritic/*`: transfer critic labels, model, training,
+  selection, and evaluation.
+- `dovla_cil/utils/*`: hashing, IO, logging, seeding, language embeddings,
+  and OpenClaude client helpers.
+- `dovla_cil/vlm/*`: VLM annotation, prompts, clients, and task generation.
+- `dovla_cil/py.typed`: marks the package as typed.
+
+### `configs/`
+
+Configuration files for experiments.
+
+- `configs/ctt/residual_smoke.yaml`: small residual CTT smoke config.
+- `configs/ctt/residual_full.yaml`: full residual CTT config.
+- `configs/ctt/gated_residual_smoke.yaml`: small gated CTT smoke config.
+- `configs/ctt/gated_residual_full.yaml`: full gated CTT config.
+- `configs/baselines/*.yaml`: baseline configs for expert-only BC,
+  cross-state negatives, random negatives, label-only counterfactuals, and
+  world-model auxiliary baselines.
+- `configs/external/*.json`: SmolVLA aligned/full/smoke external configs.
+- `configs/hpc/nvidia_icd.json`: HPC GPU/ICD runtime config.
+- `configs/large/*.yaml`: large-scale generation/training templates.
+- `configs/toy/*.yaml`: toy generation/eval/training configs.
+
+### `data/`
+
+Exported CIL chart databases. These are generated artifacts, not source code.
+
+- `data/cil_charts/{train,val,test}/`: original chart indexes/shards.
+- `data/cil_charts_rgb_refs/{train,val,test}/`: non-destructive RGB-reference
+  chart export with observation refs and deterministic RGB/object features.
+- `index.json` inside each split records split hashes, content hashes,
+  retrieval permissions, and evaluator-only outcome contracts.
+- NPZ shards store chart rows, base actions, branch actions, utility labels,
+  outcome vectors, residual action tangents, spline tangent codes, and metadata.
+
+### `latex/`
+
+Paper source and build artifacts.
+
+- `latex/main.tex`: canonical paper draft. This is the single main paper source.
+- `latex/main.pdf`: compiled PDF.
+- `latex/references.bib`: bibliography.
+- `latex/tables/*.tex`: hand-maintained or generated tables used by `main.tex`.
+- `latex/main.aux`, `main.bbl`, `main.blg`, `main.fdb_latexmk`, `main.fls`,
+  `main.log`, `main.out`: LaTeX build intermediates.
+
+### `paper/`
+
+Paper sections that are included or copied into the LaTeX draft.
+
+- `paper/sections/theory.tex`: formal theory section with same-state causal
+  contrast identifiability, CAR decomposition, support/sample-complexity
+  arguments, and transport smoothness/support-regret bounds.
+- `paper/notes/`: reserved for non-Markdown theory notes if needed. Markdown
+  notes were removed to keep this README as the single textual overview.
+
+### `scripts/`
+
+Main executable research pipeline.
+
+Data/chart export and audits:
+
+- `scripts/export_cil_charts.py`: exports train/val/test CIL chart DB.
+- `scripts/build_data_accounting.py`: builds data accounting artifacts.
+- `scripts/audit_cil_charts.py`: leakage audit for chart indexes and run hashes.
+- `scripts/audit_leakage.py`: legacy leakage audit.
+- `scripts/audit_action_bounds.py`: action-bound validity audit.
+- `scripts/audit_chart_feature_sources.py`: audits feature source availability.
+- `scripts/check_tangent_reconstruction.py`: verifies spline tangent
+  reconstruction exactly matches stored residuals.
+- `scripts/build_action_scale_vector.py`: builds per-dimension action scaling.
+
+CTT training/proxy/rollout:
+
+- `scripts/train_ctt.py`: trains residual or gated residual CTT.
+- `scripts/eval_ctt_proxy.py`: proxy support evaluation with PPTC,
+  NegativeNear, distance, diversity, and collapse metrics.
+- `scripts/eval_ctt_generated_rollout.py`: measured rollout harness that
+  restores states, decodes generated tangents, executes candidates, and writes
+  measured candidate rows.
+- `scripts/eval_ctt_rollout.py`: measured-output wrapper.
+- `scripts/build_ctt_proxy_comparison.py`: proxy comparison/gate table.
+- `scripts/build_ctt_rollout_comparison.py`: measured rollout aggregation.
+- `scripts/summarize_ctt_runs.py`: global CSV/Markdown summary. Markdown output
+  may be generated transiently, but the persistent overview is this README.
+
+Dominance and utility:
+
+- `scripts/train_utility_energy.py`: train-only utility energy model.
+- `scripts/calibrate_dominance.py`: conformal-style dominance calibration rule.
+- `scripts/eval_dominance_selector.py`: LCB dominance fallback evaluation.
+  Reports selected success, coverage, fallback, unsafe execution, PCCE,
+  selector regret, and support/selector gaps.
+- `scripts/eval_learned_dominance_selector.py`: ridge learned dominance
+  selector with basic/context/tangent/source/chart-compat features.
+- `scripts/eval_nonlinear_dominance_selector.py`: nonlinear selector sweep.
+
+Metric and paper artifacts:
+
+- `scripts/eval_metrics.py`: canonical measured/proxy metric evaluator.
+- `scripts/reproduce_v0_report.py`: V0 reproduction artifact.
+- `scripts/make_paper_artifacts.py`: generated paper tables/artifacts.
+- `scripts/build_paper_analysis.py`: paper analysis builder.
+- `scripts/build_paper_table_status.py`: paper table status builder.
+- `scripts/report_dataset.py`, `report_eval.py`, `report_hpc_clean_results.py`:
+  structured reporting helpers.
+
+Generation and baseline scripts:
+
+- `scripts/generate_cil.py`: CIL generation entrypoint.
+- `scripts/generate_cil_distributed.py`: distributed CIL generation.
+- `scripts/generate_maniskill_lattice.py`: ManiSkill lattice generator.
+- `scripts/generate_metaworld_lattice.py`: MetaWorld lattice generator.
+- `scripts/generate_rlbench_lattice.py`: RLBench lattice generator.
+- `scripts/generate_12task_collection.py`: larger task collection generator.
+- `scripts/make_cil_collection.py`: collection builder.
+- `scripts/merge_task_datasets.py`: merge task datasets.
+- `scripts/prepare_baseline_dataset.py`: baseline dataset prep.
+- `scripts/run_baseline.py`: baseline launcher.
+- `scripts/run_external_vla_baseline.py`: external VLA baseline launcher.
+- `scripts/run_manifest.py`: manifest executor.
+- `scripts/run_master_workflow.sh`: legacy master workflow.
+
+Positive tangent baselines:
+
+- `scripts/export_positive_tangent_targets.py`: exports positive tangent targets.
+- `scripts/eval_positive_tangent_memory.py`: memory baseline eval.
+- `scripts/eval_positive_tangent_local_atlas.py`: local atlas baseline eval.
+- `scripts/eval_positive_tangent_chart_synthesis.py`: chart synthesis eval.
+- `scripts/train_positive_tangent_cvae.py`: CVAE baseline training.
+- `scripts/train_positive_tangent_spline_cvae.py`: spline-CVAE training.
+- `scripts/train_positive_tangent_spline_flow.py`: spline flow training.
+- `scripts/train_positive_tangent_guided_spline_flow.py`: guided flow training.
+- `scripts/summarize_positive_tangent_*`: sweep summarizers.
+
+Legacy DOVLA training/eval:
+
+- `scripts/train_dovla.py`: base DOVLA training.
+- `scripts/train_dovla_attention.py`: attention variant.
+- `scripts/train_dovla_enhanced.py`: enhanced variant.
+- `scripts/train_dovla_transformer.py`: transformer variant.
+- `scripts/train_hybrid_direct.py`: hybrid direct model.
+- `scripts/train_transformer_with_language.py`: language transformer training.
+- `scripts/eval_*checkpoint.py`: checkpoint evaluators.
+- `scripts/evaluate_phase_a*.py`: legacy phase evaluators.
+
+HF sync and operations:
+
+- `scripts/hf_push_once.sh`: one-shot HF upload of workspace/scratch roots.
+- `scripts/hf_push_every_15m.sh`: local 15-minute HF sync daemon.
+- `scripts/hf_sync_daemon.sh`: alternate daemon wrapper.
+- `scripts/auto_sync_hf.py`: legacy auto-sync helper.
+- `scripts/check_hf_sync.sh`: HF sync check.
+- `scripts/quick_start.sh`, `run_eval.sh`, `run_inference.sh`,
+  `run_train_debug.sh`, `smoke_test.sh`: convenience shell entrypoints.
+
+### `scripts/slurm/`
+
+Cluster job templates. Important groups:
+
+- CTT: `train_ctt_proxy_sweep.sbatch`, `train_ctt_feature_proxy.sbatch`,
+  `eval_ctt_generated_rollout.sbatch`.
+- Dominance: `eval_tanh_train_dominance.sbatch`,
+  `eval_perdim_trainmax_dominance.sbatch`,
+  `train_utility_energy_selector.sbatch`.
+- Rendering/export: `render_six_task_chart_observations.sbatch`,
+  `reexport_rgb_ref_cil_charts.sbatch`, `render_maniskill_observations.sbatch`.
+- Baselines/generation: `generate_6task_h16.sbatch`,
+  `make_maniskill_collection.sbatch`, `train_maniskill_*`.
+- Legacy model training/eval: `train_dovla*.sbatch`, `train_transformer*.sbatch`,
+  `eval_*`.
+- HF sync: `hf_push_daemon.sbatch`.
+
+### `manifests/`
+
+Run manifests and templates.
+
+- `manifests/cil_1b_template.yaml`: active large template opened in the IDE.
+- `manifests/cil_160m.yaml`: smaller CIL manifest.
+- `manifests/baselines_full.yaml`: full baseline manifest.
+- `manifests/scaling_k_sweep.yaml`: scaling/K sweep.
+- `manifests/source_score_bonus_pick001_stack005.*`: source-score bonus configs.
+
+### `runs/`
+
+Reproducible experiment artifacts. Each serious run should contain:
+
+```text
+config.yaml
+command.txt
+git_hash.txt
+data_hash.txt
+split_hash.txt
+train.log
+eval.log
+metrics.json
+metrics_by_task.json
+metrics_by_seed.json
+table.tex
+```
+
+Markdown `report.md` files were removed per the current cleanup request. Use
+`metrics.json`, `table.tex`, logs, and this README instead.
+
+High-value run directories:
+
+- `runs/data_accounting`: verified data counts.
+- `runs/leakage_audit`: original leakage audit.
+- `runs/leakage_audit_rgb_refs`: RGB-ref leakage audit.
+- `runs/tangent_reconstruction`: original tangent reconstruction check.
+- `runs/tangent_reconstruction_rgb_refs`: RGB-ref tangent reconstruction check.
+- `runs/action_bound_audit_rgb_refs`: action-bound audit.
+- `runs/chart_observation_embeddings_rgb_refs`: RGB-stat embedding export.
+- `runs/chart_object_embeddings_rgb_refs`: object-layout embedding export.
+- `runs/chart_feature_audit*`: feature-source audits.
+- `runs/ctt_residual_full_seed{0,1,2}`: full residual CTT training.
+- `runs/ctt_gated_residual_full_seed{0,1,2}`: full gated residual CTT training.
+- `runs/ctt_base_context_obs_test_envclip_k16_rollout_comparison`: current
+  strongest measured support artifact.
+- `runs/ctt_base_context_obs_train_cal_envclip_k16_rollout_comparison`: train
+  calibration rows for K=16 `env_clip`.
+- `runs/ctt_base_context_obs_dominance_envclip_k16_train_to_test`: K=16 LCB
+  dominance auto threshold, negative selector result.
+- `runs/ctt_base_context_obs_dominance_envclip_k16_train_to_test_tau0`: K=16
+  LCB tau0 fallback, matches base but does not improve.
+- `runs/ctt_base_context_obs_learned_dominance_chartcompat_obs_utility_task_envclip_k16_train_to_test`:
+  best current train-clean selector diagnostic.
+- `runs/ctt_base_context_obs_nonlinear_dominance_chartcompat_obs_*`: fixed
+  nonlinear selector diagnostics.
+- `runs/summary_ctt.csv`: global run summary table.
+
+### `logs/`
+
+Cluster stdout/stderr and daemon logs.
+
+- `logs/*.out` and `logs/*.err`: Slurm job output/error files.
+- `logs/auto_sync_hf.log`: legacy HF auto-sync log.
+- `logs/auto_sync_hf.pid`: legacy auto-sync PID file.
+- `logs/workflow/`: workflow logs.
+
+### `outputs/`
+
+Local generated outputs and HF sync state.
+
+- `outputs/hf_sync/hf_sync.log`: one-shot HF sync log.
+- `outputs/hf_sync/hf_sync_daemon.log`: 15-minute daemon log.
+- `outputs/hf_sync/last_manifest.json`: latest HF sync manifest.
+- `outputs/hpc/`: HPC outputs.
+- `outputs/external_vla*`: external VLA export/probe outputs.
+- `outputs/manifest_*`: manifest smoke outputs.
+- `outputs/phase5_*`: legacy phase-5 outputs.
+- `outputs/smoke_*`, `outputs/train_smoke_*`: smoke outputs.
+- `outputs/wheels`: local wheel/cache outputs.
+
+### `results/`
+
+Legacy result files. Markdown summaries were removed. Any remaining non-Markdown
+files are legacy evidence or machine-readable artifacts. Current CTT evidence
+should be read from `runs/`, not `results/`.
+
+### `tests/`
+
+Regression tests. Key tests:
+
+- `tests/test_metrics.py`: canonical metric behavior.
+- `tests/test_causal_action_metrics.py`: causal action metric checks.
+- `tests/test_ctt.py`: CTT model/training/eval checks.
+- `tests/test_chart_features.py`: chart feature leakage invariants.
+- `tests/test_dominance_selector.py`: dominance selector, PCCE, safety fields.
+- `tests/test_cil_schema.py`, `test_cil_images.py`: CIL data/image schema.
+- `tests/test_maniskill_*`: ManiSkill backend/lattice/render/rollout tests.
+- `tests/test_tangent_*`: positive tangent generator baselines.
+- `tests/test_transfercritic.py`: transfer critic checks.
+- `tests/test_slurm_templates.py`: Slurm template sanity.
+
+## Current Best Evidence
+
+### K=16 `env_clip` measured support
+
+Run:
+
+```text
+runs/ctt_base_context_obs_test_envclip_k16_rollout_comparison
+```
+
+Key held-out test values:
+
+| Metric | Value |
+| --- | ---: |
+| Rows | 144 |
+| Base success | 0.2917 |
+| Score-only selected success | 0.2778 |
+| Proposal oracle success | 0.5694 |
+| Hidden chart oracle success | 0.7292 |
+| OutcomePTR@16 | 0.5486 |
+| Success support gap | 0.2014 |
+| Success selector gap | 0.2917 |
+| Action-bound unsafe | 0.0000 |
+
+Interpretation: support is strong; selector is not.
+
+### Best current K=16 train-clean learned selector
+
+Run:
+
+```text
+runs/ctt_base_context_obs_learned_dominance_chartcompat_obs_utility_task_envclip_k16_train_to_test
+```
+
+Key values:
+
+| Metric | Value |
+| --- | ---: |
+| Selected success | 0.3542 |
+| Coverage | 0.6597 |
+| Proposal oracle success | 0.5694 |
+| Success selector gap | 0.2431 |
+| Pairwise causal calibration ECE | 0.0150 |
+| Pair count | 12,434 |
+
+Interpretation: RGB-stat chart compatibility helps, but the selector gap is
+still too large for a deployment-clean method success claim.
+
+### K=16 score-source LCB dominance
+
+Runs:
+
+```text
+runs/ctt_base_context_obs_dominance_envclip_k16_train_to_test
+runs/ctt_base_context_obs_dominance_envclip_k16_train_to_test_tau0
+```
+
+Key values:
+
+| Variant | Selected | Coverage | Unsafe exec. | PCCE | Selector gap |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| auto | 0.2778 | 0.1319 | 0.0000 | 0.1633 | 0.2986 |
+| tau0 | 0.2917 | 0.1111 | 0.0000 | 0.1633 | 0.2986 |
+
+Interpretation: the LCB fallback records the requested safety/calibration
+fields, but it does not solve dominance. It is a negative Part-G diagnostic.
+
+## How To Run Core Commands
+
+Use the local virtual environment when possible:
+
+```bash
+.venv/bin/python -m pytest tests/test_metrics.py tests/test_ctt.py tests/test_dominance_selector.py -q
+```
+
+Build the paper:
+
+```bash
+cd latex
+latexmk -pdf -interaction=nonstopmode main.tex
+```
+
+Refresh summary:
+
+```bash
+.venv/bin/python scripts/summarize_ctt_runs.py \
+  --run-root runs \
+  --out-csv runs/summary_ctt.csv \
+  --out-md runs/summary_ctt.md
+```
+
+Run K=16 LCB dominance auto:
+
+```bash
+.venv/bin/python scripts/eval_dominance_selector.py \
+  --calibration-input runs/ctt_base_context_obs_train_cal_envclip_k16_rollout_comparison/combined_measured_candidates.json \
+  --calibration-target-index data/cil_charts_rgb_refs/train/index.json \
+  --eval-input runs/ctt_base_context_obs_test_envclip_k16_rollout_comparison/combined_measured_candidates.json \
+  --eval-target-index data/cil_charts_rgb_refs/test/index.json \
+  --checkpoint-template 'runs/ctt_residual_base_context_obs_seed{seed}/model.pt' \
+  --out-dir runs/ctt_base_context_obs_dominance_envclip_k16_train_to_test \
+  --k 16 \
+  --bootstrap-samples 1000
+```
+
+Run leakage audits:
+
+```bash
+.venv/bin/python scripts/audit_cil_charts.py \
+  --chart-root data/cil_charts \
+  --run-root runs \
+  --out-dir runs/leakage_audit
+
+.venv/bin/python scripts/audit_cil_charts.py \
+  --chart-root data/cil_charts_rgb_refs \
+  --run-root runs \
+  --out-dir runs/leakage_audit_rgb_refs
+```
+
+Run tangent reconstruction checks:
+
+```bash
+.venv/bin/python scripts/check_tangent_reconstruction.py \
+  --chart-root data/cil_charts \
+  --out-dir runs/tangent_reconstruction
+
+.venv/bin/python scripts/check_tangent_reconstruction.py \
+  --chart-root data/cil_charts_rgb_refs \
+  --out-dir runs/tangent_reconstruction_rgb_refs
+```
+
+Start HF sync daemon:
+
+```bash
+bash scripts/hf_push_every_15m.sh
+```
+
+Current local daemon process was previously observed as PID `615094`; verify
+with:
+
+```bash
+ps -p 615094 -o pid,etimes,cmd
+```
+
+## Hugging Face Remote
+
+Repository:
+
+```text
+anhtld/vla
+```
+
+The workspace is uploaded under:
+
+```text
+workspace/
+```
+
+Large scratch roots are uploaded under:
+
+```text
+scratch/
+```
+
+Use:
+
+```bash
+.venv/bin/hf auth whoami
+.venv/bin/hf upload anhtld/vla <local_path> workspace/<remote_path>
+```
+
+Avoid uploading secrets. The sync scripts exclude `.env`, token/secret/key
+patterns, virtualenvs, git internals, containers, and native library folders.
+
+## Development Rules
+
+- Do not claim method success unless the result is implemented, measured,
+  leakage-audited, and logged.
+- Do not call distance proxy metrics PTR. Use PPTC for proxy support.
+- Do not compute OutcomePTR, SelectorRegret, or SupportGap from proxy-only
+  candidates.
+- Train-only retrieval must use train charts only.
+- Validation/test outcomes are evaluator-only.
+- Keep V0/V1/V3 as diagnostics/baselines, not final method claims.
+- Use K=16 `env_clip` as the current bounded-action diagnostic convention until
+  a better action representation is implemented and measured.
+- Treat deterministic object-layout features as a negative result unless a new
+  measured run proves otherwise.
+- The next real method work is a stronger deployment-visible chart/outcome
+  representation and dominance model, not more wrapper text.
+
+## Immediate Next Actions
+
+1. Replace hand-built RGB/object descriptors with learned visual-language or
+   task/object/contact-stage tokens.
+2. Train a stronger train-only utility/dominance model under the K=16
+   `env_clip` convention.
+3. Re-run measured selection on held-out test after the representation fix.
+4. Add actual collision/contact safety labels beyond action-bound validity.
+5. Keep the paper honest: support is promising, selector is not solved.