worldbox-observer-mod/docs/mc-story-director-rewrite-plan.md

# MC story director rewrite plan

## Status

Implementation complete. Story-first is the sole production camera path.

Checkpoint 1 (2026-07-22) is complete:

- Added semantic developments, character story state, durable threads, consequences, chapters,
  structured narrative beats, and episode models under `IdleSpectator/Narrative/`.
- Dual-write is live for bonds, children, friendship, death, kills, roles, founding, wars, and plots.
- Family/lineage, power, home, conflict, war, plot, and survival thread rule foundations exist.
- Structured relationship/child Beats can replace concatenated event prose.
- Narrative chapters take precedence over copied hard-arc prose in Legacy.
- The story scheduler runs in shadow mode and does not yet own the camera.
- World-session reset clears narrative state.
- Live NML compilation passes; `saga_legacy_quality`, `caption_character_beat`, and `settings_full`
  pass after the checkpoint.

Checkpoint 2 (2026-07-22) is complete:

- Episode shot proposals now select protagonist/cast/theater-related pending candidates.
- Explicit interrupt classes distinguish related escalation, story payoff, world-critical events,
  ordinary interesting events, and texture/noise.
- Ordinary unrelated events cannot interrupt a productive episode; critical events can.
- Bounded shadow telemetry compares proposed story shots with actual event-first selections.
- Actual camera switches feed the comparison trace without changing camera ownership.
- `narrative_scheduler_policy` covers related selection, concurrent-thread scoping, ordinary-event
  rejection, and world-critical interruption.

Checkpoint 3 (2026-07-22) is complete:

- `story_first_director` now grants the scheduler guarded camera-selection ownership.
- Scheduler choices are made only from candidates already admitted by the director's liveness,
  ownership, presentability, completion, cooldown, and switch-safety filters.
- Episodes retain their thread across ordinary events and critical interruptions.
- Payoff episodes settle, stale episodes expire, and normal world coverage resumes instead of
  starving the camera when no related development appears.
- A new development on the same thread reopens its information goal.
- Recently resolved threads remain schedulable briefly so outcomes and consequences can be shown.
- `narrative_camera_cutover` proves a lower-strength related development wins over an unrelated
  event, then yields to a world-critical interrupt through the real director selection path.
- The feature remains disabled by default pending longer enabled-mode soak coverage.

Checkpoint 4 (2026-07-22) is complete:

- Story potential now decays over time and supplies a bounded, scan-free challenger lane into the
  MC roster. An ordinary living character can enter as `EmergingStory` once coherent developments
  produce enough momentum.
- Effective roster interest includes a capped story-potential component, so current narrative
  movement competes with office, fame, favorites, and manual preference without replacing them.
- `NarrativeFunctionPolicy` classifies candidates as texture, world context, opener, development,
  escalation, turning point, resolution, or consequence independently of spectacle strength.
- Episode shot scoring and interrupt policy consume that classification. Noise cannot become an
  episode shot merely by touching the cast; character texture does not interrupt unrelated stories.
- Telemetry distinguishes related proposals, critical proposals, and related versus unrelated actual
  cuts. `narrative_story_inputs` proves emerging-MC admission and semantic classification, while
  `narrative_story_first_soak` exercises real enabled camera ownership and continuity assertions.

Checkpoint 5 (2026-07-22) is complete:

- Every candidate is stamped at the single registry intake boundary with a durable narrative
  function and its provenance: exact catalog mapping, typed structural rule, or compatibility
  fallback. Downstream selection no longer has to reinterpret labels repeatedly.
- The initial explicit catalog covers relationship, lineage, war, plot, combat, disaster, political,
  loss, aftermath, milestone, and everyday texture events. Dynamic theaters retain typed structural
  mappings.
- Coverage telemetry records unique candidates and their function distribution. A 20-second natural
  enabled-mode soak typed 74 of 79 observed candidates through catalog or structural rules (94%).
- Natural telemetry exposed cast-related routine behavior being mislabeled as escalation. The policy
  now treats noise and character texture as non-progress even when they touch the active cast.
- Scheduler telemetry also samples whether the camera is already aligned with the active episode,
  covering the common case where a development opens a thread after its camera cut. The tuned natural
  soak recorded 38 aligned samples and zero unaligned samples without manufacturing extra cuts.
- `narrative_catalog_policy` and `narrative_natural_soak` are part of the regression scenario list.
  The catalog policy, natural soak, scheduler policy, camera cutover, synthetic enabled soak, Legacy
  quality, and settings compatibility scenarios pass after the tuning.

Checkpoint 6 (2026-07-22) is complete:

- A harness-only force flag now runs every compatibility scenario with story-first camera ownership,
  while the shipped default remains guarded. Narrative state is cleared between scenario batches.
