Eve library

Eve Task Board — the `eve` command

Other

Revision 1

On this page

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:

text
./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:

text
./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.json are generated. Never resolve them by hand: git checkout --theirs all three, run ./eve board, git add them, continue the merge.
  • TODOS/eve-task-board.sqlite is a committed SQLite database. ./eve git-setup — which pnpm install runs — registers a row-level merge driver, and git merge then does it for you. Where it was never installed, ./eve resolve finishes 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 a shipped/verified over an earlier state, and otherwise leaves the task ready with BOTH journals kept and a merge-conflict event 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 resolve is 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> prints closed by for a finished task: ./eve done with the agent, or import of a box checked by hand.
  • ./eve check prints one warning: line, on stdout after its verdict, for every task shipped by import since 2026-09-19 that has had no done and no verify. 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, in journal_mode=DELETE so no -wal file 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 build writes 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#

bash
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.