JesseMarkowitzandClaude Opus 5
b7005e6fdd
Replaces AI-DnD's RPG relative-delta world state with the genre-neutral typed
narrative state of ADR 010: explicit, absolute, allowlisted events proposed by
the model, validated by the application, applied to one authoritative document,
and snapshotted per position so restore stays a row read.
This commit includes the corrective pass that followed the independent review
in planning/reports/M5-IMPLEMENTATION-REPORT.md. The invariant it exists to
hold is:
visible active transcript position == stored head == authoritative state
Narrator editing (D10, STORY-BRANCH-SEMANTICS §§14-15)
A narrator edit no longer rewrites a row. It returns to the state before the
turn, takes the reader's exact text as the accepted narration, re-derives the
state that text implies, and becomes a new active continuation — while the
original narration keeps its words, its live flag and its whole future as
retained history. At the tip the correction is another take; with story below
it, it forks. No new history machinery: this is the existing fork/take/head
path with the reader's text in place of a generated reply. The §14A refusal
is therefore gone for narrator turns, and remains only for player input.
Pre-M5 positions
Migration 88 backfills the empty narrative document onto every action written
before M5, and a missing snapshot now restores the empty document instead of
leaving the previous position's state standing. Restoring to an old Save
Point no longer leaves a later position's entities and facts on screen.
Narrator context
Replayed history carries prose only; the machine-readable block is no longer
reconstructed into past turns, where it contradicted the authoritative state
in the same prompt. A fact withdrawn by a manual correction is now named as
no longer true, with the reader's reason, rather than silently dropped.
Also
- state_changes joins the action-list bulk read, removing one query per row.
- Extraction takes only the application's own protocol payload: an ordinary
```json or ```python block in a story survives, and a mangled proposal
still does not reach the reader.
Planning: ADR 013 records the authoritative document shape; §§14-15/14A, D10,
C04 and BUILD-MILESTONES are updated to describe what exists. Debt is recorded
against M8 (scenario editor UX) and M9 (export of the audit trail).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PWU4gTfLYY6Qq9U7aa9Qw2
283 lines
16 KiB
Markdown
283 lines
16 KiB
Markdown
# Planning Package Version
|
|
|
|
- **Package:** Adventure Storyteller Planning Package v2.6
|
|
- **Revision date:** 2026-09-03
|
|
- **Status:** Phase 0 complete; architecture selected; **Milestones M1-M4 implemented and accepted**; M5 is next to brief.
|
|
|
|
## v2.6 — M4 Closeout (2026-09-03)
|
|
|
|
M4 is **accepted**. Its review returned *PASS WITH CORRECTIVE WORK REQUIRED*; the
|
|
corrective work is done, and the browser condition that M3 and M4 both carried is
|
|
closed.
|
|
|
|
**The three review findings, fixed:**
|
|
|
|
- **B-1 — the Save Point list was an N+1.** It resolved each Save Point with its
|
|
own query and 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 computation: **53 SELECTs for 25 Save Points became 5**, and the count
|
|
no longer grows with the list. Guarded by three tests, including one proving
|
|
the coordinate is matched as a *pair* — an `IN`-list version would report a
|
|
Save Point resolved because another branch has a live row at the same depth.
|
|
- **B-2 — deleting a branch silently deleted its Save Points.** Fixed as a
|
|
**behaviour** defect rather than a missing warning, because
|
|
`STORY-BRANCH-SEMANTICS.md` §19 says a named checkpoint remains until
|
|
explicitly deleted and §28 already required future cleanup to retain
|
|
checkpoint-referenced paths. **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. Both delete controls disable and explain. Recorded as a new
|
|
**§19.1**.
|
|
- **B-3 — the D11/L03 automation never left one process.** A new module spawns
|
|
real server processes, kills the first, and reads the campaign back with the
|
|
second.
|
|
|
|
**Also fixed (review §S C-5):** creating a Save Point now takes the campaign's
|
|
turn lock, so "save where I am" cannot read a head a turn in flight is about to
|
|
move. Rename and Delete deliberately do not take it, and a test pins that
|
|
decision.
|
|
|
|
**Real-browser verification — the first in this project.** A Firefox 154.0.1
|
|
driven through geckodriver over the W3C WebDriver protocol exercised the rendered
|
|
DOM for **both** milestones: **44/44 checks passed**, no console errors. It
|
|
covered M3's Undo/Redo enable states, transcript movement, Retry and the take
|
|
pager, and divergence retiring Redo; and M4's whole Save Point lifecycle
|
|
including both confirmations and the new branch-delete warning. **The outstanding
|
|
M3 browser condition is therefore closed as well.** No dependency was added to
|
|
the repository: the WebDriver client for the run was written against stdlib HTTP.
|
|
|
|
**Also corrected, found while fixing B-2:** `models.py`, `TECHNICAL-DESIGN.md`
|
|
§8.8 and `DATA-MODEL.md` §8 all described the cascade as the durability rule.
|
|
They now describe the refusal, and record that `checkpoints.branch_id`'s cascade
|
|
survives as referential integrity that the application no longer reaches.
|
|
|
|
**Documents corrected by this closeout:**
|
|
|
|
- `V1-ACCEPTANCE-TESTS.md` records results for **D11-D14, I04, L03** and the
|
|
E-series, and states that the browser-level condition is satisfied. **No pass
|
|
condition was weakened** — and D11/L03 now note that the automation crosses a
|
|
genuine OS process boundary, which is the standard later milestones should
|
|
meet.
|
|
- `DATA-MODEL.md` §8 records the coordinate as implemented, with the retry
|
|
measurement that settles coordinate-versus-turn-id, and three decisions that
|
|
were previously implicit: names are not unique, several Save Points may name
|
|
one position, and the list is newest-created first.
|
|
- `STORY-BRANCH-SEMANTICS.md` gains **§19.1** — a checkpoint protects the
|
|
history it names. This is the only behavioural specification change in the
|
|
closeout, and it strengthens §19 rather than weakening anything.
|
|
- `BROWSER-UX-SPEC.md` §25 rules for the implemented vocabulary: **Moment N**,
|
|
not *Turn N*, because the branch panel and tree overlay already count in
|
|
moments. Vocabulary only; no behaviour changes.
|
|
- `BUILD-MILESTONES.md` marks **M4 COMPLETE**, records the fixes and the browser
|
|
result, and warns M5 that the instrumentation to move is now **55 tests**.
|
|
- `README.md` records M1-M4 accepted and M5 as next to brief.
|
|
- `PROJECT-SOURCES.md` and `project-sources.txt` point at the current report;
|
|
`project-sources.txt` still named the archived M3 report and was corrected.
|
|
|
|
**Report rotation** happened in the reporting pass that preceded this closeout:
|
|
`M3-IMPLEMENTATION-REPORT.md` moved to `archive/milestone-reports/` as a pure
|
|
rename, and `reports/` now holds M4's report, whose **§W** is this closeout's
|
|
evidence record.
|
|
|
|
**No new ADR.** ADR 012 already decides the architecture, and the corrective work
|
|
forced no new architectural decision. `SPECIFICATION.md`,
|
|
`STORY-BRANCH-SEMANTICS.md`, `SECURITY-THREAT-MODEL.md`, `CONTEXT-AND-MEMORY.md`,
|
|
`IMPORTED-KNOWLEDGE-DESIGN.md` and ADRs 003, 005 and 012 are unchanged.
|
|
|
|
**M5 readiness:** ready. Save Points store no state and no checkpoint code reads
|
|
any, so M5 can change what a snapshot contains without touching what a Save Point
|
|
is — provided it keeps state recoverable at a position without replay
|
|
(`TECHNICAL-DESIGN.md` §10.4).
|
|
|
|
## v2.5 — M4 Implementation (2026-09-03)
|
|
|
|
M4 added durable named Save Points. This revision records only what the
|
|
implementation established as fact; **no product requirement changed**, and the
|
|
milestone is **not** marked accepted — its review has not been written.
|
|
|
|
- `TECHNICAL-DESIGN.md` gains **§8.8** and **§9.2**: the Save Point as a name
|
|
plus a coordinate holding no story, restore as head movement with a bounds
|
|
check, the rule that the branch half of the head moves only when the
|
|
coordinate is off the path being read, restore never forking, and the bundle
|
|
carrying Save Points independently of the head.
|
|
- `DATA-MODEL.md` **§8** records the pointer as implemented — `(branch, depth)`
|
|
rather than a turn id, with the reason: one coordinate holds every attempt at
|
|
a turn and exactly one is live, so a coordinate follows a retry where a row id
|
|
would pin a superseded take. **§29** records the checkpoints in the export.
|
|
- `BUILD-MILESTONES.md` **M4** gains a status block: what shipped, the one
|
|
architectural decision the milestone had to make and why it needed no new ADR,
|
|
the test count, and the outstanding browser condition.
|
|
- `README.md` describes Save Points as a user-facing capability.
|
|
|
|
**No ADR was created.** ADR 012 already decides the architecture M4 needed —
|
|
restore reuses active-head movement — and a table is not a decision. The one
|
|
question ADR 012 does not answer, whether restore moves the branch half of the
|
|
head, is that same mechanism applied to a coordinate ADR 012 already defines;
|
|
`TECHNICAL-DESIGN.md` §8.8 records the answer rather than a new ADR asserting it.
|
|
|
|
`SPECIFICATION.md`, `SECURITY-THREAT-MODEL.md`, `STORY-BRANCH-SEMANTICS.md` and
|
|
`V1-ACCEPTANCE-TESTS.md` are unchanged. M4 altered no product requirement, added
|
|
no outbound path, and implemented the checkpoint semantics
|
|
`STORY-BRANCH-SEMANTICS.md` §18-25 already specified rather than amending them.
|
|
|
|
**The browser smoke test remains unperformed, now for both M3 and M4.** No
|
|
session has had a usable browser. See `BUILD-MILESTONES.md` M3 and M4.
|
|
|
|
## 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)
|
|
|
|
M3 replaced destructive Undo with a stored active head. Its review is
|
|
`archive/milestone-reports/M3-IMPLEMENTATION-REPORT.md`, which is also M3's primary evidence
|
|
record — no separate baseline report was produced — and whose §W records this
|
|
closeout.
|
|
|
|
In summary:
|
|
|
|
- the architecture is recorded as **ADR 012 — Active-Head Non-Destructive
|
|
History**: the head is stored rather than derived, every read of the story is
|
|
capped at it in one place, one mechanism moves it, state comes from the node
|
|
rather than from a replay, the first write below a moved-back head is the
|
|
divergence, and Redo is decided by the lineage rather than by a flag. ADR 005
|
|
is unchanged: it states the product requirement, and ADR 012 states the
|
|
architecture chosen to implement it,
|
|
- two history semantics are **ratified** in `STORY-BRANCH-SEMANTICS.md`: Undo
|
|
crosses fork points to the campaign opening (§5), and the system refuses to
|
|
switch which take is live while a later story is off screen (§10),
|
|
- a **new §14A** records the interim in-place-editing rule — refuse when story
|
|
descends from the turn and is not on screen — and states explicitly that
|
|
§14-15's full narrator-edit requirement stands and is completed in M5,
|
|
- `TECHNICAL-DESIGN.md` gains **§8.7** and **§9.1** recording the implemented
|
|
model and bundle behaviour as fact, and a constraint on §10.4: the snapshot
|
|
half of the hybrid state model is a requirement, because head movement must
|
|
not become proportional to campaign length,
|
|
- `DATA-MODEL.md` records the head as campaign-stored, the branch disposition as
|
|
implemented and deliberately advisory, and the export as carrying a chosen
|
|
position rather than a derived one,
|
|
- `BUILD-MILESTONES.md` marks **M3 complete**, states the one outstanding
|
|
condition (the browser smoke test), tells **M4** to reuse M3's head movement
|
|
rather than build a second restore path, and gives **M5** three constraints,
|
|
- `V1-ACCEPTANCE-TESTS.md` records D03's full pass, states **D10's milestone
|
|
ownership without weakening any pass condition**, adds I07's pre-M3 bundle
|
|
clause, and resolves the apparent L01/A05 conflict,
|
|
- `README.md` is corrected to describe the current local-only single-user
|
|
application rather than the upstream hosted one.
|
|
|
|
`SPECIFICATION.md` and `SECURITY-THREAT-MODEL.md` are unchanged: M3 altered no
|
|
product requirement and touched no path in the threat model.
|
|
|
|
## v2.2 — Post-M2 Closeout (2026-09-03)
|
|
|
|
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
|
|
`archive/milestone-reports/M2-BASELINE-REPORT.md` and `archive/milestone-reports/M2-IMPLEMENTATION-REPORT.md`.
|
|
|
|
In summary:
|
|
|
|
- the **inference endpoint policy is recorded as implemented** — an address
|
|
allowlist of explicit local-network CIDRs, every resolved address checked,
|
|
enforced when settings are saved and again before every outbound request, with
|
|
TLS verification never traded against it (new **ADR 011**,
|
|
`SECURITY-THREAT-MODEL.md` §10A),
|
|
- its two **residual limits are stated rather than mitigated**: a hostile host
|
|
already on the trusted LAN, and the DNS-rebinding interval between the
|
|
policy's resolution and the client's connection,
|
|
- `TECHNICAL-DESIGN.md` §5.1 items 3 and 4 are **resolved**, and a new §5.2
|
|
records the M1/M2 production architecture as fact,
|
|
- a **wiring rule** is added (§18.1): removing a setting requires testing a real
|
|
consumer path, and adding one requires proving it reaches its component — M2
|
|
shipped two defects behind a 604-test green suite because the tests at that
|
|
boundary were mocks,
|
|
- `BUILD-MILESTONES.md` records **M2 complete**, warns M5 that eight rollback
|
|
tests use the world-state engine as instrumentation rather than as
|
|
architecture, and requires M6 to make background memory failure observable,
|
|
- the security acceptance contract is strengthened: **H10** now names the
|
|
wildcard-origin and `/api` 404 conditions, and new **H12** covers inference
|
|
endpoint enforcement including the database-edited-behind-the-API case.
|
|
|
|
`SPECIFICATION.md` is unchanged: M2 altered no product requirement. Nothing in
|
|
the architecture selected in v2 was reversed.
|
|
|
|
## v2.1 — Post-M1 Corrections (2026-09-02)
|
|
|
|
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
|
|
`archive/milestone-reports/M1-BASELINE-REPORT.md` and `archive/milestone-reports/M1-IMPLEMENTATION-REPORT.md`.
|
|
|
|
In summary:
|
|
|
|
- a trusted-LAN Ollama may be **HTTPS with a privately issued certificate**;
|
|
clients verify against the operating system's CA store, with full certificate
|
|
and hostname verification and no bypass option (ADR 002,
|
|
`TECHNICAL-DESIGN.md` §5, A06),
|
|
- offline claims require a **fresh cache and no route out** to be evidence at
|
|
all, and vendored runtime artifacts should be integrity-verifiable
|
|
(ADR 004),
|
|
- A05's invariant is about **accepted** history; the user's submitted text is
|
|
deliberately retained on a failed turn,
|
|
- A06 requires a **real second machine and an HTTPS endpoint**; a plain-HTTP
|
|
LAN test is no longer sufficient evidence,
|
|
- the standard test environment records **CPU/GPU/RAM**, because cold model
|
|
load on a CPU-only host exceeded the inherited 120 s client timeout,
|
|
- `BUILD-MILESTONES.md` records M1 as complete and reframes M2's endpoint work
|
|
as **narrowing** an existing capability rather than inventing it,
|
|
- `SECURITY-THREAT-MODEL.md` §53 distinguishes **inbound** TLS (still deferred)
|
|
from **outbound** certificate verification (required, done in M1).
|
|
|
|
Nothing in the architecture selected in v2 was reversed.
|
|
|
|
## v2 — Post Phase 0B Revision (2026-09-01)
|
|
|
|
This v2 package supersedes the earlier planning package produced before the final Phase 0B review and the trusted-LAN Ollama deployment clarification.
|
|
|
|
Key v2 changes include:
|
|
|
|
- AI-DnD selected as the production base at the pinned Phase 0B commit.
|
|
- Non-destructive head-cursor Undo/Redo design selected.
|
|
- Explicit typed/absolute narrative-state events selected for production state handling.
|
|
- The authoritative narrative-state document — its shape, its authority/provenance fields, and the
|
|
event/document/snapshot split — recorded in ADR 013 after M5 implemented it.
|
|
- Imported knowledge separated from AI-DnD Story Cards.
|
|
- Trusted-LAN Ollama inference supported in v1 while the storyteller UI/API remains loopback-bound by default.
|
|
- Offline first-use dependencies and runtime remote assets identified as M1 hardening work.
|
|
- Production implementation divided into milestones M1-M11.
|
|
|
|
Historical Phase 0 prompts/reports are retained as evidence and should not be treated as current implementation instructions unless a current milestone prompt explicitly refers to them.
|