- The deterministic multi-thread stress covers initial selection, retention against a competitor,
  critical interruption, return to the interrupted episode, abandonment, and handoff to the next
  thread.
- Episode-related developments can reclaim the camera from ordinary unrelated material after a
  short settling beat. Live fights, crises, payoffs, and other explicitly protected continuity still
  finish their immediate outcome.
- Episodes without presentable footage no longer reserve an empty camera slot; normal ambient
  selection remains available until a related shot exists.
- Orange-reason telemetry is cleared when scene ownership ends, preventing a stale duel/event label
  from surviving an ambient focus handoff.
- WorldLog feeds retain an explicitly supplied event participant even when the vanilla asset hides
  its follow-location UI, fixing the missing `disaster_alien_invasion` candidate.
- The full forced story-first regression passes 19/19 scenarios. The live-event pipeline reports no
  failed authored cases, and the presentability scenario passes all 65 assertions.
- Three final 20-second natural soaks observed 265, 173, and 119 unique candidates. Catalog or
  structural typing covered 98%, 96%, and 100%; compatibility fallback accounted for 6, 7, and 0.
  Camera health passed in all runs. True unaligned samples were 1, 0, and 1, with critical/payoff
  interruptions reported separately instead of being mislabeled as drift.

Checkpoint 7 (2026-07-22) is complete:

- A five-minute story-first soak and five-minute event-first baseline ran against the same developed
  world. Both modes remained presentable: neither produced bad camera state, placeholder prose,
  subject/reason mismatch, sleep lag, or object-focus failures.
- Story-first produced 33 authored camera reasons versus 14 for event-first and accumulated 48
  narrative facts for the recurring lead versus 33 in the baseline. The story-first run revisited
  relationships and a family ensemble, and three repeated encounters earned a rivalry; the
  event-first baseline did not earn one.
- The comparison exposed a remaining biography defect rather than a camera defect: repeated kills
  could still appear as several independent `Slew ...` Legacy lines. Legacy now consolidates two or
  more confirmed kills into one dated repeated-clashes chapter while preserving a separately earned
  rivalry chapter.
- `saga_legacy_combat_summary` proves that three kill facts render as one combat summary with no raw
  kill lines. Existing `saga_legacy_quality` coverage still passes all 43 checks.
- Story-first camera ownership is now the shipped default. `story_first_director` remains available
  as an explicit event-first opt-out during the rollback window.
- The complete default-on release regression passes 19/19 scenarios, including all 65
  presentability assertions and the live-event pipeline.

Checkpoint 8 (2026-07-23) is complete:

- The first extended organic default-on session produced 333 authored cuts and 593 healthy focus
  samples with no bad focus state, placeholder, object-focus failure, fight/focus mismatch, or
  sleeping/fighting caption lag. One unpresentable candidate was rejected before selection.
- The session demonstrated genuine recurring leads: Zagatze and Xe Ze appeared in 51 and 54
  authored reasons, with repeated encounters, aftermath, relationship, family, and leadership
  material. Story-first continuity is therefore surviving beyond synthetic and five-minute tests.
- The same evidence exposed an editorial pacing defect. Combat occupied 157 of 333 cuts (47%),
  including 92 duel cards, and unchanged combat phases, family-pack cards, and generic
  `seeks ... after the story` epilogues repeated too freely.
- Identical sticky combat, war, plot, outbreak, family-pack, and synthetic-story cards now receive
  a short editorial replay cooldown after selection. A distinct opponent or changed card remains
  eligible, and ordinary moment beats retain their existing cooldown policy.
- The old generic related-character epilogue is no longer synthesized while story-first owns the
  camera; the structured narrative thread already carries that consequence. Event-first retains
  the closer only as rollback compatibility.
- A two-minute post-tuning natural sample passed with 11 cuts, no camera/prose failures, no generic
  related epilogue, two duel cuts, and four multi-unit combat cuts. One battlefield card returned
  after intervening developments rather than as an immediate replay.
- `narrative_editorial_replay`, scheduler policy, combat-story, and multi-thread stress scenarios
  pass. The complete forced story-first regression still passes 19/19 scenarios, including all 65
  presentability assertions.

Rejected comparison window (2026-07-23):

- The attempted second extended soak was not a directed spectator session. Idle Spectator first
  became active at log line 360 of 397, after roughly 91% of the captured window had already
  elapsed, and produced only five authored cuts before shutdown.
- Those active cuts were healthy, but the sample is too small to support a pacing or rollback
  decision. The fallback path remains in place.
- The soak-audit tool now reports idle-mode True/False samples and the location of the first active
  state, and explicitly flags windows where Idle Spectator activated late.

Checkpoint 9 (2026-07-23) is complete:

