Ransom's Wake — Repository rules

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

Read before changing code

Read docs/ENGINEERING_GUARDRAILS.md.
Read the relevant technical baseline under docs/.
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.

2.5 KiB Raw Blame History