# 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.

## Source-of-truth rule

The binding set is small enough to actually read before writing code. Everything else is reference material.

**Binding — read in full:**

- [`docs/specs/adr/`](docs/specs/adr/) — the 8 Architecture Decision Records.
- [`docs/plans/I0-I1-AUTHORITY.md`](docs/plans/I0-I1-AUTHORITY.md) — the distilled implementation digest: plane topology, module dependency law, lifecycle chain, authority/capability rules, transaction pattern, what is deferred.
- [`GOLIVE.md`](GOLIVE.md) — repo-root go-live journey and its acceptance gates.
- [`docs/plans/AWP-PAIN-INVARIANTS.md`](docs/plans/AWP-PAIN-INVARIANTS.md) — owner pain chains mapped to design invariants and the regression test each subsystem ships with.
- [`docs/plans/AWP-GOVERNANCE-AMENDMENT-2026-08-21.md`](docs/plans/AWP-GOVERNANCE-AMENDMENT-2026-08-21.md) — the owner amendment governing gate state, proof scope and this authority rule.

**Reference — consult for the surface you are touching:** everything else under [`docs/specs/`](docs/specs/) and [`docs/plans/`](docs/plans/). These are detailed and current; no agent is expected to have read all of them before starting.

**Precedence:** the ADRs and `I0-I1-AUTHORITY.md` win over any reference spec. The governance amendment wins over any clause it names. A reference spec governs only where nothing above speaks.

`docs/VISION.md` captures owner intent and deliberately preserves early candidate language; it is not the final authority on provider or tool selection.

Architecture-affecting code changes must update the affected binding document in the same logical change. A gate that turns out to be unsatisfiable is amended with owner authority and the amendment is recorded — it is never silently bypassed.

## Further documentation

- [`docs/README.md`](docs/README.md) — how to browse the specs (markdown is canonical; `pnpm docs:serve` renders them).
- [`docs/VISION.md`](docs/VISION.md) — owner-authored intent and historical requirements wording.
- [`docs/specs/INDEX.md`](docs/specs/INDEX.md) — full specification map.
- [`docs/plans/INDEX.md`](docs/plans/INDEX.md) — planning, decision and evidence records.
- [`docs/standards/coding-standard.md`](docs/standards/coding-standard.md) — implementation/module/trust-boundary rules.
- [`docs/mockups/i1/README.md`](docs/mockups/i1/README.md) — approved U1–U6 visual target for I1.

Research and review documents (FOSS research, planning architecture review) are retained as evidence/history. Where their exploratory recommendations conflict with the binding set, the binding set wins.

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.