# Dialogs (v2)

All modal/dialog overlays used throughout the application. v2 adds consistent
loading and error states to all mutation-backed dialogs.

**Surface level**: All dialogs render at Level 2 (`--popover`, 16% lightness in dark mode)
with the `shadow-lg` token (light mode only). See theme.md surface hierarchy.

**Max height**: All dialogs cap at `max-h-[85vh]` with internal scroll on the form/body
region. The header and footer remain fixed. This prevents dialogs from overflowing on
small screens or when content is unexpectedly long (e.g., a ProjectPicker with 20 repos).

### Source: `packages/web/src/components/CreateInitiativeDialog.tsx`, `packages/web/src/components/RegisterProjectDialog.tsx`, `packages/web/src/components/RefineSpawnDialog.tsx`, `packages/web/src/components/TaskDetailModal.tsx`, `packages/web/src/components/editor/DeleteSubpageDialog.tsx`

---

## v1 -> v2 Changes

| Aspect | v1 | v2 |
|--------|----|----|
| Create Initiative: Branch field | Present (optional text input) | REMOVED (auto-generated on first execution dispatch) |
| All dialogs: submit loading | Some had it, inconsistent | All show `[spinner] <verb>ing...` on submit button |
| All dialogs: submit error | Some had it, inconsistent | All show red error text below form, above buttons |
| All dialogs: sizing | One-size `max-w-lg` | Size class per dialog type (sm/md/lg) |
| All dialogs: animation | Default shadcn (fade+zoom) | Documented: scale+fade enter, fade+scale exit |
| All dialogs: focus management | Unspecified | Documented per dialog: initial focus, tab order, Esc |
| All dialogs: backdrop behavior | Unspecified | Close-on-backdrop per type (safe for confirmations, guarded for forms) |
| All dialogs: form validation | Submit-only | Inline validation on blur + submit |

---

## Create Initiative Dialog

**Trigger**: "New Initiative" button on `/initiatives`
**Size**: `max-w-lg` (512px) — needs room for ProjectPicker list. This is deliberately wider
than Register Project (`max-w-md`) because the ProjectPicker checkbox rows need horizontal
space for project name + truncated URL side by side. Do NOT widen further — if the project
list exceeds 6 items, the ProjectPicker scrolls internally (`max-h-[200px] overflow-y-auto`).
**Backdrop**: Click outside closes ONLY if form is pristine. If any field is dirty, show `window.confirm("Discard unsaved changes?")`.

### Focus management

- **Open**: `autoFocus` on Name input
- **Tab order**: Name -> Execution Mode -> Project checkboxes -> Register link -> (Advanced toggle if present) -> Cancel -> Create
- **Escape**: Same behavior as backdrop click (close if pristine, confirm if dirty)

### Default state

```
+----------------------------------------------------------+
|  Create Initiative                                 [x]   |
|                                                          |
|  Name *                                                  |
|  [Auth System Overhaul___________________________]       |
|                                                          |
|  Execution Mode                                          |
|  [ Review           v ]                                  |
|                                                          |
|  Projects                                                |
|  +----------------------------------------------------+  |
|  | [x] backend     github.com/org/backend-api         |  |
|  | [ ] frontend    github.com/org/frontend-app        |  |
|  | [ ] shared      github.com/org/shared-lib          |  |
|  | + Register new project                             |  |
|  +----------------------------------------------------+  |
|                                                          |
|                            [ Cancel ]  [ Create ]        |
+----------------------------------------------------------+
```

Note: Branch field has been removed from the default view. Branches are
auto-generated (`cw/<slugified-name>`) on first execution task dispatch.
See auto-branch system in architecture docs.

### Advanced section (collapsed by default)

Power users can override the auto-generated branch name via a collapsible
"Advanced" section. The toggle sits below the Projects picker.

```
|  +----------------------------------------------------+  |
|  | [x] backend     github.com/org/backend-api         |  |
|  | [ ] frontend    github.com/org/frontend-app        |  |
|  | + Register new project                             |  |
|  +----------------------------------------------------+  |
|                                                          |
|  [v] Advanced                                            |
|  +----------------------------------------------------+  |
|  | Branch Name (auto-generated if blank)               |  |
|  | [cw/auth-system-overhaul_________________________]  |  |
|  +----------------------------------------------------+  |
|                                                          |
|                            [ Cancel ]  [ Create ]        |
```

- Toggle: `text-sm text-muted-foreground` with chevron icon (ChevronRight rotates to ChevronDown).
  Use shadcn `<Collapsible>` + `<CollapsibleTrigger>` + `<CollapsibleContent>` — NOT a custom
  disclosure widget. The Collapsible primitive handles aria-expanded and content animation.
