settled-reach/docs/DEVOPS.md

DevOps Procedures

Operational procedures for building, testing, and running The Settled Reach.

Repository Layout

client/               Godot 4 client (GDScript, scenes, assets)
server/               Rust/bevy_ecs simulation server
tooling/              Build tools, scripts, asset pipelines
tests/                Integration and end-to-end tests (cross-boundary)
decisions/            Decision domain files (source of truth for all D/Q/R entries)
.config/              Configuration files (linters, formatters, CI)
.cache/               Local caches for testing/linting (gitignored)
docs/                 Design, architecture, briefings, workshops
db/                   SQLite ticketing + decisions database and connectors

Unit tests live inside their respective projects (server/ uses #[cfg(test)] inline + tests/ directory per D-030). The top-level tests/ directory is for integration tests that cross the client-server boundary (IPC round-trip, serialization fixtures, divergence tests).

Prerequisites

Tool	Version	Purpose
Rust (via rustup)	stable	Server compilation, clippy, rustfmt (auto-installed by make setup)
Godot	4.x	Client editor and runtime (auto-installed to ~/bin/ by make setup)
Python	3.x	Tooling scripts, db connectors
Make	any	Task runner (see below)
curl	any	Downloading Godot
unzip	any	Extracting Godot

Makefile Targets

All development operations go through the top-level Makefile. Run make with no arguments for a summary.

Setup

make setup                        # Install/verify all dev dependencies
GODOT_VERSION=4.4 make setup      # Pin a specific Godot version

Downloads and installs Godot to ~/bin/godot4, installs Rust clippy + rustfmt, and verifies Python/curl/unzip. Skips the download if the correct version is already installed. The GODOT_VERSION variable defaults to 4.6 and can be overridden.

Build

make build              # Build both client and server
make build-server       # cargo build in server/
make build-client       # Client builds are editor-managed (prints guidance)

Run

make server             # cargo run in server/
make client             # Launch Godot with client/ project

The server must be running before the client connects (subprocess launch will be automated later per D-020).

Test

make test               # Run all tests
make test-server        # cargo test in server/
make test-client        # gdUnit4 tests (headless runner pending)

Server tests use Rust's built-in test framework with #[cfg(test)] inline tests and tests/ integration tests (D-030). Client tests use gdUnit4 (D-030).

Lint

make lint               # Run all linters
make lint-server        # clippy (deny warnings) + rustfmt --check
make lint-client        # gdlint/gdformat (pending setup)

CI (Local)

Run the full CI pipeline locally before pushing:

make ci                 # Both pipelines
make ci-server          # lint-server → build-server → test-server
make ci-client          # lint-client → build-client → test-client

CI targets chain lint → build → test sequentially. A failure in any stage stops the pipeline.

Clean

make clean              # Remove build artifacts and .cache/ contents

Configuration Files

The .config/ directory holds shared configuration for linters, formatters, and CI. Examples of what goes here:

• Clippy configuration overrides
• gdlint/gdformat rules
• CI workflow definitions (before moving to .github/workflows/)
• Editor config templates

Project-specific config that lives in subdirectories (e.g., server/Cargo.toml, client/project.godot) stays in those directories. .config/ is for cross-cutting or shared configuration.

Cache Directory

.cache/ is gitignored and used for:

• Test result caches
• Linter caches
• Build artifact caches (if configured)
• Coverage reports

Agents and CI jobs can write freely to .cache/ without polluting the working tree. make clean clears it.

Testing Architecture (D-030)

Three-layer testing strategy:

1. Unit tests — Inside server/ (Rust #[cfg(test)]) and client/ (gdUnit4). Test individual systems in isolation.
2. Integration tests — Inside server/tests/ (Rust) and tests/ (cross-boundary). Test system interactions, IPC serialization round-trips.
3. Fixture-based tests — IPC serialization fixture files in tests/ for protocol regression testing. Known-good MessagePack payloads verified against both sides.

Key components:

• CauseChain (production ECS component) — Tracks causal attribution for testable observation sequences (D-030).
• Deterministic replay — Server simulation is deterministic given the same seed + input sequence. Replay logs enable regression testing (#201, critical).

SQLite Access

Never use the sqlite3 CLI — it crashes in Claude Code (std::bad_alloc).

Use wrapper scripts:

db/connectors/sqlite-query "SELECT * FROM tickets WHERE status='open'"
db/connectors/sqlite-exec "UPDATE tickets SET status='done' WHERE id=1"

Qdrant / Document Search

db/connectors/qdrant-search "asymmetric information design"
db/connectors/qdrant-index docs/briefings/tyre.md
db/connectors/qdrant-health
db/connectors/qdrant-count

Decisions System

Decisions are split into domain files under decisions/ (see decisions/README.md for the full index). A SQLite index table syncs metadata for cross-referencing and querying.

make decisions-sync       # Parse decisions/*.md into SQLite
make decisions-coverage   # Decision-to-ticket coverage by domain
make decisions-active     # List all active confirmed decisions
make decisions-orphan     # Decisions without implementing tickets

The sync runs automatically as part of make setup and via pre-commit hook. Markdown files are the source of truth; the DB is a derived index.

Commit Conventions

See the /commit skill (.claude/skills/commit/) for full details. Summary:

• Conventional commits: type(scope): summary
• Types: feat, fix, refactor, chore, docs, data, loc
• Scopes match project subsystems: client, server, engine, simulation, ui, audio, meta, etc.
• Imperative mood, lowercase, no period, max 72 chars
• CHANGELOG.md updated after each commit group