ThothII/docs/superpowers/specs/2026-07-03-workflow-ui-fixes-design.md

# Workflow UI fixes — design

Date: 2026-07-03
Status: approved (brainstorming), pending plan

Five defects surfaced while testing the app. All are UI/contract issues in the
frontend, plus one root-cause fix in the harness gate. No changes to the Pi RPC
wire protocol.

## Scope

| # | Problem | Fix location |
|---|---------|--------------|
| 1 | Phase circles don't reflect lifecycle (F1 never turns yellow at start; no explicit green/red on end) | frontend |
| 2 | No total elapsed-time indicator after the 8 circles | frontend |
| 3 | Reviewer artifact gate shows nothing (revised question, schema link, CTEs, final SQL) | frontend (contract fix) |
| 4 | Complex artifacts need a 90% modal, fully formatted, with a Mermaid diagram for schema linking | frontend |
| 5 | Both "Altro - specificare" and "other" appear in dialogs | harness |

---

## Problem 5 — Duplicate "Altro"/"other" (root cause)

**Cause.** `builders.js` always sets `reserved: ["back","exit","other"]`, which the
frontend renders as the `Other — specify` control. Separately, `reviewer_select`
and `reviewer_decide` strip model-supplied options via `isReserved(o.label)`
(`reserved-labels.mjs`), but `isReserved` does an **exact-string** match against
`ALTRO = "Altro — specifica…"`. The model emits variants (`"Altro - specificare"`,
plain hyphen; `"altro"`; English `"Other — specify"`) that slip through the exact
match, so both the model's free-text option **and** the reserved control appear.

**Fix.** Make `isReserved(label)` robust in `reserved-labels.mjs`:

- Normalize: lowercase, strip diacritics (NFD + remove combining marks), collapse
  punctuation/whitespace, trim.
- Treat as reserved if the normalized label **starts with** `altro` or `other`, or
  equals the normalized canonical back/exit labels (`QUIT_LABEL`, `BACK_LABEL`).

`stripReserved` and both reviewer tools inherit the fix (they call `isReserved`).
Result: only the reserved `Other — specify` control remains (English, per the UI
convention that chrome/labels stay English).

**Tests.** Unit test in the harness reserved-labels test: variants
`"Altro - specificare"`, `"altro"`, `"ALTRO — specifica…"`, `"Other — specify"` are
all reserved; a normal merit option (`"procedura"`) is not.

---

## Problem 3 — Artifact gate renders nothing (contract mismatch)

**Cause.** The harness sends `artifact: { kind, data, version }` (see
`tht-gate.js` `reviewer_confirm` → `buildArtifactGate`, golden
`artifact_gate_F5.json`). The frontend `ArtifactGateWidget` reads
`descriptor.artifact?.content`, which never exists → nothing renders. It is a
`data` vs `content` mismatch, not missing data.

**Fix.** Rendering reads `artifact.data` and switches on `artifact.kind`. This is
subsumed by the Problem 4 modal: the old `<pre>{artifact.content}</pre>` is
replaced by `ArtifactView` (below).

---

## Problem 4 — 90% modal + ArtifactView + erDiagram

### ArtifactGateModal

New `frontend/src/widgets/ArtifactGateModal.tsx`, built on the existing Radix
dialog (`components/ui/dialog.tsx`).

- Size: `90vw × 90vh`.
- Layout: **top** = scrollable artifact area (`flex-1`, `overflow-auto`) rendering
  `ArtifactView`; **bottom** = action bar: the gate `options` buttons
  (`Conferma e prosegui` / `Rifiuta`) plus `ReservedControls` (Other/Back/Exit).
- The `option.opens → freetext` linkage keeps working via the existing
  `LinkageHost`.
- Auto-opens when `pendingWidget.widget === "artifact-gate"`. The `select` /
  `multiselect` / `freetext` gates stay inline as today.
- Routing: `WidgetHost` (or the widget registry) renders artifact-gate through the
  modal instead of the inline `ArtifactGateWidget` card. The inline
  `ArtifactGateWidget` body is replaced by the modal; its option/linkage logic is
  reused.

### ArtifactView

New `frontend/src/viewers/ArtifactView.tsx`. Switches on `artifact.kind` and is
**defensive** about `data` (accepts a string or an object, picks common fields,
falls back to formatted JSON):

