Aperture MCP

AI エージェントは今や、仕様書、計画書、ADR、憲章、AGENTS.md ファイルなど、あなたの作業を規定するドキュメントを書き換えています。編集のどこかで、以前に設定した制約がひそかに消えてしまうことがあります。

Aperture は「コミットメントの見落としを検知する仕組み」です。 気にかけているコミットメントを指定すると、意思決定ドキュメントの 2 つのバージョン間でそれが消えたときに、一言一句そのまま警告します。

*「コミットメントがひそかに消えた」*ことを検知するのは、見落としを検知する仕組みの役割です。イベント発生時に許可を求めることなく、確実に作動する必要があります。そのため Aperture は、まず最適な形でこのチェックを提供します。LLM を使わず、オフラインで動作する git pre-commit フック／CI チェックです。また、CLI と、エージェントがタスクの途中で呼び出すための MCP サーバーも提供します。MCP はアダプターの 1 つであり、製品全体ではありません。

これはシグナルであり、判定ではありません。 検知したら、調査するのは あなた です。 オプトイン方式 · ローカルで実行 · データをトレーニングに使用することはありません。

---

これは何か（何ではないか）

Aperture は、同じ意思決定の 2 つのテキスト状態（以前のバージョンと後のバージョン）を比較し、限定的で具体的な種類の意思決定の乖離を明らかにします。つまり、追跡対象のコミットメントの正確なテキストが消えたときに検知します。1 つのエンジンを複数の形で提供します。

• git pre-commit フック／CI チェック — 確定的な形式です。モデルを介さずにコミット／PR イベントで作動し、自動的にブロック（または警告）します。
• aperture check CLI — 任意の 2 つの git 状態間で、同じチェックを手動で実行できます。
• MCP サーバー — エージェントが編集の途中でチェックを呼び出せます（エージェントが 自分で 呼び出すことを選んだ場合にしか実行されないため、見落とし検知の仕組みとしては劣りますが、タスクの途中で使うには便利です）。

エンジンができること、できないこと：

• ✅ できること： あなたが 一字一句そのまま 登録したコミットメントがバージョン A に存在し、バージョン B から消えたときに検知します。コミット、セッション、作成者をまたいでチェックし、独自の見落としやすい点を明記した構造化された比較可能な結果を返します。
• ❌ できないこと： 意味を理解することです。大文字と小文字を区別しない部分文字列としてテキストを照合するため、言い換え／弱められたコミットメントは見落とします（約束が弱まっていても、削除されていないように見えます）。単に翻訳されたコミットメントについては、判定を控えます（文字体系をまたいで一字一句照合できないため、誤検知するのではなく degraded を返します）。また、単に書式を変更されたコミットメントを誤検知することもあります（語句の位置が変わっても、意味は変わっていません）。選択肢を順位付けしたり、品質を評価したり、変更が誤りだったと伝えたりすることはありません。その判断はあなたに委ねられます。 確定的な git フックを使えば、チェックが確実に作動するようになりますが、検知できる範囲が広がるわけではありません。シグナルの範囲は同じで、一字一句の一致を見ます。

一文で言うと、Aperture は消えたコミットメントを探す grep をコミット時に作動するようにしたものであり、検知できないものを正直に認めます。

---

クイックスタート（約 2 分）

pip install aperture-mcp   # installs the `aperture` CLI + the MCP server (wire the CLI as a git hook — see below)

PyPI パッケージ名が aperture-mcp なのは、aperture という名前がすでに PyPI で使われていたためです。-mcp という接尾辞は、パッケージ名に歴史的な事情で残ったものです。製品は Aperture であり、MCP は提供形態の 1 つにすぎません。pip install 1 回で、以下の 3 つすべてを利用できます。

1. 決定論的なトリップワイヤー — git の pre-commit フック／CI（LLM 不使用、オフライン）

.aperture.toml を作成します。ファイルごとに、ひっそりと消えてはならないコミットメントのウォッチリストを記述します。

fail_on_drop = true

[[watch]]
path = "CHARTER.md"
commitments = ["never train on your data", "data stays on the device"]

aperture check は 2 つの git の状態を比較し、ウォッチ対象のコミットメントが逐語的に消えていた場合にフラグを立てます。

aperture check                                    # HEAD vs working tree (default)
aperture check --staged                           # HEAD vs the staged index — for a pre-commit hook
aperture check --ref-a origin/main --ref-b HEAD   # any two refs — for CI on a PR

ウォッチ対象のコミットメントが削除されている場合、終了コード 1 によってコミットをブロックします（デフォルト）。--warn-only を指定すると、検出結果を表示しますが、ブロックはしません。標準ライブラリのみを使用し、ネットワークへの呼び出しは行わず、モデルも実行しません。

pre-commit フレームワークを使ってpre-commit フックとして設定します（このリポジトリの .pre-commit-hooks.yaml を使用します）。

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/jaysinailabs/aperture-mcp
    rev: v0.2.0
    hooks:
      - id: aperture-commitment-drift

…または、単独の .git/hooks/pre-commit として設定します。

