240 lines
21 KiB
Markdown
240 lines
21 KiB
Markdown
# Implementation Plan: Spec 418 - Coverage v2 Operator Surface
|
|
|
|
**Branch**: `418-coverage-v2-operator-surface` | **Date**: 2026-06-26 | **Spec**: `specs/418-coverage-v2-operator-surface/spec.md`
|
|
**Input**: Feature specification from `/specs/418-coverage-v2-operator-surface/spec.md`
|
|
|
|
## Summary
|
|
|
|
Add one internal Coverage v2 Readiness surface for operators to inspect activation readiness without activating customer-facing proof. The implementation should build a thin DB-only read model over existing Coverage v2 resource types, supported scopes, resources, evidence, identity state, provider connection provenance, and Claim Guard state; then render it with Filament-native summary, tables, filters, badges, and disclosed diagnostics. It must remain read-only, no-legacy, no-raw-payload, no-remote-render, workspace/environment/provider-scoped, and browser-proven.
|
|
|
|
## Technical Context
|
|
|
|
**Language/Version**: PHP 8.4.x, Laravel 12.x
|
|
**Primary Dependencies**: Filament v5, Livewire v4, existing TenantConfiguration models/services, existing RBAC/capability helpers, existing OperationRun link helper
|
|
**Storage**: PostgreSQL via existing Coverage v2 tables. No new persisted summary table by default.
|
|
**Testing**: Pest 4 / PHPUnit 12 via Sail
|
|
**Validation Lanes**: fast-feedback, confidence, browser; pgsql only if indexes/constraints/migrations change
|
|
**Target Platform**: Laravel Sail locally, Dokploy/container deployment for staging/production
|
|
**Project Type**: Laravel monolith under `apps/platform`
|
|
**Performance Goals**: page render is DB-only, bounded queries, no remote calls, paginated/filterable tables
|
|
**Constraints**: read-only; no Graph/TCM/provider calls during render; no customer proof; no raw payloads; no v1/v2 adapter; no `tenant_id` ownership; no start/capture/restore/report actions
|
|
**Scale/Scope**: initial Coverage v2 registry and captured resources from Specs 414, 415, and 417; future customer/cutover work is separate
|
|
|
|
## UI / Surface Guardrail Plan
|
|
|
|
- **Guardrail scope**: new rendered operator surface.
|
|
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**: Coverage v2 Readiness page at `/admin/tenant-configuration/coverage-v2` or repo-equivalent; admin panel page registration/navigation; summary/widgets/tables/diagnostics; workspace/environment/provider filter state.
|
|
- **No-impact class, if applicable**: N/A.
|
|
- **Native vs custom classification summary**: Native Surface. Use Filament-native page/table/widget/infolist/section/action slide-over primitives where possible.
|
|
- **Shared-family relevance**: navigation, status messaging, evidence diagnostics, OperationRun links, provider provenance.
|
|
- **State layers in scope**: page, query/filter, table, read-only inspect/disclosure detail. No shell rewrite.
|
|
- **Audience modes in scope**: operator/MSP and support/platform diagnostics. Customer/read-only output is explicitly out of scope.
|
|
- **Decision/diagnostic/raw hierarchy plan**: readiness summary and critical v2 states visible first; diagnostics disclosed second; raw/support evidence hidden and not added unless existing safe route already exists.
|
|
- **Raw/support gating plan**: raw payloads, normalized payloads, permission context raw JSON, secrets, and provider response dumps are never displayed.
|
|
- **One-primary-action / duplicate-truth control**: one dominant action is inspect/open read-only detail. No export/capture/start/publish action. Avoid duplicate blocker summaries.
|
|
- **Handling modes by drift class or surface**: hard-stop if customer output, remote work, raw payload display, v1 adapter, old labels, or mutations appear.
|
|
- **Repository-signal treatment**: review-mandatory for route/navigation/UI registry updates; exception-required for Product Surface two-table Technical Annex budget.
|
|
- **Special surface test profiles**: standard-native-filament plus focused browser smoke.
|
|
- **Required tests or manual smoke**: unit read model/mappers, feature auth/redaction/no-legacy/no-remote/scope, browser smoke.
|
|
- **Exception path and spread control**: one Product Surface exception for two native tables on an internal Technical Annex page. No broad UI framework exception.
|
|
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
|
|
- **UI/Productization coverage decision**: reachable UI added. Update `docs/ui-ux-enterprise-audit/route-inventory.md` and `docs/ui-ux-enterprise-audit/design-coverage-matrix.md`, or document a bounded registry exception.
|
|
- **Coverage artifacts to update**: route inventory and design coverage matrix expected.
|
|
- **List surface review**: apply `docs/product/standards/list-surface-review-checklist.md` for the new Read-only Registry / Report tables and record the result in the implementation report.
|
|
- **No-impact rationale**: N/A.
|
|
- **Navigation / Filament provider-panel handling**: register the page in the admin panel; any navigation entry must be secondary and must not dominate primary navigation. Provider registration remains `apps/platform/bootstrap/providers.php`.
|
|
- **Screenshot or page-report need**: no full page report required unless implementation adds custom layout or deviates from native Filament. Focused browser proof is required.
|
|
|
|
## Product Surface Contract Plan
|
|
|
|
- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md`.
|
|
- **No-legacy posture**: canonical Coverage v2 internal readiness; no compatibility exception.
|
|
- **Page archetype and surface budget plan**: Technical Annex Page / Read-only Registry Report. Surface budget exception for two native tables is documented because registry support and concrete instance evidence must be visible together for internal cutover readiness.
|
|
- **Technical Annex and deep-link demotion plan**: OperationRun links, evidence hashes, source metadata, source contract state, identity diagnostics, and provider provenance are secondary diagnostics. Raw payloads and raw provider output forbidden.
|
|
- **Canonical status vocabulary plan**: top-level readiness uses `Ready`, `Needs attention`, `Blocked`, `Unknown`; existing Coverage v2 enum values display as internal diagnostic dimensions with internal/operator labels.
|
|
- **Product Surface exceptions**: one Product Surface Contract Technical Annex surface-budget exception for summary plus two native tables; no customer-facing exception. UI-EX-001 implementation exception is `none` if the surface remains native Filament. If custom UI becomes necessary, implementation must stop and name a catalogued UI-EX-001 exception type before proceeding.
|
|
- **Browser verification plan**: focused route smoke, visible required labels, hidden forbidden labels/raw payloads, primary-link inspect slide-over, no console/Livewire/Filament errors, and no remote network calls.
|
|
- **Human Product Sanity plan**: implementation report answers the six Spec 418 questions.
|
|
- **Visible complexity outcome target**: neutral to reduced.
|
|
- **Implementation report target**: `specs/418-coverage-v2-operator-surface/implementation-report.md`.
|
|
|
|
## Filament / Livewire / Deployment Posture
|
|
|
|
- **Livewire v4 compliance**: Livewire v4.x confirmed. Do not introduce Livewire v3 APIs.
|
|
- **Panel provider registration location**: Laravel 12 panel providers remain registered in `apps/platform/bootstrap/providers.php`; page registration belongs in `apps/platform/app/Providers/Filament/AdminPanelProvider.php` or repo-equivalent admin panel page discovery.
|
|
- **Global search posture**: no Filament Resource should be globally searchable for this surface. If a Resource is created instead of a Page, global search must be disabled unless safe View/Edit posture exists.
|
|
- **Destructive/high-impact action posture**: none. If implementation wants any start/capture/re-evaluate/export/publish/restore action, stop and amend spec/plan/tasks or split a new spec.
|
|
- **Asset strategy**: no new assets expected; `filament:assets` not required unless implementation registers Filament assets.
|
|
- **Testing plan**: Livewire/feature tests for page authorization/render if page is a Livewire component; unit tests for read model and display mapping; browser smoke for rendered route.
|
|
- **Deployment impact**: no env vars, queues, scheduler, storage, or assets by default. Migrations only if narrow indexes are added. No queue worker change because no operations start.
|
|
|
|
## Shared Pattern & System Fit
|
|
|
|
- **Cross-cutting feature marker**: yes.
|
|
- **Systems touched**: `TenantConfigurationResourceType`, `TenantConfigurationSupportedScope`, `TenantConfigurationResource`, `TenantConfigurationResourceEvidence`, `ClaimGuard`, `OperationRunLinks`, ProviderConnection scope, admin panel registration, UI audit registry, tests.
|
|
- **Shared abstractions reused**: existing Coverage v2 models/enums/services; existing OperationRun URL helper; existing workspace/environment/provider scope helpers; existing RBAC capability resolver/policies; `BadgeCatalog`/`BadgeRenderer` for status-like badges.
|
|
- **New abstraction introduced? why?**: one thin read model/query service and possibly a non-status display mapper. It is needed to centralize DB-only aggregate logic, blocker grouping, redaction, and no-legacy text display for tests. Status-like rendered badges must use a central BadgeDomain mapping, not page-local status semantics.
|
|
- **Why the existing abstraction was sufficient or insufficient**: Existing kernel/capture/identity services own truth but do not provide an operator-ready read model. Existing Evidence Overview/Inventory Coverage pages are v1/customer-adjacent surfaces and must not become v2 dual truth.
|
|
- **Bounded deviation / spread control**: no new persisted read model, no UI framework, no new state family, no customer output. Keep new support under TenantConfiguration or Filament page-local namespaces.
|
|
|
|
## OperationRun UX Impact
|
|
|
|
- **Touches OperationRun start/completion/link UX?**: diagnostic links only.
|
|
- **Central contract reused**: `OperationRunLinks` or current canonical helper.
|
|
- **Delegated UX behaviors**: URL resolution and authorization only; no queued toast, artifact link, run-enqueued browser event, queued DB notification, or dedupe messaging.
|
|
- **Surface-owned behavior kept local**: secondary diagnostic link visibility only.
|
|
- **Queued DB-notification policy**: N/A.
|
|
- **Terminal notification path**: N/A.
|
|
- **Exception path**: none.
|
|
|
|
## Provider Boundary & Portability Fit
|
|
|
|
- **Shared provider/platform boundary touched?**: yes.
|
|
- **Provider-owned seams**: provider connection provenance, source contract metadata, Graph fallback, beta experimental source class, external provider identifiers if ever disclosed.
|
|
- **Platform-core seams**: workspace/managed-environment/provider_connection ownership, resource type, supported scope, readiness summary, coverage/evidence/identity/claim states.
|
|
- **Neutral platform terms / contracts preserved**: provider connection, managed environment, supported scope, source class, activation blocker, readiness.
|
|
- **Retained provider-specific semantics and why**: Graph/TCM labels appear only as source class or safe metadata because the initial resource types are Intune-backed.
|
|
- **Bounded extraction or follow-up path**: document-in-feature if any provider-specific display is retained; no new provider framework.
|
|
|
|
## Constitution Check
|
|
|
|
- Inventory/evidence truth: PASS. Uses existing Coverage v2 resource/evidence truth, no legacy snapshot promotion.
|
|
- Read/write separation: PASS. Read-only surface; no mutation actions.
|
|
- Graph contract path: PASS. No new Graph calls and no render-time provider calls.
|
|
- Deterministic capabilities: PASS with implementation validation for selected view capability.
|
|
- RBAC-UX: PASS with required 404/403 tests and server-side page authorization.
|
|
- Workspace isolation: PASS with required workspace/environment/provider scope tests.
|
|
- OperationRun: PASS. Diagnostic links only; no OperationRun as default proof.
|
|
- Evidence/currentness: PASS. Evidence hash allowed; raw evidence hidden; no fallback-to-latest proof.
|
|
- Customer output: PASS. No customer output, Review Pack, report, restore readiness, or customer-ready wording.
|
|
- Provider boundary: PASS with provider IDs hidden/default metadata-only.
|
|
- Product Surface: PASS with one documented Product Surface Contract Technical Annex surface-budget exception. UI-EX-001 implementation exception remains `none` if the surface is native Filament.
|
|
- Test governance: PASS. Unit/feature/browser lanes named; no broad heavy family.
|
|
- Proportionality: PASS. Thin derived read model is justified; persisted summary disallowed.
|
|
- No premature abstraction: PASS. Do not introduce UI framework or broad presenter.
|
|
- Persisted truth: PASS. No new persisted summary by default.
|
|
- Behavioral state: PASS. Uses existing v2 state families.
|
|
- No legacy / pre-production lean: PASS. No adapters, fallback readers, dual writes, old labels, or `tenant_id`.
|
|
|
|
## Test Governance Check
|
|
|
|
- **Test purpose / classification by changed surface**: Unit for read model and display mapping; Feature for authorization, rendered content, redaction, no-legacy, no-remote, and scope; Browser for Product Surface smoke.
|
|
- **Affected validation lanes**: fast-feedback, confidence, browser; pgsql only for indexes/migrations.
|
|
- **Why this lane mix is the narrowest sufficient proof**: Unit tests prove computed readiness; feature tests prove security/render boundaries; browser proves the actual Filament/Livewire surface.
|
|
- **Narrowest proving command(s)**:
|
|
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/TenantConfiguration/CoverageV2ReadinessSummaryTest.php tests/Unit/Support/TenantConfiguration/CoverageV2ActivationBlockerGroupingTest.php tests/Unit/Support/TenantConfiguration/CoverageV2ClaimGuardDisplayMapperTest.php`
|
|
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceTest.php tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceAuthorizationTest.php tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceNoLegacyLabelsTest.php tests/Feature/TenantConfiguration/Spec418CoverageV2OperatorSurfaceRedactionTest.php`
|
|
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser/Spec418CoverageV2OperatorSurfaceSmokeTest.php`
|
|
- **Fixture / helper / factory / seed / context cost risks**: keep Spec 418 fixtures local or opt-in; do not broaden default TenantConfiguration/browser factories.
|
|
- **Expensive defaults or shared helper growth introduced?**: no expected default broadening.
|
|
- **Heavy-family additions, promotions, or visibility changes**: none.
|
|
- **Surface-class relief / special coverage rule**: standard-native-filament relief for layout; focused browser still required.
|
|
- **Closing validation and reviewer handoff**: implementation report must record exact commands/results, browser proof, Product Surface exception, and any unrelated failures.
|
|
- **Budget / baseline / trend follow-up**: none expected; document if browser fixture or feature lane cost expands materially.
|
|
- **Review-stop questions**: lane fit, hidden fixture cost, no remote render, redaction, old labels absent, customer claims absent, no `tenant_id`.
|
|
- **Escalation path**: document-in-feature for contained exception; follow-up-spec only if structural persistence or broad governance tests are required.
|
|
- **Active feature PR close-out entry**: Guardrail / Exception / Smoke Coverage.
|
|
- **Why no dedicated follow-up spec is needed**: this is the bounded operator-readiness surface; customer/cutover actions are already deferred.
|
|
|
|
## Project Structure
|
|
|
|
### Documentation (this feature)
|
|
|
|
```text
|
|
specs/418-coverage-v2-operator-surface/
|
|
├── spec.md
|
|
├── plan.md
|
|
├── tasks.md
|
|
├── implementation-report.md
|
|
└── checklists/
|
|
└── requirements.md
|
|
```
|
|
|
|
### Source Code (likely affected in later implementation)
|
|
|
|
```text
|
|
apps/platform/app/
|
|
├── Filament/
|
|
│ ├── Pages/TenantConfiguration/
|
|
│ │ └── CoverageV2Readiness.php
|
|
│ └── Widgets/TenantConfiguration/
|
|
│ ├── CoverageV2ActivationBlockersWidget.php
|
|
│ ├── CoverageV2ReadinessSummaryWidget.php
|
|
│ ├── CoverageV2ResourceInstancesTable.php
|
|
│ └── CoverageV2ResourceTypesTable.php
|
|
├── Providers/Filament/
|
|
│ └── AdminPanelProvider.php
|
|
├── Services/TenantConfiguration/
|
|
│ └── CoverageV2ReadinessReadModel.php
|
|
└── Support/TenantConfiguration/
|
|
└── CoverageV2ClaimGuardDisplayMapper.php
|
|
|
|
apps/platform/resources/views/filament/pages/tenant-configuration/
|
|
└── coverage-v2-readiness.blade.php
|
|
|
|
apps/platform/tests/
|
|
├── Unit/Support/TenantConfiguration/
|
|
├── Feature/TenantConfiguration/
|
|
└── Browser/
|
|
|
|
docs/ui-ux-enterprise-audit/
|
|
├── route-inventory.md
|
|
└── design-coverage-matrix.md
|
|
```
|
|
|
|
**Structure Decision**: Use repo-equivalent names if implementation finds a closer existing TenantConfiguration namespace. Keep the read model/service thin and DB-only. If a single Filament page with table widgets is not the best native pattern, implementation may use an equivalent native Filament page/resource-page structure while preserving the route and Product Surface contract.
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 0 - Preflight
|
|
|
|
Capture branch, HEAD, dirty state, activated skills, candidate gate, completed dependency reports, current Coverage v2 model/service names, and hard-gate stop conditions.
|
|
|
|
### Phase 1 - Inspect Existing Coverage v2 Read Paths
|
|
|
|
Inspect resource type registry, supported scopes, resources, evidence, identity states, Claim Guard, provider connection scope, OperationRun links, authorization helpers, existing Filament pages, and browser fixture patterns. Produce a dependency map in the implementation report.
|
|
|
|
### Phase 2 - Product Surface Contract Design
|
|
|
|
Lock route, surface role, surface type, native/custom classification, primary operator question, default-visible truth, diagnostics boundary, raw evidence boundary, action model, browser proof criteria, and Human Product Sanity criteria before runtime UI edits.
|
|
|
|
### Phase 3 - DB-Only Read Model
|
|
|
|
Create the derived read model/query service for readiness summary, resource type table, resource instance table, activation blockers, source class counts, and claim state counts. No remote calls, no persisted summary table.
|
|
|
|
### Phase 4 - Filament Native Surface
|
|
|
|
Add the read-only admin surface with scope summary, readiness summary, resource type table, resource instance table, activation blockers, diagnostics disclosure, empty states, filters, and one inspect model. Update admin panel/page registration and secondary navigation only if appropriate.
|
|
|
|
### Phase 5 - Authorization And Scope
|
|
|
|
Enforce workspace membership, managed environment entitlement, selected view capability, provider connection same-scope filtering, and 404/403 semantics.
|
|
|
|
### Phase 6 - Redaction, No-Remote, And No-Legacy Guards
|
|
|
|
Hide raw/normalized payloads, permission context raw JSON, secrets, raw provider details, old gap labels, customer claims, and unscoped 100% claims. Prove render path is DB-only.
|
|
|
|
### Phase 7 - Tests And Browser Smoke
|
|
|
|
Add focused unit, feature, and browser tests. Keep fixtures narrow and explicit. Run Pint dirty, focused tests, browser smoke, and `git diff --check`.
|
|
|
|
### Phase 8 - Implementation Report
|
|
|
|
Write `implementation-report.md` with candidate gate, dirty state before/after, files changed, route, Product Surface classification, UI Action Matrix, browser proof, Human Product Sanity, authorization proof, redaction proof, no remote render proof, no-tenant_id confirmation, no-legacy/no-dual-truth confirmation, tests, deployment impact, and deferred work.
|
|
|
|
## Complexity Tracking
|
|
|
|
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
|
|---|---|---|
|
|
| Thin read model/display mapper | Operators need one safe readiness answer from several existing v2 tables and services | Direct DB inspection or implementation reports lack RBAC/redaction/browser proof and cannot support Product Surface checks |
|
|
| Product Surface Contract Technical Annex surface-budget exception | Registry support and concrete instance evidence both block activation and must be visible together | A one-table page hides either denominator readiness or concrete capture/identity/claim blockers |
|
|
|
|
## Proportionality Review
|
|
|
|
- **Current operator problem**: v2 readiness cannot be verified safely from one product surface.
|
|
- **Existing structure is insufficient because**: Specs 414/415/417 created truth but no operator inspection path.
|
|
- **Narrowest correct implementation**: one derived DB-only read model and one read-only Filament-native surface.
|
|
- **Ownership cost created**: tests, central badge/status mapping, any non-status display mapping, browser smoke, UI registry updates, list-surface checklist close-out, and Product Surface close-out must be maintained as Coverage v2 evolves.
|
|
- **Alternative intentionally rejected**: add v2 sections to customer-facing or existing v1 surfaces. Rejected because that creates dual truth and premature customer activation.
|
|
- **Release truth**: current-release internal readiness inspection; future activation deferred.
|