# AWP

AWP is an **Agentic Software Delivery Control Plane**: a product that owns software-delivery intent, planning, policy, authoritative lifecycle state, observability, CI/CD semantics, and human/agent decision boundaries while delegating execution mechanics to replaceable adapters and proven infrastructure.

## Canonical architecture in one sentence

```text
stateless edge/gateway -> authoritative modular-monolith control plane -> K3s execution plane
```

The gateway and control plane are separate deployable targets from day 1 even when initially co-located. GitHub Actions CI runs on K3s through Actions Runner Controller (ARC) from day 1.

## Documentation authority

Start with:

- [`docs/VISION.md`](docs/VISION.md) — owner-authored intent and historical/non-negotiable requirements wording. It intentionally preserves early candidate language and is not the final authority for provider/tool selection.
- [`docs/plans/AWP-ARCHITECTURE-BASELINE.md`](docs/plans/AWP-ARCHITECTURE-BASELINE.md) — **current canonical architecture snapshot** and architecture-review closure position.
- [`docs/plans/AWP-DEPLOYMENT-TOPOLOGY.md`](docs/plans/AWP-DEPLOYMENT-TOPOLOGY.md) — binding edge/gateway -> control plane -> execution-plane boundary.
- [`docs/plans/AWP-FOSS-DECISIONS.md`](docs/plans/AWP-FOSS-DECISIONS.md) — binding provider/FOSS choices and trigger-only additions.
- [`docs/plans/STEP-0-PREPARATION-DEPENDENCIES.md`](docs/plans/STEP-0-PREPARATION-DEPENDENCIES.md) — foundation readiness gate, including day-one ARC/K3s CI.
- [`docs/plans/AWP-UI-SCREEN-ATLAS.md`](docs/plans/AWP-UI-SCREEN-ATLAS.md) — canonical UX/screen baseline.
- [`docs/specs/INDEX.md`](docs/specs/INDEX.md) — specification structure and next architecture-foundation spec set.
- [`docs/standards/coding-standard.md`](docs/standards/coding-standard.md) — implementation/module/trust-boundary rules.

The broad [`AWP-PLANNING-ARCHITECTURE-REVIEW.md`](docs/plans/AWP-PLANNING-ARCHITECTURE-REVIEW.md) and FOSS research documents are retained as review evidence/history. Where their exploratory recommendations conflict with the current architecture baseline, topology, or FOSS decision register, the current binding documents win.

## Source-of-truth rule

`docs/VISION.md` captures owner intent. The architecture baseline/topology/FOSS decision register govern current architectural choices until an approved spec covers that surface. Approved specs under `docs/specs/` then become implementation source of truth for the surfaces they govern.

Architecture-affecting code changes must update the affected spec in the same logical change.

AWP consumes reusable `@platform-modules/*` capabilities from the private `platform-modules/mod` repository. Generic reusable gaps discovered while building AWP should be evaluated for an upstream `mod` change rather than silently reimplemented inside AWP.