Documentation
¶
Overview ¶
Package statusblock computes the Now / Next / Later block the bare `abcd` board and the site's Status page render (itd-2609212103568351, spc-2609212138241908). The block is rendered status, never stored (adr-2609292012006845 decision 2): it is read from the lifecycle shelves, the readiness gate and the build's state file each time, so nothing on it can be edited into a lie.
- Now is every intent the build's state file shows in a lane, with its lane state, then the head marked "next up": the first READY intent in pick order that the build's record-only pre-start checks (intent.StartChecksIn) let start, that is in no lane, and that no peer holds when the caller hands in the build's peers check (ruling CC1 of 2026-09-29: the bare board pays that read, so its "next up" is the pick). Now is empty only when no READY intent passes them.
- Next is every planned intent the readiness gate reports READY and the state file shows in no lane, in pick order: `abcd build next`'s one order (intent.PickLess), each intent scored by the read the pick scores through (intent.ReadinessIn), the readiest first and the oldest among equals.
- Later is every planned intent the gate reports not READY, each with the gating checks it fails, then every draft, again leaving out an intent in a lane.
An intent the state file shows in a lane is listed under Now alone, never also under Next or Later (ruling BV2 of 2026-09-29). Next and Later are otherwise read from the record alone. The state file adds the lane rows to Now, and the head passes over an intent it shows in a lane, as the pick does over an intent with a run in progress; removing it empties Now's lane rows, returns each such intent to the list the gate places it in, and leaves a head (criterion 3).
A run started for an issue (`abcd build <iss-N>`, every drain lane) is looked up in the issue ledger rather than the intent corpus: its rows carry the issue's one-line summary marked as an issue (KindIssue). A lane leaves Now once its pull request has merged or its branch is gone, though the state file still shows it at its land stage until the loop's next step sees the merge (iss-2610090824041378); the head still passes over its intent, as the pick does over a run in progress.
The package reads the state file through a LaneReader, and the peers through a PeerReader, its caller supplies rather than importing the implement loop: the loop's own imports reach the site renderer, which renders this block, so each reader is handed in by the front door (the loop's StatusLanes and StatusPeers) and both surfaces call the one Read. The bare board hands in both; the site's Status page hands in no PeerReader, because another checkout's holdings are this machine's local state and never a published page's.
Core never writes to stdout; the front doors format the Block.
Index ¶
Constants ¶
const KindIssue = "issue"
KindIssue marks a Now row whose run was started for an issue rather than an intent (`abcd build <iss-N>`, every drain lane).
const OrderPick = "pick"
OrderPick names the order Next and the head are read in: the pick order of `abcd build next` (itd-2609211116005482), the readiest first by the pick's score and the oldest among equals.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Block ¶
type Block struct {
Now []Row `json:"now"`
Next []Row `json:"next"`
Later []Row `json:"later"`
// Order names the order Next and the head were read in.
Order string `json:"order"`
}
Block is the three lists. Each is non-nil, so --json carries [] rather than null for an empty one.
func Read ¶
func Read(repoRoot string, lanes LaneReader, peers PeerReader) (Block, error)
Read computes the block for the checkout at repoRoot. lanes may be nil, which reads as an absent state file; peers may be nil, which leaves the head unjudged against other checkouts. It writes nothing.
type HeldBy ¶
type HeldBy func(r intent.ReadyResult) string
HeldBy reports whether a peer holds the intent a readiness result judges, and why: the build's peers check, read once for the whole block. A non-empty reason is a holding.
type Lane ¶
type Lane struct {
// Run is the run the lane belongs to.
Run string `json:"run"`
// Lane is the lane's id inside the run (lane-1, …); empty while the run
// waits to open its next lane.
Lane string `json:"lane,omitempty"`
// Stage is the lane's next stage (worktree, brief, implement, validate,
// land), or "pending" while the run waits to open its next lane.
Stage string `json:"stage"`
// Awaiting is the agent roles the lane waits on, when it waits on any:
// one while its implementer works, one per validator out (ruling DR6).
Awaiting string `json:"awaiting,omitempty"`
// Waiting is what the lane waits for when it is no agent: its full check
// before its push, with the time the wait began (ruling DR6d-2).
Waiting string `json:"waiting,omitempty"`
// Branch is the lane's branch as the state file records it
// (build/<run>-<lane>), empty before the lane's worktree stage cuts it.
Branch string `json:"branch,omitempty"`
// InFlight is set when the lane's branch exists and its intent's spec is
// open: work is on a branch and the design it builds is still live
// (spc-2610031844142274, A5 and open question 3).
InFlight bool `json:"in_flight,omitempty"`
}
Lane is one lane's state as the build's state file records it.
type LaneReader ¶
LaneReader reads the build's state file for the checkout at repoRoot. An absent state file reads as no lanes, never as an error.
type PeerReader ¶
PeerReader reads the peers of the checkout at repoRoot once and returns the check the head is judged by. It is the build's own peers check (the loop's StatusPeers), so the head passes over exactly the intents the pick does.
type Row ¶
type Row struct {
ID string `json:"id"`
Title string `json:"title"`
Bucket string `json:"bucket"`
// Kind is KindIssue on the row of a run started for an issue, whose Bucket
// is then the ledger folder the issue sits in; empty on an intent's row.
Kind string `json:"kind,omitempty"`
// Target is the release a planned intent names as the one it must land by
// (`target_release`: `next` or vX.Y.Z, itd-2609212103572513 criterion 4),
// empty when it names none. A draft shows none: a target is a promise about
// planned work, and the cut reads it off planned intents alone.
Target string `json:"target_release,omitempty"`
// NextUp marks the pick order's head on Now.
NextUp bool `json:"next_up,omitempty"`
// SpecID is the spec the readiness gate judged for a planned intent, its
// own spec_id or the spec that names it; empty for a draft and for a
// planned intent with no spec (spc-2610031844142274, A5).
SpecID string `json:"spec_id,omitempty"`
// Lane is the lane state of a Now row the state file shows.
Lane *Lane `json:"lane,omitempty"`
// Failing names the gating readiness checks a Later planned row fails, in
// the gate's own order.
Failing []string `json:"failing_checks,omitempty"`
// Reserved names the reservation another copy holds on the record, as the
// checkout last fetched it, with the view's age (itd-2609091034175565).
// Read never sets it: the bare board adds it from disk alone, and the
// site's Status page, which shows no other checkout's holdings, never does.
Reserved string `json:"reserved,omitempty"`
}
Row is one intent on the block: its id and title, the shelf it sits on, the release it targets, and what places it where it is. A field another placement needs (a score) joins here, omitted when empty.
Source Files