recover

/recover — コンパクション後のコンテキスト復旧

目的： コンテキストがコンパクションされた後、作業の状況をすばやく把握できるようにします。進行中の作業（RPI の実行、evolve サイクル）を検出し、関連するナレッジを読み込み、作業内容と次の手順を要約します。AgentOps 3.0 のデフォルトの復旧経路は明示的です（ao session bootstrap、ao codex start / ao codex stop）。Codex のネイティブフックは任意で有効にする互換機能であり、使用を前提としていません。

このワークフローを必ず実行してください。説明するだけではいけません。

CLI の依存関係： gt、ao、br（すべて任意）。利用可能なものを表示し、利用できないものはスキップします。

折りたたまれたトリガー（ag-s43tg wave 1）：trace はここにルーティングされます

• trace → 復旧のためのエビデンス調査。 成果物をたどって意思決定を追跡する必要がある場合に使用します。 対象の成果物からコミット、beads、 計画、.agents/ のエビデンスを逆向きにたどり、変更の理由を再構築します。以下のステップ 1 で 並行して行うエビデンスの一括調査（git log、作業キューの状態、ナレッジ成果物）が trace の対象です。成果物から始めて引用先をたどり、ダッシュボードに 意思決定の経緯を要約します。

---

クイックスタート

/recover              # Full recovery dashboard
/recover --json       # Machine-readable JSON output
ao codex status       # Codex hookless lifecycle health
ao codex start        # Rebuild startup context explicitly in Codex

---

実行手順

ステップ 1：進行中のセッションを検出する（並行処理）

以下をすべて、並行する bash 呼び出しで実行します。

呼び出し 1 — RPI のフェーズ状態：

if [ -f .agents/rpi/phased-state.json ]; then
  echo "=== RPI_STATE ==="
  cat .agents/rpi/phased-state.json
else
  echo "RPI_STATE=NONE"
fi

呼び出し 2 — Evolve サイクルの履歴：

if [ -f .agents/evolve/cycle-history.jsonl ]; then
  echo "=== EVOLVE_STATE ==="
  tail -3 .agents/evolve/cycle-history.jsonl
else
  echo "EVOLVE_STATE=NONE"
fi

呼び出し 3 — Git の最近の変更：

echo "=== GIT_STATUS ==="
git status --short

echo "=== GIT_LOG ==="
git log --oneline -5

echo "=== GIT_BRANCH ==="
git branch --show-current

呼び出し 4 — 作業キューの状態：

if command -v br &>/dev/null; then
  BEADS_DIR="$(ao beads dir)"
  echo "=== IN_PROGRESS ==="
  BEADS_DIR="$BEADS_DIR" br list --status in_progress 2>/dev/null | head -3
  echo "=== READY ==="
  BEADS_DIR="$BEADS_DIR" br ready 2>/dev/null | head -3
else
  echo "BR_UNAVAILABLE"
fi

呼び出し 5 — ナレッジとメッセージ：

# Knowledge artifacts
echo "=== KNOWLEDGE_COUNT ==="
echo "Learnings=$(ls .agents/learnings/ 2>/dev/null | wc -l | tr -d ' ')"
echo "Patterns=$(ls .agents/patterns/ 2>/dev/null | wc -l | tr -d ' ')"

# Inbox if gt available
if command -v gt &>/dev/null; then
  echo "=== MESSAGES ==="
  gt mail inbox 2>/dev/null | head -3
else
  echo "GT_UNAVAILABLE"
fi

呼び出し 6 — Codex のライフサイクル（利用可能な場合）：

if command -v ao &>/dev/null; then
  echo "=== CODEX_STATUS ==="
  ao codex status --json 2>/dev/null || echo "CODEX_STATUS=UNAVAILABLE"
else
  echo "AO_UNAVAILABLE"
fi

ステップ 2：ナレッジベースからコンテキストを読み込む

RPI の状態が検出された場合は、以下を実行します。

if command -v ao &>/dev/null; then
  ao lookup --query "rpi recovery context" --limit 5 2>/dev/null || true
fi

取得したナレッジを適用する： 学習内容が返された場合は、それぞれが復旧時のコンテキストに適用できるか確認します。適用できる学習内容はファイル名を引用し、次を記録します：ao metrics cite "<path>" --type applied 2>/dev/null || true

Codex のフックなしフォールバックモード（v0.115.0 より前で、ネイティブフックがない状態）が検出された場合は、以下も実行します。

if command -v ao &>/dev/null && { [ -n "${CODEX_THREAD_ID:-}" ] || [ "${CODEX_INTERNAL_ORIGINATOR_OVERRIDE:-}" = "Codex Desktop" ]; }; then
  ao codex start --no-maintenance 2>/dev/null || true
fi

ステップ 3：セッション状態を解析して要約する

