diff --git a/CLAUDE.md b/CLAUDE.md index 26dd5caef..dce2e577b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -30,15 +30,28 @@ db/ .claude/ agents/ # Agent personality files skills/ # Skill definitions -DECISIONS.md # Confirmed decisions (D-001+), open questions (Q-001+) +decisions/ # Decision domain files (source of truth) + README.md # Domain index and query examples + architecture.md # D-008, D-009, D-010, D-012, D-020, D-026, D-030, D-031 + perception.md # D-011, D-015, D-016, D-017, D-018, D-019 + content.md # D-023, D-024, D-025, D-028, D-029 + scope.md # D-001, D-003, D-005, D-006, D-007, D-013, D-014, D-027 + process.md # D-004, D-021, D-022 + questions.md # Q-001 through Q-011 + rejected.md # R-001 through R-010 +DECISIONS.md # Redirect to decisions/ directory TEAM.md # Team roster and roles ``` +## DevOps + +See [docs/DEVOPS.md](docs/DEVOPS.md) for build, test, lint, and CI procedures. All development operations go through the top-level `Makefile` — run `make` for a summary of targets. + ## Agent Instructions ### Before starting work 1. Read your briefing at `docs/briefings/{your-name}.md` for current project context -2. Read `DECISIONS.md` for confirmed decisions relevant to your work +2. Read the relevant `decisions/*.md` domain file(s) listed in your briefing 3. Check `docs/discussions/` for recent discussion rounds if needed ### SQLite access @@ -59,6 +72,7 @@ db/connectors/qdrant-count ``` ### File conventions +- Decisions: domain files in `decisions/` (see `decisions/README.md` for index) - Decision IDs: `D-NNN` (confirmed), `Q-NNN` (open questions), `R-NNN` (rejected) - Discussion rounds: numbered sequentially, archived to `docs/discussions/` when complete - Briefings: one per agent, updated after decision-producing rounds diff --git a/README.md b/README.md index 0044da30a..80daf28fa 100644 --- a/README.md +++ b/README.md @@ -128,7 +128,7 @@ No fog-of-war as an afterthought. No tutorial popups. No omniscient map reveals. **Setting:** Original science fiction IP, Commonwealth-inspired **Status:** Pre-alpha development -For development documentation, see [DECISIONS.md](DECISIONS.md) and [TEAM.md](TEAM.md). +For development documentation, see the [decisions/](decisions/) directory and [TEAM.md](TEAM.md). --- diff --git a/docs/DEVOPS.md b/docs/DEVOPS.md new file mode 100644 index 000000000..31f14a9f6 --- /dev/null +++ b/docs/DEVOPS.md @@ -0,0 +1,169 @@ +# 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 | +| Godot | 4.x | Client editor and runtime | +| Python | 3.x | Tooling scripts, db connectors | +| Make | any | Task runner (see below) | + +## Makefile Targets + +All development operations go through the top-level `Makefile`. Run `make` with no arguments for a summary. + +### Setup + +```bash +make setup # Install/verify all dev dependencies +``` + +Checks for Rust toolchain (installs clippy + rustfmt components), Godot binary, and Python. Run this on a fresh clone or new workstation. + +### Build + +```bash +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 + +```bash +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 + +```bash +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 + +```bash +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: + +```bash +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 + +```bash +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: +```bash +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 + +```bash +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. + +```bash +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