long-run

長時間実行ハーネス

マイルストーンパイプラインを通じて、複雑なタスクを数日間にわたって実行します。各マイルストーンは、plan-crafting → run-plan → review-work の順に進みます。マイルストーン間にチェックポイントを設け、中断から復旧できるようにします。

基本原則

長時間実行は、再開可能で、監査可能で、フェイルセーフでなければなりません。 各状態遷移は、次のアクションを開始する前にディスクへ保存します。実行が理由を問わず停止した場合（レート制限、クラッシュ、ユーザーによる一時停止、コンテキストの消失など）でも、完了済みの作業を繰り返すことなく、最後のチェックポイントから再開できます。

厳格なゲート

1. 実行を始める前に、マイルストーンが存在していなければなりません。 milestone-planning スキルから作成するか、ユーザーが提供したものを使用します。実行中にマイルストーンをその場で生成してはなりません。
2. 各マイルストーンの前後に、状態ファイルを更新しなければなりません。 メモリ内だけの状態は認められません。ディスクに保存されていなければ、実行されていないものとして扱います。
3. 各マイルストーンで、パイプライン全体を完了しなければなりません。 plan-crafting → run-plan → review-work の順に進みます。近道は禁止です。「問題なさそうだから」という理由で review-work を省略してはなりません。
4. 失敗したマイルストーンが、依存するマイルストーンをブロックします。 M2 が M1 に依存していて、M1 が review で失敗した場合、M2 は開始しません。例外はありません。
5. デフォルトでは自律的に進め、マイルストーン間に承認ゲートを設けません。 ユーザーが承認するのは、milestone-planning の確定時に一度だけです。それ以降は、確認のために一時停止せず、マイルストーンを plan → run → review → checkpoint の順に進めます。一時停止して確認を求めるのは、次の場合に限ります。マイルストーンの再試行回数の上限に達した場合（failed）、実行中の修正でスコープに関する判断が必要な場合、統合時のエスカレーションが発生した場合、または読み込んだ状態に一貫性がない場合です。各フェーズの遷移時に簡潔な状況報告を投稿し、ユーザーがいつでも中断できるようにします。状態ファイルにより、一時停止からいつでも再開できます。
6. 完了したマイルストーンは変更してはなりません。 マイルストーンが review-work に合格した時点で、そのファイルはロックされます。後続のマイルストーンで以前の作業に変更が必要になった場合は、新しいマイルストーンとして扱います。
7. 各マイルストーンの完了後にチェックポイントを作成します。 次に進む前に、実施内容、テスト結果、レビュー判定を記録したチェックポイントファイルを書き込みます。

使用するタイミング

• milestone-planning がマイルストーン DAG を作成した後
• ユーザーが「long run」「start long run」「execute milestones」または「run all milestones」と指示した場合
• 以前に一時停止した長時間実行セッションを再開する場合

使用しないタイミング

• マイルストーンがまだ存在しない場合（まず milestone-planning を使用）
• マイルストーンが1つだけの場合（plan-crafting と run-plan を直接使用）
• 複数フェーズでの実行を必要としない簡単なタスクの場合

入力

