Fill in the change log hash for the builder's return and link check

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: claude

docs/changelog.md

@@ -367,7 +367,7 @@ zero across these commits; several were pre-existing bugs the old markup had bee
 | `539422c6d` | **Stage 1 assembled, run, and the suite found that its file list was a guess: 150 failures from five files nobody had listed.** It built, booted, and then failed with `Sprockets::Rails::Helper::AssetNotPrecompiledError` on `controllers/csv_download_controller.js` — an asset that is on `main`, is declared in `main`'s `manifest.js`, and has nothing to do with the design system. **The control made it tractable in minutes**: the same example passes on pristine `main`, so the stage caused it; asking Sprockets directly gave `manifest.js found: false` against `true` with 68 links on main, and one extra load path — `app/assets/tailwind`. Tailwind v4 source uses `@import "tailwindcss"`, Sprockets cannot parse it, **the whole manifest dies and every asset then reports as not precompiled**, so the error names whichever one the layout asked for first. `cda053539` had already solved this in `config/initializers/assets.rb`, with a comment saying Sprockets must serve the build and never the source — **and stage 1's paths listed no initializers at all.** Five files were missing: that initializer, `simple_form_essentials.rb`, `config.assets.css_compressor = nil` from `config/application.rb`, and two specs — `asset_resolution_spec.rb`, which pins which `application.css` wins and is the guard for precisely this, and `essentials_shell_spec.rb`. **Three rules, all now enforced by the builder rather than written down.** *A stage carries its own specs* — stage 1 listed none, and the spec that would have caught this was in the source commit, unlisted. *Additive by default, every overwrite named* — the stage silently replaced `confirmation_controller.js` and `donations_modal_controller.js`, both rewritten at `cda053539` from Bootstrap's modal to the native `<dialog>`; stage 1 migrates no views, so main's `<div class="modal">` would have reached `showModal()`, which is not a function on a div. `overwrite:` is an allowlist now and anything else is reverted and reported. *Some files are neither taken nor one-line composed* — `config/application.rb` at `cda053539` also switches the Devise layouts to `essentials_auth`, a later stage, so it is an `insert:` of anchor plus text. **Two environment traps** joined the checklist: main's lock omits `aarch64-linux` so `tailwindcss-ruby` has no executable (the builder adds the local platform), and **Sprockets caches its manifest in `tmp/cache` across branch switches**. Also found: `bin/rails` cannot run *any* rake task on this mount — it is case-insensitive, `File.exist?("rakefile")` answers true, and Rake loads the lowercase spelling and fails; `bundle exec rake -f Rakefile` works. Stage 1 `--check` now: 58 files. |
 | `0282f2c71` | **Two fixes to the stage builder, both from watching it run.** The additive check reverted the script's *own* composition: its allowlist was only `overwrite:`, so the first run undid the `.gitignore` entry the `ignore:` step had written a moment earlier and the 120KB Tailwind build came back as an untracked artifact. The allowlist now includes what the script composed — the `insert:` targets and `.gitignore`. **And the builder commits the stage.** A stage left staged-but-uncommitted is a trap that has now sprung twice: the next `git checkout design` is *refused*, `-q` swallows the message, and the commit intended for `design` lands on the stage branch instead — the first time it looked as though `build-stage.rb` had vanished, the second time a builder fix was committed onto stage 1 under the wrong message. Both times `git checkout` had told the truth and nothing had read it. A built stage is meant to be a reviewable commit anyway, and a clean tree makes switching away work. Verified on the rebuild: 2 controllers reverted, `.gitignore` kept. |
 | `2cdc62152` | **Stage 1 rebuilt with the five missing files: 150 failures down to 13, then to 2 that it does not cause.** `2,976 examples, 13 failures`. Ten were `essentials_shell_spec.rb` — the stage's own new spec, and **it does not belong to stage 1**: it asserts that real pages render the essentials chrome (Tailwind stylesheet and not the Bootstrap one, one `<main>`, `aria-current="page"`, self-hosted fonts) and stage 1 switches no controller to the new layout, so every example measures a later stage. Deferred to the first stage that switches a controller to `essentials_app`. *Adding a stage's specs is right; adding the specs of the stage after it only looks right.* One was `asset_resolution_spec.rb` finding a **sixth missing path**: `public/vendor/`, the Figtree and Bootstrap Icons woff2 files the built stylesheet points at — the spec earned its place immediately. **The last two were not the stage, and the controls say so rather than intuition.** Two date-range-picker examples in `distribution_system_spec.rb` failed in the full run; on **pristine main in isolation, 6 examples 0 failures**, which pointed at the stage — but on the **stage in isolation, also 6 and 0**, and the whole 55-example file passes on the stage too. So they are order-dependent or flaky across files, not a regression, and the honest next step is the full suite at the same seed (8576) rather than a claim either way. Stage 1 `--check` is 69 files. |
-| `TBD` | **The stage builder puts you back where you started, and checks its own markdown links — both learned by walking into the same trap three times in one hour.** Building a stage leaves you *on* the stage branch, where `bin/design/` does not exist; the next edit to the builder then writes into a branch that has no such directory, and the next `git checkout design` is refused because the stage is half-built. It looked like a lost file once, a commit on the wrong branch once, and a `git stash pop` conflict once. **Printing "Return with: git checkout design" was not enough — it was printed all three times.** The builder now runs the checkout itself, on the success path *and* the failure path. **Step 0 of the review plan is code now**: every relative link in a markdown file the stage touches must resolve against the files the stage contains. Only the stage's own files are checked, because `main` carries **19 broken links of its own** in `docs/user_guide` and elsewhere and a check that reports those every run is one people stop reading. It found the one that matters: `design.md` links to `docs/design-decisions.md`, 9,700 lines covering every stage, which has no business arriving with the first. A `replace:` key rewrites it to a plain code span. **Watched failing first**: with `replace:` removed the build stops at exit 4 and names the link. Two false starts on that control are worth recording — the first ran the variant from `/tmp`, where `ROOT` is not a git repository, and the second was defeated by the `git stash` that was supposed to clean the tree, which restored the good file before the run. The discipline that actually works: **commit the tool, then test it.** |
+| `095ebf5ad` | **The stage builder puts you back where you started, and checks its own markdown links — both learned by walking into the same trap three times in one hour.** Building a stage leaves you *on* the stage branch, where `bin/design/` does not exist; the next edit to the builder then writes into a branch that has no such directory, and the next `git checkout design` is refused because the stage is half-built. It looked like a lost file once, a commit on the wrong branch once, and a `git stash pop` conflict once. **Printing "Return with: git checkout design" was not enough — it was printed all three times.** The builder now runs the checkout itself, on the success path *and* the failure path. **Step 0 of the review plan is code now**: every relative link in a markdown file the stage touches must resolve against the files the stage contains. Only the stage's own files are checked, because `main` carries **19 broken links of its own** in `docs/user_guide` and elsewhere and a check that reports those every run is one people stop reading. It found the one that matters: `design.md` links to `docs/design-decisions.md`, 9,700 lines covering every stage, which has no business arriving with the first. A `replace:` key rewrites it to a plain code span. **Watched failing first**: with `replace:` removed the build stops at exit 4 and names the link. Two false starts on that control are worth recording — the first ran the variant from `/tmp`, where `ROOT` is not a git repository, and the second was defeated by the `git stash` that was supposed to clean the tree, which restored the good file before the run. The discipline that actually works: **commit the tool, then test it.** |