diff --git a/docs/README.ja.md b/docs/README.ja.md index 8121444..3395595 100644 --- a/docs/README.ja.md +++ b/docs/README.ja.md @@ -76,6 +76,10 @@ takt --pipeline --task "バグを修正して" --auto-pr ## 使い方 +## 実装メモ + +- failed タスクの retry とセッション再開: [`docs/implements/retry-and-session.ja.md`](./implements/retry-and-session.ja.md) + ### 対話モード AI との会話でタスク内容を詰めてから実行するモード。タスクの要件が曖昧な場合や、AI と相談しながら内容を整理したい場合に便利です。 diff --git a/docs/implements/retry-and-session.ja.md b/docs/implements/retry-and-session.ja.md new file mode 100644 index 0000000..c43c0c2 --- /dev/null +++ b/docs/implements/retry-and-session.ja.md @@ -0,0 +1,58 @@ +# failed -> retry とセッション再開の動作原理 + +このドキュメントは、`takt list` の `failed` タスクを `Retry` したときの挙動と、AI セッション再開の実際の仕組みを整理した実装メモです。 + +## 問題の要約 + +- `failed -> retry` で「前回のセッションがそのまま復活するか」が分かりづらい。 +- 実際には「タスク固有のセッション再開」ではなく「保存済みの persona セッション利用」で再開される。 + +## 解決方針(実装の見方) + +- `Retry` が何を再投入するかを確認する。 +- 再実行時にどのセッションIDを読み込むかを確認する。 +- `session: refresh` や worktree 条件など、再開しないケースを明記する。 + +## 実装の流れ + +1. `takt list` で `failed` タスクに `Retry` を選ぶ。 +2. `retryFailedTask()` が `TaskRunner.requeueFailedTask()` を呼ぶ。 +3. 失敗タスク配下の元タスクファイルを `.takt/tasks/` にコピーする。 +4. YAML タスクの場合のみ、必要に応じて `start_movement` と `retry_note` を書き換える。 + +参照: +- `src/features/tasks/list/taskRetryActions.ts` +- `src/infra/task/runner.ts` + +## 重要: Retry で復元される情報 + +`requeueFailedTask()` はタスクファイルに `sessionId` を書き戻さない。 +復元対象は `start_movement` と `retry_note` のみ。 + +つまり、`failed` タスクを `Retry` しても「その failed ディレクトリに紐づくセッションID」を直接復元する実装にはなっていない。 + +## セッション再開の実際 + +再実行時の `pieceExecution` で、プロジェクト保存済みセッションをロードして `initialSessions` に渡す。 + +- 通常実行: `loadPersonaSessions(projectCwd, provider)` +- worktree 実行: `loadWorktreeSessions(projectCwd, cwd, provider)` + +その後、各 movement の Phase 1 実行で `OptionsBuilder.buildAgentOptions()` が `sessionId` を組み立てる。 + +参照: +- `src/features/tasks/execute/pieceExecution.ts` +- `src/core/piece/engine/OptionsBuilder.ts` + +## セッション再開しない条件 + +- movement 側が `session: refresh` の場合。 +- `cwd !== projectCwd` など、セッション再開を抑止する条件に当たる場合。 + +このため、`Retry` で常に同じ会話が厳密再開されるわけではない。 + +## 運用上の注意 + +- `failed -> retry` は正しい復旧手順。 +- ただしセッションは「タスク単位」ではなく「persona の保存状態」基準で再開される。 +- 前回文脈を確実に残したい場合は、`retry_note` に再試行理由と前提を明記する。