@clawboo/board-core declares the board’s rules once: which statuses a task can have, which moves between them are
legal, when the board fires a task again on its own, why a task is waiting for a person, and what its runs cost.
Every layer imports this one copy, so a newly legal move reaches the server, the team engine and the board view
together, and a mismatch is a compile error.
Use this page when you change a task rule. How the database enforces the rules is on
Board internals, and the board as users see it is on The board.
Who uses it
@clawboo/dbenforces the transition table insideupdateStatusand wraps the other rules for whole boards (attentionForTasks,runCostForTasks,isLedgerAutoFireable).@clawboo/team-orchestrationuses the fire policy and the person-assignment markers when it dispatches work.- The server attaches
attentionandrunCostto every task the board API returns. - The SPA builds the status editor from
legalTargets, routes tasks into the Needs you column, and shows run cost on cards.
apps/web/src/__tests__/browserBundlePurity.test.ts checks that the built files declare no bare import and that
state-machine.ts imports nothing; the package’s own tsconfig pins types: [], so a Node global fails the
type check.
Statuses and legal moves
TASK_STATUSES lists the seven statuses in lifecycle order. done and cancelled are terminal.
canTransition(from, to)answers one move; a move to the same status is a harmless no-op and returnstrue.legalTargets(from)returns the targets in table order as a fresh array, empty for a terminal status.isLocked(status)istrueforin_progressandin_review: a task someone is working on keeps its assignee.isTerminal(status)istruefordoneandcancelled.
updateStatus re-checks the table against the freshly read row, and an illegal move
through the board API returns 409. The orphan reaper (reconcileOrphans) writes rows directly but follows the
table: a stale in_progress task goes to todo, and a stale in_review task goes to blocked.
The board view shows Needs you and then five status columns (Backlog, To do, In progress,
Done, Cancelled). An in_review task sits in In progress under a Verifying badge, and every
blocked task appears in Needs you.
When a task fires again on its own
ledgerAllowsAutoFire(execs) reads a task’s run ledger, oldest run first, and decides whether the ready-pump may
start it again. The team engine’s pump and the server’s scan both call it, so they agree on what will run.
autoFireRefusal(execs, now) names why it refuses, including the no-progress brake (brakeUntil, over trailingNoProgressRuns and the verdict runMadeProgress leaves on each run). ledgerWillAutoFire asks whether the task will ever fire by itself: a braked one will. wakes.ts holds the rules for a saved wake: commentMayWake, the one function that decides which comment wakes anyone, and wakeDecision, what the pump does with a waiting wake.
trailingFailedRuns counts the runs at the end of the ledger that ended neither succeeded nor cancelled. A
task’s sourceDelegationId records who it is bound to: delegationTargetOf reads the agent out of it, and
encodeHumanAssignment writes the marker for a task a person assigned, which isHumanAssignment detects. A
person-assigned task reports its result on its card instead of to the team’s leader.
Why a task needs a person
taskAttention returns the reason a task waits on a person, or null when the board will move it on its own. The
board view puts every task with a reason in Needs you.
The result carries the reason, the number of trailing failed runs, and a
detail taken from the last run’s error
(trimmed to a short excerpt). When the provider refused the account on the last run, it also carries cause
(sign_in or billing) and runtime, the runtime whose sign-in to fix; the board shows Fix sign-in for it.
accountFailureOf(run) makes that call for one ledger run. It reads the run’s errorClass, which spells the
Auth and Billing classes of the error taxonomy in @clawboo/obs; this package imports nothing, so a test in
@clawboo/db holds the two spellings together.
Run cost
summarizeRunCost(runs, taskCostUsd) adds up what a task’s runs cost, for the card and the drawer:
- A run counts only when its
costUsdis a finite number, so a run stopped before it priced itself adds nothing. - The total is marked as an estimate unless every counted run’s
costSourceisreportedorlocal; a missing or unknown source counts as an estimate. - When every counted run is
local, the result also carrieslocal: true: the task ran only on a model the user’s own Ollama served, and the board shows its cost asfree. - With no counted run, a positive cost stored on the task row itself is returned as an estimate; otherwise the
cost is
null.
RUN_COST_SOURCES lists reported, local, token-estimate and char-estimate, most trustworthy first. local
is a run on a model the user’s own Ollama served, so its $0 is exact.
Priority
A task’spriority column is an integer, and the ready queue serves the higher one first. priority.ts reads and
writes it through four named levels, TASK_PRIORITIES: urgent (2), high (1), normal (0, every task’s default)
and low (-1), with TASK_PRIORITY_VALUE and TASK_PRIORITY_LABEL for each.
clampTaskPriority(n)is the value to store for any requested one: rounded, then held to -1 to 2; anything that is not a finite number is 0.@clawboo/dbapplies it to every create and update, so a large number cannot jump the queue.taskPriorityOf(n)is the level a stored value reads as. A value written before the clamp, outside the range, reads as the nearest level, and the ready queue orders it the same way.
Text from people and agents
A model reads everything Clawboo hands it as one pile, so text a teammate, a person or a sub-task wrote could read like Clawboo’s own instructions.untrustedText.ts frames such text as data, the same way everywhere:
formatInterSessionMessage({ from, kind, seq? }, body)writes one header,[Inter-session message · from=… · kind=… · isUser=false], then every line of the body quoted with|. A value in the header cannot close it early, and an inter-session header inside the body is neutralised (defangInterSessionHeaders), so the body can never present itself as a second header or as the person.formatPeerPostis this for a peer-room post. The team engine uses it for each result in a[Task Update], the Tasks server for each mailbox note riding a tool result, and the server for the comments and results in a task run’s ticket block.defangSectionMarkers(text, labels)turns a line shaped like one of a surface’s own section markers into plain text, for text a surface renders unquoted between its markers (the turn envelope).oneLine(text, max?)folds a title or a name onto one line, cut with…pastmax.
Test it
Runpnpm --filter @clawboo/board-core test, and pnpm --filter @clawboo/board-core typecheck, which checks the
source and the tests against separate tsconfigs. A rule change usually needs a matching case in the board tests of
@clawboo/db and in the cascade contract of @clawboo/team-orchestration.
Related
- Board internals: how the database enforces these rules, claims and reconciles.
- The board: statuses and columns as users see them.
- Track work on the board: working the board day to day.
- @clawboo/db: the repository that applies the rules.