ROADMAP.md

# Reality Divergence — v2 Roadmap

The hackathon build is intentionally lean: two explicit tabs, schema-driven
generation, validation + fallbacks, and one atmospheric image per result. This
document parks the larger **routed, schema-driven architecture** as the post-
hackathon direction. Nothing here is required for the current submission.

## Guiding idea

Move from "two fixed tabs" to a **router → policy gate → prompt picker →
structured generation → validation → renderer** pipeline. Routing is decided in
*code*, never by the model picking its own route.

## Where we already are (≈55% of the target)

| Target capability | Status |
|---|---|
| Schema-driven structured generation | ✅ done (`prompts.py` + parsing in `app.py`) |
| Per-intent output schemas | ✅ done (timeline ≈ reflection; world ≈ alt-history/fork) |
| Validation + never-crash fallback | ✅ done (`safe_int/str/list`, curated fallbacks) |
| Timeline / branch renderer | ✅ done (HTML spine, better/worse, winners/losers) |
| Safety guardrail (personal tab) | ✅ done (risk gate + 988 notice) |
| Uncertainty framing | 🟡 in prompts + a "speculative" badge; no per-claim tagging |
| Prompt picker | 🟡 by tab, not by router (2 routes, not 9) |
| Intent router + confidence + clarification | ❌ not built |
| Tone/mode selectors, confidence indicator | ❌ not built |
| Streaming staged output | ❌ not built |
| Conversational follow-up (turn-taking) | 🟡 reflection question shown statically |

## v2 backlog (priority order)

1. **Intent router** — one lightweight model (or rules) call classifying input into
   a taxonomy: `personal_regret`, `alternate_history`, `event_counterfactual`,
   `global_shock`, `regional_disaster`, `civilizational_fork`, `comparison`,
   `creative_weird`, `mixed`. Returns `primary_intent`, `secondary_intents`,
   `confidence`, `needs_clarification`, `divergence_scale`, `tone`, `image_policy`.
2. **Policy gate** — below a confidence threshold (~0.72) ask one clarifying
   question instead of generating; decide allowed output type.
3. **Per-claim epistemic tagging** — tag statements `certain | speculative |
   assumption`; render badges; downgrade tone when the model is over-confident.
4. **Image policy** — generate images only for `creative_weird` / explicit visual
   requests, not for reflective/uncertain output. (Current build always shows one
   decorative banner — revisit.)
5. **Single prompt box + mode/tone selectors + confidence indicator** to replace
   the two-tab split.
6. **Streaming** the response in stages (intent → structure → text → timeline →
   image) so it feels fast.
7. **Retry-once on schema-validation failure** before falling back.
8. **Strict validation** via Pydantic/JSON-schema instead of the current `safe_*`
   coercion.

## Known design tensions to decide in v2

- **Images:** v2 spec says default-off, artifact-only. Current build shows one
  text-free atmospheric banner per result (decorative, not informational).
- **Visual style:** v2 spec favors restraint ("no chaotic gradients, reflective
  instrument"). Current build uses an animated gradient hero for impact.

## Reference

Architecture spec drafted from the Build Small field guide constraints and a
prompt-routing / structured-output design pass (June 2026).