constraints-registry

制約レジストリ

AI 生成コード向けのポリシー・アズ・コードのガードレールです。 MCP サーバーが コード生成時にコーディングエージェント（Claude Code、Cursor、Codex）へエンジニアリング制約を提供し、 OPA、Conftest、Checkov、Semgrepで成果物を検証します。

エンジニアリング上の制約（インフラストラクチャ、組織、アーキテクチャ）を集約した、単一のクエリ可能な情報源です。コーディングエージェント（Claude Code、Cursor、Codex、…）がコード生成時に参照できるよう、MCP サーバー経由で公開します。制約をそれ自体で強制することはありません。エージェントにガイダンスを提供し、決定論的な検証は既存の強制エンジン（OPA、Conftest、Checkov、Semgrep）に委譲します。

制約はソースリポジトリで作成し、不変でバージョン管理されたバンドルに集約して、MCP 経由で提供します。これにより、エージェントは次の操作を行えます。

1. describe_scope — 有効なセレクターの語彙を確認します。
2. get_constraints — 構築対象に関連するルールを取得します。
3. validate — 候補の成果物を、紐付けられた強制エンジンに照らして確認します。

正式な要件：constraint-registry-v0-spec.md。 要件 → コンポーネント → テストの対応表：TRACEABILITY.md。

---

目次

• 機能
• 前提条件
• クイックスタート
• MCP サーバーの実行
• コーディングエージェントとの統合
• 制約の作成
• ホットリロード
• 検証ハーネス
• 強制エンジンの追加
• リポジトリ構成
• コントリビューション
• ライセンス

---

機能

• 3 種類の制約カテゴリ — インフラストラクチャ、組織、アーキテクチャ。関係性を表すセレクター（例：「ドメイン境界を越えた同期呼び出しは禁止」）と、助言的な（強制なしの）制約も含みます。
• 複数ソースの集約 — 多数のソースリポジトリからインポートできます。ID はソースごとに名前空間化され、決定論的でコンテンツハッシュに基づく不変のバージョン管理されたバンドルを作成します。
• 優先順位とドリフト防止 — 設定可能なデフォルトポリシー（強いルールが弱いルールに優先。同じスコープに対し、下流のソースがより高い優先順位のルールを緩和することはできません）。フィクスチャによる相互チェックで、ガイダンスと強制の乖離を防ぎます。
• プラグイン可能なエンジン — 安定したアダプターインターフェースと、4 つの実際のアダプターを備えています。OPA と Conftest（Rego ポリシー）、Checkov（IaC スキャン）、Semgrep（アプリケーションのソースコード）です。SARIF を出力するエンジンは共通の正規化処理（adapters/sarif/）を利用するため、新しい SARIF エンジンの追加は主に配線作業で済みます。エンジンの追加は、アダプター 1 つと設定 1 行で行えます（強制エンジンの追加を参照）。
• カタログインポーター — Checkov と Semgrep には、エンジンのルールカタログ／ルールセットを、ドラフトの制約スタブ（ライセンスとソースの来歴情報付き）に変換するインポーターが付属しています。人が内容を充実させるためのもので、ソースの立ち上げを迅速化できます。
• MCP サーバー — stdio または共有 HTTP エンドポイント経由で、3 つのツール（describe_scope、get_constraints、validate）を提供します。get_constraints はフェイルオープンであるため、エージェントが処理を妨げられることはありません。
• ホットリロード — サーバーは定期的に再インポートできるため、再起動せずに制約の変更を反映できます。
• 検証ハーネス — レジストリと制約セットの内部整合性を検証します。機械可読な JSON を出力し、失敗時にはゼロ以外の終了コードを返します。

---

前提条件

ツール	必須？	備考
Python ≥ 3.11	はい	パッケージは 3.11 以降を対象としています
uv	はい	venv を管理し、エントリーポイントを実行します
OPA（opa）	Rego の validate／フィクスチャとの相互チェックに必要	参照用のポリシー適用エンジンです
Conftest（conftest）	任意	2 つ目の Rego エンジンです。インストールされていない場合、そのチェックは SKIP されます
Checkov（checkov）	任意	IaC スキャンエンジンです。インストールされていない場合、そのチェックは SKIP されます
Semgrep（semgrep）	同梱	ソースコード用エンジンです。uv sync によって自動的にインストールされます

macOS に外部エンジンをインストールします：

brew install opa conftest checkov   # semgrep is installed by `uv sync`

各エンジンは任意で、相互に独立しています。エンジンのバイナリが PATH にない場合、そのエンジンを必要とするテストやハーネスのチェックは、 失敗ではなくスキップされます。レジストリと get_constraints／describe_scope によるガイダンスは、エンジンがなくても 機能します。validate と、そのエンジンに関連付けられた制約のフィクスチャとの 相互チェックを実行する場合にのみ、エンジンが必要です。

---

クイックスタート

git clone https://github.com/SureshKhemka/constraints-registry.git
cd constraints-registry