収集したデータから以下を抽出します。

1. RPI の検出： .agents/rpi/phased-state.json が存在する場合：

   • goal、epic_id、phase、cycle、started_at を抽出する
   • フェーズ番号をフェーズ名に対応づける（1=research、2=plan、3=implement、4=validate）
   • started_at からの経過時間を表示する

2. Evolve の検出： .agents/evolve/cycle-history.jsonl が存在する場合：

   • 最新サイクルの最後のエントリを読み取る
   • goals_fixed、result、timestamp を抽出する
   • 最新サイクルの概要を表示する

3. 最近の作業： git log から：

   • 直近 3 件のコミット（呼び出し 3 で抽出済み）
   • 未コミットの変更数

4. 保留中の作業： beads から：

   • 進行中のイシュー（最大 3 件）
   • 着手可能なイシューの件数

5. ナレッジの状態：

   • 利用可能な学習内容とパターンの合計数
   • gt が利用可能な場合は未読メッセージ数

ステップ 4：復旧ダッシュボードを表示する

収集したデータを次の形式にまとめます。

══════════════════════════════════════════════════════════════
  Context Recovery Dashboard
══════════════════════════════════════════════════════════════

IN-PROGRESS RPI RUN
  Epic: <epic_id>
  Goal: <first 80 chars of goal>
  Phase: <phase name: research | plan | implement | validate>
  Cycle: <cycle #>
  Started: <time ago (e.g., "2 hours ago")>
  Status: <PHASE_START | IN_PROGRESS | READY_FOR_GATE | ...>

  ─ Next Step: <state-aware suggestion from Step 5>

OR

RECENT EVOLVE CYCLE (IF NO RPI)
  Cycle: <cycle #>
  Latest Goal: <goal_id or summary>
  Result: <result>
  Items Completed: <count or "—">
  Timestamp: <time ago>

  ─ Next Step: <state-aware suggestion from Step 5>

OR

[NO ACTIVE SESSION]
  No RPI run or evolve cycle in progress.
  Last activity: <time of last commit or "unknown">

IN-PROGRESS WORK
  <list up to 3 in-progress issues with IDs>
  <or "No in-progress work">

READY TO WORK
  <count of ready issues>
  <or "No ready issues">

RECENT COMMITS
  <last 3 commits>

PENDING CHANGES
  <uncommitted file count or "clean">

KNOWLEDGE AVAILABLE
  Learnings: <count>  Patterns: <count>

INBOX
  <message count or "No messages" or "gt not installed">

──────────────────────────────────────────────────────────────
SUGGESTED NEXT ACTION
  <state-aware command from Step 5>
──────────────────────────────────────────────────────────────

QUICK COMMANDS
  /status       Current workflow dashboard
  /research     Deep codebase exploration
  /plan         Decompose work into issues
  /implement    Execute a single issue
  /crank        Autonomous epic execution
  /validate   Full close-out and learnings
══════════════════════════════════════════════════════════════

ステップ 5：次のアクションを提案する（状態に応じて判断）

コンテキストを上から順に評価し、最初に一致した条件を使用します。

優先度	条件	提案
1	RPI の実行が進行中 + phase=research	「調査を続ける：/research、準備ができていれば /plan」
2	RPI の実行が進行中 + phase=plan	「計画を確認する：コーディング前の検証に /pre-mortem」
3	RPI の実行が進行中 + phase=implement	「実装を再開する：/implement <next-issue-id>」
4	RPI の実行が進行中 + phase=validate	「サイクルを完了する：学習内容を抽出して締めくくるために /validate」
5	Evolve サイクルが進行中	「自律的な改善を続ける：/evolve --resume」
6	進行中のイシューがある	「作業を続ける：/implement <issue-id>」
8	着手可能なイシューがある	「次のイシューを選ぶ：/implement <first-ready-id>」
9	未コミットの変更がある	「最近の作業を確認する：/validate」
10	状態がクリーンで、保留中の作業がない	「セッションを復旧しました。次の作業を計画するには /status から始めてください」

ステップ 6：JSON 出力（--json フラグ）

ユーザーが --json を指定した場合、すべての復旧データを構造化 JSON として出力します。

{
  "session_type": "rpi|evolve|none",
  "rpi": {
    "epic_id": "ag-l2pu",
    "goal": "Implement...",
    "phase": 2,
    "phase_name": "plan",
    "cycle": 1,
    "started_at": "2026-02-15T14:33:36-05:00",
    "elapsed_minutes": 120
  },
  "evolve": {
    "cycle": 3,
    "result": "improved",
    "goals_fixed": ["goal1", "goal2"],
    "timestamp": "2026-02-15T22:00:00-05:00"
  },
  "work_state": {
    "in_progress_count": 3,
    "in_progress_issues": ["ag-042.1", "ag-042.2"],
    "ready_count": 5,
    "uncommitted_changes": 2
  },
  "git": {
    "branch": "main",
    "recent_commits": [
      "7de51c8 feat: wave 2 — structural assertions",
      "25004f8 fix: replace per-wave vibe gate"
    ]
  },
  "knowledge": {
    "learnings_count": 12,
    "patterns_count": 5
  },
  "inbox": {
    "unread_count": 0
  },
  "suggestion": {
    "priority": 4,
    "message": "Resume implementation: /implement ag-042.1"
  }
}