- Container: `border rounded-md p-3 bg-muted/30` — visually recessed
- Branch input: pre-filled with `cw/<slugified-name>` as placeholder, editable. The placeholder
  updates live as the user types in the Name field (slugify on change).
- Collapsed by default — 99% of users should not touch this
- When collapsed, the section occupies a single line (~28px). The dialog height does NOT
  jump when toggled — use `<CollapsibleContent>` with `animate-collapsible-down` /
  `animate-collapsible-up` (already defined in shadcn's Collapsible animation presets).

### Submitting state

```
+----------------------------------------------------------+
|  Create Initiative                                 [x]   |
|                                                          |
|  Name *                                                  |
|  [Auth System Overhaul___________________________]       |
|                                                          |
|  Execution Mode                                          |
|  [ Review           v ]                                  |
|                                                          |
|  Projects                                                |
|  +----------------------------------------------------+  |
|  | [x] backend     github.com/org/backend-api         |  |
|  | [ ] frontend    github.com/org/frontend-app        |  |
|  +----------------------------------------------------+  |
|                                                          |
|                    [ Cancel ]  [ [spinner] Creating... ]  |
+----------------------------------------------------------+
```

- `[ Create ]` button replaced with `[ [spinner] Creating... ]` — uses `<Loader2 className="animate-spin h-4 w-4 mr-2" />`
- Button is `disabled` during mutation — both `disabled` prop AND `pointer-events-none` (belt and suspenders)
- `[ Cancel ]` remains enabled but closing the dialog is prevented
- `[x]` close button: hidden during mutation (not just disabled — reduces visual noise)
- Backdrop click and Escape are both suppressed during mutation via `onInteractOutside` / `onEscapeKeyDown`

### Error state

```
+----------------------------------------------------------+
|  Create Initiative                                 [x]   |
|                                                          |
|  Name *                                                  |
|  [Auth System Overhaul___________________________]       |
|                                                          |
|  Execution Mode                                          |
|  [ Review           v ]                                  |
|                                                          |
|  Projects                                                |
|  +----------------------------------------------------+  |
|  | [x] backend     github.com/org/backend-api         |  |
|  +----------------------------------------------------+  |
|                                                          |
|               Failed to create initiative.               |
|                            [ Cancel ]  [ Create ]        |
+----------------------------------------------------------+
```

- Error text: `text-sm text-destructive`, positioned between form fields and footer buttons
- Cleared on next submit attempt
- For field-specific errors (e.g., "Name already exists"), show inline below the offending field
  instead of the generic error position. Generic server errors stay above buttons.

### Form validation

| Field | Rule | Fires on | Inline message |
|-------|------|----------|----------------|
| Name | Required, non-empty after trim | blur + submit | "Name is required" |
| Name | Unique across initiatives | submit (server) | "An initiative with this name already exists" |
| Execution Mode | Always valid (has default) | -- | -- |
| Projects | Optional, no validation | -- | -- |
| Branch (Advanced) | Optional, valid slug chars | blur | "Branch name can only contain a-z, 0-9, /, -" |

Inline error styling: `text-xs text-destructive mt-1` below the input. Input border changes to `border-destructive`.

**Fields**:
- Name (required text input, `autoFocus`)
- Execution Mode (select: Review per Phase / YOLO)
- Projects (ProjectPicker: checkbox list + register link)
- Branch (optional, inside Advanced collapsible)

**Source**: `packages/web/src/components/CreateInitiativeDialog.tsx`

---

## Register Project Dialog

**Trigger**: "Register Project" button on `/settings/projects` or "+ Register new project" in ProjectPicker
**Size**: `max-w-md` (448px) — simpler form, fewer fields than Create Initiative
**Backdrop**: Click outside closes only if form is pristine. Dirty form triggers `window.confirm("Discard unsaved changes?")`.

### Focus management

- **Open**: `autoFocus` on Project Name input
- **Tab order**: Project Name -> Repository URL -> Default Branch -> Cancel -> Register
- **Escape**: Same as backdrop click

### Default state

```
+----------------------------------------------------------+
|  Register Project                                  [x]   |
|                                                          |
|  Project Name *                                          |
|  [backend-api_______________________________________]    |
|                                                          |
|  Repository URL *                                        |
|  [https://github.com/org/backend-api________________]    |
|                                                          |
|  Default Branch                                          |
|  [main______________________________________________]    |
|                                                          |
|                        [ Cancel ]  [ Register ]          |
+----------------------------------------------------------+
```

### Submitting state

```
|                [ Cancel ]  [ [spinner] Registering... ]  |
```

### Error state

```
|            Failed to register project.                   |
|                        [ Cancel ]  [ Register ]          |
```

### Branch auto-detection

After the user enters a valid-looking Repository URL and the input loses focus,
fire a debounced (500ms) request to detect the default branch. This avoids
users guessing wrong (some repos use `master`, `develop`, `trunk`).

```
|  Repository URL *                                        |
|  [https://github.com/org/backend-api________________]    |
|                                                          |
|  Default Branch                                          |
|  [[spinner] Detecting...______________________________]  |
```

States:
- **Idle**: Input shows "main" as default value, editable
- **Detecting**: Spinner inside input, field temporarily `readonly`, `text-muted-foreground`.
  Submit button is NOT disabled during detection — user can submit with the current branch value.
- **Detected**: Value replaced with detected branch (e.g., "master"), field editable again.
  If user has already manually edited the branch field before detection completes, do NOT
  overwrite — user intent wins. Track a `branchManuallyEdited` boolean.
- **Detection failed**: Keep current value, show subtle hint: `text-xs text-muted-foreground mt-1` —
  "Could not auto-detect branch. Using current value."
- **Cancelled**: If the user modifies the URL while a detection request is in flight,
  cancel the previous request (`AbortController`) and start a new debounce cycle.

Trigger conditions for detection:
- URL field loses focus AND URL has changed since last detection
- URL matches a basic pattern: starts with `http://`, `https://`, or `git@`
- Do NOT fire on every keystroke — only on blur with 500ms debounce

Implementation note: Detection requires a server-side tRPC procedure (e.g., `detectDefaultBranch`)
that runs `git ls-remote --symref <url> HEAD`. This is a nice-to-have; ship without it first,
add later. The wireframe accounts for both states. The procedure MUST have a 5-second timeout —
private repos with bad auth will hang `git ls-remote` indefinitely.

### Form validation

| Field | Rule | Fires on | Inline message |
|-------|------|----------|----------------|
| Project Name | Required, non-empty after trim | blur + submit | "Project name is required" |
| Project Name | Unique | submit (server) | "A project with this name already exists" |
| Repository URL | Required, non-empty | blur + submit | "Repository URL is required" |
| Repository URL | Valid URL format | blur | "Enter a valid git repository URL" |
| Repository URL | Unique | submit (server) | "This repository is already registered" |
| Default Branch | Non-empty (has default "main") | blur | "Branch name is required" |

**Fields**:
- Project Name (required, unique)
- Repository URL (required, unique, git repo URL)
- Default Branch (text input, defaults to "main", auto-detected when possible)

**Source**: `packages/web/src/components/RegisterProjectDialog.tsx`

---

## Refine Spawn Dialog

**Trigger**: "Refine with Agent" button in Content tab, or "Retry" button after agent crash
**Size**: `max-w-md` (448px) — single textarea, compact dialog
**Backdrop**: Click outside always closes (no data loss risk — instructions are optional, low-cost to retype)

### Focus management

- **Open**: `autoFocus` on Instructions textarea
- **Tab order**: Instructions textarea -> Cancel -> Start
- **Escape**: Closes dialog immediately

### Default state

```
+----------------------------------------------------------+
|  Refine Content                                    [x]   |
|                                                          |
|  Instructions (optional)                                 |
|  +----------------------------------------------------+  |
|  | Focus on the authentication flow section.           |  |
|  | Add more detail about the OAuth providers we        |  |
|  | need to support.                                    |  |
|  |                                                     |  |
|  +----------------------------------------------------+  |
|                                                          |
|                            [ Cancel ]  [ Start ]         |
+----------------------------------------------------------+
```

### Submitting state

```
|                    [ Cancel ]  [ [spinner] Starting... ]  |
```

### Error state

```
|              Failed to start agent.                      |
|                            [ Cancel ]  [ Start ]         |
```

**IMPLEMENTATION BUG**: The current `RefineSpawnDialog.tsx` renders `{error && ...}` AFTER
`<DialogFooter>`, placing the error text below the buttons where it is easy to miss. Fix:
move the error rendering ABOVE `<DialogFooter>` to match the pattern used by all other dialogs.
See lines 116-120 of the current implementation.

**Fields**:
- Instructions (optional textarea, free-form guidance for the agent, 3 rows default,
  auto-expands up to 8 rows via `min-h-[80px] max-h-[200px] resize-y`)

**Source**: `packages/web/src/components/RefineSpawnDialog.tsx`

---

## Task Detail Modal

**Trigger**: Click any task row in Plan tab or Execution tab
**Size**: `max-w-xl` (576px) — wider to accommodate metadata grid + dependency lists without cramping
**Backdrop**: Click outside closes IF no inline edit is active. If the description textarea is
open with unsaved changes, show `window.confirm("Discard description changes?")`. If the
textarea is open but content hasn't changed, close immediately.

### Focus management

- **Open**: Focus the dialog container itself (metadata is read-only, description edit is opt-in)
- **Tab order**: Description area (if pending task) -> Queue Task -> Stop Task -> Close (X) button
- **Escape**: Closes dialog if no inline edit is active. If description textarea is open,
  first Escape cancels the edit (reverts text), second Escape closes the dialog.

### Default state

```
+----------------------------------------------------------+
|  Implement PKCE Flow                               [x]   |
|                                                          |
|  +------------------------+-------------------------+    |
|  | Status    [IN_PROGRESS]| Priority   normal       |    |
|  | Phase     2. OAuth Flow| Type       execute      |    |
|  | Agent     blue-fox-7                             |    |
|  +------------------------+-------------------------+    |
|                                                          |
|  Description                                             |
|  Implement the OAuth 2.0 PKCE extension for public       |
|  clients. Generate code verifier/challenge pair,          |
|  include in authorization request, and validate           |
|  during token exchange.                                   |
|                                                          |
|  Dependencies                                            |
|  * Set up OAuth routes          [DONE]                   |
|                                                          |
|  Blocks                                                  |
|  * GitHub provider adapter      [BLOCKED]                |
|  * Microsoft provider adapter   [PENDING]                |
|                                                          |
|                     [ Queue Task ]  [ Stop Task ]        |
+----------------------------------------------------------+
```

### Queue in progress

```
|              [ [spinner] Queuing... ]  [ Stop Task ]     |
```

### Stop in progress

```
|                     [ Queue Task ]  [ [spinner] Stopping... ]  |
```

### Error state

```
|           Failed to queue task. Try again.               |
|                     [ Queue Task ]  [ Stop Task ]        |
```

**Fields** (read-only with inline edit affordances):
- 2-column metadata grid: Status (with badge), Priority, Phase, Type, Agent
- Description text — **click to edit** (pencil icon on hover, expands to textarea, saves on blur/Enter)
- Dependencies list (with StatusDot per dependency)
- Blocks list (dependents with StatusDot)

### Inline description editing

The Description section shows a subtle edit affordance on hover:

```
|  Description                                    [pencil] |
|  Implement the OAuth 2.0 PKCE extension for public       |
|  clients. Generate code verifier/challenge pair...        |
```

On click, the text block becomes an auto-sizing `<Textarea>`:

```
|  Description                                     [save]  |
|  +----------------------------------------------------+  |
|  | Implement the OAuth 2.0 PKCE extension for public  |  |
|  | clients. Generate code verifier/challenge pair,     |  |
|  | include in authorization request, and validate      |  |
|  | during token exchange.                              |  |
|  +----------------------------------------------------+  |
```

- Save triggers on blur or Cmd+Enter (Mac) / Ctrl+Enter (Windows)
- Cancel on Escape (reverts to original text, closes textarea back to static view)
- Mutation: `updateTask({ id, description })` — optimistic update on the local task cache
- **Saving state**: The `[save]` button shows `[spinner]` during mutation. Textarea remains
  editable but a second save is debounced until the first completes.
- **Save error**: Inline `text-xs text-destructive` below the textarea: "Failed to save. Try again."
  The textarea stays open so the user can retry without losing their edit.
- Only enabled when task status is `pending` — in-progress/completed tasks lock description.
  The pencil icon is hidden entirely (not grayed out) for non-pending tasks to avoid
  implying an action that is not available.
- **Empty state**: If description is null/empty and task is pending, show
  "Click to add description" as placeholder text in `text-muted-foreground italic`.

### Agent field

Agent row shows the assigned agent name. For pending tasks with no agent assigned,
this is not editable — agent assignment happens through the dispatch system.
Showing "Unassigned" in `text-muted-foreground` with no edit control is correct.
For in-progress tasks, the agent name should be a clickable link that navigates to
the agent's output view (same as clicking the agent name in the agents panel).
Use `text-primary hover:underline cursor-pointer` styling.

**Actions**:
- `[ Queue Task ]` -- `variant="outline" size="sm"`, disabled if already running/queued or dependencies incomplete
- `[ Stop Task ]` -- `variant="destructive" size="sm"`, disabled if not running

**Source**: `packages/web/src/components/TaskDetailModal.tsx`

---

## Delete Subpage Dialog

**Trigger**: Auto-triggered when a page link is deleted in the Tiptap editor
**Size**: `max-w-sm` (384px) — confirmation only, minimal content, no form fields
**Backdrop**: Click outside closes and keeps the subpage (same as clicking "Keep Subpage")

### Focus management

- **Open**: Focus the "Keep Subpage" button (safe default — prevents accidental deletion via Enter)
- **Tab order**: Keep Subpage -> Delete
- **Escape**: Closes dialog, keeps subpage

### Default state

```
+----------------------------------------------------------+
|  Delete Subpage?                                   [x]   |
|                                                          |
|  You removed a link to "Token Rotation". Do you          |
|  want to delete the subpage as well?                     |
|                                                          |
|                   [ Keep Subpage ]  [ Delete ]            |
+----------------------------------------------------------+
```

### Delete in progress

```
|               [ Keep Subpage ]  [ [spinner] Deleting... ]  |
```

### Error state

```
|           Failed to delete subpage.                      |
|                   [ Keep Subpage ]  [ Delete ]            |
```

**Fields**: None (confirmation dialog only)

**Cascade warning**: If the subpage has its own child subpages, the confirmation message
should include the count: "This will also delete 3 child pages." The message adapts:

```
|  You removed a link to "Token Rotation". Do you          |
|  want to delete the subpage and its 3 child pages?       |
```

This prevents users from accidentally nuking an entire page subtree. The child page count
comes from the `pages` table (count where `parentPageId = targetPageId`).

**Actions**:
- `[ Keep Subpage ]` -- `variant="outline"`, closes dialog without deleting. This is the
  focused button on open (safe default).
- `[ Delete ]` -- `variant="destructive"`, deletes the subpage and its content (cascade via FK)

**Source**: `packages/web/src/components/editor/DeleteSubpageDialog.tsx`

---

## Confirmation Dialogs (window.confirm)

Used for destructive actions throughout the app. All support **Shift+click to bypass**.

| Action | Trigger Location | Message |
|--------|-----------------|---------|
| Delete initiative | Initiative card `[...]` menu | "Delete this initiative?" |
| Archive initiative | Initiative card `[...]` menu | "Archive this initiative?" |
| Delete phase | Phase detail `[...]` menu | "Delete this phase?" |
| Delete task | Task row `[x]` button | "Delete this task?" |
| Delete project | Project card `[trash]` button | "Delete this project?" |
| Delete agent | Agent actions `[...]` menu | "Delete this agent?" |
| Stop agent (from inbox) | Inbox detail `[ Stop Agent ]` button | "Stop this agent? It will not be able to resume." |

Note: All `window.confirm()` dialogs are synchronous browser dialogs. They do not
receive the v2 loading/error treatment since the mutation fires only after confirmation.

### Shift+click discoverability

The Shift+click bypass is power-user-friendly but completely undiscoverable. Three mitigations:

1. **Tooltip on destructive buttons**: On hover (after 800ms delay), show a tooltip:
   `"Shift+click to skip confirmation"`. Use shadcn `<Tooltip>` with `text-xs`. The 800ms
   delay is critical — a shorter delay would fire on every pass-through hover and become
   noise. Only users who pause on the button see it, which is exactly the audience that
   benefits from the hint.

2. **First-time hint in confirmation dialog**: The FIRST time a user sees a `window.confirm()`
   dialog in a session, append to the message: `\n\n(Tip: Hold Shift and click to skip this dialog)`
   After the first occurrence, suppress the hint for the rest of the session via a
   `sessionStorage` flag. This teaches the shortcut at the exact moment it is relevant.

3. **NOT a "Don't ask again" checkbox**. Persistent suppression of confirmations is dangerous
   in a multi-agent system where a misclick can delete an initiative with 50 tasks and 10
   running agents. Shift+click is intentional per-action, which is the right granularity.
   A checkbox would be a footgun. The session-scoped hint in (2) is the compromise —
   teach the shortcut without offering permanent suppression.

---

## Shared Patterns Across All Dialogs

### Dialog sizing classes

Dialogs are NOT one-size-fits-all. Use the narrowest class that fits the content:

| Size | Tailwind | Pixels | Used by |
|------|----------|--------|---------|
| `sm` | `max-w-sm` | 384px | Delete Subpage, all confirmation-style dialogs |
| `md` | `max-w-md` | 448px | Register Project, Refine Spawn |
| `lg` | `max-w-lg` | 512px | Create Initiative (default shadcn, used when ProjectPicker needs room) |
| `xl` | `max-w-xl` | 576px | Task Detail Modal (metadata grid + lists need breathing room) |

Override the default `max-w-lg` on `<DialogContent>` by passing `className="max-w-sm"` etc.

### Dialog animation

All dialogs use the shadcn/Radix animation classes already present in `dialog.tsx`:

- **Enter**: `fade-in-0` + `zoom-in-95` + `slide-in-from-top-[48%]` — 200ms duration
- **Exit**: `fade-out-0` + `zoom-out-95` + `slide-out-to-top-[48%]` — 200ms duration

This is already implemented in the codebase (`data-[state=open/closed]` animations).
The spec documents it here for design intent clarity: the slight zoom (95% -> 100%)
combined with the vertical slide gives a "materializing" feel appropriate for mission
control. No changes needed to `dialog.tsx`.

**Backdrop**: `fade-in-0` / `fade-out-0` on the overlay. Already implemented. The
`bg-black/80` opacity is heavy — reduce to `bg-black/60` for dark mode where the
contrast is already high. Implementation: replace `bg-black/80` in `DialogOverlay`
with `bg-black/60 dark:bg-black/60` (or just `bg-black/60` since the app is
dark-mode-first). The lighter overlay keeps the "mission control behind glass" feel
without the claustrophobic blackout.

**Reduced motion**: Wrap all animation classes in `motion-safe:` prefix. Users with
`prefers-reduced-motion: reduce` get instant transitions. Already supported by Tailwind —
just prefix the animation utilities. The shadcn default `dialog.tsx` does NOT do this;
it needs to be patched.

### Submit button loading state

```
  v1: [ Create ]
  v2: [ [spinner] Creating... ]
```

- `[spinner]` is `Loader2` from Lucide with `animate-spin h-4 w-4 mr-2`
- Button text changes to present participle: "Create" -> "Creating...", "Register" -> "Registering...", "Start" -> "Starting...", "Delete" -> "Deleting..."
- Button is `disabled` during mutation

### Error text placement

Two tiers of error display:

**1. Field-level inline errors** (validation failures for specific fields):

```
+----------------------------------------------------------+
|  Name *                                                  |
|  [___________________________________________________]   |
|  Name is required                      <- text-xs, red   |
|                                                          |
|  ...remaining fields...                                  |
+----------------------------------------------------------+
```

- Styling: `text-xs text-destructive mt-1` directly below the offending input
- Input border: `border-destructive` (red ring) — replaces the default `ring-ring` focus style
- Fires on blur for format validation, on submit for all rules
- Does NOT fire on blur if the field has never been touched (prevents errors flashing when
  tabbing through an empty form). Track `isTouched` per field — only validate on blur after
  the first interaction (focus + blur cycle).
- Clears when user starts typing in the field (optimistic clear — re-validates on next blur)
- **Aria**: Error messages use `aria-describedby` linked to the input via `id`. Screen readers
  announce the error when the input receives focus.

**2. Generic server errors** (network failures, unexpected errors):

```
+----------------------------------------------------------+
|  ...form fields...                                       |
|                                                          |
|           <error message text>                           |
|                            [ Cancel ]  [ Submit ]        |
+----------------------------------------------------------+
```

- Styling: `text-sm text-destructive text-center`
- Positioned between form content and footer buttons
- Cleared automatically when the user initiates a new submit
- This position is correct for generic errors — it sits at the "decision point"
  where the user is about to click Submit, so it is highly visible

Note: the implementation currently places error text correctly (above footer) in
`CreateInitiativeDialog.tsx` and `RegisterProjectDialog.tsx`, but `RefineSpawnDialog.tsx`
renders it BELOW the footer (`DialogFooter` then `{error && ...}`). This is a bug
in the implementation — fix it to match this spec.

---

## Source (shared)

- `packages/web/src/components/ProjectPicker.tsx`
- `packages/web/src/components/ui/dialog.tsx`
- `packages/web/src/components/ui/button.tsx`

---

## Design Review Notes

Reviewed 2026-03-02. This section captures design decisions, rejected alternatives,
implementation gaps, and outstanding questions from the design review.

### 1. Create Initiative: Advanced section for branch override

**Decision**: Added collapsible "Advanced" section containing the branch name field.
Collapsed by default. 99% of users will never touch it — the auto-generated
`cw/<slug>` branch is the right default. But power users managing multiple initiatives
on the same repo need a way to control branch naming.

**Rejected alternative**: Putting branch back as a top-level optional field. This
was removed for good reason (v1 -> v2 simplification). Hiding it behind a collapse
preserves the simplification while maintaining the escape hatch.

**Implementation note**: The current `CreateInitiativeDialog.tsx` (lines 114-127) still
has a top-level `branch` field from v1. It needs to be wrapped in shadcn's `<Collapsible>`
component. The state already exists (`branch` / `setBranch`) — only the template needs
restructuring. The placeholder should be dynamically derived from the name field via slugify.

### 2. Dialog sizing is not one-size-fits-all

**Problem found**: All five dialog components pass no `className` override to
`<DialogContent>`, so they all render at the default `max-w-lg` (512px). Confirmed by
reading the implementations. A "Delete Subpage?" confirmation with two sentences of text
does not need the same width as Create Initiative with its ProjectPicker list.

**Decision**: Introduced a 4-tier sizing system (sm/md/lg/xl). Each dialog gets the
narrowest size that fits its content. Wider dialogs feel empty and unfocused. Narrow
dialogs feel purposeful. This is purely a className override — zero breaking changes.

**Vertical overflow**: Added `max-h-[85vh]` constraint with internal scroll on the body
region. The Create Initiative dialog is the primary beneficiary — a workspace with 15+
registered projects would push the ProjectPicker below the fold without this.

### 3. Animation: already implemented, needs reduced-motion and backdrop fix

**Finding**: The codebase already has correct dialog animations via shadcn's
`data-[state=open/closed]` classes on `DialogContent` and `DialogOverlay` in
`dialog.tsx`. The spec just never documented it. Now it does.

**Action required**: Two changes to `dialog.tsx`:
1. `bg-black/80` -> `bg-black/60` on `DialogOverlay`. The 80% opacity over a dark
   (`#111114`) background creates an almost opaque overlay. 60% is enough to signal
   "modal context" without feeling like a blackout curtain.
2. Wrap animation utilities in `motion-safe:` prefixes for `prefers-reduced-motion`
   compliance. This is a one-line-per-class change. Tailwind handles it natively.

### 4. Register Project: branch auto-detection is a nice-to-have with sharp edges

**Decision**: Spec now includes a "Detecting..." state for the Default Branch field
after URL input. This prevents users from leaving "main" as default when their repo
actually uses "master" or "develop" or "trunk".

**Implementation cost**: Requires a new tRPC procedure (`detectDefaultBranch`) that
shells out to `git ls-remote --symref <url> HEAD`. This is low-risk (read-only git
operation) but adds a server round-trip. Ship the dialog without detection first,
add it in a follow-up. The wireframe accounts for both paths.

**Edge cases documented inline**:
- User edits branch manually before detection completes -> detection result is discarded
- User modifies URL while detection is in-flight -> previous request is aborted
- Private repos with bad auth -> 5-second timeout, graceful fallback message
- Submit button is NOT blocked by pending detection (user can always proceed with current value)

### 5. Task Detail Modal: surgically editable, not fully read-only

**Decision**: Description field gains inline editing (click-to-textarea with pencil
affordance) for pending tasks only. In-progress and completed tasks remain locked.
The pencil icon is hidden entirely for non-pending tasks (not grayed out — a disabled
edit icon implies the feature exists but is locked, which creates a "why can't I?"
question with no good answer).

**Rejected alternative**: Full inline editing of all fields (reassign agent,
change priority, etc.). Agent assignment happens through the dispatch system —
letting users manually reassign would create conflicts with the dispatch queue.
Priority changes on in-progress tasks would be meaningless since the agent is
already working. Keep it simple: only description is editable, only on pending tasks.

**Added**: Agent name as clickable link for in-progress tasks — navigates to agent output
view. This transforms a static label into a useful navigation shortcut for the most common
follow-up action after checking task status ("let me see what the agent is doing").

**Backdrop behavior updated**: The Task Detail Modal is no longer purely "always closes on
backdrop click." If the description textarea is open with unsaved changes, a confirmation
dialog fires. This is a natural consequence of adding inline editing — the dialog is no
longer fully read-only.

### 6. Backdrop behavior: form-aware, not blanket

**Decision**: Four behaviors based on dialog state:

| Dialog type | Backdrop click | Rationale |
|-------------|---------------|-----------|
| Confirmation (Delete Subpage) | Closes, takes safe action | No data to lose |
| Read-only (Task Detail, no edit active) | Closes | No data to lose |
| Task Detail with description edit active | Confirms if dirty | Inline edit has unsaved text |
| Form with optional fields only (Refine Spawn) | Closes | Instructions are low-cost to retype |
| Form with required fields (Create Initiative, Register Project) | Closes if pristine, confirms if dirty | Prevents accidental data loss |

Radix `Dialog` supports `onInteractOutside` for this. Track form dirtiness via a
simple `isDirty` boolean (any field differs from initial value). For Task Detail,
track `isEditingDescription` and `descriptionIsDirty` separately.

### 7. Shift+click: discoverable via tooltip + first-use hint

**Decision**: Two complementary discoverability mechanisms:
1. Delayed tooltip (800ms) on destructive buttons.
2. First-time hint appended to the `window.confirm()` message, scoped to the session.

The tooltip teaches via observation (hover). The in-dialog hint teaches via action
(the exact moment the user hits the confirmation wall). Together, they cover both
the "browsing" and "acting" learning moments.

**Rejected alternative**: "Don't ask again" checkbox. In a multi-agent system
where one misclick can delete an initiative with 50 tasks and 10 running agents,
permanent suppression of confirmations is reckless. Shift+click is per-action
intentionality, which is the correct granularity.

### 8. Focus management: now documented per dialog

**Decision**: Each dialog section now specifies initial focus target, tab order,
and Escape behavior. Key principles:

- **Form dialogs**: Focus first input field (`autoFocus` prop)
- **Confirmation dialogs**: Focus the SAFE action (Keep Subpage, Cancel) to prevent
  accidental destructive actions via Enter key
- **Read-only dialogs**: Focus the dialog container itself
- **Escape**: Context-aware — closes immediately for clean state, confirms for dirty state

Radix Dialog already traps focus and returns it to the trigger on close. The main
implementation gap is that no dialog currently sets `autoFocus` on the safe action
for confirmation dialogs — they all rely on Radix's default (first focusable element),
which happens to be the close `[x]` button. This needs explicit `autoFocus` on the
"Keep Subpage" button in `DeleteSubpageDialog`.

### 9. Error positioning: two-tier system with an existing bug

**Decision**: Field-specific validation errors render inline below the field.
Generic server errors render between form content and footer buttons. This gives
users the right level of locality — field errors point at the problem, server
errors sit at the decision point.

**Bug confirmed**: `RefineSpawnDialog.tsx` renders `{error && ...}` AFTER `<DialogFooter>`
(line 116), placing the error text below the buttons. Verified by reading the source.
This contradicts every other dialog in the system and makes the error easy to miss.
The fix is a 3-line move (lines 116-120 to before line 101).

**Aria note**: Error messages need `role="alert"` so screen readers announce them
when they appear. None of the current implementations do this.

### 10. Form validation: blur + submit, with isTouched guard

**Decision**: Validation fires on blur for format-checkable rules (required, URL format,
slug characters) and on submit for server-validated rules (uniqueness). This gives
immediate feedback without being annoying.

**Critical nuance added**: Validation on blur ONLY fires after the field has been touched
(focused then blurred at least once). Without this guard, tabbing through an empty form
flashes "required" errors on every field — hostile UX that punishes exploration.

**What we do NOT do**: Real-time validation on every keystroke. Showing "Name is
required" while the user is still typing their first character is hostile UX.
Blur-based validation respects the user's intent to finish typing before judging.

**Accessibility**: All inline error messages use `aria-describedby` linked to their
input. This is not optional — it is a WCAG 2.1 Level A requirement.

### 11. Delete Subpage: cascade awareness

**Added during review**: The Delete Subpage dialog now includes a cascade count when
the target page has child subpages. "Do you want to delete the subpage and its 3 child
pages?" This prevents users from accidentally deleting an entire page subtree with one
click. The `pages` table already has `parentPageId` with cascade delete — the data is
there, the UI just needs to surface the consequence.

### 12. Mutation state: preventing double-submit and mid-flight interactions

**Added during review**: All submitting states now explicitly suppress backdrop click,
Escape, and the `[x]` close button. The current implementations only disable the submit
button — but the user can still close the dialog via Escape or backdrop click while a
mutation is in flight, causing the mutation to complete with no visible feedback (the
dialog is gone). This is a real bug in all five dialog components.

Implementation: During `isPending`, set `onInteractOutside={(e) => e.preventDefault()}`
and `onEscapeKeyDown={(e) => e.preventDefault()}` on `<DialogContent>`. Hide (not disable)
the `[x]` button via conditional rendering.

### Implementation gap summary

| # | Gap | File(s) | Priority |
|---|-----|---------|----------|
| 1 | Branch field needs to move into `<Collapsible>` | `CreateInitiativeDialog.tsx` | Medium |
| 2 | Dialog sizes need per-dialog `className` overrides | All 5 dialog components | Low |
| 3 | Error text positioned after footer | `RefineSpawnDialog.tsx` | **High (bug)** |
| 4 | Dialog not locked during mutation (Esc/backdrop still close) | All 5 dialog components | **High (bug)** |
| 5 | Backdrop opacity too heavy in dark mode (`bg-black/80`) | `dialog.tsx` | Low |
| 6 | `motion-safe:` prefixes missing on animation classes | `dialog.tsx` | Low |
| 7 | Inline validation not implemented (blur + isTouched) | All form dialogs | Medium |
| 8 | `aria-describedby` missing on all form error messages | All form dialogs | Medium (a11y) |
| 9 | `role="alert"` missing on server error messages | All form dialogs | Medium (a11y) |
| 10 | Description inline editing not implemented | `TaskDetailModal.tsx` | Medium |
| 11 | Agent name not a clickable link | `TaskDetailModal.tsx` | Low |
| 12 | Delete Subpage cascade count not shown | `DeleteSubpageDialog.tsx` | Medium |
| 13 | Branch auto-detection not implemented | New tRPC procedure + `RegisterProjectDialog.tsx` | Low (nice-to-have) |
| 14 | Shift+click tooltip not implemented | All destructive buttons | Low |
| 15 | First-use confirmation hint not implemented | Shared confirm helper | Low |
| 16 | `autoFocus` on safe button in confirmation dialogs | `DeleteSubpageDialog.tsx` | Low |
| 17 | `max-h-[85vh]` + internal scroll not implemented | All dialog components | Low |
| 18 | ProjectPicker needs `max-h-[200px] overflow-y-auto` | `ProjectPicker.tsx` | Medium |