deliveryL3 SystematicGovernance & Compliance

Minimum viable audit trail: model, timestamp, context, approver

The minimum viable audit trail (MVAT) is the smallest set of structured metadata that, when captured consistently for every AI-assisted change, creates a defensible provenance reco

·Minimum viable audit trail is captured per AI-assisted change: model identifier, timestamp, context description, human approver
·Policy-as-code enforces compliance rules in CI (OPA or equivalent)
·Compliance gates run on every PR to in-scope repositories

·Audit trail fields are validated by CI (missing fields fail the build)
·Policy exceptions are logged and require follow-up within 48 hours

Evidence

·Sample commit or PR metadata showing model, timestamp, context, approver fields
·OPA policy configuration in CI pipeline
·Compliance gate pass/fail logs

What It Is

The minimum viable audit trail (MVAT) is the smallest set of structured metadata that, when captured consistently for every AI-assisted change, creates a defensible provenance record for compliance and incident investigation purposes. The four core fields are: model (which AI system was used, including version), timestamp (when the AI was invoked and when the change was reviewed), context (what the AI was asked to do and in what codebase context), and approver (which human reviewed and approved the AI-generated output before merge).

At L3 (Systematic), the MVAT is captured consistently - not because developers remember to fill it in, but because the process makes it automatic or near-automatic. The difference between L2 (basic audit, manually filled PR fields) and L3 (minimum viable audit trail) is enforcement and structure: L3 audit trails block merges if the required fields are absent, use structured formats that can be queried programmatically, and are captured at the tool level rather than requiring developer manual entry.

The four-field schema is not arbitrary. Each field answers a distinct question that matters in different scenarios. Model answers "what system generated this?" - critical for understanding capability limitations and for tracing systematic AI errors to model versions. Timestamp answers "when was this AI involvement?" - necessary for correlating AI-generated changes with deployment incidents, model version changes, and regulatory windows. Context answers "what was the AI asked to do?" - essential for understanding whether the AI was operating within its intended use case and for reproducing the scenario during investigation. Approver answers "who was responsible?" - preserves human accountability in the chain even as AI automation increases.

The MVAT lives in the commit history and is queryable. A well-implemented MVAT means that in response to "show me every AI-generated change to the payment processing module in the last six months, with the model version, the human approver, and the ticket that prompted the change," you can produce that report in minutes rather than days. This is the operational value of the audit trail that goes beyond compliance theater.

Why It Matters

Creates a queryable provenance record - audit trails in structured formats can be queried by security tools, compliance dashboards, and incident investigation scripts; unstructured PR comments cannot
Enables incident attribution - when a production issue correlates with AI-generated code, the MVAT lets you identify which model version, which developer, and which task prompt were involved - turning a forensic investigation from days to minutes
Satisfies SOC2 change management controls - SOC2 Trust Service Criteria CC8 (Change Management) requires evidence of approval and testing for changes; the MVAT's approver and timestamp fields directly satisfy this requirement for AI-assisted changes
Builds the dataset for model version impact analysis - by recording model versions consistently, you can later analyze whether changes from specific model versions had higher defect rates - a feedback loop that improves AI adoption decisions
Scales to automated enforcement - once the schema is defined and enforced in CI, every team and every repository benefits automatically without additional discipline from developers

Getting Started

Define the schema as a structured git trailer - use git trailers (the Key: Value format in commit messages) to capture MVAT fields. Example schema: AI-Model: claude-3-5-sonnet-20241022, AI-Timestamp: 2025-03-01T14:32:00Z, AI-Context: Generated authentication middleware from ticket ENG-4521, AI-Approver: [email protected]. Trailers are queryable with git log --grep="AI-Model:" and parseable by CI systems.
Build a commit hook or CLI wrapper - the fastest path to consistent capture is automation. A Claude Code post-session hook that prompts the developer for the context field and appends all four trailers to the commit message removes the burden of remembering the format. Alternatively, a wrapper script around git commit that captures the fields interactively is a two-hour engineering investment with lasting returns.
Add CI validation - add a CI check that parses commit messages for required MVAT trailers on any commit that includes changes to in-scope repositories. The check should fail with a descriptive error message: "AI-assisted commit missing required audit fields. Add: AI-Model, AI-Timestamp, AI-Context, AI-Approver." This converts MVAT from a convention to an enforced requirement.
Define scope by repository risk tier - not every repository needs the same level of MVAT enforcement. Start with your highest-risk repositories: SOC2 scope, repositories handling customer data, repositories for regulated product features. Expand to all repositories over 90 days.
Build the query interface - the audit trail is only useful if you can query it. Write a script or Makefile target that answers common audit questions: make audit-trail REPO=payments START=2025-01-01 END=2025-03-01 returns all AI-assisted commits with their MVAT data in CSV format. This query tool is what you'll use in actual audits and investigations.
Document the model version registry - maintain a registry that maps model identifiers (as used in the audit trail) to their capabilities, training cutoffs, and known limitations. This registry is the reference you need when investigating "we found a vulnerability in code generated by claude-3-opus-20240229 - what else did that model generate?"

