# Projects Domain

**Status:** Approved target-state baseline — ProjectVision + Goals reconciled  
**First realization:** I1 product identity; I0 persistence/config seams.

## Target State

`Project` is the durable product boundary for one software-delivery context. It groups repositories, ProjectVision, Goals, Plans, defaults, policies, connection bindings, work/run history, delivery state and project-scoped observability without becoming a bucket for provider mechanics.

```text
Project
 ├─ Repository*
 ├─ ProjectVision
 ├─ Goal*
 ├─ Plan*
 ├─ ProjectPlanningDefaults
 ├─ ProjectDeliveryProfile
 ├─ ProjectConnectionBinding*
 ├─ ProjectPolicy / configuration overrides
 ├─ Work/Queue/Factory/CI/Release/Incident projections
 └─ Decision Log projection
```

## Identity and Ownership

`Project.id` is stable and independent of repository URL/provider. A Project may reference one or more repositories. Unbinding a repository does not rewrite Project history.

Project owns:

- human name/description and current product context;
- current/versioned `ProjectVision` relationship;
- Goal identities/lifecycle;
- repository relationships;
- project-scoped configuration/policy/defaults;
- allowed external connection bindings;
- planning/delivery defaults;
- project lifecycle status;
- project-level Decision/Approval/audit projections.

It does not own provider secrets, GitHub account identity, Kubernetes node identity or individual Run lifecycle state.

## ProjectVision

`ProjectVision` is the durable, versioned project-level statement of enduring intent generated/reconciled during onboarding and updated only through attributable material decisions.

It covers, where relevant:

```text
purpose / problem
primary users / jobs
intended direction
scope / major capabilities
non-goals
enduring product/technical/business constraints
material product principles
known assumptions / evidence provenance
current version / supersession relationship
```

It is not a giant speculative PRD and not a duplicate Plan or Goal.

For an existing Project, repository documents such as `VISION.md`, README, specs/plans and user-stated desired direction are evidence. AWP distinguishes observed current state, documented intended state, user-stated desired state and recommendation before accepting a ProjectVision version.

A material Vision change creates a new version/superseding Decision. Affected Goals, Planning defaults, Plans or readiness evidence may become stale/need review. Historical PlanRevisions retain provenance to the Vision context they were accepted under where material.

Optional repository materialization/export is policy-controlled; `ProjectVision` identity does not depend on a filename.

## Goals

`Goal` is the Project-owned outcome primitive. Examples include first go-live, next release, migration completion, production stabilization, feature parity or CI reliability improvement.

```text
ProjectVision
  enduring direction

Goal
  current/future outcome

Plan
  bounded work advancing Goal(s)
```

A Project may have multiple active/future/parked/achieved Goals. Plans may advance multiple Goals.

### Goal readiness

When a Goal has explicit readiness gates, including a launch Goal, AWP projects readiness from authoritative domains rather than maintaining a disconnected checklist:

```text
Goal
  state
  successCriteria
  readiness: Ready | Ready with accepted/deferred gaps | Blocked
  blockers
  deferred requirements + blockingAt consequence
  accepted risks
  supporting evidence
  owning primitive / next action
```

No fake percentage may imply readiness from simple item counts. Any progress statistic must expose its derivation.

`GOLIVE` is not a primitive. A go-live target is a Goal with launch-oriented success criteria and readiness evidence.

## Lifecycle

```text
draft/onboarding -> active -> paused -> archived
```

Archive prevents new work by default but preserves historical Goals, Plans, Runs, Decisions and Vision versions. Destructive purge is a separate high-risk policy-controlled operation.

## Commands

- CreateProject
- Inspect/OnboardProject
- Create/Accept/ReviseProjectVision
- Create/Update/SetGoalStatus
- LinkPlanToGoal / UnlinkPlanFromGoal
- BindRepository / UnbindRepository
- SetProjectConfigurationOverride / ResetOverride
- BindConnection / NarrowConnectionBinding
- UpdateProjectPlanningDefaults
- UpdateProjectDeliveryProfile
- Pause/Resume/ArchiveProject

Material ProjectVision/Goal/config/default changes create/supersede `Decision` records when they alter future behavior materially.

## Queries / Projections

Project overview exposes:

- active Goals and explainable Goal progress/readiness;
- Needs Your Attention items;
- blockers by type;
- next Queue/Factory candidate and why it is next;
- current Plans;
- current FactoryRuns/Agents;
- recent progress/completed work;
- current ProjectVision summary/version as secondary orientation;
- relevant health, Decisions, repository and connection status.

These are projections over authoritative primitives, not duplicated state.

## Invariants From Day 1

- Project ID survives repository/provider changes.
- ProjectVision is durable/versioned and cannot be silently overwritten.
- ProjectVision, Goal and Plan have distinct jobs and identities.
- `GOLIVE` is not a first-class primitive.
- project defaults never silently mutate because one Plan overrides them.
- connection binding can only narrow global Connection capabilities/resources.
- Plan/Task/Run can further narrow project policy, not self-broaden ceilings.
- archived Project retains history/provenance.
- every active Plan/Task/Run belongs to exactly one Project.
- Project overview may aggregate, but source primitives remain authoritative.
- Goal readiness is gate/consequence/evidence based, never cosmetic completion authority.

## Increment Realization

| Increment | Project realization |
|---|---|
| I0 | persistence/config/connection/repository seams. |
| I1 | create/select Project; compact ProjectVision; compact Goal linkage; minimal Plan/Task/Queue lifecycle and overview. |
| I2 | full onboarding, Vision generation/reconciliation, Goal management/readiness, Planning defaults and delivery profile. |
| I3 | Decision Log/autonomy/Approval depth + Project Manager/Search. |
| I4–I8 | richer Factory/CI/release/cluster/incident evidence feeds Goal/read-model projections. |
| I9 | Organization/tenant ownership, quotas, retention/supportability. |

## Failure / Recovery

Repository/provider inspection failure leaves Project durable in onboarding/attention state. Partial bindings/config changes are transactional. External connection failures do not corrupt Project state. Stale Goal readiness is marked stale and refreshed from sources rather than guessed.

## API / CLI / MCP

Stable Project IDs, ProjectVision versions and Goal IDs are accepted/returned consistently. UI/API/`aw*` CLI/MCP use the same application commands/queries.

## UI Implications

Project page is an operational project-management surface. Its primary scan order is Goals -> attention -> blockers -> Queue/next -> current Plans -> current FactoryRuns -> recent progress. Vision and Settings remain direct Project destinations but are not dominant overview content.

## Related

- [`goals.md`](goals.md)
- [`planning.md`](planning.md)
- [`work.md`](work.md)
- [`work-queue.md`](work-queue.md)
- [`../ui/project.md`](../ui/project.md)