# Eve Task Board — the `eve` command

The board is the backlog of record. This directory reads and writes shared
PostgreSQL through the Node CLI. See
[server and worker setup](../../infra/hetzner/eve/README.md). 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`](../../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.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.
