From 4ec279dc43922b338a94718a2afdaba87ef89c15 Mon Sep 17 00:00:00 2001 From: Jason Woltje Date: Fri, 23 Oct 2026 22:47:34 -0500 Subject: [PATCH] docs: run-sheet doc row brief, five operator gaps (mos-1566, ops-0282, ops-0291, ops-0292) --- docs/plans/2026-10-24_run-sheet-doc-brief.md | 78 ++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 docs/plans/2026-10-24_run-sheet-doc-brief.md diff --git a/docs/plans/2026-10-24_run-sheet-doc-brief.md b/docs/plans/2026-10-24_run-sheet-doc-brief.md new file mode 100644 index 000000000..ce3e24fa9 --- /dev/null +++ b/docs/plans/2026-10-24_run-sheet-doc-brief.md @@ -0,0 +1,78 @@ +# Host run sheet: five operator gaps from the .53 and Run B installs (#414 stage 2) + +Written 2026-10-24 by Sage for Mos's mos-1566 item 1, from ops-0282, ops-0288, ops-0291, ops-0292, +Duckworth's 323 N2 and Mos's rulings mos-1563 and mos-1565. + +## Brief: five run-sheet gaps + +**Why.** Five things stopped or slowed operators on the .53 stage 2 install and 433 Run B. Each is a gap +in `docs/guides/host-run-sheet.md` (checked at 3d2569ce2), not a product bug. The code they describe has +landed. This row writes them down. + +**What to write.** Edit only `docs/guides/host-run-sheet.md`. Source every command, path and message from +the code or the receipts named here, and cite the line you read, the way the sheet already does +(`scripts/stack-release.sh:14`). Don't invent a flag, path or exit code. + +1. **B2-2, the Console proof file format** (DEFERRED.md "ops-0282 B2-2", ops-0282). In section 9's .54 + library table (:321), the proof file row's File cell gives mode and owner but no format. Add it: one + base64url line of at least 32 characters, `[A-Za-z0-9_-]` only (packages/webui/src/serve.mjs:264). The + Console exits 2 at start otherwise (:267). `case2-unit.sh` doesn't open the file, so a bad proof fails + only at Console start. Read serve.mjs:255-270 yourself and match what it checks, including whether a + trailing newline is accepted. +2. **N2, a missing project file only warns** (Duckworth 323 round 1 N2, ROUND1-6a0f0f4f8.md). When the + project root a business file names has no `.mosaic/project.json`, `mosaic business validate` passes + with the warning "no project file at ... it has no project variables" (packages/business/src/cli.mjs:74-78). + An install on such a host passes step 7 with the project's variables missing. Say so where the sheet + describes `case2-install.sh` (near :278), and tell the operator to treat that warning as a stop. +3. **The pre-install validate step** (mos-1563, ops-0288). Before `case2-install.sh`, check by hand that + each `projects` key in the business file equals the `id` in `/.mosaic/project.json` + in the stack's user's clone, and that the file exists. The loader refuses a mismatch + (packages/business/src/cli.mjs:80) at step 7, after the copy is made. The check must use only what the + host has at that point: coreutils, grep, or the pinned node under `/opt/mosaic-stack/node-/bin` + (section 2), run as the stack's user. Give the expected output for a match and say a mismatch is a + stop: fix the business file, not the project id (mos-1563). +4. **The retry path after a failed first install** (mos-1565, ops-0291). Section 6 has no retry form. + What happened on .53: a refused `case2-install.sh` left `/.config/mosaic-dev/config.json` behind + (bootstrap ran at step 1), and the first refusal also left an empty `businesses/` dir in that config + dir. The operator then used the upgrade form's fetch, which writes the bundle to + `refs/remotes/origin/refactor` and doesn't move `refs/heads/refactor`, so `stack-copy.sh copy` refused + with "not reachable from refs/heads/refactor". Mos's ruling: move the clones aside and rerun section + 6's first-install form. Write that as a short "If the first install refuses" block in section 6: + - which paths move aside: root's checkout `/root/mosaic-stack`, the stack's user's clone + `/srv/mosaic/src/mosaic-stack`, and the stack's user's config dir. Read `scripts/case2-install.sh` + (bootstrap at step 1, :172, :200, :210-211) and `scripts/bootstrap.sh` to list what an install + writes before it can refuse, and name only those paths; + - move, never delete: `mv` to a name with a UTC timestamp suffix, as root, keeping owner and mode; + - what the operator must re-place afterwards if a credential slot under that config dir was already + filled (section 9). If nothing in section 9 can be filled before the first install, say that; + - then rerun the first-install block from its first line. Never use the upgrade form's fetch on a + clone that a first install hasn't finished with. +5. **Checking a backup's SHA256SUMS by hand** (ops-0292). The sheet has no backup check today. A backup set + under `/backups/stack//` holds `SHA256SUMS` with paths relative to `bus/` + (scripts/stack-release.sh:482 writes `(cd "$o/bus" && sha256sum bus.sqlite) > "$o/SHA256SUMS"`), and + the tool checks it with `(cd "$o/bus" && sha256sum -c --quiet ../SHA256SUMS)` (:502, :2244). Running + `sha256sum -c SHA256SUMS` from the backup dir itself fails (rc 1, "FAILED"), because `bus.sqlite` is + in `bus/`. Add a short paragraph after the upgrade exits in section 6 that gives the `bus/` form for an + operator who wants to check a backup before a rollback or restore. Read :475-510 to confirm the + layout first. + +Keep the sheet's voice: short sentences, the path and line for each claim, no em dashes. Don't renumber +sections. Don't touch any other file except your BUILD.md. + +**Test.** None ships. Before the review request, show that no test or script reads the sheet: +`git grep -n host-run-sheet -- 'packages/*/tests/*' 'scripts/*'` prints nothing, with a positive control +that the same command form finds a path you know a test reads. Also grep the tests for a 64-hex pin next +to the sheet's name. If any test reads the sheet, stop and tell Sage. + +**Gate.** Doc only (decision 137). No suite run is needed from you, and no CLEAR. Sage's landing gate +runs every suite (mos-1455). The reviewer checks every new claim against the cited line. + +**Boundaries.** No host action, no .53, .54 or 1013 contact, no credential reads, no push to refactor. +Claimant queue moves are yours (start, in-review). Work in a new worktree off refactor at 3d2569ce2 or +later, on branch `goldie/row-run-sheet`. Push the branch and report the tip, base and manifest to Sage +and to the reviewer. Record choices in `agents/goldie/work/queue-/BUILD.md`. + +**Acceptance.** An operator following the sheet can see the proof file format, treats the missing +project file warning as a stop, checks the project key before install, has a written retry path after a +refused first install, and can check a backup by hand with the form that works. Every new claim cites a +line that says it.