106 lines
10 KiB
Markdown
106 lines
10 KiB
Markdown
# Phase 0 Research: Workspace Governance Attention Foundation
|
|
|
|
## Decision: Reuse `WorkspaceOverviewBuilder` as the single orchestration point for workspace governance attention
|
|
|
|
**Rationale**: The current workspace home already builds one typed payload through `WorkspaceOverviewBuilder`, and it already applies visible-tenant scoping plus workspace capability checks before computing metrics, attention, and recency. The missing behavior is not a missing builder seam; it is that the builder currently stops at operations and alerts. Extending that existing orchestration point is narrower than creating a second workspace posture service.
|
|
|
|
**Alternatives considered**:
|
|
- Create a new workspace posture builder or presenter layer: rejected because it would duplicate ownership and violate the repo's bias toward few layers.
|
|
- Push governance promotion into widget-local queries: rejected because it would spread truth ownership across multiple workspace widgets.
|
|
|
|
## Decision: Reuse `TenantGovernanceAggregateResolver` and `BaselineCompareStats` per visible tenant instead of inventing workspace-local governance logic
|
|
|
|
**Rationale**: The tenant dashboard already uses `TenantGovernanceAggregate`, `BaselineCompareStats`, and `BaselineCompareSummaryAssessor` to answer exactly the governance questions Spec 175 wants to surface at workspace level: overdue findings, lapsed governance, expiring governance, high-severity active findings, and stale, failed, or materially degraded compare posture. Workspace attention should promote that existing tenant truth, not reinterpret it with a weaker query path.
|
|
|
|
**Alternatives considered**:
|
|
- Create a workspace-only aggregation query for overdue, lapsed, and compare states: rejected because it would split truth ownership away from the existing tenant governance path.
|
|
- Create a persisted workspace governance summary: rejected because the spec explicitly forbids new persistence and the problem is request-time semantics, not lifecycle truth.
|
|
|
|
## Decision: Count governance risk by affected tenant, not by raw issue total, in workspace summary metrics
|
|
|
|
**Rationale**: The workspace question is “which tenants need attention” rather than “how many findings exist.” Counting visible tenants with overdue findings, lapsed governance, or stale, failed, or materially degraded compare posture gives the operator a portfolio answer and avoids one noisy tenant dominating the workspace strip.
|
|
|
|
**Alternatives considered**:
|
|
- Show raw totals for overdue findings or lapsed exceptions across the whole workspace: rejected because it weakens triage value and makes the summary less tenant-actionable.
|
|
- Keep the existing single `needs attention` count derived from operations and alerts only: rejected because it preserves the false-calm problem.
|
|
|
|
## Decision: Rank governance-critical tenant states above activity-only and alert-delivery-only items
|
|
|
|
**Rationale**: The spec explicitly requires governance-critical states such as lapsed governance, overdue findings, high-severity active findings, and stale, failed, or materially degraded compare posture to outrank active operations and alert-delivery failures. Workspace attention should still include operations or alerts, but only after governance-critical tenant problems have had a chance to surface.
|
|
|
|
**Alternatives considered**:
|
|
- Keep current recency-first ordering with governance added lower down: rejected because it still lets busy but healthier workspaces look more urgent than risky but quiet ones.
|
|
- Remove operations and alerts entirely: rejected because they remain useful as supporting attention once governance-critical signals are represented.
|
|
|
|
## Decision: Make every workspace attention item tenant-identifiable with one primary destination
|
|
|
|
**Rationale**: The current workspace attention items are generic operations or alert items. Spec 175 requires tenant identity, problem family, relevance, and next jump. A bounded item contract with tenant label plus one primary destination is the narrowest way to satisfy this without turning the workspace home into a matrix or a second diagnostics page.
|
|
|
|
**Alternatives considered**:
|
|
- Continue using generic titles like “operations are still running”: rejected because it does not answer which tenant to open first.
|
|
- Add multiple buttons per item: rejected because it makes the attention surface noisier and less decisive.
|
|
|
|
## Decision: Use RBAC-safe fallback or disabled explanatory states instead of dead-end drill-throughs
|
|
|
|
**Rationale**: Some workspace members may be able to see that a tenant has a problem but may not hold the most precise downstream capability, such as findings inspection. The constitution permits visible disabled states for in-scope members. The safest behavior is to choose an allowed fallback such as the tenant dashboard or to render a disabled explanatory state instead of a clickable link that ends in `403`.
|
|
|
|
**Alternatives considered**:
|
|
- Hide the tenant problem entirely when the precise destination is not allowed: rejected because it can make the workspace appear calmer than reality.
|
|
- Always link to the precise destination and rely on downstream authorization failure: rejected because the spec forbids dead-end drill-throughs.
|
|
|
|
## Decision: Default zero-tenant recovery to the existing choose-workspace route
|
|
|
|
**Rationale**: The current admin workspace flow already uses `/admin/choose-workspace` as the canonical recovery surface when no usable workspace or tenant context is available. Reusing that existing route keeps the workspace overview honest for zero-tenant members without inventing a new recovery surface or asking them to infer the next step.
|
|
|
|
**Alternatives considered**:
|
|
- Treat zero-tenant state as a healthy calm empty state: rejected because it hides a scope problem as a health signal.
|
|
- Default zero-tenant recovery to a workspace-management surface: rejected because many members can switch workspace but cannot manage workspace memberships.
|
|
|
|
## Decision: Route alert-only follow-up to the existing alerts overview at `/admin/alerts`
|
|
|
|
**Rationale**: The app already has an admin alerts overview that serves as the canonical entry point for alert health, rules, and delivery follow-up. Using that route for workspace alert-only attention is narrower and more stable than inventing a new alert-delivery deep-link contract inside this slice.
|
|
|
|
**Alternatives considered**:
|
|
- Send alert-only attention directly to an alert-deliveries list route: rejected because the current operator surface is the alerts overview at `/admin/alerts`.
|
|
- Drop alert-only follow-up entirely: rejected because alert delivery remains a valid supporting attention family once governance-critical items are represented.
|
|
|
|
## Decision: Keep evidence and review promotion opportunistic, not foundational, in this slice
|
|
|
|
**Rationale**: The codebase already has tenant evidence and review resources, but the current workspace overview has no evidence or review aggregation. Spec 175 allows evidence or review issues where already available. The narrow implementation is to use those surfaces only when existing tenant truth already provides a clear problem family and a clear target, not to build a new workspace evidence or review subsystem.
|
|
|
|
**Alternatives considered**:
|
|
- Exclude evidence and review entirely: rejected because the spec explicitly leaves room for them where they already provide value.
|
|
- Build a dedicated workspace evidence or review aggregate now: rejected because it exceeds the foundation scope of the feature.
|
|
|
|
## Decision: Keep `WorkspaceRecentOperations` as diagnostic recency, not portfolio posture
|
|
|
|
**Rationale**: The current recent-operations widget already serves a clear supporting role and is covered by existing tests that verify visible-tenant filtering and the absence of polling. The spec does not require changing its query model; it requires preventing that surface from being mistaken for the workspace's main truth surface.
|
|
|
|
**Alternatives considered**:
|
|
- Expand recent operations into the primary attention owner: rejected because it would keep the workspace entry point operations-centered.
|
|
- Remove recent operations from the overview: rejected because it still provides useful context when subordinated to governance attention.
|
|
|
|
## Decision: Treat workspace calmness as a checked-domain claim instead of an operations-only empty state
|
|
|
|
**Rationale**: The current `WorkspaceNeedsAttention` empty state says “Nothing urgent in your current scope” and explains that recent operations and alert deliveries look healthy. That wording is only valid if the page is consciously limiting its claim to those domains. After governance promotion, calm messaging must be based on both governance and activity signals in visible scope, or else be narrowed explicitly.
|
|
|
|
**Alternatives considered**:
|
|
- Keep the current empty-state wording and rely on new governance items to suppress it sometimes: rejected because the wording still over-claims portfolio health.
|
|
- Remove calm messaging entirely: rejected because a truthful all-clear remains useful when the covered domains are genuinely calm.
|
|
|
|
## Decision: Lean on request-scoped derived-state caching instead of new persistence for performance
|
|
|
|
**Rationale**: `TenantGovernanceAggregateResolver` already uses request-scoped derived-state caching. That makes per-visible-tenant governance resolution viable for the workspace overview without introducing a new summary table or materialized view. This keeps the implementation within the spec's no-new-persistence constraint.
|
|
|
|
**Alternatives considered**:
|
|
- Add a cached database aggregate or background precompute job: rejected because it introduces durability and lifecycle cost the feature does not need.
|
|
- Resolve all tenant governance truth from raw ad-hoc queries without using the resolver: rejected because it ignores an existing request-scope caching seam and increases drift risk.
|
|
|
|
## Decision: Protect the feature with focused workspace overview regression tests instead of manual review alone
|
|
|
|
**Rationale**: The highest-risk failures are semantic: false calmness, wrong tenant prioritization, missing tenant labels, or broken destinations. Existing workspace overview tests already cover access, landing, navigation, permission visibility, empty states, content, and operations slice behavior. Extending that suite with governance attention and drill-through coverage is the narrowest way to keep this contract stable.
|
|
|
|
**Alternatives considered**:
|
|
- Rely on manual browser review only: rejected because semantic regressions are subtle and easy to reintroduce.
|
|
- Build a full browser-based suite first: rejected because focused Pest coverage is already the repo's normal enforcement layer for Filament truth contracts.
|