1 files changed, 74 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-10-20-sb-builder-phantom-deps-design.md b/docs/superpowers/specs/2026-10-20-sb-builder-phantom-deps-design.md
new file mode 100644
index 0000000..46bc41c
--- /dev/null
+++ b/docs/superpowers/specs/2026-10-20-sb-builder-phantom-deps-design.md
@@ -0,0 +1,74 @@
+# sb-builder: phantom deps (phase 4b, part 1)
+
+Date: 2026-10-20
+Status: approved
+Builds on: `2026-10-20-sb-builder-phase4-design.md`, `2026-10-20-sb-builder-ui-design.md`
+
+## Goal
+
+Manage the -current phantom deps (deps SBo packages still require but
+Slackware -current ships) from sb-builder: the list, suggestions from the
+tree, and the `DELREQUIRES` sweep that mkhint's `-F` does today. Found when
+-current added zenity: 8 SBo packages require it, nothing in the GUI could
+mark it.
+
+## Facts
+
+- When a package enters the official tree, SBo removes it. A `REQUIRES`
+  name that matches no package of the repo is then left behind. On
+  2026-10-20 the tree has 140 such names, zenity among them; the 17 on
+  mkhint's list (`/root/.config/mkhint/phantom-deps`) are all among them.
+- sbshadow ends with `mkhint -F` (skipped on `--no`). mkhint's `-F` merges
+  the phantom deps found in each `.info` `REQUIRES` into the hint's
+  `DELREQUIRES`, `.bak` first, a minimal hint when there is none; it never
+  removes entries.
+- openvino moved into the personal overlay; only neovim still needs mkhint's
+  bundled-dep logic.
+
+## Helper (`sbb-remote` 0.7.0)
+
+- Config: `phantom_deps_file`, default `/etc/sb-builder/phantom-deps`: one
+  name per line, `#` comments, mkhint's format. Missing file = empty list.
+  `manifest_packages` default becomes `["neovim"]`.
+- `phantom-list`: `{"deps": [...], "suggestions": [{"name", "needed_by":
+  [...]}]}`. Suggestions: every `REQUIRES` name (without `%README%`) that
+  matches no package of the repo and is not on the list, sorted, with the
+  packages requiring it.
+- `phantom-add <name>...`, `phantom-remove <name>...`: names must match
+  `PKGNAME`, need not exist in the repo. Rewrites the file atomically,
+  comments kept, one name per line, no duplicates. Returns the new list.
+- Job kind `fix-current`: for every package whose `.info` `REQUIRES` names a
+  listed dep, merge those deps into `DELREQUIRES` of `<hintdir>/<pkg>.hint`
+  (union, first seen order; `.bak` only when it changes; a new hint has just
+  that line and no `.bak`). Unmanaged hint paths fail that package. Log one
+  line per changed hint, then `SBB-RESULT`. Add only, like mkhint.
+- `fix-current-now`: the same sweep run inline, its log on stdout, for
+  sbshadow.
+
+## sbshadow (slackrepo_setup)
+
+The end of a non-preview run calls `sbb-remote fix-current-now` in place of
+`mkhint -F`; without sbb-remote it says so and skips, as it does for mkhint
+today.
+
+## GUI
+
+Hints ribbon: **Phantom deps…** (between Delete hint and the end). A
+non-modal dialog:
+
+- the list, one name per row, with **Remove** for the selected rows;
+- a name field with **Add**;
+- **Suggestions**: tickable rows `name  needed by a, b, c`, **Add ticked**;
+- **Apply**: starts `fix-current` (the list itself is saved by each Add or
+  Remove at once); the usual diff dialog follows, with Revert per package.
+
+## Deploy (asks first)
+
+1. Helper 0.7.0.
+2. `/etc/sb-builder/phantom-deps` from mkhint's file (17 entries).
+3. sbshadow.
+
+## Out
+
+neovim bundled deps (phase 4b, part 2), removing mkhint and nvchecker from
+the VM (part 3), removing `DELREQUIRES` entries when a dep leaves the list.