TenantAtlas/specs/396-system-panel-branding/plan.md

# Implementation Plan: Spec 396 - System Panel Branding and Productization Smoke Config v1

**Branch**: `396-system-panel-branding` | **Date**: 2026-06-21 | **Spec**: [spec.md](/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/396-system-panel-branding/spec.md)
**Input**: Feature specification from `/specs/396-system-panel-branding/spec.md`

## Summary

Productize the existing `/system` Filament panel so platform operators and reviewers see TenantPilot-branded system surfaces, canonical status labels, and deterministic focused browser proof. The implementation must stay narrow: update existing system panel configuration, labels, status vocabulary, and smoke/debug suppression only where required. It must not add system features, persisted entities, Graph calls, migrations, new dashboards, or broad Product Surface Contract enforcement.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52.0
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Laravel Sail 1.x, Pest 4.3.1, Tailwind CSS 4.2.2
**Storage**: PostgreSQL is the application database; this spec requires no schema or storage change
**Testing**: Pest feature tests, Filament/Livewire action tests where touched, Pest Browser focused smoke, Pint for formatting
**Validation Lanes**: fast-feedback for label/status/auth tests, confidence for focused system browser smoke, no broad full-browser-suite gate unless implementation touches shared panel/provider behavior
**Target Platform**: `apps/platform` Laravel application deployed as containerized Dokploy staging/production runtime
**Project Type**: Laravel monolith with Filament admin and system panels plus standalone website outside this scope
**Performance Goals**: No new query-heavy widgets or polling; smoke/helper changes must not add user-visible latency
**Constraints**: No migrations, models, Graph calls, jobs, queues, schedulers, provider framework changes, broad IA redesign, or production smoke-login bypass
**Scale/Scope**: Existing `/system` panel routes only; focused proof of `/system`, `/system/ops/runs`, and one security/repair/control page

## UI / Surface Guardrail Plan

- **Guardrail scope**: Changed operator-facing system panel surfaces and workflow-only browser-smoke guardrail.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - `/system`
  - `/system/login`
  - `/system/ops/runs`
  - `/system/ops/failures`
  - `/system/ops/stuck`
  - `/system/ops/runbooks`
  - `/system/ops/controls`
  - `/system/ops/runs/{run}`
  - `/system/directory/workspaces`
  - `/system/directory/workspaces/{workspace}`
  - `/system/directory/tenants`
  - `/system/directory/tenants/{tenant}`
  - `/system/security/access-logs`
  - `/system/repair-workspace-owners`
  - `apps/platform/app/Providers/Filament/SystemPanelProvider.php`
  - `apps/platform/app/Filament/System/Pages/**`
  - `apps/platform/app/Filament/System/Widgets/**`
  - `apps/platform/app/Support/Badges/Domains/SystemHealthBadge.php`
