plans: brief for row 186, the activate plan's backup line (P19 404, #1684)

2026-10-20 03:38:06 -05:00
parent b724b7b0bc
commit f5c72a5c3c
1 changed files with 66 additions and 0 deletions
@@ -0,0 +1,66 @@
+# Brief: the activate plan's backup line says what the run will do
+
+Sage, 2026-10-20, for Vikunja P19 404 (Filbert's N1 and N2 on row 185, #1683 comment 29404; filed by Mos
+in mos-0930, owner Sage). Gitea #1684. Owner Darkwing, reviewer Filbert, gate owner Sage. Base: the refactor head at
+briefing, b724b7b0b or later. No other open row touches `scripts/stack-release.sh`. Line numbers are at
+b724b7b0b.
+
+Nothing here runs against the live stack. Every test uses the stand-in `systemctl`, units, stores and data
+root that `packages/cli/tests/stack-release.test.mjs` already builds.
+
+## Why
+
+Row 185 (490e2771d) made every activate back up the stopped store, and `activate --plan` now prints one
+`backup:` line (:814-820). The plan prints the backup line whenever the store file exists. But `run_steps`
+(:846-849) rolls back with `store-newer` or `migration-needs-flag` before `backup_store`, so in those two
+cases the run takes no backup. The plan then says two things that can't both happen: the run would roll
+back, and the run backs up the store. T26 pins both lines together for the not-given `--migrate` case.
+That is N1.
+
+N2: `docs/TOOLS.md` "Pinned stack update" step 3 lists what `--plan` names and doesn't mention the
+backup line.
+
+Neither changed the Part A window, a 3i to 3i activate with no `--migrate`, where the line was right.
+
+## The change
+
+1. In `plan`, print the backup line only when the run reaches `backup_store`: an activate with a store
+   file whose schema equals the target's, or is in the target's chain with `--migrate` given. When the
+   run would roll back with `store-newer` or `migration-needs-flag` first, print
+   `backup: none; the run rolls back before the backup` instead. The no-store line and the rollback
+   branch (no line) stay as they are.
+2. When `S_CHANGED` is set the plan has no reliable schema to judge by. Keep today's backup line there,
+   and say in BUILD.md why that is the safe reading.
+3. Don't change `run_steps`, `backup_store`, any refusal code, exit code or flag. The run already does
+   the right thing; only the plan text moves.
+4. `docs/TOOLS.md` step 3 says the plan names the backup: where the run puts it, or why it takes none.
+
+## Tests
+
+1. Same-schema activate with a store: the plan prints today's backup line (T50 stays as it is).
+2. In-chain migration with `--migrate`: the plan prints the backup line.
+3. In-chain migration without `--migrate`: the plan prints the `needs: --migrate (not given; ...)` line
+   and `backup: none; the run rolls back before the backup`, and no other backup line. Update T26's
+   not-given case to match.
+4. Store outside the chain: the plan prints the `store-newer` line and the same `backup: none; ...` line.
+5. No store file: `backup: none; there is no store file` (T51 stays).
+6. Every case writes nothing, as `--plan` does today.
+
+Mutants, each killed by some gate test (mos-0862):
+
+- the plan ignores `--migrate` when it picks the backup line (today's text for the in-chain case)
+- the plan prints the backup line for a store outside the chain
+- the plan prints the `none; the run rolls back` line for a same-schema activate
+
+## Gate
+
+Filbert approves the candidate manifest. Cli suite and every `scripts/test-*.sh` green on Sage's gate, run
+from a git worktree of the candidate. Touched files: `scripts/stack-release.sh`,
+`packages/cli/tests/stack-release.test.mjs`, `docs/TOOLS.md`, and the packet. Anything else gets named in
+BUILD.md with the reason.
+
+## Out of scope
+
+Any change to what the run does: the backup, its layout, the restore guard, a refusal or a flag. The
+row 178 proof flags in `activate` (mos-0928 Part B, the A0 tool row). Any run against `~/.mosaic-dev` or
+the live units. Going live needs a re-pin, which is a later window, not this row.