NOTES GAP
Signed, per-function governance that travels with your code — proves it wasn’t stripped, and records whether the agent obeyed.
Notes Gap
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:
Co-location + per-entity granularity — governance is inline, attached to the exact entity it governs (more like a lint pragma than a policy file).
Cryptographic tamper-binding — HMAC-signs governance to the source; stripping or editing a directive is detectable.
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.
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 --strictInstall the commit-time gate:
git config core.hooksPath notesgap/hooksCI 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.
WE TAKE AI SAFETY VERY SERIOUS!
https://github.com/SpartanAltsoba/notesgap.git