Panama/docs/superpowers/plans/2026-08-18-settings-home-phone-completion.md

Settings Home & Phone 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: Finish the Home & Phone Settings page on Panama's shared Settings vocabulary and give the global reset path a named, durable Home preference API.

Architecture: HomePhonePage adopts SettingsPage for the shared scrolling/title/lede scaffold while retaining its specialized catalog, reorder, alias, and phone controls. HomePreferences.resetHomeDefaults() becomes the sole Home-store reset boundary: it returns the store to fresh-install state and writes immediately so SystemSettings.restoreDefaults() can call it without mutating aliases.

Tech Stack: Quickshell 0.3 QML, QtQuick, Bash contract tests, Hyprland.

Spec: docs/superpowers/specs/2026-08-17-panama-cohesion-design.md

Global Constraints

• Do not touch SystemSettings.qml, PreferenceSchema.qml, keybinds, or Claude's shared row implementations in this branch.
• Preserve ordered Home favorites, aliases, first-four Control Center badges, search, drag and keyboard reorder, retry state, Home Assistant status copy, and BlueBubbles availability behavior.
• Automated tests must not toggle or dim a real light and must not launch BlueBubbles.
• New behavior follows red-green TDD; fixture and state directories remain isolated from the live desktop.
• No mock phase and no new visual direction: this is cohesion work against the already-approved design.

---

Task 1: Shared Home & Phone page and named reset boundary

Files:

• Modify: config/dot/quickshell/config/HomePreferences.qml
• Modify: config/dot/quickshell/home-preferences-harness.qml
• Modify: config/dot/quickshell/modules/settings/HomePhonePage.qml
• Modify only if required for shared vocabulary compatibility: config/dot/quickshell/modules/settings/HomeFavoriteCard.qml
• Modify only if required for shared vocabulary compatibility: config/dot/quickshell/modules/settings/AvailableLightRow.qml
• Modify: tests/quickshell/home-preferences-contract.sh
• Modify: tests/quickshell/home-phone-settings-contract.sh

Interfaces:

• Consumes: SettingsPage { title; lede; default content }, existing SettingsCard, SettingRow, ActionRow, TextRow, HomeAssistant, SystemSettings.bluebubblesAvailable, and writable HomePreferences adapter state.

• Produces: HomePreferences.resetHomeDefaults(): void, which sets favorites to [], sets initialized to false, clears stale save error state, and invokes preferencesFile.writeAdapter() immediately after stopping the debounce timer.

• Step 1: Write failing contracts

Add reset() to the isolated home-pref-test IPC harness. Extend home-preferences-contract.sh to seed aliases/order, invoke reset, and require both IPC state and panama-home.json to become exactly {"initialized":false,"favorites":[]} without waiting for the 180 ms debounce interval. Extend home-phone-settings-contract.sh to require SettingsPage {, title: "Home & Phone", and the existing lede through lede:, while rejecting the copied root Flickable scaffold.

• Step 2: Run contracts to verify RED

tests/quickshell/home-preferences-contract.sh
tests/quickshell/home-phone-settings-contract.sh

Expected: the preference contract fails because reset is missing; the page contract fails because the page still owns a copied Flickable scaffold.

• Step 3: Implement the reset API and shared page scaffold

Implement this public boundary in HomePreferences.qml:

function resetHomeDefaults(): void {
    persistTimer.stop();
    values.favorites = [];
    values.initialized = false;
    root.saveError = "";
    preferencesFile.writeAdapter();
}

Replace the HomePhonePage root Item plus nested Flickable/title/lede scaffold with:

SettingsPage {
    id: root
    objectName: "home-phone-page"
    title: "Home & Phone"
    lede: "Choose what appears in Control Center and keep phone continuity close at hand."
    // Existing SettingsCard content remains in order.
}

Use shared ActionRow or TextRow only where their single-action/read-only contracts preserve all current status and accessibility behavior. Keep specialized rows when the shared primitive would lose information.

• Step 4: Run focused contracts to GREEN

tests/quickshell/home-preferences-contract.sh
tests/quickshell/home-phone-settings-contract.sh
tests/quickshell/settings-pages-contract.sh
tests/quickshell/settings-rows-contract.sh
tests/quickshell/settings-commit-reset-contract.sh

Expected: every command exits 0; no test launches BlueBubbles or changes a real Home Assistant entity.

• Step 5: Commit

git add config/dot/quickshell/config/HomePreferences.qml \
  config/dot/quickshell/home-preferences-harness.qml \
  config/dot/quickshell/modules/settings/HomePhonePage.qml \
  config/dot/quickshell/modules/settings/HomeFavoriteCard.qml \
  config/dot/quickshell/modules/settings/AvailableLightRow.qml \
  tests/quickshell/home-preferences-contract.sh \
  tests/quickshell/home-phone-settings-contract.sh \
  docs/superpowers/plans/2026-08-18-settings-home-phone-completion.md
git commit -m "Finish Home and Phone settings cohesion"