Task: Add compass timeline command to list documents changed in a period
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 fromgit log origin/main -- doc/agilewithin the window — file adds become created events; modifications are diffed for the Status table's State row (old vs new viagit 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]: globdoc/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).