Pre-choice usable artifact execution

Purpose & Output Contractの最小の実成果物をmain contextで作成する。effect別のparse/open・secret・irreversible・corrupt guardだけを実行し、現物path・digest・開き方を提示してからaccept-as-is/light/standard/detailedを記録する。accept-as-isはその場でhandoff完了とし、後続sectionを実行しない。

Post-choice selected improvement execution

以下の既存workflow・goal-seek・評価・修正sectionはlight/standard/detailedが記録されてsemantic_evaluator_startedへ遷移した場合だけ実行する。release/exhaustiveは別の明示eventを必要とする。

run-skill-update-notifier

Purpose & Output Contract

入力: なし (hook 経由で自動起動) / 明示起動時は scripts/notifier-check.py の subcommand (cache-status / refresh / notify)。 範囲 (Stage 1): 同じツリー（install 先またはチェックアウト）の中の plugin.json の version（installed）と CHANGELOG 先頭の版（latest）の食い違いを知らせる。配布元と比べて新しい版を知らせ、更新へ案内するのは将来の Stage 2（run-skill-update-apply）の範囲で、本 Skill はやらない。 通知の相手: plugin の作者、または同じツリーで開発している人（plugin.json の version と CHANGELOG を手で上げる人。以下まとめて作者）に向けた通知である。install 先では作者でない利用者にも表示されるが、利用者が直すものではない（不要なら HARNESS_SKILLS_NOTIFY=off で止める）。 出力: Skill の実行後、版が食い違うときだけ 1 行を、hook が systemMessage として利用者に表示する。文言は向きで 3 種（plugin.json の version の上げ忘れ / CHANGELOG の節の足し忘れ / 版を比べられない）。書式の正本は references/output-format.md。一致 / 片方欠落 / 抑制 / 同じ session で通知済みのときは何も出さない。 副作用: ~/.cache/harness/version-snapshot.json の更新のみ。plugin manifest は変更しない。 完了条件: cache 比較が完了 (差分有無を問わず) し、通知出力 or no-op を決定したとき。

Boundary

通知のみ。実際の pull/install/apply/rollback はやらない。配布元とは比べない。version 重複解消もやらない (別 Skill に分離)。既存 plugin.json / marketplace.json / bundles.json / skill-intake-self-updater は一切変更しない。

Key Rules

1. 非破壊: 既存 manifest を touch しない (read-only)。
2. graceful degradation: CHANGELOG.md 不在 / cache 不在 / cache を読めないときは静かに no-op。cache を読めるが書けないときだけは、通知は出して通知済みの記録だけを飛ばす（通知を失う向きには倒さない）。どの場合も exit 0 で、エラーで Skill 実行を妨げない。
3. Python stdlib のみ: 外部依存ゼロ (argparse, datetime, json, os, pathlib, re, subprocess, sys のみ。ネットワーク系は import しない)。
4. 24h TTL: cache 鮮度判定は 24 時間。それ未満は再 scan しない。
5. PostToolUse filter: hook は tool_name == "Skill" のときだけ通知発火。Bash/Read 等の末尾には付かない。
6. 抑制フラグ: 環境変数 HARNESS_SKILLS_NOTIFY=off で完全無効化。

Hook Integration Map

Hook Event	Script	役割	exit
UserPromptSubmit (matcher=.*)	scripts/hook-cache-refresh.py	stale/absent のときだけ cache を同期で再 scan (timeout 15 秒。24h TTL 以内は即 return)	0固定
PostToolUse (matcher=Skill)	scripts/hook-notify-skill-end.py	tool_name == "Skill" のとき、通知を systemMessage の JSON 1 個で stdout に出し、利用者に表示させる	0固定

配線は harness-creator の hooks/hooks.json に同梱され、plugin を install すると Claude Code が自動で読む。hooks.json は公開 entry point (hooks/cache-refresh.py / hooks/notify-skill-end.py) を起動し、それが上の script へ委譲する。settings.json を手で編集する必要はない。詳細は references/hook-wiring.md。

Responsibilities (brief 由来)

• R1 changelog-cache-check: 各 plugin の CHANGELOG.md を読み、cache と差分検出 (scripts/notifier-check.py)
• R2 notification-formatting: 差分時の 1 行通知整形 (出力規約は references/output-format.md)
• R3 graceful-degradation-guard: 例外を握りつぶし no-op に倒す保護層

