オープンソースの宣言チェッカー

Agent Role Contracts

役割・書き込み範囲・レビュー担当の宣言を、エージェントの実行前に点検します。JSONをオフラインで読み、宣言の矛盾を、具体的なエラーコードで報告します。

チェッカーを試す GitHubで見る

リリース: npm の 0.1.0
ライセンス: MIT
動作環境: Node.js 22.5 以上
通信: インストール時のみ。チェックはオフライン

このページが説明するのは公開済みの 0.1.0 だけです。GitHub の main にある新しい変更は未リリースで、npm install では入りません。

書き込みが起きる前に、範囲の矛盾を止める

チーム宣言では、実装担当は src/ の下だけ書けることになっています。ところがタスクは secrets/ のファイルを指しています。チェッカーは両者を突き合わせて拒否します。

例バンドルでの宣言

role: implementer
allowed_write_scopes: ["src/**"]

例タスクの要求

inputs.scope: "secrets/production.txt"

例終了コード1。宣言どうしが食い違っています。

FAIL: explain (declarations only; execution NOT authorized)
TASK_WRITE_SCOPE_OUTSIDE_AUTHORITY task/inputs/scope:
  Task scope is outside declared write scopes for role implementer: secrets/production.txt

タスクの範囲を src/example.mjs に戻せば、同じコマンドが PASS を返します。

宣言に対して行う3つのチェック

以下の結果は、0.1.0 パッケージに同梱のサンプルで得られたものです。

AUTHORITY_CONTRADICTION
読み取り専用の役割に書き込み権限は付けられない
filesystem.write.scoped を許可と禁止の両方に挙げている役割や、読み取り専用なのに書き込みを持つ役割を指摘します。
SELF_REVIEW_DECLARED
実装担当が自分でレビューすることはできない
同じ役割を実装担当とレビュー担当の両方に置いたルートや、読み取り専用でないレビュー担当を拒否します。
ROLE_REFERENCE_UNKNOWN
参照先の役割が存在すること
バンドルにない役割（例: ghost）を指す関係は、見逃さずに報告します。

手元で試す

空のフォルダに公開版パッケージを入れ、同梱のスターター用サンプルをチェックします。

mkdir agent-role-contracts-first-check
cd agent-role-contracts-first-check
npm init --yes
npm install --ignore-scripts @netsujo/agent-role-contracts@0.1.0
npx --no-install agent-role-contracts explain \
  --bundle node_modules/@netsujo/agent-role-contracts/examples/starter-bundle.json \
  --task node_modules/@netsujo/agent-role-contracts/examples/starter-task.json \
  --format text

出力の例（Example・抜粋）

PASS: explain (declarations only; execution NOT authorized)
Accountable: implementer
Reviewers: reviewer
Human approval required: true

validate はバンドルだけを検査します。
explain は1つのタスクの書き込み範囲も検査します。
handoff は別に渡した引き継ぎ文書を検査します。

終了コード: 0 は PASS、1 はルール違反、2 はCLI・ファイルの問題で判定なしです。

FAIL を見るには、starter-task.json を starter-task-outside-scope.json に差し替えます。

PASS が意味すること

意味すること

渡された宣言が、このバージョンが適用するルールのもとで矛盾していない。
実行したコマンドが行った検査だけが対象です。validate はバンドル、explain は渡されたタスクも、handoff は渡された引き継ぎ文書も検査します。

意味しないこと

何かが実行・隔離・強制されたこと。エージェントの実行基盤でもサンドボックスでもありません。
本人性や証跡が検証されたこと、ファイルシステムが走査されたこと。
エージェントの出力がスキーマに合うこと、マージやデプロイが承認されたこと。
作業が安全であること。コマンドの出力にも、実行は許可されていない（NOT authorized）と必ず表示されます。

ドキュメント、パッケージ、詳しい解説

v0.1.0 の READMEコマンド、スキーマ、サンプル。
npm パッケージ@netsujo/agent-role-contracts@0.1.0
GitHub リポジトリソース、Issue、MITライセンス。
PASS は何を示すかチェッカーの限界まで書いた技術記事。