From 2dc503380d3304455aad88d637cbf5d27a1a8840 Mon Sep 17 00:00:00 2001
From: Paul Gebheim <86010+pgebheim@users.noreply.github.com>
Date: Tue, 1 Sep 2026 22:25:50 +0000
Subject: [PATCH] feat(state): keep long-run skill state on disk so compaction
 stops losing it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A rig skill outlives its own transcript. `/rig-task` spans seven steps and
four delegated agents; `/rig-epic run` loops that over every child. Between
those steps the host agent's only memory is the conversation, so a compaction
mid-run drops the acceptance criteria, the failing assertion, and which review
findings are already fixed — and the agent re-derives them from git and gh, or
guesses.

`rig-epic` already worked around this with a hand-rolled `.rig/epics/*.json`
("replaces any external memory") — unvalidated, unschema'd, and used nowhere
else. This generalizes that one good idea into a primitive.

`scripts/rig-state.ts` keeps one small structured document per run under
`.rig/state/`, with an append-only journal beside it for humans debugging a
failed run. Updates are patches, merged and validated outside the model:
unknown keys, wrong types, undeclared phases, and impossible states are
rejected with the reason, leaving the state untouched for a retry. Size
budgets (500 chars per string, 50 items per array, 8 KB per document) are what
keep the state a state instead of a transcript by another name.

Guards make a document assert the gates the skills already describe in prose:
rig-task can't reach `pr-open` with a red suite or an open P1, rig-epic can't
reach `finish` with an unmerged child, rig-review can't call a round `clean`
while a finding is open.

rig-task, rig-epic, and rig-review now read and patch it; rig-epic's epic file
moves to `.rig/state/<integration-branch>.json`, so there's one mechanism
rather than two. rig-doctor checks `.rig/state/` is gitignored and reports
stale runs. Every state call is optional — with the script absent the skills
run as before.

This does not shorten the host agent's context; rig ships markdown procedures
and Claude Code and pi own their own loops. What changes is the cost of losing
the transcript.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MBaTgFSa8va6PTaFfuSRsz
---
 README.md                  |  11 +-
 docs/state.md              | 134 ++++++++
 scripts/rig-state.test.ts  | 297 +++++++++++++++++
 scripts/rig-state.ts       | 651 +++++++++++++++++++++++++++++++++++++
 skills/rig-doctor/SKILL.md |  11 +-
 skills/rig-epic/SKILL.md   | 129 +++++---
 skills/rig-plan/SKILL.md   |   4 +-
 skills/rig-review/SKILL.md |  32 +-
 skills/rig-task/SKILL.md   |  73 ++++-
 9 files changed, 1285 insertions(+), 57 deletions(-)
 create mode 100644 docs/state.md
 create mode 100644 scripts/rig-state.test.ts
 create mode 100644 scripts/rig-state.ts

diff --git a/README.md b/README.md
index 078d2f0..fb28188 100644
--- a/README.md
+++ b/README.md
@@ -14,7 +14,7 @@ read at runtime from a small **project profile** you fill in during onboarding.
 | **Agents** (`agents/`) | `rig-debugger`, `rig-reviewer`, `rig-architect`, `rig-qa`, `rig-coder` | Copied into `<project>/.claude/agents/` |
 | **pi adapter** (`pi/`) | Per-target persona frontmatter (`pi/agents/*.yml`, assembled onto the shared bodies) + the `/rig` dispatcher prompt | Copied into `<project>/.pi/{agents,prompts}/` — see [`docs/pi.md`](docs/pi.md) |
 | **Support docs** (`templates/`) | starter `REVIEWER.md` (+ `REVIEWER.scope-template.md`), `STYLE.md`, `label-mapping.md` | Copied into `<project>/.claude/` (only if absent) |
-| **Scripts** (`scripts/`) | `setup-worktree.sh`, `remove-worktree.sh`, `mint-gh-app-token.sh`, `scope-reviewer.ts`, `set-session-name.sh` (Claude-only) | Copied into `<project>/.claude/scripts/` |
+| **Scripts** (`scripts/`) | `setup-worktree.sh`, `remove-worktree.sh`, `mint-gh-app-token.sh`, `scope-reviewer.ts`, `rig-state.ts`, `set-session-name.sh` (Claude-only) | Copied into `<project>/.claude/scripts/` |
 | **CI templates** (`ci/`) | `security-scan`, `label-pr`, `image-build`, `slack-notify`, `test-gate`, `test-e2e`, and the **AI review-bot bundle** (`review-bot-gate`, `auto-review-fix`, `pr-review-labels`) | Copied into `<project>/.github/workflows/` (see `ci/README.md`) |
 | **Onboarding** (`skills/rig-onboard/`) | The agent-driven installer skill | Run once against a target project |
 
@@ -89,6 +89,15 @@ reference (the origin project's own values).
   colocated with the code, mirroring nested `AGENTS.md`). `rig-review` resolves
   the scoped files a diff touches and asserts them as P1s, so a subsystem's
   hard-won invariants stop getting re-discovered in PR review.
+- **Long runs keep state on disk, not in the transcript.** `/rig-task` spans
+  seven steps and four delegated agents. `/rig-epic run` loops that over every
+  child. When the transcript compacts mid-run, the acceptance criteria, the
+  failing assertion, and which review findings are already fixed go with it. So
+  every long skill keeps one small structured document per run under
+  `.rig/state/`, and `scripts/rig-state.ts` validates each update outside the
+  model. It rejects unknown keys, wrong types, and impossible states. A size
+  budget stops the document drifting back into a transcript. See
+  [`docs/state.md`](docs/state.md).
 - **Agent output is written for humans.** Agents produce a lot of prose — PR
   bodies, ticket descriptions, review findings, plans, hand-backs — and left
   alone they write it badly: buried conclusions, passive voice, hedge stacks,
