Update planning package after Phase 0B

planning/STORY-BRANCH-SEMANTICS.md

@@ -1,6 +1,6 @@
 # Adventure Storyteller — Story Branch Semantics
 
-**Status:** Draft v0.1  
+**Status:** v1.0 — behavior confirmed after Phase 0B  
 **Purpose:** Define exactly how Undo, Redo, Retry, Edit, Restore, checkpoints, and abandoned history should behave.
 
 ## 1. Design Goal
@@ -121,9 +121,7 @@ If the selected base architecture makes unlimited Undo substantially harder or u
 
 > At least five consecutive Undo operations.
 
-Technical validation during Phase 0B should determine whether unlimited Undo is straightforward.
-
-The final implementation should prefer unlimited Undo unless there is a concrete technical reason not to.
+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.
 
 ## 6. State Restoration on Undo
 
@@ -402,6 +400,8 @@ Restoring a checkpoint:
 4. restores compatible summary/memory lineage,
 5. prepares the story to continue from that position.
 
+Restore itself does not need to create a new branch immediately. The existing continuation remains the Redo/retained path until the user creates a different continuation; the first divergent write then creates the new continuation.
+
 The original later story remains retained as abandoned/disposable history.
 
 ## 21. Restore Does Not Delete
@@ -613,6 +613,19 @@ Every generated narrator take should preserve enough information to determine:
 
 This remains true even for abandoned/disposable history until it is explicitly pruned.
 
+## 36A. Export / Import Must Preserve the Active Head
+
+Non-destructive Undo means retained history may extend beyond the current active head.
+
+Export must therefore preserve both:
+
+- the retained history/branch graph, and
+- the exact active branch/head position.
+
+Import must reopen the campaign at that active head. It must not infer that the newest retained turn is current merely because later history still exists.
+
+Backward compatibility may treat the retained tip as the head only for older export formats that contain no explicit head coordinate.
+
 ## 37. Failure During Retry / Edit / Continue
 
 If generation fails:
@@ -688,7 +701,7 @@ Preferred:
 
 - unlimited Undo across retained history.
 
-Phase 0B should determine whether the preferred behavior is already practical in the selected base.
+Phase 0B demonstrated that the preferred behavior is practical in the selected base. The production implementation should retain that capability while enforcing the correct campaign-root floor.
 
 ## 42. Example: Simple Mistake
 
@@ -791,45 +804,46 @@ as authoritative.
 
 If desired, the user may also edit the narration, but that is a separate operation.
 
-## 46. Phase 0B Validation Questions
+## 46. Phase 0B Findings Applied
 
-Codex should answer:
+Phase 0B established the following implementation facts for the selected AI-DnD base:
 
-1. Does AI-DnD already support unlimited practical Undo through its lineage model?
-2. How does AI-DnD distinguish retry takes from full branches?
-3. Can retry/edit preserve prior futures without exposing a complex branch UI?
-4. Can summaries and memories be reliably lineage-filtered after divergence?
-5. Does AI-DnD state rollback restore generic state independently of RPG mechanics?
-6. How difficult would it be to mark abandoned paths disposable without deleting them?
-7. In Open Dungeon, what exact modules assume destructive tail-deletion semantics?
-8. Can checkpoints be implemented as durable turn pointers without duplicating state?
-9. What is the cost of retaining all disposable text/state history in SQLite?
-10. Does any finalist currently leak abandoned branch memories into active retrieval?
+- shipped Undo was destructive and therefore did not satisfy this document,
+- alternate-take Retry and branch lineage were genuinely non-destructive,
+- a disposable spike demonstrated head-cursor Undo/Redo without deleting accepted turns,
+- writes below a moved-back head can fork through existing branch machinery,
+- branch-scoped memory isolation remained correct with real local embeddings,
+- practical repeated Undo across retained history worked beyond the minimum five-step requirement,
+- retry/add-take paths still need to be routed through the production fork-if-behind-head rule,
+- abandoned history still needs explicit disposable/inactive marking,
+- export/import must carry the active head coordinate or it silently redoes an undone story.
+
+These findings select an implementation direction; the disposable spike itself is not production code to merge unchanged.
 
 ## 47. Acceptance Criteria
 
 The final implementation must satisfy:
 
-- Undo restores transcript and state together.
-- At least five Undo steps are available; unlimited is preferred.
+- Undo restores transcript and state together by moving the active head, not deleting accepted turns.
+- At least five Undo steps are guaranteed; the selected architecture should support Undo across all retained active-lineage history up to the root.
 - Redo works until a new continuation is created.
 - Retry preserves alternate narrator takes.
 - Editing old user input creates a safe new continuation.
 - Editing narrator output re-evaluates state.
 - Named checkpoints remain until explicitly deleted.
 - Restoring a checkpoint does not delete later history.
+- Checkpoint restore may reuse the existing continuation until the first divergent write.
 - Abandoned history is retained and marked disposable.
-- No automatic abandoned-history cleanup is required initially.
+- No automatic abandoned-history cleanup is required in v1.
 - Abandoned history does not influence active summaries, memories, state, or prompts.
 - Manual state/canon corrections are auditable.
+- Export/import preserves the exact active head even when retained history exists after it.
 - Normal UI does not require branch management.
-- A future discarded-history recovery screen remains possible without schema redesign.
+- A future discarded-history recovery/cleanup screen remains possible without schema redesign.
 
-## 48. Current Recommendation
+## 48. Selected Implementation Model
 
-Use a simple linear user experience backed by non-destructive lineage.
-
-Conceptually:
+Use a simple linear user experience backed by retained lineage and a movable active head.
 
 ```text
 USER EXPERIENCE
@@ -838,19 +852,21 @@ Undo
 Redo
 Retry
 Edit
-Checkpoint
+Save Point
 Restore
 
         ↓
 
 INTERNAL MODEL
 
-Parent-linked history
+Parent-linked retained history
 Alternate takes
-State snapshots/events
-Active head
+Active branch + active head
+Retained branch tip/future
+Typed state events + snapshots/cache
 Disposable abandoned history
 Lineage-aware summaries/memory
+Exported active-head coordinate
 ```
 
-This provides recovery and correctness without forcing the user to manage a story tree.
+The selected AI-DnD base supplies most of the lineage infrastructure; production work replaces destructive Undo, adds Redo/checkpoints/disposable marking, and preserves the head through export/import.