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
@@ -0,0 +1,170 @@
|
||||
# AI-DnD — Static Architecture Analysis
|
||||
|
||||
**Historical status:** Static Phase 0A analysis. Phase 0B corrected the shipped Undo assumption and confirmed AI-DnD as the production base after a successful head-cursor spike.
|
||||
|
||||
**Repository:** https://github.com/parththakkar106/AI-DnD
|
||||
**Date reviewed:** 2026-09-01
|
||||
**Disposition:** Preliminary fork recommendation / Finalist #1.
|
||||
|
||||
## Why it moved to first place
|
||||
|
||||
The static review indicates that AI-DnD already implements most of the difficult correctness infrastructure that would otherwise need to be invented:
|
||||
|
||||
- browser UI (React/Vite),
|
||||
- FastAPI backend,
|
||||
- local SQLite,
|
||||
- Ollama via local OpenAI-compatible endpoint,
|
||||
- story as a tree rather than a list,
|
||||
- alternate takes,
|
||||
- branch lineage that borrows ancestors,
|
||||
- state restored when switching branches,
|
||||
- non-destructive retry,
|
||||
- state snapshots,
|
||||
- exact prompt/context snapshots,
|
||||
- automatic summaries,
|
||||
- embedding-based long-term memory,
|
||||
- story cards/world information,
|
||||
- export/import of the complete story tree,
|
||||
- substantial automated backend testing.
|
||||
|
||||
The current README reports 549 backend tests. The design guide contains an older measured-results count of 440, so the clone should treat the live test suite—not prose counts—as authoritative.
|
||||
|
||||
## Story tree
|
||||
|
||||
This is the strongest reason to prefer AI-DnD.
|
||||
|
||||
The project explicitly models:
|
||||
|
||||
- branches,
|
||||
- actions/nodes,
|
||||
- parent/fork lineage,
|
||||
- multiple takes at a turn,
|
||||
- branch-aware context,
|
||||
- state after a node,
|
||||
- retry that preserves the replaced attempt.
|
||||
|
||||
That matches the user's desired “Git for stories” behavior much more closely than Open Dungeon.
|
||||
|
||||
Its documentation also describes measured optimization work so branches do not duplicate the ancestor transcript.
|
||||
|
||||
## Turn pipeline
|
||||
|
||||
The documented flow is close to the target Story Director:
|
||||
|
||||
```text
|
||||
player input
|
||||
-> optional input hook
|
||||
-> retrieve memories
|
||||
-> assemble bounded context
|
||||
-> snapshot exact context
|
||||
-> stream provider output
|
||||
-> extract proposed state delta
|
||||
-> Python referee validates state
|
||||
-> save action + resulting state
|
||||
-> background summarize/embed
|
||||
```
|
||||
|
||||
The target project would simplify this rather than reinvent it.
|
||||
|
||||
## Memory/context
|
||||
|
||||
AI-DnD already includes three useful layers:
|
||||
|
||||
- direct recent history,
|
||||
- AI-generated memories,
|
||||
- running story summary.
|
||||
|
||||
Embedding retrieval pulls old relevant memories back into context and exposes similarity/context details through an Insights UI.
|
||||
|
||||
Story cards provide a mature starting point for lore/world-info injection.
|
||||
|
||||
The main extension needed is a first-class imported document library with explicit authority classes:
|
||||
- Canon,
|
||||
- Reference,
|
||||
- Inspiration.
|
||||
|
||||
## Prompt transparency
|
||||
|
||||
The current project stores the exact prompt sent for a turn and provides an Insights view with context components and token costs. This directly satisfies a stated debugging requirement.
|
||||
|
||||
## What must be removed or generalized
|
||||
|
||||
AI-DnD is not a clean fit out of the box.
|
||||
|
||||
### RPG-specific world state
|
||||
Current world state is designed around stats, bands, flags, milestones, cooldowns, NPC presence, and state deltas.
|
||||
|
||||
Target:
|
||||
- retain the proposal/referee/snapshot pattern,
|
||||
- replace or supplement RPG stats with generic narrative entities/facts/relationships/story threads/scenes.
|
||||
|
||||
### QuickJS scripting
|
||||
The project includes AI-Dungeon-compatible user scripting.
|
||||
|
||||
For this project, executable campaign content conflicts with the desired narrow trust surface. Unless a compelling future use appears, remove or disable scripting in v1.
|
||||
|
||||
### Hosted/multi-user behavior
|
||||
Current code supports:
|
||||
- optional accounts,
|
||||
- guest users,
|
||||
- rate limits,
|
||||
- demo keys,
|
||||
- hosted deployments,
|
||||
- Postgres/Neon,
|
||||
- Render,
|
||||
- remote model providers.
|
||||
|
||||
The target is a single-user local application. These paths should be removed or compiled/configured out rather than merely hidden in the UI.
|
||||
|
||||
### Analytics
|
||||
The project includes its own owner-only aggregate visit analytics for hosted mode. It is not described as a third-party tracker, but it is unnecessary for the local fork and should be removed.
|
||||
|
||||
### Cloud providers
|
||||
OpenRouter/OpenAI/Groq/vLLM support is broader than desired. v1 should retain only the local Ollama path.
|
||||
|
||||
## Security positive
|
||||
|
||||
The local/hosted modes are already explicitly separated, and the code contains network-guard thinking around hosted deployments. This is a better starting point than a project with cloud assumptions scattered everywhere, but static review cannot prove that removal is trivial.
|
||||
|
||||
## Main risk
|
||||
|
||||
The central Phase 0B question is:
|
||||
|
||||
> Are the RPG/cloud/scripting systems modular enough that removing them is less work and less risk than adding correct branching/state/memory to Open Dungeon?
|
||||
|
||||
Static evidence suggests yes, but this must be tested with a local strip-down experiment.
|
||||
|
||||
## Best reuse case
|
||||
|
||||
If selected:
|
||||
- keep story tree,
|
||||
- keep action/state snapshots,
|
||||
- keep context/history windowing,
|
||||
- keep Memory Bank structure,
|
||||
- keep story cards,
|
||||
- keep Insights/prompt snapshots,
|
||||
- keep SQLite and local FastAPI/React split,
|
||||
- keep Ollama adapter path,
|
||||
- remove hosted/auth/analytics/cloud,
|
||||
- remove QuickJS,
|
||||
- generalize world state,
|
||||
- add document ingestion,
|
||||
- add scene/media schema and provider interface,
|
||||
- use Open Dungeon/Gamentic as media UX references.
|
||||
|
||||
## Phase 0B questions for Codex
|
||||
|
||||
1. Can the app run fully local with only Ollama and no Internet?
|
||||
2. Can QuickJS, hosted auth, analytics, Render/Neon, and remote provider paths be removed without destabilizing core tests?
|
||||
3. How tightly does branching depend on RPG world-state fields?
|
||||
4. Can an adventure run with minimal/no stats while branch rollback still passes?
|
||||
5. Can the state snapshot payload be generalized to narrative JSON without rewriting the tree?
|
||||
6. How many tests cover branch/undo/retry/context/memory independently of RPG logic?
|
||||
7. Does current Memory Bank work with a local Ollama embedding model in practice?
|
||||
8. What exact outbound traffic occurs in default local mode?
|
||||
|
||||
## Primary source links
|
||||
|
||||
- Repository / README: https://github.com/parththakkar106/AI-DnD
|
||||
- Design guide: https://github.com/parththakkar106/AI-DnD/blob/main/docs/GUIDE.md
|
||||
- MIT license: repository `LICENSE`
|
||||
Reference in New Issue
Block a user