# Morning cockpit — Workboard UX for the ritual

**Status:** design / prototype only (Grok lane, 2026-07-31).  
**Does not implement** dashboard mutations, approve/build buttons, or schema.  
**Mock:** [morning-cockpit-mock.html](./morning-cockpit-mock.html)  
**Audience:** owner + later r6 implementers of presentation and (separately) write paths.

---

## 1. Why this exists

Two truths from dogfood:

1. **ForgeLoop is a strong brake** — multi-provider plan review rejects under-specified work; authority holds (see cancelled `w-bc5e76eeebbc5b39`, three rounds, zero executions).
2. **ForgeLoop is a weak steering wheel** — after reject or “needs you,” the human still faces walls of must-fix text, dual boards (factory tasks vs Work lifecycle), and no 10-second answer to “what do I do now?”

The north star is the ritual, not an ops control plane:

> plan → council → you approve → implement → review → bank → **you** merge

Glass should make that ritual **scannable**. It should not invent authority.

---

## 2. UX critique of the current glass (r5)

### What already works

| Asset | Note |
|-------|------|
| Lifecycle view + `/api/v1` read models | Right data model for Work |
| Needs-you sort on work list | Correct priority signal |
| Expanded card survives 10s refresh | Rage-quit class fixed in r5 |
| Detail shows plan / verdicts | Approve-moment material exists |
| Metrics strip (needs you, blocked, providers) | Good at a glance if you already know the product |
| Short CLI verbs in NORTH_STAR | Product story is finally clear |

### Friction (ordered by pain)

| # | Friction | Effect |
|---|----------|--------|
| 1 | **Two products in one shell** — factory Board (tasks) vs Lifecycle (Work) | Owner unsure which board is “the” board John liked |
| 2 | **Eight equal phases** | Morning brain wants “needs me / banked / rest,” not eight columns |
| 3 | **Copy still says control plane + CLI owns every decision** while r6 aims at board build/approve | Trust and IA conflict |
| 4 | **Blockers are prose walls** | Council must-fix after 3 rounds is unreadable on phone; no checkbox structure |
| 5 | **NEXT command is easy to miss** | Ritual lives or dies on copy-paste of one command |
| 6 | **No “overnight / providers” as secondary** | Useful, but should not compete with Needs you for attention |
| 7 | **Task board investment** | Legacy surface; investing more UI there dilutes the ritual |
| 8 | **Public / token story** | Unlock panels are fine; must never look like the product is “locked SaaS” |

### Process → UI requirements (from plan critique Work)

From `w-bc5e76eeebbc5b39` (rejected last-mile plan):

| Process learning | UI requirement (presentation) |
|------------------|-------------------------------|
| Dual brief thrash | Card title = **one job**; show brief excerpt only |
| Must-fix lists | **Structured blockers**: severity, owner, one-line fix, expand for detail |
| Snapshot-bound approve (future write) | Drawer always shows **plan version + digest** prominently when open |
| Max rounds hit | Badge: “council exhausted — your revise” not just `needs-human` |
| Spend on planning | Cost line on card when available (council vs execution) |

---

## 3. Information architecture — Morning cockpit

### Primary question (10 seconds)

When the owner opens the glass, they must answer:

1. **What needs me?** (approve, revise, merge, unblock)  
2. **What is banked waiting for merge?**  
3. **Is overnight/providers healthy enough to ignore?**

### Default layout

```text
┌─────────────────────────────────────────────────────────────┐
│ ForgeLoop · Morning                    overnight · · ·  3/3 │
│ Needs you: 2   Banked: 1   In flight: 3   Cost 24h: $x      │
├──────────────────────┬──────────────────────────────────────┤
│ NEEDS YOU (hero)     │  RITUAL BOARD (compressed)           │
│                      │  Planning │ Your move │ Building │   │
│  [card]              │  Banked   │ Done                     │
│  [card]              │                                      │
│                      │  (no factory task columns here)      │
├──────────────────────┴──────────────────────────────────────┤
│ DETAIL (selected card): plan · verdicts · blockers · NEXT   │
│  forgeloop approve w-…     [copy]                           │
└─────────────────────────────────────────────────────────────┘
```

### Column model (max five “story” columns)

Map from existing `WorkPhaseV1` without inventing states:

