# CI Domain

**Status:** Approved target-state baseline  
**Substrate:** I0/I1  
**Full activation:** I5.

## Target State

AWP owns the meaning and progression of CI while delegating execution to `CIProvider` (GitHub Actions initially) and runner lifecycle to ARC.

```text
ChangeSet
  -> change classification / dependencies / capabilities
  -> CIExecutionPlan
       required CIInvariant / Check expectations
  -> CIExecution(s) via provider
  -> CIResult(s)
  -> VerificationEvidence
  -> VerificationAuthority / lifecycle gate
```

## Core Primitives

### CIExecution

AWP identity for one normalized CI occurrence tied to Project/Repository/ChangeSet/source revision, provider reference, planned/observed checks, start/end/status and result/evidence.

### CIExecutionPlan

Explains why CI runs and which invariants/check capabilities are required. May map to existing project workflows rather than generating workflows.

### CIInvariant

Durable named property required to hold, e.g. architecture boundary, unit behavior, typecheck, compatibility, security scan or journey E2E. An invariant is not necessarily one workflow/job.

### CIResult

Normalized provider result bound to exact source/candidate/provider execution.

## Invariants From Day 1

- AWP CI identity is independent of GitHub workflow/check IDs;
- project workflows remain project-owned;
- Merge/release gates consume actual provider results, not synthetic green state;
- retry history remains visible; pass-after-fail may signal flakiness;
- CI evidence is bound to relevant tree/config/dependency/environment revisions;
- no broad rerun when valid evidence already proves required properties;
- missing required provider check blocks progression even if internal planner omitted it;
- runner mechanics/ARC never become product CI identity.

## I1 Thin Realization

I1 consumes focused verification plus actual repository-required GitHub checks. It persists thin CI/check references sufficient for trusted MergeGate. It does not activate generic CI planning/optimization.

## I5 Full Realization

I5 adds:

```text
ChangeClassifier
DependencyGraph
CapabilityMap
CIPlanner
CIInvariant selection
provider dispatch/reconcile/result normalization
resolver/optimizer
compatibility gates
history/why-ran/why-skipped UX
```

## States

```text
planned -> queued -> running -> terminal
terminal: passed | failed | cancelled | skipped-with-reason | infrastructure-error
```

Provider job-level states are normalized but preserved as detailed observations.

## Evidence Reuse

A result may satisfy future gate evaluation only while all relevant identities/revisions remain valid. Candidate/config/check-definition/dependency/environment changes can invalidate selectively.

## R4 Compatibility

Stable/external contracts declare compatibility boundaries. Breaking change detection (OpenAPI/oasdiff where applicable) becomes a required invariant. Internal dogfood contracts may evolve atomically until declared stable.

## Increment Realization

| Increment | CI realization |
|---|---|
| I0 | provider/ARC substrate and AWP repository architecture checks. |
| I1 | required-check consumption + thin normalized evidence. |
| I5 | full control plane, VerificationAuthority integration, optimizer/resolver, R4 gates. |
| I6 | release/deployment consumes CI/artifact evidence. |
| I9 | enterprise/public contract stability and tenant policy. |

## Current Implementation State

Target spec; no full CI product before I5.

## Deferred Realization

Alternative CI providers are adapters. Complex optimization is evidence-driven and must preserve correctness over compute savings.

## Temporary Dogfood Behavior

Small required-check set for AWP itself is acceptable. Do not label omitted/not-started checks as passing.

## Failure / Recovery

Provider outage/infrastructure error differs from test failure. CI resolver may retry infrastructure, but semantic failures require correction/resolution according to policy.

## UI Implications

CI page shows expected/executed/omitted/failed checks, why, exact source/artifact identity, provider details, retry history and next action—not just a provider log link.

## Decisions / ADRs

See ADR 0007 and Verification domain.