docs(dev): add lean agent guidance and prototype hardening research

AGENTS.md

@@ -0,0 +1,44 @@
+# Development
+
+## Code map
+- `facts.py`: pure game-state parsing and arithmetic.
+- `brain.py`: decision policy; returns one `Decision` per observation.
+- `run.py`: observe–decide–act loop, captures, and session attribution.
+- `sts2.py`: local game HTTP client. `jev.py`: TypeSafe model client and gates.
+- `migrate.py`: dataset migration and integrity checks.
+- `CONTEXT.md`: domain terms. `docs/DATASET.md`: dataset schema and limits.
+- `docs/research/11-prototype-hardening.md`: audited findings and the proposed development order.
+- Treat historical claims in `docs/DESIGN.md` as context; verify against current code.
+
+## Checks
+Use Python 3.10+ from the repository root. Core Python code uses the standard library.
+
+```sh
+python3 test_facts.py && python3 test_brain.py && python3 test_run.py
+python3 migrate.py --check-only
+bash -n eval_batch.sh ab_card_skip.sh
+```
+
+Tests are executable scripts, not unittest/pytest suites. They need no model or game connection.
+Some checks read local captures and game history when available.
+Prefer integration/end-to-end checks; keep only essential regression tests and use temporary isolated probes for unit-level edge cases.
+
+## Invariants
+- Execute one game action, then read a fresh observation. Card indices can change after each action.
+- Compute arithmetic and legality in code, not in Jev. Confidence does not prove correctness.
+- Keep deterministic fallbacks usable with `client=None`. Test model paths with stubs.
+- Preserve session/step attribution. Run outcomes are not per-decision correctness labels.
+- Split evaluation data by run, not by decision row.
+
+## Safety and scope
+- Default to offline tests. Ask before live game actions, model calls, or evaluation batches.
+- `run.py --dry-run` sends no action POSTs or deck-cache writes; state reads, model calls, and logs still run.
+- Never print or commit credentials. Do not read secret files for development checks.
+- Do not rebuild `dataset/`, change captures, or edit `vendor/` unless the task requires it.
+- `migrate.py --verify` rebuilds data; use `--check-only` for routine verification.
+- Keep code simple and lean. Use `docs/` as the detailed reference for humans and agents.
+- Keep changes focused. Prefer `jj status` and `jj diff`; do not create commits unless asked.
+
+## Pi
+Project prompts live in `.pi/prompts/`: `/sts2-check` and `/sts2-review`.
+They provide instructions, not a sandbox or permission enforcement.