JesseMarkowitzandClaude Opus 5
62a997f364
Closes M4. The review's three findings are fixed, the durability rule the specification always implied is now enforced, and M3's and M4's browser behaviour has been verified in a real browser for the first time. B-1 -- the Save Point list was an N+1 that loaded whole Action rows, narration included, to answer "does a row exist here". It is now one bulk two-column coordinate query plus one lineage: 53 SELECTs for 25 Save Points became 5, and the count no longer grows with the list. The clause is an OR of exact (branch, depth) pairs rather than two IN lists, because the cross product would report a Save Point resolved on the strength of another one's depth existing on this one's branch. A test builds exactly that trap. B-2 -- reclassified during closeout from "missing warning" to a behaviour defect, and fixed as one. STORY-BRANCH-SEMANTICS §19 says a named checkpoint remains until explicitly deleted, and §28 already required future cleanup to retain checkpoint-referenced paths; a cascade that silently removed Save Points with a branch violated both, and a warning would only have documented the violation. A branch a Save Point names can no longer be deleted. The request is refused with the offending Save Points named, the user deletes them explicitly -- which deletes no story -- and the branch then goes. The scope is the subtree, because deleting a branch takes its descendants. Both delete controls disable and explain. Recorded as a new §19.1; models.py, TECHNICAL-DESIGN §8.8 and DATA-MODEL §8 had all recorded the cascade as the rule and now record the refusal. An earlier pass in this same closeout had kept the cascade and added a warning. That was the wrong fix and its tests were replaced rather than left standing, since they pinned the defect. B-3 -- the D11/L03 automation never left one process, so it could not distinguish durable state from a live Python object. It now spawns real server processes, kills the first, and reads the campaign back with the second. C-5 -- creating a Save Point takes the campaign's turn lock. "Save where I am" has to name one committed position, and the head is what a turn in flight is about to move. Rename and Delete deliberately do not take it. The architecture is untouched: a Save Point is still name + note + (branch, depth), and restore is still coordinate -> head.move_to_node -> head.move_to -> attempts.restore_state. No second restore path, no state copied into a checkpoint, no fork on restore. Browser verification -- the first in this project, and it covers both milestones. Firefox 154.0.1 through geckodriver over the W3C WebDriver protocol, driving the rendered DOM: 47/47 checks, twice, on independent databases, no console errors. M3's Undo/Redo enable states, transcript movement, Retry and the take pager, divergence retiring Redo; M4's whole Save Point lifecycle, both confirmations, and the new branch-delete refusal including its recovery. No dependency was added: the WebDriver client is stdlib HTTP. No application defect was found by the browser. Four failures occurred, all in the harness -- a wrong SPA route, a wait comparing transcript length when the empty-story placeholder is longer than the first turn, a fixture deleting the branch it was reading, and a reload assertion that sampled once instead of waiting. The last was checked against the app before being called a harness bug. Tests: 698 backend pass (was 680), 60 M4, 94 M3 history, 66 export/ migrations, 93 security/local-only. Frontend lint and build clean, Docker build clean, loopback binding unchanged. No assertion weakened, no skip added. Planning: STORY-BRANCH-SEMANTICS §19.1 is the only behavioural change and it strengthens §19. V1-ACCEPTANCE-TESTS records D11-D14, I04, L03 and the E-series, keeping automated, live-runtime and browser evidence distinct, and weakens no pass condition. DATA-MODEL records the coordinate with the retry measurement that settles it. BROWSER-UX-SPEC rules for Moment over Turn. BUILD-MILESTONES marks M4 COMPLETE, closes M3's browser condition, and lists what M5 inherits. VERSION adds v2.6. No new ADR: ADR 005 already decides that history is preserved rather than overwritten, and §19.1 is that decision applied to checkpoint-referenced history. M4 is closed. M5 may now be briefed; it has not been started. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PWU4gTfLYY6Qq9U7aa9Qw2
122 lines
4.3 KiB
Markdown
122 lines
4.3 KiB
Markdown
# 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/M4-IMPLEMENTATION-REPORT.md
|
|
```
|
|
|
|
M4 is the most recently completed milestone, and M5 is the next to be briefed.
|
|
This report is M4's review *and* its closeout record: its §W holds the corrective
|
|
work, the process-boundary automation, and the real-browser verification that
|
|
closed the condition M3 and M4 both carried.
|
|
|
|
**Replace it, do not accumulate.** When M5's report lands, remove this one from
|
|
the project Sources and upload M5'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.
|