repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit transition bridge gates

b411f8d18d542bfc8ff09bd630c846472ddfce9d

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`, `PARITY.md`, `audit.sh`, `smoke.sh`, `live-check.sh`.
15 +- required named-config files are present: `shell.qml`, `Theme.qml`, `nugu.json`, `README.md`, `COMPONENTS.md`, `IPC.md`, `EXTERNALS.md`, `TRANSITIONS.md`, `SERVICE.md`, `PARITY.md`, `audit.sh`, `smoke.sh`, `live-check.sh`.
16 16 - `README.md` links the required inventories, service/parity contracts, smoke/audit/live-check gates, named config command, and IPC command form.
17 17 - `live-check.sh` is executable and audited read-only: it must not link, start, stop, enable, disable, restart, or launch `qs -c nugu`.
18 18 - `smoke.sh` is executable and audited for self-contained temp `HOME`/`XDG_CONFIG_HOME`, named config launch, cleanup trap, and no live link/service mutation.
20 20 - every `nugu` IPC method from `shell.qml` is listed in `IPC.md` with purpose and rollout status.
21 21 - component, IPC, and external inventory rows reject duplicates, malformed names, thin text, and placeholder wording.
22 22 - every approved executable boundary is listed in `EXTERNALS.md` with status and reason, and stale unused rows fail.
23 +- every `transitional` external command is listed in `TRANSITIONS.md` with current role and removal gate; stale transition rows fail.
23 24 - 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.
24 25 - replacement scope is documented in `PARITY.md`, including old companion retirement targets, non-thin row statuses/gates, valid QML replacement references, human approval, and the explicit “not complete / old tools remain authoritative” boundary.
25 26 - QML imports are limited to Qt, Quickshell, and local `import "."`.
68 69 live_check_readonly=ok
69 70 smoke_contract=ok
70 71 inventory_tables=ok
72 +transition_bridges=2
73 +transition_contract=ok
71 74 service_contract=ok
72 75 parity_matrix=ok
73 76 parity_rows=12
74 77 rollout_boundary=ok
75 78 contrast_pairs=12
76 79 contrast_min=5.50
77 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh,live-check.sh
80 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh,live-check.sh
78 81 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
79 82 WARN transitional external bridge still present: cliphist
80 83 WARN transitional external bridge still present: makoctl
92 95 live_check_readonly=ok
93 96 smoke_contract=ok
94 97 inventory_tables=ok
98 +transition_bridges=2
99 +transition_contract=ok
95 100 service_contract=ok
96 101 parity_matrix=ok
97 102 parity_rows=12
98 103 rollout_boundary=ok
99 104 contrast_pairs=12
100 105 contrast_min=5.50
101 -required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh,live-check.sh
106 +required_files=shell.qml,Theme.qml,nugu.json,README.md,COMPONENTS.md,IPC.md,EXTERNALS.md,TRANSITIONS.md,SERVICE.md,PARITY.md,audit.sh,smoke.sh,live-check.sh
102 107 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
103 108 WARN transitional external bridge still present: cliphist
104 109 WARN transitional external bridge still present: makoctl

quickshell/nugu/README.md

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

quickshell/nugu/TRANSITIONS.md

Added
new file mode 100644
1 +# Nugu Quickshell transitional bridge inventory
3 +These rows are intentionally temporary. Each command listed here is still used
4 +by the self-contained Quickshell config, but must either disappear or be
5 +explicitly reclassified before old companion retirement.
7 +| Command | Current role | Removal gate |
8 +| --- | --- | --- |
9 +| `cliphist` | Clipboard storage backend for `ClipboardWidget.qml` and `ClipboardPicker.qml` while the Quickshell picker frontend replaces launcher-based selection. | Native/replacement storage is implemented, or the bridge is explicitly accepted as retained infrastructure before `hyprlauncher --dmenu` retirement. |
10 +| `makoctl` | Notification count, restore, and dismiss bridge for `NotificationBridgeWidget.qml` while Mako remains the live notification daemon. | Native notification daemon proves DBus ownership, urgency, timeout, action, dismiss, restore, history, and rollback parity before Mako retirement. |

quickshell/nugu/audit.sh

Modified
21 21 qml_files = sorted(config_dir.glob("*.qml"))
22 22 code_by_file = {}
23 23 decision_comment_files = set()
24 -required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh", "live-check.sh")
24 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh", "live-check.sh")
26 26 for name in required_files:
27 27 if not (config_dir / name).exists():
75 75 readme_path = config_dir / "README.md"
76 76 if readme_path.exists():
77 77 readme_text = readme_path.read_text()
78 - for marker in ("COMPONENTS.md", "IPC.md", "EXTERNALS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh", "live-check.sh", "qs -c nugu", "qs ipc -c nugu"):
78 + for marker in ("COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "audit.sh", "smoke.sh", "live-check.sh", "qs -c nugu", "qs ipc -c nugu"):
79 79 if marker not in readme_text:
80 80 errors.append(f"README.md missing self-contained entry marker {marker!r}")
81 81 else:
339 339 # not sneak into the self-contained config.
340 340 all_code = "\n".join(code_by_file.values())
341 341 externals_doc = config_dir / "EXTERNALS.md"
342 +transitions_doc = config_dir / "TRANSITIONS.md"
342 343 external_commands = {}
343 344 external_status = {}
345 +transition_rows = {}
344 346 if externals_doc.exists():
345 347 external_rows = inventory_rows(externals_doc, "EXTERNALS.md", r"[A-Za-z0-9_.+-]+")
346 348 for command, cells in external_rows.items():
356 358 external_commands = {}
357 359 external_status = {}
361 +if transitions_doc.exists():
362 + transition_rows = inventory_rows(transitions_doc, "TRANSITIONS.md", r"[A-Za-z0-9_.+-]+")
363 +else:
364 + transition_rows = {}
366 +expected_transitions = {command for command, status in external_status.items() if status == "transitional"}
367 +documented_transitions = set(transition_rows)
368 +for command in sorted(expected_transitions - documented_transitions):
369 + errors.append(f"TRANSITIONS.md missing transitional bridge {command!r}")
370 +for command in sorted(documented_transitions - expected_transitions):
371 + errors.append(f"TRANSITIONS.md documents non-transitional command {command!r}")
359 373 detected = []
360 374 for command, reason in sorted(external_commands.items()):
361 375 if re.search(rf"(?<![A-Za-z0-9_-]){re.escape(command)}(?![A-Za-z0-9_-])", all_code):
403 417 print("live_check_readonly=ok")
404 418 print("smoke_contract=ok")
405 419 print("inventory_tables=ok")
420 +print(f"transition_bridges={len(transition_rows)}")
421 +print("transition_contract=ok")
406 422 print("service_contract=ok")
407 423 print("parity_matrix=ok")
408 424 print(f"parity_rows={len(parity_rows)}")