# ~/.codex/AGENTS.md

## Universal Agent Execution Rules

### Purpose
Execute the assigned task **correctly, reproducibly, and verifiably**.

Agents must follow a complete loop:  
define → measure → act → verify → record → iterate.

Results without evidence are invalid.
---

## 0. Software Stack (Mandatory)

All agent execution must assume and use the following stack unless explicitly overridden:

- Use **GPU**. FORCED.
- **Python 3.12** torch 
- **micromamba** for environment and dependency management. Always activate. ENV: py312.
- Training configuration policy is fixed: every training run must respect `/shared/home/rdelprete/PythonProjects/minssm/CONFIG.yml` unless explicitly overridden by the user.
- Training batch policy is fixed: use exactly `--range-batch-size 30` and `--azimuth-batch-lines 1000` at every optimizer step (no exceptions unless explicitly requested).
- Training data usage is fixed: do not subsample `n_train_section`; `train_tiles_used` must equal the maximum allowed. For now this is fixed to **300** tiles per run.
- Model source policy is fixed: use `teacher_sarSSM` from `old-working-code/model/SSMs/SSM.py` for SSM training. Do not introduce extra training model families unless explicitly requested.
- Model capacity policy: prefer a larger SSM configuration by default (higher state/model dimensions and/or depth). If performance is insufficient, explicitly test added nonlinear capacity (activation changes and MLP blocks/heads) and keep only verified improvements.
- Loss policy is fixed: always use composite loss `alpha * huber + beta * kde` (implemented as `loss_mode=huber_kde` with positive `huber_weight=alpha`, `kde_weight=beta`). Do not run pure-MSE/pure-magnitude-only objectives unless explicitly requested.
- Code style policy: enforce simplicity. Write clear, easy-to-follow, minimal code; prefer Pythonic constructs and avoid unnecessary abstraction or boilerplate.
- Use **multi-threading** when it provides measurable performance benefit
- Use **multi-processing** only if it can be shown to improve performance without compromising correctness or reproducibility

---

## 1. Task Definition (First, Always)

- Explicitly state:
  - Inputs
  - Outputs
  - Success criteria
  - Constraints and assumptions
- If anything is ambiguous, make it explicit before proceeding.

---

## 2. Baseline State

- Capture the initial state of the task:
  - Outputs, behavior, metrics, or artifacts
- If results can vary, run **≥3 times**
- Record execution context:
  - Environment, tools, versions
  - Hardware if relevant
- Store baseline artifacts in a versioned location  
  `outputs/baseline/XX_<timestamp>/`
- Store final versions (working) in a versioned location  
  `results/final/XX_<timestamp>/`

---

## 3. Evidence Collection

- Gather objective evidence relevant to the task:
- Measurements, logs, traces, observations
- Identify limitations, failures, inefficiencies, or risks
- Do not propose actions without supporting evidence.

---

## 4. Verification Gates (Define Before Acting)

- Define how correctness is checked:
- Exact match, tolerance, invariants, or rules
- Specify acceptable variability and tolerances
- Prefer automated checks

Any change that fails a gate is rejected.

---

## 5. Action Strategy (Justified)

Apply changes incrementally, prioritized as:
1. Remove unnecessary steps or assumptions
2. Simplify logic, structure, or workflow
3. Improve data or control flow
4. Add parallelism or acceleration only if needed
5. Change tools or platforms only with proven benefit

Each action must state its justification.

---

## 6. Iteration Discipline

For each iteration:
- Apply one scoped change
- Re-run verification
- Compare against baseline
- Record deltas and side effects

Stop when:
- Success criteria are met
- Further gains are marginal
- Correctness is at risk

---

## 7. Final Record

Deliver:
- Baseline vs final comparison
- Evidence supporting decisions
- Verification results
- Reproducible steps or artifacts
- Clear recommendation or conclusion
- FINAL OUTPUT: A concise table with summary of all runs and their outcomes.

---

## Hard Rules

- No assumptions left implicit
- No unverifiable claims
- No correctness regressions
- No irreproducible outcomes

If it cannot be verified, it does not exist.

<!-- FAST-TOOLS PROMPT v1 | codex-mastery | watermark:do-not-alter -->

## CRITICAL: Use ripgrep, not grep

NEVER use grep for project-wide searches (slow, ignores .gitignore). ALWAYS use rg.

- `rg "pattern"` — search content
- `rg --files | rg "name"` — find files
- `rg -t python "def"` — language filters

## File finding

- Prefer `fd` (or `fdfind` on Debian/Ubuntu). Respects .gitignore.

## JSON

- Use `jq` for parsing and transformations.

## Install Guidance

- macOS: `brew install ripgrep fd jq`
- Debian/Ubuntu: `sudo apt update && sudo apt install -y ripgrep fd-find jq` (alias `fd=fdfind`)

## Agent Instructions

- Replace commands: grep→rg, find→rg --files/fd, ls -R→rg --files, cat|grep→rg pattern file
- Cap reads at 250 lines; prefer `rg -n -A 3 -B 3` for context
- Use `jq` for JSON instead of regex

<!-- END FAST-TOOLS PROMPT v1 | codex-mastery -->
