specs/058-tenant-ui-polish/checklists/requirements.md

@@ -0,0 +1,35 @@
+# Specification Quality Checklist: Tenant UI Polish (v1)
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2026-01-20
+**Feature**: [specs/058-tenant-ui-polish/spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- Validation run: 2026-01-20
+- Items marked incomplete require spec updates before `/speckit.clarify` or `/speckit.plan`

specs/058-tenant-ui-polish/spec.md

@@ -0,0 +1,144 @@
+# Feature Specification: Tenant UI Polish (Dashboard + Inventory Hub + Operations)
+
+**Feature Branch**: `058-tenant-ui-polish`  
+**Created**: 2026-01-20  
+**Status**: Draft  
+**Input**: User description: "Feature 058 — Tenant UI Polish: Dashboard + Inventory Hub + Operations \"Orders-style\" (v1)"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - Drift-first tenant dashboard (Priority: P1)
+
+As a tenant admin, I can open a tenant-scoped dashboard that immediately surfaces drift risk and operations health, without triggering any remote calls.
+
+**Why this priority**: This is the primary entry point for day-to-day operations and should be actionable at a glance.
+
+**Independent Test**: Visiting the dashboard shows drift + operations KPIs, a “needs attention” list with working CTAs, and recent lists, while confirming no outbound HTTP happens during render and any background UI updates.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am signed in to a tenant, **When** I open the Dashboard, **Then** I see tenant-scoped drift KPIs, operations health KPIs, and recent lists.
+2. **Given** there are urgent drift issues (e.g., high severity open findings), **When** I view the Dashboard, **Then** they appear in the “Needs Attention” section with a CTA that navigates to a filtered view.
+3. **Given** drift generation has a recent failed run, **When** I view the Dashboard, **Then** I can navigate from “Needs Attention” to the related operation run details.
+4. **Given** there is no drift data yet, **When** I view the Dashboard, **Then** the dashboard renders calmly with empty-state messaging and no errors.
+
+---
+
+### User Story 2 - Inventory becomes a hub module (Priority: P2)
+
+As a tenant admin, I can use Inventory as a “hub” with consistent sub-navigation and a shared KPI header across Inventory subpages.
+
+**Why this priority**: Inventory is a high-traffic area; a hub layout reduces cognitive load and makes it easier to find the right view quickly.
+
+**Independent Test**: Navigating Inventory Items / Sync Runs / Coverage keeps the same shared KPI header, the left sub-navigation is consistent, and all data remains tenant-scoped and DB-only.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am signed in to a tenant, **When** I open Inventory, **Then** I see hub navigation (Items / Sync Runs / Coverage) and a shared KPI header.
+2. **Given** I switch between Inventory subpages, **When** I navigate Items → Sync Runs → Coverage, **Then** the KPI header remains visible and consistent.
+3. **Given** the tenant has an inventory sync run history, **When** I open “Sync Runs”, **Then** I see only sync runs relevant to inventory synchronization.
+
+---
+
+### User Story 3 - Operations index “Orders-style” (Priority: P3)
+
+As a tenant admin, I can view Operations in an “orders-style” overview (KPIs + status tabs + table) to quickly assess activity and failures.
+
+**Why this priority**: Operations is the canonical place to investigate work; better scanning and filtering reduces time-to-triage.
+
+**Independent Test**: Visiting Operations index shows KPI cards and status tabs that correctly filter the table without introducing polling churn or any remote calls.
+
+**Acceptance Scenarios**:
+
+1. **Given** I am signed in to a tenant, **When** I open Operations, **Then** I see KPIs, status tabs, and the operations table.
+2. **Given** there are active runs, **When** I click the “Active” tab, **Then** the table filters to queued + running runs only.
+3. **Given** there are failed runs, **When** I click the “Failed” tab, **Then** the table filters to failed runs only.
+4. **Given** I navigate away and back, **When** I return to Operations, **Then** the UI remains calm (no refresh loops) and loads quickly.
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+- No data yet: dashboard/inventory/operations render with empty states and helpful CTAs.
+- Large tenants: KPI calculations remain fast enough to keep pages responsive.
+- Mixed outcomes: partial/failed/succeeded runs are correctly categorized and discoverable via tabs/filters.
+- Tenant switching: no cross-tenant leakage of KPIs, lists, or links.
+- Time windows: KPI windows (e.g., last 7/30 days) handle timezones consistently.
+- “Unknown” states: missing duration/end time renders gracefully (e.g., avg duration excludes non-terminal runs).
+
+## Requirements *(mandatory)*
+
+**Constitution alignment (required):** If this feature introduces any Microsoft Graph calls, any write/change behavior,
+or any long-running/queued/scheduled work, the spec MUST describe contract registry updates, safety gates
+(preview/confirmation/audit), tenant isolation, run observability (`OperationRun` type/identity/visibility), and tests.
+If security-relevant DB-only actions intentionally skip `OperationRun`, the spec MUST describe `AuditLog` entries.
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001 (Tenant scope)**: System MUST ensure the Dashboard, Inventory hub, and Operations views are tenant-scoped, with no cross-tenant visibility.
+- **FR-002 (DB-only surfaces)**: System MUST keep Dashboard, Inventory hub header, and Operations index DB-only during render and any background UI updates.
+- **FR-003 (Placement policy)**: System MUST show KPI cards only on these entry-point pages: Dashboard, Inventory hub (shared header), and Operations index.
+- **FR-004 (Inventory hub layout)**: System MUST provide an Inventory hub with left sub-navigation for Items, Sync Runs, and Coverage.
+- **FR-005 (Inventory KPIs)**: Inventory hub MUST show a shared KPI header across Inventory subpages with:
+  - Total Items
+  - Coverage % (covered items / total items)
+  - Last Inventory Sync (status + timestamp)
+  - Active Operations (queued + running)
+- **FR-006 (Inventory sync runs view)**: System MUST provide a “Sync Runs” view that lists only inventory synchronization runs.
+- **FR-007 (Coverage chips)**: System MUST standardize coverage chips to this set only: Restorable, Partial, Risk, Dependencies.
+- **FR-008 (Operations index KPIs)**: Operations index MUST show tenant-scoped KPIs:
+  - Total Runs (30 days)
+  - Active Runs (queued + running)
+  - Failed/Partial (7 days)
+  - Avg Duration (7 days, terminal runs only)
+- **FR-009 (Operations tabs)**: Operations index MUST provide status tabs that filter the operations table: All, Active, Succeeded, Partial, Failed.
+- **FR-010 (Canonical terminology)**: System MUST use “Operations” as the canonical label (no legacy naming on these surfaces).
+- **FR-011 (Canonical links)**: “View run” links MUST always navigate to the canonical operation run detail view.
+- **FR-012 (Calm UI rules)**: System MUST avoid polling/churn in modals and avoid refresh loops; background updates should be used only where clearly necessary.
+
+**Assumptions**:
+- Drift findings, inventory items, and operation runs already exist as tenant-scoped data sources.
+- “Coverage %” defaults to covered/total; if total is 0, coverage shows as not available.
+- Creating/generating drift is out of scope unless it can be performed as an explicit, enqueue-only user action that results in an operation run.
+
+### Key Entities *(include if feature involves data)*
+
+- **Tenant**: The scope boundary for all dashboards and lists in this feature.
+- **Operation Run**: A tenant-scoped record of work execution, including status, timestamps, and outcomes used for Operations KPIs and recent lists.
+- **Drift Finding**: A tenant-scoped record representing detected drift, including severity and state (open/closed) used for Dashboard KPIs and “Needs Attention”.
+- **Inventory Item**: A tenant-scoped record representing inventory coverage and totals used in the Inventory hub.
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001 (Task speed)**: A tenant admin can reach “what needs attention” (drift/ops) from the dashboard within 30 seconds.
+- **SC-002 (Discoverability)**: A tenant admin can find inventory sync runs within 2 clicks from Inventory.
+- **SC-003 (Triage efficiency)**: A tenant admin can filter Operations to “Active” or “Failed” within 1 click and identify a run to investigate within 60 seconds.
+- **SC-004 (Calm UI)**: No refresh loops are observed on Dashboard, Inventory hub pages, or Operations index during normal navigation.
+- **SC-005 (Safety)**: Viewing Dashboard, Inventory hub pages, and Operations index does not trigger any outbound HTTP.