552 lines
20 KiB
Markdown
552 lines
20 KiB
Markdown
# Adventure Storyteller — Production Build Milestones
|
|
|
|
**Status:** Planning-ready; implementation not yet authorized
|
|
**Base:** AI-DnD `d72f7c1bda0f34fccd84afb7a25c34eb01c901de`
|
|
|
|
## 1. Purpose
|
|
|
|
This document defines the production implementation sequence after Phase 0.
|
|
|
|
It is intentionally a milestone plan, **not a Codex execution prompt**. Each milestone should be converted into a separate coding brief only after the previous milestone has been reviewed and accepted.
|
|
|
|
The milestone order prioritizes load-bearing correctness and offline safety before broad feature work.
|
|
|
|
## 2. Global Rules for Every Milestone
|
|
|
|
Each implementation milestone must:
|
|
|
|
- preserve upstream provenance and licensing notices,
|
|
- keep the application runnable whenever practical,
|
|
- add or update automated tests for changed behavior,
|
|
- avoid unrelated refactors,
|
|
- update affected documentation,
|
|
- record schema/migration changes,
|
|
- preserve local-only defaults,
|
|
- stop at the milestone boundary for review,
|
|
- avoid implementing later milestones opportunistically.
|
|
|
|
The product specification and acceptance tests outrank convenience inherited from AI-DnD.
|
|
|
|
## 3. End-User Capability Progression
|
|
|
|
The application is expected to remain runnable throughout the sequence. **M8 does not create the browser UI from scratch**; AI-DnD already provides a browser interface from M1. M8 is where that inherited/adapted interface is completed and simplified into the intended v1 storyteller experience.
|
|
|
|
- **M1 — First playable baseline:** The user can open the inherited browser UI, start or resume a story, send prompts to Ollama, receive streamed narration, and persist the story across restart. The interface may still look and behave substantially like AI-DnD, and advanced history/state features are not yet converted to final semantics.
|
|
- **M2 — Clean local storyteller baseline:** Normal story play still works, but cloud/hosted/account/scripting surfaces are removed and Ollama can be either same-host or on an explicitly configured trusted-LAN machine. From the user's perspective this is still basic play, but the environment now matches the intended privacy/deployment model.
|
|
- **M3 — Safe history controls:** The user can play normally with production-grade Undo, Redo, Retry, alternate takes, and divergence without deleting old story history. Export/import also preserves the exact current position even when the user has undone several turns.
|
|
- **M4 — Save Points:** The user can name a point in the story, continue playing, restart, return to that Save Point, and take a different path without losing the later story. This is the first milestone where deliberate long-form experimentation/recovery should feel comfortable.
|
|
- **M5 — Reliable story state:** Characters, locations, possessions, relationships, facts, threads, and current scene become application-owned genre-neutral state rather than RPG-stat machinery. The user can begin inspecting/correcting what the storyteller believes, although the final polished state UI comes later.
|
|
- **M6 — Long-story memory:** The storyteller becomes much better suited to long campaigns because summaries and retrieved older memories remain branch-safe and inspectable. The user should be able to return to old people, promises, clues, and events without abandoned paths contaminating the active story.
|
|
- **M7 — Local knowledge library:** The user can import `.txt`/`.md` material as Canon, Reference, or Inspiration and have it retrieved locally with provenance. The functionality is usable, but some management/inspection surfaces may still be utilitarian until M8.
|
|
- **M8 — Finished v1 browser experience:** The existing browser UI is reorganized and polished around storytelling: streamlined campaign setup, transcript/input, Undo/Redo/Retry, Save Points, state, knowledge, context inspection, and model status. This milestone makes the product feel like the intended storyteller rather than an adapted AI-DnD application.
|
|
- **M9 — Portable/recoverable campaigns:** The user can reliably export, back up, import, and recover complete campaigns including history, Save Points, state, knowledge, and active position. This is where moving or restoring a campaign becomes a supported user workflow rather than merely an underlying capability.
|
|
- **M10 — Media-ready, still text-first:** Little or nothing visibly changes for normal play. The story/scene data and provider boundaries are prepared so image/video/audio/TTS/STT can be added later without redesigning the core application.
|
|
- **M11 — Release-quality v1:** The user experience should be functionally complete; this milestone proves it stays correct through long campaigns, repeated history operations, offline use, failures, export/import, and multiple genres. It is the release-validation milestone rather than a major new feature milestone.
|
|
|
|
---
|
|
|
|
# M1 — Establish Production Fork and Offline Baseline
|
|
|
|
## Objective
|
|
|
|
Create the production fork from the pinned AI-DnD commit and make ordinary local story operation genuinely offline-capable before larger changes.
|
|
|
|
## Scope
|
|
|
|
- establish production repository/fork lineage,
|
|
- record upstream commit and license provenance,
|
|
- establish reproducible dev/test environment,
|
|
- vendor/cache/replace the `tiktoken` first-use encoding dependency so story generation works without Internet,
|
|
- eliminate runtime Google Fonts/remote font dependency,
|
|
- tighten CSP for local runtime assets,
|
|
- verify same-host Ollama story generation with outbound Internet blocked,
|
|
- verify explicitly configured trusted-LAN Ollama story generation while the storyteller UI/API remains loopback-bound,
|
|
- establish baseline regression/test report.
|
|
|
|
## Explicit Non-Scope
|
|
|
|
- no history rewrite yet,
|
|
- no RPG-state redesign,
|
|
- no imported knowledge,
|
|
- no UI redesign,
|
|
- no media generation.
|
|
|
|
## Tests / Acceptance
|
|
|
|
Must demonstrate:
|
|
|
|
- A01-A06 as applicable to the inherited base, including the separate-host trusted-LAN inference path,
|
|
- H01-H03 and H11,
|
|
- no unexpected DNS/HTTP requests during ordinary story generation after setup,
|
|
- no remote font request,
|
|
- no tokenizer/BPE download on first production turn,
|
|
- existing relevant AI-DnD tests remain green except documented upstream/environment exceptions.
|
|
|
|
## Definition of Done
|
|
|
|
A clean production build can start, open the browser UI, generate and persist story turns through either same-host Ollama or an explicitly configured trusted-LAN Ollama host, restart, and resume with outbound Internet blocked. The storyteller UI/API remains loopback-bound by default.
|
|
|
|
---
|
|
|
|
# M2 — Remove Hosted, Cloud, Scripting, and Unneeded Deployment Surface
|
|
|
|
## Objective
|
|
|
|
Reduce AI-DnD to the intended single-user local product trust boundary without destabilizing the story/tree/memory foundation.
|
|
|
|
## Scope
|
|
|
|
Remove or isolate as appropriate:
|
|
|
|
- multi-user/account/guest/auth flows,
|
|
- demo API-key behavior,
|
|
- hosted analytics,
|
|
- Render/Neon deployment paths,
|
|
- Postgres/`psycopg` support,
|
|
- cloud providers not required by v1,
|
|
- arbitrary remote model-provider UI/configuration,
|
|
- QuickJS/campaign scripting,
|
|
- AI-Dungeon compatibility code that exists primarily to support scripting/hosted behavior,
|
|
- hosted-only rate-limit/account infrastructure.
|
|
|
|
Add:
|
|
|
|
- explicit Ollama endpoint policy: same-host loopback default plus user-configured trusted-LAN inference,
|
|
- clear local-model connection diagnostics,
|
|
- migration/test instrumentation replacements for any tests that depended on JS hooks or removed hosted paths.
|
|
|
|
## Explicit Non-Scope
|
|
|
|
- do not redesign story history,
|
|
- do not replace RPG state yet,
|
|
- do not build knowledge/media systems.
|
|
|
|
## Tests / Acceptance
|
|
|
|
- local story play still works,
|
|
- existing tree/retry/memory/context behavior remains intact,
|
|
- application requires no cloud API keys,
|
|
- approved trusted-LAN Ollama endpoints work while arbitrary public/Internet provider endpoints are rejected or absent from normal production configuration,
|
|
- removed provider/auth/analytics/scripting paths are no longer reachable from normal production configuration.
|
|
|
|
## Definition of Done
|
|
|
|
The codebase has a narrow single-user/local-only surface and the inherited story foundation still passes its relevant regression suite.
|
|
|
|
---
|
|
|
|
# M3 — Production Non-Destructive History, Redo, and Active-Head Export
|
|
|
|
## Objective
|
|
|
|
Replace destructive Undo with the demonstrated head-cursor model and make Undo/Redo/divergence/export/import production-safe.
|
|
|
|
## Scope
|
|
|
|
Promote the Phase 0B spike concept into maintainable production code:
|
|
|
|
- active head can move behind retained tip,
|
|
- Undo moves head and deletes zero accepted turns,
|
|
- Redo follows the retained continuation,
|
|
- new write behind tip forks on first write,
|
|
- retry/add-take/edit paths use the same safe fork/head rules,
|
|
- prevent Undo from walking before the campaign opening/root semantics,
|
|
- mark displaced/inactive futures/takes as retained/disposable using implementation-appropriate metadata,
|
|
- keep ordinary Redo invalidated after divergence,
|
|
- add browser Redo control and correct disabled/enabled states,
|
|
- keep branch complexity out of normal UI,
|
|
- export active head coordinate/depth as well as active branch,
|
|
- import honors exported active head,
|
|
- preserve backward compatibility for older bundles that lack the new field.
|
|
|
|
## Explicit Non-Scope
|
|
|
|
- named checkpoints belong in M4,
|
|
- no general branch-tree UI,
|
|
- no abandoned-history cleanup feature.
|
|
|
|
## Tests / Acceptance
|
|
|
|
Must cover:
|
|
|
|
- D01-D10,
|
|
- D02 minimum-five Undo,
|
|
- D03 practical unlimited Undo behavior across retained history,
|
|
- D04-D05 Redo semantics,
|
|
- E01-E04 lineage isolation,
|
|
- I01-I03 and I07 (undone-head round trip),
|
|
- L01-L02,
|
|
- branch-scoped memory remains isolated under Undo/Redo/divergence,
|
|
- row counts demonstrate Undo deletes zero accepted turns.
|
|
|
|
## Definition of Done
|
|
|
|
History operations are non-destructive, Redo works, divergence preserves old futures, and export/import reopens at the exact active head.
|
|
|
|
---
|
|
|
|
# M4 — Named Save Points / Checkpoints
|
|
|
|
## Objective
|
|
|
|
Add durable user-facing Save Points on top of the active-head model.
|
|
|
|
## Scope
|
|
|
|
- named checkpoint storage,
|
|
- checkpoint create/list/rename/delete,
|
|
- restore by moving the active head,
|
|
- later history retained rather than deleted,
|
|
- fork only on first new continuation after restore,
|
|
- checkpoint persistence across restart,
|
|
- checkpoint export/import,
|
|
- browser Save Point UX per `BROWSER-UX-SPEC.md`.
|
|
|
|
## Explicit Non-Scope
|
|
|
|
- no branch merge,
|
|
- no automatic discarded-history cleanup,
|
|
- no complex branch explorer required.
|
|
|
|
## Tests / Acceptance
|
|
|
|
- D11-D14,
|
|
- E lineage tests after checkpoint restore/divergence,
|
|
- I04,
|
|
- L03.
|
|
|
|
## Definition of Done
|
|
|
|
The user can create a named Save Point, continue, restart, restore it, and continue differently without losing later history.
|
|
|
|
---
|
|
|
|
# M5 — Genre-Neutral Authoritative Narrative State
|
|
|
|
## Objective
|
|
|
|
Replace/generalize AI-DnD's RPG-specific relative-delta state system with the approved genre-neutral typed-event model.
|
|
|
|
## Scope
|
|
|
|
Establish generic authoritative state for:
|
|
|
|
- entities,
|
|
- characters/locations/organizations/items/vehicles as descriptive entity categories,
|
|
- facts,
|
|
- relationships,
|
|
- possession/location/status/conditions,
|
|
- story threads,
|
|
- scene state,
|
|
- manual state/canon corrections,
|
|
- state proposal provenance.
|
|
|
|
Implement:
|
|
|
|
- explicit typed state proposal schema,
|
|
- absolute/unambiguous event semantics,
|
|
- event allowlist,
|
|
- validation,
|
|
- atomic accepted-event commit,
|
|
- current/historical snapshot/cache,
|
|
- rollback/reconstruction tied to active lineage,
|
|
- browser current-state inspector foundation.
|
|
|
|
Remove or demote:
|
|
|
|
- D&D-specific stats/bands/cooldowns/mechanics from the core product model,
|
|
- relative-delta semantics as the generic state protocol.
|
|
|
|
## Explicit Non-Scope
|
|
|
|
- no optional RPG module,
|
|
- no imported knowledge yet,
|
|
- no final rich state-editing UX if a simpler inspector is enough for this milestone.
|
|
|
|
## Tests / Acceptance
|
|
|
|
- C01-C04 and C06,
|
|
- D/E tests verifying state follows head movement,
|
|
- H05 invalid state event rejection,
|
|
- L01-L02,
|
|
- malformed JSON/state proposal handling,
|
|
- realistic-context tests against representative local models,
|
|
- fantasy and science-fiction state fixtures use the same schema.
|
|
|
|
## Definition of Done
|
|
|
|
Accepted story state is genre-neutral, auditable, reconstructable, and no longer depends on ambiguous relative deltas.
|
|
|
|
---
|
|
|
|
# M6 — Branch-Safe Context, Summaries, and Long-Term Story Memory
|
|
|
|
## Objective
|
|
|
|
Align inherited AI-DnD memory/context behavior with the final authority and history model.
|
|
|
|
## Scope
|
|
|
|
- preserve recent active-lineage history selection,
|
|
- ensure summaries are anchored to source turn ranges/lineage rather than positional list assumptions,
|
|
- preserve branch-scoped memory isolation,
|
|
- classify memory authority (accepted vs heuristic/inferred),
|
|
- maintain explicit token budgets,
|
|
- preserve/extend prompt-context inspection,
|
|
- ensure memory/summary failures do not corrupt accepted story state,
|
|
- test memory behavior after Undo/Redo/checkpoint/divergence,
|
|
- validate realistic-context prompt construction.
|
|
|
|
## Explicit Non-Scope
|
|
|
|
- imported document knowledge belongs in M7,
|
|
- no remote embeddings/vector DB.
|
|
|
|
## Tests / Acceptance
|
|
|
|
- F01-F08,
|
|
- E lineage safety,
|
|
- no abandoned-future term appears in active prompt after divergence,
|
|
- negative control proves eligible memory returns when the relevant lineage is active,
|
|
- summary lineage survives head movement correctly,
|
|
- prompt inspector identifies included memories/summaries and token costs.
|
|
|
|
## Definition of Done
|
|
|
|
Long-running story context is lineage-safe, authority-aware, local, inspectable, and bounded.
|
|
|
|
---
|
|
|
|
# M7 — First-Class Imported Knowledge Library
|
|
|
|
## Objective
|
|
|
|
Implement the separate local knowledge subsystem required by the specification rather than overloading AI-DnD Story Cards.
|
|
|
|
## Scope
|
|
|
|
- `.txt` and `.md` import,
|
|
- source validation and local copy/storage,
|
|
- Canon / Reference / Inspiration classification,
|
|
- enable/disable/delete,
|
|
- content hash and provenance,
|
|
- heading/paragraph-aware chunking,
|
|
- SQLite FTS5 lexical index,
|
|
- local Ollama embeddings where semantic retrieval is enabled,
|
|
- hybrid retrieval/reranking,
|
|
- authority-aware context insertion,
|
|
- campaign scoping,
|
|
- source/chunk inspector,
|
|
- prompt retrieval provenance,
|
|
- export/import preservation,
|
|
- no automatic URL/image fetch,
|
|
- prompt-injection framing as untrusted data.
|
|
|
|
## Explicit Non-Scope
|
|
|
|
- PDF/DOCX/EPUB import,
|
|
- remote URL ingestion,
|
|
- remote vector stores,
|
|
- general plugin/tool framework.
|
|
|
|
## Tests / Acceptance
|
|
|
|
- G01-G10,
|
|
- C05 canon beats reference/inspiration,
|
|
- hidden/abandoned story facts cannot leak through lineage-derived knowledge,
|
|
- H06-H09 as applicable to rendering/import/archive handling,
|
|
- I05 knowledge provenance survives export/import.
|
|
|
|
## Definition of Done
|
|
|
|
A campaign can import local Canon/Reference/Inspiration files, retrieve them locally with provenance, and maintain authority boundaries.
|
|
|
|
---
|
|
|
|
# M8 — Browser UX Completion for v1 Story Operations
|
|
|
|
## Objective
|
|
|
|
Turn the adapted AI-DnD interface into the focused interactive-story workspace defined by `BROWSER-UX-SPEC.md`.
|
|
|
|
## Scope
|
|
|
|
- campaign library/setup streamlined for non-RPG stories,
|
|
- story transcript and streaming polish,
|
|
- one primary natural-language input flow plus story-direction affordance,
|
|
- Undo/Redo/Retry/alternate-take controls,
|
|
- Save Points UI,
|
|
- edit user input/narrator output with safe lineage semantics,
|
|
- current scene/state side panel,
|
|
- knowledge panel,
|
|
- context inspector,
|
|
- local Ollama status/model selection,
|
|
- no cloud-provider UI,
|
|
- reserve microphone/STT affordance without implementing STT.
|
|
|
|
## Explicit Non-Scope
|
|
|
|
- no full branch-management UI,
|
|
- no image/video/TTS/STT implementation,
|
|
- no mobile-native app.
|
|
|
|
## Tests / Acceptance
|
|
|
|
- B01-B04,
|
|
- D user-facing behavior,
|
|
- relevant UX acceptance checks,
|
|
- browser state remains consistent after restart/Undo/Redo/checkpoint/failed generation.
|
|
|
|
## Definition of Done
|
|
|
|
Normal story creation and play feels like a focused local storyteller rather than an RPG or developer console.
|
|
|
|
---
|
|
|
|
# M9 — Export, Backup, Recovery, and Migration Hardening
|
|
|
|
## Objective
|
|
|
|
Make campaigns portable and recoverable without losing lineage, state, knowledge, or the active head.
|
|
|
|
## Scope
|
|
|
|
- finalize documented campaign bundle format/versioning,
|
|
- preserve active branch/head, retained history, retries, checkpoints,
|
|
- state events/snapshots,
|
|
- prompt/retrieval provenance as selected,
|
|
- knowledge source metadata/content/index rebuild information,
|
|
- scene/media metadata placeholders,
|
|
- safe SQLite backup behavior,
|
|
- import validation,
|
|
- backward-compatible migration rules,
|
|
- corruption/failure handling where practical.
|
|
|
|
## Tests / Acceptance
|
|
|
|
- I01-I06,
|
|
- L01-L04,
|
|
- undone-head round trip,
|
|
- branched campaign round trip,
|
|
- checkpoint round trip,
|
|
- knowledge provenance round trip,
|
|
- derived indexes can be rebuilt.
|
|
|
|
## Definition of Done
|
|
|
|
A campaign can be safely exported, imported into a clean data directory, and reopened at the exact intended active position with authoritative history/state intact.
|
|
|
|
---
|
|
|
|
# M10 — Future Media Extension Hooks Only
|
|
|
|
## Objective
|
|
|
|
Preserve the approved future media interfaces without adding a media-generation dependency to v1.
|
|
|
|
## Scope
|
|
|
|
- scene snapshots/packets suitable for future providers,
|
|
- optional visual character/location/item descriptors,
|
|
- provider-neutral media request/job/asset types or reserved schema as justified,
|
|
- branch/lineage association for scenes/assets,
|
|
- local-only endpoint contract for future providers,
|
|
- STT contract: local transcription -> editable draft -> normal submission,
|
|
- no core story-engine dependency on media availability.
|
|
|
|
## Explicit Non-Scope
|
|
|
|
Do not implement:
|
|
|
|
- image generation,
|
|
- video generation,
|
|
- TTS,
|
|
- STT,
|
|
- ambience/audio generation,
|
|
- ComfyUI/FLUX integration.
|
|
|
|
## Tests / Acceptance
|
|
|
|
- K01-K04 architecture/media-readiness tests,
|
|
- no v1 story flow requires a media service,
|
|
- scene data follows active lineage after Undo/restore/divergence.
|
|
|
|
## Definition of Done
|
|
|
|
Future media providers can be added through defined local interfaces without redesigning core story authority/history.
|
|
|
|
---
|
|
|
|
# M11 — v1 Security, Long-Run, and Release Validation
|
|
|
|
## Objective
|
|
|
|
Validate the full product against the release contract after all functional milestones are integrated.
|
|
|
|
## Scope
|
|
|
|
- full outbound-network blocked run,
|
|
- dependency/runtime audit,
|
|
- restrictive browser/CORS/CSP checks,
|
|
- failed-model-call recovery,
|
|
- long-running 100-turn campaign,
|
|
- repeated Undo/Redo/Retry/checkpoint cycles,
|
|
- branch/memory/summary leakage checks,
|
|
- realistic-context state extraction across selected recommended models,
|
|
- fantasy and science-fiction fixtures,
|
|
- export/import/recovery tests,
|
|
- migration tests,
|
|
- documentation and packaging.
|
|
|
|
## Tests / Acceptance
|
|
|
|
Release gate in `V1-ACCEPTANCE-TESTS.md`:
|
|
|
|
- all REQUIRED FOR V1 tests pass,
|
|
- approved exceptions documented in ADRs,
|
|
- 100-turn test passes,
|
|
- offline operation passes,
|
|
- branch/memory isolation passes,
|
|
- export/import recovery passes,
|
|
- both genre fixtures pass.
|
|
|
|
## Definition of Done
|
|
|
|
The build meets the v1 black-box acceptance contract and can be packaged as the first production release.
|
|
|
|
---
|
|
|
|
## 4. Milestone Dependency Summary
|
|
|
|
```text
|
|
M1 Production/offline foundation
|
|
-> M2 Local-only surface reduction
|
|
-> M3 Non-destructive history + export head
|
|
-> M4 Save Points
|
|
-> M5 Narrative state
|
|
-> M6 Context/memory
|
|
-> M7 Imported knowledge
|
|
-> M8 Browser UX completion
|
|
-> M9 Export/recovery hardening
|
|
-> M10 Future-media hooks
|
|
-> M11 v1 validation/release
|
|
```
|
|
|
|
Some implementation work may overlap internally, but milestone acceptance should remain sequential so architectural regressions are discovered early.
|
|
|
|
## 4. Prompting Rule
|
|
|
|
When implementation begins, prepare **one Codex prompt per milestone**.
|
|
|
|
Do not hand the entire plan to Codex as one production task.
|
|
|
|
Each prompt should contain only:
|
|
|
|
- milestone objective,
|
|
- relevant source documents,
|
|
- scope/non-scope,
|
|
- specific acceptance tests,
|
|
- stop condition and required report/diff.
|
|
|
|
No implementation prompt is included in the current planning revision.
|