Decision provenance for AI-generated code

What evidence should an AI-generated change preserve?

Preserve the evidence needed to reconstruct the architectural path without storing every model token. At minimum, record the repository revision, task or issue, applicable decision IDs, agent-declared plan, changed files, checks and approvals. Add exception IDs and policy versions when they affect the result. The final pull request should make the evidence easy to inspect rather than hiding it in a separate audit database.

Stable IDs matter because titles and wording change. A citation should identify the decision revision or source commit, the files to which it applied and the result of its linked check. That lets a later reviewer distinguish a changed decision from a change that ignored the old one.

• Record retrieved decisions before code generation begins.
• Attach citations to plans, commits or pull requests.
• Preserve check results and the policy version that produced them.
• Keep rejected proposals and expired exceptions out of active authority.

How does provenance improve review rather than add paperwork?

Good provenance shortens review because it answers the questions reviewers repeatedly ask: which decision did the agent use, did it apply to these files, what changed, and what evidence supports compliance? It also makes disagreement productive. A reviewer can challenge scope, supersession or the check itself instead of reverse-engineering the agent’s hidden context from a diff.

The record should remain compact. Evidence links and stable identifiers are more useful than a complete transcript, especially when the same decision governs many changes.

What is the minimum provenance record?

The minimum useful provenance record is a compact tuple: repository and revision, task identifier, agent identity, applicable decision IDs, changed files, checks and human approvals. Add the decision or policy revisions when they can change the interpretation of the result. Keep the record attached to the pull request or commit so it travels with the change rather than living only in a dashboard that may later lose context.

The record should support a later question, not a forensic reconstruction of every model step. A reviewer needs to know whether the agent was shown ADR-0042, whether ADR-0042 applied to the file it changed, whether the linked check ran and who approved an exception. That is enough to separate a deliberate choice from a silent omission while keeping evidence storage practical.

• Repository revision and changed-file set.
• Decision IDs retrieved and cited by the agent.
• Policy/check results and their versions.
• Approvals, exceptions and final merge state.

What is the smallest useful provenance record?

The smallest useful provenance record lets a reviewer reconstruct the authority behind a merged change without replaying an agent session. Store the task or issue identity, base and final commits, the applicable decision IDs and source revisions, the agent’s declared plan, changed-file scope, check results and human approvals. Add an exception ID and policy version when either changed the decision path. Keep the durable record close to the pull request or commit so it can be inspected with the code.

Avoid treating a transcript, model confidence score or generated summary as proof. Those artefacts can provide context, but they are not substitutes for a stable decision citation or an independently repeatable check. If raw prompts are retained for incident analysis, apply the repository’s data-classification and retention rules. The evidence bundle should be compact enough to preserve consistently and precise enough to distinguish a scope mistake from a policy failure.

A reviewer should be able to follow the chain from task to decision, from decision to check and from check to merge without trusting an undocumented agent state.

• Task, base commit and final commit.
• Decision IDs, revisions and affected files.
• Agent plan, check results and policy versions.
• Approvals, exceptions and retention classification.

Why model attribution is not enough

Knowing which model generated a patch does not explain why the implementation follows a particular retention rule, API boundary or compatibility promise. Reviewers need project provenance: the human-approved decisions and objective evidence connected to the change.

Capture a minimal evidence chain

Record the base commit, task or issue, cited decision IDs and statuses, and the commands or policy checks executed. Keep retrieval results reproducible where possible. The patch itself remains subject to normal review regardless of whether a human or agent authored it.

• Immutable base and resulting commit identifiers.
• Current decision records cited by stable ID.
• Missing or conflicting authority disclosed explicitly.
• Test and enforcement results with declared scope.

Keep provenance close to the change

A pull-request description or machine-readable attestation can carry the summary while linking to repository records. Avoid storing sensitive prompt transcripts by default; they are noisy, may contain private data and do not substitute for reviewed authority.

Use provenance during review

Reviewers can verify that cited decisions were accepted at the base commit, that no relevant superseding record was omitted and that checks actually cover the changed paths. If the patch requires a new decision, create or supersede that record through review before presenting the implementation as compliant.