- A valid five-minute default-on sample produced 36 authored cuts and 54 healthy active/focus
  samples. It had no bad camera state, unpresentable selection, placeholder prose,
  subject/reason mismatch, or sleeping/fighting caption lag.
- Relationship material rose to 9 of 36 cuts and repeatedly returned to parenthood, children,
  partners, grief, pregnancy, and gifts. Norron and Tampoo received developments across multiple
  life stages rather than isolated notifications.
- The replay guard worked: the generic after-story closer did not return, and exact sticky-card
  repetition was limited to an ongoing combat phase after intervening cuts.
- Combat nevertheless occupied 17 of 36 cuts (47%). The closing sequence followed Iraum through
  six consecutive combat cards against distinct opponents, revealing episode saturation that an
  exact-card replay guard cannot address.
- Each narrative episode now has a budget of three routine combat shots. A confirmed meaningful
  development resets the budget, non-combat developments remain eligible, and decisive combat
  with event strength 95 or higher may exceed the budget so the director does not miss a climax.
- The scheduler probe proves saturated routine combat is rejected while critical combat and
  non-combat developments remain eligible. Narrative scheduler, multi-thread stress, editorial
  replay, and combat-story scenarios pass.
- The complete forced story-first regression passes 19/19 scenarios. Normal default-on
  story-first configuration was restored after the run.

Checkpoint 10 (2026-07-23) completes the cutover:

- The ten-minute post-budget organic release soak produced 53 authored cuts and 107 healthy
  active/focus samples. It had zero bad camera states, placeholder tips, object-focus failures,
  fight/focus mismatches, or sleeping/fighting caption lag.
- Combat fell from 47% in both earlier extended samples to 11 of 53 cuts (20.8%), comfortably under
  the 35% release target. The longest uninterrupted combat run was two cuts.
- The same sample retained world coverage and recurring life stories. Waf, Waaf, and Woof returned
  through love, companionship, reproduction, mating, pregnancy, and children alongside adulthood,
  founding, leadership, plague, discovery, and decisive combat outcomes.
- The runtime `story_first_director` and `narrative_shadow` flags and their harness override were
  removed. The scheduler now has first ownership on every selection pass; bounded ambient/world
  selection remains only when no episode owns a usable development.
- The synthetic related-character epilogue implementation was deleted. Narrative threads are the
  only continuation owner.
- Hard-arc headline-to-memory writes and combat-spectacle MC admission were removed. Ordinary
  characters now enter the ensemble through confirmed narrative momentum rather than prolonged
  theater exposure.
- Obsolete `CausalHeat` scoring, scanner bias, and lifecycle writes were removed. Narrative episode
  relation, story potential, and the MC roster provide the remaining intentional continuity bias.
- The soak audit now reports combat share, maximum combat run, relationship count, and unique-tip
  coverage; a sample with at least 20 cuts fails the editorial gate above 35% combat.
- The final cleaned build compiles in NML. Camera cutover, scheduler, multi-thread, replay, natural
  story, roster replacement, and role-stake targets pass, followed by a complete 19/19 regression.
- A final five-minute soak after deleting causal heat and hard-arc admission produced 35 cuts and
  59 healthy active/focus samples with no camera or prose failures. Active combat was 4 of 35
  (11.4%) with a maximum run of one, while Theangaldar progressed from reproduction intent through
  pregnancy, child, parenthood, and death and Aethamred progressed from courtship through love and
  pregnancy.

The rollback window is closed. Story-first is the sole production path and all eight implementation
phases have passed their exit gates.

This plan supersedes the existing event-first story direction as the product target. Existing
story documents remain useful implementation history, but they are not constraints on this
rewrite.

## Product vision

IdleSpectator follows the developing lives of a small cast of main characters. The camera may
leave them for world-changing spectacle, but it should return because their circumstances have
changed, not merely because they remain important or recently appeared.

At a glance, the player should understand:

1. **Whose life are we following?**
2. **What changed for them just now?**
3. **What unresolved question or pressure does that change belong to?**
4. **What lasting consequence did earlier events have on their life?**

The intended experience is closer to an automatically edited ensemble chronicle than a ranked
event feed.

## Product contract

### Story-first selection

The primary director decision is:

> Which new development best advances a life or relationship the player is following?

It is not:

> Which isolated event currently has the highest spectacle score?

Event strength remains valuable for urgency and interrupts. It is no longer the primary model of
narrative value.

### Evidence-first narration

The system may infer narrative structure from confirmed observations, but it must not invent facts.
It may say that a war threatens a character when that character, their family, city, or kingdom is
observably involved. It may not claim fear, intent, causation, victory, succession, or grief without
supporting evidence.

### Consequences over notifications

Prefer state transitions and outcomes over repeated intent or activity:

