Files
Panama/docs/superpowers/plans/2026-08-18-roadmap-completion.md
Gabriel Brown 6016efa436 Meet main where it has moved since this branch was written
The rebase itself is the previous five commits replayed onto main; this is what
they needed once they landed there, kept separate so the replay stays readable.

The shell did not start. A Column in this branch's notification settings menu
assigned its own implicitWidth and implicitHeight, which a Qt 6 positioner
computes and does not let you set. That took out every contract that launches a
shell -- six of the seven failures were this one line, and none of them said so
until the error was read to the bottom. A Column already measures itself from its
children, so the bindings are simply gone.

Three assertions pinned an implementation main has since replaced, and each is
updated to pin the intent rather than the mechanism:

  - The display picker now reads primaryFirstMonitors, which is monitors sorted
    with the primary first. Still populated from what is connected, which is what
    the contract is for; the sorted list is the point, so the picker opens on the
    display somebody is most likely to mean. This branch made that change and
    broke its own contract without noticing.
  - The accent swatches come from the accentName schema rather than
    Object.keys(Theme.accents). Same swatches, same order, one source shared with
    every other enum row.
  - The OSD used to take no pointer input at all. It takes some now, because this
    branch's own design calls for a secondary click on a visible OSD to open its
    settings, and a Wayland input region cannot admit one button and refuse
    another. The rule that survives is that the region stays bounded to the OSD's
    own card: it floats over other windows for a couple of seconds, and a region
    bigger than the card would swallow clicks meant for something underneath.

Theme's accent table moved to ThemeProfiles, which is this branch's point -- a
curated accent and a custom profile become the same kind of record. main had
meanwhile given each accent a `gnome` member, the nearest name in GNOME's fixed
accent-color enum, which is what makes libadwaita applications recolor instead of
staying in GNOME blue. That member moved into the curated table rather than being
dropped, and adwaita-accent-contract now reads it where it lives.

Where main had simply moved further along the same path, main won: the focused
border driven by the chosen accent rather than a hardcoded pair, the gradient
built through the shared serializer rather than a hand-rolled string, the
multi-edge dock geometry. This branch's context menu, keyboard focus and
accessibility work sit on top of those rather than beside them.

Three new contracts arrived carrying .sh and lost it, along with the references
in this branch's own plan.

124 contracts pass.

Claude-Session: https://claude.ai/code/session_01NvgBuSWB5sE43yWmg21ozj
2026-08-20 22:23:27 -04:00

12 KiB
Raw Permalink Blame History

Panama Roadmap Completion 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: Close every audited correctness gap and finish the approved Phase 35 Panama roadmap.

Architecture: Preserve Settings, DesktopPreferences, and Theme.qml as the existing ownership spine. Add narrowly scoped event observers, adapters, and generated artifacts around those boundaries; contextual shell surfaces only route into Settings. Each task is independently committed and contract-tested before final integration.

Tech Stack: Quickshell/QML, JavaScript, Bash, Python 3, Hyprland Lua, systemd user units, jq.

Spec: docs/superpowers/specs/2026-08-18-roadmap-completion-design.md

Global Constraints

  • Preserve the current Prism/Tokyo Night design language and existing component library.
  • Do not introduce continuously repainting effects or polling loops.
  • Do not expose or modify config/bash/env.
  • Write a failing contract before each production change and record the red/green commands.
  • Keep interactive QML harnesses and Quickshell restarts for the final integration gate.
  • Generated and user-owned files must be written atomically.
  • No production configuration is activated until the reviewed branch is merged.

Task 1: Close Phase 1 and Phase 2 safety gaps

Files:

  • Modify: config/dot/quickshell/services/ColorScheme.qml
  • Modify: config/dot/quickshell/modules/settings/README.md
  • Modify: config/dot/hypr/looks.lua
  • Modify: config/dot/quickshell/services/Displays.qml
  • Modify: config/dot/quickshell/modules/settings/DisplaysPage.qml
  • Modify: config/dot/quickshell/scripts/panama-lock
  • Modify: config/dot/quickshell/services/Wallpaper.qml
  • Modify: config/dot/quickshell/modules/settings/WallpaperControls.qml
  • Test: tests/quickshell/settings-ownership-contract
  • Test: tests/quickshell/display-transaction-contract
  • Test: tests/quickshell/lock-screen-helper-contract
  • Test: tests/quickshell/wallpaper-service-contract
  • Test: tests/quickshell/wallpaper-settings-contract

