feat: add Slack as a source via Glean, skipped when unavailable

[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).

---

Review round 1 (all nine findings addressed)

Every CLI flag was verified against the installed claude --help (2.1.246). The relevant
help lines:

--tools <tools...>        Specify the list of available tools from the built-in set. Use ""
                          to disable all tools, "default" to use all tools, or specify tool
                          names (e.g. "Bash,Edit,Read").
--strict-mcp-config       Only use MCP servers from --mcp-config, ignoring all other MCP
                          configurations
--mcp-config <configs...> Load MCP servers from JSON files or strings (space-separated)
--json-schema <schema>    JSON Schema for structured output validation.
--output-format <format>  Output format (only works with --print): "text" (default), "json"
                          (single result), or "stream-json" (realtime streaming)
--permission-mode <mode>  (choices: "acceptEdits", "auto", "bypassPermissions", "manual",
                          "dontAsk", "plan")

1. Tool restriction. Confirmed live that --allowedTools alone leaves the child with Bash,
   Read, WebFetch and every configured MCP server (Gmail, Playwright and others were all
   reachable). The invocation is now --tools "" plus --strict-mcp-config --mcp-config <glean only> plus --allowedTools for the three Glean tools. Verified live: the child's tool list
   drops to the eight mcp__glean_default__* tools and nothing else. The Glean server is read out
   of claude mcp get at runtime, so no company-specific URL is hardcoded, and the stored OAuth
   still works through the inline config. When the server is not http/sse it cannot be isolated,
   so the source reports itself unavailable rather than falling back to a wider child. The argv is
   asserted in tests.
2. Author and visibility. author and channelType are required schema fields, the prompt
   tells the model to fill them from Glean metadata, and anything not written by
   profile.fullName/displayName or not in a public channel is dropped locally with a count in
   a warning. Identity comparison is on letters and digits only, so @first.last matches
   First Last. docs/setup.md says plainly this is best-effort on top of Glean's
   permission-aware index, not a guarantee.
3. Opt-out and budget. --no-slack added (commander boolean, skips the availability probe
   too). One 240s deadline now covers the attempt and its retry; the retry gets only the time
   left and is skipped below 60s. --verbose prints the per-week Slack seconds.
4. Permalinks. Must be https on slack.com or a subdomain. Link destinations are escaped
   before rendering.
5. Status gate. The Status: line is parsed into a word list that must be exactly
   ["connected"]. Not Connected and Needs authentication are both tested and both rejected.
6. README. The data-handling paragraph now says what reaches Claude Code and Glean when
   Slack is on, and how to turn it off.
7. Structured output. --json-schema (derived from the zod schema, one source of truth) plus
   --output-format json; structured_output is read directly. The fallback scans for a
   balanced JSON object with a depth counter, so Found {one result}: {"messages":[]} parses —
   that exact case is a test.
8. Timers. Slack has its own duration in WeekTiming, in the stats file, and as a
   Slack via Glean line in the summary breakdown. The API fetch timer stops before Slack.
9. Flaky test. The byte-equality test freezes the clock with vi.setSystemTime.

Also from this round: the brag prompt says quoted message text is data and never instruction, and
the fetch prompt says the same to the child.

Live re-verification after the changes

The first run with the hardened argv failed in one second:
--json-schema is not a valid JSON Schema: no schema with key or ref "https://json-schema.org/draft/2020-12/schema". The CLI validates the schema and rejects the
$schema dialect ref zod emits, so it is stripped; there is a regression test. The next run went
through end to end: 169s, three messages kept, 0 not public, 0 not yours, 0 malformed, 0 outside the range, zero warnings, author and channelType correctly filled from Glean metadata.

Checks

bunx tsc --noEmit clean; bun run lint clean; bun run test 680 passing across 22 files.
Thirteen guards mutation-checked, each turning tests red when removed: the channelType check, the
author check, the permalink host check, the https check, the status word-list check, the shared
deadline, the retry's remaining-time budget, --strict-mcp-config, --tools "", the $schema
strip, the balanced scan, per-item parsing, and link escaping.