- `Found love with Omyale` over `is seeking a lover` once love is confirmed.
- `Welcomed a first child with Omyale` over `gains a child · their child`.
- `Survived the fall of Super Pumpkin` over `Super Pumpkin (84) vs The Godo (46)`.
- `Lost Ylhofne during the war` over two unrelated Legacy fragments.

### Coherent episodes, not camera lock

The director commits to a developing thread long enough to establish context and show a meaningful
change. Related cast and theater shots are valid parts of that episode. Urgent world events can cut
in, but ordinary unrelated events should not continually reset the story.

### Biography, not archived UI copy

Legacy is synthesized from structured, character-perspective consequences. Orange reasons,
scoreboards, camera labels, and internal story headlines must never be copied directly into Legacy.

## Rewrite boundary

### Preserve

- Game observation patches and feeds that detect real events.
- `EventOutcome` / observation confirmation rules.
- Live actor, relationship, war, plot, status, and ensemble inspection.
- Camera movement, focus repair, hold mechanics, and presentability checks.
- The current Identity, Beat, Context, Cast, and Legacy UI surfaces.
- Chronicle as the complete historical journal.
- Existing event catalog as an observation/prose source while migration is underway.
- Useful deterministic harness infrastructure.

### Replace or substantially reshape

- Global event-candidate ranking as the main narrative decision.
- `StoryArc` as the primary story representation.
- Climax-first `Climax -> Aftermath -> Epilogue` planning.
- Heat as a substitute for story continuity.
- Hard-arc camera headlines stored as life facts.
- Legacy selection as recent facts from diverse enum buckets.
- Caption enrichment based on concatenating independently authored strings.
- MC admission based mainly on role, spectacle, and recent feature heat.

### Compatibility during migration

The old director remains available behind a configuration flag until the new path passes the story
quality gates. Both paths may consume the same observations, but only one path owns camera selection
at a time.

## Target architecture

```text
Game observations
      |
      v
Confirmed semantic developments
      |                    \
      v                     -> Chronicle journal
Character state + relationships
      |
      v
Durable narrative threads
      |
      v
Story scheduler -> episode plan -> shot selector -> camera
      |                               |
      v                               v
Beat + Context                    live focus
      |
      v
Consequences -> chapters -> Legacy
```

The critical inversion is that observations update story state before the director chooses what to
show. Camera selection consumes that story state instead of attempting to manufacture continuity
after a global event candidate wins.

## Core domain model

### NarrativeDevelopment

A typed, evidence-backed state change emitted by observation adapters.

Suggested fields:

```text
Id
Kind
OccurredAt / WorldDate
SubjectId
OtherIds
Place / City / Kingdom / Family / War / Plot ids
PreviousState
NewState
Outcome
Magnitude
Confidence
EvidenceSource
CorrelationKeys
Presentability
```

Examples:

- Bond formed or broken
- Child born, including parent perspectives
- Role gained or lost
- Home founded, gained, lost, or destroyed
- War joined, left, won, lost, or survived
- Plot joined, exposed, completed, or failed
- Rival encounter, escalation, defeat, or death
- Transformation, infection, cure, mutation, or species extinction pressure
- Meaningful combat outcome
- Death and its observed effects on connected lives

This model records meaning, not final English.

### CharacterStoryState

Durable state for every character with story evidence, whether or not they currently occupy the
visible roster.

Suggested fields:

```text
CharacterId
Identity snapshot
Current roles and affiliations
Living relationships
OpenThreadIds
ResolvedThreadIds
RecentDevelopmentIds
ConsequenceIds
StoryMomentum
StoryPotential
LastMeaningfulChangeAt
```

Memory must survive roster churn. Joining the roster affects presentation and scheduling priority,
not whether a life can accumulate a coherent history.

### NarrativeThread

A durable unresolved question involving a protagonist and supporting cast.

Suggested fields:

```text
ThreadId
ThreadKind
ProtagonistId
CastIds with roles
Anchor ids
OpenedByDevelopmentId
CurrentPhase
CentralQuestion
Pressure / stakes evidence
DevelopmentIds
LatestMeaningfulChangeId
Momentum
Urgency
Coherence
Novelty
CoverageDebt
Status: Emerging | Active | Dormant | Resolved | Abandoned
Resolution
```

Initial thread kinds:

| Family | Power | Conflict | Survival | Journey |
|---|---|---|---|---|
| Courtship | Rise to rule | Rivalry | Transformation | Founding |
| Partnership | Reign | Revenge | Outbreak | Migration |
| Lineage | Succession | War involvement | Last of kind | Exile/home loss |
| Separation/grief | Plot/betrayal | Personal combat | Recovery | Return/homecoming |

Thread kinds should be extended from observed play, not from a goal of catalog completeness.

### Narrative phase

Use phases that describe development rather than camera mechanics:

