repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit companion parity matrix

63ea075756382b6e8f6d3b007707bfd95f71260f

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (4)

docs/super/inventory/2026-06-17-quickshell-self-contained-audit.md

Modified
13 13 `quickshell/nugu/audit.sh` checks repository state only:
15 -- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `IPC.md`, `EXTERNALS.md`, `SERVICE.md`, `audit.sh`, `smoke.sh`.
15 +- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `IPC.md`, `EXTERNALS.md`, `SERVICE.md`, `PARITY.md`, `audit.sh`, `smoke.sh`.
16 16 - every QML component is listed in `COMPONENTS.md` with purpose and rollout status.
17 17 - every `nugu` IPC method from `shell.qml` is listed in `IPC.md` with purpose and rollout status.
18 18 - component, IPC, and external inventory rows reject duplicates, malformed names, thin text, and placeholder wording.
19 19 - every approved executable boundary is listed in `EXTERNALS.md` with status and reason, and stale unused rows fail.
20 20 - future service rollout is documented in `SERVICE.md`; `hypr/systemd/quickshell.service` must start `qs -c nugu`, and `x230.symlinks` must link both config and service.
21 +- replacement scope is documented in `PARITY.md`, including old companion retirement targets and human approval.
21 22 - QML imports are limited to Qt, Quickshell, and local `import "."`.
22 23 - every QML component has an early decision comment.
23 24 - QML comments do not contain unresolved TODO/stub/placeholder markers; rollout status belongs in inventories.
59 60 detected_external_commands=25
60 61 inventory_tables=ok
61 62 service_contract=ok
63 +parity_matrix=ok
62 64 contrast_pairs=12
63 65 contrast_min=5.50
64 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,audit.sh,smoke.sh
66 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh
65 67 external_commands=awk,brightnessctl,cliphist,cut,grep,head,hyprctl,hyprlock,hyprpicker,hyprshot,iwctl,loginctl,makoctl,nu,playerctl,satty,sed,sh,systemctl,upower,uptime,uwsm,wezterm,wl-copy,wpctl
66 68 WARN transitional external bridge still present: cliphist
67 69 WARN transitional external bridge still present: makoctl
75 77 detected_external_commands=25
76 78 inventory_tables=ok
77 79 service_contract=ok
80 +parity_matrix=ok
78 81 contrast_pairs=12
79 82 contrast_min=5.50
80 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,audit.sh,smoke.sh
83 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh
81 84 external_commands=awk,brightnessctl,cliphist,cut,grep,head,hyprctl,hyprlock,hyprpicker,hyprshot,iwctl,loginctl,makoctl,nu,playerctl,satty,sed,sh,systemctl,upower,uptime,uwsm,wezterm,wl-copy,wpctl
82 85 WARN transitional external bridge still present: cliphist
83 86 WARN transitional external bridge still present: makoctl

quickshell/nugu/PARITY.md

Added
new file mode 100644
1 +# Nugu Quickshell companion parity matrix
3 +This file keeps the replacement objective next to the self-contained config. It
4 +is not a completion claim. Rows stay pending until live parity and human visual
5 +approval prove that the old companion can be retired.
7 +| Current companion surface/tool | Quickshell replacement | Current status | Retirement gate |
8 +| --- | --- | --- | --- |
9 +| `ironbar.service` top bar | `Bar.qml` plus status widgets | Implemented hidden-by-default. | Multi-monitor, wheel, click, tray, screenshots, perf, and human style approval. |
10 +| `ironbar-workspaces.service` | `WorkspaceWidget.qml` | Implemented in the bar. | Live workspace click/scroll parity and same-workspace screenshots. |
11 +| Ironbar tray module | `TrayWidget.qml` | Implemented. | Real tray client and menu forwarding validation. |
12 +| Ironbar notification count/actions | `NotificationBridgeWidget.qml` | Transitional Mako bridge. | Native notification history/actions replace bridge. |
13 +| `mako.service` notification daemon | `NotificationDaemon.qml` and `NotificationToast.qml` | Implemented but disabled by default. | Healthy user DBus, urgency, timeout, dismiss, action, restore, and rollback tests. |
14 +| `makoctl` notification controls | Native notification IPC plus bar widgets | Transitional bridge remains. | Audit no longer warns about `makoctl`, and Mako is approved for retirement. |
15 +| `hyprlauncher` app launcher | `Launcher.qml` and launcher IPC | Implemented and scaffold verified. | Live bind migration, app launch proof, keyboard/mouse parity, screenshots. |
16 +| `hyprlauncher --dmenu` clipboard picker | `ClipboardPicker.qml` | Frontend implemented. | Storage decision made; `cliphist` bridge either accepted or removed before old launcher retirement. |
17 +| `cliphist` clipboard storage/actions | `ClipboardWidget.qml` and `ClipboardPicker.qml` | Transitional backend remains. | Audit no longer warns about `cliphist`, or storage bridge is explicitly approved as retained infrastructure. |
18 +| `hyprshutdown` power UI | `PowerMenu.qml` and `PowerWidget.qml` | Dry-run matrix verified; destructive actions gated. | Lock/sleep/logout/reboot/poweroff parity with explicit destructive-action approval. |
19 +| `hyprctl notify` OSD wrappers | `Osd.qml` and OSD IPC/action methods | Implemented. | Real Hypr keybind validation for audio, brightness, media, capture, color, lock, and reload actions. |
20 +| Hypr companion binds | `qs ipc -c nugu call nugu ...` | IPC surface documented. | Quickshell service live/recoverable, then Hypr config simplified and old references removed. |
22 +## Non-negotiable rollout boundary
24 +Ironbar, Mako, old helper commands, and current Hypr binds remain authoritative
25 +until their row gates pass. Retiring any row requires verification evidence and
26 +human approval for the visual/style claim.

