Workflows and watchdogs

Documented against OpenRig 0.5.14. Help text uses "node" where these pages say seat, for a seat's position in the running rig.

What it is for

A workflow turns an intended sequence of work into durable state. You write a spec as a plain file, start an instance of it, and the daemon tracks where that instance is: which step is active and who owns it. When a step's owner closes it, the runtime records the closure and projects the next step's queue row in one transaction, so nobody has to carry the work between seats by hand. The owner decides when a step is done; the runtime is the scribe, not the gate.

A watchdog is the alarm you set for yourself, because a seat cannot wake itself. Jobs are persisted in the database and survive daemon restarts. A job can fire a periodic reminder, wait for a pool of artifacts, keep a workflow moving, gate on an idle queue, or watch a seat's context usage and act before the wall.

The three commands you will use first

Start an instance from a spec. --rig binds it to a rig so roles resolve to seats there.

rig workflow instantiate workflows/conveyor.workflow.md --root-objective "Ship the search page" --rig my-rig

Close your step and let the next one appear. One daemon transaction: close the current packet, project the next.

rig workflow project --instance <id> --current-packet <qitem-id> --exit handoff --result-note "candidate ready"

Ask what needs you. status answers "what needs me" with counts and one row per failed, stuck or waiting instance, plus the next action; list answers "what exists".

rig workflow status
rig workflow list

Arming a wake

rig watchdog register takes a policy: periodic-reminder, artifact-pool-ready, edge-artifact-required, workflow-keepalive, idle-gate-qitem, or context-usage-threshold. A parked queue row can attach a live watchdog id as its wake. list, show and status tell you whether a job fired and whether it is still live; quiet skips are not recorded, so an idle job and a job that never ran can look alike until you read show.

rig watchdog register --policy context-usage-threshold --target-session dev-impl@my-rig
rig watchdog list
rig watchdog status <jobId>

The workflow and watchdog families

Command	What it does (from help)	Help source
`rig watchdog`	Coordination Watchdog , daemon-native scheduler for reminders, artifact gates, workflow health, idle gates, and context usage	watchdog.txt
`rig watchdog list`	List watchdog jobs (default: active + compact + at most 100)	watchdog.list.txt
`rig watchdog register`	Register a watchdog; queue block --wake-watchdog attaches its job id. Context transcripts measured 113K–153K tokens/MB. The margin is the protection because prompt-bound consumers act only at turn boundaries	watchdog.register.txt
`rig watchdog show`	Show one watchdog job	watchdog.show.txt
`rig watchdog status`	Show one watchdog job + recent evaluation history	watchdog.status.txt
`rig watchdog stop`	Stop a watchdog job (operator-stopped; scheduler skips it)	watchdog.stop.txt
`rig workflow`	Daemon-native Workflow Runtime , declarative spec + transactional-scribe step projection (PL-004 Phase D)	workflow.txt
`rig workflow abort`	Transactionally cancel every live packet and abort the whole workflow instance	workflow.abort.txt
`rig workflow compile`	Compile project.yaml → mission.yaml → slice.yaml into an inspectable lifecycle graph (read-only)	workflow.compile.txt
`rig workflow continue`	Inspect an instance's current frontier + step trail (read-only; advancing happens via 'rig workflow project')	workflow.continue.txt
`rig workflow guidance`	Read current selected SDLC teaching, original intent and authored/bound provenance	workflow.guidance.txt
`rig workflow instantiate`	Create a workflow instance + entry-step qitem from a spec	workflow.instantiate.txt
`rig workflow instantiate-lifecycle`	Compile and instantiate an eligible lifecycle; recover a lost response with workflow operation <key>	workflow.instantiate-lifecycle.txt
`rig workflow list`	List workflow instances; optionally filter by status	workflow.list.txt
`rig workflow operation`	Recover a lifecycle creation or revision effect by its stable key, even after a lost response or source edit	workflow.operation.txt
`rig workflow project`	Close a current packet AND project the next-step packet (transactional-scribe; one daemon transaction)	workflow.project.txt
`rig workflow resume`	Redrive a FAILED instance from its failed step (completed steps never re-run; one fresh max_hops window)	workflow.resume.txt
`rig workflow revise`	Compare authored and running lifecycle graphs; deliberately adopt compatible changes without replaying work	workflow.revise.txt
`rig workflow route`	Re-route the current frontier step to a new owner (same step, honest handoff closure; never advances)	workflow.route.txt
`rig workflow run`	Instantiate a workflow AND follow it live to a terminal state (exit 0 completed / 3 failed)	workflow.run.txt
`rig workflow show`	Show current work, exception-owner readiness and existing exception obligations	workflow.show.txt
`rig workflow specs`	List registered workflow specs; built-in starters tagged with (built-in)	workflow.specs.txt
`rig workflow status`	Which instances need attention: counts + one row per failed/stuck/waiting instance with reason + next action (read-only)	workflow.status.txt
`rig workflow trace`	Show one workflow instance + its append-only step trail (audit-only verdict)	workflow.trace.txt
`rig workflow validate`	Validate a workflow spec file (returns structured ok/error report)	workflow.validate.txt
`rig workflow watch`	Attach to an in-flight instance and follow it live (read-only; exit mirrors the outcome)	workflow.watch.txt

What it does not do

rig workflow continue is read-only despite its name; project is the verb that advances.
The runtime does not judge whether a step was done well. Closure authority stays with the queue's closure rules; acceptance stays with the next stage.
compile and revise are for lifecycle graphs authored in project, mission and slice files; they inspect and adopt changes without replaying completed work. Editing the source file alone does not change a running instance.
A watchdog with a stale message is worse than none. When the thread it refers to closes, stop it or rewrite it.

Where it goes next

Coordination: the queue rows a workflow projects and the closure reasons it records.
The work tree: the project, mission and slice files a lifecycle graph is compiled from.

Read as Markdown