KG-SSOT

---

理由

人やエージェントで構成されるチームでは、「再試行は冪等だ」「試行回数は3回に決めた」といった結論が積み重なります。 それらは会議メモ、チケット、チャットの記憶の中に残り、そこに至る過程で3つのことが失われます。出典、最終確認日、そして依存先です。この3つを欠いた説得力のある文は、慌ただしいレビューをすり抜けてしまいます。

KG-SSOT はこれを、規律の問題ではなくフォーマットの問題として扱います。ナレッジはコードの隣でバージョン管理される .kg.yaml グラフに格納され、正式な契約によって、CI で何を失敗とするかが決まります。

• confirmed または production のノードに出典がなければ失敗します（復元可能な出典がない主張は、代わりに unverifiable と宣言します）。
• プレースホルダー（unknown、n/a、tbd）だけの出典は失敗します。
• 存在しない場所を指すエッジは失敗し、エッジのないノードも失敗します。
• 照合対象がない検証スタンプ、由来のない決定、証言だけを根拠とする production の主張は、警告を出します。

60秒で始める

pip install kg-ssot

# the conformance suite against the reference reader, from the installed package
kg-conformance | tail -2

# one valid graph and one that fails
kg-validate valid.kg.yaml broken.kg.yaml

または、ハッシュ検証済みの依存関係を使ってリポジトリから直接実行できます。

git clone https://github.com/marciocar/kg-ssot && cd kg-ssot
python3 -m venv .venv && .venv/bin/pip install --require-hashes -r tools/requirements.txt
.venv/bin/python3 -I tools/kg_validate.py \
  spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml \
  spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml

PASS spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml
FAIL spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml
  MUST   form.required.node.label ×1
· 2 files; 1 pass the MUST; 0 with a SHOULD warning (kg-contract-v4.schema.json + kg-contract-v4.should.schema.json)

ツールはデフォルトで英語を出力し、ロケールが pt_BR（または KG_SSOT_LANG=pt-BR）の場合はブラジルポルトガル語で出力します。コード、終了コード、JSON キーは言語によって変わりません。変わるのは人間向けのテキストだけです。

インストール

チャネル	コマンド	得られるもの
PyPI	pip install kg-ssot	コントラクトとテストスイートを内包する、kg-validate、kg-conformance、kg-gate、kg-store、kg-query、kg-diff、kg-vocab、kg-criterion、kg-audit、kg-trace、kg-vector、kg-mcp、kg-prov-export コマンド。pip install "kg-ssot[vector]" で類似度検索が追加されます
npm	npm install kg-ssot	React Native と Expo でも動作する、バリデーターを事前コンパイルした JavaScript リーダー
Claude Desktop	最新リリースの .mcpb ファイル	ワンクリックで導入できる拡張機能としての MCP サーバー
MCP Registry	io.github.marciocar/kg-ssot	あらゆる MCP クライアントで使える同じサーバー
コンテナー	docker pull ghcr.io/marciocar/kg-ssot	LibreChat など、Python を使わないクライアントの隣でサービスとして動作する MCP サーバー
お使いのリポジトリ	kg_vendor.py update --tag kg-ssot-v4.30.0	タグで指定したリリースを sha256 スタンプ付きでベンダリングし、CI にゲートを追加します（マニュアル、第6章）

ノードの内部

- id: C_RETRY_SAFE
  node_type: claim
  plane: PROD
  status: confirmed
  impact: 4
  confidence: 0.8
  label: The payment retry is idempotent.
  verified_at: "2026-10-01"
  verified_against: tests/payment_retry_test.py
  provenance:
    source: tests/payment_retry_test.py
    locator: test_retry_is_idempotent
    method: "medição: integration test in CI"

label は短い主張です。provenance は、それがどこから、そしてどのように得られたかを示します。方法クラスは、 medição（測定）、leitura（読解）、juízes（審査員）、derivado（導出）、testemunho（証言）の5つです。 スタンプは、いつ、何を基準に検証されたかを示します。方法クラスはコントラクトのリテラル値であり、表記は そのままです。

AI エージェントから使用する

参照用 MCP サーバーは、モデルにコントラクトとストアを提供します。グラフを検証し、検証を通過したものだけを書き込み、 読み取り、一覧表示し、各エッジの接続先にあるラベルまで解決したクエリを実行し、履歴を表示します。読み取り専用のツールには その旨が注釈されているため、クライアントはそれらの確認を省略できます。

kg-mcp --root ./graphs          # stdio, for Claude Desktop, Claude Code and other MCP clients

kg_schema_help は現在のコントラクト、最小限の合格例、よくあるコードへの修正方法を返します。そのため、モデルは 最初の試行で合格するグラフを作成できます。llms.txt にはエージェント向けドキュメントのインデックスがあり、 llms-full.txt にはそのすべてが1つのファイルにまとめられています。

