gib/Panama
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c4733e0624dd3cfa56df1a5d159b0036d90ae7f2
Panama/docs/superpowers/plans/2026-08-18-roadmap-completion.md
T

12 KiB
Raw 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 3–5 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.sh
  • Test: tests/quickshell/display-transaction-contract.sh
  • Test: tests/quickshell/lock-screen-helper-contract.sh
  • Test: tests/quickshell/wallpaper-service-contract.sh
  • Test: tests/quickshell/wallpaper-settings-contract.sh

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.sh and verify PASS.

  • Add a failing display fixture that changes the harness screen model without calling the display service’s 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.sh and bash tests/quickshell/display-layout-contract.sh.

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

  • 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.sh
  • Create or modify: tests/quickshell/overview-thumbnail-contract.sh

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.sh
  • Test: create tests/quickshell/accent-controls-contract.sh
  • Test: modify tests/quickshell/control-center-contract.sh

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.sh
  • Test: modify tests/quickshell/gtk-theme-contract.sh if its invocation contract changes

Interfaces:

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

  • Consumes: the selected profile’s 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 application’s 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.sh
  • Test: modify tests/quickshell/settings-backup-live-contract.sh
  • Test: create tests/quickshell/generated-docs-contract.sh
  • Test: modify tests/quickshell/keybind-rebind-contract.sh

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 repository’s 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.

Reference in New Issue View Git Blame Copy Permalink