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

 1# Timestamps 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:** Org's date prompt, timestamp insertion (C-c ., C-c !), scheduling and deadlines (C-c C-s, C-c C-d, and removal), timestamp shifting (S-arrows on a timestamp), and repeating entries completed with DONE, all byte- and caret-exact against Emacs with a frozen clock.
 6
 7**Architecture:** `ReadDate` ports `org-read-date-analyze` with `parse-time-string`'s tokenizer and rules, `org-read-date-get-relative` and `org-small-year-to-year`. `Timestamps.swift` ports `org-at-timestamp-p` (point categories), `org-insert-timestamp`, `org-timestamp-change` with `org-modify-ts-extra`, `org-toggle-timestamp-type`, `org-add-planning-info`. `TimestampCommands.swift` holds `org-timestamp`, `org--deadline-or-schedule` and the shift commands. `Repeat.swift` ports `org-auto-repeat-maybe` and the state note (`org-store-log-note`, `org-log-beginning`); TODO cycling runs it when an entry becomes done. Commands read `now` and `calendar` from `EditContext`. A `timestamp` key context lets S-arrows shift timestamps and fall back to priority and TODO on headings.
 8
 9**Tech Stack:** Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 oracle.
10
11**Spec:** `docs/design.md`, "Commands and keymaps" (revisions, time and prompts).
12
13## Global Constraints
14
15- Org defaults: `org-read-date-prefer-future` t, `org-time-stamp-rounding-minutes` (0 5), `org-log-repeat` `time`, `org-log-into-drawer` nil, `org-log-states-order-reversed` t, `org-todo-repeat-to-state` nil, `org-log-reschedule`/`org-log-redeadline` nil.
16- The oracle freezes `current-time`, `decode-time`, `format-time-string`, `org-today` and `time-less-p`, runs with `TZ=UTC`, stubs `read-string` with the answer, and stores the deferred log note as the post-command hook would.
17
18## Defaults chosen (user may change)
19
20- Mac preset: ⌃⌘. timestamp, ⌃⌥⌘. inactive, ⌃⌘S schedule, ⌃⌘D deadline, ⌃⌘ arrows shift a timestamp under the caret.
21- Not yet: date ranges in the prompt and S-arrows on ranges, the calendar picker, CLOCK line updates, deadline warning edits (C-u C-u).
22
23---
24
25### Task 1: Date prompt
26
27- [ ] Port; oracle over 52 inputs (relative, weekdays, ISO weeks, US and European dates, am/pm, `HHhMM`, ranges, durations).
28- [ ] Commit "Port the date prompt".
29
30### Task 2: Timestamps, planning, repeats
31
32- [ ] Port; oracle over 7 texts × every caret × 9 commands × 6 answers, and 10 repeating entries.
33- [ ] Commit "Port timestamp and planning commands".
34
35### Task 3: Keys
36
37- [ ] Bind both presets; `timestamp` context.