RustyRPN/AGENTS.md

AGENTS.md — working rules for coding agents on RustyRPN

readme.md is the single source of truth for design decisions. The roadmap lives in Documentation/roadmap.md. Read at minimum these before starting work:

• readme.md §Workflow — the TDD loop you are expected to follow
• readme.md §General guidelines for AI — hard prohibitions
• readme.md §Data formats — input formats, edge cases, and where test fixtures live
• Documentation/roadmap.md — what is green, red, or unstarted

Environment

• Rust stable (edition 2024, MSRV 1.85) via rustup; on this machine the shims are at /opt/homebrew/opt/rustup/bin (in PATH via ~/.zprofile).
• All cargo commands run from Application/: cargo test, cargo fmt --check, cargo clippy.
• Workspace members: src/core (rpn-core, domain logic), src/cli (rpn-cli, binary rpnc). src/server and src/web are planned but not scaffolded yet.

Current state (verify against Documentation/roadmap.md; update both when it changes)

• core/config: implemented, tests green.
• core/db: tests committed and RED (they reference functions that do not exist yet — the crate does not compile its test target). The first task is the minimal implementation to turn them green. Do not weaken or rewrite these tests to make them pass; they encode agreed behaviour.
• cli: fn main() {}. Command surface specified in Documentation/cli.md.
• feature/epsilon-parser: does not exist yet. Create it from main when parser work starts (a stale early pointer was deleted 2026-10-08). Workflow step 2 (spec + test checklist agreed with the maintainer) must complete before any failing test is written.

Test data

• Real samples: Application/data/test_input/ — gitignored, never committed, never embed their values in test files or fixtures output.
• Committed sanitized fixtures: Application/data/fixtures/ (epsilon / tsdrms / subfranchise). Parser tests should use these. Regenerate with python3 Application/scripts/sanitize_samples.py; after any change to fixtures run python3 Application/scripts/check_fixture_leaks.py and require exit 0.
• Documentation/schema.sql is the v1 domain schema; it is also the embedded migration (test-asserted in core/db).

Git rules

• Work on a named feature branch; commit per passing test (workflow step 5.3). Commit messages are the project's code documentation: format area: imperative summary, body explaining why.
• Never commit or push to main without the maintainer's explicit approval. Never rewrite history.
• Never commit: config files (except config.template.toml), anything under data/ except data/fixtures/, secrets, real customer data.

Definition of done for a task

1. cargo test green (all crates), cargo fmt --check and cargo clippy clean for files you touched.
2. Every checklist item from the task's spec verified — by a test or by a command you actually ran, not by inspection alone.
3. Documentation/roadmap.md updated in the same branch (and readme.md if a design decision changed).
4. A short summary for the maintainer: what changed, what is still red, suggested next step.