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,155 @@
+# Adventure Storyteller Planning Package
+
+This package contains the current product requirements, provisional architecture, Phase 0 research, detailed subsystem designs, acceptance tests, and the Codex Phase 0B validation handoff for the local-only interactive-story project.
+
+## Current Status
+
+Phase 0A static research is complete.
+
+The project is now ready for **Phase 0B local validation** of the three finalists:
+
+1. AI-DnD
+2. Open Dungeon
+3. ai-adventure
+
+**Do not begin production implementation yet.**
+
+The purpose of Phase 0B is to validate the fork/base decision and resolve the remaining architecture questions with real builds, tests, offline runs, and tightly scoped experiments.
+
+## Document Authority
+
+Use the documents in this order when requirements appear to conflict:
+
+1. `SPECIFICATION.md` — product requirements and desired behavior.
+2. Detailed design/behavior documents listed below — elaborations of the specification.
+3. `V1-ACCEPTANCE-TESTS.md` — observable pass/fail interpretation of v1 requirements.
+4. `TECHNICAL-DESIGN.md` — provisional implementation direction, subject to Phase 0B findings.
+5. Phase 0A reports — research evidence and candidate analysis.
+6. `BUILD-MILESTONES.md` — intentionally incomplete until the fork/architecture decision is made.
+
+The detailed design documents describe target behavior; they do not force a particular repository schema when an equivalent implementation satisfies the behavior.
+
+## Recommended Reading Order for Codex
+
+### A. Product and architectural intent
+
+1. `SPECIFICATION.md`
+2. `DATA-MODEL.md`
+3. `STORY-BRANCH-SEMANTICS.md`
+4. `CONTEXT-AND-MEMORY.md`
+5. `IMPORTED-KNOWLEDGE-DESIGN.md`
+6. `SECURITY-THREAT-MODEL.md`
+7. `MEDIA-EXTENSION-CONTRACT.md`
+8. `BROWSER-UX-SPEC.md`
+
+### B. Test contract
+
+9. `TEST-CAMPAIGN-FIXTURE.md`
+10. `V1-ACCEPTANCE-TESTS.md`
+
+### C. Provisional architecture and research
+
+11. `TECHNICAL-DESIGN.md`
+12. `RESEARCH-PLAN.md`
+13. `reports/PHASE-0A-STATUS.md`
+14. `reports/PRELIMINARY-RECOMMENDATION.md`
+15. `reports/REUSE-MATRIX.md`
+16. Candidate-specific reports in `reports/`
+
+### D. Execute
+
+17. `PHASE-0B-CODEX-HANDOFF.md`
+
+## Core Product Decisions Already Settled
+
+The Phase 0B investigation should treat these as requirements rather than questions:
+
+- browser-first UI,
+- local-only v1 runtime,
+- local Ollama inference,
+- application-owned authoritative story state,
+- complete retained transcript,
+- simple user-facing Undo/Redo/Retry/Save Point semantics,
+- non-destructive internal lineage,
+- abandoned history retained but marked disposable; cleanup later,
+- at least five Undo operations; unlimited preferred if technically straightforward,
+- Redo and Retry supported,
+- named checkpoints retained until explicitly deleted,
+- genre-agnostic core schema,
+- imported knowledge classes: Canon / Reference / Inspiration,
+- local retrieval and embeddings,
+- prompt/context provenance and inspection,
+- no cloud inference, telemetry, automatic web retrieval, remote runtime assets, shell/MCP/general plugin execution,
+- future local image/video/TTS/STT capability must remain possible without coupling it to the core story engine.
+
+## Detailed Documents
+
+- `DATA-MODEL.md` — conceptual target data model and authority/state structures.
+- `STORY-BRANCH-SEMANTICS.md` — exact Undo, Redo, Retry, Edit, checkpoint, restore, and disposable-history behavior.
+- `CONTEXT-AND-MEMORY.md` — context construction, authority hierarchy, summaries, memory, retrieval, provenance, token budgeting.
+- `IMPORTED-KNOWLEDGE-DESIGN.md` — import, classification, chunking, local indexing, retrieval, provenance, isolation, and prompt-injection handling.
+- `SECURITY-THREAT-MODEL.md` — local trust boundary, network policy, untrusted input handling, browser security, and offline acceptance.
+- `MEDIA-EXTENSION-CONTRACT.md` — future image, video, audio, TTS, and STT extension boundaries. Media remains optional and derived from story state.
+- `BROWSER-UX-SPEC.md` — user-facing browser workflow and advanced inspection surfaces.
+- `TEST-CAMPAIGN-FIXTURE.md` — deterministic campaign fixture for comparing candidates and later regression testing.
+- `V1-ACCEPTANCE-TESTS.md` — black-box requirements and release gate.
+
+## Phase 0A Research
+
+Static repository research was completed on 2026-09-01.
+
+Key reports:
+
+- `reports/PHASE-0A-STATUS.md`
+- `reports/PRELIMINARY-RECOMMENDATION.md`
+- `reports/REUSE-MATRIX.md`
+- `reports/AI-DND-ANALYSIS.md`
+- `reports/OPEN-DUNGEON-ANALYSIS.md`
+- `reports/AI-ADVENTURE-ANALYSIS.md`
+- `reports/PRIVACY-STATIC-ANALYSIS.md`
+- `reports/LICENSING-REUSE.md`
+- `reports/SOURCE-INDEX.md`
+
+Current preliminary architecture hypothesis:
+
+```text
+AI-DnD production base
+  + ai-adventure trust/commit/privacy rules
+  + Open Dungeon scene/media UX patterns
+  + Chronicler memory authority tiers
+  + Interactive Fiction Framework Story Bible authority/validation
+  + Gamentic media-provider abstraction
+```
+
+This is a hypothesis to test, not a fork decision.
+
+## Overall Workflow
+
+```text
+Specification + detailed behavioral designs
+        |
+        v
+Phase 0A static research
+        |
+        v
+Phase 0B local validation
+        |
+        v
+Fork / architecture decision
+        |
+        v
+SPECIFICATION v1.0
+TECHNICAL-DESIGN v1.0
+        |
+        v
+Detailed BUILD-MILESTONES.md
+        |
+        v
+Production implementation
+```
+
+## Important Stop Rule
+
+Phase 0B ends with evidence and a recommendation.
+
+Codex should **not** begin production coding, repo conversion, or broad feature implementation until the Phase 0B results have been reviewed and the production base has been selected.