vault: session notes 2026-07-06

backlog-system-options-research.md

@@ -0,0 +1,64 @@
+---
+summary: Research on self-hosted, AI-CRUDable kanban/backlog systems (2026-07) — Storybloq, Planka, Vikunja, Plane, Backlog.md, beads, Obsidian Bases kanban — with comparative verdicts for a solo freelancer running Claude Code + SecondBrain vault
+tags:
+  - scope/global
+  - type/reference
+  - domain/task-management
+  - tool/claude-code
+  - project/cc-os
+last_reviewed: 2026-07-06
+---
+
+# Backlog system options research (2026-07-06)
+
+Research question: a personal, cross-project backlog with (a) a visual kanban dashboard, (b) full AI CRUD (Claude Code), (c) self-hosted, (d) modular/low-maintenance, (e) multi-domain — software dev, freelance client management, business development, property management, general projects. Researched via three parallel sonnet subagents (web research; claims below not all hands-on-verified — see caveats).
+
+Decision + pilot plan: [[vault-backlog-pilot-plan]].
+
+## Requirements that emerged during framing (not in the original ask)
+
+- **Recurrence is first-class**, not an afterthought: property maintenance (winterize spigots, HVAC/electrical/plumbing checkups via Woodfin) is date-driven, and a kanban alone doesn't do it.
+- **ADHD constraint is load-bearing**: out of sight = forgotten. A board that must be opened, or a hook that fires only when a session starts, does not by itself surface anything. The system needs a push/surfacing layer (this became the central finding of the perspectives review — see [[vault-backlog-pilot-plan]]).
+- **P0–P3 priority + effort metadata** for a morning "most important + quick wins" view; `someday` status that backgrounds items without deleting them.
+- **Fifth-backlog trap**: Forgejo issues, OpenSpec changes, build-plan docs, and vault open-items already exist. A new system must consolidate the "where did we leave off" question, not add another place to check.
+
+## Options evaluated
+
+### Storybloq (github.com/Storybloq/storybloq) — inspiration, not a fit
+
+Cross-session context persistence for AI coding: `.story/` dir of plain JSON + markdown (tickets/phases/notes/lessons/handovers), git-tracked, no server. 53 MCP tools + full CLI parity + importable TS library. v1.5.0 (2026-07-05), ~2.5 months old, 653 stars, 2 contributors, PolyForm Shield license (source-available, not OSI).
+
+Disqualifiers: the kanban dashboard is a **Mac App Store app** (Linux user — the visual requirement is unmet); per-repo and coding-session-continuity focused (overlaps memsearch + journal hooks, ignores non-code domains); young; repo-scoped, against the global-capture direction (ADR-015 era).
+
+Worth stealing: file-per-entity storage, handover-document concept, board-watches-files-live pattern, MCP tool surface breadth.
+
+### Hosted self-hosted PM tools
+
+- **Planka** — best of the hosted class. Trello-grade UI (~12K stars), lightweight Docker deploy, board-per-domain, AGPL. Key differentiator: **5+ community MCP servers** (mgertz/mcp-planka, bradrisse/kanban-mcp, etc.) giving Claude Code full CRUD with zero integration work. Named fallback if the markdown-native route fails.
+- **Vikunja** — strongest horizontal PM design (projects as top-level units, custom fields, kanban/gantt/table views, documented REST API), v2.0 2026, but no CLI/MCP — hand-wired REST only. Heavier deploy (Go + MariaDB).
+- **Plane** — Linear-class, first-party MCP server, workspace-level cross-project views, 49K stars. Built for team sprints/velocity; overkill + heaviest ops for a solo user. Good SWE-team option, wrong scale here.
+- **Forgejo project boards** (existing infra) — weaker than hoped: repo-scoped (can't span domains), `tea` CLI does **not** cleanly expose board CRUD, board API underdocumented. Fine as the code-level tracker (issues), not as the portfolio board.
+- **Kanboard** (maintenance mode, 2013 UX, no AI path), **Focalboard** (abandoned standalone, June 2024), **Huly** (no API/CLI/MCP found), **Taiga** (successor limbo), **OpenProject** (enterprise-heavy), **WeKan** (no advantage over Planka) — all ruled out.
+- **Notion / Airtable / Linear** — fail self-hosting outright.
+
+Structural cost of any hosted tool: backlog items live outside markdown — no wikilinks to how-to notes, no Graphify edges, no memsearch adjacency, a second source of truth. The Notion rental-property pattern (item note referencing contractor/how-to notes) is exactly what a DB-backed kanban can't express.
+
+### Markdown / agent-native
+
+- **Backlog.md (MrLesk/Backlog.md)** — best standalone agent-native tracker. Tasks as markdown+YAML files, agent-first deterministic CLI, web + TUI kanban, user-level `~/.backlog/<slug>/` workspaces spanning repos. 5.8K stars, MIT, active. Cost: a second markdown store outside the vault with its own schema. Devil's-advocate correction: Obsidian wikilinks **do** resolve into its files, so the "no wikilinks" dismissal was overstated — it is the primary fallback and the design template for the CLI ergonomics (`backlog task create "..."`).
+- **beads (steveyegge/beads)** — 18.7K stars, git-backed issues with dependency DAG, MCP support, excellent for code work but repo-centric and code-marketed; wrong shape for property/client domains.
+- **vibe-kanban (BloopAI)** — multi-agent orchestration kanban; post-commercial transition (Bloop shutdown 2026-04) = maintenance risk; orchestration-focused, not general PM.
+- **kanban-md, agent-kanban, taskmd, VS Code Agent Kanban** — smaller/younger variants of the same file-per-task + YAML pattern; confirm the pattern is the 2026 consensus for AI-agent task tracking, none clearly beats Backlog.md.
+
+### Obsidian-native (the chosen lane)
+
+- **Obsidian Bases + board plugins** (Base Board by mderazon; obsidian-bases-kanban by xiwcx; Kanban Bases View) — kanban views over note **frontmatter**: columns map to a property (e.g., `status`), drag-drop writes back to frontmatter. Actively maintained 2026, built on the Bases custom-view API (~May 2026). Each card = a normal vault note → wikilinks, facets, Graphify, memsearch all apply. **Caveats (unverified hands-on):** multi-property filtering, ordinal sort (P0–P3 must not sort lexically wrong), drag-write reliability, and mobile rendering (custom Bases views are a known mobile weak spot — expect desktop-only) all need a spike before commitment.
+- **mgmeyers obsidian-kanban** — de facto unmaintained; stores board state in markdown lists (fragile for external edits). Skip.
+- **TaskNotes / obsidian-pm** — same note-per-task + frontmatter pattern with their own view layers; alternatives if Bases board plugins disappoint but a plugin dependency remains either way.
+- **Tasks + Dataview** — good read-only reporting layer, weak for agent-driven mutation; not a primary store.
+
+## Comparative verdict
+
+Vault-native (task-type notes + Bases board views + thin deterministic CLI) wins on every axis except maturity-of-dashboard: one system instead of a fifth backlog, matches the proven Notion property pattern verbatim, items become graph nodes wikilinked to how-tos, AI CRUD is nearly free via existing os-vault plugin machinery, self-hosted/synced by construction. **Fallback #1: Backlog.md** (if the Bases board spike fails). **Fallback #2: Planka + community MCP** (if markdown-native fails altogether or a standalone web/mobile dashboard becomes a hard requirement). Forgejo issues remain the code-execution tracker underneath, referenced from vault tasks.
+
+The perspectives panel (devils-advocate, simplifier, implementer, premortem) materially reordered the build — push/surfacing layer first, board second, CLI minimal — see [[vault-backlog-pilot-plan]] for the verdict and the plan.

journal/2026-07-06.md

@@ -367,3 +367,10 @@ tags: [scope/global, type/log]
 **Reason:** other
 **Vault notes touched:**
 (none)
+
+## Session — 2026-07-06T16:36:11Z
+
+**Project:** /tmp/claude-1000/-home-jared-dev-cc-os/d68aab1b-3e3d-467c-9b9c-70b89e2576b0/scratchpad/adr-eval-c-grid/N3-L3-execution-haiku/N3-L3-execution-haiku-r3
+**Reason:** other
+**Vault notes touched:**
+(none)

vault-backlog-pilot-plan.md

@@ -0,0 +1,78 @@
+---
+summary: Decision + day-1 pilot plan for the vault-native backlog (task notes + push-first surfacing + Bases kanban spike), including the perspectives-panel verdict and the Fable-orchestrator/cheap-subagent execution plan
+tags:
+  - scope/global
+  - type/decision
+  - domain/task-management
+  - tool/claude-code
+  - project/cc-os
+status: accepted-pending-pilot
+last_reviewed: 2026-07-06
+---
+
+# 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:
+
+1. **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.
+2. **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.
+3. **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.
+4. **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.
+5. **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).
+6. **Task-rot defense**: the quarterly someday-review is itself a recurring P0 task in the system (dogfooding, zero extra code).
+7. **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)
+
+```yaml
+---
+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)
+
+1. Recurring tasks cannot silently miss a week (timer + staleness check both firing).
+2. Due/P0 items visible every working morning with zero navigation (session surface, later board).
+3. Capturing a task costs one command or one sentence to Claude.