エージェントスキル。 skills/kg-ssot/ は、コーディングエージェントにこれらのツールを使ったグラフの作成、 修正、検証、クエリ方法を教える Agent Skills スキルです。.kg.yaml と .kg.json に対応しています。 事前登録されたテストでは、このスキルを使ったエージェントは、出力トークンを45％、ツール呼び出しを54％に抑えながら、 同じ結果を得ました。

npx skills add marciocar/kg-ssot -s kg-ssot     # Claude Code, Codex and other clients that read Agent Skills

Claude Code では、プラグインとしても利用できます。/plugin marketplace add marciocar/kg-ssot を実行し、続いて /plugin install kg-ssot@kg-ssot を実行します。

仕組み

flowchart LR
  subgraph product["Product (one tag kg-ssot-vX.Y.Z)"]
    C["Contract<br/>JSON Schema MUST + SHOULD<br/>+ integrity rules"]
    S["Conformance suite<br/>438 cases as plain data"]
    R["Reference reader<br/>kg_validate.py"]
    S -- "every reader passes" --> R
    C --> R
  end
  subgraph adopter["Adopter repository"]
    V["vendor/kg-ssot<br/>+ sha256 stamp"]
    G["kg_gate.py in CI<br/>per-graph ratchet"]
    K["the team's .kg.yaml"]
    V --> G
    K --> G
  end
  product -- "kg_vendor.py update --tag" --> V
  G -- "nothing gets worse:<br/>a new graph passes,<br/>debt only shrinks" --> PR["PR approved"]

1. コントラクトは JSON Schema 2020-12 による2段階の定義です。MUSTに違反すると失敗し、SHOULDに違反すると警告します。スキーマで表現できないルール（ID の一意性、エッジの接続先の存在、孤立ノード）も含まれます。
2. テストスイートは互換性の証明です。各ケースは、期待される判定とコードを記載した実際の YAML ファイルであり、リーダーがまったく同じコードを出力した場合にのみ合格します。
3. キットはタグで指定したコントラクトをスタンプ付きでリポジトリに導入します。このスタンプによりローカルでの編集は失敗となり、CI ではグラフ単位のラチェットを実行します。すでに失敗していたものは債務として記録され、新しいグラフには合格が求められ、債務は減る一方です。

機能

2段階の契約	MUST は失敗、SHOULD は警告となり、段階的に厳格化されます。あるバージョンで警告となるものが次のバージョンでは失敗となる場合があり、導入者は事前に把握できます
構造化された来歴情報	source、locator、method に加え、5つの証拠クラスとソースの所在（repo、web、host、pessoa、privado）を指定します
検証スタンプ	verified_at と verified_against を指定します。対象のないスタンプや、事実の日付より前に検証されたスタンプには警告が出ます
グラフ間のエッジ	external_edges を指定し、接続先がコーパスに含まれているか確認します
安定したコード	すべての違反に form.required.node.provenance のようなコードが付き、--where でノードが示されます
構造化された判定結果	kg_validate.py --format json は、コード、ドキュメントのパス、行番号、メッセージ、修正のヒントを含む判定結果を、バージョン管理された形式（spec/verdict.schema.json）で返します。ツールや MCP サーバーから利用できます
2つの形式、1つのモデル	差分での記述とレビューには .kg.yaml を、実行時の利用（アプリやサーバー）には .kg.json を使います。.kg.json は契約の JSON プロファイル（RFC 8259、I-JSON、最大128階層、キーの重複なし）に準拠した JSON パーサーで読み取られます
ゲート付きストア	kg_store.py は、契約に合格した場合にのみ、.kg.yaml または .kg.json をディスク、git リポジトリ、バージョン管理されたストアに書き込みます。ストア内の外部エッジを確認し、同時書き込みには楽観的ロックを使います
リファレンス MCP サーバー	kg_mcp.py は、ツールのアノテーション付きで、契約とストアを MCP 経由（stdio、またはアイデンティティごとの領域を設けたプロキシ背後の HTTP）で提供します
クエリと差分	kg_query.py はコーパス全体からノードを選択し、ページネーション対応で、すべてのエッジについて接続先のラベルも含めて出力します（kg-ssot.query/1）。kg_diff.py はチェックアウトせずに git を読み取り、ID ごとにフィールド単位でリビジョンを比較します（kg-ssot.diff/1）
ドメイン語彙	x_term プロファイルでは、各同義語に出典、ドキュメントのバージョン、検証日を指定します。kg_vocab.py はテキストを該当する用語に対応付け、期限が到来した項目を一覧表示し、SKOS-XL と Apache Ossie にエクスポートします（kg-ssot.vocab/1）。MCP サーバーはこれを kg_terms として提供します。4.23以降は、短いコードにスキーム内の読みやすい名前（notation と scheme）を設定でき、kg_vocab.py lint はラチェット付きで文章中のコードを確認します
事前登録された基準	x_criterion では、尺度の各バージョンにノードと sha256 を割り当て、x_measured_under で結果を測定時のバージョンに紐付けます。データを確認した後に尺度を変更すると事後的な警告が表示され、kg_criterion.py はテキストまたはファイルに対して sha256 を確認します（kg-ssot.criterion/1）
解決可能なトレース	kg_trace.py check --root . は、各ノードの trace: アンカーがリポジトリ内のファイルを指しているか確認し（integrity.trace-target-missing、kg-ssot.trace/1）、判定対象としないものは別途集計します
意味による検索	kg_query.py --text <term> --semantic "<question>" は、質問で別の言葉が使われていても該当するノードを見つけます。テキスト検索とローカルの多言語埋め込みモデルを RRF で統合します。オプション機能（kg-ssot[vector]）で、sha256 で固定されており、すべての判定の対象外です
質問ごとの監査パッケージ	kg_audit.py は、質問票の各項目につき1行を出力します（x_questionnaire プロファイル）。質問、回答、判定結果、必要な証拠と提示された証拠およびその日付と期限、証拠の要求（role: evidence_request と evidence_requirement）、矛盾、担当者、算出した不足項目を、CSV、XLSX（依存関係なし）、または JSON（kg-ssot.audit/1）で出力します
データのみのテストスイート	独自のメタスキーマを持つ438件のケースで構成され、JSON-Schema-Test-Suite 形式です
グラフごとのラチェット	大規模な一括移行をせずに導入できます。引き継がれた負債は明示されたまま、減少するだけです
タグによるベンダー管理	コピー＆ペーストも共有コードもなく、ファイルごとに1つの sha256 スタンプを付与します
プロファイル駆動型マイグレーター	kg_migrate.py は、導入者が宣言したルールに基づき、契約が求める provenance を提案します。まず計画を表示し、ノード単位の不変性を保って書き込みます
PROV-O ブリッジ	kg_prov_export.py は、各ノードの来歴情報を JSON-LD の prov:Entity と prov:Derivation として、W3C PROV エコシステム向けにエクスポートします。--edges を指定するとエッジが追加され、標準用語が存在する場合は cito:supports、cito:refutes、dcterms:replaces が使われます
プラットフォーム不要	Python 3.11 以降、PyYAML、jsonschema を、検証済みハッシュ付き（--require-hashes）でインストールします。サーバー、エディター、アシスタントは不要です

