checkpoint

ワークフローチェックポイントスキル

概要

コンテキストの自動要約後も保持される、永続的なワークフロー状態を保存・変更します。

状態ファイルには、タスクの詳細、ワークツリーの場所、PR の URL、レビュー状況が保存されます。このスキルはワークフロー状態の書き込み側を担い、ワークフローの初期化、フィールドの更新、フェーズの移行、構造化された引き継ぎ情報の記録を行います。休止後の再開、git との照合、ワークフローの存在確認など、読み取り／復元側については、@skills/rehydrate/SKILL.md を参照してください。

トリガー

次の場合にこのスキルを有効にします。

• 新しいワークフローの開始（ideate）
• ワークフローのフェーズ間の移行
• 後で続行するための進捗の保存（checkpoint）

フェーズの移行

すべてのワークフロータイプで有効な移行、ガード、前提条件については、references/phase-transitions.md に記載されています。重要： フェーズの変更は、フィールドの変更とは別の操作です。移行にガードがある場合は、前提フィールドを先に action: "update" で更新し、その後 action: "transition" を実行します。ガードは最新の状態を読み取るため、ガードの評価前に更新が反映されます。action: "update" で phase を変更しようとすると、transition を指定するよう示す RESERVED_FIELD エラーが返されます（以下の「予約済みフィールド」を参照）。

スキーマの確認

パラメーターのスキーマを確認するには exarchos_workflow({ action: "describe", actions: ["update", "init", "get"] }) を使用し、フェーズの移行、ガード、プレイブックのガイダンスを確認するには exarchos_workflow({ action: "describe", playbook: "feature" }) を使用してください。軽量な oneshot 版（synthesisPolicy によって決まる implementing → synthesize|completed の選択状態を備えています）については、exarchos_workflow({ action: "describe", playbook: "oneshot" }) を呼び出してください。oneshot は feature/debug/refactor と並ぶ、第一級のプレイブックです。イベントデータのスキーマには exarchos_event({ action: "describe", eventTypes: ["workflow.transition", "task.completed"] }) を使用してください。

状態の保存場所

