Adventure Storyteller Planning Package

Status: Phase 0 complete; architecture selected; Milestone M1 implemented and accepted (2026-09-02).
Production coding: Underway, milestone by milestone. M1 is done; M2 is the next milestone to brief.

This package contains the current product requirements, final Phase 0 architecture decisions, detailed subsystem designs, acceptance tests, research evidence, and the production milestone plan for the local-only interactive-story project.

Current Decision

Phase 0A static research and Phase 0B local validation are complete.

The production starting point is:

Fork AI-DnD at upstream commit d72f7c1bda0f34fccd84afb7a25c34eb01c901de.

The selection is based on measured Phase 0B behavior, not feature count. AI-DnD already contains the highest-value structural machinery: browser UI, FastAPI service boundary, SQLite persistence, parent-linked story history, alternate takes, branch-aware state snapshots, local Ollama operation, branch-scoped memory, prompt/context inspection, streaming, export/import, and a substantial automated test suite.

The selected composition of ideas is:

AI-DnD production base
  + ai-adventure state/event/commit/checkpoint/privacy patterns
  + Open Dungeon story-reading and future-media UX patterns
  + Chronicler memory-authority concepts
  + Interactive Fiction Framework canon/validation concepts
  + Gamentic provider-neutral media concepts

This is not a repository merge. AI-DnD is the ownership center. Other projects are implementation references only unless a later milestone explicitly reimplements a compatible idea.

Phase 0B Findings That Changed the Plan

Phase 0B confirmed the fork choice while correcting several Phase 0A assumptions:

AI-DnD's shipped Undo was destructive and had no Redo.
A disposable spike proved non-destructive head-cursor Undo/Redo in three backend files while preserving branch-scoped memory isolation.
A new continuation written after Undo can fork from the moved-back head while retaining the abandoned future.
AI-DnD's current relative-delta world-state protocol can produce semantically wrong state under realistic context even when the proposal is syntactically valid.
Production narrative state will therefore use explicit typed events/absolute assignments inspired by ai-adventure rather than AI-DnD's relative-delta protocol.
AI-DnD requires offline hardening: tiktoken attempts a first-use CDN fetch and the SPA requests Google Fonts at runtime.
AI-DnD's export format must preserve the active head position; otherwise export/import can silently redo an undone story.
AI-DnD Story Cards are not a sufficient imported-knowledge store because they are not designed for the required classification, provenance, chunking, and lineage semantics.
Open Dungeon remains useful for UX/media ideas but is no longer a serious production-fork candidate.
ai-adventure is not the production base but is the strongest implementation reference for authoritative typed state events, head movement, checkpoints, replay, and narrow local-only behavior.

See PHASE-0B-RECOMMENDATION.md for the coding agent's evidence. That report is retained as research evidence; the planning documents in this package record the decisions made after reviewing it.

Document Authority

Use the documents in this order when requirements appear to conflict:

SPECIFICATION.md — product requirements and required behavior.
Detailed behavior/design documents:
- STORY-BRANCH-SEMANTICS.md
- CONTEXT-AND-MEMORY.md
- IMPORTED-KNOWLEDGE-DESIGN.md
- SECURITY-THREAT-MODEL.md
- MEDIA-EXTENSION-CONTRACT.md
- BROWSER-UX-SPEC.md
- DATA-MODEL.md
V1-ACCEPTANCE-TESTS.md — observable pass/fail contract.
TECHNICAL-DESIGN.md — selected implementation architecture.
Foundational ADRs (001-...md through the current ADR set).
BUILD-MILESTONES.md — implementation sequence; it does not override product behavior.
Phase 0 research reports — evidence and historical findings.

Candidate repositories and research reports are not specifications. In particular, ai-adventure is an implementation reference for selected patterns; its behavior does not override this package.

Foundational Decisions

The following are settled for v1:

