AI agents now rewrite the documents that govern your work — specs, plans, ADRs, charters, AGENTS.md files. Somewhere in the edit, a constraint you set earlier can quietly disappear.

Aperture is a commitment tripwire. You name the commitments you care about; it flags — word for word — when one of them vanishes between two versions of a decision document.

Catching "a commitment silently vanished" is a tripwire job: it should fire on an event, deterministically, without asking permission. So Aperture ships that check on the surface that fits it best first — a git pre-commit hook / CI check that runs with no LLM, offline — and also as a CLI and an MCP server for agents to call mid-task. MCP is one adapter, not the whole product.

A signal, not a judge. It trips; you investigate. Opt-in · runs locally · never trains on your data.

What it is (and what it is not)

Aperture compares two text states of the same decision — an earlier version and a later one — and surfaces a narrow, specific kind of decision drift: when a tracked commitment’s exact text disappeared. One engine, several surfaces:

• git pre-commit hook / CI check — the deterministic form. Fires on the commit / PR event with no model in the loop, and blocks (or warns) automatically.
• aperture check CLI — run the same check by hand between any two git states.
• MCP server — so an agent can call the check while it edits (weaker as a tripwire, since it only runs if the agent chooses to call it — but useful mid-task).

What the engine does and doesn’t do:

• ✅ It does: flag when a commitment you listed verbatim is present in version A and gone from version B — across commits, sessions, or authors. It returns a structured, comparable result with its own blind spots written on the label.
• ❌ It does not: understand meaning. It matches text as a case-insensitive substring, so it misses a commitment that was reworded / softened / paraphrased (it looks dropped-free even though the promise weakened); it declines/abstains on a commitment that was merely translated (it can’t compare verbatim across scripts, so it returns degraded rather than false-flag); and it can still false-flag a commitment that was merely reformatted (the words moved, the meaning didn’t). It does not rank options, score quality, or tell you a change was wrong. That judgment stays with you. Moving to the deterministic git-hook makes the check fire reliably — it does not widen what it can see. Same narrow, verbatim signal.

If you want one sentence: Aperture is grep for vanished commitments, wired to fire on commit — and honest enough to admit what it can’t see.

Quickstart (≈2 minutes)

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

The PyPI package is named aperture-mcp because the bare name aperture was already taken on PyPI. The -mcp suffix is a historical package-name artifact — the product is Aperture, and MCP is only one of its surfaces. One pip install gives you all three below.

1. The deterministic tripwire — git pre-commit hook / CI (no LLM, offline)

Create a .aperture.toml — a watchlist of the commitments that must not silently vanish, per file:

fail_on_drop = true

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

aperture check compares two git states and flags any watched commitment that disappeared verbatim:

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

Exit code 1 blocks the commit when a watched commitment dropped (the default); --warn-only prints the finding but never blocks. It’s stdlib-only, makes no network calls, and runs no model.

Wire it as a pre-commit hook — either through the pre-commit framework (uses this repo’s .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

…or as a standalone .git/hooks/pre-commit:

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

…or run it in CI as a GitHub Action on every PR (needs fetch-depth: 0 so both sides are available — see 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 }}

Kick the tires first with the bundled fixture (clone the repo): it trips on a dropped commitment against checked-in before/after docs, no setup, fully offline — python3 examples/git_decision_drift/git_decision_drift.py.

2. Mid-task, from an agent — the MCP server

The same check, callable by an agent while it edits. (An MCP tool only fires if the agent chooses to call it — a weaker delivery for a tripwire than the git-hook, but handy mid-task.)

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

Prefer zero-install? Point the client at uvx instead: { "command": "uvx", "args": ["aperture-mcp"] }.

3. Or from your own 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

A scene you’ll recognize

On a long task, your agent keeps rewriting the doc it works from — a plan, a spec — across sessions and edits. And every so often, a line that mattered just… vanishes.

“Always ask before you delete anything.” Gone. “User data never leaves the device.” Gone. “The free tier stays free.” Gone.

Nobody meant to drop them; nobody reads all 400 lines of the diff.

Aperture watches the exact lines you name. Put it on the commit — a hook that fires before the drop lands — and it won’t try to understand the doc or judge it; it just tells you which promise was there, word for word, and now isn’t. A tripwire, not a judge — and honest about the rest: soften a line, reword it, or change a number instead of deleting it, and it’ll slip past. Better you hear that now.

What trips it — and what slips past

Aperture is a heuristic. We measured it on our own gold corpus and we publish the numbers instead of a single flattering score, because knowing where it’s blind is the product — recall 0.400, precision 0.667 on a 100-case corpus, labeled by an isolated LLM-judge panel (it catches 26 of 65 real drifts; ~1 flag in 3 is noise), full breakdown in docs/measured-limits.md:

The deterministic surface doesn’t widen the aperture. The git-hook fires reliably — but it still only catches verbatim deletion. Every ❌ / ⚠️ row above is exactly as blind through the hook as through MCP. What you gain is when it checks (on the commit, without anyone remembering to ask), not what it can see.

Anchor style matters for that last row: the abstain applies to a natural-language anchor. A code-identifier anchor (the ci-gates-green style the quickstart teaches) is treated as translation-stable — Aperture keeps checking it across languages, so if that exact token disappears it still flags DROPPED_SILENTLY (usually what you want for a stable identifier).

Takeaway: treat every flag as “look here,” never as “this is wrong” — and never assume silence means nothing drifted. Aperture catches the verbatim disappearance case well and is honest that it catches little else. That narrow, reliable signal is useful precisely because it doesn’t pretend to be more.

Hit one of those misses on your own docs? That's the single most useful thing you can send us — report it in ~30s (your wording is optional). Real misses guide what we fix next.