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

12 KiB
Raw Permalink Blame History

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

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