# Repositories and VCS Domain

**Status:** Approved target-state baseline  
**First realization:** I0 provider seam / I1 product flow.

## Target State

`Repository` is AWP's stable representation of a source repository. Forge/VCS mechanics are handled by `ForgeProvider` adapters; GitHub is the initial adapter.

```text
Project
  -> Repository
       -> ProviderReference(GitHub repo)
       -> Branch/ref observations
       -> ChangeSet publication
       -> Review/PR mapping
       -> required CI/check observations
```

## Identity and Ownership

Repository owns:

- stable AWP repository ID;
- Project relation;
- canonical clone/source metadata;
- default branch and repository policy observations;
- provider mapping(s);
- source revision references used by Plans/Tasks/Workspaces/ChangeSets;
- repository-native configuration evidence used by Planning/Execution.

It does not own Project policy, provider credentials, ChangeSet lifecycle, PR review authority or CI meaning.

## Revision Model

AWP identifies immutable source revisions by provider-neutral digest/commit identity. Mutable branch names are references, not execution provenance. Every AgentRun/ChangeSet records exact base revision.

## Trusted Publication

Coding AgentRuns do not push. Publication flow:

```text
ChangeSet exact candidate
  -> ForgeProvider trusted publisher
  -> validate repository/base/ref policy
  -> create/update AWP-owned branch/commit/PR as configured
  -> read back provider result
  -> persist ProviderReference + fidelity evidence
```

Merge is separately authorized and verified.

## Invariants From Day 1

- provider repo ID/URL is not AWP Repository identity;
- no reusable publication credential in agent/CI workspace;
- mutable ref never substitutes for immutable base/candidate identity;
- publication verifies exact ChangeSet fidelity;
- retries are idempotent or reconcile before repeating;
- externally moved/deleted refs become observable drift/conflict, not silent data rewrite;
- repository `.github/workflows`, devcontainer and project config remain project-owned evidence/source.

## Repository Inspection

Onboarding may inspect:

- language/tool manifests;
- package/workspace layout;
- `.devcontainer`, Compose/mise/Devbox;
- CI workflows/required checks;
- release/versioning configuration;
- deployment manifests;
- coding/testing standards;
- existing plans/specs/docs.

Inspection records evidence/provenance. It does not silently declare repo observations as user desired state when documentation/code conflict.

## Commands

- RegisterRepository / BindRepository
- RefreshRepositoryObservation
- ResolveRevision
- PublishChangeSet
- Create/UpdateReviewRequest
- MergeChangeSet
- ReconcileProviderState

## Increment Realization

| Increment | Repository realization |
|---|---|
| I0 | ForgeProvider, credential/ref mapping, repository registration/inspection seam. |
| I1 | immutable base, ChangeSet publication, review/merge path, required checks. |
| I2 | richer existing-project evidence for Planning. |
| I5 | CI/check/dependency integration. |
| I6 | release provenance/tag/package relationships. |
| I9 | stable public repository/provider API and enterprise forge adapters. |

## Current Implementation State

GitHub is initial provider; other forges remain adapter-compatible target seams.

## Deferred Realization

Complex monorepo multi-repository release coordination is specified by Plans/workflows when needed, not assumed for every Repository.

## Temporary Dogfood Behavior

I1 may use only GitHub and AWP-owned test branches/PRs. This is provider scope reduction, not a different Repository model.

## Failure / Recovery

Base moved, branch conflict, permission revoked and provider outage are distinct. A failed publication preserves the ChangeSet and can retry/reconcile through trusted publisher without rerunning coding work.

## UI Implications

Repository details are secondary to Project/workflow context. Users see source revision, branch/PR/check status and provider health with direct links, not raw API JSON.

## Decisions / ADRs

Publication authority is constrained by Security/Trust and ChangeSet specs.