The board is the backlog of record. This directory reads and writes shared PostgreSQL through the Node CLI. See server and worker setup. SQLite support below describes historical checkouts and local test fixtures; the live board and document catalog are no longer committed database files.
Run it as ./eve from the repository root (or pnpm eve from anywhere in the
workspace). The plan, every task and every decision behind them are in
TODOS/initiatives/EVE_TASK_BOARD_TODOS_2026-09-18.md.
What works today#
./eve help is the list. The path through one task:
./eve next what to work on: ready, nothing holding it back
./eve show <key> the item, its dependencies, its claim, its journal
./eve claim <key> --agent <you> lease it for four hours; prints a fencing token
./eve start <key> --token <n> leased → in-progress
./eve done <key> --evidence "…" --token <n>
check the box IN THE TRACKER, write the evidence,
ship the task, release the claim
./eve park <key> --reason <r> --note "…"
write the tag and the sentence into the item
./eve verify <key> --by <somebody-else> shipped → verified, by a second actor
and the rest: list, search, families, stats, add, edit, dep,
reject, unpark, renew, release, note, import, drift, check,
dump, git-setup, resolve, merge-driver.
./eve context <key> [--max-chars 20000] is the one an agent reads before it
starts: the item, what it depends on, what the tracker says about itself (its
rules AND the prose section that holds its legend — EI.1.01 says AD/lib/…
and only ### 0.0 says AD = apps/oshun/admin/src), the closest section of
each document it cites with how many of its terms that section matched, the code
paths with their sizes, what sits beside it, and any parked task that names it.
It is byte-identical on every run against a given tree, and --max-chars drops
whole entries in a stated order and says which.
./eve promote <key> posts a task to Eve's workbench queue
(POST /v1/workbench/items, added by ETB.9.02 — before it, the queue could only
be written by Eve's own tool inside a turn). It sends the ETB.7.03 brief, is
idempotent per task, records the work-item id in task_links, and refuses with
the URL it tried when the workbench is not there. It needs
OSHUN_WORKBENCH_TOKEN and takes --url (or OSHUN_WORKBENCH_URL).
It does NOT send requirementRefs, although the item asked for it. Measured
2026-09-19 against the live database: work_item_planning_binding_shape
(migration 20260913050000) permits a non-empty requirement_refs only alongside
a complete planning tuple with a foreign key into planning_plan_work_revision,
and a probe insert carrying only requirement_refs was refused by Postgres. The
board key rides in expectation.board and on the first line of the body, both
of which the task brief returns; the endpoint refuses a requirementRefs
parameter rather than accepting and dropping it.
./eve pull reads every promoted task's work item and mirrors leased,
in-progress, shipped and verified onto the board, journalled as
workbench. One direction only, and it never checks a box: a mirrored shipped
stops ./eve next offering the task, while the checkbox in the tracker is
written by ./eve done, with evidence, by whoever did the work. A task the
queue holds also refuses ./eve claim — two agents each holding "the" lease is
the failure both mechanisms exist to prevent.
The documents are a second index beside the tasks:
./eve docs search "<query>" [--kind adr] [--domain isis] [--limit 20]
rank the 16,379 catalogued documents
./eve docs show <path> [--section "<heading>"]
its headings, or one section of it
./eve docs related <key> what a task NAMES, then what merely
looks like it answers — two lists
./eve docs stale what changed under the tasks citing it
./eve docs export --format bff-corpus the assistant's JSONL corpus; --scope, --out
./eve docs build [--kinds a,b] the local full-text cache
./eve docs index re-read the tree into the catalog
docs export builds the corpus apps/oshun/bff/src/assistant/docs-search.ts
loads. tools/build-assistant-docs-search.mjs builds it by parsing the rendered
reader HTML, which has not been committed since audit R-2 — so that builder only
works where pnpm docs:center has run. This one builds the same shape from what
IS committed: the Docs Center's published index for each page's href, title,
vertical, kind and [heading, anchor] pairs, and the page's markdown source for
the text. Measured 2026-09-19: 49,231 chunks from 2,802 pages, 37.8 MB, and the
318 pages the generator synthesises (docs-center/**) are counted as
skippedPages rather than invented. The member scope stays empty, which is what
fails the assistant's search_docs tool closed.
docs stale takes about 35 seconds: it asks git blame when each citing line
was last edited, because a task's updated_at is when the IMPORTER wrote the
row and every row in this board carries today's. It reports what changed after
the item that cites it, what is cited and no longer there, and — separately —
what is cited by a name (ADR-0008) that means more than one document, plus
counts for the citations it could not date and the ones that changed on the same
day as the item.
All three readers work without the cache, on the catalog's titles and headings,
and say in one line which of the two they used. docs show never needed it: it
reads the file.
Anything not built refuses with exit 2 and names the task that will build it, so
./eve promote answers "not yet — ETB.9.02" rather than "no such command".
Those are different facts and a caller acts differently on each.
Two sessions at once#
Several sessions work this repository in parallel, so the board is edited from two places and a merge conflict in it is ordinary rather than exceptional.
TODOS/BOARD.md,PARKED.md,board.jsonare generated. Never resolve them by hand:git checkout --theirsall three, run./eve board,git addthem, continue the merge.TODOS/eve-task-board.sqliteis a committed SQLite database../eve git-setup— whichpnpm installruns — registers a row-level merge driver, andgit mergethen does it for you. Where it was never installed,./eve resolvefinishes the merge by hand from the index stages (:1:,:2:,:3:) and stages the result.- The merge is by task
key: a task closed on one side survives; changed on both sides with the same outcome is fine; changed differently takes ashipped/verifiedover an earlier state, and otherwise leaves the taskreadywith BOTH journals kept and amerge-conflictevent naming each side. A claim goes to the higher fencing token and the loser is told. Nothing is resolved by guessing, because a driver that picked would lose somebody's work with no trace. - If neither the driver nor
resolveis available, take either side and run./eve import: the board is derived from the trackers and rebuilds in about four seconds. What that costs is the journal — claims and evidence events — which is why it is the last resort and not the first.
git diff on the board shows rows, not bytes, once git-setup has run: a
one-row status change is a one-line diff instead of Bin 25604096 -> 25604096.
dump is what makes that work: git cannot diff SQLite, so this is the
textconv a reviewer reads. --stable omits the file path so two databases can
be compared byte for byte; --file exists because git hands a textconv driver a
temporary copy rather than the working file.
Two ways a task gets closed#
./eve done is the front door: it checks the caller's fencing token, refuses
evidence over 160 words, writes the box and journals done under the agent's
name with the commit it was given. The importer is the other: it reads a box
somebody checked by hand and journals shipped under the actor markdown, with
whatever commit last touched the tracker. That door stays open — it is how a
board is rebuilt — but it is visible (ETB.5.05, lib/provenance.mjs):
./eve show <key>printsclosed byfor a finished task:./eve donewith the agent, orimport of a box checked by hand../eve checkprints onewarning:line, on stdout after its verdict, for every task shipped by import since 2026-09-19 that has had nodoneand noverify. It never changes the exit code and is not one of the eight questions../eve verify <key> --by <someone else>is the second look, and clears the line.
Call done AFTER the commit it names exists. A chain that carries on past a
failed commit hook records the commit before the work — which is the defect this
section is about, reproduced by its own author on the day it was written
(EI.7.08's journal has the correction).
Exit codes#
| code | meaning |
|---|---|
| 0 | it did what was asked |
| 1 | a refusal: a check failed or a precondition was unmet, with a code |
| 2 | the command is not one this tool has, or is not built yet |
| 3 | this Node cannot run the tool: node:sqlite needs Node 22.13 or newer |
Exit 3 is decided before anything imports node:sqlite. On an older Node
that import throws, and the message a reader needs is the version requirement,
not a stack trace about a missing builtin.
Layout#
| file | what it owns |
|---|---|
cli.mjs |
argument parsing, dispatch and the exit codes — no logic |
lib/paths.mjs |
the repository root, the database path, the cache path |
lib/db.mjs |
opening the database, its pragmas, and numbered migrations |
*.spec.mjs |
specs, run by node --test. No build step and no node_modules |
There is deliberately no package.json here. tools/* is a pnpm workspace
glob, so one would make this directory a workspace package with an install step
— and the first rule of the plan is that this tool has neither.
Where its files live#
TODOS/eve-task-board.sqlite— committed. Open work and its journal, kept under a 25 MB budget, injournal_mode=DELETEso no-walfile can ever appear beside it.TODOS/eve-task-board-docs.sqlite— committed. The document catalog: what documents exist, under a 16 MB budget..cache/eve-task-board/knowledge.sqlite— never committed. The full-text index over those documents: 243,616 chunks and 24,852 tasks in 262 MiB, measured 2026-09-19../eve docs buildwrites it from scratch in 9.6s and re-runs in 0.8s, because a document whose sha256 is unchanged is not read.
The repository root is found by walking up to pnpm-workspace.yaml, so the tool
works from a subdirectory and gives each git worktree its own database.
Specs#
node --test tools/eve-task-board/cli.spec.mjs tools/eve-task-board/lib/*.spec.mjs
Two things those specs do that are worth keeping when they grow:
- the three exits are driven, not asserted about.
run()takes argv, the Node version and two writers as arguments, so the exit-3 path is exercised on a machine running a new Node — instead of an environment variable the CLI honours, which would be a test-only backdoor in a tool that refuses things for a living; - every pragma is read back. A pragma that did not take is silent in SQLite, and a store that believes its foreign keys are on when they are off is worse than one that knows they are off. The foreign-key spec inserts a dangling row and requires the error.