# lib/workflow — the shared feature board

A board is one file per feature: what the feature is for, what it promises, why it sits
where it does, and the two signatures a person gives it. The `board` tool, `team`'s round,
and the served page read and write those files through this directory, and no surface may
decide one of their rules for itself.

What belongs here rather than in `extensions/board/`: the record and the boundary a read
passes, the lifecycle that decides who may do what, the store that is the only writer, and
the bodies every surface renders. The extension keeps the tool, its schema, its commands,
its transport, and the browser bundle, which receives `view.ts`'s snapshot as its data and
the spliced rules below as its source. The user-facing contract is
[`docs/extensions/board.md`](../../docs/extensions/board.md); the decisions behind these
rules, with the conditions that would revisit them, are
`AGENTS.md` for the rules, and the code for the limits it states.

Each module below owns one paragraph: what it is, and the couple it must not drift out of.
The one-line index of the same modules is the `workflow/` block of [`../README.md`](../README.md).

## The record and its boundary

### card.ts

The shape one card file holds, the caps a write is held to, and the parser that decides
whether a file on disk is still a card. `CARD_VERSION` with `SUPPORTED_VERSIONS` and
`ENDED_VERSION` say which builds wrote what; `Card`, `CardOwner`, `CardNote`,
`CardBlock`, `CardTransition`, `CardLanded`, and the `EndedCard` a finished card becomes
are the record, and `MAX_TITLE` / `MAX_PATHS` / `MAX_PATH` / `MAX_PLAN` / `MAX_NOTE` /
`MAX_NOTES` / `MAX_LOG` / `MAX_DEPENDS` are its caps. Ownership, priority
(`PRIORITIES`, `DEFAULT_PRIORITY`, `priorityOf`, `priorityRank`), and the `BLOCKERS` a
block names, with a 200-char reason, are part of the same record, so a lane's `ownerless`
invariant can be read off the lane table rather than restated.

The `normalize*` boundary is what the model's arguments pass: `normalizeTitle`,
`normalizePathHints` (repo-relative hints, never claims), `normalizeNote`,
`normalizePlanPath`, `normalizePriority`, `normalizeCardId`, `normalizeBlock`. Each answers
`{ error }` instead of throwing, because a bad argument is a refusal a reader can act on.
`isCard` is the shape every read is held to and `isEndedCard` the older finished record —
`read.ts` maps a past shape onto this one, so the router, the tool, and the page see the
same record or none.

Three rules live here because two surfaces need each and a second copy would be a second
answer. `matchesQuery` is the rule `list`'s `query` and the page's filter box both answer,
spliced into the bundle as `MATCHES_QUERY_JS`. `holds` (the id decides when both sides have
one) with `cardRef` and `signatureOf` names a card and notices it changed; `dependsOf`
reads a card's own links. `laneSince` says
when the card entered the lane it is in, computed from the lane log because a stored clock
would be one more field to keep true.

### kind.ts

What kind of work a card is (`type`) and whether it breaks an existing user (`breaking`),
the two facts a changelog line answers. `CARD_TYPES` is the closed table — feature, bug,
refactor, docs, test, chore — and `normalizeType` refuses anything else rather than defaulting
to a kind nobody chose, so an unclassified card draws nothing. `normalizeBreaking` takes a
boolean and `breakingOf` reads an absent marker as not breaking, because the record writes
the key only when it is true. Both fields are optional, so a card written before the kind
existed is still a card; `card.ts` holds the two keys and imports the type, which is why this
is its own module rather than four more rules in that record's row.

### read.ts

The one gate a card file read passes. `readCard` maps every version this build can read
onto the current record — a v1 file's `status`, `plan`, and `blockedBy`/`blocker` become
`lane`, `planPath`, and `blocked`, and the four-lane log's `todo` / `doing` become
`backlog` / `execute` — then stamps `CARD_VERSION`. The map is read-time only: no file is
rewritten, so a board full of older cards reads as a board rather than as a pile of
refusals, and each card takes the new shape on its next write.

### lanes.ts

The lane vocabulary as data, and the one table that decides what each lane means.
`LANES` / `Lane` (backlog, plan, execute, blocked, done) and `LANE_RULES` carry each
lane's label, its empty word, its colour role, and the three facts the rest of the board
reads off it: `ownerless` (the pool), `terminal` (finished), `pulled` (held to a WIP
limit). The page receives the table in its snapshot and the tool's schema is generated
from `LANES`, so a lane cannot be spelled one way in a schema and another in a renderer.

