docs: maintenance-console spec to DOING + build decomposition

The spec encodes the converged 2026-07-06/07 design as 13 decisions and 13 phases (CLI-first maint package, four-layer test strategy) and carries its full review trail inside, live-verified on ratio. Late calls landed during authoring: the bar glyph replaces custom/sysmon, doubles as the laptop battery display, and keeps the btop scratchpad on right-click.

todo.org now carries the build: 13 phase tasks under a SPEC_ID-stamped parent, the manual-testing collector, the flip-to-IMPLEMENTED closer, and the vNext deferral.

1 files changed, 53 insertions, 2 deletions

diff --git a/todo.org b/todo.org
index 7022682..e7509d4 100644
--- a/todo.org
+++ b/todo.org
@@ -21,8 +21,59 @@ The vocabulary is open — topic tags are coined as needed — so these are conv
 - *Effort / autonomy*: =:quick:= a spare-moment fix (minutes, not a sitting); =:solo:= Claude can carry it end to end — there's a build path, a test path, and no upfront decision needed (a leftover manual spot-check doesn't disqualify it).
 - *Topic / area* (open): the subsystem a task touches — e.g. =:hyprland:= =:waybar:= =:mpd:= =:music:= =:network:= =:tooling:= =:llm:= =:eask:= =:pocketbook:= =:cmail:=. Coin a new one when it aids filtering.
 * Archsetup Open Work
