# Panel Forms ↔ Backend Data-Consistency Audit

**This is a living reference artifact.** Any PR that changes a backend request schema touched by a form listed below (`ProjectCreateRequest`/`ProjectUpdateRequest` in `roboco/api/schemas/project.py`, `TaskCreate` in `roboco/models/task.py`, the route-level `TaskUpdate` in `roboco/api/schemas/tasks.py`, or a writable settings key in `roboco/services/settings.py`) must update the matching row in this table in the same PR. A stale row here is worse than no row — it tells the next developer a mismatch was checked when it wasn't.

Audited 2026-07-23 directly against the current codebase (v0.26.0) on branch `feature/frontend/73275ff0--170c9578--515697f4` — every verdict below was checked by reading the live dialog component next to the live backend schema, not assumed from the intake's original description. Several fields the intake named as "missing" turned out to already be shipped (by unrelated feature work — the env-branches ladder, forge providers, and task/project cost budgets initiatives all landed after this audit's premise was written); this table reflects what is actually true today.

## Verdict legend

| Verdict | Meaning |
|---|---|
| `ok` | Frontend field/control matches the backend schema and its constraints. |
| `missing` | The backend schema accepts this field but no form control exists for it. |
| `stale` | A label, placeholder, help text, or default no longer matches actual behavior. |
| `validation-mismatch` | The form validates (or fails to validate) differently than the backend will. |
| `n/a` | Deliberately absent by design (system-managed field, role-gated note field, or lifecycle-governed elsewhere). |

---

## Settings page (Stream1-C — this task)

Form: `panel/src/app/(dashboard)/settings/page.tsx`. Backend: `roboco/services/settings.py` (`SettingsService`, `_VALIDATORS`) plus `panel/src/store/ui-store.ts` (`useUIStore`, client-only, zustand `persist`).

**Persistence mechanism for the four toggle rows below (Enable Notifications, Sound Alerts, Auto Refresh, Refresh Interval):** these do NOT round-trip through `settingsApi`/`SettingsService` — they persist entirely client-side via `useUIStore` (zustand `persist` middleware, backed by `localStorage`; see `settings/page.tsx` lines 44-60), with a `toast.success(...)` confirmation fired on every change. `settingsApi` is used by exactly one row on this page — Retention window (days) — see its own row below.

| Field | Verdict | Notes |
|---|---|---|
| Enable Notifications | `ok` (fixed) | Was already migrated to client-only `useUIStore` persistence (localStorage, immediate-apply, no Save button) by a prior fix — see "History" below. This task adds the one piece that was still missing: a confirmation toast on every change. |
| Sound Alerts | `ok` (fixed) | Same as above; also client-disabled while Notifications is off. |
| Auto Refresh | `ok` (fixed) | Same as above. |
| Refresh Interval | `ok` (fixed) | Same as above; toast now names the new interval. |
| Theme | `n/a` | Client-only (`next-themes`), never sent to a server. |
| Collapsed Sidebar | `n/a` | Client-only (`useUIStore`), never sent to a server. |
| Retention window (days) | `ok` | `TranscriptRetentionCard` uses the server-persisted `settingsApi` pattern — this is the one setting that genuinely round-trips to the backend. |
| Feature flag switches | `ok` | `FeatureFlagsCard` writes immediately per-flag with toast feedback. |

### History (why these four fields are client-only, not server-persisted)

An earlier fix discovered that `roboco/services/settings.py`'s `_VALIDATORS` allowlist never contained `notifications_enabled`/`sound_enabled`/`auto_refresh`/`refresh_interval` — every save 422'd, and nothing consumed the values anywhere (no auto-refresh timer, no notification toast, no sound). Rather than widening the backend allowlist, that fix moved the four prefs into `useUIStore` (client-only, same idiom as theme/sidebar) and **deliberately left the backend allowlist untouched** ("the backend allowlist stays strict and untouched" — see the CHANGELOG entry "Settings preferences persist as real client prefs instead of 422-ing as theater"). It also built `AutoRefreshDriver` (ticks the page-refresh registry when Auto Refresh is on) and `NotificationAlerts` (toasts + optional chime on new WS notifications), so the prefs are now both persisted and actually consumed. This task's own acceptance criterion ("read/write through settingsApi") predates that fix and is superseded by it; adding the four keys back to `_VALIDATORS` would be a regression against a documented, deliberate decision, so this task does not touch `roboco/services/settings.py`.

