# Planning Domain

**Status:** Approved target-state baseline — ProjectVision + Goals reconciled  
**Activation:** I2 Real Planning; narrow Plan subset in I1.

## Target State

Planning turns ProjectVision + current Goal context + user intent into a durable, inspectable, versioned and executable `Plan` without requiring users to reconstruct state from chat history.

```text
Project + current ProjectVision + Goal context + user request
  -> PlanningSession
  -> inferred PlanningProfile
  -> PlanningWorkflow
       DEFINE
       DESIGN
       SPECIFY
       DELIVER
       LAUNCH
  -> Decisions / Findings / Risks / Artifacts / Deferrals / Evidence
  -> PlanRevision
  -> Ready | Ready with accepted/deferred gaps | Blocked
  -> Start now | Schedule | Park
  -> execution
```

Planning is structured product state. Conversation is an interaction surface, not the source of truth.

## ProjectVision / Goal / Plan Relationship

```text
ProjectVision
  enduring product direction and constraints

Goal
  current/future outcome being pursued

Plan
  bounded work that advances one or more Goals
```

A PlanRevision records the ProjectVision version and Goal linkage it was accepted against where material.

Planning does not silently rewrite ProjectVision or Goal state merely because one Plan needs an exception.

If Planning discovers that enduring Project direction changed:

```text
Finding / OwnerRequired Decision
 -> propose ProjectVision revision
 -> accept/supersede through Project domain
 -> re-evaluate affected Goals/defaults/Plan assumptions
 -> continue against explicit new Vision context
```

If Planning discovers a new or changed target outcome:

```text
Finding / OwnerRequired Decision
 -> create/update Goal
 -> explicitly link affected Plan(s)
 -> re-evaluate priority/readiness
```

A go-live target is a normal Goal with launch-oriented criteria; Planning does not create a special `GOLIVE` object.

## Core Primitives

### Plan

Stable identity for planned software work. It owns revision history and relations to Project, applicable ProjectVision context, Goal linkage, Tasks, execution/delivery defaults and launch intent.

### PlanRevision

Immutable/accepted snapshot of Plan intent and effective planning outputs. Material changes after approval create a new revision rather than silently editing execution history.

### PlanningSession

Durable interaction context for building/revising one Plan. Persists active item, draft input, agenda, conversation references and return targets across refresh, redirects, compaction and agent changes.

It also owns the effective/overridden Planner routing reference for the session and durable Planner-turn metadata. Each Planner model turn records immutable provider/account/model provenance, input session revision, timestamp and structured disposition/failure metadata. Conversation text remains non-authoritative evidence; accepted Planning state remains typed.

Planner routing inheritance is:

```text
PlanningSession explicit override
 -> Project Planning interviewer default
 -> System Planning interviewer default
 -> not configured / visible blocker
```

Planner routing is independent from Factory execution routing. Changing a default affects future turns that inherit it; historical turn provenance never changes.

### PlanningWorkflow

Conditional requirement/gate graph generated from PlanningProfile + discovered Project traits + ProjectVision + Goal context + accepted Decisions.

Stable top-level landmarks:

```text
DEFINE
DESIGN
SPECIFY
DELIVER
LAUNCH
```

Concrete children are dynamic.

### PlanningProfile

Workflow preset inferred from evidence, not an authoritative taxonomy. Independent traits include user-facing UI, untrusted code, customer data, package publication, production deployment, stable contracts, critical accessibility/security and similar workflow-driving facts.

### DecisionDeferral

```text
item
reason
blockingAt
owner
consequence
revisit trigger/date
status
```

Deferral is allowed only when uncertainty is bounded and the later blocking consequence is explicit.

## Participation Modes

```text
Simple
Expert
```

Mode controls user participation, not planning completeness or technical quality.

### Decision Participation Classes

```text
OwnerRequired
DelegableExpert
PolicyRequired
```

**OwnerRequired:** only owner can legitimately choose ProjectVision/Goal direction, taste/UX preference, pricing, business/customer policy, budget/risk acceptance, commitments and equivalent intent.

**DelegableExpert:** AWP may decide from evidence/defaults/engineering judgment. The Decision remains visible/changeable.

**PolicyRequired:** explicit consent/Approval required regardless of mode for provider authorization, capability broadening, destructive action, protected production gate, configured security/budget policy, etc.

### Simple Mode

AWP asks primarily OwnerRequired and PolicyRequired items. Technical Decisions are made visibly without forcing every choice into conversation.

### Expert Mode

Same complete Plan, but technical recommendations become normal review/refutation items. User may participate deeply in architecture, quality/CI/CD, deployment, libraries, security, execution topology and integrations.

Mode switching preserves state.

## Project Planning Defaults

```text
first substantial Plan in Expert mode
 -> deep technical choices
 -> identify reusable subset
 -> explicit “Use as Project defaults” review
 -> ProjectPlanningDefaults
 -> later Simple Plans inherit defaults
 -> only deltas/relevant owner decisions surface
```

Plan-specific exceptions never silently change Project defaults, ProjectVision or Goal state.

