# AWP UI / Page Specification Completeness Audit

**Date:** 2026-08-20  
**Status:** **SEMANTIC PAGE-CONTRACT AUDIT CLOSED — all 17 page/surface specs meet the page contract; rendered diagrams + high-fi remain Design Complete gates**  
**Authority checked against:** [`../specs/SPEC-PRESENTATION-STANDARD.md`](../specs/SPEC-PRESENTATION-STANDARD.md), [`../VISION.md`](../VISION.md), [`../VISION-EXTENSIONS-2026-08-20.md`](../VISION-EXTENSIONS-2026-08-20.md), [`AWP-UI-SCREEN-ATLAS.md`](AWP-UI-SCREEN-ATLAS.md).

## Executive Result

The original UI audit found the then-existing 15 page specs directionally strong but incomplete under AWP's own presentation standard, most universally because explicit **User Journeys** were missing. Those 15 were normalized.

The later Advisor/Search owner-Vision extension added two new dedicated surface specs:

```text
Advisor Chat
Search / Command Palette
```

Both were written from creation against the normalized page contract and are now included in this closure record.

There are therefore **17 dedicated page/surface specs plus the whole-product UI/IA authority**.

## Binding Page Contract

Every target page/surface explicitly covers material behavior from this checklist:

```text
Target State
page purpose/job
Primary users/jobs
Entry / exit
complete target information architecture
User Journeys
Data / source of truth
Actions / authorization
Async / duplicate-mutation safety
Invariants From Day 1
Empty / Loading / Error / Populated / Stale where material
waiting/blocked/failure behavior
responsive behavior
keyboard/focus/accessibility
URL-restorable state where meaningful
Increment Realization
Current Implementation State
Deferred Realization
Temporary Dogfood Behavior
Related domain/workflow contracts
Decisions / provider-boundary implications
Visual mockup authority
Acceptance
```

This closes semantic page-spec completeness. It does **not** declare visual Design Complete.

## Scope / Closure Matrix

| Page / surface | Journeys | Data truth | Auth/mutation safety | Current/deferred/temp | Related contracts | Visual authority | Result |
|---|---:|---:|---:|---:|---:|---:|---|
| Home / Work | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Project | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Plan | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Planning | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Advisor Chat | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Search / Command Palette | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| FactoryRun | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Agents | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Agent detail | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Review / ChangeSet | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| CI | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Decision Log | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Approval / Attention | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Release / Deployment | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Cluster | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Incident | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |
| Settings | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | **CLOSED** |

The whole-product [`../specs/ui/INDEX.html`](../specs/ui/INDEX.html) remains the shell/IA authority and now includes cross-cutting Search and Advisor placement.

## Page-Specific Journey Coverage

Examples already captured:

```text
Home
  resume important work / resolve attention / diagnose degradation / ask AWP across Projects

Project
  orient & resume / inspect Vision / start Plan / resolve blocker / ask Project Manager

Plan
  inspect concurrency / resolve blocker / launch-resume / inspect history

Planning
  planner-led Plan / challenge recommendation / defer safely /
  external connection return / resume long session

Advisor Chat
  ask about current page / cross-Plan optimization / system portfolio advice /
  switch expert persona / resume old thread with refreshed sources

Search / Command Palette
  find Plan / find technical run / deep filtered search /
  keyboard command / distinguish Search from Advisor

FactoryRun
  observe work / understand wait / recover with WIP safety / follow ChangeSet

Review
  exact candidate / correction loop / trusted merge / stale-base conflict

CI
  explain evidence / resolve failure / invalidate stale evidence / improve CI safely

Cluster
  inspect health / explain queue-placement / enroll machine / safe maintenance

Incident
  current safe state / deterministic recovery / agentic escalation / qualify recipe
```

## Advisor/Search UX-specific Completeness

### Advisor Chat

Explicitly covers:

```text
one reusable AdvisorShell
Project Manager vs AWP Advisor scope
visible/removable page context
source/freshness links
recommendation vs canonical mutation
saved/versioned persona/thread semantics
provider/partial-source/permission/stale/disconnected states
floating functional launcher + small-screen full-height behavior
```

### Search / Command Palette

Explicitly covers:

```text
visible shell Search + Cmd/Ctrl+K
cmdk interaction behavior
server-authorized/server-ranked entity results
Search vs Advisor distinction
full /search URL truth
zero results / partial failure / offline
keyboard/focus behavior
large-result pagination/cursor behavior
```

## Whole-Product UX Invariants Reconfirmed

```text
one primary action per decision context
waiting always explains itself
failure tells recovery story before raw logs
Last / Current / Next / Attention for operational work
URL truth for meaningful persistent views
complete Empty / Loading / Error / Populated / Stale where material
keyboard/focus/accessibility are specification requirements
live high-risk mutations require authoritative connection
provider JSON/logs/Kubernetes detail remain evidence layers
six-group HOME / WORK / EXECUTION / DELIVERY / OPERATIONS / SETTINGS target IA
Advisor scope/context is explicit
Search does not silently become AI mode
```

## Remaining Visual / Diagram Gap

Semantic completeness is not visual Design Complete.

The Vision/presentation standard expects diagrams where they materially improve human review. Current Markdown contains explicit journey flows and layout contracts, but the human site still needs a selective rendered diagram/presentation pass for complex flows.

Highest-value targets:

```text
Planning
Advisor scope/context -> grounded answer -> proposal -> canonical action
Factory execution / WIP recovery
Review / MergeGate
CI evidence/invalidation
Release/Deployment rollback
Cluster enrollment/placement
Incident resolution
```

Do not generate decorative diagrams just to satisfy a count.

## High-Fidelity Sequence

Immediate I1 visual gate:

```text
U1 Project + ProjectVision + minimal Plan/Task
U2 FactoryRun active
U3 waiting/failure/retry + WIP safety
U4 ChangeSet / Review
U5 Ready to merge
U6 Merged / completed
```

These are **mockup/product interaction states, not architecture**.

Advisor/Search are target-specified now but receive separate I3/I4 high-fi/usability gates before their implementation. U1–U6 deliberately omit inactive Advisor/Search controls.

## Source / Reuse Gate Remains Separate

UI semantic closure does not waive no-rebuild preflight.

Examples:

```text
Astryx first
Platform UI primitives checked before generic local components
deck-ui behavior harvested only on actual Astryx gap
cmdk for command-palette interaction
@platform-modules/search before custom generic search registry
Platform AI/realtime seams before generic advisor chat/provider mechanics
```

## Closure

```text
SEMANTIC PRODUCT/SPEC COVERAGE       GREEN
17 UI PAGE/SURFACE CONTRACTS         GREEN
ADVISOR/SEARCH TARGET UX CONTRACT    GREEN
PHYSICAL OVERDECK/PROVIDER PREFLIGHT PENDING before consuming code
PAGE DIAGRAM/PRESENTATION PASS       PENDING visual Design Complete
I0/I1 U1–U6 HIGH-FI                  PENDING explicit owner approval
I3/I4 ADVISOR/SEARCH HIGH-FI         DEFERRED to consuming increments
IMPLEMENTATION                       NOT STARTED
```