Say what the app is now, everywhere it is published

The README, the project page and the engineering guide all describe a linear
story. The tree shipped two days ago. Every published surface is a phase
behind, and the guide is not merely behind — it is wrong in a way that costs a
reader time.

Its 2.2 was "Two coordinate systems, and the bug class they create", and it
explained the codebase through position_of_index, note_action_removed and
settled_story_actions. All three were deleted in SP3. 2.3 explained retry
through Action.variants and state_before. Somebody reading either would go
looking for machinery that is not there, which is worse than a gap.

So 2.2 is now "The story is a tree", written at the depth 1.2 and 1.3 are
written at: the seven bugs that turned out to be one bug, the lineage clause
and the two properties that make fork count free, why takes group by parent_id
rather than by coordinate, cursors becoming anchors, and a closing list of what
the design is honest about. 2.3 is rewritten around state_after and takes, and
1.1 and 1.5 follow, because the pipeline no longer snapshots before the call
and the memory bank no longer holds an action back.

The numbers were simply old: 151 tests where there are 440, 37 migrations where
there are 64, twelve phases where there are fourteen. They appear in four
places across the README, the project page's stat tiles and the guide's results
table. The measured branch cost — 103 B, and 1.007x the page load of the same
story flat — is added beside the egress and turn-cost figures it belongs with,
since it is the number that answers "what does branching cost me".

Three screenshots, on a new tools/shots_fixture.py: the Bandit Camp demo driven
through eight written turns with written deltas, three discarded takes forked
onto branches of their own, one off a branch so the map has to nest. Same
reason tree_fixture.py is committed — the shots have to be reproducible and the
frontend still has no test runner. play-world-state.jpg is reshot because it
predates the entire tree UI; the map and the branches panel are new.

Note for next time: docs/guide.html is hand-written, not generated from the
Markdown, so every guide edit is two edits in two vocabularies. Both files were
checked for tag balance and both pages rendered locally before this landed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DfMCsN1KBLsTqMkj5hSgrY
This commit is contained in:
parththakkar106
2026-08-20 04:19:53 +05:30
co-authored by Claude Opus 5
parent c8e081e9d6
commit 40d2555f84
10 changed files with 995 additions and 163 deletions
+40 -2
View File
@@ -3,7 +3,7 @@
Read this first when picking the project back up. Updated at the end of a working
session; the per-phase plan files hold the detail, this holds the thread.
**Last updated: 2026-08-18.**
**Last updated: 2026-08-20.**
---
@@ -200,7 +200,8 @@ an automated version; see SP7's entry in `plan/14`.
The Branches panel gained a **⌗ See the tree** button opening a full-screen map: one
horizontal lane per branch, running from the moment it left its parent to the moment it
ends, joined to the parent by an elbow at the fork. Clicking a lane selects it; the
footer switches, renames or deletes it. Not merged, not deployed. **440 backend tests
footer switches, renames or deletes it. **Merged to `main` and pushed on 2026-08-20**
(`c8e081e`), so it is on its way to Render with the rest of the branch. **440 backend tests
pass, unchanged — this is frontend-only.**
**It is a branch map, not the node map SP7 refused, and that is the whole reason it was
@@ -241,6 +242,43 @@ app serves `frame-ancestors 'none'`, so an in-page iframe has no reachable
`scrollWidth` against `clientWidth` instead, which tests the reflow path that actually
matters.
## What happened on 2026-08-20, part two — the published docs caught up
Everything the project publishes had drifted a full phase behind the code. The README, the
project page (`docs/index.html`) and the engineering guide (`docs/GUIDE.md` + its
hand-written `docs/guide.html`) all described a **linear** story: 151 tests, 37 migrations,
no tree, no takes, no branches. On branch `docs-story-tree`.
**The numbers that were wrong:** 151 → **440** tests, 37 → **64** migrations, "all twelve
phases" → fourteen. Those appear in four places between the README, the project page's stat
tiles, and the guide's results table.
**What was actively misleading, not merely stale.** The guide's §2.2 was *Two coordinate
systems, and the bug class they create*, and it explained the codebase through
`position_of_index`, `note_action_removed` and `settled_story_actions` — **all three deleted
in SP3**. §2.3 explained retry through `Action.variants` and `state_before`. A reader
following either would have gone looking for machinery that isn't there. §2.2 is now *The
story is a tree*, written at the same depth as §1.2 and §1.3: the seven bugs that were all
one bug, the lineage clause and its two properties, why takes group by `parent_id`, cursors
becoming anchors, and what the design is honest about. §2.3 is rewritten around
`state_after` and takes.
**Three screenshots**, shot on a new `backend/tools/shots_fixture.py` — the Bandit Camp demo
scenario driven through eight scripted turns, three discarded takes forked onto branches,
one of them off a branch so the map has to nest. It exists for the same reason
`tree_fixture.py` does: the shots have to be reproducible, and there is still no frontend
test runner. `play-world-state.jpg` was reshot (it predated the whole tree UI);
`branch-map.jpg` and `branches-panel.jpg` are new.
Worth not rediscovering: **`docs/guide.html` is hand-written, not generated from the
Markdown.** Every guide edit is two edits, and the HTML has its own vocabulary
(`.trap`/`.tag` callouts, `.stats`/`.stat`/`.v`/`.k` tiles) that has to be matched by hand.
The two files were checked for tag balance with `html.parser` and both pages were rendered
over a local `http.server` before committing — `file://` URLs are blocked from the browser
tooling, which is worth knowing before trying it again.
---
## What happened on 2026-08-18, part five — the review, and PR #6
The stack went up as **one PR (#6)** rather than seven stacked ones: `sp7-tree-ui` was