# Eve Task Board — the `eve` command

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](../../infra/hetzner/eve/README.md)
for the database and the worker API, and the plan behind the tool in
[`TODOS/initiatives/EVE_TASK_BOARD_TODOS_2026-09-18.md`](../../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)

```
./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.

```
./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; `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.