`TRANSITIONS` is the other half: every lane change a move may make, with the
`Requirement`s (`REQUIREMENTS`: contract, approval, review, artifact, blocker, waiting) in
front of it. `steps.ts` enforces them, and `transitionOf` / `targetsFrom` are the same table
asked about one move — `targetsFrom` is the list a refusal prints. The tool's `lane`
description names `movableLanes()` instead: which targets exist depends on the card's own
lane and a schema has no card, so it offers every lane but `backlog` and leaves the route to
the refusal. `laneIndex` and `isLane` are the questions left.

### contract.ts

What a card promises before it may be executed: `Contract` (goal, acceptance, scopeOut,
`verify`, and the `Sign` that approved the wording), `CONTRACT_FIELDS` / `CONTRACT_LINES` /
`MAX_CONTRACT`, and the boundary `normalizeContractField` applies to one line of a model's
argument. The plan file says how; the contract says what and why, so a session that picks a
card up does not renegotiate it and one that finishes it can be checked against something it
did not write. The two lists are one fact each: `CONTRACT_LINES` is every line a complete
contract states, and `CONTRACT_FIELDS` is the keys `isContract` requires — the fourth is not
one, because a contract stored before `verify` was required has no such key and must still read.

The sign is part of the contract because it is a statement about *this* wording:
`mergedContract` drops it when an edited line arrives, and `missingContractFields` /
`contractComplete` / `contractApproved` are the gate `steps.ts` asks. `normalizeInstruction`
is the one line an overriding sign says why, which `isSign` and `isContract` also hold a
stored value to.

The merge a review became lives in the same module: `Landing` on a card, `LandingProof` as a
door reads it, and `resolveLanding`, the one rule that answers which commit a `done` records.
The proof carries the default branch's first-parent chain, oldest first; a reviewed commit
names itself only when it is a merge or the chain's tip, and any other merge is found through
its non-first parent — the branch the merge carried. A plain ancestor is the older tree a
pre-merge sign was taken in, and `reviewedAncestor` refuses it; a commit no merge carries gets
`unlandedReview` and the override. `landingGate` and `landingFor` are the two questions
`steps.ts` asks of the same rule, and `movedTree` is the merge that rewrote the review's own
lines.

### links.ts

The dependency graph, answered over an index of the whole board. A link is one id in the
waiting card's own file — the reverse edge is never stored, because a second copy of one
edge is a copy that can drift. `BoardIndex` / `indexOf` build the map; `blockersOf` says what
is unfinished, `lanesText` is a card list as a reader meets it (`#2 (execute), #3 (blocked)`,
with `titles` for the one surface that has room for a title), and `waitingOn` is the same
unfinished list as one sentence. `dependentsOf` / `openDependentsOf` / `dependedOn` say what
a drop would strand or block, `wouldCycle` refuses a loop, and `normalizeDepends` stores one
edge once. A dependency naming a card that is not on the board is refused when it is written,
and a card cannot be dropped while another waits on it.

### limits.ts

How many cards a pulled lane may hold, and the sentence that refuses the next one. The
board is a pull system whose binding constraint is the person who approves and spot-checks,
so `plan` and `execute` are gated rather than advised. `WipLimits`, `DEFAULT_WIP` (3 and
5), `MAX_WIP`, and `normalizeWip` over `clampInteger` turn the settings into numbers, so a
typo cannot stop a board; `limitOf` / `countIn` answer a lane's `Requirement`; and
`wipRefusal` names the count, the limit, and the ways out.

The arithmetic only: where the numbers are read from is `config.ts`, which hands them to
`applyOp` whole so `rules.ts` stays pure.

### artifact.ts

Whether a path is a plan of this repository, which is the one thing the board asks of the
plan store. `PlanArtifact` is the resolved path that was proved and `ArtifactCheck` is that
path or the sentence refusing it — one fact for the state machine to order. `planForContract`
requires a `.md` this repository's store holds whose file is there; `planForExecute` requires
the recorded plan to still be there, named with the card and `contractRoute` as the way out.
The path rules come from [`../plans/paths.ts`](../plans/paths.ts), so the board and the plan
tool cannot disagree about what a plan path is; the board still never reads a plan.

