jason.woltje
13968e9a8b
ci/woodpecker/pr/ci Pipeline failed
Addresses CPS-PRD-REV1-REVIEW-Q90 findings F1 and F3 on PR #1491: F1 (format gate): `prettier --write` on the 18 rev1 bundle documents. Whitespace, table padding, list markers and emphasis delimiters only — a normalized token comparison of every file before/after shows zero content difference, so the ratified text is unchanged and no re-ratification applies. F3 (rev0 relative links): the archived rev0 PRD stays byte-identical (sha256 60cc2f98...36afdf verified) per GOV.1 archive-never-edit. A sibling docs/PRDs/2026-08-26_PRD_rev0/README.md records the digest, the original location, the owner disposition that the in-file links are intentionally historical, and a resolution table for all 9 targets (11 occurrences), each verified to exist. Future relocated archives ship the same README instead of edited bytes. F2 (test step) is investigated separately against the CI log.
109 lines
6.4 KiB
Markdown
109 lines
6.4 KiB
Markdown
---
|
||
id: UI.1
|
||
status: ratified
|
||
ratified: 2026-09-01 (Jason Woltje; PRD rev1 ratification PR)
|
||
---
|
||
|
||
# UI.1 — WebUI control-plane surfaces (all functions of the site)
|
||
|
||
The complete function inventory of the WebUI control plane. Every page obeys
|
||
the governing rules; every control ultimately calls the same engine as the CLI.
|
||
|
||
## Governing rules
|
||
|
||
1. **Full CLI parity** — every aspect of the `mosaic` CLI surfaces in the WebUI
|
||
([[CLI.1-parity]] carries the matrix obligation).
|
||
2. **One canonical API** (L2-D14; register OD-53) — CLI, TUI, WebUI, API, and
|
||
automation share one CLI-backed schema, resolver, planner, authorization,
|
||
transaction, validation, and audit engine. The WebUI holds no separate
|
||
logic.
|
||
3. **The webUI sits OVER official tooling** (D8/D12 hard rule) — no page ever
|
||
reaches the database or filesystem around the tooling; a missing tool means
|
||
the gap is "blocked on tooling" and the tool is built first.
|
||
4. **Strict surface separation** — seat pages never modify role config; role
|
||
pages never modify seat config ([[ROLE.1-role-governance]]).
|
||
5. **No direct settings-file authorship** — settings are generated projections
|
||
(L2-D19; [[DATA.1-record-authority]]).
|
||
6. **Agents can never reach these surfaces** (L2-D13; the API refuses agent
|
||
identity — the enforcement is not the page's absence).
|
||
7. **WebUI drafts** (register OD-54) — draft configuration is revisioned
|
||
server-side desired-state; drafts have no effect until planned and applied.
|
||
|
||
## Interaction conventions
|
||
|
||
Logically separated pages; dropdowns, activate/deactivate buttons, drag-drop
|
||
actions performed on-page.
|
||
|
||
## Page inventory
|
||
|
||
| Page | Section doc | Functions |
|
||
| ---------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- |
|
||
| Seat configuration | [[SEAT.1-seat-profile]] | harness, model, reasoning, workdir, auth account, overlay; separated role-binding section |
|
||
| Role configuration | [[ROLE.1-role-governance]] | manifest editing, revision create/diff/activate/rollback, role links, projection status |
|
||
| Harness configuration | [[HARN.1-harness-config]] | install (button), enable/disable, available-models allowlist, reasoning defaults, provider link, linked accounts |
|
||
| Provider configuration | [[PROV.1-providers]] | provider dropdown, named instances, OAuth/API mode, local providers, activate/deactivate |
|
||
| Authentication | [[AUTHN.1-auth-accounts]] | in-browser OAuth establishment, account list, force renew, deactivate, allowed harnesses |
|
||
| Authorization audit | below | effective grants, escapation potential, drift |
|
||
|
||
## Page: Authorization audit (closes gap G3)
|
||
|
||
Surfaces, per seat, to the user:
|
||
|
||
- **Effective capability grant** — the live intersection
|
||
(role ∩ assignment ∩ lease ∩ workflow ∩ target policy ∩ backend).
|
||
- **Misdirection potential** — which seats hold capabilities that would let
|
||
another seat's work be routed around its own role lane.
|
||
- **Escalation potential** — any path that would add capability. Should be
|
||
provably empty; the audit's job is proving it _stays_ empty.
|
||
- **Drift** — seats whose on-disk projection diverges from their active role
|
||
revision (`role check` class).
|
||
- **Failure/blocked surfacing** (register OD-64) — the canonical alert stream's
|
||
WebUI adapter.
|
||
|
||
Implementation choice (dedicated auditor agent vs mechanical tooling) and the
|
||
auditor-identity problem are on the grill: [[GOV.5-open-questions]] Q-A1/Q-A2.
|
||
|
||
## Cross-cutting requirement
|
||
|
||
Every change made through these pages — or the CLI — automatically reconciles
|
||
authentication, `settings.json`, and required symlinks
|
||
([[DATA.1-record-authority]] §reconciliation; removal-fast / addition-attested
|
||
per L2-D17). The user never touches a file.
|
||
**Measured 2026-08-31** ([[CLI.1-parity]] Artifacts 2–3): the shipped WebUI
|
||
already contains two D12 violations — the admin role/ban toggles and the stored
|
||
harness/provider/model selection mutate state with no backing CLI command.
|
||
Remediation, not precedent. The server-side hierarchy/grants CRUD surface
|
||
(`hierarchy.controller.ts`) is the natural backing for the authorization audit
|
||
page below, but needs a CLI face and an audit read-path first.
|
||
|
||
## E2 inputs (triage 2026-08-31; see [[GOV.2-docs-inventory]])
|
||
|
||
**Canonical ground truth**: `USER-GUIDE/product/web-dashboard.md` (route-by-route
|
||
current state, incl. explicit gaps — no New Project/Task UI),
|
||
`webui/PHASE-P-STRUCTURE.md` (Next→Vite SPA migration).
|
||
**Pending pulls**: DRAFT S2 `onboarding-wizard.md` (D4/D11/D8),
|
||
`tool-gateway-mapping.md` (the D8/D12 gate made concrete), `api-artifacts.md`.
|
||
|
||
## S2 contract feed (extraction 2026-08-31)
|
||
|
||
Full extraction record: lane `S2-EXTRACTION-2026-08-31.md` (per-contract cores, dependency edges, ruling cross-checks). Pulls binding on this section:
|
||
|
||
- **Contract 5 verbatim-affirms the parity rule**: "The webUI is a Gateway
|
||
client only"; "No webUI-only command exists; a Gateway command without CLI
|
||
exposure is a conformance gap." "Blocked on tooling" closure is mandatory;
|
||
UI workarounds (direct DB/filesystem, legacy endpoints, domain logic in the
|
||
web app) are non-conformant. This is the ratifiable D8/D12 text this
|
||
section's violation findings measure against.
|
||
- **Legacy non-substitutes** barred from backing any P1 surface, frozen for
|
||
new consumers: `/api/projects`, `/api/tasks` CRUD, `POST /api/workspaces`,
|
||
`/api/teams` reads, `POST /api/bootstrap/setup`, MCP `brain_*` mutations.
|
||
- **Onboarding wizard (contract 3)** is the reference pattern for every config
|
||
page this section specifies: pure client-side composition of Gateway
|
||
commands, exactly one disclosed server-side composed transaction (bootstrap
|
||
finalize), wizard state always derived from canonical state — never a
|
||
persisted answer file that can drift.
|
||
- **Company visibility** (`private` default vs `directory`) is a UI-facing
|
||
disclosure control with a bounded existence-only carve-out.
|
||
- P1 build rank order (T10): hierarchy → hierarchy RBAC → typed kanban →
|
||
agent enrollment → authorized roll-up → onboarding orchestration.
|