Skip to content

Obsidian first, and every commit traceable to a vault project, enforced by a hook

  • Date: 2026-11-04
  • Status: Accepted
  • Tags: tooling workflow

Context

The rule in ~/.claude/CLAUDE.md is that LifeOS holds the why and what, and Linear holds the how and when. Two things showed the rule wasn't holding:

  • The morning habit had slipped. On 2026-11-03 the newest daily note was eight days old. Across the 64 notes from 2026, ## Daily Record is the section actually written in (33 notes), and only 4 of the last 12 had content.
  • Sessions drifted into untracked sidebars. On 2026-11-03 a session moved into the AWS MCP setup and a clone-sync fix. Neither got an issue, so neither appears in Linear or ties back to a vault project.

No document defined a morning practice. ADR-0006 calls the daily note "the morning landing pad", and ADR-0007 worries about projects going stale, but the automation they describe fills the note for the reader, and nothing asks the reader to choose anything. /am-sweep even shows its output so the note needn't be opened.

The first design was a warning at session start. It failed on a real habit: sessions are left open overnight and resumed by opening the laptop, so SessionStart never fires.

Decision

I will run one user-level hook, claude/hooks/work-tracker.py, in every session on this Mac. Design: docs/superpowers/specs/2026-11-03-work-tracking-hook-design.md.

Morning check (soft stop). On every prompt, in every session, it reads today's note. Until ## Daily Record holds real text, Claude holds the request, opens the note in Obsidian and carries on once it's written. Saying "skip note" passes for that day. Claude declines to write the line itself, even when asked, because the point is to open Obsidian. The day rolls over at 4am.

Work check (hard block). Before git commit and gh pr create, it checks the chain and denies at the first gap:

  1. The work has a Linear issue, from a pha- branch name or an explicit link.
  2. The issue has a Linear project.
  3. A README under 1. Projects carries that project's URL in linear_project:. The daily note's Project List is a live query of the same READMEs, so this is the "listed in the daily note" test.
  4. That README's ## Outcome has at least 8 words, so the vault holds a real why.

Claude never creates an issue without asking. Only the user can clear a block ("this work isn't tracked"), for that session and that repo's branch. Reads and edits are never blocked.

Fail open, visibly. A Linear outage, unreadable vault, or missing branch never blocks; it shows a note. Only a confirmed gap blocks.

Automated sessions (claude -p, Cyrus) skip the morning check and the end-of-turn question, because nobody can answer, but their commits are still checked.

Alternatives Considered

Option Why Rejected
Check only at SessionStart Misses sessions left open overnight, the normal case
Warnings only at commit The first default, but the user chose blocking
Hard-block the morning prompt UserPromptSubmit blocking discards what was typed
Require the today - standup line Filled in only 8 of 64 notes, and /daily-note pre-fills it
A new Focus today line Proposed, but the user chose the section they already write in, accepting that any errand passes
Let Claude write Daily Record when dictated The check could pass without Obsidian ever being opened
Matching commands with a regex The larvis lb-commit-nudge.sh regex fires on quoted text; as a block that stops unrelated commands
Keeping the code in larvis It applies to every repo and isn't part of the larvis service

Consequences

Positive:

  • The vault is opened before work starts, and every commit traces to a project with a stated why.
  • Sidebars get noticed when they happen, not at the next review.

Negative / Trade-offs:

  • The commit block covers every repo on this Mac, including work repos, which need a PHA issue or an override per session and branch.
  • The soft stop and "only the user can clear a block" are instructions to Claude, not locks.
  • Any errand satisfies the morning check, so it proves the note was opened, not that the most important project was chosen.
  • The Project List shows every project, so the hook can't tell which matter today.

Verified live on 2026-11-04: the hold and resume in a session already open before the install; all four gaps; the override; automated sessions; a bad Linear key letting the commit through.

Not yet seen live: "skip note" and the end-of-turn question (automated tests only), and whether a /loop prompt is held at 4am (unmeasured, the hold wording tells Claude to carry on).

Known gaps to iterate on:

  • git commit --help, --dry-run and gh pr create --help are blocked like real commits.
  • Unparseable commands, bash -c, env-prefixed git, gh -R and pushd pass unchecked, mostly with no note.
  • An HTTP error body containing "not found" reads as a missing issue.
  • Parallel subagents can lose a state update, because writes are atomic but not locked.
  • link shows a traceback if its directory was deleted; an unknown hook subcommand exits 2.
  • Frontmatter with a trailing comment, markdown link or BOM reads as no vault project.
  • A session resumed after 14 days loses its override.
  • Daily Record accepts a bare --- or heading as real text.

Ongoing obligations:

  • Change the source here, run just work-tracker-test, then just work-tracker-install. Uninstall with just work-tracker-uninstall, which leaves other hooks alone.
  • If the daily template's ## Daily Record heading changes, update the pass test.
  • The vault's README naming and linear_project: frontmatter (ADR 0002 and lifeos-project-check.py) are now load-bearing for the block.

ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.