- **No-impact class, if applicable**: N/A because visible labels and smoke proof are in scope.
- **Native vs custom classification summary**: Native Filament pages, panels, widgets, notifications, and actions. Smoke helper, if required, must be a local/testing-only route helper, not a product UI surface.
- **Shared-family relevance**: Badge/status vocabulary and system smoke/debug-suppression pattern.
- **State layers in scope**: Shell, page, detail, navigation, and local/testing smoke request context.
- **Audience modes in scope**: Support-platform/system operator only.
- **Decision/diagnostic/raw hierarchy plan**: Keep `/system` intentionally technical, but make top-level labels decision-first; keep diagnostics and raw details in their existing technical pages.
- **Raw/support gating plan**: Capability-gated platform panel remains required; no tenant session access.
- **One-primary-action / duplicate-truth control**: Preserve existing page actions; do not add duplicate CTA cards or new dashboards.
- **Handling modes by drift class or surface**: Existing product-surface drift on system branding/status copy is review-mandatory and fixed within this feature. Unrelated full-suite browser noise is report-only unless directly caused by this spec.
- **Repository-signal treatment**: Existing Spec 376/377/395 evidence is context only; completed specs are not rewritten.
- **Special surface test profiles**: Technical Annex, system-admin surface, focused browser smoke, native Filament panel.
- **Required tests or manual smoke**: Feature/status/auth tests, action posture verification for any touched high-impact actions, focused Pest Browser smoke, human product sanity on the system panel.
- **Exception path and spread control**: None planned. Any local/testing-only helper is explicitly not a Product Surface exception if hidden from production navigation and guarded by environment.
- **Active feature PR close-out entry**: Must report Product Surface Impact, UI Surface Impact, no-legacy posture, browser proof, human sanity result, Livewire v4, provider registration, global search, destructive/high-impact actions, asset strategy, and deployment impact.
- **UI/Productization coverage decision**: Durable coverage registry artifacts plus this active spec and implementation report must be updated.
- **Coverage artifacts to update**: `docs/ui-ux-enterprise-audit/route-inventory.md`, `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`, and `specs/396-system-panel-branding/implementation-report.md` during implementation.
- **No-impact rationale**: N/A.
- **Navigation / Filament provider-panel handling**: Provider-panel handling is in scope; registration location must remain `apps/platform/bootstrap/providers.php`.
- **Screenshot or page-report need**: Focused browser proof and screenshots/log evidence are required because this is a visible productization spec.

## Product Surface Contract Plan

- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md` reviewed before preparation.
- **No-legacy posture**: Canonical replacement. Old scaffold/default labels are not preserved as compatibility aliases in active UI.
- **Page archetype and surface budget plan**: System Admin / Technical Annex. The budget is existing system panel surfaces only; no new cards, metrics, navigation groups, or workflows.
- **Technical Annex and deep-link demotion plan**: Existing operations, repair, control, runbook, failure, and stuck-run pages may remain technical. Raw IDs/source keys/payloads stay in existing detail/technical views and are not promoted onto primary system dashboard copy.
- **Canonical status vocabulary plan**:
  - `ok`, healthy equivalents, and `All systems healthy`: `Ready`
  - `warn`, warning equivalents, `Degraded`, and ambiguous attention states: `Needs attention`
  - `critical`: `Critical`
  - operation/control execution states: preserve existing `Blocked`, `Running`, or `Failed` wording only where they already represent OperationRun/control truth
  - `unknown`: `Unknown`
  - Do not introduce a new status family; map existing states to canonical presentation labels.
- **Product Surface exceptions**: None.
- **Browser verification plan**: Focused platform-guard browser smoke for `/system`, `/system/ops/runs`, and one security/repair/control page; assert no debugbar, Vite overlay, exception page, Livewire/Filament console/runtime errors, or default framework branding.
- **Human Product Sanity plan**: Review `/system` and `/system/ops/runs` as a platform operator and record whether visible complexity stayed neutral or decreased.
- **Visible complexity outcome target**: Neutral or decreased.
- **Implementation report target**: `specs/396-system-panel-branding/implementation-report.md`.

## Filament / Livewire / Deployment Posture

- **Livewire v4 compliance**: Livewire 4.1.4 confirmed; no Livewire v3 APIs or references allowed.
- **Panel provider registration location**: Existing Laravel provider registration remains `apps/platform/bootstrap/providers.php`; no provider registration change is planned.
- **Global search posture**: No Filament Resource or global-search behavior is changed. If implementation unexpectedly touches a globally searchable resource, it must either have Edit/View page support or disable global search.
- **Destructive/high-impact action posture**: No new destructive action is planned. Existing break-glass and operational-control actions must retain `->action(...)`, `->requiresConfirmation()`, platform capability checks, and audit logging if touched.
- **Asset strategy**: No new assets by default. Existing panel-only theme asset remains the strategy. `php artisan filament:assets` is not newly required unless implementation registers or changes Filament assets.
- **Testing plan**: Cover status/badge vocabulary, system panel auth/smoke safety, touched high-impact actions, and focused browser smoke through Pest/Pest Browser.
- **Deployment impact**: No env vars, migrations, queues, schedulers, storage, workers, Graph scopes, or Dokploy runtime changes planned.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: Yes, because status vocabulary and smoke/debug suppression are shared patterns.
- **Systems touched**:
  - Filament system panel provider.
  - System pages and widgets.
  - Badge/status rendering.
  - Local/testing browser smoke support if required.
  - Platform auth/capability tests.
- **Shared abstractions reused**:
  - `SystemHealthBadge` / badge-rendering patterns.
  - Existing platform guard and capability policies.
  - Existing smoke/debug-suppression middleware where possible.
  - Existing localization files.
- **New abstraction introduced? why?**: None approved. A local/testing helper route is allowed only if existing Pest Browser platform guard is insufficient for manual in-app proof.
- **Why the existing abstraction was sufficient or insufficient**: Existing panel/pages/widgets already own the visible surfaces; existing badge and localization layers can carry the label changes. Existing browser test evidence proves platform-guard access, so any new smoke helper must justify itself as manual proof support only.
- **Bounded deviation / spread control**: Any smoke helper must be environment-gated, unlinked, platform-guarded, and covered by route safety tests.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: No.
- **Central contract reused**: N/A.
- **Monitoring/deduplication semantics preserved**: Yes. This spec only productizes visible system surfaces and smoke proof.
- **User-facing run state copy changed?**: Only if existing system status labels on operations pages use scaffold/default copy; no OperationRun status semantics change is approved.
- **Required tests**: Existing OperationRun authorization/listing tests continue to pass; no new run lifecycle tests unless implementation touches operation actions.

## Provider Boundary Impact

- **Touches Graph/provider identity or contract boundary?**: No.
- **Provider-specific semantics introduced into platform-core?**: No.
- **Governed-subject taxonomy affected?**: No.
- **Cross-provider readiness or compare strategy affected?**: No.
- **Contract fixtures required?**: No.
- **Boundary note**: This is a system-panel productization and smoke-proof feature, not a provider-readiness or Graph-contract feature.

## Constitution Check

*GATE: Must pass before implementation. Re-check after implementation design.*

- **SPEC-GATE-001**: Passed. Candidate scored 10/12 and is direct user-provided P2 follow-up.
- **Product Surface Contract Gate**: Passed for preparation. The spec states no-legacy posture, Product Surface Impact, UI Surface Impact, archetype, surface budget, Technical Annex stance, canonical status vocabulary, exception posture, browser proof, human sanity target, and implementation-report fields.
- **Completed-spec guardrail**: Passed. Specs 376, 377, 391, and 395 are context only and not reopened.
- **BLOAT-001**: Passed. No new persisted entity, enum/status family, taxonomy/framework, provider abstraction, or cross-domain UI framework is approved.
- **RBAC/Audit**: Passed. Platform guard and capability enforcement remain required. High-impact actions retain confirmation, authorization, and audit.
- **Data isolation**: Passed. No tenant/customer data model change.
- **Test governance**: Passed. Tasks require focused feature/action/browser tests before implementation close-out.
- **Deployment safety**: Passed. No runtime infrastructure change planned.

## Test Governance

- **Tests to add/update**:
  - Status/badge vocabulary tests for canonical system labels.
  - System panel auth/smoke helper safety tests if a helper is added.
  - Focused Pest Browser smoke for `/system`, `/system/ops/runs`, and one system security/repair/control page.
  - Action posture tests or reflection assertions if high-impact actions are touched.
  - `/admin` regression smoke only if a shared provider/config change can affect the tenant admin panel.
- **Commands expected during implementation**:
  - `cd apps/platform && ./vendor/bin/sail artisan test --filter=SystemHealthBadgeSemanticsTest`
  - `cd apps/platform && ./vendor/bin/sail artisan test --filter=SystemPanelAuthTest`
  - `cd apps/platform && ./vendor/bin/sail artisan test --filter=Spec396`
  - `cd apps/platform && ./vendor/bin/sail pint --dirty`
  - Browser command to follow the repo's Pest Browser setup for focused Spec 396 proof.
- **No verification scripts**: Do not add ad hoc verification scripts when Pest/Pest Browser tests can prove the behavior.

## Project Structure

### Documentation (this feature)

```text
specs/396-system-panel-branding/
├── spec.md
├── plan.md
├── tasks.md
├── checklists/
│   └── requirements.md
└── implementation-report.md   # created during implementation
```

### Source Code (repository root)

```text
apps/platform/
├── app/
│   ├── Filament/
│   │   └── System/
│   │       ├── Pages/
│   │       │   ├── Auth/Login.php
│   │       │   ├── Dashboard.php
│   │       │   ├── Directory/
│   │       │   ├── Ops/
│   │       │   ├── RepairWorkspaceOwners.php
│   │       │   └── Security/
│   │       └── Widgets/
│   ├── Http/Middleware/SuppressDebugbarForSmokeRequests.php
│   ├── Providers/Filament/SystemPanelProvider.php
│   └── Support/Badges/Domains/SystemHealthBadge.php
├── lang/
│   ├── de/localization.php
│   └── en/localization.php
├── routes/web.php
└── tests/
    ├── Browser/
    └── Feature/
