Vault-native backlog: decision and pilot plan (2026-07-06)

Research behind this decision: backlog-system-options-research.

Decision

Build the personal cross-project backlog inside the SecondBrain vault: one note per backlog item (task note type), a push-first surfacing layer, Obsidian Bases kanban views as the visual dashboard, and a minimal deterministic CLI. Forgejo issues remain the code-execution tracker (rule: Forgejo = code/arch/deployment work inside a repo; vault = everything else; vault tasks may wikilink/reference Forgejo issues). Fallbacks, in order: Backlog.md (if the Bases board spike fails), Planka + community MCP (if markdown-native fails or a standalone/mobile dashboard becomes a hard requirement).

Perspectives panel verdict (4 agents: devils-advocate, simplifier, implementer, premortem)

The panel kept the vault-native direction but inverted the build order. Consensus corrections to the original proposal:

The load-bearing layer is push/surfacing, not the data store. A board that must be opened and a SessionStart hook that fires only when a session starts both fail the ADHD constraint (out of sight = forgotten). The recurring-maintenance scenario (frozen spigots) fails in any week with no Claude sessions. → Push first, board later.
Three reliability requirements or the system is "theater within three months" (premortem): (a) time-aware idempotent tick with a staleness catch-up check, (b) SessionStart text summary of due/P0 items, (c) one-field quick-add capture.
Daemon contradiction resolved honestly (implementer): a systemd --user timer (one-shot daily, not a daemon) firing tick + an ntfy/email push is the minimum genuine fix for no-session weeks. Recurrence math must be elapsed-time catch-up ("instantiate all missed occurrences since last tick"), never one-session-one-tick.
YAGNI cuts (simplifier): no recur rule engine (simple offsets like recur: +1y); no full CLI at launch (tick + quick-add only; list/move/next deferred to demand); board built only after live task data exists (a Bases saved view is minutes of work once notes exist); AI comms drafting (tenant emails) is week-3; effort field + quick-win filter is week-4.
Spike before building (implementer): verify Base Board / bases-kanban against fixture notes — multi-property filters, ordinal priority sort (use sortable encodings: P0–P3, E1–E3; never low/medium/high strings), drag-drop frontmatter write-back, missing-property rendering, mobile (expect desktop-only). Also spike the Obsidian-open-buffer vs. external-frontmatter-write collision, and verify CLI YAML serialization round-trips byte-identically with Obsidian's processFrontMatter (serializer churn pollutes git diffs and widens the conflict surface with the existing vault_sync.py SessionEnd push).
Task-rot defense: the quarterly someday-review is itself a recurring P0 task in the system (dogfooding, zero extra code).
Fair challenge accepted (devils-advocate): Backlog.md was dismissed too fast (wikilinks do resolve into its files); it stays the named fallback and the ergonomic template for the CLI. And the morning surface should eventually include top Forgejo issues (via tea) so the two trackers get one unified decision point (week-2).

Task note schema (v1 — to be formalized via /os-vault:design-template new-type lifecycle)

---
summary: <one-line>
tags: [scope/global, type/task, <client|project|domain facet>]
status: backlog | next | doing | done | someday
priority: P0 | P1 | P2 | P3        # sortable encoding, verified in spike
due: YYYY-MM-DD                     # optional
recur: +1y | +6m | +3m | +1m       # optional, simple offset only — no rule engine
---
<body: context + wikilinks to how-tos, client notes, property/contractor notes,
Forgejo issue URLs — the Notion rental-property pattern>

Open spike question: whether status/priority live as frontmatter fields (Bases-friendly, likely) vs. tags — decide during the spike, record in vault-conventions.md.

Pilot plan — Fable orchestrates, cheap models do grunt work (runnable in one day)

Fable's role throughout: sequencing, design decisions, spike-result judgment, reviewing every subagent deliverable before it lands, updating vault-conventions.md and cc-os docs/ADR at the end.

Phase 0 — schema + fixtures (parallel, ~30 min)

haiku subagent: create _templates/task.md + 8–10 fixture task notes in the vault (real content: spigot winterization due 2026-10-15 recur +1y; Woodfin HVAC/electrical/plumbing checkups; 2–3 cc-os someday items — including "adopt Storybloq's handover-doc pattern" as the first captured down-the-road idea; 1–2 client items). Mechanical work from a spec Fable writes.
Fable: write the spec; verify facet/frontmatter correctness against vault-conventions.md.

Phase 1 — the two spikes (the riskiest assumptions, before any CLI code)

Bases board spike: human-in-the-loop (Obsidian GUI required). Fable/haiku prepares a step-by-step checklist: install Base Board (and bases-kanban as alternate), build a board over type/task fixtures, test the six capabilities from panel point 5. Gate: pass → continue; fail → switch dashboard track to Backlog.md, keep everything else.
sonnet subagent: concurrent-write spike — script that externally rewrites frontmatter while the file is open/dirty in Obsidian; document observed behavior (reload/prompt/clobber) and the serializer round-trip check.

Phase 2 — the three must-haves (parallel once Phase 1 passes)

sonnet subagent: tick — deterministic, idempotent, elapsed-time catch-up (advance done+recurring tasks by their offset, flag overdue); plus backlog add --quick "title" (defaults: status=backlog, priority=P2). Ruby, Sandi Metz style, thin bins over a small lib — mirror the os-adr lib/ + bin/ pattern in cc-os. Includes model-free tests.
sonnet subagent: SessionStart surfacing hook for the os-vault plugin (Python, matching existing hooks): terse 3–5-line block of due + P0 items, plus the ≥7-days-since-last-tick staleness check that runs tick catch-up inline. Timestamp state file in the vault .state/ (gitignored).
haiku subagent: systemd --user timer + service units firing daily tick, with ntfy (or mail) push when property-domain tasks come due — the no-session-week safety net.
Fable: review all three (correctness, invariants, naming per cc-os-plugin-skill-naming-convention), integrate into cc-os/plugins/os-vault/, run bin/refresh-plugins, verify a fresh session surfaces the fixtures.

Phase 3 — close-out (Fable)

Update vault-conventions.md (task type), cc-os CLAUDE.md + build docs, and record the decision as an ADR in cc-os.
Live for one week with real tasks. Week-2 review gates (each pre-captured as a task note): noisy summary → filter tighter; board friction → revisit Backlog.md; capture demand → extend CLI (list/move/next); add Forgejo top-issues to the morning surface.

Explicitly deferred (each captured as a someday task, not built): recur rule engine, effort/quick-win filter, AI comms drafting, mobile dashboard, per-domain board polish, Planka migration.

Success criteria (from premortem)

Recurring tasks cannot silently miss a week (timer + staleness check both firing).
Due/P0 items visible every working morning with zero navigation (session surface, later board).
Capturing a task costs one command or one sentence to Claude.

7.8 KiB Raw Blame History Unescape Escape