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:
co-authored by
Claude Opus 5
parent
c8755c21c2
commit
d27ee34901
@@ -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.
|
||||
Reference in New Issue
Block a user