```

**Structure Decision**: Use existing `apps/platform` Filament, localization, badge, route, middleware, and Pest/Pest Browser structure. No new base folders are approved.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | N/A | N/A |

## Proportionality Review

- **Current operator problem**: `/system` can still expose default/scaffold-like branding and inconsistent health labels, and focused manual browser smoke is not deterministic enough for productization review.
- **Existing structure is insufficient because**: Labels and smoke proof are spread across provider config, localization, widgets, badge mapping, and existing browser fixtures. They need coordinated preparation, but not new product infrastructure.
- **Narrowest correct implementation**: Update existing copy/mapping/config/tests and add only focused smoke support if existing platform-guard browser proof cannot serve manual sanity.
- **Ownership cost created**: A few focused tests and an implementation report. No schema, model, enum family, provider contract, or new UI framework cost.
- **Alternative intentionally rejected**: Full `/system` redesign or new system dashboard cards, because the current problem is productization and proof, not missing capability.
- **Release truth**: Current-release follow-up from completed productization and gate specs.

## Implementation Phases

### Phase 1 - Inventory And Contract Lock

Inventory every visible system label/status/action in scope and record the exact current surfaces. Confirm no completed spec artifacts need rewriting.

### Phase 2 - Tests First

Add or update focused tests for canonical status vocabulary, system auth/smoke safety, action posture, and browser proof before or alongside behavior changes.

### Phase 3 - Productized System Branding

Apply TenantPilot system branding through existing provider/localization/page paths. Keep the technical system-admin character but remove default or ambiguous visible copy.

### Phase 4 - Canonical Status Vocabulary

Map existing system health/status states to canonical labels through existing badge/widget/localization paths.

### Phase 5 - Smoke And Debug-Safe Proof

Reuse the existing platform-guard browser path where possible. Add a local/testing-only smoke helper only if required for manual in-app sanity, with route safety coverage.

### Phase 6 - Close-Out Evidence

Run focused tests, capture browser proof, complete `implementation-report.md`, and document deployment impact as none unless implementation changes assets.

## Risk And Rollback Plan

- **Rollback**: Revert label/config/test changes in the feature branch. No database rollback is required.
- **Staging validation**: Run focused test lane and browser smoke before production promotion.
- **Production risk**: Low if no smoke helper is exposed outside local/testing and no shared provider config changes affect `/admin`.
- **Forward fix path**: If shared branding affects `/admin`, add a focused `/admin` regression fix and proof within this spec before close-out.