これを単一のコードブロックで表示します。--json が有効な場合、ビジュアルダッシュボードは表示しません。

---

例

RPI の途中でコンパクションが発生した後の復旧

ユーザーの入力： /recover

処理内容：

1. エージェントが 5 件の並列 bash 呼び出しを実行して状態を収集します
2. エージェントが phased-state.json から RPI の実行を検出します（phase=2、epic ag-l2pu）
3. エージェントが ao lookup --query "rpi recovery context" を実行して関連するナレッジを読み込みます
4. エージェントがゴール、現在のフェーズ（plan）、サイクル 1、開始から 2 時間経過したことを表示します
5. エージェントが進行中のイシュー 2 件と、対応可能なイシュー 3 件を一覧表示します
6. エージェントがクリーンな Git 状態と最近のコミットを表示します
7. エージェントが次のように提案します：「プランをレビューします：コーディング前に検証するには /pre-mortem を実行してください」

結果： ダッシュボードで進行中の RPI セッションを確認し、コンテキストを読み込み、次のステップを提案します。

Evolve サイクル中にコンパクションが発生した後の復旧

ユーザーの入力： /recover

処理内容：

1. エージェントが並列で状態を収集します
2. エージェントが RPI の実行がないことを確認します
3. エージェントが Evolve サイクルを検出します（最新：サイクル 3、結果「改善済み」、goals_fixed=["goal1", "goal2"]）
4. エージェントがタイムスタンプ（1 時間前）と items_completed（8）を表示します
5. エージェントが ao lookup --query "evolve cycle recovery" を使用してナレッジを読み込みます
6. エージェントが次のように提案します：「自律的な改善を続けます：/evolve --resume」

結果： ダッシュボードで Evolve サイクルを確認し、進捗を表示して、再開コマンドを提示します。

クリーンな状態（アクティブなセッションなし）からの復旧

ユーザーの入力： /recover

処理内容：

1. エージェントが並列で状態を収集します
2. エージェントが RPI の実行も Evolve サイクルもないことを確認します
3. エージェントが直近 3 件のコミットのみを表示します
4. エージェントが進行中の作業も対応可能なイシューもないことを確認します
5. エージェントがナレッジベースで利用可能な 12 件の学びを表示します
6. エージェントが次のように提案します：「セッションを復旧しました。次の作業を計画するには /status から始めてください」

結果： ダッシュボードでクリーンな状態を確認し、ユーザーに開始点を示します。

---

トラブルシューティング

問題	原因	解決策
「BR_UNAVAILABLE」または「GT_UNAVAILABLE」と表示される	CLI ツールがインストールされていないか、PATH に含まれていない	不足しているツール（br / gt）をインストールしてください。このスキルは利用可能な状態のみを表示し、適切に縮退動作します。
RPI の状態に誤ったフェーズが表示される	古い phased-state.json が更新されていない	.agents/rpi/phased-state.json のタイムスタンプを確認してください。古い場合は、前回の実行時のものかもしれません。現在のフェーズを確認するには /status を実行してください。
Evolve の履歴に誤ったサイクルが表示される	古い cycle-history.jsonl エントリが削除されていない	tail -3 で最新のエントリを表示できます。tail -20 .agents/evolve/cycle-history.jsonl ですべてのエントリを確認してください。
ナレッジの注入が何も表示せずに失敗する	ao CLI がインストールされていないか、ナレッジアーティファクトがない	ao がインストールされていることを確認してください：brew install ao。学びが存在しない場合は、/validate を実行してナレッジベースに初期データを登録してください。
提案されたアクションがコンテキストに合わない	状態に応じたルールが特殊なケースを捉えられなかった	--json を使用して生の状態を確認し、どの条件に一致したかを検証してください。ステップ 5 の優先順位テーブルを確認してください。
JSON 出力の形式が正しくない	並列 bash 呼び出しが想定外の形式を返した	各 bash 呼び出しを個別に確認してください。実際のデータで jq の解析が機能することを確認してください。ユーザーに返す前に JSON 構造を検証してください。

参考ドキュメント

• references/recover.feature — 実行可能な仕様：phased-state から rpi フェーズを検出し、claimed／ready の br 作業と最近の Git 状態を提示し、--json ダッシュボードを表示する（soc-qk4b）