coulomb/core-hub
Archived
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Define Core Hub operator UI contract

Browse Source
This commit is contained in:
Bernd Worsch
2026-06-27 13:39:13 +02:00
parent 0b90ebafd0
commit 6a2b9a9dde
4 changed files with 138 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/specs/README.md
View File

@@ -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

76
docs/specs/ui-operator-console.md
View File

@@ -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.

70
docs/specs/whynot-ui-adapter.md Normal file
View File

@@ -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 `<wn-button>`, `<wn-table>`, `<wn-sidebar>`, `<wn-page-header>`, `<wn-field-row>`, `<wn-tag>`, and `<wn-stage-dot>`.
- 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 `<wn-*>` 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 | `<wn-top-nav>`, `<wn-sidebar>` |
| Page title and actions | `<wn-page-header>` |
| Primary/secondary/ghost command | `<wn-button>` |
| Status, severity, task state, policy scope | `<wn-tag>`, `<wn-stage-dot>` |
| Dense registry/list surface | `<wn-table>` or table classes from `components.css` |
| Form row and filter controls | `<wn-field-row>`, `<wn-input>`, `<wn-select>`, `<wn-search-input>` |
| Warnings and blocked states | `<wn-banner>` |
| Empty/no-results state | `<wn-empty-state>` |
| Breadcrumb/context trail | `<wn-breadcrumb>` |
| Progress or migration stage | `<wn-pipeline>` 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.

8
workplans/CORE-WP-0006-operator-console-and-whynot-ui.md
View File

@@ -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