<!-- runtime-root-contract:v1 -->

Runtime root contract

• runtime_root_policy: host-skill-path を適用する。
• Claude Codeでは CLAUDE_PLUGIN_ROOT をplugin rootとして使用する。
• Codexではホストが提示したこの SKILL.md のabsolute pathから、plugin manifestを持つ祖先を上方探索して論理 PLUGIN_ROOT を解決する。
• cwd からplugin rootを推測せず、literal placeholderをshellへ渡さない。各shell invocation内で解決済みabsolute pathを PLUGIN_ROOT に設定する。
• prompts/ 配下はこのowner Skill契約を継承する。

<!-- /runtime-root-contract:v1 -->

ゴールシーク実行

ゴール (Goal)

cache 比較が完了し（差分有無を問わず）、tool_name == "Skill" の実行後に版の食い違いの 1 行通知を hook から systemMessage として利用者に表示する、または no-op を決定した状態（既存 manifest は不変・graceful degradation を維持）。

目的・背景 (Why)

同じツリー内の plugin.json と CHANGELOG の版の食い違い（CHANGELOG の節の足し忘れや version の上げ忘れ）に、作者が意識せず気づける仕組みを、Skill 実行を妨げず非破壊で提供するため。cache 鮮度・CHANGELOG 有無・抑制フラグなど分岐が多く、固定手順では graceful 維持が脆い。到達状態（通知 or no-op の決定）をゴールに据える。

完了チェックリスト (Checklist)

• cache 鮮度判定（notifier-check.py cache-status → fresh/stale/absent）を実施済み（fresh なら scan を省略）
• stale/absent 時は notifier-check.py refresh に plugins/ と自 plugin root を絶対パスで渡し（cwd 基準の plugins/ は渡さない）、各 plugin の CHANGELOG.md 先頭の version を抽出し ~/.cache/harness/version-snapshot.json へ atomic rename で書き出し済み
• snapshot の key は plugin.json の name（読めなければディレクトリ名）。同じ name が複数ある（install 先に版ディレクトリが並ぶ）ときは、--plugin-root で渡したもの → installed が semver として読めるもの → semver で最大のもの → パスが辞書順で後ろのもの、の順で 1 つに決める
• 通知文字列を notifier-check.py notify --plugin $PLUGIN_NAME で生成し、installed(plugin.json) vs latest(cache) を比較済み
• 一致 / cache 未提供 / installed 未取得 / HARNESS_SKILLS_NOTIFY=off のいずれかは空文字列（no-op）になっている
• 版の前後を semver として比較している（文字列比較では "0.10.0" < "0.9.0" が真になり向きが逆転する）。先頭の v / V は表記差として読み飛ばす
• 食い違いの向きで文言を分けている: CHANGELOG の版が新しい → version の上げ忘れ、plugin.json の版が新しい → CHANGELOG の節の足し忘れ、どちらかが semver として読めない → 向きを決めず「版を比べられない」。文字列は references/output-format.md に従い、利用者に更新を促す文言は出さない
• PostToolUse hook (hook-notify-skill-end.py) が tool_name == "Skill" のときだけ、通知に <plugin>: を前置して systemMessage を持つ JSON 1 個を stdout に出し、Read/Bash や通知の無いときは何も出さない
• 1 セッション内で同一 plugin の通知が重複しない（hook が payload の session_id を --session-id で渡し、cache の notified.<plugin> に session_id と last_notified_at を記録。session_id の無い payload では抑止しない）
• CHANGELOG 不在 / cache 不在 / 権限不足のいずれも例外を握りつぶし exit 0 に倒れている（cache を読めないときは no-op、読めるが書けないときは通知を出して記録だけ飛ばす）
• 既存 manifest（plugin.json / marketplace.json / bundles.json / skill-intake-self-updater）を一切変更していない（read-only）
• ネットワーク取得を行わず Python stdlib のみで完結している（24h TTL 鮮度判定）

ゴールシークループ

正本 ../run-build-skill/references/goal-seek-paradigm.md の 6 ステップに従う。本スキル固有差分:

