Ransom-s-wake/AGENTS.md

Ransom's Wake — Repository rules

These rules apply to the whole repository. They are mandatory for human and AI contributors.

Read before changing code

1. Read docs/ENGINEERING_GUARDRAILS.md.
2. Read the relevant technical baseline under docs/.
3. Check docs/adr/ for decisions affecting the change.

Prototype boundary

• src/ and scenes/ contain the disposable POC A/B implementation.
• They may be changed only for an explicitly requested prototype correction.
• Production code must not import, extend, copy, or silently promote code from src/ or scenes/.
• Reuse a validated behavior by rewriting it behind a production contract and by linking the relevant baseline in the change description.

Production boundary

New production code belongs under game/ and follows these dependency rules:

• game/domain/: pure rules and typed data; depends on no other game layer.
• game/application/: use cases and ports; may depend only on domain.
• game/world/: Godot actors and physics adapters; may depend on application and domain.
• game/presentation/: HUD and rendering; may depend on application and read-only domain data.
• game/infrastructure/: saves, audio, platform and input adapters; may depend on application and domain.
• game/composition/: scene assembly; this is the only layer allowed to wire all other layers together.

Do not create a generic utils, helpers, common, or shared dumping ground. Reusable behavior must have one named owner in the layer responsible for it.

Implementation rules

• One authoritative implementation per concept.
• Use typed objects or resources across production boundaries, not anonymous dictionaries with implicit keys.
• UI and renderers never calculate gameplay rules or mutate world state directly; they issue application commands and consume snapshots/events.
• Domain code does not access Input, the scene tree, rendering, audio, files, clocks, or random global state.
• Randomness and time-dependent behavior must be injectable and deterministic in tests.
• New autoloads, cross-layer dependencies, save-format changes, or exceptions to these rules require an ADR in docs/adr/.
• A bug fix requires a regression test unless the behavior cannot reasonably be automated; document that exception.

Required verification

Run this command before declaring a code change complete:

bash scripts/quality_gate.sh

Do not weaken, skip, or delete a failing check to make a change pass. Fix the cause or record an explicit architectural decision.