Baseline metrics are recorded before phase 1 starts: central files touched by one audio change, context files required, registration points, iterations to green.
Recorded in baseline.md.
Every step keeps just lint, the full just test, and the full just ui-test green.
just ui-test admits at most two software-rendered sandboxes concurrently without skipping suites or changing their deadlines.
Prerequisites (done)
Fold agent law into .system/, remove the folded sources, extend justfile QML and test discovery to recurse into features/ without weakening any gate.
Exit when zero-warning lint and the full suite pass with recursive discovery.
Load check
One shared offscreen Quickshell load harness replaces the setup copied across existing offscreen tests. just load-test <feature> loads a feature's panel with fixture dependencies and fails on any warning. No second test system.
Exit when just load-test audio and just load-test osd pass and the migrated offscreen tests pass through the shared harness.
Audio pilot
Move audio sources, tests, and fixtures into features/audio/. Introduce the typed QML registry; the audio entry names its service, panel, bar control, sizing and retained state, load target, and ui-test suite. Registry-driven instantiation replaces the audio case and inline component in PopoutHost and the audio entries in SurfaceManager, Bar, and popoutCatalog; generic computation stays in the host. IPC stays explicit in shell.qml; state APIs stay JSON. Audio flows move out of the tasks suite into an audio suite.
Exit when just load-test audio, just ui-test audio, and every gate pass, and audio fanout is re-measured against the baseline.
Independent OSD onboarding
Freeze the registry contract and audio as reference. A second agent onboards OSD using public contracts only: .system/, registry, audio reference. Record central-file edits, context files, contract gaps, and iterations to green.
Exit when the owner reviews the evidence against the baseline and decides continue, adjust, or stop.
Owner decision 2026-11-13: continue, adjusting first; evidence in osd-onboarding.md.
4b. Contract adjustments
Hosts select registry entries by kind. Feature suites live in features/<name>/fixtures/suite.mjs and are discovered by name. Agents work in just worktree checkouts, never the live desktop config. Live verification of production shell.qml is the owner's (decision 2026-11-13); the shell suite closes the test-tool gap: production shell.qml loads with zero warnings against private stand-ins (PipeWire, UPower, power profiles, BlueZ, polkit authority, fixture logind session) and opens every popup and the OSD. Then an independent agent onboards an ordinary popup and the fanout is re-measured against the pilot's prediction.
Exit when those hold and every gate is green.
Re-measured with the tray: tray-onboarding.md; the pilot's prediction missed by about four times, and the phase exit is not met.
Broader migration
Migrate remaining features onto the registry one slice at a time, each with its load target and named suite. Decompose SurfaceManager and PopoutHost further only where migration proves the need. Lock and privilege retain external specialized controllers, not registry kinds.
Exit when just load-test <feature> and just ui-test <suite> pass for every registry entry and the full gate is green.
Done 2026-11-14: all fifteen features are registry entries with a load target and suite (just ui-test 21/21); hosts and diagnostics.js hold no per-feature cases, popoutCatalog.js is gone, and bar chip order comes from the registry. New generic contracts: nullable Registry host inputs, opening/dismissed, panel sessionState/closeRequested, bar fields and barControl, focusOverlay, the toggle kind, and fixtures/production.mjs. Re-measured with a new feature: uptime-onboarding.md, two production files outside the feature and no harness files.
Typed internal service APIs
Separate follow-up: replace internal stateJson() consumption with typed readonly properties or QML models where practical; rewrite affected fixture doubles; keep JSON at IPC and diagnostics boundaries. The "where practical" criterion is defined in that follow-up.
Exit when affected panels and fixtures pass unchanged interaction and visual evidence.
"Where practical", decided 2026-11-14: panels, surfaces, hosts and in-process callers bind readonly service properties (typed scalars, var only for row lists and records) and never call another object's stateJson()/stateObject() or parse a service's return; stateJson()/stateObject() are built from those properties for IPC and diagnostics; parsing subprocess output, files and the niri event stream stays JSON.
Done 2026-11-14: osd, audio, media, brightness, power, tray, launcher, connectivity and privilege converted; every converted suite's screenshots matched their baselines pixel for pixel outside the bar clock and known motion frames; typed-state.test.mjs enforces the contract and fails on the pre-step-6 tree.
---
id: NL-PLAN-C4V7TQ2X
type: plan
title: Nuguland agent revamp rollout
spec: NL-SPEC-A7K4QX2M
status: approved
---
# Nuguland agent revamp rollout
## Historical rollout
Completed rollout record; intermediate names and gaps below are historical.
Current contract: [onboarding](../../specs/NL-SPEC-A7K4QX2M-nuguland-agent-onboarding/index.md).
Step 5 supersedes step 4b's failed exit measurement; step 6 completed typed APIs.
```mermaid
flowchart LR
p1["1 prerequisites · done"] --> p2["2 load check"]
p2 --> p3["3 audio pilot · registry live"]
p3 --> p4{"4 independent OSD onboarding"}
p4 -->|owner: continue| p5["5 broader migration · done"]
p4 -->|owner: stop| stop["revert convention"]
p5 --> p6["6 typed state APIs"]
```
Baseline metrics are recorded before phase 1 starts: central files touched by one audio change, context files required, registration points, iterations to green.
Recorded in [baseline.md](baseline.md).
Every step keeps `just lint`, the full `just test`, and the full `just ui-test` green.
`just ui-test` admits at most two software-rendered sandboxes concurrently without skipping suites or changing their deadlines.
1. **Prerequisites** (done)
Fold agent law into `.system/`, remove the folded sources, extend justfile QML and test discovery to recurse into `features/` without weakening any gate.
Exit when zero-warning lint and the full suite pass with recursive discovery.
2. **Load check**
One shared offscreen Quickshell load harness replaces the setup copied across existing offscreen tests. `just load-test <feature>` loads a feature's panel with fixture dependencies and fails on any warning. No second test system.
Exit when `just load-test audio` and `just load-test osd` pass and the migrated offscreen tests pass through the shared harness.
3. **Audio pilot**
Move audio sources, tests, and fixtures into `features/audio/`. Introduce the typed QML registry; the audio entry names its service, panel, bar control, sizing and retained state, load target, and `ui-test` suite. Registry-driven instantiation replaces the audio case and inline component in `PopoutHost` and the audio entries in `SurfaceManager`, `Bar`, and `popoutCatalog`; generic computation stays in the host. IPC stays explicit in `shell.qml`; state APIs stay JSON. Audio flows move out of the `tasks` suite into an `audio` suite.
Exit when `just load-test audio`, `just ui-test audio`, and every gate pass, and audio fanout is re-measured against the baseline.
4. **Independent OSD onboarding**
Freeze the registry contract and audio as reference. A second agent onboards OSD using public contracts only: `.system/`, registry, audio reference. Record central-file edits, context files, contract gaps, and iterations to green.
Exit when the owner reviews the evidence against the baseline and decides continue, adjust, or stop.
Owner decision 2026-11-13: continue, adjusting first; evidence in [osd-onboarding.md](osd-onboarding.md).
4b. **Contract adjustments**
Hosts select registry entries by `kind`. Feature suites live in `features/<name>/fixtures/suite.mjs` and are discovered by name. Agents work in `just worktree` checkouts, never the live desktop config. Live verification of production `shell.qml` is the owner's (decision 2026-11-13); the `shell` suite closes the test-tool gap: production `shell.qml` loads with zero warnings against private stand-ins (PipeWire, UPower, power profiles, BlueZ, polkit authority, fixture logind session) and opens every popup and the OSD. Then an independent agent onboards an ordinary popup and the fanout is re-measured against the pilot's prediction.
Exit when those hold and every gate is green.
Re-measured with the tray: [tray-onboarding.md](tray-onboarding.md); the pilot's prediction missed by about four times, and the phase exit is not met.
5. **Broader migration**
Migrate remaining features onto the registry one slice at a time, each with its load target and named suite. Decompose `SurfaceManager` and `PopoutHost` further only where migration proves the need. Lock and privilege retain external specialized controllers, not registry kinds.
Exit when `just load-test <feature>` and `just ui-test <suite>` pass for every registry entry and the full gate is green.
Done 2026-11-14: all fifteen features are registry entries with a load target and suite (`just ui-test` 21/21); hosts and `diagnostics.js` hold no per-feature cases, `popoutCatalog.js` is gone, and bar chip order comes from the registry. New generic contracts: nullable `Registry` host inputs, `opening`/`dismissed`, panel `sessionState`/`closeRequested`, bar fields and `barControl`, `focusOverlay`, the `toggle` kind, and `fixtures/production.mjs`. Re-measured with a new feature: [uptime-onboarding.md](uptime-onboarding.md), two production files outside the feature and no harness files.
6. **Typed internal service APIs**
Separate follow-up: replace internal `stateJson()` consumption with typed readonly properties or QML models where practical; rewrite affected fixture doubles; keep JSON at IPC and diagnostics boundaries. The "where practical" criterion is defined in that follow-up.
Exit when affected panels and fixtures pass unchanged interaction and visual evidence.
"Where practical", decided 2026-11-14: panels, surfaces, hosts and in-process callers bind readonly service properties (typed scalars, `var` only for row lists and records) and never call another object's `stateJson()`/`stateObject()` or parse a service's return; `stateJson()`/`stateObject()` are built from those properties for IPC and diagnostics; parsing subprocess output, files and the niri event stream stays JSON.
Done 2026-11-14: osd, audio, media, brightness, power, tray, launcher, connectivity and privilege converted; every converted suite's screenshots matched their baselines pixel for pixel outside the bar clock and known motion frames; `typed-state.test.mjs` enforces the contract and fails on the pre-step-6 tree.