Planning: close M3 and record active-head architecture
M3's review recommended planning changes and, following the M2 pattern, reported rather than applied them. This applies them, and adds the ADR the review asked for. ADR 012 records the architecture rather than the requirement. ADR 005 already says that going backward must preserve abandoned history and that the user sees Undo/Redo/Retry rather than branch management; it names a movable active head as the direction and stops. What M3 settled is the shape: the head is stored rather than derived, every read of the story is capped at it in one place, one mechanism moves it, the state of a position comes off the node rather than from a replay, the first write below a moved-back head is the divergence, and whether Redo exists is decided by the lineage rather than by a flag that could be stale. The last of those is the property worth keeping — a flag can be wrong and make the story wrong; a lineage cannot. Two semantics are ratified in STORY-BRANCH-SEMANTICS.md, both of them reversals or narrowings that a reader would otherwise take for bugs. Undo now crosses fork points and continues to the campaign opening, because refusing at the fork was a consequence of deleting rows the parent line was also reading, and nothing is deleted any more. And the system refuses to switch which take is live while a later story is off screen, because doing it quietly would leave retained history continuing from words the story no longer says. A new §14A covers editing in place. §14-15 describe the finished behaviour — the edit becomes authoritative, the state it implies is re-evaluated, a new continuation is created, the original is retained — and that requirement is intact and explicitly not weakened here. It is also not built, because re-evaluating state from prose a user typed needs M5's extraction pass. §14A says what exists in the meantime and why refusing is the minimum that holds the invariant rather than the destination. TECHNICAL-DESIGN.md gains §8.7 and §9.1, recording the implemented model and the bundle behaviour as fact in the way §5.2 records M1 and M2. §10.4 gains a constraint that is easy to lose: the snapshot half of the hybrid state model is a requirement, not an optimization. Head movement is a row lookup plus a restore, which is why Undo, Redo and Save Point restore cost the same at any distance into a campaign; a state model recoverable only by replaying from the opening would make all three proportional to campaign length, on exactly the long campaigns this product is for. DATA-MODEL.md records the head as stored on the campaign rather than derived from its newest turn — two campaigns holding identical turns can be read at different places, and nothing about the turns can tell them apart — and the branch disposition as implemented: the depth a divergent write left the branch at, deliberately advisory, and carried through export because every row of an abandoned line is exported either way. BUILD-MILESTONES.md marks M3 complete and states the one condition still open. M4 is told a Save Point is a durable pointer and that restoring one is head movement with a bounds check, not a restore system: a second mover is the specific failure to avoid, because the two paths would silently disagree about what restore means. M5 gets three constraints — keep state efficiently recoverable, move the test instrumentation rather than the assertions when the world-state protocol goes, and finish the narrator edit §14A defers. V1-ACCEPTANCE-TESTS.md clarifies ownership without lowering a bar. D10 keeps all three pass conditions and is explicitly recorded as *not* satisfied at the end of M3; what changed is that the document now says which milestone delivers which condition. D03's result is recorded as a full pass rather than the partial the text allowed for, I07 gains the pre-M3 bundle clause, and L01 gains the note that resolves its apparent conflict with A05 — a failed turn does advance the head by one, onto the player's retained input, and that is A05 working rather than L01 failing. README.md described a different application: a hosted demo, guest accounts, cloud providers, Postgres, a Render blueprint, an analytics dashboard, a QuickJS scripting engine, and 549 tests. M2 removed all of that and the README was never updated — a gap M2's own debt table missed. It now describes what this fork is, including the endpoint policy and the TLS behaviour, and the numbers in it are the current ones. M3's report is included here as its own evidence record: no separate baseline report was produced, so it carries the raw counts and runtime observations as well as the review, and §W records this closeout. SPECIFICATION.md and SECURITY-THREAT-MODEL.md are unchanged. M3 altered no product requirement and touched no path in the threat model. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QF5TcoB86QADgjHz1GZe8u
This commit is contained in:
co-authored by
Claude Opus 5
parent
7f082b61d8
commit
c8755c21c2
@@ -1,7 +1,8 @@
|
||||
# Adventure Storyteller — V1 Acceptance Tests
|
||||
|
||||
**Status:** v1.1 planning/release contract — updated after Phase 0B, and after M2 for
|
||||
the security contract (H10 strengthened, H12 added)
|
||||
**Status:** v1.2 planning/release contract — updated after Phase 0B, after M2 for
|
||||
the security contract (H10 strengthened, H12 added), and after M3 for history
|
||||
ownership and results (D03, D10, I07, L01)
|
||||
**Purpose:** Define black-box acceptance tests for finalist evaluation during Phase 0B and for the eventual v1 release.
|
||||
|
||||
## 1. Test Philosophy
|
||||
@@ -575,6 +576,17 @@ All retained turns can be traversed backward safely.
|
||||
### Partial
|
||||
System supports at least five but has a documented technical limit.
|
||||
|
||||
### Result (M3)
|
||||
**Pass, not partial.** Undo traverses to the campaign opening and then reports
|
||||
that there is nothing to undo. No technical limit applies: each step is one
|
||||
indexed query regardless of story length, because the position is a stored
|
||||
coordinate rather than a replay. The floor is the campaign opening — there is no
|
||||
pre-campaign position to reach.
|
||||
|
||||
Note also that Undo continues backward through story a branch inherited from the
|
||||
line it forked from; it does not stop at a fork. See
|
||||
`STORY-BRANCH-SEMANTICS.md` §5.
|
||||
|
||||
---
|
||||
|
||||
## D04 — Redo
|
||||
@@ -689,6 +701,26 @@ Mara wears a green cloak.
|
||||
- downstream state is re-evaluated,
|
||||
- old version/future remains retained/disposable.
|
||||
|
||||
### Milestone ownership
|
||||
|
||||
All three pass conditions stand for v1. They are delivered across three
|
||||
milestones, and this note records which is which rather than reducing the
|
||||
requirement:
|
||||
|
||||
- **M3 — safe history behavior.** Replaying a narrator turn with different text
|
||||
forks, keeps the original take and its future, and starts the new continuation
|
||||
from the correct earlier state. In-place editing of a turn is **refused** while
|
||||
story descends from it off screen, so retained history cannot be made to
|
||||
contradict itself unseen (`STORY-BRANCH-SEMANTICS.md` §14A). Delivered.
|
||||
- **M5 — authoritative state re-evaluation.** The second pass condition. Making a
|
||||
hand-typed narrator correction authoritative and re-evaluating the state it
|
||||
implies requires the narrative-state extraction pass, so it is completed there,
|
||||
and the §14A refusal is replaced by it. Outstanding.
|
||||
- **Later browser UX work — the finished editing workflow.** How the user reaches
|
||||
and confirms the operation. Outstanding.
|
||||
|
||||
D10 is therefore **not** satisfied at the end of M3, and is not scored as such.
|
||||
|
||||
---
|
||||
|
||||
## D11 — Named Checkpoint
|
||||
@@ -1358,6 +1390,21 @@ No external API credentials are embedded in campaign export.
|
||||
- import does not silently Redo to the newest retained turn,
|
||||
- Redo/recovery behavior remains coherent after import.
|
||||
|
||||
### Also required — an export written before the head was carried
|
||||
|
||||
Import an export produced by a build that recorded no active head, and confirm it
|
||||
opens at the retained tip of its active branch.
|
||||
|
||||
This is compatibility, not a degraded path, and the distinction matters when
|
||||
reading a result: such a file was written when the head could not be anywhere but
|
||||
the tip, so opening it there reproduces the position it actually recorded. An
|
||||
import that refused it, or that guessed some other position for it, would be the
|
||||
failure.
|
||||
|
||||
An export whose stated head lies beyond the story it contains is a file
|
||||
disagreeing with itself and must be refused rather than opened at a guessed
|
||||
position.
|
||||
|
||||
---
|
||||
|
||||
# J. Genre Independence
|
||||
@@ -1490,6 +1537,20 @@ No condition exists where:
|
||||
- branch head advances incorrectly,
|
||||
- previous story becomes inaccessible.
|
||||
|
||||
### Note on the head, and on A05
|
||||
|
||||
"The head advances incorrectly" must be read together with A05, or the two appear
|
||||
to contradict each other. A failed turn **does** move the active head forward by
|
||||
one, onto the player's submitted text, because A05 deliberately retains that text
|
||||
so the player can try again. That is correct behavior, not a half-advanced head.
|
||||
|
||||
What this test forbids is the head moving past a turn that did not happen: an
|
||||
accepted narration with state written only partway, or a position that implies a
|
||||
reply the story never received. Assert on the accepted narration and the
|
||||
authoritative state, not on whether the head moved at all. One Undo from that
|
||||
position steps back over the stranded input and leaves the story on a complete
|
||||
turn.
|
||||
|
||||
---
|
||||
|
||||
## L02 — State Reconstruction
|
||||
|
||||
Reference in New Issue
Block a user