uv sync                      # create the venv + install deps (incl. semgrep)

uv run cregistry-harness     # run the validation harness against the bundled samples

ハーネスは機械可読な JSON を出力し、失敗があるとゼロ以外の終了コードで終了します。 正常に実行された場合は、次のようになります：

{ "passed": true, "summary": { "pass": 21, "fail": 0, "skip": 0, "total": 21 }, "checks": [ ... ] }

（skip は、conftest のような任意のエンジンがインストールされていない場合にのみ使われます。）

---

MCP サーバーの実行

トランスポートは 2 種類あります。ツールの接続方法に応じて選択してください。

# stdio (default): each tool launches its own copy; nothing to manage
uv run cregistry-mcp

# one shared HTTP server every tool connects to (recommended for multiple tools)
uv run cregistry-mcp --http --port 8765 --reload-interval 60

フラグ：--transport {stdio,http,sse}、--http（短縮形）、--host （デフォルト 127.0.0.1）、--port（デフォルト 8765）、--config （または $CREGISTRY_CONFIG）、--reload-interval SECONDS（0 = オフ）。

共有 HTTP サーバーを管理します：

lsof -ti tcp:8765 | xargs kill     # stop
# restart = stop + start

運用ガイドの全文（停止／再起動、macOS の launchd による自動起動、 リポジトリ同期／分離のパターン）：docs/RUNNING.md。 ツールの入出力仕様：docs/MCP_CONTRACT.md。

---

コーディングエージェントとの統合

サーバーは 3 つのツールを公開します：describe_scope、get_constraints、validate。

Claude Code

# shared HTTP server (start it first, see above), available in every project:
claude mcp add --scope user --transport http constraint-registry http://127.0.0.1:8765/mcp

# OR stdio (no separate server to run; Claude launches it):
claude mcp add constraint-registry -- uv run --directory "$(pwd)" cregistry-mcp

claude mcp list   # should show: constraint-registry ... ✔ Connected

Cursor（~/.cursor/mcp.json）

{ "mcpServers": { "constraint-registry": { "url": "http://127.0.0.1:8765/mcp" } } }

Codex／stdio のみをサポートするその他のツール

command: uv、args: ["run","--directory","/abs/path/to/repo","cregistry-mcp"] を指定して、MCP サーバーを設定します。

エージェントに確実に参照させる

エージェントはツールを自動検出しますが、コード生成の前にレジストリを参照させるには、 プロジェクトまたは ~/.claude/CLAUDE.md に次の指示を追加してください：

AWS／インフラのコードを書く前に、constraint-registry MCP を呼び出してください。まず describe_scope で有効なセレクター値を確認し、次に適切なスコープを指定して get_constraints を呼び出し、 すべての hard 制約を、譲れない下流ゲートとして遵守してください。 必要に応じて validate で結果を検証してください。

---

制約の作成