browser-first UI,
local-only runtime across user-controlled local infrastructure,
Ollama inference with same-host loopback as default and explicitly configured trusted-LAN inference supported,
single-user deployment,
AI-DnD production base at the pinned Phase 0B commit,
application-owned authoritative state,
complete retained transcript/history,
simple user-facing Undo/Redo/Retry/Save Point semantics,
non-destructive head-cursor history internally,
new write after moving backward creates a new continuation while retaining the old future,
abandoned history is retained and marked disposable; no automatic cleanup is required in v1,
named checkpoints remain until explicitly deleted,
genre-agnostic core state,
explicit typed narrative-state events/absolute assignments rather than ambiguous relative deltas,
hybrid state model: validated events plus state snapshots/cache,
branch/lineage-safe summaries and memories,
imported knowledge is a separate first-class subsystem rather than an extension of AI-DnD Story Cards,
knowledge classes: Canon / Reference / Inspiration,
local lexical retrieval plus local semantic retrieval where practical,
prompt/context provenance and inspection,
export/import must preserve active branch and active head position, including an undone position,
no cloud/Internet inference, telemetry, automatic web retrieval, remote runtime assets, shell/MCP/general plugin execution,
LAN inference is distinct from LAN exposure of the storyteller UI/API; the latter is not required for v1,
future local image/video/audio/TTS/STT support remains optional and decoupled from the story engine.

Phase 0 Status

Complete

candidate discovery and triage,
static architecture/privacy/licensing review,
local clone/build/test validation,
real Ollama testing,
offline/network observation,
AI-DnD strip-down/entanglement checks,
Open Dungeon history-retrofit analysis,
ai-adventure Ollama/service-boundary checks,
AI-DnD non-destructive Undo/Redo spike,
referee/state-protocol follow-up,
export/import head-position follow-up,
Story Card lineage review,
Postgres removability review,
production fork decision,
production architecture decision.

Deferred to implementation/release validation

These do not block the architecture decision:

comparative recommendation of narrator/state models for real users,
multi-hour/100-turn long-run behavior,
detailed concurrency behavior beyond the single-user turn lock,
actual future image/video/TTS/STT provider integration,
abandoned-history cleanup UI/policy (not required in v1).

Workflow From Here

Phase 0 research and spikes         COMPLETE
        |
        v
Architecture/fork decision         COMPLETE
        |
        v
Planning package revision          COMPLETE
        |
        v
Approve planning package           COMPLETE
        |
        v
Milestone M1                       COMPLETE (2026-09-02)
  fork + offline baseline          see planning/reports/M1-*.md
        |
        v
Milestone M2                       NEXT — brief not yet prepared
        |
        v
Implement and review milestone-by-milestone

Stop Rule

One milestone at a time. Do not begin a milestone before its brief exists.

M1 is complete and accepted; its evidence is in reports/M1-BASELINE-REPORT.md and reports/M1-IMPLEMENTATION-REPORT.md. No M2 brief has been prepared. The current action is to review the post-M1 planning corrections below before writing one.

Post-M1 corrections applied (2026-09-02)

Implementation evidence contradicted or under-specified six places in this package, and a seventh was added on review. All seven are now corrected:

Document	Correction
`DECISIONS/002-ollama-only-v1.md`	New section: a trusted-LAN Ollama may be HTTPS with a private CA; verify against the OS trust store; full certificate and hostname checking; no bypass option.
`DECISIONS/004-local-only-production.md`	New Testing Consequence: offline tests need a fresh cache and no route out. Vendored runtime artifacts should be integrity-verifiable.
`V1-ACCEPTANCE-TESTS.md` A05	Pass conditions reworded around accepted history; explicit note that the user's submitted text is deliberately retained.
`V1-ACCEPTANCE-TESTS.md` A06	Now requires a real second machine and an HTTPS endpoint with a locally issued certificate; a plain-HTTP LAN test is no longer sufficient evidence.
`V1-ACCEPTANCE-TESTS.md` §3	Record CPU/GPU/RAM: cold model load on a CPU-only host exceeded the inherited 120 s timeout.
`BUILD-MILESTONES.md`	M1 marked COMPLETE with the capabilities it delivered; M2's endpoint-policy line reframed from inventing trusted-LAN support to narrowing it.
`TECHNICAL-DESIGN.md` §5	Runtime boundary restated: the storyteller is loopback-only, inference may be same-host or trusted-LAN, and the two are independent. Adds the TLS/private-CA rule.

9.7 KiB Raw Permalink Blame History