Design: prune removed packages; build-results spec approved

Prune removes built packages whose SlackBuild is gone (slackrepo remove
on a helper-computed list) without running Update all.

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

1 files changed, 42 insertions, 4 deletions

diff --git a/docs/design/2026-10-21-sb-builder-build-results-design.md b/docs/design/2026-10-21-sb-builder-build-results-design.md
index 27d6c40..f6e87b9 100644
--- a/docs/design/2026-10-21-sb-builder-build-results-design.md
+++ b/docs/design/2026-10-21-sb-builder-build-results-design.md
@@ -1,15 +1,16 @@
 # sb-builder: named builds and per-package results
 
 Date: 2026-10-21
-Status: draft
+Status: approved
 
 ## Goal
 
-Two fixes to how slackrepo jobs run several packages:
+Three fixes to how slackrepo jobs run:
 
 1. A never-built package can be built from the GUI by name.
 2. A job that builds several packages says which ones failed, and its status
    reflects that.
+3. Packages whose SlackBuild is gone can be removed without an Update all.
 
 One job keeps running every package given to it. Splitting into one job per
 package was considered and rejected: slackrepo already orders deps across
@@ -38,8 +39,9 @@ Changes (GUI only, the helper is unchanged):
   `slackrepo build --preview <pkgs>` instead of `update`.
 - The Packages tab drops its per-row **Update** action: **Build** now does
   the same thing.
-- **Update all** stays `slackrepo update` with no items: it scans the whole
-  package database and is what removes packages whose SlackBuild is gone.
+- **Update all** stays `slackrepo update` with no items. It still removes
+  packages whose SlackBuild is gone, but that is no longer the only way:
+  see section 3.
 
 ## 2. Per-package results of a job
 
@@ -85,12 +87,48 @@ is a separate job and keeps its own exit status.
   from the Jobs tab ribbon for the highlighted job, like a preview's next
   step.
 
+## 3. Prune: remove built packages whose SlackBuild is gone
+
+When SBo drops a SlackBuild (e.g. the package moved to the official tree),
+the built package stays in the repository until an Update all removes it.
+Prune does just that removal, without building anything.
+
+### Helper
+
+- New slackrepo action `prune` (`slackrepo prune [--preview]`). It takes
+  no package names: the helper computes the list itself, so no name crosses
+  the trust boundary. Items: `select distinct itemid from packages` in
+  `slackrepo_db` (read-only), keeping those with no
+  `<repo_dir>/<itemid>/<pkg>.SlackBuild`. argv:
+  `slackrepo --repo=... remove [--preview] <itemid>...`. slackrepo's
+  `remove` looks items up in the same `packages` table (`find_items -p`) and
+  honours `--preview`.
+- An empty list is an error at `job-start` ("nothing to prune"): no job.
+- `stats` gains `prunable`, the length of that list, for the GUI to enable
+  the action.
+- `signs()`: a real prune ends in `gen_repos_files.sh` like any slackrepo
+  run, so it signs: `kind == "slackrepo"` already covers it.
+
+### GUI
+
+- Packages tab ribbon: **Prune** after **Update all**, disabled with reason
+  "no built package lost its SlackBuild" when `prunable` is 0. It starts
+  `slackrepo prune --preview`. The preview lists what would be removed; the
+  NextStep runs `slackrepo prune` for real (the helper recomputes the list,
+  same result unless the tree changed in between).
+- The Dashboard's Built tile shows `N to prune` in its detail when
+  `prunable` is non-zero.
+
 ## Tests
 
 - `test_remote.py`: `cmd_run` on a fake slackrepo that writes rows to a
   temp `buildresults` db and exits 0: `results` filled; status `failed` when
   one row is `failed`, `ok` when all are `ok`; rows older than the job's
   start ignored; a preview job gets no `results`.
+- `test_remote.py`: `kind_slackrepo(["prune"])` on a temp db with one item
+  whose SlackBuild dir exists and one whose dir is gone: argv names only the
+  gone one; `--preview` passes through; package names are rejected; an
+  empty list raises.
 - `test_gui.py`: Packages tab has no Update action; the hint result's build
   request starts `build`; a finished job with a failed result opens
   `BuildResultDialog`, and Retry failed starts `build --preview` on the