| `artifact.kind` | Renderer |
|-----------------|----------|
| `schema_linking` | `SchemaLinkingViewer` (data = linking object) |
| `sql`, `cte_result` | `SqlViewer` (string or `{sql}` / `{ctes[], final}`) |
| `cte_plan` | ordered list of CTE names (`data` = array or `{names[]}`) |
| `question`, `phase` | `MarkdownView` (string or `{markdown}`/`{question}`) |
| default / unknown | pretty-printed JSON in a formatted `<pre>` |

### Schema-linking diagram → Mermaid erDiagram

In `SchemaLinkingViewer.tsx`, replace `buildFlowchart` with `buildErDiagram`
producing a Mermaid `erDiagram`:

- Entities = promoted **tables**; each table's promoted **columns** (name format
  `table.column`) become entity attributes.
- Relationships = `joins` between promoted tables.
- **Relations are drawn only if `artifact.data.joins` is present.** If the model
  supplies no joins, tables render without edges. This intervention does **not**
  change the harness/model to force joins into `schema_linking`.
- Keep the existing table-view fallback and the oversized-graph cap.

This viewer is shared with `SessionDocumentsPanel`, which improves consistently.

---

## Problem 1 — Phase-circle lifecycle (frontend-optimistic)

`currentPhase` is set only on `ui_request.phase` (`sessionStore.ts`), so before
F1's first gate (the 3–4 min cold start) no circle is yellow; and "done/green" is
positional (`i < activeIdx`), so the last phase never greens and there is no
explicit end signal.

**Fix, in `WorkflowBar.tsx` + the new-question submit path:**

- **Yellow at start.** On **new-question** creation, set `currentPhase = "F1"`
  immediately (in the submit path — `SteerInput` / store action), so F1 is yellow
  during cold start. On **resume**, leave `currentPhase` null until the first gate
  (the phase is unknown until then).
- **Green on end.** Keep positional green while advancing. Additionally, when the
  active session is `finalized`, mark **all 8** circles `done` (green).
- **Red on error.** Unchanged: `phaseError` (set on `info` level `error`) drives
  the current phase's red state until the next gate.
- `WorkflowBar` receives `finalized` from `AppShell` (derived from the active
  session's status).

Positional inference already handles multi-gate phases, auto-advanced phases
(empty memory F2), and the reviewer `back` control (recomputed each render).

---

## Problem 2 — Total elapsed timer

New `frontend/src/shell/ElapsedTimer.tsx`, rendered after the 8 circles inside the
workflow strip.

- Anchor = active session's `created_at` (robust to reload/resume).
- Ticks every second while not `finalized`; freezes at `updated_at − created_at`
  once `finalized`.
- Fallback: if `created_at` is not yet available (brand-new session before the
  sessions-list poll returns it), anchor on a local timestamp captured when the
  session became active.
- Format: `Xm Ys`.
- `AppShell` passes `createdAt` / `finalized` to `WorkflowBar`, which lays out the
  circles (centered) and the timer (trailing).

---

## Files touched

**Frontend**
- `shell/WorkflowBar.tsx` — accept `finalized`/`createdAt`; optimistic F1; all-green
  on finalized; render `ElapsedTimer`.
- `shell/AppShell.tsx` — pass active session `created_at`/`finalized` to `WorkflowBar`.
- new-question submit path (`shell/SteerInput.tsx` and/or `store/sessionStore.ts`) —
  set `currentPhase = "F1"` on new question.
- new `shell/ElapsedTimer.tsx`.
- new `widgets/ArtifactGateModal.tsx`; `widgets/index.ts` / `shell/WidgetHost.tsx`
  route artifact-gate to the modal.
- new `viewers/ArtifactView.tsx`.
- `viewers/SchemaLinkingViewer.tsx` (+ `viewers/mermaid.ts` if needed) — erDiagram.

**Harness**
- `.pi/extensions/reserved-labels.mjs` — normalized `isReserved`.
- reserved-labels test — variant coverage.

## Testing

- Harness: `node --test` on the reserved-labels test (variant coverage);
  existing `builders`/gate tests stay green.
- Frontend: `npx vitest run` — update/keep `ArtifactGateWidget` / f1-loop /
  sessionStore tests; add tests for `ArtifactView` kind routing, `ElapsedTimer`
  formatting/freeze, `WorkflowBar` optimistic-F1 + finalized-all-green, and the
  erDiagram builder. `npx tsc -b` clean.

## Out of scope

- No Pi RPC wire-protocol change; no authoritative phase-lifecycle events from the
  harness (chosen: frontend-optimistic).
- No harness/model change to force `joins` into `schema_linking`.
- Reserved control label stays English (`Other — specify`) per UI convention.