/harness-update Skill — Harness Full Upgrade

Implements the full harness upgrade path: version check → CHANGELOG → checklist → approval → apply. Analogous to npm update / brew upgrade — upgrades the entire installed harness, not just CLAUDE.md. Prerequisite: /init has been run (.claude/harness-answers.yml exists).

When to Use

• After a new harness release is available (patrick-work-harness tag bump)
• When session-dashboard.html is missing, Stop hooks are unwired, or session stubs are absent on an existing init'd repo
• To verify whether a repo is fully up to date without applying changes (--check mode)

Invocation Modes

Step 1 — Read provenance and resolve engine version

Read .claude/harness-answers.yml in the current working repo (the repo Claude Code is opened in):

• _engine_version: version at last /init or /harness-update run
• session_docs: bool — whether session stubs (SESSION_INDEX / CURRENT_SESSION) are expected
• plan_tier: "1" or "2" — read only, never re-prompted here (changing tiers is a manual, explicit action, not an upgrade concern). Field absent (repo initialized before this field existed) → treat as plan_tier: "2", not an error and not a reason to halt.

Resolve the latest engine version via this priority order:

1. ${CLAUDE_PLUGIN_ROOT}/plugin.json → version (plugin-install topology)
2. Local patrick-work-harness clone: search for plugin.json under common paths (<로컬 하네스 체크아웃>/plugin.json, ~/.claude/plugins/*/plugin.json)
3. If neither is found: halt with "Cannot resolve engine version — ensure CLAUDE_PLUGIN_ROOT is set or patrick-work-harness is cloned locally."

Step 1-b — Cross-check the provenance field against what is actually installed

🔴 The _engine_version field can be wrong. It is written by /init and /harness-update, and until 2026-09-24 install.sh did not touch it at all — so a repo installed via the script kept the old value while the hooks on disk were newer (real case: field 1.3.4, hooks v1.4.1). Judging from the field alone then tells the user to re-install what is already installed.

Before applying the comparison table below, read the install marker and compare:

# Written by install.sh since v1.4.2 (HARNESS-INSTALL-PROVENANCE-2)
grep '^version:' ~/.claude/hooks/patrick-work-harness/.harness-owned | cut -d' ' -f2

Why the marker wins: the field records what a skill last claimed; the marker records what the installer actually wrote. When they disagree, the files on disk are the ground truth.

Step 2 — Display CHANGELOG

Read CHANGELOG.md from the engine source (same directory as plugin.json resolved in Step 1).

Extract all version sections newer than _engine_version (sections between ## [X.Y.Z] headers where X.Y.Z > _engine_version, semver order).

Output format:

── 변경 내역 ({_engine_version} → {latest}) ──────────
  ## [1.0.1] - 2026-06-26
    Added: /harness-update 스킬 (버전 확인→체크리스트→승인→일괄 갱신)
  ...
──────────────────────────────────────────────────────

If CHANGELOG.md is absent or the section is empty, output "변경 내역 없음 (CHANGELOG 미존재)" and continue.

Step 3 — Checklist: what needs applying

Inspect the current repo state across 7 axes (A–G). Mark each ✅ (ok) or ❌ (needs update):

Output the checklist table with ✅/❌ per row, then:

• If all ✅: "모든 항목 최신 상태 — 갱신 불필요합니다."
• If --check mode: stop here (no file writes).
• If ≥1 ❌: list the items needing update and proceed to Step 4.

Step 4 — Await user approval

Output:

위 {N}항목을 적용하겠습니다.
「harness-update 승인」으로 응답하면 실행합니다.

STOP — await user response before any file writes.

Recognized approval phrases: 「harness-update 승인」「승인」「적용」「진행」. On any other response, abort with "갱신을 취소했습니다."

Step 5 — Apply updates (checklist-driven, conditional per axis)

Execute only the axes marked ❌ in Step 3. Axes already ✅ are skipped silently.

Axis A — HARNESS zone reconcile

Reconcile the HARNESS zone:

• Locate <!-- HARNESS:START … <!-- HARNESS:END --> sentinels in CLAUDE.md
• If the zone holds a ## Build · Test section (an older /init put it there), move it verbatim to right below <!-- PROJECT-OWNED below --> first. Those are the project's own commands, and Gate D copies them
• Overwrite the zone wholesale with the current engine template, substituting project_repo from harness-answers.yml
• Update version tag to <!-- HARNESS:START v{latest} -->
• Everything after <!-- PROJECT-OWNED below --> is never touched

If sentinels are absent: output "⚠️ HARNESS sentinel 없음 — /init을 먼저 실행하세요." and skip this axis.

Axis B — Hook wiring (check, then fix)

Same check as /init Step 6: ls "${CLAUDE_PLUGIN_ROOT}/hooks/session-dashboard-sync.py".

• The file exists (plugin or install.sh install). The guards are already wired outside the project. In the project's .claude/settings.json, remove every hook entry whose command contains ${CLAUDE_PLUGIN_ROOT} — an earlier /init added them, and Claude Code refuses that variable in settings.json, so they never ran and logged a failed hook at every response. List the entries you will remove in the Step 4 approval. Leave every other entry untouched.
• The file is missing (a source copy). Make sure the 3 Stop guards are wired with the absolute path of that copy's hooks/ folder (/init Step 6 JSON shape), session-dashboard-sync.py first; prepend only the missing ones and keep existing entries.
• In both cases, remove every hook entry in the project's .claude/settings.json and .claude/settings.local.json whose script is a retired hook — comprehension-ledger-stale-guard.py, claude-gate-guard.py or skill-usage-auto.py — and list them in the Step 4 approval. Leave every other entry untouched.

Never write ${CLAUDE_PLUGIN_ROOT} into a settings file.

Axis C — Generate session-dashboard.html

Run the sync script once manually:

CLAUDE_PROJECT_DIR=<repo root> python3 "${CLAUDE_PLUGIN_ROOT}/hooks/session-dashboard-sync.py"

If CLAUDE_PLUGIN_ROOT is unavailable (a source copy), use that copy's hooks/ folder — the absolute path already wired in .claude/settings.json:

CLAUDE_PROJECT_DIR=<repo root> python3 <source copy>/hooks/session-dashboard-sync.py

Confirm session-dashboard.html exists at the repo root after execution.

Axis D — Create session stubs

Only when session_docs: true in harness-answers.yml AND stub(s) are absent.

Create missing stubs using the same templates as /init Step 5:

${SESSION_INDEX_FILE} stub:

---
project: "{project_repo}"
last_updated: "{YYYY-MM-DD}"
gate: "신규 — 다음 작업 시 /gate-a로 시작"
sessions_since_audit: 0
last_audit_date: ""
priority_note: ""
next_action: "새 작업 시 /gate-a로 시작."
---

# 세션 인덱스

| 세션 ID | 제목 | 저장소 | 상태 |
|---------|------|--------|------|

${CURRENT_SESSION_FILE} stub:

# 현재 세션 상태

> **세션 ID**: (미정 — /gate-a로 시작)
> **현재 상태**: 신규
> **직전 세션**: —

> **세션 주제**: harness-update 백필 적용 완료 — 다음 작업 시 /gate-a로 시작

After writing, verify both files exist (ls check). If either is absent after write, retry once.

Axis E — Layer 2 document skeletons

For each Pending row in DOC_INDEX.md, create that file's skeleton as /init Step 9 does and set the row to Skeleton. Do not create documents the index does not list.

Axis F — Lesson store

Ask the user where Gate E should record lessons (default error_topics_path: "docs/rules/error_topics"; a multi-repo workspace may list code_repos instead), write the field into harness-answers.yml, then create the folder README.md with the /init Step 4-b template. For code_repos, create files inside sibling repositories only after the user confirms those paths. Existing entries are never rewritten.

Axis G — Autonomous-lane setting

Append the /init Step 3 autonomous_lane: block with enabled: false. Do not turn it on here — say that the user can set enabled: true and commit the file to opt in (gate-a/SKILL.md §0-Lane), and that the lane also needs archive_path for the card ledger. The lane guard itself arrives with the plugin update; a user who installed with install.sh must re-run it to wire the guard.

Step 6 — Update _engine_version

Write _engine_version: "{latest}" back to .claude/harness-answers.yml. All other fields remain unchanged.

Verification Checklist (for Gate C after /harness-update)

• C1: harness-answers.yml → _engine_version equals latest engine version
• C2: CLAUDE.md HARNESS zone version tag matches latest: <!-- HARNESS:START v{latest} -->
• C3: no settings file contains ${CLAUDE_PLUGIN_ROOT}; a source copy has the 3 Stop guards with absolute paths, session-dashboard-sync.py first
• C4: session-dashboard.html exists at repo root
• C5: Already-up-to-date repo exits cleanly at Step 1 with "✅ 이미 최신 버전"
• C6: --check mode produces no file writes (read-only confirmed by grep)
• C7: harness-answers.yml sets error_topics_path or code_repos, and the lesson store README.md exists

Notes

• /harness-update is explicit-invoke only (D-4 decision). The SessionStart hook may detect version mismatch and notify, but reconciliation requires explicit invocation.
• Idempotent: re-running when already up to date exits cleanly at Step 1 or reports all-✅ at Step 3.
• Scope: /harness-update is the full upgrade path — HARNESS zone + hooks + dashboard + stubs in one run (HARNESS-zone reconcile is Axis A).
• Relation to /init: /init is for new repos. /harness-update is for existing init'd repos. Never run /init on an existing repo to apply updates — use /harness-update.