Phase 3 design: full repo rebuild as a guarded job

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2 files changed, 52 insertions, 0 deletions

diff --git a/docs/design/2026-10-19-sb-builder-phase1-design.md b/docs/design/2026-10-19-sb-builder-phase1-design.md
index 3ec3fc0..6d9c7f9 100644
--- a/docs/design/2026-10-19-sb-builder-phase1-design.md
+++ b/docs/design/2026-10-19-sb-builder-phase1-design.md
@@ -21,6 +21,7 @@ Each phase gets its own spec, plan and implementation cycle.
    (search and filter by name, category, overlay, maintainer, build status);
    Build, Rebuild, Bulk update screens.
 3. **Full repo rebuild**: `slackrepo_setup_SBo-danix.sh`, destructive, guarded.
+   See `2026-10-21-sb-builder-phase3-design.md`.
 4. **Hints**: mkhint browse, edit, update, create, `-F`, diff before save.
    Requires non-interactive flags in mkhint (it has about 10 `read -p`
    prompts and wraps slackrepo at `mkhint:1798`). Also: `--no-dl` must write
diff --git a/docs/design/2026-10-21-sb-builder-phase3-design.md b/docs/design/2026-10-21-sb-builder-phase3-design.md
new file mode 100644
index 0000000..f422cbb
--- /dev/null
+++ b/docs/design/2026-10-21-sb-builder-phase3-design.md
@@ -0,0 +1,51 @@
+# sb-builder phase 3: full repo rebuild
+
+Date: 2026-10-21
+Status: approved
+
+## Goal
+
+Run `slackrepo_setup_SBo-danix.sh` from the GUI as a job: replace the
+SBo-danix tree with a fresh clone of upstream plus the personal and
+pentesting subtrees, then reapply shadowing. This rebuilds the git tree, not
+the packages.
+
+## Script (`slackrepo_setup` repo)
+
+Two changes to `slackrepo_setup_SBo-danix.sh`:
+
+1. Build the new tree beside the live one. Clone, branch and add subtrees in
+   `$REPO.new` (a stale `.new` from an earlier failed run is removed first).
+   Only when that succeeds: `mv $REPO $REPO.old`, `mv $REPO.new $REPO`. A
+   failed clone or subtree add leaves the live tree untouched.
+2. After the swap, run `sbshadow --yes` (bare `sbshadow` prompts; a job's
+   stdin is `/dev/null`, so the prompt reads EOF and shadowing is silently
+   skipped). It runs on the real path, so its `sbb-remote fix-current-now`
+   sees the new tree. When it succeeds, `rm -rf $REPO.old`. When it fails,
+   `set -e` stops the script and `.old` stays for a manual rollback (`mv`).
+
+Disk: the tree is about 600M; peak use during a run is about 1.2G.
+
+## Helper (`sbb-remote`)
+
+New job kind `rebuild-tree`, no arguments, argv
+`["slackrepo_setup_SBo-danix.sh"]` (on PATH, like `sbshadow`). Runs under
+the job flock, so it never overlaps a slackrepo run or a sync. Version bump.
+
+## GUI
+
+Jobs tab main ribbon: "Rebuild tree", after the sync actions. Modal confirm
+(destructive step): replace SBo-danix with a fresh clone. No next-step
+dialog; other tabs read the new tree on their next reload.
+
+## Testing
+
+`test_remote.py`: `rebuild-tree` builds its argv and rejects arguments.
+`test_gui.py`: the action asks for confirmation and starts the job only on
+yes. The script change is tried on the VM against a throwaway path before
+deploying.
+
+## Out of scope
+
+A GUI rollback action: the rollback window is only a failed sbshadow, and
+`mv` covers it.