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
@@ -123,6 +123,29 @@ If the selected base architecture makes unlimited Undo substantially harder or u
|
||||
|
||||
Phase 0B demonstrated repeated non-destructive Undo well beyond the minimum five-step requirement. The selected head-cursor design should therefore support Undo across retained active-lineage history up to the root unless a later implementation defect forces a documented exception.
|
||||
|
||||
### Undo crosses fork points (settled in M3)
|
||||
|
||||
Undo continues backward through story a branch **inherited** from the line it
|
||||
forked from, up to the campaign opening. It does not stop at the fork.
|
||||
|
||||
This reverses the behavior of the pre-M3 base, and the reversal follows from the
|
||||
history model rather than from a change of mind about the product. Undo used to
|
||||
delete the turns it stepped over, and the turns before a fork belong to the
|
||||
parent line's story as well, so refusing at the fork was the only way to stop
|
||||
one line's Undo from destroying story another line was still telling. Undo now
|
||||
moves the reading position and deletes nothing, so there is nothing to protect
|
||||
the parent from: a forked story includes the story it was forked out of, and
|
||||
walking back through it is a reader moving backward, not a branch reaching into
|
||||
another branch's history.
|
||||
|
||||
The only floor is the campaign opening. There is no pre-campaign position to
|
||||
reach, and Undo at the opening reports that there is nothing to undo.
|
||||
|
||||
One consequence is worth stating plainly for anyone reading a transcript: a
|
||||
single Undo on a forked story can step back over a turn that was originally
|
||||
written on the line it forked from. Nothing about that turn changes; it simply
|
||||
stops being part of what is currently being told.
|
||||
|
||||
## 6. State Restoration on Undo
|
||||
|
||||
Undo must restore more than visible transcript text.
|
||||
@@ -242,6 +265,28 @@ User action
|
||||
|
||||
Inactive takes should remain retained initially.
|
||||
|
||||
### Selecting a take while a later story is off screen (settled in M3)
|
||||
|
||||
Selecting a different take is a change to what the story says at a position that
|
||||
already has a story after it. While that later story is on screen, the choice is
|
||||
plainly visible and the user can see what they are changing.
|
||||
|
||||
It is not, once the later story has been moved out of view — undone and not yet
|
||||
redone, or left behind by a new continuation. Silently switching the take
|
||||
underneath it would leave retained history continuing from words the story no
|
||||
longer says, and the user would have no way to see that it had happened.
|
||||
|
||||
The system must therefore refuse to switch the selected take in that situation
|
||||
and say why, rather than switching it quietly. The user resolves it by deciding
|
||||
what they mean:
|
||||
|
||||
- **Redo**, bringing the later story back into view, and then choose freely; or
|
||||
- **play the turn again from here**, which starts a new continuation and keeps
|
||||
the old one as retained history.
|
||||
|
||||
The same rule and the same two resolutions apply to editing a turn's text in
|
||||
place; see §14A.
|
||||
|
||||
## 11. Retry vs Branch
|
||||
|
||||
Retry should not be presented to the user as “creating a branch.”
|
||||
@@ -332,6 +377,38 @@ Therefore the system must:
|
||||
|
||||
The system must not simply replace visible text while leaving stale state behind.
|
||||
|
||||
## 14A. Editing In Place, Before §14-15 Are Implemented
|
||||
|
||||
§14 and §15 describe the finished behavior: a narrator edit becomes
|
||||
authoritative, the state it implies is re-evaluated, a new continuation is
|
||||
created, and the original narration and its future are retained. That
|
||||
requirement stands in full and is **not** weakened by this section.
|
||||
|
||||
It is not yet built. Re-evaluating the state implied by prose a user typed
|
||||
requires the authoritative narrative-state extraction that the genre-neutral
|
||||
state milestone introduces, so the finished behavior is completed there. What
|
||||
exists in the meantime is a plain correction: it changes the words of one turn
|
||||
and re-evaluates nothing.
|
||||
|
||||
That correction is safe while everything descending from the turn is on screen,
|
||||
because the user can see what their change has to stay consistent with. It is
|
||||
not safe when a continuation descends from the turn and is **off screen** —
|
||||
undone and not yet redone, or left behind by a divergence — because the edit
|
||||
would then silently change the words that retained story was written from, and
|
||||
nothing on screen would show it. Retained history is not permitted to be made to
|
||||
disagree with itself in a way the user cannot see.
|
||||
|
||||
Until §14-15 are implemented, the system must therefore **refuse** an in-place
|
||||
edit of a turn that has story descending from it which is not currently being
|
||||
shown, and say why. The user resolves it the same two ways as §10:
|
||||
|
||||
- **Redo**, bringing the later story back into view; or
|
||||
- **play the turn again from here**, which is the §13 shape — return to the
|
||||
parent position, continue differently, and keep the old line as retained
|
||||
history.
|
||||
|
||||
Refusing is the minimum that keeps the invariant. It is not the destination.
|
||||
|
||||
## 16. Manual State / Canon Correction
|
||||
|
||||
The user should be able to correct authoritative story state without rewriting prose.
|
||||
|
||||
Reference in New Issue
Block a user