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
2026-09-03 14:33:07 -04:00
co-authored by Claude Opus 5
parent c8755c21c2
commit d27ee34901
84 changed files with 504 additions and 11271 deletions
@@ -0,0 +1,155 @@
# Phase 0A Preliminary Recommendation
**Historical status:** Superseded by Phase 0B runtime validation and ADR 009. Retained as Phase 0A evidence.
**Date:** 2026-09-01
**Status:** Static recommendation; pending Phase 0B clone/build/runtime experiments.
## Recommendation
### First choice to validate: AI-DnD
Use **AI-DnD as the preliminary production fork candidate**.
This is a change from the earlier slight preference for Open Dungeon.
The deciding evidence is not feature count; it is **where the hard architectural work already lives**.
AI-DnD already implements:
- parent/lineage story tree,
- alternate takes,
- non-destructive retry,
- branch-aware state rollback,
- prompt snapshots,
- context windowing,
- memory bank + embeddings,
- story cards,
- complete tree export/import,
- local Ollama,
- a substantial automated test suite.
Those are precisely the systems most dangerous to retrofit after a linear chat application has accumulated behavior.
## Why Open Dungeon is second
Open Dungeon remains the best direct match to the desired *product*:
- simple browser fiction interface,
- Ollama,
- local SQLite,
- strong local image path,
- visual continuity.
However, its present persistence semantics are linear and destructive:
- prior messages can be updated,
- retry/erase deletes the selected message and the story tail.
To satisfy the specification, we would need to introduce turn parentage/branches, branch-specific summaries/state, and non-destructive editing underneath features already written around a list. That is foundational work.
Open Dungeon should remain the fallback base if Codex proves AI-DnD's RPG/cloud systems are too entangled to remove.
## Why ai-adventure is third
ai-adventure has the cleanest *architecture* for state authority and local-only trust:
- typed model proposals,
- validation,
- atomic commit,
- append-only events,
- replay,
- checkpoints,
- branches,
- deterministic local lore,
- explicit minimal network posture.
Its problem is product distance:
- CLI presentation,
- LM Studio primary provider,
- no browser application,
- no media,
- less semantic long-memory machinery.
It should be the architectural control against which the selected browser fork is judged.
## Do not merge repositories
The recommendation is not to combine several projects mechanically.
Fork one project and re-implement selected ideas using compatible patterns/code only where justified.
A merged codebase would import:
- incompatible assumptions,
- duplicate persistence models,
- different provider abstractions,
- unnecessary dependencies,
- licensing complexity.
## Proposed target architecture after Phase 0B
If AI-DnD passes validation:
### Retain
- React/Vite browser shell,
- FastAPI service boundary,
- SQLite,
- story tree/lineage,
- state snapshots,
- context budgeting,
- Memory Bank,
- story cards,
- Insights,
- Ollama path,
- export/import,
- relevant tests.
### Remove
- multi-user/hosted auth,
- demo keys/rate-limit hosting features,
- Render/Neon path,
- analytics,
- cloud model providers,
- QuickJS scripting,
- AI-Dungeon compatibility not needed for core stories,
- RPG-only presentation/mechanics.
### Generalize
- world-state engine -> narrative state/facts/entities/threads,
- Story Cards -> local knowledge sources with authority/provenance,
- Memory Bank -> branch-safe story memory with Canon/Scene/Heuristic trust classes,
- scenario -> genre-neutral campaign/story profile.
### Add
- local document ingestion,
- Canon / Reference / Inspiration source classification,
- local lexical + optional Ollama semantic retrieval,
- scene snapshots,
- visual character/location fields,
- media asset/job records,
- media-provider interface,
- later local image/video adapters.
## Phase 0B should be narrow
Codex should not repeat the broad research.
It should validate three concrete engineering hypotheses:
### Hypothesis 1 — AI-DnD can be stripped safely
Prove local Ollama story/branch/memory operation still works after disabling/removing hosted/cloud/analytics/scripting paths and running with minimal RPG state.
### Hypothesis 2 — Open Dungeon branch retrofit is materially larger
Map exactly how many DB functions/API routes/UI components/summary behaviors must change to make retry/edit non-destructive and branch-aware.
### Hypothesis 3 — ai-adventure is viable but farther from product
Prove Ollama adapter effort is small and estimate the service/browser wrapper effort without starting production UI development.
Then choose the fork based on measured modification cost.
## Decision gate
Select AI-DnD unless Phase 0B finds one of these blockers:
- branching/state logic is inseparable from RPG mechanics,
- removing hosted/scripting paths destabilizes a large percentage of tests,
- local-only configuration still requires hard-to-remove external services,
- dependency/security burden is materially worse than static review suggests.
If any blocker is confirmed, select Open Dungeon and explicitly budget a story-tree/persistence rewrite as the first production architecture milestone.