docs/plans/2026-10-05-agenda.md

 1# Agenda Implementation Plan
 2
 3> **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.
 4
 5**Goal:** The day/week agenda (`org-agenda-list`): which entries appear on which day, with org's leaders, times, categories, tags, sort order and time grid, checked line by line against Emacs; an agenda window in the app that jumps to entries.
 6
 7**Architecture:** `OrgCore/Agenda` ports the collectors of org-agenda.el: `org-agenda-get-deadlines`, `-get-scheduled`, `-get-timestamps`, `-get-blocks`, `org-agenda-format-item` with the default prefix ` %i %-12:c%?-12t% s`, `org-agenda-highlight-todo`, `org-entries-lessp` with `(habit-down time-up urgency-down category-keep)`, `org-agenda-add-time-grid-maybe`, and the day headers of `org-agenda-format-date-aligned`. Repeaters go through `org-closest-date`. An `AgendaSource` is built per file from its text and tree (headings, planning, timestamps with positions, categories, skip ranges); the app caches sources by file hash and replaces them with the open session's text, which is the overlay the design asks of the index. The index rows don't carry positions or raw timestamp text, so the agenda reads sources rather than SQL.
 8
 9**Tech Stack:** Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 oracle.
10
11**Spec:** `docs/design.md`, "Phase 3", "Workspace, storage and index".
12
13## Global Constraints
14
15- Oracle: `org-agenda-list` over temp files with the clock frozen; each line compared as text (tags realigned to one space) plus `type`, `org-category`, `time-of-day`, `extra`, `urgency` and the heading marker.
16- Org defaults otherwise: 14 warning days, deadlines and scheduled items shown when done, future repeats shown, overdue items only on today, no habits (phase 6), no diary or diary sexps.
17
18## Defaults chosen (user may change)
19
20- Doom's view: 10 days starting 3 days before today.
21- Agenda files: the top-level `.org` files of each workspace root, as Doom's `org-agenda-files` is the org directory.
22
23---
24
25### Task 1: Engine
26
27- [x] Absolute days, ISO weeks; `org-closest-date`; `org-get-wdays`.
28- [x] `AgendaSource` from text; collectors; formatting; sorting; time grid; day headers.
29- [x] Oracle over synthetic files (repeaters of every unit, warnings, delays, ranges, times in headings, priorities, categories, inherited tags, archived and commented trees, src blocks, done items) for several "today"s, and over the three corpora for a 10-day span.
30- [x] Commit "Agenda engine".
31
32### Task 2: App
33
34- [x] Agenda window (⌘⇧A, palette): day headers, items with category, time, leader, TODO, title, tags; previous/next span, today; click or RET jumps to the entry; refreshes on saves and open-document edits.
35- [x] Settings: span, start offset, agenda folders.
36- [x] Commit "Agenda view".