Spec database OPAL command reference

The spec.* family is the only way anything reaches the spec database. No session opens the file; every access goes through a task, so it is mediated, permissioned and attributable.

Two companion families are documented here too: trove.dispatch, which turns a described work unit into a running session, and node.probe/fleet.describe, which say what a machine can do.

Reads never ask permission

spec.search, spec.get, spec.tree, spec.relations, spec.history, spec.blame, spec.dod.standards and spec.dod.check declare no permission scope, are idempotent, and never prompt.

That is deliberate and it is what makes the database useful: a session can read a spec before anything is committed. A model that had to ask consent to look something up would guess instead.

Writes are the opposite — one thing per call, always. There is no batch mutate, no glob, no "update all matching". Those are the surfaces where one careless call corrupts fifty rows, so they are not offered. Bulk reads are fine.

Keys, not paths

Every spec, section and work unit has a stable key — sqb4gsd1zn9 — issued by the database, never chosen by a caller. The human-readable path (CSCC.EFC.3) is a display address derived from position, so renumbering a section changes paths and changes nothing else. Always pass keys.

Reading

Deleted entities still resolve — that is what soft delete means. Ask the returned deleted flag rather than expecting a miss.

Authoring

Every work unit needs a Definition of Done. The field is NOT NULL from the first migration and authoring rejects an empty one: a unit whose done-ness cannot be checked is a unit that will be argued about later.

Definition of Done

The catalog is fixed: STD-UNIT, STD-COVERAGE-NEW, STD-E2E, STD-BUILD, STD-DOC, STD-VERIFY. A Definition of Done cites them by name — "meets STD-UNIT and STD-BUILD" — instead of re-describing testing every time.

A citation the catalog does not know is refused when you write it. A typo'd STD-COVERAGE would cite nothing at all, leaving a Definition of Done that reads rigorous and enforces nothing.

node= is not optional for STD-BUILD. A green build says nothing without the box it was green on — the same reason a green Linux build says nothing about Windows-only code. A pass recorded without one counts as unattributed, and blocks completion exactly as a failure would.

STD-VERIFY cannot be recorded at all. It is settled by a separate work unit of type Verify that names its subject in depends_on and finishes successfully. The implementer does not grade its own homework for the parts that need an opinion.

Status, claims and plans

donesuccess is the one status the database will not take on trust. If the unit's Definition of Done cites standards, they must all be satisfied first, and the refusal names the gap. Every other terminal status is a report rather than a claim: doneerror says it was not met, rejected says it will not be attempted, and neither needs evidence.

A claim is a lease, not a lock. If a session dies mid-unit the lease expires and the work becomes available again — a crashed session cannot make a unit permanently unclaimable.

spec.plan.regroup runs one round and reports what it re-opened. It does not loop: how many rounds are worth trying depends on the budget you have left, which only you know. Rejected is left alone unless you ask, because it is a decision rather than a failure.

Publishing

spec.publish key=<key> [root=<worktree>] [spec_path=<tree>] [node=<box>]

Renders a spec into a .md under the repository's spec tree so the code arrives with a description of what it was for. It publishes terminal work only, and says how many units it left out.

The file says in its own header that it is generated and that editing it changes nothing. It is a re-derivable snapshot; the database is the source.

This is the one spec.* task that takes a coarse resource scope. It touches the working tree rather than the database, and there "another publish is already running" is the right answer.

Running work

trove.dispatch lane=<n> key=<plan-or-unit> [model=<model>]

Selects the next runnable unit of a plan (or takes one named unit), claims it, writes its briefing into the lane's CLAUDE.md, and queues the session.

It claims before it queues, because a queued-but-unclaimed unit is one a second lane can take. A plan with nothing left says "no work left" rather than failing — those two call for opposite responses.

What a machine can do

Everything advertised is measured, not configured. An advertisement that can be optimistic routes work to a box that cannot run it, and the failure lands much later as a confusing error on somebody else's machine.

Calling these from the CLI

The --opal forms and their two silent traps are documented in the audio-recovery task reference and apply identically here:

hub --opal 'spec.put kind=spec code=gait title=Gait' -c
hub --opal '{"steps":[{"task":"spec.search","args":{"q":"gait"}}]}' -c

Remember that the short form splits on spaces, so any value containing one needs the plan form.