Interfaces:

  • Produces: Displays.primaryFirstMonitors, event-driven topology refresh, and a lock helper that never emits an unreadable image.

  • Consumes: current Theme.accent, Theme.accentSecondary, display transaction rollback, and wallpaper preference schema.

  • Add failing ownership assertions that active borders derive from Theme.accent and Theme.accentSecondary, while inactive borders derive only from scheme roles; verify the current contract fails for the stale prohibition.

  • Update the ownership implementation comments and documentation, then run bash tests/quickshell/settings-ownership-contract and verify PASS.

  • Add a failing display fixture that changes the harness screen model without calling the display services public refresh() and expects topology reconciliation plus rollback of a pending transaction.

  • Add an event-driven screen-model observer and primary-first derived monitor list; run bash tests/quickshell/display-transaction-contract and bash tests/quickshell/display-layout-contract.

  • Add failing lock fixtures for missing global and per-monitor wallpapers, requiring readable shipped-image fallback and screenshot fallback when no image exists.

  • Tighten panama-lock path validation and bounded warnings; run bash tests/quickshell/lock-screen-helper-contract.

  • Add failing wallpaper contracts for primary-first output order, selection preservation, and a HOME path containing a single quote.

  • Replace inline bash -lc path interpolation with an argument-safe helper and update controls to preserve selection; run both wallpaper contracts.

  • Run the Task 1 contract set and commit with message Close desktop safety gaps.

Task 2: Complete contextual configuration and reliable overview capture

Files:

  • Modify: config/dot/quickshell/modules/dock/Dock.qml
  • Modify: relevant dock context-menu component if already split
  • Modify: config/dot/quickshell/modules/notifications/NotificationCard.qml
  • Modify: config/dot/quickshell/modules/osd/Osd.qml
  • Modify: config/dot/quickshell/modules/overview/WindowThumbnail.qml
  • Modify: config/dot/quickshell/services/ShellState.qml
  • Test: tests/quickshell/settings-jump-contract
  • Create or modify: tests/quickshell/overview-thumbnail-contract

Interfaces:

  • Produces: one route per configurable surface into the existing owning Settings page.

  • Consumes: ShellState.openSettings(page) and the existing app-icon thumbnail fallback.

  • Extend the settings-jump contract so it fails until dock, notifications, and OSD each expose a contextual Settings route without replacing their primary action.

  • Add the three restrained contextual actions using existing menu/button styles and Settings routes.

  • Add a failing static/isolated contract proving capture does not start before recording readiness, is bounded, and retains the icon fallback.

  • Gate capture on recording readiness or the appropriate Quickshell frame-ready signal, remove warning-producing blind retries, and keep capture event-driven.

  • Run both contracts and commit with message Complete contextual desktop controls.

Task 3: Complete advanced accents and named themes

Files:

  • Modify: config/dot/quickshell/config/PreferenceSchema.qml
  • Modify: config/dot/quickshell/config/Theme.qml
  • Create: config/dot/quickshell/services/ThemeProfiles.qml
  • Modify: config/dot/quickshell/modules/settings/AccentPicker.qml
  • Create: config/dot/quickshell/modules/settings/AccentEditor.qml
  • Create: config/dot/quickshell/modules/settings/ThemeProfilePicker.qml
  • Modify: config/dot/quickshell/modules/settings/AppearancePage.qml
  • Modify: config/dot/quickshell/services/ColorScheme.qml
  • Modify: config/dot/quickshell/services/SettingsSearch.qml
  • Test: create tests/quickshell/theme-profiles-contract
  • Test: create tests/quickshell/accent-controls-contract
  • Test: modify tests/quickshell/control-center-contract

Interfaces:

  • Produces: profile records {id,name,scheme,accent,secondary,shipped} and reactive Theme colour roles.

  • Consumes: DesktopPreferences, SystemSettings.commitPreference, hyprpicker, and current Prism Settings components.

  • Write failing pure-model fixtures for three shipped profiles, custom profile creation, bounded unique names, shipped-profile immutability, and HSV/hex conversion.

  • Implement ThemeProfiles with Moon, Moon Rose, and Day plus saved custom profiles, then verify model tests.

  • Write failing UI contracts for labelled HSV controls, curated swatches, keyboard focus, screen picking, profile save/switch/delete, and search routing.

  • Build the profile picker and advanced editor from existing SettingRow, ValueSlider, SettingsButton, and focus tokens; do not add ambient animation.

  • Update Theme.qml and ColorScheme so custom pairs reactively reach shell roles and Hyprland borders.

  • Extend the Control Center contract to cover power profiles, night light, and colour scheme controls added after its original contract.

  • Run theme, accent, ownership, settings-search, and Control Center contracts; commit with message Complete the Panama theme system.

Task 4: Propagate the accent to external applications

