# Work Domain

**Status:** Approved target-state baseline — dependency-aware Queue reconciled  
**First realization:** I1.

## Target State

The Work domain represents executable Plan decomposition independently of Factory provider mechanics. `Task` is the primary executable unit; optional `Wave`, `Phase` and generic `WorkItem` grouping express structure and policy.

```text
PlanRevision
  -> Work graph
       Task A ----> Task B
          \          |
           \------> Task C
  -> dependency-aware Queue
  -> FactoryRun realizes eligible selected work
```

## Task

A Task has stable ID, Project/PlanRevision ownership, Goal context, bounded scope, dependencies, acceptance/evidence expectations, constraints, execution selection/status and links to FactoryRuns/ChangeSets/Decisions.

Task identity survives retries and re-execution.

## Wave / Phase

Structural/grouping primitives only when the Plan explicitly uses them. They may carry ordering, synchronization or checkpoint semantics. AWP does not invent them for every Plan.

## WorkItem

A generic abstraction may support future custom methodology, but `Task` remains the concrete executable unit. Plan, Task and FactoryRun are distinct identities.

## Dependency Model

Hard Task dependencies are directed prerequisite relationships:

```text
Task A -> Task B
```

means B cannot dispatch until A satisfies the applicable dependency completion policy.

Rules:

- hard dependency graph is acyclic;
- cycles are rejected with a readable path;
- dependencies may cross Plan boundaries within the same Project when explicitly allowed;
- blocked dependency state names exact unsatisfied prerequisites;
- dependency meaning is domain truth, not inferred from visual position;
- informational/association edges use different relation types and do not affect dispatch legality.

## Queue Relationship

The Work Queue is an ordered projection/control surface over work eligibility.

```text
dependency legality
  first
policy/approval/resource legality
  next
manual priority among otherwise legal choices
```

The Queue can expose a legal movement range for a Task. UI drag/drop may proactively block illegal locations, but server/domain validation remains authoritative.

Completing a prerequisite re-evaluates dependents and may transition them to READY automatically when no other gate remains.

## Task Lifecycle

```text
planned -> ready -> queued -> executing
 -> waiting/blocked
 -> review/correction
 -> completed
 -> cancelled
 -> failed (terminal only when retry/resolver policy exhausted)
```

Display states may aggregate, but domain reasons stay structured.

## Execution Policy

Plan/Project resolves topology:

- sequential;
- phase/wave;
- dependency DAG;
- custom workflow.

Concurrency limit, integration checkpoints, retry/resolver and pause/escalation are separate policy. Scrum/Kanban/Scrumban methodology is not the execution graph itself.

## Acceptance / Evidence

Task declares what outcome must be demonstrated. Completion requires accepted ChangeSet/evidence/result as defined by Task/Plan, not merely process exit.

## UI Implications

### Plan / Task surfaces

Show hierarchy, dependencies, progress and current/previous FactoryRun relationships. Plan and Task rows/nodes navigate directly to their authoritative details.

### Queue

Show dependency indicators such as:

```text
Depends on 2
Blocks 3
Cross-plan dependency
```

Invalid reorder locations are unavailable before drop and explain the blocking prerequisite/dependent.

### Graph

The dependency visualization is a compound directed dependency graph (DAG):

```text
Plan = group/container
Task = node
hard dependency = prerequisite -> dependent edge
```

Cross-Plan edges cross group boundaries. Clicking Plan/Task opens that primitive. Filtering may not hide the semantic existence of external prerequisites.

## Invariants From Day 1

- Task identity survives retries/re-execution.
- AgentRun/Attempt identity is separate from Task.
- hard dependency graph is acyclic.
- blocked dependency state is explicit/explainable.
- manual Queue priority cannot violate hard dependencies.
- client validation never replaces domain validation.
- concurrent tasks may not silently violate shared resource/source integration constraints.
- completion requires accepted outcome/evidence, not process exit.
- material Task scope/dependency changes after execution starts retain Decision/revision provenance.

## Increment Realization

| Increment | Work realization |
|---|---|
| I1 | final Task identity, hard dependencies, Queue legality/readiness, compact Queue/Graph visibility needed for dogfood, Factory links. |
| I2 | rich Plan-generated decomposition/methodology/execution policy. |
| I4 | deeper large-graph/live execution visualization and analytics where useful. |
| I5 | change-impact/verification relationships. |
| I7 | capacity/placement context deepens Queue without replacing Work authority. |
| Later | richer custom workflow semantics without changing Task identity. |

## Failure / Recovery

Task failure is not synonymous with one Attempt failure. Retry/correction/resolver creates linked execution records. Dependency blockage remains visible and reversible when upstream work changes.

## Related

- [`goals.md`](goals.md)
- [`planning.md`](planning.md)
- [`work-queue.md`](work-queue.md)
- [`../ui/queues-and-dependency-graph.md`](../ui/queues-and-dependency-graph.md)

## Decisions / ADRs

Material Task scope/dependency/topology changes are Decisions when they alter Plan outcome/risk or invalidate downstream work.