diff --git a/docs/backups/settledreach.db.backup b/docs/backups/settledreach.db.backup index a6fcdaba5..d79571e51 100644 Binary files a/docs/backups/settledreach.db.backup and b/docs/backups/settledreach.db.backup differ diff --git a/docs/sprints/sprint-31/ci.md b/docs/sprints/sprint-31/ci.md new file mode 100644 index 000000000..01bb4304d --- /dev/null +++ b/docs/sprints/sprint-31/ci.md @@ -0,0 +1,57 @@ +# Sprint 31: Bedrock — CI Tasks + +**Goal:** Complete Phase 1 wiki content (cultural sweep, GTTR depth, star map popups) and refactor accumulated complexity in atlas.rs, main.gd, and Python tooling. + +**Branch:** `sprint-31/ci` +**Agents:** Justine (build/deploy), Hoshe (QA) + +## New Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #777 | Add ruff linting + shared DB path module for Python scripts | — | + +Use `tooling/db/ticket show ` for full details. + +## Key Decisions + +- `decisions/process.md` — development process decisions + +## Notes + +### #777 ruff linting + shared DB path module (refactor) +Python scripts in `tooling/db/` lack linting and share duplicated patterns. + +**Deliver:** +1. **pyproject.toml** at repo root with ruff config (line length, target Python version, rule selection) +2. **Shared module** `tooling/db/common.py` extracting: + - `resolve_db_path()` — uses `PROJECT_DB_PATH` env var with parent-dir fallback + - `load_config()` — reads `tooling/db/config.json` + - `get_connection()` — returns WAL-mode SQLite connection +3. **Update all consumers** — `sqlite_connector.py`, `ticket`, `sprint`, `decisions_sync.py` to import from `common.py` instead of duplicating +4. **Pre-push hook integration** — add `ruff check tooling/` to the pre-push hook alongside GDScript and Rust checks +5. **Makefile target** — `make lint-python` running ruff + +**Key files:** +- `tooling/db/sqlite_connector.py` — current DB path resolution +- `tooling/db/ticket` — duplicated resolve pattern +- `tooling/db/sprint` — duplicated resolve pattern +- `tooling/db/decisions_sync.py` — duplicated resolve pattern +- `tooling/db-backup` — bash equivalent + +**Verify:** `ruff check tooling/` passes. All DB CLI commands still work +(`tooling/db/ticket count`, `tooling/db/sprint status`). + +## Dependency Chain + +``` +#777 (ruff + shared module) → standalone +``` + +## PR Workflow + +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz \ + --title "chore(ci): Sprint 31 — ruff linting + shared DB module" \ + --description "body" --base main --head sprint-31/ci +``` diff --git a/docs/sprints/sprint-31/client.md b/docs/sprints/sprint-31/client.md new file mode 100644 index 000000000..53498610f --- /dev/null +++ b/docs/sprints/sprint-31/client.md @@ -0,0 +1,73 @@ +# Sprint 31: Bedrock — Client Tasks + +**Goal:** Complete Phase 1 wiki content (cultural sweep, GTTR depth, star map popups) and refactor accumulated complexity in atlas.rs, main.gd, and Python tooling. + +**Branch:** `sprint-31/client` +**Agents:** Stig (UI), Tyre (architecture), Hoshe (QA) + +## New Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #780 | Star map click-through — wiki/GTTR popup on system select | — | +| #775 | Decompose main.gd and game_state.gd god objects | — | + +Use `tooling/db/ticket show ` for full details. + +## Key Decisions + +- `decisions/architecture.md` — D-013 (diegetic UI), D-020 (client architecture) +- `decisions/scope.md` — development cascade, Phase 1 deliverable + +## Notes + +### #780 Star map click-through (Phase 1 deliverable) +The star map insert module (#674, Sprint 30) renders 301 systems as a hop-ring +view with click-to-select. Currently selecting a system updates `_selected_system` +and shows the name in a basic info panel. + +**Deliver:** When a system is selected, show a popup/panel with: +- System name, star type, hop distance, corridor +- GTTR narrative excerpt (first paragraph of the wiki entry) +- Body count, population summary +- Adjacent systems (topology links) + +Data source: `client/data/star_map_data.json` already contains most fields. +For GTTR text, either embed excerpts in the JSON (via `tooling/generate-star-map-data.py`) +or load from a separate text file at runtime. + +**Key files:** +- `client/ui/star_map.gd` — existing star map (525 lines) +- `client/ui/star_map.tscn` — scene file +- `client/data/star_map_data.json` — 4363 lines, 301 systems +- `tooling/generate-star-map-data.py` — data generator (may need extending) + +### #775 Decompose main.gd and game_state.gd (refactor) +Gemini code review flagged these as god objects: +- `client/scripts/main.gd` (28KB) — UI management, input, state transitions +- `client/scripts/autoloads/game_state.gd` (19KB) — global state, snapshots + +**Approach:** Extract focused components. Suggested splits: +- `main.gd` → extract UI manager, insert state controller, input dispatcher +- `game_state.gd` → extract snapshot handler, character state, session state + +**Constraint:** GDScript autoload parse-order rule (documented in CLAUDE.md). +Autoloads can't reference `class_name` types at top level. Any new autoloads +must follow the `load()` inline pattern. Prefer non-autoload scripts where possible. + +## Dependency Chain + +``` +#780 (star map popup) → standalone, Phase 1 priority +#775 (decompose god objects) → standalone, refactor track +``` + +Independent — work in parallel. + +## PR Workflow + +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz \ + --title "feat(client): Sprint 31 — star map popup, main.gd decomposition" \ + --description "body" --base main --head sprint-31/client +``` diff --git a/docs/sprints/sprint-31/copy.md b/docs/sprints/sprint-31/copy.md new file mode 100644 index 000000000..23edf9f9f --- /dev/null +++ b/docs/sprints/sprint-31/copy.md @@ -0,0 +1,70 @@ +# Sprint 31: Bedrock — Copy Tasks + +**Goal:** Complete Phase 1 wiki content (cultural sweep, GTTR depth, star map popups) and refactor accumulated complexity in atlas.rs, main.gd, and Python tooling. + +**Branch:** `sprint-31/copy` +**Agents:** Mellanie (author), Paula (narrative), Miri (worldbuilding) + +## New Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #766 | Cultural diversity sweep — wiki naming and heritage asymmetry | — | +| #782 | Per-body GTTR entries for moons and stations | — | +| #774 | Enrich GJ-672 (Nova Estrada) and GJ-147 (Entremeio) wiki entries | — | +| #773 | Evaluate Iserlohn (GJ-532) planet name for IP originality | — | + +Use `tooling/db/ticket show ` for full details. + +## Key Decisions + +- `decisions/content.md` — D-NNN content decisions, cultural corridor system +- `decisions/scope.md` — development cascade, Phase 1 deliverable definition + +## Notes + +### #766 Cultural diversity sweep (largest ticket) +The cultural stereotyping audit (`docs/audits/cultural-stereotyping-audit.md`) flagged +multiple cultural groups with imbalanced representation. Afrikaans is the worst at ~15:1 +confirming:subverting ratio (Sprint 30 added Brandpunt as first subversion). This ticket +requires reviewing all cultural groups, identifying imbalances, and rewriting wiki entries +to add subversions. Work across all 5 corridors. The audit's recommendations (tech hubs, +academic centers, commercial dynasties, artistic communities) should guide the rewrites. + +**Scope rule:** This is a separate sprint's worth of work if done exhaustively. For this +sprint, focus on the top 3 most imbalanced groups and deliver concrete wiki rewrites for +at least 2 systems per group. File follow-up tickets for the remaining groups. + +### #782 Per-body GTTR entries +Many systems have only system-level GTTR. Significant moons and stations (pop >10K) need +their own entries. Existing patterns: `wiki/star-systems/GJ-*/gttr.md`. Prioritize hub +systems at hops 1-4 first (highest traffic, most gameplay relevance). + +### #774 Thin wiki entries +Paula's Sprint 30 review flagged Nova Estrada and Entremeio as noticeably thinner than +the batch standard. Enrich to match Kettenschmied-level quality (economic logic + human +cost in the same breath). + +### #773 Iserlohn IP evaluation +Miri's review flagged "Iserlohn" (GJ-532 planet name) as a potential Legend of the Galactic +Heroes reference. The real-German-city rationale is documented in the proposal notes. Make a +deliberate decision: keep with rationale, or rename to another Sauerland-region reference. + +## Dependency Chain + +``` +#766 (cultural sweep) → standalone, largest piece +#782 (per-body GTTR) → standalone, parallel track +#774 (thin entries) → standalone, quick +#773 (Iserlohn IP) → standalone, quick decision +``` + +All tickets are independent — work in parallel by agent. + +## PR Workflow + +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz \ + --title "data(copy): Sprint 31 — cultural sweep, GTTR depth, wiki quality" \ + --description "body" --base main --head sprint-31/copy +``` diff --git a/docs/sprints/sprint-31/joint.md b/docs/sprints/sprint-31/joint.md new file mode 100644 index 000000000..5dc3d986e --- /dev/null +++ b/docs/sprints/sprint-31/joint.md @@ -0,0 +1,45 @@ +# Sprint 31: Bedrock — Joint Notes + +**Goal:** Complete Phase 1 wiki content (cultural sweep, GTTR depth, star map popups) and refactor accumulated complexity in atlas.rs, main.gd, and Python tooling. + +## Sprint Completion Proof + +When Sprint 31 is done, you can: + +1. **Click any system** in the star map and see a popup with its name, star type, corridor, GTTR excerpt, body count, and adjacent systems +2. **Read culturally diverse wiki entries** — at least 2 subversion entries per top-3 imbalanced cultural groups +3. **Read GTTR entries for major moons and stations** — hub system bodies at hops 1-4 have individual entries +4. **Run `ruff check tooling/`** and get a clean pass +5. **Browse atlas.rs** and find subcommands in separate module files +6. **Browse main.gd** and find it under 15KB with responsibilities extracted + +## Phase 1 Context + +This sprint advances Phase 1 of the development cascade (epic #746). Phase 1 +deliverable: "Implant-ready Godot map of the Reach with click-throughs + wiki/GTTR popups." + +**What's done:** 301/301 systems, body catalogs, star map insert, GTTR coverage +**What this sprint adds:** Star map popups (#780), cultural quality (#766), GTTR depth (#782) +**What remains after this sprint:** Heightmaps (#778), planetary screenshots (#779), economic profiles (#781) — these need design discussion before implementation, targeted for Sprint 32. + +## Not In Scope + +The following are **Phase 2-6 work** and must NOT be started until Phase 1 is complete: +- Character creation production UI (#694) +- Location-to-culture resolution (#679) +- NPC personality surface area (#621) +- Tycoon starting state design (#615) +- Economic simulation +- Settlement generation + +The cascade is enforced in the ticket system: #747 (Phase 2) is blocked by #746 (Phase 1). + +## Refactor Rationale + +The three refactors (#775, #776, #777) are infrastructure work, not feature development. +They reduce complexity that compounds every sprint: +- `atlas.rs` (2000+ lines) — every atlas feature adds to a single file +- `main.gd` (28KB) + `game_state.gd` (19KB) — every client feature touches these +- Python tooling (5 files with duplicated DB path logic) — every new script copies the pattern + +Doing these now prevents the debt from growing further as Phase 1 content work continues. diff --git a/docs/sprints/sprint-31/server.md b/docs/sprints/sprint-31/server.md new file mode 100644 index 000000000..181679ddc --- /dev/null +++ b/docs/sprints/sprint-31/server.md @@ -0,0 +1,57 @@ +# Sprint 31: Bedrock — Server Tasks + +**Goal:** Complete Phase 1 wiki content (cultural sweep, GTTR depth, star map popups) and refactor accumulated complexity in atlas.rs, main.gd, and Python tooling. + +**Branch:** `sprint-31/server` +**Agents:** Dudley (simulation), Tyre (architecture), Hoshe (QA) + +## New Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #776 | Split atlas.rs subcommands into modules | — | + +Use `tooling/db/ticket show ` for full details. + +## Key Decisions + +- `decisions/architecture.md` — D-010 (server-authoritative), D-020 (Rust/bevy_ecs) + +## Notes + +### #776 Split atlas.rs subcommands into modules (refactor) +`server/src/bin/atlas.rs` is 2000+ lines containing all CLI subcommands in one +file. Each subcommand (author, commit-system, corridor-status, list-systems, +verify, next, show-system, etc.) should be extracted into its own module. + +**Approach:** +- Create `server/src/bin/atlas/` module directory +- Move `atlas.rs` → `server/src/bin/atlas/main.rs` (thin dispatch) +- Extract each `cmd_*` function into its own file: + - `author.rs` — `cmd_author`, `generate_body_matrix` + - `commit.rs` — `cmd_commit_system` + - `corridor_status.rs` — `cmd_corridor_status` + - `list.rs` — `cmd_list_systems`, `cmd_next`, `cmd_unfinished` + - `show.rs` — `cmd_show_system` + - `verify.rs` — `cmd_verify` +- Shared types/helpers stay in `main.rs` or a `common.rs` + +**Key file:** `server/src/bin/atlas.rs` (~2000 lines) + +**Verify:** `cargo build --bin atlas` must compile. `cargo test` must pass. +Run `tooling/atlas stats` and `tooling/atlas corridor-status` to verify CLI +still works after the split. + +## Dependency Chain + +``` +#776 (atlas split) → standalone +``` + +## PR Workflow + +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz \ + --title "refactor(simulation): Sprint 31 — split atlas.rs into modules" \ + --description "body" --base main --head sprint-31/server +```