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

Clocking 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: 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.

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.

Tech Stack: Swift 6.2 tools, Swift Testing, Emacs 31.1 / Org 9.8.7 oracle; your config.el for the report oracle.

Spec: docs/design.md, "Phase 6".

Global Constraints

• Clock oracle: clock in, then out or cancel, on nine entry shapes, with the clock frozen.
• Report oracle: your own tr/ functions, loaded from ~/.config/doom/config.el, on a sample and on work-notes/time.org, four date ranges.
• No clock rounding, resume, idle detection or clocktable blocks.

• Clock commands; oracle.
• ClockModel; ClockReport; tests.
• Toolbar, menu bar item, Clock Report window, C-c C-x C-i/C-o/C-q/C-j.
• Commit "Clocking".