Backlog system: decision and pilot plan v2 (2026-07-06)

Research behind this decision: backlog-system-options-research (including the same-day second-pass Planka deep-dive and alternatives sweep).

Supersedes the v1 vault-native plan (same day). v1 chose vault task notes + Obsidian Bases kanban. It was overturned within hours by a requirement clarification, recorded here so the reasoning survives:

The requirement change that flipped the decision

The perspectives panel and v1 optimized for "push beats pull." The user corrected this: the pull surface — a visual board viewable and interactable from anywhere, any device, any time — is the primary requirement, not a nice-to-have. The founding pain point is "when I want to jump into a project I have no visual interface to see what's on the docket," and with ADHD a desktop-only interface means forgotten/missed tasks. Conversational access ("what's on my plate?" via chat) does not satisfy this; it must be visual.

Vault-native's known weakness (dashboard maturity, mobile — Bases custom views are desktop-weak) became disqualifying.
Planka's known weakness (task data outside markdown) became "a development problem" — solvable via REST API, per the user.

Decision

Planka v2 Community Edition (AGPL, plankanban/planka) deployed on the OVH production server (systems-prod-01, see ~/servers/ovh-prod/), as a standard ~/services/planka/ docker-compose service behind Traefik with automatic SSL. Auto-discovered by the existing backup script.
Why OVH, not the home Proxmox box / hermes01: always-on independent of home ISP/power; already reachable from anywhere with SSL (phone needs a bookmark, not Tailscale); fits the established deploy + backup pattern. Access control (strong auth at minimum; optional Traefik middleware/IP allowlist — client names will appear on cards) is a deploy-time decision.
No filesystem co-location with the vault is needed. Planka state is Postgres; all integration (CLI, tick, digest, future Hermes) goes through Planka's REST API + git. Cards reference SecondBrain notes by name/URL; any host that ever needs note content clones the vault from Forgejo (one command). The vault does NOT currently sync to OVH and doesn't need to.
Vault role demoted to knowledge layer: how-tos, contractor/client notes, conventions, decisions stay in SecondBrain; task state lives in Planka. The proven Notion rental pattern (item-with-references) survives split across the two: card = state + links, vault note = knowledge.
Forgejo issues remain the code-execution tracker (rule unchanged: Forgejo = code/arch/deployment work inside a repo; Planka = everything else; cards may link issues).
CLI over MCP. No official Planka CLI exists; we build a thin Ruby one (Sandi Metz style, lib/ + bin/, mirroring the os-adr pattern) over the REST API. plankapy (Python SDK) is the endpoint-reference crib. Community MCP servers (bradrisse/kanban-mcp etc.) are shelf reference only.

Repo/artifact separation + gem scope (2026-07-07 amendment)

Three repos, three concerns: deploy artifacts (compose, cron wiring, config, deploy PRD/runbook) live in ~/servers/ovh-prod/; the Ruby gem (API client + backlog CLI + tick/digest logic) lives in ~/dev/ruby-gems/; cc-os carries only the SessionStart-brief plugin + its eval harness. The plugin depends on the gem's installed binary — no cross-repo source coupling. ovh-prod stays behavior-free (compose + cron + config only) so all logic remains model-free-testable inside the gem.
Gem is two-layer: (1) a thin faithful client layer wrapping the Planka REST API broadly — core resources (projects/boards/lists/cards/tasks/due-dates/labels/comments/memberships/auth) plus webhooks (decided: wanted, so Planka can trigger strategic outbound actions via n8n/other APIs) and admin + attachments (less certain but likely useful — included in the first pass on the grounds that shipping probably-working endpoints now beats reopening the client later; Planka API churn judged low-risk); (2) a small opinionated domain layer (add --quick, list --all, tick) used by the CLI, digest, and future Hermes. Client layer generated with the api-wrapper skill, plankapy as endpoint crib. Per-credential instantiation (no global auth singleton) to support Hermes' scoped tokens.
PRDs drafted 2026-07-07: deploy PRD → ovh-prod repo docs; gem PRD → ruby-gems repo. cc-os plugin PRD deferred to Phase 1 (blocked on the extend-os-vault vs. new-os-backlog decision).

Fallback ladder (if the phone gate fails)

TaskView (taskview.tech) — on-paper ideal (native mobile apps, scoped API tokens, first-party MCP) but source-available, ~6 months old, thin sourcing. Verify claims hands-on first, then trial. Modern-and-unproven; only reached if Planka fails the gate.
Vikunja — mature API, kanban view, but mobile app explicitly alpha; revisit 2027.
Vault-native v1 plan (archived below via git history) / Backlog.md — the markdown lane, if hosted boards fail entirely.

Donetick (recurring-chore tracker, native mobile) noted as a lane-specific fallback if tick-driven recurrence proves annoying for property maintenance — resisted for now (fifth-backlog trap).

The Planka Pro paywall and how we route around it

Planka went commercial (2025); CE keeps the full board UI. Three Pro-only features matter here, all covered by composing around the API — we never modify or fork Planka:

