Cursor Rules for DynoAI

# Cursor Rules for DynoAI

## Automatic Model Selection

### Sonnet 4.5 Max
Use for:
- Any changes to math-critical files:
  - `core/ai_tuner_toolkit_dyno_v1_2.py`
  - `core/ve_operations.py`
  - `core/io_contracts.py`
  - `experiments/protos/*.py`
- Repository-wide refactoring operations
- Structural changes affecting multiple subsystems
- Safety-critical operations (VE apply/rollback logic, clamping enforcement)
- Complex debugging involving tuning algorithms

### Sonnet 4
Use for:
- Normal feature development
- Test implementation and updates
- Documentation improvements
- Web service API development
- Script and automation work
- Bug fixes in non-critical code

### Haiku
Use for:
- Single-file trivial edits
- Typo fixes
- Comment updates
- Formatting-only changes
- Simple variable renames within one file

---

## Safety Guardrails

### Confirmation Required
- Deleting any directory
- Modifying more than 25 files in a single operation
- Changes to `core/`, `experiments/protos/`, or test harnesses
- Dependency updates (requirements.txt)
- CI/CD workflow changes

### Read-Only by Default
- `archive/` - Historical code and artifacts (reference only)
- `experiments/` - Research kernels and experiment outputs (unless explicitly instructed)
- `tables/` - Calibration base tables (unless performing VE operations)

### Protected Operations
- Never modify tuning math or algorithms without maintainer approval
- Never weaken test assertions to "make tests pass"
- Never skip safety tests (selftests, kernel harnesses, pytest)
- Never commit secrets, API keys, or credentials

---

## Testing Expectations

### After Modifying Runtime Code
Run in this order:
```bash
python tests/selftest.py
python tests/acceptance_test.py
python tests/kernels/test_k1.py
python tests/kernels/test_k2.py
python tests/kernels/test_k2_fixed.py
python tests/kernels/test_k3.py
python -m pytest tests/unit tests/integration -v
```

### For Structural Changes
```powershell
pwsh scripts/dynoai_safety_check.ps1 -RunSelftests -RunKernels -RunPytest
```

### Before Committing
- All tests must pass
- No new linter errors introduced
- Documentation updated if behavior changed

---

## Code Review Standards

### Math-Critical Changes
- Require design document
- Require validation plan with before/after comparisons
- Require maintainer approval
- Extended review period (3-7 days minimum)
- Must include test evidence in PR

### Standard Changes
- Self-review completed
- Tests added for new functionality
- Documentation updated
- CI passes

---

## Documentation

### When to Update
- **Always:** New CLI flags, API endpoints, or workflows
- **Always:** Changes to test requirements or safety policies
- **Usually:** Bug fixes affecting user-facing behavior
- **Sometimes:** Refactoring (if it impacts usage)

### Key Documents
- `README.md` - Overview, quick start, troubleshooting
- `docs/DYNOAI_CORE_REFERENCE.md` - Minimal runnable examples
- `docs/DYNOAI_SAFETY_RULES.md` - Safety policies
- `docs/DYNOAI_ARCHITECTURE_OVERVIEW.md` - System architecture

---

## Common Patterns

### Adding a New Test
```python
# tests/unit/test_new_feature.py
from pathlib import Path
import pytest

ROOT = Path(__file__).resolve().parents[2]  # Repo root

def test_new_feature():
    """Test description."""
    # Test implementation
    assert True
```

### Adding a New CLI Flag
1. Update `core/ai_tuner_toolkit_dyno_v1_2.py` argparse section
2. Add test coverage in `tests/selftest.py` or new unit test
3. Update `docs/DYNOAI_CORE_REFERENCE.md` with example
4. Update `README.md` if user-facing

### Adding a New Experimental Kernel
1. Create `experiments/protos/kN_description_v1.py`
2. Implement `kernel_smooth()` function matching signature
3. Add to `experiments/run_experiment.py` IDEAS dict
4. Create `tests/kernels/test_kN.py` harness
5. Document in experiment notes

---

## Emergency Procedures

### Rollback a Bad Commit
```bash
git revert <commit-hash>
git push origin main
```

### Restore VE Table After Bad Apply
```python
from pathlib import Path
from core.ve_operations import VERollback

VERollback().rollback(
    current_ve_path=Path("tables/VE_Front_Bad.csv"),
    metadata_path=Path("tables/VE_Front_Bad_meta.json"),
    output_path=Path("tables/VE_Front_Restored.csv"),
)
```

### Recover from Failed Reorganization
```powershell
# If backup exists
Remove-Item -Recurse -Force DynoAI_2
Copy-Item -Recurse DynoAI_2_backup_<timestamp> DynoAI_2
```

---

By following these rules, we maintain DynoAI's tuning accuracy, customer safety, and code quality standards.