kcp-harness — KCP compliance proxy

kcp-harness

🧾 実際の動作を見る — インタラクティブな KCP プレイグラウンド · 解説を読む

あらゆる AI エージェントのための、決定論的なナレッジガバナンス。

エージェントはプロジェクト内のすべてのファイルを読めます。なぜそのファイルを読んだのか、証明できますか？

KCP Harness は、AI コーディングエージェントとそのツールの間に配置される MCP コンプライアンスプロキシです。ナレッジに関わる呼び出しをインターセプトし、 kcp-agent の決定論的プランナー（14 ゲートのカスケード、LLM 不使用）を通してルーティングし、通常のエージェント操作の副産物としてコンプライアンス成果物（決定トレース、監査ログ、予算台帳）を生成します。

エージェントが利用するのはプロキシの MCP インターフェースだけなので、ガバナンスを迂回できません。プロキシはアクセス可能なナレッジを決定し、支出を追跡し、すべての決定を記録します。フェイルクローズ：ハーネスがリクエストを検証できない場合、エージェントには何も渡されません。

Agent (Claude Code / Cursor / Copilot / Windsurf / Cline / Crush / OpenClaw / ...)
  │
  │  MCP tool call
  v
┌─────────────────────────────────────────────────────────┐
│  kcp-harness                                            │
│                                                         │
│  classify → govern (14 gates) → execute → audit         │
│                                                         │
│  Side outputs:                                          │
│  · Decision traces     (per-request, deterministic)     │
│  · Audit log           (append-only JSONL)              │
│  · Budget ledger       (itemized, ceiling-enforced)     │
│  · Temporal drift      (plan validity over time)        │
│  · Approval tickets    (named-human sign-off, durable)  │
│  · Confidence verdicts (post-synthesis gate)            │
└─────────────────────────────────────────────────────────┘
  │
  v
Knowledge manifests (knowledge.yaml)

ドキュメント →

理由

企業に必要なのは、説明責任を果たせるエージェントです。監査可能で、再現可能で、予算管理され、時間的に固定されている必要があります。現在のエージェントは、なぜそのファイルを読んだのか証明できません。ハーネスはエージェントを置き換えることなく、コンプライアンスレイヤーを追加します。

維持するもの	ハーネスが追加するもの
エージェント（Claude Code、Cursor、Copilot、...）	決定論的なナレッジ選択
ワークフロー（コーディング、レビュー、リリース）	決定トレース（ユニットごとに 14 ゲート）
ツール（MCP サーバー、シェル、ブラウザー）	予算の適用（上限、通貨ごと）
	時間的ガバナンス（ドリフト検出）
	追記専用監査ログ
	リプレイ／反対尋問
	人間による承認ゲート（指名されたレビュアー＋ポリシーの引用）
	信頼度ゲーティング（合成後、人間にルーティング）

コンプライアンスレイヤーを販売できます。エージェントは差し替え可能です。

インストール

npm install -g kcp-harness

または、インストールせずに使用します：

npx kcp-harness --help

ネイティブ実行ファイル

Linux x64/arm64、macOS x64/arm64、Windows x64 向けのビルド済みバイナリ（Node/Deno 不要）をリリースから入手できます。自分でビルドするには：

npm ci && npm run build
deno compile --allow-read --allow-env --allow-net --allow-run \
  --node-modules-dir=auto --output kcp-harness dist/cli.js

クイックスタート

1. 初期化

kcp-harness init          # creates harness.yaml

2. エージェント連携を生成

kcp-harness integrate claude-code    # or: pi, cursor, copilot, windsurf, cline, continue, crush, openclaw

3. コーディングを開始

エージェントはナレッジへのアクセスをハーネス経由でルーティングするようになります。すべての決定が記録されます。

対応エージェント

