ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
875528cd35
TenantAtlas/specs/114-system-console-control-tower/tasks.md
Ahmed Darrazi 875528cd35 feat(114): system console control tower 
Implements Spec 114 System Console Control Tower pages, widgets, triage actions, directory views, and enterprise polish (badges, repair workspace owners table, health indicator).
2026-02-27 17:28:09 +01:00

15 KiB
Raw Blame History

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)

  • 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)
  • T002 [P] Create new System page namespaces for Spec 114 in app/Filament/System/Pages/Directory/ and app/Filament/System/Pages/Security/
  • 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)

  • 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)
  • T005 Update seeded platform operator capabilities in database/seeders/PlatformUserSeeder.php to include the new Spec 114 capabilities
  • T006 Add stuck threshold defaults to config/tenantpilot.php under system_console.stuck_thresholds.{queued_minutes,running_minutes} (used by /system/ops/stuck)
  • T007 [P] Implement a typed time-window helper in app/Support/SystemConsole/SystemConsoleWindow.php (allowed: 1h, 24h default, 7d; provides start timestamp)
  • T008 [P] Implement stuck run classification helper in app/Support/SystemConsole/StuckRunClassifier.php (DB-only query constraints for queued/running + thresholds)
  • 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
  • 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)

  • T011 [P] [US1] Add Control Tower access + window default tests in tests/Feature/System/Spec114/ControlTowerDashboardTest.php
  • 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

  • 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
  • T014 [P] [US1] Create KPIs widget in app/Filament/System/Widgets/ControlTowerKpis.php (DB-only aggregation on operation_runs within selected window)
  • T015 [P] [US1] Create “Top offenders” widget in app/Filament/System/Widgets/ControlTowerTopOffenders.php (group failed runs by tenant/workspace/type within window)
  • 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)
  • T017 [US1] Register Spec 114 widgets on the System dashboard in app/Filament/System/Pages/Dashboard.php (ensure all widget queries are DB-only)
  • 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
  • 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
  • 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)

  • T021 [P] [US2] Add workspaces directory access + listing tests in tests/Feature/System/Spec114/DirectoryWorkspacesTest.php
  • T022 [P] [US2] Add tenants directory access + listing tests in tests/Feature/System/Spec114/DirectoryTenantsTest.php

Implementation

  • 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
  • T024 [P] [US2] Add badge mapping semantics tests in tests/Feature/Badges/SystemHealthBadgeSemanticsTest.php
  • 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)
  • 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)
  • 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)
  • 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
  • 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)
  • 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)

  • T031 [P] [US3] Add failures view access + prefilter tests in tests/Feature/System/Spec114/OpsFailuresViewTest.php
  • T032 [P] [US3] Add stuck view access + stuck classification boundary tests in tests/Feature/System/Spec114/OpsStuckViewTest.php
  • 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)
  • 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

  • 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)
  • 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)
  • 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)
  • 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)
  • 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)
  • 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

  • T041 [P] Run code formatting on touched files via vendor/bin/sail (use vendor/bin/sail bin pint --dirty --format agent)
  • T042 Run Spec 114 focused tests via vendor/bin/sail in tests/Feature/System/Spec114/
  • T043 Validate quickstart steps remain accurate in specs/114-system-console-control-tower/quickstart.md (adjust if needed)
  • 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)
  • 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
  • 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)
  • 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.

  • 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
  • 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
  • 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
  • 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()
  • T052 [P] [Polish] Add navigation badge to Recovery > Repair Workspace Owners showing count of ownerless workspaces
  • 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)
  • 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
  • T055 Run Pint on touched files via vendor/bin/sail bin pint --dirty --format agent
  • T056 Run Spec 114 focused tests via vendor/bin/sail artisan test --compact tests/Feature/System/Spec114/

Dependencies & Execution Order

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.