From 6a2b9a9ddec3e6654712b8003a7c19b976dff46b Mon Sep 17 00:00:00 2001 From: tegwick Date: Sat, 27 Jun 2026 13:39:13 +0200 Subject: [PATCH] Define Core Hub operator UI contract --- docs/specs/README.md | 1 + docs/specs/ui-operator-console.md | 76 +++++++++++++++---- docs/specs/whynot-ui-adapter.md | 70 +++++++++++++++++ ...-WP-0006-operator-console-and-whynot-ui.md | 8 +- 4 files changed, 138 insertions(+), 17 deletions(-) create mode 100644 docs/specs/whynot-ui-adapter.md diff --git a/docs/specs/README.md b/docs/specs/README.md index 8e7e27b..2966a8d 100644 --- a/docs/specs/README.md +++ b/docs/specs/README.md @@ -14,6 +14,7 @@ This directory is the specification map for Core Hub. The specs are intentionall - [Auth, Access, and Custody](auth-access-and-custody.md) - API auth semantics and secret routing rules - [Workplan Coordination](workplan-coordination.md) - file-first workplans, tasks, progress, messages, decisions - [UI and Operator Console](ui-operator-console.md) - whynot-design aligned UI direction +- [whynot UI Adapter](whynot-ui-adapter.md) - design-system consumption and adapter rules - [Testing, Release, and Migration](testing-release-and-migration.md) - verification, deployment, and cutover gates ## Contract Artifacts diff --git a/docs/specs/ui-operator-console.md b/docs/specs/ui-operator-console.md index b0a40d2..d97ae56 100644 --- a/docs/specs/ui-operator-console.md +++ b/docs/specs/ui-operator-console.md @@ -10,22 +10,72 @@ Define the Core Hub operator interface without coupling the framework to one UI - Prefer custom-element/Lit adapters for framework-neutral surfaces. - Keep the canonical UI contract separate from generated or hand-authored implementation code. - Use Playwright visual checks once UI components exist. +- Treat the console as an operational tool: dense, readable, stable, and built for repeated review. -## Initial Console Areas +## Console Information Architecture -- hub registry and health -- active workplans and blocked tasks -- progress/event stream -- messages and agent coordination -- decisions and deployment records -- API consumers and non-secret access metadata -- compatibility/migration dashboard +The first console should use a persistent shell with top-level operational areas. Each area maps to Core Hub API/resources so the UI can be implemented as server-rendered HTML, HTMX fragments, Lit components, or another thin adapter without changing the framework contract. -## Design Constraint +| Area | Purpose | Primary resources | Expected actions | +|---|---|---|---| +| Overview | Show system health, open blockers, recent progress, and readiness gates. | health, workplans, tasks, progress, migration runs | refresh, filter by severity, open linked record | +| Hub registry | Inspect hubs, active manifests, declared capabilities, widgets, and events. | hubs, hub capability manifests, widgets, interaction events | register hub, activate manifest, inspect capability | +| Workplans | Review active workplans, tasks, status drift, and human-needed items. | workplans, tasks, consistency reports | change task status, mark human review, open file reference | +| Event stream | Read recent interaction events, progress notes, and operational evidence. | interaction events, progress, outcome signals | filter by hub, task, event type, time window | +| Decisions | Browse decisions, deployment records, requirements, and evidence links. | decision records, deployment records, requirements | record decision, link evidence, mark superseded | +| Access | Manage API consumers and non-secret key metadata. | API consumers, API keys, policy scopes | create consumer, rotate key, disable consumer | +| Migration | Track Inter-Hub import readiness, migration bundles, row counts, discrepancies, smokes, rollback state. | migration runs, compatibility fixtures, deployment records | validate bundle, inspect dry-run, mark staging import reviewed | +| Messages | Coordinate agents and operators without exposing credentials. | messages, inbox, progress notes | read, reply, mark read, link to workplan | -The operator console is an operational tool. It should be dense, readable, and stable, not a marketing surface. +## Screen Model -## Open Questions +Every screen should expose the same operational primitives: -- Whether initial UI is server-rendered, Lit/custom-element, or a thin static frontend consuming FastAPI. -- Which Inter-Hub admin screens should be preserved as compatibility views vs. redesigned. +- title and short status line; +- filter controls for status, severity, source hub, owner, and time window where relevant; +- dense table or list body with stable columns; +- detail drawer or detail page for long JSON, evidence, and history; +- explicit empty, loading, stale, degraded, and unauthorized states; +- last refreshed timestamp and source API path; +- links back to backing workplan files when a record originates in git. + +## Initial Navigation + +1. Overview +2. Registry +3. Workplans +4. Events +5. Decisions +6. Access +7. Migration +8. Messages +9. System + +`System` holds health, OpenAPI, consistency, release, and deployment diagnostics. It should not become a dumping ground for ordinary operator workflows. + +## Data Exposure Rules + +- Never render full API keys, raw tokens, database passwords, SSH material, or provider credentials. +- Render API key prefix, hash custody status, scopes, consumer status, creation time, and rotation status only. +- For migration bundles, render source, bundle hash, counts, warnings, and relationship diagnostics; do not render secrets from rejected payloads. +- Distinguish current state from imported historical state. +- Make uncertainty explicit with status labels such as `unverified`, `stale`, `degraded`, `blocked`, and `fallback`. + +## Workflow Priority + +The first useful prototype should implement read-heavy surfaces before mutation-heavy ones: + +1. Overview with active blockers and readiness gates. +2. Registry read model for hubs, manifests, widgets, and events. +3. Migration dashboard for validation/import reports. +4. Access read model for consumers and key prefixes. +5. Workplan/task status view with file links. +6. Mutations for task status, manifest activation, consumer/key lifecycle, and decision records. + +## Visual Posture + +Use whynot-design quiet, document-like operational language: mostly neutral surfaces, strong typography hierarchy through labels and tables, no marketing hero, no decorative imagery, no gradients, no animation beyond basic hover/focus feedback. The console should feel like a control room notebook rather than a product landing page. + +## Open Implementation Choice + +The preferred first implementation is a thin FastAPI-served HTML/HTMX or static custom-element shell that consumes `/api/v2` and later Core Hub-native read endpoints. A heavier SPA should wait until the API and workflows prove the extra runtime is useful. diff --git a/docs/specs/whynot-ui-adapter.md b/docs/specs/whynot-ui-adapter.md new file mode 100644 index 0000000..f95e027 --- /dev/null +++ b/docs/specs/whynot-ui-adapter.md @@ -0,0 +1,70 @@ +# whynot UI Adapter Spec + +## Purpose + +Map the whynot-design system into Core Hub without binding Core Hub to a single frontend framework or copying design behavior by hand. + +## Source Contract + +Core Hub consumes whynot-design as an external design contract: + +- Layer 1: `colors_and_type.css`, `components.css`, and token files. +- Layer 2: Lit custom elements such as ``, ``, ``, ``, ``, ``, and ``. +- Layer 3: optional adapters or server-side partials for repeated patterns. +- IR: committed `whynot-design/ir/` tokens, component contracts, exemplars, and schemas. + +Core Hub must not hand-edit whynot-design IR or fork tokens. Changes to shared visual language belong in whynot-design and flow through its adapter/drift process. + +## Consumption Modes + +| Mode | When to use | Core Hub stance | +|---|---|---| +| Static vendored assets | First prototype or server-rendered console. | Copy or package whynot CSS and `index.js` into Core Hub static assets with a repeatable sync command. | +| Custom elements directly | Default UI implementation mode. | Use `` tags in HTML/Jinja/HTMX/static pages; pass state through attributes and slots. | +| Framework adapter | Only when a stack wrapper removes meaningful repetition. | Generate scaffold/drift reports from whynot IR; never overwrite hand-authored behavior. | +| Bespoke component | Only for Core Hub-specific operational views not present in whynot. | Preserve whynot tokens, typography, spacing, and data-state semantics. | + +## Component Mapping + +| Core Hub need | Preferred whynot primitive | +|---|---| +| Application shell | ``, `` | +| Page title and actions | `` | +| Primary/secondary/ghost command | `` | +| Status, severity, task state, policy scope | ``, `` | +| Dense registry/list surface | `` or table classes from `components.css` | +| Form row and filter controls | ``, ``, ``, `` | +| Warnings and blocked states | `` | +| Empty/no-results state | `` | +| Breadcrumb/context trail | `` | +| Progress or migration stage | `` where a true ordered stage model exists | + +## Core Hub Adapter Rules + +1. Tokens are generated or vendored deterministically; rerunning sync on unchanged whynot-design output should produce no diff. +2. Component behavior remains hand-authored in Core Hub only when it is Core Hub-specific. +3. Attribute names should follow whynot IR prop-to-attribute mappings. +4. Non-portable props from whynot IR must be surfaced as adapter drift, not silently ignored. +5. Adapter reports are snapshots, not logs; regenerate instead of appending. +6. Visual parity checks should use whynot-design exemplars for shared components and Core Hub screenshots for composed screens. +7. Core Hub screens must not introduce secrets into DOM state, local storage, test snapshots, or visual artifacts. + +## Data-State Semantics + +Use stable, low-cardinality state names across UI, API, and tests: + +- lifecycle: `draft`, `active`, `disabled`, `archived`, `superseded`; +- task: `wait`, `todo`, `progress`, `done`, `cancel`; +- readiness: `unverified`, `ready`, `degraded`, `blocked`, `fallback`; +- migration: `validated`, `dry-run`, `imported`, `discrepancy`, `rolled-back`; +- severity: `info`, `warn`, `fail`, `critical`. + +When an API value is richer than these UI states, preserve the raw value in the detail view and map only the visible status marker. + +## First Adapter Deliverables + +1. Static whynot asset sync plan or package dependency decision. +2. One console shell using whynot custom elements directly. +3. One registry table and one migration-run table with empty/loading/error states. +4. Playwright smoke that checks desktop and mobile screenshots for non-overlap and visible controls. +5. Drift/parity note that records the whynot-design git ref used by Core Hub. diff --git a/workplans/CORE-WP-0006-operator-console-and-whynot-ui.md b/workplans/CORE-WP-0006-operator-console-and-whynot-ui.md index ebbd3c5..26e9cdd 100644 --- a/workplans/CORE-WP-0006-operator-console-and-whynot-ui.md +++ b/workplans/CORE-WP-0006-operator-console-and-whynot-ui.md @@ -20,23 +20,23 @@ Create the Core Hub operator UI without binding the framework contract to a sing ```task id: CORE-WP-0006-T01 -status: todo +status: done priority: medium state_hub_task_id: "8ea0294d-2730-4d4a-9c96-394ed6874368" ``` -Define screens for hub registry, workplans, blocked tasks, progress/events, decisions, messages, API consumers, and migration status. +Result 2026-06-27: Defined the operator console IA in `docs/specs/ui-operator-console.md`, covering shell navigation, screen model, workflows, data exposure rules, and first prototype priorities. ## Map whynot-design Contract ```task id: CORE-WP-0006-T02 -status: todo +status: done priority: medium state_hub_task_id: "f16e2dba-b6fb-46e2-8f66-272ef0300f63" ``` -Map whynot-design tokens, component semantics, and adapter rules to Core Hub UI needs. +Result 2026-06-27: Added `docs/specs/whynot-ui-adapter.md`, mapping whynot-design tokens, custom elements, IR/adapter rules, component usage, data-state semantics, and first adapter deliverables to Core Hub. ## Build First UI Prototype