repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

docs(quickshell): audit standing objective contract

c3c7c817b7dee48ea1eb373f35d27bfa0144a94b

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (4)

quickshell/nugu/MANIFEST.md

Modified
30 30 | `NotificationBridgeWidget.qml` | QML component | Transitional Mako count and action bridge while native notification parity is blocked. |
31 31 | `NotificationDaemon.qml` | QML component | Gated native notification server candidate for eventual Mako retirement. |
32 32 | `NotificationToast.qml` | QML component | Nugu-styled notification toast renderer used by the gated native daemon. |
33 +| `OBJECTIVE.md` | documentation | Audited standing-goal contract preventing smaller success claims before live parity. |
33 34 | `Osd.qml` | QML component | Nugu OSD surface replacing transient `hyprctl notify` wrappers after bind migration. |
34 35 | `PARITY.md` | documentation | Audited companion parity matrix and old-service retirement gates. |
35 36 | `PERF.md` | documentation | Audited performance budget for polling, action processes, and future live perf evidence. |

quickshell/nugu/OBJECTIVE.md

Added
new file mode 100644
1 +# Nugu Quickshell objective contract
3 +This file prevents the self-contained config from redefining success smaller than
4 +the standing goal. It is not a completion claim.
6 +## Standing objective
8 +Reimplement the current Hypr companion apps in Quickshell with:
10 +- same feature as now;
11 +- same style and integration;
12 +- dark/light mode;
13 +- verified feature parity with the current setup;
14 +- simplification;
15 +- better performance;
16 +- better looks;
17 +- simpler Hypr config;
18 +- old companion apps obsolete only after verified parity and approval.
20 +## User criteria
22 +1. Keep the Quickshell config self contained.
23 +2. Comment the config with decisions as to why code exists.
25 +## Non-shrink rule
27 +Do not redefine the objective smaller. Static audits, smoke tests, screenshots,
28 +or documentation may prove progress, but they cannot complete the goal alone.
29 +Completion still requires live parity, simplified Hypr binds, retirement proof,
30 +rollback proof, performance evidence, and human visual approval.
32 +## Current blocking truths
34 +Until the rollout gates pass, Ironbar, Ironbar workspaces, Mako, and current Hypr
35 +helper binds remain authoritative. Transitional `cliphist` and `makoctl` bridges
36 +must disappear or receive explicit retained-infrastructure approval before old
37 +app retirement.

quickshell/nugu/README.md

Modified
28 28 NUGU_QS_SMOKE_SCREENSHOT_DIR=/tmp/nugu-qs-theme-smoke quickshell/nugu/smoke.sh
31 +`OBJECTIVE.md` records the full standing goal and prevents smaller success claims.
31 32 `MANIFEST.md` inventories every file in this directory so the named config stays
32 33 self-contained and has no undocumented helpers. `COMPONENTS.md` inventories every QML file with why it exists and current rollout
33 34 status. `IPC.md` inventories every `nugu` IPC method Hypr binds can later target.
40 41 `SCRIPTS.md` inventories each verification script and its mutation boundary.
41 42 `PARITY.md` maps current companion apps/tools to their Quickshell replacements
42 43 and retirement gates. `HYPR_MIGRATION.md` maps current Hypr binds/helpers to
43 -future Quickshell IPC targets. `live-check.sh` reports final rollout blockers, including old Hypr companion refs, without mutating live services or links. `gate.sh` runs the current read-only/self-contained verification chain. The audit checks that required named-config files are present, every direct config file is listed in the manifest, every verification script is inventoried and executable, the rollout runbook keeps approval/rollback boundaries visible, the performance budget documents every polling/action boundary, the style contract keeps IBM Plex/Nugu-token usage enforced, every QML component and IPC method
44 +future Quickshell IPC targets. `live-check.sh` reports final rollout blockers, including old Hypr companion refs, without mutating live services or links. `gate.sh` runs the current read-only/self-contained verification chain. The audit checks that required named-config files are present, the objective contract preserves the full standing goal, every direct config file is listed in the manifest, every verification script is inventoried and executable, the rollout runbook keeps approval/rollback boundaries visible, the performance budget documents every polling/action boundary, the style contract keeps IBM Plex/Nugu-token usage enforced, every QML component and IPC method
44 45 are documented with non-thin inventory rows, QML imports stay local/Qt/Quickshell, every component has an
45 46 early decision/why comment, QML has no unresolved TODO/stub comments, local resources
46 47 are audited, the bundled palette matches

quickshell/nugu/audit.sh

Modified
24 24 style_font_refs = 0
25 25 style_hex_refs = 0
26 26 script_rows = {}
27 -required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "MANIFEST.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "STYLE.md", "SCRIPTS.md", "audit.sh", "smoke.sh", "live-check.sh", "gate.sh")
27 +required_files = ("shell.qml", "Theme.qml", "nugu.json", "README.md", "OBJECTIVE.md", "MANIFEST.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "STYLE.md", "SCRIPTS.md", "audit.sh", "smoke.sh", "live-check.sh", "gate.sh")
29 29 for name in required_files:
30 30 if not (config_dir / name).exists():
117 117 readme_path = config_dir / "README.md"
118 118 if readme_path.exists():
119 119 readme_text = readme_path.read_text()
120 - for marker in ("MANIFEST.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "STYLE.md", "SCRIPTS.md", "audit.sh", "smoke.sh", "live-check.sh", "gate.sh", "qs -c nugu", "qs ipc -c nugu"):
120 + for marker in ("OBJECTIVE.md", "MANIFEST.md", "COMPONENTS.md", "IPC.md", "EXTERNALS.md", "TRANSITIONS.md", "SERVICE.md", "PARITY.md", "HYPR_MIGRATION.md", "ROLLOUT.md", "PERF.md", "STYLE.md", "SCRIPTS.md", "audit.sh", "smoke.sh", "live-check.sh", "gate.sh", "qs -c nugu", "qs ipc -c nugu"):
121 121 if marker not in readme_text:
122 122 errors.append(f"README.md missing self-contained entry marker {marker!r}")
126 126 if not qml_files:
127 127 errors.append("no QML files found")
129 +objective_doc = config_dir / "OBJECTIVE.md"
130 +if objective_doc.exists():
131 + objective_text = objective_doc.read_text().lower()
132 + required_objective_markers = (
133 + "same feature as now",
134 + "same style and integration",
135 + "dark/light mode",
136 + "verified feature parity",
137 + "better performance",
138 + "better looks",
139 + "simpler hypr config",
140 + "old companion apps obsolete",
141 + "keep the quickshell config self contained",
142 + "comment the config with decisions as to why code exists",
143 + "do not redefine the objective smaller",
144 + "not a completion claim",
145 + "live parity",
146 + "rollback proof",
147 + "human visual approval",
148 + "transitional `cliphist` and `makoctl` bridges",
150 + for marker in required_objective_markers:
151 + if marker not in objective_text:
152 + errors.append(f"OBJECTIVE.md missing standing-goal marker {marker!r}")
153 +else:
154 + errors.append("missing OBJECTIVE.md")
129 156 manifest_doc = config_dir / "MANIFEST.md"
130 157 manifest_rows = {}
131 158 if manifest_doc.exists():
760 787 print(f"documented_external_commands={len(external_commands)}")
761 788 print(f"detected_external_commands={len(detected)}")
762 789 print("docs_index=ok")
790 +print("objective_contract=ok")
763 791 print(f"manifest_files={len(manifest_rows)}")
764 792 print("manifest=ok")
765 793 print(f"script_files={len(script_files)}")