エージェント	設定	連携
Claude Code	.mcp.json + PreToolUse フック	kcp-harness integrate claude-code
Cursor	.cursor/mcp.json + .mdc ルール	kcp-harness integrate cursor
GitHub Copilot	.vscode/mcp.json（"servers" キーを使用）	kcp-harness integrate copilot
Windsurf	グローバル設定 + .windsurfrules	kcp-harness integrate windsurf
Cline	MCP 設定 + .clinerules	kcp-harness integrate cline
Continue	.continue/mcpServers/*.yaml	kcp-harness integrate continue
Crush	crush.json + PrepareStep	kcp-harness integrate crush
OpenClaw	openclaw.json + プラグインフック	kcp-harness integrate openclaw
Pi	.pi/mcp.json + プロジェクトスキル	kcp-harness integrate pi

エージェントごとに MCP 設定形式、ルールファイル、固有の仕様が異なります。integrate コマンドがすべてに対応します。ガバナンスレイヤーは 1 つで、あらゆるエージェントに使えます。

仕組み

すべてのツール呼び出しは、5 段階のパイプラインを通ります：

1. RECEIVE      MCP JSON-RPC request from agent
2. CLASSIFY     Knowledge-navigation or pass-through?
3. GOVERN       14-gate cascade (audience → temporal → budget → ...)
4. EXECUTE      Call downstream tool / return content
5. AUDIT        Log decision to append-only audit log

分類器

分類器は各ツール呼び出しを調べ、ガバナンス対象のナレッジを扱うものかどうかを判定します。 docs/ がガバナンス対象の場合の Read("docs/api.md") は、プランナー経由でルーティングされます。package.json がガバナンス対象でない場合の Read("package.json") は、そのまま通過します。KCP ツール（kcp_plan、kcp_load）は常にガバナンス対象です。

ガバナー

自動モードが2つあり、さらにその両方より優先される人間による承認ゲートがあります。

• プラン優先（高速パス） — エージェントは最初に kcp_plan を呼び出します。ハーネスは承認済みのプランをキャッシュします。以降の読み取りはキャッシュ済みのプランに照らしてチェックされるため、再プランニングは不要です。
• 自動プランニング（フォールバック） — エージェントがプランニングせずにガバナンス対象のパスを読み取ると、ハーネスがプランナーを自動実行します。時間はかかりますが、kcp_plan を知らないエージェントにもガバナンスが適用されます。
• 人間による承認 — governance.approvals ルールに一致する呼び出しは、自動パスでの判断にかかわらず、指名されたレビュアーの確認待ち（pending）になります。チケットは再起動後も保持され、kcp-harness approvals CLI（またはカスタムの ApprovalProvider チャネル）で処理されます。処理には指名されたレビュアーとポリシーの引用が必要です。

14段階のゲートカスケード

すべてのナレッジユニットは、順番に14個の決定論的なゲートで評価されます。

audience → not_for → temporal → deprecated → supersession → relevance →
skill_eligibility → attestation → payment → access → strict → max_units →
money_budget → context_budget

ユニットはすべてのゲートを通過する必要があります。ブロックしたゲートは判断トレースに記録されます。同じ入力なら同じプランになります。モデルは関与しません。

skill_eligibility ゲートの対象領域、つまりガバナンス対象の kind: skill ユニットについては、作成規約、リンター、適合性テストベクトルが Cantara/kcp-skill にあります。

MCP ツール

接続すると、エージェントは次のガバナンスツールを使用できます。

ツール	説明
kcp_plan	決定論的なロード計画 — 対象ユニット、読み込み順、スキップされたユニットとその理由
kcp_load	プランを作成し、対象となるユニットの内容を読み込みます
kcp_trace	14段階すべての判断トレース
kcp_validate	knowledge.yaml をリントします
harness_status	現在のガバナンス状態
harness_session	このセッションで承認済みのプランと既知のユニット
harness_budget	明細付きの支出追跡
harness_temporal_check	プランのドリフト検出
harness_approvals	人間による承認チケット（保留中／承認済み／却下済み／期限切れ）
harness_assess	合成された回答に対し、実行前に信頼度ゲートを適用します

コンプライアンス成果物

監査ログ

追記専用の JSONL 形式です。ガバナンス対象かパススルーかを問わず、すべての判断がシーケンス番号、タイムスタンプ、ツール、対象、ガバナンス判断とともに記録されます。

cat .kcp-harness/audit.jsonl | jq 'select(.governed == true)'

予算台帳

追記専用の明細付き支出追跡です。通貨ごとの累計を記録します。上限を適用し、予算を超えるロードは原子的に拒否されます（部分的なロードは行われません）。

時間的ガバナンス

プランは時間監視機能に登録されます。以降の呼び出しでは、監視機能が現在時刻に照らして再評価します。ユニットの状態が変化した場合（期限切れ、または新たに有効になった場合）、ハーネスはドリフトイベントを出力します。長時間実行されるセッションでも、実態に即した状態を保てます。

承認チケット

承認ルールに一致する呼び出しは、永続的なチケットを開きます （pending_review → approved | dismissed | expired。一度限りの許可が消費された場合は used も含みます）。チケットストアは再起動後も保持されます — セッションは一時的なものですが、人間によるレビューはそうではありません。すべての解決記録には、誰が承認したか、いつ承認したか、どのポリシーを満たすかが記録されます — 承認時に生成される証拠であり、ログから再構成されることはありません。

承認は範囲が限定された許可であり、恒久的な権限ではありません。 チケットを開いたセッション、特定のツールと対象、呼び出しの引数ダイジェストが対象であり、期限が切れます。各ルールでは grant: once | session | <duration> を設定します（デフォルトは session）。常に governance.approvals.grant_max（デフォルトは 24h）が上限となります。有効な許可の範囲外の呼び出しは拒否され、grant_denied（expired、wrong_session、used など）として監査記録され、新しいチケットが開かれます。恒久的な権限は、クリックではなくポリシールールです。許可の有効期間は、レビュー担当者が指定した reviewedAt ではなく、ストア独自の時計を基準に計測されます。チケットの最初の有効な解決が優先されます（却下されたチケットは、行を追記しても再承認できません）。また、approvals.require_signed_resolutions を設定すると、署名は resolve() 内だけでなく、読み込みのたびに検証されます。approvals.require_args_binding を設定すると、呼び出しの引数に紐付けられていないチケットからの許可は拒否されます。チケットストアが保護しないもの — そのディレクトリへの書き込みアクセス — については、チケットストアの信頼モデルに記載されています。ガバナンスモデルを参照してください。

信頼度の判定

harness_assess は、合成された回答を実行に移す前に、kcp-agent の合成後の assess() を実行します。プランナーは読み込みを制御し、グラウンディングは断言を制御し、これは実行を制御します。ルーティングされた設定でしきい値を下回る判定が出た場合、判定全体を証拠として埋め込んだ承認チケットが開かれます。

設定

# harness.yaml
version: "1.0"

governance:
  domains:
    - manifest: "./knowledge.yaml"
      paths: ["docs/", "src/"]

  policy:
    fail_closed: true
    audit_all: true
    max_units: 5
    budget:
      amount: 1.00
      currency: USDC

  confidence:                  # optional post-synthesis gate (harness_assess)
    threshold: 0.7
    severity: critical
    route_to_role: account-owner

  approvals:                   # optional human-approval gates
    provider: file
    rules:
      - match: { tools: [Write, Edit], paths: [records/] }
        required_role: account-owner
        expires_after: 72h
        policy_ref: POL-7.2
        grant: session           # once | session | 15m / 4h / 1d  (default: session)
    grant_max: 24h               # hard cap on any approval's validity (default 24h)
    # require_signed_resolutions: true  # + trusted_keys: verify signatures on every read (recommended)
    require_args_binding: true   # refuse grants not bound to the call's arguments (recommended)

audit:
  path: ".kcp-harness/audit.jsonl"

CLI

kcp-harness serve  [--config harness.yaml]   Start the MCP proxy
kcp-harness init                             Create a harness.yaml template
kcp-harness check  [--config harness.yaml]   Validate configuration
kcp-harness integrate <agent> [options]       Generate agent integration files
kcp-harness integrate --list                  List supported agents
kcp-harness export   [options]               Export compliance evidence (SOC 2 / ISO 27001)
kcp-harness dashboard [options]              Launch the live compliance dashboard
kcp-harness approvals list [--state s]        List human-approval tickets
kcp-harness approvals approve <id> --reviewer <name> --policy-ref <ref>
kcp-harness approvals dismiss <id> --reviewer <name> --policy-ref <ref>

ライブラリ

import { classify, govern, BudgetLedger, TemporalWatch } from "kcp-harness";
import { generate, listAgents } from "kcp-harness";

// Classify a tool call
const result = classify("Read", { file_path: "docs/api.md" }, governedDomains);

// Generate integration files
const output = generate("claude-code", { manifest: "./knowledge.yaml", paths: ["docs/"] });

アーキテクチャ

┌──────────────────────────────────────────────┐
│  Layer 3: Integration Packages               │
│  Agent-specific configs + rules files        │
│  (claude-code, cursor, copilot, ...)         │
├──────────────────────────────────────────────┤
│  Layer 2: KCP Compliance Harness             │  ← THIS
│  MCP proxy — deterministic governance        │
├──────────────────────────────────────────────┤
│  Layer 1: kcp-agent (planner core)           │
│  14-gate cascade, decision traces            │
└──────────────────────────────────────────────┘

エージェントをフォークすると競争になります。ハーネスを使うと連携できます。

テスト

npm test     # 314 tests across 20 test files

分類器、ガバナー（承認の優先順位を含む）、承認ステートマシンとプロバイダー、信頼度ゲートの配線、プロキシ、監査、予算台帳、時間監視、証拠エクスポート、ダッシュボード、およびすべてのエージェント統合をカバーしています。

ライセンス

Apache-2.0 · eXOReaction AS による提供、Cantara のもとでホストされています。