# Story Planner

IdleSpectator commits to short multi-beat stories instead of channel-surfing ranked tips.

Feeds, sticky ensembles, presentability, and `InterestDirector` stay in place.
`StoryPlanner` sits above the director and owns *which story* the next 30–90s belongs to.

See also: [scoring-model.md](scoring-model.md), [event-reason.md](event-reason.md).

## Pipeline

```text
Feeds → InterestRegistry → StoryPlanner (boost / inject)
       → InterestVariety.Pick → InterestDirector → CameraDirector
```

Director still owns camera, sticky maintain, and switch margins.
Planner never calls `MoveCamera`.

## Arc model

| Kind | Climax | Hard hold |
|------|--------|-----------|
| CombatDuel | sticky pair | only notable pairs (2+ notables) |
| CombatMass | Skirmish+ | yes |
| WarFront / Plot / Love / Grief | existing sticky / life | yes |

Phases: `Climax → Aftermath → Epilogue → Done`.

- **Aftermath** injects on climax cold (quiet grace), or claims natural `death_*` grief.
- **Epilogue** once after aftermath if a living lover/friend resolves.
- Soft anonymous duels still get aftermath tips; they do not use raised `arcHoldMargin`.

## Selection discipline

- `InterestVariety.Pick` takes `#1` when score gap ≥ `story.nearTieEpsilon` (default 8).
- Near-ties still roll among top-3.
- Causal heat + Character Ledger heat add into `RecalcTotal`.

## Knobs

`scoring-model.json` → `story` block (loaded by `InterestScoringConfig.Story`).

Catalog policy ids live under `event-catalog.json` → `story`
(`aftermath_survivor`, `aftermath_mourner`, `aftermath_war_linger`, …).

## Harness

| Scenario | Proves |
|----------|--------|
| `story_aftermath_combat` | duel cold → aftermath tip |
| `story_aftermath_war` | war sticky cold → aftermath |
| `story_near_tie` | large gap always picks #1 |
| `story_arc_combat` | climax → aftermath ownership |
| `story_arc_preempt_resume` | epic cut then fresh scrap aftermath |
| `story_ledger_revisit` | featured unit wins near-tie |

```bash
./scripts/harness-run.sh --repeat 3 story_aftermath_combat
./scripts/harness-run.sh --repeat 3 story_near_tie
./scripts/harness-run.sh --repeat 3 story_arc_combat
./scripts/harness-run.sh --repeat 3 story_ledger_revisit
```

## Files

- `IdleSpectator/Story/StoryPlanner.cs` - ownership, cold-hook, inject
- `IdleSpectator/Story/CausalHeat.cs` - decaying cast heat
- `IdleSpectator/Story/CharacterLedger.cs` - watched lives (cap 16)
- `IdleSpectator/Story/StoryReason.cs` - presentable aftermath Labels