jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(meta): plan Sprint 26: Clean House

Browse Source 
13 tickets across server (5), copy (6), client (1), planning (1).
Sprint goal: ship voice pipeline to production via observer integration,
remove v0.1 dead weight, stabilize codebase. #648 cancelled as duplicate
of #658.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-03-07 19:44:02 +01:00
co-authored by Claude Sonnet 4.6
parent a2554118a5
commit cbe8b5b5ab
6 changed files with 270 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/backups/settledreach.db.backup
BIN
View File
Binary file not shown.
docs/sprints/sprint-26/client.md
+36
View File
@@ -0,0 +1,36 @@
# Sprint 26: Clean House — Client Tasks
**Goal:** Ship the voice pipeline to production by integrating observer, removing v0.1 dead weight, and stabilizing the codebase.
**Branch:** `client`
**Agents:** Stig (dev), Tyre (arch), Hoshe (QA)
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #646 | UX: AI-Enhanced Dialogue toggle + hardware detection | #641 (done) |
Use `tooling/db/ticket show <id>` for full details.
## Key Decisions
- `decisions/content.md` — D-138 (LLM re-voicing pipeline: pre-voicing modes, base-text fallback model, hardware detection requirement)
- `decisions/architecture.md` — D-088 (3-state pause system, server-authoritative)
## Notes
- **#646 AI-Enhanced Dialogue toggle + hardware detection:** The voice pipeline (server-side, `server/src/voice/`) is wiring up this sprint via #652. The client needs layered hardware detection and player-facing controls so the feature degrades gracefully. Three detection layers in sequence: (1) CPU/RAM check — can the model even load? (2) time-per-token benchmark on first load — is it fast enough to be useful? (3) player-facing toggle — opt out even on capable hardware. The toggle state must persist (see #627 SQLite settings storage — not in this sprint, use a flat config file or `ProjectSettings` as interim). The UI for this is in the options/settings panel. Coordinate with server team: the client toggle must communicate to the server process whether voicing is requested (the server queue drains but does not requeue when disabled). Key integration point: `client/scripts/` settings panel and the existing `SR_LIVE` / subprocess launch flow. Check `docs/workshops/llm-voice-pipeline/` for hardware thresholds decided in the workshop.
## Dependency Chain
```
#646 (UX toggle + hardware detection) — #641 done, unblocked
```
## PR Workflow
When ready to submit, create a PR with `tea` CLI. **All flags are required** to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(ui): description" --description "body" --base main --head client
```
docs/sprints/sprint-26/copy.md
+61
View File
@@ -0,0 +1,61 @@
# Sprint 26: Clean House — Copy Tasks
**Goal:** Ship the voice pipeline to production by integrating observer, removing v0.1 dead weight, and stabilizing the codebase.
**Branch:** `copy`
**Agents:** Mellanie (author), Paula (narrative), Gestalt (systems)
## Carry-over from Sprint 25
| # | Title | Status | Notes |
|---|-------|--------|-------|
| #634 | Author decomposed behavior content | backlog | Deferred from Sprint 25. Depends on format agreed in #633 (server). Coordinate with server team before starting. |
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #647 | Docs: Amend D-123, supersede D-124, file workshop D-records | — |
| #645 | Content: Base text elevation pass | — |
| #656 | Remove handwritten Krenn dialogue and monologue content | — |
| #657 | Remove detective mission system | — |
| #653 | Voice pipeline: culture persona authoring for non-Krenn cultures | — |
Use `tooling/db/ticket show <id>` for full details.
## Key Decisions
- `decisions/content.md` — D-138 (LLM re-voicing pipeline: culture persona format, negative injectors, double-prompt technique), D-121 (voice is culture-driven, job as modifier), D-123 (generative AI for NPC content — amended by D-138), D-128 (Krenn System = Krenn culture), D-122 (all NPCs generated — no named hand-authored characters), D-117 (zero investigation content in v0.2)
- `decisions/scope.md` — D-114 (generator-first proof-of-life), D-117 (tycoon bookmark, no detective/smuggler)
## Notes
- **#647 Amend D-123, supersede D-124, file workshop D-records:** Documentation debt from the LLM Voice Pipeline Workshop (2026-03-07). D-123 needs amending to cover both baked (build-time, human-reviewed) and pre-voiced (runtime background) modes — Paula's distinction must be captured. D-124 is already superseded by D-138 in the decisions file, but needs the formal amendment record. Also file any remaining D-records from the workshop that haven't been committed to `decisions/content.md` yet. Check `docs/workshops/llm-voice-pipeline/` for outputs not yet formalized. This is a documentation ticket — no code.
- **#645 Base text elevation pass:** The voice pipeline uses base text as both the LLM seed and the fallback when the pipeline is unavailable or disabled. Base text that is flat or mechanical produces bad seeds AND bad fallbacks. Review NPC observable behaviors in the zone RON content (~50 lines per role). Criteria: vivid enough to seed a good voicing, specific enough to be informative as-is, no corporate-speak ("initiating task completion protocol" → "gets back to sorting the manifests"). Focus on roles present in the generated Krenn rural zone from Sprint 25. Coordinate with server team: do not change `Factual`-type lines (numbers, denials) — those bypass the LLM and must remain precise.
- **#634 Decomposed behavior content:** This is the copy-side counterpart to #633 (server composable behavior engine). Do not start until the server team has agreed on the behavior primitive format — the content must conform to the data structure. Once the format is known: (1) role action templates — generic stage directions per role, no culture specificity (e.g., `dock_worker.routines.yaml`); (2) culture modifiers — Krenn-specific behavioral inflections per action category; (3) context tags — situational selectors (quiet, busy, under-observation). Deliverable is authored content files, not a design spec. Check `decisions/content.md` D-138 for the Q-057 resolution framing.
- **#656 Remove handwritten Krenn dialogue and monologue content:** Delete v0.1 hand-authored content from `content/campaigns/main/systems/krenn/`. Full scope: all NPC YAML profiles in `stations/sova/districts/transit/` (shift-supervisor, courier, new-hire, scheduler, kael-davan, maintenance-tech, dock-worker, etc.), all files under `dialogue/`, all files under `monologue/detective/` and `monologue/smuggler/`, `insert/detective.yaml` and `insert/smuggler.yaml`, `items/smuggler-inventory.yaml`. Also remove compiled versions in `content-ron/campaigns/` if they exist. **Do not delete:** `content/global/culture-krenn.ron`, `culture-krenn.example.ron` — these are live generator inputs. Also preserve `content/campaigns/main/systems/krenn/stations/sova/districts/transit/pools.yaml` if it contains zone metadata rather than authored dialogue (check first). After deletion, verify `cargo check` and content validator pass.
- **#657 Remove detective mission system:** Delete: `content/global/knowledge/investigation.yaml`, `content/global/factions/lattice-commission.yaml`, `docs/design/character-build-detective.md`, `docs/design/detective-chain-of-command.md`, `docs/design/archetype-evidence-presentation.md`, `docs/design/divergent-starting-knowledge.md`, detective sections of `docs/design/insert-hud-wireframe-v01.md` (edit, don't delete the file). Also remove workshop outputs: `docs/workshops/v01-content-scoping/` and `docs/workshops/content-gap-analysis_v0_1/` directories. Check `content/campaigns/main/systems/krenn/stations/sova/districts/transit/` for `pc-detective.yaml` and `pc-smuggler.yaml` NPC files — delete both. Review `client/tests/test_insert_off_behavior.gd` for detective references — flag to client team if it needs updating, do not edit client files directly. Note: `content/global/factions/` will still contain valid non-detective factions (concord-assembly, guardians-of-autonomy, syndics, the-ring, the-unbound, veil-institute) — only remove lattice-commission.yaml.
- **#653 Culture persona authoring for non-Krenn cultures:** The voice pipeline is designed for multi-culture expansion. Each culture needs: `voice_persona` (prose description of the cultural voice register), `voice_examples` (3-5 example lines showing the voice in action), `occasional_injections` (recurring phrases or idioms), and explicit NOT-lists (what this culture never sounds like — the negative injectors that Spike 2 showed are critical). Krenn culture is already authored and tested. This ticket authors at least 2 additional cultures from the Settled Reach lore. Coordinate with Miri (worldbuilding) for canonical culture details — check `docs/briefings/miri.md` for her existing knowledge base. Output format must match the Krenn culture RON structure in `content/global/culture-krenn.ron`.
## Dependency Chain
```
#647 (file D-records) — standalone, start immediately
#645 (base text elevation) — standalone, parallel
#656 (remove Krenn hand-authored content) — standalone, parallel
#657 (remove detective system) — standalone, parallel
#653 (culture persona authoring) — standalone, parallel
#634 (decomposed behavior content) — blocked on server #633 format agreement
```
## PR Workflow
When ready to submit, create a PR with `tea` CLI. **All flags are required** to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "docs(content): description" --description "body" --base main --head copy
```
docs/sprints/sprint-26/joint.md
+77
View File
@@ -0,0 +1,77 @@
# Sprint 26: Clean House — Joint
**Goal:** Ship the voice pipeline to production by integrating observer, removing v0.1 dead weight, and stabilizing the codebase.
## Pre-Sprint
No blocking decisions or schema work required before implementation starts. All design decisions for this sprint are locked (D-138, D-122, D-117).
One cross-team coordination point must happen at sprint start:
| Item | Owner | Needed by |
|------|-------|-----------|
| Behavior primitive format agreement | Server (#633) | Copy (#634) cannot start until format is specified |
Server team (#633) should document the behavior primitive data structure (as a Rust type or YAML schema) and share it with copy team before #634 begins. This is a 1-day coordination item, not a blocker on other tickets.
## Sprint Completion Proof
The sprint is done when all of the following are observable:
1. **Voice pipeline live end-to-end:** Start the game with a generated Krenn NPC visible. Observable behaviors and dialogue lines for that NPC are voiced (culture-inflected, not raw base text). A `Factual`-type line (containing a number or denial) shows as base text, not LLM output.
2. **Client toggle functional:** Settings panel contains an AI-Enhanced Dialogue toggle. Disabling it causes the server to serve base text. Hardware detection runs at startup; if the system cannot run the model, the toggle is greyed out with an explanation.
3. **v0.1 content deleted:** `server/src/content/` does not exist. `content/campaigns/main/systems/krenn/stations/sova/districts/transit/dialogue/` and `monologue/` are gone. `content/global/knowledge/investigation.yaml` and `content/global/factions/lattice-commission.yaml` are gone. `cargo check` passes with no references to deleted modules.
4. **D-records filed:** `decisions/content.md` reflects the amended D-123 and the LLM voice pipeline workshop outputs. D-138 Spike 2 findings are formally in the record.
5. **Agent profiles updated:** At least 10 of 20 agent profiles and 10 of 18 briefings updated to reflect v0.2 framing. Zero references to Kael Davan, Sera Venn, or playable detective/smuggler archetypes in updated files.
## Test Plan
| Area | Method | Owner |
|------|--------|-------|
| Voice pipeline integration | Live test: generate NPC, inspect voiced output vs base text | Server |
| ContentType::Factual bypass | Unit test: inject Factual-tagged line, assert LLM not called | Server |
| Observer wiring | Integration test: `voice_pipeline.rs` test suite + live Gauntlet run | Server |
| Client toggle | Manual: toggle off, verify server serves base text | Client |
| Hardware detection | Manual: run on low-spec config, verify graceful degradation | Client |
| Content deletion | `cargo check` + `make test` full suite passing after deletion | Server |
| D-record accuracy | Qatux review of decisions/content.md for completeness | Copy/Planning |
## Cross-Team Dependencies
```
Server #650 (ContentType::Factual)
→ Server #652 (observer integration) — preferred ordering, not hard block
Server #633 (composable behavior engine) — format agreement
→ Copy #634 (decomposed behavior content)
Copy #656 (remove Krenn hand-authored) — may require client test update
→ flag to Client if test_insert_off_behavior.gd needs edits
Client #646 (toggle) — depends on server #652 being wired
(parallel development OK; both can land independently, integrate at end)
```
## Ticket Summary
| Team | Ticket | Title |
|------|--------|-------|
| server | #650 | ContentType::Factual — LLM bypass |
| server | #652 | Voice pipeline: observer integration |
| server | #655 | Remove v0.1 content loading system |
| server | #633 | Composable behavior engine (carry-over) |
| server | #651 | Friendly/RoutineDeviation tells — iterate |
| copy | #647 | Docs: Amend D-123, supersede D-124, file workshop D-records |
| copy | #645 | Content: Base text elevation pass |
| copy | #656 | Remove handwritten Krenn dialogue and monologue |
| copy | #657 | Remove detective mission system |
| copy | #634 | Author decomposed behavior content (carry-over) |
| copy | #653 | Culture persona authoring for non-Krenn cultures |
| client | #646 | UX: AI-Enhanced Dialogue toggle + hardware detection |
| planning | #658 | Update agent profiles and briefings for v0.2 |
**Total: 13 tickets** — server (5), copy (6), client (1), planning (1)
docs/sprints/sprint-26/planning.md
+36
View File
@@ -0,0 +1,36 @@
# Sprint 26: Clean House — Planning Tasks
**Goal:** Ship the voice pipeline to production by integrating observer, removing v0.1 dead weight, and stabilizing the codebase.
**Branch:** `planning` (or `main` — no code, docs only)
**Agents:** Qatux (documenter), SI (project manager)
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #658 | Update agent profiles and briefings for v0.2 | — |
Use `tooling/db/ticket show <id>` for full details.
## Key Decisions
- `decisions/scope.md` — D-114 (generator-first proof-of-life), D-117 (tycoon bookmark, zero investigation content), D-119 (generator spike Sprint 25 as critical path)
- `decisions/content.md` — D-122 (all NPCs generated), D-128 (culture implicit in location), D-138 (LLM re-voicing pipeline)
## Notes
- **#658 Update agent profiles and briefings for v0.2:** Audit and update `.claude/agents/` (20 files) and `docs/briefings/` (18 files). Many still reference v0.1 detective/smuggler gameplay, hand-authored content pipeline, and pre-workshop assumptions. Specific removals: all references to Kael Davan, Sera Venn, smuggler/detective archetypes as playable characters, the v0.1 triangle configuration, the complicity framing (superseded by consequence per D-132). Specific additions: generator-first approach (D-114), all NPCs generated (D-122), voice pipeline (D-138), tycoon bookmark (D-117), Krenn culture as implicit starting context (D-128). Work through each agent briefing systematically — do not bulk-replace. Each agent has a different scope and different stale assumptions. After updating, cross-check: does any briefing still imply a playable detective or smuggler? Does any profile still describe the hand-authored content pipeline as the primary content creation method? Note: #648 (superseded by this ticket) was cancelled — its scope is included here.
## Dependency Chain
```
#658 (update agent profiles and briefings) — standalone
```
## PR Workflow
When ready to submit, commit to `main` directly (no code branch needed for doc-only changes), or create a PR from a short-lived branch:
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "docs(briefings): update agent profiles and briefings for v0.2 pivot" --description "body" --base main --head planning
```
docs/sprints/sprint-26/server.md
+60
View File
@@ -0,0 +1,60 @@
# Sprint 26: Clean House — Server Tasks
**Goal:** Ship the voice pipeline to production by integrating observer, removing v0.1 dead weight, and stabilizing the codebase.
**Branch:** `server`
**Agents:** Dudley (simulation), Tyre (arch), Hoshe (QA)
## Carry-over from Sprint 25
| # | Title | Status | Notes |
|---|-------|--------|-------|
| #633 | Composable behavior engine | backlog | Deferred from Sprint 25 — behavior pool explosion problem. No blockers. |
## New Tickets
| # | Title | Blocked by |
|---|-------|------------|
| #650 | ContentType::Factual — LLM bypass for fact-bearing lines | — |
| #652 | Voice pipeline: observer integration | #650 (preferred, not hard block) |
| #655 | Remove v0.1 content loading system | — |
| #651 | Friendly and RoutineDeviation tells — iterate post-ship | — |
Use `tooling/db/ticket show <id>` for full details.
## Key Decisions
- `decisions/content.md` — D-138 (LLM re-voicing pipeline: ContentType::Factual from Spike 2, observer wiring spec), D-121 (voice is culture-driven), D-122 (all NPCs generated)
- `decisions/scope.md` — D-117 (zero investigation content in v0.2), D-114 (generator-first)
## Open Questions to Resolve Early
- **Q-057: Composable behavior generation** — partially resolved by D-138 (resolves the pipeline question). #633 implementation still needs a concrete behavior primitive format. Resolve the data structure before writing code. Resolve before #633 starts.
## Notes
- **#650 ContentType::Factual:** The voice module currently routes all content through the LLM. Spike 2 showed that 2B models corrupt quantitative lines ("14 crates in bay seven" → "fourteen crates are missing") and invert denials. Add `Factual` as a third `ContentType` variant alongside `Dialogue` and `Behavior`. Lines tagged `Factual` skip the LLM entirely and are served as base text. The classification logic lives in `server/src/voice/prompt_builder.rs` (currently builds prompts for all content types). Paula endorsed ContentType::Factual in the Spike 2 session — do not revisit the design decision.
- **#652 Voice pipeline observer integration:** The pipeline exists (`server/src/voice/`) but nothing wires into it yet. The observer emits behavior and dialogue events to the client via `server/src/bridge/types.rs` — the voice lookup must intercept those events before they hit the bridge. Integration points: `server/src/voice/lookup.rs` (the query interface), `server/src/perception/observer/mod.rs` (snapshot generation), `server/src/bridge/text_renderer.rs` (current text output path). Fall back to base text on cache miss — never block on LLM. Tell behaviors are passthrough (already routed per #642). Prefer landing #650 first so `Factual` content type is established before observer wiring routes content to it.
- **#655 Remove v0.1 content loading system:** Delete `server/src/content/` entirely: `loader.rs`, `types.rs`, `line_pool.rs`, `hot_reload.rs`, `spawn.rs`, `template.rs`, `instantiation.rs`, `entanglement.rs`, `mod.rs`. Also remove: `tooling/content-converter/`, `tooling/validate-content`, `content-ron/` compiled output, `content/_meta/` style guides. Server tests to delete: `server/tests/content_loading.rs`, `server/tests/content_runtime.rs`, `server/tests/content_scaling.rs`, `server/tests/template_instantiation.rs`, `server/tests/template_schema.rs`. **Preserve** `content/global/` (enums, knowledge, culture profiles — still live). Before deleting `server/src/content/types.rs`, audit re-exports: any types still used by other modules must be moved, not dropped. Run `cargo check` after each deletion step, not once at the end.
- **#633 Composable behavior engine:** Current hand-authored behavior pools in `server/src/npc/routine.rs` enumerate culture×zone×role combinations, which won't scale to the generator. Goal: introduce a behavior primitive format (role action + culture modifier + context tag) and an assembly function that composes them at NpcBlueprint instantiation time. The `NpcBlueprint` struct in `server/src/npc/blueprint.rs` is the output target. Do not delete existing behavior pools until new assembly produces equivalent output — verify with an eyeball diff on generated behaviors for seed 42.
- **#651 Friendly/RoutineDeviation tells — iterate post-ship:** Spike 2 showed these two tells produce output indistinguishable from neutral on Gemma 2B. Three options: stronger few-shot examples in the prompt, non-speech-act encoding (body language descriptions rather than dialogue register), or treat as a 2B capacity ceiling and defer to a larger model. Start with stronger examples (lowest cost). If no improvement after 3 prompt iterations, document the ceiling and close. This is a low-priority polish ticket — do not block sprint completion on it.
## Dependency Chain
```
#650 (ContentType::Factual) → #652 (observer integration)
#633 (composable behavior engine) — parallel track, standalone
#655 (remove v0.1 content loading) — parallel track, standalone
#651 (tells iterate) — parallel track, standalone
```
## PR Workflow
When ready to submit, create a PR with `tea` CLI. **All flags are required** to avoid TTY prompts (see CLAUDE.md "Gitea access" section):
```bash
tea pr create --repo jpmschweitzer/settled-reach --login schweitz --title "feat(simulation): description" --description "body" --base main --head server
```