quickshell/nugu/README.md

Modified
29 29 `COMPONENTS.md` inventories every QML file with why it exists and current rollout
30 30 status. `IPC.md` inventories every `nugu` IPC method Hypr binds can later target.
31 31 `EXTERNALS.md` inventories every approved executable boundary. `SERVICE.md`
32 -documents the future user-service rollout contract without activating it. The
33 -audit checks that required named-config files are present, every QML component and IPC method
32 +documents the future user-service rollout contract without activating it.
33 +`PARITY.md` maps current companion apps/tools to their Quickshell replacements
34 +and retirement gates. The audit checks that required named-config files are present, every QML component and IPC method
34 35 are documented with non-thin inventory rows, QML imports stay local/Qt/Quickshell, every component has an
35 36 early decision comment, QML has no unresolved TODO/stub comments, local resources
36 37 are audited, the bundled palette matches
37 38 `hypr/generated/nugu.json`, critical Nugu foreground/background pairs keep at
38 39 least 4.5 contrast, external commands are documented without stale rows, the
39 40 future user service starts the named config, the x230 dorkfiles manifest links
40 -that service/config pair, and retired companion launchers are not executable dependencies. It intentionally
41 +that service/config pair, the parity matrix still names old companion retirement
42 +targets, and retired companion launchers are not executable dependencies. It intentionally
41 43 warns while
42 44 transitional `cliphist` and `makoctl` bridges remain; those warnings must
43 45 disappear before final retirement.

quickshell/nugu/audit.sh

Modified
19 19 warnings = []
20 20 qml_files = sorted(config_dir.glob("*.qml"))
21 21 code_by_file = {}
22 -required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "SERVICE.md", "audit.sh", "smoke.sh")
22 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh")
24 24 for name in required_files:
25 25 if not (config_dir / name).exists():
216 216 errors.append("missing x230.symlinks")
218 +parity_doc = config_dir / "PARITY.md"
219 +if parity_doc.exists():
220 + parity_text = parity_doc.read_text().lower()
221 + required_parity_markers = (
222 + "ironbar.service",
223 + "ironbar-workspaces.service",
224 + "mako.service",
225 + "makoctl",
226 + "hyprlauncher",
227 + "hyprlauncher --dmenu",
228 + "cliphist",
229 + "hyprshutdown",
230 + "hyprctl notify",
231 + "traywidget.qml",
232 + "qs ipc -c nugu call nugu",
233 + "human approval",
235 + for marker in required_parity_markers:
236 + if marker not in parity_text:
237 + errors.append(f"PARITY.md missing replacement marker {marker!r}")
238 +else:
239 + errors.append("missing PARITY.md")
218 241 # Keep executable dependencies explicit. Quickshell can replace companion UI,
219 242 # but system/session CLIs still exist at command boundaries until later parity
220 243 # phases remove or validate them. Unknown commands fail so new dependencies do
281 304 print(f"detected_external_commands={len(detected)}")
282 305 print("inventory_tables=ok")
283 306 print("service_contract=ok")
307 +print("parity_matrix=ok")
284 308 print(f"contrast_pairs={len(contrast_pairs)}")
285 309 if contrast_pairs:
286 310 print(f"contrast_min={min(ratio for _mode, _label, ratio in contrast_pairs):.2f}")