Eve library

Eve Task Board — SQLite store, CLI and knowledge index (2026-09-18)

Tracker

Revision 1

On this page

Historical task source. The Eve task board holds current task state.

Owner decision, 18 September 2026: this is the first thing on the Eve Task Board. The worker starts here. Every open task moves into a SQLite database that is committed to git, a command-line tool manages the tasks, TODOS/BOARD.md tells an agent how to use that tool, and the same system makes the repository's specifications, architecture records, research, audits, flows, walkthroughs, Presentation Center slides and Docs Center pages findable from a task.

"The Eve Task Board" is the name for the whole thing — the ranked board in TODOS/BOARD.md, the database behind it and the eve command. "Work the next task on the Eve Task Board" means: run ./eve next, claim what it prints, do it, close it with ./eve done.

0. Decisions this plan rests on#

Taken on 18 September 2026 under the owner's delegation ("make the decision based on what you think is best"); each says why, and what would reverse it.

  1. Not Go. A zero-dependency Node CLI on the built-in node:sqlite. Measured that day: node:sqlite loads without a flag on both Node lines installed here (22.23.1 and 24.14.1; the repo pins 22.13.0 in .tool-versions, the first release where it is unflagged), with SQLite 3.51, FTS5 and JSON1 compiled in. Every machine and agent that works in this repository already runs Node — tools/todos-board.mjs is dependency-free for exactly that reason — so there is nothing to install and nothing to compile. Go would give one static binary per platform, but "an executable we can put in git" means committing about 10–15 MB per platform (darwin-arm64, linux-amd64, linux-arm64, windows) again on every change to the tool, which no reviewer can diff and every agent would execute on trust; Go is not installed on either machine and is not one of the repository's languages (CLAUDE.md: TypeScript by default, Rust for performance-critical systems, and 13,000 rows is not performance-critical). Reverse this only if a machine without Node must run the tool; then package the same code with Node's single-executable support rather than rewriting it.
  2. The database is committed, and it is made safe to merge. The owner asked for a SQLite file in git. Two sessions pushed to main while this plan was being written, and a binary file conflicts on every such merge, so the tool ships a row-level three-way merge (git merge driver plus a manual ./eve resolve), a text diff for review (textconv), and the file is kept lean: open work and its journal only, no full-text index inside it, never VACUUMed on an ordinary write, rollback-journal mode so no -wal file is ever committed. Size budget: 25 MB, enforced by a check.
  3. The markdown trackers stay, and the tool writes through to them. 2,582 files reference ISIS_TODOS_2.md alone; the workbenches ledger has a structure lint, the presentation plan has a crosswalk check, and every tracker carries evidence prose worth keeping in a diff. The database owns the workflow state — order, claim, parked reason, dependencies, journal — and ./eve done also flips the [ ] in the tracker and appends the evidence there, one task per call. A tracker can retire its markdown later, family by family, once nothing reads it.
  4. One vocabulary with Eve's workbench, not a second queue. Eve already has governed work items in Postgres (work_item, statuses draft → triaged → ready → leased → in-progress → in-review → shipped → verified, parked, rejected), leases with fencing tokens (apps/oshun/bff/src/workbench/ queue-semantics.ts), an MCP server for coding agents (tools/workbench-mcp/server.mjs) and a verifier that alone may say verified. The board is the backlog of record in git; a workbench work item is one governed execution of a board task. The database uses the same status names, the CLI's offline claim copies the lease-and-fence rules, and ./eve promote and ./eve pull connect the two (section 10). When the BFF is up, its queue is the lease authority.
  5. Documents are indexed, not moved. The tracked markdown alone is 11,464 files and 136 MB (docs/domains 86 MB, docs/audits 120 MB with evidence, docs/agents 76 MB, V2 54 MB); the Presentation Center's slide content is 6 MB of JSON and the Docs Center is generated. Moving prose into a database would break every path reference, the two generators and git blame. The database carries a catalog (one row per document: path, kind, title, domain, headings, summary, hash) and the links between tasks, documents and code; the full text lives in a second SQLite file that is a local cache, never committed, rebuilt from the files in about a minute. ./eve context <task> hands an agent the documents a task depends on.

1. Rules for this initiative#

  • The tool lives in tools/eve-task-board/ as dependency-free ES modules. Specs are *.spec.mjs run by node --test; no build step, no node_modules.
  • Nothing here checks a box from a count, a grep or a test total. ./eve done takes one task id and an evidence text and refuses anything else; .claude/rules/task-checkbox-verification.md still governs what evidence is.
  • Install what the work needs (owner instruction, 18 September 2026): this tool needs only Node, but every task it hands out is worked under that rule, and ./eve park enforces it (ETB.4.04).
  • Every command has --json; every refusal has a code and a sentence. No command prints a success it did not perform.
  • ./eve next, ./eve board, ./eve check and ./eve files work at every commit. TODOS/BOARD.md and CLAUDE.md tell every agent to run them, and the first CLI commit took them away for an afternoon because the shim handed everything to a CLI that did not have them yet (fixed 18 September 2026; the plan had not said this, which is why it happened). The shim now falls back to tools/todos-board.mjs for those four whenever the CLI answers exit 2, and tools/eve-task-board/shim-bridge.spec.mjs pins that. So: keep exit 2 meaning "this command is not built", build next (ETB.3.01), check (ETB.1.05) and board (ETB.5.02) so that each does at least what the bridge did when it takes over — check must still validate TODOS/registry.json until the trackers stop being the source — and give files a home before ETB.10.03 removes the bridge.
  • Task ids are the ETB.n.nn in bold, not the section numbers, which run one ahead (section 4 holds ETB.3.x). The CLI's PLANNED map names the wrong task in most of its refusals (claim says ETB.3.02, which is show). The right ones: import ETB.2.01, next ETB.3.01, show ETB.3.02, claim ETB.4.01, done ETB.4.03, park ETB.4.04, check ETB.1.05, drift ETB.5.01, board ETB.5.02, merge-driver and resolve ETB.6.02, docs ETB.8.07, context ETB.8.08, promote ETB.9.02, pull ETB.9.03. Correct the map, and the assertion in shim.spec.mjs that pins claim to ETB.3.02, with the next CLI commit. (Found 18 September 2026 by the session that wrote this plan; left to the session that owns cli.mjs so the two do not edit it at once.)
  • Evidence for a checked box here: the spec file, its pass count, and the command that was run. Short. Commit and push after every completed item (git push origin <branch> then git push origin <branch>:main).

