task-creator

Task Creator

This project stores every task as a dedicated artifact directory under tasks/.

There are two stores, and only one of them is authoritative:

tasks/<slug>/task.md frontmatter   source of truth (durable, human-readable, greppable)
        ^ every write goes here first        | discover_and_sync (lazy, on every command)
.state/tasks-index.db  tasks       one table, fully rebuildable from tasks/

scripts/tasks_index.py owns both. It is the one callable creation interface: do not hand-assemble a task.md, and do not hand-edit the frontmatter when a command exists for the field. Reading the index directly is fine; writing to it is not.

The Database Is Rebuildable, All Of It

Delete .state/tasks-index.db and the next command builds it again from tasks/ — including the next task number, which is MAX(id) + 1 over the table after it has been synced. A corrupt database is repaired by removing it. Nothing here is the record of anything.

This replaced a design that split the same file in half: a disposable lookup table beside an id_allocation ledger that was the allocator of record, never re-derived from disk, with no repair path. Losing .state/ while tasks/ survived left task creation broken with no way back. Do not reintroduce a durable allocator under another name.

One Discovery, Shared By Everything

discover_and_sync is the only thing that reads the task tree, and query, add, reindex, write-command argument resolution and check all call it. It lists the immediate directories of tasks/ — never their payloads — compares each task.md against a stored mtime_ns+size fingerprint, and parses YAML only for what is new or changed.

Do not implement discovery a second time. add runs it inside the BEGIN IMMEDIATE that computes the number, so a directory the table has not yet seen still owns its number. An add that allocated from an unsynced table would reissue a number that already exists on disk.

A task's id comes from its frontmatter and never from the directory name. A directory with no usable number is indexed with a null id: visible in listings, absent from MAX(id), reported by check. The prefix and the id: must agree exactly, and a directory that has a usable id must carry it in its name: a name with no numeric prefix (tasks/archive/) or a date-shaped one (2026-05-26-…) blocks allocation exactly as a mismatched prefix does. Both used to pass — tasks/archive/task.md claiming id: 90000 moved the next number to 90001, and a date whose year equalled the id satisfied the prefix comparison while still being a date.