```text
Setup -> Pressure -> Escalation -> TurningPoint -> Outcome -> Consequence
```

Phases may be skipped. A thread can become dormant in any unresolved phase. A resolution requires
an observed outcome; timeout alone makes a thread dormant or abandoned, not resolved.

### CharacterConsequence

A durable character-perspective result suitable for later chapter synthesis.

Suggested fields:

```text
CharacterId
ThreadId
DevelopmentId
ConsequenceKind
Role in event
OtherIds
Before / after state
Outcome confidence
Importance
WorldDate
```

Examples from the same battle may differ per character:

- Defender: `Defended Super Pumpkin against The Godo`.
- Survivor: `Survived the fall of Super Pumpkin`.
- Bereaved partner: `Lost Ylhofne during the war`.
- Attacker: `Helped The Godo defeat Super Pumpkin`.

Only emit the most specific statement supported by evidence.

### EpisodePlan

A temporary editorial commitment to one thread.

Suggested fields:

```text
ThreadId
ProtagonistId
EligibleCastIds
EligibleTheater
EntryDevelopmentId
Purpose: Establish | Develop | Payoff | Consequence | Reintroduce
MinimumInformationGoal
StartedAt
CoverageState
InterruptState
```

An episode ends because its information goal was met, its subject became unavailable, the thread
went dormant, or a stronger story requires the camera. It should not end solely because a fixed
dwell timer expired.

### NarrativeBeatModel

Structured presentation model shared by orange Beat and muted Context.

Suggested fields:

```text
PerspectiveCharacterId
DevelopmentId
ThreadId
ActionKind
OtherIds and relationship roles
Change
Outcome
ThreadPhase
ContextEvidence
Confidence
```

The prose renderer receives this model and decides what information belongs in Identity, Beat, and
Context. It must perform semantic deduplication before producing strings.

## Story scheduler

### Thread scoring

Score stories, not raw events. Initial factors:

- New meaningful change
- Approaching or confirmed payoff
- Existing player preference
- MC or emerging-MC involvement
- Unresolved pressure
- Repeated cast and relationship continuity
- Cross-MC interaction
- Coverage debt
- Visual presentability
- Urgency
- Recent overexposure penalty
- Dormancy and stale-evidence penalty

Raw spectacle affects urgency and interrupt eligibility. It should not automatically make a weakly
connected event a better story than a meaningful development in an established life.

### Episode entry

An episode may begin when:

- A new thread opens with sufficient story potential.
- An active thread receives a meaningful development.
- A thread reaches a turning point, outcome, or consequence.
- A preferred character returns with genuinely new information.
- A dormant thread becomes active again.

Do not begin an episode for repeated attempts, ordinary maintenance activity, or an unchanged live
state unless it is an establishing shot needed for an imminent payoff.

### Shot selection inside an episode

Eligible shots include:

- The protagonist performing or receiving the development.
- A directly involved supporting character.
- The relevant family, city, kingdom, war front, plot cell, or disaster theater.
- A short grounding shot that establishes the protagonist before a payoff.
- A consequence shot after a confirmed outcome.

Every shot must be able to answer why it belongs to the active episode.

### Interrupts

Define explicit interrupt classes:

- **World critical:** major disaster, kingdom destruction, huge war turning point. May interrupt.
- **Story payoff:** another high-priority thread resolves. Usually may interrupt.
- **Related escalation:** belongs to active protagonist/cast. Fold into the episode.
- **Ordinary interesting event:** queue or ignore while the episode remains productive.
- **Texture/noise:** never interrupts.

After an interrupt, resume only if the previous thread still has an unmet information goal or a new
development. Do not resume because an old score or heat value remains high.

### World coverage

The system must still make the world feel alive. Maintain a coverage budget rather than globally
ranking every event against every character beat:

- Most time follows active MC stories.
- Some time introduces emerging lives.
- A bounded share shows world context and critical spectacle.
- Quiet time grounds characters or advances low-intensity threads.

Exact shares and episode durations are tuning outcomes, not hard-coded product requirements.

## MC roster redesign

Keep the visible roster at ten unless UI testing suggests otherwise, but separate roster membership
from active narrative attention.

### Cohorts

- **Active ensemble:** a small set of lives with strong current story momentum.
- **Roster:** visible noteworthy lives with durable importance or story history.
- **Emerging:** off-roster lives accumulating a coherent thread.
- **Preferred:** explicit player preference; strong scheduling prior, not an absolute camera lock.

### Story potential

Calculate story potential from:

- Strength and number of unresolved threads
- Recent meaningful state changes
- Recurring cast and relationships
- Proximity to a turning point or outcome
- Cross-MC connections
- Reversal or contrast in life trajectory
- Distinctiveness from the current ensemble
- Existing coherent history