Tip

The context field is the hardest to get right and the most valuable in practice. "Generated auth middleware" is marginally useful. "Generated JWT validation middleware for ticket ENG-4521, which required RS256 support - I reviewed and modified the key rotation logic" is genuinely useful for an investigator six months later. Invest in a context field template that prompts developers to include the ticket, the requirement, and any modifications they made.

6 steps to get from here to the next level

Common Pitfalls

Making the schema too complex. An MVAT with twelve required fields will not be filled in consistently no matter how many CI checks enforce it. The four fields (model, timestamp, context, approver) are the minimum that provide genuine value. Resist the temptation to add fields "just in case" until you have operational evidence that they're needed.

Treating the timestamp wrong. The MVAT timestamp should capture when the AI was invoked (start of the AI session or prompt), not when the commit was made. These can be hours apart for complex agent tasks. The difference matters in incident investigation: you want to know what the model knew when it generated the code, not when the developer committed it.

Not versioning the schema. As your MVAT implementation matures, the schema will evolve. Without versioning (a AI-Schema-Version: 1.0 field), queries that assume the current schema format will fail on historical commits that used a different format. Add a schema version field from day one and maintain backward compatibility in your query tools.

Capturing context at the wrong granularity. One MVAT record per PR is too coarse when a PR contains ten AI-generated commits for different purposes. One record per line of code is impractical. The right granularity is per task: one MVAT block per distinct AI session or distinct task within a session. If Claude Code generates the implementation and a separate session generates the tests, those are two MVAT records.

Storing audit data only in git. Git history is authoritative for commit-level provenance, but it can be rewritten (rebased, squashed) in ways that destroy audit records. Export MVAT records to an immutable append-only store (S3 with object locking, a compliance database) at PR merge time. The git history is the source of truth for the audit record, but the external store is the tamper-evident backup.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob's SOC2 auditors have asked specifically about AI change management controls - they want to see evidence that AI-generated changes are reviewed by a human and that the review is documented. Bob has the PR template disclosure fields from L2, but the auditors want something more structured and queryable than free-text PR comments.

What Bob should do: Bob should implement the MVAT schema in the two weeks before the audit evidence window opens. He needs two artifacts: the schema implementation (git trailers with the four fields), and a sample audit report generated from the schema (showing 30 days of AI-assisted changes with model, timestamp, context, approver). The sample report demonstrates to auditors that the system is queryable and that the approver field documents human review. Bob should also note that the approver is captured both in the MVAT (the developer who ran the AI session) and in the PR approval (the reviewer who approved the PR) - two distinct human accountability records per AI-assisted change, which is a strong control story.

What Bob should do - role-specific action plan

SarahProductivity Lead

Sarah wants to use the MVAT data to build model version performance analysis - correlating which Claude model version generated code with downstream defect rates and review round counts. This would be the first data-driven input to AI tool version adoption decisions.

What Sarah should do: Sarah should start by verifying that the model field is captured consistently and accurately before building the analysis on top of it. She should pull the last 90 days of MVAT records and check: what model versions appear, what's the distribution, are there obviously wrong values (free-text instead of structured model IDs)? Once she has confidence in the data quality, she can join the MVAT records with defect tracking data (bugs filed in the two weeks after a PR merged) and review round counts. The resulting analysis - "PRs generated with claude-3-5-sonnet have X% lower defect rate than claude-3-opus" - gives the team a data-driven basis for model selection rather than relying on intuition or marketing claims.

What Sarah should do - role-specific action plan

VictorStaff Engineer - AI Champion

Victor runs complex multi-session agent workflows where a single feature involves multiple Claude Code sessions: one for the implementation, one for tests, one for documentation updates, and sometimes a separate session for a security review. The four-field MVAT schema covers single sessions well but doesn't naturally capture multi-session work.

What Victor should do: Victor should extend the schema with a session chain concept: an AI-Session-Chain field that groups related AI sessions under a single feature or task identifier. When he starts an agent workflow for a feature, he generates a UUID for the chain; every session in that workflow includes the chain ID. This allows the audit trail to say "this PR involved four AI sessions over three days; here they are in sequence." Victor should prototype this extension, use it for a month, then bring the usage data to the team with a proposal to standardize it. The chain concept is likely to become relevant to other developers as multi-session agent workflows become more common.

What Victor should do - role-specific action plan