# AWP Increment 0/1 Design Decision Batch **Date:** 2026-08-19 **Status:** **APPROVED IN FULL.** Original `I01-D1` is rejected and replaced by approved `I01-D1R`. `I01-D2..D14` are owner-approved. **Purpose:** Preserve the approved Increment-0/1 design boundaries while full AWP target specifications are written before implementation. **Delivery authority:** [`AWP-INCREMENTAL-DELIVERY-PLAN.md`](AWP-INCREMENTAL-DELIVERY-PLAN.md). **Full-specification authority:** [`AWP-FULL-SPECIFICATION-RATIFICATION.md`](AWP-FULL-SPECIFICATION-RATIFICATION.md). **Intent-preservation strategy:** [`AWP-TARGET-STATE-AND-INCREMENT-REALIZATION-STRATEGY.md`](AWP-TARGET-STATE-AND-INCREMENT-REALIZATION-STRATEGY.md). **Realization matrix:** [`AWP-INCREMENT-REALIZATION-MATRIX.md`](AWP-INCREMENT-REALIZATION-MATRIX.md). **Live Factory testing:** [`AWP-DOGFOOD-LIVE-FACTORY-TESTING-POLICY.md`](AWP-DOGFOOD-LIVE-FACTORY-TESTING-POLICY.md). ## I01-D1 — Earlier minimal-spec boundary — REJECTED The earlier recommendation to make only the Increment-0/1 contracts fully specified before coding is rejected because it risks losing full-system intent across later increments. ## I01-D1R — Full canonical specs, increment-scoped realization — APPROVED ```text full AWP architecture/domain/workflow/UI specs now + final seams / ownership / identity / authority / invariants now + HTML human companions now + explicit I0..I9 Increment Realization mapping + implementation remains bounded by the increment plan ``` Every early implementation must be a compatible subset of the target model rather than a throwaway temporary domain model. Later increments are deferred **realization**, not deferred design intent. See [`AWP-FULL-SPECIFICATION-RATIFICATION.md`](AWP-FULL-SPECIFICATION-RATIFICATION.md). --- ## I01-D2 — Minimal Increment-1 Plan interaction — APPROVED Increment 1 uses a deliberately small **interaction surface**, not a separate throwaway Plan model. The full Plan/PlanRevision target contract is specified now. I1 realizes only what it needs: ```text id project/repository base ref/revision name goal / desired outcome constraints / supplied instructions Task(s) execution selection created/updated state ``` Entry paths: ```text write/paste a small work request or import/reference an existing plan/spec/task ``` Planning Profile, Simple/Expert, delivery interview and Start/Schedule/Park are specified now but become operational in I2. --- ## I01-D3 — Task and FactoryRun boundary — APPROVED The full Work/Task/Factory target contract is specified now. I1 must support multiple Tasks and explicit dependencies in the domain, while acceptance fixtures remain intentionally small. ```text Plan -> Task[] dependencyIds[] goal acceptance/evidence expectations execution state FactoryRun -> executes selected Plan/Task graph ``` I1 proves at least one single-Task happy path and one two-Task dependency fixture without activating the later full Factory graph UX. Fabro remains the primary FactoryProvider; AWP owns Task/FactoryRun/AgentRun identity and lifecycle. --- ## I01-D4 — Run, Attempt, account and model provenance — APPROVED ```text AgentRun -> Attempt 1 -> Attempt 2 -> ... ``` Provider/account/model are immutable inputs of one Attempt. Retry, account exhaustion or model fallback creates a new Attempt. Persist on every Attempt: ```text AgentProvider Account Model reason for selection/fallback workspace/execution profile start/end/result checkpoint/change provenance ``` Live-test routing follows [`AWP-DOGFOOD-LIVE-FACTORY-TESTING-POLICY.md`](AWP-DOGFOOD-LIVE-FACTORY-TESTING-POLICY.md). --- ## I01-D5 — Workspace and WIP durability — APPROVED Each coding AgentRun gets an isolated K3s workspace rooted at a known immutable source revision. ```text base commit -> isolated Workspace -> agent modifications -> durable/checkpointed recoverable WIP -> terminal ChangeSet collection -> durable ChangeSet/evidence -> only then cleanup disposable compute ``` A pod may be disposable; recoverable work may not be. Retry after process/pod/node failure must resume preserved WIP or explicitly start a new Attempt from the latest durable checkpoint. No normal AgentRun executes on the user's workstation. --- ## I01-D6 — ChangeSet and trusted publication boundary — APPROVED The agent does not push or merge. `ChangeSet` is the authoritative AWP representation of the proposed source change and includes at minimum: ```text project/repository base commit resulting tree/head identity or patch identity changed paths diff/content digest originating Task / AgentRun / Attempt verification evidence references publication state ``` ```text AgentRun produces WIP -> AWP collects ChangeSet -> trusted control-plane publisher verifies base/fidelity -> publishes AWP-owned branch/commit/PR as needed -> Review -> trusted merge ``` Git publication credentials remain outside AgentRun/CI workloads. --- ## I01-D7 — Increment-1 Review semantics — APPROVED `Review` is first-class from I1 while richer later review/approval semantics remain defined in the full target spec. Default dogfood path uses an independent reviewer agent and keeps human inspection available. ```text reviewer consumes ChangeSet + existing verification evidence reviewer has no merge authority reviewer does not rerun valid checks without a new reason reviewer is read-only in the default path ``` Changes requested return to coding: ```text Review -> changes requested -> correction AgentRun/Attempt -> new ChangeSet revision -> focused re-verification -> re-review ``` The reviewer does not silently edit the candidate and approve its own edits in one step. --- ## I01-D8 — Minimal Increment-1 verification and MergeGate — APPROVED The full Verification/CI target contract is specified now, but I1 operationalizes only the minimum trustworthy merge evidence path: ```text focused verification required by Task/change + repository-required GitHub checks when configured + independent Review disposition + ChangeSet/base/fidelity verification + no unresolved blocking review state ↓ trusted control-plane MergeGate ``` A thin authoritative `VerificationEvidence`/check-result realization exists in I1. Change classification, CI planning, evidence optimization and full VerificationAuthority operations activate in I5. ARC/GitHub Actions remain day-one substrate without pulling the I5 CI product UI/planner into I1. --- ## I01-D9 — Security/threat boundary for privileged dogfooding — APPROVED Before the first privileged I1 dogfood run, maintain an explicit AWP threat model covering: ```text browser/gateway -> control plane trust provider/model credentials GitHub connection/publication authority K3s execution untrusted agent code Workspace isolation WIP/checkpoint storage AgentRun -> trusted publisher boundary Review -> merge authority boundary webhook/provider event trust ``` Use OWASP conventions and Threat Dragon where useful. Mitigations required by I1 become current implementation requirements. Enterprise controls remain later realization but their target trust boundaries are fully specified now. --- ## I01-D10 — Increment-1 user-facing surface and high-fi set — APPROVED The full product information architecture and page behavior are specified now. I1 implements and high-fi approves only the states it ships: ```text U1 Project + minimal Plan/Task creation/selection U2 FactoryRun active: current Task, AgentRun, provider/model/account, progress U3 Waiting/failure/retry: reason, preserved work, next action U4 ChangeSet/Review: diff, changed files, evidence, reviewer disposition U5 Ready to merge: exact candidate, checks/evidence, merge action U6 Merged/completed: resulting commit/PR/merge identity and lifecycle history ``` Each surface specifies relevant Empty / Loading / Error / Stale behavior. Rich I2 Planning and I4 Factory observability remain later realization while their target page relationships are already part of the full specification set. --- ## I01-D11 — Increment-1 acceptance journeys — APPROVED ### J1 — happy-path dogfood change ```text select/create AWP Project -> create minimal Plan + Task -> start FactoryRun -> AgentRun executes on K3s -> produces a real small source change -> focused verification evidence collected -> ChangeSet published by trusted control plane -> independent Review approves -> trusted merge -> UI shows merged result and provenance ``` ### J2 — execution interruption and recovery ```text AgentRun has WIP -> kill process/pod or simulate recoverable interruption -> WIP/checkpoint survives -> retry/new Attempt -> lifecycle continues without silent work loss ``` ### J3 — model/account exhaustion fallback ```text Spark Attempt hits exhaustion/unavailability -> failure reason visible -> WIP/checkpoint preserved -> next eligible account/model selected -> new Attempt records provenance -> lifecycle continues ``` ### J4 — review rejects and correction succeeds ```text ChangeSet -> Review requests changes -> correction AgentRun -> new ChangeSet revision -> focused re-verification -> re-review -> merge ``` --- ## I01-D12 — Increment-1 dogfood exit criterion — APPROVED I1 exits only when AWP can use AWP to make a small real change to the AWP repository through the complete lifecycle without normal agent execution on the workstation: ```text Project -> Plan -> Task -> FactoryRun -> AgentRun on K3s -> ChangeSet -> Review -> trusted Merge ``` The run is durable, observable, retryable and recoverable through the tested failure cases with enough polished UI to understand what happened. --- ## I01-D13 — Explicitly deferred operational scope — APPROVED The following are fully specified now but not operationally activated in I0/1: ```text rich Simple/Expert Planning interview I2 generic autonomy policy I3 full Project Decision Log productization I3 full Factory graph/chat/files/cost UX I4 change classifier / CI optimizer/planner I5 full VerificationAuthority productization I5 Release / Environment / Deployment / CD I6 full Cluster product surface I7 generic self-healing operations I8 enterprise tenancy/public API/SLO machinery I9 ``` This is a realization defer list, not a specification defer list. --- ## I01-D14 — No serial Increment-0/1 technical interview — APPROVED The owner-facing I0/1 technical decision batch is closed. Next sequence: ```text 1. write the full AWP target specification system 2. generate all mandatory human HTML companions + diagrams 3. cross-check I0..I9 realization boundaries 4. make I0/1 exact shipped UI states high-fi 5. present consolidated full-spec + I0/1 high-fi review 6. amend differences 7. begin I0 implementation 8. complete I1 end to end and dogfood ``` Only surface a new owner decision before implementation if specification work uncovers a genuine OwnerRequired choice or a contradiction that cannot be resolved from accepted intent. ## Approval record ```text I01-D1 original REJECTED I01-D1R APPROVED / RATIFIED I01-D2 APPROVED I01-D3 APPROVED I01-D4 APPROVED I01-D5 APPROVED I01-D6 APPROVED I01-D7 APPROVED I01-D8 APPROVED I01-D9 APPROVED I01-D10 APPROVED I01-D11 APPROVED I01-D12 APPROVED I01-D13 APPROVED as realization defer list I01-D14 APPROVED ```