Part II of a two-part series on version control for the AI SDLC.

Part I introduced the high-level idea: version control should evolve from versioning code to versioning engineering.

This article makes the design more concrete.

It is not a prediction.

It is a design exercise:

If we were designing a version-control protocol for AI-assisted software development, which Git capabilities should remain, and which concepts should become first-class?

Git already gives software engineering a strong foundation: immutable history, content integrity, cheap branching, merging, local operations, and distributed collaboration. Those principles should stay.

The question is how to extend the model so it can represent the artifacts AI-assisted development already depends on:

  • intent,
  • specifications,
  • architecture,
  • operational context,
  • policies,
  • evaluations,
  • implementation,
  • approvals,
  • production learning.

Design Goal

The goal is not “Git with prompts.”

That would be too small.

The goal is a version-control layer that treats engineering work as a connected lifecycle:

Intent
Specification
Context
Implementation
Verification
Review
Operation
Learning

Git models implementation exceptionally well.

An AI SDLC version-control protocol should preserve that strength while adding first-class lineage across the rest of the lifecycle.

The protocol should answer questions that are hard to answer from code alone:

  • Which requirement introduced this behavior?
  • Which context was available when the agent generated the change?
  • Which architecture decision constrained the implementation?
  • Which evaluation accepted it?
  • Which human approved it?
  • Which production signal later challenged it?
  • Which operational knowledge should be updated as a result?

Those are not abstract questions.

They appear in real engineering work whenever a team debugs behavior, audits a change, reviews generated code, investigates an incident, or updates an architectural standard.

What Git Capabilities Should Stay

Before changing anything, it is worth being explicit about what should not change.

Git capability Why it should stay
Immutable history AI-assisted changes need auditability, not less of it.
Content integrity Generated and human-authored artifacts both need tamper-evident identity.
Branching Teams still need isolated workstreams.
Merging Collaboration still requires reconciliation.
Distributed work Local operation and portability remain important engineering properties.
Diffs Textual diffs remain necessary for implementation review.
Tags and references Named points in history are still useful for releases, evaluations, and audits.
Hooks and automation Workflows still need policy checks, tests, and integrations.

The right direction is not to weaken Git’s primitives.

It is to add primitives for artifacts that currently exist around Git but not inside the version-control model.

First-Class Object 1: Intent

Most engineering work begins before code.

A human asks for something:

  • fix a bug,
  • add a feature,
  • migrate an API,
  • improve latency,
  • reduce operational risk,
  • update a policy,
  • clean up a service boundary.

In today’s workflow, that intent often lives in a ticket, issue, document, Slack thread, or meeting note.

For AI-assisted development, intent should be a first-class object.

An intent object might contain:

id: INTENT-2841
title: Reduce duplicate payment retries
requester: product-lead
business_goal: Reduce accidental duplicate charges during retry storms.
scope:
  services:
    - payments-api
    - retry-worker
constraints:
  - Do not change public API behavior.
  - Preserve existing audit log semantics.
  - Roll out behind a feature flag.
success_criteria:
  - Duplicate retry attempts are suppressed.
  - Existing idempotency tests continue to pass.
  - New retry-storm tests cover concurrent requests.

This is not a replacement for implementation.

It is the source of implementation accountability.

The implementation can then be reviewed against the intent that produced it.

First-Class Object 2: Context Snapshot

AI-assisted implementation depends heavily on available context.

That context changes over time.

A service README changes.

An architecture decision is superseded.

A security policy is updated.

A team standard evolves.

An incident adds operational knowledge.

If an agent generates code using context that later changes, the organization should be able to reconstruct what the agent knew at the time.

A context snapshot could record:

context_snapshot: CTX-9128
organization_context: org-context@34
team_context: payments-team@18
service_context: payments-api@77
architecture_decisions:
  - ADR-014@3
  - ADR-029@6
policies:
  - security-standard@12
  - pii-handling@7
repository_instructions:
  - AGENTS.md@4
  - CLAUDE.md@9

This connects directly to Hierarchical Context.

The point is not to stuff every document into a prompt.

The point is to know which authoritative context was in force when the change was produced.

First-Class Object 3: Engineering Change

Git commits are excellent implementation objects.

An AI SDLC protocol needs a broader engineering change object.

It should include the code diff, but it should not stop there.

change: CHANGE-6821
intent: INTENT-2841
context_snapshot: CTX-9128
implementation:
  git_commit: 8f31c9a
  files_changed: 12
