feat: file activity as timestamped events and add worklog refresh

[Bhekani Khumalo (bhekanik)]

Activity is now recorded as timestamped events in a cache-side ledger, sources are plugins behind one interface, and worklog refresh picks up what has changed since the last run and rewrites only the weeks it belongs to.

The rule this serves

We keep the state of things as they were when we first fetched them. If there is a change later, we record it on the date the change happened: a new comment goes on the week of the comment's timestamp; a description change goes on the week it happened, or if we cannot know that, the week we spotted it. We can add things we missed in history, but we do not rewrite history.

Before this, a week was fetched as "how these items look right now". Regenerating an August week in September narrated August from September's state — a ticket closed last week read as finished work in a week where it was still in progress.

Ledger layout

$XDG_CACHE_HOME/worklog/ledger/     (~/.cache/worklog/ledger by default)
├── meta.json                  # version, and per source: fetchedAt, windows[], state{}
├── events/<weekId>.json       # append-only, sorted by (at, key)
└── snapshots/<source>.json    # id -> { id, firstSeenAt, payload }, written once per item

Why this shape:

• Sharded by week, not by source. Reading or writing one week touches one file. refresh writes only the weeks whose event set changed, which is the property the whole command rests on.
• Snapshots separate from events. A snapshot is written once and never again — it is what a week is entitled to show about an item. Everything after that is an event with its own date. That split is the history rule made structural rather than remembered.
• A week is its events' timestamps. A comment written in September lands in September's file even though the ticket is from August. No source decides week membership.
• In the cache dir, not the vault. Refetchable, large, and the vault is synced to iCloud and indexed by Obsidian. Deleting it costs a refetch.
• JSON, parsed on read. A person can read and therefore edit these files, and a machine can lose power mid-write. Every row goes through zod on the way in; a row that no longer parses is dropped and the rest of the ledger still opens.
• Idempotent recording. Event identity is the system's own id when there is one (source|id), else source|kind|itemId|at. Re-fetching a week matches instead of duplicating, files are only written when their contents differ, and a second run is byte-identical in both the vault and the cache — asserted in commands/__tests__/refresh.test.ts.

The frozen Source interface

lib/sdk/sources.ts, matching what M3 (#54) built against, extended only with optional fields:

export interface SourceSnapshot { id: string; firstSeenAt: string; payload: unknown; }

export interface SourceEvent {
  source: string; kind: string; itemId: string; at: string; payload: unknown; id?: string;
}

export interface SourceBatch {
  snapshots: SourceSnapshot[]; events: SourceEvent[]; warnings: string[];
}

export interface SourceState {
  get(key: string): string | undefined;
  set(key: string, value: string): void;
}

export interface SourceContext {
  config: WorklogConfig;
  log?: Logger;
  headers?: FetchHeaders;
  identity?: { atlassianAccountId: string; githubUsername: string };
  onWarning?: (message: string) => void;
  state?: SourceState;
}

export type SourceAvailability = { ok: true } | { ok: false; reason: string };
export interface SourceWindow { start: Date; end: Date; }

export interface Source {
  name: string;
  isAvailable(ctx: SourceContext): Promise<SourceAvailability>;
  fetchWindow(window: SourceWindow, ctx: SourceContext): Promise<SourceBatch>;
  fetchSince(since: Date, itemIds: string[], ctx: SourceContext): Promise<SourceBatch>;
}

Two questions and nothing else: what happened in this window (the expensive first look) and what has happened since this moment (the cheap one every later run asks).

worklog refresh

worklog refresh                    # every week since the current team started
worklog refresh --since 2026-01-01
worklog refresh --week 2026-W07
worklog refresh --source jira

Asks each source the delta question, files each answer in the week it happened, and rewrites only the weeks whose event set changed. A run that finds nothing makes no AI call and writes no file. A week that does need rewriting has its existing brag book sent back with only the events this run added, and the instruction is to add to the entry rather than replace it; the vault writers from #47 make re-applying what was already applied a no-op.

The closing table shows what each source contributed per week and how long each source took — Slack's Glean path takes minutes where the HTTP sources take seconds, and a user waiting deserves to know which.

Dating what has no date

A description edit has no timestamp of its own. It is dated at the moment it was found and its payload marked spotted: true; the work log then carries a ## Dating section saying so plainly, so the model is never quietly told a change happened on a day it did not.

Prompt

prompts/weekly-brag-prompt.md no longer tells the model to fetch the current status of a ticket and describe reality at generation time. It now says the week is a closed record, and generation_context states whether it is the current week or a past one.

Also

• The weekly command generates from the ledger too, so a week written today and the same week amended next month are built the same way from the same events.
• getWeekEnd returns Sunday at 00:00 — the start of the last day. Window ends are pushed to the last instant of Sunday in one place (weekWindow) rather than in each source.
• allSources() is one list, read by both commands.

Tests

652 passing, 23 files. New: lib/sdk/__tests__/ledger.test.ts (28), lib/sdk/__tests__/source-adapters.test.ts (30), commands/__tests__/refresh.test.ts (6), plus 8 in markdown.test.ts. anti-slop-check --base origin/main is down to 3 findings, all no-unknown-parameters on the three functions whose job is to be the parsing boundary (keepParsable, writeJsonAtomic, renderable).