# AGENTS.md — Florence–Bridge OPTR

## Mission

Reproduce or extend Florence–Bridge continuations without changing the experimental contract. Treat `EXPERIMENT_CONTRACT.md` and the downloaded 20K state as authoritative.

## Non-negotiable rules

- Do not use Git operations for this handoff.
- Never overwrite the 20K common start, frozen proposal, or published 20.5K snapshots.
- New runs use new output directories.
- Resume new branches from the complete 20K Accelerate state, never from a 20.5K model-only file.
- Do not add code, path, manifest, or self-referential checksum launch gates.
- Keep dataset, episode, valid-anchor and proposal-support identity checks.
- Checkpoint readiness is established by required-file presence, byte size, loadability and semantic contract checks.
- Do not silently change world size, global batch, continuation seed, proposal, correction, budget or evaluation panel.

## Required local assets

Set these variables before launch:

```bash
export OPTR_PROJECT_ROOT=/path/to/this/repository
export OPTR_RUN_ROOT=/path/to/new/runs
export OPTR_PYTHON=/path/to/python
export FLORENCE_MODEL_PATH=/path/to/Florence-2-large
export BRIDGE_DATA_ROOT=/path/to/OXE_LEROBOT_DATASET
export BRIDGE_STATISTICS_PATH=/path/to/dataset_statistics.json
export BRIDGE_PROVENANCE_PATH=$OPTR_PROJECT_ROOT/manifests/data_provenance.json
export BRIDGE_FINGERPRINT_PATH=$OPTR_PROJECT_ROOT/manifests/content_fingerprints.json
export BRIDGE_MANIFEST_PATH=$OPTR_PROJECT_ROOT/manifests/valid_anchor_manifest_florence_scratch_v1.json
export COMMON_START_20K=$OPTR_PROJECT_ROOT/common_start_20k/checkpoints/steps_20000_accelerate
```

## Locked training contract

- Base: Florence-2-large; action head: DiT-B; horizon 16; state/action dim 7.
- Two GPUs, BF16, DeepSpeed ZeRO-2.
- Micro-batch 4/GPU × world size 2 × accumulation 8 = global batch 64.
- Parent seed 42; continuation/sampler seed 117465; model RNG 588643; transform RNG 298226.
- Resume step 20,000; stop and save at step 20,500.
- AdamW `(0.9, 0.95)`, eps `1e-8`, weight decay `1e-8`; clipping 1.0.
- Cosine scheduler, 5K warmup, min LR `5e-7`; preserve restored scheduler state.
- Residual: K=8, alpha=0.2, epsilon=0.1, linear within-episode interpolation, ordinary p/q correction.

## Commands

```bash
bash scripts/run_florence_bridge_arm.sh uniform <new-run-id>
bash scripts/run_florence_bridge_arm.sh residual <new-run-id> \
  proposals/residual_temporal_proposal_k8_alpha0.2.json
```

After start, verify exact resume at 20K, global batch 64, and the first update above 20K. A valid finish has exit code 0 and a complete step-20500 model snapshot.

## Evaluation

Use `scripts/evaluate_bridge_384_no_video.sh`. The locked panel has policy seeds 518957/765353/686765/516408; tasks Stack/Carrot/Spoon/Eggplant; 24 episodes per seed-task; BF16; no video; 384 rollouts per checkpoint. Preserve raw episode outcomes.

## Where to look first

- Bridge training and evaluation seeds for Rebuttal: `BRIDGE_SEED_PROTOCOL.md`
- Contract and factual provenance: `EXPERIMENT_CONTRACT.md`
- File roles and sizes: `ASSET_MANIFEST.json`
- Source authority and known corrections: `SOURCE_INVENTORY.md`
- Training config: `configs/florence_bridge_20k_plus500.yaml`
- Sampling implementation: `starVLA/dataloader/temporal_proposal.py`, `infoflow_sampler.py`
- Training integration: `starVLA/training/infoflow.py`, `train_starvla.py`