#!/bin/sh
exec aperture check --staged

…または、すべての PR で GitHub Action としてCIで実行します（両方の状態を取得できるよう fetch-depth: 0 が必要です。詳細は examples/github-action/aperture-check.yml を参照してください）。

- uses: actions/checkout@v4
  with: { fetch-depth: 0 }
- run: pip install aperture-mcp
- run: aperture check --ref-a ${{ github.event.pull_request.base.sha }} --ref-b ${{ github.sha }}

まずは同梱のフィクスチャで動作を確かめてください（リポジトリをクローンしてください）。チェックアウト済みの変更前後のドキュメントを比較し、コミットメントが削除されていると検知します。セットアップ不要で、完全にオフラインで実行できます。 python3 examples/git_decision_drift/git_decision_drift.py

2. タスクの途中でエージェントから — MCP サーバー

エージェントが編集しながら呼び出せる、同じチェック機能です。（エージェントが呼び出すことを選んだ場合にのみ MCP ツールが実行されます。トリップワイヤーとしては git フックより確実性が低いものの、タスクの途中で使うには便利です。）

{
  "mcpServers": {
    "aperture-mcp": { "command": "aperture-mcp" }
  }
}

インストールを一切行いたくない場合は、代わりにクライアントから uvx を指定してください。 { "command": "uvx", "args": ["aperture-mcp"] }

3. または自分の Python から

from aperture import compare, Anchor, AnchorKind

result = compare(
    state_a="We commit to: ci-gates-green before release; data-never-leaves-device.",
    state_b="We commit to: data-never-leaves-device.",
    anchors=[Anchor(kind=AnchorKind.COMMITMENT, id="ci-gates-green")],
)
print(result.status)            # DROPPED_SILENTLY
print(result.anchor_violations) # the commitment that vanished

---

見覚えのある光景

長いタスクに取り組んでいると、エージェントは作業の基になるドキュメント（計画や仕様書）を、セッションや編集をまたいで何度も書き換えます。そして時折、大事な一文が……消えてしまいます。

「何かを削除する前に、必ず確認すること。」 消えた。 「ユーザーデータがデバイスの外に出ることはない。」 消えた。 「無料プランは無料のまま。」 消えた。

誰も消すつもりはありませんでした。誰も差分の 400 行すべてに目を通しません。

Aperture は、指定した行をそのまま監視します。コミットに組み込み、削除が確定する前に実行されるフックとして設定すれば、ドキュメントの内容を理解したり、良し悪しを判断したりせず、そこにあった約束を一語一句そのまま示し、今はなくなっていることを伝えます。これは判定者ではなく、トリップワイヤーです。また、ほかのことについては正直です。行を和らげたり、言い換えたり、削除する代わりに数字を変更したりすれば、検知をすり抜けます。その点は今のうちに知っておくとよいでしょう。

---

何を検知し、何を見逃すのか

Aperture はヒューリスティックです。独自の正解コーパスで評価した結果を、都合のよい単一のスコアではなく数値として公開しています。なぜなら、何を見逃すのかを把握することこそが、この製品の価値だからです。100 件のコーパスにおける再現率 0.400、適合率 0.667です。独立した LLM 判定パネルがラベル付けしたもので、実際にドリフトした 65 件のうち 26 件を検知し、フラグの約 3 件に 1 件は誤検知です。詳しい内訳はdocs/measured-limits.mdをご覧ください。

変更の種類	Aperture はフラグを立てますか？
監視対象のコミットメントがそのまま削除された	✅ 確実に検知します。これが得意な唯一のことです（コーパスの 24 件中 24 件）
コミットメントの言い回しが変更／弱められた（「必須」→「推奨」）	❌ 見逃します。テキストは依然として「一致」します
コミットメントが言い換え／再構成された	❌ 見逃します
数値／範囲／否定がひそかに変更された	❌ 見逃します
コミットメントが別の言語に翻訳された	⚠️ 判定を保留します（アブステイン）。自然言語のアンカーでは、スクリプトをまたいでそのまま比較できないため、誤検知を出す代わりに degraded を返します（コミットメントが削除され、かつ翻訳された場合は見逃します）

決定論的な仕組みにしても、検知範囲は広がりません。 Git フックは確実に実行されますが、それでも検知できるのはそのまま削除された場合だけです。上の ❌／⚠️ の項目はすべて、MCP と同様にフックでも見逃します。得られるのは、確認するタイミング（誰かが忘れずに尋ねなくても、コミット時にチェックすること）であり、見えるものが増えるわけではありません。

最後の項目ではアンカーのスタイルが重要です。 判定保留が適用されるのは、自然言語のアンカーです。クイックスタートで説明している ci-gates-green のようなコード識別子のアンカーは、翻訳の影響を受けないものとして扱われます。Aperture は言語が変わってもチェックを続けるため、そのトークンが完全に消えれば、引き続き DROPPED_SILENTLY を通知します（安定した識別子に対しては、通常これが望ましい動作です）。

