Agent Change Record

Agent Change Record (ACR) is a vendor-neutral evidence manifest for AI-authored software changes.

ACR records the task, approved plan, agent identity, Git range, policy decisions, verification results, evidence hashes, and merge readiness for a change. It is designed to live inside a Git repository and to be safe for public pull requests by default.

Why ACR exists

AI coding agents can produce useful changes faster than current review workflows can explain them. The missing layer is not another chat transcript. Reviewers need a compact, verifiable record that answers:

• what work was requested
• which plan was approved or waived
• which agent and toolchain performed the work
• what Git range changed
• which policy rules were evaluated
• what verification ran
• whether the change is merge-ready

ACR provides that record as JSON plus a JSON Schema.

Core principle

ACR is an evidence projection, not a source of truth.

The record should be generated from canonical workflow artifacts such as task state, plans, approvals, verification logs, policy decisions, and Git history. Validators should compare ACR back to those artifacts whenever local evidence is available.

Current version

• Specification: ACR v0.1.0
• Schema: spec/v0.1/acr.schema.json
• Human-readable spec: spec/v0.1/acr.md
• Validation semantics: spec/v0.1/validation.md
• Versioning: VERSIONING.md
• Governance: GOVERNANCE.md
• Package identity: @basilisk-labs/acr (private until the import surface is published)

Validation classes

ACR has multiple validation levels:

• schema-valid: JSON shape, enums, and required fields.
• local-valid: schema plus local evidence hashes, Git commits, ancestry, and record digest.
• ci-valid: local validation plus merge-gate rules for plan approval, verification, waivers, and policy decisions.
• merge-ready: CI-valid with result.merge_ready=true.

Schema-valid does not mean merge-ready. Tools MUST NOT treat JSON Schema success as approval to merge. Merge readiness is a semantic property checked by local and CI validators.

Examples

• examples/v0.1/schema-minimal.acr.json is a schema-valid draft record. It does not claim merge readiness and has record_digest=null.
• examples/v0.1/merge-ready.acr.json is a semantically merge-ready record with approval, evidence, verification, and a computed digest.
• Additional examples cover GitHub PRs, failed policy, waived verification, and high-risk changes.

Repository layout

spec/v0.1/          normative ACR v0.1 specification, validation semantics, and JSON Schema
examples/v0.1/      example records for common review situations
tests/v0.1/         schema and semantic validation fixtures
docs/               implementation, privacy, integrity, and CI guidance
rfcs/               design rationale and future proposals
scripts/            repository validation scripts

Validate examples

npm install
npm test

The test suite validates schema fixtures, recomputes record digests, verifies evidence hashes, and confirms CI-invalid fixtures fail semantic merge-gate validation.

Adoption model

Tools can adopt ACR incrementally:

1. Generate acr.json after verified agent work.
2. Validate the record against the v0.1 schema.
3. Add local evidence checks for Git commits, file hashes, approvals, and verification logs.
4. Gate PR/MR merge on result.merge_ready=true plus local/CI validation.

License

This specification is licensed under the Apache License 2.0. See LICENSE.