---
id: tooling/a-kanban-board-over-todo-synchronised-both
title: "A Kanban board over `todo/`, synchronised both ways"
theme: tooling
status: open
created: 2026-08-21
date_source: stated
order: 1
---

**A Kanban board over `todo/`, synchronised both ways.** Wanted 2026-08-21, and it is the reason the
list became a directory rather than a file. Read the tree, render columns, and write changes back —
drag a card to another column and the file changes; edit the file and the board follows.

**The file system is the database.** There is no second store to reconcile, which is the whole point:
these items are already versioned, already reviewable, already synced between machines by git. A board
that kept its own copy would be a second truth with no way to say which one is right — the failure this
repository has already documented twice (`command_hq_sessions` refusing a `status` column,
`chat_session_events` being derived rather than stored).

The contract it can rely on is written down in `todo/README.md` → "Two-way sync". In short: a card is a
file, `id` is the identity so a retitle never orphans one, frontmatter is the machine's half and the
prose body is the owner's, and `TODO.md` is generated output that the board must never write to.

Open, and deliberately not decided here: which columns (`status` today holds only `open`/`done`, so
`doing` and `blocked` are new values whenever the board wants them); whether it is an Officer screen, a
panel app or a plugin; and how it notices a change made on disk while the board is open — a watcher, a
poll, or a refresh button, which is the cheapest thing that works.