Role, renown, kills, rarity, and favorite status remain useful standing signals. They should not be
the only reliable route into the cast.

### Admission and retirement

- Admit emerging characters because a thread is developing, not because a spectacle lasted long
  enough.
- Retain a life while it has an active thread, strong unresolved consequence, player preference, or
  durable historical importance.
- Allow dormant characters to rotate out without deleting story memory.
- Reintroduce them with concise context when a thread reactivates.

## Orange Beat and Context

### Ownership

- **Identity:** who this is now.
- **Beat:** the confirmed development occurring now.
- **Context:** the unresolved question, pressure, or consequence that makes the Beat matter.

### Prose rules

1. Render from `NarrativeBeatModel`, not directly from `InterestCandidate.Label`.
2. Choose one perspective character before writing.
3. Prefer outcomes and state changes over intent.
4. Do not repeat a relationship already expressed by the Beat.
5. Do not repeat a title or role already expressed by Identity.
6. Do not repeat the same fact in Context.
7. Use names when they distinguish the relationship or stakes.
8. Omit Context when no supported, useful context exists.
9. Never expose raw asset ids, enum values, correlation keys, or internal phase names.
10. Never upgrade uncertainty into fact.

### Example transformations

| Observation | Weak presentation | Target presentation |
|---|---|---|
| Child added | `Gains a child, Omyale · their child` | `Welcomes a child, Omyale` |
| First child confirmed | same | `Welcomes a first child, Omyale` |
| Child continues threatened lineage | same | Beat: `Welcomes Omyale`; Context: `Their lineage continues` |
| Battle begins | `A (84) vs B (46)` | Beat may retain theater framing while live |
| Settlement later falls | same line in Legacy | `Survived the fall of A` when supported |
| Lover dies during war | `Lost Ylhofne` | `Lost Ylhofne during the war` when correlated |

The renderer should choose natural grammar for species and reproduction mode where known. The table
describes information structure, not a single universal English template.

## Legacy redesign

### Chapter synthesis

Legacy is a short biography assembled from consequences, not a list of event records. Related
developments may collapse into one chapter.

Example:

```text
Joon 145 · Fell in love with Ylhofne
Joon 152 · Lost Ylhofne during the war with The Godo
Meow 145 · Survived the fall of Super Pumpkin
Meow 161 · Founded a new home in Northreach
```

### Selection priorities

Rank candidate chapters by:

1. Confirmed lasting consequence
2. Identity or affiliation change
3. Relationship change
4. Personal role and specificity
5. Causal importance to later chapters
6. Resolution
7. Narrative diversity
8. Recency as a tie-breaker, not the primary rule

### Consolidation

Consolidate when developments share a thread and the later event supplies a clearer consequence:

- Courtship + bond formed -> one relationship beginning.
- Repeated fights + credible rivalry -> one rivalry chapter.
- War joined + settlement destroyed + survival -> one war consequence when space is limited.
- Multiple children -> first notable child plus a lineage summary where useful.

### Exclusions

Never place these directly in Legacy:

- Live scoreboards or side counts
- `A vs B` theater headlines without a personal outcome
- Internal story phase names
- Repeated intents
- Routine activity
- Current state already fully expressed by Identity or Cast
- An unresolved claim worded as a completed achievement

## Event catalog reclassification

Catalog completeness remains useful for observation coverage. Add narrative function independently
from camera strength:

```text
ThreadOpener
Development
Escalation
TurningPoint
Resolution
Consequence
CharacterTexture
WorldContext
Noise
```

Each emitted development also declares whether it changes state. Repeated observations that do not
change state may refresh liveness but must not create new chapters or story momentum.

Initial policy pass should focus on the event classes that produce most visible narrative value:

1. Relationships, children, family, and death
2. Leadership, founding, succession, and home loss
3. War, plots, rivalry, and personal combat outcomes
4. Transformation, disease, mutation, and recovery
5. Books, traits, items, and other identity texture
6. World spectacle and ambient events

Do not rewrite every catalog string before the structured pipeline proves useful.

## Implementation phases

### Phase 0 - Baseline and story-quality instrumentation

Build measurements before changing selection.

Deliverables:

- A soak trace that records camera shots, selected subject, active thread, episode purpose,
  development id, interrupt reason, Beat, Context, and resulting chapter.
- Baseline metrics from the current director.
- Deterministic multi-event life scenarios.
- A feature flag for `event_first` versus `story_first` selection.

Required scenarios:

- Courtship -> bond -> child -> separation/death
- Nobody -> founder -> leader -> home loss
- Repeated opponents -> credible rivalry -> decisive outcome
- War join -> settlement destruction -> survivor consequence
- Transformation/infection -> crisis -> cure or death
- Two simultaneous MC threads plus a world-critical interrupt

