harness-progress

Harness Progress Tracker

Phase 65.4 (Progress Tracker) — the 3rd surface of the cognitive-load HTML triplet. Following the Plan Brief / Acceptance Demo, this is the 3rd HTML surface, andgrasp the overall picture of the in-progress session on a single sheet of paper Make it possible.

Quick Reference

Input	Behavior
`/harness-progress`	Generate and open the progress snapshot HTML for the current project
`/harness-progress --no-open`	Generation only (does not open browser, for PostToolUse hook)
`/harness-progress --out <path>`	Specify output destination (default: `out/progress-snapshot.html`)

Mission

Generate a single HTML page that lets a non-engineer vibecoder grasp in 3 seconds in the browser "how many tasks the current session has completed and to what extent, when it is expected to finish, and how much it has cost".

Do:

Aggregate the cc:TODO / cc:WIP / cc:Done counts from Plans.md
Calculate progress_pct (completion rate) (cc:Done ÷ total tasks × 100)
Display elapsed minutes / estimated total minutes / cost so-far / cost estimate
Display drift alert (populated in Phase 65.4.3 and later)

Don't do (this cycle):

Live update via WebSocket / SSE (static HTML, updated by regeneration)
History comparison of past sessions (separate axis in Phase 65.4.4)
Cross-project view of other projects (independent of Phase 65.3)

Schema: progress-snapshot.v1

Detailed spec: schemas/progress-snapshot.v1.schema.json

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>

Execution Flow

Step 0: Obtain PROJECT_NAME

PROJECT_NAME="$(basename "$(git rev-parse --show-toplevel)" 2>/dev/null || echo "current")"

Step 1: Assemble the snapshot

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 (implemented in Phase 65.4.1) parses Plans.md and progress-snapshot.v1 outputs JSON conforming to the schema.

Step 2: Render HTML

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: Open in the browser

--no-open flag がNoOnly execute in this case (skip for background regeneration from the PostToolUse hook):

bash scripts/plan-brief-open.sh --path "$OUT_PATH"

Cross-project search (default OFF)

Phase 65.4.4 で --cross-project-group <name> flag is added. In this cycle (65.4.1), default OFF, aggregates only the current project.

Failure modes

State	Behavior
There is no Plans.md	`progress-snapshot.sh` が exit 1 (clear error message)
Plans.md has not a single task	`progress_pct: 0`, generate the snapshot with an empty array (the HTML displays "no tasks")
There is no state file (elapsed minutes, etc.)	`elapsed_minutes: 0`, `cost_so_far_usd: 0` with fallback (no warning)
`git` Absent / outside a git repo	`project: "current"` で fallback

harness-plan-brief (Phase 65.1.x) — 1st surface (briefing before implementation)
harness-accept (Phase 65.2.x) — 2nd surface (acceptance decision)
harness-progress (this skill, Phase 65.4.x) — 3rd surface (progress dashboard)
Features will be extended in 65.4.2 (PostToolUse auto-regen), 65.4.3 (5 types of drift alert), and 65.4.4 (past-decision lookup)

About this skill