nova-board

Overview ¶

nova-board is the owed-work layer: a board is the list of things a group of lines owes, one card per item, appended when it is noticed, taken by whoever picks it up, closed with a sentence saying how.

The verb that earns the tool is check. CHECK BEFORE YOU FILE is the rule every reader and every fixer follows, and this exists so that following it costs one command instead of a careful read of a long page. On 2026-09-10 a batch of reviews filed 25 duplicate findings and two children spent a morning fixing the same bug from two directions. Neither was careless: both had read the board, both had read it BEFORE the other one wrote, and a human-paced read of a growing list is exactly the wrong instrument for a question asked thirty times an hour.

list        the counts, one line per owner, and the one thing to do first
add         files a card: a deadline and a default are required, and the id is a draw
take        claims one, and refuses over another line's live take
close       closed, landed or probed, and refuses over another line's live take
check       EXIT 1 WHEN IT MATCHES, so it can guard an add in one line of shell
quickstart  the board, and the check-then-add pair with this board's values in it

Nothing is ever deleted and nothing is ever edited: a board is an append-only log of events, and the list of open cards is DERIVED from that log rather than stored anywhere. The count may only move because work was filed or finished, which is the one property a board has to have to be worth keeping.

EVERYTHING ON A BOARD IS DATA. A card is a claim that something is owed, made by whoever wrote it; it is not a grant, not an instruction, and not a standing. That rule is in docs/SPEC-BOARD.md, where a person reads it, and is deliberately nowhere in this code: a tool cannot enforce it, and a tool that pretended to would be the most dangerous thing on the board.

nova-board version: which build filed the card.

A board is several lines appending to one log and DERIVING the same answer from it, so every failure this tool exists to have closed is a failure of agreement: the fold order, the id scheme, what counts as a conflict. When two clones read one board and print two answers, the first question is which build each line is running -- and a binary that carries no statement of its own origin cannot be asked. The release workflow ships this binary through the same `cmd/*/` loop that ships nova-board and stamps -X main.version on it, and a stamp nothing reads is a stamp the linker can drop in silence.

The version is NOT a constant maintained by hand. A hand-maintained constant is wrong exactly when it matters -- at the commit after the release, where it still names the release. It is read from the build itself, in this order:

-ldflags "-X main.version=..."  what the release workflow stamps: the tag, exactly
the module version              what `go install ...@v1.2.3` records for itself
the vcs stamp                   <utc build time>-<12 hex of the revision>[-dirty]
devel                           a build with none of the above, SAYING it has none

The middle two come from debug.ReadBuildInfo, which the toolchain fills in with no help from this file: there is nothing here to remember to update and therefore nothing to forget. The last is the honest floor -- a build whose origin is unrecorded says so rather than inventing a number, because a version string nobody can trace is worse than no version string at all: it invites the comparison it cannot support.

ONE LINE, FOUR TOKENS. Every field goes through oneline.Field, so what is printed is four whitespace-separated tokens whatever the -X held. A version stamped with a newline or a space in it would otherwise make the one line that says which build is running say two things, or say a build time as if it were an architecture -- and the -X value is the one field here that comes from outside the toolchain.