65 lines
2.5 KiB
Markdown
65 lines
2.5 KiB
Markdown
# 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.
|