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.
- Not Go. A zero-dependency Node CLI on the built-in
node:sqlite. Measured that day:node:sqliteloads 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.mjsis 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. - The database is committed, and it is made safe to merge. The owner asked
for a SQLite file in git. Two sessions pushed to
mainwhile 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, neverVACUUMed on an ordinary write, rollback-journal mode so no-walfile is ever committed. Size budget: 25 MB, enforced by a check. - The markdown trackers stay, and the tool writes through to them. 2,582
files reference
ISIS_TODOS_2.mdalone; 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 donealso 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. - One vocabulary with Eve's workbench, not a second queue. Eve already has
governed work items in Postgres (
work_item, statusesdraft → 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 sayverified. 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 promoteand./eve pullconnect the two (section 10). When the BFF is up, its queue is the lease authority. - Documents are indexed, not moved. The tracked markdown alone is 11,464
files and 136 MB (
docs/domains86 MB,docs/audits120 MB with evidence,docs/agents76 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 andgit 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.mjsrun bynode --test; no build step, nonode_modules. - Nothing here checks a box from a count, a grep or a test total.
./eve donetakes one task id and an evidence text and refuses anything else;.claude/rules/task-checkbox-verification.mdstill 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 parkenforces 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 checkand./eve fileswork at every commit.TODOS/BOARD.mdandCLAUDE.mdtell 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 totools/todos-board.mjsfor those four whenever the CLI answers exit 2, andtools/eve-task-board/shim-bridge.spec.mjspins that. So: keep exit 2 meaning "this command is not built", buildnext(ETB.3.01),check(ETB.1.05) andboard(ETB.5.02) so that each does at least what the bridge did when it takes over —checkmust still validateTODOS/registry.jsonuntil the trackers stop being the source — and givefilesa home before ETB.10.03 removes the bridge.- Task ids are the
ETB.n.nnin bold, not the section numbers, which run one ahead (section 4 holds ETB.3.x). The CLI'sPLANNEDmap names the wrong task in most of its refusals (claimsays ETB.3.02, which isshow). The right ones:importETB.2.01,nextETB.3.01,showETB.3.02,claimETB.4.01,doneETB.4.03,parkETB.4.04,checkETB.1.05,driftETB.5.01,boardETB.5.02,merge-driverandresolveETB.6.02,docsETB.8.07,contextETB.8.08,promoteETB.9.02,pullETB.9.03. Correct the map, and the assertion inshim.spec.mjsthat pinsclaimto ETB.3.02, with the next CLI commit. (Found 18 September 2026 by the session that wrote this plan; left to the session that ownscli.mjsso 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>thengit push origin <branch>:main).
2. Package, schema and the shim#
- ETB.1.01 Create
tools/eve-task-board/withcli.mjs(argument parsing and dispatch only),lib/db.mjs(open, pragmas, migrations),lib/paths.mjs(repository root by walking up topnpm-workspace.yaml; database atTODOS/eve-task-board.sqlite; cache at.cache/eve-task-board/), andREADME.md.node tools/eve-task-board/ cli.mjs --versionprints 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.mjscovers 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 --versionnow 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'})answers3and 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: -DatabaseSyncHAS NOcreateOPTION. Passingcreate: falsefor 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:sqliteis imported dynamically, inlib/db.mjsand 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. Nopackage.jsonin 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 incli.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(POSIXsh, mode 755) andeve.cmdexist since 18 September 2026 as a bridge: they find Node (also under~/.nvmwhen it is not on a non-interactivePATH), hand every call totools/eve-task-board/cli.mjsonce that file exists, and until then mapnext,board,checkandfilesontotools/todos-board.mjsand refuse anything else with exit 2. Keep that behaviour, add the script"eve": "node tools/eve-task-board/cli.mjs"to the rootpackage.json, and makeeve.cmdpass every argument through. Verify:./eve --versionandpnpm eve --versionprint the same line; a spec runs the shim throughchild_processfrom a subdirectory and with aPATHthat has nonodeon it. DONE 2026-09-18.node --test tools/eve-task-board/shim.spec.mjs→ 6 pass, 0 fail../eve --versionandpnpm eve --versionprint 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 withnodeonPATH, which is every machine that could run the assertion — so the spec pointsHOMEat a temporary directory whose only node is an nvm-shaped symlink, runs the shim withPATH=/nonexistent-bin, and gets the version line back. With an emptyHOMEtoo, it gets exit 3 andnode is not installed or not on PATH. AND THE SPEC CHECKS WHICH HALF ANSWERED../eve claimcomes 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: fivetodos-board.mjscalls still stand behind a missingcli.mjs.eve.cmdnow forwards%*to the CLI and forwards arguments in every bridged branch — the first version passed%2 %3and 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 %3survives, that all four bridged commands are present) and says why that is all it can do../eveis mode 755 in git (100755) andeve.cmdis 644. - ETB.1.03 Write
tools/eve-task-board/schema.sqland apply it through numbered migrations keyed onPRAGMA 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 ofready,later,parked,leased,in-progress,shipped,verified,rejected(the workbench's words;lateris the board's own), enforced by a CHECK. Verify:lib/db.spec.mjscreates a database, readsuser_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:openBoardcreates the ten tables anduser_versionreads 1;in_progressanddoneare 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.statusis the workbench's eight words plus the board'slater;tasks.parked_reasonisregistry.json's eight blockers;families.kind,statusandpriorityare 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:parkedwith no reason, and a reason on areadytask), and a claim's window must end after it starts.events.datatakes JSON or nothing, checked withjson_valid. AND ONE DELIBERATE NON-KEY:task_deps.depends_onis 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_onis enforced. Tables areSTRICT, 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.sqlis 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.versionandupdated_at, appends oneeventsrow, and never issuesVACUUM. 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 --stableof 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.mjsis the only way this tool writes.mutate()opens one transaction, runs the change, bumpsversionandupdated_at, appends exactly oneeventsrow, 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.dumpgained--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.--stableomits 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 issuesVACUUM, 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 becausedumpwas the first command that could fail: an error carrying a code becomeseve: <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 akey, no expired claim left on aleasedtask, 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 aleasedtask, a board over a budget the spec sets below the file's size, and a corrupt file. The command exits 0 witheve check: 6 checks, cleanand 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 withdatabase disk image is malformed, because SQLite walkssqlite_masterbefore the first statement and this schema spans pages. SoPRAGMA integrity_checkis not the corruption detector it looks like; - on a smaller board the open survives and the pragma THROWS rather than returning a row that saysokis 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.checkis 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 takesnowas an argument: the spec asserts the same rows are clean before the expiry and reported after it.--fileis accepted here as it is ondump, 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 checkis the commandTODOS/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 answeredcheckwith 0 or 1 the shim stopped falling through — by design, and theirshim-bridge.spec.mjsasserts exactly that — so the documented command quietly becameno_database.checknow 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--fileonly 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: readTODOS/registry.jsonand scan every tracked markdown file withscanMarkdownfromtools/todos-board-lib.mjs(it already returns each open item with its heading path, line, text andblocked: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 (eventsgains 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 neithereventsnor the sum oftasks.versionmoves. NOTHING RESCANS.lib/tree.mjsbuilds the SAME modeltools/todos-board.mjsbuilds —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 checksays so. The composition, so the choice is informed: the bodies are only 5.07 MB of text; thetaskstable is 11.85 MB, its five indexes 7.84 MB,task_body6.72 MB. Insidetasks,sectionis 2.65 MB across 24,472 rows for 4,091 distinct values andsource_path1.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 importrebuilds 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 captured29.19.1.10and 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 captured5.5and 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 —scanMarkdownhands 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:
titleis the first sentence (capped at 200 characters),task_body.bodyis the item with its indented continuation lines, HTML evidence comments included. Record the source anchor (source_path,source_line, andsource_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 againstbodyOfover the file on disk and assertssource_hashis the digest of exactly those lines —sourceHash(body)differs fromsourceHash(body + ' '), which is what a later write-through needs to prove it is editing the same item.titleis the first sentence, capped at 200 characters, with the id's emphasis unwrapped. - ETB.2.04 Map state: a
blocked:<reason>tag →parkedwithparked_reason(first tag; further tags intask_linksasblocked-also); an item in a registrydeferredsection →later; a family the registry marksblocked→ every taskparkedwith the family'sblocked_by; everything else →ready. A box with any other mark (the scanner counts them asoffVocabulary;[~]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.positionis the board's working order (queue selectors first, then file order). Verify: the per-family counts ofready,laterandparkedequal the Actionable, Later and Parked columns ofTODOS/board.jsongenerated 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 againstboard.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'sorderedlist IS the ready set in working order,item.reasonsis what parks one, and an open item in neither is in a section the registry defers.selectorMatchesis 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 inparked_reasonand the rest intotask_linksasblocked-also. AND THE REGISTRY'S BLOCKER IS A TOKEN PLUS PROSE, which the first run got wrong.blocked_byreads'human — 7.2 and 8.1 need the operator to label the 42-transcript sheet…', the whole string went intoparked_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 blockerupstreambecause 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 onhuman— and that case is how a silent?? 'upstream'default was caught, becauseplan()had droppedblocked_byon 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.adepends on nothing, its parent depends on its children). Unknown targets are kept as text intask_linkswith kindunresolved-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 inlib/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 INSIDE5.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+and5.5, 5.24, 12.10, and 14.7read 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 was29.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). ANupstreamTAG RESOLVES OR IS DROPPED, and a stated phrase does not: the registry definesupstreamas "Depends on another item", so the ids in such a body are prerequisites (148.8.14says 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-SDRandMUSDB18sit 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-6006states "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 checkgained 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 butsource_hashmatches 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 journaledited-in-markdown; when a box became[x]in markdown, mark the taskshippedwith actormarkdownand the commit that did it (git log -1 --format=%h -- <file>); when an item disappeared, mark itrejectedwith reasonremoved-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, soscanMarkdownnow also reportsdoneItemsin the same shape and from the same accumulation as the open ones (tools/todos-board-lib.mjs), and the importer applies the sametaskKeyto 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 needsPRAGMA defer_foreign_keys, because all five child tables referencetasks(key)and none declaresON UPDATE CASCADE, so with immediate enforcement the parent update fails against its own children. CASE 1 FOUND A LIVE DEFECT:source_hashis 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 — leftsource_lineat its old value. The board's whole contract with a worker ispath: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, andedited-in-markdownstays 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 TOmarkdown, 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, andgit status --porcelainis asserted empty. CORRECTED 2026-09-19, and the correction is the important half of this item. A merge brought three new families intoTODOS/registry.jsonand a batch of tracker edits, and the next import marked 110 tasksrejectedwith reasonremoved-from-markdown— about 95 of which were still in the markdown: 18 whose file the registry had RECLASSIFIED intophase-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 FALSErejectedIS 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 samesource_hash(byte-identical, so it only moved); same file and same key SUFFIX (the part afterfamily: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.mdgained 23 children of the formV1-P2-3516.a, each of which capturedV1-P2-3516and collided with its own PARENT, so the importer refused the whole tree — the second time that exact shape has bitten after29.19.1.10.aon 2026-09-18. The hyphenated id pattern now takes a dotted tail, and the token must still end at whitespace or punctuation soV1-P2-3403. Wire the thingtakes 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 checkis clean and./eve stats --jsonequalsTODOS/board.jsonfor 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 markedshippedwith actormarkdown— ETB.2.06's case 4, on the real tree rather than a fixture.)./eve checkprints7 checks, clean, and./eve stats --jsonagrees withTODOS/board.jsonon 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 checksaid so.dbstatfound the same 907 file paths stored 24,584 times intasksand again intasks_by_source(1.70 MB), and 4,130 heading paths stored 24,584 times (2.79 MB), so migration 2 givesfilesandsectionstheir own tables and saves 4,833,280 bytes — lossless, reversible, every value still there once, with atask_textview 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, splittingtask_bodyinto 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, becauseschema.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, notsource_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 statsis ETB.3.03's command and is built here in the minimal form this item's verification names; ETB.3.03 extends it withlistandfamilies..gitignoregains one negation, because*.sqliteis 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 fallbackposition— 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 nextreadytasks in working order whose dependencies are allshippedorverifiedand 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;--jsonis parseable and carries the same fields. DONE 2026-09-18:lib/next.mjs, 10 specs inlib/next.spec.mjs, 100 in the family. On the committed board./eve nextanswerseve-task-board:ETB.3.01— this item — and--jsoncarries 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 reachesshippedorverified; 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; andlater,parked,leased,in-progress,shippedandrejectedare 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 waytask_deps.depends_onnames 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 anunresolved-deplink instead and a cross-family id never becomes an edge. AJOINthere 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, andnode:sqliterefused 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 inlib/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 --jsonresolves this item by suffix and exits 0,./eve show 2.3exits 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 ownexitCodeand the CLI's wrapper honours it, printing at most five candidates and counting the rest (--jsoncarries 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 makeEI.1.02a suffix ofXEI.1.02— a typo resolving to a task instead of being refused. AND NOLIKE: 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 asfinished (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 — anddocumentsstays empty until section 9 fills it, which the fixture proved by having itsdoc_linksrow refused until thedocumentsparent existed. ALSO CORRECTED HERE, as the plan's own decision asked of "the session that ownscli.mjs": thePLANNEDmap named the wrong task in most of its refusals —claimsaid ETB.3.02, which isshow— and the assertions incli.spec.mjsandshim.spec.mjshad pinned the wrong answer in place. The map is now the plan's:claimETB.4.01,doneETB.4.03,parkETB.4.04,driftETB.5.01,boardETB.5.02,merge-driver/resolveETB.6.02,docsETB.8.07,contextETB.8.08,promoteETB.9.02,pullETB.9.03, pluslistETB.3.03 andsearchETB.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 listwith--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 inlib/list.spec.mjs, 113 in the family (./eve statsshipped 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 redyanswering "0 tasks" would let a caller conclude there is no such work, so--statusand--parked-reasonare checked against vocabularies the spec compares against thetasksDDL itself rather than trusting them to match, and an unknown--familyis refused too. AND NO PATTERN LANGUAGE:--textand--sectioncome off a command line where%and_areLIKEwildcards, so--text 100%would match anything beginning "100";instr(lower(x), lower(?)) > 0andsubstr(x, 1, length(?))ask "contains" and "starts with" and nothing else, with a task under no heading matching no prefix rather than every one.--limitdefaults 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 familiesprints the board's own columns and a spec compares every one of them againstTODOS/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 readywould have looked for a family called--status, so a flag whose value is another flag is nowno_flag_valuerather 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 aLIKEscan 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 inlib/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,ORand"as syntax, so./eve search 100%or./eve search node:sqlitewould 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 usesinstrrather thanLIKEfor 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 isWire the OneRoster publisher, which for a list of tasks is backwards, so the four column weights are0, 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--jsonreports which path answered.lib/cache.mjsholds 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 notready, has an unmet dependency, or has a live claim (the refusal names the holder and the expiry); on success setsleased, increments the task's fencing token and prints it../eve renew,./eve release, and an expired claim returning toreadyon the next write followqueue-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 ondone. DONE 2026-09-19:lib/lease.mjs, 10 specs inlib/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 30mprinted token 1, a second agent gotlease_held: … is held by spec-run until …, and./eve releasegave it back. THE NUMBERS ARE THE CONTRACT'S, READ NOT GUESSED:durable-leased- workinlibs/shared/resilience/src/eve-operation-policy.tshasattemptTimeoutMsanddeadlineMsboth 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 ISleased, 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:claimsis 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 nextsweeps as well as the writes do, becausenextis precisely the command that would otherwise go quiet: the task would sitleased, a statusnextdoes not offer, until somebody happened to run something that writes. A task leftleasedwith 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 saysexpiresAt: nullrather 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 ondone, which is ETB.4.03 and does not exist yet: the guard it will use isrequireLease, and the spec refuses a superseded token through every write that presents one today —renew,releaseandstart. - ETB.4.02
./eve start <key>(leased→in-progress) and./eve note <key> --text "…"(journal only). Verify: spec. DONE 2026-09-19: 2 specs inlib/lease.spec.mjs, and both commands driven on the committed board —claim,start,note,releaseleft the journal reading exactly that.startis 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-progressis a separate word fromleasedbecause they answer different questions — a lease says who may write, andin-progresssays 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'sversion, 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 tosource_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 HTMLevidence:comment in the workbenches ledger), setsshipped, 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>": refusesgpu,hardwareandexternalunless 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, setsparked../eve unpark <key>removes the tag and returns the task toready. Verify: spec for each, including the refusal, and thatnode tools/todos-board.mjs --checkstays clean on the scratch tree. DONE 2026-09-19:lib/park.mjs, 6 specs inlib/park.spec.mjs, 149 in the family. THE CHECK IS A VOCABULARY, NOT A JUDGE, and saying so is the honest part: forgpu,hardwareandexternalthe 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 reasongpu, rather than only that the text is in the file.unparktakes 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--checkruns; 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 secondparkon the item it had just parked answered "the tracker changed" — caused by the first write. Bothdoneandparknow update, in the same transaction, the edited item'ssource_hashand thesource_lineof 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, andpath:lineis 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 whosesource_lineis not a checkbox line are allshippedorrejected— 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 inlib/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.mjstakes 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-idandchild-outside-parent, because**BASE.1.c**is not underBASE.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;--afteris the flag for "beside that one". ANEvidence: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;--afterputs the item after the anchor's whole subtree, so a sibling never lands inside somebody else's children; and aprocedurefamily (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 inlib/amend.spec.mjs, 167 in the family. THESE ARE THE TWO COMMANDS THE WRITE POLICY EXISTS FOR (ETB.4.08):doneandparkonly ever append, whileedit --titlerewrites an item's FIRST LINE andrejecttakes its checkbox away — exactly the two edits a gate notices. Both are refused on anappendor aprocedurefamily, 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:rejectwrites 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 nextorders this graph and a loop in it has no answer, sodep addwalks 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).editkeeps 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 byeditand a row written by the importer answer./eve list --textthe same way. - ETB.4.07
./eve verify <key> --by <agent> --evidence "…": a second actor (not the one who shipped it) movesshipped→verified; the same actor is refused. Verify: spec. DONE 2026-09-19:verifyinlib/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 lastdoneorshippedevent, which is what the board actually knows. A BOX CHECKED IN THE MARKDOWN WAS SHIPPED BYmarkdown: 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 — andmarkdownitself 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, onlyshippedwork 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,addandeditwrite 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 awrite_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) andprocedure(the CLI never writes the file:doneandparkrecord the change in the database, print the file's own procedure and leave the markdown to it). Setprocedureforv1-v9-autonomous-contentandphase-180-remote-control, andappendwith the_( … )_note form foreve-sota-gap-closure; every V-series family isappend, anddoneorparkon one prints the registry regeneration it now owes. Verify: specs over fixture trackers: aparkon anappendfamily leaves every first line byte-identical and puts the tag after the note; adoneon aprocedurefamily 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 inlib/policy.spec.mjsplus one inlib/reimport.spec.mjs, 156 in the family. Seven families carry a policy:procedureforv1-v9-autonomous-contentandphase-180-remote-control, each with the sentence the CLI prints instead of writing;appendforeve-sota-gap-closureand for the four families whose paths feedcontent-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 ofscripts/content-coverage/generate-seed-registry.tsitself, 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 —apendread asfreewould let a write-through command edit a file whose text a gate pins, silently, which is how the nine broke on 18 September — socompileRegistryvalidates the vocabulary and requires aprocedurefamily to name its procedure, and./eve checkreports both. THE NOTE FORM WAS ALREADY APPEND-ONLY, which is why this is a policy and not a rewrite: the spec asserts aparkon 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. Underprocedurenot one byte of the file moves fordone,parkorunpark, and the board records the change anyway. THAT LAST PART NEEDED ONE MORE THING THE ITEM DID NOT ASK FOR: aprocedurefamily's board is deliberately ahead of its markdown, so an import reading the still-open box back asreadywould undo the record on the very next run — the tool silently forgetting what it was told. The importer now carriesshippedandverifiedforward 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 importapplies them (ETB.2.06). Verify: spec that plants one of each. DONE 2026-09-19:lib/drift.mjs, 4 specs inlib/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 —driftdescribes whatimportwould 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 reportedabsentrather thanchecked— 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-driftexits 1 for the gate ETB.5.04 asks for. -
ETB.5.02 Generate the board from the database.
tools/todos-board.mjskeeps scanning markdown for the kinds that are not work (inventories, proposals, templates) but takes families, counts, order and next items from the database whenTODOS/eve-task-board.sqliteexists, soTODOS/BOARD.md,TODOS/PARKED.md,TODOS/board.jsonand./eve nextcan never disagree. Verify: the existingtools/todos-board.spec.mjsstill 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, andtools/todos-board.spec.mjsstill 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'sblocked: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 storestitleOf(first sentence, 200) and the board printsplainText(first line, 150), so the ordered items are mapped back to the scanned ones bypath:lineand 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 driftis 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 boardBEFORE./eve importwrites 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
renderBoardemits 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). Keepnode tools/todos-board.mjs --nextworking 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 intools/todos-board.spec.mjs(40 pass) and 1 intools/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 --bya second actor,drift,stats. IT FOUND A DEFECT 173 SPECS HAD MISSED: step four answeredeve: 'park' is not a command.parkandunparkwere 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", andimportwas 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 newnextread only--familyand-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 checkand./eve drift --fail-on-driftto theverify:todos:registryscript inpackage.jsonand 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 importpasses. DONE 2026-09-19:tools/eve-task-board/gate.mjs, wired into.husky/pre-commitandverify:todos:registry, 2 specs ingate.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 withchecked in markdown: 1andedited in markdown: 1naming both keys, and the same tree after./eve importpasses with zeros — and the board then records the checked item asshipped, 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.mjsdid its work at import time and calledprocess.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 checkresolvedtools/todos-board.mjsfrom 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: aproposalfamily 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 importships the task with actormarkdown: 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 showsaysclosed by./eve doneorimportfrom the journal;./eve checkprints, 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 nodoneand noverifyevent, as a WARNING line that does not change the exit code, because a recovery is legitimate and hiding it is not;./eve verifyclears it, as the second look it is. Verify: specs on a fixture board: a task closed bydoneis not listed, one closed by checking the box and importing is, the same task afterverifyis 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.mjsis 270 passed, 3 failed on Node 22.23.1:check.spec.mjs,list.spec.mjsandshow.spec.mjsread a child's stderr as "one line per problem" or as one JSON document, and Node printsExperimentalWarning: SQLite is an experimental featurethere. The same two lines land in the stderr of every./evecall an agent parses. Fix it at the source rather than in the specs:lib/db.mjs'ssqlite()is the one placenode:sqliteis imported, and it drops that one warning — by name and text, nothing else — while it imports; the two direct imports inlib/cache.mjsand the one incli.mjsgo through it. Verify: the command above is green withNODE_NO_WARNINGSunset;./eve list --limit 1 2>&1 >/dev/nullprints 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 atextconvsogit diffand review show rows, not bytes:.gitattributesgetsTODOS/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:.gitattributescarries the line, 2 specs inlib/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,readyagainstshipped, 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 ingit diffas 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:.gitattributesis committed and true of every clone, whilediff.evetaskboard.textconvlives 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=evetaskboardnames the driver ETB.6.02 builds; until then the.gitattributescomment 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 taskkeyusingversionand theeventsjournal — a task changed on one side takes that side; changed on both sides with the same outcome is fine; changed differently takes the latershipped/verifiedover an earlier state and otherwise keeps both journals and leaves the taskreadywith amerge-conflictevent 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 inlib/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 bothshippedwith bothdoneevents, 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 aclaim-supersededevent and bothclaimedevents survive. THE CASE THAT DECIDES THE DESIGN is the one where neither side is obviously right: parkedgpuagainst parkedhuman. This driver does not pick. It keeps BOTH journals, leaves the taskready— available to whoever reads the conflict — and writes amerge-conflictevent 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.idandsections.idare 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:openBoardapplies migrations, which is a write, and writing tooursbefore 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 overoursonly once it is whole; the spec drives a failed merge and comparesoursbyte for byte afterwards. - ETB.6.03
./eve git-setup: writes thediff.evetaskboard.textconvandmerge.evetaskboard.driverentries into the clone's git config, and is called from the rootpackage.jsonpreparescript afterhusky../eve resolvedoes 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 mergesucceeds with the driver and produces both; without the driver the merge conflicts and./eve resolvefinishes it. DONE 2026-09-19:lib/gitsetup.mjs, 4 specs inlib/gitsetup.spec.mjs, 190 in the family, andpreparein the rootpackage.jsonnow runsgit-setupafterhusky. BOTH STATES ARE DRIVEN IN A REAL TEMPORARY REPOSITORY, which is the only way to know: with the driver installed,git mergeof two branches that each shipped a different task EXITS 0 and both survive with bothdoneevents; without it,git mergefails and leaves three stages in the index — the state every fresh clone is in, because.gitattributesis committed and git config never is — and./eve resolvereads:1:,:2:and:3:, merges them with ETB.6.02's driver, writes the result and STAGES it, after whichgit commitsucceeds. 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-setupis 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 fromprepareon everypnpm 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 inTODOS/BOARD.md,PARKED.mdorboard.jsonby 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 intools/eve-task-board/README.mdand 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 importand./eve board, the database by path,git checkout --theirsfor 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 (leftready, both journals kept), so nobody has to guess what happened to their work, and both name./eve importas 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 -vHbefore and aftergit gc). If a closure costs more than 50 KB of pack on average, movetask_bodyto 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 donewrites to the database — the taskshipped, the claim gone, one journal row — committed one at a time, thengit gc. Five layouts measured, pack size before and after, per closure: as committed (4 KiB pages) 5.91M → 23.96M = 92.4 KiB;task_bodyremoved (the item's own remedy) 3.94M → 16.02M = 61.8 KiB; 1 KiB pages 6.44M → 26.09M = 100.6 KiB; as committed withpack.window=50 pack.depth=2505.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 movingtask_bodyout 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 defaultpack.window=10git 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=250alone 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— becausepack.windowandpack.depthare repository-wide and a wider delta search makes everygit gcin 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 donein a loop or from a script". Keep every other rule. Verify: the file names the commands and the rule'spaths:front matter also matchesTODOS/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 importso the two never drift apart. Step 6 is./eve parkwith the install-before-you-park rule in one sentence. The banned list gains "calling./eve donein 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 gainsTODOS/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) andAGENTS.md: the Eve Task Board isTODOS/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 parkfor what truly cannot be done here and./eve helpfor the rest../eve showstands where the item wrote./eve context, becausecontextis 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, andshowis 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 claimand./eve donelines to run. Verify: spec that the brief contains each part for a fixture task and stays under the--max-charsit 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.mdrather than having one invented for it. Under--max-charsTHE BODY IS WHAT GIVES, because it is the one part the reader can go and read atpath: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 akind—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 underdocs/). The rules live in one table in the module with a spec per rule; an unclassified markdown file isotherand is listed by./eve docs unclassified. Verify: spec per rule; on the real tree fewer than 5% of documents areother, 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 areV3(51),V10(27),V1(12), the repository root (11),ISIS_GAPS(9+9),V1/planning(8) and theV7–V9roots (8 each) — V-series documents that sit beside their trackers rather than in adocs/directory. THREE RULES WERE WIDENED BY MEASUREMENT, NOT BY TASTE, and the first pass was 12.1% other:guidereaddocs/**when the item means a docs DIRECTORY (V2/docs/**and its siblings are 665 documents);architecturehad no rule forV1/architecture/**, whose 31 files are named for their subject rather thanARCH*; andspecnamedV1/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 INSIDEWALKTHROUGH/), 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.trackeris not a glob: it is whateverTODOS/registry.jsonclassifies, which is the one list of work files that already exists. - ETB.8.02 Fill
documents: title (first#heading, else the file name), domain (fromdomains.jsonby 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; onegit log --name-onlywalk 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 cis 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.mdsummarised 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 inTODOS/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 checknow asks about both files,./eve showreads 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 fromdocs/presentations/presentation-center/content/ *.json(path…/content/<file>.json#<slideId>, title, the guide ids that use it fromcatalog.json, summary = subtitle + takeaway), with itssources[]recorded asdoc_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 itsbytesare 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, anddoc_linksalready 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'ssliderule wasdocs/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 readsdocs/presentations/**/*.json. (2) The document sweep and the slide indexer were deleting each other's rows:indexDocumentsremoves 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-pagefrom the generator's own index, the repo-rootvdocs-search-index.js(window.__VDOCS_INDEX=), reusing the parser intools/build-assistant- docs-search.mjsby 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) anddocs-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 --helpdoes not print help — that builder has no flags and simply RAN, rewriting two committed artefacts (docs-graph-inventory.jsonfrom 3,256 pages to 3,121 and emptyingdocs-search-corpus.member.jsonl). Both were restored withgit 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, intotask_linkswith atarget_kindofdoc,code,task,slideordocs-page. From each document take markdown links to other tracked files intodoc_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-remediation226,v1-p2-backlog164,v1-domain-workbenches163,phases91,walkthrough-studio88,phase-29-demeter66,v-series-residue58,walkthrough-web-other43; 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.htmlhref 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 whileblocked-alsoandunresolved-dep— the importer's rows — are left alone, which a spec asserts. - ETB.8.06 The full-text cache:
./eve docs buildwrites.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;--kindslimits 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 KBevidencedocument reduced to its headings, and--kindsplus 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'ranksdocs/agents/incident-2026-08-15-jetsam-freeze.mdand 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 whensourcesalready 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.)
- (Done 2026-09-19: Evidence:
- 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 isisfilter, and a typo in either is a refusal that shows the vocabulary —--domain walkthroughanswers "Did you mean: Surface walkthrough (782)", becausedomainholds 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--sectionprints one; a slide is read out of its deck (…json#id, every field rendered, not a named few) and adocs-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.fprints 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 isOR+ bm25 (ftsExpression({match}), one quoting rule, not two); the filters had to move out of SQL into the ranked iteration, because a SQLLIMITcuts before they run and--kind adr --limit 1would return the top chunk of any kind and then show none; and one document could fill the page — uncapped,checkboxput 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, returnssnippet: nullrather than inventing one, and every reader prints which path it took.cli.spec.mjsgrew a second walkthrough that runs every subcommand./eve docslists — the first one takes only the first word of a usage line, which is the exact holeparkshipped through.)
- (Done 2026-09-19: Evidence:
- 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.01namesapps/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.01is 16,594 characters and DOES nameapps/oshun/admin/src— from### 0.0 What the code is today(192), which is where that tracker expandsAD =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 wereapps,src,docsandcommit— words in every document here — so every section ofV1/architecture/glossary.mdscored 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 bysqrt(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 prints2 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-charsdrops whole entries least-important-first and names them: dropping whole SECTIONS made--max-chars 6000return 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.)
- (Done 2026-09-19: Evidence:
- 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 realgit blame --line-porcelainoutput whose blocks arrive in file order rather than flag order.updated_atCOULD 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 fromgit blameof 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) citesdocs/audits/EVE_SMX_SCORECARD.md(committed 2026-09-12) and a slide finding checks out the same way againstgit logandgit blamedirectly. 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 holdADR-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. Andcommitted_atfor 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.)
- (Done 2026-09-19: Evidence:
- ETB.8.10 One extractor for Eve and for agents. Give
./eve docs export --format bff-corpus --scope fullthe chunk shapeapps/oshun/bff/src/assistant/docs-search.tsloads, sotools/build-assistant-docs-search.mjsand 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 indocs-search.spec.ts's loader over a fixture, anddocs-search-member-audience.spec.tsstill 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.tsbuilds a fixture repository, runs THIS command as a child process, and hands its stdout to the realAssistantDocsSearch.fromJsonl— 2/2, including thatdocs/guides/leases.html#renewing-a-leasedeep-links through the reader's own anchor and that the member scope loads as 0 chunks, which is what failssearch_docsclosed.docs-search-member-audience.spec.tsanddocs-search.spec.tsstill 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, rankingV7/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.mjsparses the rendered reader HTML, uncommitted since audit R-2, so it only works wherepnpm docs:centerhas 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 aredocs-center/**pages the generator synthesises and are counted asskippedPages, 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 "Theagentrunenvelope", 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,chunkerVersionis derived from the chunker rather than declared, and the corpus goes through the CLI's injected writer rather thanprocess.stdout, so a caller that captures output gets it instead of 37 MB arriving past them.)
- (Done 2026-09-19: Evidence:
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.tsaddboard_next(family, count),board_show(key) andboard_search(text), readingTODOS/eve-task-board.sqliteunderOSHUN_WORKBENCH_REPO_DIRwithnode:sqlite, operator scope only, results underTOOL_RESULT_MAX_CHARSand framed untrusted. Add them to the allowlist of theworkbench-readskill (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.tspasses; an eval case "what is next on the Eve Task Board" names the task./eve nextprints.- (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 throughresolveAssistantAgentBindinganswered 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-nextran 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:1734where a citation must be pasteable — not on what it named. Driven once more directly throughresolveAssistantAgentBindingfor a quotable answer: the turn calledboard_nextand 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 andpath:linethe tool returned and exactly what./eve nextprints. 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.tsis 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/fp8andstreamlake/fp8answer that 404 anddeepinfra/fp8answers 200, so the account admits a zero-retention endpoint; what refuses every turn istoolOnly: ['baidu/fp8']meetingzdr: 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'screate_work_itemtool inside a turn (apps/oshun/bff/src/workbench/workbench-agent-tools.ts→intent-store.ts);apps/oshun/bff/src/routes/workbench.tshas queue, lease, brief, report, triage, shipped and verify routes but none that creates an item. So first addPOST /v1/workbench/itemsthere: operator scope, an idempotency key, the same intent-store call the tool makes, andrequirementRefscarried through. Then./eve promoteposts the task brief of ETB.7.03 withrequirementRefs: ["board:<key>"], usingOSHUN_WORKBENCH_TOKEN, and records the work-item id intask_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/itemsinapps/oshun/bff/src/routes/workbench.ts+./eve promote(lib/promote.mjs), verified on all three clauses. Route: 3/3 inworkbench-create-item.integration.spec.tsagainst 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 inlib/promote.spec.mjsagainst a REAL HTTP server on a real port rather than a mockedfetch, 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 freshoshun_etb902database with all 65 prisma migrations applied (the dev database had no_prisma_migrationsledger 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 inwork_item;GET /v1/workbench/items/<id>/briefreturnsexpectation.board = {key, source: TODOS/…:1775, promotedAt}and a body whose first line isBoard: eve-task-board:ETB.10.02 — TODOS/…:1775; pointed at :4999 it refusesthe 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 postrequirementRefs: ["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-emptyrequirement_refsonly alongside a complete planning tuple — tenant, goal, goal revision, plan version, plan revision, plan work item, non-emptyverification_plan_refs— with a foreign key intoplanning_plan_work_revision; a probe insert carrying onlyrequirement_refswas 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 inexpectation.boardand the first body line, both of which the task brief returns, and the endpoint REFUSES arequirementRefsparameter naming the constraint rather than accepting and silently dropping it.)
- (Done 2026-09-19: Evidence:
- ETB.9.03
./eve pull: for every promoted task, read the work item's status and mirrorleased,in-progress,shippedandverifiedonto the board (journal actorworkbench), never the other way round, and never checking a box for a status belowshipped. When the BFF is up, a promoted task refuses./eve claimand 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 claimstand-back, 7 specs (6 inlib/pull.spec.mjs, 1 incli.spec.mjs; family suite 246/246), each against a REAL HTTP server on a real port rather than a mockedfetch— 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,shippedandverifiedeach move the board row and write ONE journal line whose actor isworkbench, 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 mirroredshipped/verifiedsets the board row so./eve nextstops offering the task while the CHECKBOX stays for./eve doneand its evidence — the command says so in its own output. A status belowshippedthat 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, becauseparkandunparkonce shipped built, specced and listed with the dispatch never wired:./eve claim f:A.1exits 1 with "held by the workbench queue as wi-held (leased); release it there, or run./eve pullif 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 staleleasedis a refusal a person can clear by pulling, and a stalereadywas never a lock.)
- (Done 2026-09-19: Evidence:
11. Cut-over and closure#
- ETB.10.01 Rehearse on a scratch clone: import, close three real tasks
of three different trackers through
./eve donewith 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 isgit clone --local --no-checkoutfrom/root/workspace/oshun(hardlinked objects,dfunchanged) with a non-cone sparse checkout of every*.mdanywhere plus/tools,/scripts,/TODOS,/configs,/docs/presentations, the root manifests and/eve— every file the four steps read; onlyapps/andlibs/SOURCE is absent and no step reads it../eve nextanswered 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.bin the workbenches ledger's<!-- evidence:comment style,presentation-center:todos-ea3d1c9fandeve-sota-gap-closure:3.1as nested bullets. (3) The three checks:checklist-structure-lint.mjsexit 0 andtodos-board.mjs --checkexit 0 ("registry clean: 1411 checkbox files, 51 families").check-generation-crosswalk.pyEXITS 1 AND DID BEFORE THE REHEARSAL TOUCHED ANYTHING: its output is BYTE-IDENTICAL on the untouched main worktree (diff -qclean), it is aboutT.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:grepfinds no reference in.github/,.husky/orpackage.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-setupregistered the textconv and the driver, branch A closedisis-chroma-runpod:A.00.05, branch B closedphase-29-demeter:29.18.3.11from the same base, andgit mergeexited 0 with the driver reportingmerged 24856 tasks, 0 claims, 43 journal rows— the 25 MB binary board auto-merged besideTODOS/phase-29.md. The merged state was then CHECKED rather than assumed: all five closures readshipped,./eve driftreports 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.)
- (Done 2026-09-19: Evidence: rehearsed on a scratch clone and the log is
committed at
- 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 nextworks 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 regeneratedTODOS/BOARD.mdwhose "How to use this board" section teaches the CLI (./eve next,claim,start,done,park,show),.claude/rules/task-checkbox-verification.mdwritten around./eve done/./eve park/./eve importwith the hand-edit fallback, and CLAUDE.md's board paragraph naming./eve nextand./eve resolve. VERIFIED THE WAY THE ITEM ASKS, on a fresh clone rather than on this worktree:git clone --localof the pushed branch, sparse-checked-out, NOnode_modulesat all (ls node_modules→ No such file or directory), Node v24.15.0 and nothing else —./eve nextanswered immediately witheve-task-board:ETB.10.02and itspath:line. Then, in that throwaway, the family's last two items were closed to show the roll: witheve-task-boardat 0 actionable,./eve nextprintedpresentation-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 statsagreed (eve-task-board 0 actionable,presentation-center-eve-redesign 1136). The clone was deleted and nothing from it was pushed.)
- (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 (
- 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 statsshows noreadytask 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 datedParked 2026-09-19:note and ablockedtag whose reason isexternal, 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./eveis and the five things that cost measurement to learn — the board is committed and merges row-level so./eve git-setupcomes first;./eve donewrites both the tracker and the database and the commit hook compares them;updated_atis import time and not edit time, so anything asking "when was this last edited" usesgit blame;promotecannot sendrequirementRefs; and every document reader works without the cache. (3) THE REGISTRY ROW ISclosed, with its priority, rank and focus removed —tools/todos-board-lib.mjsrefuses 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.mjsregenerates with0 registry problem(s), and./eve stats eve-task-boardshows0 actionablewith1 parked: noreadytask remains 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