AIP-7: agentgovernance/v1 — audit, approval & policy primitives

Abstract

agentgovernance/v1 is an open file-format standard for recording approvals, audit logs, and autonomy policies as workspace files. It provides a vendor-neutral, filesystem-first, third-party-verifiable primitive for any system — human, agentic, or hybrid — that needs auditable decisions. Three doctypes: signature (universal approval event), audit-event (append-only hash-chained log line), policy (declarative autonomy rule).

Motivation

Auditability in agentic systems is typically vendor-locked: each platform keeps approvals and logs in its own database, with proprietary formats and no cross-platform verification. agentgovernance/v1 makes the artifacts themselves portable and verifiable: a workspace receiving these files can validate every doctype and verify the audit chain end-to-end without trusting the originating system.

The standard is domain-agnostic: signature/audit/policy reference no business concepts. Any workflow that needs auditable approvals — clinician overrides, approve-to-publish flows, AI agent action gates, board votes — adopts the spec directly.

Specification

Full normative text is in packages/governance/core/AGENTGOVERNANCE.md. AIP-7 will absorb that text in full as part of moving Draft → Review.

Conventions adopted:

• Markdown canonical with YAML frontmatter (for POLICY.md)
• JSON canonical for signature.json and audit-log.jsonl lines
• Slug-based references, never database IDs
• schema: agentgovernance/v1 on every doctype
• Vendor-specific extensions under metadata.<vendor>.*
• Git-native workspace layout

The hash-chain protocol for audit-event is published separately and allows third-party verifiers in any language to validate the chain.

Rationale

To be authored. Defend: hash-chained append-only over signed snapshots, per-event JSONL over batched JSON arrays (streaming-friendly), markdown for POLICY.md (human-authorable autonomy rules), peer-standard status to AIP-6 instead of merging into one mega-spec.

Reference Implementation

packages/governance/core — parser, validator, hash-chain implementation, and policy evaluator.

Backwards Compatibility

Not applicable — first version of the spec.

Security Considerations

Audit-log integrity is the central invariant. The hash chain is verifiable end-to-end by any third party using the published protocol. Threats:

• Tampering: detected by hash mismatch on any altered prior event.
• Truncation: head-pointer attestations (separate, vendor-specific) guard against silent truncation.
• Replay: audit-event includes monotonic sequence numbers and timestamps; replay attacks are detectable.
• Signature spoofing: signers identify themselves with cryptographic keys; the spec is key-format agnostic but RECOMMENDS Ed25519 or Sigstore-style transparency-log signatures.