| Cockpit column | Includes phases / states |
|----------------|---------------------------|
| **Planning** | planning (council running) |
| **Your move** | approval + needsOwner + needs-human / invalid plan after rounds |
| **Building** | implementation + verification |
| **Banked** | promotion (awaiting human merge) |
| **Done** | done + closed (collapsed by default) |

Delivery stays secondary (footer or expand) — rare for personal daily driver.

### Card anatomy

```text
┌────────────────────────────────────┐
│ needs you · plan v3 · invalid      │
│ Title one line                     │
│ w-bc5e… · forgeloop · 12m ago      │
│ ✗ grok  ✗ claude · 3 rounds max    │
│ NEXT: forgeloop revise …   [copy]  │
└────────────────────────────────────┘
```

### Detail drawer (read-only in this lane)

1. **Status strip** — phase, assurance, rounds used / max  
2. **Blockers** — structured list (not one blob)  
3. **Council** — per-reviewer verdict chips + first must-fix  
4. **Plan** — body, monospaced, version + digest  
5. **NEXT** — exact CLI, large copy button  
6. **Cost** — when known  

**No** Approve / Build / Merge buttons in this prototype. Future r6 may add token-gated actions **only** under Your move and only snapshot-bound; merge stays loud/CLI.

### What we demote

| Surface | Treatment |
|---------|-----------|
| Factory task Board | Advanced / hide from default nav for personal mode |
| Economy deep charts | Link from Cost 24h, not home |
| Config / commands audit | Power user drawer |
| Intake views | Gone with r5 — do not resurrect in UI |

---

## 4. Visual & interaction principles

1. **Needs you is loud; everything else is quiet.** Red/amber only for owner action.  
2. **One primary CTA per card** — always a CLI line + copy (until write path exists).  
3. **Phone skim** — hero column stacks full width < 720px; board becomes horizontal scroll or accordion.  
4. **Plan is for reading** — max readable measure (~72ch), not a log dump; collapse execution-spec fence behind “machine boundary.”  
5. **Digests are second-class visual** — mono, truncated, copy-full on click.  
6. **Refresh must not steal focus** — keep r5 expansion/cache rule.  
7. **Honesty over polish** — unmetered providers show tokens/runs, not fake $0.  
8. **Borrow from Pi Web carefully** — side-by-side plan + evidence is good; chat session as product is not.  
9. **Empty states teach the ritual** — “Queue empty — `forgeloop work \"…\"`” not six blank columns.  
10. **Accessibility** — keyboard expand, focus trap later for drawers, contrast via existing tokens.

### Anti-patterns

- Equal visual weight for Done and Your move  
- Showing task-factory columns as home  
- Buttons that look primary but only open docs  
- Must-fix as a single 4k-character string  
- “Developer control plane” / enterprise chrome for a personal tool  

---

## 5. Mapping to implementation (later — not this lane)

| When r6 implements glass | Use this spec |
|--------------------------|---------------|
| Presentation pass | Column remap + hero Needs you + card NEXT |
| Board approve/build | Only in Your move; freeze WorkViewV1 snapshot; required reason |
| Notify | Prefer “Needs you” count + deep link to work id |
| Dual board | Default nav = cockpit; task board under Advanced |

Do **not** add tables or event kinds from this doc alone.

---

## 6. Process improvements (operator, from dogfood)

1. One job per Work.  
2. Pre-flight payload contracts before write-path Work.  
3. After 2 council rejects, human-edit the plan file.  
4. Strategy Work stops at plan-ready.  
5. After each blocked Work, one line: “would a cockpit have saved me?”

---

## 7. Success criteria for this design package

- [x] Critique of current glass documented  
- [x] IA + principles documented  
- [x] Static mock opens offline and answers the 10-second questions  
- [ ] Owner feedback: keep / change columns / density  
- [ ] Later: presentation PR against live Lifecycle (separate, after r6 client is quiet)

---

## 8. Files

| File | Role |
|------|------|
| `docs/ui/morning-cockpit.md` | This spec |
| `docs/ui/morning-cockpit-mock.html` | Interactive static prototype |

Open the mock:

```bash
# any browser
xdg-open docs/ui/morning-cockpit-mock.html
# or
python3 -m http.server 8765 --directory docs/ui
# → http://127.0.0.1:8765/morning-cockpit-mock.html
```