One deliberate collision

anti-slop-check flags the vi.mock added to commands/__tests__/worklog.test.ts. That file
already mocks the AI, the network, the vault writer and clack the same way (six pre-existing
findings). The stub is needed because runWorklog would otherwise spawn the Claude Code CLI from
a test. Left as-is to match the file rather than making it the odd one out.

---

Review round 2

1. Hooks and settings in the child — fixed, and measured rather than assumed.
claude --help (2.1.246):

--setting-sources <sources>   Comma-separated list of setting sources to load
                              (user, project, local).

Measured it rather than trusting the description. A project .claude/settings.json with a
UserPromptSubmit hook, child run with that directory as cwd:

--- WITHOUT --setting-sources ---
HOOK FIRED
--- WITH --setting-sources "" ---
exit=0
hook did not fire
stdout: OK

So the finding was real, and --setting-sources "" closes it without breaking auth. Three changes
went in together:

• --setting-sources "" in the argv, asserted in a test.
• The child runs in a directory made by mkdtemp per call and removed afterwards, so there is no
  project CLAUDE.md, settings or memory above it to discover. A test asserts the cwd is under
  the system temp dir, is empty, is not process.cwd(), is shared by the status probe and the
  fetch, and is gone afterwards.
• The environment is now an allowlist (HOME, PATH, shell/locale basics, ANTHROPIC_*, proxy
  and CA variables) instead of a copy of this process's with three keys deleted. The three Claude
  Code nesting markers fall out of it for free.

2. MCP endpoint validation — fixed. resolveGleanServer now requires Scope: to be the
user's own config, because a local or project-scoped entry can shadow the real server and a
checked-out repository is somewhere one could come from, and requires the URL: to parse as
https:. The hostname is deliberately not checked against a list: every company has its own
Glean host and this is a public repo. Three tests: plain http rejected, non-user scope rejected,
https user-scope accepted (plus a non-URL rejected).

3. Handle normalisation — documented limit. The check already compared whole normalised
strings rather than prefixes; that is now pinned by a test (Test Userson and test are both
rejected against Test User/testuser). docs/setup.md names the remaining limit: it compares
names, not Slack member ids, so a colleague whose name normalises to the same string would pass,
and Glean does not reliably expose member ids to compare instead.

Live re-verification

Availability ok, one week in 197s, three messages kept, 0 not public, 0 not yours, 0 malformed, 0 outside the range, zero warnings. Payload keys, channelType: "public", and https *.slack.com
permalinks all as expected. The tightened environment and settings isolation do not break OAuth.

One more fix, found the hard way

While mutation-testing the new cwd handling, a mutation pointed the directory factory at
process.cwd(). The cleanup is an rm -rf, so the test run deleted this worktree. Nothing was
lost (everything was committed) but the lesson stands: that cleanup was safe only because the
factory happened to always be mkdtemp. It now refuses any path that is not directly under the
system temp directory with this module's prefix, and the factory is injectable so the refusal is
tested against throwaway directories.

Checks

bunx tsc --noEmit clean; bun run lint clean; bun run test 688 passing across 22 files.
Eighteen guards now mutation-checked in total; the five new ones (temp directory removed, the
deletion guard itself, the scope check, the https check, whole-name matching) each turn tests red
when removed.

anti-slop-check still reports one finding, the same vi.mock in
commands/__tests__/worklog.test.ts reported in round 1, kept to match that file's six
pre-existing mocks.

---

Review round 3

1. Cleanup can delete a directory it did not create — fixed by removing the seam.
The injectable directory factory is gone from production code, so there is no longer any way for
a caller to hand this an arbitrary path. withEmptyCwd resolves the temp root with realpath
before creating anything, uses exactly what mkdtemp returned as the child cwd, records that
directory's dev/ino with lstat at creation, and checks them again before removing it.
A changed identity, or a path that is no longer a directory, means: warn, leave it, carry on.
Tests redirect TMPDIR at a sandbox instead of injecting, and cover a same-prefix decoy
(a sibling worklog-slack-* directory that must survive) and a symlink retarget (the directory
is swapped for a symlink pointing at a directory that must survive).