Exit gate: the current system has a reproducible narrative-quality baseline.

### Phase 1 - Semantic development layer

Introduce `NarrativeDevelopment` and adapters from existing confirmed feeds.

Deliverables:

- Stable typed development ids and correlations.
- Subject, other, theater, before/after state, outcome, and confidence.
- Idempotency for repeated observations.
- Dual-write to existing memory and the new story store.
- Debug dump showing raw observation -> development.

Start with relationship, birth, death, role, founding/home, war, plot, and combat outcome events.

Exit gate: deterministic scenarios produce correct developments without changing camera behavior.

### Phase 2 - Character state, consequences, and chapter synthesis

Build the durable character-centric memory before changing the director.

Deliverables:

- `CharacterStoryState` store independent of roster membership.
- `CharacterConsequence` creation from confirmed developments.
- Thread-aware chapter consolidation.
- New Legacy builder behind a presentation flag.
- Migration or graceful fallback for existing session memory.

Exit gate:

- No scoreboard/theater-only line appears in new Legacy.
- Each displayed line has a character role and supported consequence.
- Related facts consolidate without losing important names or outcomes.
- The supplied child and battle examples render without duplication or archived scoreboard prose.

### Phase 3 - Narrative threads

Create and update durable threads from developments.

Deliverables:

- Thread open/update/dormant/resolve rules.
- Protagonist and cast-role assignment.
- Phase transitions based on developments.
- Central-question and pressure evidence models.
- Multiple simultaneous threads per character.
- Thread merge/split rules for overlapping war, rivalry, family, and grief evidence.
- Thread debug board visible to the harness.

Exit gate:

- Threads persist across unrelated events and roster churn.
- Timeout cannot falsely resolve a thread.
- Concurrent threads do not steal developments from one another.
- Every phase change cites its triggering development.

### Phase 4 - Structured Beat and Context prose

Replace string concatenation with `NarrativeBeatModel` rendering.

Deliverables:

- Perspective selection.
- Semantic redundancy checks.
- Beat renderer by development class.
- Context renderer from active thread pressure/question.
- Honest fallbacks when only partial evidence exists.
- Existing Identity and status-banner behavior retained.

Exit gate:

- No `child ... · their child`-style duplication.
- Beat, Context, and Identity never repeat the same semantic fact.
- No raw ids or internal terms appear.
- Prose remains correct when camera focus is a supporting cast member.

### Phase 5 - Story scheduler in shadow mode

Run the new scheduler without giving it camera ownership.

Deliverables:

- Thread scoring and episode proposal.
- Episode information goals.
- Explicit interrupt classification.
- Proposed-shot trace compared with actual event-first shots.
- Story-potential scoring for active, roster, and emerging characters.

Exit gate: offline/shadow traces demonstrate higher continuity and payoff coverage without hiding
world-critical events.

### Phase 6 - Story-first camera ownership

Enable the new scheduler behind the feature flag.

Deliverables:

- Episode selection and lifecycle.
- Shot selection within the active story.
- World-critical interrupt and evidence-based resume behavior.
- Quiet-time grounding shots.
- Old `InterestDirector` camera mechanics reused through a narrower shot request interface.
- Only one camera-selection owner at runtime.

Exit gate:

- The camera remains on causally related material through an episode.
- Ordinary unrelated events do not thrash the story.
- Critical events still cut in promptly.
- Resume occurs only for an unmet goal or new development.
- Focus and orange prose always describe the same perspective.

### Phase 7 - MC roster and event-policy retuning

Retune admission and observation policy after story-first selection is working.

Deliverables:

- Story-potential and momentum-driven emerging admission.
- Active ensemble separate from the ten-slot roster.
- Thread-aware retirement and reintroduction.
- Narrative-function classification for high-value event families.
- Reduced camera eligibility for texture/noise that does not change state.

Exit gate: ordinary characters with coherent developing lives can become MCs without first becoming
leaders or prolonged combat spectacles.

### Phase 8 - Cutover and deletion (complete)

Remove the compatibility core only after the new director passes the release gate.

Delete or simplify:

- Story ownership paths whose only purpose was manufacturing continuity after event selection.
- Hard-arc headline-to-memory recording.
- Obsolete causal heat and roster bias used only by event-first ranking.
- Redundant prose paths.
- Old feature flag after a stable soak period.

Retain event strength where it still models urgency, visual value, or interrupt class.

Exit gate: story-first is the sole production path, with no dual ownership or duplicate memory
writes.

## Proposed module layout

Names are provisional; responsibilities are the important part.

