Implementation Plan: Workbench UI

Provide an operator/developer “Workbench” UI for inspecting semantic state and operating the system: KGS explorer, manifest inspector, adapter/gateway console, governance console, and simulation cockpit.

Provenance & Traceability

Architectural Decisions (ADRs)

Product Requirements (PRDs)

Software Design Specifications (SDS)

Dependencies (Existing Specs This Plan Builds On)

• KGS querying: docs/specs/semantic-core/sds/003-knowledge-graph-service.md
• Manifest inspection: docs/specs/shared/reference/011-manifest-schema.md
• Governance evidence: docs/specs/shared/sds/047-governedspeed-governance-runtime.sds.yaml (supersedes SDS-043)
• Observability envelope: docs/specs/shared/sds/030-semantic-observability.md
• UI shells integration patterns: docs/specs/shared/sds/048-platform-ui-integration.md

Architecture and Design

Design Principles Applied

• Isomorphism: Workbench surfaces are projections of semantic state (KGS/manifest/evidence), not hand-maintained.
• Invariants: No privileged actions without explicit authority/approval (SDS-031).
• Idempotency: Operational actions triggered from UI are commands with request IDs (like SDS-048 CMD-060).

Expected Filetree

1
2
3
/
├── docs/specs/**                             # (new) PRD/SDS for workbench UI
└── apps/**/src/gen/**                        # generated UI shell code (if applicable)

Proposed Cycles

Task Breakdown

Wave 1 (Parallel)

• C1A: Author missing PRD/SDS for Workbench UI ✅ PRD-025 and SDS-054 already complete
  • Implements: Read-only views (KGS, manifests, evidence) and gated actions (simulations, approvals)
  • Satisfies: PRD-025, ADR-033
  • Files: docs/specs/shared/prd/025-workbench-ui.md, docs/specs/shared/sds/054-workbench-ui-service.md
• C1B: Define read-only “console” endpoints and models for workbench consumption
  • Implements: Queries and DTOs for KGS/manifest/evidence browsing
  • Satisfies: Operator inspection use-cases
  • Files: docs/specs/shared/sds/048-platform-ui-integration.md (extend with workbench endpoints) or new SDS
• C1C: Add Case Management Console integration
  • Implements: Case dashboard, task queue, artifact pipeline, timeline (incl. historical cases)
  • Satisfies: PRD-026 (Case Management Platform), SDS-012
  • Files: docs/specs/shared/sds/054-workbench-ui-service.md (extended)

Wave 2 (Depends on Wave 1)

• C2A: Define and enforce privileged operational actions (approvals, break-glass, simulation runs) ✅ SDS-054 §Action Endpoints
  • Implements: Authority + audit rules (SDS-031, REF-012 §10)
  • Satisfies: Governance invariants and auditability requirements (REQ-WB-004, REQ-WB-005)
  • Files: docs/specs/shared/sds/054-workbench-ui-service.md (Action Endpoints + Authorization Middleware)

Validation & Verification

Spec Validation

• All workbench actions map to explicit commands/queries with schemas (SDS-054 BFF)
• All privileged actions reference SDS-031 and are auditable (SDS-054 §Authorization)

Implementation Validation

• Read-only views are safe-by-default (no secrets/PII leaks per SDS-030)
• Operational actions require approvals and produce evidence artifacts where applicable (SDS-047)

Note: SDS-043 (Risk & Evidence Service) has been superseded by SDS-047 per ADR-031.

Open Questions

1. Is Workbench a web app inside this repo (apps/*) or an external UI (like Zed/LibreChat)? apps/workbench (internal)
2. What is the minimal read-only surface to ship first (KGS explorer vs governance console)? KGS explorer
3. Should simulation cockpit be part of Workbench or a separate shell/service? Part of Workbench

Risks & Mitigation

Rollback Strategy

1. Ship read-only mode only until authority and audit are fully enforced.

Related Documents

Reference Documents

• docs/specs/shared/sds/048-platform-ui-integration.md
• docs/specs/shared/sds/030-semantic-observability.md