jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
11b29baefed11262a9e786d930388b39b80098aa
settled-reach/docs/architecture/v01-yaml-content-audit.md
T
jpmschweitzerandClaude Opus 4.6 034c1c6e37 fix(simulation): apply PR #94 review suggestions 
- validate_ron: add eligible_roles referential integrity check against
  defined RoleSpec.id values in zone-type templates
- v01-yaml-content-audit.md: fix grep path from data/templates to
  server/data/templates in the superseded-files verification command
- pre-commit hook: comment out nonexistent check-decision-ids script
  to stop per-commit warnings until the script is implemented

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-17 12:25:07 +01:00

120 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# v0.1 YAML Content Audit
**Date:** 2026-03-17
**Ticket:** #672
**Author:** Hoshe (QA)
**Sprint:** 27
## Summary
63 YAML files surveyed across `server/content/`, `server/data/templates/`, and `client/data/`.
- **Deprecated:** 14 files — pure named NPC / detective arc content, no generator value
- **Convertible:** 25 files — useful structure or data worth extracting to RON generator format
- **Already-superseded:** 4 files — role-based templates predating RON format, replaced by zone-type RON files
- **Infrastructure (no action):** 20 files — gauntlet, schemas, client UI, geography hierarchy, manifest
**Do not delete anything in this document.** Disposition requires explicit team review per ticket #672.
---
## Deprecated
Pure detective arc or named NPC content. No generator value. Recommend **archive** (move to `docs/archive/v01-content/`) rather than deletion.
| File | Why deprecated | Named NPCs |
|------|---------------|------------|
| `server/content/global/knowledge/ring.yaml` | All facts tied to named NPC actions (Kael's missed verification, Kael's corridor access, Voss/office confrontation, Sera's avoidance of Torek). No role-neutral facts. | Kael Davan, Sera Venn, Torek Lintar, Voss, Naia Tamm |
| `server/content/global/knowledge/behavioral.yaml` | Named NPC behavioral tells: Kael's lying tell, Kael's behavior change, Sera's avoidance pattern, Sera's deflection topics, Sera's kiosk habit, Sera's manifest knowledge. All keyed to specific characters. | Kael, Sera, Torek |
| `server/content/global/knowledge/relationship.yaml` | Named NPC relationship facts: Kael-Naia partnership, Torek's financial arrangement. No generic relationship fact patterns. | Kael, Naia, Torek |
| `server/content/global/knowledge/entity-attributes.yaml` | Explicitly lists "Kael Davan" and "Kael" as example entity attribute values. The entire file is about named NPC attributes. | Kael Davan |
| `server/content/global/knowledge/progress.yaml` | Detective investigation milestone facts (`characters: [detective]`). E.g. "Detective filed first manifest discrepancy evidence". Detective-exclusive, no smuggler or generator path. | detective archetype only |
| `server/content/global/knowledge/awareness.yaml` | All facts reference the detective-vs-smuggler tension: `detective_presence`, `detective_investigating_ring`, `commission_audit_scheduled`. Not applicable to generated NPC knowledge. | detective, smuggler archetypes only |
| `server/content/modules/tier1/smuggling_ring_v0_1.yaml` | Full v0.1 drama module with named NPC cast (Kael, Naia, Sera, Voss, Torek). Kael's exit plan, dual-lens player experience. The module schema itself (drama_module.schema.yaml) may be worth keeping, but this specific content instance is named-NPC only. | Kael Davan, Naia Tamm, Sera Venn, Voss, Torek Lintar, Devra |
| `server/content/npc-conversations/overheard.yaml` | **Self-labeled LEGACY CONTENT** in the file header: "All entries in this file reference named NPCs… not served at runtime." Already flagged by the copy team; superseded by ticket #664 (zone-type-aware overheard generator). | Kael, Sera, Naia, Voss, Nils, Maret Korr, Lera |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/triangles/worried-partner.yaml` | Named NPC triangle: Kael Davan, Naia Tamm, Devra. Members reference `npc:kael-davan` directly. | Kael Davan, Naia Tamm, Devra |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/triangles/hub-power.yaml` | References Kael-adjacent narrative (hub power / ring pressure). Named NPC members. | Kael (indirect) |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/triangles/bar-tensions.yaml` | Named NPC triangle: Lera Sessik (bar owner), Resha (regular), Pell (bartender). Members reference `npc:lera-sessik` directly. | Lera Sessik, Resha, Pell |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/environmental/the-last-shift.yaml` | Environmental text for The Last Shift bar. 10 named NPC references. Lera, Sera, etc. character-specific text. | Lera, Sera |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/ticker/the-last-shift.yaml` | Ticker pool with `dual_lens` commentary for detective vs. smuggler archetypes specifically. Dual-lens framing assumes named player arcs. | smuggler/detective archetypes |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/routines/schedules.yaml` | Stub file (2 lines, comment only). No content. | none |
---
## Convertible
Useful data or structure worth extracting into the RON generator format. Disposition: **convert** (port specific patterns to RON zone-type files or generator schemas before archiving).
| File | What's worth extracting | Conversion target |
|------|------------------------|-------------------|
| `server/content/global/knowledge/knowledge.yaml` | Knowledge fact schema: `fact_id`, `description`, `typical_confidence`, `characters`, `notes`. Generic investigation knowledge patterns (ring structure, exit plan, organizational knowledge). The fact ID taxonomy and confidence level system are the most reusable. | Generator knowledge schema for zone-type fact pools |
| `server/content/global/knowledge/social.yaml` | Social positioning fact patterns (`bar_regular_status`, `social_circle_member`, `faction_affiliation`). These are role-neutral patterns that any NPC social site could produce. | Role-based social knowledge pools |
| `server/content/global/knowledge/location.yaml` | Location knowledge fact patterns: access points, operational significance, safe houses. The location knowledge taxonomy maps to zone-type location specs. | Zone-type location knowledge schemas |
| `server/content/global/knowledge/world.yaml` | World-level knowledge patterns: faction presence, station governance, lattice tech context. These are world-building facts any NPC could know. | World knowledge pools for zone-type culture profiles |
| `server/content/global/knowledge/contraband.yaml` | Contraband knowledge structure: ring existence, component types, operational methods. The schema structure (ring_exists → ring_lattice_components → ring_medical_components → ring_vault_location) is a good template for role-based secret knowledge escalation. | Role-based secret knowledge schemas for zone-type ring roles |
| `server/content/global/enums/triggers.yaml` | Monologue trigger type enum: `enter_location`, `observe_npc`, `observe_event`, etc. These values are still used by the current monologue system (D-035). Named NPC examples in descriptions are incidental. | Already in use; clean up named NPC examples from descriptions only |
| `server/content/global/enums/topics.yaml` | Dialogue topic types. The enum values themselves are still relevant for NPC conversation routing. Named NPC examples in descriptions are incidental. | Already in use; clean up named NPC examples from descriptions only |
| `server/content/global/enums/motivations.yaml` | NPC functional motivation archetypes: HANDLER, OPERATOR, PERIPHERAL, OBSERVER, UNKNOWN. These role-archetypes map directly to zone-type role pools and could seed generator role taxonomy. | Zone-type role archetype vocabulary |
| `server/content/global/enums/access-tiers.yaml` | Access tier definitions (public/private/restricted/secure/classified). The tier system is still used by the knowledge graph. Named NPC examples in tier descriptions can be removed. | Already in use; strip named NPC examples |
| `server/content/global/enums/patterns.yaml` | NPC personality pattern types. Useful for zone-type culture profiles. | Zone-type culture profile generator |
| `server/content/global/enums/situations.yaml` | Situation types for NPC behavioral context. Useful for zone-type activity schemas. | Zone-type activity/situation vocabulary |
| `server/content/global/enums/activities.yaml` | Activity types used in daily routine generation. Still referenced by the current DailyRoutine system. | Already in use |
| `server/content/global/enums/moods.yaml` | Mood type enum. Still used by MoodState system. | Already in use |
| `server/content/global/enums/trust-tiers.yaml` | Trust tier definitions (0–10 scale with named tiers). Still used by RelationshipGraph trust levels. | Already in use |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/templates/smuggling-ring.yaml` | Social site template structure: capacity, roles, operational notes. The YAML schema maps to the RON `ZoneTypeTemplate.social_site_types` structure (D-142). Worth porting as a reference for `rural_agricultural.ron` social site entries. | RON zone-type social_site_types pattern |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/templates/bar.yaml` | Bar social site template. Same as above — schema maps to D-142 structure. | RON zone-type social_site_types for bar/hospitality zones |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/templates/logistics-hub.yaml` | Logistics hub template. Useful reference for `industrial_freight.ron` social site types. | RON zone-type social_site_types for industrial zones |
| `server/content/global/factions/concord-assembly.yaml` | Faction structure definition. Faction identifiers, cultural values, and institutional roles are usable as zone-type culture profile ingredients. | Zone-type culture profile vocabulary (6 files) |
| `server/content/global/factions/guardians-of-autonomy.yaml` | Same as above | Same |
| `server/content/global/factions/syndics.yaml` | Same as above | Same |
| `server/content/global/factions/the-ring.yaml` | Same as above | Same |
| `server/content/global/factions/the-unbound.yaml` | Same as above | Same |
| `server/content/global/factions/veil-institute.yaml` | Same as above | Same |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/environmental/the-terminal.yaml` | Environmental text for The Terminal logistics hub. 1 detective reference; the rest is location flavor text, signage, and readable objects. The environmental text schema is a useful template for zone-type flavor text pools. | Zone-type environmental text schema |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/environmental/maintenance-corridors.yaml` | Environmental text for maintenance corridors. No named NPC references. Pure location flavor. The schema (signs, terminals, documents, graffiti) maps to zone-type flavor text. | Zone-type environmental text schema |
---
## Already-superseded
These files were authored before the RON zone-type system. The zone-type RON files (`server/content/global/zone-types/`) and the D-142 `ZoneTypeTemplate` struct now serve the same purpose with better generator integration. Disposition: **delete** after confirming no Rust code still loads them.
| File | Superseded by |
|------|--------------|
| `server/data/templates/dock-worker.yaml` | Role definitions in `ZoneTypeTemplate.roles` within RON zone-type files |
| `server/data/templates/logistics-hub.yaml` | Social site definitions in RON zone-type files |
| `server/data/templates/terminal-social-site.yaml` | Social site definitions in RON zone-type files |
| `server/data/templates/terminal-triangle-01.yaml` | Triangle definitions will move to RON format via #663 |
**Edge case:** verify with `grep -r "data/templates" server/src/` that no Rust code still loads these paths before deletion. The `generator_spike.rs` binary uses `content/global/` paths, not `data/templates/`.
---
## Infrastructure — no action required
These files are active infrastructure, not deprecated v0.1 content.
| File(s) | Status |
|---------|--------|
| `server/content/gauntlet/` (4 files) | Test world specifications — active, do not touch |
| `server/content/schemas/drama_module.schema.yaml` | JSON schema for drama modules — may be reusable if drama module format is retained |
| `server/content/content.yaml` | Server content manifest — active |
| `project.yaml` | Project metadata — active |
| `client/data/dialogue-theme.yaml` | Client UI theming — active |
| `client/data/ui-strings.yaml` | Client UI microcopy — active |
| `server/content/campaigns/main/campaign.yaml` | Campaign metadata (structural) — active |
| `server/content/campaigns/main/systems/van-maanens-star/system.yaml` | Geographic hierarchy — active |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/station.yaml` | Geographic hierarchy — active |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/district.yaml` | Geographic hierarchy — active |
| `server/content/campaigns/main/systems/van-maanens-star/stations/sova/districts/transit/locations/` (5 files) | Location definitions for Sova Transit — active world geography |
---
## Recommended disposition priority
1. **Immediate:** Strip named NPC examples from descriptions in `enums/triggers.yaml`, `enums/topics.yaml`, `enums/access-tiers.yaml` (these are actively used, the named examples create false impressions about the current system).
2. **Before v0.2 content sprint:** Convert social site template YAMLs (bar, logistics-hub, smuggling-ring) to inform RON `ZoneTypeTemplate.social_site_types` entries. The schemas align closely.
3. **v0.2 content sprint:** Archive `deprecated` files (move, don't delete — the named NPC narrative design remains valuable as reference material for future hand-authored arcs).
4. **After #663 lands:** Verify `data/templates/` files are unreferenced, then delete.
5. **After #664 lands:** Remove `npc-conversations/overheard.yaml` (already not served; #664 replaces it).
Reference in New Issue View Git Blame Copy Permalink