jason.woltje
ad21ad7ac5
ci/woodpecker/pr/ci Pipeline failed
Ratifies the Mosaic Stack PRD rev1 (Jason Woltje, 2026-09-01) as project source of truth and installs the GOV.1 lifecycle model: - docs/PRD.md becomes a permanent shim (kind: shim, current_rev -> docs/PRDs/2026-08-31_PRD_rev1/). Its path never changes again. - docs/PRDs/2026-08-26_PRD_rev0/PRD.md archives the 2026-08-26 North Star verbatim (sha256 60cc2f98...36afdf unchanged). Archive, never delete. - docs/PRDs/2026-08-31_PRD_rev1/ is the frozen rev1 bundle: 18 sectioned documents (VIS, DATA, AUTHN, AUTHZ, SEAT, ROLE, HARN, PROV, SESS, UI, CLI, GOV.1-5) consolidating rev0 D1-D15, the fleet north star, the agent-runtime L1/L2 contracts and the control-plane-surfaces lane findings, with a single decision map (GOV.3) and a closed open-questions frontier (GOV.5, grill rounds 1-8). Drafting inputs (_source-* snapshots) are not shipped. Consequences of the ratified rulings carried in the same change: - Q-T1 (ruling B, "shipped but frozen"): D3 amended in GOV.3/VIS.1; federation M1-M3 acknowledged as shipped behind tier === 'federated', excluded from the v1 bar and frozen, with a security re-audit gate before any resumption. docs/MISSION-MANIFEST.md, docs/federation/MISSION-MANIFEST.md and docs/scratchpads/mvp-20260312.md get status: superseded + banners (content preserved verbatim); docs/guides/deployment.md gains a "Relationship to the PRD (D15)" section. NORTH_STAR.yaml adds dormant workstream M (projects no goals by design); NORTH_STAR.md regenerated. - Q-G2 (distinct registry prefixes): every citation of the operator DECISION-REGISTER in the bundle reads OD-nn; the stack registry stays D1-D15; L1-Dnn/L2-Dnn untouched. Prefix rule recorded in GOV.1. Follow-ups (not in this PR): CI parity drift-gate witness (Q-C1); brain-side DECISION-REGISTER rename to OD- with redirect table on its next touch.
109 lines
5.9 KiB
Markdown
109 lines
5.9 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.
|