Docs: consolidate active planning and archive historical material
The planning package had grown to where a new agent could not tell what was authoritative. Phase 0 execution prompts sat beside the specification; four completed milestone reports sat beside the current one; and upstream AI-DnD's own `plan/` build log and `docs/` project site still described a hosted, scripted, multi-user product with accounts — every screenshot in it showed a Scripts tab and a Sign up button, none of which has existed since M2. `planning/archive/` now holds the history and says so in its own README: `phase0/` for the research that chose AI-DnD, `milestone-reports/` for M1 and M2, `decisions/` for ADR 008, the Phase-0-before-build gate Phase 0 satisfied. `planning/reports/` holds only the current milestone's report, because that is the one M4 planning has to read; it moves to the archive when M4's replaces it. Deleted rather than archived: the Phase 0B execution prompts and the handoff/status/summary documents, the Phase 0A discovery and triage reports, upstream's `plan/` and `docs/` trees, and `frontend/README.md`, which was Vite's template boilerplate. All of it is in Git history, and the two recommendation reports carry every conclusion the deleted research reached. Archived documents are kept verbatim. Paths written inside them point at where those files were when the document was written, which is the point: an evidence record that has been quietly edited is no longer evidence. Active documentation is corrected where it pointed at the removed trees or described removed capability as present. `DEVELOPMENT.md`'s "things M1 did not touch" list had gone stale at M2 and claimed QuickJS scripting was still tested; its test count was 604 against an actual 638. `README.md` loses the upstream CI badge, which reported upstream's pipeline rather than this fork's, and a reference to `backend/app/worldstate/engine.py`, a file that does not exist. `planning/README.md` is rewritten as the documentation index. New: `planning/PROJECT-SOURCES.md` and `planning/project-sources.txt`, the manifest of what belongs in the ChatGPT project's Sources. Source comments referring to the deleted trees are reworded; no behaviour changes. 638 backend tests pass, frontend lints and builds, and a reference scan over all 48 tracked Markdown files reports no unresolved path in active documentation. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NCbwH7yLGKsj1rhXXzKSCu
This commit is contained in:
JesseMarkowitz
co-authored by
Claude Opus 5
Claude Opus 5
parent
c8755c21c2
commit
d27ee34901
+179
-115
@@ -1,21 +1,151 @@
|
||||
# Adventure Storyteller Planning Package
|
||||
# Adventure Storyteller — Planning Package
|
||||
|
||||
**Status:** Phase 0 complete; architecture selected; **Milestones M1, M2 and M3 implemented and accepted (M3: 2026-09-03)**.
|
||||
**Production coding:** Underway, milestone by milestone. M1, M2 and M3 are done; M4 is the next milestone to brief.
|
||||
**This file is the index. Start here.**
|
||||
|
||||
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 state:** Phase 0 complete; AI-DnD forked as the production base;
|
||||
milestones **M1, M2 and M3 implemented and accepted** (M3: 2026-09-03).
|
||||
**Next:** **M4 — named Save Points.** Its brief has not been written yet, and
|
||||
writing it is the current action.
|
||||
|
||||
## Current Decision
|
||||
**Package version:** see `VERSION.md`, which records what each revision changed
|
||||
and why.
|
||||
|
||||
Phase 0A static research and Phase 0B local validation are complete.
|
||||
## Where documentation lives
|
||||
|
||||
The production starting point is:
|
||||
```text
|
||||
planning/
|
||||
active specifications and implementation planning — authoritative
|
||||
|
||||
planning/DECISIONS/
|
||||
active architectural decisions (ADRs) — authoritative
|
||||
|
||||
planning/reports/
|
||||
the current milestone's implementation report — evidence, not instruction
|
||||
|
||||
planning/archive/
|
||||
historical evidence and completed planning material;
|
||||
not authoritative for current implementation
|
||||
```
|
||||
|
||||
You do not need to open `planning/archive/` to do ordinary milestone work. Go
|
||||
there only when an active document sends you for a specific piece of historical
|
||||
evidence. If an archived document contradicts an active one, the active one is
|
||||
right.
|
||||
|
||||
Outside `planning/`: `README.md` describes the application, `DEVELOPMENT.md` is
|
||||
setup and local operation, and `PROVENANCE.md` records what came from upstream
|
||||
AI-DnD and what each milestone changed.
|
||||
|
||||
## Which document controls
|
||||
|
||||
When two documents appear to conflict, the one higher in this list wins:
|
||||
|
||||
1. `SPECIFICATION.md` — product requirements and required behavior.
|
||||
2. The 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`.
|
||||
3. `V1-ACCEPTANCE-TESTS.md` — the observable pass/fail contract.
|
||||
4. `TECHNICAL-DESIGN.md` — the selected implementation architecture.
|
||||
5. The ADRs in `DECISIONS/`.
|
||||
6. `BUILD-MILESTONES.md` — implementation sequence. It sequences work; it does
|
||||
not override product behavior.
|
||||
7. The current milestone report in `reports/`, then `planning/archive/` —
|
||||
evidence and historical findings, authoritative over nothing.
|
||||
|
||||
Two standing qualifications:
|
||||
|
||||
- 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.
|
||||
- Where an ADR records the architecture chosen to implement a requirement stated
|
||||
elsewhere, both stand: ADR 005 states the history requirement and ADR 012
|
||||
states the architecture that implements it.
|
||||
|
||||
## The active documents
|
||||
|
||||
| Document | What it is for |
|
||||
| --- | --- |
|
||||
| `SPECIFICATION.md` | What the product must do. The top of the authority order. |
|
||||
| `TECHNICAL-DESIGN.md` | The selected architecture, including what M1-M3 built, recorded as fact. |
|
||||
| `DATA-MODEL.md` | Entities, the stored head, branch disposition, and the export shape. |
|
||||
| `STORY-BRANCH-SEMANTICS.md` | Undo/Redo/Retry/branch/take behavior, including the M3 ratifications. |
|
||||
| `CONTEXT-AND-MEMORY.md` | Prompt assembly, summarization, branch-safe memory. |
|
||||
| `IMPORTED-KNOWLEDGE-DESIGN.md` | Canon / Reference / Inspiration knowledge as a first-class subsystem. |
|
||||
| `SECURITY-THREAT-MODEL.md` | The trust boundary, and the inference endpoint policy as implemented. |
|
||||
| `MEDIA-EXTENSION-CONTRACT.md` | The contract future image/video/audio/TTS/STT work must fit. |
|
||||
| `BROWSER-UX-SPEC.md` | The browser surface, and what is deliberately not in it. |
|
||||
| `BUILD-MILESTONES.md` | M1-M11, what each delivers, what is done, and the notes each milestone leaves its successors. |
|
||||
| `V1-ACCEPTANCE-TESTS.md` | The pass/fail contract v1 is measured against. |
|
||||
| `TEST-CAMPAIGN-FIXTURE.md` | The standard campaign the acceptance tests are run on. |
|
||||
| `VERSION.md` | Package revision history: what each closeout changed. |
|
||||
| `PROJECT-SOURCES.md` | Which files to upload as ChatGPT Project Sources. |
|
||||
|
||||
## Reading order for a new coding agent
|
||||
|
||||
1. This file.
|
||||
2. `SPECIFICATION.md`
|
||||
3. `TECHNICAL-DESIGN.md`
|
||||
4. `BUILD-MILESTONES.md` — find the milestone you are being asked to do.
|
||||
5. `STORY-BRANCH-SEMANTICS.md`
|
||||
6. `DATA-MODEL.md`
|
||||
7. `CONTEXT-AND-MEMORY.md`
|
||||
8. `IMPORTED-KNOWLEDGE-DESIGN.md`
|
||||
9. `SECURITY-THREAT-MODEL.md`
|
||||
10. `BROWSER-UX-SPEC.md`
|
||||
11. `V1-ACCEPTANCE-TESTS.md`
|
||||
12. `DECISIONS/` — all of them; they are short.
|
||||
13. `reports/M3-IMPLEMENTATION-REPORT.md`, for what the last milestone actually
|
||||
left behind. Nothing in `planning/archive/` unless sent there.
|
||||
|
||||
## Architectural decisions
|
||||
|
||||
Active ADRs, all of which still constrain current or future work:
|
||||
|
||||
| ADR | Decision |
|
||||
| --- | --- |
|
||||
| `001-browser-first.md` | The UI is a browser application. |
|
||||
| `002-ollama-only-v1.md` | Ollama-compatible local inference only; trusted-LAN HTTPS with a private CA is verified, never bypassed. |
|
||||
| `003-authoritative-local-state.md` | The application owns authoritative state; the model does not. |
|
||||
| `004-local-only-production.md` | Local-only runtime; no cloud, telemetry or runtime remote assets. |
|
||||
| `005-branch-preserving-history.md` | History is preserved, not overwritten. **The requirement.** |
|
||||
| `006-genre-agnostic-core.md` | The core state model is genre-agnostic. |
|
||||
| `007-future-media-extension.md` | Media generation stays optional and decoupled. |
|
||||
| `009-ai-dnd-production-base.md` | AI-DnD at `d72f7c1b…` is the production base. |
|
||||
| `010-explicit-typed-narrative-state-events.md` | Explicit typed events / absolute assignments, not relative deltas. |
|
||||
| `011-local-inference-endpoint-policy.md` | Address allowlist, deny by default, checked twice, TLS mandatory. |
|
||||
| `012-active-head-non-destructive-history.md` | The stored active head. **The architecture implementing ADR 005.** |
|
||||
|
||||
`008-phase0-before-build-plan.md` was a process gate — do not begin production
|
||||
work until Phase 0 closes — which Phase 0 satisfied on 2026-09-01. It is in
|
||||
`archive/decisions/` and constrains nothing now. ADR numbering continues from
|
||||
012; 008 is not reused.
|
||||
|
||||
## Milestone reports
|
||||
|
||||
`reports/` holds the report for the milestone most recently completed, because
|
||||
that is the one the next milestone's planning has to consult:
|
||||
|
||||
- `reports/M3-IMPLEMENTATION-REPORT.md` — M3's review **and** its primary
|
||||
evidence record; no separate M3 baseline report was produced. M4 needs its
|
||||
§W (closeout) and §M/§W.4 (the open browser smoke test).
|
||||
|
||||
Completed earlier milestones are in `archive/milestone-reports/`. When M4's
|
||||
report lands, M3's moves there too: a milestone report is useful during the
|
||||
immediate next milestone and historical afterwards.
|
||||
|
||||
## The decision this package rests on
|
||||
|
||||
Phase 0A static research and Phase 0B local validation closed on 2026-09-01 with
|
||||
one decision:
|
||||
|
||||
> **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:
|
||||
It was chosen on measured behavior, not feature count: AI-DnD already had the
|
||||
browser UI, the FastAPI service boundary, SQLite persistence, parent-linked
|
||||
story history, alternate takes, branch-aware state snapshots, local Ollama
|
||||
operation, branch-scoped memory, prompt inspection, streaming, export/import and
|
||||
a substantial test suite. The composition of ideas selected around it:
|
||||
|
||||
```text
|
||||
AI-DnD production base
|
||||
@@ -26,45 +156,20 @@ AI-DnD production base
|
||||
+ 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.
|
||||
This is **not** a repository merge. AI-DnD is the ownership center; the others
|
||||
are implementation references only.
|
||||
|
||||
## Phase 0B Findings That Changed the Plan
|
||||
Phase 0B also corrected several Phase 0A assumptions, and those corrections are
|
||||
now built into the active documents rather than needing to be read from the
|
||||
research: shipped Undo was destructive with no Redo (ADR 012 replaced it);
|
||||
relative-delta world state can be semantically wrong while syntactically valid
|
||||
(ADR 010); `tiktoken` and Google Fonts broke offline operation (fixed in M1);
|
||||
export had to carry the head position (M3); Story Cards were not a sufficient
|
||||
imported-knowledge store (`IMPORTED-KNOWLEDGE-DESIGN.md`).
|
||||
|
||||
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:
|
||||
|
||||
1. `SPECIFICATION.md` — product requirements and required behavior.
|
||||
2. 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`
|
||||
3. `V1-ACCEPTANCE-TESTS.md` — observable pass/fail contract.
|
||||
4. `TECHNICAL-DESIGN.md` — selected implementation architecture.
|
||||
5. Foundational ADRs (`001-...md` through the current ADR set).
|
||||
6. `BUILD-MILESTONES.md` — implementation sequence; it does not override product behavior.
|
||||
7. 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.
|
||||
The evidence is in `archive/phase0/`, and `archive/phase0/PHASE-0B-RECOMMENDATION.md`
|
||||
is the strongest single document there. It is research evidence, not a
|
||||
specification, and it was not rewritten to match later conclusions.
|
||||
|
||||
## Foundational Decisions
|
||||
|
||||
@@ -95,29 +200,10 @@ The following are settled for v1:
|
||||
- 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
|
||||
## Still open, and deliberately so
|
||||
|
||||
- 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:
|
||||
These do not block the architecture and are not v1 requirements:
|
||||
|
||||
- comparative recommendation of narrator/state models for real users,
|
||||
- multi-hour/100-turn long-run behavior,
|
||||
@@ -125,78 +211,56 @@ These do not block the architecture decision:
|
||||
- actual future image/video/TTS/STT provider integration,
|
||||
- abandoned-history cleanup UI/policy (not required in v1).
|
||||
|
||||
## Recommended Reading Order for the Next Implementation Stage
|
||||
|
||||
Do not convert this into a coding prompt until the package review is approved.
|
||||
|
||||
When implementation planning resumes, read:
|
||||
|
||||
1. `SPECIFICATION.md`
|
||||
2. `TECHNICAL-DESIGN.md`
|
||||
3. `BUILD-MILESTONES.md`
|
||||
4. `STORY-BRANCH-SEMANTICS.md`
|
||||
5. `DATA-MODEL.md`
|
||||
6. `CONTEXT-AND-MEMORY.md`
|
||||
7. `IMPORTED-KNOWLEDGE-DESIGN.md`
|
||||
8. `SECURITY-THREAT-MODEL.md`
|
||||
9. `BROWSER-UX-SPEC.md`
|
||||
10. `V1-ACCEPTANCE-TESTS.md`
|
||||
11. ADRs, especially the production-base and narrative-state-event decisions
|
||||
12. Phase 0B reports only as supporting evidence
|
||||
|
||||
## Workflow From Here
|
||||
## Where the work stands
|
||||
|
||||
```text
|
||||
Phase 0 research and spikes COMPLETE
|
||||
Architecture/fork decision COMPLETE
|
||||
Planning package approved COMPLETE
|
||||
|
|
||||
v
|
||||
Architecture/fork decision COMPLETE
|
||||
Milestone M1 COMPLETE (2026-09-02)
|
||||
fork + offline baseline archive/milestone-reports/M1-*.md
|
||||
|
|
||||
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 COMPLETE (2026-09-02)
|
||||
local-only surface + endpoint see planning/reports/M2-*.md
|
||||
Milestone M2 COMPLETE (2026-09-02)
|
||||
local-only surface + endpoint archive/milestone-reports/M2-*.md
|
||||
policy
|
||||
|
|
||||
v
|
||||
Milestone M3 COMPLETE (2026-09-03)
|
||||
non-destructive undo/redo, see planning/reports/M3-*.md and ADR 012
|
||||
active-head export one open condition: the browser smoke test
|
||||
Milestone M3 COMPLETE (2026-09-03)
|
||||
non-destructive undo/redo, reports/M3-IMPLEMENTATION-REPORT.md
|
||||
active-head export and ADR 012
|
||||
|
|
||||
v
|
||||
Milestone M4 NEXT — brief not yet prepared
|
||||
Milestone M4 NEXT — brief not yet prepared
|
||||
named Save Points
|
||||
|
|
||||
v
|
||||
Implement and review milestone-by-milestone
|
||||
M5-M11, one at a time see BUILD-MILESTONES.md
|
||||
```
|
||||
|
||||
## Stop Rule
|
||||
|
||||
**One milestone at a time. Do not begin a milestone before its brief exists.**
|
||||
|
||||
M1, M2 and M3 are complete and accepted; the evidence is in `reports/M1-*.md`,
|
||||
`reports/M2-*.md` and `reports/M3-IMPLEMENTATION-REPORT.md` — the last of which
|
||||
is M3's primary evidence record as well as its review, since no separate M3
|
||||
baseline report was produced. **No M4 brief has been prepared.** The current
|
||||
action is to write one, informed by the post-M3 corrections below, by the note
|
||||
`BUILD-MILESTONES.md` now attaches to M4, and by **ADR 012**, which records the
|
||||
head-movement mechanism M4 must reuse rather than reimplement.
|
||||
**No M4 brief has been prepared.** Writing one is the current action, informed
|
||||
by the post-M3 corrections below, by the note `BUILD-MILESTONES.md` attaches to
|
||||
M4, and by **ADR 012**, which records the head-movement mechanism M4 must reuse
|
||||
rather than reimplement.
|
||||
|
||||
One M3 condition remains open and is not a blocker for M4: the required
|
||||
**browser smoke test has not been performed**, because no session in which M3
|
||||
was implemented or reviewed had a browser available. See
|
||||
One M3 condition remains open and does not block M4: the required **browser
|
||||
smoke test has not been performed**, because no session in which M3 was
|
||||
implemented or reviewed had a browser available. See
|
||||
`reports/M3-IMPLEMENTATION-REPORT.md` §M and §W.4.
|
||||
|
||||
## What each milestone closeout corrected
|
||||
|
||||
These tables are the audit trail: what implementation evidence forced back into
|
||||
the planning package, milestone by milestone. `VERSION.md` narrates the same
|
||||
changes.
|
||||
|
||||
### Post-M3 corrections applied (2026-09-03)
|
||||
|
||||
M3's review recommended planning changes and, following the M2 pattern, reported
|
||||
|
||||
Reference in New Issue
Block a user