unzhakov
3c0a43ad4d
- Mark v0.4.0 as complete in TODO.md with all phases checked - Update Phase 4 items with actual outcomes - Next step: Track A 99Tc spectrum-shape analysis - Add AGENTS instruction to update project metadata on significant structural changes (package additions, version bumps, etc.)
73 lines
2.7 KiB
Markdown
73 lines
2.7 KiB
Markdown
# Agent Instructions — beta-spectrum
|
|
|
|
High-precision beta decay spectrum calculator. Extracts shape factor C(W) from ⁹⁹Tc beta spectrum to parametrize g_V coupling.
|
|
|
|
## Stack & Commands
|
|
|
|
```
|
|
pytest # all tests
|
|
nbmake notebooks/ # execute notebooks as tests
|
|
black --check . # formatting
|
|
ruff check . # linting
|
|
mypy . # type checking (strict)
|
|
bs_pnpi --nuclide Tc99 -vv --output ./output/verification.csv # debug verification
|
|
```
|
|
|
|
Install: `source ~/.pyenv/sci/bin/activate && pip install -e ".[dev]"`
|
|
|
|
## Git Workflow (GitHub Flow)
|
|
|
|
- **Never commit directly to `main`.** Always branch: `git checkout -b dev/<short-desc>`
|
|
- **Atomic commits** with **Conventional Commits** format:
|
|
- `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`
|
|
- Imperative mood, present tense, under 72 chars
|
|
- WIP commits fine on dev branches — squash before final merge
|
|
- **Commit each logical change** — don't wait for green. Use `git add -p`.
|
|
- **Rebase over merge** for linear history: `git rebase main` before merge.
|
|
- Delete branch locally + remotely after merge.
|
|
- **Update project metadata on significant changes:** When a commit changes the package structure, adds/removes modules, or bumps the version, also update `TODO.md` and `README.md` to reflect the new state. This keeps documentation in sync with code.
|
|
|
|
## TDD
|
|
|
|
Test-first by default. For new classes/functions: write failing test first.
|
|
|
|
- **RED** — failing test defining desired behavior
|
|
- **GREEN** — minimal code to pass
|
|
- **REFACTOR** — clean up, confirm tests still pass
|
|
|
|
State which phase you're in. Name phases explicitly.
|
|
|
|
### Python Testing Conventions
|
|
|
|
- Tests mirror package structure: `beta_spectrum/components/foo.py` → `tests/physics/test_foo.py`
|
|
- Shared fixtures in `tests/conftest.py`
|
|
- Classes organized by feature area (e.g., `TestComponentBasicProperties`)
|
|
- Descriptive names: `test_<function>_<expected_behavior>_<context>`
|
|
- Include implementation-level assertions (type checks, pre/postconditions)
|
|
- Use `hypothesis` for property-based tests where applicable
|
|
- Physics tests verify: physical constraints at thresholds, positivity, monotonicity, numerical stability
|
|
|
|
## Quality Gates
|
|
|
|
All must pass before merge:
|
|
|
|
```bash
|
|
pytest
|
|
nbmake notebooks/
|
|
black --check .
|
|
ruff check .
|
|
mypy .
|
|
```
|
|
|
|
Run individually to identify failures.
|
|
|
|
## Debug Verification (Final Step)
|
|
|
|
After quality gates pass, run:
|
|
|
|
```bash
|
|
bs_pnpi --nuclide Tc99 -vv --output ./output/verification.csv --plot ./output/verification.png --log-file ./output/debug.log 2>&1 | tee ./output/debug_stdout.log
|
|
```
|
|
|
|
Verify parameter consistency across all components. Save artifacts to `./output/`.
|