docs(meta): add DEVOPS.md, update project docs for decisions directory split
Adds DevOps procedures document and updates CLAUDE.md/README.md to reference decisions/ domain files and Makefile-based workflow. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -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
|
||||
|
||||
@@ -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).
|
||||
|
||||
---
|
||||
|
||||
|
||||
+169
@@ -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
|
||||
Reference in New Issue
Block a user