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 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.

• 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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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?"

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.