From 1ee17f67996a1efa43f3dbc57ae491580cd7e5d7 Mon Sep 17 00:00:00 2001 From: Bernardo Magri Date: Thu, 9 Jul 2026 18:55:29 +0100 Subject: [PATCH] =?UTF-8?q?docs(agent):=20promote=20V0/V1=20PROPOSED=20ite?= =?UTF-8?q?ms=20to=20NEXT=20#47=E2=80=9350?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bernardo-directed triage: bump the no-VM (V0/V1) PROPOSED items into NEXT so parallel worktree agents can take them without contending for the VM. Grouped into #47 docs+string drift pass, #48 i2c option-docs, #49 pure-contract checks.* batch, #50 small code one-liners. Removed the promoted pitches from PROPOSED (breadcrumbs left); V2-wanting items stay in PROPOSED. Co-Authored-By: Claude Opus 4.8 --- agent/BACKLOG.md | 168 ++++++++++++++++++----------------------------- agent/JOURNAL.md | 19 ++++++ 2 files changed, 82 insertions(+), 105 deletions(-) diff --git a/agent/BACKLOG.md b/agent/BACKLOG.md index d2aa79f..68f3dbb 100644 --- a/agent/BACKLOG.md +++ b/agent/BACKLOG.md @@ -114,6 +114,55 @@ Next slice: on hardware, run `hyprctl clients` while each is open, read the real `class`, then append rules. Also revisit whether blueman/s-c-p actually float once seen (regex tolerance for the `.…-wrapped` form). +### 47. Docs + string factual-drift pass (promoted 2026-07-09) +Pure docs (V0) plus two `.nix` string fixes (V1: HM build). One pass or split: +- **README/docs drift:** theme count **21 → 24** (`README.md`, + `docs/TESTING.md`, `templates/downstream/README.md`); waybar whole-swap + list → summer-day/summer-night/executive-slate/boreal/neon-glass (drop the + catppuccin/lumon/nord/retro-82 stubs); idle table "suspend **30**" → + **15 min battery-only** (`idle.nix`); Tailscale row `sudo tailscale up` → + operator/no-sudo; `hosts/live.nix` header "No installer yet" → current; + CONVENTIONS parity list add **boreal**. +- **Secondary docs:** README layout tree add doctor/control-center/ + battery-notify; link `docs/MIGRATION.md` from README nav + fix its + placeholder flake-init URL; OVERRIDES.md screenshot pipe swappy → **satty**. +- **Document always-on home pieces:** easyeffects/udiskie/cliphist ship with + no toggle by design — a short README note + override pointer. +- **String fixes (V1):** keybind cheatsheet `desc = "Network (nmtui)"` → + networkmanager_dmenu (`keybinds.nix`); complete the `nomarchy-menu` usage + string (add doctor/controlcenter/rollback/firmware/…, `rofi.nix`). +Verify any documented command by running it. + +### 48. Document `nomarchy.hardware.i2c.*` — close checks.option-docs (promoted 2026-07-09) +`nomarchy.hardware.i2c.enable` and `.ddcci` (`modules/nixos/hardware.nix`) +have no README table rows → `checks.option-docs` is red. Add rows (+ note the +effective default: option default `false` but distro `mkDefault true` for +ddcci in `modules/nixos/default.nix`). Optional template opt-in comment. +V0 — `checks.option-docs` verifies (pure runCommand, no VM). + +### 49. Pure-contract `checks.*` batch — no VM (promoted 2026-07-09) +Add pure runCommand checks (all V0): +- Expand CI `py_compile` to **all** tracked `*.py` (compose-lock, tools/*, + tools/vm/*), not just theme-sync (`.gitea/workflows/check.yml`; sync + `docs/TESTING.md §1`). +- Hardware-db module names ∈ pinned `nixos-hardware.nixosModules` (a lock bump + can rename modules and break profiled installs only on matching DMI). +- Installer pure contracts: `compose-lock.py`, disko `swapSize` + ("0"/"0G"/"NG") + `withLuks` arg contract. +- **windowrule dead-syntax guard:** build the generated `hyprland.conf` and + fail on the rule-first `windowrule = (float|center|size|tile|…) ,` pattern + or the `windowrulev2` keyword (would have caught `ed7fd93`). + +### 50. Small code one-liners batch — V0/V1 (promoted 2026-07-09) +- Bluetooth menu row self-gate on `command -v blueman-manager` (`rofi.nix`) — + no-op when `nomarchy.system.bluetooth.enable = false`, like Printers. +- Control Center rollback list `/tmp/nomarchy-gens` → `mktemp` (predictable + world-writable path → multi-user race). +- `usbutils` on `nomarchy-install` PATH so the fingerprint `lsusb` probe works + (sysfs is the current fallback). +- Export overlay tools (doctor/control-center/battery-notify) as flake + `packages` (`nix build .#nomarchy-doctor`) — three lines in flake.nix. + ## LATER - **Wallpapers artifact split** (ROADMAP § Faster switches — decided, @@ -139,12 +188,11 @@ implement. Bernardo moves accepted items into a tier.* ### v1.0 track — see `docs/VISION.md` -Product themes and the release bar live in **VISION**. **NEXT:** -#43 System › Firmware · #44 doctor hardware. #42 boreal default -shipped + V2-verified (session reads as Boreal); `preview.png` captured -(headless fallback — hardware recapture nicety noted under theme polish). -Remaining candidate promotions: fingerprint menu · first-boot tips · -human rebuild errors · neon-glass quarantine. +Product themes and the release bar live in **VISION**. Shipped 2026-07-09: +#42 boreal default (V2-verified) · #43 Firmware menu (V1, V2 pending) · +#44 doctor hardware (V1 + hw smoke, V2 pending). Remaining candidate +promotions: fingerprint menu · first-boot tips · human rebuild errors · +neon-glass quarantine. ### Pre-existing @@ -211,13 +259,6 @@ human rebuild errors · neon-glass quarantine. identical until a later rebuild. Fix: run switch for appearance keys, or refuse / warn clearly. Cost: small UX fix in one script. -- **Bluetooth menu row not self-gated** - System submenu always offers Bluetooth and `exec blueman-manager`. - If `nomarchy.system.bluetooth.enable = false`, blueman is not - installed → silent/broken launch. Printers / colorpicker / audio - gate correctly. Fix: gate on `command -v blueman-manager` (or the - settings flag). Cost: tiny; V0 + manual. - - **summer-day workspace scroll dispatches differently from every other bar** `themes/summer-day/waybar.jsonc` uses `workspace e+1` / `e-1` (next **empty** workspace); summer-night, executive-slate, boreal use @@ -235,37 +276,8 @@ human rebuild errors · neon-glass quarantine. ### Docs / option-surface drift (codebase exam 2026-07-09) -- **`option-docs` would fail: undocumented `nomarchy.hardware.i2c.*`** - Live options `nomarchy.hardware.i2c.enable` and `.ddcci` in - `modules/nixos/hardware.nix`; distro default turns ddcci **on** - (`modules/nixos/default.nix` `mkDefault true`). No README table - rows, no template comments. Simulated `checks.option-docs` finds - exactly these two. Also: option default is false while module - default is true — document the effective default. Cost: docs + - optional template opt-in comments; would green option-docs. - -- **README / docs factual drift pack** (single docs pass or split): - (1) theme count still says **21** — repo has **24** presets - (`README.md`, `docs/TESTING.md`, `templates/downstream/README.md`); - (2) waybar whole-swap list still names catppuccin/lumon/nord/ - retro-82 — stubs purged; live CSS whole-swaps are summer-day, - summer-night, executive-slate, boreal, neon-glass; (3) idle table - still says "suspend **30**" — code is **15 min battery-only** - (`idle.nix`; ROADMAP already correct); (4) Tailscale row says - `sudo tailscale up` but module grants `--operator=` / template - says no sudo; (5) `hosts/live.nix` header still says "No installer - yet"; (6) CONVENTIONS parity list omits **boreal** (has full - waybar.jsonc). Cost: pure docs; high trust payoff. - -- **Keybind cheatsheet: Network still labeled nmtui** - `keybinds.nix` `desc = "Network (nmtui)"` but the module runs - `networkmanager_dmenu`. Cheatsheet inherits the wrong label. Cost: - one string. - -- **`nomarchy-menu` usage string incomplete** - Usage omits implemented modules (`doctor`, `controlcenter`, - `rollback`, …). Misleading for direct invocation / scripting. - Cost: one string in `rofi.nix`. +_(i2c option-docs → #48; README/docs drift pack, keybind nmtui label, +nomarchy-menu usage string, secondary docs, always-on pieces → #47.)_ - **Template / seed state drift (residual after SoT work)** (1) `templates/downstream/theme-state.json` lacks `border` and @@ -283,13 +295,6 @@ human rebuild errors · neon-glass quarantine. closure); (3) residual theme-state / i2c comment polish on template (see residual seed drift item). -- **Secondary docs polish** - README layout tree omits many real modules and pkgs - (doctor/control-center/battery-notify); `docs/MIGRATION.md` - unlinked from README nav and has a placeholder flake-init URL; - OVERRIDES.md example still pipes screenshots to **swappy** while - shipped annotator is **satty**. Cost: docs-only. - ### Theme polish / completeness (codebase exam 2026-07-09) - **Missing theme picker previews + hand btop for identity themes** @@ -498,31 +503,8 @@ flagged separately from fidelity bugs.* ### Tooling / CI / installer hardening (codebase exam 2026-07-09) -- **CI `py_compile` only covers theme-sync** - `.gitea/workflows/check.yml` compiles only - `pkgs/nomarchy-theme-sync/nomarchy-theme-sync.py`. Misses - `compose-lock.py`, `tools/*.py`, `tools/vm/*.py` — syntax errors - can ship. Expand to all tracked `*.py` (or at least installer + - tools). Cost: one workflow line; TESTING.md §1 should match. - -- **No guard against dead Hyprland rule syntax in the generated conf** - The `windowrule` 0.53-migration bug (fixed 2026-07-09, `ed7fd93`) shipped - a red config-error banner on the *default* desktop for weeks — invisible - to `nix flake check` (the conf builds fine; Hyprland only rejects it at - session start). A cheap `checks.*` could build the generated - `hyprland.conf` and grep for the dead rule-first pattern - (`windowrule\s*=\s*(float|center|size|tile|...)\s*,`) and the - `windowrulev2` keyword, failing on a match. Better still (heavier): - `hyprland --verify`-style parse if one exists. Cost: small runCommand - check; catches the whole class. Pairs with the theme-shot harness that - actually caught this. - -- **No automated check for installer pure contracts** - `compose-lock.py`, disko `swapSize`/`withLuks` arg contract, and - hardware-db module names vs `nixos-hardware.nixosModules` have no - `checks.*`. Lock bumps of nixos-hardware can rename modules and - break profiled installs only on matching hardware. Cost: medium - one-time check scaffolding; high long-term install safety. +_(py_compile expand, installer pure contracts, hardware-db ∈ nixos-hardware, +windowrule dead-syntax guard → #49.)_ - **Installer soft gaps** (1) fingerprint path prefers `lsusb` but package PATH has @@ -532,9 +514,7 @@ flagged separately from fidelity bugs.* doctor / control-center / battery-notify (runtime via overlay is fine — discoverability only). Cost: small each. -- **Control Center `/tmp/nomarchy-gens` for rollback list** - Predictable world-writable path for generation listing — multi-user - race / trash. Prefer `mktemp`. Cost: tiny. +_(Control Center `/tmp/nomarchy-gens` → mktemp → #50.)_ ### Distro improvement ideas (codebase exam 2026-07-09) @@ -551,20 +531,14 @@ flagged separately from fidelity bugs.* fixed) grouped with Theme once the root stays six entries. Cost: menu structure only; product call. -- **Export all overlay tools as flake packages** - `nix build .#nomarchy-doctor` etc. for maintainers and CI - convenience without going through modules. Cost: three lines in - flake.nix. +_(Export overlay tools as flake packages → #50.)_ - **Unattended-install test matrix** `test-install.sh` always LUKS+swap; add (or document) no-swap and no-LUKS paths once those contracts are fixed, so swap/LUKS-class bugs cannot recur. Cost: script flags + time on KVM host. -- **Document always-on home pieces** - easyeffects, udiskie, cliphist always on with no toggle (by - design) — optional README note so users know what ships and how to - override. Cost: docs only. +_(Document always-on home pieces (easyeffects/udiskie/cliphist) → #47.)_ ### Hardware product (investigation 2026-07-09) @@ -599,24 +573,8 @@ of that doc — design notes live there (§4–§10).* powerManagement / open-module and docs/HARDWARE.md §6 — not a full second stack. Cost: install script strings; V0 + doc. -- **CI: hardware-db module names ∈ nixos-hardware** - Every `HARDWARE_DB` third field must exist in the pinned - `nixos-hardware.nixosModules` or installs break only on matching - DMI. Add a pure `checks.*` (or option-docs-style runCommand). Pairs - with existing “installer pure contracts” proposal. Cost: small - check; V0. - -- **Installer: `usbutils` on PATH for fingerprint probe** - Fingerprint path prefers `lsusb` but package wrap has `pciutils` - only; sysfs VID walk is the fallback. Add `usbutils` to - `nomarchy-install` PATH for reliable detection. Cost: one package - in wrap; V0. - -- **Document + README table: `nomarchy.hardware.i2c.*`** - `i2c.ddcci` is **mkDefault true** (external monitor brightness) but - missing from README option tables → `checks.option-docs` red (also - under docs-drift pack). Document in README + HARDWARE.md already - mentions ddcci; close option-docs. Cost: docs; V0 with option-docs. +_(hardware-db ∈ nixos-hardware → #49; usbutils on install PATH → #50; +i2c README table → #48.)_ - **Post-install hardware hints (MOTD / first session)** When relevant services exist, surface one line each: firmware diff --git a/agent/JOURNAL.md b/agent/JOURNAL.md index bfb753e..af18928 100644 --- a/agent/JOURNAL.md +++ b/agent/JOURNAL.md @@ -17,6 +17,25 @@ Template: --- +## 2026-07-09 — Promote V0/V1 PROPOSED items → NEXT #47–50 (Bernardo-directed) +- **Task:** Bernardo asked to bump the non-V2 PROPOSED items into NEXT (to + feed parallel worktree agents that can't touch the VM). Triage is his call; + I did the move on his instruction. +- **Did:** Grouped the genuinely V0/V1 (no session/VM) pitches into four NEXT + items — **#47** docs+string factual-drift pass, **#48** i2c option-docs, + **#49** pure-contract checks.* batch (py_compile expand, hardware-db ∈ + nixos-hardware, installer pure contracts, windowrule dead-syntax guard), + **#50** small code one-liners (Bluetooth self-gate, CC mktemp, usbutils on + PATH, export overlay tools as flake packages). Removed the promoted pitches + from PROPOSED, leaving `_→ #NN_` breadcrumbs. Deliberately left V2-wanting + items in PROPOSED (Waybar doctor icon, CC appearance toggles, theme-color + retunes, neon-glass, summer-day scroll, installer review warnings). +- **Verified:** V0 (docs/backlog only) — grep confirms #47–50 present, no + leftover promoted-pitch text. +- **Pending:** none. #47–50 are now actionable and agent-friendly (all no-VM). +- **Next suggestion:** spawn worktree agents on #47–50 in parallel with the + #46 VM; land their branches after review. + ## 2026-07-09 — #44 Doctor hardware section (delegated to worktree agent) - **Task:** NEXT #44 — read-only hardware checks in nomarchy-doctor (HARDWARE.md §10). Delegated to a worktree-isolated opus agent so it ran