```text
IdleSpectator/Narrative/
  NarrativeDevelopment.cs
  NarrativeDevelopmentRouter.cs
  CharacterStoryState.cs
  CharacterStoryStore.cs
  NarrativeThread.cs
  NarrativeThreadStore.cs
  ThreadRules/
    FamilyThreadRules.cs
    PowerThreadRules.cs
    ConflictThreadRules.cs
    SurvivalThreadRules.cs
    JourneyThreadRules.cs
  CharacterConsequence.cs
  ChapterSynthesizer.cs
  StoryPotential.cs
  StoryScheduler.cs
  EpisodePlan.cs
  EpisodeShotSelector.cs
  InterruptPolicy.cs
  NarrativeBeatModel.cs
  NarrativeProse.cs
  NarrativeTelemetry.cs
```

Existing feed modules should call thin adapters or emit developments through the router. They should
not open threads, author chapters, or choose camera shots themselves.

## Quality metrics

Track metrics over deterministic runs and long soaks:

### Continuity

- Share of shots causally related to the active episode
- Unexplained cut rate
- Average useful developments per episode
- Episode abandonment rate
- Evidence-based resume rate

### Story coverage

- Setup-to-outcome coverage
- Turning points shown
- Consequences shown after outcomes
- Open high-potential threads never covered
- Emerging-character admission rate

### Prose

- Semantic duplication rate
- Beat/Context contradiction rate
- Perspective mismatch rate
- Raw-id/internal-term leakage
- Unsupported-claim rate

### Legacy

- Consequence-bearing line share
- Theater-only/scoreboard line count, target zero
- Duplicate chapter rate
- Relationship and identity change retention
- Chapter consolidation rate

### Camera health

- Empty or invalid focus rate
- Critical interrupt latency
- Thrash rate
- Unpresentable selected shot rate

Metrics guide tuning; they do not replace qualitative review of complete generated lives.

## Release gate

Story-first becomes the default only when all of the following are true:

1. Deterministic life scenarios produce coherent threads, shots, and Legacy chapters.
2. Multi-thread correlation tests show no cross-thread mutation.
3. No observed Legacy line is a copied scoreboard or generic theater headline.
4. Orange Beat and Context are semantically non-redundant.
5. Critical world events remain visible without ordinary-event thrashing.
6. A long soak shows the same MCs developing across multiple meaningful beats.
7. Emerging non-notable characters can become MCs through story momentum.
8. Camera focus, perspective, Beat, and Context remain aligned.
9. Unsupported narrative claims remain at zero in the audited scenarios.
10. Story-first wins side-by-side qualitative review against the event-first baseline.

## Risks and controls

### Over-narrating weak evidence

Control: every thread transition, context claim, and consequence cites development evidence and a
confidence policy. Prefer omission over invented motive or outcome.

### Staying too long on a dull story

Control: information goals, development freshness, dormancy, and coverage debt replace unconditional
holds. Episodes end when no new information remains.

### Missing the wider world

Control: explicit world-critical interrupts and a bounded world-context budget.

### Excessive special cases

Control: shared development, thread, consequence, and phase contracts. Thread-family rules specialize
only causal interpretation, not camera or UI ownership.

### Double systems becoming permanent

Control: define phase-8 deletion targets now. Dual-write and shadow scheduling are migration tools
with explicit exit gates.

### Performance on large worlds

Control: update threads from emitted developments rather than rescanning every actor. Amortize roster
discovery, cap active thread evaluation, and keep dormant histories indexed but cold.

## First vertical slice

Implement family/lineage as the first end-to-end slice because it exposes the current orange
duplication, requires relationship perspective, has clear state changes, and produces understandable
Legacy consequences without depending on combat scoring.

Scope:

1. Seeking is optional setup evidence, not a chapter.
2. Bond formation opens or advances a relationship thread.
3. Child birth emits parent- and child-perspective developments.
4. The renderer produces one non-redundant Beat.
5. Context can express first-child or lineage continuation only when supported.
6. Bond loss or death transforms/resolves the relationship thread.
7. Legacy consolidates the relationship into one or two meaningful chapters.
8. The scheduler shadows the current camera and proposes family episode shots.

Acceptance story:

```text
Character A seeks a partner.
A and B form a bond.
They have child C.
B dies during an observed war.
A survives and later forms a new home.
```

Expected results:

- The birth Beat names C once and identifies the relationship naturally.
- Context reflects a supported open pressure, not a generic slogan.
- B's death is correlated with the relationship and war when evidence permits.
- A's Legacy reads as a life sequence, not five independent event notifications.
- The proposed episode shots remain centered on A, B, C, and their relevant theater.

After this slice is sound, repeat the same architecture for founding/power and rivalry/war before
granting the scheduler camera ownership.

## Definition of done

The rewrite is complete when IdleSpectator can follow an initially ordinary character through
multiple causally connected changes, return to that life when something genuinely develops, explain
each selected beat without redundancy, and leave behind a short Legacy that reads as that
character's biography rather than a record of camera labels.