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

feat(content): drama module schema + line ID design (#158, #544) #64

Closed
jpmschweitzer wants to merge 0 commits from copy into main
pull from: copy
merge into: :main
Conversation 3 Commits - Files Changed -
jpmschweitzer commented 2026-02-25 02:28:41 +01:00
Owner
Copy Link
Copy Source

Summary

Sprint 18 copy team deliverables — two design-first tickets:

  • #544 — D-084: Dual-namespace line ID scheme — resolves Q-028. Role namespace (shared pool) unchanged; instance namespace (role-slug + seeded counter) added as opt-in for per-instance authored content on auto-generated NPCs. No schema migration needed.
  • #158 — Tier 1 drama module schema — JSON Schema for drama modules covering entry conditions, NPC requirements, event sequences, and outcomes. Includes smuggling ring v0.1 stub module (6 NPC roles, dual event sequences, 5 outcomes) and authoring guide with review feedback.

Files changed

  • decisions/content.md — D-084 decision record added
  • decisions/questions.md — Q-028 resolved → D-084
  • decisions/README.md — index updated
  • content/schemas/drama_module.schema.yaml — new schema
  • content/modules/tier1/smuggling_ring_v0_1.yaml — new stub module
  • docs/design/line-id-authoring-guide.md — new authoring guide
  • docs/design/tier1-module-authoring.md — new authoring guide
  • CHANGELOG.md — updated

Review notes

  • Mellanie reviewed #158 for authoring ergonomics — three doc gaps patched (pattern/motivation reference, terminal outcome semantics, discovery method → trigger bridge)
  • D-084 unblocks server/ci registry implementation (Sprint 19)
  • Drama module schema unblocks storyteller activation (future sprint)
## Summary Sprint 18 copy team deliverables — two design-first tickets: - **#544 — D-084: Dual-namespace line ID scheme** — resolves Q-028. Role namespace (shared pool) unchanged; instance namespace (role-slug + seeded counter) added as opt-in for per-instance authored content on auto-generated NPCs. No schema migration needed. - **#158 — Tier 1 drama module schema** — JSON Schema for drama modules covering entry conditions, NPC requirements, event sequences, and outcomes. Includes smuggling ring v0.1 stub module (6 NPC roles, dual event sequences, 5 outcomes) and authoring guide with review feedback. ## Files changed - `decisions/content.md` — D-084 decision record added - `decisions/questions.md` — Q-028 resolved → D-084 - `decisions/README.md` — index updated - `content/schemas/drama_module.schema.yaml` — new schema - `content/modules/tier1/smuggling_ring_v0_1.yaml` — new stub module - `docs/design/line-id-authoring-guide.md` — new authoring guide - `docs/design/tier1-module-authoring.md` — new authoring guide - `CHANGELOG.md` — updated ## Review notes - Mellanie reviewed #158 for authoring ergonomics — three doc gaps patched (pattern/motivation reference, terminal outcome semantics, discovery method → trigger bridge) - D-084 unblocks server/ci registry implementation (Sprint 19) - Drama module schema unblocks storyteller activation (future sprint)
jpmschweitzer added 3 commits 2026-02-25 02:28:42 +01:00
feat(content): D-084 dual-namespace line ID scheme — resolve Q-028 (#544) 9cec3df68c 
Role namespace (shared pool) stays unchanged; instance namespace
(role-slug + seeded counter) added as opt-in for per-instance
authored content on auto-generated NPCs. No schema migration needed.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
feat(content): Tier 1 drama module schema and smuggling ring stub (#158) 16a79c928c 
JSON Schema for drama modules covering entry conditions, NPC
requirements, event sequences, and outcomes. Includes v0.1
vertical slice stub module and authoring guide with review
feedback from Mellanie (pattern/motivation reference, terminal
outcome semantics, fact ID conventions, trigger type bridge).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
chore(meta): update changelog 2493dcb5f0 
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
jpmschweitzer commented 2026-02-25 02:37:55 +01:00
Author
Owner
Copy Link
Copy Source

Review: copy → main (PR #64, type: copy)

Hoshe (QA): REQUEST_CHANGES

Well-structured schema and docs, but the module has schema conformance issues.

# File Severity Issue
1 content/modules/tier1/smuggling_ring_v0_1.yaml:507-508,578-579 critical events_fired references flag names (secret_meeting_occurred, final_shipment_known) instead of event IDs (kael_secret_meeting, final_shipment_scheduled). Two outcomes unreachable.
2 content/modules/tier1/smuggling_ring_v0_1.yaml:191,215,342,377 warning 4 orphaned flags set but never consumed by any outcome condition.
3 content/modules/tier1/smuggling_ring_v0_1.yaml:458 warning Typo: "Observer Sera's path" → "Observe Sera's path".
4 decisions/README.md:18 warning Question count stale — says Q-026, should be Q-028.
5 content/schemas/drama_module.schema.yaml:38-43 suggestion module_id pattern accepts trivially short name portions.
6 docs/design/line-id-authoring-guide.md:96 suggestion "Fresh sequence" wording ambiguous for cross-location NPC files.

Paula (Narrative Depth): APPROVE

Strong design work — dual-lens experience mechanically enforced, moral weight in every outcome path.

# File Severity Issue
1 smuggling_ring_v0_1.yaml:501 suggestion ring_exposed outcome description doesn't capture relational dimension of Kael's hostility.
2 smuggling_ring_v0_1.yaml:530 suggestion is_terminal priority logic buried in inline comment — upgrade to explicit PRIORITY NOTE.
3 smuggling_ring_v0_1.yaml:596-628 suggestion ring_completes/ring_splinters say nothing about Naia's awareness — consequence-light vs other outcomes.
4 drama_module.schema.yaml:350-357 suggestion SKEPTIC motivation has no instantiated example in the reference module.
5 tier1-module-authoring.md:236-248 suggestion D-035 trigger mapping table omits hear_sound.
6 tier1-module-authoring.md:57 suggestion "Write dual_lens first" advice doesn't cover adapting existing NPC triangles.

Miri (World Consistency): APPROVE

Setting-faithful, IP-clean, consistent with all relevant D-records.

# File Severity Issue
1 smuggling_ring_v0_1.yaml:257 suggestion "Meridian" comms network not anchored in any D-record — floating nomenclature.
2 smuggling_ring_v0_1.yaml:521-523,561-563 suggestion Faction slugs lattice-commission and the-ring unverified against faction registry.
3 tier1-module-authoring.md:445 suggestion content/campaigns/main/systems/krenn/ path not in project structure docs.
4 drama_module.schema.yaml:350-357 suggestion must_have_pattern enum lacks reference to D-024 definition source.
5 drama_module.schema.yaml:670-718 suggestion No npc_knowledge_update outcome effect — Naia's awareness not structurally trackable.
6 smuggling_ring_v0_1.yaml:630-655 suggestion (Positive) Expiry outcome correctly uses facts_not_known — good reference model.

Verdict: CHANGES REQUESTED

Deduplicated blockers:

  1. Critical — events_fired uses flag names instead of event IDs — two outcomes unreachable
  2. Warning — 4 orphaned flags (set, never consumed)
  3. Warning — Typo in discovery_method text
  4. Warning — README question count stale
## Review: copy → main (PR #64, type: copy) ### Hoshe (QA): REQUEST_CHANGES Well-structured schema and docs, but the module has schema conformance issues. | # | File | Severity | Issue | |---|------|----------|-------| | 1 | `content/modules/tier1/smuggling_ring_v0_1.yaml:507-508,578-579` | critical | `events_fired` references flag names (`secret_meeting_occurred`, `final_shipment_known`) instead of event IDs (`kael_secret_meeting`, `final_shipment_scheduled`). Two outcomes unreachable. | | 2 | `content/modules/tier1/smuggling_ring_v0_1.yaml:191,215,342,377` | warning | 4 orphaned flags set but never consumed by any outcome condition. | | 3 | `content/modules/tier1/smuggling_ring_v0_1.yaml:458` | warning | Typo: "Observer Sera's path" → "Observe Sera's path". | | 4 | `decisions/README.md:18` | warning | Question count stale — says Q-026, should be Q-028. | | 5 | `content/schemas/drama_module.schema.yaml:38-43` | suggestion | `module_id` pattern accepts trivially short name portions. | | 6 | `docs/design/line-id-authoring-guide.md:96` | suggestion | "Fresh sequence" wording ambiguous for cross-location NPC files. | ### Paula (Narrative Depth): APPROVE Strong design work — dual-lens experience mechanically enforced, moral weight in every outcome path. | # | File | Severity | Issue | |---|------|----------|-------| | 1 | `smuggling_ring_v0_1.yaml:501` | suggestion | `ring_exposed` outcome description doesn't capture relational dimension of Kael's hostility. | | 2 | `smuggling_ring_v0_1.yaml:530` | suggestion | `is_terminal` priority logic buried in inline comment — upgrade to explicit PRIORITY NOTE. | | 3 | `smuggling_ring_v0_1.yaml:596-628` | suggestion | `ring_completes`/`ring_splinters` say nothing about Naia's awareness — consequence-light vs other outcomes. | | 4 | `drama_module.schema.yaml:350-357` | suggestion | `SKEPTIC` motivation has no instantiated example in the reference module. | | 5 | `tier1-module-authoring.md:236-248` | suggestion | D-035 trigger mapping table omits `hear_sound`. | | 6 | `tier1-module-authoring.md:57` | suggestion | "Write dual_lens first" advice doesn't cover adapting existing NPC triangles. | ### Miri (World Consistency): APPROVE Setting-faithful, IP-clean, consistent with all relevant D-records. | # | File | Severity | Issue | |---|------|----------|-------| | 1 | `smuggling_ring_v0_1.yaml:257` | suggestion | "Meridian" comms network not anchored in any D-record — floating nomenclature. | | 2 | `smuggling_ring_v0_1.yaml:521-523,561-563` | suggestion | Faction slugs `lattice-commission` and `the-ring` unverified against faction registry. | | 3 | `tier1-module-authoring.md:445` | suggestion | `content/campaigns/main/systems/krenn/` path not in project structure docs. | | 4 | `drama_module.schema.yaml:350-357` | suggestion | `must_have_pattern` enum lacks reference to D-024 definition source. | | 5 | `drama_module.schema.yaml:670-718` | suggestion | No `npc_knowledge_update` outcome effect — Naia's awareness not structurally trackable. | | 6 | `smuggling_ring_v0_1.yaml:630-655` | suggestion | (Positive) Expiry outcome correctly uses `facts_not_known` — good reference model. | ### Verdict: CHANGES REQUESTED Deduplicated blockers: 1. **Critical** — `events_fired` uses flag names instead of event IDs — two outcomes unreachable 2. **Warning** — 4 orphaned flags (set, never consumed) 3. **Warning** — Typo in discovery_method text 4. **Warning** — README question count stale
jpmschweitzer added 1 commit 2026-02-25 02:42:52 +01:00
fix(content): PR #64 review — schema compliance and orphaned flags c55474f46d 
Fix events_fired referencing flag names instead of event IDs (two
outcomes unreachable). Wire 4 orphaned flags into narratively
coupled outcome conditions. Fix typo and stale question count.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
jpmschweitzer commented 2026-02-25 09:42:40 +01:00
Author
Owner
Copy Link
Copy Source

Review: copy -> main (type: copy) — PR #64

Hoshe (QA): REQUEST_CHANGES

Schema and authoring guides are well-structured. The fix commit c55474f addressed schema compliance correctly. However, three critical issues remain in the smuggling ring module's logic and data references.

# File Severity Issue
1 content/modules/tier1/smuggling_ring_v0_1.yaml:134 critical named_npc: "npc:nils" doesn't match canonical ID npc:nils-davan in the district profile. Schema Tier 2 validation = load-time failure.
2 content/modules/tier1/smuggling_ring_v0_1.yaml:579-585 critical ring_completes outcome uses flags_not_set: [kael_message_sent], but kael_message_sent is auto-set at ~tick 1550. Outcome requires ticks_since_activation: 3600. Gate is permanently false — outcome unreachable.
3 content/modules/tier1/smuggling_ring_v0_1.yaml (throughout) critical All ring.* fact IDs have no entries in content/global/knowledge/. Facts will silently never become discoverable at runtime.
4 content/modules/tier1/smuggling_ring_v0_1.yaml:599-633 warning ring_splinters is is_terminal: false with no clear downstream exit path after ring goes quiet. May run indefinitely.
5 decisions/README.md:14-15 suggestion D-035 ID collision — appears in both perception.md (LOS shadowcasting) and content.md (tag taxonomy). Pre-existing but now more visible.
6 docs/design/line-id-authoring-guide.md:96 suggestion "Contiguous prefix" wording slightly misleading given that gaps from deleted lines are acceptable.

Paula (Narrative Depth): APPROVE

Outstanding narrative design. The Kael arc produces genuine retroactive reinterpretation — events seen earlier mean something different after later reveals. Dual-lens framing creates distinct moral weight per character (smuggler: loyalty vs safety; detective: duty vs harm reduction).

# File Severity Issue
1 smuggling_ring_v0_1.yaml:529-565 suggestion kael_escapes relies on outcome ordering to avoid co-firing with ring_exposed. A defensive flags_not_set guard would be more robust.
2 smuggling_ring_v0_1.yaml:599-633 suggestion ring_splinters non-terminal with no explicit downstream exit path documented. Expiry is the implicit safety net but could confuse future authors.
3 smuggling_ring_v0_1.yaml:100-106 suggestion Pattern/motivation constraints on named bindings are redundant (useful as documentation, but guide should note this explicitly).
4 tier1-module-authoring.md:236-248 suggestion Guide recommends two discovery methods per fact, but the reference module only provides one per fact. Clarify stub vs production expectation.

Miri (World Consistency): REQUEST_CHANGES

Setting integration is strong — Meridian network, Commission, Syndic supply chains all use established Settled Reach terminology with no franchise parallels. Internal consistency is solid. However, the same ring_completes/ring_splinters auto-flag gating issue makes two outcome paths unreachable.

# File Severity Issue
1 smuggling_ring_v0_1.yaml:580-585 warning ring_completes gated on flags_not_set: [kael_message_sent] — auto-fired flag makes this permanently false by tick 1550. Unreachable outcome.
2 smuggling_ring_v0_1.yaml:617-621 warning ring_splinters has same auto-flag gate issue. Partial-discovery resolution path unreachable.
3 global/factions/lattice-commission.yaml, the-ring.yaml suggestion Empty faction stubs — faction_reaction effects will silently no-op. Add at least slug/display_name or a # TODO reference.
4 smuggling_ring_v0_1.yaml:135 suggestion npc:nils binding vs existing npc:renn ring-operative — clarify whether these are distinct characters.

Verdict: CHANGES REQUESTED

Two reviewers flagged critical/warning issues. Key problems:

  1. NPC ID mismatch (npc:nils vs npc:nils-davan) — load-time failure
  2. Auto-flag gating bug — ring_completes and ring_splinters both unreachable due to kael_message_sent being auto-set before evaluation
  3. Unregistered fact IDs — all ring.* facts missing from content/global/knowledge/
## Review: copy -> main (type: copy) — PR #64 ### Hoshe (QA): REQUEST_CHANGES Schema and authoring guides are well-structured. The fix commit `c55474f` addressed schema compliance correctly. However, three critical issues remain in the smuggling ring module's logic and data references. | # | File | Severity | Issue | |---|------|----------|-------| | 1 | `content/modules/tier1/smuggling_ring_v0_1.yaml:134` | critical | `named_npc: "npc:nils"` doesn't match canonical ID `npc:nils-davan` in the district profile. Schema Tier 2 validation = load-time failure. | | 2 | `content/modules/tier1/smuggling_ring_v0_1.yaml:579-585` | critical | `ring_completes` outcome uses `flags_not_set: [kael_message_sent]`, but `kael_message_sent` is auto-set at ~tick 1550. Outcome requires `ticks_since_activation: 3600`. Gate is permanently false — outcome unreachable. | | 3 | `content/modules/tier1/smuggling_ring_v0_1.yaml` (throughout) | critical | All `ring.*` fact IDs have no entries in `content/global/knowledge/`. Facts will silently never become discoverable at runtime. | | 4 | `content/modules/tier1/smuggling_ring_v0_1.yaml:599-633` | warning | `ring_splinters` is `is_terminal: false` with no clear downstream exit path after ring goes quiet. May run indefinitely. | | 5 | `decisions/README.md:14-15` | suggestion | D-035 ID collision — appears in both `perception.md` (LOS shadowcasting) and `content.md` (tag taxonomy). Pre-existing but now more visible. | | 6 | `docs/design/line-id-authoring-guide.md:96` | suggestion | "Contiguous prefix" wording slightly misleading given that gaps from deleted lines are acceptable. | ### Paula (Narrative Depth): APPROVE Outstanding narrative design. The Kael arc produces genuine retroactive reinterpretation — events seen earlier mean something different after later reveals. Dual-lens framing creates distinct moral weight per character (smuggler: loyalty vs safety; detective: duty vs harm reduction). | # | File | Severity | Issue | |---|------|----------|-------| | 1 | `smuggling_ring_v0_1.yaml:529-565` | suggestion | `kael_escapes` relies on outcome ordering to avoid co-firing with `ring_exposed`. A defensive `flags_not_set` guard would be more robust. | | 2 | `smuggling_ring_v0_1.yaml:599-633` | suggestion | `ring_splinters` non-terminal with no explicit downstream exit path documented. Expiry is the implicit safety net but could confuse future authors. | | 3 | `smuggling_ring_v0_1.yaml:100-106` | suggestion | Pattern/motivation constraints on named bindings are redundant (useful as documentation, but guide should note this explicitly). | | 4 | `tier1-module-authoring.md:236-248` | suggestion | Guide recommends two discovery methods per fact, but the reference module only provides one per fact. Clarify stub vs production expectation. | ### Miri (World Consistency): REQUEST_CHANGES Setting integration is strong — Meridian network, Commission, Syndic supply chains all use established Settled Reach terminology with no franchise parallels. Internal consistency is solid. However, the same `ring_completes`/`ring_splinters` auto-flag gating issue makes two outcome paths unreachable. | # | File | Severity | Issue | |---|------|----------|-------| | 1 | `smuggling_ring_v0_1.yaml:580-585` | warning | `ring_completes` gated on `flags_not_set: [kael_message_sent]` — auto-fired flag makes this permanently false by tick 1550. Unreachable outcome. | | 2 | `smuggling_ring_v0_1.yaml:617-621` | warning | `ring_splinters` has same auto-flag gate issue. Partial-discovery resolution path unreachable. | | 3 | `global/factions/lattice-commission.yaml`, `the-ring.yaml` | suggestion | Empty faction stubs — faction_reaction effects will silently no-op. Add at least `slug`/`display_name` or a `# TODO` reference. | | 4 | `smuggling_ring_v0_1.yaml:135` | suggestion | `npc:nils` binding vs existing `npc:renn` ring-operative — clarify whether these are distinct characters. | ### Verdict: CHANGES REQUESTED Two reviewers flagged critical/warning issues. Key problems: 1. **NPC ID mismatch** (`npc:nils` vs `npc:nils-davan`) — load-time failure 2. **Auto-flag gating bug** — `ring_completes` and `ring_splinters` both unreachable due to `kael_message_sent` being auto-set before evaluation 3. **Unregistered fact IDs** — all `ring.*` facts missing from `content/global/knowledge/`
jpmschweitzer added 1 commit 2026-02-25 09:49:21 +01:00
fix(content): PR #64 round 2 — NPC ID, outcome gating, fact stubs cc898d60c7 
Fix npc:nils → npc:nils-davan canonical ID mismatch. Replace
auto-flag gates on ring_completes/ring_splinters with player-
action-gated fact conditions (unreachable outcomes). Add
ring_stalemate terminal exit for non-terminal ring_splinters.
Create ring.yaml with 10 fact stubs for content/global/knowledge/.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
jpmschweitzer commented 2026-02-25 09:54:44 +01:00
Author
Owner
Copy Link
Copy Source

Review Round 3: copy -> main — PR #64

Hoshe (QA): APPROVE

All 4 previous issues confirmed fixed:

  1. NPC ID — npc:nils-davan matches canonical ID.
  2. Auto-flag gating — replaced with facts_not_known / facts_known polarity. module_abandoned also fixed.
  3. Unregistered facts — ring.yaml registers all 10 fact IDs. Cross-reference verified: 10/10.
  4. Exit path — ring_stalemate (terminal) added as downstream from ring_splinters.
# File Severity Issue
1 ring.yaml suggestion Field vocabulary differs from schema — pre-existing pattern, not introduced by this PR.
2 smuggling_ring_v0_1.yaml:134 suggestion nils-davan profile says off-stage but module fires observable events for him. Worth reviewing before simulation hookup.

Paula (Narrative Depth): APPROVE

Fixes are narratively coherent. facts_not_known gating correctly measures player investigation engagement. Knowledge catalog entries are evocative and precise.

# File Severity Issue
1 ring.yaml suggestion ring.voss_accelerating_timeline description over-explains at knows_of confidence.

Miri (World Consistency): APPROVE

Both warnings resolved. All 10 fact IDs registered. IP originality holds. Outcome tree is coherent.

No issues.

Verdict: APPROVED

Ready to merge.

## Review Round 3: copy -> main — PR #64 ### Hoshe (QA): APPROVE All 4 previous issues confirmed fixed: 1. **NPC ID** — `npc:nils-davan` matches canonical ID. 2. **Auto-flag gating** — replaced with `facts_not_known` / `facts_known` polarity. `module_abandoned` also fixed. 3. **Unregistered facts** — `ring.yaml` registers all 10 fact IDs. Cross-reference verified: 10/10. 4. **Exit path** — `ring_stalemate` (terminal) added as downstream from `ring_splinters`. | # | File | Severity | Issue | |---|------|----------|-------| | 1 | `ring.yaml` | suggestion | Field vocabulary differs from schema — pre-existing pattern, not introduced by this PR. | | 2 | `smuggling_ring_v0_1.yaml:134` | suggestion | `nils-davan` profile says off-stage but module fires observable events for him. Worth reviewing before simulation hookup. | ### Paula (Narrative Depth): APPROVE Fixes are narratively coherent. `facts_not_known` gating correctly measures player investigation engagement. Knowledge catalog entries are evocative and precise. | # | File | Severity | Issue | |---|------|----------|-------| | 1 | `ring.yaml` | suggestion | `ring.voss_accelerating_timeline` description over-explains at `knows_of` confidence. | ### Miri (World Consistency): APPROVE Both warnings resolved. All 10 fact IDs registered. IP originality holds. Outcome tree is coherent. No issues. ### Verdict: APPROVED Ready to merge.
jpmschweitzer closed this pull request 2026-02-25 09:59:28 +01:00

Pull request closed

This pull request cannot be reopened because the branch was deleted.
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
jpmschweitzer (Jeroen Schweitzer)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: jpmschweitzer/settled-reach#64