875528cd35
Implements Spec 114 System Console Control Tower pages, widgets, triage actions, directory views, and enterprise polish (badges, repair workspace owners table, health indicator).
202 lines
15 KiB
Markdown
202 lines
15 KiB
Markdown
---
|
|
description: "Executable task breakdown for Spec 114 implementation"
|
|
---
|
|
|
|
# Tasks: System Console Control Tower (Spec 114)
|
|
|
|
**Input**: Design documents from `specs/114-system-console-control-tower/`
|
|
|
|
**Docs used**:
|
|
- `specs/114-system-console-control-tower/spec.md`
|
|
- `specs/114-system-console-control-tower/plan.md`
|
|
- `specs/114-system-console-control-tower/research.md`
|
|
- `specs/114-system-console-control-tower/data-model.md`
|
|
- `specs/114-system-console-control-tower/contracts/system-console-control-tower.openapi.yaml`
|
|
- `specs/114-system-console-control-tower/quickstart.md`
|
|
|
|
**Tests**: REQUIRED (Pest) for runtime behavior changes.
|
|
|
|
---
|
|
|
|
## Phase 1: Setup (Shared Structure)
|
|
|
|
- [X] T001 Review existing System panel primitives in `app/Providers/Filament/SystemPanelProvider.php`, System auth/security primitives in `app/Filament/System/Pages/Auth/Login.php` + `app/Services/Auth/BreakGlassSession.php`, and System tests in `tests/Feature/System/Spec113/` + `tests/Feature/Auth/BreakGlassModeTest.php` + `tests/Feature/System/OpsRunbooks/` (confirm session isolation cookie middleware, login throttling + audit trail, break-glass banner/audits, 404/403 semantics, and existing Ops-UX start-surface contract patterns)
|
|
- [X] T002 [P] Create new System page namespaces for Spec 114 in `app/Filament/System/Pages/Directory/` and `app/Filament/System/Pages/Security/`
|
|
- [X] T003 [P] Create new System Blade view directories for Spec 114 in `resources/views/filament/system/pages/directory/` and `resources/views/filament/system/pages/security/`
|
|
|
|
---
|
|
|
|
## Phase 2: Foundational (Blocking Prerequisites)
|
|
|
|
- [X] T004 Extend platform capability registry with Spec 114 constants in `app/Support/Auth/PlatformCapabilities.php` (add `platform.console.view`, `platform.directory.view`, `platform.operations.view`, `platform.operations.manage`; keep existing constants for compatibility)
|
|
- [X] T005 Update seeded platform operator capabilities in `database/seeders/PlatformUserSeeder.php` to include the new Spec 114 capabilities
|
|
- [X] T006 Add stuck threshold defaults to `config/tenantpilot.php` under `system_console.stuck_thresholds.{queued_minutes,running_minutes}` (used by `/system/ops/stuck`)
|
|
- [X] T007 [P] Implement a typed time-window helper in `app/Support/SystemConsole/SystemConsoleWindow.php` (allowed: `1h`, `24h` default, `7d`; provides start timestamp)
|
|
- [X] T008 [P] Implement stuck run classification helper in `app/Support/SystemConsole/StuckRunClassifier.php` (DB-only query constraints for queued/running + thresholds)
|
|
- [X] T009 Update System panel access regression tests in `tests/Feature/System/Spec113/AuthorizationSemanticsTest.php` (if needed) to preserve the clarified rule: wrong guard / unauthenticated → 404; platform user missing page capability → 403
|
|
- [X] T010 Add Spec 114 access semantics tests in `tests/Feature/System/Spec114/SystemConsoleAccessSemanticsTest.php` (assert 404 for tenant-guard requests across representative `/system/*` URLs and 403 for platform users missing required capabilities; also assert `/system` uses a distinct session cookie name from `/admin` to enforce SR-006)
|
|
|
|
**Checkpoint**: Capabilities/config/helpers/tests exist; user story work can begin.
|
|
|
|
---
|
|
|
|
## Phase 3: User Story 1 — Global Health & Triage Entry (Priority: P1) 🎯 MVP
|
|
|
|
**Goal**: Control Tower KPIs + top offenders + quick clickthrough to a canonical run detail.
|
|
|
|
**Independent Test**: A platform user can open `/system` (dashboard), switch time window, see KPIs/top offenders, and open a run detail.
|
|
|
|
### Tests (write first)
|
|
|
|
- [X] T011 [P] [US1] Add Control Tower access + window default tests in `tests/Feature/System/Spec114/ControlTowerDashboardTest.php`
|
|
- [X] T012 [P] [US1] Add canonical run detail access + data-minimization tests in `tests/Feature/System/Spec114/CanonicalRunDetailTest.php` (assert SR-004 v1 behavior: no raw error/context drilldowns; only sanitized summaries render)
|
|
|
|
### Implementation
|
|
|
|
- [X] T013 [US1] Gate the dashboard with `platform.console.view` and add a time-window switcher to header actions in `app/Filament/System/Pages/Dashboard.php`
|
|
- [X] T014 [P] [US1] Create KPIs widget in `app/Filament/System/Widgets/ControlTowerKpis.php` (DB-only aggregation on `operation_runs` within selected window)
|
|
- [X] T015 [P] [US1] Create “Top offenders” widget in `app/Filament/System/Widgets/ControlTowerTopOffenders.php` (group failed runs by tenant/workspace/type within window)
|
|
- [X] T016 [P] [US1] Create “Recently failed operations” widget in `app/Filament/System/Widgets/ControlTowerRecentFailures.php` (links to canonical run detail via `app/Support/System/SystemOperationRunLinks.php`)
|
|
- [X] T017 [US1] Register Spec 114 widgets on the System dashboard in `app/Filament/System/Pages/Dashboard.php` (ensure all widget queries are DB-only)
|
|
- [X] T018 [US1] Convert the System runs list to *global* runs (not runbook-only) in `app/Filament/System/Pages/Ops/Runs.php` and keep the table rendering in `resources/views/filament/system/pages/ops/runs.blade.php`
|
|
- [X] T019 [US1] Make run detail canonical (remove runbook-only + platform-workspace-only constraints) and gate it with `platform.operations.view` in `app/Filament/System/Pages/Ops/ViewRun.php`
|
|
- [X] T020 [US1] Generalize the run detail rendering to non-runbook runs in `resources/views/filament/system/pages/ops/view-run.blade.php` (keep sanitized failures + avoid leaking sensitive context by default)
|
|
|
|
**Checkpoint**: US1 is shippable and independently testable.
|
|
|
|
---
|
|
|
|
## Phase 4: User Story 2 — Directory for Workspaces & Tenants (Priority: P2)
|
|
|
|
**Goal**: Provide cross-workspace directory pages with health signals and safe links into ops views.
|
|
|
|
**Independent Test**: A platform user can list workspaces/tenants, open details, and jump to filtered run listings without session bridging.
|
|
|
|
### Tests (write first)
|
|
|
|
- [X] T021 [P] [US2] Add workspaces directory access + listing tests in `tests/Feature/System/Spec114/DirectoryWorkspacesTest.php`
|
|
- [X] T022 [P] [US2] Add tenants directory access + listing tests in `tests/Feature/System/Spec114/DirectoryTenantsTest.php`
|
|
|
|
### Implementation
|
|
|
|
- [X] T023 [US2] Add a System health badge domain (OK/Warn/Critical/Unknown) in `app/Support/Badges/BadgeDomain.php`, map it in `app/Support/Badges/BadgeCatalog.php`, and implement its mapper in `app/Support/Badges/Domains/SystemHealthBadge.php`
|
|
- [X] T024 [P] [US2] Add badge mapping semantics tests in `tests/Feature/Badges/SystemHealthBadgeSemanticsTest.php`
|
|
- [X] T025 [P] [US2] Add directory URL helpers in `app/Support/System/SystemDirectoryLinks.php` (workspaces/tenants index + detail URLs, plus safe “Open in /admin” URL-only links)
|
|
- [X] T026 [US2] Implement Workspaces index page (table + filters) in `app/Filament/System/Pages/Directory/Workspaces.php` with view `resources/views/filament/system/pages/directory/workspaces.blade.php` (gate with `platform.directory.view`)
|
|
- [X] T027 [US2] Implement Workspace detail page in `app/Filament/System/Pages/Directory/ViewWorkspace.php` with view `resources/views/filament/system/pages/directory/view-workspace.blade.php` (tenants summary + recent ops links)
|
|
- [X] T028 [US2] Implement Tenants index page in `app/Filament/System/Pages/Directory/Tenants.php` with view `resources/views/filament/system/pages/directory/tenants.blade.php`
|
|
- [X] T029 [US2] Implement Tenant detail page in `app/Filament/System/Pages/Directory/ViewTenant.php` with view `resources/views/filament/system/pages/directory/view-tenant.blade.php` (connectivity/permission signals + recent ops)
|
|
- [X] T030 [US2] Ensure any “Open in /admin” links remain URL-only (no auto-login, no session bridging) in `resources/views/filament/system/pages/directory/view-workspace.blade.php` and `resources/views/filament/system/pages/directory/view-tenant.blade.php`
|
|
|
|
**Checkpoint**: Directory is usable and independently testable.
|
|
|
|
---
|
|
|
|
## Phase 5: User Story 3 — Operations Triage Actions & Auditability (Priority: P3)
|
|
|
|
**Goal**: Provide failures/stuck/access-log surfaces plus safe triage actions with confirmation and audit trails.
|
|
|
|
**Independent Test**: A view-only platform user can inspect but cannot mutate; a manage-capable user can perform a supported triage action and an audit log entry is written.
|
|
|
|
### Tests (write first)
|
|
|
|
- [X] T031 [P] [US3] Add failures view access + prefilter tests in `tests/Feature/System/Spec114/OpsFailuresViewTest.php`
|
|
- [X] T032 [P] [US3] Add stuck view access + stuck classification boundary tests in `tests/Feature/System/Spec114/OpsStuckViewTest.php`
|
|
- [X] T033 [P] [US3] Add access logs filtering tests in `tests/Feature/System/Spec114/AccessLogsTest.php` (assert `platform.auth.login` includes both success + failure events and includes `platform.break_glass.*` actions)
|
|
- [X] T034 [P] [US3] Add triage action authorization + audit-write tests in `tests/Feature/System/Spec114/OpsTriageActionsTest.php` (include an Ops-UX contract regression assertion for any triage action that queues work: intent-only toast + working “View run” link + no queued database notifications, mirroring `tests/Feature/System/OpsRunbooks/`)
|
|
|
|
### Implementation
|
|
|
|
- [X] T035 [US3] Implement failures page in `app/Filament/System/Pages/Ops/Failures.php` and view `resources/views/filament/system/pages/ops/failures.blade.php` (prefilter failed runs; gate with `platform.operations.view`)
|
|
- [X] T036 [US3] Implement stuck page in `app/Filament/System/Pages/Ops/Stuck.php` and view `resources/views/filament/system/pages/ops/stuck.blade.php` (use `app/Support/SystemConsole/StuckRunClassifier.php`; gate with `platform.operations.view`)
|
|
- [X] T037 [US3] Implement access logs page in `app/Filament/System/Pages/Security/AccessLogs.php` and view `resources/views/filament/system/pages/security/access-logs.blade.php` (AuditLog list scoped to `platform.auth.login` + `platform.break_glass.*`; gate with `platform.console.view`)
|
|
- [X] T038 [US3] Implement triage policy + execution in `app/Services/SystemConsole/OperationRunTriageService.php` (define retryable/cancelable allowlist by operation type; “mark investigated” requires reason and writes audit)
|
|
- [X] T039 [US3] Implement system-console audit logging helper in `app/Services/SystemConsole/SystemConsoleAuditLogger.php` (wrap `app/Services/Intune/AuditLogger.php` using the `platform` tenant; stable action IDs; includes break-glass marker)
|
|
- [X] T040 [US3] Add manage-only Filament actions (Retry/Cancel/Mark investigated) to run tables and run detail in `app/Filament/System/Pages/Ops/Runs.php`, `app/Filament/System/Pages/Ops/Failures.php`, `app/Filament/System/Pages/Ops/Stuck.php`, and `app/Filament/System/Pages/Ops/ViewRun.php` (all mutations use `->action(...)` + `->requiresConfirmation()`, “Mark investigated” includes a required reason field)
|
|
|
|
**Checkpoint**: All Spec 114 operator actions are capability-gated, confirmed, and audited.
|
|
|
|
---
|
|
|
|
## Phase 6: Polish & Cross-Cutting Concerns
|
|
|
|
- [X] T041 [P] Run code formatting on touched files via `vendor/bin/sail` (use `vendor/bin/sail bin pint --dirty --format agent`)
|
|
- [X] T042 Run Spec 114 focused tests via `vendor/bin/sail` in `tests/Feature/System/Spec114/`
|
|
- [X] T043 Validate quickstart steps remain accurate in `specs/114-system-console-control-tower/quickstart.md` (adjust if needed)
|
|
- [X] T044 [P] Optional performance follow-up: add indexes for windowed queries in `database/migrations/` (only if needed after measuring/explain plans; deferred for now because current EXPLAIN baselines do not indicate index pressure at present data volumes)
|
|
- [X] T045 [P] Performance validation: capture a baseline for the primary list pages (dashboard widgets, `/system/ops/runs`, `/system/ops/failures`, `/system/ops/stuck`, directory lists) and only then decide whether T044 is needed
|
|
- [X] T046 Confirm Runbook navigation/shortcuts satisfy FR-007: System navigation provides Runbooks entry, and the canonical run detail exposes a “Go to runbooks” affordance (or explicitly documents “coming soon” where applicable)
|
|
- [X] T047 Explicitly document v1 scope decisions in tasks acceptance notes: Export (FR-009) is deferred; raw error/context drilldowns (SR-004) are not present in v1
|
|
|
|
---
|
|
|
|
## Phase 7: Enterprise UI Polish
|
|
|
|
**Goal**: Elevate the System Console from functional to enterprise-grade: richer page content, contextual badges in navigation, visual hierarchy for break-glass actions, and visible audit trails.
|
|
|
|
- [X] T048 [P] [Polish] Add stats overview widget to Recovery > Repair Workspace Owners page (`app/Filament/System/Pages/Ops/RepairWorkspaceOwners.php`): show "X healthy | Y ownerless | Z stuck" counts above the purpose box
|
|
- [X] T049 [P] [Polish] Add a Workspaces table to Repair Workspace Owners page listing workspaces with owner status (name, owner count, last activity, health badge) — currently the page is empty below the purpose box
|
|
- [X] T050 [Polish] Restyle the "Assign owner (break-glass)" button: use `->icon('heroicon-o-shield-exclamation')` + `->color('danger')` with better label "Emergency: Assign Owner" to distinguish intentional danger-action from error-state appearance
|
|
- [X] T051 [P] [Polish] Add navigation badge counts to Ops sidebar items (Failures, Stuck) showing live counts (e.g. "3" next to Failures, "1" next to Stuck) using `::getNavigationBadge()` + `::getNavigationBadgeColor()`
|
|
- [X] T052 [P] [Polish] Add navigation badge to Recovery > Repair Workspace Owners showing count of ownerless workspaces
|
|
- [X] T053 [Polish] Add "Recent break-glass actions" infolist/table to the Repair Workspace Owners page showing the last 10 audit log entries for `platform.break_glass.*` actions (who, when, what workspace)
|
|
- [X] T054 [P] [Polish] Add a System Console health summary widget to the Dashboard (`app/Filament/System/Pages/Dashboard.php`) showing traffic-light indicator (green/yellow/red) based on failure + stuck counts
|
|
- [X] T055 Run Pint on touched files via `vendor/bin/sail bin pint --dirty --format agent`
|
|
- [X] T056 Run Spec 114 focused tests via `vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/`
|
|
|
|
---
|
|
|
|
## Dependencies & Execution Order
|
|
|
|
```mermaid
|
|
graph TD
|
|
P1[Phase 1: Setup] --> P2[Phase 2: Foundational]
|
|
P2 --> US1[Phase 3: US1 (MVP)]
|
|
P2 --> US2[Phase 4: US2]
|
|
P2 --> US3[Phase 5: US3]
|
|
US1 --> POL[Phase 6: Polish]
|
|
US2 --> POL
|
|
US3 --> POL
|
|
POL --> ENT[Phase 7: Enterprise UI Polish]
|
|
```
|
|
|
|
- Phase 2 blocks all user stories.
|
|
- US2 and US3 can proceed in parallel after Phase 2, but MVP should ship US1 first.
|
|
|
|
---
|
|
|
|
## Parallel Execution Examples
|
|
|
|
### User Story 1
|
|
|
|
- Parallel: T011 + T012 (tests)
|
|
- Parallel: T014 + T015 + T016 (widgets)
|
|
|
|
### User Story 2
|
|
|
|
- Parallel: T021 + T022 (tests)
|
|
- Parallel: T024 + T025 (badge semantics)
|
|
|
|
### User Story 3
|
|
|
|
- Parallel: T031 + T032 + T033 + T034 (tests)
|
|
- Parallel: T035 + T036 + T037 (page scaffolds)
|
|
|
|
---
|
|
|
|
## Implementation Strategy
|
|
|
|
### MVP First (US1 only)
|
|
|
|
1) Complete Phase 1 + Phase 2
|
|
2) Ship US1 (dashboard widgets + global runs + canonical run detail)
|
|
3) Add US2 directory
|
|
4) Add US3 triage pages/actions + access logs
|
|
|
|
---
|
|
|
|
## Acceptance Notes (v1 Scope)
|
|
|
|
- FR-009 Export is explicitly deferred for v1.
|
|
- SR-004 raw error/context drilldowns are intentionally not exposed in v1 run detail views.
|