# AWP Specification and Design Finalization Record **Date:** 2026-08-20 **Status:** **FINALIZED FOR IMPLEMENTATION** **Owner decision:** U1–U6 approved. Specification/design phase is closed for I0/I1 except for evidence-backed amendments. ## Finalization Decision AWP has completed the full-target specification baseline required before implementation and the complete I1 visual Design Complete gate. The implementation sequence is now: ```text FINALIZED TARGET SPECS + OWNER-APPROVED U1–U6 + explicit reuse/security/evidence gates ↓ I0 FOUNDATION IMPLEMENTATION ↓ I1 FIRST COMPLETE VERTICAL SLICE ↓ DOGFOOD ↓ explicit Decision/spec amendment only when implementation evidence changes the design ``` No further broad product/design interview is required before I0/I1 implementation. ## Canonical Product Model ```text ProjectVision enduring product direction Goal current/future outcome Plan bounded work advancing Goal(s) Task executable work with hard dependencies Queue dependency-constrained dispatch projection FactoryRun orchestration instance AgentRun logical agent assignment Attempt concrete provider/model/account/workspace execution ChangeSet immutable candidate source change Review independent candidate disposition Merge trusted control-plane protected mutation ``` `GOLIVE` is not a first-class primitive. A launch target is a Goal with launch/readiness criteria. ## Specification Completeness The following target-state families are finalized and binding: - architecture and deployment topology; - domain model and stable identities; - ProjectVision / Goal / Planning / Work / dependency Queue; - Factory / Agent / Workspace / ChangeSet / Review; - account/model/provider and Connection/CredentialReference seams; - CI / Verification / Artifact / Release / Deployment; - Cluster / Incident / Resolver / Reliability; - Policy / Approval / Decision / autonomy; - Advisor personas and Search/command palette target behavior; - cross-domain workflows; - complete product UI/IA and page contracts; - transport/events/audit/configuration/adapter contract families; - I0..I9 Increment Realization boundaries; - I0/I1 threat model and reuse/source/provider preflight. Implementation-local details may still be selected behind these seams. A change that alters product behavior, ownership, trust, identity, workflow, page composition or future increment contract requires an explicit Decision/spec amendment. ## I1 Visual Design Complete The owner has explicitly approved the complete U1–U6 lifecycle set. ```text U1 Project Overview APPROVED / FINAL U2 Active FactoryRun APPROVED / FINAL U3 Waiting / Failure / Retry + WIP safety APPROVED / FINAL U4 ChangeSet / Review APPROVED / FINAL U5 Ready to Merge APPROVED / FINAL U6 Merged / Completed APPROVED / FINAL ``` Binding implementation references: ```text docs/mockups/i1/u1-project.html docs/mockups/i1/u1-final.css docs/plans/AWP-U2-FACTORYRUN-HIGH-FIDELITY-BRIEF.md docs/mockups/i1/u2-factory-active.html (must use approved U2 composition) docs/mockups/i1/u3-waiting-failure-retry.html docs/mockups/i1/u4-review.html docs/mockups/i1/u5-ready-to-merge.html docs/mockups/i1/u6-completed.html docs/mockups/i1/awp-i1-final.css docs/mockups/i1/awp-i1-final.js ``` U3 preserves the U2 FactoryRun page identity in a recovery state. U4 -> U5 -> U6 preserve one ChangeSet/Review page identity as the lifecycle advances. ## Approved Visual Language Across I1: - dark near-black/navy shell; - compact professional density; - restrained purple primary/selected accent; - thin navy/blue borders; - human-readable names before IDs; - small semantic status pills; - one dominant primary action per decision context; - destructive actions visually separated; - no generic KPI-card hierarchy; - no glassmorphism/marketing hero treatment; - operational state before raw provider/log details; - waiting/failure states explain recovery and WIP safety first. ## Full-Spec Gate Closure The specification-completeness gate is closed: ```text [✓] full architecture target specification set exists [✓] full domain target specification set exists [✓] full major workflow specification set exists [✓] full UI/page target specification set exists [✓] schemas/contracts/adapters have defined ownership and compatibility boundaries [✓] active canonical specs have human presentation/index coverage [✓] Increment Realization is explicit [✓] major primitives/flows are cross-linked [✓] material Decisions/ADRs are linked [✓] dogfood/temporary behavior is explicit [✓] I0/I1 implementation boundaries are unambiguous [✓] I1 U1–U6 visual states are owner-approved ``` ## What Remains Red These are **implementation/evidence gates, not specification gaps**: - exact current Overdeck physical harvest for overlapping I0/I1 mechanics; - exact AWP consumer pins/tests for Platform packages; - live Subrouter adapter proof; - DBOS crash/recovery/idempotent-side-effect proof; - K3s Workspace/WIP recovery proof; - gVisor representative toolchain proof; - Dev Container representative environment proof; - Fabro runtime mapping proof; - ACP supported-agent runtime proof; - ARC ephemeral runner E2E; - trusted Git publication/merge E2E; - executable security mitigation proofs tied to the same runtime gates. These gates are completed when the corresponding subsystem is introduced. They are never guessed green. ## Implementation Start Decision Implementation may now begin with I0 work that is not blocked on unavailable external/live evidence. Safe first work includes: ```text runtime/monorepo skeleton final IDs/types/contracts architecture dependency checks PostgreSQL/Drizzle schema + transaction skeleton business-event/audit skeleton Principal/capability/config skeleton Goal/Plan/Task/dependency Queue pure domain logic + tests provider interfaces/test doubles UI shell/component foundation against approved U1–U6 ``` Provider-dependent code must stop at the adapter seam until its required source/runtime proof is green. ## Parallel Execution Authority Implementation concurrency is governed by: - [`AWP-I0-I1-PARALLEL-IMPLEMENTATION-PLAN.md`](AWP-I0-I1-PARALLEL-IMPLEMENTATION-PLAN.md) - [`AWP-I0-DEVELOPMENT-AGENT-1-PROMPT.md`](AWP-I0-DEVELOPMENT-AGENT-1-PROMPT.md) Agents must use isolated branches/worktrees, obey path ownership, record durable progress, and converge only at explicit integration points. ## Anti-Drift Rule From this point onward: ```text implementation pressure != permission to redesign provider limitation != permission to change domain ownership silently failed proof != permission to mark the gate green agent preference != permission to move approved UI composition ``` If new evidence requires a material change: ```text open Decision -> record evidence -> impact affected specs/mockups/increment boundary -> amend canonical docs -> only then implement the changed design ``` ## Final Result **Specification phase: complete.** **I1 visual Design Complete: complete.** **Next phase: I0 implementation, in parallel-safe lanes, followed by I1 end-to-end dogfood.**