diff --git a/docs/backups/settledreach.db.backup b/docs/backups/settledreach.db.backup index cff67bb98..e15baffa7 100644 Binary files a/docs/backups/settledreach.db.backup and b/docs/backups/settledreach.db.backup differ diff --git a/docs/sprints/sprint-36/client.md b/docs/sprints/sprint-36/client.md new file mode 100644 index 000000000..bc1df4aab --- /dev/null +++ b/docs/sprints/sprint-36/client.md @@ -0,0 +1,77 @@ +# Sprint 36: Forge — Client Tasks + +**Goal:** Close Phase 3 Atlas (unified nav chain, brand corps, content refinement) and establish Phase 4 foundations (bookmark system, location-culture resolution, character creation skeleton). + +**Branch:** `sprint-36/client` +**Agents:** Stig (dev), Tyre (arch), Hoshe (QA) + +## New Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #844 | Unify star map and atlas into single implant/map chain | — | +| #618 | CK3-style character creation screen | #614 (server) | +| #680 | Location picker in character creation UI | #679 (server) | +| #722 | Add --help flag to custom DB scripts | — | +| #724 | Show client and server version on loading screen | — | + +Use `tooling/db/ticket show ` for full details. + +## Key Decisions + +- `decisions/architecture.md` — D-191 (atlas scope, zoom hierarchy, implant/map chain), D-170 (HUD layer groups), D-169 (implant component library) +- `decisions/scope.md` — D-115 (character creation scoped to skills + bookmark), D-146 (character creation preview — tile-scale sprite), D-155 (cardinal rotation only), D-158 (frontal camera default), D-159 (11 body types) +- `decisions/content.md` — D-128 (culture implicit in starting location) + +## Notes + +**#844 — Unify star map and atlas into single implant/map chain** +- Current state: `client/ui/star_map.gd` registers as `implant/map/starchart` and `client/ui/implant/atlas_panel.gd` registers as `implant/map/atlas`. They are two separate `HudGroups` apps with separate key bindings (M for starchart, A for atlas). +- D-191: the atlas is the star map extended downward — not a separate app. The unified chain should be a single `implant/map` app with internal level navigation. The star map (hop-ring view) becomes Level 0 of the atlas hierarchy. +- Approach: `AtlasPanel` already has a 4-level `Level` enum (`SYSTEM_PICKER`, `ORBITAL_DIAGRAM`, `BODY_ENTRY`, `HEIGHTMAP_VIEWER`). Extend it with a Level -1 or `REACH_MAP` that renders the star map view. Star map rendering logic can be lifted from `star_map.gd` into a method called by `AtlasPanel._draw()`. +- `StarMapRenderer` registers itself with `HudGroups` — after unification, de-register it or make it a sub-component rather than an independent app. Don't break the `implant/map/starchart` path for existing callers until the unified path is confirmed working. +- `client/ui/implant/atlas_viewer.gd` and `client/ui/implant/atlas_overlay_bar.gd` are the heightmap layer — preserve these. + +**#618 — CK3-style character creation screen** +- IMPORTANT: extend the EXISTING character creation screen (`client/ui/character_creation.gd`, `client/scenes/character_creation.tscn`) — do NOT create a separate screen. +- D-146: character creation preview is the tile-scale sprite at heavy zoom. The existing screen already implements this correctly. The CK3-style extension adds a **skills tab** and a **bookmark selector** to the existing `TabContainer`. +- D-115: creation is limited to skills + bookmark. No family/culture/religion sliders. +- The existing tab structure: Body, Head, Hair, Clothing, Accessories, Debug. Add two new tabs: "Skills" and "Bookmark". The Bookmark tab consumes the bookmark data from #614 (server). The skills tab is a stub for this sprint — display placeholder content until the skills system is implemented. +- Blocked by #614 until the bookmark data structure is available from the server. Coordinate with Tyre on what the server exposes. +- Game flow does not change: main_menu → character_select → character_creation → main.tscn. The `creation_confirmed(descriptor)` signal already carries `CharacterVisualDescriptor` — that type will need a bookmark field added. + +**#680 — Location picker in character creation UI** +- Client side of the location/culture system. The player selects their starting location in the character creation screen — this feeds into the bookmark selection flow. +- Blocked by #679 (server). Once the server exposes a location-to-culture resolution endpoint, the client needs a picker UI that shows selectable starting locations and displays the resolved culture. +- Integrate into the character creation screen as part of the Bookmark tab (coordinate with #618). The location picker is a sub-component of the bookmark selector, not a standalone screen. +- The `CharacterVisualDescriptor` or a new `CharacterProfile` struct will need to carry the selected location/bookmark. + +**#722 — Add --help flag to custom DB scripts** +- `tooling/db/` scripts: `ticket`, `sprint`, `decision`, `sqlite-query`, `sqlite-exec`. +- These scripts already print usage on bad args. Wire `--help` as an alias to that same usage output. +- This is a tooling/DX improvement — no game code impact. Low priority, parallelizable with everything else. +- Note: ticket is assigned to client team but touches `tooling/db/` — this is a tooling ticket, not client game code. + +**#724 — Show client and server version on loading screen** +- `client/ui/loading_screen.gd` currently shows only a loading message. Add version display. +- Client version: read from `project.yaml` at the repo root (root `version` field, format `0.1.{sprint}`). Use GDScript's `FileAccess` or a preload JSON export — choose the simplest approach that doesn't require a plugin. +- Server version: the bridge protocol already has `PROTOCOL_VERSION` (`server/src/bridge/types.rs`). The server can emit this in the initial handshake or a version ping. Alternatively, display it from the `ObserverSnapshot` if it carries a version field. +- The loading screen is `client/ui/loading_screen.tscn` — it is a simple overlay with a label. Add a second label below for version text. + +## Dependency Chain + +``` +#614 (server bookmark) → #618 (CK3 character creation) +#679 (server location-culture) → #680 (location picker) +#844 → standalone (no server dependency) +#722, #724 → standalone, parallel +``` + +## PR Workflow + +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz \ + --title "feat(client): sprint 36 — unified map chain, character creation foundations" \ + --description "body" \ + --base main --head sprint-36/client +``` diff --git a/docs/sprints/sprint-36/copy.md b/docs/sprints/sprint-36/copy.md new file mode 100644 index 000000000..2df6d47e3 --- /dev/null +++ b/docs/sprints/sprint-36/copy.md @@ -0,0 +1,71 @@ +# Sprint 36: Forge — Copy Tasks + +**Goal:** Close Phase 3 Atlas (unified nav chain, brand corps, content refinement) and establish Phase 4 foundations (bookmark system, location-culture resolution, character creation skeleton). + +**Branch:** `sprint-36/copy` +**Agents:** Mellanie (author), Paula (narrative), Gestalt (systems) + +## New Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #849 | Core-world atlas cohesion pass — hand-refine high-visibility systems | — | +| #838 | Review and hand-refine generated atlas content across all inhabited bodies | — | +| #828 | Author 120-170 notable brand corps across all 8 categories | — | + +Use `tooling/db/ticket show ` for full details. + +## Key Decisions + +- `decisions/economics.md` — D-189 (brand layer architecture — 8 categories), D-190 (brand volume calibration), D-185 (brands are not commodities), D-182 (TOML source of truth) +- `decisions/architecture.md` — D-191 (atlas pipeline, markers.json pixel-space format, cultural corridor naming palettes) +- `decisions/content.md` — D-128 (culture implicit in starting location — corridor identity matters for brand names and atlas names) + +## Notes + +**#849 — Core-world atlas cohesion pass — hand-refine high-visibility systems** +- The high-traffic systems in the Reach (Gateway/Sirius, Groombridge/Lendel, Van Maanen's Star, Lalande, etc.) were generated by the Sprint 35 Gemma pipeline. These are the systems players will see most — they need white-glove treatment above the baseline #838 pass. +- Deliverable: edited `markers.json` files for each priority system. Files live under `tooling/planet-gen/generate/` (path is `//markers.json`). +- D-191 §8: markers.json is in pixel-space `[row, col]` format against a `512 × 256` grid. City positions, road polylines, and named features all use this format. Do not convert to lat/lon — that is a display-time derivation. +- Corridor naming palettes per D-191: north_reach (Anglo-Saxon), south_reach (Iberian/Portuguese), east_reach (East Asian), west_reach (Germanic/Nordic), inner_orbit (institutional Latin/Anglo). Cohesion pass should check that names match the corridor palette and that no Earth-echoes slip through the blocklist. +- This is a child of #838 and should share notes on quality standards. + +**#838 — Review and hand-refine generated atlas content across all inhabited bodies** +- Baseline refinement pass across all 273 inhabited bodies. Blockers (#832, #833) are already done from Sprint 35. +- Check city placements: not in water (ocean/river cells in the heightmap), not on steep mountain slopes, reasonable quadrant distribution. +- Check names: culturally appropriate for corridor, no Earth IP echoes, no dedup collisions. +- Check infrastructure: road and rail paths should follow terrain logic — rivers and valleys are cheap corridors, mountains are expensive. Paths that cross mountains without a pass are a generation artifact. +- Deliverable: corrected `markers.json` files committed to `tooling/planet-gen/generate/`. Document any systematic issues found (patterns the generator repeats) in a refinement notes file so the generator can be patched. + +**#828 — Author 120-170 notable brand corps across all 8 categories** +- Source of truth format: TOML entries for `content/brands/brands.toml` (or equivalent — check with server team on exact file location used by #829 generate_brands pipeline). +- D-189: 8 categories with census targets: + - terroir: 15-20 (planetary origin goods — food, wine, materials) + - heritage_craft: 10-15 (old-world craftsmanship — tools, fabric, instruments) + - tech_premium: 20-25 (consumer electronics, implants, vehicles) + - cultural: 15-20 (entertainment, fashion, media) + - service_premium: 10-15 (hospitality, professional services) + - commodity_branded: 15-20 (branded commodity goods — fuel, water, staples) + - design_heritage: 10-15 (luxury goods, art, high design) + - institutional: 10-15 (education, healthcare, finance brands) +- D-190: these are notable brands, not minor ones. They are the top-of-mind touchstones in the Reach — the ones players will encounter in dialogue, on signage, in product descriptions. Minor brands (~10K) are generated by #829. +- D-185: brand corps are commodity demand nodes — they consume raw/intermediate goods from the economy simulation. Brand entries should specify their primary inputs (which commodity categories they consume). +- D-182: TOML is the source of truth. Each brand entry needs: name, category, founding_system (or corridor), price_tier, tagline (optional but useful for copy team), primary_inputs (list of commodity categories). +- Coordinate with server team (#829) to confirm the exact TOML schema before starting bulk authoring. + +## Dependency Chain + +``` +#849 (core-world cohesion) — standalone, start immediately +#838 (baseline refine pass) — standalone, start immediately; #849 is a deeper pass on the same files +#828 (brand corps authoring) — standalone; coordinate with server on schema before bulk writing +``` + +## PR Workflow + +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz \ + --title "content(atlas): sprint 36 — atlas refinement and brand corps" \ + --description "body" \ + --base main --head sprint-36/copy +``` diff --git a/docs/sprints/sprint-36/joint.md b/docs/sprints/sprint-36/joint.md new file mode 100644 index 000000000..8ca276549 --- /dev/null +++ b/docs/sprints/sprint-36/joint.md @@ -0,0 +1,81 @@ +# Sprint 36: Forge — Joint / Cross-Team Coordination + +**Sprint goal:** Close Phase 3 Atlas (unified nav chain, brand corps, content refinement) and establish Phase 4 foundations (bookmark system, location-culture resolution, character creation skeleton). + +## Pre-Sprint: Schema and Architecture Alignment + +These items must be resolved before dependent implementation starts: + +| Item | Owner | Needed by | +|------|-------|-----------| +| Bookmark struct shape — what fields does `BookmarkDefinition` expose to the client? | Tyre (arch) | #618 (client) | +| Location-culture API shape — function signature and return type for culture resolution | Tyre (arch) | #680 (client) | +| Brand TOML schema — exact field names for `brands.toml` entries | Tyre or Dudley (server) | #828 (copy) | +| Confirm brand_products table is in place from #827 before #829 runs | Dudley (server) | #829 (server) | + +## Cross-Team Dependencies + +``` +#614 (server: bookmark system) → #618 (client: CK3 character creation) +#679 (server: location-culture resolution) → #680 (client: location picker) +#827 (server: brand DB schema) → #829 (server: generate_brands pipeline) +#828 (copy: notable brand corps authored) → #829 (server: pipeline reads templates) +#842 (server: audit NPC orphans) → #848 (server: retire NPC system) +``` + +## Integration Points + +**Atlas unification (#844)** +- `star_map.gd` (`client/ui/star_map.gd`) registers as `implant/map/starchart`. +- `atlas_panel.gd` (`client/ui/implant/atlas_panel.gd`) registers as `implant/map/atlas`. +- Unified target: single `implant/map` HudGroups registration, single key binding. +- After merge: `main.gd` must route the single toggle to the unified panel. Check `client/scripts/main.gd` for existing KEY_M / KEY_A bindings before removing them. + +**Character creation extension (#618 + #680)** +- Both tickets extend `client/ui/character_creation.gd` — coordinate to avoid conflicts. +- #618 adds Skills and Bookmark tabs. #680 adds the location picker as a sub-component of the Bookmark tab. +- Recommended order: #618 lands first with Bookmark tab stub; #680 fills in the location picker once #679 is done. +- The `creation_confirmed` signal emits `CharacterVisualDescriptor`. The descriptor type or a wrapper will need to carry `bookmark_id` and `starting_location` fields — agree on this shape before either ticket writes code. + +**Brand pipeline coordination (#828 + #829)** +- #829 reads `brand_templates.toml` (authored Sprint 35) and generates minor brands. +- #828 authors notable brands directly — these are hand-written entries in `brands.toml`, not generated. +- Copy team (#828) must confirm the exact TOML schema with server team before bulk writing. Server team must not change the schema after copy starts authoring. + +**NPC cleanup (#842 + #848)** +- `server/src/simulation/mod.rs` currently references `npc::vision`, `npc::awareness`, and other modules. +- #842 audits what is safe to remove. #848 does the removal. Assign both to the same agent or run #842 first and hand off a confirmed safe-delete list to #848. +- Do NOT remove `server/src/npc/blueprint.rs` without checking if it is used by any active non-scrapped system. + +## Sprint Completion Proof + +The sprint is complete when all of the following are observable: + +1. **Atlas unification (#844):** A single key binding opens the implant/map panel at the hop-ring (Reach) view. Navigating into a system and drilling to a planet heightmap works in one continuous session without switching HudGroups apps. + +2. **Character creation foundations (#618, #614):** The character creation screen shows a "Bookmark" tab with at least the tycoon bookmark listed. Selecting it does not crash. The "Skills" tab is present as a stub. + +3. **Location picker (#680, #679):** The Bookmark tab includes a location picker. Selecting a starting location resolves to a culture tag visible in the UI (even if just logged to console). + +4. **Brand pipeline (#829, #827, #828):** Running the generate_brands binary against the DB produces rows in the brand_products table. At least 120 notable brand entries are present in `brands.toml`. + +5. **Atlas content (#838, #849):** All 273 inhabited bodies have reviewed markers.json files committed. Core systems (Gateway, Lendel, Van Maanen's Star) pass a visual sanity check (cities not in water, names corridor-appropriate). + +6. **NPC cleanup (#842, #848):** `server/src/npc/` contains only code that is actively used. `content/global/` is removed (if it existed). CI compiles clean. + +7. **Tooling (#722, #724, #726, #636):** `tooling/db/ticket --help` prints usage. Loading screen shows version. `cargo deny check` passes with the new config. `cargo audit` shows no critical advisories after bincode migration. + +## Phase Marker + +Sprint 36 closes **Phase 3** (planetary maps and Atlas of the Reach). The atlas content is complete, the nav chain is unified, and the brand pipeline is seeded. + +Sprint 36 also opens **Phase 4** foundations: bookmark definition (#614) and location-culture resolution (#679) are the first Phase 4 server primitives. Phase 4 focus (player control scheme) begins in Sprint 37. + +## Test Plan Alignment + +- #844: visual test — open atlas, navigate from Reach → system → planet → heightmap in one session. Verify no double-registration in HudGroups. +- #618/#680: functional test — create a character with a bookmark selected, reach the main game loop (even if empty). +- #829: `cargo test` in `server/src/bin/` for the generate_brands binary. Run against test DB, verify row count. +- #842/#848: `cargo build` and `cargo test` must pass after removal. No regressions in existing server tests. +- #726: `cargo deny check` must pass CI. Run locally before PR. +- #636: `cargo test` after bincode bump. Focus on `server/src/bridge/` serialization tests. diff --git a/docs/sprints/sprint-36/server.md b/docs/sprints/sprint-36/server.md new file mode 100644 index 000000000..0da21602b --- /dev/null +++ b/docs/sprints/sprint-36/server.md @@ -0,0 +1,92 @@ +# Sprint 36: Forge — Server Tasks + +**Goal:** Close Phase 3 Atlas (unified nav chain, brand corps, content refinement) and establish Phase 4 foundations (bookmark system, location-culture resolution, character creation skeleton). + +**Branch:** `sprint-36/server` +**Agents:** Dudley (dev), Tyre (arch), Hoshe (QA) + +## New Tickets + +| # | Title | Blocked by | +|---|-------|------------| +| #826 | Thread world seed into economy simulation | — | +| #827 | Add brand_products, brand_inputs, system_fiscal schema + Phase 2 demand stubs | — | +| #679 | Location-to-culture resolution system | — | +| #614 | Bookmark definition system | — | +| #829 | Build generate_brands pipeline — 10K minor brands from templates | — | +| #848 | Retire v0.1 PoC NPC system and content/global/ | — | +| #842 | Clean out orphaned NPC and environment interaction systems | — | +| #726 | Configure cargo deny.toml for license and advisory checking | — | +| #636 | Migrate bincode v1.x to v2.x | — | + +Use `tooling/db/ticket show ` for full details. + +## Key Decisions + +- `decisions/content.md` — D-128 (culture implicit in starting location), D-115 (character creation scoped to skills + bookmark) +- `decisions/scope.md` — D-117 (tycoon is the bookmark), D-115 (bookmark definition) +- `decisions/economics.md` — D-189 (brand layer architecture), D-190 (brand volume calibration), D-185 (brands are not commodities) +- `decisions/rejected.md` — R-012 (NPC ambient interaction system scrapped) + +## Notes + +**#679 — Location-to-culture resolution system** +- No culture resolution code exists in `server/src/`. This is greenfield. +- D-128: culture is implicit in the starting bookmark location — Van Maanen's Star start = Van Maanen's Star culture. The server needs a function that takes a location identifier and returns a culture tag. +- Blocks #680 (client location picker) and #621/#681 (downstream character init). Implement as a clean public function in a new module (e.g. `server/src/knowledge/culture.rs` or `server/src/settings/culture.rs`) — the client ticket depends on the type being stable. +- Input: location/system id string. Output: culture tag. Source of truth: `server/data/systems.db` (geographic_sector → corridor → culture mapping). + +**#614 — Bookmark definition system** +- No bookmark code exists. Greenfield. +- A bookmark = skills + starting state + context. Tycoon is the first bookmark. Must define a data structure that the character creation screen (#618) can consume. +- D-115: character creation is limited to skills + bookmark for now. Family, culture, religion are deferred. +- Blocks #618 (client CK3-style character creation). Define the bookmark type and expose it via the bridge so the client can enumerate bookmarks. +- Coordinate with Tyre on the struct shape before Stig starts #618. + +**#829 — Build generate_brands pipeline — 10K minor brands from templates** +- New Rust binary in `server/src/bin/`. Model the existing `server/src/bin/generate_corporations/` for structure. +- Reads `content/brands/brand_templates.toml` (authored in Sprint 35 #831). Generates 10,000 minor brand product rows. +- D-189: 8 brand categories (terroir, heritage_craft, tech_premium, cultural, service_premium, commodity_branded, design_heritage, institutional). D-190: population-relative calibration — scale to ~80B Reach population. +- Output writes to `server/data/systems.db` brand_products table (schema in #827). Coordinate with #827 to ensure schema is in place first. +- Corridor-specific procedural name generation should reuse the existing naming infrastructure (`server/src/bin/generate_corporations/names.rs`). + +**#848 — Retire v0.1 PoC NPC system and content/global/** +- R-012: the entire NPC ambient interaction model is scrapped. `server/src/npc/` contains the v0.1 PoC modules. +- `content/global/` does not currently exist in the repo — confirm before deleting. Check `server/src/npc/` for live integration points before removing: `server/src/simulation/mod.rs` references several npc modules (vision, awareness, etc.). +- Coordinate with #842 — both tickets touch the same area. Recommended order: #842 first (audit scope), then #848 (retire). Or assign both to same agent and do together. +- Do NOT delete any code that is referenced by non-NPC simulation paths. Check `server/src/simulation/ticker.rs` and `server/src/tick_phases.rs` for what is currently active in the tick loop. + +**#842 — Clean out orphaned NPC and environment interaction systems** +- Companion to #848. Scope: `server/src/npc/` orphaned modules, any `content/` directories with overheard.ron or zone-type conversation pools. +- R-012 is the authoritative reference. Cross-check against `server/src/simulation/mod.rs` to identify what is actually still wired up vs. dead code. +- After cleanup, `server/src/npc/` should contain only modules that are actively used by non-scrapped systems. + +**#726 — Configure cargo deny.toml for license and advisory checking** +- `cargo-deny` is installed but there is no `deny.toml` in `server/`. The CI check is failing because of this. +- Allowed licenses: MIT, Apache-2.0, BSD-2-Clause, BSD-3-Clause, ISC, Unlicense, Zlib, CC0-1.0. +- Also configure advisory DB (RUSTSEC advisories). Target path: `server/deny.toml`. + +**#636 — Migrate bincode v1.x to v2.x** +- `server/Cargo.toml` has `bincode = "1"`. RUSTSEC-2025-0141 flags v1.3.3 as unmaintained. +- bincode v2.x has a different API — encode/decode functions changed. Grep all usage sites before upgrading: `grep -r "bincode::" server/src/`. +- `server/src/bridge/` is the most likely consumer (IPC serialization). Verify v2 compatibility before bumping the version pin. +- Low priority — no active vulnerability, no player-facing impact. + +## Dependency Chain + +``` +#827 (brand schema) → #829 (generate_brands pipeline) +#679 (location-culture) → [unblocks #680 client] +#614 (bookmark system) → [unblocks #618 client] +#842 (audit NPC orphans) → #848 (retire NPC system) [coordinate together] +#726, #636, #826, #827 → standalone, parallel +``` + +## PR Workflow + +```bash +tea pr create --repo jpmschweitzer/settled-reach --login schweitz \ + --title "feat(server): sprint 36 — bookmarks, brands, NPC cleanup" \ + --description "body" \ + --base main --head sprint-36/server +```