Notes Gap

Signed, per-function governance that travels with your code — proves it wasn't stripped, and records whether the agent obeyed.

Notes Gap is an inline, AI-readable code governance layer. Governance directives live in comments attached to the exact function, class, or file they govern — not in a separate policy file that can drift or be ignored. An enforcer turns them into ALLOW / WARN / DENY decisions. An HMAC layer cryptographically binds the governance to the source, so directives can't be silently stripped, injected, or downgraded without detection.

# @!RO @S!C @!NE
def decrypt_evidence(blob: bytes) -> bytes:
    # @!RO  = AI must not modify this   @S!C = critical sensitivity
    # @!NE  = must not exfiltrate data
    ...

The code declares its own governance. The agent reading it self-applies the rules. The system records whether they were honored — and the supply-chain gate refuses any commit that tampers with them.

---

Why it's different

Most agent-governance approaches keep policy in a separate artifact (a policy card, a config, a middleware layer). Notes Gap's distinct combination:

1. Co-location + per-entity granularity — governance is inline, attached to the exact entity it governs (more like a lint pragma than a policy file).
2. Cryptographic tamper-binding — HMAC-signs governance to the source; stripping or editing a directive is detectable.
3. Compliance audit — the system records whether the agent honored or violated each directive.

See PRIOR_ART.md for how this maps against Policy Cards, Policy-as-Prompt, MI9, and the Microsoft Agent Governance Toolkit.

Two enforcement planes (by design)

Plane	Posture	Why
Runtime (enforcer.py)	Cooperative + audited override	A live agent (e.g. crisis response) must keep latitude to act; every override is logged.
Dev-time / supply-chain (gate.py, pre-commit, CI)	Hard, non-cooperative	Runs at commit/CI only — never at runtime. Fails the build if governance was tampered with.

Teeth where they belong (protecting governance integrity in the pipeline); flexibility where it belongs (the live agent). The dev-time gate cannot interfere with a runtime decision because it never runs at runtime.

Proven (reproducible)

100% detection of governance tampering and signature forgery across 44 attacks, 0% false positives, ~1.3% file-size overhead. Full method + raw data in RESULTS.md — re-run with PYTHONPATH=. python benchmark/run_benchmark.py.

Quickstart

pip install pydantic

# 1. Baseline-sign your annotated code (needs your constitutional key)
export NOTESGAP_CONSTITUTION_HASH=<your-hash>
python -m notesgap.gate sign path/to/your/code

# 2. Verify nothing was tampered (exit 1 on tamper — wire into CI)
python -m notesgap.gate verify path/to/your/code --strict

Install the commit-time gate:

git config core.hooksPath notesgap/hooks

CI workflow: see .github/workflows/notesgap-gate.yml.

Design principle: transparency by default

All governance is human-readable and auditable. The standard forbids concealed instructions.

Encrypting a signature (proving who authored a rule) is fine. Encrypting a directive (hiding what a rule tells the model to do) is forbidden — concealed model-targeted instructions are exactly what makes prompt injection dangerous. A governance standard whose purpose is auditability must be structurally anti-concealment. Done right, the framework cannot become the attack tool, because the attack requires hiding instructions and the standard refuses to.

Spec

The annotation specification (six pillars: Identity, Authority, Mission, Ethics, Transparency, Termination) is in notesgap/SPEC.md.

License

Apache 2.0 (includes an express patent grant) — see LICENSE.

Status

v0.1 — public reference implementation. Threat model: THREAT_MODEL.md. Contributions welcome: CONTRIBUTING.md.