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,141 @@
# CaoRuiming/ai-adventure — Static Architecture Analysis
**Historical status:** Static Phase 0A analysis. Phase 0B promoted ai-adventure to the primary implementation reference for state/event/head/checkpoint semantics, but not the production base.
**Project name in repository docs:** Local Adventure Engine
**Repository:** https://github.com/CaoRuiming/ai-adventure
**Date reviewed:** 2026-09-01
**Disposition:** Finalist #3; strongest state/privacy reference, possible core candidate.
## Architectural fit
This project most closely matches the desired trust boundary:
> The model proposes narration/events; the application validates and commits authoritative state.
Its architecture separates:
- authored content,
- runtime state and pure reducers,
- SQLite storage/migrations,
- local lore indexing/retrieval,
- deterministic bounded context construction,
- model provider,
- application turn logic,
- CLI presentation.
That separation makes it especially valuable even if it is not the final fork.
## Turn/commit model
The documented flow:
1. load/replay state,
2. synchronize lore,
3. build deterministic bounded context,
4. call local model,
5. parse a structured turn proposal,
6. validate proposed events,
7. apply events in memory,
8. atomically append turn/events and move the session head,
9. display narration only after commit.
This is the strongest candidate design for “the model is not the database.”
## Persistence and recovery
The project documents:
- parent-linked turn history,
- append-only state events,
- cached reconstructed state,
- undo by moving session head,
- named checkpoints,
- restore,
- branching into another session that shares ancestors,
- replayable state.
This satisfies the conceptual checkpoint/branch requirement better than a destructive chat log.
Potential mismatch:
- branches are represented as sessions rather than necessarily one unified visual story tree.
- export behavior and cross-branch navigation should be tested for the browser product.
## Lore and long memory
The project currently favors deterministic local retrieval:
- Markdown lore,
- SQLite FTS5/fallback,
- bounded context,
- summaries.
It intentionally avoids an embedding/vector dependency in the initial architecture.
This is attractive for privacy and auditability, but the target project likely also wants optional local semantic retrieval through Ollama for:
- old story events,
- large imported reference/inspiration libraries.
The deterministic lexical layer should still be considered as part of a hybrid retriever.
## Privacy/security fit
This is the strongest static privacy design among the finalists.
The project documentation explicitly addresses:
- local data directory,
- loopback model endpoint by default,
- warning for non-loopback endpoints,
- no telemetry/cloud account,
- no MCP,
- no executable plugins,
- no shell tools,
- parameterized SQL,
- bounded imports,
- path traversal/symlink restrictions,
- local world files treated as data.
The default provider is LM Studio rather than Ollama, but the provider boundary appears intentionally small.
## Tests
Project documentation reports an offline test suite that grew during implementation (later milestone notes report 74 tests). Phase 0B should run the actual current suite and treat it as authoritative.
## Major gaps for target product
- terminal UI,
- LM Studio rather than Ollama as documented primary provider,
- no browser API/UI,
- no current media system,
- no semantic embedding retrieval,
- authored entity/event model may be more rigid than freeform narrative state,
- likely more front-end work than either browser finalist.
## Best reuse case
Even if it is not the production base, reuse its architectural rules:
- append-only authoritative events,
- model proposals never direct state writes,
- validate before commit,
- commit narration and state atomically,
- deterministic replay,
- non-destructive head movement,
- imported files are data only,
- minimal network surface.
If selected as base, Phase 0B must prove that adding Ollama + a browser service/UI is smaller than stripping AI-DnD.
## Phase 0B questions for Codex
1. Can its provider interface talk to Ollama via compatibility mode with a tiny adapter?
2. Can a native Ollama adapter be added without touching turn/state logic?
3. How much application code assumes CLI presentation?
4. Is the app/service layer clean enough to expose through FastAPI without refactoring state internals?
5. How are branches/checkpoints exported and navigated?
6. Can generic freeform narrative facts/entities be represented without expanding typed events excessively?
7. With Internet blocked, is the only runtime network connection the configured local model endpoint?
## Primary source links
- Repository: https://github.com/CaoRuiming/ai-adventure
- Architecture: https://github.com/CaoRuiming/ai-adventure/blob/main/docs/architecture.md
- Privacy/security: https://github.com/CaoRuiming/ai-adventure/blob/main/docs/privacy-and-security.md
- Apache-2.0 license: repository `LICENSE`