• 対象ファイル: ~/.cache/harness/version-snapshot.json（書込対象はこれのみ）、各 plugins/*/CHANGELOG.md（read-only）
• 固定パス/閾値: cache 鮮度 24h TTL（時刻欠落時は stale 扱い）、通知書式（正本は references/output-format.md）、抑制 HARNESS_SKILLS_NOTIFY=off
• Hook 連携は hooks/hooks.json で plugin install 時に自動配線される（references/hook-wiring.md）。settings.json は編集しない
• いずれの分岐でも Skill 実行を止めない（exit 0 固定 / graceful no-op）。未達があれば原因（cache/CHANGELOG/権限）を特定して no-op か通知かを再決定する

局面カタログ (順序は都度判断)

パスは harness-creator の plugin root（${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}）基準で渡す。cwd 基準の相対パスでは呼ばない。

• 鮮度確認: python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/run-skill-update-notifier/scripts/notifier-check.py" cache-status（fresh なら scan skip）
• scan/更新: python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/run-skill-update-notifier/scripts/notifier-check.py" refresh --plugins-root "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/.." --plugin-root "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}"（hook-cache-refresh.py と同じ解決。stale/absent のときだけ走らせるなら python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/run-skill-update-notifier/scripts/hook-cache-refresh.py"）
• 通知生成: python3 "${PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/skills/run-skill-update-notifier/scripts/notifier-check.py" notify --plugin "$PLUGIN_NAME"
• hook 出力: hook-notify-skill-end.py が tool_name == "Skill" を判定し、通知を {"systemMessage": "<plugin>: <通知>"} の JSON 1 個で stdout に出す（重複抑止: payload の session_id を渡し、cache の notified.<plugin>.last_notified_at に記録）

Constraints

• 実行中スキルの自己書換禁止 (PreToolUse 等で deny は不要。本 Skill の書き込みは ~/.cache/harness/version-snapshot.json だけで、Skill 自身のファイルには書かないため)。
• ネットワーク取得は行わない (cache はローカルファイルのみ)。
• 出力フォーマットの変更は references/output-format.md を Edit し、本 SKILL は touch しない。

Gotchas

• 素の stdout は利用者に届かない: PostToolUse hook が素のテキストを print しても debug log に行くだけで、利用者にも Claude にも見えない。stdout 全体を systemMessage を持つ JSON 1 個にする（ほかのテキストを混ぜると JSON として読まれない）。
• PostToolUse 全 tool 発火事故: filter を忘れると Read/Bash 末尾にも通知が付き UX 大破壊。hooks/hooks.json の matcher=Skill と hook-notify-skill-end.py 内の tool_name == "Skill" 判定の両方で絞る。
• cache 不在初回: 起動直後は cache 空。refresh（scan/更新の局面。UserPromptSubmit hook が走らせる）が走るまで notify は無出力 (graceful)。
• 24h TTL の挙動: last_refreshed_at が cache に無いと毎回 refresh して負荷増。fresh 判定は時刻欠落時 stale 扱い。
• install 先の走査範囲: install 先では --plugins-root が <marketplace>/<name>/（版ディレクトリの親）になるので、snapshot に入るのは自 plugin（harness-creator）だけで、他 plugin の Skill には通知が出ない。チェックアウトでは plugins/ 全体を見る。
• 共用 cache と重複抑止の制限: ~/.cache/harness/ は user-global で、全 session が同じ snapshot を読む。重複抑止の記録は plugin ごとに最新の session 1 件だけなので、2 つの session が同じ plugin を A→B→A と交互に使うと A にもう一度出る。通知が増える向きの制限で、通知を黙って失う向きには倒れない。
• cache に書けないときは重複抑止が働かない: ~/.cache/harness/ を読めても書けないと、通知済みの記録（notified.<plugin>）が残らない。同じ session でも Skill を使うたびに同じ通知がもう一度出る。通知を失わない側に倒した設計（notifier-check.py は表示の後に記録する）で、直すには cache の書き込み権限を戻す。
• Codex では通知が自動で出ない: Codex に配線されるのは UserPromptSubmit の cache-refresh だけで、PostToolUse（matcher=Skill）の notify-skill-end は Claude Code 専用（.codex/hooks/registry.json の products が claude だけ）。Codex で通知を見るには、局面カタログの通知生成（notifier-check.py notify）を明示して起動する。

Additional Resources

• scripts/notifier-check.py — cache 比較ロジック (CLI 単体実行可)
• references/output-format.md — 通知文字列規約
• references/hook-wiring.md — hooks/hooks.json による hook 配線と無効化の方法
• 設計書 10 章 §7 — Hook 競合解決
• 関連 Stage: Stage 0 lint-version-singletruth (将来)