# Domain Model **Status:** Approved target-state baseline — Goals, dependency-aware work, Advisor/Search integrated **First realization:** I0/I1 core; rich Planning I2; Advisor/Search I3+. ## Target State AWP models the software-delivery lifecycle as related primitives with AWP-owned stable IDs. Provider identity never replaces AWP identity. ```text Project ── Repository* │ ├─ ProjectVision ├─ Goal* │ └── Plan* <──────────────┐ │ └─ PlanRevision │ │ └─ Task* ────┼── dependency DAG / Queue │ │ └──────────────────────── FactoryRun │ AgentRun │ Attempt* ─ Workspace │ ChangeSet │ VerificationEvidence │ Review │ Merge │ Artifact / Release │ Environment / Deployment ``` Cross-cutting: ```text Principal · Policy · Approval · Decision Provider · Account · Model · Connection · CredentialReference AdvisorPersona · AdvisorThread · AdvisorTurn CIExecution · CIResult · CIInvariant · VerificationAuthority Cluster · Machine · Workload · PlacementDecision Incident · Resolver · ResolutionAttempt CommunicationEndpoint · Notification ``` `Search` and `Queue` read models are projections over canonical primitives. They do not become alternate lifecycle authorities. ## ProjectVision, Goal and Plan These three concepts are deliberately distinct: ```text ProjectVision durable versioned statement of enduring product purpose, users/jobs, direction, non-goals and enduring constraints Goal current/future Project outcome actively pursued Plan / PlanRevision bounded software-delivery intent that advances one or more Goals ``` A go-live target is a normal `Goal`. `GOLIVE` is not a primitive. A material ProjectVision change creates a new version/superseding Decision and may invalidate current Goal assumptions, Planning defaults or Plan assumptions. Historical PlanRevisions retain the Vision/Goal context they were accepted against where material. ## Work and Dependency Model `Task` is the primary executable unit. Hard execution dependencies form a directed acyclic graph: ```text Task A ---> Task B prerequisite dependent ``` Dependencies may cross Plan boundaries inside the same Project when explicitly allowed. A Task is not dispatch-eligible while required prerequisites are unsatisfied. Queue priority is user intent constrained by the dependency DAG and policy. Manual priority cannot make an illegal ordering legal. ## Advisor Primitives Advisors are bounded control-plane agents for analysis and decision support. Their conversation state is distinct from software-delivery truth and execution AgentRuns. ```text AdvisorPersona versioned role/instructions/scope/model/capability policy AdvisorThread durable conversation identity bound to Principal + persona version + explicit scope AdvisorTurn attributable user/advisor/tool turn with context/source/proposal references ``` Initial built-ins: ```text Project Manager ProjectScoped AWP Advisor SystemScoped ``` Advisor conclusions become durable product truth only through canonical primitives such as ProjectVision, Goal, Decision, PlanRevision, Task, Policy or Configuration. ## Agent Role Boundary ```text Planner Agent Planning / PlanRevision formation Advisor Agent canonical-state analysis + proposals Resolver Agent bounded technical diagnosis/recovery Execution Agent coding/review/fix inside Factory execution ``` Prompt text cannot broaden a role's capability or authorization. ## Identity Rules - IDs are opaque, immutable and globally unique within AWP namespace. - Provider references are mappings, not business identity. - ProjectVision has stable Project-scoped version history. - Goal has stable Project-scoped identity and lifecycle. - Plan has stable identity; accepted material changes create PlanRevision. - Task identity survives retries/re-execution. - AgentRun is logical assignment; Attempt is concrete provider/account/model/workspace execution. - ChangeSet identifies candidate source change independently of forge branch/PR URL. - accepted Decisions are immutable and superseded rather than rewritten. ## Ownership Boundaries | Primitive | Owns | Does not own | |---|---|---| | Project | project scope/defaults/connections/repositories | provider mechanics | | ProjectVision | enduring versioned product intent | work breakdown/current Goal state | | Goal | current/future outcome + criteria/linkage | execution lifecycle | | Plan/PlanRevision | approved bounded work intent | live execution state/whole-project purpose | | Task | work scope/dependencies/acceptance expectations | pod/process lifetime | | FactoryRun | orchestration instance for 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 source change/provenance | merge authority | | Review | finding/disposition | candidate mutation/merge authority | | CIExecution | normalized CI occurrence | provider workflow source definition | | Release | immutable release intent | environment rollout mechanics | | Deployment | rollout lifecycle | package build identity | | Decision | material choice/rationale/consequence | authorization itself | | Approval | authorization disposition | design rationale | ## Lifecycle Relationships A parent lifecycle may constrain child creation but never erases child history. Retry creates explicit Attempt/revision records. Cross-domain state changes emit business events and audit atomically with authoritative state. ProjectVision/Goal supersession does not rewrite historical Plans. It marks affected current assumptions/artifacts for impact review. Advisor proposal acceptance invokes the canonical target command and links the proposal to resulting product state; there is no advisor-private mutation store. ## Provider Mapping ```text ProviderReference { providerId accountId resourceType nativeId nativeRevision? observedAt } ``` Adapters reconcile provider observations into AWP primitives and do not expose provider SDK objects through domain APIs. ## Increment Realization | Family | First realization | Deepening | |---|---|---| | Project/Repository | I0 seam / I1 product | I2 onboarding; I9 org/tenant | | ProjectVision | I1 compact | I2 generation/reconciliation/version UX | | Goal | I1 compact linkage | I2 full Goal management/readiness | | Plan/Task/dependencies | I1 | I2 rich Planning; I4 graph depth | | Queue | I1 legal ordering/read model | I7 cross-cluster/capacity depth | | FactoryRun/AgentRun/Attempt/Workspace | I0 substrate / I1 live | I4 observability; I7 infrastructure UX | | AdvisorPersona/Thread/Turn | target-specified | I3 Project Manager; I4 AWP Advisor; later experts | | ChangeSet/Review/Evidence | I1 | I5 CI/evidence depth | | Decision/Approval/Policy | narrow gates earlier | I3 generic productization | | Search/read-model projection | target-specified | I3 palette/full Search | | CI | substrate/required checks I0/I1 | I5 full control plane | | Artifact/Release/Deployment | target seam | I6 activation | | Cluster | substrate I0 | I7 product UI | | Incident/Resolver | local failure semantics earlier | I8 generic productization | | Reliability | target boundary | I9 activation | ## Current Implementation State Target domain model is specification authority; no legacy Overdeck storage model is inherited as a requirement. The repository remains pre-I0 implementation. ## Invariants From Day 1 - ProjectVision != Goal != Plan. - `GOLIVE` is not a primitive. - hard Task dependencies are acyclic and authoritative for dispatch legality. - manual priority cannot override dependency/policy constraints. - compute may be disposable; accepted WIP is durable until deliberate terminal cleanup. - agents never inherit trusted publication/merge authority from prompt text. - provider-native IDs never replace AWP IDs. ## Decisions / ADRs See `domains/goals.md`, `domains/work.md`, `domains/work-queue.md`, `domains/approvals-decisions.md`, `domains/advisory-personas.md` and `architecture/search-and-command-palette.md`.