# AWP Target-State and Increment Realization Strategy **Date:** 2026-08-19 **Status:** **RATIFIED / BINDING** **Authority:** Detailed anti-drift interpretation of [`AWP-FULL-SPECIFICATION-RATIFICATION.md`](AWP-FULL-SPECIFICATION-RATIFICATION.md). **Purpose:** Preserve the full product/architecture intent across weeks or months of incremental implementation so later increments cannot drift into locally convenient but globally incompatible designs. ## 1. Problem being solved AWP is intentionally delivered incrementally, but incremental delivery must not become incremental product memory. The failure mode to prevent is: ```text Increment 1 ships a locally convenient model -> Increment 2 extends that local model -> original Planning/CI/CD/Factory intent is no longer active context -> later seams are forced around accidental early choices -> future UI and architecture become inconsistent -> the product has drifted away from the design without one explicit decision ``` At product level this is reasonably called **vision drift**. More precise engineering failure modes are: ```text design-intent drift architecture drift requirements/decision drift increment-local optimization that violates target-state seams ``` AWP must defend against all four. ## 2. Ratified direction > **Plan and specify the complete target state now; deliver that target state incrementally.** Increment boundaries control **when behavior is realized**, not **when the system is allowed to know what it is supposed to become**. ```text FULL TARGET-STATE PRODUCT / ARCHITECTURE SPECIFICATION written before implementation materially begins + INCREMENT REALIZATION PLAN says which already-specified subset becomes operational in I0..I9 + PER-INCREMENT DESIGN COMPLETE GATE validates current high-fi + realization boundary before code = full design memory + incremental delivery ``` This supersedes the earlier minimal-spec interpretation. ## 3. Full specification versus implementation mechanics Full specification is required early for: ```text product/domain primitives and ownership relationships between primitives stable identity rules module boundaries and dependency direction trust/authority boundaries provider/adapter seams persistence authority and transaction/event rules major lifecycle/state-machine semantics configuration/policy inheritance Decision / Approval / evidence relationships Planning -> Work -> Factory -> Agent -> ChangeSet -> Review -> CI -> Release -> Deployment relationships Connection / CredentialReference boundaries realtime vs authoritative-state rules compatibility/versioning expectations full product information architecture and core page/workflow behavior increment-to-increment realization constraints ``` The full spec does not need to freeze private implementation details that can change behind those seams without changing the contract, such as internal helper algorithms, SQL index tuning, measured concurrency constants or provider-version request plumbing. Rule: > **Specify every behavior/invariant/seam whose later change would affect product or architecture. Defer only mechanics that can vary behind the defined contract.** ## 4. Every canonical spec carries target truth and realization timing Required structure: ```text Target State complete intended semantics and boundaries Invariants From Day 1 constraints early code may never violate Increment Realization I0..I9 activation/deepening map Current Implementation State what exists now Deferred Realization already-specified target behavior intentionally not operational yet Temporary Dogfood Behavior explicit shortcut + reason + compatibility constraint + removal/deepening increment Decisions / ADRs why the target exists and what may supersede it ``` Do not create unrelated `minimal` and `future` truth sources for the same primitive. ## 5. Increment Realization Matrix The canonical capability-to-increment map is [`AWP-INCREMENT-REALIZATION-MATRIX.md`](AWP-INCREMENT-REALIZATION-MATRIX.md) with human view [`AWP-INCREMENT-REALIZATION-MATRIX.html`](AWP-INCREMENT-REALIZATION-MATRIX.html). The matrix prevents a future contributor from interpreting: ```text not implemented yet ``` as: ```text not designed / free to reinvent ``` ## 6. Early implementations must be subsets of the target model A narrow increment is allowed. A throwaway incompatible domain model is not. Example: ```text Target Plan model Plan PlanRevision Decisions Tasks execution/delivery relationships readiness/launch semantics Increment 1 UI creates/uses only the subset needed to run Task(s) NOT TemporaryPlan with unrelated identity/state followed by a migration into the real model in Increment 2 ``` The same rule applies to Review, VerificationEvidence, Connection, CIExecution, Artifact, Release and Deployment. ## 7. Decision and ADR protection against drift Material target-state choices record: ```text what was decided why alternatives consequences confidence/evidence what depends on it which increment first realizes it what would justify reopening it ``` If implementation pressure suggests violating a target seam: ```text implementation discovers mismatch -> do not silently code around it -> create/reopen Decision -> impact analysis -> update target spec -> update Increment Realization Matrix -> update affected mockups if needed -> implement the amended direction ``` Architecture-significant Decisions project to ADRs. ## 8. Drift gate before every increment Before an increment enters implementation: ```text 1. Which target-state contracts does this increment touch? 2. Which already-specified parts become operational now? 3. Which future invariants constrain the implementation now? 4. Are temporary dogfood shortcuts introduced? 5. Do they preserve the final seam and have a removal/deepening increment? 6. Does anything contradict an accepted Decision/spec? ``` Contradictions become Decision/spec changes, never implicit drift. ## 9. Human readability is intent preservation The HTML specification system is part of the anti-drift architecture. A human reviewing a current increment must be able to navigate: ```text current realization -> target state -> later realization increments -> linked Decisions / ADRs -> affected workflows -> page specs / approved mockups ``` `docs/specs/INDEX.html` must support both domain/spec navigation and increment-realization navigation. ## 10. UX / visual intent across increments Specify early: ```text full information architecture navigation model product shell shared design system / visual language major screen relationships primary journeys across future increments complete target page behavior ``` Before an increment implements a user-facing state, approve its exact high-fidelity design including material error/waiting/permission/responsive variants. This prevents an increment from creating a polished but dead-end product shell. ## 11. Relationship to incremental delivery The implementation sequence does not change: ```text I0 foundation/self-hosting substrate I1 Project -> Plan -> Task -> FactoryRun -> AgentRun -> ChangeSet -> Review -> Merge I2 Real Planning I3 generic autonomy / Decisions / Approvals I4 full Factory observability UX I5 CI control plane I6 Release / Deployment I7 Cluster product surface I8 self-healing I9 external/enterprise productization + formal SLO/error-budget machinery ``` What changes is specification timing: ```text ALL TARGET SPECS NOW IMPLEMENTATION BY I0..I9 ``` ## 12. Full specification scope before Increment 0 Reach coherent full target specifications across: ```text Architecture topology modules/dependencies persistence/transactions durable execution events/audit/realtime security/trust configuration/policy connections/credentials workspace/execution provider/adapter contracts CI/runner boundary release/deployment boundary reliability boundary Domains Project / Repository Plan / Planning Work / Task / dependencies FactoryRun / AgentRun / Attempt / Workspace ChangeSet / Commit Review Verification / CI Decision / Approval / Policy Artifact / Release / Environment / Deployment Cluster / Machine / Workload Incident / Resolver Communication / Notification ReliabilityPlan / SLI / SLO / error budget Cross-domain workflows project -> plan -> task -> factory -> change -> review -> merge planning -> execution change -> verification -> merge merge -> release -> deployment connection onboarding/return machine/cluster operations incident -> resolution reliability policy response UI whole-product IA / shell / navigation complete target page behavior increment realization for each surface ``` ## 13. What may evolve Full specifications are durable authority, not immutable dogma. ```text new evidence -> Decision -> affected-spec links -> target-state amendment -> increment matrix amendment if needed -> mockup amendment if affected -> implementation follows ``` That is explicit evolution rather than drift. ## 14. I01-D1R — APPROVED **Full target-state intent, full canonical specifications, increment-scoped realization** is approved. 1. Write the complete AWP target-state architecture/domain/workflow/UI specification set before implementation materially begins. 2. Define final seams, ownership, identity, authority, relationships and invariants from day 1, including later-increment domains. 3. Give every spec an explicit `Increment Realization` map. 4. Keep current increment implementation and high-fi bounded by the canonical I0..I9 plan. 5. Require every early implementation to be a compatible subset of the final model. 6. Mark dogfood shortcuts explicitly with compatibility constraints and a removal/deepening increment. 7. Reopen a Decision before violating an approved target-state seam. 8. Keep R5 operational machinery parked at I9 while its target contract is still fully specified now. ## 15. Approval state ```text I01-D1 original REJECTED I01-D1R APPROVED / RATIFIED I01-D2..D14 APPROVED ``` Full-specification policy is further ratified in [`AWP-FULL-SPECIFICATION-RATIFICATION.md`](AWP-FULL-SPECIFICATION-RATIFICATION.md).