-** TODO [#B] Maintenance console — spec from design doc + prototype :feature:
-Run spec-create against [[file:docs/design/maintenance-console-design-ideas.org][maintenance-console-design-ideas.org]] (all decisions resolved 2026-07-06/07) and the interactive prototype ([[file:docs/prototypes/2026-07-07-maint-console-E5-selector-subpanel.html][E5]], the converged design). The design is complete: selector + dense subpanels, doctor (Clean up / Review & fix) streaming to the results wall, determinate remedies incl. guard-armed updates, evidence digests + curation lifecycles (known-noise, expected-listeners, expected-containers, kept-orphans), rotary band selectors on tall subpanels, refresh cadence, CLI-first architecture with the four-layer test strategy (unit fakes → read-only live → VM remedies via the archsetup test harness → AT-SPI GUI smoke on fixtures). Prototype's GOOD/BAD snapshots become test fixtures. Build lands as the =maint= package in dotfiles (fourth panel sibling); thresholds TOML owned by archsetup. Related: the proposed system-health-check workflow move from home (see doc) sequences at implementation time.
+** DOING [#B] Maintenance console build :feature:
+:PROPERTIES:
+:SPEC_ID: 9d9df833-c592-4aec-a7df-50d588e943ce
+:END:
+Build the maintenance console per [[file:docs/specs/2026-07-07-maintenance-console-spec.org][maintenance-console-spec.org]] (DOING; review incorporated 2026-07-07 — two rounds, all 13 decisions DONE, all 10 findings DONE, verdict Ready; Craig approved config paths + sysmon right-click re-homing). Design source of truth: [[file:docs/design/maintenance-console-design-ideas.org][maintenance-console-design-ideas.org]]; pixel reference: [[file:docs/prototypes/2026-07-07-maint-console-E5-selector-subpanel.html][E5 prototype]]. CLI-first =maint= package in dotfiles (archsetup-owns-dotfiles applies: edit, test, commit, push, note dotfiles inbox per phase); thresholds TOML + VM harness in archsetup. Each phase gates on green tests before its commit.
+
+*** TODO Phase 1 — package skeleton, thresholds, contract :solo:
+=maint/= scaffold + stow wiring, thresholds.py (TOML + user-layer merge + disable flags + env overrides), schema.py severity model, capability probe (battery ⇔ type==Battery), =maint status --json= with three pilot collectors, fake-binary harness in tests/maint/. Seed maintenance-thresholds.toml in archsetup from the workflow's values. Verify: unit suite green; =make test= picks up tests/maint/ via the glob.
+
+*** TODO Phase 2 — collectors: storage & snapshots :solo:
+btrfs (unallocated, scrub age, device error counters vs SMART), ZFS (health/capacity/frag/autotrim/scrub), SMART + last self-test, fstrim.timer, disk top-consumers digest (slow-local tier), snapshot counts split timeline·single·pre-post. Both-host fixtures. Verify: unit green + read-only =maint status --json= on ratio.
+
+*** TODO Phase 3 — collectors: packages, security, systemd :solo:
+Cache size, orphans (name+size), pacnew classification, keyring freshness, reboot-required, -Qkk (slow-local, parses output not exit code); network-tier cache readers (checkupdates, arch-audit CVEs, AUR, fwupd, topgrade freshness) with age; is-system-running + cause, failed-unit roster, maintenance-timers meta-metric, taint decode. Prereq: add arch-audit to archsetup deps + install. Verify: unit green + live read-only on ratio.
+
+*** TODO Phase 4 — collectors: logs, memory, power :solo:
+Journal digest (identifier groups, noise layers), coredumps by binary, kernel/hw events; memory + top-5, OOM, swap/zram, temps, throttle, EPP read, battery health + charge threshold read, unclean-shutdown rate. Verify: unit green + live read-only on ratio.
+
+*** TODO Phase 5 — collectors: network posture, services :solo:
+DNS/NM, firewall + public-bind exposure, listeners digest + expected merge, tailscale, fail2ban, NTP offset; rsyncshot freshness, docker df + containers + expected layer, libvirt, cron drift. Curation read side complete. Verify: unit green + live read-only on ratio; velox presence sweep for the tool set (tailscale ssh).
+
+*** TODO Phase 6 — remedies, priv, guard, doctor CLI :solo:
+remedies.py (allowlisted argv + re_probe_ids + running-%), priv.py verb table (MAINT_SUDO), guard.py live-update matcher (pairwise-tested), curation writes, =maint fix --dry-run=, =maint doctor clean|review= streaming event feed, topgrade wrapper (--disable git), KILL four guards. Argv tests only — no execution. Splits 6a/6b if long. Verify: unit green; one live Auto-tier doctor run on ratio at the end.
+
+*** TODO Phase 7 — GUI shell :solo:
+GTK4 window, faceplate, selector row (lamps + fixable/watch), subpanel scaffolding, hydration + live/fast refresh tiers, MAINT_PANEL_FIXTURE loading, panel CSS (dupre panel.css). Read-only render. Verify: AT-SPI + off-workspace screenshot vs E5.
+
+*** TODO Phase 8 — GUI: storage, snapshots, packages, updates strip :solo:
+Evidence digests, armed keys (orphan REMOVE/KEEP, pacnew MERGE, DELETE STALE, scrub running-%), Packages rotary band, updates strip + arming live-update guard + REBOOT key. Verify: AT-SPI on GOOD/BAD fixtures + screenshots.
+
+*** TODO Phase 9 — GUI: systemd, logs, mem·pwr, network, services :solo:
+Failed-unit roster keys, journal MARK KNOWN lifecycle + OPEN JOURNAL, Logs/Services rotary bands, MEM·PWR strip + CPU-mode control + velox SET 80% + guarded KILL, listeners curation + STOP/KILL, firewall ENABLE, container START, RECLAIM SPACE macro. Splits 9a/9b if long. Verify: AT-SPI + screenshots.
+
+*** TODO Phase 10 — results wall + doctor keys :solo:
+Wall widget (lamp stream, timestamps, inline results, running-%, HIDE/COPY, 3.5-entry cap), CLEAN UP / REVIEW & FIX via doctor.py, curation events logged, post-action re-probes. Verify: AT-SPI + live Auto-tier doctor on ratio streaming to the wall.
+
+*** TODO Phase 11 — waybar glyph + timers :solo:
+indicator.py + waybar-maint, custom/maint replaces custom/sysmon (canonical + waybar-active-config + SIGUSR2), right-click re-homes pypr toggle monitor, battery text on type==Battery hosts (low-charge threshold feeds diagnostic), maint-scan.timer + maint-net-scan.timer, glyph CSS both themes. Retire waybar-sysmon + sysmon-cycle + their suites + #custom-sysmon CSS (3 files) same commit. Verify: glyph live on ratio through a timer cycle; battery text + one-time stow on velox over tailscale.
+
+*** TODO Phase 12 — VM remedy scenarios + AT-SPI target :solo:
+Scenario orchestration over vm-utils.sh snapshot primitives (grouped batches per Decision 11), scenario scripts (break → =maint fix= → assert), nspawn variant for pacman-level, FS_PROFILE=zfs scenario if the base image builds, test-panel-maint Makefile target. May split VM (archsetup) from AT-SPI (dotfiles). Verify: full scenario run green from pristine snapshot.
+
+*** TODO Phase 13 — install wiring, workflow move, docs :solo:
+archsetup installs the TOML (idempotent, never overwrites user layer); deps; maint README (user + developer); move system-health-check.org + homelab-inventory into archsetup, rewire to the TOML, handoff note to home's inbox for the home-side removal. Verify: fresh-shell =maint status= works from installed paths; docs build/read.
+
+*** TODO Manual testing and validation
+Collects everything not agent-verifiable; populate per verification.md as phases land. Known so far: panel look-and-feel vs the E5 prototype (Craig's eyeball); arm-press wording reads right at the moment of use; results-wall readability during a real doctor run; a real UPDATE through the armed guard (and the TTY path once); REBOOT offer after an update; velox in-person glyph check (battery %, charging glyph, low-charge red); SET 80% charge limit sticks across a charge cycle; KILL on a real memory hog.
+
+*** TODO Flip the spec to IMPLEMENTED
+When all phases land: spec keyword → IMPLEMENTED + dated history line naming the closing commits + Status mirror. The lifecycle loop closes here — do not skip.
+
+** TODO [#D] Maintenance console vNext :feature:
+Deferred from the [[file:docs/specs/2026-07-07-maintenance-console-spec.org][spec]] (v1 ships determinate remedies only): AI/workflow assistance on read-only metrics (the vLater tier — failed-unit diagnosis, journal-error fix suggestions, OOM investigation); SIGKILL escalation for TERM-survivors on the KILL lever; live streaming meters on evidence rows where a count could be a level.
 
 ** TODO [#C] Consistent keybinding family for the panel console :feature:hyprland:
 Consider putting every panel (net, bluetooth, audio, timer, and the coming maintenance console) on one consistent chord family — a shared modifier set (Super+Shift, Control+Alt, or similar) plus a mnemonic letter per panel (N/B/A/T/M). Today the panels open via waybar clicks only; a uniform chord family makes them keyboard-reachable and predictable. Watch for collisions with existing binds: Super+Shift+A is already PTT toggle, and the hold-to-talk grave bind is load-bearing. Decide the family, audit current hyprland binds for conflicts, wire via the dotfiles hyprland config, and document in the keybind reference. Both machines (velox can't QMK-remap, so chords must work on a plain laptop keyboard).