Names, paths, findings and gate counts below describe the recorded tree, not today's onboarding contract.
Current contract: onboarding.
Step 4 evidence, 2026-11-13, for the owner's continue, adjust, or stop decision.
A fresh child agent (Claude Opus, high reasoning) onboarded the OSD with only the public contracts as its brief: .system/, Registry.qml, FeatureEntry.qml, features/audio/, justfile, the fixture README, and the UI skill.
It recorded its own reads, gate runs, and gaps; the parent agent read the diff and re-ran every gate.
The work sits on branch revamp/osd-onboarding, not on trunk.
Production load: unproven
No gate loads production shell.qml; the just lint runtime stage only pings the already running shell.
The live desktop shell hot-reloads this working tree, so it loaded the child's in-progress OSD states: its log shows Unable to assign Osd_QMLTYPE… to Osd_QMLTYPE… at shell.qml (the Media injection) and Registry.qml (the panel binding), followed by panel TypeErrors.
Those warnings may be a stale type cache from hot-reloading a moved type, or a real type-identity defect; a later reload logged no warnings, but which tree state it loaded is unknown.
A fresh, isolated production load of the branch has not been run.
Result
OSD lives in features/osd/: service, pure model, model test, panel, load target.
Registry.qml gains an overlays list with the OSD entry; a new generic OverlayHost.qml replaces the inline OSD surface in shell.qml and keeps its per-screen, primary-screen-only, click-through, keyboardless behavior.
Parent re-run on the branch: just lint 0 (includes just test and just load-test), just load-test osd 0, just ui-test 9/9 in 31 s.
The OSD card moved with identifier renames and added objectNames only (parent diff read against trunk shell.qml).
Rendering: the parent viewed two 1280×720 screenshots; 1366×768 and 2560×1440 rest on the child's review. There is no pre-move nested OSD image to compare against, and event icons render empty in the fixture.
Step 2's exit (just load-test osd) is met only on this branch; trunk has no OSD load target.
Against the pilot's prediction
baseline.md "After the audio pilot" predicted a second feature needs 2 production and 4 shared test files.
Metric
Predicted
OSD onboarding
Onboarded from public contracts alone
goal
no
Host-internal files read
0
about 12, each recorded with its blocker
Production files changed outside features/osd/
2
8: Registry.qml, FeatureEntry.qml, new OverlayHost.qml, shell.qml, Media.qml, Brightness.qml, Screenshots.qml, the audio reference features/audio/Audio.qml
Test and harness files changed
4
9: load-test.mjs, ui-test.mjs, ui-test.test.mjs, tasks.mjs, tasks.qml, four brightness tests
Iterations to green
unmeasured
11 gate runs from first edit to first full green, 6 failing; 4 more after a test race surfaced at another size
OSD is an overlay with a cross-feature service type, the hardest kind of second feature; an ordinary popup would cost less, but how much less is unmeasured.
Contract gaps
FeatureEntry.kind and uiSuite are read by nothing; every entry is a popup. Workaround: a separate overlays list and OverlayHost; kind and list membership now duplicate each other.
The entry has no data for overlay visibility or placement. Workaround: overlayShown; placement is OverlayHost policy.
Moving a service other features type against (Osd) fans out to every consumer, including test copies. The contracts are silent on cross-feature service types.
just load-test applied only the target feature's doubles, but the registry creates every feature's service. The branch makes it apply every feature's doubles, which also changes just load-test audio; RULES.md still describes the old behavior.
A named ui-test suite cannot be added from feature-local files: suite name, branch, projection, and events live in four shared test files.
No public way for a fixture to locate overlay surfaces. Workaround: OverlayHost.surface(name).
Undocumented: screenshot names containing error/failed/warn trip the log gate.
Undocumented: keys sent before popup.windowActive are lost.
No isolated production load of shell.qml exists (see above).
Owner decision
2026-11-13: continue, adjusting the contract first (plan step 4b).
Addressed in step 4b: gap 1 (hosts read kind), gap 5 (feature-local suites), and agent isolation from the live shell.
Open issues
The OSD renders capitalized labels (Volume, Microphone, Error, OSD) against the lowercase-label rule; existing behavior, left unchanged.
Event icons are empty in the nested fixture because it lacks the production icon theme pragma; production icon rendering is unproven.
The frozen audio reference changed one import line.
The osd suite drives events through fixture IPC, not through real producers.
Agents editing this working tree hot-reload the user's live desktop shell; isolation needs a decision.
# Independent OSD onboarding
## Historical evidence
Names, paths, findings and gate counts below describe the recorded tree, not today's onboarding contract.
Current contract: [onboarding](../../specs/NL-SPEC-A7K4QX2M-nuguland-agent-onboarding/index.md).
Step 4 evidence, 2026-11-13, for the owner's continue, adjust, or stop decision.
A fresh child agent (Claude Opus, high reasoning) onboarded the OSD with only the public contracts as its brief: `.system/`, `Registry.qml`, `FeatureEntry.qml`, `features/audio/`, `justfile`, the fixture README, and the UI skill.
It recorded its own reads, gate runs, and gaps; the parent agent read the diff and re-ran every gate.
The work sits on branch `revamp/osd-onboarding`, not on trunk.
## Production load: unproven
No gate loads production `shell.qml`; the `just lint` runtime stage only pings the already running shell.
The live desktop shell hot-reloads this working tree, so it loaded the child's in-progress OSD states: its log shows `Unable to assign Osd_QMLTYPE… to Osd_QMLTYPE…` at `shell.qml` (the `Media` injection) and `Registry.qml` (the panel binding), followed by panel `TypeError`s.
Those warnings may be a stale type cache from hot-reloading a moved type, or a real type-identity defect; a later reload logged no warnings, but which tree state it loaded is unknown.
A fresh, isolated production load of the branch has not been run.
## Result
- OSD lives in `features/osd/`: service, pure model, model test, panel, load target.
- `Registry.qml` gains an `overlays` list with the OSD entry; a new generic `OverlayHost.qml` replaces the inline OSD surface in `shell.qml` and keeps its per-screen, primary-screen-only, click-through, keyboardless behavior.
- Parent re-run on the branch: `just lint` 0 (includes `just test` and `just load-test`), `just load-test osd` 0, `just ui-test` 9/9 in 31 s.
- The OSD card moved with identifier renames and added `objectName`s only (parent diff read against trunk `shell.qml`).
- Rendering: the parent viewed two 1280×720 screenshots; 1366×768 and 2560×1440 rest on the child's review. There is no pre-move nested OSD image to compare against, and event icons render empty in the fixture.
- Step 2's exit (`just load-test osd`) is met only on this branch; trunk has no OSD load target.
## Against the pilot's prediction
`baseline.md` "After the audio pilot" predicted a second feature needs 2 production and 4 shared test files.
| Metric | Predicted | OSD onboarding |
| --- | --- | --- |
| Onboarded from public contracts alone | goal | no |
| Host-internal files read | 0 | about 12, each recorded with its blocker |
| Production files changed outside `features/osd/` | 2 | 8: `Registry.qml`, `FeatureEntry.qml`, new `OverlayHost.qml`, `shell.qml`, `Media.qml`, `Brightness.qml`, `Screenshots.qml`, the audio reference `features/audio/Audio.qml` |
| Test and harness files changed | 4 | 9: `load-test.mjs`, `ui-test.mjs`, `ui-test.test.mjs`, `tasks.mjs`, `tasks.qml`, four brightness tests |
| Iterations to green | unmeasured | 11 gate runs from first edit to first full green, 6 failing; 4 more after a test race surfaced at another size |
OSD is an overlay with a cross-feature service type, the hardest kind of second feature; an ordinary popup would cost less, but how much less is unmeasured.
## Contract gaps
1. `FeatureEntry.kind` and `uiSuite` are read by nothing; every entry is a popup. Workaround: a separate `overlays` list and `OverlayHost`; `kind` and list membership now duplicate each other.
2. The entry has no data for overlay visibility or placement. Workaround: `overlayShown`; placement is `OverlayHost` policy.
3. Moving a service other features type against (`Osd`) fans out to every consumer, including test copies. The contracts are silent on cross-feature service types.
4. `just load-test` applied only the target feature's doubles, but the registry creates every feature's service. The branch makes it apply every feature's doubles, which also changes `just load-test audio`; `RULES.md` still describes the old behavior.
5. A named `ui-test` suite cannot be added from feature-local files: suite name, branch, projection, and events live in four shared test files.
6. No public way for a fixture to locate overlay surfaces. Workaround: `OverlayHost.surface(name)`.
7. Undocumented: screenshot names containing `error`/`failed`/`warn` trip the log gate.
8. Undocumented: keys sent before `popup.windowActive` are lost.
9. No isolated production load of `shell.qml` exists (see above).
## Owner decision
2026-11-13: continue, adjusting the contract first (plan step 4b).
Addressed in step 4b: gap 1 (hosts read `kind`), gap 5 (feature-local suites), and agent isolation from the live shell.
## Open issues
- The OSD renders capitalized labels (`Volume`, `Microphone`, `Error`, `OSD`) against the lowercase-label rule; existing behavior, left unchanged.
- Event icons are empty in the nested fixture because it lacks the production icon theme pragma; production icon rendering is unproven.
- The frozen audio reference changed one import line.
- The `osd` suite drives events through fixture IPC, not through real producers.
- Agents editing this working tree hot-reload the user's live desktop shell; isolation needs a decision.