skill-provenance

スキル：skill-provenance

各スキルの出所と完全性を記録します。orca-sec-scans はコンテンツ内の脆弱性／シークレットをスキャンしますが、このスキルはサプライチェーンに関する別の2つの問い、つまりスキルがどこから来たのか、そしてインストール後にこっそり変更されていないかに答えます。ストアは fdk/skills.provenance.json です（出所＋記録日＋skills/<name>/ 内のすべてのファイルの sha256）。チェックサムを再計算して台帳と照合し、差異があれば MODIFIED、ディスク上にあるのに台帳に記録されていないスキルがあれば UNTRACKED と判定します。

WHAT

目的とコンテキスト

• 目的： 各スキルについて、台帳 fdk/skills.provenance.json（出所＋記録日＋すべてのファイルの sha256）とチェックサムを再計算するコマンドを使って、サプライチェーンに関する2つの問い、つまりどこから来たのか、そしてインストール後にこっそり変更されていないかに答えます。
• トリガー（使用するタイミング）：
  • 外部ソース（マーケットプレイス、別のリポジトリ、別プロジェクトのセッションでの蒸留）からスキルをインストール／蒸留した直後 → 出所とチェックサムを確定するために record を実行します。
  • スキルが外部から変更されていないか疑わしい、または確認したい → check を実行します。
  • 「このスキルはどこから来たのか」「スキルの出所を監査」「スキルのチェックサム」「スキルのサプライチェーン」といった質問がある場合。
  • CI で不明なスキルや、台帳を更新せずに変更されたスキルをブロックしたい場合。
• 対象外： スキルのコンテンツ内の脆弱性／シークレットはスキャンしません（これは orca-sec-scans の役割です）。スキルの出所を推測しません。

メンタルモデル

skills/<name>/ (ディスク上のファイル) → 各ファイルの sha256 → fdk/skills.provenance.json の台帳と照合 → OK | MODIFIED（差異あり）| UNTRACKED（ディスク上にあるが台帳に未記録）| MISSING（台帳にはあるがディスク上にない）。record = 台帳の項目を記録／上書きします。check = 読み取って照合します。

入出力の契約

	フィールド	必須？	意味
In	<name> または --all	record では必須	台帳に記録するスキル
In	--source	record では必須	URL、実在する repo#ref、または local-authored
In	--ci	任意	check で MODIFIED／UNTRACKED がある場合に exit 1 を返します
Out	fdk/skills.provenance.json 内の台帳項目	record の後	出所＋記録日＋sha256
Out	各スキルのステータス	check の後	OK／MODIFIED／UNTRACKED／MISSING ＋ exit code

ルールと機能

• RULE-01（MUST）：出所を捏造しないでください。 --source には実在する URL／ref または local-authored を指定します。出所情報が誤っているのは、情報がないよりも悪いことです。
• RULE-02（MUST）：有効なインストール／変更のたびに record を実行してください。 台帳を唯一の信頼できる情報源とします。スキルを変更して再記録しないと、意図どおり、CI によって不明な変更としてブロックされます。
• RULE-03（MUST）：orca-sec-scans の代わりにはなりません。 このスキルは出所と完全性を扱い、コンテンツの脆弱性／シークレットはスキャンしません。両方を使用してください。
• RULE-04（MUST）：check --ci では MISSING（スキルが削除済み）はエラーではありません。ブロックするのは MODIFIED／UNTRACKED のみです。
• RULE-05（MUST）：ストア fdk/skills.provenance.json はキュレーション対象のファイルです。スキルの変更と一緒にコミットし、乖離させないでください。
• 機能：スキルファイルの読み取りとハッシュ計算、ローカルの出所台帳への書き込み。ネットワークアクセスはありません。

失敗時の境界

• スキルの実際の出所がわからない場合 → ユーザーに確認し、推測した --source を記録しないでください。
• check --ci で MODIFIED／UNTRACKED が見つかった場合 → 失敗（exit 1）です。意図した変更なら再記録し、不明な変更なら調査してください。
• MISSING → 報告しますが、ブロックしません。

HOW

メインワークフロー

Step	Type	Inputs	Action	Outputs/exit	Failure/next
W01	effect	空の台帳	1 回だけ record --all --source local-authored を実行	完全な台帳	台帳がすでにある → スキップ
W02	effect	新しいスキル + 実際のソース	record <name> --source …	台帳エントリ	ソースが不明 → 確認
W03	deterministic	台帳 + ディスク	check（すべて、または特定のスキル）	OK/MODIFIED/UNTRACKED/MISSING	—
W04	deterministic	台帳 + ディスク	CI ゲート check --ci	exit 0/1	MODIFIED/UNTRACKED → exit 1
W05	effect	意図的に変更したスキル	元のソースで再記録	新しいチェックサム	再記録しない → W04 が失敗

各ステップの詳細（W01～W05 の正とする情報源）：

1. 1 回だけバックフィル（台帳が空の場合）— 既存のすべてのスキルを自作として記録します：

   python3 fdk/tools/skill-provenance.py record --all --source local-authored
   

2. 新しいスキルをインストール／追加するとき — 実際のソース（URL、repo#ref、または local-authored）を記録します：

   python3 fdk/tools/skill-provenance.py record <name> --source "https://github.com/<owner>/<repo>#<ref>"
   

3. 整合性を確認します。いつでも実行でき、OK / MODIFIED / UNTRACKED / MISSING を出力します：

   python3 fdk/tools/skill-provenance.py check          # xem tất cả
   python3 fdk/tools/skill-provenance.py check <name>   # một skill
   

4. CI ゲート — MODIFIED または UNTRACKED がある場合は exit 1 になります（.github/workflows/skills-sync.yml に組み込み済み）：

   python3 fdk/tools/skill-provenance.py check --ci
   

5. スキルを意図的に変更した後は、record <name> --source <元のソース> を再実行してチェックサムを更新します。そうしないと、check --ci は MODIFIED を報告します（これは正しい動作です。すべての変更を台帳に記録する必要があります）。

分岐

ID	Kind	Guard	動作	スキップ／失敗	再合流
B01	conditional_required	台帳が空	W01 でバックフィル	台帳がすでにある → スキップ	W03
B02	recovery	check が MODIFIED を報告	意図的な変更 → W05 で再記録。不明な変更 → 未確認の変更として調査	—	W03
B03	recovery	check が UNTRACKED を報告	新しいスキルが正当なもの → W02 で実際のソースを指定して記録	ソースが不明 → 確認	W03

検証と停止条件

完全に決定論的です。skill-provenance.py のチェックサムと終了コードで判定します。人による確認が必要なのは、--source が実際のソースを示しているかどうかです。check がすべて OK（MISSING は許容）を出力したら停止します。

例

• 正常例： https://github.com/acme/skills#v1.2 からスキルを取得した直後に、python3 fdk/tools/skill-provenance.py record foo --source "https://github.com/acme/skills#v1.2" を実行 → check foo が OK を出力します。
• 境界条件／失敗例： skills/foo/SKILL.md を変更して再記録しない → check --ci が MODIFIED foo を出力し、exit 1 になります。ユーザーが「foo の出所は？」と尋ねても誰も分からない → 推測で --source を記録せず、確認します。