Eve library

Eve Task Board — the `eve` command

Other

Revision 23

On this page

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 file EVE_API_CONFIG names, or EVE_API_URL with EVE_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_URL or by the file EVE_DATABASE_CONFIG names (default ~/.config/oshun/eve-postgres.json). Workers do not use this path.
  • Historical SQLite. TODOS/eve-task-board.sqlite is 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)#

text
./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, history and show read the board through the API. ./eve board and ./eve files read the family totals and source-alias counts the database reports.
  • ./eve check asks the API's check read for the board's integrity results, a page at a time (--limit, default 50, and --offset). It also reports on the Eve graph, eve_graph in the Eve database: graph counts a live edge whose end is not a live node as a problem (eve-gap-analysis:G01.6), and graph-rules runs the shape rules in lib/graph-rules.mjs and prints each rule's offenders as warnings, which never change the exit code (eve-gap-analysis:G11.4). Where eve_graph is absent both answer "graph not compiled".
  • ./eve drift compares 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 releases lists 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.

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

text
./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; renew extends it.
  • Board writes take a PostgreSQL advisory lock, and task definition changes (edit, dep, reject and family 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> and abort <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_board schema, documents in eve_documents, the API's requests, reviews, questions, work products, family snapshots, releases and the rest in eve_api, and the compiled graph in eve_graph.
  • Local, never committed (.cache is ignored): the pending request records above, and the full-text cache docs build writes.

Specs#

bash
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 import read every tracker into the board. It refuses a database-owned board (database_owned).
  • ./eve git-setup, merge-driver and resolve merged 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 done wrote the checkbox and the evidence into the tracker, and a box checked by hand became shipped on the next import.
  • ./eve promote and ./eve pull linked tasks to Eve's workbench queue. promote is local-only and refused in API mode; it needs OSHUN_WORKBENCH_TOKEN. pull refuses a database-owned board.