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

• Start here; use docs/DEVELOPMENT.md#context-index to open only the task's canonical paths, then the relevant README instructions if needed.
• 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 the opening of docs/CURRENT_STATUS.md for active work; use the bounded lookup in docs/DEVELOPMENT.md#canonical-feature-lookup for feature evidence and docs/RULE_DECISIONS.md for source authority and rulings.
• Run git status --short before editing; preserve other work.
• Locate the feature's helper and consumers from its existing evidence paths; search the relevant subsystem only when those paths are missing. 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 8 October 2026 user amendment sets the content order: complete Basic rules for all twelve factions first, then Advanced rules, then refine interactions. Usable first versions may be imperfect; mark provisional interpretations honestly rather than postponing all independent content. Defer administration detours, broad test suites, capture-resumption sweeps and combination campaigns. Use only brief changed-path smoke during rule delivery; batch type/lint feedback rather than repeating it for each small edit.
• The 2 October 2026 amendment supersedes the 26 September sequencing: implement all rules first; save/recovery, privacy and custody assurance plus comprehensive review follow afterward, not as per-prototype gates. Do not repeat seat-restoration audits, whole-database comparisons or preservation loops at each feature. This defers assurance, not printed card/force/payment mechanics, existing authorization, no-reset/no-deletion or secret protection.
• Track missing, prototyped, integrated, verified and polished work in the existing checklist. Prototypes need usable controls, connected rule behavior, a minimal legal AI path and changed-path smoke; placeholders and disconnected helpers are not completed features. Recovery certification comes later.
• 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.
• Iterate on the smallest failing case first. Keep legality, crashes, deadlocks, usable controls and minimal legal AI feedback; batch related rules by dependency before integration proof. Do not add privacy/custody/save audits to that loop.
• 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.
• Keep one shared integration owner and selectively delegate disjoint substantial slices. Rule-specific decisions may need bounded review now; comprehensive rules/privacy/persistence review follows all rules. Commit and push verified checkpoints under standing authorization. No 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 and compact handoff. Live tool schemas take precedence. Use native planning, delegation and browser tools; one integration owner freezes related work before running shared checks.

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.
• Reuse shared rule quotes rather than duplicating legality in bots or components. Preserve existing rejected-action immutability, physical card/force mechanics, private boundaries and JSON behavior; defer their assurance campaigns until all rules are implemented rather than making them new per-feature gates.
• 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> --name '<failing-case-regex>'. Inspect with --list; verify the intended case actually ran. Once repaired, run the related file union once, not after every tiny fixture edit. Filename typos fail instead of passing an empty selection.
• At a frozen related-rule batch, the integration owner runs npm run check:quick (types/lint), affected tests and the changed runtime path once. Build app/build/dependency changes; run relevant HTTP tests for actual boundary changes, not routine assurance. See docs/DEVELOPMENT.md#feedback-and-proof-schedule for the full schedule.
• Full npm run check, comprehensive review, recovery/privacy/custody audits, combinations, browser/deployed acceptance and required release proof remain due after all rules. Earlier broad checks need a concrete integration risk or observed failure, not habit. Documentation-only edits need link/command review. Do not run AI calibration or unrelated browser acceptance for maintenance.
• 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 and defer to a safe point. Observe server health after a necessary restart; comprehensive restoration assurance follows all rules. No recurring maintenance automation is installed.
• .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 reports and the deferred final saved-game/seat assurance commands. Keep artifacts outside Git.
• 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.” The intended origin is https://git.juiced.computer/admin/Dune.git; verify the destination and push success. Do not fall back to GitHub, force-push or expose secrets. Gitea Actions and container publication require a configured runner and credentials; a source push alone does not prove an image was published or deployed.