l123 AGENTS.md

AGENTS.md — L123 project guide

Session-level conventions for working on L123 (a Lotus 1-2-3 R3.4a for DOS TUI clone). Living document — edit freely as conventions emerge.

Canonical docs — read these before making decisions

• docs/SPEC.md — what L123 is. Scope, modes, menu tree, authenticity contract.
• docs/PLAN.md — implementation milestones, risk register, test strategy.
• docs/MENU.md — complete menu tree; source of truth for l123-menu.

If code and doc disagree, fix the doc first, then write code to match.

---

How we develop: red / green / refactor (strict TDD)

Test-first, always. Every change to shipping code follows this loop:

1. Red

Write the failing test(s) that describe the behavior you want. Run them. They must fail for the right reason — not a compile error, not a panic from unrelated setup. cargo test -p <crate> shows a clean failure in the new test, pointing at the behavior being specified.

If you can't figure out what the test should assert, the behavior isn't specified enough yet. Re-read SPEC, or write the acceptance transcript first, then come back.

2. Green

Write the minimum code to make the tests pass. No refactoring, no extra features, no speculative abstractions, no helpers you "might need later." If a test is green before you meant it to be, delete the extra code until only the test's claim is covered.

3. Refactor

Now, and only now, clean up. Re-run tests after every small refactor step. Never refactor with red tests. Clippy must stay clean: cargo clippy --workspace --all-targets -- -D warnings.

Exceptions (be honest — they should be rare)

• Pure docs/comment changes.
• Throwaway spikes — must be marked WIP: spike and deleted before landing. Any code you keep must have tests written before it.

---

Test tiers

Every feature lands with tests at one or more of:

1. Unit tests — colocated with source (#[cfg(test)] mod tests). Pure-function tests; no ratatui, no IronCalc.
2. Engine integration tests — crates/l123-engine/src/ironcalc_adapter.rs under #[cfg(test)]. Drive the Engine trait against real IronCalc.
3. Acceptance transcripts — tests/acceptance/*.tsv, run by crates/l123-ui/tests/acceptance.rs. Keystrokes in, on-screen state out. Every item in SPEC §20 "Authenticity Contract" gets ≥1 transcript before the claim can be called done.