`ArtifactProof` is why the fact is a question as often as an answer: a door proves a plan before
`store.mutate` takes the board's lock, so a fact taken there is a fact about a moment the write
has left. `proved` takes the deferred answer where the rule asks for it — inside the locked pass —
and a caller that already holds one may hand the fact itself. `planIsGone` and `gonePlans` are the
same stat asked for the drawing side: the `plan` and `execute` lanes only, because those are the
cards a reader can still rescue.

## The lifecycle

### rules.ts

The card lifecycle as a pure function of the card, the operation, who asked, the clock, the
other cards, and the board's limits. `Actor`, `CardOp`, and `createCard` define the inputs;
`mayOp` is the same decision without the write, which is what `team` asks before it sends a
handoff — a dry run is a question, not a mutation performed as a fake session; and `applyOp`
is one switch over the card *and* the board index, so a lane change cannot be reachable from
one surface and refused from another.

The one write bumps the revision, appends the lane log, and clears what the lane
left behind. Two shapes of failure matter here: a refusal is `{ ok: false }` with its reason
and the card untouched, while a no-op is `{ ok: true, changed: false }` — the preconditions
already hold, so nothing is written and the revision does not move. Nothing here touches the
filesystem or the bus: ownership is advisory, and the store's write lock is what makes a
concurrent writer lose.

### steps.ts

What each operation a card alone can decide does — the gates, the lane changes, and the sentence
a refusal carries — split from the table that dispatches it so the dispatch reads as one switch
and the rules read as one decision per operation. `claim` pulls a pool card into `plan`; `assign`
hands one over and moves only a pool card's lane; `release` returns it; `move` walks
`TRANSITIONS` and asks every gate; `contractOp` writes the four lines and the plan path;
`approve` / `review` record the two human gates, both refused to the card's own holder, and
`review` also signs a card already in `done` when an override gives the one line saying why;
`note` / `edit` / `offer` / `archive` / `drop` keep their own rules, and a drop is refused
while something waits on the card. `reseat` is the one operation that moves no lane and changes no
word of the work: it re-points a card's owner id to the session wearing that owner's label, which is
what a `/resume` needs before it can write the card its old id still holds.

Each answers a `Prepared`: a refusal sentence, a no-op, or the fields a write would apply.
`{ fields: null, changed: true }` is the one operation that changes the board without
changing the record — `archive` moves the file, and that is the store's write.

### the announcement, in signs.ts

A sign nobody heard is a gate nobody knows is open, so the card records when its message was settled:
`Sign.told`, absent while the sign still owes one. `signRecord` reads the sign a gate holds,
`owesAnnouncement` says whether a call owes the message — a fresh stamp always, a repeat only while
the record says the first never landed — and `announced` writes the moment, refused to anybody but
that sign's own signer (`signedAs`, so the person's mark counts and a session wearing the lead's name
does not). A failed send leaves the fact absent, which is what makes a repeat sign the retry.

### the spot-check, in lead.ts

`review` is the one sign whose record is a *run*, so it lives with the signer rule rather than with
the other steps: the contract's `verify` line names a command, the signer's own call runs it, and
`evidenceFor` holds the result to three rules rather than trusting it — the card's contract has to
name that command (a green for the *old* wording is the failure this exists to prevent), the exit
has to be zero, and an override carries none, because an instruction is not a check. The accepted
run rides the sign as `Sign.verified`, and the `done` gate reads it: a card whose contract names a
command needs a result newer than the sign's own writes. The sentences are `SIGN_WORDS`'s here,
with the rest a refusal says.

### reclaim, in lead.ts

The other operation `steps.ts` cannot hold, because its gate reads a fact the card does not carry:
whether the session holding it is still running. A session takes its own card back (a release by
another name), the lead takes anybody's, and a peer takes one only from an owner whose record says
it stopped — `quiet` or `gone`. `absent` is refused with no fact at all, because a session that
never joined this bus writes no record either. The fact is bound to the owner it was read for, so a
card that changed hands under the read is taken on nothing.

What returns to the pool keeps the notes and the contract, and keeps a spot-check unless the
reclaimer is its signer: the sign is evidence, and only the person who made it withdraws it. It
lives in `lead.ts` because that module already answers who may act on a card's two gates, and this
is the same question asked of another verb.

### actions.ts

