設計の理由

SkillPact の設計判断の記録です。それぞれ、決めたこと、理由、採らなかった案を書きます。参考情報です。

DR-1 6 種類の効果#

決定：read、write、network、exec、spend、send。 理由：ツールに権限を与えるときに人が実際に判断する単位です。spend と send はコンピューターの外（お金、人）に届き、取り消せないので network と分けました。 採らなかった案：自由な権限の一覧（スキル同士を比べられない）、特定のハーネスのツール名をそのまま使う（1 社に縛られる）、もっと少ない区分（別々に判断すべきものが混ざる）。

DR-2 3 つのレベル#

決定：L1 宣言済み、L2 テスト済み、L3 署名済み。 理由：レベルごとに 1 種類の根拠（整合性、観測した振る舞い、身元と完全性）が加わります。バッジにできるほど単純です。 採らなかった案：点数（持っていない精度があるように見える）、「安全」のレベル（証明できない）。

DR-3 署名に JCS（RFC 8785）、role も署名する#

決定：0.8 から {"contract", "role"} を JCS にしたものに署名。 理由：JCS は公開された標準で、独立した実装があります。2 つの実装（Python、TypeScript）はファズのすべてのケースで一致します。role を含めることで、reviewer の署名を author に付け替えられなくなります。 採らなかった案：ファイルそのものに署名（空白の違いで壊れる）、独自の並べ方（0.1〜0.3 で使ったが、小数を確実に表せなかった）。

DR-4 ed25519 と Sigstore#

決定：両方を使えるようにする。 理由：ed25519 は公開鍵があればオフラインで検証でき、署名も小さい。Sigstore は鍵を管理せずに CI やアカウントの身元と署名を結び付けられます。 採らなかった案：GPG（鍵の扱いが複雑）、Sigstore だけ（完全な検証にオンラインの基盤が要る）。

DR-5 ファイル名と置き場所#

決定：SKILL.md の隣に skill.contract.json。 理由：SKILL.md を変えないので、SkillPact を知らないハーネスに影響しません。名前が 1 つに決まっていれば見つけやすい。 採らなかった案：frontmatter の項目（SKILL.md が変わり、文章と機械用のデータが混ざる）、中央のレジストリ（対象外）。

DR-6 YAML ではなく JSON#

決定：I-JSON の制限つきの JSON。 理由：解釈が 1 つに決まる（YAML には複数の版と暗黙の型変換がある）、JSON Schema の道具がどこにでもある、署名用の標準の正規形（JCS）がある。 採らなかった案：YAML（型があいまいで正規化しにくい）、TOML（正規形がない）。

DR-7 テストはオフラインのサンドボックスで#

決定：ネットワークの隔離、読み取り専用のファイルシステム、環境変数の許可リスト。 理由：結果が外の世界に左右されず、テストがデータを漏らしたり利用者のファイルを変えたりできません。 採らなかった案：全権限でテストを実行（危険）、テストなし（L2 がただの申告になる）。

DR-8 全ファイルの網羅（0.8）#

決定：integrity には短い既定の除外と許された除外を除くすべてのファイルを載せる。エージェントへの指示ファイルは除外できない。 理由：0.7 の自己レビューで、載っていない入口スクリプトや CLAUDE.md が署名を壊さずに振る舞いを変えられることが分かったためです。

DR-9 インストール前だけを担い、実行時へは書き出す#

決定：SkillPact はインストール前に確かめ、APS / ACS / HushSpec / Rego へ書き出す。 理由：実行時ポリシーの規格はすでにあり、もう 1 つ作ると分断を招きます。

DR-10 英語を規範、日本語は翻訳#

決定：0.8 から英語版を規範とする。 理由：実装者の多くは英語を読みます。日本語訳は編集者が保守します。