chapter-framework-and-story-sanitizer

name	chapter-framework-and-story-sanitizer
description	Add Bible story chapters with canon anchors and a sanitizer layer that cleans raw backend output for non-technical viewers
source	auto-skill
extracted_at	2026-05-30T17:30:00.000Z

Chapter Framework and Story Sanitizer

When building a Bible-inspired simulation for a non-technical audience (e.g., a family viewer), separate the raw simulation output from what the viewer sees. Use a chapter framework to structure the story and a sanitizer layer to clean all text before display.

Chapter Framework

Define chapters as data objects with these fields:

@dataclass
class Chapter:
    id: str                          # e.g., "garden_is_good"
    title: str                       # e.g., "The Garden Is Good"
    plain_language_summary: str      # Simple explanation for viewers
    what_this_means: str = ""        # One-sentence meaning for family viewers
    read_aloud_text: str = ""        # Clean paragraph for reading out loud
    canon_anchors: list[CanonAnchor] # Bible passages this chapter references
    allowed_simulation_events: list[str]  # What agents can do this chapter
    locked_events: list[str]         # Events that must NOT happen yet
    completion_conditions: list[str] # What advances to next chapter
    enabled: bool                    # True = active, False = locked for future

Chapter Progression

• Chapters 1-4 enabled (Garden → Adam → Eve → Boundary)
• Chapters 5-7 locked (Question → Choice → Expulsion)
• Progression based on tick milestones or event-based conditions
• get_current_chapter(tick, events) returns the active chapter

Locked Events

Each chapter defines events that must NOT occur yet:

locked_events = [
    "serpent temptation",
    "eating forbidden fruit",
    "hiding from God",
    "expulsion from Eden",
]

The consequence engine checks is_event_allowed(event_type, chapter) before processing.

Story Sanitizer Layer

Raw backend output contains technical artifacts that must never reach the family viewer:

[mock:Adam:197] Processing: You are Adam. Role: first huma...
Adam performs a mock action for tick 199.
Eve waits — live call limit reached.

The sanitizer cleans this to:

Adam is quiet in this moment. The garden remains peaceful.

Sanitizer Rules

1. Strip mock/provider prefixes: [mock:Adam:197], [nim-dry-run:...], [live-...]
2. Strip processing prefixes: Processing: You are Adam...
3. Detect technical phrases: "performs a mock action", "live call limit reached", "fallback to mock"
4. Replace with gentle language: "This moment is quiet. The garden remains peaceful."
5. Capitalize first letter of cleaned text

Sanitize Narrative

Strip event label prefixes from narratives:

narrative = re.sub(r'^\[(CANON_ANCHOR|INTERPRETIVE_BRIDGE|SIMULATION_EVENT)\]\s*Tick\s*\d+:\s*', '', narrative)

Family Viewer API Endpoint

Create a dedicated /api/mom/state endpoint that:

1. Gets current chapter from framework
2. Sanitizes all agent text through sanitizer
3. Sanitizes all event narratives
4. Returns chapter info (title, summary, canon anchors)
5. Returns sanitized Adam/Eve thoughts and actions
6. Returns sanitized recent events

Never return raw provider output, debug text, or technical artifacts through this endpoint.

Viewer Display

• Show chapter title and plain-language summary prominently
• Show Bible source references when available
• Use family-friendly labels: "Bible source" not "CANON_ANCHOR", "Interpretation" not "INTERPRETIVE_BRIDGE"
• Show "Moment" not "Tick" in the UI
• Default to showing 3 recent moments with "Show more" button

Key Principles

1. Two-layer cleaning: Sanitize in backend API AND in frontend JS
2. Gentle fallbacks: When no valid text exists, show peaceful garden language
3. Chapter context: Every viewer screen shows what chapter the story is in
4. Locked events stay locked: Chapters 5-7 cannot trigger until explicitly enabled
5. No raw text escapes: Test the viewer page for mock/provider prefixes before deploying

Chapter Content Guidelines

Write chapter content in warm, story-like language — not system status:

what_this_means

One or two sentences explaining the chapter's meaning in plain terms:

"Adam and Eve remember the one boundary in the garden. They may enjoy the garden freely, but one tree is set apart. For now, the boundary is respected and the garden remains peaceful."

read_aloud_text

A clean paragraph that can be read out loud to a family viewer:

"God had given Adam and Eve one rule. They could eat from any tree in the garden, but not from the tree of the knowledge of good and evil. They knew the boundary and respected it. The garden was full of good things, and they enjoyed them freely. The one tree stood apart, and they left it in peace. For now, the garden remained quiet and good."

Rules for chapter text:

• No theology arguments
• No technical words (tick, provider, model, API)
• No model/provider language
• Write like a story, not a system summary
• Keep it respectful and gentle