The actions and which of them only read the board, as one table. `BOARD_ACTIONS` /
`BoardAction` is the list the tool publishes, in its description order, and
`BOARD_ACTION_KIND` is a `Record` over every one of them, so an action added to the tuple
does not compile until somebody says whether it reads. `BOARD_READ_ACTIONS` is the same
answer for a reader that has to name the reads, `readActionsText` is that list as the phrase
plan mode's refusal prints, `boardWriteRefusal` is the refusal a write action gets there,
and `isBoardReadAction` answers for one unnormalized value, where anything unknown is not a
read.

One table, so the tool's enum and the read-only policy cannot disagree: `lib/policy.ts`'s
`isBoardRead` and `board`'s own schema both read this one, so a second read action cannot be
admitted by one and refused by the other.

## Storage and identity

### store.ts

The backend: `BoardStore` over `<agent-dir>/board/<repo-key>/cards/*.json`, with `createStore`
and the one construction point `openBoard`. `BOARD_DIR_NAME` / `CARDS_DIR_NAME` and
`boardDirFor` are the layout a caller names, the `ended/` and `archive/` piles sit beside
`cards/`, and `key`
is the hash it was filed under, carried rather than read back off the directory's last segment
because `session-bus` files this repository's records under the same key.

Two writes take turns. `create` hard-links a temp file onto the name, so two adds cannot share
an id and the loser retries with the next one. `mutate` takes the board's write lock, re-reads the
card and the board, and renames over the old file — a write says "apply when this holds", never
"force this state", and the lock is what keeps a peer's write from landing between the check and
the rename. The lock is the board's because the questions a check asks are about other cards: has
this lane a slot, would this link close a loop, does anything wait on the card being dropped.
`scan` is one pass answering the cards,
the files it refused (`Skip`), and the bytes they occupy, so a page's frame reads the board
once; `list` and `skipped` are its two halves, and `list` orders a lane by priority then id.

`archive` renames a finished card's file into the `archive/` pile beside the cards without
rewriting it, so `read` finds a card in either pile while `list` still reads the board alone —
and only the board's pile is writable: `mutate` hands `applyOp` the place it found the card
(`Place`), and every operation but `drop` is refused there. `archived()` / `archivedCount()` are the pile on request
and its count, a number spent by an ended or archived card is never handed out again, and nothing
prunes: `archive` and `drop` are the two ways a card leaves the board.

### lock.ts

The board's write lock: `lockBoard` creates `<board>/.lock-board` exclusively, waits
`LOCK_WAIT_MS` for a live holder, takes over a lock older than `LOCK_STALE_MS` — a holder needs
one board read and one rename, so a file still there seconds later is a process that died inside
its window — and hands back the `release` that clears it. `lockPathFor` is that one name, shared
by every writer whichever pile the card it touches lies in.

The exclusive create is the decision, not a read before it. `release` removes a file only while it
still carries its own token, so the victim of a takeover cannot open the board to a third writer.
The unit is the board, not the card — `mutate` reads the whole board, so a per-card lock let two
writers answer one rule from two snapshots, a rule passed twice rather than a file overwritten —
and `concurrency.test.ts` is that pair. `create` takes none, and neither does a read.

Neither removal is a plain unlink: a stat and a removal are two instants, and so are a read and a
removal. Two takers of one abandoned lock both removed, the second took the first taker's fresh
lock, and both creates then succeeded — two writers on one board. So both go through
`proven-remove.ts`, which proves the file it moved aside: the age rule for a takeover, the token
for a release. A fresh rival's lock is put back and the create that follows decides between them;
`beforeTakeOver` is the suite's seam into that window, since a rival written from `create` fires
before the age check and is never stale.

### proven-remove.ts

`removeIfProven(path, prove)` — remove a file only if the copy this call took aside proves it. A
rename is one instant, so the file `prove` reads is the file that was at the name; a name taken
again meanwhile keeps its newer file, and the moved copy is removed either way so a refusal leaves
nothing beside the one it kept. `false` is not a failure: something was there that this call did
not earn, or nothing was. The proof is the caller's question — a lock's token or age, a page
note's token — and this module is the window and the restore, which is why `lock.ts` and
`page-pointer.ts` share it rather than each carrying a copy.

### config.ts

The `board` and `team` sections of `bytefly.json`, read once: `TeamConfig` (`lead` and
`teammates`), `BoardConfig` (that plus `wip`), `DEFAULT_TEAM_CONFIG` / `DEFAULT_BOARD_CONFIG`,
`normalizeTeamConfig` / `normalizeWipConfig` / `normalizeBoardConfig` — each key falling back on
its own, so a file that sets one keeps the others — `readTeamConfig` (what the footer draws from)
and `readBoardConfig`, the project's section over the global one. The default is one lead and five
names, from `gavin`, and a stated list replaces it whole — `[]` included, which is a team of nobody.
The sections are read together when the store opens, because a board that asked the file on every
write would spend a stat to answer a question nobody changed. `addTeammate` writes the whole list
the project then states.

