# 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 && tests/quickshell/sound-page-contract && 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 && tests/quickshell/lock-screen-service-contract && tests/quickshell/lock-screen-settings-contract && 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 && tests/quickshell/wallpaper-service-contract && tests/quickshell/wallpaper-settings-contract && 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 && tests/quickshell/display-transaction-contract && tests/quickshell/display-arrangement-contract && PANAMA_DISPLAYS_STATIC_ONLY=1 tests/quickshell/displays-contract && 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` 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`

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 && tests/quickshell/settings-search-contract && tests/quickshell/settings-ownership-contract`

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**

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

Expected: all PASS.

- [ ] **Step 2: Run affected existing contracts**

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

Expected: all PASS.

- [ ] **Step 3: Run the one state-changing display contract**

Run: `tests/quickshell/displays-contract`

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
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.
