Record index
backlog_item.index.toml
The backlog, namespace BI, at
.working/toml/backlog_item.index.toml.
About
One record per unit of planned work. A backlog item moves open to
active to done or dropped (or straight from open to
dropped), and a ratified done creates a one-to-one completion receipt in the
done index.
Why
A backlog that lives in prose drifts: items vanish, "done" means different things, and
blocked work hides. Typed records give each item a permanent ID, a closed state set, and a
ratification step: an assistant or automation finishing an item lands
done/proposed, and only a maintainer transition removes the qualifier.
Blocked-ness is deliberately never a stored state; it is derived from active blocks at view
time, so it can never go stale in the record.
Description
The shared index shape: schema = 1 plus an array of [[record]]
rows. Each record carries the standard envelope: id, type,
status, title, created_at and updated_at
(RFC 3339 UTC, read from the clock), actor.kind (maintainer, assistant,
automation, or importer), optional summary, links (a closed
vocabulary: supersedes, resolves, remediates, receipt_of, corrects, follows, relates,
exemplifies, derives_from), refs (captured external sources: path, url, or doc),
and registered x-<vendor> extensions. Schemas are closed; an unknown key is
a validation failure.
How it works
States: open (initial), active (working), done and
dropped (terminal). No resurrection: a record in an unqualified terminal state
never re-enters a working state; a revived concern is a new record linking the old one. An
item is actionable when its state is open or active and no unqualified active block scopes
it; that block join is the actionability rule every scheduling view renders.
Generated view
Three composed views draw on this index joined against blocks: TODO.md,
BACKLOG.md, and PIPELINE.md, all byte-drift-gated. An optional
BACKLOG_ITEM-INDEX.md mirror renders the index one-to-one for human reading.
Value
A backlog whose completion claims are gated: "done" is a ratified transition with a durable receipt, not a feeling, which helps prevent silent scope loss and unratified completion from entering the record.
Usage
- Created by:
opf init(empty index); records by process as work is planned. - Updated by: state transitions under the status grammar; maintainer ratification of proposed terminals.
- Read by:
opf render(TODO, BACKLOG, PIPELINE, and the mirror);opf doctor(schema validity, ID uniqueness, transition legality, no-resurrection).