Dune/AGENTS.md

# Working on Dune

Unofficial Dune board game: React 19, TypeScript, Vinext/Vite, Cloudflare
Workers and D1. Use npm and the checked-in lockfile; Node >=22.13 is required
for the in-memory SQLite tests. `tsx` is a pinned development dependency.

## Start small

- Read `README.md` and this guide first. See `docs/DEVELOPMENT.md` for the
  architecture map and focused verification commands.
- When continuing the complete project goal in this checkout, explicitly read
  `GOAL.local.md` if present; it is local and ignored, not automatically loaded
  project context. If absent, use the tracked guidance and the current user
  request. Never recreate it from credential-bearing handovers or commit it.
- Read `docs/CURRENT_STATUS.md` for current gates and `docs/RULE_DECISIONS.md`
  for existing rulings before reopening research.
- Run `git status --short` before editing; preserve other work.
- Search the relevant feature in `game/`, `components/`, `tests/`, and `docs/`.
  Use OMP `find` for unknown behavior, `grep` for known literals and bounded
  `read` for `game/engine.ts` and `components/game-table.tsx`; both are large
  orchestration files.
- `docs/IMPLEMENTATION_STATUS.md` is a historical evidence log, newest first.
  Read its opening checkpoint and the relevant feature document rather than
  loading the entire log. Verify historical claims against current code/tests.
- Do not read `github.md` for routine development: it is ignored private local
  credential material. Do not put secrets in logs or tracked files.

## Prototype the remaining scope first

- The user prioritizes working first versions of all remaining functions across
  Basic, Advanced and every expansion, followed by integration, refinement and
  polish. Reuse existing capabilities; batch related functions by dependency.
- The 26 September 2026 priority amendment puts game content first. Current
  playable continuation and blocking save fixes remain required; historical-save
  compatibility, exhaustive restore/seat audits, backup refinement and routine
  whole-database comparisons move to final polish after game content. Retain
  privacy, authorization, custody, no-reset safety, complete administration,
  relevant checkpoint checks and final recovery acceptance.
- Track missing, prototyped, integrated, verified and polished work in the
  existing checklist. Prototypes need usable controls, a legal AI path and saved
  continuation; placeholders and disconnected helpers are not completed features.
- A complete administration panel is required non-AI scope: room creation,
  lifecycle/removal, participant support, backups/restoration and operations.
  Follow `docs/ADMIN_PANEL.md`; retain authorization, privacy, audit history and
  saved-game safeguards. Adding this scope does not authorize a game reset.
- Keep focused checks for crashes, deadlocks, legality, custody, privacy and save
  integrity. Defer exhaustive combinations and visual polish until broader
  functional coverage, unless current failures require them.
- Defer full AI implementation, strategic refinement and difficulty calibration
  until all non-AI game features are complete. Until then, maintain only minimal
  legal participation and fix critical playability/correctness issues. Afterward,
  target approximately 75% higher-tier wins for each adjacent pair: Medium/Easy,
  Hard/Medium and Brutal/Hard. See `docs/AI_DEVELOPMENT_PLAN.md` for evaluation.
- Preserve required checkpoint checks, selective subagents and independent
  review for complex rules/privacy/persistence. Commit and push verified
  checkpoints under standing authorization. No user-imposed usage cutoff or
  routine account-usage check remains.
- Keep material rulings explicit and prototype independent work while pending.
  The user-authorized Advanced preview permits unfinished base-faction starts
  with a visible warning; see `docs/ADVANCED_PREVIEW.md`. Prototype evidence does
  not certify complete modes or open expansion/publication gates.

## OMP harness workflow

See [the OMP harness workflow](docs/DEVELOPMENT.md#omp-harness-workflow).
Live tool schemas take precedence. Use native planning, delegation and browser
tools, keep one integration owner and retain selective independent review for
complex rules, hidden information and persistence.

## Implement and verify

- Keep rule calculations/validation in focused `game/` modules; integrate them
  through the engine, player view, bots and UI as the feature requires.
- Preserve rejected-action immutability, physical card/force custody, private
  information boundaries, and JSON save/restore behavior. Reuse shared rule
  quotes instead of independently duplicating legality in bots or components.
- Add meaningful regressions to `tests/**/*.test.ts`; discovery is automatic.
  HTTP tests must start with `// @dune-suite integration`. Tests importing
  `node:sqlite` are classified as in-memory recovery tests automatically.
- During iteration: `npm test -- <filename-fragment>`; multiple fragments form
  a union. Use `--list` to inspect selection and `--name <regex>` to narrow
  cases. A filename typo fails rather than silently passing an empty suite.
- Before handing off code changes: `npm run check` (types, lint, offline tests).
  Run `npm run build` for app/build/dependency changes. Run
  `npm run test:integration` against a development server for HTTP, auth or
  persistence changes. Documentation-only edits need link/command review.
- Extend testing when failures or changed behavior justify it. Do not run AI
  calibration or browser acceptance for unrelated maintenance changes.
- If a sandbox blocks test subprocess pipes with `EPERM`, rerun the exact check
  with approved subprocess permissions. Do not disable isolation or skip tests
  to obtain a green result; the runner self-test checks real failure propagation.
- Report actual check results and limitations. Passing focused tests does not
  certify a complete faction, expansion or rules mode; preserve release gates.
- Verify relevant runtime changes on `https://dune.procrastination.games` after
  deployment, matching the deployed revision to the checkpoint. Use dedicated
  QA rooms and preserve existing games; local success is not deployed evidence.
  Follow `docs/VERIFICATION_WORKFLOW.md` for production checks and limitations.

## Preserve development state

- The user-authorized 2026-09-13 reset cleared old local games once; see
  `docs/VERIFICATION_WORKFLOW.md`. Preserve all games created afterward.
- Keep `.wrangler/state` and all saved games: do not delete/reset or
  intentionally damage existing games; extensive historical-save hardening
  follows the content-first priority above. Never reset a database to fix a
  test, migration, connection or gameplay problem. Migrations are additive.
- Reuse a running dev server. Restart only when a code/configuration change or
  observed server condition warrants it; there is no hourly restart schedule.
  Warn before interrupting human play, defer to a safe point, and verify
  restoration after a necessary restart. No recurring maintenance automation
  is installed; do not recreate it without a request.
- `.openai/hosting.json` identifies the existing Sites project. Preserve it.
  Follow the applicable Sites skills for site work; publication has existing
  completion and verification gates documented in `README.md`.
- Keep generated builds, caches and editor backups out of version control.
  Avoid mass formatting, unrelated dependency updates and broad engine rewrites.

## Efficient checkpoints

- Use `docs/VERIFICATION_WORKFLOW.md` for compact source-bound check reports
  and private saved-game/seat checks. Keep artifacts outside the checkout.
- Use subagents selectively for bounded independent tasks and complex reviews;
  they remain explicitly authorized. Share concise briefs and file ownership.
- Review, verify, commit and push completed checkpoints automatically under
  “Push all from now on.” Confirm push success; never force-push or expose secrets.