state-protocol

State Protocol

One schema, one writer, one startup sequence — defined here and only here. Commands defer to this skill instead of re-spelling state mechanics; bin/orc-state is the single writer, so the registry and every checkpoint's frontmatter cannot drift apart.

The one-writer rule

Never hand-write .orc/orc.json or a checkpoint's frontmatter — every mutation goes through orc-state (atomic jq writes; registry entry + checkpoint mirror updated by the same verb). The checkpoint body below the frontmatter is yours to write freely, except the ## Resume digest section, which only orc-state digest write - touches (it enforces the cap), and ## Auto-checkpoint, which only the PreCompact hook writes (orc-state checkpoint --auto — phase, slices, HEAD, dirty files; mechanical, so trust it over a stale digest for git state).

Register a session (the 2-line pattern every multi-phase command uses):

orc-state init --command <cmd> --total-phases <N> [--jira KEY] [--scope workspace --repos a,b] [--plan-file P]

Register state via orc-state init; defer to orc-state-protocol for schema and rules.

Then per phase boundary: orc-state phase set <n|done> [--label <word>], and rewrite the digest (below). On completion: orc-state status set completed.

Registry schema (.orc/orc.json, schema 1)

{ "schema": 1, "sessions": [{
    "sessionId": "feat-142-notifs",        // sanitized branch — THE key; one live session per branch
    "command": "flow", "branch": "feat-142-notifs", "gitBranch": "feat/142-notifs",
    "description": "≤120 chars", "status": "in_progress",
    "phase": 5, "phaseLabel": "implement", "totalPhases": 9,
    "jiraTicket": null, "planFile": null,
    "linkedPRs": [{ "repo": "api", "number": 45, "url": "…", "stackId": null, "stackPosition": null, "stackedOn": null }],
    "startedAt": "2026-08-20T14:03:00Z", "updatedAt": "2026-08-20T18:11:00Z",
    "scope": "workspace", "repos": ["api", "ui"], "perRepoState": { "api": { "repoPath": "…", "branch": "…", "currentSlice": 0, "prUrl": null } }
}]}