The arithmetic of a limit stays in `limits.ts` and the signer rule stays in `signs.ts`; this
module is the file. `extensions/bytefly` imports it too, so the settings screen shows what the
loader keeps rather than a copy of the default.

### session.ts

What a board call works on and who it writes as: `BoardSession`, `TeamStanding` — what the
last join did, so a claim joins and `/board status` can say — and `openBoardSession`. One
store per working directory, opened on first use and remembered, because the repository
lookup shells out to git; a failed open is not remembered, so one bad read does not outlive
the call that hit it. The identity is the pair a card records: the Pi session id, which keeps
a card held across a rename, and the name the bus already holds for it, else the first free
`team.teammates` name, else the id-derived one.

One session per *host*, not one per extension: `board` and `team` load with separate module
caches, so two sessions would mean the seat `/board` sets is invisible to every write `team`
makes. That state lives in the closure, never in a module variable, and `busDirFor` builds the
bus's directory from the key the store carries, so the roster cannot be moved by regrouping
the board's own files. `roster(cwd)` is the one read of the records the bus files there —
`who` asks it for a name, the join for the record that decides the ask, the rollup for the
owners it folds, and `/team` for who is here — so no caller re-derives a directory or a parse,
and a failed read is the caller's to report. `planDir(cwd)` is this repository's plan store through
[`../plans/paths.ts`](../plans/paths.ts), which is what a card's plan file has to be inside. `cross`
is the lane crossing every write reports: two doors make one — the board's `move`, `release`,
`reclaim` and `drop`, and the round's `reclaim` — so the rule is asked here, loaded on the first
crossing, and a third door cannot forget it.

### claims.ts

A card in `execute` holds its paths, and nothing else does — the one sentence the bus's path
claims witness. `holdPaths(claims, ctx, result)` reads the `MutateResult`'s `previous` card
against the one the write left, so a write that stays in its lane costs no bus call at all, and
only the two crossings ask: entering claims the card's `paths` and names the ones another session
already had, leaving releases them. A release frees the writer's claims and nobody else's, so a
card taken out of `execute` by another session keeps the holder's claims until that session
stops: the clause names them (`2 paths stay held by api-core until it stops`) rather than saying
nothing, because the new owner's next claim is refused over exactly those paths. The writer is
compared with the previous owner on labels, so a session taking its own card back — or a peer
wearing the holder's name — reads as a self-release and stays silent. `Claims`/`busClaims` are the
seam that keeps every case here off a bus, `reclaimHeld` re-takes the paths of the cards a resumed
session is already executing, and nothing here may cost a card write: no bus is silence, a refusal
is a sentence, and a conflict is neither.

### verify.ts

The acceptance command a contract may name, and the one run a spot-check records. The board
executes nothing of its own: `verifySpotCheck(card, cwd, run, now, tree)` reads the contract's
`verify` line, runs it through the `VerifyRun` seam, and answers either the record
(`{ cmd, exit, at, root, branch, checkout, sha }`) or the sentence that stops the sign — so the
tool's `review` and the person's `/board review` word a red command the same way, from one body.
`runVerification` is the production seam: a shell in the card's directory, its merged output
clipped to `MAX_VERIFY_OUTPUT` and killed with its tree at `VERIFY_TIMEOUT_MS`, which is the only
thing keeping a sign finite. `treeOf` is the `TreeReader` that names the tree the run was taken
in: the commit, the branch, and `checkout` when the tree is the repository's checkout rather than
one of its worktrees — the one word a path does not say, since work is made in a worktree and
lands in the checkout. A board outside git records the run without any of it. The output tail is
for the refusal and never the card: a record keeps a verdict, and a buffer in a card file would
grow with whatever the command printed.

### join.ts