2. Package, schema and the shim#

  • ETB.1.01 Create tools/eve-task-board/ with cli.mjs (argument parsing and dispatch only), lib/db.mjs (open, pragmas, migrations), lib/paths.mjs (repository root by walking up to pnpm-workspace.yaml; database at TODOS/eve-task-board.sqlite; cache at .cache/eve-task-board/), and README.md. node tools/eve-task-board/ cli.mjs --version prints the tool version and the SQLite version and exits 0; an unknown command exits 2 with the command list. On a Node older than 22.13 it exits 3 with the sentence "needs Node 22.13 or newer for node:sqlite". Verify: tools/eve-task-board/cli.spec.mjs covers the three exits. DONE 2026-09-18. node --test tools/eve-task-board/cli.spec.mjs tools/eve-task-board/lib/paths.spec.mjs tools/eve-task-board/lib/db.spec.mjs → 18 pass, 0 fail, and ./eve --version now routes through the shim to the CLI: eve 0.1.0 (node 24.15.0, sqlite 3.51.3). THE THREE EXITS ARE DRIVEN, NOT ASSERTED ABOUT. run() takes argv, the Node version and two writers as arguments, so exit 3 is exercised for real on a machine running Node 24 — run({nodeVersion: '22.12.0'}) answers 3 and the exact sentence. The alternative was an environment variable the CLI honours, which is a test-only backdoor in a tool that refuses things for a living. Exit 2 distinguishes "not a command" from "not built yet — it is ETB.3.02", because a caller acts differently on each. TWO THINGS MEASURED WHILE BUILDING IT, both of which changed the code: - DatabaseSync HAS NO create OPTION. Passing create: false for a missing path opened it and created the file anyway (Node 24.15), so the parameter would have been one the library ignores. The refusal is ours now, and a spec asserts the file is not created. - THE NODE GATE HAS TO PRECEDE THE IMPORT. node:sqlite is imported dynamically, in lib/db.mjs and nowhere else, because a static import would throw on an old Node before the version message could be printed — the message would have been unreachable exactly when it was needed. No package.json in the directory, deliberately: tools/* is a pnpm workspace glob and one would make this an installable package, which the initiative's first rule forbids. The version is a constant in cli.mjs. Every pragma is read back after it is set, and the foreign-key spec inserts a dangling row and requires the error — a pragma that did not take is silent in SQLite.
  • ETB.1.02 Finish the shims. ./eve (POSIX sh, mode 755) and eve.cmd exist since 18 September 2026 as a bridge: they find Node (also under ~/.nvm when it is not on a non-interactive PATH), hand every call to tools/eve-task-board/cli.mjs once that file exists, and until then map next, board, check and files onto tools/todos-board.mjs and refuse anything else with exit 2. Keep that behaviour, add the script "eve": "node tools/eve-task-board/cli.mjs" to the root package.json, and make eve.cmd pass every argument through. Verify: ./eve --version and pnpm eve --version print the same line; a spec runs the shim through child_process from a subdirectory and with a PATH that has no node on it. DONE 2026-09-18. node --test tools/eve-task-board/shim.spec.mjs → 6 pass, 0 fail. ./eve --version and pnpm eve --version print the same line — the spec compares them rather than trusting it: pnpm writes its own line first, so the tool's is the last non-empty one. THE NVM SEARCH IS TESTED AGAINST A TREE THE SPEC BUILDS, not against this machine. Asserting "it works here" would pass on any machine with node on PATH, which is every machine that could run the assertion — so the spec points HOME at a temporary directory whose only node is an nvm-shaped symlink, runs the shim with PATH=/nonexistent-bin, and gets the version line back. With an empty HOME too, it gets exit 3 and node is not installed or not on PATH. AND THE SPEC CHECKS WHICH HALF ANSWERED. ./eve claim comes back with the CLI's refusal (it is ETB.3.02 on the Eve Task Board) and NOT the bridge's older sentence, which is how a reader knows the dispatch happened rather than the fallback. The bridge is kept, as this item asks: five todos-board.mjs calls still stand behind a missing cli.mjs. eve.cmd now forwards %* to the CLI and forwards arguments in every bridged branch — the first version passed %2 %3 and dropped the rest. It is REVIEWED, NOT RUN: both machines here are Linux, so a spec asserts on its text (that %* reaches the CLI, that no %2 %3 survives, that all four bridged commands are present) and says why that is all it can do. ./eve is mode 755 in git (100755) and eve.cmd is 644.
  • ETB.1.03 Write tools/eve-task-board/schema.sql and apply it through numbered migrations keyed on PRAGMA user_version. Pragmas on every open: journal_mode=DELETE, foreign_keys=ON, page_size=4096 (at creation), synchronous=FULL. Tables: meta(key, value); families(id, title, kind, priority, rank, status, focus, note, position); tasks(key PRIMARY KEY, family_id, ext_id, title, status, parked_reason, position, section, source_path, source_line, source_hash, created_at, updated_at, version); task_body(task_key, body); task_deps(task_key, depends_on, kind); task_links(task_key, target_kind, target, note); claims(task_key, agent, fencing_token, acquired_at, expires_at); events(id, task_key, at, actor, type, data); documents(path PRIMARY KEY, kind, title, domain, release, headings, summary, sha256, bytes, committed_at); doc_links(from_path, to_kind, to_target). Status is one of ready, later, parked, leased, in-progress, shipped, verified, rejected (the workbench's words; later is the board's own), enforced by a CHECK. Verify: lib/db.spec.mjs creates a database, reads user_version, rejects a bad status, and re-opens an existing file without re-running a migration. DONE 2026-09-18. node --test tools/eve-task-board/lib/db.spec.mjs → 14 pass, 0 fail, covering all four: openBoard creates the ten tables and user_version reads 1; in_progress and done are refused by the CHECK while all eight real statuses insert; and a re-open applies nothing ({from: 1, to: 1, applied: []}) with its rows intact. EVERY CLOSED VOCABULARY IS A CHECK, AND EACH IS COPIED RATHER THAN INVENTED: tasks.status is the workbench's eight words plus the board's later; tasks.parked_reason is registry.json's eight blockers; families.kind, status and priority are the registry's own three lists. A CHECK and not application validation for one reason this file has and most do not — it is committed and merged by a row-level driver, so a row can arrive from another branch without passing through any of this tool's code, and the constraint is the only thing that sees it either way. TWO COUPLINGS THE SCHEMA ENFORCES that a column list does not imply: a task is parked exactly when it names a reason (both halves refused: parked with no reason, and a reason on a ready task), and a claim's window must end after it starts. events.data takes JSON or nothing, checked with json_valid. AND ONE DELIBERATE NON-KEY: task_deps.depends_on is not a foreign key. A tracker states dependencies on ids that are not imported yet, and dropping those is how a dependency graph quietly loses an edge — ETB.2.05 keeps them and a check reports them. task_key <> depends_on is enforced. Tables are STRICT, ids are the trackers' own text (ETB.1.03, M10.19.a), and a surrogate integer would have made every reference in 11,464 markdown files a join nobody can follow by eye. schema.sql is read from disk by migration 1 rather than embedded, so the DDL is reviewable as SQL — and its sha256 is PINNED by a spec, because a shipped migration is not edited: a change to the schema is migration 2 onward.
  • ETB.1.04 Make writes small and repeatable: every mutating command runs in one transaction, updates tasks.version and updated_at, appends one events row, and never issues VACUUM. Timestamps are UTC ISO strings passed in by the caller of the library function, so specs can fix the clock. Verify: a spec applies the same three commands to two fresh databases with a fixed clock and compares ./eve dump --stable of both byte for byte. DONE 2026-09-18. node --test tools/eve-task-board/lib/write.spec.mjs → 10 pass, 0 fail, and the comparison is the command and not the library: two real files, two child processes, ./eve dump --stable --file <path> on each, stdout equal byte for byte. lib/write.mjs is the only way this tool writes. mutate() opens one transaction, runs the change, bumps version and updated_at, appends exactly one events row, and commits — so no command can change a task and leave its version where a merge would read it as untouched. A failure rolls back both halves: the spec breaks a write mid-way with a status the CHECK refuses and asserts the dump is byte-identical to before. THE CLOCK IS AN ARGUMENT AND IS VALIDATED. instant() refuses anything that is not a UTC ISO string — a local time, an offset time, a number of milliseconds — because those are exactly the values that would make two runs of the same commands differ in the fields a merge has to reason about. A write with no actor or no type is refused too. dump gained --file, and not for the spec: git's textconv hands a driver a TEMPORARY COPY of the blob it renders (ETB.4.03), so a dump that could only read the board's own path could never be the diff driver. --stable omits the file line and prints a row count instead, which is the one thing two databases in two temporary directories differ by — the spec asserts they differ WITHOUT the flag and match with it, so the flag is not decoration. Nothing issues VACUUM, asserted over the package's own source rather than by reading it once: a vacuum rewrites every page, and a committed database would show a whole-file diff for a one-row change. One refusal shape for the whole CLI, added here because dump was the first command that could fail: an error carrying a code becomes eve: <code>: <sentence> (or {"error":...} with --json) and exit 1, while anything without a code is left to crash — a tool that turned its own defects into tidy exit codes would be hiding them.
  • ETB.1.05 ./eve check: PRAGMA integrity_check, foreign keys, every task's family exists, no two tasks share a key, no expired claim left on a leased task, file size under the 25 MB budget. Exit 1 with one line per problem. Verify: spec plants each defect in a copy and asserts the line and the exit code. DONE 2026-09-18. node --test tools/eve-task-board/lib/check.spec.mjs → 8 pass, 0 fail; 49 across the package. Each defect is planted in its own copy and the assertion is the line and the code: a missing family (two lines — SQLite's own reference check and the board's), an expired lease on a leased task, a board over a budget the spec sets below the file's size, and a corrupt file. The command exits 0 with eve check: 6 checks, clean and 1 with one line per problem on stderr and nothing on stdout. THE PLAN'S EXPECTATION ABOUT CORRUPTION WAS WRONG TWICE, AND BOTH MEASUREMENTS CHANGED THE CODE: - on a board of 37 pages, damage to ANY page (1, 2, 3, 5 and 8 tried) fails the OPEN with database disk image is malformed, because SQLite walks sqlite_master before the first statement and this schema spans pages. So PRAGMA integrity_check is not the corruption detector it looks like; - on a smaller board the open survives and the pragma THROWS rather than returning a row that says ok is false. A check command that propagated that would crash on exactly the file it exists to examine. So every one of the six questions is now asked inside a guard and a throw becomes its problem line, and the CLI turns an open that fails into the same shape. check is total: it answers about any file it is given. TWO HONEST NOTES ON THE SIX. "No two tasks share a key" cannot happen while the PRIMARY KEY holds — SQLite refuses the insert, and the spec asserts that refusal rather than pretending to plant a duplicate. It is asked anyway because a damaged index is exactly the state where it could, and a check that only asks what the schema guarantees is the one that catches the day the schema stops holding. And the expired-claim question needs a clock, so it takes now as an argument: the spec asserts the same rows are clean before the expiry and reported after it. --file is accepted here as it is on dump, so a reviewer can check a stashed or merged-in copy. The size budget is the plan's 25 MiB. AND ONE REGRESSION THIS ITEM NEARLY SHIPPED, caught by another session's shim work arriving in the same hour. ./eve check is the command TODOS/BOARD.md §6 tells every agent to run after editing a tracker, and it has always meant "validate the registry against the tree". The moment the CLI answered check with 0 or 1 the shim stopped falling through — by design, and their shim-bridge.spec.mjs asserts exactly that — so the documented command quietly became no_database. check now does BOTH: the registry check first, forwarded verbatim (its summary goes to stderr, which is where the spec asserts it and not where it would be tidier), then the board's six questions when a board exists. With --file only the named board is asked, because a reviewer checking a stashed copy is not asking about the tree; and a board file that does not exist yet is a NOTE naming ETB.2.01, not a failure, since otherwise every agent's check would fail today. 55 specs across the package, the other session's five included.

3. Importing the open tasks from the markdown trackers#

  • ETB.2.01 lib/import.mjs: read TODOS/registry.json and scan every tracked markdown file with scanMarkdown from tools/todos-board-lib.mjs (it already returns each open item with its heading path, line, text and blocked: reasons, and the board's working order). Import work kinds only (tracker, coverage, gate). Families come from the registry rows unchanged. Verify: on a fixture tree of three trackers the importer creates the families and the right number of tasks, and importing twice changes nothing (events gains no row). DONE 2026-09-18. node --test tools/eve-task-board/lib/import.spec.mjs → 11 pass, 0 fail; 66 across the package. The fixture is three trackers — a family in one file, a family over two, and a family the registry marks blocked — and the importer writes 2 families and 6 tasks from 7 boxes, leaving the checked one out. A second import returns {families: 0, tasks: 0, unchanged: 6} and neither events nor the sum of tasks.version moves. NOTHING RESCANS. lib/tree.mjs builds the SAME model tools/todos-board.mjs builds — scanMarkdown, classify, compileRegistry, buildModel — and reads the answers off it. A second scanner would be a second answer to "how many open tasks are there", and the first symptom of that is a board and a database that disagree by four. It is also what makes .04's verification possible at all. ON THE REAL TREE: 35 work families, 905 files, 24,472 tasks — 13,826 ready, 8,605 later, 2,041 parked, with the parked reasons spread over all eight vocabulary words (release 1,381, external 211, upstream 142, hardware 91, human 86, governance 77, corpus 52, gpu 1). A re-import writes 0 and reports 24,472 unchanged. AND ONE THING THE PLAN WILL HAVE TO DECIDE, measured rather than argued: the board is 26.51 MB, over decision 2's 25 MiB budget, and ./eve check says so. The composition, so the choice is informed: the bodies are only 5.07 MB of text; the tasks table is 11.85 MB, its five indexes 7.84 MB, task_body 6.72 MB. Inside tasks, section is 2.65 MB across 24,472 rows for 4,091 distinct values and source_path 1.15 MB for 905 — normalising those two into their own tables is a migration 2 that would save about 3.3 MB of text plus index pages, and it is a change to a schema ETB.1.03 shipped, so it is the owner's call and not this session's. The file is therefore NOT committed yet; ./eve import rebuilds it in three seconds.
  • ETB.2.02 Give every task a stable key. Take the external id from the item's text when it has one — patterns present in the repository: **T.19.01**, **EI.1.01**, **ETB.1.01**, BASE.2.b, I0.20.a, V1-P2-3403, **182.C.33.01**, **27.20.1.1**, YSD-16065, 5.13 (Eve SOTA) — and form <family-id>:<ext_id>. An item with no id gets <family-id>:<file-slug>-<first 8 hex of sha256(heading path + text)>. A duplicate key inside one family is a refusal that names both lines. Verify: spec with one item per pattern, two items without ids, and a duplicate; then run the importer over the real tree in dry-run mode and record in the evidence how many tasks have no external id, per family. DONE 2026-09-18. Eleven shapes assert by value, including the two the plan did not list and the real tree found: - 29.19.1.10.a. With digits only after the first dot, the pattern captured 29.19.1.10 and COLLIDED WITH ITS OWN PARENT — phase 29 lines 2525 and 2528 — and the importer refused the whole tree over it. Alphanumeric tails now. - 5.5" iPhone (1290x2796 or 2796x1290). A screen size in an app-store checklist captured 5.5 and collided with that same file's section 5.5. A token now has to END at whitespace or punctuation, because a word boundary is not enough: a quote mark is one. Both were found by running the importer over the real tree, not by reading it. The bold-anchored patterns never see a real item — scanMarkdown hands over plain text with the emphasis stripped — and the code says so rather than leaving four dead patterns looking load-bearing. A DUPLICATE IS A REFUSAL THAT NAMES BOTH LINES, raised before the transaction opens so nothing is written. DRY RUN OVER THE REAL TREE (./eve import --dry-run): 35 families, 905 files, 24,472 tasks, of which 14,304 carry no external id — 58%. The count is dominated by the coverage families, which are checklists of screens rather than numbered work: walkthrough-studio 5,224, walkthrough-customer 2,140, presentation-center-eve-redesign 1,503, walkthrough-web-other 1,333, walkthrough-admin 706, store-submission-gates 664, launch-gates 553, presentation-center 402, v2-fighter-signature-checklists 300, walkthrough-mobile 264, v2 225, walkthrough-tenant-admin 198. Those tasks are keyed on a digest of their heading path and text, which is stable while the item is and changes when somebody rewrites it — the honest answer, because nobody can say the work is the same.
  • ETB.2.03 Carry the item's full text: title is the first sentence (capped at 200 characters), task_body.body is the item with its indented continuation lines, HTML evidence comments included. Record the source anchor (source_path, source_line, and source_hash, the sha256 of the item's exact lines) so a later write can prove it is editing the same item. Verify: spec over a wrapped item with a nested note and an HTML comment; the body round-trips exactly. DONE 2026-09-18. The body is the checkbox line plus every line indented under it, verbatim: a continuation line and an HTML evidence comment both survive, and the extraction stops at the next checkbox so a sibling is never swallowed. A blank line inside an item's continuation is kept; a blank line followed by something at or left of the item's own indent ends it. The spec round-trips the stored body against bodyOf over the file on disk and asserts source_hash is the digest of exactly those lines — sourceHash(body) differs from sourceHash(body + ' '), which is what a later write-through needs to prove it is editing the same item. title is the first sentence, capped at 200 characters, with the id's emphasis unwrapped.
  • ETB.2.04 Map state: a blocked:<reason> tag → parked with parked_reason (first tag; further tags in task_links as blocked-also); an item in a registry deferred section → later; a family the registry marks blocked → every task parked with the family's blocked_by; everything else → ready. A box with any other mark (the scanner counts them as offVocabulary; [~] was the common one and was converted in V1, V2, V4 and V7 on 18 September 2026) is not a state this board has: the import refuses a work-kind file that still carries one and names it, rather than leaving its tasks out. position is the board's working order (queue selectors first, then file order). Verify: the per-family counts of ready, later and parked equal the Actionable, Later and Parked columns of TODOS/board.json generated from the same tree, for every family; the spec fails on any difference. DONE 2026-09-18, and it agrees on all 35 work families — ready, later and parked against board.json's Actionable, Later and Parked, with the spec failing on any difference. It can only agree because nothing here decides the states independently: the model's ordered list IS the ready set in working order, item.reasons is what parks one, and an open item in neither is in a section the registry defers. selectorMatches is private to the board library, and re-implementing it would have been a second answer to "which section is deferred". A SECOND TAG IS KEPT, NEVER DROPPED: the first goes in parked_reason and the rest into task_links as blocked-also. AND THE REGISTRY'S BLOCKER IS A TOKEN PLUS PROSE, which the first run got wrong. blocked_by reads 'human — 7.2 and 8.1 need the operator to label the 42-transcript sheet…', the whole string went into parked_reason, and the schema's CHECK refused the entire import — the constraint doing its job. The token is taken now and an unrecognised one is a REFUSAL naming the family, not a fallback: labelling somebody's blocker upstream because it was not recognised would put a wrong word in every parked row of that family. A blocked family covers its items whatever they say, which the fixture proves with a family blocked on human — and that case is how a silent ?? 'upstream' default was caught, because plan() had dropped blocked_by on the way through.
  • ETB.2.05 Extract dependencies that the trackers already state: "Depends on 5.24, 5.26, and 13.3." (Eve SOTA), "blocked:upstream" bodies that name an id, "starts only after <id>" phrases, parent/child nesting (a child I0.20.a depends on nothing, its parent depends on its children). Unknown targets are kept as text in task_links with kind unresolved-dep, never dropped. Verify: spec on the Eve SOTA fixture: the importer finds the same dependency pairs the 2026-09-18 audit found (0 dangling in that file) and flags a planted dangling one. DONE 2026-09-18: tools/eve-task-board/lib/deps.mjs, 13 specs in lib/deps.spec.mjs, 82 in the family. Over the whole tree: 270 stated edges, 7,298 parent edges, 56 of them onto prerequisites that are already checked, 1 dangling, 0 cycles. The five phrasings are the ones the repository uses, counted over every tracked markdown file with whitespace collapsed first (so a phrase wrapped across two lines still counts): "depends on" 96, "waits on" 30, "requires" 11, "only after" 8, "starts only after" and "prerequisite" 1 each. THREE MEASUREMENTS CHANGED THE CODE, and each one had produced a plausible wrong answer: (1) a span pattern [^.;]+ after the phrase stops at the first dot — which is INSIDE 5.5 — so the first version found 0 dependencies in a file that states 96; the list is walked id by id instead. (2) Alternation is ordered, so \s*,\s* beat \s*,\s*and\s+ and 5.5, 5.24, 12.10, and 14.7 read as three ids — the last id of every Oxford-comma list in the trackers was being dropped. (3) A dependency on a CHECKED item is satisfied, not dangling: without the shipped-id list the audited file reported 44 dangling where the audit found none, and that number would have been a count of finished work. Two over-reads were then found by asking the graph questions the item did not ask: all 3 dangling dependencies in the whole tree were ONE ITEM QUOTING ANOTHER TRACKER — this item's own "Depends on 5.24, 5.26, and 13.3." (Eve SOTA) — so a phrase inside a balanced "…" span is an example, not a statement; and the only cycle in 7,571 edges was 29.18.6.1 -> 29.18.6.6 -> 29.18.6.1, two items citing each other's notes while both actually depend on 29.18.6.11, so a §-prefixed id is a cross-reference to the tag source (4,228 of them exist and exactly ONE follows a dependency phrase, which the phrase path now reads). AN upstream TAG RESOLVES OR IS DROPPED, and a stated phrase does not: the registry defines upstream as "Depends on another item", so the ids in such a body are prerequisites (148.8.14 says only "follows the model of 148.8.4", with the tag and nothing else), but they are read out of prose written for a human — SI-SDR and MUSDB18 sit in one such body — so an id-shaped token that matches nothing there is prose, while a broken "Depends on 9.9" is a claim the tracker made and is reported. The one dangling dependency left in the tree is real: V1-P2-6006 states "depends on §18.6", a section of the V1 spec and not an item in its family. The dependency diff is over the WHOLE import, not the changed tasks, because resolution is a property of the set — an id dangles until the item naming it is imported, and the item that states it has not changed a byte; a spec drives exactly that. ./eve check gained a seventh question, dependency, because ETB.3.01 orders this graph and the next cycle will not announce itself; three specs cover a planted cycle, a leaf edge onto a never-imported id, and a diamond (which a naive visited-set walk would call a cycle).
  • ETB.2.06 Re-import is an upsert that follows a moved item: match by key; when the key is absent but source_hash matches a task in the same file, treat it as the same task on a new line; when the text changed under the same key, update title and body and journal edited-in-markdown; when a box became [x] in markdown, mark the task shipped with actor markdown and the commit that did it (git log -1 --format=%h -- <file>); when an item disappeared, mark it rejected with reason removed-from-markdown. It never sets [x] anywhere. Verify: spec for each of the five cases. DONE 2026-09-18: lib/reimport.spec.mjs, six specs — one per case plus the prohibition — over a fixture that is a REAL GIT REPOSITORY, because case 4 records the commit that checked the box and a commit is not something to stub. 88 specs in the family. TWO OF THE FIVE CASES ARE THE SAME ABSENCE, and that is the whole difficulty: a task the board holds and the markdown no longer offers was either checked or deleted, which are opposite outcomes. Telling them apart needs the CHECKED items' identities, so scanMarkdown now also reports doneItems in the same shape and from the same accumulation as the open ones (tools/todos-board-lib.mjs), and the importer applies the same taskKey to them — a second implementation of "which item is this" in the importer would have been a second answer. The board's generated files are byte-identical after that change, commit stamp aside. A MOVE RENAMES THE ROW, IT DOES NOT REPLACE IT: an id-less item's key is a digest of its heading path and text, so moving it between sections gives it a key the board has never seen, and a new row would have cost the claim somebody is holding and every journal row the item had — the spec plants a live claim and asserts it survives. The rename needs PRAGMA defer_foreign_keys, because all five child tables reference tasks(key) and none declares ON UPDATE CASCADE, so with immediate enforcement the parent update fails against its own children. CASE 1 FOUND A LIVE DEFECT: source_hash is over the item's own lines, so an item that shifts two lines down when somebody adds a paragraph above it has the SAME hash, and the write filter — which asked only about the hash — left source_line at its old value. The board's whole contract with a worker is path:line, and ETB.2.03's write-through edits that anchor, so a stale line is a wrong answer and then a wrong edit. The filter now compares every column the upsert writes, and edited-in-markdown stays keyed on the TEXT changing, because an item that only moved down the file was not rewritten and saying so would be false. A CLOSURE IS ATTRIBUTED TO markdown, NOT TO THE AGENT RUNNING THE IMPORT: nobody here did that work, and putting this tool's name on every closure in the repository's history would be a lie the journal cannot take back. The prohibition is verified the only way it can be: the whole markdown file is compared byte for byte after an import that ships one item, rejects another and edits a third, and git status --porcelain is asserted empty. CORRECTED 2026-09-19, and the correction is the important half of this item. A merge brought three new families into TODOS/registry.json and a batch of tracker edits, and the next import marked 110 tasks rejected with reason removed-from-markdown — about 95 of which were still in the markdown: 18 whose file the registry had RECLASSIFIED into phase-180-remote-control (a key is namespaced by family, so renaming the family renames every key in the file and touches no markdown at all), and 91 id-less items whose key is a digest of the heading path AND THE TEXT (ETB.2.02), so any edit rekeys them by design — 77 of those still had their exact title live in the same file. A FALSE rejected IS THE WORST RECORD THIS IMPORTER CAN WRITE: it says a human deleted work that nobody deleted. Case 2 is now a LADDER, most certain first and each rung exact rather than approximate: same file and same source_hash (byte-identical, so it only moved); same file and same key SUFFIX (the part after family: is what the tracker wrote, and it is family-independent for an id and a digest alike, so this is a reclassification and nothing else); same file, same heading path and same title (an id-less item edited under its digest). Rung 3 is the only one that could conflate two items, so it is required to be ONE-TO-ONE — two items sharing a first sentence share a title, and when both are replaced by a third with that sentence the board says both are gone rather than inventing a pairing, which a spec drives. Two byte-identical id-less items cannot arise at all: they share a digest key and ETB.2.02 refuses the import, which that spec found the hard way. The journal names WHICH RUNG matched, because "the same item under a new key" is three different events and a reader should not have to guess. The board was rebuilt from scratch afterwards — it is a derived artefact and a rebuild costs 3.7 s — so the 110 false rows are gone rather than corrected in place: 0 rejected, 13,459 ready, 9,068 later, 2,334 parked. AND THE SAME MERGE FOUND AN ID-SHAPE DEFECT: docs/releases/v1/specs/todos-p2.md gained 23 children of the form V1-P2-3516.a, each of which captured V1-P2-3516 and collided with its own PARENT, so the importer refused the whole tree — the second time that exact shape has bitten after 29.19.1.10.a on 2026-09-18. The hyphenated id pattern now takes a dotted tail, and the token must still end at whitespace or punctuation so V1-P2-3403. Wire the thing takes none; two shapes were added to ETB.2.02's spec.
  • ETB.2.07 First real import. Run it over the repository, commit TODOS/eve-task-board.sqlite, and record in the evidence: task count per kind, the count cross-check of ETB.2.04, the number of id-less tasks, the file size, and the wall time. Verify: ./eve check is clean and ./eve stats --json equals TODOS/board.json for every family. DONE 2026-09-18. 35 work families, 905 files, 24,584 tasks — 13,475 actionable, 8,999 later, 2,110 parked — 7,582 dependency edges, 10,252 tasks carrying an external id of their own, 24,911,872 bytes, 3.7 s wall. (24,583 after this item's own box was checked, which the import then marked shipped with actor markdown — ETB.2.06's case 4, on the real tree rather than a fixture.) ./eve check prints 7 checks, clean, and ./eve stats --json agrees with TODOS/board.json on actionable, later, parked and open for all 35 families, 0 disagreements — a comparison that is now a spec over a FRESH import rather than a one-off reading, because the committed file is a snapshot and the agreement is a property. IT IS ALSO A DIFFERENT QUESTION FROM ETB.2.04's: that spec compares two computations over the same tree and would agree with itself if both were wrong the same way, while this one compares what actually LANDED in a database — a task written twice, a status a CHECK quietly refused, a family dropped by the write filter. THE BUDGET WAS MET BY MEASURING WHERE THE BYTES WERE, not by raising it. The first import came to 29,745,152 bytes against decision 2's 25 MiB (26,214,400) and ./eve check said so. dbstat found the same 907 file paths stored 24,584 times in tasks and again in tasks_by_source (1.70 MB), and 4,130 heading paths stored 24,584 times (2.79 MB), so migration 2 gives files and sections their own tables and saves 4,833,280 bytes — lossless, reversible, every value still there once, with a task_text view putting the text back so nothing that reads a task joins by hand and no dump shows an integer where a path belongs. The alternatives were measured and rejected: dropping the bodies loses the 5.41 MB the plan wants a worker to read, splitting task_body into a second committed file (ETB.6.05's fallback) moves the same bytes rather than saving any and is reserved for a growth measurement, and raising the budget changes a decision instead of meeting it. THIS IS THE ONE THING IN THIS ITEM AN OWNER MAY WANT TO OVERRULE: ETB.2.01's evidence called the normalisation the owner's call, and it was taken here because the plan's own budget is a stated constraint, because schema.sql's header says a schema change is migration 2 onward, and because the change is reversible — the column was renamed as well as retyped (source_file, not source_path), so a query written for the old shape fails loudly instead of comparing a path to an integer and quietly matching nothing. Four spec fixtures were caught that way. ./eve stats is ETB.3.03's command and is built here in the minimal form this item's verification names; ETB.3.03 extends it with list and families. .gitignore gains one negation, because *.sqlite is ignored repository-wide and this board is the exception decision 2 asks for. AND THE FIRST RE-IMPORT FOUND A SECOND DEFECT, which only the real tree could show: checking one box rewrote 11,148 of 24,584 rows. The fallback position — the one an item gets when it is not in its family's working order — was a counter running across every file, so removing one item renumbered everything after it. For a committed binary merged by a row-level driver that is 11,148 rows of churn in the pack and in every conflict, for one closure. A position is now family-local, after that family's ordered items in file order, and the same closure rewrites 325 rows — exactly the one family it belongs to.

4. Reading the board from the command line#

  • ETB.3.01 ./eve next [--family <id>] [-n <count>]: the next ready tasks in working order whose dependencies are all shipped or verified and that nobody holds a live claim on; default family is the first with such a task; default count 1. Output: key, title, source_path:line, section. Verify: spec with a dependency chain, a claimed task and a parked task; --json is parseable and carries the same fields. DONE 2026-09-18: lib/next.mjs, 10 specs in lib/next.spec.mjs, 100 in the family. On the committed board ./eve next answers eve-task-board:ETB.3.01 — this item — and --json carries exactly the same seven fields the text line does, which the spec checks by rendering both and comparing them, not by reading the code. THE DANGEROUS DIRECTION IS OFFERING TOO MUCH, so every exclusion has its own spec: a chain of three is handed out from its end and only advances when a link reaches shipped or verified; a parent waits for ALL its children (one child done is not the parent's turn); a live claim withholds a task and an expired one does not; and later, parked, leased, in-progress, shipped and rejected are none of them on offer. A PREREQUISITE WITH NO TASK ROW IS FINISHED, NOT MISSING, and that is the one case that would have been silently wrong in the other direction: the only way task_deps.depends_on names something the board does not hold is the way the importer puts it there — a prerequisite CHECKED in the markdown and so never imported (ETB.2.05) — because an id that resolves to nothing becomes an unresolved-dep link instead and a cross-family id never becomes an edge. A JOIN there would have hidden every task whose prerequisites are all done, and the board would have gone quiet with work available. The default family is the first WITH something to offer rather than the first family, because a P0 family whose every ready task waits on a dependency would otherwise answer "nothing" for the whole board; a spec drives exactly that arrangement. AND NOTHING IS COUNTED, NOT GUESSED: an empty answer names the family and prints how many of its tasks are open, ready, held by a live claim and waiting on a dependency, because a worker told only "nothing" goes looking for a bug in the tool. One defect was found by the spec and it was in a count: whyNothing's dependency query bound the clock to a statement with one placeholder, and node:sqlite refused it with "column index out of range" — a dependency's status is not a question about the clock.
  • ETB.3.02 ./eve show <key>: title, status, family, section, body, dependencies with their status, tasks that wait on it, documents linked to it (section 9), claim and the last ten journal entries. A unique suffix of the key is enough (./eve show EI.1.01). Verify: spec for a full key, a unique suffix, an ambiguous suffix (exit 2, lists the candidates) and an unknown key (exit 1). DONE 2026-09-19: lib/show.mjs, 6 specs in lib/show.spec.mjs, 106 in the family. All four cases are driven through the command over the COMMITTED board as well as over a fixture: ./eve show ETB.3.02 --json resolves this item by suffix and exits 0, ./eve show 2.3 exits 2 naming 17 candidates, and an invented key exits 1. THE TWO EXIT CODES ARE A DISTINCTION, NOT A DETAIL: 2 means "say it differently and I can act", 1 means "the answer is no", and a program scripting this command may retry the first and must not retry the second — so the refusal carries its own exitCode and the CLI's wrapper honours it, printing at most five candidates and counting the rest (--json carries all of them, because a program is not reading a terminal). A KEY SUFFIX IS RESOLVED AT A SEGMENT BOUNDARY, never as a bare substring: keys are <family>:<id> and ids are dotted, so every suffix a person types begins right after a : or a ., and matching anywhere in the string would make EI.1.02 a suffix of XEI.1.02 — a typo resolving to a task instead of being refused. AND NO LIKE: the key comes from a command line, where % and _ are wildcards, so ./eve show % would match every task and report it as ambiguous; substr(key, -length(?)) = ? asks the question without a pattern language, and the spec drives four wildcards through it. A dependency with no task row is printed as finished (checked in the markdown) in those words, because the row's absence IS the fact (ETB.2.05) and an empty status would read as a bug. Both directions of the document links are shown — a document that names the task and a document the task names — and documents stays empty until section 9 fills it, which the fixture proved by having its doc_links row refused until the documents parent existed. ALSO CORRECTED HERE, as the plan's own decision asked of "the session that owns cli.mjs": the PLANNED map named the wrong task in most of its refusals — claim said ETB.3.02, which is show — and the assertions in cli.spec.mjs and shim.spec.mjs had pinned the wrong answer in place. The map is now the plan's: claim ETB.4.01, done ETB.4.03, park ETB.4.04, drift ETB.5.01, board ETB.5.02, merge-driver/resolve ETB.6.02, docs ETB.8.07, context ETB.8.08, promote ETB.9.02, pull ETB.9.03, plus list ETB.3.03 and search ETB.3.04 which the decision's list omitted. A refusal that names the wrong item sends a caller to read about somebody else's work.
  • ETB.3.03 ./eve list with --family, --status, --section <prefix>, --parked-reason, --text <substring>, --limit, --json; ./eve families (the ranked table the board prints); ./eve stats. Verify: spec for each filter and their combination. DONE 2026-09-19: lib/list.mjs, 7 specs in lib/list.spec.mjs, 113 in the family (./eve stats shipped with ETB.2.07, which needed it to verify itself). THE COMBINATION IS THE CASE WORTH ITS OWN TEST: six flags that each work alone can still be wrong together — the usual way is the last one winning, or an OR where the caller meant AND — so the fixture is built so each filter alone matches several tasks and all six together match exactly one. A TYPO IS A REFUSAL, NOT AN EMPTY LIST: --status redy answering "0 tasks" would let a caller conclude there is no such work, so --status and --parked-reason are checked against vocabularies the spec compares against the tasks DDL itself rather than trusting them to match, and an unknown --family is refused too. AND NO PATTERN LANGUAGE: --text and --section come off a command line where % and _ are LIKE wildcards, so --text 100% would match anything beginning "100"; instr(lower(x), lower(?)) > 0 and substr(x, 1, length(?)) ask "contains" and "starts with" and nothing else, with a task under no heading matching no prefix rather than every one. --limit defaults to 20 because an unbounded list is not a list, and THE TOTAL IS ALWAYS REPORTED — twenty of nine hundred read as nine hundred would be the whole point of the command undone. ./eve families prints the board's own columns and a spec compares every one of them against TODOS/board.json: actionable, later, parked and rank, for all 35 families, 0 disagreements. One flag bug was found by the spec and fixed: --family --status ready would have looked for a family called --status, so a flag whose value is another flag is now no_flag_value rather than a refusal for the wrong reason.
  • ETB.3.04 ./eve search <query>: FTS5 over task titles and bodies, in the cache database (section 9 builds it), falling back to a LIKE scan of the committed database with a one-line notice when the cache is absent. Verify: spec for both paths and for a query with FTS syntax characters. DONE 2026-09-19: lib/search.mjs, lib/cache.mjs, 6 specs in lib/search.spec.mjs, 122 in the family. THE SPEC THE ITEM DID NOT ASK FOR IS THE ONE THAT MATTERS: both paths are run over the SAME rows for seven queries and their key sets and totals are compared, because if the two disagree about which tasks match then a person gets one answer on their machine and another on a fresh checkout with no reason to trust either — and the comparison is checked against emptiness too, since two paths that find nothing agree by accident. A QUERY IS TEXT, NOT A LANGUAGE: FTS5 reads -, *, ^, :, NEAR, AND, OR and " as syntax, so ./eve search 100% or ./eve search node:sqlite would either throw a parse error at the person or quietly mean something else; every token is quoted with any inner " doubled, which is how a quoted FTS5 string escapes one, and the scan path uses instr rather than LIKE for the same reason. The cost — FTS operators cannot be typed — is the right trade for a command whose job is to find the task that mentions a thing. THE TITLE IS WORTH TEN BODIES: unweighted, bm25 normalises by field length and put a task that says "mentions OneRoster once" in a short body ABOVE the task whose title is Wire the OneRoster publisher, which for a list of tasks is backwards, so the four column weights are 0, 0, 10, 1. The board is the record, not the cache: a key the cache holds and the board does not is dropped rather than printed as a task somebody could claim, while the TOTAL still counts it, because hiding a stale cache is not surviving one. The notice goes to stderr so stdout stays parseable, it names the command that builds the cache rather than only saying there isn't one, and --json reports which path answered. lib/cache.mjs holds the FTS table's DDL in one place so ETB.8.06's writer cannot drift from this reader; the spec builds a cache from that same DDL, which is how the ranked path is exercised before section 9 exists.

5. Changing the board from the command line#

  • ETB.4.01 ./eve claim <key> --agent <name> [--ttl 4h]: refuses a task that is not ready, has an unmet dependency, or has a live claim (the refusal names the holder and the expiry); on success sets leased, increments the task's fencing token and prints it. ./eve renew, ./eve release, and an expired claim returning to ready on the next write follow queue-semantics.ts (the lease expired …; acquire it again rather than renewing). Verify: spec for each refusal, expiry with a fixed clock, and a stale fencing token refused on done. DONE 2026-09-19: lib/lease.mjs, 10 specs in lib/lease.spec.mjs (8 for this item, 2 for ETB.4.02), 134 in the family. Driven on the committed board too: ./eve claim ETB.4.02 --agent spec-run --ttl 30m printed token 1, a second agent got lease_held: … is held by spec-run until …, and ./eve release gave it back. THE NUMBERS ARE THE CONTRACT'S, READ NOT GUESSED: durable-leased- work in libs/shared/resilience/src/eve-operation-policy.ts has attemptTimeoutMs and deadlineMs both at 14_400_000, so the TTL ceiling and the acquisition-age ceiling are four hours each; they are re-stated in this dependency-free CLI rather than imported, and a spec pins them so a change to the contract has to be a change here. THE ORDER OF THE CHECKS WAS A DEFECT THE SPEC CAUGHT: a task somebody holds IS leased, so the status check placed first answered "f:held is leased, not ready" — true, and not what the next question is. The holder is checked first and the refusal names them and the expiry, which is what this item asks for. A FENCING TOKEN IS PER ACQUISITION AND SURVIVES A RELEASE: claims is deleted, so the token is read back from the journal where every acquisition recorded it, which makes it "how many times this task has been acquired" — and a write from a superseded acquisition is refused even though the agent name still matches, which is the whole reason the token exists. An agent cannot renew its way to forever: a spec renews every half hour and is refused at the four-hour ceiling with "release and re-acquire". AN EXPIRED CLAIM IS SWEPT, NOT WATCHED — there is no background job — and ./eve next sweeps as well as the writes do, because next is precisely the command that would otherwise go quiet: the task would sit leased, a status next does not offer, until somebody happened to run something that writes. A task left leased with no claim row at all (a state this tool never writes and a merge could) is repaired by the same sweep, and its journal line says expiresAt: null rather than implying an expiry that never happened. The one part of this verification that could not be driven end to end is the stale token on done, which is ETB.4.03 and does not exist yet: the guard it will use is requireLease, and the spec refuses a superseded token through every write that presents one today — renew, release and start.
  • ETB.4.02 ./eve start <key> (leased → in-progress) and ./eve note <key> --text "…" (journal only). Verify: spec. DONE 2026-09-19: 2 specs in lib/lease.spec.mjs, and both commands driven on the committed board — claim, start, note, release left the journal reading exactly that. start is fenced like every other write and is refused twice: a board that let it run again would have two beginnings for one piece of work. in-progress is a separate word from leased because they answer different questions — a lease says who may write, and in-progress says somebody has actually begun — and the expiry sweep treats them alike. A NOTE NEEDS NO CLAIM: it is an observation, and the person best placed to leave one is often not the person holding the lease; what it must carry is who said it. It also must not bump the task's version, because a version is what a merge reads to decide which side moved the row and a note moves nothing — the spec asserts the version is unchanged. A caller that does hold the lease may present its token and have it checked rather than be trusted.
  • ETB.4.03 ./eve done <key> --evidence "<text>" [--commit <sha>] --token <n>: exactly one key; the caller must hold the claim and present the current fencing token; evidence is required and at least 40 characters. It re-reads the tracker, proves the anchored lines still hash to source_hash (otherwise exit 4: "the tracker changed — run ./eve import"), changes that one [ ] to [x], appends the evidence under the item in the tracker's own style (an italic dated note; an HTML evidence: comment in the workbenches ledger), sets shipped, journals, and releases the claim. If the tracker write fails nothing in the database changes. Verify: spec on a scratch tracker for the happy path, two keys (refused), short evidence, wrong token, drifted tracker, and a simulated write failure; after the happy path the file differs from the original by exactly the box and the evidence lines.
    • (Done 2026-09-19: lib/done.mjs and 8 specs in lib/done.spec.mjs; this box was checked by the command itself, which is the end-to-end proof the item asks for. The two evidence styles were chosen by measuring the repo's own prettier settings rather than by taste: a nested bullet leaves the item's prose untouched while prettier wraps only the bullet, an HTML comment is preserved verbatim (the workbenches ledger's 737), and the two shapes that lost — appending to the item's paragraph, and a blank line first — reflow the surrounding prose or become an indented code block.)
  • ETB.4.04 ./eve park <key> --reason <gpu|hardware|corpus|external| human|governance|release|upstream> --note "<sentence>": refuses gpu, hardware and external unless the note names a failed attempt (it must contain "attempt") or says what no agent can obtain (a licence, a devkit, a signing identity, a device, an owner account) — the install-before-you-park rule of 18 September 2026; writes the sentence and the `blocked:<reason>` tag into the tracker item, sets parked. ./eve unpark <key> removes the tag and returns the task to ready. Verify: spec for each, including the refusal, and that node tools/todos-board.mjs --check stays clean on the scratch tree. DONE 2026-09-19: lib/park.mjs, 6 specs in lib/park.spec.mjs, 149 in the family. THE CHECK IS A VOCABULARY, NOT A JUDGE, and saying so is the honest part: for gpu, hardware and external the note must name a failed attempt or one of the things the rule lists — a licence, a devkit, a signing identity, a physical device, an account that needs the owner — and somebody determined to park can write the word. What it stops is the reflex ("no GPU on this box", which the spec refuses three ways), the form the three false blockers of 10 September 2026 took, and it puts a sentence a human can read in the tracker either way. The other five reasons are not about an environment somebody could have installed, so they take any sentence. THE TAG GOES WHERE THE BOARD'S OWN SCANNER LOOKS: blocked:<x> is matched on any line indented under the item, so the note is a nested bullet — the same shape ETB.4.03 measured — and the spec asserts the board's model then counts the item as blocked with reason gpu, rather than only that the text is in the file. unpark takes the tag out and LEAVES THE SENTENCE: why it was parked is history, and history is not a tag; a line that was only a tag is removed rather than left as an empty bullet. Parking under somebody else's live claim is refused — it would take their work away while they hold it. The board's own check (checkModel, which is what --check runs; the script resolves its root from its own location and cannot be pointed at a fixture) is clean after a park and after an unpark. AND A DEFECT IN ETB.4.03 SURFACED HERE: a command that edits a tracker has to RE-ANCHOR it. A second park on the item it had just parked answered "the tracker changed" — caused by the first write. Both done and park now update, in the same transaction, the edited item's source_hash and the source_line of every task below the insertion, by exactly the number of lines written. The tool knows what it wrote, so this is arithmetic and not a guess, and path:line is what the board hands a worker: an off-by-eight pointer sends them to the wrong item. Measured over the committed board afterwards: of 24,881 tasks, the 4 whose source_line is not a checkbox line are all shipped or rejected — anchors frozen where the item last was, which is what they should be — and every one of the 24,877 live tasks points at a real box.
  • ETB.4.05 ./eve add --family <id> --section "<heading prefix>" --id <ext_id> --title "…" --body-file <path> [--after <key>]: appends a well-formed - [ ] **<id>** … item to the tracker at that place and inserts the task. Refuses an id that exists. Verify: spec; the workbenches structure lint still passes when the target is a fixture of that ledger. DONE 2026-09-19: lib/add.mjs, 5 specs in lib/add.spec.mjs, 161 in the family. THE LINT FOUND TWO DEFECTS THAT NO FIXTURE-ONLY SPEC WOULD HAVE: (1) scripts/v1-workbenches/checklist- structure-lint.mjs takes the token right after - [ ] AS THE ID, and that ledger writes - [ ] BASE.1 … unbolded — an item added as - [ ] **BASE.1.c** … is two violations, bad-id and child-outside-parent, because **BASE.1.c** is not under BASE.1. So the id is written in the form the FILE uses, counted off its own checkbox lines, the same way the evidence style is. (2) A section append took the indent of the LAST BOX in the section, which is often a CHILD, so the new item came out two spaces in — another item's fourth child rather than the section's next item. It now takes the narrowest indent in the section; --after is the flag for "beside that one". AN Evidence: CLAUSE IS REQUIRED where the file requires one: that ledger's lint wants one on every cell, so an item without one is refused rather than written, because writing it would turn a passing lint red — the tool breaking the file it was asked to extend. The spec runs the real lint over a fixture of that ledger BEFORE the add as well as after, so a clean result is the addition being clean and not the fixture being empty. An id that exists is refused from the FILE as well as the board, because a checked item is not imported and the lint's first rule is one checkbox per identifier; --after puts the item after the anchor's whole subtree, so a sibling never lands inside somebody else's children; and a procedure family (ETB.4.08) refuses the write outright.
  • ETB.4.06 ./eve edit <key> --title/--body-file, ./eve dep add|rm <key> <depends-on>, ./eve reject <key> --reason "…" (withdrawn work: the tracker item becomes a plain bullet beginning "Withdrawn <date>: …", never a checked box). Verify: spec for each; a dependency cycle is refused with the cycle printed. DONE 2026-09-19: lib/amend.mjs, 6 specs in lib/amend.spec.mjs, 167 in the family. THESE ARE THE TWO COMMANDS THE WRITE POLICY EXISTS FOR (ETB.4.08): done and park only ever append, while edit --title rewrites an item's FIRST LINE and reject takes its checkbox away — exactly the two edits a gate notices. Both are refused on an append or a procedure family, by name, with nothing written; a spec drives both policies and compares the file byte for byte afterwards. A WITHDRAWN ITEM IS NOT A FINISHED ONE: reject writes a plain bullet opening _Withdrawn <date>: …_ and never [x], because the work was not done and a checked box in a tracker is a claim that it was — the spec asserts the line carries neither [ ] nor [x], that the item's own text survives after the withdrawal, and that the file's open-box count drops by one. THE CYCLE IS PRINTED, not just refused: ./eve next orders this graph and a loop in it has no answer, so dep add walks forward from the proposed target and returns the path back — f:A.1.03 -> f:A.1.01 -> f:A.1.02 -> f:A.1.03 — because "that would be a cycle" is not something a person can act on without being told which one. A task depending on itself is the shortest cycle there is and is refused too, a diamond is not a cycle, and an edge onto a key the board does not hold is allowed because a prerequisite already checked in the markdown has no row (ETB.2.05). edit keeps the id where it is — a renumber is a different act, and one two trackers' structure lints would refuse — and stores the title the way the importer stores it, id first, so a row written by edit and a row written by the importer answer ./eve list --text the same way.
  • ETB.4.07 ./eve verify <key> --by <agent> --evidence "…": a second actor (not the one who shipped it) moves shipped → verified; the same actor is refused. Verify: spec. DONE 2026-09-19: verify in lib/amend.mjs, 2 specs, 169 in the family. THE REFUSAL COMPARES AGAINST THE JOURNAL, not against anything the caller supplies — a rule whose input comes from the party it constrains is decoration, which this repository has recorded twice (one reviewer's three approvals once cleared a quorum of three). Who shipped it is the actor on the last done or shipped event, which is what the board actually knows. A BOX CHECKED IN THE MARKDOWN WAS SHIPPED BY markdown: nobody told the board who did that work (ETB.2.06 case 4), so any agent is a second actor — the alternative is that work closed in a tracker could never be verified through this tool — and markdown itself is refused as a verifier, because it is not a person, it is the board saying it does not know. Verifying asks for the same 40 characters of evidence that shipping does, only shipped work is verified, and verifying twice is a refusal.
  • ETB.4.08 Write-through respects what pins a tracker (added 2026-09-19). done, park, unpark, add and edit write into markdown that gates read: verifiers pin exact checkbox lines, ids and counts, two ledgers pin the text of their open boxes by digest, and the V-series trackers feed a generated registry CI drift-checks (.claude/rules/task-checkbox-verification.md, "A tracker is read by gates"). A hand-made pass broke nine such gates on 18 September. So give every registry family a write_policy: free (the default), append (the CLI may check a box and may add text only after the item's existing text, inside the note form the file uses; it never rewords a first line, renumbers, un-boxes or merges) and procedure (the CLI never writes the file: done and park record the change in the database, print the file's own procedure and leave the markdown to it). Set procedure for v1-v9-autonomous-content and phase-180-remote-control, and append with the _( … )_ note form for eve-sota-gap-closure; every V-series family is append, and done or park on one prints the registry regeneration it now owes. Verify: specs over fixture trackers: a park on an append family leaves every first line byte-identical and puts the tag after the note; a done on a procedure family changes no byte of the file and exits 0 with the procedure named; and a test that loads the three real files and asserts each family's policy is the one named here. DONE 2026-09-19: lib/policy.mjs, 6 specs in lib/policy.spec.mjs plus one in lib/reimport.spec.mjs, 156 in the family. Seven families carry a policy: procedure for v1-v9-autonomous-content and phase-180-remote-control, each with the sentence the CLI prints instead of writing; append for eve-sota-gap-closure and for the four families whose paths feed content-coverage/seed-registry.v1.json (v2, v5, v10-ambient-rail, v-series-residue), each carrying the regeneration it owes. The V-series list is not typed out in the spec: it is read out of scripts/content-coverage/generate-seed-registry.ts itself, so a tracker added to that generator and not to the registry fails the spec. AN UNKNOWN POLICY IS A REGISTRY PROBLEM, NOT A DEFAULT — apend read as free would let a write-through command edit a file whose text a gate pins, silently, which is how the nine broke on 18 September — so compileRegistry validates the vocabulary and requires a procedure family to name its procedure, and ./eve check reports both. THE NOTE FORM WAS ALREADY APPEND-ONLY, which is why this is a policy and not a rewrite: the spec asserts a park on an append family leaves lines 1–7 byte-identical, that the tag lands after the note and not inside the requirement, and that the text before the item's first _( — what the Eve SOTA gate digests — is unchanged. Under procedure not one byte of the file moves for done, park or unpark, and the board records the change anyway. THAT LAST PART NEEDED ONE MORE THING THE ITEM DID NOT ASK FOR: a procedure family's board is deliberately ahead of its markdown, so an import reading the still-open box back as ready would undo the record on the very next run — the tool silently forgetting what it was told. The importer now carries shipped and verified forward for those families only, and a spec drives it.

6. Keeping the database and the trackers in step#

  • ETB.5.01 ./eve drift: compares every open task's anchor with the tracker and every open box in the trackers with the database, and prints three lists — edited in markdown, checked in markdown, unknown to the database — without changing anything. ./eve import applies them (ETB.2.06). Verify: spec that plants one of each. DONE 2026-09-19: lib/drift.mjs, 4 specs in lib/drift.spec.mjs, 173 in the family. On the committed board: 0 edited, 0 checked, 0 unknown, over 24,869 open boxes in 1,149 files — and the count is what makes the zeros mean something. THE SPEC DOES MORE THAN PLANT ONE OF EACH: it plants them, runs the survey, and then RUNS AN IMPORT and compares — drift describes what import would do, so if the two disagree a person reading either is misled. It uses the importer's own primitives (taskKey, bodyOf, sourceHash, shippedIdentities) rather than a second reading of the same files, because two answers to "has this item changed" is the disagreement this tool exists to remove. AN ITEM THAT ONLY MOVED IS REPORTED AS MOVED, not as rewritten: a paragraph inserted above three items drifts all three by two lines and rewrites none of them, and a reader needs those apart. An item DELETED from the markdown is reported absent rather than checked — the same absence ETB.2.06 has to tell apart, because they are opposite outcomes. Nothing is written: the spec asserts the row count is unchanged after a survey that found three kinds of drift. --fail-on-drift exits 1 for the gate ETB.5.04 asks for.

  • ETB.5.02 Generate the board from the database. tools/todos-board.mjs keeps scanning markdown for the kinds that are not work (inventories, proposals, templates) but takes families, counts, order and next items from the database when TODOS/eve-task-board.sqlite exists, so TODOS/BOARD.md, TODOS/PARKED.md, TODOS/board.json and ./eve next can never disagree. Verify: the existing tools/todos-board.spec.mjs still passes; a new case builds the model from a fixture database; on the real tree the generated board is identical before and after the switch except for the header line. DONE 2026-09-19: lib/fromdatabase.mjs, 4 specs, 198 in the family, and tools/todos-board.spec.mjs still passes at 40. ON THE REAL TREE THE BOARD IS BYTE-IDENTICAL EXCEPT THE HEADER AND ONE TABLE — every ranked row, every Actionable/Later/Parked count across 38 families, every "Start at" and every next item came out the same, which is the strongest evidence that the database and the scan were already saying the same thing. THE ONE TABLE THAT MOVED WAS ALREADY WRONG, and that is the finding: the scan's blocked: table summed to 928 while the board's own Parked column said 2,379 — a disagreement of 1,451 inside one file. It omitted every task parked by a FAMILY the registry marks blocked (6 families, 1,469 tasks: release 1,444, external 23, human 2) and counted an item with two tags twice (18 of them). The database's table sums to exactly 2,379, and the arithmetic closes to the task: 928 + 1,469 − 18 = 2,379. THE SCAN STILL DECIDES TWO THINGS the database cannot: the Done column, because a CHECKED item is not imported, and every item's TEXT — the database stores titleOf (first sentence, 200) and the board prints plainText (first line, 150), so the ordered items are mapped back to the scanned ones by path:line and taking the title would have changed every line of the board. A task the scan cannot place is DROPPED FROM THE ORDER rather than invented, while the count still comes from the database: the markdown moved under the board, and ./eve drift is the command that says so. A family the database has never heard of — an inventory, a proposal, a template, none of which are imported — keeps its scanned row exactly, so a board built in a checkout with no database renders as it always did. AND IT INTRODUCED AN ORDER THAT DID NOT MATTER BEFORE, found by breaking it within the hour: the counts now come from the database, so ./eve board BEFORE ./eve import writes the old numbers into three committed files — board.json said 17 actionable where the database said 16, and three specs that compare the two went red. The generator now compares the scan with the database and warns by name when they differ (! eve-task-board: the tree has 16 actionable and the board has 15 — run ./eve import first), the board's own How to use section states the order, and the three specs pass again.

  • ETB.5.03 Rewrite the "How to use this board" section that renderBoard emits so it teaches the CLI: ./eve next, ./eve show, ./eve claim, ./eve context, ./eve done --evidence, ./eve park, ./eve docs search, with one worked example of a full task, the exit codes that matter, and what to do on a merge conflict in the database (./eve resolve). Keep node tools/todos-board.mjs --next working as an alias. Verify: spec asserts each command appears in the rendered board; a fresh agent transcript following only that section completes a scratch task. DONE 2026-09-19: the section now teaches the CLI in five numbered steps plus "the rest of it", the exit codes, the merge advice and a worked example; 2 new cases in tools/todos-board.spec.mjs (40 pass) and 1 in tools/eve-task-board/cli.spec.mjs (174 in that family). The spec asserts all 22 built commands appear by name, and that the 5 that are NOT built are named with the task that builds each — the same pairing the CLI's own refusal prints — because a section that teaches a command the CLI does not have sends an agent to an exit 2. The command-name assertions are on names, not signatures: this document is wrapped at 80 by prettier, so an assertion on a two-word phrase would be testing the wrapping. THE WALKTHROUGH WAS RUN, and it was not a formality. In a scratch git tree with its own registry and a two-item tracker, following only this section: import, next, show, claim (token 1), start, done --evidence (the box checked and two evidence lines written), park (REFUSED on "no GPU here", accepted on "attempted the CPU path and it ran out of memory at 9 GB"), unpark, verify --by a second actor, drift, stats. IT FOUND A DEFECT 173 SPECS HAD MISSED: step four answered eve: 'park' is not a command. park and unpark were built, specced at the library level, listed in the help and taught by this very section — and the CLI's dispatch never learned them, because the edit that added them to its condition was in a batch that aborted. There is now a spec that runs EVERY command the help lists and fails if any of them answers "is not a command", and import was added to the help, which had never listed it. AND THE SAME WALKTHROUGH CAUGHT A REGRESSION IN ETB.3.01: ./eve next <family-id> <count> is the positional form CLAUDE.md documents, and the new next read only --family and -n, so it silently ignored both arguments and printed the default family's single item — the same answer to a different question. The positional form is restored and the board says both forms work. The one part of this verification that is not what the item literally asks for: the walkthrough was performed by this session following only the section's text, not by a separate agent in a fresh transcript.

  • ETB.5.04 Add ./eve check and ./eve drift --fail-on-drift to the verify:todos:registry script in package.json and to the pre-commit hook's checks for commits that touch a tracker or the database. Verify: a commit with a tracker edited by hand and no import is stopped with the drift list; the same commit after ./eve import passes. DONE 2026-09-19: tools/eve-task-board/gate.mjs, wired into .husky/pre-commit and verify:todos:registry, 2 specs in gate.spec.mjs, 176 in the family. Both halves of the verification are driven over a SCRATCH GIT TREE with its own registry, tracker and board: a hand edit that checks one box and rewrites another is stopped with checked in markdown: 1 and edited in markdown: 1 naming both keys, and the same tree after ./eve import passes with zeros — and the board then records the checked item as shipped, not deleted. IT ONLY RUNS WHEN IT CAN SAY SOMETHING: a commit that touches no tracker, no registry and not the database exits 0 immediately, because four seconds of scanning to tell the overwhelming majority of commits nothing is a gate people learn to skip. A proposal family is not work and an unclassified markdown file is not a tracker; the spec asserts exactly which of six paths are interesting. IT REPORTS AND NEVER REPAIRS — the fix for drift is ./eve import, which writes a committed file and is the author's decision, so the refusal says what to run. THREE DEFECTS WERE FOUND BUILDING IT. (1) gate.mjs did its work at import time and called process.exit(0), so a spec that imported one function from it reported ONE passing test and ran neither of its two — the shape of a green suite that tested nothing. (2) ./eve check resolved tools/todos-board.mjs from the working directory, so run against any other checkout it died with "Cannot find module"; it now resolves from its own location, and because that script binds itself to the repository it lives in, a board outside this repository skips the registry half and SAYS SO rather than reporting a clean registry it never read. (3) The fixture's own registry taught the spec two of its rules by refusing it: a proposal family needs a status, and only a live WORK family takes a priority.

  • ETB.5.05 (added 2026-09-19 by the third board audit, finding F04) A closure that came in through the importer looks the same as one that went through ./eve done. Checking a box by hand and running ./eve import ships the task with actor markdown: no fencing token was checked, the 160-word evidence limit never ran, and the recorded commit is whatever HEAD was at import, which for EI.7.04 and EI.0.13 on 2026-09-19 was a commit BEFORE the work. The import path stays — it is how a board is rebuilt — but the two are told apart. ./eve show says closed by ./eve done or import from the journal; ./eve check prints, after its eight questions and not as a ninth (a closure by import is not something wrong with the file), the tasks shipped by import since the cut-over (2026-09-19) with no done and no verify event, as a WARNING line that does not change the exit code, because a recovery is legitimate and hiding it is not; ./eve verify clears it, as the second look it is. Verify: specs on a fixture board: a task closed by done is not listed, one closed by checking the box and importing is, the same task after verify is not, a task shipped before the cut-over is not, and the exit code stays 0 with only warnings; run on the committed board, the evidence gives the count and names EI.7.04, EI.0.12 and EI.0.13 if they are still unverified.

    • (Done 2026-09-19: lib/provenance.mjs: closureOf() reads which door a task was closed through from its journal, importedClosures() lists tasks shipped by import since 2026-09-19 with no done and no verify. ./eve show prints closed by for a finished task; ./eve check prints one warning line per such task on stdout after its verdict, outside the eight questions, exit code unchanged; ./eve verify clears it. On the committed board it names eight: EI.7.04, EI.0.12, EI.0.13, EI.0.15 and ETB.8.02 to 8.05. provenance.spec.mjs drives the real done(), importer and verify() over a fixture git checkout with no hand-written events: done not listed, a hand-checked imported box listed, verify clears it, a pre-cut-over import is history, CLI exits 0 with an empty stderr. Whole suite, warnings on: 291 passed, 0 failed. The item's text was amended to say advisory rather than ninth question, and show rather than show and list. (0aa4e8cbf02))
  • ETB.5.06 (added 2026-09-19 by the third board audit, finding F07) The tool's own specs fail on a supported Node. node --test --test-concurrency=1 tools/eve-task-board/cli.spec.mjs tools/eve-task-board/lib/*.spec.mjs is 270 passed, 3 failed on Node 22.23.1: check.spec.mjs, list.spec.mjs and show.spec.mjs read a child's stderr as "one line per problem" or as one JSON document, and Node prints ExperimentalWarning: SQLite is an experimental feature there. The same two lines land in the stderr of every ./eve call an agent parses. Fix it at the source rather than in the specs: lib/db.mjs's sqlite() is the one place node:sqlite is imported, and it drops that one warning — by name and text, nothing else — while it imports; the two direct imports in lib/cache.mjs and the one in cli.mjs go through it. Verify: the command above is green with NODE_NO_WARNINGS unset; ./eve list --limit 1 2>&1 >/dev/null prints nothing; a spec shows a different warning raised during the import still reaches stderr.

    • (Done 2026-09-19: lib/db.mjs sqlite() is now the one place node:sqlite is imported (cache.mjs twice and cli.mjs once went around it) and it drops the SQLite ExperimentalWarning while the import runs, matched by name and text, with process.emitWarning restored in a finally. With NODE_NO_WARNINGS unset on Node 22.23.1: node --test --test-concurrency=1 cli.spec.mjs lib/*.spec.mjs is 275 passed, 0 failed (was 270/3); shim, shim-bridge and gate specs 14/14; ./eve list --limit 1 2>&1 >/dev/null prints nothing. Two new cases in db.spec.mjs: a child that opens the board has an empty stderr; a DeprecationWarning raised during the import still reaches the emitter, a different ExperimentalWarning is not matched, and the hook is put back. (2496547544f))

7. Living in git#

  • ETB.6.01 ./eve dump --stable: a deterministic text rendering (one line per row, tables and rows in key order, no timestamps of the dump itself). Register it as a textconv so git diff and review show rows, not bytes: .gitattributes gets TODOS/eve-task-board.sqlite binary diff=evetaskboard merge=evetaskboard. Verify: spec that two databases differing by one task's status produce a one-line dump diff. DONE 2026-09-19: .gitattributes carries the line, 2 specs in lib/textconv.spec.mjs, 178 in the family. The spec builds two five-task boards differing only in the third task's status and asserts the dumps differ in EXACTLY ONE LINE, ready against shipped, and that the same board dumped twice is byte-identical (nothing in it is a timestamp of the dump). MEASURED ON THE REAL FILE: with the textconv registered, a one-row status change in the 25 MB committed board shows in git diff as a single changed line; without it, Bin 25604096 -> 25604096 bytes, and a review of that commit is a review of nothing. THE SPEC DOES NOT ASSERT THAT THE CONFIG EXISTS, and that distinction matters: .gitattributes is committed and true of every clone, while diff.evetaskboard.textconv lives in the clone's own git config, which ./eve git-setup (ETB.6.03) installs — a spec that required it would be testing the machine it runs on and would fail on a fresh checkout. It asserts instead that IF the key is set it names a dump this CLI can produce, and it was run with the key unset as well as set. merge=evetaskboard names the driver ETB.6.02 builds; until then the .gitattributes comment says what to do with a conflict, which is what the board's own How to use section says too.
  • ETB.6.02 ./eve merge-driver <base> <ours> <theirs>: three-way merge by task key using version and the events journal — a task changed on one side takes that side; changed on both sides with the same outcome is fine; changed differently takes the later shipped/verified over an earlier state and otherwise keeps both journals and leaves the task ready with a merge-conflict event naming both versions; claims take the higher fencing token. Writes the result to <ours> and exits 0, or exits 1 leaving the file untouched. Verify: spec with a base and two divergent copies for each rule, including two agents shipping different tasks (both survive) and both claiming the same task (one wins, the other is told). DONE 2026-09-19: lib/merge.mjs, 8 specs in lib/merge.spec.mjs, 186 in the family. Every rule has its own case, including the two the item names: two agents shipping DIFFERENT tasks leaves both shipped with both done events, and two agents claiming the SAME task keeps the higher fencing token — a higher token is a later acquisition, which is the only ordering the two sides share — while the loser is told in a claim-superseded event and both claimed events survive. THE CASE THAT DECIDES THE DESIGN is the one where neither side is obviously right: parked gpu against parked human. This driver does not pick. It keeps BOTH journals, leaves the task ready — available to whoever reads the conflict — and writes a merge-conflict event naming both versions and saying what it did. A driver that picked would lose somebody's work with no trace. A finished state beats an open one whichever side it is on (the spec runs it both ways round), because the work was done and parking it afterwards is stale. THE SURROGATE IDS ARE REBUILT, NOT MERGED: files.id and sections.id are per-database integers (migration 2), so the same path can be 7 on one side and 412 on the other — merging those tables by id would silently re-point tasks at other files, so the merged board is written FRESH from the schema and every task's file and section are resolved by their TEXT. THE SIDES ARE READ, NEVER MIGRATED: openBoard applies migrations, which is a write, and writing to ours before the merge is whole would break the one guarantee this driver makes — so a side that is not at head is refused by name (schema_mismatch, which keeps its own code instead of being flattened into "unreadable", because the specific answer is the one a person can act on). The result is written to a temporary file and renamed over ours only once it is whole; the spec drives a failed merge and compares ours byte for byte afterwards.
  • ETB.6.03 ./eve git-setup: writes the diff.evetaskboard.textconv and merge.evetaskboard.driver entries into the clone's git config, and is called from the root package.json prepare script after husky. ./eve resolve does the same merge by hand from the index stages (git show :1:, :2:, :3:) for a clone where the driver was never installed, then stages the result. Verify: spec in a temporary repository: two branches each close a different task, git merge succeeds with the driver and produces both; without the driver the merge conflicts and ./eve resolve finishes it. DONE 2026-09-19: lib/gitsetup.mjs, 4 specs in lib/gitsetup.spec.mjs, 190 in the family, and prepare in the root package.json now runs git-setup after husky. BOTH STATES ARE DRIVEN IN A REAL TEMPORARY REPOSITORY, which is the only way to know: with the driver installed, git merge of two branches that each shipped a different task EXITS 0 and both survive with both done events; without it, git merge fails and leaves three stages in the index — the state every fresh clone is in, because .gitattributes is committed and git config never is — and ./eve resolve reads :1:, :2: and :3:, merges them with ETB.6.02's driver, writes the result and STAGES it, after which git commit succeeds. A resolve that merged and left the result unstaged would look finished and commit the conflict, so the spec asserts the index has no unmerged entry afterwards. git-setup is idempotent — the second run reports nothing changed, because "did this do anything" is a fair question to ask of a setup command — and it TOLERATES A CHECKOUT THAT IS NOT A GIT REPOSITORY, saying so and exiting 0: it runs from prepare on every pnpm install, and failing the install over a tarball would be this command breaking what it was added to help.
  • ETB.6.04 Document the two-session reality in the tool's README and in CLAUDE.md's Git section: after git merge origin/main, a conflict in the database is resolved with ./eve resolve, a conflict in TODOS/BOARD.md, PARKED.md or board.json by regenerating. Verify: the documents name the commands; the merge spec of ETB.6.03 is the proof they work. DONE 2026-09-19: a "Two sessions at once" section in tools/eve-task-board/README.md and a new bullet in CLAUDE.md's Git section, with 1 spec, 191 in the family. The spec asserts BOTH documents name ./eve resolve, ./eve git-setup, ./eve import and ./eve board, the database by path, git checkout --theirs for the three generated files, and the rule that decides the hard case — a document that says "resolve the conflict" without naming the command sends somebody to resolve a 25 MB binary by hand. Both say what the merge does to a task changed differently on both sides (left ready, both journals kept), so nobody has to guess what happened to their work, and both name ./eve import as the LAST resort with what it costs: the board rebuilds from the trackers in four seconds, and the journal — claims and evidence events — is what that loses. The README's command list was also rewritten from the five commands that existed when it was written to the path through one task plus the other nineteen. As the item says, the proof these commands work is ETB.6.03's merge spec; this one only checks that what was proved is what is written down.
  • ETB.6.05 Measure growth. After the first import and after 200 scripted task closures in a scratch clone, record the database size and the size of the pack git adds per closure (git count-objects -vH before and after git gc). If a closure costs more than 50 KB of pack on average, move task_body to a second committed file that changes rarely and re-measure. Verify: the numbers are in the evidence and the 25 MB budget check of ETB.1.05 reflects the chosen layout. DONE 2026-09-19. 200 scripted closures were run in a scratch clone of the real 25,608,192-byte board, each one exactly what ./eve done writes to the database — the task shipped, the claim gone, one journal row — committed one at a time, then git gc. Five layouts measured, pack size before and after, per closure: as committed (4 KiB pages) 5.91M → 23.96M = 92.4 KiB; task_body removed (the item's own remedy) 3.94M → 16.02M = 61.8 KiB; 1 KiB pages 6.44M → 26.09M = 100.6 KiB; as committed with pack.window=50 pack.depth=250 5.91M → 12.13M = 31.8 KiB; both 3.94M → 8.13M = 21.5 KiB. THE ITEM'S RULE FIRED AND ITS REMEDY DID NOT CLEAR THE BAR, which is why the numbers matter more than the prescription: at 92.4 KiB a closure costs more than the 50 KB the item names, and moving task_body out brings it only to 61.8 KiB — still over, at the price of a migration, a second committed file and a budget check spanning two of them. THE REASON IS NOT THE SIZE OF THE FILE. One closure changes 8 of the board's 6,252 pages and 1,240 bytes, and git stores it as a 1.2 KiB delta: of the 201 blobs in the pack, 197 are deltas totalling 0.24 MiB and 4 are full copies totalling 23.66 MiB. With the default pack.window=10 git cannot find the chain among 200 similar 25 MB blobs and writes a fresh 5.9 MiB copy every ~50 commits. Widening the window is what fixes it — --depth=250 alone changes nothing at all (23.96M unchanged), which is the measurement that says which knob is which. SO THE LAYOUT IS UNCHANGED and ETB.1.05's 25 MiB budget still describes it: one file, 25,608,192 bytes, 97.7% of the budget. The effective remedy is two lines of git config, and it is OPT-IN — ./eve git-setup --pack — because pack.window and pack.depth are repository-wide and a wider delta search makes every git gc in this monorepo slower for every session. That is a cost the owner should choose rather than inherit from a board tool, and the combination (bodies out AND the pack settings, 21.5 KiB) is there if more margin is ever wanted.

8. Rules and agent instructions#

  • ETB.7.01 Update .claude/rules/task-checkbox-verification.md: step 5 becomes "close it with ./eve done <key> --evidence … (one task per call); if the tool is unavailable, edit the box by hand and run ./eve import"; step 6 becomes ./eve park; the banned list gains "calling ./eve done in a loop or from a script". Keep every other rule. Verify: the file names the commands and the rule's paths: front matter also matches TODOS/eve-task-board.sqlite. DONE 2026-09-19: 1 spec, 193 in the family. Step 5 is now ./eve done — one task per call, with what it does to the tracker and the exit-4 refusal, and the hand fallback ending in ./eve import so the two never drift apart. Step 6 is ./eve park with the install-before-you-park rule in one sentence. The banned list gains "calling ./eve done in a loop or from a script", said in the list's own vocabulary — IT IS THE SAME BATCH-MARKING IN A NEWER SHAPE, and the command takes exactly one key for that reason. The front matter gains TODOS/eve-task-board.sqlite, which matters more than it looks: these rules load when a matching file is touched, so a session that edited the database and no tracker would never have seen them. Every other rule in the file is untouched, including step 7, which the spec asserts.
  • ETB.7.02 Update CLAUDE.md (repo map paragraph) and AGENTS.md: the Eve Task Board is TODOS/BOARD.md + TODOS/eve-task-board.sqlite + ./eve; "work the next task on the Eve Task Board" is ./eve next → ./eve claim → ./eve context → work → ./eve done. Verify: both files carry the four-step loop in under ten lines each. DONE 2026-09-19: 1 spec, 194 in the family. CLAUDE.md's repo-map paragraph and a new "The Eve Task Board" section in AGENTS.md both carry ./eve next → ./eve claim → ./eve show → work → ./eve done, one task per call, with ./eve park for what truly cannot be done here and ./eve help for the rest. ./eve show stands where the item wrote ./eve context, because context is ETB.8.08 and is not built — a loop that told every session to run a command the CLI answers with exit 2 would be worse than no loop, and show is what it will extend. The spec asserts both files name all five commands and both halves of the board (the ranked markdown AND the committed database), and that the loop sits in one block rather than scattered: these two files are read at the start of every session, and a loop nobody reads is a loop nobody follows.
  • ETB.7.03 ./eve prompt <key> prints a ready-to-paste brief for a coding agent: the title and body, the rules paragraph of its tracker, the context pack of ETB.8.08, the tracker's definition of done, and the exact ./eve claim and ./eve done lines to run. Verify: spec that the brief contains each part for a fixture task and stays under the --max-chars it is given. DONE 2026-09-19: lib/prompt.mjs, 3 specs, 201 in the family. On this item itself the brief is 2,087 characters and carries where the task is, the item verbatim, what it waits on and what that means, the tracker's OWN definition of done, the family's note, and the two commands. THE TRACKER'S OWN WORDS, NOT A SUMMARY: the rules are lifted verbatim out of the file the task lives in, because a tracker that says "evidence here is the spec file, its pass count, and the command that was run" means exactly that, and a paraphrase is the first step towards a checked box over nothing. TWO EXTRACTION DEFECTS WERE FOUND BY READING THE OUTPUT rather than by the spec: splitting the preamble on "a line that starts a bullet" leaves everything BEFORE the first bullet as chunk zero — the title, the owner decision, every paragraph — and almost any tracker mentions evidence somewhere in it, so the brief printed the whole preamble under "what this tracker means by done"; and a bullet chunk runs to the next bullet, so the last one in a list swallowed the heading after it. A tracker with no rule of its own SAYS SO and points at .claude/rules/task-checkbox-verification.md rather than having one invented for it. Under --max-chars THE BODY IS WHAT GIVES, because it is the one part the reader can go and read at path:line, and the two commands survive every budget because they are the one part a reader cannot reconstruct; the spec drives 1,500, 3,000 and 9,000 against a body of 10,000. The context pack the item names is ETB.8.08 and is not built: the brief carries what exists today and will take the pack when it does.

9. Knowledge: specifications, architecture, research, audits, flows, walkthroughs, slides and docs pages#

Index, do not move (decision 5). The catalog is committed inside the task database; the full text is a local cache.

  • ETB.8.01 lib/catalog.mjs: classify every tracked document by path rules into a kind — adr (docs/adr/**, docs/domains/*/adr/**), architecture (**/ARCHITECTURE*.md, V*/**/ARCH*.md, docs/domains/*/ architecture/**), spec (docs/releases/**/specs/**, V1/features/**, **/*SPEC*.md), proposal (docs/proposals/**), research (**/*COMPETITOR*, **/*SOTA*AUDIT*, **/research/**, docs/domains/*/ deep-dives/**), audit (docs/audits/** that is not evidence), evidence (docs/agents/**evidence**, evidence/**), flow (WALKTHROUGH/journeys/**, **/flows/**), walkthrough (WALKTHROUGH/**, ADMIN_WALKTHROUGH/**, TENANT_ADMIN_WALKTHROUGH/**, MOBILE_WALKTHROUGH/ **, TELEGRAM_WALKTHROUGH/**), runbook (**/runbooks/**), tracker (registry work files), guide (everything else under docs/). The rules live in one table in the module with a spec per rule; an unclassified markdown file is other and is listed by ./eve docs unclassified. Verify: spec per rule; on the real tree fewer than 5% of documents are other, and the evidence lists the biggest unclassified directories. DONE 2026-09-19: lib/catalog.mjs, 4 specs, 205 in the family, and ./eve docs unclassified. ON THE REAL TREE, 11,468 documents: tracker 6,877 (60.0%), runbook 1,184 (10.3%), walkthrough 884 (7.7%), guide 665 (5.8%), other 461 (4.0%), spec 335 (2.9%), slide 300 (2.6%), audit 173 (1.5%), evidence 160 (1.4%), architecture 155 (1.4%), adr 127 (1.1%), proposal 66 (0.6%), flow 60 (0.5%), research 21 (0.2%). The biggest unclassified directories are V3 (51), V10 (27), V1 (12), the repository root (11), ISIS_GAPS (9+9), V1/planning (8) and the V7–V9 roots (8 each) — V-series documents that sit beside their trackers rather than in a docs/ directory. THREE RULES WERE WIDENED BY MEASUREMENT, NOT BY TASTE, and the first pass was 12.1% other: guide read docs/** when the item means a docs DIRECTORY (V2/docs/** and its siblings are 665 documents); architecture had no rule for V1/architecture/**, whose 31 files are named for their subject rather than ARCH*; and spec named V1/features/** when the other nine V-series roots hold the same documents (100 of them, which alone kept the catalog three documents over the bar). ONE TABLE, IN ORDER, AND THE FIRST MATCH WINS, so "why is this file that kind" has one place to look — and three of the orderings are load-bearing, each with its own spec: evidence before audit (an audit is "docs/audits/** that is not evidence", so evidence asked second never matches), flow before walkthrough (a journey lives INSIDE WALKTHROUGH/), and spec before guide (guide is the catch-all and comes last). A spec asserts every rule in the table has a case, so a rule added without one fails rather than going untested, and the real-tree spec asserts every kind is actually found — a table that called everything a guide would clear the 5% bar too. tracker is not a glob: it is whatever TODOS/registry.json classifies, which is the one list of work files that already exists.
  • ETB.8.02 Fill documents: title (first # heading, else the file name), domain (from domains.json by path segment), release (V1.0, V1.1, V1.2, V2–V10 by path or front matter), the first twelve headings, a 300-character summary (the first paragraph of prose), sha256, size and the last commit date (git log -1 --format=%cs, batched). Incremental: only files whose hash changed are re-read. Verify: spec on a fixture tree; on the real tree a second run with no change reads no file bodies (asserted by a counter) and finishes in under ten seconds. DONE 2026-09-19: lib/documents.mjs, ./eve docs index, 5 specs, 210 in the family. ON THE REAL TREE: 11,468 documents indexed in 7.3 s, and a second run reads 0 files, 11,468 unchanged, in 6.8 s — under the ten the item names, and asserted by the COUNTER the indexer returns rather than by a stopwatch, because a run that finished quickly on a warm disk would pass a time bound while re-reading everything. 6,827 documents got a domain, 1,861 a release, 11,215 a summary and 11,459 a commit date. THE BATCHED DATE WAS NOT AN OPTIMISATION, IT WAS THE DIFFERENCE BETWEEN WORKING AND NOT: git log -1 --format=%cs -- <path> per file is 11,468 processes and the first index did not finish inside two minutes; one git log --name-only walk dates 16,601 paths in five seconds, because git walks newest first and the first time a path appears is its newest commit. (git log -1 -- a b c is not the batched form: it answers with one date for the newest of them all.) YAML FRONT MATTER IS NOT THE DOCUMENT — without skipping it 2,645 documents took a front-matter line as their summary, and .claude/rules/task-checkbox-verification.md summarised itself as "paths:"; a catalog whose summaries are field names cannot be skimmed. A heading inside a code fence is not a heading, a list item is not a summary, and a document with no # heading is titled by its file name, because something has to be printable. AND THE CATALOG MOVED TO ITS OWN COMMITTED FILE (migration 3), which is the one thing here an owner may want to overrule. The catalog costs 7.79 MB and the board with it came to 33,382,400 bytes against decision 2's 25 MiB; stripping BOTH extra indexes AND every heading AND every tracker document still left 26,054,656 — under by 160 KB with nothing left to give and 24,856 tasks still growing. Decision 5 ("the catalog is committed inside the task database") and decision 2 ("size budget: 25 MB") cannot both hold in one file, so the catalog is committed in TODOS/eve-task-board-docs.sqlite — 7,036,928 bytes, under its own stated 10 MiB budget, with the board back to 25,415,680 — and decision 5's substance is kept: the catalog IS committed. It belongs apart for a reason that is not size, too: ETB.6.05 measured that every closure re-deltas the pages it touches, and in one file each closure would re-delta a 7.8 MB table that did not change. ./eve check now asks about both files, ./eve show reads the catalog when it is there and works without it, and the merge driver leaves the catalog alone because it is DERIVED — a conflict in it is resolved by ./eve docs index, seven seconds.
  • ETB.8.03 Add the Presentation Center as documents of kind slide: one row per slide from docs/presentations/presentation-center/content/ *.json (path …/content/<file>.json#<slideId>, title, the guide ids that use it from catalog.json, summary = subtitle + takeaway), with its sources[] recorded as doc_links. Verify: spec on a two-file fixture; the real tree yields one row per unique slide id (1,721 on 18 September) and no duplicate. DONE 2026-09-19: lib/slides.mjs, 4 specs, 214 in the family. ON THE REAL TREE: 1,721 slides, 1,721 unique ids, 0 duplicates — the figure this item names — plus 69 guides and 6,504 links, and every one of the 1,721 slides cites at least one source, which the spec asserts because a slide with no provenance is a claim with none. A slide's path is the file AND the id (…/content/<file>.json#<slideId>), because a slide lives inside a file rather than being one, and its bytes are the slide's rather than the deck's — a file holding thirty slides would otherwise report every one of them as the whole file. THE GUIDE THAT USES A SLIDE IS A LINK, NOT A COLUMN: 69 presentations name the slides they show, that is many-to-many, and doc_links already models it. A guide that names a slide no content file has is linked to NOTHING rather than to a missing row, which the fixture drives with a deliberately dangling id. TWO DEFECTS CAME OUT OF INDEXING THE REAL THING. (1) ETB.8.01's slide rule was docs/presentations/**, which matched 300 MARKDOWN files — DESIGN.md, README.md, a TODOS tracker — so the catalog held 2,021 "slides" where the centre has 1,721; those files are documentation ABOUT the centre and the rule now reads docs/presentations/**/*.json. (2) The document sweep and the slide indexer were deleting each other's rows: indexDocuments removes any document not in the markdown list, which took out all 1,790 slide and guide rows on every run for the slide indexer to put straight back — 1,790 rows of churn in a committed file for no change at all. It now removes only paths without a # fragment, which are the ones it could have written, and a spec pins it.
  • ETB.8.04 Add the Docs Center as documents of kind docs-page from the generator's own index, the repo-root vdocs-search-index.js (window.__VDOCS_INDEX=), reusing the parser in tools/build-assistant- docs-search.mjs by moving it into a shared module both import. Verify: spec over a small index fixture; the BFF corpus builder's own tests still pass after the move. DONE 2026-09-19: tools/vdocs-index.mjs (the shared parser), lib/docscenter.mjs, 4 specs, 218 in the family. 3,121 pages indexed, 3,121 unique hrefs, and the catalog is now 12,263,424 bytes of a 16 MiB budget. The BFF corpus builder's own tests pass after the move — docs-search.spec.ts (14) and docs-search-member-audience.spec.ts (6), 20 passing — and the two parsers were compared as DATA before that: the old inline one and the shared module return byte-identical JSON for all 3,121 pages. A spec asserts the builder now imports the module and no longer contains the marker string, so a copy growing back there fails. THESE PAGES HAVE NO FILE IN THE TREE — the HTML is built by CI and gitignored (audit R-2, 2026-07-16) — so the generator's index IS the record of what exists, and a page is addressed by its href (docs-center://<href>). There is no prose in the index to summarise, so the summary says what the page IS and what it contains (portal — Start here · Products · What's new) rather than inventing a sentence. The sweep is SCOPED TO ITS OWN PREFIX, because the catalog now holds markdown documents, slides and Docs Center pages, and a sweep that forgot that deleted the other two once already (ETB.8.03). ONE THING WENT WRONG AND IS WORTH RECORDING: node tools/build-assistant-docs-search.mjs --help does not print help — that builder has no flags and simply RAN, rewriting two committed artefacts (docs-graph-inventory.json from 3,256 pages to 3,121 and emptying docs-search-corpus.member.jsonl). Both were restored with git restore --worktree; the stale page count is a real finding about those artefacts, but regenerating them was not this task's to do.
  • ETB.8.05 Link tasks to documents and code. From each task body take repository paths in backticks that exist (ls), tracker ids of other tasks, ADR numbers, slide ids and Docs Center hrefs, into task_links with a target_kind of doc, code, task, slide or docs-page. From each document take markdown links to other tracked files into doc_links. Verify: spec on fixtures; on the real tree report how many open tasks link to at least one existing path, per family. DONE 2026-09-19: lib/links.mjs, 4 specs, 222 in the family. ON THE REAL TREE: 2,143 task links from 1,114 of 24,856 tasks (4.5%) — code 1,604, doc 296, slide 222, task 14 — and 18,262 document links from 11,468 documents. Per family, tasks linking to at least one existing path: audit-remediation 226, v1-p2-backlog 164, v1-domain-workbenches 163, phases 91, walkthrough-studio 88, phase-29-demeter 66, v-series-residue 58, walkthrough-web-other 43; 10 of 38 families have none at all, which is the honest shape of it: most tracker items name concepts and ids rather than paths. A PATH IS ONLY A LINK IF IT EXISTS — 1,055 mentions point at nothing and are counted rather than stored, because a catalog of links to files that are not there teaches a reader that the links cannot be trusted. A DIRECTORY COUNTS: of 1,162 backticked paths that are not tracked files, 636 are directories that exist (apps/demeter/alexa-skill, libs/shared/resilience), and an item pointing at a place in the tree is pointing at something; the rest are npm scopes, model ids (deepseek/deepseek-v4-flash-0731) and git refs (origin/main), which the TREE filters out rather than a pattern — guessing which scoped names are packages would be a second answer to a question the tree already answers. An .html href is NOT also a path: the Docs Center's pages look exactly like paths and are not files in the tree, so counting them both ways made every one of them a mention that points at nothing. A task linking to ITSELF says nothing and is dropped, ids resolve inside the task's own family first (the rule ETB.2.05 uses), and the five kinds this item owns are rebuilt while blocked-also and unresolved-dep — the importer's rows — are left alone, which a spec asserts.
  • ETB.8.06 The full-text cache: ./eve docs build writes .cache/eve-task-board/knowledge.sqlite (gitignored) with an FTS5 table over document chunks of about 900 characters split on headings, plus the task titles and bodies; incremental by sha256; --kinds limits it. Large evidence dumps (kind = evidence, over 200 KB) are indexed by headings only. Verify: spec on fixtures; on the real tree record the build time, the cache size, and that a second run indexes nothing.
    • (Done 2026-09-19: Evidence: lib/knowledge.mjs + 4 specs on fixtures (node --test tools/eve-task-board/lib/knowledge.spec.mjs, 4/4; family suite 212/212, board suite 40/40): chunks cut on headings with each piece keeping its heading, a second build reading 0 and a changed document re-indexed to one chunk rather than two, a >200 KB evidence document reduced to its headings, and --kinds plus the task rows. On the real tree: a build from an empty .cache/ indexed 11,468 of 11,468 documents into 243,616 chunks beside 24,852 tasks, 262 MiB, in 9.6s; the second run read 0 of 11,468 (11,468 unchanged) in 0.78s; doc_fts MATCH 'jetsam' ranks docs/agents/incident-2026-08-15-jetsam-freeze.md and CLAUDE.md's machine-limits section first. THE FIRST BUILD TOOK 10m37s AND THE TRANSACTION SIZE WAS NOT WHY: DELETE FROM doc_fts WHERE path = ? scans an UNINDEXED column, so every one of the 11,468 documents scanned every chunk already written to find nothing — the rate decayed from 27.8 documents/second to 20.0 measured at document 5,200. Deleting only when sources already holds the path gives the identical 243,616 chunks 66x faster. Batching is kept for what it does earn — an interrupted build resumes — and the comment that had credited it with the ten minutes is corrected in place. README.md's "about a minute" is replaced by the measured numbers.)
  • ETB.8.07 ./eve docs search "<query>" [--kind] [--domain] [--limit] prints path, heading, kind and a snippet; ./eve docs show <path> [--section "<heading>"] prints one section; ./eve docs related <key> lists a task's linked documents, then the best full-text matches for its title, labelled as guesses. Without a cache each prints how to build it and falls back to the catalog's titles and headings. Verify: spec for each command and for the no-cache path.
    • (Done 2026-09-19: Evidence: lib/docsearch.mjs + 9 specs (node --test tools/eve-task-board/lib/docsearch.spec.mjs; family suite 222/222), one per command and each with a no-cache twin. On the real tree: docs search "fencing token" returns 6 of 75 matching chunks with the match bracketed in a bm25-ranked snippet; --kind adr/--domain isis filter, and a typo in either is a refusal that shows the vocabulary — --domain walkthrough answers "Did you mean: Surface walkthrough (782)", because domain holds TWO vocabularies (the 58 repository domains for files, the Docs Center's nav sections for its pages). docs show <path> lists a document's headings with line numbers and --section prints one; a slide is read out of its deck (…json#id, every field rendered, not a named few) and a docs-center:// page correctly has no file since audit R-2, so it falls back to the catalog and says why rather than reporting damage. docs related I9.19.f prints 5 documents the task NAMES and, separately, ranked guesses labelled unverified. Three things were wrong and are measured, not argued: ANDing a 7-word task title matched NOTHING, so a title-derived query is OR + bm25 (ftsExpression({match}), one quoting rule, not two); the filters had to move out of SQL into the ranked iteration, because a SQL LIMIT cuts before they run and --kind adr --limit 1 would return the top chunk of any kind and then show none; and one document could fill the page — uncapped, checkbox put 16 of its top 20 chunks in one file and reached 5 documents, now 10. The no-cache path is not a stub: it ranks by how many asked-for words are in the title (×3), headings (×2) and summary, returns snippet: null rather than inventing one, and every reader prints which path it took. cli.spec.mjs grew a second walkthrough that runs every subcommand ./eve docs lists — the first one takes only the first word of a usage line, which is the exact hole park shipped through.)
  • ETB.8.08 ./eve context <key> [--max-chars 20000]: the context pack an agent reads before starting — the task, the rules paragraph of its tracker (the text under the tracker's "rules" or "how to use this file" heading), its dependencies, the linked documents' relevant sections (the section whose heading or text matches the task's terms, not whole files), linked code paths with their sizes, sibling tasks in the same section, and any parked task that names it. Deterministic for a given tree. Verify: spec on a fixture; on the real tree ./eve context EI.1.01 names apps/oshun/admin/src/middleware.ts-class paths from its body and the Phase 0 rules.
    • (Done 2026-09-19: Evidence: lib/context.mjs + 4 specs on a fixture tracker shaped like the real ones (node --test tools/eve-task-board/lib/context.spec.mjs; family suite 226/226). The pack carries all eight things the item lists and is byte-identical across two runs. On the real tree the item's own test passes: ./eve context EI.1.01 is 16,594 characters and DOES name apps/oshun/admin/src — from ### 0.0 What the code is today (192), which is where that tracker expands AD = and is 132 lines from the item, together with the Phase 0 preamble and ## 0. How to use this file. The rule that finds it is stated once: a section with no checkbox in it is the tracker talking, and one that is an ancestor of, or a sibling under the same parent as, the task's own section is context; a section full of checkboxes is somebody else's work. TWO SCORING DEFECTS WERE MEASURED AND FIXED, both of which had produced a confident wrong answer. Splitting a backticked span on its slashes turned one task into 491 terms whose loudest were apps, src, docs and commit — words in every document here — so every section of V1/architecture/glossary.md scored within 20% of every other and the "best match" for a task about recording approvals was a section about availability tiering; a backticked span is now one term plus its basename, which gives 47. And summing hits without length normalisation let the longest section win for being longest, so the score is divided by sqrt(length/1000) — bm25's length normalisation without its term saturation, named as the approximation it is, and the fixture carries a deliberately long decoy section that the right answer must beat. The pack no longer claims "the best match": it prints 2 of the 47 terms this task names, because a document cited for one line has a closest section that answers nothing and the count is the fact a reader needs. --max-chars drops whole entries least-important-first and names them: dropping whole SECTIONS made --max-chars 6000 return the same 1,108 characters as --max-chars 2000, since the rules are four prose blocks totalling 15 KB and the only move was all or none; entry-at-a-time gives 1,913 at 2,000 and 9,282 at 12,000, and nothing is ever cut mid-sentence. The task itself is never dropped.)
  • ETB.8.09 ./eve docs stale: documents whose hash changed after a task that links to them was last edited, and tasks whose linked paths no longer exist. Verify: spec that plants each.
    • (Done 2026-09-19: Evidence: lib/stale.mjs + 4 specs that plant each case (node --test tools/eve-task-board/lib/stale.spec.mjs; family suite 231/231) — a document committed after the citing item was edited, a code path deleted since the link was stored, a document that left the catalog, a shipped task that is deliberately silent, a same-day pair, a tracker git cannot date, and real git blame --line-porcelain output whose blocks arrive in file order rather than flag order. updated_at COULD NOT BE THE TASK'S DATE and using it would have made this a permanent green light: all 24,849 rows carry today's, because it records when the importer wrote the row. The date comes from git blame of the item's own line — 169 trackers, 1,337 lines, 34.5s measured, announced before it is spent. On the real tree: 95 findings (76 documents, 19 slides), 0 gone, 12 cited by a name meaning more than one document, 79 same-day, 0 undated; eve-sota-gap-closure:15.5 (line edited 2026-09-01) cites docs/audits/EVE_SMX_SCORECARD.md (committed 2026-09-12) and a slide finding checks out the same way against git log and git blame directly. TWO DEFECTS IN ITS INPUTS WERE FOUND BY BUILDING THE CONSUMER. A stored link target is not always a path — a slide link holds the slide's ID and a doc link can hold ADR-0008 — so the first version reported every slide and every ADR citation as "no longer there"; resolution now handles all three shapes and a name that means two documents is its own answer, never a false alarm. And committed_at for all 1,721 slides and 3,121 Docs Center pages was the DAY THE INDEXER RAN, not a commit date, which made 222 of 298 findings spurious: a slide now inherits its deck's real commit date (9 distinct dates, deck 46 correctly 2026-09-09) and a Docs Center page, rendered by CI from a generated index with no committed file behind it, is honestly NULL and skipped.)
  • ETB.8.10 One extractor for Eve and for agents. Give ./eve docs export --format bff-corpus --scope full the chunk shape apps/oshun/bff/src/assistant/docs-search.ts loads, so tools/build-assistant-docs-search.mjs and task EI.5.04 of the presentation redesign (slides in Eve's corpus) read from this index instead of each parsing the sources again. The member scope stays empty. Verify: the exported corpus loads in docs-search.spec.ts's loader over a fixture, and docs-search-member-audience.spec.ts still passes.
    • (Done 2026-09-19: Evidence: lib/bffcorpus.mjs + ./eve docs export --format bff-corpus --scope full|member [--out], verified exactly as the item asks. The end-to-end proof is in the BFF, because a second copy of the parsing rules kept beside the writer would agree with itself and prove nothing: apps/oshun/bff/src/assistant/docs-search-eve-export.spec.ts builds a fixture repository, runs THIS command as a child process, and hands its stdout to the real AssistantDocsSearch.fromJsonl — 2/2, including that docs/guides/leases.html#renewing-a-lease deep-links through the reader's own anchor and that the member scope loads as 0 chunks, which is what fails search_docs closed. docs-search-member-audience.spec.ts and docs-search.spec.ts still pass (20/20). The REAL corpus was loaded too, not only the fixture: 49,231 chunks from 2,802 pages, 37.8 MB, read by the same loader, ranking V7/architecture/danu-meshing-and-nephthys-persistence.html — The single-writer replication broker (fencing tokens) first for "fencing token lease". 4 further specs on the eve side cover what the end-to-end cannot reach — the refusals, the clamps and the ordering (family suite 235/235). THE HTML THIS FORMAT WAS BUILT FROM IS NOT COMMITTED. tools/build-assistant-docs-search.mjs parses the rendered reader HTML, uncommitted since audit R-2, so it only works where pnpm docs:center has run; this 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 — so no HTML and no slugifier of our own. Measured on this tree: 2,803 of 3,121 pages have a markdown source; the 318 that do not are docs-center/** pages the generator synthesises and are counted as skippedPages, exactly as the HTML builder counts a page it cannot open, never invented. Anchors: 1,019 of those 2,803 pages publish any section anchor at all, and 1,012 of them get one — matching raw text reached 1,002, and the misses were markup, the reader's "the agentrun envelope" against the file's "The agentrun envelope", so inline code, emphasis and link syntax are stripped because the renderer strips them. A heading that still does not match gets an EMPTY anchor, which links to the page; a forced match would link to the wrong part of it. Output is sorted by href so two runs over one tree give the same bytes, chunkerVersion is derived from the chunker rather than declared, and the corpus goes through the CLI's injected writer rather than process.stdout, so a caller that captures output gets it instead of 37 MB arriving past them.)

10. The seam with Eve's workbench#

  • ETB.9.01 Read-only Eve tools over the committed database. In apps/oshun/bff/src/assistant/admin-agent-tools.ts add board_next (family, count), board_show (key) and board_search (text), reading TODOS/eve-task-board.sqlite under OSHUN_WORKBENCH_REPO_DIR with node:sqlite, operator scope only, results under TOOL_RESULT_MAX_CHARS and framed untrusted. Add them to the allowlist of the workbench-read skill (apps/oshun/bff/src/assistant/skills/workbench-read.ts) and re-stamp the prompt ratchet by its own procedure. Verify: tool specs over a fixture database; eve-smx-prompt-hash.spec.ts passes; an eval case "what is next on the Eve Task Board" names the task ./eve next prints.
    • (Parked 2026-09-19: Built, specced and pushed; the third verification clause needs an account that needs the owner. Since 2026-09-15 (235fca3ec9e, c28ce9e2cc4) an OpenRouter route is constructed only through a REGIONAL endpoint, and https://us.openrouter.ai/api/v1 answers HTTP 403 "Regional routing not enabled for this account — reach out to our enterprise sales team" while https://openrouter.ai/api/v1 answers 200 on the same key and model. Attested once to test: the provider rejected it on the wire exactly as the code's comment predicts, so no live assistant deck measurement is obtainable here. Unpark when regional routing is enabled and run EVE_SMX_EVAL_CASE_IDS=builder-board-next.)
    • (Unparked 2026-09-19: the owner made in-region routing optional the same day, so the global host serves a key alone under the same request controls (docs/audits/eve-sota-provider-subprocessor-review/owner-attestations/2026-09-19-openrouter-global-route.json; one live completion through resolveAssistantAgentBinding answered in 1.26 s from DeepInfra). What is left is the third clause alone: run EVE_SMX_EVAL_CASE_IDS=builder-board-next on the cheap binding and record what it named.)
    • (Done 2026-09-19: the third clause is measured. builder-board-next ran in BOTH full live decks (251 cases, k=3, served by DeepInfra) at 2/3 each, and the one failing run failed only EVE-VIS-211 — it wrote a bare :1734 where a citation must be pasteable — not on what it named. Driven once more directly through resolveAssistantAgentBinding for a quotable answer: the turn called board_next and replied "The next task on the Eve Task Board is: EI.0.14 … Family: presentation-center-eve-redesign … Source: docs/presentations/presentation-center/EVE-V1-REDESIGN-TODOS.md:743", which is exactly the key, family and path:line the tool returned and exactly what ./eve next prints. The case stays ADVISORY and the 1-in-3 shortened citation is left as the signal it is: it is a real quality defect in the answer, caught by a rule that exists for it, and not a reason to weaken the rule to :-free. eve-smx-prompt-hash.spec.ts is 11/11 after EI.0.17 re-stamped the census.)
    • (Parked 2026-09-19: An account that needs the owner. The live clause is blocked on the OpenRouter account's DATA POLICY, not on regional routing, which was made optional on 2026-09-19 and whose global host answers 200. FAILED ATTEMPT, 2026-09-19: the full deck was driven for real on the cheap binding, 250 cases times k=3, and every case failed 0/3; stopped after 41. With the route's logger enabled the error behind assistant_agent_provider_error is 404 No endpoints found matching your data policy (Zero data retention). Every Eve turn sends zdr true and dataCollection deny and allows only Baidu, DeepInfra and StreamLake; the account has no endpoint for deepseek/deepseek-v4-flash-0731 that satisfies it. Only the account owner can change those privacy settings, or admit a non-production route by a named variable (EI.11.00 option b). See the journal and the scorecard's 2026-09-19 re-stamp.)
    • (Dependency stated 2026-09-19: depends on presentation-center-eve-redesign:EI.0.15.)
    • (Corrected 2026-09-19 by the second board audit: the cause in the park note above is wrong and the tag is off. Measured the same day, one tool-bearing request per endpoint with zdr: true: baidu/fp8 and streamlake/fp8 answer that 404 and deepinfra/fp8 answers 200, so the account admits a zero-retention endpoint; what refuses every turn is toolOnly: ['baidu/fp8'] meeting zdr: true, both pins of this repository. EI.0.15 repairs the route and the live clause waits on it, not on the owner.)
  • ETB.9.02 ./eve promote <key>. Checked on 18 September 2026: work items are created only by Eve's create_work_item tool inside a turn (apps/oshun/bff/src/workbench/workbench-agent-tools.ts → intent-store.ts); apps/oshun/bff/src/routes/workbench.ts has queue, lease, brief, report, triage, shipped and verify routes but none that creates an item. So first add POST /v1/workbench/items there: operator scope, an idempotency key, the same intent-store call the tool makes, and requirementRefs carried through. Then ./eve promote posts the task brief of ETB.7.03 with requirementRefs: ["board:<key>"], using OSHUN_WORKBENCH_TOKEN, and records the work-item id in task_links. It refuses when the BFF is unreachable, naming the URL it tried. Verify: a route spec for the new endpoint (created, replayed key returns the same item, member token refused); the CLI spec against a stub HTTP server; one live call against a local BFF recorded in the evidence.
    • (Done 2026-09-19: Evidence: POST /v1/workbench/items in apps/oshun/bff/src/routes/workbench.ts + ./eve promote (lib/promote.mjs), verified on all three clauses. Route: 3/3 in workbench-create-item.integration.spec.ts against the REAL Postgres, because everything this endpoint promises is database behaviour — created 201, replayed key returns 200 with the same id and exactly one row, a reused key with different content is refused rather than overwriting, an unknown token is 401, and a missing key / unknown kind / empty title are 400. CLI: 4/4 in lib/promote.spec.mjs against a REAL HTTP server on a real port rather than a mocked fetch, which would agree with whatever headers this code decided to send and could not refuse a connection; it pins the wire shape (bearer token, x-workbench-agent, the per-task idempotency key, the brief), the refusals, and a genuinely closed port. LIVE CALL, recorded: a BFF booted on :4010 against a fresh oshun_etb902 database with all 65 prisma migrations applied (the dev database had no _prisma_migrations ledger at all, so it was left alone). ./eve promote eve-task-board:ETB.10.02 → queued … as wi-f803eee8b5b7b492c6cb326e5a331e0e [draft]; the same command again → already queued … as wi-f803…, one row in work_item; GET /v1/workbench/items/<id>/brief returns expectation.board = {key, source: TODOS/…:1775, promotedAt} and a body whose first line is Board: eve-task-board:ETB.10.02 — TODOS/…:1775; pointed at :4999 it refuses the workbench is unreachable at http://127.0.0.1:4999/v1/workbench/items. The server was killed, :4010 verified empty, the scratch database dropped, the env script deleted, and the link the live test wrote to the committed board was removed — a link to a work item in a dropped database is exactly the false claim this code refuses to write before a post succeeds. ONE DEVIATION, MEASURED NOT ARGUED: the item says to post requirementRefs: ["board:<key>"], and the database will not accept it. work_item_planning_binding_shape (migration 20260913050000, five days BEFORE this item was written) permits a non-empty requirement_refs only alongside a complete planning tuple — tenant, goal, goal revision, plan version, plan revision, plan work item, non-empty verification_plan_refs — with a foreign key into planning_plan_work_revision; a probe insert carrying only requirement_refs was refused by Postgres with that constraint named. A board key is not a planning requirement and fabricating a planning goal to carry one would be worse than the problem, so the provenance rides in expectation.board and the first body line, both of which the task brief returns, and the endpoint REFUSES a requirementRefs parameter naming the constraint rather than accepting and silently dropping it.)
  • ETB.9.03 ./eve pull: for every promoted task, read the work item's status and mirror leased, in-progress, shipped and verified onto the board (journal actor workbench), never the other way round, and never checking a box for a status below shipped. When the BFF is up, a promoted task refuses ./eve claim and says the workbench queue holds the lease. Verify: spec against the stub for each status and the refusal.
    • (Done 2026-09-19: Evidence: lib/pull.mjs + ./eve pull + the ./eve claim stand-back, 7 specs (6 in lib/pull.spec.mjs, 1 in cli.spec.mjs; family suite 246/246), each against a REAL HTTP server on a real port rather than a mocked fetch — a stub function agrees with whatever headers this code sends and cannot refuse a connection. Every status the item names is covered: leased, in-progress, shipped and verified each move the board row and write ONE journal line whose actor is workbench, not whoever ran the command. ONE DIRECTION, AND IT NEVER CHECKS A BOX: a task that was never promoted is untouched whatever the queue says, there is no write path back to the queue, and a mirrored shipped/verified sets the board row so ./eve next stops offering the task while the CHECKBOX stays for ./eve done and its evidence — the command says so in its own output. A status below shipped that this board does not share — draft, triaged, ready, parked, rejected — moves nothing and writes nothing, because the two vocabularies are not the same and mapping them would be the tool inventing meaning; they are counted and reported instead. Pulling twice moves nothing the second time and leaves one journal line. A work item the queue no longer has is reported and the LINK SURVIVES: deleting it would throw away the only record that the task was ever promoted. No token, nothing promoted (an answer, not an error) and an unreachable workbench naming the URL it tried are each specced. The claim refusal is proven AT THE DISPATCH, in a scratch repository root the CLI finds for itself, because park and unpark once shipped built, specced and listed with the dispatch never wired: ./eve claim f:A.1 exits 1 with "held by the workbench queue as wi-held (leased); release it there, or run ./eve pull if that is stale", while an unpromoted task is claimed exactly as before. It is answered from what was last mirrored rather than from a live call, so it still refuses with the workbench down — a stale leased is a refusal a person can clear by pulling, and a stale ready was never a lock.)

11. Cut-over and closure#

  • ETB.10.01 Rehearse on a scratch clone: import, close three real tasks of three different trackers through ./eve done with their true evidence, run each tracker's own checks (node scripts/v1-workbenches/ checklist-structure-lint.mjs, python3 tools/presentations/ check-generation-crosswalk.py, node tools/todos-board.mjs --check), and merge two divergent branches. Verify: every check passes and the rehearsal log is in the evidence.
    • (Done 2026-09-19: Evidence: rehearsed on a scratch clone and the log is committed at docs/agents/etb-cutover-rehearsal-2026-09-19.md. THE CLONE COULD NOT BE A FULL ONE AND THAT IS MEASURED, not assumed: the tracked checkout is 5.61 GB against 3.5 GB free on this box, so it is git clone --local --no-checkout from /root/workspace/oshun (hardlinked objects, df unchanged) with a non-cone sparse checkout of every *.md anywhere plus /tools, /scripts, /TODOS, /configs, /docs/presentations, the root manifests and /eve — every file the four steps read; only apps/ and libs/ SOURCE is absent and no step reads it. ./eve next answered on that clone with nothing installed but Node, which is also ETB.10.02's test. (1) ./eve import: 0 families, 0 tasks written, 24,845 unchanged, 7,693 dependency edges — a fresh clone already agrees with its trackers. (2) Three real tasks, three trackers, BOTH evidence writers: v1-domain-workbenches:BASE.2.b in the workbenches ledger's <!-- evidence: comment style, presentation-center:todos-ea3d1c9f and eve-sota-gap-closure:3.1 as nested bullets. (3) The three checks: checklist-structure-lint.mjs exit 0 and todos-board.mjs --check exit 0 ("registry clean: 1411 checkbox files, 51 families"). check-generation-crosswalk.py EXITS 1 AND DID BEFORE THE REHEARSAL TOUCHED ANYTHING: its output is BYTE-IDENTICAL on the untouched main worktree (diff -q clean), it is about T.20.08: it has shipped, so something must teach it; gated slides only is not enough — a missing teaching slide in the isis-chroma-runpod tracker, not a cut-over defect — and nothing gates on it: grep finds no reference in .github/, .husky/ or package.json, and the tool was added 2026-09-18 (4ca64ad5757). It is reported red rather than called green. (4) TWO DIVERGENT BRANCHES MERGED: ./eve git-setup registered the textconv and the driver, branch A closed isis-chroma-runpod:A.00.05, branch B closed phase-29-demeter:29.18.3.11 from the same base, and git merge exited 0 with the driver reporting merged 24856 tasks, 0 claims, 43 journal rows — the 25 MB binary board auto-merged beside TODOS/phase-29.md. The merged state was then CHECKED rather than assumed: all five closures read shipped, ./eve drift reports 0 edited / 0 checked / 0 unknown across 1,149 files, and the board regenerates clean. The three checks were re-run on the merged tree with the same three results. The clone was deleted.)
  • ETB.10.02 Cut over: commit the database, the regenerated board with the CLI instructions, the rule and CLAUDE.md changes in one commit series, and push both refs. Verify: on a fresh clone ./eve next works with no setup beyond Node, and prints the first task of the next family on the board.
    • (Done 2026-09-19: Evidence: the cut-over landed as this session's commit series, each part pushed to both refs as it was made: the committed database and catalog (TODOS/eve-task-board.sqlite, TODOS/eve-task-board-docs.sqlite), the regenerated TODOS/BOARD.md whose "How to use this board" section teaches the CLI (./eve next, claim, start, done, park, show), .claude/rules/task-checkbox-verification.md written around ./eve done / ./eve park / ./eve import with the hand-edit fallback, and CLAUDE.md's board paragraph naming ./eve next and ./eve resolve. VERIFIED THE WAY THE ITEM ASKS, on a fresh clone rather than on this worktree: git clone --local of the pushed branch, sparse-checked-out, NO node_modules at all (ls node_modules → No such file or directory), Node v24.15.0 and nothing else — ./eve next answered immediately with eve-task-board:ETB.10.02 and its path:line. Then, in that throwaway, the family's last two items were closed to show the roll: with eve-task-board at 0 actionable, ./eve next printed presentation-center-eve-redesign:EI.0.01 — the first task of the next family in the board's own ranking, with its section heading — and ./eve stats agreed (eve-task-board 0 actionable, presentation-center-eve-redesign 1136). The clone was deleted and nothing from it was pushed.)
  • ETB.10.03 Close the initiative: every ETB item checked or carrying a dated note naming its one blocker; a memory note written; the registry row for this file set to closed. Verify: ./eve stats shows no ready task in this family.
    • (Done 2026-09-19: Evidence: the initiative is closed on all three counts, and the verification holds. (1) EVERY ETB ITEM IS CHECKED OR CARRIES A DATED BLOCKER NOTE: 49 of the 50 boxes are [x], and the one that is not — ETB.9.01 — carries a dated Parked 2026-09-19: note and a blocked tag whose reason is external, naming its one blocker in full: its tools are built, specced and pushed, and its third verification clause needs a live assistant deck run, which since 2026-09-15 (235fca3ec9e, c28ce9e2cc4) can only go through a REGIONAL OpenRouter endpoint that answers HTTP 403 "Regional routing not enabled for this account" while the ordinary endpoint answers 200 on the same key and model — an account change only the owner can make. (2) A MEMORY NOTE IS WRITTEN: project_eve_task_board_initiative_complete_2026-09-19.md, indexed in MEMORY.md, recording what ./eve is and the five things that cost measurement to learn — the board is committed and merges row-level so ./eve git-setup comes first; ./eve done writes both the tracker and the database and the commit hook compares them; updated_at is import time and not edit time, so anything asking "when was this last edited" uses git blame; promote cannot send requirementRefs; and every document reader works without the cache. (3) THE REGISTRY ROW IS closed, with its priority, rank and focus removed — tools/todos-board-lib.mjs refuses a priority on a family that is not live work, which it said out loud on the first attempt ("only live work families take a priority") — and the note records what was built and what is parked. node tools/todos-board.mjs regenerates with 0 registry problem(s), and ./eve stats eve-task-board shows 0 actionable with 1 parked: no ready task remains in this family.)