Add initial planning files from ChatGPT research here

2026-09-01 12:09:38 -04:00
commit f011362494
37 changed files with 14601 additions and 0 deletions
@@ -0,0 +1,578 @@
+# Adventure Storyteller — Phase 0 Research Plan
+
+**Status:** Ready for execution  
+**Phase:** 0 — Research, Validation & Architecture  
+**Goal:** Determine what to build, what to fork/reuse, and finalize the technical design before production implementation begins.
+
+## 1. Why Phase 0 Exists
+
+The project has several promising open-source starting points. They differ substantially in:
+
+- browser UX,
+- persistence model,
+- branching semantics,
+- long-term memory,
+- local knowledge retrieval,
+- Ollama support,
+- dependency footprint,
+- privacy/network behavior,
+- game-specific assumptions,
+- licensing,
+- test quality.
+
+A detailed production milestone plan written before inspecting the code would rely on guesses.
+
+Phase 0 therefore ends when we can answer:
+
+> What exact codebase and architecture should be used for the production storyteller?
+
+No production feature work should begin before that decision unless explicitly authorized.
+
+## 2. Candidate Repositories
+
+Initial candidates:
+
+1. **Open Dungeon**
+   - Repository: `newideas99/open-dungeon`
+   - Interest: browser-first interactive-fiction UX, Ollama, SQLite.
+
+2. **AI-DnD**
+   - Repository: `parththakkar106/AI-DnD`
+   - Interest: browser UI, story tree, rollback, memory, story cards, prompt inspection.
+
+3. **Local Adventure Engine / ai-adventure**
+   - Repository: `CaoRuiming/ai-adventure`
+   - Interest: append-only state, checkpoints, branching, privacy-focused architecture, deterministic replay.
+
+4. **aiMultiFool**
+   - Repository: exact upstream URL to be confirmed during inventory.
+   - Interest: local semantic memory/RAG and context inspection.
+
+Reference projects:
+
+- SillyTavern
+- RisuAI
+- KoboldAI
+- Chronicler
+- other credible projects discovered during Phase 0.
+
+## 3. Research Workspace
+
+Create a dedicated workspace such as:
+
+```text
+adventure-storyteller-research/
+├── candidates/
+│   ├── open-dungeon/
+│   ├── ai-dnd/
+│   ├── ai-adventure/
+│   └── aimultifool/
+├── notes/
+├── experiments/
+├── reports/
+└── inventory/
+```
+
+Do not copy source code from one project into another during initial analysis.
+
+Each candidate should remain a clean upstream clone or worktree.
+
+Record:
+
+- upstream URL,
+- upstream default branch,
+- commit SHA examined,
+- release/tag if applicable,
+- clone date,
+- license,
+- language/framework,
+- build tooling,
+- runtime services,
+- expected local ports.
+
+## 4. Phase Rules
+
+During Phase 0:
+
+- do not begin production feature development,
+- do not merge candidate codebases,
+- do not remove features from candidate repos,
+- do not commit speculative refactors,
+- small disposable experiments are allowed,
+- experiments must be isolated and clearly documented,
+- candidate repos should remain easy to reset to upstream,
+- every conclusion should cite observed code/config/test behavior.
+
+## 5. Milestone R0 — Research Workspace and Inventory
+
+### Objective
+
+Create the research environment and establish a reproducible inventory of all candidates.
+
+### Tasks
+
+- create the research workspace,
+- clone all initial candidates,
+- record exact upstream commits,
+- locate and record licenses,
+- inventory languages/frameworks,
+- inventory package managers,
+- inventory database/storage dependencies,
+- inventory model/provider dependencies,
+- inventory frontend/backend separation,
+- record build/run instructions,
+- identify existing tests,
+- identify documentation directories,
+- identify migrations/schema definitions,
+- identify obvious telemetry/cloud integrations.
+
+### Deliverables
+
+- `inventory/candidates.md`
+- `inventory/licenses.md`
+- `inventory/dependencies.md`
+- `inventory/build-instructions.md`
+- machine-readable candidate metadata if useful.
+
+### Exit Criteria
+
+All serious candidates are locally available and reproducibly identified.
+
+## 6. Milestone R1 — Build and Run Candidates
+
+### Objective
+
+Verify actual behavior rather than relying on README claims.
+
+### Tasks
+
+For each serious candidate:
+
+- install dependencies,
+- build successfully where applicable,
+- start locally,
+- create a minimal story,
+- confirm persistence after restart,
+- test Ollama directly where supported,
+- identify how model configuration works,
+- record application ports,
+- identify data locations,
+- inspect browser developer/network activity for unexpected outbound requests where applicable,
+- record startup failures or undocumented requirements.
+
+For projects not supporting Ollama:
+
+- determine adapter/interface boundary,
+- do not yet permanently modify the project.
+
+### Deliverables
+
+Per candidate:
+
+```text
+reports/runtime-<candidate>.md
+```
+
+Include:
+
+- exact commands,
+- success/failure,
+- screenshots only if useful,
+- local services used,
+- observed storage files,
+- observed network activity,
+- known blockers.
+
+### Exit Criteria
+
+Each serious candidate has either been run successfully or has a documented reason it cannot reasonably be evaluated.
+
+## 7. Milestone R2 — Source Architecture Review
+
+### Objective
+
+Understand how each candidate actually works internally.
+
+### Review Areas
+
+#### Browser/UI
+- framework,
+- state management,
+- streaming,
+- transcript representation,
+- campaign navigation,
+- edit/retry behavior,
+- extensibility for future media.
+
+#### Backend/service layer
+- routing/API design,
+- model invocation boundary,
+- background jobs,
+- validation boundaries.
+
+#### Persistence
+- database type,
+- schema,
+- migrations,
+- turn representation,
+- snapshots,
+- event log,
+- transactions,
+- branch representation.
+
+#### Story history
+- linear vs tree,
+- retry semantics,
+- undo semantics,
+- destructive vs non-destructive restore,
+- branch naming/navigation.
+
+#### Context
+- prompt assembly,
+- recent history,
+- summaries,
+- token budgeting,
+- author notes/system rules.
+
+#### Memory
+- summaries,
+- vector retrieval,
+- keyword retrieval,
+- entity state,
+- old-turn retrieval.
+
+#### Lore/knowledge
+- import formats,
+- chunking,
+- story cards/world info,
+- semantic retrieval,
+- provenance.
+
+#### Tests
+- unit tests,
+- integration tests,
+- migration tests,
+- model mocks,
+- coverage of state/rollback.
+
+### Deliverables
+
+- `reports/architecture-open-dungeon.md`
+- `reports/architecture-ai-dnd.md`
+- `reports/architecture-ai-adventure.md`
+- `reports/architecture-aimultifool.md`
+- `reports/architecture-comparison.md`
+
+### Exit Criteria
+
+We can explain each candidate's architecture without relying on marketing descriptions.
+
+## 8. Milestone R3 — Privacy and Network Review
+
+### Objective
+
+Determine what must be removed, disabled, or isolated to satisfy the local-only requirement.
+
+### Search For
+
+- OpenAI,
+- OpenRouter,
+- Groq,
+- Anthropic,
+- Google,
+- cloud inference,
+- telemetry,
+- analytics,
+- Sentry,
+- PostHog,
+- crash reporting,
+- CDN,
+- Google Fonts,
+- remote image hosts,
+- automatic update checks,
+- remote database support,
+- URL retrieval,
+- external web search,
+- MCP,
+- plugins,
+- arbitrary executable scripts,
+- third-party auth.
+
+### Tasks
+
+- static source search,
+- dependency review,
+- environment-variable review,
+- runtime network observation,
+- identify outbound requests required vs optional,
+- identify localhost vs wildcard binds,
+- identify stored secrets/API keys,
+- identify browser-side remote resources.
+
+### Deliverables
+
+- `reports/privacy-network-review.md`
+- per-candidate removal/mitigation list.
+
+### Exit Criteria
+
+For each candidate, we can state exactly what local-only hardening would be required.
+
+## 9. Milestone R4 — Feature and Reuse Matrix
+
+### Objective
+
+Compare candidates by subsystem rather than declaring one project the winner prematurely.
+
+### Compare
+
+- browser UX,
+- Ollama adapter,
+- streaming,
+- SQLite schema,
+- story tree,
+- rollback,
+- checkpoints,
+- edit/retry semantics,
+- state extraction,
+- entity/world state,
+- summaries,
+- semantic memory,
+- lexical memory,
+- lore/story cards,
+- source imports,
+- prompt inspection,
+- export/import,
+- tests,
+- local-only posture,
+- media extensibility.
+
+### Rate Each Feature
+
+Use categories such as:
+
+- Keep as-is
+- Keep with modification
+- Reuse concept only
+- Replace
+- Not present
+- Not wanted
+
+### Deliverables
+
+- `reports/reuse-matrix.md`
+
+### Exit Criteria
+
+We know which candidate has the best implementation of each required subsystem.
+
+## 10. Milestone R5 — Licensing and Code-Reuse Review
+
+### Objective
+
+Determine what code can legally be copied, modified, linked, or used only as inspiration.
+
+### Tasks
+
+- verify repository licenses at the exact commits reviewed,
+- note third-party code with separate licenses,
+- note generated/vendor code,
+- compare compatibility if combining code from multiple projects,
+- pay special attention to GPL/copyleft candidates,
+- distinguish:
+  - direct code reuse,
+  - dependency use,
+  - architecture inspiration,
+  - protocol/API reimplementation.
+
+### Deliverables
+
+- `reports/licensing-reuse.md`
+
+### Exit Criteria
+
+The recommended architecture does not rely on legally ambiguous code mixing.
+
+## 11. Milestone R6 — Critical Prototypes
+
+### Objective
+
+Test only the uncertainties that could change the architecture decision.
+
+Possible experiments include:
+
+### Experiment A — Ollama adapter for ai-adventure
+Determine how difficult it is to replace/extend the LM Studio adapter with Ollama.
+
+### Experiment B — Branch-safe state in Open Dungeon
+Determine whether Open Dungeon's current persistence can support immutable branch parentage without invasive rewrite.
+
+### Experiment C — Strip-down feasibility in AI-DnD
+Identify whether RPG/cloud systems are modular enough to remove without destabilizing core story-tree/memory behavior.
+
+### Experiment D — Local semantic retrieval
+Test a minimal local embedding pipeline using Ollama and a local-only store.
+
+### Experiment E — Scene extraction
+Verify that the narrator/state pipeline can produce a neutral scene packet suitable for future media.
+
+Only run experiments that resolve a documented decision.
+
+### Deliverables
+
+Each experiment:
+
+```text
+experiments/<name>/README.md
+```
+
+Record:
+
+- question,
+- hypothesis,
+- minimal changes,
+- result,
+- implications,
+- whether code should be discarded.
+
+### Exit Criteria
+
+No high-impact fork/architecture decision remains based solely on speculation.
+
+## 12. Milestone R7 — Fork / Build Decision
+
+### Objective
+
+Select the production starting strategy.
+
+### Required Options to Evaluate
+
+- fork Open Dungeon,
+- fork AI-DnD,
+- fork/use ai-adventure core,
+- clean new shell with reused permissive components,
+- other candidate if discovered.
+
+### Decision Criteria
+
+Weight heavily:
+
+1. fit with interactive-story product,
+2. browser-first architecture,
+3. Ollama fit,
+4. state/branch correctness,
+5. local-only hardening effort,
+6. amount of code to remove,
+7. maintainability,
+8. licensing,
+9. test quality,
+10. future media extensibility.
+
+### Deliverables
+
+- `reports/fork-build-recommendation.md`
+- ADR documenting the selected strategy.
+
+### Exit Criteria
+
+One strategy is approved as the production base.
+
+## 13. Milestone R8 — Finalize Specification and Technical Design
+
+### Objective
+
+Convert assumptions into committed decisions.
+
+### Tasks
+
+Update:
+
+- `SPECIFICATION.md`
+- `TECHNICAL-DESIGN.md`
+
+Resolve:
+
+- base repository,
+- frontend framework,
+- backend framework,
+- storage model,
+- branch/state model,
+- model adapter,
+- memory/retrieval strategy,
+- local knowledge design,
+- import formats for v1,
+- context budgeting strategy,
+- security boundaries,
+- export format,
+- future media interfaces,
+- test strategy.
+
+Mark documents v1.0 when approved.
+
+### Deliverables
+
+- `SPECIFICATION.md` v1.0
+- `TECHNICAL-DESIGN.md` v1.0
+- relevant ADRs.
+
+### Exit Criteria
+
+A developer can explain the final architecture without unresolved foundational choices.
+
+## 14. Milestone R9 — Create Production Build Plan
+
+### Objective
+
+Write the detailed implementation milestone plan only after the technical design is stable.
+
+### Tasks
+
+Create:
+
+- `BUILD-MILESTONES.md`
+
+It must include:
+
+- milestone dependencies,
+- exact intended outcomes,
+- acceptance criteria,
+- test expectations,
+- migration steps from selected upstream,
+- removal/hardening work,
+- v1 feature sequence,
+- definition of done.
+
+### Exit Criteria
+
+The build plan is specific enough to hand directly to Codex milestone-by-milestone.
+
+## 15. Phase 0 Final Deliverables
+
+At Phase 0 completion:
+
+```text
+SPECIFICATION.md             v1.0
+TECHNICAL-DESIGN.md          v1.0
+RESEARCH-PLAN.md             completed
+BUILD-MILESTONES.md          production-ready
+DECISIONS/                   finalized foundational ADRs
+reports/                     research evidence
+experiments/                 critical prototype evidence
+inventory/                   candidate metadata
+```
+
+## 16. Phase 0 Definition of Done
+
+Phase 0 is complete only when:
+
+- candidate repositories have been cloned and reviewed,
+- serious candidates have been run or ruled out with evidence,
+- network/privacy behavior is documented,
+- licensing is understood,
+- critical architectural uncertainties have been tested,
+- a fork/build strategy has been selected,
+- the specification is v1.0,
+- the technical design is v1.0,
+- the actual implementation milestone plan has been written.
+
+At that point, production implementation can begin.