gib/Panama
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Panama/docs/superpowers/plans/2026-08-18-phase2-expectation-gaps.md
T
Gabriel Brown e1faaf7a76 Drop the extension, and give the test suite a front door 
Phase 6, the last of the fresh-install spec.

159 scripts lose their .sh: 110 contracts, 47 Vicinae commands, 2 compositor
contracts. A shebang and the executable bit already select the interpreter. The
extension only ever added something that had to stay in sync, and the rename
proved the point twice over in the space of an hour.

The spec's stated risk was Vicinae's script discovery. One script was renamed and
reloaded on its own before the other 46 followed; it came back as
scripts:panama.capture and all 47 resolve. What the probe turned up instead is
that the extension was never only a filename: Vicinae's command IDs embed it, so
every ID changed. Nothing in this repository refers to them, so nothing breaks.
The only trace is Vicinae's metadata.json, whose visited map had two Panama
entries that are now orphaned -- two commands lost their usage ranking and will
earn it back. Worth knowing before anyone renames these again on a machine that
has a keybind pointing at one.

Rewriting the references by exact filename missed two things it structurally
could not see: a name built from a variable, settings-$page.sh, and a glob,
-name '*.sh'. Both were in the contract that counts the generated commands, which
promptly reported 47 expected and 0 found. The mechanical part of a rename is the
part that looks finished.

The three subcommands. panama doctor fronts a health check that already existed
and already ran at the end of every install but could not be reached from a
terminal. panama upgrade re-runs the installer from anywhere. panama test runs
the suite, which had no entry point at all -- 121 files that were the main safety
net in this repository and were invisible in it.

Writing that runner found three tests nothing was running.
calendar_agenda_bridge_test, home_assistant_bridge_test and kdeconnect_bridge_test
are unittest suites without the executable bit, so no contract invoked them and
the first draft of the runner skipped them silently. All three pass, and have
passed unobserved for weeks. The runner collects *_test.py as well now, because a
runner with a blind spot is worse than no runner for the same reason a dependency
checker with one is: it reports PASS.

Six worktrees pruned. Each was re-checked rather than trusted to the spec's list,
and two needed it: panama-commands is not on feat/panama-commands but on
feat/gnome-tweaks-parity, and fix/panama-displays-review reads [ahead 3] -- ahead
of its remote, not of main, with every commit patch-equivalent to landed work.
roadmap-completion stays; it has five commits that are genuinely unlanded. The
branches are left alone: pruning a worktree costs nothing, deleting a branch is a
decision.

121 contracts pass.

Claude-Session: https://claude.ai/code/session_01NvgBuSWB5sE43yWmg21ozj
2026-08-20 21:55:55 -04:00

267 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
Reference in New Issue View Git Blame Copy Permalink