The one join every door asks for, so a claim through `board` and one through `team` cannot
answer it differently, and neither can the page. `JoinSession` is the standing, the clock,
and the roster — all the rule reads — and `joinTeam` asks while the roster holds no `live`
record under the name being asked for: a standing stays true after the bus stops, the TTL
prunes the record, or `/resume` takes the seat over, so a claim that trusted it would write
a card under a name peers no longer resolve, while a page opening on a session the bus holds
as a teammate renames it to the seat. The record decides and the standing only fills in when
the roster cannot be read — a session joined through `/session join` never asked a board door,
and it is still on the team — and the record has to be this process's own: two panes opened on
one session id write one record each, and the other pane's watch is not this one's, so a door
here asks and arms its own. The ask repeats the watch the record names, so a rename keeps a
`join({listen: false})` and a wake the session had, and a failed join never undoes the card it
came after — a bus that is not loaded is a sentence, not an exception. The ask is recorded
here, and `TeamState`/`standingOf` hand the line its words — `teamPhrase` is those words, the one
clause both doors print for a state, so `listening` is one name rather than a board word and a
round word for the same watch; `teamStatus` prefers the live
record too, and prints no team once the bus no longer holds the session, because a name no
peer resolves is worse than no name at all.

### seat.ts

The seat a page is served as: `SEAT_ID_PREFIX` (`board:`) and `pageActor`, the actor a page
reads as. A page outlives the session that opened it, so it needs one name for its whole
life and one id derived from it, and the name is `team.lead` because the two questions have
one answer: the page belongs to the lead, and serving it is how a session becomes the lead.
The name arrives normalized by `config.ts`, so there is no second label rule here and no
default name — a constant would be a second answer to what the config already says. The page
writes nothing, so the id decides no ownership.

### signs.ts

What a sign is: who may write one, what it records, and which one still speaks. `Lead` (the
team name a signature carries, declared in `contract.ts` beside the words a sign says),
`normalizeLead` over [`../session-label.ts`](../session-label.ts), `isLead` (a case-insensitive
label compare, which is not `holds`), and the person at the keyboard — `PERSON_LABEL` (`you`),
`personActor` / `isPerson`, whose actor carries the id `person:you` — which is the actor
`/board approve` and `/board review` write, and the one actor a file can name that is not a
holder, so a repository worked by one session can still close a card.

`signOf` names the two signs, `approve` and `review`, from one list, and `signMark` / `signedAs`
are what a sign records and whose it is: the name *and* the person's mark, because a comparison on
the label alone would read a session signing under the lead's name back as the person's.

Which sign speaks is the question three readers must answer alike, so it is one rule here:
`laneReview` asks whether this execution had one at all, `signStale` whether the card has been
written since, and `currentReview` is both — the lead's queue, the card's reason line, and the
`done` gate each read it rather than deciding for themselves. `CURRENT_REVIEW_JS` is the same
four bodies as the page receives them, and one block because a caller that carries one carries all
four.

`HolderFact` binds a bus fact to the owner it was read for, and `appendNote` is the note cap's one
arithmetic for both writers.

### lead.ts

The gate ladder: why a call may move, sign, close or take a card back, and the sentence that says
why not. `mayMove` admits the holder, and the lead for the two doors it owns; `leadCannot`,
`heldBy`, `signRefusal` (not the lead), `holderRefusal` (a lead holding the card it means to sign)
and `missingSign` (the sign a lane requires) are the words, so the gates and the lane requirements
cannot drift into four versions of one rule. `askLead` is the table's one phrase for how a session
asks (`session send`), `signedText` is what a sign sends the owner, and `notToldLine` is what the
caller prints when that message did not go.

The refusals live here rather than in a module of their own because the ladder writes them:
`mayMove`, `reviewGate` and `reclaim` each build the sentence for the state they found, so a
sentences module would import the decisions it answers for.

## What a surface renders

### round.ts

The lead's rollup computed from the cards alone: `buildRound` with `RoundSummary` /
`RoundGroup` over owners, unassigned, unplanned (a contract still missing a line, or a plan
never recorded), unapproved, unreviewed (every card in `execute` until somebody has
spot-checked it, so the second gate is owed from the lane change rather than from a clock),
blocked, unwritten (`UNWRITTEN_MS`, half an hour), and done. It reads nothing but the cards,
so the board works with `session-bus` unloaded; a session that is merely idle is a bus fact
this rollup never reads.

The groups overlap on purpose: a card can be both `unplanned` and `unwritten`, and `unreviewed`
and `unwritten` say different things — one that the lead owes a look, the other that nobody has
written the card. Hiding it in one group would lose half the reason to look. `archivableOf` is
the finished pile `archive` is offered.

