# 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:

```sh
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.