TenantAtlas/specs/085-tenant-operate-hub/plan.md

# Implementation Plan: Spec 085 — Tenant Operate Hub / Tenant Overview IA

**Branch**: `085-tenant-operate-hub` | **Date**: 2026-02-09 | **Spec**: specs/085-tenant-operate-hub/spec.md
**Input**: specs/085-tenant-operate-hub/spec.md

## Summary

Make central Monitoring pages feel context-aware when entered from the tenant panel, without introducing tenant-scoped monitoring routes and without implicit tenant switching.

Key outcomes:
- Tenant panel sidebar replaces “Operations” with a “Monitoring” group of shortcuts (Runs/Alerts/Audit Log) that open central Monitoring surfaces.
- `/admin/operations` becomes context-aware when tenant context is active: scope label shows tenant, table defaults to tenant filter, and header includes `Back to <tenant>` + `Show all tenants` (clears tenant context).
- `/admin/operations/{run}` adds deterministic “back” affordances: tenant back link when tenant context is active + entitled, plus secondary `Show all operations`; otherwise `Back to Operations`.
- Monitoring page render remains DB-only: no outbound calls and no background work triggered by view-only GET.

## Technical Context

**Language/Version**: PHP 8.4 (Laravel 12)  
**Primary Dependencies**: Filament v5, Livewire v4, Laravel Sail, Tailwind CSS v4  
**Storage**: PostgreSQL (Sail)  
**Testing**: Pest v4 (`vendor/bin/sail artisan test`)  
**Target Platform**: Web (enterprise SaaS admin UI)  
**Project Type**: Laravel monolith (Filament panels + Livewire)  
**Performance Goals**: Monitoring page renders are DB-only, low-latency, and avoid N+1 regressions  
**Constraints**:
- Canonical monitoring URLs must not change (`/admin/operations`, `/admin/operations/{run}`)
- No new tenant-scoped monitoring routes
- No implicit tenant switching (tenant selection remains explicit POST)
- Deny-as-not-found (404) for non-members/non-entitled; 403 only after membership established
- No outbound calls on render; no render-time side effects (jobs/notifications)
**Scale/Scope**: Small-to-medium UX change touching tenant navigation + 2 monitoring pages + Pest tests

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- Inventory-first / snapshots: Not applicable (read-only monitoring UX).
- Read/write separation: PASS (changes are navigation + view-only rendering; the only mutation is explicit “clear tenant context” action).
- Graph contract path: PASS (no new Graph calls).
- Deterministic capabilities: PASS (uses existing membership/entitlement checks; no new capability strings).
- Workspace isolation: PASS (non-member workspace access remains 404).
- Tenant isolation: PASS (no tenant identity leaks when not entitled; tenant pages remain 404).
- Run observability: PASS (view-only pages do not start operations; Monitoring stays DB-only).
- RBAC-UX destructive confirmation: PASS (no destructive actions added).
- Filament UI Action Surface Contract: PASS (we’re modifying Pages; we will provide explicit header actions and table/default filter behavior; no new list resources are added).

## Project Structure

### Documentation (this feature)

```text
specs/085-tenant-operate-hub/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── openapi.yaml
└── tasks.md
```

### Source Code (repository root)

```text
app/
├── Filament/
│   ├── Pages/
│   ├── Resources/
│   └── ...
├── Http/
│   ├── Controllers/
│   └── Middleware/
├── Providers/
└── Support/

resources/views/
tests/Feature/
routes/web.php
```

**Structure Decision**: Laravel monolith with Filament panels. Changes will be localized to existing panel providers, page classes, shared helpers (if present), and feature tests.

## Phase Plan

### Phase 0 — Research (complete)

Outputs:
- specs/085-tenant-operate-hub/research.md (decisions + alternatives)

### Phase 1 — Design & Contracts (complete)

Outputs:
- specs/085-tenant-operate-hub/data-model.md (no schema changes; context rules)
- specs/085-tenant-operate-hub/contracts/openapi.yaml (canonical routes + clear-tenant-context POST)
- specs/085-tenant-operate-hub/quickstart.md (manual verification)

### Phase 2 — Implementation Planning (next)

Implementation will be executed as small, test-driven slices:

1) Tenant panel navigation IA
  - Replace tenant-panel “Operations” entry with “Monitoring” group.
  - Add 3 shortcut items (Runs/Alerts/Audit Log).
  - Verify no new tenant-scoped monitoring routes are introduced.

2) Operations index context-aware header + default scope
  - If tenant context active + entitled: show scope `Tenant — <name>`, default table filter = tenant, CTAs `Back to <tenant>` and `Show all tenants`.
  - If no tenant context: show scope `Workspace — all tenants`.
  - If tenant context active but not entitled: behave workspace-wide (no tenant name, no back-to-tenant).

3) Run detail deterministic back affordances
  - If tenant context active + entitled: `← Back to <tenant>` plus secondary `Show all operations`.
  - Else: `Back to Operations`.

4) Pest tests (security + UX)
  - OperationsIndexScopeTest (tenant vs workspace scope labels + CTAs)
  - RunDetailBackToTenantTest (tenant-context vs no-context actions)
  - Deny-as-not-found coverage for non-entitled tenant pages
  - “No outbound calls on render” guard for `/admin/operations` and `/admin/operations/{run}`

## Complexity Tracking

No constitution violations expected.