agent:
  name: codex
  mode: supervised
human_supervisor: fryzhykau
verification:
  test_run: EVAL-5339
  security_check: SEC-2021
approval:
  reviewer: staff-engineer
  decision: approved
open_questions:
  - Should retry suppression be shared with subscriptions-api?

This object preserves the relationship between why, what, how, and how verified.

Without that relationship, the code still exists, but the engineering lineage is weak.

First-Class Object 4: Evaluation Record

In many current workflows, tests run in CI and produce logs.

That is useful, but AI-assisted development benefits from making evaluation records more explicit.

An evaluation record should answer:

  • What was tested?
  • Which risks were targeted?
  • Which requirements were covered?
  • Which generated assumptions were challenged?
  • Which benchmark or policy version was used?
  • What failed?
  • What passed?
  • What was waived?

Example:

evaluation: EVAL-5339
change: CHANGE-6821
requirement_coverage:
  - duplicate retry suppression
  - idempotency preservation
checks:
  unit: passed
  integration: passed
  concurrency: passed
  security: passed
waivers: []
risk_notes:
  - Does not cover regional failover.
recommended_follow_up:
  - Add failover scenario to retry-worker test suite.

This makes verification reviewable as an artifact, not only a CI status badge.

First-Class Object 5: Knowledge Update

AI-assisted work can reveal missing or outdated context.

A good review should not only fix the generated code.

It should improve the system that produced it.

If an agent misunderstood a service boundary, the right outcome may include:

  • code correction,
  • test update,
  • service README update,
  • architecture decision clarification,
  • repository instruction update,
  • prompt or agent-policy update.

That is a knowledge update.

knowledge_update: KNOW-1472
triggered_by: CHANGE-6821
reason: Agent assumed retries were owned by payments-api only.
updates:
  - payments-api/README.md
  - retry-worker/README.md
  - architecture/payment-retries.md
effect:
  - Clarifies ownership boundary between payments-api and retry-worker.

This is where AI-assisted development becomes a learning system instead of a code generator with cleanup.

Repository Model: From File Tree to Engineering Graph

Git stores a file tree.

An AI SDLC version-control layer should expose an engineering graph.

The file tree still exists.

The graph adds relationships:

Intent
Specification
Architecture Decision
Policy
Context Snapshot
Implementation
Evaluation
Approval
Knowledge Update
Production Observation

The relationships matter as much as the nodes.

For example:

INTENT-2841
  uses CTX-9128
  constrained by ADR-029
  implemented by CHANGE-6821
  verified by EVAL-5339
  approved by REVIEW-771
  updated knowledge through KNOW-1472

This is not only documentation.

It is navigable engineering history.

Branching: Workstreams With Artifact Scope

A Git branch isolates file changes.

An AI SDLC workstream should isolate a coordinated set of artifacts.

For example:

retry-suppression/
  intent
  specification
  context snapshot
  implementation
  evaluations
  review decisions
  knowledge updates

This makes it easier to answer:

  • What changed in the requirement?
  • What changed in the implementation?
  • What changed in tests?
  • What changed in operational knowledge?
  • Are those changes consistent?

The branch is no longer only a file-diff container.

It is a bounded engineering change.

Diff: From Lines to Meaning

Line diffs remain essential.

But AI-assisted workflows need additional diff types.

Diff type Question answered
Line diff What text changed?
Requirement diff What behavior or intent changed?
Architecture diff Which design constraints changed?
Policy diff Which rules changed?
Context diff What knowledge was added, removed, or superseded?
Evaluation diff What is now tested differently?
Behavior diff What observable behavior changed?

Example:

Requirement diff:
Before: Retry attempts are limited per request.
After: Retry attempts are limited per idempotency key across concurrent requests.

Affected implementation:
- payments-api/src/retries.ts
- retry-worker/src/idempotency.ts

Affected evaluation:
- retry-storm.integration.test.ts

That gives reviewers a more useful surface than a file list alone.

Merge: From Text Conflicts to Engineering Conflicts

Text conflicts happen when two changes edit the same lines.

Engineering conflicts can happen even when text merges cleanly.

Examples:

  • two changes update the same business rule differently,
  • one change uses an outdated policy version,
  • an implementation passes tests but violates an ADR,
  • a service change contradicts team ownership boundaries,
  • an evaluation weakens a safety requirement,
  • two generated changes introduce incompatible assumptions.

