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