ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/355-platform-sellable-smoke-matrix/plan.md
ahmido f35782a163 feat: platform sellable smoke matrix (spec 355) (#426) 
Added artifacts, screenshots, and documentation for the platform sellable smoke matrix. Fixed a bug in FindingRiskGovernanceResolver and updated related tests.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #426
2026-06-05 10:42:31 +00:00

15 KiB
Raw Permalink Blame History

Implementation Plan: Spec 355 - Platform Sellable Smoke Matrix

  • Branch: 355-platform-sellable-smoke-matrix
  • Date: 2026-06-05
  • Spec: specs/355-platform-sellable-smoke-matrix/spec.md
  • Input: Spec 355 draft plus repo inspection of dashboard, provider readiness, review output, accepted-risk, governance, evidence, and operations proof surfaces.

Summary

Run one bounded, browser-first sellable-readiness gate across the current operator/productization surfaces and capture the result as a matrix plus readiness report.

The slice stays narrow:

  • verify existing owner surfaces end-to-end instead of building another feature
  • inventory fixture truth before claiming anything is testable
  • classify flows as pass, pass with notes, blocked, fail P1, or fail P0
  • allow only direct P0/P1 fixes on the owning surface when a browser-verified issue is in scope
  • preserve current RBAC, audit, OperationRun, provider-boundary, and customer-safe truth

Technical Context

  • Language/Version: PHP 8.4.15, Laravel 12.52.x
  • UI stack: Filament 5.2.x, Livewire 4.x
  • Database: PostgreSQL, no schema change planned
  • Artifact storage: markdown and screenshots under specs/355-platform-sellable-smoke-matrix/artifacts/
  • Testing: browser-first verification plus targeted Pest unit/feature/browser coverage only when a direct P0/P1 fix is necessary
  • Validation lanes: browser + confidence + fast-feedback
  • Local runtime posture: Sail-first
  • Deployment/runtime impact: none expected; no env, migration, queue-family, scheduler, storage, or panel/provider change is planned
  • Global search: unchanged; Spec 355 does not make any surface globally searchable

Current Repo Truth That Constrains The Slice

  • The primary product surfaces already exist and are route-inventory-backed:
    • Environment Dashboard (UI-011, page report ui-002-environment-dashboard.md)
    • Provider Connections (UI-072, page report ui-009-provider-connections.md)
    • Required Permissions (UI-077, page report ui-077-required-permissions.md)
    • Governance Inbox (UI-028, page report ui-004-governance-inbox.md)
    • Finding Exceptions Queue (UI-026, page report ui-012-finding-exceptions-queue.md)
    • Exception Detail (UI-036, page report ui-036-exception-detail.md)
    • Customer Review Workspace (UI-038, page report ui-006-customer-review-workspace.md)
    • Environment Review Detail (UI-040, page report ui-040-environment-review-detail.md)
    • Operations hub (UI-016, page report ui-003-operations.md)
    • Evidence Overview (UI-044, route-inventory only today)
    • workspace operation detail (UI-017, route-inventory only today)
  • Existing browser smoke coverage already exists in the repo for:
    • Governance Inbox (Spec346...SmokeTest)
    • review-output guidance (Spec351...SmokeTest)
    • dashboard guidance (Spec352...SmokeTest)
    • provider-readiness guidance (Spec353...SmokeTest)
    • accepted-risk guidance (Spec354...SmokeTest)
  • Current dependency signals are not perfectly normalized:
    • Spec 351 is commit-backed and implemented, but still carries residual P2 browser audit notes and a Draft spec header.
    • Spec 352 is the cleanest implemented baseline.
    • Spec 353 is marked implemented with close-out audit pending.
    • Spec 354 is commit-backed and screenshot-backed, but still lacks the cleanest spec-package close-out shape.
  • Existing local/testing helpers already exist for some states:
    • local smoke login route: admin.local.smoke-login
    • review-output ready-path fixture command: tenantpilot:review-output:seed-browser-fixture
  • Evidence Overview and workspace operation detail have lighter durable audit coverage than the other strategic surfaces. Spec 355 should use its own artifact package first instead of broadening the audit registry by default.

Domain / Model Implications

  • No schema or migration change is planned.
  • No new persisted readiness classification, queue, or release-gate entity is allowed.
  • Existing truth stays on the current runtime owners:
    • environment guidance: EnvironmentDashboardSummaryBuilder
    • provider readiness: existing provider-connection and required-permissions derivation paths
    • review output: existing review-output readiness and resolve-action paths
    • accepted risk: existing finding-exception and governance resolver paths
    • evidence: existing evidence snapshot/evidence overview truth
    • proof: existing OperationRun hub and detail truth
  • New durable artifacts are limited to:
    • artifacts/platform-sellable-smoke-matrix.md
    • artifacts/platform-sellable-readiness-report.md
    • optional artifacts/blocked-fixtures.md
    • screenshots under artifacts/screenshots/

UI / Filament / Livewire Implications

  • Filament v5 continues to run on Livewire v4.x; no version or API drift is permitted.
  • No panel/provider registration change is allowed; apps/platform/bootstrap/providers.php remains untouched.
  • No new asset registration is planned, so there is no expected filament:assets deployment change for this spec.
  • Existing destructive or high-impact actions must keep their current confirmation, authorization, notification, and audit posture even if Spec 355 changes their prominence, disabled state, or label.
  • Spec 355 must not create a second CTA rail on detail surfaces simply to make a smoke matrix easier to pass.

RBAC / Policy Implications

  • Workspace membership and entitled environment access remain the only scope authorities.
  • Guidance, filters, and deep links must remain scope-safe and must not reintroduce hidden tenant query dependence where Specs 313/315/316 already constrained hub filtering behavior.
  • Any direct fix must preserve current 404 vs 403 semantics and current policy ownership.
  • The smoke matrix itself must classify wrong-scope or wrong-workspace continuity as a blocker, not as cosmetic drift.

Audit / Logging / Evidence Implications

  • Existing audit, OperationRun, and proof ownership remain authoritative.
  • The readiness report must explicitly state whether:
    • console errors were observed
    • network/server errors were observed
    • customer-safe boundaries were upheld
  • No new audit stream, notification family, or support artifact is planned.
  • Browser screenshots and matrix/report notes are the close-out evidence for this gate.

Data / Migration Implications

  • No database migration, backfill, or persisted projection is planned.
  • No compatibility shims are justified because this is a verification/productization gate, not a data-shape replacement.
  • Existing local/testing fixture helpers may be reused, but Spec 355 must not add new product persistence just to make demo data easier.

Rollout Considerations

  • No feature flag is expected because this slice is a verification gate over existing surfaces.
  • If no P0/P1 fix is required, rollout impact is documentation/artifact-only.
  • If a direct P0/P1 fix is required, staging/browser proof should re-run the affected flow before the platform is called sellable-ready.
  • The final report must clearly distinguish:
    • ready/pass flows
    • pass-with-notes flows
    • blocked flows caused by fixture or dependency gaps
    • failure flows caused by real operator or safety issues

UI / Surface Guardrail Plan

  • Guardrail scope:
    • Environment Dashboard
    • Provider Connections / Required Permissions
    • Customer Review Workspace / Environment Review Detail
    • Finding Exceptions Queue / Exception Detail
    • Governance Inbox
    • Evidence Overview / Evidence basis
    • Operations hub / operation proof
  • Affected surfaces:
    • apps/platform/app/Filament/Pages/EnvironmentDashboard.php
    • apps/platform/app/Filament/Resources/ProviderConnectionResource.php
    • apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php
    • apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
    • apps/platform/app/Filament/Resources/EnvironmentReviewResource/Pages/ViewEnvironmentReview.php
    • apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php
    • apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php
    • apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php
    • apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
    • apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
    • apps/platform/app/Filament/Resources/OperationRunResource.php
  • Native vs custom: preserve current Filament-native surfaces and shared guidance/proof helpers; do not introduce a custom sellable-readiness runtime layer
  • Shared-family relevance:
    • next-action guidance
    • proof/deep-link behavior
    • customer-safe disclosure
    • queue routing
    • dashboard signal hierarchy
  • Handling modes:
    • strategic operator surfaces: review-mandatory
    • missing fixture states: report-only
    • direct P0/P1 regressions: hard-stop-candidate
    • out-of-scope structural drift: exception-required or follow-up-spec
  • Required tests / smoke:
    • browser matrix is mandatory
    • targeted feature/unit/browser coverage only when a direct fix lands
  • UI/Productization coverage:
    • use existing page reports where they already exist
    • keep Spec 355 artifacts as the primary proof package
    • use unresolved-pages.md only if Evidence Overview or operation detail needs an explicit durable blocker note after a fix attempt

Shared Pattern And System Fit

  • Preferred reuse path:
    • current ResolutionCase / ResolutionAction contract
    • current dashboard operator-guidance path
    • current Governance Inbox deep-link/routing path
    • current OperationRunUrl / OperationRunLinks
  • Likely implementation shape:
    • no new product runtime layer
    • matrix/report/screenshot artifacts only
    • if needed, direct surface-local fixes that reuse existing guidance or link helpers
  • Avoid:
    • new cross-surface guidance registry
    • new sellability status persistence
    • new portal/readiness workflow
    • new provider/platform abstraction

OperationRun UX Impact

Spec 355 does not create a new OperationRun type and does not introduce new queued/start behavior.

Implementation responsibility is limited to:

  • verifying existing Open operation / View run links
  • ensuring proof links do not become the dominant CTA when a higher-priority owner action exists
  • ensuring scope-safe operation URLs remain truthful

Likely Runtime Files

Area Repo-real files
Dashboard apps/platform/app/Filament/Pages/EnvironmentDashboard.php, apps/platform/app/Support/EnvironmentDashboard/EnvironmentDashboardSummaryBuilder.php
Provider readiness apps/platform/app/Filament/Resources/ProviderConnectionResource.php, apps/platform/app/Filament/Pages/EnvironmentRequiredPermissions.php, provider-readiness support classes
Review output apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php, apps/platform/app/Filament/Resources/EnvironmentReviewResource.php, review-output guidance support classes
Accepted risk apps/platform/app/Filament/Pages/Monitoring/FindingExceptionsQueue.php, apps/platform/app/Filament/Resources/FindingExceptionResource/Pages/ViewFindingException.php, apps/platform/app/Services/Findings/FindingRiskGovernanceResolver.php
Governance queue apps/platform/app/Filament/Pages/Governance/GovernanceInbox.php, apps/platform/app/Support/GovernanceInbox/GovernanceInboxSectionBuilder.php
Evidence apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php, apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
Operations proof apps/platform/app/Filament/Resources/OperationRunResource.php, apps/platform/app/Support/OpsUx/OperationRunUrl.php, apps/platform/app/Support/OperationRunLinks.php
Smoke helpers apps/platform/routes/web.php, apps/platform/app/Console/Commands/SeedReviewOutputBrowserFixture.php, existing browser smoke tests

Likely Test Files

Layer Planned file or reuse path
Browser apps/platform/tests/Browser/Spec355PlatformSellableSmokeMatrixSmokeTest.php only if a durable automated smoke adds value during implementation
Feature/Livewire targeted regressions on existing Spec 351/352/353/354 or owner-surface tests only when a direct fix lands
Unit none expected unless a direct P0/P1 fix changes deterministic guidance/link selection

Likely Artifact Files

Artifact Purpose
specs/355-platform-sellable-smoke-matrix/artifacts/platform-sellable-smoke-matrix.md primary browser verification matrix
specs/355-platform-sellable-smoke-matrix/artifacts/platform-sellable-readiness-report.md executive close/fix/defer recommendation
specs/355-platform-sellable-smoke-matrix/artifacts/blocked-fixtures.md explicit fixture blockers when states cannot be exercised honestly
specs/355-platform-sellable-smoke-matrix/artifacts/screenshots/* first-screen proof images

Implementation Approach

Phase 0 - Repo State And Dependency Gate

  1. Re-read spec.md, plan.md, tasks.md, repo-truth-map.md, and checklists/requirements.md.
  2. Run git status --short --branch, git diff --stat, and git log -1 --oneline, then record them in the repo-truth map.
  3. Re-verify Specs 351-354 at runtime-proof level, not by one metadata field alone.
  4. If Spec 354 still has the specifically named dependency concerns open, or if the implementation package cannot prove browser-verified close-readiness, record the blocker and do not publish a final demo-ready or sellable foundation-ready verdict.

Phase 1 - Fixture Inventory

  1. Inventory reusable local/testing/browser helpers already present in the repo.
  2. Confirm which real states can be exercised now:
    • provider blocker
    • review-output blocker
    • ready draft/publish path
    • accepted risk expiring/expired/incomplete
    • governance inbox queue item
    • evidence missing/stale
    • operation follow-up/proof
    • no urgent action
  3. Record missing states in artifacts/blocked-fixtures.md instead of silently broadening runtime scope.

Phase 2 - Browser Smoke Matrix

  1. Run the 10 required flows using visible UI, URLs, and in-browser inspection only.
  2. Capture the required screenshot set or explain each missing screenshot in the matrix.
  3. Record:
    • expected primary action
    • actual primary action
    • scope continuity result
    • customer-safe boundary result
    • console/network/server error observations

Phase 3 - Classification And Readiness Report

  1. Complete the matrix with PASS, PASS WITH NOTES, BLOCKED, FAIL P1, or FAIL P0.
  2. Count pass/fail/blocked results and summarize them in the readiness report.
  3. Do not treat BLOCKED as equivalent to pass.
  4. Keep readiness language conservative when dependencies or fixtures remain unresolved.

Phase 4 - Minimal P0/P1 Fixes Only

  1. If a direct P0/P1 runtime issue is proven and in scope, add the narrowest failing targeted test first.
  2. Patch only the owning surface or direct helper.
  3. Re-run the affected browser flow and update the matrix/report/screenshot set.
  4. Do not widen Spec 355 into a redesign or a new feature lane.

Phase 5 - Regression And Close-Out

  1. Run the targeted regression commands listed in the spec.
  2. Run pint --dirty and git diff --check if code changed.
  3. Report whether the full suite was or was not run.
  4. Close with a readiness decision and an explicit list of any deferred follow-up specs.