An AI SDLC merge system should detect conflict classes such as:

Conflict type Example
Text conflict Same line changed differently.
Requirement conflict Two intents define different behavior for the same domain rule.
Architecture conflict Implementation violates an active ADR.
Policy conflict Change uses an outdated security or privacy rule.
Evaluation conflict Test change reduces coverage for a stated risk.
Context conflict Agent used superseded service context.

The output should not be only:

Resolve conflict in retries.ts

It should also say:

Resolve conflict between INTENT-2841 and ADR-029.
The implementation changes retry ownership, but ADR-029 assigns that ownership to retry-worker.

That is a more useful review problem.

Review: From Code Review to Engineering Review

Pull requests currently center on implementation diffs.

For AI-assisted development, review should be organized around risk and evidence.

A review packet might include:

Intent
Specification
Context used
Implementation diff
Evaluation summary
Architecture impact
Security impact
Open assumptions
Human decisions required

The reviewer should not have to reconstruct the entire story from comments and tabs.

The review interface should make the engineering lineage visible.

Practical review questions:

  • Is the intent clear?
  • Is the context current?
  • Does the implementation satisfy the specification?
  • Are the tests aimed at the real risk?
  • Which assumptions did the agent make?
  • Which assumptions should become permanent knowledge?
  • Is human judgment required before merge?

This does not eliminate code review.

It makes code review part of a broader engineering review.

Identity and Accountability

AI-assisted development introduces more actors:

  • human requester,
  • human supervisor,
  • implementation agent,
  • review agent,
  • security agent,
  • test generator,
  • human reviewer,
  • release approver.

The protocol should record identity clearly.

Not to create blame theater.

To preserve accountability.

Example:

actors:
  requester:
    type: human
    id: product-lead
  implementation:
    type: agent
    id: codex
    mode: supervised
  supervisor:
    type: human
    id: engineering-owner
  reviewer:
    type: human
    id: staff-engineer
  validation:
    type: automation
    id: payments-ci

The important question is not “who typed the line?”

The important question is “who or what contributed to the engineering decision?”

Provenance: Knowing Where a Change Came From

Provenance is the record of origin.

For AI-assisted software development, provenance should include:

  • source requirement,
  • context snapshot,
  • model or agent class,
  • tool permissions,
  • generated files,
  • human edits,
  • review outcomes,
  • evaluation results,
  • policy versions.

This matters because generated implementation is not self-explanatory.

The code may be correct, but an organization still needs to know which context produced it.

Without provenance, audits become archaeology.

With provenance, audits become graph queries.

Querying Engineering History

Once engineering history is connected, teams can ask better questions.

Examples:

Show every change generated with security-standard@11.
Find implementations that used service-context@42 after it was superseded.
List changes where evaluation passed but production incidents later referenced the same requirement.
Show all services affected by ADR-029.
Find changes where AI output required human correction for ownership boundaries.

These are not Git queries today.

They are engineering-history queries.

That is the practical value of the protocol.

A Minimal Object Model

The protocol does not need to start enormous.

A minimal useful model could contain seven objects.

Object Purpose
Intent Captures the human or product goal.
Specification Makes expected behavior explicit.
Context Snapshot Records the knowledge used for implementation.
Change Connects implementation to intent and context.
Evaluation Records verification evidence.
Review Captures human and automated decisions.
Knowledge Update Feeds learning back into the repository.

These objects can live in files at first.

They can be represented as YAML, JSON, Markdown frontmatter, signed metadata, or database records.

The storage format matters less than the relationships.

The essential rule is:

Every material implementation should be traceable to intent, context, verification, and review.

Example Workflow

Here is one end-to-end workflow.

1. Human creates intent

Reduce duplicate payment retries during retry storms.

2. Specification is written

Concurrent requests sharing an idempotency key must not create duplicate retry jobs.

3. Context snapshot is resolved

Organization context: engineering-principles@34
Team context: payments-team@18
Service context: payments-api@77
Policy: pii-handling@7
ADR: retry-ownership@6

4. Agent proposes implementation

Generated change touches payments-api and retry-worker.

5. Evaluations run

Unit tests passed.
Integration tests passed.
New retry-storm test added.
Security check passed.

6. Review packet is generated

Intent: clear
Architecture impact: retry-worker ownership confirmed
Open question: Should subscriptions-api share this guardrail?
Human decision required: no for current scope, yes for follow-up platform work

7. Knowledge update is captured

