harness-progress

# Harness Progress Tracker Phase 65.4 (Progress Tracker) — 3rd surface of the cognitive-load HTML triplet. Plan Brief / Acceptance Demo に続く 3 つ目の HTML surface で、**進行中セッションの全体像を 1 枚の紙で把握** できるようにする。 ## Quick Reference | 入力 | 動作 | |---|---| | `/harness-progress` | 現プロジェクトの進捗 snapshot HTML を生成し開く | | `/harness-progress --no-open` | 生成のみ (browser 開かない、PostToolUse hook 用) | | `/harness-progress --out <path>` | 出力先指定 (default: `out/progress-snapshot.html`) | ## Mission > "今のセッションは何件のタスクをどこまで終わらせて、いつ終わる見込みで、いくら使ったか" を、 > エンジニアじゃない vibecoder が **3 秒でブラウザで把握** できる HTML 1 枚を生成する。 **やる**: - Plans.md の cc:TODO / cc:WIP / cc:完了 件数を集計 - progress_pct (完了率) を計算 (cc:完了 ÷ 総タスク × 100) - 経過分数 / 推定総分数 / コスト so-far / コスト estimate を表示 - drift alert を表示 (Phase 65.4.3 以降で populate) 完了率は Plans.md のマーカーから算出した値であり、受け入れ検証の合格率ではない。説明では計測値と推定値を分ける。 state 欠損時の表示用既定値を実測の 0 と主張せず、元の計測が未取得ならその限界を報告する。ボード生成だけでタスクを完了にしない。 **やらない** (本 cycle): - WebSocket / SSE による live update (静的 HTML、再生成で更新) - 過去 session の history 比較 (Phase 65.4.4 で別軸) - 他 project の cross-project view (Phase 65.3 と独立) ## Schema: progress-snapshot.v1 詳細仕様: [schemas/progress-snapshot.v1.schema.json](${CLAUDE_SKILL_DIR}/schemas/progress-snapshot.v1.schema.json) ```yaml schema: progress-snapshot.v1 project: <basename of git repo> current_task: <cc:WIP の最初の項目 1 行サマリ、なければ空文字> progress_pct: <0-100 の整数、cc:完了 ÷ 総タスク × 100 の四捨五入> todo_tasks: [{number, title}] ← cc:TODO のみ wip_tasks: [{number, title}] ← cc:WIP のみ done_tasks: [{number, title, commit}] ← cc:完了 [hash] のみ、hash は 7 chars elapsed_minutes: <int, state file から> estimated_total_minutes: <int, state file から> cost_so_far_usd: <float, state file から> cost_estimate_usd: <float, state file から> alerts: [] ← Phase 65.4.3 以降で populate generated_at: <ISO8601 UTC> writing_lint_pending: [{id, pattern, approve_command, pending_count}] ← optional/additive (Phase 136.2) deferred_ops_pending: [{id, command, approve_command, pending_count}] ← optional/additive (Phase 140.2) ``` ### writing_lint_pending (Phase 136.2) `scripts/writing-rule-list.sh --status pending --json` の出力をそのまま snapshot に 組み込む optional フィールド。pending proposal が 0 件のときは配列が空になり、 `progress.html.template` の該当セクションは何も展開せず非表示になる (render-html.sh の `{{#section}}` は配列が空だと block を 0 回展開するため)。 表示するのは **コピペ用のコマンド文字列** (`scripts/writing-rule-approve.sh --id <id>`) であって押せるボタンではない。承認は人間が CLI で `writing-rule-approve.sh` を実行する 一択の経路のまま (Phase 135.4。自動昇格経路は無い)。 ## Execution Flow ### Step 0: PROJECT_NAME を取得 ```bash PROJECT_NAME="$(basename "$(git rev-parse --show-toplevel)" 2>/dev/null || echo "current")" ``` ### Step 1: snapshot を組み立て ```bash SNAPSHOT_JSON="$(mktemp /tmp/progress-snapshot-XXXX.json)" bash scripts/progress-snapshot.sh \ --plans Plans.md \ --project "$PROJECT_NAME" \ > "$SNAPSHOT_JSON" ``` `scripts/progress-snapshot.sh` (Phase 65.4.1 で実装) は Plans.md を parse し `progress-snapshot.v1` schema 準拠の JSON を出力する。内部で `scripts/writing-rule-list.sh --status pending --json` も呼び、`writing_lint_pending` を additive に組み込む (Phase 136.2。writing-rule-list.sh が無い/失敗する場合は空配列)。 同様に `.claude/state/deferred-ops.jsonl` の `status: pending` 行を `deferred_ops_pending` として組み込む (Phase 140.2。ファイルが無い/壊れた行は読み飛ばして空配列)。表示するのは コピペ用の `bin/harness deferred approve <id>` 文字列で、押せるボタンではない。 ### Step 2: HTML をレンダリング ```bash OUT_PATH="${OUT_PATH:-out/progress-snapshot.html}" mkdir -p "$(dirname "$OUT_PATH")" bash scripts/render-html.sh \ --template progress \ --data "$SNAPSHOT_JSON" \ --out "$OUT_PATH" ``` ### Step 3: ブラウザで開く `--no-open` flag が**ない**場合のみ実行 (PostToolUse hook からの背景再生成では skip): ```bash bash scripts/plan-brief-open.sh --path "$OUT_PATH" ``` ## Cross-project search (default OFF) Phase 65.4.4 で `--cross-project-group <name>` flag が追加される。本 cycle (65.4.1) では default OFF、現プロジェクトのみ集計する。 ## Failure modes | 状態 | 動作 | |---|---| | Plans.md が無い | `progress-snapshot.sh` が exit 1 (clear error message) | | Plans.md にタスクが 1 件もない | `progress_pct: 0`, 空配列 で snapshot 生成 (HTML は「タスクなし」表示) | | state file (経過分数等) が無い | `elapsed_minutes: 0`, `cost_so_far_usd: 0` で fallback (warning なし) | | `git` 不在 / git repo 外 | `project: "current"` で fallback | ## Related - `harness-plan-brief` (Phase 65.1.x) — 1st surface (実装前の説明会) - `harness-accept` (Phase 65.2.x) — 2nd surface (検収判断) - `harness-progress` (本 skill, Phase 65.4.x) — 3rd surface (進捗ダッシュボード) - 65.4.2 (PostToolUse auto-regen)、65.4.3 (drift alert 5 種)、65.4.4 (過去判断 lookup) で機能拡張