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

2.5 KiB
Raw Blame History

Development

Code map

  • facts.py: pure game-state parsing and arithmetic.
  • brain.py: decision policy and session-owned PolicyContext; proposes one action 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.

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 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.