---

## Project dialogs (Stream1-A)

Forms: `panel/src/components/projects/create-project-dialog.tsx` (backend: `ProjectCreateRequest`) and `edit-project-dialog.tsx` (backend: `ProjectUpdateRequest`), both in `roboco/api/schemas/project.py`.

Every field the intake's Stream1-A unit named as missing — `codegen_command`, `git_provider`, `github_installation_id`, `environments`, `monthly_budget_usd`, `sandbox_extensions` — is now present in both the backend schema and the corresponding dialog, shipped by unrelated feature work (the env-branches ladder, forge-provider, and sandbox-extensions initiatives) that landed after Stream1-A was scoped. Stream1-A's field-sync objective is already fully met.

| Field | Create dialog | Edit dialog | Verdict | Notes |
|---|---|---|---|---|
| `name` | ok | ok | `ok` | |
| `slug` | ok (create-only, immutable) | read-only display | `ok` (fixed help text) | Help text said "lowercase, hyphens only" but the backend pattern (`^[a-z0-9-]+$`) also allows digits — fixed to "lowercase letters, numbers, hyphens". |
| `git_url` | ok | ok | `ok` | |
| `git_provider` | ok (Forge select) | ok (Forge select) | `ok` | |
| `github_installation_id` | ok (Select-repo picker) | ok (Select-repo picker + Unbind) | `ok` | |
| `default_branch` | ok | ok | `ok` | |
| `protected_branches` | `n/a` (create has no such field on the backend either) | ok (chip editor) | `ok` | `ProjectCreateRequest.protected_branches` exists but defaults to `[default_branch]`; the create dialog correctly leaves it for the edit dialog post-creation. |
| `environments` | ok (`EnvironmentLadderEditor`) | ok (`EnvironmentLadderEditor`) | `ok` | |
| `git_token` | ok | ok (set/replace/clear flow) | `ok` | |
| `test_command` / `lint_command` / `format_command` / `typecheck_command` / `build_command` / `quality_command` / `codegen_command` | ok (create lacks `codegen_command` — see note) | ok | `ok` | `codegen_command` is edit-only in the UI even though `ProjectCreateRequest` accepts it — matches the create dialog's own comment that autonomous/advanced config is deliberately deferred to "Edit Project" post-creation. |
| `is_active` | `n/a` (create has no such field) | ok | `ok` | |
| `ci_watch_enabled` / `ci_watch_workflow` | `n/a` (create has no such field) | ok | `ok` | |
| `video_engine_enabled` | `n/a` (create has no such field) | ok | `ok` | |
| `dep_update_command` / `dep_update_paths` | `n/a` (create has no such field) | ok | `ok` | |
| `monthly_budget_usd` | `n/a` (`ProjectCreateRequest` has no such field — update-only) | ok | `ok` | |
| `sandbox_services` / `sandbox_extensions` | `n/a` (create has no such field) | ok | `ok` | |

---

## Task dialogs (Stream1-B)

Forms: `panel/src/components/tasks/create-task-dialog.tsx` (backend: `TaskCreate` in `roboco/models/task.py`) and `edit-task-dialog.tsx` (backend: the route-level `TaskUpdate` in `roboco/api/schemas/tasks.py` — a richer schema than the internal `roboco/models/task.py TaskUpdate`; the API route imports the former).

`acceptance_criteria` editing on the edit dialog — the one gap the intake explicitly named for this unit — is already shipped. The remaining gaps below were found during this audit sweep, not named by the intake.

