Update planning package after Phase 0B

2026-09-01 20:41:23 -04:00
parent ba737de9b4
commit 717670afe0
34 changed files with 2061 additions and 1204 deletions
@@ -0,0 +1,93 @@
+# ADR 009 — AI-DnD Is the Production Base
+
+**Status:** Accepted  
+**Date:** 2026-09-01
+
+## Decision
+
+Use AI-DnD as the production fork/base, pinned initially to upstream commit:
+
+```text
+d72f7c1bda0f34fccd84afb7a25c34eb01c901de
+```
+
+AI-DnD is the ownership center for the production codebase.
+
+Other candidate projects remain implementation references only unless a later explicit decision authorizes compatible code reuse.
+
+## Context
+
+Phase 0A favored AI-DnD because it appeared to contain the most difficult correctness infrastructure. Phase 0B then cloned, built, tested, and exercised the three finalists with local Ollama and targeted experiments.
+
+Phase 0B corrected one major assumption: AI-DnD's shipped Undo hard-deletes history and there is no Redo. A disposable follow-up spike demonstrated that the architecture can support non-destructive head-cursor Undo/Redo with a bounded change while retaining alternate history and branch-scoped memory isolation.
+
+AI-DnD also demonstrated:
+
+- browser UI and FastAPI backend,
+- SQLite persistence,
+- story-tree/lineage machinery,
+- alternate takes,
+- branch switching,
+- per-node state snapshots,
+- local Ollama operation,
+- branch-scoped memory with local embeddings,
+- prompt/context inspection,
+- streaming,
+- export/import foundation,
+- substantial automated regression coverage,
+- ability to run without RPG scenario state.
+
+Open Dungeon would require a foundational history/persistence/summary rewrite with no existing automated test foundation. ai-adventure has the strongest state/privacy core but would require building most of the browser product around it.
+
+## Alternatives Considered
+
+- fork Open Dungeon,
+- use ai-adventure as the core and build browser/API layers,
+- build a new application shell,
+- continue repository-selection research.
+
+## Reason
+
+AI-DnD minimizes the amount of high-risk correctness infrastructure that must be invented while providing the browser/service/test foundation the target product needs.
+
+The remaining work is substantial but is more bounded and testable than the alternatives.
+
+## Consequences
+
+Retain or adapt from AI-DnD:
+
+- React/Vite browser application,
+- FastAPI service boundary,
+- SQLite and migration foundation,
+- story tree and lineage queries,
+- alternate takes,
+- state snapshot pattern,
+- local Ollama integration,
+- Memory Bank concepts and branch scoping,
+- Insights/context snapshots,
+- SSE streaming,
+- export/import framework,
+- relevant automated tests.
+
+Remove or replace:
+
+- hosted/multi-user/auth/demo functionality,
+- analytics,
+- Postgres/Neon/Render paths,
+- cloud model providers,
+- QuickJS/campaign scripting,
+- AI-Dungeon compatibility not needed by the product,
+- RPG-specific presentation and relative-delta state mechanics,
+- runtime remote fonts/assets,
+- first-use remote tokenizer dependency.
+
+Reimplement selected patterns from references:
+
+- ai-adventure: typed state events, validation/commit discipline, checkpoints/head movement, replay/privacy patterns,
+- Open Dungeon: focused story UX and future local-media interaction ideas,
+- Chronicler/IFF: authority/trust concepts,
+- Gamentic: provider-neutral optional media boundary.
+
+## Non-Decision
+
+This ADR does not authorize production coding by itself. Implementation begins only after the revised planning package is approved and a milestone-specific prompt is prepared.