The board is the backlog of record. Its tasks, claims, journal and review queue
live in shared PostgreSQL, and this directory is the Node CLI that reads and
changes them. See server and worker setup
for the database and the worker API, and the plan behind the tool in
TODOS/initiatives/EVE_TASK_BOARD_TODOS_2026-09-18.md.
Run it as ./eve from the repository root (or pnpm eve from anywhere in the
workspace). ./eve help is the list of commands.
Which board it talks to#
- API mode, the worker's path. A private credential file,
~/.config/oshun/eve-api.json(mode 0600) or the fileEVE_API_CONFIGnames, orEVE_API_URLwithEVE_API_KEY, sends every command to the worker API over HTTPS. The API refuses rather than falling back to any database. Remote coding agents set up this way. - Direct PostgreSQL, for operators. Without an API credential, the CLI
connects to the database named by
EVE_DATABASE_URLor by the fileEVE_DATABASE_CONFIGnames (default~/.config/oshun/eve-postgres.json). Workers do not use this path. - Historical SQLite.
TODOS/eve-task-board.sqliteis no longer committed. A SQLite board exists only in migration fixtures, specs and historical checkouts; see the last section.
Tracker checkboxes, TODOS/BOARD.md and the old SQLite files are historical
projections, not writable task records. No command writes a tracker on the
database-owned board, and ./eve import refuses it.
Working one task (API mode)#
./eve next what to work on: ready, nothing holding it back
./eve show <key> the task, its dependencies, its claim, its journal
./eve context <key> everything to read before starting (--max-chars)
./eve prompt <key> the same as a ready-to-paste brief (--max-chars)
./eve claim <key> lease it for up to four hours; prints a fencing token
./eve start <key> --token <n> leased → in-progress
./eve note <key> --token <n> --text "…" a journal line and nothing else
./eve renew <key> --token <n> extend the lease (--ttl, at most 4h)
./eve release <key> --token <n> give the lease back; the task returns to ready
./eve park <key> --token <n> --reason <r> --note "…"
park it with a reason and a sentence
./eve unpark <key> back to ready
./eve done <key> --token <n> --commit <full-sha> --evidence "…"
record the completion (below)
Close a task in this order: verify, commit the change with an
Eve-Task: <key> trailer, push it to origin/main, then run ./eve done with
that commit's full SHA. Before it sends anything, done fetches origin main
and refuses a commit that is not an ancestor of origin/main
(commit_not_on_remote; --branch <name> checks another branch). It also
refuses a commit that leaves Eve content the next Dev release checks in a state
this task made incomplete (publication_coupling); ./eve preflight reports
those gaps before you push. Without --commit it records HEAD, or, when
HEAD is a merge, the newest non-merge first-parent commit whose Eve-Task:
trailer names the task. --integrate instead rebases the branch on fresh main,
runs the gates, pushes the branch and main, and records the SHA it pushed.
The evidence is 40 characters to 160 words. The server checks the lease and
token, moves the task to shipped, drops the claim, journals done with the
token, evidence and commit, stores a work product given with --product, and
queues the task for independent review. ./eve reviews shows the feedback; a
returned review puts the task back on offer.
A park needs a live lease and its token, one of the reasons gpu,
hardware, corpus, external, human, governance, release or
upstream, and a note; for gpu, hardware and external the note must name
a failed attempt or something no agent can obtain. It writes the reason and the
note to the database and drops the claim.
./eve verify <key> --expected-version <n> --evidence "…" moves a shipped
task to verified. <n> is the version ./eve show prints; without it the CLI
refuses (missing_version), and a stale one is refused (version_conflict).
Verification is a review action: it needs a credential with the board:review
scope, an independent reviewer's, not the worker's that shipped the task
(select it with EVE_API_CONFIG). The verifier is that credential's identity.
--by <agent> may name it, and a name that is not the credential's is refused
(identity_mismatch). It is also refused when that identity shipped the task.
Reads and reports#
./eve list,search,families,stats,historyandshowread the board through the API../eve boardand./eve filesread the family totals and source-alias counts the database reports../eve checkasks the API'scheckread for the board's integrity results, a page at a time (--limit, default 50, and--offset). It also reports on the Eve graph,eve_graphin the Eve database:graphcounts a live edge whose end is not a live node as a problem (eve-gap-analysis:G01.6), andgraph-rulesruns the shape rules inlib/graph-rules.mjsand prints each rule's offenders as warnings, which never change the exit code (eve-gap-analysis:G11.4). Whereeve_graphis absent both answer "graph not compiled"../eve driftcompares nothing: the Markdown comparison is retired, and it says so../eve advance <family>names the family's one next step, or why there is none../eve releaseslists the release controller's deploys with the tasks each carried../eve graph <query>reads the code graph.
Briefs: context and prompt#
In API mode both are built from the worker API's context read, Eve's content
API for the source document's rules, and the family's autonomy profile, and
both render the same brief. --max-chars is its budget: 20,000 for context
and 12,000 for prompt by default, 500 to 65,536. The brief carries the task
and its body, the family's policy, note and autonomy profile, what it depends
on, the rule sections of its source document, the documents it links, the
related tasks in its section, and the questions asked about it.
Questions to Elikem#
Questions go through one typed queue in the shared board. The three commands need the API; on a local board they exit 2.
./eve ask <key> --concern <kind> --text "…" [--suggest "…"]... [--blocks task|family|review] [--token <n>]
ask; with the token of a task in hand, the task
is parked until the answer comes
./eve answer <question-id> --text "…" the answer (Elikem's Dev session only, from the
mode-0600 file EVE_SESSION_FILE names, holding
"EveSession-dev <token>"; a worker credential is
refused). The task is ready again only when a question
made its current park, once that question and every
other open one blocking the task are answered; a park
made by hand stays. The reply says unparked, and
stillOpen while any remain
./eve questions [--family <id>] [--task <key>] [--open] [--older-than 2h] [--cursor <c>] [--limit <n>] [--json]
the queue, newest first (asked_at, then id), with each
question's age, at most 100 a read; a full page ends
"more: --cursor <c>" (nextCursor in --json), and
--cursor <c> reads the page after it
./eve questions --id <question-id> [--json]
one question whole, whatever its age
The concern is one of low_confidence, contradiction, missing_source,
coverage_gap, ambiguous_scope or blocked_external. After a lost reply,
the same command again reuses the same request.
./eve context and ./eve prompt print a "Questions and answers" section
right after the task, from the task's question-asked and question-answered
journal events: each question with its concern, who asked and when, the
suggested answers, and the answer or "Not answered yet". It carries the task's
newest 50 questions, each with every answer recorded for it, and the question
with the task's newest answer even when it was asked before those 50: that
answer is the one that resumed the agent. When the brief is over its budget,
older questions give way first and the newest answered question stays (the
newest question, when none is answered). If it alone is over the room, its text
and answer are shortened, the answer first, with a note naming
./eve questions --id <its id> --json, which returns it whole. The section
says how many earlier and later questions it left out, and that
./eve questions --task <key> --json --limit 100 lists the task's newest 100,
with --cursor and the read's nextCursor to page back. The cursor is the last
row's asked_at and id, so questions asked at the same instant are neither
skipped nor repeated at a page boundary.
Documents#
In API mode the document readers use Eve's content API:
./eve docs search "<query>" [--kind adr] [--domain isis] [--limit 20]
./eve docs show <document> [--section "<heading>"]
./eve docs history <document>
./eve docs unclassified documents with no kind
./eve docs related <key> what a task names, from its context read
./eve docs stale what changed under the tasks citing it
docs stale reads the change cascade's stale records through the worker API.
docs stale --blame runs the older local sweep instead, dating each citing
line with git blame.
docs build, docs index and docs export --format bff-corpus are local
commands, refused in API mode. They read the repository and write a local
full-text cache (.cache/eve-task-board/knowledge.sqlite), a document catalog,
or the assistant's JSONL corpus.
Many sessions at once#
Several sessions work this board in parallel. The database keeps them apart:
- A task has at most one live claim. Each claim gets a fencing token one higher
than any issued before, and every leased action must present the current
token, so a stale holder is refused (
stale_fence). A lease lasts at most four hours;renewextends it. - Board writes take a PostgreSQL advisory lock, and task definition changes
(
edit,dep,rejectandfamily set) carry an expected version, so a stale edit is refused rather than overwriting. - Every API mutation has a request id. The CLI keeps it in
.cache/eve-task-board/remote-requests/until the server confirms, so running the same command again after a lost reply replays the same request instead of doing it twice../eve remote pending,resume <id>andabort <id>manage those requests. - The API's default allowance is 1,000 mutations per worker identity in any rolling 24 hours.
Exit codes#
| code | meaning |
|---|---|
| 0 | it did what was asked |
| 1 | a refusal: a check failed or a precondition was unmet, with a code, including the other API-only commands (such as reviews, remote, family, releases, advance and soa) run without an API credential |
| 2 | no such command or subcommand, an ambiguous key, or ask, answer or questions without the API |
| 3 | this Node is older than 22.13, checked first on every command |
| 4 | historical Markdown mode only: the tracker changed under the command |
Layout#
| path | what it owns |
|---|---|
cli.mjs |
argument parsing, dispatch and the exit codes |
lib/remote-cli.mjs, lib/api-client.mjs |
API mode: the commands, the HTTPS client, request recovery |
lib/api-operations.mjs, api-server.mjs |
the worker API's reads and actions |
lib/postgres.mjs |
the direct PostgreSQL connection, through a worker thread |
*.spec.mjs |
specs, run by node --test |
This directory is the workspace package @oshun/eve-task-board. Its
package.json declares two dependencies, which pnpm install provides: pg,
which the direct PostgreSQL connection loads, and ioredis, the Redis adapter
the daily family-snapshot run (lib/snapshots.mjs cron) takes its lease
through. API mode needs neither. The original design (no manifest and no dependencies) held while the
board was a SQLite file.
Where its data lives#
- PostgreSQL: the board in the
eve_boardschema, documents ineve_documents, the API's requests, reviews, questions, work products, family snapshots, releases and the rest ineve_api, and the compiled graph ineve_graph. - Local, never committed (
.cacheis ignored): the pending request records above, and the full-text cachedocs buildwrites.
Specs#
node --test tools/eve-task-board/cli.spec.mjs tools/eve-task-board/lib/*.spec.mjs
The PostgreSQL specs run when EVE_POSTGRES_TEST_URL names a disposable
database whose name ends in _test, and skip otherwise; a skipped spec is not
a pass. The 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 new
Node without a test-only switch in the tool.
Historical: the SQLite board and the trackers#
Before the database cutover the board was a committed SQLite file built from Markdown trackers, and several commands served that model. They remain for historical checkouts and fixtures, and none of them is a current workflow:
./eve importread every tracker into the board. It refuses a database-owned board (database_owned)../eve git-setup,merge-driverandresolvemerged the committed SQLite file by task key and gave git a text diff of it (dump). The database needs no file merge.- On that board,
./eve donewrote the checkbox and the evidence into the tracker, and a box checked by hand becameshippedon the next import. ./eve promoteand./eve pulllinked tasks to Eve's workbench queue.promoteis local-only and refused in API mode; it needsOSHUN_WORKBENCH_TOKEN.pullrefuses a database-owned board.