1. ハーネスの状態ディレクトリのパス — 例：docs/engineering-discipline/harness/<session-slug>/
2. ディレクトリ内に state.md と milestones/*.md ファイルが存在すること

状態ディレクトリが存在しない場合は、まず milestone-planning を実行するか、ユーザーに確認します。

プロセス

フェーズ 1：状態の読み込みと検証

1. ハーネスディレクトリから state.md を読み込みます
2. milestones/ からすべてのマイルストーンファイルを読み込みます
3. 以下を検証します。
   • state.md で参照されているすべてのマイルストーンに、対応するファイルがあること
   • 依存関係 DAG が有効であること（循環がなく、トポロジカルソートが可能であること）
   • 無効な状態のマイルストーンがないこと（例：プランファイルがないのに「executing」になっている）
4. 現在の状況を判断します。
   • 完了したマイルストーンはどれか
   • 開始可能なマイルストーンはどれか（すべての依存関係が満たされているもの）
   • 新規開始か再開か
5. 状況をユーザーに提示します。

## Long Run Status: [Session Name]

**Progress:** N/M milestones completed
**Current phase:** [planning M3 | executing M3 | reviewing M3 | ready to start M3]
**Next up:** [M3, M4 (parallel)]

Completed: M1 ✓, M2 ✓
In progress: M3 (executing)
Pending: M4, M5

6. 読み込んだ状態に一貫性があれば、すぐに処理を続行します。状況表示は報告であり、ゲートではありません。ユーザーに確認するのは、手順3の検証で矛盾が見つかった場合、または failed のマイルストーンが後続の進行をブロックしている場合だけです。

フェーズ 2：マイルストーン実行ループ

各マイルストーンをトポロジカル順に処理します。

┌─────────────────────────────────────┐
│         Milestone Pipeline          │
│                                     │
│  ┌──────────┐    ┌─────────┐        │
│  │  Plan    │───→│  Run    │        │
│  │ Crafting │    │  Plan   │        │
│  └──────────┘    └────┬────┘        │
│                       │             │
│                  ┌────▼────┐        │
│                  │ Review  │        │
│                  │  Work   │        │
│                  └────┬────┘        │
│                       │             │
│              ┌────────▼────────┐    │
│              │   PASS?         │    │
│              │  Yes → checkpoint│    │
│              │  No  → retry    │    │
│              └─────────────────┘    │
└─────────────────────────────────────┘

手順 2-1：ゲートチェック

マイルストーンを開始する前に、次を行います。

1. すべての依存マイルストーンのステータスが completed であることを確認します
2. 進行中の並列マイルストーンとファイルの競合がないことを確認します
3. state.md を更新し、マイルストーンのステータスを planning に設定します
4. 実行ログにタイムスタンプを追加します

ステップ 2-2：計画作成フェーズ

1. マイルストーンの定義からコンテキストブリーフを作成します。
   • 目標 → マイルストーンファイルから取得
   • スコープ → マイルストーンファイルから影響を受けるファイルを取得
   • 成功基準 → マイルストーンファイルから取得
   • 制約 → 親の問題と完了済みマイルストーンのコンテキストを引き継ぐ
   • 完了済みマイルストーンのコンテキストに関する契約： 完了済みの各前提マイルストーンから含めるのは、次のもののみです。
     • 作成／変更したファイル（チェックポイントの「Files Changed」リストから取得）
     • 確立されたインターフェース契約（関数シグネチャ、API の形式、型定義）
     • 達成済みと検証された成功基準
   • 含めてはいけないもの：実行ログ、レビュー文書、ワーカー／バリデーターの出力、チェックポイントの全内容
   • 注： マイルストーンの定義から作成するコンテキストブリーフでは、複雑度評価のセクションは省略します。ルーティングはマイルストーン計画フェーズですでに決定済みだからです。ブリーフはルーティングをやり直さず、直接計画作成に進みます。
2. plan-crafting スキルパターンを呼び出します。
   • docs/engineering-discipline/plans/YYYY-MM-DD-<milestone-name>.md に計画文書を作成します。
   • 計画はすべてのマイルストーンの成功基準を満たす必要があります。
   • 計画によって、マイルストーンのスコープ外のファイルを変更してはいけません。
3. state.md を更新し、このマイルストーンの計画ファイルのパスを記録します。
4. 承認を求めず、報告する： 目標、タスク数、変更するファイルを含む簡潔な計画の概要を進捗報告として投稿し、そのまま実行に進みます。承認を待ってはいけません。

ステップ 2-3：計画実行フェーズ

1. state.md を更新し、マイルストーンのステータスを executing に設定して、Attempts カウンターを 1 増やします。
2. run-plan スキルパターンを使用して計画を実行します。
   • 各タスクでワーカーとバリデーターのループを実施
   • 独立したタスクは並行して実行
   • 情報を隔離したバリデーターを使用
3. いずれかのタスクで、3 回の再試行後に run-plan が失敗を報告した場合：
   • state.md を更新し、マイルストーンのステータスを failed に設定
   • 失敗の詳細を実行ログに記録
   • 停止してユーザーに報告します。 依存するマイルストーンには進みません。
4. すべてのタスクが完了した場合は、レビューのフェーズに進みます。

ステップ 2-4：作業レビューのフェーズ

1. state.md を更新し、マイルストーンのステータスを validating に設定します。
2. review-work スキルパターンを呼び出します。
   • 計画文書に照らして、情報を隔離したレビューを実施
   • PASS／FAIL の二択で判定
3. PASS の場合：
   • state.md を更新し、マイルストーンのステータスを completed に設定
   • チェックポイントファイルを作成（以下の「チェックポイント形式」を参照）
   • 実行ログを更新
   • 次のマイルストーンに進む
4. FAIL の場合：
   • レビューの指摘事項を実行ログに記録
   • 再試行の判断（クラッシュ後も保持される state.md の Attempts カウンターに基づく）：
     • Attempts == 1 の場合：レビューのフィードバックを添えてステップ 2-3 に戻る（同じ計画を再実行）
     • Attempts == 2 の場合：レビューのフィードバックを制約として再計画するため、ステップ 2-2 に戻る
     • Attempts >= 3 の場合：ステータスを failed に設定し、停止してユーザーに報告

ステップ 2-5：マイルストーン間の統合チェック

マイルストーンが review-work に合格した後、チェックポイントを作成する前に、そのマイルストーンの成果物が、それまでに完了したすべてのマイルストーンと正しく統合されていることを確認します。

1. プロジェクトで最も高いレベルの検証を実行する（state.md の Verification Strategy を参照するか、plan-crafting の Verification Discovery の順序に従って再検出します）
2. マイルストーン間のインターフェースを確認する： 完了したマイルストーンが、前提となるマイルストーンのインターフェースを定義または利用している場合、それらに互換性があることを検証します（関数シグネチャが一致し、API コントラクトが保たれ、型が整合していること）

統合チェックに合格した場合： チェックポイントに進みます。

統合チェックに失敗した場合 — マイルストーン間の失敗への対応：

マイルストーンは独自の review-work（内部的な正しさ）には合格しましたが、他のマイルストーンとの統合に問題が発生しています。これは境界の問題です。

1. 診断（1 回目）：

   • 失敗出力を読む
   • どのインターフェース境界または連携に問題があるかを特定する
   • 修正が現在のマイルストーンに含まれるか、修正用マイルストーンが必要かを判断する
   • 現在のマイルストーンのスコープ内で修正可能な場合：対象を絞った修正ワーカーをディスパッチする → review-work を再実行する → 統合チェックを再実行する
   • 修正が現在のマイルストーンのスコープ外の場合：エスカレーションに進む

2. 診断（2 回目）：

   • 1 回目の修正で解決しなかった場合、再分析する
   • 2 回目の対象を絞った修正を適用する
   • 統合チェックを再実行する

3. ユーザーにエスカレーション（2 回失敗した後）：

   • 関係するマイルストーン、失敗した統合境界、試した修正を報告する
   • 選択肢：修正用マイルストーンを追加する、チェックポイントまでロールバックする、問題を認識したうえで続行する
   • ユーザーの判断を state.md の実行ログに記録する

ステップ 2-6：チェックポイント

マイルストーンがレビューに合格した後：

checkpoints/M<N>-checkpoint.md を作成します。

# Checkpoint: M<N> — [Milestone Name]

**Completed:** YYYY-MM-DD HH:MM
**Duration:** [time from planning start to review pass]
**Attempts:** [number of plan-execute-review cycles]

## Plan File
`docs/engineering-discipline/plans/YYYY-MM-DD-<name>.md`

## Review File
`docs/engineering-discipline/reviews/YYYY-MM-DD-<name>-review.md`

## Test Results
[Full test suite status at checkpoint time]

## Files Changed
[List of files created/modified in this milestone]

## State After Milestone
[Brief description of system state — what works now that didn't before]

フェーズ 3：マイルストーンの並列実行

複数のマイルストーンがすべての依存関係を満たし、ファイルの競合がない場合：

1. 並列化可能なマイルストーングループを特定する
2. すべての並列マイルストーンに対して、最初に plan-crafting を実行する（計画は軽量なため、順次実行します）
3. すべての計画の要約を 1 件の進捗報告として投稿し（承認待ちは行わず）、各マイルストーンのパイプラインを同時にディスパッチする：
   • 各マイルストーンで run-plan → review-work を実行する
   • ファイルの競合を防ぐため、それぞれをワークツリー（isolation: "worktree"）で実行する
   • 両方が完了し、レビューに合格したら、ワークツリーをマージする
4. いずれかが失敗した場合：個別に対応する（依存関係がなければ、もう一方は続行できます）

ワークツリーのマージ手順：

1. 両方のマイルストーンが、それぞれのワークツリーでレビューに合格する
2. ワークツリー間で変更にファイル競合がないか確認する
3. 競合がない場合：順次マージする（先に M_lower、次に M_higher）
4. 競合が検出された場合：停止し、ユーザーに報告して手動での解決を依頼する
5. マージ後：マージ済みの結果に対して、テストスイート全体を実行する
6. テストに失敗した場合：停止し、ユーザーに報告する

フェーズ 4：完了

すべてのマイルストーン（milestone-planning の統合検証マイルストーンを含む）が完了した後：

1. state.md を更新する：全体のステータスを completing に設定する
2. 最終 E2E ゲート： 完全に統合されたコードベースに対して、プロジェクトで最も高いレベルの検証を最後にもう一度実行する
3. 回帰チェックのためにテストスイート全体を実行する
4. 最終 E2E ゲートに失敗した場合：
   • 診断する：原因である可能性が高いマイルストーンの成果物を特定する
   • 実行中の修正手順を用いて修正用マイルストーンを作成する
   • 完全なパイプライン（plan-crafting → run-plan → review-work）を通じて、修正用マイルストーンを実行する
   • 修正後に E2E ゲートを再実行する
   • 修正を 2 回試みても失敗した場合：詳細な診断結果を添えてユーザーにエスカレーションする
5. 最終 E2E ゲートに合格した場合： state.md を更新する：全体のステータスを completed に設定する
6. 完了の要約を作成する：

# Long Run Complete: [Session Name]

**Started:** YYYY-MM-DD
**Completed:** YYYY-MM-DD
**Total milestones:** N
**Total attempts:** [sum of all milestone attempts]

## Milestone Summary

| Milestone | Status | Attempts | Duration |
|-----------|--------|----------|----------|
| M1: [name] | ✓ completed | 1 | 2h |
| M2: [name] | ✓ completed | 2 | 4h |
| ...

## Final Test Suite
[PASS/FAIL — N passed, M failed]

## Files Changed (Total)
[Aggregated list across all milestones]

4. ユーザーに提示し、最後のコード品質チェックとして simplify を提案する

復旧プロトコル

一時停止または中断されたセッションを再開する場合：

1. state.md を読み、最後に確認された状態を把握します
2. 各マイルストーンについて、復旧アクションを判断します：

最終ステータス	復旧アクション
pending	通常どおり開始
planning	plan-crafting を再開します（計画ファイルが未完成の可能性があります）
executing	run-plan の進捗を確認し、再開するか最初からやり直します
validating	review-work を再開します（レビューが未完了の可能性があります）
completed	スキップします（すでにチェックポイントが作成されています）
failed	失敗をユーザーに提示し、再試行するかスキップするかを尋ねます（以下のスキップルールを参照）
skipped	スキップします（ユーザーが以前このマイルストーンをスキップすることを選択しています）

3. executing 状態のマイルストーンについては、計画内のタスクにチェックボックスが付いているか確認します。最初の未チェックのタスクから再開します。
4. state.md の Attempts カウンターを読み、残りの再試行回数を確認します。再開時にカウンターをリセットしないでください。無限の再試行ループを防ぐため、クラッシュ後もカウンターは維持されます。
5. 復旧計画をステータスレポートとして投稿し、実行を続けます。failed 状態のマイルストーンが進行を妨げる場合、または状態に矛盾がある場合にのみ、ユーザーに確認します。

実行中の修正

実行中に、完了済みマイルストーンの出力が誤っていることが判明した場合、または新しいマイルストーンが必要になった場合：

1. 実行を一時停止します — 依存するマイルストーンを続けて実行しないでください
2. state.md の実行ログに、発見した内容と、その発見につながったマイルストーンを記録します
3. ユーザーの判断が必要です： 状況と選択肢を提示します：
   • 修正マイルストーンを追加する： 新しいマイルストーンの定義を作成します（ユーザーが目標と成功基準を記述するか、新しい範囲のみについて milestone-planning を再実行します）。適切な依存関係を設定して DAG に追加します。新しいマイルストーンから実行を再開します。
   • チェックポイントから再計画する： 完了済みマイルストーンのチェックポイントまでロールバックし、それ以降のマイルストーンを pending に設定して、Attempts を 0 にリセットし、その地点から再開します。
   • 中止する： 全体のステータスを failed に設定して停止します。
4. 新しいマイルストーンにも同じパイプラインを適用します — plan-crafting → run-plan → review-work。「簡単な修正」であっても手順を省略しないでください。
5. 完了済みマイルストーンは変更しません（ハードゲート #6 が引き続き適用されます）。修正マイルストーンでは、完全な計画サイクルを経て新しいファイルを作成するか、ファイル全体を上書きします。

スキップルール

ユーザーが失敗したマイルストーンをスキップすることを選択した場合：

1. state.md でマイルストーンのステータスを skipped に設定します
2. ユーザーの理由とともに、スキップのイベントを実行ログに記録します
3. スキップされたマイルストーンに依存するマイルストーンは、デフォルトでブロックされます — failed の場合と同じです。DAG の契約では、依存先は前提条件が completed になった後にのみ実行されます。
4. ユーザーは、不足している前提条件を了承したうえで、依存するマイルストーンのブロックを明示的に解除できます：「M2 がスキップされた状態で M4 を進めてください。」この例外を実行ログに記録します。
5. ユーザーが依存するマイルストーンのブロックを解除した場合、plan-crafting 中にそのマイルストーンの Context Brief に次の注記を追加します：「前提条件の M2 はスキップされました。以下の出力が不足しています：[M2 の成功基準から抜粋したリスト]」

スキップされたマイルストーンのスキップを取り消すことはできません。 ユーザーが後でそのマイルストーンを試すことを希望する場合は、同じ目標を持つ新しいマイルストーンを作成します。

所要時間のガード

1 つのマイルストーンの合計アクティブ時間（計画開始からレビュー完了まで）が過度に長くなった場合：

1. ソフトリミット： マイルストーンが planning または executing 状態のまま、全体の作業量に比べて著しく長いと思われる期間が経過した場合、一時停止してユーザーに報告します：「マイルストーン M3 は長時間進行中です。このまま続行するか、範囲を見直すか、中止しますか？」
2. 試行回数のハードリミット： 3 回の試行制限（F1）により、再試行ループを制限します。ただし、1 回の試行で plan-crafting が 15 個を超えるタスクを生成した場合も、一時停止して報告します：「このマイルストーンの計画には N 個のタスクがあります。1 つのマイルストーンには大きすぎる可能性があります。分割を検討してください。」
3. 目的： 1 つの制御不能なマイルストーンが実行予算を使い切ったり、不安定なテストを延々と実行したりすることを防ぎます。

コンテキストウィンドウの管理

長時間のセッションでは、コンテキストウィンドウの上限に達します。Claude Code は古いメッセージを自動的に圧縮します（コンテキストの折りたたみ）。ハーネスはこれに耐えられるよう設計する必要があります。

1. 状態の管理に会話の記憶を頼らないでください。 すべての状態は、ディスク上の state.md とマイルストーンファイルに保存します。コンテキストが圧縮された場合、ハーネスは状態ファイルを再読み込みするため、情報は失われません。
2. 各マイルストーンを新たなコンテキストの境界とします。 新しいマイルストーンの計画作成を開始するとき、作業サブエージェントはクリーンなコンテキストで開始します。受け取るのは、マイルストーンの定義と完了済みの前提マイルストーンのコンテキスト（F8 の契約を参照）のみで、会話履歴全体は受け取りません。
3. チェックポイントファイルを信頼できる唯一の情報源とします。 マイルストーンの途中でコンテキストが失われた場合、復旧時には圧縮された会話の要約ではなく、チェックポイントファイルを読み込みます。
4. 大量の状態をインラインで蓄積しないでください。 会話の中で全マイルストーンの要約を更新し続けるのではなく、state.md とチェックポイントファイルをパスで参照してください。

レート制限への対処

長時間のセッションでは、レート制限に遭遇します。Claude Code には指数バックオフによる再試行（最大 10 回、最大バックオフ 5 分）が組み込まれています。ハーネスはこれに逆らわず、連携して動作させてください。

1. 一時的なレート制限は claude-code に処理させてください。 短時間の 429／529 エラーは、バックオフを伴って自動的に再試行されます。API エラーが発生するたびに、先回りして状態を保存しないでください。
2. レート制限が継続する場合は状態を保存してください。 レート制限が自動再試行の時間を超えて続く場合（「rate limit」のメッセージが繰り返し表示されます）は、現在の状態を直ちにディスクに記録してください。
3. 実行ログにタイムスタンプとともにレート制限の発生を記録してください。
4. ユーザーに次のように報告してください。「レート制限に達しました。状態を保存しました。準備ができたら long-run で再開してください。」
5. claude-code に組み込まれている再試行に、手動の再試行ループを重ねて追加しないでください。再試行が増幅されます。
6. バックグラウンドエージェントの中断： Claude Code のバックグラウンドエージェント（critic サブエージェントなど）は、529 の過負荷エラーが発生すると、再試行せずにすぐ中断します。そのため、milestone-planning には critic の失敗処理（再ディスパッチを 1 回行い、最小限のパネルを用意する）が備わっています。critic の失敗は、恒久的なエラーではなく、一時的なレート制限によることがよくあります。

アンチパターン

アンチパターン	失敗する理由
milestone-planning を使わず、インラインでマイルストーンを生成する	マイルストーンに敵対的レビューがなく、分解の質が低くなります
「単純な」マイルストーンだからと review-work を省略する	検出されなかった欠陥がマイルストーンをまたいで積み重なります
マイルストーンが失敗した後も続行する	依存するマイルストーンが、壊れた土台の上に構築されます
フェーズ間で state.md を更新しない	クラッシュすると進捗が失われ、再開できなくなります
完了済みのマイルストーンファイルを変更する	チェックポイントの不変条件が破られ、レビューが無効になります
worktree による分離なしで並行してマイルストーンを実行する	ファイルの競合によって、両方のマイルストーンが破損します
レート制限時に自動再試行する	クォータを浪費します。ユーザーは待つことを選ぶかもしれません
マイルストーン間の承認待ちで一時停止する	自律実行の目的に反します。ユーザーはマイルストーンの確定時に一括実行を選択しています。エスカレーションは、失敗とスコープ変更の場合に限ってください
競合を確認せずに worktree をマージする	ファイルが重複している場合、気付かないままデータが失われます
マイルストーン間の統合チェックを省略する	マイルストーン単体では成功しても、境界で互いに不具合を引き起こします
ユーザーへのエスカレーションなしに E2E の失敗を際限なく再試行する	誤診された問題に予算を浪費しないよう、試行回数を 2 回に制限しています

最小チェックリスト

• 状態ディレクトリが存在し、有効な state.md とマイルストーンファイルがある
• 依存関係の DAG が検証されている（循環なし）
• 現在の位置が特定されている（新規開始または再開）
• セッション開始時と各フェーズの移行時にステータスレポートを投稿している
• 各マイルストーンで、plan-crafting → run-plan → review-work を実施している
• 各フェーズの移行前後に State.md を更新している
• マイルストーンが成功するたびにチェックポイントを作成している
• 失敗したマイルストーンが依存先をブロックしている
• 並列のマイルストーンで worktree による分離を使用している
• 各マイルストーンの後に、マイルストーン間の統合チェックに合格している
• 完了時に最終 E2E ゲートに合格している
• 完了時にテストスイート全体に合格している

移行

長時間の実行が完了した後：

• 最終的なコード品質チェックを行う場合 → simplify スキル
• 完了時のテストで問題が見つかった場合 → systematic-debugging スキル
• ユーザーがマイルストーンを追加して拡張したい場合 → milestone-planning スキル

このスキル自体は、次のスキルを呼び出しません。完了を報告し、次のステップはユーザーに委ねます。