`gateOf(card)` is what those three queues are about: `contract`, `approval`, `review`, or
`undefined` for a card that owes no route gate — the list and the words it wears are `tone.ts`'s
`GATES` / `Gate` / `GATE_WORD`. Only the two lanes a card is worked in answer: a `plan` card owes
its contract (a missing line, or no plan file to execute against) and then its approval, and an
`execute` card owes the spot-check that speaks for the execution it is in now, which is
`currentReview`'s rule rather than "a sign exists". The transcript's rows and `board list`'s line
print that word; before it they read `planPath` alone and called a card with half a contract
planned while the rollup counted it unplanned.

### round-text.ts

That rollup as the lines a reader gets, because `board`'s tool returns them — the model's next
decision is taken from the counts and the ids — and `team`'s `/team` prints them, because a
lead in a terminal should not have to open a browser. `formatRound` folds the owners a bus has
no record of and that hold nothing into one line, given the roster, and counts the closes made
by instruction on the done count. `teamPhrase` is the clause both doors print for a team state, so `listening` is one name rather than a board word and a round word for the same watch. `plural` and the fold's own bodies (`isHistoryOwner`,
`historyLine`) are spliced into the page as `PLURAL_JS` / `HISTORY_OWNER_JS` / `HISTORY_LINE_JS`;
the page's filter rule and the card face's reason arrive the same way.

`LEAD_ROUND` is the round's one line rather than its contents: `/team`'s command description and
`team`'s lead guideline splice the same sentence, so the two surfaces that name the round cannot
name it two ways — they did, from #579 until the line moved here.

