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).