Panama/docs/superpowers/plans/2026-08-18-phase2-expectation-gaps.md

Phase 2 Expectation Gaps Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Deliver application volume, managed lock appearance, wallpaper modes, and safe multi-monitor arrangement as one coherent Panama Settings phase.

Architecture: Phase 2 is four independent subsystems, so each has its own executable plan and focused commits. This master plan fixes their order, cross-slice integration, and the single conservative live verification gate.

Tech Stack: Quickshell 0.3, Qt 6 QML/JavaScript, PipeWire 1.6, Hyprland 0.56.2 Lua, hyprlock 0.9.6, hyprpaper 0.8.4, Bash, jq

Spec: docs/superpowers/specs/2026-08-18-phase2-expectation-gaps-design.md

Global Constraints

• Implement the approved A — Continuity direction; do not introduce an inspector or extra navigation level.
• Use schema/service boundaries already established by Panama Settings.
• Write and observe a focused failing test before every production behavior.
• Keep live desktop mutations out of development loops.
• Do not start playback, acquire the live lock screen, rotate the live wallpaper through fixtures, or emulate a second physical display.
• Run changed-page QML harnesses and the live display contract once at completion, not after every edit.
• Each subsystem must be independently green and committed before the next begins.

Plan set

1. docs/superpowers/plans/2026-08-18-phase2-application-volume.md
2. docs/superpowers/plans/2026-08-18-phase2-lock-screen.md
3. docs/superpowers/plans/2026-08-18-phase2-wallpaper-modes.md
4. docs/superpowers/plans/2026-08-18-phase2-display-arrangement.md

Spec coverage map

Approved requirement	Owning plan/tasks
PipeWire application grouping, controls, empty/error states	Application Volume Tasks 1–4
Generated lock config, safe fallback, preview, search, restore, health	Lock Screen Tasks 1–5
Single/slideshow/per-monitor policy, verification, timer, UI, restore	Wallpaper Modes Tasks 1–6
Position, primary role, transaction/revert, canvas, identify, restore	Display Arrangement Tasks 1–7
Shared ownership, search vocabulary, deterministic restore ordering	Master Task 5
Conservative runtime/config/visual verification and publication	Master Tasks 6–7

---

Task 1: Execute the application-volume plan

Files: Defined in 2026-08-18-phase2-application-volume.md.

Interfaces:

• Produces: AudioDevices.applications and the Sound Applications card.

• Independent of: lock, wallpaper, and display state.

• Step 1: Read the spec and application-volume plan completely

Run: sed -n '1,520p' docs/superpowers/specs/2026-08-18-phase2-expectation-gaps-design.md && sed -n '1,420p' docs/superpowers/plans/2026-08-18-phase2-application-volume.md

• Step 2: Execute every unchecked application-volume task in order

Use strict red-green-refactor cycles and the exact commit boundaries in that plan.

• Step 3: Confirm the slice head

Run: tests/quickshell/application-volume-contract.sh && tests/quickshell/sound-page-contract.sh && git status --short

Expected: both PASS and no uncommitted files.

Task 2: Execute the lock-screen plan

Files: Defined in 2026-08-18-phase2-lock-screen.md.

Interfaces:

• Consumes: existing schema, wallpaper fallback values, and SettingsBackup settle sequencing.

• Produces: panama-lock, LockScreen.qml, generated config, Appearance card, and health/restore integration.

• Step 1: Read the lock-screen plan completely

Run: sed -n '1,520p' docs/superpowers/plans/2026-08-18-phase2-lock-screen.md

• Step 2: Execute every unchecked lock-screen task in order

Never invoke panama-lock run outside its fake-hyprlock fixture.

• Step 3: Confirm the slice head

Run: tests/quickshell/lock-screen-helper-contract.sh && tests/quickshell/lock-screen-service-contract.sh && tests/quickshell/lock-screen-settings-contract.sh && git status --short

Expected: all PASS, no live hyprlock test process, and no uncommitted files.

Task 3: Execute the wallpaper-modes plan

Files: Defined in 2026-08-18-phase2-wallpaper-modes.md.

Interfaces:

• Consumes: schema and connected output names.

• Produces: policy calculation, verified hyprpaper orchestration, runtime slideshow, controls, and restore integration.

• Step 1: Read the wallpaper plan completely

Run: sed -n '1,620p' docs/superpowers/plans/2026-08-18-phase2-wallpaper-modes.md

• Step 2: Execute every unchecked wallpaper task in order

All apply tests use fake hyprpaper IPC and temporary image files.

• Step 3: Confirm the slice head

Run: tests/quickshell/wallpaper-policy-contract.sh && tests/quickshell/wallpaper-service-contract.sh && tests/quickshell/wallpaper-settings-contract.sh && git status --short

Expected: all PASS and no uncommitted files.

Task 4: Execute the display-arrangement plan

Files: Defined in 2026-08-18-phase2-display-arrangement.md.

Interfaces:

• Consumes: existing Displays apply/revert contract and SettingsBackup display protection.

• Produces: pure geometry, extended persistence, whole-layout transactions, arrangement UI, identify overlays, and search/restore integration.

• Step 1: Read the display plan completely

Run: sed -n '1,720p' docs/superpowers/plans/2026-08-18-phase2-display-arrangement.md

• Step 2: Execute every unchecked display task except the live display test

Use fixture monitor JSON for all multi-monitor cases.

• Step 3: Confirm the static slice head

Run: tests/quickshell/display-layout-contract.sh && tests/quickshell/display-transaction-contract.sh && tests/quickshell/display-arrangement-contract.sh && PANAMA_DISPLAYS_STATIC_ONLY=1 tests/quickshell/displays-contract.sh && git status --short

Expected: all PASS and no uncommitted files.

