interactive-story/planning

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:

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

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.