/harness-sync

name: harness-sync
description: "HAR: Sync Plans.md with implementation. Drift detect, marker update, retrospective. Trigger: sync-status, where am I, check progress. --snapshot for snapshots. Do NOT load for: planning, implementation, review, release."
description-en: "HAR: Sync Plans.md with implementation. Drift detect, marker update, retrospective. Trigger: sync-status, where am I, check progress. --snapshot for snapshots. Do NOT load for: planning, implementation, review, release."
description-ja: "HAR:Plans.md と実装の進捗同期。差分検出・マーカー更新・レトロスペクティブ。sync-status、進捗確認、今どこ、どこまで終わったで起動。--snapshot でスナップショット保存。プランニング・実装・レビュー・リリースには使わない。"
kind: workflow
purpose: "Reconcile Plans.md, git, and implementation state"
trigger: "sync-status, where am I, check progress"
shape: workflow
role: synchronizer
pair: harness-plan
owner: harness-core
since: "2026-05-05"
allowed-tools: ["Read", "Edit", "Bash", "Grep", "Glob"]
argument-hint: "[--snapshot|--no-retro]"
user-invocable: true
effort: medium

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: 現状収集（並列）

# 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 のタスクと照合する:

# 直近の編集ファイル一覧
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: 進捗サマリー出力

## 進捗サマリー

**プロジェクト**: {{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 形式で保存:

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"

スナップショット内容

{
  "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": ""
}

差分比較

前回スナップショットが存在する場合、差分を表示:

## スナップショット差分

| 指標 | 前回 ({{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: 完了タスク収集

# 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: 振り返りサマリー出力

## 振り返りサマリー

**期間**: {{start_date}} 〜 {{end_date}}

| 指標 | 値 |
|------|-----|
| 完了タスク | {{count}} 件 |
| ブロック発生 | {{blocked_count}} 件 |
| スコープ変動 | +{{added}} / -{{removed}} 件 |
| 見積もり精度 | 想定 {{est}} ファイル → 実際 {{actual}} ファイル |

### 学び
- {{1-2 行の学び}}

### 次に活かすこと
- {{1-2 行の改善アクション}}

S