Task 5: Cross-slice Settings integration audit

Files:

• Modify: config/dot/quickshell/services/SettingsBackup.qml
• Modify: config/dot/quickshell/services/SettingsSearch.qml
• Modify: config/dot/quickshell/modules/settings/AppearancePage.qml
• Modify: config/dot/quickshell/modules/settings/README.md
• Modify: relevant existing contracts only when the combined behavior requires it.

Interfaces:

• Consumes: LockScreen.regenerate(), Wallpaper.applyCurrentPolicy(false), and complete display-layout restore.

• Verifies: one deterministic restore sequence and one ownership/search vocabulary.

• Step 1: Expand the combined restore fixture before the final audit

The slice plans already extend tests/quickshell/settings-backup-live-contract.sh test-first. Confirm its final fixture now contains lock, slideshow, and two-output layout values and asserts this exact order: preferences reload, display apply/verify, idle apply, lock generate, wallpaper apply/verify, keybind/compositor settle, shell reload. It must also assert bounded failure remains in service state and shell reload waits for the settle cap.

• Step 2: Run the combined audit

Run: tests/quickshell/settings-backup-live-contract.sh

Expected: PASS. A failure means the independently green hooks conflict and must be debugged before any consolidation.

• Step 3: Consolidate only if the audit exposes duplication

Keep SettingsBackup.qml as the established restore coordinator and its injected wrapper pattern for Displays, Wallpaper, LockScreen, Keybinds, and SystemSettings. If two slices added equivalent settle state, collapse them under the existing timer without changing observable order. Do not create another restore service.

• Step 4: Reconcile search and ownership once

Run the ownership contract against final pages. Manual search entries may exist only for internal JSON controls with no schema row. Remove duplicate terms that the schema already indexes.

• Step 5: Run and verify GREEN

Run: tests/quickshell/settings-backup-live-contract.sh && tests/quickshell/settings-search-contract.sh && tests/quickshell/settings-ownership-contract.sh

Expected: all PASS.

• Step 6: Commit only audit-driven corrections

If Step 2 or Step 5 required corrections, stage only those files and commit them as Integrate Phase 2 desktop settings. If the audit is already green and no consolidation is needed, leave the branch unchanged; an empty ceremony commit is forbidden.

Task 6: Consolidated completion gate

Files:

• Modify only if verification finds a defect.

• Step 1: Run new contracts

tests/quickshell/application-volume-contract.sh
tests/quickshell/lock-screen-helper-contract.sh
tests/quickshell/lock-screen-service-contract.sh
tests/quickshell/lock-screen-settings-contract.sh
tests/quickshell/wallpaper-policy-contract.sh
tests/quickshell/wallpaper-service-contract.sh
tests/quickshell/wallpaper-settings-contract.sh
tests/quickshell/display-layout-contract.sh
tests/quickshell/display-transaction-contract.sh
tests/quickshell/display-arrangement-contract.sh

Expected: all PASS.

• Step 2: Run affected existing contracts

tests/quickshell/sound-page-contract.sh
tests/quickshell/settings-pages-contract.sh
tests/quickshell/settings-search-contract.sh
tests/quickshell/settings-ownership-contract.sh
tests/quickshell/settings-preferences-contract.sh
tests/quickshell/settings-commit-reset-contract.sh
tests/quickshell/settings-backup-live-contract.sh
tests/quickshell/migrations-contract.sh
tests/quickshell/panama-doctor-contract.sh
tests/quickshell/schema-hypr-shape-contract.sh

Expected: all PASS.

• Step 3: Run the one state-changing display contract

Run: tests/quickshell/displays-contract.sh

Expected: PASS and cleanup proves the physical monitor returns to its captured original mode, scale, transform, x, and y. Stop immediately if the preflight reports a dirty display baseline.

• Step 4: Run config and source checks

bash -n config/dot/quickshell/scripts/panama-lock
bash -n config/dot/quickshell/scripts/panama-idle
git diff --check
Hyprland --verify-config

Expected: shell syntax exits 0, diff check is empty, and Hyprland reports config ok.

• Step 5: Construct changed QML once

Run the isolated harness collection once and inspect its complete log for ERROR, WARN, ReferenceError, TypeError, binding loops, invalid anchors, failed property assignments, and focus-grab failures. Expected: none.

• Step 6: Review requirement coverage and branch state

Compare the final diff with every heading in the approved spec. Run git status --short --branch and git log --oneline origin/main..HEAD. Expected: only intentional commits and a clean tree.

Task 7: Merge, activate, and publish

Files: None unless final activation exposes a defect.

• Step 1: Push the feature branch

Run: git push -u origin feat/phase2-expectation-gaps

Expected: remote branch points to the verified head.

• Step 2: Fast-forward clean main

In /home/gib/.local/share/Panama, fetch, prove main is clean and not behind an unexpected remote commit, then run git merge --ff-only feat/phase2-expectation-gaps.

• Step 3: Push main

Run: git push origin main

Expected: origin/main equals local main.

• Step 4: Restart Quickshell once

Use Panama's verified graceful shell restart action. Do not open repeated harness windows. Confirm qs list --all reports one live production instance and inspect only the fresh startup log.

• Step 5: Perform one visual review

Open Settings once and inspect Sound Applications, Appearance Lock screen and Wallpaper, and Displays Arrangement. Confirm narrow tiled layout, empty states, focus order, and preview/canvas geometry. Locking, wallpaper rotation, and adding a monitor remain user-driven real-world follow-ups unless a safe no-op state already exercises them.

• Step 6: Report exact delivery evidence

Provide commit range, pushed branch/main state, contract counts, the live display restoration result, Quickshell instance state, and any capability that could not be exercised without external hardware or acquiring the live lock screen.