`ranClause` is the other sentence three surfaces print — the transcript's card, the person's
`/board review` line, and the page's dialog, which receives it as `RAN_CLAUSE_JS` — so a sign's
run is worded once: the command, the tree it was taken in (`the checkout`, or a worktree's path),
the exit, and the branch and commit there.

The same module carries what a session is holding — `holdingOf` (`#162 plan`, `#162 plan +2`,
or `idle`) and `holdingLine`, which is the label and its holding as one sentence, received by
the page as `HOLDING_OF_JS` — so `/team`'s presence line and the Team tab's teammate row say
what a named session is doing from one body.

The last thing it carries is the name itself. `withLiveOwner` / `liveLabelOf` label a card's
owner from the roster's record for its **id**, and hand the card back unchanged when no record
names it. A card records the label its write knew, and a rename moves the record rather than the
card — `/team join`, `/session join`, and a rename in Pi all do — so a label is a word a reader
must not take for an identity: `holds` compares ids first, and a sign is addressed by the id for
the same reason. Resolved once per read, before anything groups or joins by a label: the page's
snapshot, `board`'s listing, and `/team`'s round each map the cards they were handed, and a card
nobody owns or whose handoff never resolved a session is left alone. It writes nothing,
deliberately: a rename that rewrote every card a session holds would race whoever else is writing
and would never reach a finished one.

### skipped.ts

The sentence for the card files a board refused. A skipped file is not an absent one: a board
written by a newer build, or a record this build cannot trust, would otherwise read as "nobody
has planned anything" while the work sits on disk. `skippedText` prints it under a listing and
the page prints the same sentence on the footer's hover title, so the two name the same files.
`Skip` is the store's own record, already phrased for a reader.

### view.ts

The page's snapshot — `buildView` answering `BoardView` (lanes, each carrying its words,
colour, limit, and count, the total, the rollup, the signature, the repository's name and
root, and the store's path) — and the one shape a client is allowed to know. Each card arrives
as a `ViewCard` carrying the priority it acts on, the moment it entered its lane (`since`), and
`waits` when something unfinished blocks it, so the browser renders an answer instead of
re-deciding one. The owner arrives under the name the roster holds for its id ([`round-text.ts`](./round-text.ts)),
so a session that renamed after claiming a card is one row in the Agents column rather than a live
one beside a label nothing answers to. `sig` is what makes a push cheap: the page is re-sent only when a card's
revision moved, a teammate's state did, or the rollup's clock pushed a card into `unwritten` —
a membership time alone decides has to be in there, or the tab keeps a frame that is no longer
true. A client cannot invent a state the model surface would not report.

### page-pointer.ts

How a second session finds the page a repository already serves. A page is one loopback server
owned by one session's process, so the only thing discoverable is the note it leaves at
`PAGE_FILE` (`page.json`): the port, the seat, and the token the page reads by — nothing a
reader could misuse, since a page writes nothing. `PagePointer` is that note as a record and
`urlOf` the address it answers at; `PING_PATH` / `SNAPSHOT_PATH` / `BOARD_BASE`
are the routes the router serves and the probe asks for; `probePage` is the question "is it
still there", with the network as a seam so a test drives it.

Two rules make the file safe to trust. It is created exclusively by hard-linking a temp file
onto the name (`createPointer`), so two sessions starting at once cannot both believe they are
the page — the loser reads the winner's pointer and attaches. And it is believed only while it
answers: `settlePointer` runs the ladder — write, attach to a winner that answers, take over a
note proved dead — and `readPointer` / `clearPointer` (its own note only) leave an unreadable
note named rather than blaming a session.

### tone.ts

What colour a board surface wears, and which band a Team queue row is filed under, stated once,
because the page and the terminal both need it and two statements drift apart. `BoardTone` is the
page kit's own colour words plus `dim`, so a tone is the name of a CSS property and the page needs
no map; `BOARD_TONES`, `REASON_TONE` (every reason kind, `waiting` included because the card face
invents it), and `DECISION_KINDS` / `DECISION_TONE`, the Team queue's kinds in rank order with the
tone each wears in its pill, so a row's rank and the tone it says cannot disagree. `GATES` / `Gate` /
`GATE_WORD` are the three route gates a card can owe and the word each wears, aliases of
`DECISION_LABEL` rather than a second spelling of it: the rule that answers which gate is
`round.ts`'s `gateOf`. `DECISION_BAND`
files every kind under one of `DECISION_BANDS` — the two gates only the lead can sign, what nobody
holds, and what a card's own owner owes — with `DECISION_BAND_LABEL` naming the file, so a queue
that grouped backlog beside approvals cannot do it by accident. The rule behind the words: warn
is a person who must act next, danger is a refusal or a loss, and anything merely true of the card
is muted.

`DECISION_RANK_JS` / `DECISION_TONE_JS` / `DECISION_BAND_JS` / `REASON_TONE_JS` are those tables
as the browser bundle's own source, spliced in like every other rule the page shares. The
terminal's vocabulary is not here: `extensions/board/tone.ts` maps a tone to a `TuiRole`, because
only the transcript speaks it.

### reason.ts

Why a card sits where it does, as one rule for the card face, the lead's queue, and the
transcript. `REASON_KINDS` is every kind there is, and `reasonFor(card, ago)` answers a
`Reason` — a `ReasonKind` and one sentence — for
an unanswered offer, a blocked card's recorded reason, a contract's missing line, an approval
nobody gave, a spot-check nobody did, and a finished card's commit. The card face, the lead's
queue, and the transcript read this one body, because the states it names would otherwise be
three sentences that drift.

`ReasonCard` is the record plus the one fact only the server can add: `planGone`, which says the
plan the card recorded is no longer in the store. In `execute` it outranks the spot-check sentence,
because a card that cannot land is not a card to sign; in `plan` it comes after the approval, since
the next move is the one that would refuse. A plain card — the transcript's — is read as it was.

The offered sentence is the one reason that carries an age, so it answers `at` and `wording`
(a `{age}` template) beside its `text`: the page stamps those instead of writing the sentence,
and its one ticker keeps the line true without a frame. `text` stays the snapshot a transcript
line and a tooltip read.

`REASON_FOR_JS` is why it is self-contained: it reads the card and a formatter for relative
times and nothing else, and the clock is a parameter because the two callers read an age
against different nows — the page's against the reader's, the transcript's against the
snapshot's.

## What must not drift

- **One writer.** `store.ts` is the only code that writes a card file; a rule that seems to
  need a write belongs in an operation, and the store applies it with a re-read.
- **One action table.** `actions.ts` answers both "what may be called" and "what only reads",
  and `lib/policy.ts` reads it rather than keeping a list.
- **One lane table.** `lanes.ts` decides a lane's words, colour, ownership, and the moves out
  of it; the tool's enum, the page's snapshot, and `steps.ts` all read it.
- **One body per page rule.** Anything the browser bundle needs is a `*_JS` export here,
  spliced in by the extension's bundle — never a second copy written in JavaScript.
- **One set of sign words.** `contract.ts`'s `SIGN_WORDS` is what each refusal and each sign says, so the two
  gates and the lane requirements that ask for a signature cannot drift apart.
