Task: Add compass timeline command to list documents changed in a period

Table of Contents

This page documents a task in the Agile timeline: bucketed summaries of recent activity story. It captures the goal, current status, acceptance, and any notes or results.

Goal

Add compass timeline with the two behaviours the story defines: generate (the changed-document event list for a window, from consistent data only) and show (render the last N snapshot buckets from the sprint's timeline/ folder).

Status

Field Value
State DONE
Parent story Agile timeline: bucketed summaries of recent activity
Now Nothing.
Waiting on Nothing.
Next Nothing.
Last touched 2026-06-07

Acceptance

Two distinct behaviours:

  • Generate (input for the LLM summary): list stories/tasks/captures changed in a window with what changed and id links — the raw material the snapshot skill buckets and writes to the sprint's timeline/ folder. Window is a parameter (e.g. –since/–from/–to); "now" is a convenience default, not a hard-coded 20 minutes.
  • Generate reads consistent data only: git history of doc/agile on origin/main plus the gh PR record — never per-worktree journals — so a fresh checkout of main produces the same output as any other environment.
  • View (read the timeline): show the last N buckets sourced purely from the sprint's timeline/ folder — no change detection, just render what the snapshots already say (e.g. compass timeline show [-n N]).

Plan

New compass_timeline.py module following the compass_review.py run(argv, project_root) pattern, early-dispatched from compass.py.

  • timeline generate [--since 20m | --from A --to B] [-f pretty|json]: events mined from git log origin/main -- doc/agile within the window — file adds become created events; modifications are diffed for the Status table's State row (old vs new via git show sha^:path / sha:path) to become state or updated events. Each event carries time, action, doc type, title, :ID:, path, state transition, the #+environment: stamp when present (forward-compatible with the stamping task), and commit sha. PR events (opened/merged in window) joined from gh; degrade with a warning when gh is unavailable.
  • timeline now — alias for generate with the default window.
  • timeline show [-n N]: glob doc/agile/versions/*/sprint_*/timeline/*.org, sort by the ISO-range filename, print the newest N.
  • No journal input anywhere, per the coherence investigation: identical output from any fresh checkout.

Notes

PRs

PR Title
#1175 [compass] Add timeline command: generate and show

Review

Comment summary File Decision Notes
       

Result

compass timeline shipped (PR #1175) with generate (consistent-substrate events: doc created/state/updated from origin/main git history + environment stamps when present + gh PR opened/merged; –since/–from/–to windows; pretty and json), the now alias, and show -n over the sprint timeline/ folders. Scan-ability guards built in: bulk sweeps collapse to a single line and repeated updates of one document coalesce with a count. Verified against real history (6h window: state transitions, creations, two 297-doc sweeps collapsed, PR stream) and from-fresh-checkout semantics hold by construction (origin/main only).

Emacs 29.1 (Org mode 9.6.6)