# AWP Architecture Closure Audit

**Date:** 2026-08-19  
**Status:** Complete  
**Scope:** Review the existing AWP architecture/planning documentation after the minimal FOSS decisions, day-one ARC requirement, and three-plane edge/control/execution topology were accepted.

## 1. Verdict

The broad architecture-review phase is complete.

The project is ready to move from **architecture review** to **architecture foundation specifications**.

It is not yet ready to skip directly into unconstrained implementation because `docs/specs/` currently contains only `INDEX.md`; the architectural decisions still need to be converted into authoritative contracts and ADRs.

The canonical current architecture is summarized in `AWP-ARCHITECTURE-BASELINE.md`.

## 2. Gaps found and dispositions

| Finding | Problem | Disposition |
|---|---|---|
| Two-plane diagrams remained in older review text | Did not represent the accepted edge/gateway boundary | Superseded by `AWP-DEPLOYMENT-TOPOLOGY.md` and `AWP-ARCHITECTURE-BASELINE.md` |
| ARC described as late/optional in older minimalism/review text | Conflicted with explicit day-one K3s-hosted GitHub Actions requirement | ARC is now day-one baseline; Step 0 and binding FOSS decisions reflect it |
| CI deepening was scheduled only in a late increment | Runner substrate is required from day 1 even if advanced CI semantics come later | ARC/GitHub Actions runner substrate moves to foundation; CI optimizer/impact-analysis depth may remain later |
| Flux remained a review recommendation | Binding decision now uses Helm render + Kubernetes Server-Side Apply | Flux is trigger-only for continuous GitOps reconciliation |
| Hatchet/DBOS, Hono/Fastify and XState choices remained open in old review text | Those bake-offs were already resolved by the minimalism pass | DBOS, Hono and typed AWP transitions are binding defaults |
| Agent Sandbox appeared as a likely workspace provider | Current decision is native Kubernetes Pod/PVC first | Agent Sandbox is trigger-only optimization |
| CloudNativePG appeared too close to a product dependency | Product only needs a normal PostgreSQL endpoint | Managed/external Postgres preferred; CNPG+Barman optional self-host profile |
| Architecture review said exact provider choices would be decided later | Many are already decided | Current provider decisions live in `AWP-FOSS-DECISIONS.md` |
| Architecture review's control/execution module picture did not constrain public transport | Risked future edge extraction work | Gateway and control plane are now separate deployable targets from day 1 |
| Gateway -> control-plane trust was underspecified | Forwarded identity could accidentally become authoritative | Control plane performs final Principal resolution/authorization; internal caller authenticity is required |
| CI runners were not explicitly modeled as untrusted execution workloads | Could recreate broad workstation-style authority inside K3s | Ephemeral ARC runners, trust-tiered scale sets, no reusable publication credentials, no universal privileged runner |
| Git publication authority was not prominent enough in the original review | Agent/runner credentials could bypass AWP lifecycle ownership | Trusted control-plane publication boundary is now an architecture invariant |
| Durable-execution guidance implied universal hand-rolled leases | DBOS now supplies durable workflow mechanics | DBOS owns workflow recovery; explicit AWP leases/tokens remain only where external execution ownership requires them |
| `generic policy engine` wording was ambiguous | Could be read as requiring OPA or another policy service | AWP owns typed policy/rule semantics; no external policy engine baseline |
| `spec/` examples differed from actual repository path `docs/specs/` | Could create a duplicate spec tree | `docs/specs/` is canonical |
| Coding standard pinned Node 22 while runtime version is an ADR/dependency concern | Stale version could silently override later runtime work | Coding standard must refer to the runtime ADR/pinned package baseline rather than hard-code an obsolete version |
| Raw VISION names technologies/candidates directly | Owner intent document can be mistaken for current provider authority | VISION remains preserved owner wording; current architecture/provider docs govern technical dispositions |
| UX research says `before further architecture deepening` | Architecture has now deepened | UX content remains canonical for UX; architecture assumptions are governed by current architecture baseline |
| Specs index omitted some now-critical architecture surfaces | Three-plane topology, transport, persistence, runner trust and execution boundaries need first-class specs | Specs backlog updated to include them |

## 3. Cross-document authority after cleanup

```text
docs/VISION.md
  owner intent / historical requirements wording

AWP-ARCHITECTURE-BASELINE.md
  current architecture snapshot

AWP-DEPLOYMENT-TOPOLOGY.md
  binding runtime/deployable-plane boundary

AWP-FOSS-DECISIONS.md
  binding provider/tool dispositions

AWP-UI-SCREEN-ATLAS.md
  binding UX/screen baseline

STEP-0-PREPARATION-DEPENDENCIES.md
  implementation-readiness gate

docs/specs/**
  implementation source of truth once a surface is specified
```

Historical research/review documents remain useful evidence but do not override the binding documents above.

## 4. Architecture gaps intentionally left for specification, not more research

These are details that must be made precise before their consuming implementation, but they do not require reopening the broad architecture:

```text
exact runtime/package version pins
PostgreSQL transaction/store layout
public/internal API schemas and compatibility rules
gateway -> control-plane service authentication mechanism
DBOS workflow contract details and recovery tests
Workspace PVC/storage-class implementation details
ARC runner scale-set labels/groups/trust tiers
container-build strategy for workflows needing privilege
GitHub App/auth installation model
Subrouter exact adapter contract
Fabro ID/event/checkpoint mapping
ACP provider-specific escape-hatch matrix
object-store required S3 operation subset
retention policies
backup/restore values
release/environment promotion policy
multi-tenant productization details
```

These belong in specs/ADRs because the architecture has already determined the owning boundary.

## 5. Required next phase

The next work package is the **Architecture Foundation Specification Set**, not another broad research pass.

Required first specs:

```text
architecture/principles
architecture/deployment-topology
architecture/domain-model
architecture/module-boundaries
architecture/transport-and-contracts
architecture/persistence-and-transactions
architecture/durable-execution
architecture/event-audit-realtime
architecture/security-and-trust
architecture/configuration-and-policy
architecture/workspace-execution
architecture/adapter-contracts
architecture/ci-and-runner-boundary
```

Then the first end-to-end product slice can be specified:

```text
Project
 -> Plan
 -> WorkItem
 -> FactoryRun
 -> AgentRun
 -> ChangeSet
 -> Review
 -> Merge
```

with K3s containment, Fabro/ACP integration, durable state/events and GitHub Actions + ARC available from the beginning.