# I0 / I1 Implementation Authority **Date:** 2026-08-21 **Status:** **BINDING — this is the implementation context for I0/I1 agents** **Read with:** the 9 ADRs under [`../specs/adr/`](../specs/adr/), repo-root `GOLIVE.md`, [`AWP-PAIN-INVARIANTS.md`](AWP-PAIN-INVARIANTS.md), [`AWP-GOVERNANCE-AMENDMENT-2026-08-21.md`](AWP-GOVERNANCE-AMENDMENT-2026-08-21.md) **Distilled from:** `specs/adr/0001`–`0009`, `specs/architecture/{module-boundaries,security-and-trust,domain-model,persistence-and-transactions}.md`, the I0/I1 sections of [`AWP-INCREMENTAL-DELIVERY-PLAN.md`](AWP-INCREMENTAL-DELIVERY-PLAN.md) ## How To Use This This digest is sized to be held in working context alongside the code you are writing. It is the binding rule set. Everything else in `docs/specs/` and `docs/plans/` is reference material — read the reference spec for the surface you are actually touching, not the whole corpus. ## What AWP Is An Agentic Software Delivery Control Plane. It owns delivery intent, planning, policy, authoritative lifecycle state, observability, CI/CD semantics and the human/agent decision boundary. It delegates execution mechanics to replaceable adapters and proven infrastructure. It is not an agent runner with a UI. Provider state is never authority over AWP state. ## Plane Topology ```text Internet │ ├─ Edge / Gateway plane │ public ingress, auth/session ingress, webhooks, realtime fan-out │ holds NO authority │ ├─ Control plane │ final Principal resolution + authorization │ domain + application + repositories + providers │ PostgreSQL (authoritative) + DBOS (durable workflow) │ business events, audit, outbox │ └─ Execution plane (K3s) AgentRuns, Workspaces, Factory runs, CI jobs untrusted by default ``` Three logical/code/trust boundaries exist from day one even when co-located in one cluster. Forwarded gateway claims are context, never authority — the control plane re-resolves the `Principal` and re-authorizes every privileged operation. The gateway, agent runtime, CI runner, browser and provider webhooks are **never trusted merely because they look internal**. ## Module Dependency Law ```text apps/ gateway/ control-plane/ web/ packages/ contracts/ domain/ application/ providers/ adapters/ ``` Allowed direction: ```text gateway -> contracts web -> contracts control -> application + domain + providers + contracts application -> domain + provider interfaces domain -> domain only / runtime-neutral primitives adapters -> provider interfaces + SDK/infrastructure libraries ``` Forbidden, enforced by dependency-cruiser + architecture tests in CI from I0: ```text gateway -X-> DBOS / repositories / Kubernetes / GitHub SDK domain -X-> Hono / React / Kubernetes / GitHub / Fabro / DBOS SDK types web -X-> server repositories / provider SDKs adapter -X-> mutate unrelated domain state directly -X-> circular dependencies across domain modules -X-> secret-store implementations imported into execution-facing code ``` Provider interfaces are named for the AWP capability, never the vendor: ```text WorkspaceProvider not KubernetesService ForgeProvider not GitHubService FactoryProvider not FabroService CIProvider not ActionsService DurableWorkflowProvider not DBOSService DeploymentProvider not KubernetesDeploymentService ``` Hono route handlers do exactly four things: parse/validate the transport DTO, establish caller/gateway context, call an application command or query, map result/error to the transport contract. No lifecycle logic, no SQL, no orchestration, no policy in a handler. A small I0/I1 codebase may co-locate several modules in one package **only** if folder/import boundaries and public exports already preserve the target direction. It must not become a permanent grab-bag. Organize application/domain code around cohesive families rather than one giant package: ```text projects · planning/work · factory/agents/workspaces · changes/reviews verification/ci · delivery · cluster · connections/providers configuration/policy/governance · incidents/communications ``` Cross-family dependencies go through explicit application/domain contracts. No convenient bidirectional imports — shared concepts move into a smaller stable package, or the families communicate by ID, event or use case. ## Lifecycle Chain ```text Project ├─ ProjectVision enduring versioned product intent ├─ Goal current/future outcome being pursued │ └─ Plan / PlanRevision bounded work advancing Goal(s) │ └─ Task executable unit, hard dependency DAG └─ FactoryRun orchestration instance for a work graph └─ AgentRun logical agent assignment └─ Attempt concrete provider/account/model execution └─ Workspace isolated env + durable WIP └─ ChangeSet candidate source change └─ Review findings + disposition └─ trusted Merge ``` Rules that hold at every link: - `ProjectVision != Goal != Plan`. `GOLIVE` is **not** a primitive — a launch is a `Goal` with readiness criteria. - Hard `Task` dependencies form an acyclic graph and are authoritative for dispatch legality. A `Task` is not dispatch-eligible while a prerequisite is unsatisfied. **Manual Queue priority cannot make an illegal ordering legal.** - `Queue` and `Search` are read-model projections. They never become alternate lifecycle authorities. - IDs are opaque, immutable, globally unique in the AWP namespace. Provider-native IDs are mappings (`ProviderReference`), never business identity. - `Task` identity survives retries. `AgentRun` is logical; `Attempt` is the immutable concrete execution record with account/model/workspace provenance. - `ChangeSet` identity is independent of any forge branch or PR URL. - A parent lifecycle may constrain child creation but never erases child history. Retries create new `Attempt`/revision records; accepted `Decision`s are superseded, never rewritten. - Compute is disposable; **accepted WIP is durable until deliberate terminal cleanup.** ### Who owns what | Primitive | Owns | Does not own | |---|---|---| | `Project` | scope, defaults, connections, repositories | provider mechanics | | `ProjectVision` | enduring versioned intent | work breakdown, current Goal state | | `Goal` | outcome + criteria + linkage | execution lifecycle | | `Plan`/`PlanRevision` | approved bounded work intent | live execution state | | `Task` | scope, dependencies, acceptance expectations | pod/process lifetime | | `FactoryRun` | orchestration of a work graph | agent-provider internals | | `AgentRun` | logical agent assignment | concrete retry/fallback identity | | `Attempt` | immutable provider/account/model/workspace execution | logical Task identity | | `Workspace` | isolated environment + durable WIP association | product workflow meaning | | `ChangeSet` | proposed change + provenance | merge authority | | `Review` | findings + disposition | candidate mutation, merge authority | | `Decision` | material choice, rationale, consequence | authorization itself | | `Approval` | authorization disposition | design rationale | ### Agent role boundary ```text Planner Agent Planning / PlanRevision formation Advisor Agent canonical-state analysis + proposals (I3+) Resolver Agent bounded technical diagnosis / recovery (I8) Execution Agent coding / review / fix inside Factory execution ``` Advisor conclusions become durable product truth only by invoking a canonical command (ProjectVision, Goal, Decision, PlanRevision, Task, Policy, Configuration). There is no advisor-private mutation store. ## Authority and Capability Rules `Principal = Human | Agent | System`, with stable AWP identity and resolved capabilities. Capabilities are action/resource scoped (`project.read`, `plan.modify`, `factory.start`, `changeset.publish`, `review.submit`, `merge.execute`, `connection.bind`). Roles are convenience groupings, not the authorization model. ```text Connection -> CredentialReference -> SecretStore secret/version ProjectConnectionBinding -> allowed capabilities/resources Plan/Task/Run -> may NARROW a binding -X-> may never silently broaden it ``` Binding invariants: - Secrets stay behind the credential seam. Product state stores `CredentialReference` only. Secret values never appear in domain events, audit payloads, logs, Plan/Task records or UI state. - **Agents and CI runners never receive reusable Git publication, merge or production credentials.** The publication credential lives in the trusted control-plane adapter and is never mounted into a coding workspace. - Every privileged operation rechecks authorization against the current Principal, policy, connection binding **and target state** — not against a decision made earlier in the flow. - Prompt text cannot broaden an agent role's capability or authorization. Ever. - Provider/webhook identity and signatures are verified before observations enter reconciliation. - Security failures fail closed for privileged actions; read-only degradation may stay available where safe. Trusted publication verifies, at the moment of mutation: expected repository/base revision, changed-tree/patch fidelity, allowed ref/repository, attempt/task provenance, required verification/review state, and current merge/publish policy. Execution isolation baseline (**non-negotiable, not descoped**): isolated namespace and workload identity, non-root where possible, egress policy by execution profile, resource limits, no host filesystem or socket access by default, dedicated PVC/object checkpointing. Normal AgentRuns execute in K3s, never on a workstation. ## Transaction Pattern PostgreSQL is authoritative product state. Drizzle is the schema/query layer. DBOS uses PostgreSQL for durable-workflow mechanics but **does not replace AWP's explicit domain state**. Every lifecycle-changing command: ```text begin transaction load authoritative state / expected revision resolve Principal authorize evaluate domain + policy guards write domain state write business event + audit + outbox <- same transaction, atomic commit asynchronous providers / realtime consume the committed result ``` Non-negotiable: - state + business event + audit + outbox **commit atomically or not at all**; - no external network call held open inside a database transaction without an explicit proof it is safe; - retries are idempotent and distinguish operation identity from execution-attempt identity; provider idempotency keys include AWP operation/attempt identity where available; - mutable aggregates carry a revision/version; commands that would overwrite concurrent work use expected revisions and return conflict/stale state rather than last-write-wins; - immutable provenance/history is never rewritten to simplify a current-state query; - application use cases own transaction scope — domain modules do not open nested infrastructure transactions; - a module never mutates another module's tables as a shortcut; - realtime projections consume events and can never mutate authoritative state by bypassing application commands; - large logs/artifacts/checkpoints go to S3-compatible storage by immutable digest reference, not into relational columns. External side effects use transaction-outbox plus durable workflow: ```text commit intent/state -> durable workflow/provider call -> observe/reconcile result -> commit resulting lifecycle transition ``` Observed provider state updates observation fields or triggers a reconciler command. It never silently overwrites intended AWP state; drift surfaces as a Finding, Incident or blocked state. ### Data families ```text current authoritative state Projects, Plans/Revisions, Tasks, Runs, Attempts, Changes, Reviews, config immutable / provenance Decision history, Attempt provenance, ChangeSet revisions, Review dispositions, audit records — append/supersede only business event + outbox written in the state transaction; consumers are idempotent object references artifacts, large logs, checkpoints, evidence — S3-compatible, immutable digest + policy ``` Migrations are version controlled, forward/retry safe, and compatible with the increment's deployment strategy. Destructive changes need an explicit compatibility plan. Backfills are durable, idempotent and observable. A single PostgreSQL deployment is acceptable for dogfood — it still uses migrations, backup-capable storage and object-store references rather than local ephemeral files. ### Connection and security states `Connection` states are distinct and must not be collapsed into a generic "error": `connected`, `needs-resource-selection`, `needs-permission`, `needs-reauth`, `revoked`, `degraded/error`. Authentication failure, permission failure, resource-selection gaps, revocation and provider outage are different user situations with different remedies. ## The 9 ADRs, One Line Each ```text 0001 Three planes: Edge/Gateway -> Control -> Execution. Trust boundaries from day one; merging gateway and control authority needs a new ADR. 0002 Modular monolith control plane. Explicit domain/application/provider boundaries, enforced by fitness rules; extraction needs evidence. 0003 Hono for gateway and control-plane HTTP. Hono types terminate at the transport handler; contracts are runtime-neutral. 0004 PostgreSQL authoritative + Drizzle. Large objects by S3 reference. Provider observations are non-authoritative; secrets are references. 0005 DBOS TypeScript on PostgreSQL for durable workflows, behind DurableWorkflowProvider. It is mechanics, not domain state. 0006 Native Kubernetes WorkspaceProvider: Pod/PVC/ServiceAccount/ NetworkPolicy/RuntimeClass/owner refs. No custom CRD or operator. 0007 GitHub Actions + ARC on K3s for CI. (Runner-infrastructure timing descoped post-dogfood by the 2026-08-21 amendment A4; the provider choice itself is unchanged.) 0008 Helm render + Kubernetes Server-Side Apply for deployment. Activates at I6; the boundary is specified now. 0009 Single-operator authentication at the public gateway with Argon2id, opaque server-side PostgreSQL sessions, Secure HttpOnly __Host cookie, and control-plane Principal re-resolution on every owner request. ``` ## I0 Scope — Foundation Substrate Activate only what I1 needs: ```text modular-monolith runtime skeleton + package/deployable boundaries final IDs/types for Project, ProjectVision, Goal, Plan, Task, FactoryRun, AgentRun/Attempt, Workspace, ChangeSet, Review PostgreSQL/Drizzle persistence + the transaction pattern above business events / audit / outbox Principal + capability skeleton typed configuration Connection / CredentialReference seam provider + adapter framework minimal Forge provider + trusted publication boundary minimal account/model provider K3s execution substrate + isolated durable Workspace/WIP contract DBOS durable-workflow ownership and retry semantics structured logs + OTel-compatible telemetry boundary executable architecture-conformance checks (R1) ``` I0's proof burden is **one integration test per provider seam** (DBOS, Workspace/K8s, Forge, Factory, Agent, Account), deepened into failure matrices after the first dogfood. K3s pod execution containment is the exception: it is proven before any agent runs real work. ## I1 Scope — First Complete Vertical Slice Prove one lifecycle end to end: ```text Project + compact ProjectVision + Goal -> Plan -> Task with dependency/Queue legality -> FactoryRun -> AgentRun/Attempt on K3s -> durable WIP -> ChangeSet -> VerificationEvidence + repository-required checks -> independent Review -> trusted Merge ``` Required characteristics: durable authoritative state; observable progress; account/model Attempt provenance; isolated execution; WIP survival across failure; retry as a new Attempt; cleanup only after durable collection; visible failure/waiting states; trusted publication/merge separation; UI sufficient to understand current/next/blocked/completed work; no dependency on workstation state for normal agent execution. The owner-approved `docs/mockups/i1/` U1–U6 set is the I1 acceptance journey and the binding visual target **for I1**. Per amendment A5, it makes no claim about I2–I9 layout. ## Deferred — Do Not Build In I0/I1 ```text gVisor RuntimeClass compatibility proofs post-dogfood ARC ephemeral-runner day-one gate post-dogfood (hosted CI meanwhile) pluggable SecretStore implementation post-dogfood (contract stays) rich Planning / full Goal management I2 Decisions/Approvals/Autonomy, Project Manager, Search + command palette I3 full Factory/Agent observability, AWP Advisor I4 CI control plane I5 Release / Deployment / Helm activation I6 Cluster product surface I7 Incident / Resolver self-healing I8 multi-tenant, SLO/reliability, service extraction, partitioning/read replicas I9 Overdeck physical harvest parallel non-blocking track ``` Deferred does not mean undefined. The target semantics exist in the reference specs; do not implement them early, and do not invent temporary domain identities that the later increment would have to replace. ## Landing Policy — Internal Merge Protection (A7) GitHub branch protection is unavailable on this hosting plan. The gate is internal and mandatory: ```text code reaches main only via a PR whose CI job is green on its head commit docs-only changes may push directly (CI runs its docs-only fast path) never merge on a red or pending check red main = stop-the-line: fix forward or revert before landing anything else ``` ## Anti-Drift ```text do not implement a future capability merely because it is specified do not invent a temporary domain identity do not let code silently override an approved seam do not treat GOLIVE as a primitive do not let manual Queue priority bypass dependencies do not rebuild HTTP/workflow/auth/jobs/wire-protocol frameworks (see the No-Build Hold List in AWP-I0-I1-REUSE-PREFLIGHT.md) do not mark work Done without machine-verified evidence (see AWP-PAIN-INVARIANTS.md) ``` When evidence changes the design, record an explicit Decision or ADR and amend the affected document in the same logical change. A gate that turns out to be unsatisfiable gets amended with owner authority — it never gets silently bypassed. --- All other specs are reference material; where this digest conflicts with a reference spec, this digest and the ADRs win until amended.