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
@@ -97,8 +97,8 @@ A clean production build can start, open the browser UI, generate and persist st
|
||||
|
||||
## Status: COMPLETE
|
||||
|
||||
Accepted 2026-09-02. Evidence: `planning/reports/M1-BASELINE-REPORT.md` (run
|
||||
logs and packet captures) and `planning/reports/M1-IMPLEMENTATION-REPORT.md`
|
||||
Accepted 2026-09-02. Evidence: `planning/archive/milestone-reports/M1-BASELINE-REPORT.md` (run
|
||||
logs and packet captures) and `planning/archive/milestone-reports/M1-IMPLEMENTATION-REPORT.md`
|
||||
(review report). A01-A06, H01-H03 and H11 all pass on runtime evidence; 648
|
||||
backend tests pass, including with no route to the Internet.
|
||||
|
||||
@@ -168,8 +168,8 @@ The codebase has a narrow single-user/local-only surface and the inherited story
|
||||
|
||||
## Status: COMPLETE
|
||||
|
||||
Accepted 2026-09-02. Evidence: `planning/reports/M2-BASELINE-REPORT.md`
|
||||
(measurements) and `planning/reports/M2-IMPLEMENTATION-REPORT.md` (review);
|
||||
Accepted 2026-09-02. Evidence: `planning/archive/milestone-reports/M2-BASELINE-REPORT.md`
|
||||
(measurements) and `planning/archive/milestone-reports/M2-IMPLEMENTATION-REPORT.md` (review);
|
||||
verdict *accept with non-blocking debt, proceed to M3*. Implementation is
|
||||
commit `8c65ae9`, and the three defects the review found are commit `8652fe7`
|
||||
— see the closeout note appended to both reports.
|
||||
@@ -193,9 +193,10 @@ commit `8c65ae9`, and the three defects the review found are commit `8652fe7`
|
||||
**Debt carried forward, none of it blocking M3:** `Settings.model` still
|
||||
defaults to `""` with nothing prompting for it (M8); inert legacy tables and
|
||||
columns await a cleanup migration once the schema settles, after M3/M5; there
|
||||
are still no frontend tests (M8); `docs/*.html`, upstream's project site and not
|
||||
served by the app, still links Google Fonts. Full table in the implementation
|
||||
report §P.
|
||||
are still no frontend tests (M8). `docs/*.html`, upstream's project site, was
|
||||
listed here as still linking Google Fonts; the whole inherited `docs/` tree was
|
||||
deleted in the 2026-09-03 documentation pass, which closes that item. Full table
|
||||
in the implementation report §P.
|
||||
|
||||
---
|
||||
|
||||
@@ -434,7 +435,7 @@ undo semantics and are expected to be rewritten by M3; that is separate from
|
||||
this instrumentation point, and they should likewise be rewritten rather than
|
||||
dropped.
|
||||
|
||||
Evidence: `planning/reports/M2-IMPLEMENTATION-REPORT.md` §K.2, §Q.
|
||||
Evidence: `planning/archive/milestone-reports/M2-IMPLEMENTATION-REPORT.md` §K.2, §Q.
|
||||
|
||||
## Note from M3 — three constraints this milestone must satisfy
|
||||
|
||||
@@ -529,7 +530,7 @@ M6 therefore additionally requires:
|
||||
degraded the storyteller quietly and left the transcript correct, which is the
|
||||
right failure direction — but it must also be a *visible* one.
|
||||
|
||||
Evidence: `planning/reports/M2-IMPLEMENTATION-REPORT.md` §A.1, §9.1.
|
||||
Evidence: `planning/archive/milestone-reports/M2-IMPLEMENTATION-REPORT.md` §A.1, §9.1.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,14 +0,0 @@
|
||||
# Codex Handoff Note
|
||||
|
||||
**Status:** Phase 0B handoff complete; historical only.
|
||||
|
||||
The earlier Phase 0B execution prompts are retained for audit/history:
|
||||
|
||||
- `PHASE-0B-CODEX-BRIEF.md`
|
||||
- `PHASE-0B-CODEX-HANDOFF.md`
|
||||
|
||||
Do **not** execute either as the next production task.
|
||||
|
||||
Phase 0B has been completed and the resulting recommendation reviewed. AI-DnD is now the selected production base, and the planning package has been revised accordingly.
|
||||
|
||||
The next production Codex prompt has **not** been prepared. It should be created only after the current planning-package revision is reviewed and approved. When authorized, the first implementation prompt should be derived from Production Milestone M1 in `BUILD-MILESTONES.md`, not from the Phase 0B validation briefs.
|
||||
@@ -57,4 +57,4 @@ Therefore:
|
||||
`http://…:11434`.
|
||||
|
||||
M1 implemented this (`backend/app/tlstrust.py`); see
|
||||
`planning/reports/M1-IMPLEMENTATION-REPORT.md` §G.
|
||||
`planning/archive/milestone-reports/M1-IMPLEMENTATION-REPORT.md` §G.
|
||||
|
||||
@@ -115,4 +115,4 @@ itself beyond loopback, which remains out of scope for v1.
|
||||
- `SECURITY-THREAT-MODEL.md` §10A, §71A item 5, §77
|
||||
- `TECHNICAL-DESIGN.md` §5.1 item 4, §5.2
|
||||
- ADR 002 (Ollama-only, and the TLS consequence), ADR 004 (local-only production)
|
||||
- `planning/reports/M2-IMPLEMENTATION-REPORT.md` §F, §K.1
|
||||
- `planning/archive/milestone-reports/M2-IMPLEMENTATION-REPORT.md` §F, §K.1
|
||||
|
||||
@@ -1,272 +0,0 @@
|
||||
# Phase 0B — Codex Initial Validation Brief
|
||||
|
||||
**Status:** COMPLETE / HISTORICAL — do not execute as a production prompt
|
||||
**Purpose:** Run a focused first round of local validation on the three finalist repositories and return a recommendation based on what was actually learned.
|
||||
|
||||
## 1. Goal
|
||||
|
||||
We are **not** asking you to build the production application yet.
|
||||
|
||||
The goal of this round is to answer one question:
|
||||
|
||||
> Which existing project is the best starting point for the local interactive-story application, and what important technical facts did we learn that should affect the next design step?
|
||||
|
||||
The three finalists are:
|
||||
|
||||
1. AI-DnD
|
||||
https://github.com/parththakkar106/AI-DnD
|
||||
|
||||
2. Open Dungeon
|
||||
https://github.com/newideas99/open-dungeon
|
||||
|
||||
3. ai-adventure
|
||||
https://github.com/CaoRuiming/ai-adventure
|
||||
|
||||
## 2. Important Product Requirements
|
||||
|
||||
Use these as the main evaluation criteria.
|
||||
|
||||
The eventual application should be:
|
||||
|
||||
- browser-first,
|
||||
- local-only in v1,
|
||||
- based on local Ollama inference,
|
||||
- single-user,
|
||||
- genre-agnostic,
|
||||
- persistent across restarts,
|
||||
- able to retain authoritative story state separately from model prose,
|
||||
- able to Undo/Redo/Retry safely,
|
||||
- able to preserve named save points/checkpoints,
|
||||
- able to retain abandoned history without immediately deleting it,
|
||||
- able to prevent abandoned-history facts/memories from leaking into the active story,
|
||||
- able to support long-term context/memory,
|
||||
- able to import local knowledge,
|
||||
- able to inspect what context was sent to the model,
|
||||
- architecturally compatible with future local image/video/TTS/STT support.
|
||||
|
||||
Do not try to implement all of these now.
|
||||
|
||||
This round is about determining which candidate already gives us the strongest foundation.
|
||||
|
||||
## 3. Read Only What You Need
|
||||
|
||||
Start with:
|
||||
|
||||
1. `README.md`
|
||||
2. `SPECIFICATION.md`
|
||||
3. `reports/PRELIMINARY-RECOMMENDATION.md`
|
||||
4. `reports/REUSE-MATRIX.md`
|
||||
|
||||
Then use these only when relevant to a specific experiment:
|
||||
|
||||
- `STORY-BRANCH-SEMANTICS.md`
|
||||
- `CONTEXT-AND-MEMORY.md`
|
||||
- `SECURITY-THREAT-MODEL.md`
|
||||
- `TEST-CAMPAIGN-FIXTURE.md`
|
||||
|
||||
Do **not** read every planning document up front unless needed.
|
||||
|
||||
## 4. Baseline Work for Each Candidate
|
||||
|
||||
For each repository:
|
||||
|
||||
1. Clone it cleanly.
|
||||
2. Record the exact commit SHA.
|
||||
3. Follow the documented install instructions.
|
||||
4. Run the existing tests.
|
||||
5. Build/start the application.
|
||||
6. Confirm the basic local story flow.
|
||||
7. Record:
|
||||
- test results,
|
||||
- storage/database technology,
|
||||
- model/provider assumptions,
|
||||
- local ports,
|
||||
- major runtime failures,
|
||||
- obvious cloud/hosted dependencies.
|
||||
|
||||
Do not spend excessive time fixing unrelated upstream problems.
|
||||
|
||||
If a project does not run cleanly, document why and continue.
|
||||
|
||||
## 5. Focused Experiment A — AI-DnD
|
||||
|
||||
We want to know whether AI-DnD can realistically serve as the production base.
|
||||
|
||||
Test:
|
||||
|
||||
- Can it run with Ollama locally?
|
||||
- Can its story-tree/history system support simple user-facing Undo/Redo/Retry behavior?
|
||||
- Does state rollback work independently of heavy RPG/stat mechanics?
|
||||
- Can RPG-specific state be left empty/minimal without breaking the useful history/state architecture?
|
||||
- Can QuickJS/scripting and hosted/cloud-oriented features be disabled without breaking local story operation?
|
||||
- Can local memory/embedding behavior work without cloud services?
|
||||
- Do memories/state respect the active history path?
|
||||
- Is its context/Insights system useful for showing what was sent to the model?
|
||||
|
||||
Use a small disposable experiment if necessary.
|
||||
|
||||
Do **not** start stripping the whole application down.
|
||||
|
||||
## 6. Focused Experiment B — Open Dungeon
|
||||
|
||||
We want to know how expensive it would be to fix its history model.
|
||||
|
||||
Test:
|
||||
|
||||
- Confirm how Retry/Edit/Erase affect stored history.
|
||||
- Identify whether old future turns are deleted.
|
||||
- Trace which parts of the application depend on that linear/destructive behavior.
|
||||
- Estimate how invasive it would be to change to:
|
||||
- parent-linked turns,
|
||||
- active head,
|
||||
- retained abandoned history,
|
||||
- named checkpoints,
|
||||
- lineage-safe summaries/state.
|
||||
|
||||
Do not implement the complete branch system.
|
||||
|
||||
Also record useful existing pieces:
|
||||
- browser UX,
|
||||
- local image generation,
|
||||
- character visual continuity,
|
||||
- any scene/media architecture worth reusing.
|
||||
|
||||
## 7. Focused Experiment C — ai-adventure
|
||||
|
||||
We want to know whether its strong state/privacy architecture can realistically become a browser-based Ollama application.
|
||||
|
||||
Test:
|
||||
|
||||
- Run the existing tests.
|
||||
- Confirm Undo/branch/checkpoint/replay behavior.
|
||||
- Identify the provider abstraction.
|
||||
- Prove one local Ollama-backed story turn using the smallest practical adapter.
|
||||
- Determine how tightly the core application logic is coupled to the CLI.
|
||||
- Assess whether the core could sit behind a browser/API layer without moving authoritative state logic.
|
||||
- Review its local lore/FTS approach for possible reuse.
|
||||
|
||||
Do not build a browser frontend.
|
||||
|
||||
## 8. Offline / Privacy Check
|
||||
|
||||
For each candidate, once dependencies/models are installed:
|
||||
|
||||
- run it with outbound Internet unavailable or blocked where practical,
|
||||
- exercise basic story generation,
|
||||
- note any unexpected network attempts.
|
||||
|
||||
We do not need a full penetration test in this round.
|
||||
|
||||
We do need to know:
|
||||
|
||||
- whether local story use truly works offline,
|
||||
- whether cloud services are required,
|
||||
- whether analytics/telemetry/remote assets are present,
|
||||
- how difficult those paths would be to remove.
|
||||
|
||||
## 9. Use the Standard Fixture Selectively
|
||||
|
||||
Use `TEST-CAMPAIGN-FIXTURE.md` where it helps answer continuity questions.
|
||||
|
||||
You do not need to execute the entire fixture against every candidate.
|
||||
|
||||
The most important checks are:
|
||||
|
||||
- possession/state consistency,
|
||||
- restore/undo behavior,
|
||||
- abandoned-path isolation,
|
||||
- whether an old discarded fact can leak into current memory/context.
|
||||
|
||||
## 10. What Not to Do
|
||||
|
||||
Do not:
|
||||
|
||||
- build the production fork,
|
||||
- merge repositories,
|
||||
- redesign the full UI,
|
||||
- implement full RAG,
|
||||
- implement complete branching in Open Dungeon,
|
||||
- remove all RPG code from AI-DnD,
|
||||
- build a browser frontend for ai-adventure,
|
||||
- add image/video/TTS/STT features,
|
||||
- write the final production milestone plan.
|
||||
|
||||
Small disposable code changes are allowed only when needed to answer the evaluation questions.
|
||||
|
||||
## 11. Final Deliverable
|
||||
|
||||
The main output from this round should be a single recommendation document:
|
||||
|
||||
```text
|
||||
PHASE-0B-RECOMMENDATION.md
|
||||
```
|
||||
|
||||
It should summarize what was learned, not just list test logs.
|
||||
|
||||
Include:
|
||||
|
||||
### A. Executive Recommendation
|
||||
|
||||
- Which repository should be the production base?
|
||||
- Confidence level: high / medium / low.
|
||||
- Did the initial AI-DnD recommendation hold up?
|
||||
|
||||
### B. What We Learned About Each Candidate
|
||||
|
||||
For each:
|
||||
- what worked,
|
||||
- what failed,
|
||||
- strongest reusable pieces,
|
||||
- major architectural problems,
|
||||
- likely amount/type of adaptation required.
|
||||
|
||||
### C. Key Technical Findings
|
||||
|
||||
Especially:
|
||||
- history/undo model,
|
||||
- state rollback,
|
||||
- memory isolation,
|
||||
- local Ollama support,
|
||||
- offline/privacy behavior,
|
||||
- browser suitability,
|
||||
- imported-knowledge potential,
|
||||
- future media extension potential.
|
||||
|
||||
### D. Important Surprises
|
||||
|
||||
Anything that contradicts the current planning assumptions.
|
||||
|
||||
### E. Recommendation for Next Step
|
||||
|
||||
Do **not** perform the next step.
|
||||
|
||||
Instead recommend what should happen next, such as:
|
||||
- fork AI-DnD and begin a controlled strip-down,
|
||||
- perform one additional experiment first,
|
||||
- reconsider Open Dungeon,
|
||||
- use ai-adventure as the base instead,
|
||||
- revise one of the product assumptions.
|
||||
|
||||
### F. Open Questions
|
||||
|
||||
List anything that could not be resolved in this round.
|
||||
|
||||
## 12. Supporting Evidence
|
||||
|
||||
You may also create concise supporting notes/logs for:
|
||||
|
||||
- baseline results,
|
||||
- AI-DnD experiment,
|
||||
- Open Dungeon history analysis,
|
||||
- ai-adventure Ollama adapter,
|
||||
- offline/network observations.
|
||||
|
||||
Keep them concise.
|
||||
|
||||
The recommendation document is the primary deliverable.
|
||||
|
||||
## 13. Stop Condition
|
||||
|
||||
When `PHASE-0B-RECOMMENDATION.md` is complete, stop.
|
||||
|
||||
We will take the findings back into the design discussion, re-examine the assumptions, and decide the next step before any production implementation begins.
|
||||
@@ -1,277 +0,0 @@
|
||||
# Phase 0B — Codex Local Validation Handoff
|
||||
|
||||
**Status:** COMPLETE / HISTORICAL — do not execute as a production prompt
|
||||
**Purpose:** Validate the Phase 0A recommendation using local builds, tests, offline runtime observation, and tightly scoped experiments.
|
||||
**Stop rule:** Do not begin production implementation.
|
||||
|
||||
## 1. Read Before Starting
|
||||
|
||||
Read the package in the order listed in `README.md`.
|
||||
|
||||
At minimum, before modifying any finalist, read:
|
||||
|
||||
1. `SPECIFICATION.md`
|
||||
2. `DATA-MODEL.md`
|
||||
3. `STORY-BRANCH-SEMANTICS.md`
|
||||
4. `CONTEXT-AND-MEMORY.md`
|
||||
5. `IMPORTED-KNOWLEDGE-DESIGN.md`
|
||||
6. `SECURITY-THREAT-MODEL.md`
|
||||
7. `MEDIA-EXTENSION-CONTRACT.md`
|
||||
8. `BROWSER-UX-SPEC.md`
|
||||
9. `TEST-CAMPAIGN-FIXTURE.md`
|
||||
10. `V1-ACCEPTANCE-TESTS.md`
|
||||
11. `reports/PRELIMINARY-RECOMMENDATION.md`
|
||||
12. `reports/REUSE-MATRIX.md`
|
||||
|
||||
Treat the detailed behavioral documents and acceptance tests as the target behavior. Treat `TECHNICAL-DESIGN.md` as provisional.
|
||||
|
||||
## 2. Finalists to Clone
|
||||
|
||||
Clone only these three primary finalists for Phase 0B:
|
||||
|
||||
1. https://github.com/parththakkar106/AI-DnD
|
||||
2. https://github.com/newideas99/open-dungeon
|
||||
3. https://github.com/CaoRuiming/ai-adventure
|
||||
|
||||
At clone time record exact commit SHA, branch/tag, date, license, dependency lockfiles, required runtimes, and documented local model/provider assumptions.
|
||||
|
||||
Keep each upstream clone clean. Use separate experiment branches/worktrees for disposable changes. Do not merge candidate repositories together.
|
||||
|
||||
## 3. Result Codes
|
||||
|
||||
Use consistently:
|
||||
|
||||
```text
|
||||
PASS
|
||||
PARTIAL
|
||||
FAIL
|
||||
NOT IMPLEMENTED
|
||||
NOT APPLICABLE
|
||||
```
|
||||
|
||||
Do not convert an untested requirement into a PASS.
|
||||
|
||||
## 4. Validation V0 — Environment and Baseline
|
||||
|
||||
For all three:
|
||||
|
||||
- install from documented instructions,
|
||||
- run existing test suite,
|
||||
- run build/lint/typecheck where applicable,
|
||||
- record failures,
|
||||
- record actual current test count,
|
||||
- record local data paths,
|
||||
- record listening ports,
|
||||
- record child processes/services,
|
||||
- record model/provider configuration,
|
||||
- record database/storage technology.
|
||||
|
||||
Deliver one baseline report per project. Do not rely on README claims for test counts or feature behavior.
|
||||
|
||||
## 5. Validation V1 — Offline and Network Behavior
|
||||
|
||||
After dependencies and local models are already installed, block outbound Internet and exercise launch, story creation, 5+ turns, restart/resume, summaries, memory/embeddings if present, Retry, Undo/rewind, checkpoint/branch features if present, `.txt`/`.md` import if present, and Open Dungeon local image generation if configured.
|
||||
|
||||
Capture open sockets, DNS attempts, HTTP(S)/WebSocket destinations, and which feature caused each request.
|
||||
|
||||
Use `SECURITY-THREAT-MODEL.md` and acceptance groups A, G, and H.
|
||||
|
||||
Pass condition for target v1 operation:
|
||||
|
||||
> Story content, imported knowledge, prompt/context data, and media prompts do not leave loopback or explicitly approved local endpoints.
|
||||
|
||||
## 6. Standard Fixture Use
|
||||
|
||||
Use `TEST-CAMPAIGN-FIXTURE.md` as the standard narrative test bed.
|
||||
|
||||
Where a finalist cannot represent the fixture directly, map it as closely as possible, document the mismatch, and do not silently change expected truth/state to suit the candidate.
|
||||
|
||||
Important checks:
|
||||
|
||||
- Mara's knowledge boundaries,
|
||||
- Silver Key ownership,
|
||||
- resurrection canon,
|
||||
- Canon vs Reference vs Inspiration authority,
|
||||
- Path A secret followed by restore/divergence into Path B,
|
||||
- abandoned-history memory isolation,
|
||||
- long-term memory plant,
|
||||
- checkpoint persistence,
|
||||
- science-fiction variant.
|
||||
|
||||
## 7. Acceptance-Test Mapping
|
||||
|
||||
Use `V1-ACCEPTANCE-TESTS.md` as the common comparison contract. Produce a gap matrix rather than forcing each candidate to fully pass v1.
|
||||
|
||||
Use these interpretations:
|
||||
|
||||
```text
|
||||
Already passes
|
||||
Passes with configuration
|
||||
Small adaptation
|
||||
Foundational redesign
|
||||
Not present
|
||||
```
|
||||
|
||||
Prioritize high-risk groups:
|
||||
|
||||
- A01-A05 — local operation/persistence
|
||||
- C01-C05 — canon/state
|
||||
- D01-D14 — Undo/Redo/Retry/checkpoints
|
||||
- E01-E04 — lineage safety
|
||||
- F01-F08 — memory/context
|
||||
- G01-G10 — imported knowledge where supported
|
||||
- H01-H10 — security/privacy
|
||||
- J01-J03 — genre independence
|
||||
- K01-K04 — media readiness
|
||||
- L01-L04 — data integrity
|
||||
|
||||
Long-run M01-M04 need not be fully executed against every candidate if disproportionate; identify production risk and existing test coverage instead.
|
||||
|
||||
## 8. Experiment V2 — AI-DnD Strip-Down Feasibility
|
||||
|
||||
Do not redesign the application.
|
||||
|
||||
Answer:
|
||||
|
||||
1. Can a scenario run with RPG stats absent, empty, or minimal?
|
||||
2. Do branch/retry/undo/tree tests operate independently of RPG mechanics?
|
||||
3. Can user-facing tree complexity be hidden behind `STORY-BRANCH-SEMANTICS.md`?
|
||||
4. Disable QuickJS scripting. What breaks?
|
||||
5. Disable/remove hosted multi-user/auth/demo/analytics paths. What breaks locally?
|
||||
6. Configure only local Ollama generation.
|
||||
7. Configure only local embeddings, preferably Ollama/local.
|
||||
8. Verify branch switching restores correct generic state.
|
||||
9. Verify memory retrieval respects active lineage.
|
||||
10. Test whether abandoned Path A facts leak into Path B.
|
||||
11. Map Story Cards/world-info to Canon / Reference / Inspiration.
|
||||
12. Determine whether prompt/context snapshots satisfy Context Inspector requirements.
|
||||
13. Determine whether visual/scene snapshot data can be added without RPG coupling.
|
||||
14. Inventory code coupled to RPG worldstate, scripting, hosted auth, analytics, remote providers, and AI Dungeon compatibility.
|
||||
|
||||
Estimate invasiveness by affected files/modules, not hours. Do not merge the experiment.
|
||||
|
||||
## 9. Experiment V3 — Open Dungeon Branch Retrofit Impact
|
||||
|
||||
Do not implement full branching.
|
||||
|
||||
Trace message CRUD, Retry, Erase, Edit, Continue, summary generation, state/character persistence, image association, and visual continuity. Confirm destructive-tail assumptions.
|
||||
|
||||
Design a minimal hypothetical persistence change supporting:
|
||||
|
||||
```text
|
||||
turn/node ID
|
||||
parent turn ID
|
||||
active head
|
||||
alternate narrator takes
|
||||
retained disposable history
|
||||
checkpoint pointer
|
||||
lineage-safe summaries/memories
|
||||
```
|
||||
|
||||
Use the standard fixture to reason through Undo/restore, Path A -> Path B divergence, stale summary/state risks, and image attachment after divergence.
|
||||
|
||||
Also inspect local image/provider patterns for reuse. Measure invasiveness; do not build the branch system.
|
||||
|
||||
## 10. Experiment V4 — ai-adventure Ollama / Service Boundary
|
||||
|
||||
1. Run existing tests unchanged.
|
||||
2. Identify provider interface.
|
||||
3. Prove one Ollama-backed turn using the smallest disposable adapter possible.
|
||||
4. Identify modules that know about the CLI.
|
||||
5. Determine whether the app/state layer can be wrapped by a browser/API service without moving authoritative logic.
|
||||
6. Verify undo, branch, checkpoint, restore, replay.
|
||||
7. Evaluate event/commit discipline for reuse.
|
||||
8. Evaluate its FTS/lore system against `IMPORTED-KNOWLEDGE-DESIGN.md`.
|
||||
9. Determine difficulty of adding semantic local retrieval while preserving lexical retrieval.
|
||||
10. Check privacy boundary with the Ollama adapter.
|
||||
|
||||
Do not build a browser UI.
|
||||
|
||||
## 11. Validation V5 — Test Quality
|
||||
|
||||
For each finalist report actual test count, categories, branch/rollback coverage, state reconstruction, migrations, summary/memory coverage, provider mocks, offline/network tests, browser tests, security tests, flaky/failing tests, and tests requiring Internet.
|
||||
|
||||
Highlight which high-risk acceptance requirements already have regression coverage.
|
||||
|
||||
## 12. Validation V6 — Imported Knowledge Gap Analysis
|
||||
|
||||
Against `IMPORTED-KNOWLEDGE-DESIGN.md`, report local `.txt`/`.md` ingestion, classifications, campaign isolation, provenance, lexical/semantic search, embedding provider, enable/disable, deletion, export/import, hidden canon, prompt-injection framing, and remote URL/image behavior.
|
||||
|
||||
Do not implement a full new RAG subsystem during Phase 0B.
|
||||
|
||||
## 13. Validation V7 — Browser UX Gap Analysis
|
||||
|
||||
Against `BROWSER-UX-SPEC.md`, report story reading/input quality, streaming, Undo/Redo/Retry UI, alternate-take selection, edit behavior, Save Points, state inspection, knowledge management, prompt/context inspection, local-model status, and advanced complexity exposed to the user.
|
||||
|
||||
Explicitly identify AI-DnD components worth retaining and Open Dungeon components worth borrowing/reimplementing. Do not redesign the frontend.
|
||||
|
||||
## 14. Validation V8 — Future Media and Speech Readiness
|
||||
|
||||
Against `MEDIA-EXTENSION-CONTRACT.md`, determine whether the architecture can support future local image generation, video generation, audio/ambience, text-to-speech, and speech-to-text.
|
||||
|
||||
For STT, verify the architecture can support:
|
||||
|
||||
```text
|
||||
local microphone/audio
|
||||
->
|
||||
local STT provider
|
||||
->
|
||||
editable draft text
|
||||
->
|
||||
normal user submission
|
||||
```
|
||||
|
||||
STT output must not bypass the normal story commit path.
|
||||
|
||||
Do not implement STT/TTS/video during Phase 0B. Open Dungeon local image behavior may be exercised because it already exists.
|
||||
|
||||
## 15. Final Acceptance Gap Matrix
|
||||
|
||||
Produce a matrix organized by acceptance-test group covering A, C, D, E, F, G, H, I, J, K, L, plus UX fit. Include production impact for each gap.
|
||||
|
||||
## 16. Final Decision Matrix
|
||||
|
||||
Return:
|
||||
|
||||
| Question | AI-DnD | Open Dungeon | ai-adventure |
|
||||
|---|---|---|---|
|
||||
| Baseline builds | | | |
|
||||
| Existing tests pass | | | |
|
||||
| Runs offline after setup | | | |
|
||||
| Ollama works | | | |
|
||||
| History semantics fit | | | |
|
||||
| State authority fits | | | |
|
||||
| Memory/lineage fits | | | |
|
||||
| Imported knowledge fit | | | |
|
||||
| Prompt inspection fit | | | |
|
||||
| Security/local-only hardening | | | |
|
||||
| Unwanted-code removal scope | | | |
|
||||
| Browser UX fit | | | |
|
||||
| Media extension fit | | | |
|
||||
| Future TTS/STT fit | | | |
|
||||
| Major blockers | | | |
|
||||
|
||||
## 17. Recommendation Report
|
||||
|
||||
The final recommendation should answer:
|
||||
|
||||
1. Which single repository should be the production base?
|
||||
2. Why?
|
||||
3. What are the top architectural risks?
|
||||
4. What must be removed?
|
||||
5. What must be generalized?
|
||||
6. Which concepts/components should be reimplemented from other candidates?
|
||||
7. Does Phase 0B change the preliminary AI-DnD recommendation?
|
||||
8. Which open questions remain before `TECHNICAL-DESIGN.md` v1.0?
|
||||
9. Are any v1 requirements likely to need reconsideration because of real technical constraints?
|
||||
10. Is unlimited Undo straightforward? If not, what practical limit exists and why?
|
||||
|
||||
Use evidence, not repository popularity or feature count.
|
||||
|
||||
## 18. Stop Condition
|
||||
|
||||
Stop after baseline reports, offline/network evidence, three scoped experiments, test-quality report, acceptance-gap matrix, decision matrix, and final recommendation.
|
||||
|
||||
Do not start the production fork conversion, implement the complete branch system, build the final browser UI, implement full RAG, add video/TTS/STT, rewrite the production technical design, or write production milestones.
|
||||
|
||||
Return reports and experiment diffs/results for review. The fork/architecture decision will be made from those results.
|
||||
@@ -1,49 +0,0 @@
|
||||
# Planning Update Summary — Post Phase 0B Review
|
||||
|
||||
**Date:** 2026-09-01
|
||||
**Purpose:** Review aid. This file summarizes planning changes made after accepting the ten architecture decisions from the Phase 0B review.
|
||||
|
||||
## New Decisions Recorded
|
||||
|
||||
1. AI-DnD is the production base at pinned Phase 0B commit `d72f7c1b...`.
|
||||
2. AI-DnD's browser/service/story-tree/memory/context foundation is retained as the ownership center.
|
||||
3. The non-destructive head-cursor Undo/Redo spike is promoted into the production design, but the disposable spike is not treated as merge-ready production code.
|
||||
4. Narrative state will use explicit typed events/absolute assignments inspired by ai-adventure, not AI-DnD's relative-delta protocol.
|
||||
5. ai-adventure is an implementation reference, not the product specification.
|
||||
6. Open Dungeon is a UX/media reference only.
|
||||
7. Abandoned history is retained and marked disposable; no automatic cleanup is required in v1.
|
||||
8. Export/import must preserve active head position as part of the history work.
|
||||
9. Imported knowledge will be a separate first-class subsystem rather than an extension of Story Cards.
|
||||
10. Future image/video/audio/TTS/STT extension contracts remain, but no media generation is required for v1.
|
||||
11. Local-only inference may span user-controlled machines: same-host Ollama is the default, but an explicitly configured trusted-LAN Ollama host is supported in v1 without exposing the storyteller UI/API to the LAN.
|
||||
|
||||
## Documents Materially Revised
|
||||
|
||||
- `README.md`
|
||||
- `SPECIFICATION.md`
|
||||
- `TECHNICAL-DESIGN.md`
|
||||
- `DATA-MODEL.md`
|
||||
- `STORY-BRANCH-SEMANTICS.md`
|
||||
- `CONTEXT-AND-MEMORY.md`
|
||||
- `IMPORTED-KNOWLEDGE-DESIGN.md`
|
||||
- `SECURITY-THREAT-MODEL.md`
|
||||
- `V1-ACCEPTANCE-TESTS.md`
|
||||
- `BUILD-MILESTONES.md`
|
||||
- `RESEARCH-PLAN.md`
|
||||
- `CODEX-HANDOFF-NOTE.md`
|
||||
- `004-local-only-production.md`
|
||||
- `005-branch-preserving-history.md`
|
||||
- `008-phase0-before-build-plan.md`
|
||||
|
||||
## New ADRs
|
||||
|
||||
- `009-ai-dnd-production-base.md`
|
||||
- `010-explicit-typed-narrative-state-events.md`
|
||||
|
||||
## Historical Evidence Intentionally Preserved
|
||||
|
||||
The Phase 0A candidate reports and the coding agent's `PHASE-0B-RECOMMENDATION.md` remain research evidence. They may contain assumptions that are superseded by the current planning documents. They are not silently rewritten to make the historical analysis appear as if it had reached later conclusions originally.
|
||||
|
||||
## Coding Prompt Status
|
||||
|
||||
No next Codex implementation prompt is included in this revision.
|
||||
@@ -0,0 +1,121 @@
|
||||
# ChatGPT Project Sources — what to upload
|
||||
|
||||
This file exists for one purpose: to tell the repository owner which files
|
||||
belong in the **InteractiveStory** ChatGPT project's Sources. It is not a
|
||||
documentation index — `planning/README.md` is that.
|
||||
|
||||
`planning/project-sources.txt` is the same list as bare paths, one per line, for
|
||||
gathering the files.
|
||||
|
||||
The rule behind the list: **upload what is authoritative now.** A project source
|
||||
is treated as current fact by whatever reads it, so a superseded document
|
||||
uploaded alongside a current one does not add context — it manufactures a
|
||||
conflict.
|
||||
|
||||
Refresh the Sources whenever the planning package is revised (`VERSION.md`
|
||||
records each revision) and whenever a milestone completes.
|
||||
|
||||
## REQUIRED PROJECT SOURCES
|
||||
|
||||
Twenty-eight files.
|
||||
|
||||
**Repository orientation**
|
||||
|
||||
```text
|
||||
README.md
|
||||
DEVELOPMENT.md
|
||||
PROVENANCE.md
|
||||
```
|
||||
|
||||
**The planning index and its version**
|
||||
|
||||
```text
|
||||
planning/README.md
|
||||
planning/VERSION.md
|
||||
```
|
||||
|
||||
**Product requirements and design**
|
||||
|
||||
```text
|
||||
planning/SPECIFICATION.md
|
||||
planning/TECHNICAL-DESIGN.md
|
||||
planning/DATA-MODEL.md
|
||||
planning/STORY-BRANCH-SEMANTICS.md
|
||||
planning/CONTEXT-AND-MEMORY.md
|
||||
planning/IMPORTED-KNOWLEDGE-DESIGN.md
|
||||
planning/SECURITY-THREAT-MODEL.md
|
||||
planning/MEDIA-EXTENSION-CONTRACT.md
|
||||
planning/BROWSER-UX-SPEC.md
|
||||
```
|
||||
|
||||
**Implementation plan and acceptance contract**
|
||||
|
||||
```text
|
||||
planning/BUILD-MILESTONES.md
|
||||
planning/V1-ACCEPTANCE-TESTS.md
|
||||
planning/TEST-CAMPAIGN-FIXTURE.md
|
||||
```
|
||||
|
||||
**The active ADRs** — all eleven. They are short, and each one closes a question
|
||||
that will otherwise be reopened.
|
||||
|
||||
```text
|
||||
planning/DECISIONS/001-browser-first.md
|
||||
planning/DECISIONS/002-ollama-only-v1.md
|
||||
planning/DECISIONS/003-authoritative-local-state.md
|
||||
planning/DECISIONS/004-local-only-production.md
|
||||
planning/DECISIONS/005-branch-preserving-history.md
|
||||
planning/DECISIONS/006-genre-agnostic-core.md
|
||||
planning/DECISIONS/007-future-media-extension.md
|
||||
planning/DECISIONS/009-ai-dnd-production-base.md
|
||||
planning/DECISIONS/010-explicit-typed-narrative-state-events.md
|
||||
planning/DECISIONS/011-local-inference-endpoint-policy.md
|
||||
planning/DECISIONS/012-active-head-non-destructive-history.md
|
||||
```
|
||||
|
||||
ADR **008** is deliberately absent: it was the process gate requiring Phase 0 to
|
||||
close before production work began, Phase 0 closed on 2026-09-01, and it is now
|
||||
in `planning/archive/decisions/`.
|
||||
|
||||
## CURRENT-MILESTONE SOURCE
|
||||
|
||||
One file, and it changes as development progresses:
|
||||
|
||||
```text
|
||||
planning/reports/M3-IMPLEMENTATION-REPORT.md
|
||||
```
|
||||
|
||||
M3 is the most recently completed milestone, and M4 is the next to be briefed.
|
||||
This report is M3's review *and* its primary evidence record — no separate M3
|
||||
baseline report was produced — so it is the only place some of what M3 left
|
||||
behind is written down, including the browser smoke test M3 still owes.
|
||||
|
||||
**Replace it, do not accumulate.** When M4's report lands, remove this one from
|
||||
the project Sources and upload M4's instead. The repository does the same thing:
|
||||
`planning/reports/` holds the current milestone's report and
|
||||
`planning/archive/milestone-reports/` holds the rest.
|
||||
|
||||
## DO NOT UPLOAD AS PROJECT SOURCES
|
||||
|
||||
Not because these are worthless — because a source is read as current fact, and
|
||||
these are not current.
|
||||
|
||||
- **Everything under `planning/archive/`.** The Phase 0 research reports, the
|
||||
Phase 0B recommendation and spikes, the completed M1 and M2 milestone reports,
|
||||
and archived ADR 008. Every conclusion they reached that still matters has
|
||||
already been applied to the active documents; what is left is superseded
|
||||
reasoning that will contradict the current package if uploaded beside it.
|
||||
- **Older milestone reports**, once their successor exists. Uploading M1, M2 and
|
||||
M3 together produces three descriptions of the same subsystem at three
|
||||
different stages.
|
||||
- **Source code.** `backend/`, `frontend/`, tests, migrations. The planning
|
||||
package describes the system; the code is read in the repository, where it can
|
||||
be searched and run.
|
||||
- **Inherited upstream documentation.** Upstream AI-DnD's `plan/` build log and
|
||||
`docs/` guides, generated HTML and screenshots were deleted from this
|
||||
repository on 2026-09-03 for exactly this reason: they describe a hosted,
|
||||
scripted, multi-user product this fork removed. Do not re-upload them from
|
||||
upstream or from Git history.
|
||||
- **Generated HTML, images and screenshots.** They add tokens, not facts.
|
||||
- **`repo-inventory.txt` or any other local scratch output.** Not tracked, not
|
||||
authoritative, stale the moment it is written.
|
||||
+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
|
||||
|
||||
@@ -184,7 +184,7 @@ controls on a network they trust — and why the endpoint is always explicitly
|
||||
configured, never discovered.
|
||||
|
||||
See ADR 002 (*Transport for a Trusted-LAN Endpoint*) and, for the demonstrated
|
||||
deployment, `planning/reports/M1-IMPLEMENTATION-REPORT.md` §F.
|
||||
deployment, `planning/archive/milestone-reports/M1-IMPLEMENTATION-REPORT.md` §F.
|
||||
|
||||
Allowed future local paths may also include explicitly configured local media services.
|
||||
|
||||
|
||||
+41
-5
@@ -1,8 +1,44 @@
|
||||
# Planning Package Version
|
||||
|
||||
**Package:** Adventure Storyteller Planning Package v2.3
|
||||
**Revision date:** 2026-09-03
|
||||
**Status:** Phase 0 complete; architecture selected; **Milestones M1, M2 and M3 implemented and accepted**; M4 is next to brief.
|
||||
- **Package:** Adventure Storyteller Planning Package v2.4
|
||||
- **Revision date:** 2026-09-03
|
||||
- **Status:** Phase 0 complete; architecture selected; **Milestones M1, M2 and M3 implemented and accepted**; M4 is next to brief.
|
||||
|
||||
## v2.4 — Documentation Consolidation (2026-09-03)
|
||||
|
||||
No product requirement, architecture decision or milestone status changed in
|
||||
this revision. It reorganises the documentation so that a new coding agent can
|
||||
tell authoritative material from evidence at a glance.
|
||||
|
||||
- `planning/archive/` is created and is **non-authoritative by declaration**
|
||||
(`archive/README.md`). It holds `phase0/` — the research that chose AI-DnD —
|
||||
`milestone-reports/` — the completed M1 and M2 reports — and `decisions/`,
|
||||
which now holds ADR **008**, the Phase-0-before-build process gate that Phase 0
|
||||
satisfied. ADR numbering continues from 012; 008 is not reused.
|
||||
- `planning/reports/` now holds **only the current milestone's report**,
|
||||
`M3-IMPLEMENTATION-REPORT.md`, because M4 planning has to consult it. It moves
|
||||
to the archive when M4's report replaces it.
|
||||
- The Phase 0B execution prompts and handoff/status/summary documents
|
||||
(`CODEX-HANDOFF-NOTE.md`, `PHASE-0B-CODEX-BRIEF.md`,
|
||||
`PHASE-0B-CODEX-HANDOFF.md`, `PLANNING-UPDATE-SUMMARY.md`) and the Phase 0A
|
||||
discovery and triage reports were **deleted**: intermediate working documents
|
||||
whose conclusions all reached the two recommendation reports, and which remain
|
||||
in Git history.
|
||||
- Upstream AI-DnD's inherited `plan/` build log and `docs/` project site
|
||||
(guides, generated HTML, screenshots) were **deleted**. They documented a
|
||||
hosted, scripted, multi-user product with accounts — every screenshot showed a
|
||||
Scripts tab and a Sign up button — which M2 removed. Both trees remain in Git
|
||||
history and in upstream.
|
||||
- `README.md`, `DEVELOPMENT.md` and `PROVENANCE.md` are corrected where they
|
||||
pointed at the removed trees or described removed capability as present.
|
||||
`DEVELOPMENT.md`'s "things M1 did not touch" section had gone stale at M2 and
|
||||
now says what is actually still inherited.
|
||||
- `planning/README.md` is rewritten as **the documentation index**: current
|
||||
milestone, the three-way active/ADR/archive split, the authority order,
|
||||
reading order, where reports live, and what comes next. The milestone
|
||||
correction tables are preserved unchanged.
|
||||
- New: `planning/PROJECT-SOURCES.md` and `planning/project-sources.txt`, the
|
||||
manifest of files to upload as ChatGPT Project Sources.
|
||||
|
||||
## v2.3 — Post-M3 Closeout (2026-09-03)
|
||||
|
||||
@@ -51,7 +87,7 @@ M2 removed the hosted, cloud, account and scripting surface and added the
|
||||
inference endpoint policy. Its review recommended six planning changes and
|
||||
reported rather than applied them; all six are applied in this revision, listed
|
||||
in `README.md` § *Post-M2 corrections applied*, with the evidence in
|
||||
`reports/M2-BASELINE-REPORT.md` and `reports/M2-IMPLEMENTATION-REPORT.md`.
|
||||
`archive/milestone-reports/M2-BASELINE-REPORT.md` and `archive/milestone-reports/M2-IMPLEMENTATION-REPORT.md`.
|
||||
|
||||
In summary:
|
||||
|
||||
@@ -84,7 +120,7 @@ the architecture selected in v2 was reversed.
|
||||
M1 implementation evidence contradicted or under-specified parts of v2. The
|
||||
corrections are recorded in the documents themselves and listed in
|
||||
`README.md` § *Post-M1 corrections applied*; the evidence behind them is in
|
||||
`reports/M1-BASELINE-REPORT.md` and `reports/M1-IMPLEMENTATION-REPORT.md`.
|
||||
`archive/milestone-reports/M1-BASELINE-REPORT.md` and `archive/milestone-reports/M1-IMPLEMENTATION-REPORT.md`.
|
||||
|
||||
In summary:
|
||||
|
||||
|
||||
@@ -0,0 +1,67 @@
|
||||
# Archive — historical material, not authoritative
|
||||
|
||||
Everything under `planning/archive/` is **evidence and history**. None of it
|
||||
governs current implementation. If an archived document and an active planning
|
||||
document disagree, the active document is right and the archived one records
|
||||
what was believed or measured at the time.
|
||||
|
||||
Do not consult this directory during ordinary milestone work unless an active
|
||||
document sends you here for a specific piece of historical evidence.
|
||||
|
||||
## What is here
|
||||
|
||||
### `phase0/` — why AI-DnD was selected
|
||||
|
||||
Phase 0A static research and Phase 0B local validation, closed 2026-09-01.
|
||||
|
||||
| File | What it is |
|
||||
| --- | --- |
|
||||
| `RESEARCH-PLAN.md` | The question Phase 0 existed to answer, and its final dispositions. |
|
||||
| `PRELIMINARY-RECOMMENDATION.md` | The Phase 0A conclusion, from static review alone. |
|
||||
| `REUSE-MATRIX.md` | What each candidate offered against the required subsystems. |
|
||||
| `AI-DND-ANALYSIS.md` | The selected base, analysed before the fork. |
|
||||
| `AI-ADVENTURE-ANALYSIS.md` | The rejected finalist still cited as the implementation reference for typed state events. |
|
||||
| `OPEN-DUNGEON-ANALYSIS.md` | The rejected finalist still cited as the UX/future-media reference. |
|
||||
| `PHASE-0B-RECOMMENDATION.md` | **The strongest single document.** The measured Phase 0B findings and the fork decision. |
|
||||
| `PHASE-0B-BASELINE.md` | Clean clones, builds and test runs for the three finalists. |
|
||||
| `PHASE-0B-AI-DND-EXPERIMENT.md` | AI-DnD driven against a real local Ollama. |
|
||||
| `PHASE-0B-AI-ADVENTURE-OLLAMA.md` | ai-adventure's Ollama and service-boundary behaviour. |
|
||||
| `PHASE-0B-OPEN-DUNGEON-HISTORY.md` | Whether Open Dungeon could be retrofitted with history. |
|
||||
| `PHASE-0B-OFFLINE-NETWORK.md` | What each candidate reached for with no route to the Internet. |
|
||||
| `PHASE-0B-UNDO-SPIKE.md` | The disposable spike that proved non-destructive undo/redo, and became ADR 012's architecture. |
|
||||
| `PHASE-0B-FOLLOWUP-CHECKS.md` | The world-state protocol, export/head, story-card lineage and Postgres checks. |
|
||||
|
||||
Phase 0A discovery and triage material (the candidate inventory, source index,
|
||||
reference-project list, licensing and static-privacy reviews, the Phase 0A
|
||||
status page) and the Phase 0B execution prompts were deleted in the 2026-09-03
|
||||
documentation cleanup. They are intermediate working documents whose
|
||||
conclusions all reached the two recommendation reports above, and they remain in
|
||||
Git history.
|
||||
|
||||
### `milestone-reports/` — completed milestone evidence
|
||||
|
||||
`M1-BASELINE-REPORT.md`, `M1-IMPLEMENTATION-REPORT.md`,
|
||||
`M2-BASELINE-REPORT.md`, `M2-IMPLEMENTATION-REPORT.md`.
|
||||
|
||||
Every architectural conclusion these reports reached has already been applied to
|
||||
the active planning documents and the ADRs — see `planning/VERSION.md`, which
|
||||
lists the corrections each milestone produced. The reports are kept for their
|
||||
measurements and their reasoning, not as instructions.
|
||||
|
||||
The **current** milestone's report stays in `planning/reports/` while it is
|
||||
still useful for reviewing the next milestone, and moves here when it is not.
|
||||
|
||||
### `decisions/` — superseded or completed ADRs
|
||||
|
||||
`008-phase0-before-build-plan.md` — a process gate ("do not start production
|
||||
work before Phase 0 closes") that Phase 0 satisfied on 2026-09-01. It
|
||||
constrains nothing now. ADR numbering continues from 012 in
|
||||
`planning/DECISIONS/`; 008 is not reused.
|
||||
|
||||
## A note on paths inside these files
|
||||
|
||||
Archived documents are kept **verbatim**. File paths written inside them refer
|
||||
to where those files lived when the document was written — before this archive
|
||||
existed, and in some cases before files were deleted. That is deliberate: an
|
||||
evidence record that has been quietly edited is no longer evidence. Resolve any
|
||||
such path against Git history, not against the current tree.
|
||||
@@ -0,0 +1,29 @@
|
||||
README.md
|
||||
DEVELOPMENT.md
|
||||
PROVENANCE.md
|
||||
planning/README.md
|
||||
planning/VERSION.md
|
||||
planning/SPECIFICATION.md
|
||||
planning/TECHNICAL-DESIGN.md
|
||||
planning/DATA-MODEL.md
|
||||
planning/STORY-BRANCH-SEMANTICS.md
|
||||
planning/CONTEXT-AND-MEMORY.md
|
||||
planning/IMPORTED-KNOWLEDGE-DESIGN.md
|
||||
planning/SECURITY-THREAT-MODEL.md
|
||||
planning/MEDIA-EXTENSION-CONTRACT.md
|
||||
planning/BROWSER-UX-SPEC.md
|
||||
planning/BUILD-MILESTONES.md
|
||||
planning/V1-ACCEPTANCE-TESTS.md
|
||||
planning/TEST-CAMPAIGN-FIXTURE.md
|
||||
planning/DECISIONS/001-browser-first.md
|
||||
planning/DECISIONS/002-ollama-only-v1.md
|
||||
planning/DECISIONS/003-authoritative-local-state.md
|
||||
planning/DECISIONS/004-local-only-production.md
|
||||
planning/DECISIONS/005-branch-preserving-history.md
|
||||
planning/DECISIONS/006-genre-agnostic-core.md
|
||||
planning/DECISIONS/007-future-media-extension.md
|
||||
planning/DECISIONS/009-ai-dnd-production-base.md
|
||||
planning/DECISIONS/010-explicit-typed-narrative-state-events.md
|
||||
planning/DECISIONS/011-local-inference-endpoint-policy.md
|
||||
planning/DECISIONS/012-active-head-non-destructive-history.md
|
||||
planning/reports/M3-IMPLEMENTATION-REPORT.md
|
||||
@@ -1,46 +0,0 @@
|
||||
# aiMultiFool — Static Architecture Analysis
|
||||
|
||||
**Repository:** https://github.com/omgboohoo/aimultifool
|
||||
**Date reviewed:** 2026-09-01
|
||||
**Disposition:** Reference only.
|
||||
|
||||
## Useful ideas
|
||||
|
||||
aiMultiFool is a local roleplay/chat sandbox with:
|
||||
- Ollama support,
|
||||
- local inference paths,
|
||||
- Vector Chat / semantic-memory concepts,
|
||||
- save/load,
|
||||
- rewind/regenerate,
|
||||
- context inspection,
|
||||
- optional encrypted local data.
|
||||
|
||||
Those are useful implementation references for local memory tooling and diagnostics.
|
||||
|
||||
## Why it is not a fork finalist
|
||||
|
||||
### Product mismatch
|
||||
The interface is terminal/Textual-oriented and character-chat/roleplay focused rather than a browser-first persistent fiction editor.
|
||||
|
||||
### History/context mismatch
|
||||
Its documented smart-pruning strategy removes older middle messages from active chat state as context pressure grows. That is a reasonable chat optimization but not the target architecture. The target must preserve an immutable authoritative transcript and prune only the prompt representation.
|
||||
|
||||
### State model
|
||||
The project does not provide the same authoritative event/state/branch model found in AI-DnD or ai-adventure.
|
||||
|
||||
### License
|
||||
The repository is GPL-3.0. Directly copying substantial GPL code into an MIT/Apache-derived application would change licensing obligations. Unless the final project intentionally adopts GPL-compatible distribution terms, use this project for concepts rather than source copying.
|
||||
|
||||
## Recommended reuse
|
||||
|
||||
Study:
|
||||
- local embedding workflow,
|
||||
- vector inspection/debugging,
|
||||
- encrypted local payload design,
|
||||
- user-facing memory controls.
|
||||
|
||||
Do not make it a Phase 0B build finalist.
|
||||
|
||||
## Source
|
||||
|
||||
- Repository: https://github.com/omgboohoo/aimultifool
|
||||
@@ -1,68 +0,0 @@
|
||||
# Candidate Inventory and Triage
|
||||
|
||||
**Historical status:** Phase 0A triage. The final production disposition was selected after Phase 0B; see ADR 009.
|
||||
|
||||
**Phase:** 0A — Static research
|
||||
**Date:** 2026-09-01
|
||||
|
||||
## Executive result
|
||||
|
||||
Three projects should advance to local validation:
|
||||
|
||||
1. **AI-DnD** — strongest implementation of the hardest required backend capabilities.
|
||||
2. **Open Dungeon** — strongest direct product/UX fit and strongest near-term media path.
|
||||
3. **CaoRuiming/ai-adventure (Local Adventure Engine)** — strongest authoritative-state, replay, checkpoint, and privacy architecture.
|
||||
|
||||
Everything else should remain available as a design/source reference but should not consume local build-validation effort unless one of the three finalists fails.
|
||||
|
||||
## Triage table
|
||||
|
||||
| Project | Browser-first | Ollama | Durable branch/rollback | Long memory | Local knowledge | Future media | Static disposition |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| AI-DnD | Yes | Yes | **Strong** | **Strong** | Story cards + memory | Not core | **Finalist #1** |
|
||||
| Open Dungeon | **Yes** | **Yes** | Weak / destructive linear tail today | Summary-based | Limited | **Strong; local image generation already present** | **Finalist #2** |
|
||||
| ai-adventure | No; CLI | LM Studio today | **Strong** | Summary + lore FTS | **Strong deterministic local lore** | No | **Finalist #3** |
|
||||
| Chronicler | Yes | Yes | Not the focus | **Excellent memory model** | Memory-centric | No | Reference |
|
||||
| Gamentic | **Yes** | llama.cpp/OpenAI-compatible | Game-state oriented | Strong | World bible | **Excellent image/voice provider design** | Reference |
|
||||
| Interactive Fiction Framework | **Yes** | **Yes** | Not established as required story-tree model | Canon/scene/character memory | Story Bible | Not core | Reference |
|
||||
| Sonder Engine | **Yes** | **Yes** | Persistent variants/checkpoints, but much more agentic | **Very sophisticated** | Character-scoped retrieval | Not primary | Reference |
|
||||
| Corvus Story Core | **Yes** | OpenAI-compatible | No equivalent branch tree established | Summaries + state | World/state | ComfyUI + TTS | Reference |
|
||||
| aiMultiFool | No; terminal | **Yes** | Rewind, not target architecture | Vector chat | RAG-oriented | No | Reference only |
|
||||
| SillyTavern | **Yes** | Local backends | Chat-oriented | Extensions/lorebooks | **Excellent lorebook UX** | Broad extensions | Reference only |
|
||||
| RisuAI | **Yes** | Local/remote ecosystem | Chat-oriented | Hypa/SupaMemory | Lorebooks | Broad media | Reference only |
|
||||
| KoboldAI | **Yes** | Local ecosystem | Traditional save/load | Memory/World Info | World Info | Limited | Reference only |
|
||||
|
||||
## Why the shortlist is only three
|
||||
|
||||
### AI-DnD advances because
|
||||
It already implements the expensive correctness work: a parent/lineage story tree, alternate takes, non-destructive retry, state snapshots and rollback, branch-aware context, summaries, embedding retrieval, story cards, exact prompt inspection, export/import of the complete tree, and a substantial automated test suite.
|
||||
|
||||
### Open Dungeon advances because
|
||||
It is almost exactly the desired product shape: browser-first, simple interactive fiction, Ollama, local SQLite, streaming narration, visual character continuity, and local image-generation hooks. Its key weakness is architectural rather than cosmetic: its current message schema is linear and its retry/erase operation deletes the selected message and the rest of the tail.
|
||||
|
||||
### ai-adventure advances because
|
||||
Its core philosophy most closely matches the required trust model. SQLite and typed events are authoritative; the model proposes changes; validation occurs before atomic commit; undo/checkpoint/restore/branch work by replaying parent-linked history; lore is local; and the privacy documentation explicitly minimizes network and executable-extension surfaces.
|
||||
|
||||
## Projects eliminated from fork contention
|
||||
|
||||
### Chronicler
|
||||
Excellent source for memory semantics, but the application is centered on long-running roleplay and YantrikDB cognitive memory rather than the simpler interactive-story product. Its memory-tier design should be borrowed conceptually.
|
||||
|
||||
### Gamentic
|
||||
Technically impressive and very useful for future media design, but it is intentionally a multi-agent RPG with image and voice infrastructure, tuned around a heavier local stack. Forking it would mean removing more game/agent behavior than necessary.
|
||||
|
||||
### Interactive Fiction Framework
|
||||
Its Story Bible, validation, and application-owned-state design are highly relevant. However, it is oriented toward contributor-authored, schema-driven stories and planner-approved choices rather than the unrestricted natural-language story continuation and branch history required here.
|
||||
|
||||
### Sonder Engine
|
||||
Strong engineering, but its core differentiator is separate fictional minds with strict perception/knowledge boundaries and a multi-stage agent pipeline. That is substantially more complexity than v1 requires.
|
||||
|
||||
### Corvus Story Core
|
||||
Useful image/TTS and state-extraction reference, but its persistence is JSON/JSONL-oriented and the static review did not establish the required non-destructive branch/checkpoint model.
|
||||
|
||||
### aiMultiFool
|
||||
Useful local vector-memory ideas, but it is a terminal character-roleplay application, its context-pruning approach is not the desired immutable-history architecture, and GPL-3.0 complicates direct code reuse into a permissively licensed fork.
|
||||
|
||||
## Sources
|
||||
|
||||
See `SOURCE-INDEX.md` for repository/source links.
|
||||
@@ -1,75 +0,0 @@
|
||||
# Licensing and Reuse Review
|
||||
|
||||
**Date:** 2026-09-01
|
||||
**Nature:** Engineering planning summary, not legal advice.
|
||||
|
||||
## Production Selection Update
|
||||
|
||||
Phase 0B selected **AI-DnD (MIT)** as the production fork/base. The production strategy therefore remains on a permissive-license path.
|
||||
|
||||
The project may reimplement compatible ideas from other projects, but direct source copying must still be reviewed file-by-file and retain applicable notices. GPL/AGPL projects remain concept/reference sources unless a later explicit licensing decision changes that policy.
|
||||
|
||||
Maintain third-party notices from the first production milestone.
|
||||
|
||||
## Permissive finalists
|
||||
|
||||
### AI-DnD
|
||||
- License: MIT
|
||||
- Direct modification/forking is generally compatible with a permissive local application, subject to preserving required notices.
|
||||
|
||||
### Open Dungeon
|
||||
- License: MIT
|
||||
- Same practical advantage for direct reuse.
|
||||
|
||||
### ai-adventure
|
||||
- License: Apache-2.0
|
||||
- Permissive, but Apache notice/license obligations must be preserved.
|
||||
|
||||
These three can plausibly participate in a permissively licensed implementation strategy, subject to checking individual vendored/third-party files.
|
||||
|
||||
## Permissive reference projects
|
||||
|
||||
Static repository licensing indicates:
|
||||
- Chronicler: MIT
|
||||
- Interactive Fiction Framework: MIT
|
||||
- Gamentic: MIT
|
||||
- Sonder Engine: MIT
|
||||
- Corvus Story Core: MIT
|
||||
|
||||
If source is copied, retain the applicable notices and verify whether particular directories/files carry separate licenses.
|
||||
|
||||
## Copyleft references
|
||||
|
||||
### aiMultiFool
|
||||
- GPL-3.0
|
||||
- Treat as a concept/reference source unless the final project intentionally accepts GPL obligations.
|
||||
|
||||
### LettuceAI
|
||||
- AGPL-3.0
|
||||
- Reference only for this project unless there is a deliberate licensing decision.
|
||||
|
||||
Mature roleplay ecosystems such as SillyTavern/RisuAI/KoboldAI should have their exact current license verified before any code copying. No direct reuse is currently recommended.
|
||||
|
||||
## Media dependencies
|
||||
|
||||
Important distinction:
|
||||
- application code license,
|
||||
- media runtime license,
|
||||
- model-weight license
|
||||
are separate.
|
||||
|
||||
For example Gamentic documents:
|
||||
- its own code under MIT,
|
||||
- ComfyUI runtime under GPL-3.0,
|
||||
- model weights under their own terms.
|
||||
|
||||
Using a separately running local service through an API is architecturally different from copying its code into the storyteller, but distribution/bundling choices should be reviewed before release.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Keep the production application's own code on a permissive-license path if possible:
|
||||
- primary fork from MIT or Apache-2.0,
|
||||
- copy code only from compatible permissive sources,
|
||||
- treat GPL/AGPL projects as design references unless a conscious license change is made,
|
||||
- keep optional media providers as external adapters/services where practical,
|
||||
- maintain a third-party notices file from the first production milestone.
|
||||
@@ -1,41 +0,0 @@
|
||||
# Phase 0A Status
|
||||
|
||||
**Historical status:** Phase 0A complete. Phase 0B is also complete; see README, ADR 009, ADR 010, and `TECHNICAL-DESIGN.md` for current architecture.
|
||||
|
||||
**Completed:** 2026-09-01
|
||||
|
||||
## Completed statically
|
||||
|
||||
- candidate discovery and triage,
|
||||
- deep source/document architecture review of the three finalists,
|
||||
- static privacy/network-surface review,
|
||||
- preliminary licensing/reuse review,
|
||||
- subsystem reuse matrix,
|
||||
- preliminary fork recommendation,
|
||||
- narrowed Codex validation plan.
|
||||
|
||||
## Preliminary decision
|
||||
|
||||
Validate **AI-DnD first as the production fork candidate**.
|
||||
|
||||
Keep:
|
||||
- **Open Dungeon** as the fallback fork and primary UI/media reference.
|
||||
- **ai-adventure** as the state/replay/privacy architecture reference and third validation candidate.
|
||||
|
||||
## Still requires local/Codex work
|
||||
|
||||
- pin exact SHAs,
|
||||
- clone/install/build,
|
||||
- run actual tests,
|
||||
- verify Ollama against the user's machine,
|
||||
- runtime network capture,
|
||||
- offline operation,
|
||||
- AI-DnD strip-down experiment,
|
||||
- Open Dungeon branch-retrofit impact experiment,
|
||||
- ai-adventure Ollama/service-boundary experiment.
|
||||
|
||||
See `PHASE-0B-CODEX-HANDOFF.md`.
|
||||
|
||||
## Phase gate
|
||||
|
||||
Do not finalize `TECHNICAL-DESIGN.md` v1.0 or production `BUILD-MILESTONES.md` until Phase 0B results are reviewed.
|
||||
@@ -1,122 +0,0 @@
|
||||
# Static Privacy and Network Review
|
||||
|
||||
**Date:** 2026-09-01
|
||||
**Scope:** Source/config/documentation review only. Runtime capture is still required in Phase 0B.
|
||||
|
||||
## Target rule
|
||||
|
||||
The final v1 should be able to operate with Internet access physically blocked, with ordinary story data traveling only:
|
||||
|
||||
```text
|
||||
Browser -> local application -> local Ollama
|
||||
```
|
||||
|
||||
Future media should similarly use explicitly configured local providers.
|
||||
|
||||
## AI-DnD
|
||||
|
||||
### Static positives
|
||||
- documented local single-user mode,
|
||||
- local SQLite,
|
||||
- local Ollama support,
|
||||
- no auth required in local mode,
|
||||
- hosted analytics are first-party application functionality rather than a required third-party browser tracker.
|
||||
|
||||
### Unwanted surfaces to remove
|
||||
- OpenRouter/OpenAI/Groq/vLLM provider support,
|
||||
- hosted account/guest flows,
|
||||
- demo API keys,
|
||||
- Render deployment,
|
||||
- Neon/Postgres cloud deployment path,
|
||||
- visit analytics,
|
||||
- QuickJS user scripting,
|
||||
- Claude CLI shim if not wanted,
|
||||
- any hosted-mode rate-limit/account code that adds no local value.
|
||||
|
||||
### Risk
|
||||
The cloud/hosted code is explicit and documented, which is good, but Phase 0B must prove it can be removed cleanly.
|
||||
|
||||
## Open Dungeon
|
||||
|
||||
### Static positives
|
||||
- Ollama loopback default,
|
||||
- local SQLite,
|
||||
- local image backend,
|
||||
- no telemetry requirement apparent in inspected package/config.
|
||||
|
||||
### Unwanted or optional surfaces
|
||||
- OpenRouter configuration,
|
||||
- arbitrary remote OpenAI-compatible endpoint support,
|
||||
- Tailscale/LAN exposure options,
|
||||
- any runtime remote assets,
|
||||
- any model/image automatic download behavior after setup.
|
||||
|
||||
### Risk
|
||||
The app is smaller, so hardening may be easier, but no runtime capture has been performed.
|
||||
|
||||
## ai-adventure
|
||||
|
||||
### Static positives
|
||||
This project most closely matches the target from the outset:
|
||||
- no telemetry,
|
||||
- no cloud account,
|
||||
- no MCP,
|
||||
- no executable plugins,
|
||||
- no shell tools,
|
||||
- loopback model endpoint default,
|
||||
- non-loopback warning,
|
||||
- imported content treated as bounded data,
|
||||
- path traversal/symlink defenses documented.
|
||||
|
||||
### Unwanted surface
|
||||
- configurable non-loopback model endpoint should be prohibited or strongly gated in the target v1.
|
||||
- LM Studio provider should be replaced/extended with Ollama.
|
||||
|
||||
## Reference projects
|
||||
|
||||
### Gamentic
|
||||
Local defaults are strong, but the project intentionally supports cloud text/image/audio dialects as alternatives. A target fork would need those disabled. Its Docker/media stack also has setup-time model acquisition concerns separate from story-time privacy.
|
||||
|
||||
### Chronicler
|
||||
Supports local Ollama but also broader providers and a separate local YantrikDB/MCP memory service. More moving parts than needed.
|
||||
|
||||
### Sonder / Corvus
|
||||
Both support local backends but also remote provider configurations; Sonder additionally has extension/optional external-service surfaces.
|
||||
|
||||
### aiMultiFool
|
||||
Primarily local, but direct code reuse is constrained by GPL considerations and it is not a fork finalist.
|
||||
|
||||
## Required Phase 0B runtime tests
|
||||
|
||||
For each finalist:
|
||||
|
||||
1. block outbound Internet access,
|
||||
2. start the app,
|
||||
3. create/load a story,
|
||||
4. generate multiple turns,
|
||||
5. trigger summarization/memory,
|
||||
6. trigger embeddings where applicable,
|
||||
7. save/restore/branch,
|
||||
8. for Open Dungeon, generate a local image,
|
||||
9. capture socket/DNS/HTTP activity,
|
||||
10. fail the test if story content leaves loopback or explicitly approved LAN endpoints.
|
||||
|
||||
Record:
|
||||
- process,
|
||||
- destination IP/hostname,
|
||||
- port,
|
||||
- trigger,
|
||||
- payload classification,
|
||||
- whether required or optional.
|
||||
|
||||
## Recommended production hardening
|
||||
|
||||
- bind app and Ollama to loopback by default,
|
||||
- allowlist provider URLs rather than accept arbitrary URLs,
|
||||
- no API-key UI in v1,
|
||||
- no remote URL ingestion,
|
||||
- no executable campaign scripts,
|
||||
- no third-party analytics,
|
||||
- bundle frontend assets locally,
|
||||
- content-security policy that rejects remote scripts/styles/images by default,
|
||||
- CI test or integration harness that runs with outbound networking disabled.
|
||||
@@ -1,111 +0,0 @@
|
||||
# Reference Project Findings
|
||||
|
||||
**Date:** 2026-09-01
|
||||
|
||||
These projects are not recommended as primary forks after static review, but each contributes a useful architectural pattern.
|
||||
|
||||
## Chronicler
|
||||
|
||||
Repository: https://github.com/yantrikos/chronicler
|
||||
|
||||
### Borrow
|
||||
Its memory model distinguishes different trust levels rather than treating all remembered text equally.
|
||||
|
||||
Useful conceptual tiers:
|
||||
- durable canon,
|
||||
- scene/recent memory,
|
||||
- heuristic/inferred memory.
|
||||
|
||||
Its anti-confabulation approach is especially relevant: retrieved hints should not automatically become established historical fact.
|
||||
|
||||
### Do not necessarily adopt
|
||||
The full YantrikDB/MCP cognitive-memory stack is heavier than v1 needs. Start with a simpler local store and preserve the trust-tier semantics.
|
||||
|
||||
## Interactive Fiction Framework
|
||||
|
||||
Repository: https://github.com/georgebutler/interactive-fiction-framework
|
||||
|
||||
### Borrow
|
||||
- Story Bible as highest-authority narrative context,
|
||||
- application owns durable state,
|
||||
- model enriches prose rather than overriding state,
|
||||
- structured output validation,
|
||||
- deterministic fallback,
|
||||
- separation of director/planner/memory/validator.
|
||||
|
||||
### Why not fork
|
||||
It is designed around contributor-authored story bundles and planner-approved choices, whereas the target is more freeform collaborative fiction with branch-preserving history.
|
||||
|
||||
## Gamentic
|
||||
|
||||
Repository: https://github.com/hec-ovi/gamentic
|
||||
|
||||
### Borrow
|
||||
This is the strongest reference found for future multimodal architecture.
|
||||
|
||||
It separates each modality behind a provider layer:
|
||||
|
||||
```text
|
||||
engine
|
||||
-> text provider
|
||||
-> image provider
|
||||
-> audio provider
|
||||
```
|
||||
|
||||
The game can continue text-first while images render asynchronously. Character image/voice identity lives in game state rather than in provider-specific code.
|
||||
|
||||
It also demonstrates an unusually strong local-project test strategy with over a thousand automated tests documented across backend/frontend/services.
|
||||
|
||||
### Why not fork
|
||||
The core product is a multi-agent RPG with significant game mechanics and a heavy local image/voice stack. That is broader than the desired v1 storyteller.
|
||||
|
||||
## Sonder Engine
|
||||
|
||||
Repository: https://github.com/N0819/Sonder_Engine
|
||||
|
||||
### Borrow later
|
||||
- one persistent commit boundary,
|
||||
- objective state distinct from character perception/belief/memory,
|
||||
- retrieval scoped by what a character may legitimately know,
|
||||
- model stages with different contexts.
|
||||
|
||||
### Why not fork
|
||||
Its defining feature is separate character minds and a multi-stage agent pipeline. That is valuable for a future sophisticated simulation but unnecessary complexity for v1.
|
||||
|
||||
## Corvus Story Core
|
||||
|
||||
Repository: https://github.com/JustLateNightAI/Corvus-Story-Core
|
||||
|
||||
### Borrow
|
||||
- hidden GM/state extraction pass,
|
||||
- scene/NPC visual descriptions,
|
||||
- ComfyUI scene art,
|
||||
- optional TTS,
|
||||
- local-first media integration.
|
||||
|
||||
### Why not fork
|
||||
Static review did not show the same robust branch/checkpoint/replay model; persistence is oriented around local JSON/JSONL rather than the desired transactional story graph.
|
||||
|
||||
## SillyTavern / RisuAI / KoboldAI
|
||||
|
||||
### Borrow
|
||||
- lorebook/world-info UX,
|
||||
- author's-note concepts,
|
||||
- context placement and triggering,
|
||||
- character/world metadata workflows.
|
||||
|
||||
### Why not fork
|
||||
They are mature but broad roleplay/chat ecosystems. Adapting them would mean carrying a large amount of unrelated general-purpose functionality.
|
||||
|
||||
## Design consequence
|
||||
|
||||
The production fork should not try to merge these projects.
|
||||
|
||||
Use a primary codebase, then deliberately implement selected patterns:
|
||||
|
||||
- AI-DnD: story tree, rollback, memory, prompt inspection.
|
||||
- ai-adventure: authoritative event/replay/privacy discipline.
|
||||
- Open Dungeon: story-focused UX and visual continuity.
|
||||
- Chronicler: memory trust tiers.
|
||||
- Gamentic: provider-neutral/asynchronous media.
|
||||
- IFF: Story Bible authority and validation.
|
||||
@@ -1,83 +0,0 @@
|
||||
# Phase 0 Source Index
|
||||
|
||||
**Status:** Phase 0 source inventory; static links plus Phase 0B pinned finalist commits.
|
||||
**Scope:** Repository/source references used during Phase 0. Runtime findings are recorded in `PHASE-0B-RECOMMENDATION.md` and supporting Phase 0B evidence.
|
||||
|
||||
## Phase 0B Production Selection
|
||||
|
||||
Selected production base:
|
||||
|
||||
- AI-DnD
|
||||
- pinned Phase 0B commit: `d72f7c1bda0f34fccd84afb7a25c34eb01c901de`
|
||||
- license: MIT
|
||||
|
||||
Phase 0B also evaluated:
|
||||
|
||||
- Open Dungeon `b0a79f96bf852be7b4e53908dff6a7f7c179da23`
|
||||
- ai-adventure `873ea9180d5b611576cddb155921fc16a17ae88b`
|
||||
|
||||
The source list below records the Phase 0 research set.
|
||||
|
||||
## Finalists
|
||||
|
||||
### AI-DnD
|
||||
- Repository: https://github.com/parththakkar106/AI-DnD
|
||||
- README / architecture summary: https://github.com/parththakkar106/AI-DnD/blob/main/README.md
|
||||
- Design guide: https://github.com/parththakkar106/AI-DnD/blob/main/docs/GUIDE.md
|
||||
- License: MIT
|
||||
|
||||
### Open Dungeon
|
||||
- Repository: https://github.com/newideas99/open-dungeon
|
||||
- Database layer: https://github.com/newideas99/open-dungeon/blob/main/src/lib/db.ts
|
||||
- Prompt/context layer: https://github.com/newideas99/open-dungeon/blob/main/src/lib/story-prompt.ts
|
||||
- Environment configuration: https://github.com/newideas99/open-dungeon/blob/main/.env.example
|
||||
- Package manifest: https://github.com/newideas99/open-dungeon/blob/main/package.json
|
||||
- License: MIT
|
||||
|
||||
### Local Adventure Engine / ai-adventure
|
||||
- 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
|
||||
- License: Apache-2.0
|
||||
|
||||
## High-value reference projects
|
||||
|
||||
### aiMultiFool
|
||||
- Repository: https://github.com/omgboohoo/aimultifool
|
||||
- Role: local roleplay/RAG/encryption ideas
|
||||
- License: GPL-3.0
|
||||
|
||||
### Chronicler
|
||||
- Repository: https://github.com/yantrikos/chronicler
|
||||
- Role: memory tiers, canon/heuristic/reflex separation, anti-confabulation patterns
|
||||
- License: MIT (application); YantrikDB is separately Apache-2.0
|
||||
|
||||
### Interactive Fiction Framework
|
||||
- Repository: https://github.com/georgebutler/interactive-fiction-framework
|
||||
- Role: Story Bible, model-as-prose-writer/application-as-state-owner, validation/fallback patterns
|
||||
- License: MIT
|
||||
|
||||
### Gamentic
|
||||
- Repository: https://github.com/hec-ovi/gamentic
|
||||
- Role: local text/image/voice provider abstraction, asynchronous media generation, large automated test suite
|
||||
- License: MIT
|
||||
|
||||
### Sonder Engine
|
||||
- Repository: https://github.com/N0819/Sonder_Engine
|
||||
- Role: objective truth vs perception/memory/belief, commit boundary, sophisticated character knowledge
|
||||
- License: MIT
|
||||
|
||||
### Corvus Story Core
|
||||
- Repository: https://github.com/JustLateNightAI/Corvus-Story-Core
|
||||
- Role: structured state + local ComfyUI/TTS integration
|
||||
- License: MIT
|
||||
|
||||
## Mature ecosystem references
|
||||
|
||||
- SillyTavern: https://github.com/SillyTavern/SillyTavern
|
||||
- RisuAI: https://github.com/kwaroran/RisuAI
|
||||
- KoboldAI Client: https://github.com/KoboldAI/KoboldAI-Client
|
||||
|
||||
## Important research caveat
|
||||
|
||||
Repository documentation can be stale relative to current source. Phase 0B should pin exact commit SHAs at clone time, run the projects, run their tests, and verify all network behavior locally.
|
||||
Reference in New Issue
Block a user