2. Managed policy hooks — documentation corrected. No auth redesign. Every absolute claim
about hooks is gone from README.md, docs/setup.md and the source comment. They now say that
user, project and local settings and hooks are not loaded, that organisation-managed policy
settings still apply including any hooks they define, that those hooks would see the Glean tool
responses, and that disabling them needs --bare, which never reads an OAuth login and would log
out every subscription user, so worklog does not use it. --no-slack is the answer for anyone
that affects.

3. The optional source can no longer crash the run. TMPDIR=/nonexistent used to throw
mkdtemp's error straight out through commands/worklog.ts. Setup failure is now
{ ok: false, reason } from isAvailable and an empty batch with a warning from a fetch; a
cleanup failure warns, leaves the directory and keeps the result; a directory that is already
gone says nothing. Tests for each, including one asserting nothing is spawned when setup fails.

4. Child environment — CLAUDE_CONFIG_DIR, CLAUDE_CODE_OAUTH_TOKEN and XDG_CONFIG_HOME
added. All three appear in the installed CLI binary. CLAUDE_CONFIG_DIR is clearly load-bearing
(the bundle carries messages about its behaviour and suggests CLAUDE_CONFIG_DIR=/tmp for
ephemeral local writes). The XDG_CONFIG_HOME hits are around git and editor keybinding paths
rather than Claude's own config, so its relevance is less certain; it is preserved anyway because
passing it through costs nothing and dropping it would break anyone who relies on it. The three
nesting markers stay out. childEnvironment() is extracted and directly tested: kept keys,
dropped nesting markers, dropped unrelated secrets (GITHUB_TOKEN, ATLASSIAN_API_TOKEN,
AWS_SECRET_ACCESS_KEY), and no undefined values passed through.

Live re-verification

Availability ok; one week in 184s; 3 messages kept; 0 not public, 0 not yours, 0 malformed, 0 outside the range; zero warnings; channelType: "public", https *.slack.com permalinks.
The realpath change, the identity checks and the widened environment allowlist all hold up
against the real CLI.

Checks

bunx tsc --noEmit clean; bun run lint clean; bun run test 696 passing across 22 files.
anti-slop-check reports one finding, the same vi.mock collision reported in rounds 1 and 2.

Seven of the eight new guards are mutation-checked. The eighth, the isDirectory() test on the
cleanup path, provably changes no test: a symlink has its own inode and already fails the
dev/ino comparison. It is kept anyway, with a comment saying so, because it guards an rm -rf
and the intent should be readable without deriving it.

---

Review round 4

Cleanup is rmdir, never a recursive remove. The dev/ino check did not do what it looked
like it did: stat-then-delete is two path operations, and a same-user process can swap the
directory between them, at which point the recursive delete follows the swap and takes the
replacement with it. No amount of checking makes those two calls atomic.

The directory only ever holds a working directory for a child that writes nothing, so it never
needed a recursive delete. rmdir refuses a directory with anything in it and never descends,
which closes the race by construction rather than by inspection: the worst a swap can achieve is
the removal of an empty directory someone else put there. The dev/ino machinery and the
isDirectory() guard are gone with it, since both existed only to make a recursive delete safe.

Behaviour change worth knowing: anything the child leaves behind now survives and is reported as
a warning instead of being deleted.

Tests: an empty directory is removed; a non-empty one is left with a warning and its contents
intact; a same-prefix sibling and a directory reachable only through a symlink inside the cwd are
both untouched; the body's result survives a failed cleanup; an already-removed directory is
silent.

Checks

bunx tsc --noEmit clean; bun run lint clean; bun run test 704 passing across 22 files.
anti-slop-check reports the same single vi.mock collision as rounds 1 to 3.

Six mutations, all red, including the one this round is about: restoring the recursive delete
breaks the non-empty-directory test and the touches-nothing-outside test.

No live probe this round — the change is cleanup only and cannot affect what the child returns.