# Step 0 Preparation — Dependency and Architecture Readiness **Date:** 2026-08-20 **Status:** **CANONICAL STEP-0 GATE — specification/design complete; implementation/live proofs lane-owned** **Readiness ledger:** [`AWP-I0-I1-IMPLEMENTATION-READINESS.md`](AWP-I0-I1-IMPLEMENTATION-READINESS.md) **Parallel implementation:** [`AWP-I0-I1-PARALLEL-IMPLEMENTATION-PLAN.md`](AWP-I0-I1-PARALLEL-IMPLEMENTATION-PLAN.md) **Reuse/source proof:** [`AWP-I0-I1-REUSE-PREFLIGHT.md`](AWP-I0-I1-REUSE-PREFLIGHT.md) **Threat model:** [`AWP-I0-I1-THREAT-MODEL.md`](AWP-I0-I1-THREAT-MODEL.md) ## Purpose Make the accepted AWP architecture executable without silently changing provider boundaries, reintroducing workstation authority, rebuilding proven mechanics, or calling unavailable live evidence “done.” ## Preparation Rule For every dependency/mechanism: ```text project-native implementation? -> adopt it where compatible. Platform already ships a fitting generic capability? -> consume exact export/version and prove it as an AWP consumer. Node/PostgreSQL/Kubernetes already provide the mechanic? -> use native primitive. standard/FOSS/provider deletes a difficult subsystem? -> put it behind an AWP-owned semantic boundary. proven Overdeck capability exists? -> inspect exact current source and disposition it before equivalent custom code. AWP-specific meaning/policy/state? -> keep it in AWP. ``` ## Canonical Dependency Register | Concern | Binding disposition | Current gate | |---|---|---| | Runtime | TypeScript + Node + ESM + pnpm | current Platform baseline: Node 22.x / pnpm 9.7.0; final TS/lock pin in I0 workspace | | Persistence | PostgreSQL + Drizzle + fitting Platform DB mechanics | contract GREEN; consumer integration I0 | | Public HTTP | Hono | contract GREEN | | Runtime topology | gateway -> control plane -> K3s execution | contract GREEN; executable dependency tests I0 | | Durable workflow | DBOS TypeScript + PostgreSQL | SOURCE-FIT; live crash/recovery proof lane C | | Lifecycle transitions | AWP typed state/transition functions | GREEN contract | | Short jobs/outbox | `@platform-modules/jobs` where fitting | GREEN reuse decision | | Auth/API keys | Platform auth primitives where fitting | GREEN reuse decision; consumer integration I0 | | SecretStore | AWP abstraction -> Kubernetes Secrets initially | GREEN contract | | K3s execution | Kubernetes/K3s | GREEN architecture; live proof lane C | | WorkspaceProvider | native Pod/PVC/ServiceAccount/NetworkPolicy | GREEN contract; live WIP recovery lane C | | Runtime isolation | gVisor where compatible | SOURCE-FIT; representative live proof lane C | | ExecutionProfile | Dev Container standard/CLI + adopt-first project declarations | GREEN contract; representative live proof lane C | | FactoryProvider | Fabro | SOURCE-FIT; runtime mapping lane B/C | | AgentProvider | ACP where supported + explicit native escape hatches | SOURCE-FIT; live agent proof lane B | | Account routing | Subrouter candidate behind AWP AccountProvider semantics | SOURCE-FIT; AWP adapter consumer proof lane B | | VCS | GitHub initial provider | SOURCE-FIT; trusted publication E2E in I1 | | Git publication | trusted control-plane publication boundary | GREEN contract; I1 E2E pending | | CI provider | GitHub Actions | GREEN architecture | | Runner infrastructure | ARC on K3s | SOURCE-FIT; live ephemeral runner proof lane C | | DeploymentProvider | Helm render + Kubernetes Server-Side Apply | target contract; product activation I6 | | Object storage | external S3-compatible endpoint | specify exact subset before first production artifacts/backups | | OCI registry | GHCR initially | target provider | | UI system | React + Astryx | GREEN direction | | Board mechanics | Pragmatic Drag and Drop | selected mechanics; AWP owns semantics | | Graph mechanics | React Flow | selected mechanics; compound Plan/Task DAG meaning is AWP-owned | | Charts | Chart.js where useful + accessible equivalents | selected mechanics | | Work management | AWP-owned typed Goal/Plan/Task/Queue policy | GREEN semantic baseline | | Business events/audit | AWP/PostgreSQL + Platform audit mechanics where fitting | GREEN contract | | Telemetry | structured logs + OTel-compatible instrumentation | GREEN boundary | | MCP | official MCP SDK | SOURCE-FIT; AWP Principal/policy integration when activated | ## Platform Gate Verified source baseline recorded by the preflight: ```text platform-modules/mod revision b7c7f97fa0c51a1cc2f5d87ee752a3c08a08495a Node 22.x pnpm 9.7.0 ``` Before AWP authors a local generic equivalent, exact consumed Platform packages are installed/imported/tested in the I0 workspace. Upstream package presence alone is not enough to claim consumer integration. ## Three-Plane Foundation Gate Mechanical architecture checks must enforce: ```text gateway -> contracts only web -> contracts/application client seam only control -> contracts + application + domain + providers gateway -X-> DBOS gateway -X-> Kubernetes adapters gateway -X-> control-plane repositories domain -X-> Hono/Kubernetes/GitHub/Fabro/ACP provider types ``` The control plane performs final Principal resolution/authorization. Forwarded gateway claims are never authority by themselves. ## Durable Workflow Gate Before long-running product workflows depend on DBOS, prove one representative operation through: ```text start process kill restart/recovery wait/resume retry cancel idempotent external side effect duplicate delivery terminal result persistence ``` Current status: **PENDING lane C; requires executable PostgreSQL/runtime environment**. ## Workspace / WIP Gate Native baseline: ```text Pod PVC when persistence required Service only when required ServiceAccount NetworkPolicy RuntimeClass labels / owner references ``` Before real coding AgentRuns, prove: ```text process crash pod deletion/replacement AWP/control restart cancel/retry recoverable node interruption change collection cleanup/orphan recovery ``` Invariant: compute may be disposable; accepted WIP is durable until deliberate terminal cleanup. Current status: **PENDING lane C; requires authorized cluster execution**. ## Runtime Isolation Gate Use gVisor RuntimeClass for untrusted AgentRuns/runners where compatible. Prove representative TypeScript/React and PHP/WordPress toolchains. An incompatibility can justify an explicit native runtime fallback profile; it cannot silently weaken the global baseline. Current status: **PENDING lane C; requires authorized cluster execution**. ## Day-One CI / ARC Gate Before Step-0 is fully green: ```text [ ] ARC installed with supported GitHub authentication [ ] at least one runner scale set works on intended K3s cluster [ ] real repository workflow completes on ephemeral runner [ ] runner pod is removed after job [ ] runner group/label/trust profile documented [ ] untrusted/fork policy prevents protected secret exposure [ ] no reusable Git publication credential in runner [ ] default runner is unprivileged [ ] privileged workloads use separate explicit profile if required [ ] AWP can correlate GitHub run/check to canonical CI identity ``` Current status: **PENDING lane C; requires authorized K3s/ARC environment**. ## Trusted Git Publication Gate Before I1 Merge is green: ```text AgentRun/Workspace/ARC runner has no reusable publication credential trusted control-plane adapter owns publication candidate identity + expected target head revalidated immediately before mutation review/evidence/current authorization rechecked ambiguous provider result reconciled rather than guessed operation idempotent and audited ``` Current status: contract GREEN; live I1 E2E pending actual candidate flow in provider + convergence work. ## Account / Subrouter Gate Current Subrouter source-contract review is complete. It can provide sticky account placement, explicit account pinning, live usage/headroom routing and provider credential substitution behind an AWP adapter. AWP retains Account/Model/Provider IDs, policy, authorization, Attempt provenance, health normalization, force-account authorization and audit. Current status: SOURCE-FIT; AWP consumer adapter proof belongs to lane B. ## Overdeck Harvest Gate The canonical physical harvest requires exact current source path + commit + capability + disposition before equivalent custom code. The GitHub-only environment used for specification finalization could not access the canonical Overdeck repository. Lane E is therefore the explicit source-evidence lane and can run immediately in parallel with A0 when an authorized source/workstation environment is available. Current status: **PENDING/BLOCKED until authorized source access**. Do not invent exact paths/commits from memory. ## Data / Observability Gate Before first executable product slice: ```text PostgreSQL schema ownership/migration rules lifecycle transaction pattern business event envelope audit atomicity correlation/causation propagation structured log redaction OTel-compatible trace/metric boundary realtime as projection, never state authority reconnect + authoritative state recovery ``` Contract side is specified. Executable integration tests are I0 implementation work. ## UI Gate — GREEN FOR I1 ```text Astryx first AWP-owned implementation for real Astryx gap no deck-ui runtime/product identity Pragmatic DnD for drag mechanics React Flow for graph mechanics AWP owns Goal/Plan/Task/Queue/dependency meaning ``` The complete U1–U6 set under `docs/mockups/i1/` is **OWNER-APPROVED / FINAL**. I1 Design Complete is GREEN. UI implementation still consumes authoritative application/domain state; visual approval is not permission to duplicate lifecycle or dependency authority in the client. ## Security Gate Threat-model design is complete in `AWP-I0-I1-THREAT-MODEL.md`. Privileged I1 is security-green only after executable mitigations pass in the actual I0/I1 environment. ## Step-0 Exit Gate ```text [✓] canonical architecture/domain/workflow/UI contracts reconciled [✓] Goal model canonical; no GOLIVE primitive [✓] dependency-aware Work Queue and Graph semantics fixed [✓] current Platform source/runtime baseline recorded [✓] selected provider/source contracts reviewed [✓] I0/I1 threat model written [✓] deterministic U1–U6 produced [✓] owner-approved U1–U6 visual Design Complete [✓] parallel-safe I0/I1 implementation plan recorded [ ] exact current Overdeck I0/I1 physical harvest where overlapping mechanics may exist [ ] exact AWP Platform package consumer integration/pins [ ] DBOS failure/recovery runtime proof [ ] K3s Workspace/WIP runtime proof [ ] gVisor representative compatibility proof [ ] Dev Container representative environment proof [ ] Fabro/ACP live mapping proofs [ ] ARC ephemeral runner proof [ ] trusted I1 publication/merge E2E [ ] executable security mitigation evidence for privileged I1 ``` Therefore **the entire Step-0 live-evidence exit is not green yet**, but the specification/design gate is closed and implementation is authorized to begin on non-blocked I0 work. ## Implementation Start Boundary Launch Development Agent 1 using [`AWP-I0-DEVELOPMENT-AGENT-1-PROMPT.md`](AWP-I0-DEVELOPMENT-AGENT-1-PROMPT.md). It owns I0-A0 Bootstrap and lands convergence point C0. Lane E source harvest may run immediately in parallel. After C0, lanes A/B/C/D proceed in path-isolated branches according to [`AWP-I0-I1-PARALLEL-IMPLEMENTATION-PLAN.md`](AWP-I0-I1-PARALLEL-IMPLEMENTATION-PLAN.md). Pure/local I0 work may proceed on contracts, domain logic, persistence skeleton, architecture checks and provider interfaces/test doubles while lane-specific external proofs are obtained. A provider-dependent subsystem cannot be called complete or used for privileged dogfood until its required live proof turns green.