# Freezing The First Book **version** v0.3.27 · **date** 23 August 2026 **source** memo 2 in full --- ## What is being frozen, and why The first book is the record of how this was worked out, including three corrections to claims it made about itself, a ladder that ran out of altitude, and a contradiction it reached twice by two different routes. That record is worth more intact than improved. Memo 2 is explicit: "I don't want the new stuff to overwrite what we've done there because historically there's a lot of stuff there to learn." **The first edition freezes at v0.3.26**, the release that shipped the retrospective brief. That is not arbitrary: it is the last release in which the first book was the only book. --- ## ADR-1 · How the freeze is done **Status** DECIDED by the founder, 23 August 2026, and it is a **move**, not a copy. > "the copy of v1 should actually be move of all the relevant files to a folder structure that > is prefixed with `v1/*`, since some of those files might be good references of v2 (which > should have its own copy of the files used in that version). But at the moment v2 is empty" ### The decision Every file that constitutes the first edition **moves** to a `v1/` prefix. Nothing is duplicated. When the second book needs a file, it takes **its own copy** into `v2/`, which is how an edition ends up owning everything it uses. ``` v1/ the first edition, complete, frozen at v0.3.26 v2/ empty. The second book takes copies into here as it needs them. ``` This is better than the copy proposed earlier, for a reason worth recording: a copy leaves two live trees and no rule about which one is authoritative, so the first thing that happens is somebody edits the wrong one. A move leaves exactly one, and the `v1/` prefix makes an edition's boundary visible in every path. ### What moves | Moves to `v1/` | Why | |---|---| | `book/` | the first edition itself: 22 pages, both PDFs, the cover, the version diff | | `content/` | its 17 source units | | `start/` `why-graphs/` `grammar/` `depth/` `examples/` `maps/` `shipped/` `origins/` `network/` `glossary/` `about/` | the sixteen chapter-source pages: they are the same text as the chapters and freeze with them | | `altitudes/` | the ladder pilot, which was built over the first edition | | `vaults/` | the evidence estate as the first edition cited it | | `docs/` | the twenty-one carried sources as the first edition used them | | `briefs/` and `documents/` | the brief pack that produced it and the readers over it | | `reviews/` | the four reviews of it | | `index.html`, `index.md` | the front page, which is also the book's introduction source | | Stays at the root | Why | |---|---| | `assets/` | the site's stylesheet, scripts and vendored libraries, shared by both editions | | `admin/` | engineering, release history, comms, publishing: site-level, not edition-level | | `decisions/` | the register spans editions by design | | `dev-pack/`, `dev-packs/` | this pack. It belongs to the second book, not the first | | `llms.txt`, `llms-full.txt`, `sitemap.xml`, `robots.txt`, `LICENSES.md` | the site's own surface | The boundary is one `git mv` away from being different. If a tree is on the wrong side, moving it is a single command plus a regenerate, and the gates will say if a link broke. ### The URLs A move changes every URL under the moved trees. **Every moved HTML page keeps a stub at its old address**: a generated redirect carrying a canonical link to the new location and a visible line saying where it went and why. Roughly a hundred small files, generated by `gen_redirects.py`, excluded from the freeze manifest because they are not part of the edition. **Two URLs cannot be preserved this way**: the print and screen PDFs, because a PDF cannot carry a redirect. Their old addresses stop working and the new ones are under `v1/book/`. That is the one unavoidable cost of the move and it is recorded rather than discovered later. ### The gate that makes the freeze real A rule with no enforcement is a preference. `validate.js` gains: ``` gate 14 every path listed in v1/MANIFEST.json must still hash to its recorded SHA-256. The build fails on any difference. ``` This is the same mechanism already protecting the twenty-one carried source documents, applied to the site's own history. It is verified negatively before the freeze is declared done: change one byte, watch the build fail, put it back. ## The front page that explains everything Memo 2.3: "we should have a front page that just links to everything and explains everything, including explains the sequence of events." **`/books/first-edition/index.html`**, and it is the only new writing the first edition receives. It is not a summary of the book. It is an account of how the book happened, which is the part that is currently spread across the release history, the comms board, four reviews and a retrospective brief, and which nobody can read in one sitting. Contents, in order: 1. **What the first edition is**, in a paragraph, and how to read it: the reader, the single page, the print PDF, the screen PDF. 2. **The sequence of events**, as a dated narrative from v0.1.0 to v0.3.26. Thirty-four releases, generated from the release table rather than retold, with the six that changed the method called out in prose. 3. **The four reviews**, what each one asked for and what it changed. 4. **What it got wrong**, which is the section that justifies keeping it. Three corrections it made to itself, the ladder findings still open, and the honesty table's known defects. 5. **What carried forward**, linking each surviving idea to where it lives in the second book. This section is written last and updated once, when the second book's level 3 exists. 6. **Everything in it**, as a complete index: every chapter, every page, both PDFs, the cover, the ladder, the concept map, the reviews, the decisions as they stood. Sections 2 and 6 are generated. Sections 1, 3, 4 and 5 are written. --- ## What the second book takes, and how it records that it took it Material moves by copy, and every copy records its origin, in the same shape the carried source documents already use: ```json { "from": "books/01__first-edition/source/grammar.md", "sha256": "…", "release": "v0.3.26", "verdict": "CARRY", "changed": "none" } ``` A `verdict` of `LIFT` or `REWRITE` records the origin without claiming the text is the same. The point is not to prove the second book is a copy. It is that **for any passage in the second book, a reader can ask where it came from and get an answer**, which is the provenance chapter applied to the book itself rather than to somebody else's regulation. This also answers a question the decoupling decision (r003-D1) has been holding open: the relationship between editions is provenance edges, not equality. The second book is decoupled from the first by construction, because it is a different tree that cites its ancestor. --- ## What does not freeze The estate keeps moving: `/vaults/`, `/docs/`, `/documents/`, `/reviews/`, `/decisions/`, `/admin/`. These belong to the site rather than to an edition. Both editions cite them, and their movement is why editions need to be frozen in the first place. The one consequence to note: a frozen chapter can cite a moving vault page, and the vault page can change under it. That is acceptable and it is why the carried sources record hashes. If it becomes a problem, the answer is the one the corpus already gives: an index is not a source, and a citation without a date is indistinguishable from a claim. --- This document is released under the Creative Commons Attribution 4.0 International licence (CC BY 4.0).