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

 1# Clocking 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:** Clock in, out, cancel and go to, written as Emacs writes them, and the time report your Doom config makes (`SPC z t`), as a window.
 6
 7**Architecture:** `OrgCore/Commands/Clock.swift` ports `org-clock-find-position` (an existing LOGBOOK drawer, newest first; a new drawer after the metadata; stray `CLOCK:` lines moved into one), the `CLOCK: [start]` line of `org-clock-in`, `org-clock-out`'s `--[end] =>  H:MM`, `org-clock-cancel`, and empty-drawer removal. `ClockModel` keeps the running clock (file, start stamp, heading) in `clock.json` and runs the commands through the open buffer or the save path, clocking out a running clock before clocking in. `ClockReport` reads finished clocks as `tr/parse-org-clock-entries` does and writes `tr/generate-report`'s table (date × heading, ISO-week totals). The main toolbar and a menu bar item show the running clock; the Clock Report window chooses files and dates and copies or saves the table.
 8
 9**Tech Stack:** Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 oracle; your config.el for the report oracle.
10
11**Spec:** `docs/design.md`, "Phase 6".
12
13## Global Constraints
14
15- Clock oracle: clock in, then out or cancel, on nine entry shapes, with the clock frozen.
16- Report oracle: your own `tr/` functions, loaded from `~/.config/doom/config.el`, on a sample and on work-notes/time.org, four date ranges.
17- No clock rounding, resume, idle detection or `clocktable` blocks.
18
19---
20
21- [x] Clock commands; oracle.
22- [x] `ClockModel`; `ClockReport`; tests.
23- [x] Toolbar, menu bar item, Clock Report window, `C-c C-x C-i/C-o/C-q/C-j`.
24- [x] Commit "Clocking".