health-check

スキル：health-check

WHAT

目的とコンテキスト

• 目的： .template-manifest.json に宣言されたファイルのセットである「標準パターン」について、sync-template のようにファイルごとに手動で差分を確認せずに、次の3つの質問にすばやく回答します。
  1. 不足はないか？ — 宣言されたすべてのパターンがディスク上に存在するか（MISSING）。
  2. ローカルに差分はあるか？ — 前回の同期以降に変更されたパターンはあるか（DRIFT）。
  3. リモートとの同期が必要か？ — リモートに、より新しいパターンがあるか（BEHIND／古いバージョン）。
• 使用するタイミング：
  • ハーネスがセッション開始時に自動実行するとき（SessionStart フック）— 差分があれば自動的に通知します。
  • ユーザーが手動でいつでも確認するために /health-check を実行するとき。
  • /sync-template を実行するかどうかを決める前。
• 対象外： ファイルの取得・送信は自動で行いません（それは /sync-template の役割です。health-check は診断のみです）。wiki の内容（リンク切れ、孤立ページ、古い情報など）も確認しません（それは harness/scripts/wiki-health.py の役割です）。

メンタルモデル

仕組み：唯一の設定ファイル harness/version.json に template_version と各パターンのハッシュを保存します。3つの基準を比較します：ディスク ↔ version.json（drift）、ローカル ↔ リモートの version.json（behind）、manifest ↔ ディスク（missing）。各パターンの結果は OK · DRIFT · NEEDS-SYNC となり、推奨アクションが示されます。

入力と出力の契約

	フィールド	必須？	意味
In	.template-manifest.json + harness/version.json	はい	パターンセットとフィンガープリント。version.json がない場合はローカルの結果を報告します（fail-open）。
In	--branch / --offline / --json / --fail-on	いいえ	リモートブランチ、fetch のスキップ、機械可読な出力、CI ゲート用の exit 2
Out	グループごとのステータスレポート + OKF v0.1 の行	はい	OK / DRIFT / NEEDS-SYNC + ✓ OKF v0.1: N/N …
Out	exit code	--fail-on 指定時	指定されたグループに違反がある場合は 2
Out	更新済みの harness/version.json	sync 後に --update を指定した場合のみ	ハッシュがディスクと一致

ルールと機能

• RULE-01（MUST）：必ず fail-open とします。ネットワークエラー／version.json の欠落時には、ローカルの結果を報告し、セッションをブロックしません。
• RULE-02（MUST）：バージョンの唯一の真実の情報源は harness/version.json です。他の場所にバージョンをハードコードしません。
• RULE-03（MUST）：パターンセットは .template-manifest.json の includes とします。ただし、harness/version.json とプロジェクトごとに異なる「稼働中」のファイル（index.md、log.md、active-context.md、decisions.md）は除きます。これらのファイルはシードされますが、drift の対象にはなりません。
• RULE-04（MUST）：--bump を使えるのはテンプレートリポジトリのみです。子プロジェクトでは --update のみを使用します。
• RULE-05（MUST）：新しいパターンを追加するときは、まず .template-manifest.json の includes に追加し、その後 --update を実行します。
• 機能：ローカルのディスク、manifest、version.json を読み取ります。リモートの version.json は任意で読み取ります（オフラインでも実行可能）。version.json への書き込みは --update 指定時のみです。

失敗時の境界

• ネットワークエラー／リモートに接続できない場合 → ローカルの結果を報告し、partial とします。ブロックしません（RULE-01）。
• harness/version.json がない場合 → 確認できた結果を報告し、ブロックしません。
• --fail-on で違反グループが見つかった場合 → CI ゲート向けに failed（exit 2）となります。
• DRIFT が改善なのか誤操作なのか不明な場合 → upstream への反映や revert の前に、ユーザーに確認します。

HOW

メインワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	deterministic	repo、ブランチ	harness/scripts/health-check.py のレポートを実行します（リモートを確認するかどうかを指定）	ステータステーブル + OKF の行	オフライン → B01
W02	judgment	レポート	ステータステーブルを見て結果を読み取ります	推奨アクション	OK → 完了
W03	effect	推奨事項	アクション：/sync-template で downstream/upstream に同期する、または git checkout -- <file> を実行する	同期／revert 済みのパターン	DRIFT が曖昧 → 確認
W04	effect	同期後	フィンガープリントを更新します。--update を指定します（--bump はテンプレートリポジトリのみ。B02）	ディスクと一致する version.json	—

各ステップの詳細（W01～W04 の信頼できる情報源）：

1. レポートを実行する（リモートも照合）

python3 harness/scripts/health-check.py --root . --branch orca

• --offline：ネットワークがない場合、リモートへの fetch をスキップしてローカルのみを確認します。
• --json：機械可読な出力（フック／CI 用）です。
• --fail-on behind,drift,missing：指定したグループに違反がある場合は exit 2 となります（CI ゲート用）。

2. 結果を読む

status	意味	対応
OK	pattern が十分にあり、リモートと一致	対応不要
DRIFT	pattern がローカルで変更されている	upstream（/sync-template push）または revert を検討
NEEDS-SYNC	ファイルが不足している、またはリモートのほうが新しい	downstream /sync-template を実行

レポートには OKF v0.1 の1行も含まれます：✓ OKF v0.1: N/N concept đạt chuẩn（すべての concept に YAML frontmatter と type がある場合）、または ⟳ OKF v0.1: x/N … cần migrate。これは「project は OKF に準拠していますか？」への簡易回答です。未準拠の場合は → python3 harness/scripts/okf-check.py --migrate。

3. 推奨に従って対応

• BEHIND / MISSING → /sync-template（downstream）を呼び出し、新しい／不足している pattern を取り込みます。
• DRIFT → 保持したい改善の場合は /sync-template upstream、誤って変更した場合は git checkout -- <file>。

4. sync 完了後 — version.json を更新

downstream sync によって pattern の内容が変更されるたびに、fingerprint を更新します：

python3 harness/scripts/health-check.py --update            # giữ nguyên version
python3 harness/scripts/health-check.py --update --bump patch   # khi PHÁT HÀNH bản mới (chỉ làm ở repo template)

--bump（major/minor/patch）は、新しい pattern version をすべての project に公開するときに、template repo Rheinmir/setup でのみ実行します。子 project では hash を pull 後に同期するため、--update（bump なし）のみ実行します。

Branches

ID	種類	条件	動作	スキップ／失敗	再合流
B01	user_optional	ネットワークがない／ユーザーがローカルチェックのみを希望	--offline を追加し、リモートの fetch を省略	フラグなしでネットワークエラーが発生した場合 → ローカル部分は引き続き報告（fail-open）	W02
B02	conditional_required	template repo Rheinmir/setup にいて、新しい pattern version をリリースする	--update --bump patch（major/minor/patch）	子 project → --update のみ	終了
B03	capability_optional	CI gate／hook 内で実行	--json および／または --fail-on behind,drift,missing	—	W02（または exit 2）

検証と停止条件

Status は health-check.py が決定的に計算します（hash + version の比較）。model が推測するものではありません。status が OK になったとき、または推奨された対応が完了し、--update で hash が同期されたときに停止します。

Examples

• Positive： セッション開始時に、リモートの orca の template_version のほうが新しい → NEEDS-SYNC（BEHIND）を報告 → /sync-template downstream を呼び出し → python3 harness/scripts/health-check.py --update を実行 → 再実行して OK が返る。
• Boundary/failure： マシンがオフラインで、--offline なしで実行 → リモートの fetch に失敗しても、ローカル部分（DRIFT/MISSING）は出力され、セッションはブロックされません。BEHIND グループは特定できません。

Reference — 他の skill との関係

• [[sync-template]] — health-check は診断（sync が必要かどうかを確認）、sync-template は実行（ファイルを pull／push）します。必ず health-check を先に実行し、その後に sync-template を実行します。
• harness/scripts/wiki-health.py — 同じ L4 層の関連ツールですが、確認するのは wiki の内容（リンク切れ、孤立ページ、古い情報）であり、pattern の version ではありません。

Origin

• Draft：llmwiki/wiki/sources/draft/150626-health-check-pattern-sync.md