ワークフロー状態はファイルシステムではなく、MCP イベントストアに保存されます。状態の読み取りには exarchos_workflow get を使用し、アクティブなワークフローの確認には exarchos_view pipeline を使用してください。パイプラインビューはデフォルトでリポジトリ単位です。呼び出し元のリポジトリのみが対象となります。レスポンスの unscopedTotal が page.total より大きい場合、他のリポジトリにあるワークフローは表示されていません。scope: "all" を指定して再クエリすると、それらを表示できます。~/.claude/workflow-state/*.state.json はレガシーのパスであり、古い状態または空の可能性があるため、スキャンしないでください。

状態の操作

MCP ツールのシグネチャ、エラー処理、アンチパターンの詳細については、references/mcp-tool-reference.md を参照してください。

状態の初期化

ideate の開始時に、以下を指定して exarchos:exarchos_workflow の action: "init" を使用します。

• featureId：ワークフロー識別子（例："user-authentication"）
• workflowType："feature"、"debug"、"refactor"、"oneshot" のいずれか
• synthesisPolicy (任意、oneshot のみ)："always"、"never"、"on-request" のいずれか（デフォルトは "on-request"）。oneshot 以外のタイプでは無視されます。

これにより、新しいワークフロー状態エントリが作成されます。初期フェーズは workflowType によって異なります。

• feature → plan から開始
• debug → triage から開始
• refactor → explore から開始
• oneshot → plan から開始

ワークフロータイプの概要

• feature — サブエージェントのディスパッチとレビューを伴う実機能向けのフルフロー plan → plan-review → delegate → review → synthesize
• debug — トラック選択を伴うバグ対応ワークフローの triage → investigate → (thorough | hotfix)
• refactor — コード改善向けの explore → brief → (polish | overhaul)。小規模な変更には polish、複数タスクには overhaul を使用
• oneshot — ささいな変更向けの plan → implementing → (completed | synthesize)。デフォルトでは直接コミットし、任意で PR を作成できます。PR 作成の経路は、synthesisPolicy と synthesize.requested イベントによって決まる選択状態ガードで解決されます。

選択状態の仕組みや finalize_oneshot トリガーなど、軽量版の詳しい説明については、@skills/oneshot/SKILL.md を参照してください。

状態の更新（フィールドのみ）

exarchos:exarchos_workflow を action: "update"、featureId、updates とともに使用します。このアクションで変更できるのはフェーズ以外のフィールドのみです。phase、workflowType、featureId、createdAt、version は予約済みです（下記の「予約済みフィールド」を参照）。

• 成果物のパスを設定する: updates: { "artifacts.spec": "docs/specs/2026-01-05-feature.md" }
• タスクを完了する: update は使用しないでください。タスクのゲートを通過した後に exarchos:exarchos_orchestrate を action: "task_complete" とともに呼び出すか、settle にタスクを完了状態にしてもらいます。タスクを完了状態にできるのは task_complete と settle のみです。
• ワークツリーを追加する: updates: { "worktrees.wt-001": { "branch": "feature/001-types", "taskId": "001", "status": "active" } }

ワークツリーのステータス値: 'active' | 'merged' | 'removed'

フェーズの遷移

exarchos:exarchos_workflow を action: "transition"、featureId、target とともに使用します。

• フェーズを進める: target: "delegate"

遷移は HSM によって検証され、workflow.transition イベントが発行されます。ガード付きの遷移では、直近の update の後の状態が参照されます。そのため、ガードが依存する updates: {...} は先に反映してください。

tasks 配列の編集

set updates で使用されるドットパスパーサーが認識する配列ブラケットは、数値のみです（tasks[0]、tasks[1]、…）。tasks[id=T-001] のようなキー付き形式はサポートされておらず、明確なメッセージとともに INVALID_INPUT エラーがスローされます。以前のバージョンではエラーにならず、実際のタスクは変更されないまま、存在しないトップレベルキーに書き込まれて success: true が返されていました。次の3つの方法がサポートされています。

1. 配列全体を置き換える（計画全体を改訂する場合に使用します）:

   exarchos_workflow({
     action: "update",
     featureId: "<id>",
     updates: { tasks: [
       { id: "T-001", title: "...", status: "pending" },
       { id: "T-002", title: "...", status: "pending" },
     ]},
   })
   

2. 配列インデックスを指定して1つのタスクを編集する:

   exarchos_workflow({
     action: "update",
     featureId: "<id>",
     updates: { "tasks[0].status": "in_progress", "tasks[0].startedAt": "<ts>" },
   })
   

   まず tasks を読み込み（action: "get", query: "tasks"）、編集したいタスクのインデックスを確認してから、そのインデックスを指定して設定します。この方法でステータスを "complete" に設定しないでください。タスクを完了状態にできるのは task_complete と settle のみです。

3. 次に空いているインデックスに書き込み、新しいタスクを追加する。配列の現在の長さが N の場合は、tasks[N] に書き込みます。

   // Suppose tasks already contains T-001 and T-002 (length 2). To append:
   exarchos_workflow({
     action: "update",
     featureId: "<id>",
     updates: { "tasks[2]": { id: "T-003", title: "Follow-up", status: "pending" } },
   })
   

   パーサーでは、現在の長さを1つ超える位置への書き込みが許可されます（MAX_ARRAY_GAP = 1）。それより先（長さ2の配列に対する tasks[5] など）への書き込みは INVALID_INPUT をスローします。追加する前に、現在の tasks の長さを読み込んでください。

統合ポイント

状態を更新するタイミング

イベント	状態の更新
ideate の開始	ワークフローを init する（初期フェーズは plan）
設計と根拠を作成	update: { "artifacts.spec": "<path>" }（遷移なし — 初期フェーズは plan）
分解を追加	update: { "artifacts.plan": "<path>", "tasks": [...] } を実行し、その後 transition target: "plan-review"
計画レビューで不足が見つかった	update: { "planReview.gaps": [...] } を実行し、計画に自動的に戻る
計画レビューが承認された	update: { "planReview.approved": true } を実行し、その後 transition target: "delegate"
タスクをディスパッチ	タスクの status = "in_progress"、startedAt を設定
タスク完了	更新なし: task_complete または settle がタスクを完了状態にする
ワークツリーを作成	worktrees オブジェクトに追加
レビュー完了	reviews オブジェクトを更新
PR を作成	artifacts.pr、synthesis.prUrl を設定
PR フィードバック	synthesis.prFeedback に追加

Oneshot 固有の状態更新

Oneshot は、圧縮されたライフサイクルとオプトイン方式の PR パスを備えた、第一級のワークフロータイプです。以下の行は、上記の機能ワークフローの表に対応しています。

フェーズ	状態の更新	発行されるイベント
plan（oneshot）	oneshot.planSummary、artifacts.plan、任意の oneshot.synthesisPolicy	workflow.transition
implementing（oneshot）	tasks[].status、artifacts.tests	task.*、任意の synthesize.requested（request_synthesize 経由）
synthesize（oneshot）	synthesis.prUrl、artifacts.pr	workflow.transition、stack.submitted
completed（oneshot）	—	workflow.transition（completed へ）

implementing → synthesize | completed の分岐は、synthesisOptedIn ガード（synthesisPolicy と synthesize.requested イベント）を読み取る finalize_oneshot によって解決される選択状態です。オプトインの仕組み全体については、@skills/oneshot/SKILL.md を参照してください。

自動状態更新

スキルは、重要なタイミングで状態を更新する必要があります。

ideate/SKILL.md:

After authoring the Design & Rationale section of the unified docs/specs/ artifact:
- `action: "update"` — `updates: { "artifacts.spec": "<path>" }`
  (no transition — `plan` is the initial phase; continue to decomposition in the same phase)

plan/SKILL.md:

After saving plan:
1. `action: "update"` — `updates: { "artifacts.plan": "<path>", "tasks": [...] }`
2. `action: "transition"` — `target: "plan-review"`

delegate/SKILL.md:

On task dispatch:
- Update task status to "in_progress"
- Add worktree to state if created

On task complete:
- Call task_complete after the gates of the task pass (it marks the task complete)
- Check if all tasks done, suggest checkpoint

状態スキーマ

完全なスキーマについては、docs/schemas/workflow-state.schema.json を参照してください。

主なセクション：

• version：スキーマのバージョン（現在は "1.1"）
• featureId：一意のワークフロー識別子
• workflowType：必須。 "feature"、"debug"、"refactor"、"oneshot" のいずれか
• phase：現在のワークフローフェーズ
• artifacts：設計、計画、PR へのパス
• tasks：ステータス付きのタスクリスト
• worktrees：アクティブな git worktree
• planReview：計画レビューの差分分析結果（gaps、approved）
• reviews：レビュー結果
• synthesis：マージ／PR の状態

予約済みフィールド

action: "update" を指定した exarchos:exarchos_workflow は、RESERVED_FIELD により、次の 2 種類のパスを拒否します。

1. トップレベルの不変キー — phase、workflowType、featureId、createdAt、version。初期化時に一度設定され、それ以降は直接変更できません。
2. アンダースコアで始まるパス — トップレベルキー、または各セグメントのいずれかが _ で始まるドットパス（例：_version、_checkpoint.summary、_eventHints）。これらはプロジェクションまたはイベントストアのメタデータです。

代替の書き込み方法：

• phase → action: "transition" と target: "<phase>" を指定した exarchos:exarchos_workflow。遷移は HSM によって検証され、遷移イベントを発行します。
• アンダースコアで始まるパス → action: "append" を指定した exarchos:exarchos_event で型付きイベントを発行します（例：checkpoint、state.patched）。プロジェクションは、次回の読み取り時にイベントをフィールドへ反映します。
• workflowType、featureId、createdAt、version → 移行できません。別のワークフロータイプが必要な場合は、新しいワークフローを初期化してください。

RESERVED_FIELD エラーエンベロープには、型付きの data ブロックが含まれるようになりました。

{
  "success": false,
  "error": {
    "code": "RESERVED_FIELD",
    "message": "Cannot update reserved field: phase",
    "data": {
      "rejectedPath": "phase",
      "rule": "`phase` is top-level immutable — set once at init, never directly mutated thereafter.",
      "alternateWritePath": "Use `exarchos:exarchos_workflow` with `action: \"transition\"` and `target: \"<phase>\"` — phase changes are HSM-validated and emit transition events."
    }
  }
}

アンダースコアで始まるパスに対する正規表現の包括的なパターンも含め、記述全体を読むには、action: "describe" と actions: ["update"] を指定して exarchos:exarchos_workflow を呼び出してください。返される reservedFields ブロックが唯一の信頼できる情報源です。

構造化された引き継ぎ出力

引き継ぎ（checkpoint コマンドのインターフェース）を記録するときは、この構造化された要約を出力し、コンテキストがクリアされた後に再開するエージェントが、作業時と同じ前提を確認できるようにしてください。### House Rules ブロックは、正確性を示すシグナルの対称性を保つため、rehydrate の出力（@skills/rehydrate/SKILL.md を参照）に対応しています。つまり、チェックポイントを作成するエージェントは、再水和を行うエージェントと同じハウスルールを確認できます。

## Checkpoint Saved

**Feature:** <feature-id>
**Phase:** <current-phase>
### Progress
- Tasks: X/Y complete
- Current: <what's in progress>
- Next: <suggested next action>

### House Rules (apply every action this turn forward)
**Skill:** <phasePlaybook.skillRef or "(no playbook for this phase)">
**Tools:** <phasePlaybook.tools rendered as bullets>
**Required model-emitted events:** <phasePlaybook.events rendered as bullets — e.g. `task.progressed`, `phase.advanced`>
**Auto-emitted events (runtime fires these):** <phasePlaybook.autoEmittedEvents rendered as bullets>
**Transition:** <phasePlaybook.transitionCriteria> | Guard: <phasePlaybook.guardPrerequisites>
**Validation scripts:** <phasePlaybook.validationScripts joined>

### Event Emission Hints
<_eventHints.missing rendered as bullets, or "(none — phase machinery satisfied)">

### Resume Instructions

To continue this workflow in a new session, run `rehydrate` — or start the harness fresh, and the SessionStart hook will auto-discover active workflows.

> **Discipline reminder:** every task transition this turn forward MUST land on the workflow event stream via `exarchos_event.append` or `delegate` subagent emission. Direct `Edit` / `Bash` / `git` actions on task branches without corresponding events will desync the workflow tracker (see RCA `docs/rca/2026-05-08-rehydrate-behavioral-gap.md`).

自動チェックポイントのトリガー

次の場合に、チェックポイントを提案してください。

1. delegate の完了後 — すべてのタスクが完了し、レビューを開始する前
2. PR の作成後 — synthesize 内で、フィードバックループを開始する前
3. フィードバックの反復が 3 回以上になった後 — コンテキスト蓄積のリスクがあるため
4. ユーザーがコンテキストの問題に言及したとき — 先回りして保存するため

ベストプラクティス

1. 頻繁に更新する - 状態は常に実情を反映している必要があります
2. MCP ツールを使用する - 手動で JSON を編集するより、checkpoint MCP ツールを優先してください
3. 再開時に整合性を確認する - 状態が git の状態と一致していることを必ず確認してください（@skills/rehydrate/SKILL.md を参照）
4. 区切りのタイミングでチェックポイントを作成する - コンテキストの枯渇が予想される前に状態を保存してください
5. 記憶に頼らず、状態を読み取る - 要約の後は、状態から情報を読み取ってください（@skills/rehydrate/SKILL.md を参照）

トラブルシューティング

MCP ツール呼び出しの失敗

Exarchos MCP ツールがエラーを返した場合：

1. エラーメッセージを確認してください。通常、具体的な対処方法が記載されています
2. ワークフローの状態が存在することを確認してください。action: "get" と featureId を指定して exarchos:exarchos_workflow を呼び出します
3. 「version mismatch」の場合：別のプロセスが状態を更新しています。操作を再試行してください
4. 状態が破損している場合：action: "cancel" と dryRun: true を指定して exarchos:exarchos_workflow を呼び出します

チェックポイントが見つからない

アクティブなワークフローがない状態で checkpoint が呼び出された場合：

1. まず検出します。action: "list" を指定して exarchos:exarchos_workflow を呼び出し、アクティブなワークフローを列挙します。一覧が空の場合、checkpoint コマンドの「アクティブなワークフローがありません」という報告は正しいため、そのまま終了してください
2. list が候補を返した場合は確認します。その featureId を指定して action: "get" を指定し、exarchos:exarchos_workflow を呼び出します
3. ワークフローが存在するのにチェックポイントの作成に失敗する場合：イベントストアのディスク容量とアクセス権限を確認してください

ワークフローの例

1. 新しいワークフローを開始する：featureId: "user-authentication"、workflowType: "feature" を指定して、action: "init" で exarchos:exarchos_workflow を使用します

2. Design & Rationale セクションの作成後（plan はすでに初期フェーズです。遷移は不要です）：

   • action: "update"、featureId: "user-authentication"、updates: { "artifacts.spec": "docs/specs/2026-01-05-user-auth.md" }

3. 中断前に進捗を保存する：checkpoint を使用して構造化された引き継ぎ情報を記録し、後で rehydrate を使用して再開します（@skills/rehydrate/SKILL.md を参照）。