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

docs(design): add Gestalt KG validation to #253 prerequisite map and #121 mood guide

Browse Source 
#253 monologue-content-architecture.md:
- All prerequisite fact_ids validated against knowledge vocabulary — APPROVED
- Flag: behavioral.sera_avoidance should be behavioral.sera_avoidance_pattern
- Flag: investigation.drin_inspection_pattern duplicated in investigation.yaml
- Confirm: cooldown is content-layer (schema field) — OQ item 3 resolved
- Pending: witness_interaction trigger payload (OQ item 4) — Dudley to confirm
  before named-pair witness_interaction lines can be authored

#121 monologue-voice-guide.md:
- BLOCKING: mood vocabulary mismatch — voice guide uses neutral/anxious/frustrated/
  content/warm/hostile but schema enum uses fond/comfortable/worried/analytical/
  conflicted/concerned/relieved; hostile not in schema at all
- Provide interim mapping table so Mellanie can use correct schema names
- Flag schema gaps: analytical and relieved have no voice guide coverage
- Recommend schema rename to voice guide names (Lead decision required)
- Mood-as-selection-weight model is mechanically coherent — APPROVED

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-02-20 18:43:55 +01:00
co-authored by Claude Sonnet 4.6
parent 8c362c8535
commit df4d7b4666
2 changed files with 130 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/design/monologue-content-architecture.md
+48
View File
@@ -513,6 +513,54 @@ Mellanie is final authority on voice. Paula is final authority on arc coherence.
---
## 9. Gestalt — KG Expressibility Validation (2026-02-20)
**Overall assessment:** The prerequisite map is expressible from KG state. All referenced fact_id categories exist in the knowledge vocabulary. One naming error, one duplicate in the vocabulary, and two open questions requiring server-side confirmation before #120 can write gated lines.
---
### Validated fact_id references
All prerequisite patterns from Section 5.2 verified against `content/global/knowledge/*.yaml`:
| Fact ID in doc | Status | Notes |
|----------------|--------|-------|
| `investigation.kael_corridor_meeting` | ✅ EXISTS | Shared ID, both characters |
| `investigation.kael_unknown_contact` | ✅ EXISTS | Shared ID |
| `behavioral.kael_evasion` | ✅ EXISTS | Smuggler only, `direct` confidence |
| `behavioral.kael_behavioral_change` | ✅ EXISTS | Smuggler only (Paula's Phase 2 gate) |
| `behavioral.sera_avoidance` | ⚠️ NAMING ERROR | Actual ID is `behavioral.sera_avoidance_pattern` — doc must use the full name or lines won't load |
| `behavioral.sera_topic_deflection` | ✅ EXISTS | Both characters |
| `knowledge.ring_routing_knowledge` | ✅ EXISTS | Smuggler only, Background-level (`knows_details`) |
| `awareness.detective_presence` | ✅ EXISTS | Smuggler only |
| `investigation.manifest_discrepancy` | ✅ EXISTS | Shared; detective starts at `suspects` (Background) |
**Action required (Mellanie):** Every authored line using `behavioral.sera_avoidance` as a prerequisite must be corrected to `behavioral.sera_avoidance_pattern` before content validation will pass.
---
### KG vocabulary issue: duplicate fact_id
`investigation.drin_inspection_pattern` appears **twice** in `content/global/knowledge/investigation.yaml` with slightly different descriptions. This is a vocabulary error that will cause undefined behavior when the fact is queried. Action: Qatux to deduplicate and merge descriptions in the knowledge vocabulary.
---
### Open question resolutions
**OQ from Section 7, item 3 — `time_idle` cooldown handling:** CONFIRMED as content-layer. The monologue schema already has `cooldown` as an integer field per line (minimum ticks before refiring). Authors set this in YAML. No schema update needed. Atmosphere lines: `cooldown: 300` (roughly 5 minutes at 60 ticks/second). Investigation lines: `cooldown: 600`. FRIEND arc lines that should fire once and not again: `cooldown: 99999`.
**OQ from Section 7, item 4 — `witness_interaction` trigger payload:** NOT YET CONFIRMED. The trigger needs to pass which two NPCs are interacting so pool queries can filter for named-pair lines. If the trigger doesn't provide this, witness_interaction lines can't target Kael+unknown or Voss+Maret specifically — they'd have to fire generically. **Action:** Dudley to confirm trigger payload before #120 writes witness_interaction lines. Do not author named-pair witness_interaction lines until this is confirmed.
---
### Priority field review
Priority guidelines from Section 5.3 are mechanically sound. The selection pipeline uses priority as a tiebreaker when multiple eligible lines compete for one trigger slot. Values are reasonable. One note: "FRIEND trust-contamination" lines tagged 9-10 will always win when eligible — authors must make sure these only fire when the KG state is correct, or they'll dominate every trigger slot during that arc phase. Keep the prerequisite gates tight (compound gates with both relationship + fact conditions are the right call for 9-10 priority lines).
**Prerequisite map validation: APPROVED** with the `behavioral.sera_avoidance_pattern` naming fix required before ship.
---
## 8. Paula — Narrative Review (2026-02-20)
**Overall assessment:** The architecture is sound and coherent with THE FRIEND arc. All critical design constraints (D-032 hard partition, D-034 no generation expansion, D-016 four functions) are correctly applied. No blocking issues.
docs/design/monologue-voice-guide.md
+82
View File
@@ -456,3 +456,85 @@ For Mellanie — a vocabulary guide per background to use when writing example l
---
*Narrative framing complete as of 2026-02-20. Mellanie to supply example lines for all section prompts marked "Mellanie — write X examples." Gestalt to validate mood → delivery mappings in Chapter 4 for mechanical coherence with server-side mood system (#323).*
---
## Gestalt — Mood → Delivery Validation (2026-02-20)
**Status: BLOCKING ISSUE — mood vocabulary mismatch between this document and the schema.**
---
### The problem
Chapter 4 uses mood names that do **not match** the D-035 schema enum values or the Rust `Mood` type in `server/src/content/line_pool.rs`. Content authors following this guide will write `mood: warm` in their YAML files, but the schema only accepts `mood: fond`. The selection pipeline will silently skip lines with unrecognized mood tags.
**Voice guide names:** `neutral`, `anxious`, `frustrated`, `content`, `suspicious`, `warm`, `hostile`, `focused`
**Schema/Rust enum names:** `fond`, `comfortable`, `worried`, `suspicious`, `analytical`, `conflicted`, `concerned`, `relieved`, `focused`
---
### Mapping table (interim — for use until the vocabulary is reconciled)
Authors MUST use schema names in YAML files. Use this table to translate from Chapter 4 concepts:
| Chapter 4 concept | Schema tag to use | Fit quality | Notes |
|-------------------|------------------|-------------|-------|
| `neutral` | *(no tag — omit mood field)* | ✅ Good | Neutral = baseline = untagged. Selection system defaults to eligible untagged lines. |
| `anxious` | `worried` | ✅ Good | Schema description: "Anxious about something specific." Exact match. |
| `frustrated` | `concerned` | ⚠️ Imperfect | Schema description: "Worried about someone else's wellbeing." Close enough for v0.1 authoring, but semantically different. |
| `content` | `comfortable` | ✅ Good | Schema description: "At ease, relaxed." Good match. |
| `suspicious` | `suspicious` | ✅ Exact | Same word. |
| `warm` | `fond` | ✅ Good | Schema description: "Warm, affectionate." Exact match. |
| `hostile` | *(no clean match)* | ❌ GAP | `hostile` is not in the current schema enum. `conflicted` (torn between impulses) is the closest but doesn't capture adversarial register. See resolution below. |
| `focused` | `focused` | ✅ Exact | Sprint 8 addition. Same word. |
**Uncovered schema values** (not addressed in Chapter 4):
- `analytical` — described as "Thoughtful, assessing. Processing information." This is a mood the voice guide doesn't model explicitly. It surfaces in the detective's NPC interaction monologue during passive evidence-gathering. Mellanie: treat as a subdued version of `suspicious` without a specific object — the character is processing, not alarmed.
- `relieved` — described as "Tension has eased." The voice guide doesn't model this but it's mechanically useful post-confrontation or after a drop completes cleanly. Author a handful of `relieved` atmosphere lines per character per location; use the opposite of `anxious` as the authoring direction.
- `conflicted` — described as "Torn between competing impulses." The voice guide doesn't model this explicitly but it IS the dominant emotional state during the FRIEND arc's middle phase. FRIEND arc lines where the character is caught between loyalty and evidence should carry `conflicted` (not `suspicious` alone).
---
### Resolution proposal
**Recommended resolution (Gestalt proposes — Lead to decide):**
The voice guide's mood vocabulary is more intuitive for authors. Recommend updating the schema enum and Rust `Mood` type to match Chapter 4 names:
| Current schema name | Proposed new name | Rationale |
|--------------------|-------------------|-----------|
| `fond` | `warm` | Chapter 4 name is clearer for authors |
| `comfortable` | `content` | Chapter 4 name is clearer |
| `worried` | `anxious` | Chapter 4 name is more precise |
| `analytical` | keep or → `focused` | Overlaps with `focused`; consider merging |
| `conflicted` | keep as `conflicted` | Has specific meaning, Chapter 4 doesn't cover it |
| `concerned` | `frustrated` | Schema `concerned` = "worried about others" ≠ author intent; `frustrated` is more useful |
| `relieved` | keep as `relieved` | Useful, add coverage in voice guide |
| `suspicious` | `suspicious` | No change |
| `focused` | `focused` | No change |
| *(missing)* | add `hostile` | Required for adversarial register modeled in Chapter 4 |
This would require: schema update, Rust enum update (5 renames + 1 addition), global enums YAML update, and any existing content using the old names updated. Content volume is low enough that this is feasible now before large-scale authoring begins.
**Alternative (minimal change):** Update only the voice guide to use the current schema names. Authors use less-intuitive terms but no code changes needed. Lower cost but worse authoring experience.
---
### Mood as selection weight — mechanical coherence
The selection model in Section 4.3 is mechanically coherent with how the pipeline works:
- Line pool query returns all eligible lines (pass Layers 1-3)
- Layer 4 (topic + mood) applies weights, not hard filters — correct
- Untagged lines remain eligible — correct
- Mood-tagged lines are preferred when mood matches — correct
No issues with the model. The only mechanical problem is the vocabulary mismatch documented above.
**Trait modifier system (Chapters 2-3):** Mechanically coherent. Traits are authoring modifiers, not runtime filters. No engine-side trait tracking needed for monologue (unlike NPC dialogue, where trait modifiers shape the transformation guide). The authoring guide is sufficient. ✅
**FRIEND arc special case (Section 4.3):** The note about prioritizing mood-tagging for crisis beats is correct. The collision of `suspicious` (or `conflicted` in schema) + `warm` as the trust-contamination zone is the right call — that tension is what makes those lines land. ✅
---
**Mood → delivery validation: CONDITIONAL PASS.** The delivery model is mechanically coherent. Blocking issue: vocabulary mismatch with schema must be resolved before Mellanie authors any mood-tagged lines. Lead decision required on resolution path (schema rename vs. voice guide rename). All other mood system design is approved.