要点： フラグはすべて*「ここを確認してください」として扱い、「これは間違っています」*とは決して受け取らないでください。また、何も通知されないからといって、ドリフトがなかったと決めつけないでください。Aperture はそのまま消失したケースをうまく検知し、それ以外はほとんど検知できないことを正直に示します。この限定的で信頼できるシグナルは、それ以上の能力があるかのように装わないからこそ役立ちます。

ご自身のドキュメントで、こうした見逃しのいずれかに遭遇しましたか？ それは私たちに送っていただける情報の中で、最も役に立つものです。約 30 秒で報告できます（実際の表現を記入するかどうかは任意です）。実際の見逃しを参考に、次に修正する内容を決めます。

git diff や grep ではだめなのですか？ 基本的なチェックは手作業で再現できます。Aperture が追加するのは、コミット／PR イベントで実行されるように組み込めること（フックまたは CI チェックとして）、さらにエージェントがタスクの途中で呼び出せること（MCP 経由）、そして構造化された方向性のある結果（ok／degraded／DROPPED_SILENTLY／…）を返すことです。また、人間がギャップを監査できるよう、結果に自身の見落としやすい点を明示します。これは、シンプルで分かりやすいチェックを使いやすくし、その限界を正直に示すものであり、より賢い検出器ではありません。

---

なぜ作られたのか

長期間にわたるワークフローや複数エージェントによるワークフローでは、ドリフトが発生します。ターン 3／セッション 1 でエージェント A が設定した制約が、40 ターン後、別のセッションでエージェント B によってひそかに編集されて消え、リリースされるまで誰も気付きません。Aperture は、エージェントが管理するドキュメントに設定できる事前チェックです。ひそかに消えてはならないコミットメントを指定しておけば、消えたときに警告を受け取れます。理想的には、変更が取り込まれる前、コミット時点で検知できます。

Aperture は意図的に小さく、分かりやすく作られています。判断を代行する AI ではなく、自分自身との一貫性を保つためのシグナルです。

---

対象ユーザー

（a） AI エージェントにリポジトリ内の意思決定ドキュメント（仕様、計画、ADR、憲章、AGENTS.md ファイル）を編集させており、（b） それらのドキュメントをバージョン管理しているチームや開発者です。エージェントが約束を記したテキストを編集するなら、ひそかに失うわけにはいかない内容について、コミット時、CI 内、またはタスクの途中で、低コストかつ正直なトリップワイヤーを利用できます。

---

プライバシー

• オプトイン方式でローカルに動作します。 Aperture はお使いのマシン上で動作します。git フック、CLI、MCP サーバーのいずれも同様です。ネットワーク通信は行いません。
• お客様のデータを学習に使うことはありません。 意思決定のテキストはお客様のものであり、プロセスの外に出ることはありません。
• 使用状況のログ記録はデフォルトでオフです。有効にした場合も、記録するのはメタデータ（タイムスタンプ、ツール、ステータス、件数）のみで、意思決定のテキストやコミットメントの表現は記録しません。

---

デモについての正直な説明

このリポジトリには、手作業で作成した小さな ADR のフィクスチャ（変更前／変更後のペア）が examples/git_decision_drift/fixtures/ に含まれています。ここでは Aperture が、意図的に撤回したコミットメントを正しく検出し、維持したコミットメントには反応しません。これは仕組みを忠実に示す例ですが、私たち自身が作成し、評価した一例にすぎません。実証しているのはトリップワイヤーの仕組みであり、シグナルの強さではありません。後者については、上記および docs/measured-limits.md に記載された、ファミリーごとの測定値をご覧ください。 現時点では外部の導入事例はまだありません。Aperture をご自身の意思決定ドキュメントで実行した場合、何を検出し、何を見逃したかをぜひお聞かせください。

---

プロジェクトのステータス

開発初期段階の1.0 より前であり、まだ本番環境のゲートとして使える段階ではありません。比較の契約（v0.2）は確定しており、適合性スイートでテストされていますが、パッケージ API は今後変更される可能性があります。互換性ポリシーについては VERSIONING.md、変更履歴については CHANGELOG.md をご覧ください。

見逃しに気づきましたか？改善にご協力ください

Aperture は見逃しを起こします。これは仕様です（あらゆる形式において、言い換えられたもの、表現が和らげられたもの、翻訳されたコミットメントは検出できません）。気にかけていたドリフトを見逃した場合や、書き換えを誤検出した場合は、ぜひお知らせください。それが最も価値のある貢献になります。

• 約30秒で完了し、アカウント情報や使用状況データは不要です。文面の共有も任意です → ドリフト事例を報告する。
• 実際の見逃しから、次に修正すべき盲点がわかります。また、文面の共有を選択した場合に限り、docs/measured-limits.md に掲載する数値の正確性を保つゴールドコーパスの事例に追加できます。

何かを自動収集することはありません（プライバシーをご覧ください）。共有が行われるのは、お客様が選択した場合のみです。 ご質問や「自分のケースにこのツールは適していますか？」といったお問い合わせは、GitHub Discussions へどうぞ。

その他の協力方法については、CONTRIBUTING.md をご覧ください。

ライセンス

Apache-2.0。