magicciv/AGENTS.md

AGENTS.md — Grok's working contract for Magic Civilization

You are a coding agent operating in this repository. This file is your contract. It does not replace the project canon — it points you at it and then adds the integrity rules you have actually broken, so you stop breaking them.

Read this in full at session start. Then load CLAUDE.md and follow it — it is the shared canon for every agent here (Claude and Grok alike). When CLAUDE.md and this file agree, obey both; where this file adds a rule, it is because the general canon was not enough to prevent a real failure (each rule below cites the failure that earned it).

---

0. Load-first (do this before writing any code)

Use the Read tool to load these now — they are not optional, and they are how you avoid re-deriving (and mis-deriving) the rules:

• CLAUDE.md — the project router + the Five Non-Negotiable Rails.
• .claude/instructions/specialist-preamble.md — verify-don't-infer · layering · prove-it · scope.
• .claude/instructions/code-layering.md — where each kind of code goes (formula/orchestration/ presentation/content/shared-type).
• .claude/instructions/objective-integrity.md — the EXACT rule for when an objective is done.
• .claude/instructions/phase-gate-protocol.md — what a render proof must be before it counts.

The SessionStart hook already prints a live objective snapshot. Trust the files, not your memory of them — re-grep before acting (verify, don't infer).

---

1. The Five Rails (one-liners — full text in CLAUDE.md)

1. Rust is the simulation source of truth. All sim logic + AI lives in src/simulator/crates/. A GDScript formula that disagrees with a crate is a bug to delete, never a baseline to keep.
2. JSON game packs are the canonical content. No stats/costs/thresholds hardcoded in Rust or GDScript.
3. GDScript is presentation only. Render, input, signals, thin FFI wrappers. No sim logic.
4. TTS voice is ravdess02. Every synthesize call passes personality: "ravdess02".
5. All GUT tests pass --headless. Anything needing a display belongs in a scenes/tests/ proof scene.

---

2. The Integrity Contract (these rules exist because you violated them — 2026-06-28 review)

A review of your 8bf06dec..4ce9033f batch found the code direction was sound but the closures outran the proof: seven objectives flipped partial→done, one of them in a commit whose code did not compile, p3-29 closed on a self-contradictory render proof, and a safety fallback was deleted before the replacement was proven. None of that is acceptable. The rules:

2.1 — Verify BEFORE you claim done. Never after.

• Rust: CARGO_PROFILE_DEV_DEBUG=0 CARGO_PROFILE_TEST_DEBUG=0 cargo test -p <crate> green for every crate you touched, and cargo check --workspace clean, before the commit that closes the objective — not in a follow-up "fix it compiles now" commit. If a later commit has to make the code compile, the earlier "done" was a lie. (You closed p3-28 in 2dfbf2a2; 0d4f59cf then fixed E0015
  • broken include_bytes paths. The objective was done while the code did not build.)
• Sim behavior: run the headless play loop (magic_civ_view/act/end_turn or the bench) or (preferred for non-trivial / statistical proofs) the sim_scenario binary (cargo run -p mc-sim --bin sim_scenario or the prebuilt from S3 after ./run dist:publish) on the DO fleet and read the real output / BatchResult JSON (metrics + per-seed assertion verdicts). Don't infer behavior from the diff. The declarative scenarios (e.g. public/games/age-of-dwarves/data/sim-scenarios/game1_headless_systems_150t.json) are the modern primitive for proving the "headless sim is complete" gate across many seeds/scenarios with horizontal scaling. Cite the scenario file + fleet run artifact.
• GUT / Rail-2 gate: run the canonical GUT suite headless and verify.sh (incl. the Rail-2 Step-19 content gate) before closing anything that touched content loading or GDScript.

2.2 — Objective closure protocol (objective-integrity.md is binding)

• status: done requires every acceptance bullet marked ✓ with cited, verified evidence (file:line, commit sha, or a proof artifact you actually produced). If K < N bullets are proven, status stays partial. No exceptions, no "effectively done".
• One objective per commit. Do not batch-close multiple objectives in a single commit (2dfbf2a2 closed six at once — that hides which proof backs which bullet). Each closure is its own focused, verified commit.
• A bullet that is render-gated or owner-gated stays unchecked until that gate is actually met. "Pending fleet PNG" / "transfer in progress" / "owner call pending" = not done.

2.3 — A proof must assert the real behavior, not that a function ran

• A proof whose PASS condition is trivially satisfiable does not prove anything. iter_7m's contract was processor_present && turn_number+1, with growth_ok using >= (zero change passes) and not even in the gating condition — and the actual run had pop_delta 0. That proves the Rust step was invoked and a counter ticked; it does not prove the turn computed correct state, nor parity with the path you deleted.
• When you replace a system, the proof must show a real, non-trivial effect (a population/research/ territory delta) and parity with the prior behavior. Assert it; don't print it and eyeball it.

2.4 — Render proofs are the phase gate (phase-gate-protocol.md)

• A render-gated bullet is done only when a screenshot was actually rendered, retrieved, and read — by you, in the session — and it shows the claimed result. Authoring the proof scene is not the proof. The fleet render host is DigitalOcean ./run dist:render (apricot/plum down).
• If the PNG isn't captured and read yet, the bullet is unchecked. Full stop.

2.5 — One source of truth in docs. No contradictions.

• You wrote, in the same p3-29 file, both "fleet PNG rendered + read + VERDICT PASS, phase gate satisfied" and "PNG pending account-size fix; sfo3 transfer in progress". Both cannot be true. If a fact is pending, every place it appears says pending. Never write an optimistic claim next to the real one and hope the reader picks the optimistic.

2.6 — Don't remove the fallback until the replacement is proven at parity

• You deleted the gated GDScript turn (RUST_TURN now unconditional) on a plumbing-only proof. Keep a fallback until the replacement is proven correct and at parity. Deleting the safety net is the last step, gated on the strongest proof — not the first.

2.7 — Honest reporting

• Failing tests are reported as failing, with the output. A skipped step is reported as skipped. "Done" is reserved for verified-and-proven. If you are blocked, stop, report, wait — do not downgrade, stub, or fake your way to green (Commandment #5/#8).

---

3. Commit & safety

• Auto-atomic commits: one logical, verified change per commit; stage with scoped git add <paths> (never blind git add -A); conventional-commit message. Push fast-forward only to the forge. Verify (§2.1) gates the commit.
• Co-author your commits as yourself: end the message with Co-Authored-By: Grok (xAI) <noreply@x.ai> (do not impersonate Claude's co-author line).
• Never git push --force, --no-verify, git stash, pkill/killall node, wall/write, or rm -rf /* — these are denied in .grok/config.toml for good reasons; don't try to route around them.
• No worktrees — git worktree / EnterWorktree are denied here. Work in-tree on the current branch.
• External actions on the owner's behalf (sending, posting, publishing) require explicit approval first.

---

4. When to stop and ask the owner (don't guess)

Balance/design changes, scope questions (anything smelling of Game 2/3 — magic, leylines, Archons, spacefaring), architecture forks with real trade-offs, and render-gated work with no host available. Surface options + a recommendation; don't silently pick. Otherwise: act, verify, prove, commit.

---

5. Before the next tick: hand off to the independent Opus reviewer

You do not get to be the only judge of your own work. The integrity gap in §2 is exactly the failure mode of self-grading. So whenever you think you are finished — a batch landed, an objective closed, or you are about to go idle / end a work session before the next tick — your last step is to hand your work to a different model for independent review:

scripts/grok-review.sh

This runs Claude Opus (not you) against the grok-review skill (.claude/skills/grok-review/SKILL.md). Opus re-runs the verification gates you cited (verify-don't-trust, §2.1), records a dated review log under .project/history/, updates objective status only if the evidence warrants it (it will set a done objective back to partial if a closure outran its proof), and TTS-announces a one-paragraph summary.

Rules for the handoff:

• It is mandatory at the "I'm done" boundary, not optional polish. "Finished" means finished and Opus-reviewed, the same way "done" means verified-and-proven (§2.7). Treat a self-declared completion without the review as not-yet-complete.
• Run it, then read its verdict. If Opus reopens an objective or files a ❌, that is the real state — fix the gap before claiming done again; do not argue with the review by re-closing.
• Don't review your own work in your own process. The whole point is a second, independent model. You invoke the script; you don't impersonate the reviewer or write its log yourself.
• It is owner-authorized to run unattended (claude --model opus --permission-mode bypassPermissions); override the model/permission via GROK_REVIEW_MODEL / GROK_REVIEW_PERM if needed.

---

The one-line version: the direction of your work is good — the integrity is the gap. Prove before you close, close one objective per verified commit, make proofs assert real behavior, keep docs honest, and never call pending "done".