# Changes Domain

**Status:** Approved target-state baseline  
**First realization:** I1.

## Target State

`ChangeSet` is AWP's authoritative representation of a proposed source change independent of GitHub branch/PR mechanics.

```text
Task / AgentRun / Attempt
  -> recoverable WIP/checkpoint
  -> ChangeSet revision
       base revision
       candidate tree/patch identity
       changed paths
       digest/provenance
       evidence refs
  -> trusted publication
  -> Review / verification / MergeGate
```

## Identity and Revisions

A logical ChangeSet may receive revisions after requested corrections. Each revision is immutable enough to bind review/evidence/fidelity to the exact candidate. A new correction never silently mutates evidence attached to an older tree.

Conceptual fields:

```text
id
projectId/repositoryId
originating plan/task/factoryRun/agentRun/attempt
baseRevision
candidateRevision/treeDigest/patchDigest
changedPaths[]
status
provider publication refs[]
verificationEvidence[]
createdAt
```

## Invariants From Day 1

- base and candidate are immutable identities, not branch names;
- changed candidate invalidates affected verification/review by explicit rules;
- agent cannot self-publish/merge with reusable forge authority;
- publication read-back verifies candidate fidelity;
- ChangeSet survives provider publication failure;
- review applies to an exact ChangeSet revision;
- merge records exact merged revision/provider result;
- WIP is checkpointed before destructive cleanup or retry.

## Lifecycle

```text
collecting -> candidate-ready -> publishing
 -> published -> reviewing/verifying
 -> ready-to-merge -> merged

branches:
changes-requested -> revised candidate
publication-failed -> retry/reconcile
superseded / cancelled
```

## Change Classification

I5 VerificationAuthority may classify changed paths/capabilities/risk to choose checks. Classification is attached to ChangeSet revision and can be invalidated by candidate changes.

## Publication

Trusted publisher may choose branch/commit/PR depending on repository policy. Provider artifacts are projections/references; AWP ChangeSet remains the cross-provider identity.

## Merge

Merge uses current base/candidate/provider state, required evidence/review/approvals and repository policy. If base drift makes candidate unsafe, MergeGate blocks and requires rebase/reconciliation/correction through trusted workflow.

## Increment Realization

| Increment | ChangeSet realization |
|---|---|
| I1 | candidate identity, WIP collection, publication, review, merge fidelity. |
| I5 | change classification/evidence invalidation/CI graph depth. |
| I6 | source/release/artifact provenance links. |
| I8 | incidents/resolution can produce ChangeSets through normal review path. |

## Current Implementation State

Target spec only; no provider PR object replaces ChangeSet.

## Deferred Realization

Multi-repository atomic ChangeSets can be added as explicit coordinated change semantics if a real project requires them; do not fake distributed atomic merge now.

## Temporary Dogfood Behavior

I1 can use one Repository and one AWP-owned PR/branch per ChangeSet. Fidelity and trusted publication invariants still apply.

## Failure / Recovery

Provider timeout triggers reconcile before repeat. Lost Agent pod does not lose collected/checkpointed candidate. Merge conflict preserves candidate and returns structured blocked state.

## UI Implications

Review surface shows exact base/candidate, changed files/diff, evidence, origin and publication state. Users never need to infer which agent output maps to which PR.

## Decisions / ADRs

Any relaxation of exact candidate/evidence binding is architecture-significant and requires Decision.