# Plan Page UI

**Status:** Approved target-state behavior  
**First realization:** I1 minimal; rich Planning integrates I2.

## Page Job

Answer:

```text
What is this Plan trying to achieve?
Which revision is current?
How is work decomposed and progressing?
What is running on each task?
What is blocked/deferred?
What Decisions/defaults define it?
What happens after the current work?
```

Plan page is the durable execution/progress view. Interactive Planning has its own Planning workspace but links back to the same Plan identity.

## Header

Plan name/outcome, current PlanRevision, status/readiness/launch state, Project breadcrumb. Primary action depends on state: Resume Planning, Start, Resolve blocker, View active FactoryRun, etc.

## Structure / Progress

Render Plan's actual topology rather than imposing a generic layout:

```text
Wave 3 / 7   [FactoryRun 5j13mlx]
  Phase ...
  Task 11 / 12   running
    AgentRun: codex / spark / low / account zync-2
  Task 12        blocked by Task 11
```

For simple Plans, show a flat Task list. For DAGs, use graph only where it clarifies dependencies; keep an accessible list/table equivalent.

## Task Rows

Show task goal, status/reason, dependencies, current/previous FactoryRun/AgentRun, ChangeSet/Review/evidence result and latest activity. All linked primitives clickable.

## Decision / Delivery Summary

Compact sections summarize relevant accepted Decisions, Project-default overrides, Quality/CI/delivery/execution configuration and deferred gaps. Do not make users enter Planning workspace simply to inspect why current Plan behaves as it does.

## Launch / Schedule / Park

Before execution in I2+, Plan page reflects latest launch state and schedule. A scheduled/parked Plan clearly distinguishes ready intent from active execution and exposes reschedule/cancel/start where policy allows.

## States

- Empty draft: goal exists but no work breakdown; primary Resume Planning.
- Loading/error/stale: preserve revision identity and last known status; explicit refresh/retry.
- Ready: requirements/preflight summary and launch action.
- Scheduled/Parked: explicit state, timing/freshness.
- Executing: active graph/list and current agents.
- Waiting/blocked: reason + owner/next action.
- Completed/cancelled: outcome, merge/release links and history.

## Responsive / Accessibility

On small screens flatten structural hierarchy into expandable semantic list; graph becomes optional drill-in. Keyboard can traverse Tasks and open relationships. State differences have text/icons, not color alone.

## URL Truth

`/projects/:projectId/plans/:planId`; revision can be selected via stable path/query and historical view is clearly read-only. Task deep links can route to Plan anchored context or dedicated primitive detail where implemented.

## Increment Realization

I1: minimal Plan/Task creation, status and Run relationships. I2: rich Planning/readiness/defaults/launch. I3 Decisions, I4 richer Factory, I5 evidence/CI, I6 release/deployment relationships.

## High-Fidelity Requirements

I1 U1 covers minimal creation/selection; U2/U3 can show Plan context inside active/failure work. I2 high-fi replaces/extends richer Plan/Planning states without changing shell/identity.

## Target State

Plan is the durable owner-facing view of one accepted/evolving software-delivery intent and its work topology. It makes PlanRevision, Task dependencies, concurrency, execution relationships, blockers and resulting evidence legible without requiring the user to reconstruct state from chat or provider runs.

## Primary Users / Jobs

- plan owner: confirm outcome, readiness and what work remains;
- engineering/delivery lead: inspect topology, concurrency, blockers and next work;
- contributor/reviewer: navigate from Task to its FactoryRun, AgentRun, ChangeSet, Review or evidence.

## Entry / Exit Points

Entry: Project Plans list, Home/Work, search, Factory/Agent breadcrumbs, Planning handoff. Exit: Planning workspace, Task context, FactoryRun, Agent, ChangeSet/Review, CI/evidence, Decision detail and later Release/Deployment.

## User Journeys

### J1 — Inspect active execution

```text
Open Plan
 -> orient on outcome + current PlanRevision
 -> scan Wave/Phase/Task topology
 -> identify concurrent running/waiting Tasks
 -> open relevant FactoryRun/Agent
 -> return to Plan with context preserved
```

### J2 — Resolve a blocker

```text
blocked Task / deferred requirement
 -> read reason + dependency/owner + consequence
 -> open Decision/Approval/Connection/Review/CI source
 -> resolve or intentionally defer where allowed
 -> Plan recomputes next eligible work
```

### J3 — Launch or resume a ready Plan

```text
Ready / Scheduled / Parked
 -> inspect preflight + effective delivery/execution summary
 -> Start / Schedule / Park or Resume Planning
 -> protected confirmation/revalidation
 -> durable launch/schedule state
 -> execution appears on same Plan identity
```

### J4 — Inspect history safely

```text
select historical PlanRevision
 -> read-only state + decisions/work interpretation
 -> compare with current revision
 -> follow supersession/Decision links
 -> return to current Plan
```

## Data / Source of Truth

Plan/PlanRevision, Task topology and launch state come from Planning/Work domains. FactoryRun/AgentRun, ChangeSet/Review, VerificationEvidence and delivery relationships remain authoritative in their own domains and are projected here. No graph renderer owns dependency truth.

## Actions / Authorization

Resume Planning, Start/Schedule/Park, cancellation/replan and protected blocker actions use application commands with Project/Plan policy. Historical revisions are read-only. Lower-scope action cannot broaden Project/system capability ceilings.

## Async / Duplicate-Mutation Safety

Launch/schedule/reschedule/cancel actions use revision/idempotency protection, immediate acknowledgement and durable PlanLaunch/operation state. Start always revalidates preflight. If state changes underneath the user, stale action is rejected with an explanation instead of silently applying to a different revision.

## Invariants From Day 1

- PlanRevision identity is always visible when consequences depend on it;
- topology shown in graph/list is the same Task dependency model;
- concurrent work is visible, not flattened into fake sequential progress;
- waiting/blocked always states reason, owner and next action;
- historical revisions never accept current mutations;
- Planning and execution views share one Plan identity.

## Current Implementation State

Target page specification only. I1 activates the minimal final-form Plan/Task surface; rich Planning is not implemented yet.

## Deferred Realization

I2 adds readiness/defaults/launch depth; I3 generic Decision/Approval; I4 richer Factory links; I5 CI; I6 Release/Deployment. No later capability requires replacing Plan identity or topology.

## Temporary Dogfood Behavior

I1 may use a flat Task list when the first Plan is simple and may show only minimal run/review evidence. It must still preserve final Task/PlanRevision identities, dependencies and active concurrency.

## Related Contracts / Decisions

- [`../domains/planning.md`](../domains/planning.md)
- [`../domains/work.md`](../domains/work.md)
- [`../workflows/interactive-planning.md`](../workflows/interactive-planning.md)
- [`../workflows/plan-to-production.md`](../workflows/plan-to-production.md)
- [`planning.md`](planning.md), [`factory-run.md`](factory-run.md), [`review.md`](review.md)

## Visual Mockup Authority

U1 is the first canonical Plan visual gate. No exploratory Plan frame is implementation authority. I2 Planning/Plan high-fi may deepen the page but must preserve the approved shell, Plan identity and relationship model.

## Acceptance

User can identify exactly which task/work is active, what blocks progression and which Factory/Agent/Change/Review is responsible without reading logs.