0xrsydn/sts2-bot
1
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
sts2-bot/AGENTS.md

3.3 KiB
Raw Blame History

Development

Code map

  • facts.py: pure game-state parsing and arithmetic.
  • brain.py: policy entry point; dispatch, navigation, shops, and minigames.
  • policy/combat.py and policy/selection.py: combat and selection proposals.
  • policy/context.py: shared Decision, pending actions, and session-owned PolicyContext.
  • run.py: observe–decide–act loop and session attribution.
  • recording.py: linked session journals; schema and limits in docs/RECORDING.md.
  • run_state.py: reported run identity and combat-pile provenance; see docs/RUN_STATE.md.
  • 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/POLICY.md: policy boundaries. 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. Use direnv allow with nix-direnv or nix develop for the pinned toolchain. nix flake check -L runs the offline checks below in an isolated environment. See docs/DEVELOPMENT.md for setup and platform limits.

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.
  • Keep policy memory session-owned. Proposals do not record execution; reconcile accepted requests with fresh observations.
  • 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 observation/proposal/attempt links. Flush attempt intent before POST; acceptance is not proof of a game effect.
  • 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; state/identity reads, model calls, and logs still run.
  • The runner ignores legacy deck.json. Combat-pile evidence is session-local and is not the persistent deck.
  • 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.