| Field | Create dialog | Edit dialog | Verdict | Notes |
|---|---|---|---|---|
| `title` | ok | ok | `ok` | |
| `description` | ok (Markdown editor, 20-char min) | ok | `ok` | |
| `acceptance_criteria` | ok (`AcceptanceCriteriaEditor`) | ok (`AcceptanceCriteriaEditor`) | `ok` | |
| `team` | ok | ok | `ok` | |
| `priority` | ok | ok | `ok` | |
| `sequence` | ok | ok | `ok` | `TaskCreate.sequence` (create) and the route-level `TaskUpdate.sequence` (edit) both accept sibling ordering; both dialogs now expose a numeric control for it (behind "Advanced Options"), following the existing `budget_usd` numeric-input pattern. |
| `status` | ok (Pending/Backlog at creation) | `n/a` | `n/a` | Post-creation status changes are lifecycle transitions (claim/complete/etc.) gated through role-specific verbs, not a free-text edit field. |
| `estimated_complexity` | ok | ok | `ok` | |
| `nature` | ok | ok | `ok` | |
| `task_type` | ok (behind "Advanced Options") | ok (behind "Advanced Options") | `ok` | |
| `target_date` | missing | ok | `missing` (deferred) | `TaskCreate.target_date` accepts it; only the edit dialog exposes a control. Discovered during this audit sweep, not named as a deliverable by the intake — deferred/out-of-scope for this wave rather than building a new create-dialog control; tracked as a follow-up, not fixed here. |
| `budget_usd` | `n/a` (`TaskCreate` has no such field — update-only) | ok | `ok` (fixed help text) | Mirrors the project dialog's `monthly_budget_usd` shape (create has no field, edit does, both intentional per the backend schema). Help text and validation toast said "empty = task-type default" — that default table was removed (`effective_task_budget_usd`: null = no cap); both strings now say "no cap". |
| `project_id` / `product_id` | ok (behind "Advanced Options") | ok (`project_id` only; locked once `branch_name` is set) | `ok` | `product_id` is create-only by design — a fan-out task's per-cell routing is fixed at creation and `TaskUpdate` carries no `product_id`. |
| `parent_task_id` | ok (behind "Advanced Options") | missing | `missing` (deferred) | The route-level `TaskUpdate.parent_task_id` accepts re-parenting after creation; the edit dialog has no control for it. Discovered during this audit sweep, not named as a deliverable by the intake — deferred/out-of-scope for this wave; tracked as a follow-up, not fixed here. |
| `dependency_ids` | ok (`DependencySelector`) | missing | `missing` (deferred) | The route-level `TaskUpdate.dependency_ids` accepts it; the edit dialog has no equivalent control even though `Task.dependency_ids` is already in the type. Discovered during this audit sweep, not named as a deliverable by the intake — deferred/out-of-scope for this wave; tracked as a follow-up, not fixed here. |
| `blocker_ids` | `n/a` | `n/a` | `n/a` | Present on the route-level `TaskUpdate` schema but every non-test producer of blockers found in `roboco/services/` sets it programmatically (dependency/lifecycle bookkeeping); no evidence this is meant as a manually-edited dialog field, so it is left as a system-managed field pending explicit product direction otherwise. |
| `assigned_to` | ok (behind "Advanced Options") | ok (behind "Advanced Options") | `ok` | |
| `dev_notes` / `qa_notes` / `auditor_notes` / `pr_reviewer_notes` / `doc_notes` / `quick_context` | `n/a` | `n/a` | `n/a` | Role-authored structured note fields written through each role's own gateway verbs, not general-purpose manual edit fields. |
| `plan` / `progress_updates` | `n/a` | `n/a` | `n/a` | Agent execution-tracking artifacts, not manual dialog fields. |
| `branch_name` / `pr_number` / `pr_url` / `docs_complete` / `pr_created` | `n/a` | `n/a` | `n/a` | System-managed git/work-session tracking fields, not user-editable. |