Files:

  • Modify: config/dot/quickshell/scripts/panama-theme-apps
  • Modify: config/dot/quickshell/services/ColorScheme.qml
  • Modify: tracked kitty/tmux/Vicinae/Wofi/Neovim include points as required
  • Create: generated-file templates or helpers under the owning application directories
  • Test: create tests/quickshell/theme-apps-accent-contract
  • Test: modify tests/quickshell/gtk-theme-contract if its invocation contract changes

Interfaces:

  • Produces: panama-theme-apps dark|light [#RRGGBB #RRGGBB] with per-adapter JSON status.

  • Consumes: the selected profiles validated primary and secondary accents.

  • Write a failing isolated fixture invoking the helper with dark/light and custom pairs, asserting atomic generated overrides for kitty, tmux, btop, Vicinae/Wofi, hyprlock, and Neovim plus backward-compatible two-state invocation.

  • Implement validated optional accent arguments and independent adapters; never rewrite user-owned base files wholesale.

  • Update each applications tracked config to include its generated accent override after the base Tokyo Night theme.

  • Pass the selected pair from ColorScheme and expose bounded adapter failures through its existing error state.

  • Run the isolated helper contract, GTK contract, Bash syntax, and a fixture-only idempotence check; commit with message Propagate accents across desktop applications.

Task 5: Finish onboarding, recovery automation, and generated docs

Files:

  • Modify: config/dot/quickshell/config/PreferenceSchema.qml
  • Create: config/dot/quickshell/modules/settings/WelcomePage.qml
  • Modify: config/dot/quickshell/modules/settings/SettingsShell.qml
  • Modify: config/dot/quickshell/modules/settings/SettingsSidebar.qml
  • Modify: config/dot/quickshell/services/SettingsSearch.qml
  • Modify: config/dot/quickshell/services/SystemSettings.qml
  • Modify: display/theme/reset/restore call sites for pre-risk snapshots
  • Modify: setup/scripts/link-dotfiles
  • Create: user systemd snapshot service/timer files under the existing systemd config tree
  • Create: config/dot/quickshell/scripts/panama-generate-docs
  • Create: docs/SETTINGS.md
  • Create: docs/SHORTCUTS.md
  • Test: create tests/quickshell/first-run-contract
  • Test: modify tests/quickshell/settings-backup-live-contract
  • Test: create tests/quickshell/generated-docs-contract
  • Test: modify tests/quickshell/keybind-rebind-contract

Interfaces:

  • Produces: fresh-install marker lifecycle, snapshot --cause <cause> retention, and deterministic generated Markdown.

  • Consumes: existing Settings navigation, backup/restore helper, preference schema, and shipped keybind metadata.

  • Write failing first-run fixtures proving only fresh installs get a marker, completion removes it atomically, existing settings are not interrupted, and Welcome remains searchable.

  • Implement the Welcome page and marker lifecycle using existing card/row components.

  • Add failing backup fixtures for daily retention and pre-risk snapshots before display layout, named theme, reset-all, and restore operations.

  • Extend the backup helper/service with labelled atomic snapshots, fourteen-day retention, and a systemd user timer; wire the four risky call sites.

  • Strengthen keybind contracts to explicitly cover both rebind and reset collisions.

  • Write a failing drift contract for generated settings and shortcut documentation.

  • Implement the deterministic generator, generate both Markdown files, and verify a second run produces no diff.

  • Run first-run, backup, keybind, generated-docs, schema, and search contracts; commit with message Finish onboarding and desktop recovery.

Task 6: Integrate, review, activate, and verify live readiness

Files:

  • Modify only files required by review findings.
  • Update roadmap/status documentation to mark exact delivered scope.

Interfaces:

  • Consumes: all preceding task commits.

  • Produces: reviewed main, pushed origin, one activated Quickshell session, and an evidence ledger.

  • Run git diff --check, executable Bash syntax, Lua syntax, generated-doc drift, every non-interactive Quickshell contract, and Hyprland configuration validation.

  • Dispatch a whole-branch code review against this plan and fix every Critical/Important finding with one reviewed fix wave.

  • Merge the reviewed branch into main without rewriting shared history and push origin/main.

  • Run the repositorys user-level setup/link step needed for new systemd units and autostarts; do not print environment secrets.

  • Resolve live health where locally actionable: enable RustDesk and Nextcloud user autostart, install/link calendar integration if its declared dependency is already available, and leave hardware-only DDC as a documented warning.

  • Restart Quickshell once, perform the interactive visual/runtime gate, inspect logs for QML errors and screencopy warnings, and run panama-doctor --json.

  • Record exact passed commands, remaining environment-only observations, and final commit IDs.