docs: brief for human and tester commands from the checkout (Vikunja #287)

Mos asked for a row after the #284 go-live: the checkout's scripts/mosaic is refused tester-required and human-required because the bus proofs accept only the pinned copy's entry paths. README text, a TOOLS.md sentence and one stderr hint line; no redirect to the live copy. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-14 17:24:56 -05:00
parent 7651e6b1dd
commit 9edac91073
1 changed files with 57 additions and 0 deletions
@@ -0,0 +1,57 @@
+# Human and tester commands from the checkout (2026-10-14)
+
+Filed by Sage at Mos's request after the #284 go-live (Vikunja #287).
+The section below is one queue row's brief.
+
+## Human and tester commands name the tree the bus runs from
+
+Small. Owner Rocko, reviewer Filbert.
+
+### Problem
+
+Since row 85 the bus runs from a pinned copy under
+`${XDG_DATA_HOME:-$HOME/.local/share}/mosaic-stack/copies/<id>/`. The
+broker's proofs are path-bound: `packages/bus/src/runtime.mjs:80` accepts a
+tester only from its own tree's `tester-cli.mjs`, and the human proof
+accepts only its own `human-cli.mjs`. So `scripts/mosaic talk --tester`
+from the canonical checkout exits 3 `tester-required`, and the human
+commands from the checkout exit 3 `human-required`, while the same
+commands through `mosaic` on PATH (the Q81 wrapper, which execs the copy's
+`scripts/mosaic`) work. Mos hit this in the #284 go-live on 2026-10-14.
+Nothing says so where a reader would look: `packages/cli/README.md`
+under `--tester` and "One pinned copy" says the bus, Console and wrapper
+must share a tree, but not that the checkout's own `scripts/mosaic` is
+refused for these commands, or which command to run instead.
+
+### What ships
+
+1. `packages/cli/README.md`, in the `--tester` bullet and in "One pinned
+   copy": the human commands and `--tester` run only from the tree the bus
+   runs from. On a host with a pinned copy that is `mosaic` on PATH, and
+   the checkout's `scripts/mosaic` exits 3 with `human-required` or
+   `tester-required`. Queue writes stay on the checkout's `scripts/mosaic`.
+2. `docs/TOOLS.md`, in "Pinned stack update", one sentence that says the
+   same and points at the README.
+3. In `packages/cli/src/`, when a human or tester command is refused with
+   `human-required` or `tester-required`, one more stderr line: "the bus
+   accepts these commands only from the tree it runs from; on a pinned
+   host run `mosaic` on PATH". The exit code stays 3, and the line adds no
+   path the CLI doesn't already know.
+
+### Not in this row
+
+The checkout's `scripts/mosaic` doesn't redirect to the live copy. That
+would tie every checkout to the live switch, and a redirect for some verbs
+but not the queue verbs makes it unclear which tree a command ran from.
+No change to the proofs, the bus or the wrapper.
+
+### Acceptance
+
+- A test that each of `human-required` and `tester-required` prints the
+  extra line and still exits 3, and that another exit-3 refusal
+  (`tester-off`) doesn't print it.
+- One mutant: drop the extra line. A test fails.
+- The cli package suite (`node --test packages/cli/tests/`) green, plus
+  the targeted gate (decision 136). Sage reruns the full gate at the landing target.
+- No live step. The copy picks up the change at the next re-pin, on Mos's
+  go (decision 109).