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` | コミット履歴 vs マーカー |
| 着手済みなのに `cc:TODO` | 変更ファイル vs マーカー |
| `cc:完了` なのに未コミット | git status vs マーカー |

## Step 3: Plans.md 更新提案

差分が検出された場合、提案して実行する:

```
Plans.md 更新が必要です

| Task | 現在 | 変更後 | 理由 |
|------|------|--------|------|
| XX   | cc:WIP | cc:完了 | コミット済み |
| YY   | cc:TODO | cc:WIP | ファイル編集済み |

更新しますか？ (yes / no)
```

## 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 に記録し、次回の `create` 時に参照できるようにする。
記録先: `.claude/agent-memory/` 配下の該当エージェントメモリ。

## 関連スキル

- `harness-plan` — 計画作成・タスク管理
- `harness-work` — タスク実装
- `harness-review` — コードレビュー