1.9 KiB
ADR 005 — Branch-Preserving Story History
Status: Accepted; implementation direction validated in Phase 0B
Decision
Returning to an earlier story point preserves abandoned future history rather than destructively erasing it.
The selected implementation model uses a movable active head over retained lineage:
- Undo moves the head backward,
- Redo moves it forward along the retained continuation,
- accepted turns are not deleted by ordinary Undo,
- a new write after moving backward creates a new continuation on first divergent write,
- the displaced future remains retained/disposable,
- normal UI presents Undo/Redo/Retry/Save Point rather than branch-management concepts.
Context
The user must be able to recover from unwanted story developments and explore alternatives while retaining prior work.
Phase 0B found that AI-DnD's shipped Undo was destructive even though its tree/take infrastructure was otherwise strong. A disposable spike demonstrated non-destructive head-cursor Undo/Redo using existing lineage chokepoints and branch creation while preserving branch-scoped memory isolation.
Alternatives Considered
- destructive undo,
- overwrite-in-place editing,
- complete copy of campaigns for every retry,
- branch-preserving turn graph with movable active head.
Reason
The selected model provides recovery, experimentation, auditability, and Redo without unnecessary campaign duplication or a complicated user-facing branch workflow.
Consequences
- turn identity/parentage remains first-class,
- active head and retained tip are distinct concepts,
- state restore is lineage-aware,
- retry/edit/add-take must honor fork-if-behind-head behavior,
- summaries/memories must respect active lineage/head,
- named checkpoints point to durable story positions,
- abandoned history is marked disposable but is not automatically cleaned up in v1,
- export/import must preserve the active head coordinate as well as the retained history graph.