Pro-only	Our layer instead
Recurring cards	`tick` script creates cards via REST on schedule — idempotent, elapsed-time catch-up (instantiates all missed occurrences), rules ours and portable
Cross-board global view	CLI `backlog list --all`, daily digest, and SessionStart brief aggregate across boards via API; in-app stays per-board (acceptable start)
Notification providers	The digest is ours (script-sent), Planka's notifiers irrelevant

Known costs: "Pro discovery" banner in the free UI (cosmetic); API-token scoping story unverified (historically username/password; verify at deploy — matters for per-profile Hermes credentials; worst case a tiny API proxy enforces scope, which fits the approval-broker pattern anyway). Project health: v2 GA early 2025, tagged releases slowed since but commits continue — mature/stabilizing with a commercial turn, not dead. 12K+ stars, strong ecosystem.

Notification policy (ADHD / notification-blindness constraint)

Three tiers, designed so silence stays meaningful:

Ambient (default, zero interruptions): the board itself + the Claude Code SessionStart brief. Information waits where the user already looks.
Digest (the only routine notification): at most ONE morning message, on ONE channel, sent only when something is due or P0 — silent days stay silent.
Interrupt: essentially never in v1; reserved for genuinely urgent items.

Target trajectory: reminders are the degenerate case where AI can't act yet. Eventually the agent drafts the action (e.g., tenant spigot email) and the notification becomes "draft ready — approve?" — a decision, not a chore.

Pilot plan — Fable orchestrates, cheap models do grunt work

Phase 0 — deploy + THE GATE (day 1)

sonnet subagent: deploy Planka CE per the ovh-prod service pattern (~/services/planka/, compose + postgres, Traefik labels, temp domain first, verify backup discovery). Decide auth posture at deploy.
haiku subagent: seed boards per hat (property, clients, cc-os/dev, business dev) + 8–10 real fixture cards via REST (spigot winterization due 2026-10-15; Woodfin HVAC/electrical/plumbing checkups; cc-os someday items incl. "adopt Storybloq handover-doc pattern"; 1–2 client items). Also proves API CRUD end-to-end.
Human gate — the phone test: from the phone (responsive web; official app and Planka Pal as alternates), view boards, drag a card between lists, add a card, complete one. Pass → continue. Fail → fallback ladder.

Phase 1 — the agent layer (parallel after the gate)

sonnet subagent: Ruby backlog CLI (lib/ + bin/, model-free tests): add --quick "title" (defaults board/list/priority), list --all (cross-board), tick (idempotent elapsed-time recurrence catch-up from a recurrence manifest; simple offsets +1y|+6m|+3m|+1m only — no rule engine).
haiku subagent: daily tick + digest scheduling on the OVH box (cron or a small container next to Planka), digest per the notification policy (one channel — ntfy or email, decide at build; silent when empty).
sonnet subagent: Claude Code SessionStart brief — terse 3–5 line due/P0 cross-board block via the CLI. Plugin home + naming per cc-os-plugin-skill-naming-convention (extend os-vault vs. new os-backlog — decide at build; run bin/refresh-plugins after).
Fable: review all deliverables; verify a fresh session surfaces the fixtures.

Phase 2 — Hermes (independent design exercise, guardrails-first — NOT in the pilot's critical path) Considered separately from the task system; the task system's only obligation is integrate-ability, which REST + (verified) scoped tokens provide by construction. Design principles locked now:

Capability-based access: each Hermes profile/hat (property manager, accountant, client manager, business partner) gets its own narrow, revocable credential (e.g., read-only or single-board token). Hermes never holds credentials for catastrophic actions (money movement, deletion, infra).
Approval broker: catastrophic-class actions are requests Hermes submits to an interface (n8n workflow / API) that holds the real credentials and routes to the user for approve/reject. Guardrails are the interface, not a policy.
Sequence: read-only digest/query first, then narrow acting (comms drafting for property items), one hat at a time, property manager first. Gets its own design note when started.

Phase 3 — close-out (Fable)

cc-os ADR + CLAUDE.md update; retire the v1 vault-task-type idea from vault-conventions planning.
One-week live trial. Week-2 review gates (each pre-captured as a card): digest too noisy → tighten; capture friction → extend CLI; Forgejo top-issues added to brief; recurrence annoyance → evaluate Donetick for the property lane.

Explicitly deferred (captured as someday cards, not built): recurrence rule engine, effort/quick-win filter, AI comms drafting, Hermes acting autonomously, vault→OVH sync, per-board polish, TaskView evaluation (unless gate fails).

Success criteria

The board is viewable and interactable from the phone, anywhere (the gate, then daily reality).
Recurring tasks cannot silently miss a week (tick catch-up on an always-on host).
Due/P0 items visible every working morning with zero navigation (SessionStart brief + digest-when-warranted).
Capturing a task costs one command or one sentence to Claude.

11 KiB Raw Blame History Unescape Escape