ソースとは、constraints/*.yaml（制約を 1 ファイルにつき 1 つ）を含むディレクトリです。 任意で policies/（エンジンポリシー）や fixtures/（サンプル成果物）も含められます。 ソースとエンジンは registry.config.yaml に登録します：

sources:
  - { name: platform-security, path: sources/platform-security, precedence: 100 }
  - { name: data-platform,     path: sources/data-platform,     precedence: 50  }
engines:
  - { name: opa,      adapter: "cregistry.engine.adapters.opa:OpaAdapter" }
  - { name: conftest, adapter: "cregistry.engine.adapters.conftest:ConftestAdapter" }
  - { name: checkov,  adapter: "cregistry.engine.adapters.checkov:CheckovAdapter", options: { min_level: warning } }
  - { name: semgrep,  adapter: "cregistry.engine.adapters.semgrep:SemgrepAdapter", options: { min_level: warning } }
precedence_policy: default

制約の例（sources/platform-security/constraints/aws-s3-no-public-access.yaml を参照）：

id: aws.s3.no-public-access
title: "S3 buckets must not be publicly accessible"
intent: "Public buckets are the top source of data-exposure incidents."
category: infrastructure          # infrastructure | organizational | architectural
scope:
  providers: [aws]
  resource_types: [aws_s3_bucket] # Terraform resource ids (NOT "s3_bucket")
  environments: [all]
  repos: ["tag:data-plane"]
severity: hard                    # hard | soft | advisory
enforcement:                      # omit for an advisory (guidance-only) constraint
  - { engine: opa, policy: policies/s3_public.rego }
guidance:
  do:   ["Attach an aws_s3_bucket_public_access_block with all four flags true"]
  dont: ["Never set acl = 'public-read' or 'public-read-write'"]
  example_compliant: |
    {"resources": {"aws_s3_bucket": {"data": {"acl": "private", "public_access_block": true}}}}
owner: platform-security
version: 1.0.0
fixtures:                         # optional; cross-checked against the engine
  pass: fixtures/s3_private.json
  fail: fixtures/s3_public.json

スコープに関する注意事項（エージェントからクエリする際に重要です）：

• resource_types には、対象ツールの識別子を使います（Terraform の場合は aws_s3_bucket）。 正確な語彙を確認するには describe_scope を呼び出してください。
• あるディメンションがクエリから省略されている場合は広く一致します。一方、制約のセレクターと矛盾する 値が指定されている場合、その制約は除外されます。関係性スコープ付きの制約は、一致する関係性が指定されたクエリにのみ返されます。
• 作成後、uv run cregistry-harness を実行して、スキーマ、優先順位、フィクスチャを検証してください。

---

ホットリロード（制約の変更時に再起動不要）

--reload-interval N を指定してサーバーを実行すると、N 秒ごとにディスクから再インポートし、コンテンツが変更されている場合は新しい不変のバンドルを公開します。

uv run cregistry-mcp --http --port 8765 --reload-interval 60

• 変更がない場合は何も行いません。以前のバンドルバージョンは ID で引き続き指定できます。
• 再インポートに失敗した場合（解決できない優先順位の競合など）、最後に正常だったバンドルを提供し続け、理由をログに記録します。サーバーが停止することはありません。
• サーバーは設定されたソースパスから読み込むため、チームの制約リポジトリをそれらのパスに同期／プルするよう設定してください（別の運用ジョブで、たとえば cron による git pull や CI からの公開など）。コードや依存関係の変更には、引き続き再起動が必要です。

---

検証ハーネス

uv run cregistry-harness は、同梱の自己完結型サンプルソースに対してエンドツーエンドの検証を実行し、スキーマ準拠、決定論的なインポート、不正な制約の分離、名前空間と優先順位、バージョン管理と非推奨化、エンジンインターフェースへの準拠（任意のアダプターで実行できる再利用可能なテストスイートを含む）、フィクスチャの相互検証／バインディングの不備の検出、MCP のコントラクト／スコープ設定／フェイルオープン、ホットリロードの動作を確認します。構造化 JSON を出力し、失敗がある場合はゼロ以外の終了コードを返すため、CI に適しています。

uv run cregistry-harness            # human-readable JSON to stdout, exit 0/1
uv run cregistry-harness --config path/to/registry.config.yaml

---

強制適用エンジンの追加

EngineAdapter インターフェースを src/cregistry/engine/adapters/ の下に新しいモジュールとして実装し、registry.config.yaml の engines: に1行追加して、既存の適合性テストスイートで検証します。スキーマ、インポーター、MCP サーバー、ハーネスを変更する必要はありません。詳しい手順は docs/ADDING_AN_ENGINE.md を参照してください。

---

リポジトリの構成

src/cregistry/
  model.py            constraint schema (Pydantic)
  loader.py           load + per-field schema validation
  config.py           registry config (sources, engines)
  importer.py         import → aggregate → bundle
  precedence.py       namespacing precedence / conflict resolution
  scope.py            scope matching (query + conflict)
  bundle.py store.py  immutable versioned bundles + store
  query.py validate.py  scoped queries + artifact validation
  integrity.py        fixture cross-check / anti-drift
  service.py          transport-independent service (+ hot reload)
  mcp_server.py       MCP server (stdio / http) + CLI
  engine/             stable engine interface, registry, and adapters:
    adapters/opa, adapters/conftest, adapters/checkov, adapters/semgrep
    adapters/sarif    shared SARIF normalization seam (used by checkov + semgrep)
  harness/            the validation harness (checks/*)
sources/              bundled sample source repos (constraints, policies, fixtures)
scenarios/            self-contained fixtures for harness edge cases
tests/                pytest suite: adapter conformance, fixtures, import, e2e
docs/                 RUNNING.md, MCP_CONTRACT.md, ADDING_AN_ENGINE.md
deploy/               launchd template for auto-starting the HTTP server
CONTRACTS.md          the frozen engine-adapter seam new adapters code against

アダプターのテストスイートは uv run pytest で直接実行できます。

---

コントリビューション

バグ報告、新しいエンジンアダプター、制約ソース、ドキュメントなど、コントリビューションを歓迎します。エンジンの追加は意図的にシンプルにしてあります。アダプターモジュール1つと設定1行を追加するだけで、スキーマ、インポーター、MCP サーバー、ハーネスを変更する必要はありません。

• 開発環境のセットアップ、規約、エンジンアダプターのチェックリストについては、CONTRIBUTING.md をお読みください。
• 周囲の人への配慮をお願いします。行動規範 をご確認ください。
• 脆弱性を発見した場合は、SECURITY.md に従って非公開で報告してください。

PR を作成する前に、uv run pytest と uv run cregistry-harness がすべて成功することを確認してください。CI では、すべてのプルリクエストで両方を実行します。

---

ライセンス

Apache License 2.0 の下でライセンスされています。著作権表示と、このプロジェクトが統合する外部エンジンのライセンスについては、NOTICE を参照してください。