Status & handoffs
Start every session with carol status, end it with a handoff, and check the handoff with carol handoff check.
Carol v0.1.22
Two read-only commands bracket a working session. carol status tells you where the initiative stands when you sit down. carol handoff check makes sure the note you leave when you stop is one the next session can trust. Neither contacts your tracker and neither writes anything, so both are safe to run at any time, even while zurdo run or carol watch is going.
Start a session: carol status
carol status [initiative] [--format json]
With no argument, Carol uses the only initiative under docs/. If there are several, it lists them and asks you to name one (exit 2).
$ carol status billing Status — Billing (docs/billing/) Destination: Customers get itemised invoices and self-serve refunds.phase-01 Invoices done prd-01-invoices.md settled: 7 passed · 0 pending-review · 0 failed · 0 blocked phase-02 Refunds running prd-02-refunds.md in flight phase-03 Dunning researching — no run Row conflict: phase-03 researching-unblocked
Handoff: stale — committed 4e1a9c2, stopped_at 2026-10-05T18:40:00Z. Since the handoff: 9b03f7d Resolve tax-rules ticket run prd-02-refunds-3f1d (phase-02) at 2026-10-05T21:12:44Z Uncommitted: M docs/billing/scope.md
Read it top to bottom, and act on what it shows:
| You see | It means | Do this |
|---|---|---|
no run | The phase's PRD hasn't been run | Run it, or let the engine loop do it |
in flight | zurdo run is running it right now | Leave it. Check back later. |
settled with failures or blocked tasks | The run finished and some tasks didn't pass | Diagnose them, or rescope in a follow-up PRD |
settled with pending-review | A [manual] criterion waits on a person | Sign it off with zurdo review |
crashed | A run died and left its lock | Resume it with zurdo run |
Row conflict: … researching-unblocked | Every ticket blocking the phase is resolved | Consider setting the row to ready |
Row conflict: … ready-blocked | The row is ready, but a ticket still blocks it | Resolve the ticket, or set the row back |
Handoff: fresh | Nothing has moved since the last session stopped | Pick up the handoff's next action |
Handoff: stale | Commits or runs came after the handoff | Read it for open questions, but work out the next step again from the files |
Handoff: none | No handoff yet | Normal before a session first stops |
Uncommitted | Your working tree has changes | Commit or discard them before you hand off |
Carol reports a row conflict but never fixes it: the Status in scope.md is your call.
--format json prints the same map as one envelope, for scripts and agent skills. The bundled zurdo-wayfinder skill reads it to orient a new session. How the run state, the handoff verdict and the JSON fields are worked out is on the Internals page.
End a session: the handoff
When a session stops, it writes docs/<initiative>/handoff.md: where the initiative stands, what's in flight, what waits on a person, and exactly one next action. The bundled zurdo-handoff skill writes it for you. Its format is on Planning files.
Check it: carol handoff check
carol handoff check docs/billing/handoff.md [--format json]
handoff check validates the file's structure, not its content, and doesn't compare it with the tree (that's what status does). With no findings it prints <path>: ok and exits 0. Otherwise each finding goes to stderr as <line>: <rule>: <message>, and it exits 2.
| Rule | Checks |
|---|---|
frontmatter | Opens with --- front matter holding exactly initiative, stopped_at, station, phase and by, with no unknown or duplicate keys |
initiative | Matches the handoff's directory name |
stopped-at | UTC ISO-8601 to the second, for example 2026-10-05T18:40:00Z |
station | One of scope, research, phase-prd, publish, run-and-sync, phase-review |
phase | Appears in the sibling scope.md Phases table |
by | agent or user |
title | # Handoff: <initiative title> |
sections | The seven sections in order (Stopped at, Done this session, In flight, Waiting on a human, Next action, Uncommitted, Watch out), with no others |
empty-section | Every section has text. Write None. when there's nothing to say. |
next-action | Exactly one Row <n> — <action> line |
Run it as the last step before you commit a handoff. Then the next session can trust the file's shape, and carol status tells it whether the content still holds.
Next: Triage, scoring & usage