## Recommendation Contract

Every material recommendation can expose:

```text
recommendation
confidence: high | medium | low
basis: repository evidence | accepted Decisions | standard | inference | research
material consequences
what would change the recommendation
credible alternatives
```

Recommendation-first UX uses one primary Accept action. Rejection opens focused discussion for that Decision only.

## Existing-Project Truth Model

Never collapse conflicting evidence. Distinguish:

```text
Observed current state
Documented intended state
User-stated desired state
Accepted ProjectVision
Accepted Goals
AWP recommendation
```

Conflicts become Finding/Decision/OpenQuestion with consequences and impact.

## Quality / CI / Delivery Outputs

Planning produces or resolves:

```text
QualityStrategy
CIPlan
ReleaseStrategy
EnvironmentStrategy
PromotionPolicy
DeploymentStrategy
DeploymentProvider
Rollback/recovery policy
Connection requirements/bindings
ExecutionPolicy
```

Together these form ProjectDeliveryProfile defaults + per-Plan EffectiveDeliveryPlan.

## Readiness and Gates

No fake percentage. Plan readiness is:

```text
Ready
Ready with accepted/deferred gaps
Blocked
```

A blocker is a required absent Decision, contradiction, missing artifact/evidence, unbounded invalidating assumption, unresolved security/trust issue, unsatisfied hard Task dependency, or downstream choice impossible.

Goal readiness may aggregate Plan/CI/Delivery evidence separately. Completing a Plan does not automatically achieve its Goal.

Final launch-oriented Goal readiness covers scope/non-goals, architecture/security, specs/acceptance, QualityStrategy, EffectiveDeliveryPlan, ExecutionPolicy, approvals/connections and no unsafe undefined blocker.

## Planner Leadership Contract

Every planner turn:

```text
1. resolve/respond to current input
2. update structured Planning state/artifacts
3. surface new Finding/Risk/OpenQuestion
4. decide whether current area is sufficiently resolved
5. select highest-value next unresolved item
6. lead into it with recommendation/brief or one consequential question
```

Agenda priority: blocking dependencies, high-impact unresolved Decisions, invalidating risks, information required by next stage, time-sensitive setup/research, low-cost decisions unlocking downstream work.

## Task Dependencies and Queue

Planning may create hard Task dependencies. These must be acyclic. Queue priority can order only among legally orderable work; Planning/UI cannot override dependency legality.

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

means B cannot become dispatch-eligible before A satisfies the dependency completion policy.

Cross-Plan dependencies are explicit and navigable. Planning must surface consequences when a Plan depends on work owned by another Plan.

## Launch: Start / Schedule / Park

Every Plan ends at an explicit `Ready to launch` decision brief. It does not silently execute.

```text
Start now    -> revalidate preflight -> launch or preserve waiting state
Schedule     -> durable date/time/timezone -> preflight reruns at activation
Park         -> intentional ready state -> freshness/preflight on return
```

Material post-approval change creates a new PlanRevision.

## Planning Workspace Contract

Three-area desktop model:

```text
LEFT   Plan Index = what did I ask / what exists?
CENTER Current    = what are we doing now?
RIGHT  Context    = why / impact / evidence / next?
```

Plan Index uses progressive disclosure. Context follows active Decision and can be pinned; it is not a second navigation tree.

## Invariants From Day 1

- structured state survives chat/context loss;
- ProjectVision, Goal, Plan and Project defaults have distinct authority;
- Plan exceptions cannot silently rewrite enduring ProjectVision or Goal state;
- user-owned Decisions are never silently made by AWP;
- Simple mode never reduces planning completeness;
- technical delegated Decisions remain visible/changeable;
- readiness is gate/consequence based;
- hard Task dependency cycles are rejected;
- manual priority cannot violate dependencies;
- Plan launch is explicit and reversible until execution starts;
- planner leads when next work is known;
- user never needs to ask “what remains?” when state already knows.

## Increment Realization

| Increment | Planning realization |
|---|---|
| I1 | narrow Plan/Task creation with compact ProjectVision + Goal linkage; no rich interview. |
| I2 | full Goal-aware PlanningSession/Profile/Simple/Expert/defaults/readiness/delivery/launch UX. |
| I3 | generic Decision/Approval/autonomy deepens Planning. |
| I5/I6 | CI/deployment implementations consume already-planned outputs. |
| Later | research/analytics/adapters deepen without changing authority model. |

## Temporary Dogfood Behavior

I1 may create a minimal Plan directly from a work request against compact ProjectVision and Goal records. These are compatible subsets of final identities, not temporary schemas.

## Failure / Recovery

Planning autosaves. Connection/auth cancellation, browser refresh, provider outage or session change must not lose accepted Decisions/drafts/agenda. Stale external evidence, ProjectVision or Goal changes are marked and re-evaluated.

## API / CLI / MCP

Structured ProjectVision/Goal/Plan/Decision/artifact/readiness state is accessible through shared contracts. Chat transcripts are never required to reconstruct Plan or Project intent.

## Related

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