diff --git a/docs/state.md b/docs/state.md
new file mode 100644
index 0000000..4b83016
--- /dev/null
+++ b/docs/state.md
@@ -0,0 +1,134 @@
+# Run state (`rig-state`)
+
+A rig skill is a long procedure. `/rig-task` spans seven steps and four
+delegated agents; `/rig-epic run` loops that over every child. The host agent's
+only memory of what happened between those steps is its transcript. When that
+transcript compacts mid-run, three things go with it: the acceptance criteria,
+which test went red and why, and which review findings are already fixed. The
+agent then re-derives them from `git` and `gh`, or guesses.
+
+`rig-state` replaces that memory with one small structured document per run,
+kept on disk and validated outside the model:
+
+```
+.rig/state/<run-id>.json     the current state — what the next step reads
+.rig/state/<run-id>.jsonl    an append-only journal of accepted patches
+```
+
+The state is the working memory. The journal is the audit trail, there so a
+human can debug a failed run. **Never feed the journal to a model.** That
+reintroduces the history the state replaces.
+
+Both are throwaway coordination state, rebuildable from the tracker and the
+repo, and **gitignored — never committed**. `/rig-doctor` checks that.
+
+## The contract
+
+Each step of a skill does three things, in this order:
+
+1. Read the state (`rig-state show <run-id>`) instead of scrolling back.
+2. Do the step's work.
+3. Persist what a *later* step needs, as a patch — not a summary of what
+   happened.
+
+That third rule is the one that matters. Record facts and decisions the next
+step reads: the branch name, the failing assertion, the reason you rejected an
+approach. Don't record narration. If a later step never reads it, it doesn't go
+in the state.
+
+## Commands
+
+`<SCRIPTS>` resolves from the repo root: `.claude/scripts/` first, then
+`.rig/scripts/`, first hit wins — the same rule `/rig-worktree` uses. Run these
+with `bun` (or your TypeScript runner).
+
+| Command | Does |
+|---|---|
+| `rig-state.ts init <skill> <run-id> [--json '{…}']` | Start a run at the skill's first phase. Fails if the run exists. |
+| `rig-state.ts patch <run-id> --json '{…}' [--step <label>]` | Merge a patch, validate the result, journal it. `--json -` reads stdin. |
+| `rig-state.ts show <run-id>` | Render the compact block you paste into a subagent prompt. |
+| `rig-state.ts get <run-id> [--field <dotted.path>]` | Raw JSON, or one field. |
+| `rig-state.ts list [--skill <name>]` | Active runs: id, skill, phase, updated, next action. |
+| `rig-state.ts journal <run-id>` | The accepted patches, for a human debugging a run. |
+| `rig-state.ts rm <run-id>` | Delete the run's state and journal. |
+
+Exit codes: `0` accepted, `1` rejected, `2` usage error or missing run.
+
+## Patch semantics
+
+Patches merge; they don't replace. So a step sends only what changed, and never
+has to reproduce the whole document:
+
+- Nested objects deep-merge. `{"tests":{"status":"green"}}` keeps
+  `tests.command`.
+- `null` deletes a key. `{"blockers":null}` clears the blockers.
+- Arrays replace wholesale. Treating an array as one atomic value keeps the
+  merge unambiguous: to add a finding, send the new list.
+- `runId`, `skill`, and `createdAt` are set at `init` and never patched.
+
+## Validation happens outside the model
+
+A rejected patch leaves the state exactly as it was. It prints the reason on
+stderr and the unchanged state on stdout, so the fix-and-retry loop needs no
+extra read. A patch is rejected when it carries:
+
+- **An unknown key**, at the top level or nested. The rejection lists the keys
+  the schema knows. This is what stops the state from drifting into a memory
+  blob.
+- **A wrong type**, or a value outside a field's enum.
+- **An undeclared phase** for that skill.
+- **An oversized value.** A string caps at 500 characters, an array at 50
+  items, and the whole document at 8 KB. Hitting a cap means summarize, not
+  raise the cap — the budget is what keeps the state a state.
+- **A guard violation** — a combination that can't be true (below).
+- **A move off a terminal phase** (`done`, `abandoned`) without `--force`. A
+  finished run doesn't quietly restart.
+
+## Phases and guards, per skill
+
+Guards encode the gates the skill already describes in prose. A state that
+claims to have passed a gate has to satisfy it.
+
+**`rig-task`** — `spec → spec-review → red → green → refactor → self-review →
+pr-open → review-loop → done` (plus `abandoned`).
+
+- `pr-open` and beyond require `tests.status: green`. Step 4 has to be GREEN
+  before a push.
+- `pr-open` and beyond require `review.p0: 0` and `review.p1: 0`. Step 4.5 is a
+  gate, not a suggestion.
+- `done` requires a `pr.number`.
+
+**`rig-epic`** — `plan → start → run → review → finish → done`.
+
+- `finish` requires every child at `merged`.
+- `review` requires at least one merged child.
+- A child at `merged` has to record its `branch`.
+
+**`rig-review`** — `find → fix → done`.
+
+- Outcome `clean` requires no finding still `open`.
+- `round` must not exceed `maxRounds`; past that, a human takes it.
+
+## Run IDs
+
+Use the unit's identity, lowercased: the ticket (`abc-18`), the integration
+branch for an epic (`abc-42-agent-as-definition`), or `pr-<number>` for a review
+loop. A run id has to match `[A-Za-z0-9][A-Za-z0-9._-]{0,79}` — it becomes a
+filename.
+
+Reuse the id across a `start`/`finish` split. That reuse is the point: `finish`
+resolves the same run and reads what `start` recorded instead of reconstructing
+it.
+
+## What this does not do
+
+- **It doesn't shorten the host agent's context.** rig ships markdown
+  procedures; Claude Code and pi own their own loops and still send their
+  transcripts. What the state changes is the *cost of losing* that transcript.
+- **It can't recover a fact nobody recorded.** If a step needs an observation
+  no patch persisted, the state won't have it. Re-derive it from the repo or the
+  tracker; the journal is how a human diagnoses the omission afterward.
+- **It isn't the source of truth for work that lives elsewhere.** The tracker
+  owns ticket status; git owns the branches; the PR owns the review. The state
+  records rig's position in the procedure, and caches only what re-fetching
+  would cost a step.
diff --git a/scripts/rig-state.test.ts b/scripts/rig-state.test.ts
new file mode 100644
index 0000000..7b85a33
--- /dev/null
+++ b/scripts/rig-state.test.ts
@@ -0,0 +1,297 @@
+import { describe, expect, it } from "bun:test";
+import {
+  applyPatch,
+  LIMITS,
+  mergePatch,
+  phaseAtOrPast,
+  renderCompact,
+  SCHEMAS,
+  validateState,
+  validRunId,
+  type State,
+} from "./rig-state.ts";
+
+const TASK = SCHEMAS["rig-task"]!;
+const EPIC = SCHEMAS["rig-epic"]!;
+const REVIEW = SCHEMAS["rig-review"]!;
+const NOW = "2026-09-01T00:00:00.000Z";
+
+function task(extra: State = {}): State {
+  return mergePatch(
+    { runId: "abc-18", skill: "rig-task", phase: "spec", createdAt: NOW, updatedAt: NOW },
+    extra,
+  );
+}
+
+function epic(extra: State = {}): State {
+  return mergePatch(
+    { runId: "abc-42", skill: "rig-epic", phase: "start", createdAt: NOW, updatedAt: NOW },
+    extra,
+  );
+}
+
+function reasons(result: ReturnType<typeof validateState>): string[] {
+  return result.ok ? [] : result.reasons;
+}
+
+describe("mergePatch", () => {
+  it("deep-merges nested objects instead of replacing them", () => {
+    const merged = mergePatch({ tests: { command: "bun test", status: "red" } }, { tests: { status: "green" } });
+    expect(merged).toEqual({ tests: { command: "bun test", status: "green" } });
+  });
+
+  it("deletes a key when the patch sets it to null", () => {
+    expect(mergePatch({ a: 1, b: 2 }, { b: null })).toEqual({ a: 1 });
+  });
+
+  it("deletes a nested key without disturbing its siblings", () => {
+    expect(mergePatch({ pr: { number: 4, url: "u" } }, { pr: { url: null } })).toEqual({ pr: { number: 4 } });
+  });
+
+  it("replaces arrays wholesale rather than appending", () => {
+    expect(mergePatch({ blockers: ["a", "b"] }, { blockers: ["c"] })).toEqual({ blockers: ["c"] });
+  });
+
+  it("leaves the base object untouched", () => {
+    const base = { a: 1 };
+    mergePatch(base, { a: 2 });
+    expect(base).toEqual({ a: 1 });
+  });
+});
+
+describe("validateState — shape", () => {
+  it("accepts a well-formed task state", () => {
+    expect(validateState(TASK, task({ base: "origin/main" })).ok).toBe(true);
+  });
+
+  it("rejects an unknown top-level key and lists the known ones", () => {
+    const out = reasons(validateState(TASK, task({ scratchpad: "notes" })));
+    expect(out.join()).toContain("scratchpad: unknown key");
+    expect(out.join()).toContain("worktree");
+  });
+
+  it("rejects an unknown nested key", () => {
+    expect(reasons(validateState(TASK, task({ tests: { flakes: 2 } }))).join()).toContain("tests.flakes: unknown key");
+  });
+
+  it("rejects a wrong type", () => {
+    expect(reasons(validateState(TASK, task({ branch: 7 }))).join()).toContain("branch: expected a string");
+  });
+
+  it("rejects a value outside a field's enum", () => {
+    expect(reasons(validateState(TASK, task({ tests: { status: "mostly" } }))).join()).toContain(
+      "not one of not-run | red | green | error",
+    );
+  });
+
+  it("rejects an undeclared phase and names the declared ones", () => {
+    expect(reasons(validateState(TASK, task({ phase: "vibing" }))).join()).toContain("is not a rig-task phase");
+  });
+
+  it("rejects a string array holding non-strings", () => {
+    expect(reasons(validateState(TASK, task({ blockers: ["ok", 3] }))).join()).toContain("an array of strings");
+  });
+
+  it("checks every element of an object array", () => {
+    const out = reasons(validateState(EPIC, epic({ children: [{ id: "a", status: "todo" }, { id: "b", status: "nope" }] })));
+    expect(out.join()).toContain("children[1].status");
+  });
+});
+
+describe("validateState — budgets", () => {
+  it("rejects a string longer than the per-string limit", () => {
+    const out = reasons(validateState(TASK, task({ nextAction: "x".repeat(LIMITS.stringChars + 1) })));
+    expect(out.join()).toContain("summarize it");
+  });
+
+  it("rejects an array past the item limit", () => {
+    const out = reasons(validateState(TASK, task({ decisions: Array.from({ length: LIMITS.arrayItems + 1 }, () => "d") })));
+    expect(out.join()).toContain("item limit");
+  });
+
+  it("rejects a state past the byte budget", () => {
+    const filler = Array.from({ length: 40 }, () => "y".repeat(400));
+    const out = reasons(validateState(TASK, task({ decisions: filler, blockers: filler })));
+    expect(out.join()).toContain("byte budget");
+  });
+});
+
+describe("guards — rig-task", () => {
+  const green = { tests: { status: "green" }, review: { p0: 0, p1: 0 }, pr: { number: 9 } };
+
+  it("blocks pr-open while the suite is red", () => {
+    expect(reasons(validateState(TASK, task({ phase: "pr-open", tests: { status: "red" } }))).join()).toContain(
+      "tests.status = green",
+    );
+  });
+
+  it("blocks pr-open with an unresolved P1", () => {
+    const out = reasons(validateState(TASK, task({ phase: "pr-open", tests: { status: "green" }, review: { p0: 0, p1: 1 } })));
+    expect(out.join()).toContain("Step 4.5 is a gate");
+  });
+
+  it("allows pr-open once the suite is green and the self-review is clean", () => {
+    expect(validateState(TASK, task({ phase: "pr-open", ...green })).ok).toBe(true);
+  });
+
+  it("blocks done without a PR number", () => {
+    const out = reasons(validateState(TASK, task({ phase: "done", tests: { status: "green" }, review: { p0: 0, p1: 0 } })));
+    expect(out.join()).toContain("a finished task has a PR");
+  });
+
+  it("does not re-assert a passed gate on an abandoned run", () => {
+    expect(validateState(TASK, task({ phase: "abandoned", tests: { status: "red" } })).ok).toBe(true);
+  });
+
+  it("still applies the gate to a phase past pr-open", () => {
+    const out = reasons(validateState(TASK, task({ phase: "review-loop", tests: { status: "red" } })));
+    expect(out.join()).toContain("tests.status = green");
+  });
+});
+
+describe("guards — rig-epic", () => {
+  it("blocks finish while a child is unmerged", () => {
+    const state = epic({
+      phase: "finish",
+      children: [
+        { id: "1", status: "merged", branch: "b1" },
+        { id: "2", status: "todo" },
+      ],
+    });
+    expect(reasons(validateState(EPIC, state)).join()).toContain("every child at status 'merged'");
+  });
+
+  it("blocks review before any child has merged", () => {
+    const state = epic({ phase: "review", children: [{ id: "1", status: "in-progress" }] });
+    expect(reasons(validateState(EPIC, state)).join()).toContain("at least one merged child");
+  });
+
+  it("requires a merged child to record its branch", () => {
+    const state = epic({ phase: "run", children: [{ id: "1", status: "merged" }] });
+    expect(reasons(validateState(EPIC, state)).join()).toContain("must record its branch");
+  });
+
+  it("accepts a finish with every child merged and branched", () => {
+    const state = epic({ phase: "finish", children: [{ id: "1", status: "merged", branch: "b1" }] });
+    expect(validateState(EPIC, state).ok).toBe(true);
+  });
+});
+
+describe("guards — rig-review", () => {
+  const base = { runId: "pr-418", skill: "rig-review", phase: "fix", createdAt: NOW, updatedAt: NOW };
+
+  it("blocks a clean outcome while a finding is open", () => {
+    const state = mergePatch(base, { outcome: "clean", findings: [{ id: "f1", severity: "P1", status: "open" }] });
+    expect(reasons(validateState(REVIEW, state)).join()).toContain("still at status 'open'");
+  });
+
+  it("accepts a clean outcome once every finding is fixed or deferred", () => {
+    const state = mergePatch(base, {
+      outcome: "clean",
+      findings: [
+        { id: "f1", severity: "P1", status: "fixed" },
+        { id: "f2", severity: "P2", status: "deferred" },
+      ],
+    });
+    expect(validateState(REVIEW, state).ok).toBe(true);
+  });
+
+  it("blocks a round past maxRounds", () => {
+    expect(reasons(validateState(REVIEW, mergePatch(base, { round: 6, maxRounds: 5 }))).join()).toContain(
+      "hand back to a human",
+    );
+  });
+});
+
+describe("applyPatch", () => {
+  it("stamps updatedAt on an accepted patch", () => {
+    const result = applyPatch(TASK, task(), { phase: "red" }, { now: "2026-09-02T00:00:00.000Z" });
+    expect(result.ok && result.state.updatedAt).toBe("2026-09-02T00:00:00.000Z");
+  });
+
+  it("leaves the current state untouched when it rejects", () => {
+    const current = task({ tests: { status: "red" } });
+    const result = applyPatch(TASK, current, { phase: "pr-open" }, { now: NOW });
+    expect(result.ok).toBe(false);
+    expect(current.phase).toBe("spec");
+  });
+
+  it("refuses to patch the identity fields", () => {
+    expect(reasons(applyPatch(TASK, task(), { runId: "other" }, { now: NOW })).join()).toContain("never patched");
+  });
+
+  it("refuses to move a run off a terminal phase", () => {
+    const done = task({ phase: "done", tests: { status: "green" }, review: { p0: 0, p1: 0 }, pr: { number: 9 } });
+    expect(reasons(applyPatch(TASK, done, { phase: "red" }, { now: NOW })).join()).toContain("terminal phase");
+  });
+
+  it("allows the terminal move under --force", () => {
+    const done = task({ phase: "done", tests: { status: "green" }, review: { p0: 0, p1: 0 }, pr: { number: 9 } });
+    expect(applyPatch(TASK, done, { phase: "review-loop" }, { force: true, now: NOW }).ok).toBe(true);
+  });
+
+  it("rejects a non-object patch", () => {
+    expect(applyPatch(TASK, task(), [] as unknown as State, { now: NOW }).ok).toBe(false);
+  });
+});
+
+describe("phaseAtOrPast", () => {
+  it("is true at the target phase", () => {
+    expect(phaseAtOrPast(TASK, task({ phase: "pr-open" }), "pr-open")).toBe(true);
+  });
+
+  it("is false before it", () => {
+    expect(phaseAtOrPast(TASK, task({ phase: "green" }), "pr-open")).toBe(false);
+  });
+
+  it("is false for an abandoned run", () => {
+    expect(phaseAtOrPast(TASK, task({ phase: "abandoned" }), "pr-open")).toBe(false);
+  });
+});
+
+describe("renderCompact", () => {
+  const rendered = renderCompact(
+    task({
+      phase: "green",
+      spec: { id: "ABC-18", title: "Add rate limiting" },
+      tests: { status: "green", pass: 412 },
+      blockers: [],
+      decisions: ["Reuse TokenBucket rather than add a dependency"],
+    }),
+  );
+
+  it("leads with the skill, run, and phase", () => {
+    expect(rendered.split("\n")[0]).toBe("# rig-task state · abc-18 · phase: green");
+  });
+
+  it("flattens nested objects to dotted keys", () => {
+    expect(rendered).toContain("tests.status: green");
+    expect(rendered).toContain("spec.id: ABC-18");
+  });
+
+  it("marks an empty list rather than dropping it", () => {
+    expect(rendered).toContain("blockers: (none)");
+  });
+
+  it("lists array items one per line", () => {
+    expect(rendered).toContain("  - Reuse TokenBucket rather than add a dependency");
+  });
+});
+
+describe("validRunId", () => {
+  it("accepts a ticket-shaped id", () => {
+    expect(validRunId("abc-18")).toBe(true);
+  });
+
+  it("rejects a path traversal", () => {
+    expect(validRunId("../escape")).toBe(false);
+  });
+
+  it("rejects a separator", () => {
+    expect(validRunId("a/b")).toBe(false);
+  });
+
+  it("rejects an over-long id", () => {
+    expect(validRunId("a".repeat(81))).toBe(false);
+  });
+});
diff --git a/scripts/rig-state.ts b/scripts/rig-state.ts
new file mode 100644
index 0000000..b541797
--- /dev/null
+++ b/scripts/rig-state.ts
@@ -0,0 +1,651 @@
+#!/usr/bin/env bun
+/**
+ * rig-state.ts — durable, validated run state for long-horizon rig skills.
+ * Part of Rig (used by rig-task, rig-epic, and rig-review).
+ *
+ * The problem: a rig skill is a long procedure — `/rig-task` spans seven steps
+ * and four delegated agents; `/rig-epic run` loops that over every child. The
+ * host agent's only memory of what happened is its transcript, so a compaction
+ * mid-run drops the acceptance criteria, which tests went red and why, and
+ * which review findings are already fixed. The agent then re-derives that from
+ * `git` and `gh`, or guesses.
+ *
+ * The fix: keep one small structured document per run, on disk, and treat it —
+ * not the transcript — as what the next step reads. The skill patches it after
+ * each step; this script validates and merges the patch OUTSIDE the model, so a
+ * malformed or oversized update is rejected rather than silently persisted.
+ * `rig-epic` already did this by hand for epics; this generalizes it.
+ *
+ * Files, under `.rig/state/` (gitignored — throwaway coordination state):
+ *   <runId>.json    the current state; what `show` renders into a prompt
+ *   <runId>.jsonl   append-only journal of accepted patches, for humans
+ *
+ * The journal exists so a failed run is debuggable. Never feed it to a model —
+ * that reintroduces the history this replaces.
+ *
+ * Usage:
+ *   rig-state.ts init <skill> <runId> [--json '{...}']
+ *   rig-state.ts patch <runId> [--json '{...}'|-] [--step <label>] [--force]
+ *   rig-state.ts get <runId> [--field <dotted.path>]
+ *   rig-state.ts show <runId>
+ *   rig-state.ts list [--skill <name>]
+ *   rig-state.ts journal <runId>
+ *   rig-state.ts rm <runId>
+ *
+ * Exit codes: 0 accepted · 1 rejected (reason on stderr, state unchanged) ·
+ * 2 usage or missing run. A rejection is recoverable: fix the patch, retry.
+ */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path/posix";
+
+// ---------------------------------------------------------------- schema ----
+
+export type FieldSpec = {
+  type: "string" | "number" | "boolean" | "string[]" | "object" | "object[]";
+  enum?: string[];
+  of?: Record<string, FieldSpec>;
+};
+
+export type Guard = {
+  /** What this guard protects, in the message a rejected patch gets back. */
+  reason: string;
+  /** Return true when the state VIOLATES the guard. */
+  violated: (state: State) => boolean;
+};
+
+export type SkillSchema = {
+  skill: string;
+  phases: string[];
+  terminal: string[];
+  fields: Record<string, FieldSpec>;
+  guards: Guard[];
+};
+
+export type State = Record<string, unknown>;
+
+/** Budgets. They aren't arbitrary: they're what keeps state from becoming a
+ * transcript by another name. A rejected patch tells the model to summarize. */
+export const LIMITS = { bytes: 8_192, stringChars: 500, arrayItems: 50 } as const;
+
+/** Fields every skill carries. `createdAt`/`updatedAt` are tool-managed. */
+const CORE_FIELDS: Record<string, FieldSpec> = {
+  runId: { type: "string" },
+  skill: { type: "string" },
+  phase: { type: "string" },
+  createdAt: { type: "string" },
+  updatedAt: { type: "string" },
+  nextAction: { type: "string" },
+  blockers: { type: "string[]" },
+  decisions: { type: "string[]" },
+};
+
+const TASK_SCHEMA: SkillSchema = {
+  skill: "rig-task",
+  phases: [
+    "spec", "spec-review", "red", "green", "refactor",
+    "self-review", "pr-open", "review-loop", "done", "abandoned",
+  ],
+  terminal: ["done", "abandoned"],
+  fields: {
+    ...CORE_FIELDS,
+    spec: {
+      type: "object",
+      of: {
+        id: { type: "string" },
+        title: { type: "string" },
+        source: { type: "string", enum: ["linear", "github", "adhoc"] },
+        acceptanceCriteria: { type: "string[]" },
+      },
+    },
+    worktree: { type: "string" },
+    branch: { type: "string" },
+    base: { type: "string" },
+    pr: {
+      type: "object",
+      of: {
+        number: { type: "number" },
+        url: { type: "string" },
+        state: { type: "string", enum: ["open", "merged", "closed"] },
+      },
+    },
+    tests: {
+      type: "object",
+      of: {
+        command: { type: "string" },
+        status: { type: "string", enum: ["not-run", "red", "green", "error"] },
+        pass: { type: "number" },
+        fail: { type: "number" },
+        failures: { type: "string[]" },
+      },
+    },
+    review: {
+      type: "object",
+      of: {
+        source: { type: "string", enum: ["local", "bot"] },
+        round: { type: "number" },
+        p0: { type: "number" },
+        p1: { type: "number" },
+        p2: { type: "number" },
+        open: { type: "string[]" },
+        outcome: {
+          type: "string",
+          enum: ["pending", "clean", "actionable", "timeout", "unresolved"],
+        },
+      },
+    },
+  },
+  guards: [
+    {
+      reason: "phase 'pr-open' requires tests.status = green (Step 4 must be GREEN before push)",
+      violated: (s) => phaseAtOrPast(TASK_SCHEMA, s, "pr-open") && dig(s, "tests.status") !== "green",
+    },
+    {
+      reason: "phase 'pr-open' requires review.p0 = 0 and review.p1 = 0 (Step 4.5 is a gate)",
+      violated: (s) =>
+        phaseAtOrPast(TASK_SCHEMA, s, "pr-open") &&
+        (num(dig(s, "review.p0")) > 0 || num(dig(s, "review.p1")) > 0),
+    },
+    {
+      reason: "phase 'done' requires pr.number (a finished task has a PR)",
+      violated: (s) => s.phase === "done" && typeof dig(s, "pr.number") !== "number",
+    },
+  ],
+};
+
+const EPIC_SCHEMA: SkillSchema = {
+  skill: "rig-epic",
+  phases: ["plan", "start", "run", "review", "finish", "done", "abandoned"],
+  terminal: ["done", "abandoned"],
+  fields: {
+    ...CORE_FIELDS,
+    parent: {
+      type: "object",
+      of: {
+        id: { type: "string" },
+        title: { type: "string" },
+        source: { type: "string", enum: ["linear", "github", "none"] },
+      },
+    },
+    integrationBranch: { type: "string" },
+    whyEpic: { type: "string" },
+    children: {
+      type: "object[]",
+      of: {
+        id: { type: "string" },
+        title: { type: "string" },
+        blockedBy: { type: "string[]" },
+        branch: { type: "string" },
+        pr: { type: "number" },
+        status: { type: "string", enum: ["todo", "in-progress", "blocked", "merged"] },
+      },
+    },
+    specReview: {
+      type: "object",
+      of: {
+        frontLoaded: { type: "boolean" },
+        outcome: { type: "string", enum: ["pending", "cleared", "halted"] },
+        blockers: { type: "string[]" },
+      },
+    },
+    combinedReview: {
+      type: "object",
+      of: {
+        outcome: { type: "string", enum: ["pending", "clean", "applied", "paused"] },
+        p0: { type: "number" },
+        p1: { type: "number" },
+        p2: { type: "number" },
+      },
+    },
+  },
+  guards: [
+    {
+      reason: "phase 'finish' requires every child at status 'merged'",
+      violated: (s) =>
+        phaseAtOrPast(EPIC_SCHEMA, s, "finish") &&
+        childList(s).some((c) => c.status !== "merged"),
+    },
+    {
+      reason: "phase 'review' requires at least one merged child (nothing to review yet)",
+      violated: (s) =>
+        s.phase === "review" && !childList(s).some((c) => c.status === "merged"),
+    },
+    {
+      reason: "a child at status 'merged' must record its branch",
+      violated: (s) => childList(s).some((c) => c.status === "merged" && !c.branch),
+    },
+  ],
+};
+
+const REVIEW_SCHEMA: SkillSchema = {
+  skill: "rig-review",
+  phases: ["find", "fix", "done", "abandoned"],
+  terminal: ["done", "abandoned"],
+  fields: {
+    ...CORE_FIELDS,
+    base: { type: "string" },
+    worktree: { type: "string" },
+    source: { type: "string", enum: ["local", "bot"] },
+    pr: { type: "number" },
+    round: { type: "number" },
+    maxRounds: { type: "number" },
+    outcome: {
+      type: "string",
+      enum: ["pending", "clean", "actionable", "timeout", "unresolved"],
+    },
+    findings: {
+      type: "object[]",
+      of: {
+        id: { type: "string" },
+        severity: { type: "string", enum: ["P0", "P1", "P2", "P3"] },
+        file: { type: "string" },
+        line: { type: "number" },
+        summary: { type: "string" },
+        status: { type: "string", enum: ["open", "fixed", "deferred", "rejected"] },
+      },
+    },
+  },
+  guards: [
+    {
+      reason: "outcome 'clean' requires no finding still at status 'open'",
+      violated: (s) =>
+        s.outcome === "clean" && findingList(s).some((f) => f.status === "open"),
+    },
+    {
+      reason: "round must not exceed maxRounds (hand back to a human instead)",
+      violated: (s) =>
+        typeof s.maxRounds === "number" && num(s.round) > (s.maxRounds as number),
+    },
+  ],
+};
+
+export const SCHEMAS: Record<string, SkillSchema> = {
+  "rig-task": TASK_SCHEMA,
+  "rig-epic": EPIC_SCHEMA,
+  "rig-review": REVIEW_SCHEMA,
+};
+
+// ------------------------------------------------------------- utilities ----
+
+function dig(state: State, path: string): unknown {
+  return path.split(".").reduce<unknown>(
+    (acc, key) => (isPlainObject(acc) ? (acc as State)[key] : undefined),
+    state,
+  );
+}
+
+function num(value: unknown): number {
+  return typeof value === "number" ? value : 0;
+}
+
+function isPlainObject(value: unknown): boolean {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function childList(state: State): Array<Record<string, unknown>> {
+  return Array.isArray(state.children) ? (state.children as Array<Record<string, unknown>>) : [];
+}
+
+function findingList(state: State): Array<Record<string, unknown>> {
+  return Array.isArray(state.findings) ? (state.findings as Array<Record<string, unknown>>) : [];
+}
+
+/** True when the state's phase is at or past `target` in the declared order. */
+export function phaseAtOrPast(schema: SkillSchema, state: State, target: string): boolean {
+  const here = schema.phases.indexOf(String(state.phase));
+  const there = schema.phases.indexOf(target);
+  if (here < 0 || there < 0) return false;
+  // Terminal phases sit past every gate but shouldn't re-assert a gate they
+  // already passed through — `abandoned` is a stop, not a completed run.
+  if (state.phase === "abandoned") return false;
+  return here >= there;
+}
+
+// ----------------------------------------------------------------- merge ----
+
+/**
+ * Deep-merge `patch` into `base`. A `null` value deletes its key. Arrays
+ * replace wholesale — treating them as atomic values keeps merge unambiguous,
+ * so "add one finding" means "send the new list", not "append and hope".
+ */
+export function mergePatch(base: State, patch: State): State {
+  const out: State = { ...base };
+  for (const [key, value] of Object.entries(patch)) {
+    if (value === null) {
+      delete out[key];
+    } else if (isPlainObject(value) && isPlainObject(out[key])) {
+      out[key] = mergePatch(out[key] as State, value as State);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+// ------------------------------------------------------------ validation ----
+
+export type Rejection = { ok: false; reasons: string[] };
+export type Acceptance = { ok: true; state: State };
+
+function checkValue(path: string, spec: FieldSpec, value: unknown, reasons: string[]): void {
+  const fail = (want: string) => reasons.push(`${path}: expected ${want}, got ${JSON.stringify(value)}`);
+  switch (spec.type) {
+    case "string":
+      if (typeof value !== "string") return fail("a string");
+      if (value.length > LIMITS.stringChars)
+        reasons.push(`${path}: ${value.length} chars exceeds the ${LIMITS.stringChars}-char limit — summarize it`);
+      if (spec.enum && !spec.enum.includes(value))
+        reasons.push(`${path}: "${value}" is not one of ${spec.enum.join(" | ")}`);
+      return;
+    case "number":
+      if (typeof value !== "number" || Number.isNaN(value)) fail("a number");
+      return;
+    case "boolean":
+      if (typeof value !== "boolean") fail("a boolean");
+      return;
+    case "string[]":
+      if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) return fail("an array of strings");
+      if (value.length > LIMITS.arrayItems)
+        reasons.push(`${path}: ${value.length} items exceeds the ${LIMITS.arrayItems}-item limit — keep what the next step needs`);
+      for (const [i, v] of value.entries())
+        if (String(v).length > LIMITS.stringChars)
+          reasons.push(`${path}[${i}]: ${String(v).length} chars exceeds the ${LIMITS.stringChars}-char limit — summarize it`);
+      return;
+    case "object":
+      if (!isPlainObject(value)) return fail("an object");
+      checkFields(path, spec.of ?? {}, value as State, reasons);
+      return;
+    case "object[]":
+      if (!Array.isArray(value)) return fail("an array of objects");
+      if (value.length > LIMITS.arrayItems)
+        reasons.push(`${path}: ${value.length} items exceeds the ${LIMITS.arrayItems}-item limit`);
+      for (const [i, item] of value.entries()) {
+        if (!isPlainObject(item)) {
+          reasons.push(`${path}[${i}]: expected an object, got ${JSON.stringify(item)}`);
+          continue;
+        }
+        checkFields(`${path}[${i}]`, spec.of ?? {}, item as State, reasons);
+      }
+      return;
+  }
+}
+
+function checkFields(
+  path: string,
+  fields: Record<string, FieldSpec>,
+  value: State,
+  reasons: string[],
+): void {
+  for (const [key, v] of Object.entries(value)) {
+    const spec = fields[key];
+    const where = path ? `${path}.${key}` : key;
+    if (!spec) {
+      reasons.push(`${where}: unknown key. Known keys: ${Object.keys(fields).sort().join(", ")}`);
+      continue;
+    }
+    if (v === null) continue; // a delete; nothing to type-check
+    checkValue(where, spec, v, reasons);
+  }
+}
+
+/**
+ * Validate a candidate state against its skill schema: known keys, right types,
+ * declared phase, budget, and every guard. This runs outside the model on
+ * purpose — a state the model can't corrupt is the whole point.
+ */
+export function validateState(schema: SkillSchema, state: State): Rejection | Acceptance {
+  const reasons: string[] = [];
+  checkFields("", schema.fields, state, reasons);
+
+  if (typeof state.phase !== "string" || !schema.phases.includes(state.phase)) {
+    reasons.push(
+      `phase: "${String(state.phase)}" is not a ${schema.skill} phase. Declared: ${schema.phases.join(" → ")}`,
+    );
+  }
+
+  const size = JSON.stringify(state).length;
+  if (size > LIMITS.bytes)
+    reasons.push(
+      `state is ${size} bytes, over the ${LIMITS.bytes}-byte budget — drop what no later step reads`,
+    );
+
+  if (reasons.length === 0) {
+    for (const guard of schema.guards) if (guard.violated(state)) reasons.push(guard.reason);
+  }
+
+  return reasons.length ? { ok: false, reasons } : { ok: true, state };
+}
+
+/**
+ * Apply a patch to a state and validate the result. Rejects a move off a
+ * terminal phase unless `force` — a finished run doesn't quietly restart.
+ */
+export function applyPatch(
+  schema: SkillSchema,
+  current: State,
+  patch: State,
+  opts: { force?: boolean; now: string } = { now: "" },
+): Rejection | Acceptance {
+  if (!isPlainObject(patch)) return { ok: false, reasons: ["patch: expected a JSON object"] };
+  for (const key of ["runId", "skill", "createdAt"]) {
+    if (key in patch) return { ok: false, reasons: [`${key} is set at init and never patched`] };
+  }
+  if (
+    !opts.force &&
+    schema.terminal.includes(String(current.phase)) &&
+    "phase" in patch &&
+    patch.phase !== current.phase
+  ) {
+    return {
+      ok: false,
+      reasons: [
+        `run is at terminal phase '${current.phase}'; start a new run rather than reopening it (--force overrides)`,
+      ],
+    };
+  }
+  const merged = mergePatch(current, patch);
+  if (opts.now) merged.updatedAt = opts.now;
+  return validateState(schema, merged);
+}
+
+// ----------------------------------------------------------------- render ---
+
+/**
+ * Render the state as the compact block a skill pastes into the next step's
+ * prompt. Line-oriented so it greps, and so a diff between two steps reads.
+ */
+export function renderCompact(state: State): string {
+  const lines: string[] = [
+    `# ${state.skill} state · ${state.runId} · phase: ${state.phase}`,
+  ];
+  const skip = new Set(["skill", "runId", "phase", "createdAt", "updatedAt"]);
+  const emit = (key: string, value: unknown): void => {
+    if (value === undefined || value === null) return;
+    if (Array.isArray(value)) {
+      if (value.length === 0) return void lines.push(`${key}: (none)`);
+      lines.push(`${key}:`);
+      for (const item of value) {
+        lines.push(`  - ${isPlainObject(item) ? renderInline(item as State) : String(item)}`);
+      }
+      return;
+    }
+    if (isPlainObject(value)) {
+      for (const [k, v] of Object.entries(value as State)) emit(`${key}.${k}`, v);
+      return;
+    }
+    lines.push(`${key}: ${String(value)}`);
+  };
+  for (const [key, value] of Object.entries(state)) {
+    if (!skip.has(key)) emit(key, value);
+  }
+  lines.push(`updated: ${String(state.updatedAt ?? "unknown")}`);
+  return lines.join("\n");
+}
+
+function renderInline(obj: State): string {
+  return Object.entries(obj)
+    .filter(([, v]) => v !== undefined && v !== null && !(Array.isArray(v) && v.length === 0))
+    .map(([k, v]) => `${k}=${Array.isArray(v) ? v.join(",") : String(v)}`)
+    .join(" ");
+}
+
+// ------------------------------------------------------------------ store ---
+
+export function stateDir(root = process.cwd()): string {
+  return join(root, ".rig", "state");
+}
+
+export function statePath(runId: string, root = process.cwd()): string {
+  return join(stateDir(root), `${runId}.json`);
+}
+
+export function journalPath(runId: string, root = process.cwd()): string {
+  return join(stateDir(root), `${runId}.jsonl`);
+}
+
+/** Run IDs become filenames, so keep them to a safe, readable alphabet. */
+export function validRunId(runId: string): boolean {
+  return /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/.test(runId) && !runId.includes("..");
+}
+
+function readState(runId: string, root: string): State {
+  const path = statePath(runId, root);
+  if (!existsSync(path)) die(2, `no run '${runId}' — run 'rig-state init <skill> ${runId}' first`);
+  return JSON.parse(readFileSync(path, "utf8")) as State;
+}
+
+function writeState(state: State, root: string): void {
+  const path = statePath(String(state.runId), root);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(state, null, 2)}\n`);
+}
+
+function appendJournal(runId: string, entry: Record<string, unknown>, root: string): void {
+  const path = journalPath(runId, root);
+  mkdirSync(dirname(path), { recursive: true });
+  const prior = existsSync(path) ? readFileSync(path, "utf8") : "";
+  writeFileSync(path, `${prior}${JSON.stringify(entry)}\n`);
+}
+
+// -------------------------------------------------------------------- cli ---
+
+function die(code: number, message: string): never {
+  process.stderr.write(`rig-state: ${message}\n`);
+  process.exit(code);
+}
+
+function flag(argv: string[], name: string): string | undefined {
+  const i = argv.indexOf(name);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+
+function readPatchArg(argv: string[]): State {
+  const inline = flag(argv, "--json");
+  const raw = !inline || inline === "-" ? readFileSync(0, "utf8") : inline;
+  try {
+    return JSON.parse(raw) as State;
+  } catch (err) {
+    die(1, `patch is not valid JSON: ${(err as Error).message}`);
+  }
+}
+
+function main(argv: string[]): void {
+  const [command, ...rest] = argv;
+  const root = flag(argv, "--root") ?? process.cwd();
+  const now = new Date().toISOString();
+
+  switch (command) {
+    case "init": {
+      const [skill, runId] = rest;
+      if (!skill || !runId) die(2, "usage: rig-state init <skill> <runId> [--json '{...}']");
+      const schema = SCHEMAS[skill];
+      if (!schema) die(2, `unknown skill '${skill}'. Known: ${Object.keys(SCHEMAS).join(", ")}`);
+      if (!validRunId(runId)) die(2, `run id '${runId}' must be alphanumeric with . _ -, under 80 chars`);
+      if (existsSync(statePath(runId, root))) die(2, `run '${runId}' already exists — patch it instead`);
+      const seed = argv.includes("--json") ? readPatchArg(argv) : {};
+      const state = mergePatch(
+        { runId, skill, phase: schema.phases[0], createdAt: now, updatedAt: now },
+        seed,
+      );
+      const result = validateState(schema, state);
+      if (!result.ok) die(1, `rejected:\n  - ${result.reasons.join("\n  - ")}`);
+      writeState(result.state, root);
+      appendJournal(runId, { ts: now, step: "init", patch: seed }, root);
+      process.stdout.write(`${renderCompact(result.state)}\n`);
+      return;
+    }
+    case "patch": {
+      const [runId] = rest;
+      if (!runId) die(2, "usage: rig-state patch <runId> --json '{...}' [--step <label>]");
+      const current = readState(runId, root);
+      const schema = SCHEMAS[String(current.skill)];
+      if (!schema) die(2, `run '${runId}' names unknown skill '${current.skill}'`);
+      const patch = readPatchArg(argv);
+      const result = applyPatch(schema, current, patch, { force: argv.includes("--force"), now });
+      if (!result.ok) {
+        // Rollback-and-retry: state is untouched, and the reasons say what to fix.
+        process.stderr.write(`rig-state: patch rejected:\n  - ${result.reasons.join("\n  - ")}\n`);
+        process.stdout.write(`${renderCompact(current)}\n`);
+        process.exit(1);
+      }
+      writeState(result.state, root);
+      appendJournal(runId, { ts: now, step: flag(argv, "--step") ?? "", patch }, root);
+      process.stdout.write(`${renderCompact(result.state)}\n`);
+      return;
+    }
+    case "get": {
+      const [runId] = rest;
+      if (!runId) die(2, "usage: rig-state get <runId> [--field <dotted.path>]");
+      const state = readState(runId, root);
+      const field = flag(argv, "--field");
+      if (field) {
+        const value = dig(state, field);
+        if (value === undefined) process.exit(1);
+        process.stdout.write(`${typeof value === "object" ? JSON.stringify(value) : String(value)}\n`);
+        return;
+      }
+      process.stdout.write(`${JSON.stringify(state, null, 2)}\n`);
+      return;
+    }
+    case "show": {
+      const [runId] = rest;
+      if (!runId) die(2, "usage: rig-state show <runId>");
+      process.stdout.write(`${renderCompact(readState(runId, root))}\n`);
+      return;
+    }
+    case "list": {
+      const dir = stateDir(root);
+      if (!existsSync(dir)) return;
+      const want = flag(argv, "--skill");
+      for (const file of readdirSync(dir).filter((f) => f.endsWith(".json")).sort()) {
+        const state = JSON.parse(readFileSync(join(dir, file), "utf8")) as State;
+        if (want && state.skill !== want) continue;
+        process.stdout.write(
+          `${state.runId}\t${state.skill}\t${state.phase}\t${state.updatedAt ?? ""}\t${state.nextAction ?? ""}\n`,
+        );
+      }
+      return;
+    }
+    case "journal": {
+      const [runId] = rest;
+      if (!runId) die(2, "usage: rig-state journal <runId>");
+      const path = journalPath(runId, root);
+      if (!existsSync(path)) die(2, `no journal for '${runId}'`);
+      process.stdout.write(readFileSync(path, "utf8"));
+      return;
+    }
+    case "rm": {
+      const [runId] = rest;
+      if (!runId) die(2, "usage: rig-state rm <runId>");
+      if (!validRunId(runId)) die(2, `run id '${runId}' is not a valid id`);
+      for (const path of [statePath(runId, root), journalPath(runId, root)]) {
+        if (existsSync(path)) rmSync(path);
+      }
+      return;
+    }
+    default:
+      die(2, "usage: rig-state <init|patch|get|show|list|journal|rm> [args]");
+  }
+}
+
+if (import.meta.main) main(process.argv.slice(2));
diff --git a/skills/rig-doctor/SKILL.md b/skills/rig-doctor/SKILL.md
index 625ebf7..a543904 100644
--- a/skills/rig-doctor/SKILL.md
+++ b/skills/rig-doctor/SKILL.md
@@ -71,17 +71,20 @@ run /rig-onboard"). Everything below is gated on what the config actually uses
 - **auto-accept** — a skill **cannot** read the harness's mode, so this is
   advice, not a check: if you're *not* in auto-accept, epics and `rig-loop`
   pause on every edit. In Claude Code, `shift+tab` toggles it.
-- **`.rig/epics/` gitignored** — it's throwaway coordination state and must not
-  be committed. *(--fix: add `.rig/epics/` to `.gitignore`.)*
+- **`.rig/state/` gitignored** — run state and its journal are throwaway
+  coordination state and must not be committed. *(--fix: add `.rig/state/` to
+  `.gitignore`.)*
 - **sourceScope paths exist** — each `sourceScope[i]` resolves. Fix: correct it.
-- **stale epics** — `.rig/epics/*.json` whose branches are already merged/gone.
+- **stale runs** — `bun <SCRIPTS>/rig-state.ts list` entries whose branch is
+  merged or gone, or whose `updatedAt` is over a week old. Fix: `rig-state.ts rm
+  <run-id>`.
 
 ## `--fix` (opt-in)
 
 Only when `--fix` is passed. Show the exact change and get a yes before each,
 then apply **only the safe set**:
 - create missing `shapeLabels` repo labels (`gh label create … --force`);
-- add `.rig/epics/` to `.gitignore`;
+- add `.rig/state/` to `.gitignore`;
 - copy `REVIEWER.md` from the kit template if absent;
 - copy `STYLE.md` from the kit template if absent;
 - add missing board columns.
diff --git a/skills/rig-epic/SKILL.md b/skills/rig-epic/SKILL.md
index 6e6fc01..e4a336b 100644
--- a/skills/rig-epic/SKILL.md
+++ b/skills/rig-epic/SKILL.md
@@ -17,7 +17,7 @@ delivery is one squashed rebase.
 Reads `.rig/config.json` (defaults in parentheses):
 
 - `tracker.provider` — `linear` | `github` | `none` (`none`). How parent/child
-  items are stored. `none` → items live only in the epic **state file** (below);
+  items are stored. `none` → items live only in the epic **run state** (below);
   no tracker calls.
 - `tracker.team` / `tracker.project` / `tracker.ticketPrefix` / `tracker.githubIntegration`.
 - `tracker.shapeLabels.epic` (`epic`) — GitHub-only label put on the parent at
@@ -40,36 +40,54 @@ Reads `.rig/config.json` (defaults in parentheses):
 Delegates to `/rig-task` (per child), `/rig-worktree` (checkouts), `/rig-review`
 + `/rig-review fix` (the combined-diff review), `/rig-tidy` (optional).
 
-### Epic state file (replaces any external memory)
+### Epic run state (replaces any external memory)
 
-Each active epic is tracked in a repo-local JSON file at
-**`.rig/epics/<integration-branch>.json`**:
+Each active epic is one **run state** document, keyed by its integration branch
+— `.rig/state/<integration-branch>.json`. Read and write it through
+`rig-state`, which validates every update outside the model; see
+[`docs/state.md`](../../docs/state.md). Resolve the helper once: `<STATE>` =
+`bun <SCRIPTS>/rig-state.ts`, with `<SCRIPTS>` resolved from the repo root — `.claude/scripts/` then
+`.rig/scripts/`, first hit wins, as in [`/rig-worktree`](../rig-worktree/SKILL.md).
 
-```json
+```jsonc
 {
-  "parent": "ABC-42 or a slug in tracker=none",
-  "parentTitle": "…",
-  "integrationBranch": "abc-42-<slug>",
+  "runId": "abc-42-agent-as-definition",   // = the integration branch
+  "skill": "rig-epic",
+  "phase": "plan|start|run|review|finish|done",
+  "parent": { "id": "ABC-42", "title": "…", "source": "linear|github|none" },
+  "integrationBranch": "abc-42-agent-as-definition",
   "whyEpic": "which children interleave and why",
   "children": [
-    { "id": "ABC-43", "title": "…", "blockedBy": [], "branch": null, "status": "todo|merged" }
-  ]
+    { "id": "ABC-43", "title": "…", "blockedBy": [], "branch": null, "pr": 0, "status": "todo|in-progress|blocked|merged" }
+  ],
+  "specReview": { "frontLoaded": true, "outcome": "cleared", "blockers": [] },
+  "combinedReview": { "outcome": "pending", "p0": 0, "p1": 0, "p2": 0 },
+  "nextAction": "run child ABC-44"
 }
 ```
 
+Three guards make the document assert the gates this skill already describes.
+`finish` requires every child at `merged`. `review` requires at least one merged
+child. A `merged` child has to record its `branch`. A rejected patch means the
+epic isn't where you think it is — read the reason, don't work around it.
+
 **Where the truth lives.** On `tracker: github`, the source of truth is the
-**parent issue and its native sub-issues on the tracker** — not this file. The
-JSON is a *local cache* rebuilt from the tracker (`gh api
+**parent issue and its native sub-issues on the tracker** — not this document.
+It's a *local cache* rebuilt from the tracker (`gh api
 repos/<repo>/issues/<parent>/sub_issues`), and it is **gitignored — never
-committed** (`.rig/epics/` is in `.gitignore`). On `linear` the parent/children
-live in Linear; on `none` the file is the only record. Either way it's throwaway
-coordination state, rebuildable from the tracker at any time — the board is the
-shared brain, not the repo.
+committed** (`.rig/state/` is in `.gitignore`). On `linear` the parent/children
+live in Linear; on `none` the document is the only record. Either way it's
+throwaway coordination state, rebuildable from the tracker at any time — the
+board is the shared brain, not the repo.
+
+If the `rig-state` script is absent, keep the same document by hand at the same
+path and carry on — the validation is an accelerator, not a dependency.
 
-`next`/`run`/`review`/`finish`/`prune` read the reconstructed set. Parent
+`next`/`run`/`review`/`finish`/`prune` read the reconstructed set
+(`<STATE> show <integration-branch>`). Parent
 inference (when `<PARENT>` is omitted): on `github`, the open issue labelled
-`shapeLabels.epic` that has sub-issues; else if exactly one `.rig/epics/*.json`
-exists, use it; if zero or many, ask.
+`shapeLabels.epic` that has sub-issues; else if exactly one `rig-epic` run
+exists (`<STATE> list --skill rig-epic`), use it; if zero or many, ask.
 
 **Intent banner:** every invocation MUST print one line first — mode, what
 branch PRs target, what it won't do:
@@ -80,7 +98,10 @@ rig-epic: <subcommand> — <action>. PRs target <branch>. Will not <thing>.
 
 ## `status` (default, report-only)
 
-Read the epic state file(s). Report: integration branch + commits ahead of
+Read the epic run state(s): `<STATE> list --skill rig-epic`, then `<STATE> show
+<integration-branch>` for each.
+
+Report: integration branch + commits ahead of
 `vcs.baseRef`; open child PRs (`gh pr list --base <integration-branch>`) and
 their state; each child's tracker status (if a tracker); leftover merged/deleted
 worktrees (suggest `/rig-epic prune`); and a one-line recommendation (`open child
@@ -89,7 +110,7 @@ nothing; spawn nothing.
 
 ## `plan <FEATURE>`
 
-Decompose a feature into a parent + 3–8 children, write the state file, then
+Decompose a feature into a parent + 3–8 children, open the run state, then
 chain into `start`.
 
 Use this only when the work is genuinely epic-shaped (children interleave —
@@ -115,7 +136,7 @@ no integration branch.
      exists first (`gh label create "<L>" --force`). Skip entirely if
      `tracker.shapeLabels` is absent. (Linear needs no label — native parent
      grouping already distinguishes the epic.)
-   - `tracker: none` → the parent is a slug + title recorded in the state file only.
+   - `tracker: none` → the parent is a slug + title recorded in the run state only.
 4. **Create each child** with its dependency edges.
    - Small enough for one agent session (1–3 files); concrete, testable
      acceptance criteria; foundational work first.
@@ -126,11 +147,14 @@ no integration branch.
      a native sub-issue of the parent** —
      `gh api repos/<repo>/issues/<parent#>/sub_issues -F sub_issue_id=$(gh api repos/<repo>/issues/<child#> -q .id)` —
      and write "Blocked by #<n>" in the child body (GitHub has no native
-     blockedBy). The sub-issues **are** the epic on the board; the `.rig/epics`
-     cache is derived from them, never the other way around.
+     blockedBy). The sub-issues **are** the epic on the board; the run state's
+     `children` cache is derived from them, never the other way around.
    - **`tracker: linear`**: set the native parent + blocked-by relations.
-   - **`none`**: the state file is the only record.
-5. **Show a summary table** (ID · Title · Depends On).
+   - **`none`**: the run state is the only record.
+5. **Show a summary table** (ID · Title · Depends On), then **open the run
+   state**:
+   `<STATE> init rig-epic <integration-branch> --json '{"parent":{…},"whyEpic":"…","children":[…],"nextAction":"cut the integration branch"}'`
+   (patch `children` instead if the run already exists).
 6. **Chain into `start <PARENT>`** — `plan` is plan-and-start; don't stop to ask.
 7. **Stop after `start`.** Report the integration branch, the children, and the
    next step (`/rig-epic next` for one, `/rig-epic run` for the loop). Never
@@ -146,9 +170,10 @@ GitHub epic (e.g. `/rig-epic 42` or `/rig-epic run`), reconstruct the children
 from its **sub-issues** rather than trusting any local file:
 `gh api repos/<repo>/issues/<parent#>/sub_issues` → each becomes a child (id =
 issue number, `blockedBy` parsed from "Blocked by #n" in the body,
-`status` from open/closed + board column). Write that to `.rig/epics/<branch>.json`
-(gitignored). This is what makes an epic you were handed on the board runnable —
-no committed state required.
+`status` from open/closed + board column). Write that to the run state —
+`<STATE> init rig-epic <integration-branch> --json '{…}'`, or patch `children`
+if the run already exists. This is what makes an epic you were handed on the
+board runnable — no committed state required.
 
 1. **Integration branch name:** `<parent-slug>-<title-slug>` (kebab, e.g.
    `abc-42-agent-as-definition`).
@@ -159,9 +184,11 @@ no committed state required.
    ```
    Non-destructive. If the branch already exists, leave it (never overwrite —
    could destroy in-flight work).
-3. **Write `.rig/epics/<integration-branch>.json`** (schema above) with the
-   parent, why-epic, and every child + `blockedBy`. This is what makes each
-   `/rig-task <child>` target the integration branch instead of the trunk.
+3. **Write the run state** (schema above) with the parent, why-epic, and every
+   child + `blockedBy`:
+   `<STATE> patch <integration-branch> --step start --json '{"phase":"start","integrationBranch":"…","children":[…],"nextAction":"first unblocked child"}'`.
+   This is what makes each `/rig-task <child>` target the integration branch
+   instead of the trunk.
 4. **If a tracker is configured**, add an "Integration branch: target
    `<integration-branch>`, not the trunk" note to each child so the next agent
    doesn't re-read this skill, and ensure the **parent** is In Progress
@@ -200,14 +227,15 @@ no committed state required.
 5. **Merge gate — only `clean` is merge-green:**
    - `clean` → the child enabled auto-merge, so its PR lands when CI passes.
      **Wait** for it: poll `gh pr view <N> --json state` (~60s, up to ~30min)
-     until `MERGED`, then `git fetch origin` and confirm the tip advanced. Record
-     the child `merged` + its branch in the state file, and **ensure the child
-     ticket is Done** (adaptive — move only if not already Done; defer if a live
+     until `MERGED`, then `git fetch origin` and confirm the tip advanced. Patch the
+     child to `merged` with its branch and PR number — send the whole `children`
+     array, since arrays replace wholesale — and point `nextAction` at the next
+     pick. Then **ensure the child ticket is Done** (adaptive — move only if not already Done; defer if a live
      integration closed it). On a **`tracker: github` board**, move it via the
      adapter: `<TRACKER> set-status <child#> "<tracker.board.statusOptions.done>"`.
-     (The child'"'"'s PR merged into the **integration branch**, not the default
-     branch, so its `Closes #<n>` has **not** fired — the adapter move is what
-     marks it Done now; the issue itself closes when the epic squashes to trunk.)
+     (The child's PR merged into the **integration branch**, not the default
+     branch, so its `Closes #<n>` has **not** fired. The adapter move is what
+     marks it Done now. The issue closes when the epic squashes to trunk.)
      If CI fails / it never merges → treat as not-clean.
    - anything else (`actionable`/`timeout`, or a tracker-parked state) → the child
      did **not** enable auto-merge; stop. Surface the outcome, the PR URL, and any
@@ -225,7 +253,11 @@ resolve the specs before any child starts coding:
 1. Fan out `agents.architect` + `agents.qa` over **every** child's spec, read
    against the integration branch; each returns its blockers.
 2. Consolidate into one blocker list and resolve it **once** — clarify in the
-   tracker, or decide with the user. This is the epic's single spec decision point.
+   tracker, or decide with the user. This is the epic's single spec decision
+   point. **Patch:**
+   `{"phase":"run","specReview":{"frontLoaded":true,"outcome":"cleared|halted","blockers":[…]},"nextAction":"first unblocked child"}`
+   — so a resumed session knows the specs are cleared and doesn't re-run the
+   fan-out.
 3. Then run each child with its own spec gate **pre-cleared**:
    `/rig-task <CHILD> --base <integration-branch> --auto-merge --spec-cleared`, so
    no child re-pauses on a question already answered.
@@ -293,6 +325,9 @@ child worktree if one still exists (avoids a fresh install + env re-symlink).
      re-reviews to clean), commit + `git push origin <integration-branch>`,
      re-run `review` once to confirm convergence.
 6. **Outcome string** (for `finish`): `clean — …` / `applied — …` / `paused — …`.
+   **Patch:** `{"phase":"review","combinedReview":{"outcome":"clean|applied|paused","p0":<n>,"p1":<n>,"p2":<n>},"nextAction":"…"}`.
+   `review` is guarded on at least one merged child; a rejection means no child
+   has landed yet.
 
 ## `finish [<PARENT>] [--merge]`
 
@@ -330,8 +365,11 @@ opens only on `clean` or `applied`. On `paused`, stop and wait.
    `--merge`, leave the parent In Progress — it goes Done when a human merges the
    squash PR (a later `finish`/reconcile run, or a live integration's closes-verb,
    sets it).
-6. **Delete the epic state file** `.rig/epics/<integration-branch>.json` (the
-   work is on the trunk now).
+6. **Close the run** — `<STATE> patch <integration-branch> --json
+   '{"phase":"done","nextAction":null}'`. Once the squash PR merges, the work is
+   on the trunk: `<STATE> rm <integration-branch>`. `phase: finish` is guarded on
+   every child being `merged`, so a rejection there names the child still
+   outstanding.
 7. **Offer local verification.** Ask whether to verify the epic on a local build
    before moving on. If the project ships a local-run/QA skill, invoke it **from
    the integration-branch worktree** (`cd` there first — don't accidentally serve
@@ -364,9 +402,12 @@ or gone on origin. Epic-specific *policy* here; the teardown delegates to
 - **Auto-closed PRs aren't reviewed.** FF'ing over a child's tip closes its PR as
   MERGED without a gate — the real review is `finish`'s combined squash PR. If a
   child truly needs its own review, hold off FF'ing and let the user merge it.
-- **State file carries the *why*.** The integration branch carries the code; the
-  `.rig/epics/*.json` note carries why-it's-an-epic, the dependency chain, and
-  what got descoped. Future sessions shouldn't re-derive the plan.
+- **Run state carries the *why*.** The integration branch carries the code; the
+  run state carries why-it's-an-epic, the dependency chain, and what got
+  descoped. Future sessions shouldn't re-derive the plan. It also carries the
+  loop position: which child is in flight, which spec blockers are already
+  resolved, and what the combined review found. That position is what an epic
+  loses to a compacted transcript.
 - **Drive tracker state adaptively — `githubIntegration` is a hint, not a gate.**
   The flag can claim `true` while nothing is actually connected (no PR ever links
   to an issue), which silently strands tickets. So *ensure* each transition
diff --git a/skills/rig-plan/SKILL.md b/skills/rig-plan/SKILL.md
index 5686c85..9bff867 100644
--- a/skills/rig-plan/SKILL.md
+++ b/skills/rig-plan/SKILL.md
@@ -77,7 +77,9 @@ chunks), and `/rig-issue` (singletons). Hands execution to `/rig-epic start` /
    - **epic** → create the parent + children following `/rig-epic plan`'s
      creation steps (parent gets `shapeLabels.epic`; children carry their
      `blockedBy`), but **stop before `start`** — do not cut an integration
-     branch. Record it in `.rig/epics/<slug>.json` as planned-not-started.
+     branch. Open its run state as planned-not-started:
+     `bun <SCRIPTS>/rig-state.ts init rig-epic <slug> --json '{"parent":{…},"children":[…],"nextAction":"awaiting /rig-epic start"}'`
+     (see [`docs/state.md`](../../docs/state.md)).
    - **sprint** → create the independent items following `/rig-sprint plan` (each
      gets `shapeLabels.sprint`).
    - **ticket** → `/rig-issue create`.
diff --git a/skills/rig-review/SKILL.md b/skills/rig-review/SKILL.md
index 559995a..2a0518a 100644
--- a/skills/rig-review/SKILL.md
+++ b/skills/rig-review/SKILL.md
@@ -66,7 +66,31 @@ and has the reviewer assert each as a **P1**. No-op if the project ships none.
     `vcs.baseRef`.
 
 If invoked from another skill, the caller may thread `{base}`, `{ticket-id}`,
-`{worktree-path}` — use them.
+`{worktree-path}`, and `{run-id}` — use them.
+
+## Run state
+
+A `fix` loop spans several rounds and a lot of bot output, so keep which
+findings are already fixed on disk rather than in the transcript. `<STATE>` =
+`bun <SCRIPTS>/rig-state.ts`. Resolve `<SCRIPTS>` from the repo root:
+`.claude/scripts/` then `.rig/scripts/`, first hit wins, as in
+[`/rig-worktree`](../rig-worktree/SKILL.md). See
+[`docs/state.md`](../../docs/state.md). Skip these calls if the script is
+absent.
+
+- **Called with a `{run-id}`** (the usual case — `/rig-task` Step 4.5 and Step 6
+  pass theirs): patch that run's `review` block after each round —
+  `<STATE> patch {run-id} --step review-round-<n> --json '{"review":{"source":"local|bot","round":<n>,"p0":<n>,"p1":<n>,"p2":<n>,"open":["<finding, one line>"],"outcome":"pending|clean|actionable|timeout|unresolved"}}'`.
+  The caller reads it back instead of re-running `find`.
+- **Invoked directly on a PR**: open your own run, `pr-<N>` —
+  `<STATE> init rig-review pr-<N> --json '{"phase":"fix","pr":<N>,"source":"bot","maxRounds":<review.maxRounds>,"round":1}'`
+  — and patch `findings` and `round` each pass. Two guards apply: `outcome:
+  clean` is rejected while any finding is still `open`, and `round` may not
+  exceed `maxRounds`. Both rejections mean the same thing — hand back to a
+  human rather than declaring victory.
+
+Record the finding, not the bot's prose: severity, `file:line`, one line of
+summary, and its status.
 
 ---
 # `find` — the read-only gate
@@ -157,7 +181,8 @@ If invoked from another skill, the caller may thread `{base}`, `{ticket-id}`,
      > Findings:\n{find_output}\n\nFor each, either apply the fix or explain in
      > one line why the finding is wrong. Don't silently skip."
    - Re-run the `find` verb (fresh context). If still P0/P1, increment `round`.
-4. Return the outcome.
+   - Patch the run state with the round's counts and which findings closed.
+4. Return the outcome, and patch it (`"outcome": "clean" | "unresolved"`).
 
 **Outcomes (local):**
 - `clean — 0 P0/P1 vs {base}` (P2/P3, if any, listed)
@@ -264,7 +289,8 @@ Loop, `round` starting at 1:
      doesn't re-run a gate check — re-run the required check or let the next push
      re-trigger it.
    - Re-trigger: `gh pr comment $PR --repo "$REPO" --body "$RETRIGGER"`.
-   - Increment `round`; update `PUSH_TIME` to the new commit; loop to 1.
+   - Increment `round`; update `PUSH_TIME` to the new commit; patch the run
+     state with the new round and finding statuses; loop to 1.
 4. **After N rounds** (or `clean`/`timeout`): the merge-queue gate is the
    authority — converge to it. If the project ships a P1-gate script, run it
    **with `REVIEW_BOT_LOGIN` set to the bot's login regex** (the same one used
diff --git a/skills/rig-task/SKILL.md b/skills/rig-task/SKILL.md
index 0a8ad36..95e11c3 100644
--- a/skills/rig-task/SKILL.md
+++ b/skills/rig-task/SKILL.md
@@ -101,6 +101,32 @@ Print the resolved unit + phase as the first output line, e.g.
 `rig-task start: ABC-369 (from branch alice/abc-369-...)` or
 `rig-task start: ad-hoc "add dark mode"`.
 
+## Run state
+
+This skill runs long enough to outlive its own transcript. A compaction between
+Step 3 and Step 6 drops the acceptance criteria, the failing assertion, and
+which review findings you already fixed. Keep them on disk instead, in a
+validated run-state document. See [`docs/state.md`](../../docs/state.md).
+
+Resolve the helper once: `<STATE>` = `bun <SCRIPTS>/rig-state.ts`, with
+`<SCRIPTS>` resolved from the repo root — `.claude/scripts/` then
+`.rig/scripts/`, first hit wins, as in [`/rig-worktree`](../rig-worktree/SKILL.md). If the script is absent, skip every state call below and run as
+before — the state is an accelerator, not a dependency.
+
+**Run id:** the ticket, lowercased (`abc-18`), or a kebab slug of the task in
+ad-hoc mode. `start` and `finish` share it. That reuse is what lets `finish`
+read what `start` recorded instead of reconstructing it.
+
+Each step below ends with the patch it owes. Two rules govern what goes in:
+
+- **Persist what a later step reads**, not what happened. Record the branch
+  name, the failing assertion, and the reason you rejected an approach. Don't
+  record a narration of Step 3.
+- **A rejected patch means fix the patch**, not the state. The tool prints the
+  reason and leaves the state untouched; correct it and retry. A rejection on
+  `phase: pr-open` means a gate genuinely isn't met.
+
+---
 ---
 The steps below are grouped into the two phases. **Steps 1–5 are `start`;
 Steps 6–7 are `finish`.** A bare `rig-task` runs all of them in order.
@@ -141,6 +167,14 @@ Steps 6–7 are `finish`.** A bare `rig-task` runs all of them in order.
    Base from `vcs.baseRef`. `cd` into the printed worktree path (`$WT`); use it
    as `{worktree-path}` in the agent prompts below.
 
+3. **Open the run state** with the spec from Step 1.1:
+   ```bash
+   <STATE> init rig-task <run-id> --json '{"spec":{"id":"…","title":"…","source":"linear|github|adhoc","acceptanceCriteria":["…"]},"base":"<vcs.baseRef or --base>","nextAction":"spec review"}'
+   ```
+   Then patch the checkout: `<STATE> patch <run-id> --step step-1 --json
+   '{"branch":"…","worktree":"$WT"}'`. If the run already exists, you're
+   resuming — `<STATE> show <run-id>` and continue from its phase.
+
    **Name the session** so a background-job list reads as the work, not the
    prompt (Claude-Code-only; no-ops elsewhere). Pass `--name` through to
    `/rig-worktree` — `"FEAT: <title> (<ticket>)"` for new behavior/bug fixes
@@ -159,6 +193,10 @@ Launch the **architect** and **qa** agents in parallel (names via `agents.*`):
   needed? Are the acceptance criteria testable? What edge cases matter?
   Spec:\n{title}\n\n{description}"
 
+**Patch:** `{"phase":"spec-review","decisions":["<what you clarified, one line each>"],"blockers":["<what a human must answer>"],"nextAction":"write failing tests"}`.
+Blockers are what a resumed session needs to know it's parked on — clear them
+(`"blockers":null`) once they're answered.
+
 If either flags something that should be fixed before coding, clarify it — and,
 in tracker mode, update the item's description with the clarification and tell
 the user what changed. **With `--spec-cleared`** (a caller like `/rig-epic run`
@@ -179,6 +217,10 @@ Launch **qa** to write tests against the spec, *before* any implementation:
 
 Run the suite from the worktree: `cd "$WT" && <test.command>`.
 
+**Patch:** `{"phase":"red","tests":{"command":"<test.command>","status":"red","fail":<n>,"failures":["<the assertion, not the stack trace>"]},"nextAction":"minimum implementation"}`.
+The failing assertions are the spec Step 4 codes against, so they're worth the
+bytes; the stack traces aren't.
+
 **Verify red.** The new tests must fail with a message that reflects the missing
 behavior (e.g. "expected X, got undefined" / "not-yet-implemented symbol"). A
 new test that passes immediately was pinning existing behavior — send it back to
@@ -194,6 +236,8 @@ Launch **coder** with the failing tests as the spec:
   — no features not required by a test.\n\nSpec:\n{title}\n{description}\n\n
   Architect notes:\n{architect_output}\n\nFailing tests:\n{test_output}"
 
+**Patch once green:** `{"phase":"green","tests":{"status":"green","pass":<n>,"fail":0,"failures":null},"nextAction":"pre-PR self-review"}`.
+
 Re-run the suite. If still red, send coder a fix iteration with the current
 failures. **Max 3 iterations**; if still red after 3, stop and surface to the
 user — the spec is likely wrong or there's an unstated constraint. If
@@ -222,6 +266,9 @@ don't pay a round-trip on. Delegate so the gate lives in one place:
      round it returns `unresolved` — stop, surface to the user, don't push.
 3. Report the final state before pushing, e.g. `tests: green, review: 0 P0/P1 +
    2 P2 (deferred)`.
+4. **Patch:** `{"phase":"self-review","review":{"source":"local","round":<n>,"p0":0,"p1":0,"p2":<n>,"open":["<deferred P2, one line each>"]},"nextAction":"open the PR"}`.
+   The `pr-open` phase is guarded on `tests.status: green` and zero P0/P1. A
+   rejection here means the gate isn't met — go fix the code, not the patch.
 
 ## Step 5 — Push and open the PR
 
@@ -265,7 +312,10 @@ don't pay a round-trip on. Delegate so the gate lives in one place:
        no GitHub *event* moves a card to In Review, so the adapter does it. Skip
        if no board is configured.
    Ensure the item's labels match `tracker.labelMapFile` if that file exists.
-5. Capture the PR number for Step 6.
+5. Capture the PR number for Step 6, and **patch:**
+   `{"phase":"pr-open","pr":{"number":<n>,"url":"…","state":"open"},"nextAction":"drive the review loop"}`.
+   This is what a later `finish` resolves the PR from — no re-derivation from
+   the branch.
 
 **Merge behavior.** Without `--auto-merge`, **do NOT `gh pr merge`** — open the PR
 and hand back (the human, `/rig-sprint`, or `/rig-epic` decides). **With
@@ -278,9 +328,16 @@ labels if the project ships a PR-labeler workflow — it applies them.
 ## ── `finish` phase (Steps 6–7) ──
 
 When resuming via `rig-task finish` (rather than a one-shot run), first
-**re-establish context**: resolve the open PR and its worktree from the target
-arg / current branch / the single open PR for this unit, and `cd` into that
-worktree before continuing.
+**re-establish context from the run state** — `<STATE> show <run-id>` (or
+`<STATE> list --skill rig-task` if you're not sure of the id). It carries the
+spec, the branch, the worktree, the PR, and what the self-review deferred, so a
+compacted or brand-new session picks up where `start` left off. `cd` into
+`worktree` and continue.
+
+**If there's no state** — the run predates it, or `start` ran without the
+script — fall back to the old path. Resolve the open PR and its worktree from
+the target arg, the current branch, or the single open PR for this unit, then
+`cd` into that worktree.
 
 ## Step 6 — Review-bot loop: watch (default) or drive (`--local`)
 
@@ -300,6 +357,8 @@ worktree before continuing.
   - `actionable` — still has feedback after the last round; left for a human.
   - `timeout` — bot didn't respond in time; left for a human.
 
+**Patch:** `{"phase":"review-loop","review":{"source":"bot","round":<n>,"outcome":"clean|actionable|timeout"},"nextAction":"hand back"}`.
+
 Only `clean` is merge-green; everything else stops for a human.
 
 ## Step 7 — Hand back
@@ -316,6 +375,12 @@ it). If the PR is still open, leave it **In Review** — the merge event (a late
 `finish` run, `/rig-epic`'s merge gate, or a live integration) moves it to Done.
 Never clobber a further-along state.
 
+**Close the run.** Patch `{"phase":"done","nextAction":null}` once the PR is
+open and the review reached a terminal state (`done` is guarded on a
+`pr.number`). Keep the state file — `/rig-doctor` reports stale runs, and the
+journal (`<STATE> journal <run-id>`) is how a human reconstructs a run that went
+wrong. Delete it with `<STATE> rm <run-id>` when the PR merges.
+
 If invoked by `/rig-sprint`, **return the outcome string** so the caller can decide
 whether to merge, and skip any local-QA offer (the caller makes it once).