Service README updated to clarify retry ownership.
ADR linked from retry-worker docs.

The code change is still there.

But now the engineering story is there too.

How Much of This Already Exists

Most of these objects already exist as separate tools. What is missing is the connection between them.

Intent and specification are the clearest case. Spec-driven development tools now treat a written spec as the unit of work. Kiro, AWS’s agentic IDE, walks from requirements to design to a task list and traces each task back to a requirement. GitHub Spec Kit does the same as an open, model-agnostic CLI. Tessl goes furthest, treating the spec as source and the code as a regenerated output not meant to be edited by hand. The shared limitation, as Martin Fowler’s review of these tools notes, is that most discard the spec once the code exists. Intent is captured, then thrown away, rather than versioned.

The context snapshot has a convention too. AGENTS.md is a README for coding agents, read natively by most of them, from Claude Code and Codex to Cursor and Devin, and now stewarded by the Agentic AI Foundation under the Linux Foundation. Tens of thousands of repositories use it. But it records current state. It is one live file, not a record of which context was in force when a given change was generated.

The evaluation record is emerging from the LLM tooling side. Platforms like Langfuse already version prompts and evaluations as comparable artifacts tied to execution traces. That is close to the evaluation record described here, but it is scoped to the AI application, not connected to the engineering change or the intent behind it.

Provenance is being pulled in from supply-chain security. SLSA and Sigstore already produce signed, verifiable provenance for build artifacts, and that model is being stretched to cover models, datasets, and evaluation artifacts. This proves origin and integrity. It does not yet answer which intent, context, and review produced a change.

The pattern is the same across all four.

Each object has a credible existing implementation. None of them is connected to the others.

The value of a version-control layer for the AI SDLC is not inventing these objects.

It is the graph that links them.

Migration Path From Current Git Workflows

This model does not need a new tool on day one.

Teams can approximate it with current Git repositories.

Start with conventions:

/specs
/architecture
/decisions
/evaluations
/operations
/memory
AGENTS.md
CLAUDE.md

Then add required metadata to pull requests:

## Intent

## Context used

## Architecture impact

## Evaluation evidence

## Open assumptions

## Knowledge updates

Then connect artifacts with stable identifiers:

INTENT-2841
SPEC-9002
ADR-029
CTX-9128
EVAL-5339
CHANGE-6821

The first implementation can be boring.

That is fine.

The concept matters more than the initial tooling.

What Not to Build

There are obvious traps.

Do not store every prompt forever.

Prompts can contain noise, secrets, or temporary reasoning. Store material context and decisions, not every intermediate token.

Do not let metadata become a bureaucratic tax.

If engineers have to fill out twenty fields manually, the system will rot.

Do not treat agent confidence as truth.

Confidence is only useful when paired with evaluation evidence and human review.

Do not replace human judgment with prettier provenance.

Traceability helps judgment. It does not remove the need for it.

Do not build a tool that only works for AI.

The same artifacts should help humans understand the system better.

If the protocol helps agents but confuses engineers, the design is wrong.

Design Principles

A practical version-control protocol for the AI SDLC should follow these principles.

1. Preserve Git’s strengths

Do not weaken immutability, integrity, locality, branching, merging, or review.

2. Treat knowledge as operational

Requirements, architecture, policies, standards, and runbooks influence implementation. They should be versioned with rigor.

3. Make context explicit

Every material generated change should record the context snapshot that informed it.

4. Connect implementation to intent

Code should be reviewable against the reason it exists.

5. Treat verification as an artifact

Test results, evaluations, benchmarks, waivers, and risk notes should be part of the engineering record.

6. Detect semantic conflicts

Clean text merges are not enough when requirements, policies, or architecture are inconsistent.

7. Feed learning back into context

If an implementation exposes missing knowledge, the repository should improve.

8. Serve humans first

AI is a participant in the workflow. Humans remain accountable for engineering judgment.

Closing Thoughts

Git made source code collaborative.

That remains one of software engineering’s great achievements.

AI-assisted development expands the set of artifacts collaboration depends on.

Intent matters.

Context matters.

Architecture matters.

Policies matter.

Evaluations matter.

Operational learning matters.

A version-control system designed for the AI SDLC should not abandon Git’s principles.

It should apply those principles across the engineering lifecycle.

The useful abstraction is not “Git for prompts.”

It is versioning engineering.

Source code remains the central executable artifact.

But the engineering system that produces it deserves history too.