harness-sync

# Harness Sync Plans.md と実装状況を照合し、差分を検出・更新する。 旧 `sync-status` および `harness-plan sync` サブコマンドの独立版。 ## Quick Reference | ユーザー入力 | 動作 | |------------|------| | `harness-sync` | 進捗同期 + レトロスペクティブ（デフォルト ON） | | `harness-sync --no-retro` | 進捗同期のみ（レトロスキップ） | | `harness-sync --snapshot` | スナップショット保存（進捗の時点記録） | | `harness-sync --plan roadmap` | named Plans の `roadmap` を同期 | | "今どこ？" / "進捗確認" | 同上 | ## オプション | オプション | 説明 | デフォルト | |----------|------|----------| | `--snapshot` | 現在の進捗をスナップショットとして保存 | false | | `--no-retro` | レトロスペクティブをスキップ | false（デフォルトで実行） | | `--plan NAME` | `plans/manifest.json` の named plan を使う | active/default | ## Step 0: Plans.md 検証 Plans.md の存在とフォーマットを確認する。問題がある場合は即座に案内して停止する。 複数 Plans.md がある repo では、対象 plan を `scripts/plan-registry.sh list` または `--plan NAME` で確認してから読む。 | 状態 | 案内 | |------|------| | Plans.md が存在しない | `Plans.md が見つかりません。harness-plan create で作成してください。` → **停止** | | ヘッダーに DoD / Depends カラムがない（v1 形式） | `Plans.md が旧フォーマット（3カラム）です。harness-plan create で v2（5カラム）に再生成してください。既存タスクは自動的に引き継がれます。` → **停止** | | v2 形式（5カラム） | そのまま Step 1 に進む | ## Step 1: 現状収集（並列） ```bash # Plans.md の状態 cat Plans.md # Git 変更状態 git status git diff --stat HEAD~3 # 直近コミット履歴 git log --oneline -10 # エージェントトレース（直近の編集ファイル） tail -20 .claude/state/agent-trace.jsonl 2>/dev/null | jq -r '.files[].path' | sort -u ``` ## Step 1.5: Agent Trace 分析 Agent Trace から直近の編集履歴を取得し、Plans.md のタスクと照合する: ```bash # 直近の編集ファイル一覧 RECENT_FILES=$(tail -20 .claude/state/agent-trace.jsonl 2>/dev/null | \ jq -r '.files[].path' | sort -u) # プロジェクト情報 PROJECT=$(tail -1 .claude/state/agent-trace.jsonl 2>/dev/null | \ jq -r '.metadata.project') ``` **照合ポイント**: | チェック項目 | 検出方法 | |------------|----------| | Plans.md にないファイル編集 | Agent Trace vs タスク記述 | | タスク記述と異なるファイル | 想定ファイル vs 実際の編集 | | 長時間編集がないタスク | Agent Trace 時系列 vs WIP 期間 | ## Step 2: 差分検出 | チェック項目 | 検出方法 | |------------|----------| | 完了済みなのに `cc:WIP` | DoD・必須チェック・必要な review の証拠 vs マーカー | | 着手済みなのに `cc:TODO` | 変更ファイル vs マーカー | | `cc:完了` なのに未コミット | git status vs マーカー | ## Step 3: Plans.md 更新提案 状況確認だけの依頼は読み取りと差分報告で完了する。同期更新を明示依頼されている場合は、証拠に一致するマーカー更新を再確認せず実行する。 対象が曖昧、証拠が不足、または仕様判断が必要な項目だけ提案に残す。コミットや Worker の自己申告だけでは完了にしない。 ``` Plans.md 更新が必要です | Task | 現在 | 変更後 | 理由 | |------|------|--------|------| | XX | cc:WIP | cc:完了 | DoD・必須チェック・review の証拠を確認済み | | YY | cc:TODO | cc:WIP | ファイル編集済み | ``` ## Step 4: 進捗サマリー出力 ```markdown ## 進捗サマリー **プロジェクト**: {{project_name}} | ステータス | 件数 | |----------|------| | 未着手 (cc:TODO) | {{count}} | | 作業中 (cc:WIP) | {{count}} | | 完了 (cc:完了) | {{count}} | | PM確認済 (pm:確認済) | {{count}} | **進捗率**: {{percent}}% ### 直近の編集ファイル (Agent Trace) - {{file1}} - {{file2}} ``` ## Step 4.5: スナップショット保存（`--snapshot` 指定時） `--snapshot` が指定された場合、現在の進捗状態を時刻付きスナップショットとして保存する。 ### 保存先 `.claude/state/snapshots/` ディレクトリに JSON 形式で保存: ```bash SNAPSHOT_DIR="${PROJECT_ROOT}/.claude/state/snapshots" mkdir -p "${SNAPSHOT_DIR}" SNAPSHOT_FILE="${SNAPSHOT_DIR}/progress-$(date -u +%Y%m%dT%H%M%SZ).json" ``` ### スナップショット内容 ```json { "timestamp": "2026-03-08T10:30:00Z", "phase": "Phase 26", "progress": { "total": 16, "todo": 5, "wip": 3, "done": 6, "confirmed": 2 }, "progress_rate": 50, "recent_commits": ["abc1234 feat: ...", "def5678 fix: ..."], "recent_files": ["skills/harness-work/SKILL.md", "..."], "notes": "" } ``` ### 差分比較 前回スナップショットが存在する場合、差分を表示: ```markdown ## スナップショット差分 | 指標 | 前回 ({{prev_time}}) | 今回 | 変化 | |------|---------------------|------|------| | 進捗率 | {{prev}}% | {{current}}% | +{{diff}}%pt | | 完了タスク | {{prev_done}} | {{current_done}} | +{{diff_done}} | | WIP タスク | {{prev_wip}} | {{current_wip}} | {{diff_wip}} | ``` > **設計意図**: snapshot はユーザーが「今の状態を記録しておきたい」と思った時に手動で使う。 > breezing 中の自動的なプログレスフィード（26.2.3）とは別の機能。 ## Step 5: 次のアクション提案 ``` 次にやること **優先 1**: {{タスク}} - 理由: {{依頼中 / アンブロック待ち}} **推奨**: harness-work, harness-review ``` ## 異常検知 | 状況 | 警告 | |------|------| | 複数の `cc:WIP` | 複数タスクが同時進行中 | | `pm:依頼中` が未処理 | PM の依頼を先に処理する | | 大きな乖離 | タスク管理が追いついていない | | WIP が 3日以上更新なし | ブロックされていないか確認 | ## Step 6: レトロスペクティブ（デフォルト ON） `cc:完了` タスクが 1 件以上あれば自動的に振り返りを実行する。 `--no-retro` で明示的にスキップ可能。 ### Step R1: 完了タスク収集 ```bash # Plans.md から cc:完了 / pm:確認済 のタスクを抽出 grep -E 'cc:完了|pm:確認済' Plans.md # 直近の完了コミット履歴 git log --oneline --since="7 days ago" # 変更規模 git diff --stat HEAD~10 ``` ### Step R2: 振り返り 4 項目 | 項目 | 分析方法 | |------|---------| | **見積もり精度** | Plans.md のタスク記述から想定ファイル数を推論 → `git diff --stat` の実変更ファイル数と比較 | | **ブロック原因** | `blocked` マーカーが付いたタスクの理由パターンを集計（技術的/外部依存/仕様不明確） | | **品質マーカー的中率** | `[feature:security]` 等を付けたタスクで実際に関連問題が出たか | | **スコープ変動** | Plans.md の初回コミット時のタスク数 vs 現在のタスク数（追加/削除件数） | ### Step R3: 振り返りサマリー出力 ```markdown ## 振り返りサマリー **期間**: {{start_date}} 〜 {{end_date}} | 指標 | 値 | |------|-----| | 完了タスク | {{count}} 件 | | ブロック発生 | {{blocked_count}} 件 | | スコープ変動 | +{{added}} / -{{removed}} 件 | | 見積もり精度 | 想定 {{est}} ファイル → 実際 {{actual}} ファイル | ### 学び - {{1-2 行の学び}} ### 次に活かすこと - {{1-2 行の改善アクション}} ``` ### Step R4: harness-mem への記録 振り返りは今回確認した証拠と改善案を報告する。永続記録を明示依頼されている場合だけ、対象の harness-mem または `.claude/agent-memory/` に出典と判断理由を記録する。 通常の進捗確認や `sync` を永続記録の依頼として扱わない。 ## 関連スキル - `harness-plan` — 計画作成・タスク管理 - `harness-work` — タスク実装 - `harness-review` — コードレビュー