Plan the Panama calendar agenda

2026-08-17 11:15:19 -04:00
parent e92c2ee5f9
commit 530a5590a6
1 changed files with 811 additions and 0 deletions
@@ -0,0 +1,811 @@
 # Calendar Agenda 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:** Build the approved A · Daybook date menu using the workstation's existing Evolution Data Server calendars, with a quiet upcoming-event capsule and GNOME Calendar handoff.
 **Architecture:** A Python/GObject bridge queries enabled EDS calendar sources through `EDataServer` and `ECal`, expands recurring instances, and streams normalized JSON snapshots. A Quickshell singleton owns that stream and exposes date/event selectors to a two-column Daybook, while GNOME Calendar remains responsible for accounts and event editing.
 **Tech Stack:** Python 3.14, PyGObject, Evolution Data Server 3.60 (`EDataServer`, `ECal`, `ICalGLib`), Quickshell 0.3/QML, Gio D-Bus, Bash contract tests, jq, Hyprland 0.56
 **Spec:** `docs/superpowers/specs/2026-08-17-calendar-agenda-design.md`
 ## Global Constraints
 - Use only enabled EDS event sources; never read authentication extensions or credential stores.
 - GNOME Calendar owns account configuration and event editing.
 - Live event content must never be written to logs, settings, test fixtures, screenshots committed to the repository, or documentation.
 - The bridge may emit event content only to its Quickshell consumer over stdout.
 - Descriptions and attendees never enter the bridge output; descriptions may only be inspected to locate an allowed HTTPS meeting URL.
 - Allowed meeting providers are Google Meet, Zoom, Microsoft Teams, Webex, and Jitsi.
 - Calendar failures must not break notifications, media, weather, or the static month grid.
 - The bar capsule appears from 15 minutes before through 5 minutes after a timed event starts; all-day events never produce it.
 - No calendar toasts, sounds, pulse, shimmer, or continuously repainting animation.
 - No test may create, modify, or delete a real calendar event.
 - Wi-Fi QR sharing is removed from Panama's roadmap and package guidance.
 ---
 ## File map
 ### Calendar data boundary
 - `config/dot/quickshell/scripts/calendar-agenda` — executable Python bridge; the only code that imports EDS libraries.
 - `config/dot/quickshell/services/CalendarAgenda.qml` — singleton state consumed by shell UI; supervises the bridge and owns date-derived selectors.
 - `tests/quickshell/calendar_agenda_bridge_test.py` — pure normalization and URL-policy tests using synthetic components only.
 - `tests/quickshell/calendar-agenda-helper-contract.sh` — executable/probe/live-query contract that redacts live content.
 - `tests/quickshell/calendar-agenda-contract.sh` — live Quickshell IPC/state contract using synthetic in-memory fixtures.
 ### Daybook presentation
 - `config/dot/quickshell/modules/datemenu/AgendaEvent.qml` — one event row.
 - `config/dot/quickshell/modules/datemenu/AgendaPane.qml` — Up Next, all-day section, timed agenda, empty/error states, and notification summary.
 - `config/dot/quickshell/modules/datemenu/NotificationSummary.qml` — quiet bridge from Agenda to the existing grouped notification list.
 - `config/dot/quickshell/modules/datemenu/DateMenuPanel.qml` — approved two-column layout and agenda/notification routing.
 - `config/dot/quickshell/modules/datemenu/CalendarGrid.qml` — date selection, adjacent-month navigation, and event dots.
 - `config/dot/quickshell/modules/datemenu/DateMenu.qml` — panel sizing, preparation, and notification read-state behavior.
 - `config/dot/quickshell/modules/datemenu/qmldir` — explicit registrations for new components.
 ### Shell and bar integration
 - `config/dot/quickshell/services/ShellState.qml` — `dateMenuPage` and explicit Agenda/Notifications open semantics.
 - `config/dot/quickshell/modules/bar/Clock.qml` — clock opens Agenda rather than an undifferentiated notification overlay.
 - `config/dot/quickshell/modules/bar/CalendarIndicator.qml` — quiet 15-minute capsule.
 - `config/dot/quickshell/modules/bar/Bar.qml` — mounts the capsule in the right status area.
 - `config/dot/quickshell/shell.qml` — calendar IPC fixture/diagnostics surface and notification-page routing.
 ### Documentation
 - `config/dot/hypr/DESKTOP-PARITY.md` — calendar becomes Live and Wi-Fi QR is removed.
 - `config/dot/hypr/README.md` — EDS/GNOME Calendar handoff and capsule behavior.
 - `setup/packages/hyprland-packages` — remove `qrencode` if it is present only for the abandoned Wi-Fi QR feature.
 ---
 ### Task 1: EDS calendar bridge
 **Files:**
 - Create: `config/dot/quickshell/scripts/calendar-agenda`
 - Create: `tests/quickshell/calendar_agenda_bridge_test.py`
 - Create: `tests/quickshell/calendar-agenda-helper-contract.sh`
 **Interfaces:**
 - Consumes: enabled sources returned by `EDataServer.SourceRegistry.list_enabled(EDataServer.SOURCE_EXTENSION_CALENDAR)`.
 - Produces: `calendar-agenda probe`, `calendar-agenda query START END`, and `calendar-agenda watch START END`.
 - Produces: one-line JSON snapshots with `ok`, `generatedAt`, `sources`, `events`, and `errors`.
 - Produces event objects with exactly `id`, `sourceId`, `uid`, `summary`, `start`, `end`, `allDay`, `location`, and `joinUrl`.
 - [ ] **Step 1: Write failing pure bridge tests**
 Create `tests/quickshell/calendar_agenda_bridge_test.py` with import-by-path and synthetic policy cases:
 ```python
 import importlib.machinery
 import importlib.util
 import pathlib
 import unittest
 from unittest.mock import Mock
 ROOT = pathlib.Path(__file__).resolve().parents[2]
 HELPER = ROOT / "config/dot/quickshell/scripts/calendar-agenda"
 loader = importlib.machinery.SourceFileLoader("calendar_agenda", str(HELPER))
 spec = importlib.util.spec_from_loader(loader.name, loader)
 calendar_agenda = importlib.util.module_from_spec(spec)
 loader.exec_module(calendar_agenda)
 class CalendarAgendaBridgeTest(unittest.TestCase):
    def test_meeting_url_allowlist(self):
        values = ["Planning: https://meet.google.com/abc-defg-hij"]
        self.assertEqual(calendar_agenda.find_join_url(values), values[0].split()[-1])
        self.assertEqual(calendar_agenda.find_join_url(["https://example.com/private"]), "")
        self.assertEqual(calendar_agenda.find_join_url(["http://zoom.us/j/123"]), "")
    def test_stable_instance_id_includes_recurrence(self):
        self.assertEqual(
            calendar_agenda.stable_event_id("source", "uid", "20260817T133000Z"),
            "source:uid:20260817T133000Z",
        )
    def test_snapshot_sort_order(self):
        events = [
            {"id": "b", "start": 20, "end": 30, "allDay": False},
            {"id": "a", "start": 10, "end": 20, "allDay": True},
        ]
        self.assertEqual([event["id"] for event in calendar_agenda.sort_events(events)], ["a", "b"])
    def test_normalizes_an_all_day_recurrence_instance(self):
        component_id = Mock()
        component_id.get_uid.return_value = "uid"
        component_id.get_rid.return_value = "20260817"
        summary = Mock()
        summary.get_value.return_value = "Synthetic event"
        component = Mock()
        component.get_id.return_value = component_id
        component.get_summary.return_value = summary
        component.get_location.return_value = ""
        component.get_url.return_value = None
        component.get_descriptions.return_value = []
        start = Mock()
        start.as_timet.return_value = 1786924800
        start.is_date.return_value = True
        end = Mock()
        end.as_timet.return_value = 1787011200
        end.is_date.return_value = True
        event = calendar_agenda.normalize_instance(
            {"id": "source", "name": "Synthetic", "color": "#82aaff"},
            component,
            start,
            end,
        )
        self.assertTrue(event["allDay"])
        self.assertEqual(event["id"], "source:uid:20260817")
 if __name__ == "__main__":
    unittest.main()
 ```
 - [ ] **Step 2: Run the unit test and verify RED**
 Run:
 ```bash
 python3 tests/quickshell/calendar_agenda_bridge_test.py
 ```
 Expected: FAIL because `config/dot/quickshell/scripts/calendar-agenda` does not exist.
 - [ ] **Step 3: Implement the bridge's pure contract and CLI boundary**
 Create `config/dot/quickshell/scripts/calendar-agenda` with a Python shebang and no top-level execution on import. Begin with these pure helpers:
 ```python
 MEETING_HOST_SUFFIXES = (
    "meet.google.com",
    "zoom.us",
    "teams.microsoft.com",
    "teams.live.com",
    "webex.com",
    "meet.jit.si",
 )
 def stable_event_id(source_id: str, uid: str, recurrence_id: str) -> str:
    return f"{source_id}:{uid}:{recurrence_id}"
 def sort_events(events: list[dict[str, object]]) -> list[dict[str, object]]:
    return sorted(events, key=lambda event: (not bool(event["allDay"]), int(event["start"]), str(event["id"])))
 def is_allowed_meeting_host(host: str) -> bool:
    normalized = host.lower().rstrip(".")
    return any(normalized == suffix or normalized.endswith("." + suffix) for suffix in MEETING_HOST_SUFFIXES)
 ```
 `find_join_url` must parse URLs with `urllib.parse.urlsplit`, require `https`, lowercase the hostname, and match either an exact allowed host or a subdomain boundary (`host == suffix or host.endswith("." + suffix)`). Strip trailing sentence punctuation before parsing.
 Then implement these exact public boundaries: `find_join_url(values: list[str]) -> str`, `normalize_instance(source_meta, component, instance_start, instance_end) -> dict[str, object]`, `probe() -> dict[str, object]`, `collect_snapshot(start: int, end: int) -> dict[str, object]`, `watch(start: int, end: int) -> int`, and `main(argv: list[str]) -> int`.
 Import GI with exact version requirements:
 ```python
 import gi
 gi.require_version("ECal", "2.0")
 gi.require_version("EDataServer", "1.2")
 from gi.repository import ECal, EDataServer, Gio, GLib
 ```
 For each enabled source:
 ```python
 client = ECal.Client.connect_sync(source, ECal.ClientSourceType.EVENTS, 5, None)
 client.generate_instances_sync(start, end, None, on_instance, None)
 ```
 The callback signature is `(component, instance_start, instance_end, cancellable, callback_data)`. Convert callback times with `as_timet()`. Use `component.get_id().get_uid()` and `.get_rid()`, `component.get_summary().get_value()`, `component.get_location()`, `component.get_url()`, and `component.get_descriptions()`.
 Use source metadata from `source.get_uid()`, `source.get_display_name()`, and the calendar extension's `get_color()`. Fall back to `#82aaff` only when color is absent or invalid. Catch failures per source and append a generic `{sourceId, code: "unavailable"}` error without raw exception text.
 `watch` must emit the initial snapshot, subscribe to EDS source-registry changes and GNOME CalendarServer invalidation signals when available, debounce refreshes by 350 ms, and emit a fallback snapshot every 600 seconds. Failure to subscribe to GNOME CalendarServer must not stop periodic EDS reads.
 Write each snapshot with `json.dumps(snapshot, separators=(",", ":")) + "\n"` and immediately flush stdout. Never print event data to stderr.
 Make the helper executable:
 ```bash
 chmod +x config/dot/quickshell/scripts/calendar-agenda
 ```
 - [ ] **Step 4: Run pure tests and verify GREEN**
 Run:
 ```bash
 python3 tests/quickshell/calendar_agenda_bridge_test.py
 ```
 Expected: four tests PASS.
 - [ ] **Step 5: Add the redacted live helper contract**
 Create `tests/quickshell/calendar-agenda-helper-contract.sh` with:
 ```bash
 #!/usr/bin/env bash
 set -euo pipefail
 fail() { printf 'calendar agenda helper contract: %s\n' "$1" >&2; exit 1; }
 project_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 helper="$project_root/config/dot/quickshell/scripts/calendar-agenda"
 [[ -x "$helper" ]] || fail 'helper is missing or not executable'
 probe="$($helper probe)"
 jq -e '.eds == true and .sourceRegistry == true and .enabledSources > 0' <<<"$probe" >/dev/null \
    || fail 'EDS readiness probe failed'
 range_start="$(date +%s)"
 range_end="$((range_start + 1209600))"
 snapshot="$($helper query "$range_start" "$range_end")"
 jq -e '
  .ok == true and
  (.sources | type == "array" and length > 0) and
  (.events | type == "array") and
  ([.events[] | keys_unsorted - ["id","sourceId","uid","summary","start","end","allDay","location","joinUrl"]] | all(length == 0))
 ' <<<"$snapshot" >/dev/null || fail 'live snapshot shape is invalid'
 printf 'calendar agenda helper contract: PASS (%s sources, %s events; contents redacted)\n' \
  "$(jq '.sources | length' <<<"$snapshot")" "$(jq '.events | length' <<<"$snapshot")"
 ```
 Make it executable and run it. Expected: PASS with counts only; no source names, summaries, locations, or URLs in terminal output.
 - [ ] **Step 6: Commit the bridge**
 ```bash
 git add config/dot/quickshell/scripts/calendar-agenda \
  tests/quickshell/calendar_agenda_bridge_test.py \
  tests/quickshell/calendar-agenda-helper-contract.sh
 git commit -m "Add the EDS calendar bridge"
 ```
 ---
 ### Task 2: Quickshell calendar service and deterministic contract
 **Files:**
 - Create: `config/dot/quickshell/services/CalendarAgenda.qml`
 - Create: `tests/quickshell/calendar-agenda-contract.sh`
 - Modify: `config/dot/quickshell/shell.qml`
 **Interfaces:**
 - Consumes: `calendar-agenda watch START END` newline-delimited snapshots.
 - Produces: singleton properties `phase`, `available`, `sources`, `events`, `selectedDate`, `selectedDateKey`, `selectedEvents`, `nextEvent`, `nextEventForSelectedDate`, `rangeStart`, `rangeEnd`, `capsuleVisible`, and `capsuleText`.
 - Produces: functions `selectDate(date)`, `selectIsoDate(dateString)`, `setVisibleMonth(year, month)`, `eventsForDate(date)`, `markersForDate(date)`, `openEvent(event)`, `openCalendar(date)`, `join(event)`, `refresh()`, `applyFixture(name)`, and `clearFixture()`.
 - Produces IPC target `calendar-agenda` with `fixture`, `reset`, `open`, `select`, `refresh`, and `status`.
 - [ ] **Step 1: Write the failing live service contract**
 Create `tests/quickshell/calendar-agenda-contract.sh` that first asserts the IPC target, loads fixture `daybook`, and validates only synthetic state:
 ```bash
 #!/usr/bin/env bash
 set -euo pipefail
 fail() { printf 'calendar agenda contract: %s\n' "$1" >&2; exit 1; }
 cleanup() {
  qs ipc call calendar-agenda reset >/dev/null 2>&1 || true
  qs ipc call calendar-agenda close >/dev/null 2>&1 || true
 }
 trap cleanup EXIT
 qs ipc show | rg -q '^target calendar-agenda$' || fail 'calendar IPC target is missing'
 qs ipc call calendar-agenda fixture daybook >/dev/null
 status="$(qs ipc call calendar-agenda status)"
 jq -e '.fixture == true and .sourceCount == 3 and .eventCount == 5 and .selectedDate == "2026-08-17"' \
  <<<"$status" >/dev/null || fail 'daybook fixture state is malformed'
 qs ipc call calendar-agenda select 2026-08-18 >/dev/null
 jq -e '.selectedDate == "2026-08-18" and .selectedEventCount == 1' \
  <<<"$(qs ipc call calendar-agenda status)" >/dev/null || fail 'date selection did not update events'
 qs ipc call calendar-agenda reset >/dev/null
 jq -e '.fixture == false' <<<"$(qs ipc call calendar-agenda status)" >/dev/null \
  || fail 'fixture reset did not restore live mode'
 printf 'calendar agenda contract: PASS\n'
 ```
 - [ ] **Step 2: Run the contract and verify RED**
 Run `tests/quickshell/calendar-agenda-contract.sh`.
 Expected: FAIL with `calendar IPC target is missing`.
 - [ ] **Step 3: Implement `CalendarAgenda.qml` stream supervision**
 Create the singleton with `pragma Singleton`, `Quickshell`, `Quickshell.Io`, and `QtQuick` imports. Use a streaming parser, not `StdioCollector`:
 ```qml
 Process {
    id: watchProc
    command: [root.helperPath, "watch", String(root.rangeStart), String(root.rangeEnd)]
    running: !root.fixtureMode && root.rangeStart > 0
    stdout: SplitParser {
        onRead: data => root.consumeSnapshot(data)
    }
    onExited: (code, status) => {
        if (!root.fixtureMode)
            restartTimer.restart();
    }
 }
 ```
 The restart timer uses 2 seconds and does not loop while fixture mode is active. `consumeSnapshot(data)` parses one line, rejects snapshots without `ok === true`, assigns arrays atomically, and sets `phase` to `ready` or `degraded` when `errors.length > 0`.
 Implement date keys in local time with `Qt.formatDate(new Date(epoch * 1000), "yyyy-MM-dd")`. For multi-day/all-day markers, treat `end` as exclusive and include each local date touched before `end - 1`.
 `setVisibleMonth(year, month)` computes a range from seven days before the first day through seven days after the final 42-cell grid day. Only restart the bridge when the requested range falls outside the loaded range.
 `nextEvent` excludes all-day and ended events. `capsuleVisible` is true when `start - now` is at most 900 seconds and at least -300 seconds. `capsuleText` is `Now` after start, otherwise the ceiling minute count plus `m`.
 `applyFixture("daybook")` must install three synthetic sources and five synthetic events spanning August 17–18, 2026. Use clearly synthetic labels (`Fixture standup`, `Fixture planning`, `Fixture focus`, `Fixture dinner`, `Fixture tomorrow`) and no real account or event data.
 - [ ] **Step 4: Add calendar IPC without exposing live content**
 Add to `shell.qml`:
 ```qml
 IpcHandler {
    target: "calendar-agenda"
    function fixture(name: string): void { CalendarAgenda.applyFixture(name); }
    function reset(): void { CalendarAgenda.clearFixture(); }
    function refresh(): void { CalendarAgenda.refresh(); }
    function open(): void { ShellState.openDateMenu("agenda"); }
    function close(): void { ShellState.close(); }
    function select(date: string): void { CalendarAgenda.selectIsoDate(date); }
    function status(): string {
        return JSON.stringify({
            phase: CalendarAgenda.phase,
            fixture: CalendarAgenda.fixtureMode,
            sourceCount: CalendarAgenda.sources.length,
            eventCount: CalendarAgenda.events.length,
            selectedDate: CalendarAgenda.selectedDateKey,
            selectedEventCount: CalendarAgenda.selectedEvents.length,
            capsuleVisible: CalendarAgenda.capsuleVisible,
            capsuleText: CalendarAgenda.capsuleText
        });
    }
 }
 ```
 Do not include titles, source names, locations, identifiers, or URLs in status output.
 - [ ] **Step 5: Run service contracts and verify GREEN**
 Allow Quickshell to hot reload, then run:
 ```bash
 tests/quickshell/calendar-agenda-contract.sh
 tests/quickshell/calendar-agenda-helper-contract.sh
 qs log -n 80 | rg -i 'calendar|error|warn'
 ```
 Expected: both contracts PASS; no calendar QML error or bridge restart loop.
 - [ ] **Step 6: Commit the service**
 ```bash
 git add config/dot/quickshell/services/CalendarAgenda.qml \
  config/dot/quickshell/shell.qml \
  tests/quickshell/calendar-agenda-contract.sh
 git commit -m "Add live calendar state to Quickshell"
 ```
 ---
 ### Task 3: Explicit date-menu routing and interactive month grid
 **Files:**
 - Modify: `config/dot/quickshell/services/ShellState.qml`
 - Modify: `config/dot/quickshell/modules/bar/Clock.qml`
 - Modify: `config/dot/quickshell/shell.qml`
 - Modify: `config/dot/quickshell/modules/datemenu/CalendarGrid.qml`
 - Modify: `tests/quickshell/calendar-agenda-contract.sh`
 **Interfaces:**
 - Consumes: `CalendarAgenda.selectDate(date)` and `CalendarAgenda.markersForDate(date)`.
 - Produces: `ShellState.dateMenuPage`, `ShellState.toggleDateMenu(page)`, and `ShellState.openDateMenu(page)`.
 - Produces from CalendarGrid: signals `dateActivated(date)` and `visibleMonthChanged(year, month)`.
 - [ ] **Step 1: Extend the failing contract with page-routing assertions**
 Append fixture assertions:
 ```bash
 qs ipc call calendar-agenda open >/dev/null
 jq -e '.open == true and .page == "agenda"' <<<"$(qs ipc call calendar-agenda status)" >/dev/null \
  || fail 'calendar open did not route to Agenda'
 qs ipc call notifications open >/dev/null
 jq -e '.open == true and .page == "notifications"' <<<"$(qs ipc call calendar-agenda status)" >/dev/null \
  || fail 'notification open did not route to Notifications'
 ```
 Update the calendar status response to include only `open: ShellState.notificationsOpen` and `page: ShellState.dateMenuPage` in addition to the non-sensitive fields from Task 2.
 - [ ] **Step 2: Run the contract and verify RED**
 Expected: FAIL because `dateMenuPage` and notification `open()` do not exist.
 - [ ] **Step 3: Implement explicit ShellState routing**
 Add:
 ```qml
 property string dateMenuPage: "agenda"
 function openDateMenu(page: string): void {
    root.dateMenuPage = page === "notifications" ? "notifications" : "agenda";
    root.activeOverlay = "notifications";
 }
 function toggleDateMenu(page: string): void {
    const target = page === "notifications" ? "notifications" : "agenda";
    if (root.activeOverlay === "notifications" && root.dateMenuPage === target) {
        root.activeOverlay = "";
        return;
    }
    root.dateMenuPage = target;
    root.activeOverlay = "notifications";
 }
 ```
 Change Clock activation to `ShellState.toggleDateMenu("agenda")`. Change notification IPC `toggle()` to `ShellState.toggleDateMenu("notifications")`, add `open()` using `openDateMenu("notifications")`, and leave `Super+B` routed through that IPC target.
 - [ ] **Step 4: Make CalendarGrid date-aware and event-aware**
 Replace numeric-only cell objects with full local `Date` values and add:
 ```qml
 signal dateActivated(date date)
 signal visibleMonthChanged(int year, int month)
 property date selectedDate: CalendarAgenda.selectedDate
 function activateCell(cell): void {
    if (!cell.current) {
        root.viewYear = cell.date.getFullYear();
        root.viewMonth = cell.date.getMonth();
    }
    root.dateActivated(cell.date);
 }
 ```
 Every cell receives `markers: CalendarAgenda.markersForDate(cell.date).slice(0, 3)`. Render dots in a centered row beneath the day number with each marker's source color. Today remains solid accent; selected non-today uses `Theme.alpha(Theme.accent, 0.18)` plus accent text. Add a hover surface only now that cells are actionable.
 Month changes call `visibleMonthChanged(viewYear, viewMonth)`. Adjacent-month date activation changes month and selection in one click.
 - [ ] **Step 5: Verify routing and grid contracts**
 Run:
 ```bash
 tests/quickshell/calendar-agenda-contract.sh
 rg -q 'markersForDate' config/dot/quickshell/modules/datemenu/CalendarGrid.qml
 rg -q 'dateActivated' config/dot/quickshell/modules/datemenu/CalendarGrid.qml
 ```
 Expected: contract PASS and both interaction hooks present.
 - [ ] **Step 6: Commit routing and grid behavior**
 ```bash
 git add config/dot/quickshell/services/ShellState.qml \
  config/dot/quickshell/modules/bar/Clock.qml \
  config/dot/quickshell/shell.qml \
  config/dot/quickshell/modules/datemenu/CalendarGrid.qml \
  tests/quickshell/calendar-agenda-contract.sh
 git commit -m "Route the interactive Panama date menu"
 ```
 ---
 ### Task 4: Build the approved A · Daybook panel
 **Files:**
 - Create: `config/dot/quickshell/modules/datemenu/AgendaEvent.qml`
 - Create: `config/dot/quickshell/modules/datemenu/AgendaPane.qml`
 - Create: `config/dot/quickshell/modules/datemenu/NotificationSummary.qml`
 - Modify: `config/dot/quickshell/modules/datemenu/DateMenuPanel.qml`
 - Modify: `config/dot/quickshell/modules/datemenu/DateMenu.qml`
 - Modify: `config/dot/quickshell/modules/datemenu/MediaCard.qml`
 - Modify: `config/dot/quickshell/modules/datemenu/qmldir`
 - Modify: `tests/quickshell/calendar-agenda-contract.sh`
 **Interfaces:**
 - Consumes: `CalendarAgenda.selectedEvents`, `nextEventForSelectedDate`, `phase`, and action functions.
 - Consumes: `ShellState.dateMenuPage`, `Notifs.hasNotifications`, and existing `NotificationList`.
 - Produces: a 760-pixel two-column date menu with left width 310 and independently bounded right content.
 - [ ] **Step 1: Add failing structural and live-surface assertions**
 Extend the contract to assert the loaded layer and approved components:
 ```bash
 hyprctl layers | rg -q 'namespace: qs-popover-datemenu' || fail 'Daybook layer did not map'
 rg -q 'implicitWidth: 760' config/dot/quickshell/modules/datemenu/DateMenu.qml \
  || fail 'Daybook is not the approved width'
 for component in AgendaPane AgendaEvent NotificationSummary; do
  rg -q "${component} 1.0 ${component}.qml" config/dot/quickshell/modules/datemenu/qmldir \
    || fail "$component is not registered"
 done
 ```
 Run the contract and expect failure on width or missing components.
 - [ ] **Step 2: Implement focused event and summary components**
 `AgendaEvent.qml` accepts `property var event`, `property bool past`, and signals `activated` and `joinRequested`. It renders a 48-pixel tabular time column, 3-pixel source-color rail, elided summary, source/location metadata, and optional Join pill. All-day rows replace time with `All day`.
 `NotificationSummary.qml` is visible only when `Notifs.hasNotifications`; it displays history count and emits `activated`. It never marks notifications read by itself.
 `AgendaPane.qml` renders exactly one of:
 - loading copy (`Loading calendars…`);
 - unavailable copy plus `Open Calendar`;
 - empty-day copy plus `Open Calendar`;
 - Up Next plus the selected day's ordered list.
 The Up Next card is omitted for selected dates other than today and when no future timed event exists. Use `ScrollColumn` with a maximum content height derived from the panel's available height. Event clicks call `CalendarAgenda.openEvent(event)`; Join calls `CalendarAgenda.join(event)`.
 - [ ] **Step 3: Recompose DateMenuPanel as Daybook**
 Keep the existing header styling and Prism container, but replace the single `Column` with this concrete structure:
 ```qml
 Column {
    id: frame
    spacing: 0
    Item {
        id: header
        width: parent.width
        height: 42
    }
    Rectangle { width: parent.width; height: 1; color: Theme.alpha(Theme.fg, 0.1) }
    Row {
        width: parent.width
        Item {
            id: leftColumn
            width: 310
            height: rightColumn.height
        }
        Rectangle {
            width: 1
            height: rightColumn.height
            color: Theme.alpha(Theme.fg, 0.1)
        }
        Item {
            id: rightColumn
            width: frame.width - 311
            height: Math.max(438, activeContent.implicitHeight)
            property Item activeContent: ShellState.dateMenuPage === "agenda" ? agendaPane : notificationList
            AgendaPane { visible: ShellState.dateMenuPage === "agenda" }
            NotificationList { visible: ShellState.dateMenuPage === "notifications" }
        }
    }
 }
 ```
 Populate `leftColumn` inline in `DateMenuPanel.qml` with a `Column` containing CalendarGrid, conditional MediaCard, and WeatherCard. Populate `header` with the existing date text and pill controls. Bind date activation to `CalendarAgenda.selectDate(date)` and month changes to `CalendarAgenda.setVisibleMonth(year, month)`.
 When Agenda's notification summary activates, set `ShellState.dateMenuPage = "notifications"` and call `Notifs.markAllRead()`. Notification view header exposes `Back to agenda`, DND, and Clear All. Returning to agenda retains selected date and month.
 Resize MediaCard typography/controls responsively for the 310-pixel column; do not duplicate its playback logic.
 - [ ] **Step 4: Update DateMenu lifecycle and bounds**
 Set `DateMenu.implicitWidth: 760`. Bound height to the active screen's available geometry, with the panel content choosing a maximum right-column scroll height instead of overflowing the monitor.
 On opening:
 ```qml
 CalendarAgenda.refresh();
 if (ShellState.dateMenuPage === "notifications")
    Notifs.markAllRead();
 panel.prepare(ShellState.dateMenuPage);
 ```
 Add a connection that marks notifications read when an already-open panel switches into Notifications. Opening from the clock must not mark them read.
 - [ ] **Step 5: Verify fixture visuals on the real layer surface**
 Run:
 ```bash
 qs ipc call calendar-agenda fixture daybook
 qs ipc call calendar-agenda open
 tests/quickshell/calendar-agenda-contract.sh
 ```
 Capture a temporary full-screen screenshot with `grim`, inspect the Daybook at original detail, and verify:
 - no clipped text at 1.5 scale;
 - month and agenda are simultaneously visible;
 - right content has no unexplained empty glass;
 - three source colors remain restrained;
 - notification summary is quieter than Up Next;
 - no continuously repainting animation.
 Close the panel and reset fixture mode after inspection. Do not add screenshots to git.
 - [ ] **Step 6: Commit the Daybook**
 ```bash
 git add config/dot/quickshell/modules/datemenu \
  tests/quickshell/calendar-agenda-contract.sh
 git commit -m "Build the Prism calendar Daybook"
 ```
 ---
 ### Task 5: Quiet upcoming-event capsule
 **Files:**
 - Create: `config/dot/quickshell/modules/bar/CalendarIndicator.qml`
 - Modify: `config/dot/quickshell/modules/bar/Bar.qml`
 - Modify: `config/dot/quickshell/services/CalendarAgenda.qml`
 - Modify: `tests/quickshell/calendar-agenda-contract.sh`
 **Interfaces:**
 - Consumes: `CalendarAgenda.capsuleVisible`, `capsuleText`, and `nextEvent`.
 - Produces: a right-side Pill showing calendar glyph plus `12m` or `Now`.
 - Produces: `applyFixture("upcoming")` and `applyFixture("outside-window")` for boundary tests.
 - [ ] **Step 1: Add failing capsule boundary assertions**
 Append:
 ```bash
 qs ipc call calendar-agenda fixture upcoming >/dev/null
 jq -e '.capsuleVisible == true and .capsuleText == "12m"' \
  <<<"$(qs ipc call calendar-agenda status)" >/dev/null || fail 'upcoming capsule window is wrong'
 qs ipc call calendar-agenda fixture outside-window >/dev/null
 jq -e '.capsuleVisible == false' <<<"$(qs ipc call calendar-agenda status)" >/dev/null \
  || fail 'capsule appears outside the quiet window'
 ```
 Run and expect RED because those fixtures do not exist.
 - [ ] **Step 2: Implement deterministic timing fixtures and capsule state**
 Add `fixtureNow` to CalendarAgenda. Production uses `Date.now() / 1000`; fixture modes use their explicit clock. `upcoming` creates one timed event exactly 12 minutes ahead. `outside-window` creates one 20 minutes ahead plus an all-day event. Verify all-day never wins `nextEvent`.
 Use a one-minute `Timer` only while events are loaded to update relative time. Midnight refresh remains separate. There is no sub-minute repaint.
 - [ ] **Step 3: Build CalendarIndicator and mount it in Bar**
 Use `Pill` with `visible: CalendarAgenda.capsuleVisible`, horizontal padding 8, a calendar Nerd Font glyph, and tabular relative text. `onActivated` opens Agenda. Import `QtQuick.Controls` and use `ToolTip.visible: root.hovered && root.visible` with the next event's title; the title must not otherwise appear in the bar.
 Mount the indicator at the beginning of Bar's right row, before ActivityIndicator, so it does not shift the centered clock.
 Use a single 120 ms opacity/width entrance tied to visibility. No looping animation.
 - [ ] **Step 4: Run capsule and full shell contracts**
 ```bash
 tests/quickshell/calendar-agenda-contract.sh
 for test in tests/quickshell/*.sh; do "$test"; done
 ```
 Expected: calendar fixture boundaries PASS and every existing Quickshell contract remains green.
 - [ ] **Step 5: Commit the capsule**
 ```bash
 git add config/dot/quickshell/modules/bar/CalendarIndicator.qml \
  config/dot/quickshell/modules/bar/Bar.qml \
  config/dot/quickshell/services/CalendarAgenda.qml \
  tests/quickshell/calendar-agenda-contract.sh
 git commit -m "Add the quiet calendar capsule"
 ```
 ---
 ### Task 6: Documentation, live EDS verification, and delivery
 **Files:**
 - Modify: `config/dot/hypr/DESKTOP-PARITY.md`
 - Modify: `config/dot/hypr/README.md`
 - Modify: `setup/packages/hyprland-packages`
 - Modify: `docs/superpowers/plans/2026-08-17-calendar-agenda.md`
 **Interfaces:**
 - Consumes: completed helper, service, Daybook, capsule, and test suite.
 - Produces: documented live behavior and a pushed sequence of reviewed commits.
 - [ ] **Step 1: Update parity and operator documentation**
 In DESKTOP-PARITY:
 - change Calendar Agenda to Live with EDS/Google/iCloud/Nextcloud wording;
 - remove Wi-Fi QR from remaining work;
 - remove `qrencode` from the privileged package command;
 - keep KDE Connect, Home Assistant, printer UI, and RustDesk lock-screen validation as future work.
 In Hyprland README document:
 - clock opens Agenda;
 - `Super+B` opens Notifications inside the same Daybook;
 - event clicks hand off to GNOME Calendar;
 - account management remains in GNOME Calendar/Online Accounts;
 - the bar capsule's 15-minute to +5-minute window.
 Remove `qrencode` from `setup/packages/hyprland-packages` only if `rg -n qrencode .` confirms no remaining runtime consumer.
 - [ ] **Step 2: Run static verification**
 ```bash
 bash -n tests/quickshell/*.sh config/dot/quickshell/scripts/screen-intelligence
 python3 -c 'compile(open("config/dot/quickshell/scripts/calendar-agenda", encoding="utf-8").read(), "calendar-agenda", "exec")'
 python3 tests/quickshell/calendar_agenda_bridge_test.py
 desktop-file-validate config/local/share/applications/*.desktop
 Hyprland --verify-config
 git diff --check
 ```
 Expected: every command exits 0 and Hyprland reports `config ok`.
 - [ ] **Step 3: Run every Quickshell contract**
 ```bash
 for test in tests/quickshell/*.sh; do
  "$test"
 done
 ```
 Expected: all prior contracts plus both calendar contracts report PASS.
 - [ ] **Step 4: Verify the live calendar without leaking content**
 Reset fixture mode and refresh:
 ```bash
 qs ipc call calendar-agenda reset
 qs ipc call calendar-agenda refresh
 ```
 Poll status until `phase` is `ready` or `degraded`. Assert `sourceCount > 0`; report only source/event counts. Open Agenda from the clock path, inspect the real panel locally, test one date containing events, and confirm event clicks launch GNOME Calendar. Do not capture or print a screenshot containing real event details.
 Test a Join action only when a recognized URL is already present; opening that URL is an external navigation and requires an explicit click in the local UI. Do not fabricate or modify an event for testing.
 - [ ] **Step 5: Review logs and the complete diff**
 ```bash
 qs log -n 250 | rg -i 'calendar|qml|error|warn'
 git status --short
 git diff --stat 5248883..HEAD
 git diff --check 5248883..HEAD
 ```
 Expected: no calendar QML errors, no bridge restart loop, no secrets, and only calendar/planned-roadmap changes beyond the already-approved desktop snapshot.
 - [ ] **Step 6: Mark this plan complete and commit documentation**
 Mark completed checkboxes only after their commands actually passed, then:
 ```bash
 git add config/dot/hypr/DESKTOP-PARITY.md \
  config/dot/hypr/README.md \
  setup/packages/hyprland-packages \
  docs/superpowers/plans/2026-08-17-calendar-agenda.md
 git commit -m "Document the Panama calendar agenda"
 ```
 - [ ] **Step 7: Push without rewriting history**
 ```bash
 git status --short
 git push origin main
 ```
 Expected: clean worktree and `main` advances on `origin`. If Gitea still returns HTTP 502, preserve all commits locally, report the remote outage, and do not force-push or change remote history.