KG-SSOTが対象としないもの

必要なもの	…その場合は別のものを使用してください	KG-SSOTが提供するもの
大規模なグラフを対象とするクエリ言語	グラフデータベース	サーバー不要のファイル形式と契約
セマンティックウェブの相互運用性	RDF、OWL、SHACL	差分で読みやすい、小規模で閉じたYAML語彙とPROV-Oエクスポート
ドキュメントを対象とするエンタープライズ検索	検索プラットフォーム	コネクターもインデックスもなく、チームが書き込むグラフだけ
主張が真実であるという保証	人によるレビュー、テスト	どこから得た情報で、いつ検証されたかを記載しているという保証

ステータス

• 現行: 契約v4、リリースkg-ssot-v4.30.0。参照リーダーはlatest/の438ケース中424ケースに合格します。
• 利用状況: 3つの採用者がCIでゲートを実行しており、そのうち1つは本番環境で使用しています。
• 次の予定: v5では、現在は警告のみとなっている<class>: <detail>形式以外のmethodをエラーにします。
• 未対応: セマンティックレイヤー（鮮度、矛盾、ドメインの完全性）はoptional/にあり、参照リーダーは実装していません。ここでは有効な10ケースのみに合格します。

ドキュメント

マニュアル	概念、形式、契約、ツール、レシピ、トラブルシューティング
ADOPTING.md	あらゆる例外ケースを含む、採用ガイドの完全版
契約	契約v4：2つのレベル、コード、バージョン間の変更点
spec/conformance/	テストスイートの形式、コード、別の言語のリーダーを測定する方法
CHANGELOG.md	各リリースの記録（新しい順）
llms.txt · llms-full.txt	AI エージェント向け：リンク付きの索引と、ドキュメント全体をまとめたファイル

コントリビューション

契約の変更は適合性ケースから始まります。これは、動作と期待される判定を示す.kg.yamlです。 リリースは開発リポジトリのkg-ssot-vX.Y.Zタグです。このリポジトリでは、spec/または tools/に触れるすべてのプルリクエストで、CIがテストスイートとキットのテストを実行します。リリースミラーには各タグに含まれるものだけが格納され、タグごとに1つのコミットで構成されます。また、プルリクエストは受け付けていません。提案やバグは、該当するケースを添えて issueとして報告してください。別の 言語でのリーダーも歓迎します。その測定方法についてはマニュアル第7章で説明しています。

ライセンス

製品（リリースに含まれるもの。内容はspec/release.jsonに記載されています：契約、テストスイート、 .kg.yamlケース、tools/内のキット、ADOPTING.md、このREADME、マニュアル）はApache-2.0です： LICENSE。適用範囲はNOTICEに記載されています。

_{KG-SSOTはOnionフレームワーク内で生まれました。Onionは現在、他の採用者と同じようにタグ単位でKG-SSOTを採用しています。製品はOnionに依存しません。}