mav-durability-on-gh

Durability on GitHub

Maverick runs on many machines concurrently. Any one of them can die without notice. The only way to make the workflow crash-safe is to treat GitHub as the source of truth and treat local files as a derivable cache.

Principle

Every piece of state that another Maverick instance might need to resume your work must be on GitHub before you move to the next step. If the only copy of a piece of state is in your local filesystem, losing it loses the run.

Markers — the durable state surface

Maverick persists workflow state to GitHub as fenced JSON code blocks inside issue comments. Each block is tagged with a kind-specific language marker so another instance can find and parse it reliably.

A marker looks like this inside a comment body:

```maverick-state
{
  "epic": 123,
  "stories": {"140": "merged", "142": "in_flight"},
  "updated_at": "2026-04-23T10:15:00Z"
}

The canonical read/write surface is `uv run maverick gh-state …` (backed by
`src/maverick/gh_state.py`). Skills should call the CLI; they should not
re-implement marker parsing.

## Cold-start hydration

At the top of every run, assume your local filesystem is stale or empty and
rebuild context from GitHub:

```dot
digraph hydrate {
    "Session starts" [shape=box];
    "Identify target issue / epic" [shape=box];
    "Read maverick-dag marker" [shape=box];
    "Read maverick-state marker" [shape=box];
    "Read claim / lease / block labels" [shape=box];
    "Read open PRs and CI status" [shape=box];
    "bprop marker present?" [shape=diamond];
    "Resume block-propagation" [shape=box];
    "Local cache hydrated" [shape=box];

    "Session starts" -> "Identify target issue / epic";
    "Identify target issue / epic" -> "Read maverick-dag marker";
    "Read maverick-dag marker" -> "Read maverick-state marker";
    "Read maverick-state marker" -> "Read claim / lease / block labels";
    "Read claim / lease / block labels" -> "Read open PRs and CI status";
    "Read open PRs and CI status" -> "bprop marker present?";
    "bprop marker present?" -> "Resume block-propagation" [label="yes"];
    "bprop marker present?" -> "Local cache hydrated" [label="no"];
    "Resume block-propagation" -> "Local cache hydrated";
}