TenantAtlas/specs/340-post-scope-contract-browser-verification-gate/plan.md

Implementation Plan: Spec 340 - Post-Scope Contract Browser Verification Gate

• Branch: 340-post-scope-contract-browser-verification-gate
• Date: 2026-05-31
• Spec: specs/340-post-scope-contract-browser-verification-gate/spec.md
• Input: User-provided Spec 340 draft and repo inspection after Specs 338 and 339.

Summary

Prepare and later execute a browser-level scope/IA verification gate after Specs 338 and 339. The implementation work is verification-first: create Spec 340 audit artifacts, run browser checks against in-scope surfaces, classify findings, and return a go/no-go recommendation before new feature work resumes.

The planned implementation must not start with runtime fixes. Runtime code changes are allowed only after browser/test evidence proves a narrow P1/P2 contract break and the active Spec 340 artifacts are updated or a follow-up spec is split.

Technical Context

• Language/Version: PHP 8.4.15, Laravel 12.52.x.
• Primary Dependencies: Filament 5.2.x, Livewire 4.1.x, Pest 4.x browser testing, PostgreSQL through Sail.
• Storage: no runtime storage change; Spec-local Markdown artifacts only.
• Testing: browser verification, optional focused Pest Browser test, optional targeted Feature tests for Provider Connections or route/query classification.
• Validation Lanes: browser, optional fast-feedback. No PostgreSQL lane unless a later bounded runtime fix touches DB behavior.
• Target Platform: local Sail for verification; Dokploy/runtime deployment posture unchanged.
• Project Type: Laravel monolith under apps/platform.
• Performance Goals: verification should avoid broad suite expansion and keep any new browser test bounded to representative surfaces.
• Constraints: no migrations, env vars, queues, scheduler, storage, provider/OAuth changes, new packages, new persisted truth, or broad UI redesign in this gate.
• Scale/Scope: in-scope representative surfaces are the post-338/339 workspace/environment scope contract surfaces, not the full application.

UI / Surface Guardrail Plan

• Guardrail scope: verification-only, no planned operator-facing surface change.
• Affected routes/pages/actions/states/navigation/panel/provider surfaces: browser-inspected Workspace Sidebar, Environment Sidebar, Topbar, Workspace Hubs, Provider Connections, Baselines, Evidence, Operations, Alerts, Audit Log, Reviews, Governance Inbox, Decision Register, and related environment-to-hub links.
• No-impact class: QA/spec-artifact-only unless browser evidence proves a narrow runtime contract break.
• Native vs custom classification summary: current native/custom surfaces are inspected, not changed.
• Shared-family relevance: navigation entry points, scope presentation, action links, local filters, Provider Connection authority.
• State layers in scope: shell, sidebar, topbar, page header, URL query, local filter state, reload/back-forward state.
• Audience modes in scope: operator/MSP admin; customer-safe review surfaces are inspected only for scope/truth signals where reachable.
• Dangerous action posture: no destructive action execution is planned. Credential-adjacent Provider Connection actions are inspected for confirmation/authorization affordance and record-derived scope only.
• Coverage artifact posture: no UI coverage registry update is expected unless implementation makes a runtime UI change. The go/no-go report records checked no-impact if verification-only.

Current Repo Surfaces To Inspect

Implementation should inspect these surfaces and helpers before browser execution:

• apps/platform/routes/web.php
• apps/platform/app/Providers/Filament/AdminPanelProvider.php
• apps/platform/app/Support/Navigation/AdminSurfaceScope.php
• apps/platform/app/Support/Navigation/WorkspaceHubRegistry.php
• apps/platform/app/Support/Navigation/WorkspaceHubEnvironmentFilter.php
• apps/platform/app/Support/Navigation/WorkspaceSidebarNavigation.php
• apps/platform/app/Support/ManagedEnvironmentLinks.php
• apps/platform/app/Support/OperationRunLinks.php
• apps/platform/app/Support/Workspaces/WorkspaceContext.php
• apps/platform/app/Filament/Pages/EnvironmentDashboard.php
• apps/platform/app/Filament/Pages/Monitoring/Operations.php
• apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php
• apps/platform/app/Filament/Resources/ProviderConnectionResource.php
• apps/platform/app/Policies/ProviderConnectionPolicy.php
• existing browser tests under apps/platform/tests/Browser/Spec314*, Spec316*, Spec322*, Spec338*, and Provider Connection browser tests.

Shared Pattern & System Fit

• Shared patterns reused: existing workspace/environment scope contract, environment_id local filter semantics, deny-as-not-found authorization posture, existing browser smoke patterns, and Spec 322 browser harness patterns where applicable.
• New abstraction introduced?: none.
• New persisted truth introduced?: none.
• Provider boundary: verify platform-core authority (workspace, environment_id, record ownership) stays separate from provider-owned Microsoft tenant identity.
• OperationRun: verify Operations hub/link scope only; no OperationRun lifecycle or notification changes.
• Audit/observability: the go/no-go report is the evidence artifact for this gate; no runtime AuditLog writes are introduced.

Implementation Approach

Phase 1 — Preflight and completed-spec guardrail

• Confirm current branch, clean working tree, baseline commit, and that related completed specs are read-only context.
• Confirm no existing specs/340-* package or 340-* branch existed before this preparation.
• Re-read spec.md, plan.md, tasks.md, constitution, and relevant guidelines.

Phase 2 — Repo discovery and verification matrix setup

• Create Spec 340 artifacts:
  • surface-inventory.md
  • scope-verification-matrix.md
  • findings.md
  • audit-report.md
  • artifacts/screenshots/ if screenshots are captured.
• Populate first-pass route/surface inventory from repo files and existing route list.
• Classify each surface into Workspace-owned source of truth, Workspace Hub with local environment filter, Environment-owned detail surface, or credential-adjacent provider surface.

Phase 3 — Browser verification

• Resolve the local app URL through Laravel Boost get_absolute_url or documented local/Sail configuration.
• Use existing smoke-login or seeded fixture conventions without modifying seeders.
• Verify:
  • clean Workspace origin,
  • Environment Dashboard origin,
  • environment-to-hub filtered entry,
  • clean hub entry with remembered environment,
  • reload and browser back/forward,
  • Topbar workspace/environment selector semantics,
  • Provider Connections create/list/view/edit/action affordances.

Phase 4 — Finding classification

• Classify each matrix row as pass, P1, P2, P3, backlog, blocked, or not applicable.
• P1 means a critical scope/authority error or credential-adjacent ambiguity blocks feature work.
• P2 means contract drift should be fixed soon but does not expose immediate credential/security risk.
• P3 means polish/cleanup.
• Backlog means non-blocking improvement or broader productization.
• Blocked means missing route/data/tooling prevented proof and requires explicit next action.

Phase 5 — Optional focused regression coverage

Add focused Pest Browser coverage only if automation is stable and valuable:

• Prefer one bounded Spec340PostScopeContractVerificationSmokeTest.php.
• Reuse existing browser setup/harness patterns.
• Do not add broad fixture defaults or seeders without updating the spec first.
• Keep exhaustive route/query permutations in Feature tests, not browser tests.

Phase 6 — Go/no-go close-out

• Update audit-report.md with final commands, browser tooling, screenshots, blocked checks, and go/no-go status.
• If no P1/P2 drift is found, recommend moving to the next roadmap candidate.
• If P1/P2 drift is found, recommend the smallest safe follow-up or bounded fix and stop unrelated feature work.

Constitution Check

• Inventory-first / snapshots-second: N/A, no inventory/snapshot behavior changed.
• Read/write separation: pass; this is read-only verification unless a later bounded fix is explicitly authorized by updated artifacts.
• Single Graph contract path: pass; no Graph calls are added.
• Deterministic capabilities / RBAC: pass; existing capabilities are verified, not changed.
• Workspace and environment isolation: primary verification focus.
• Provider boundary: pass; verify provider credential-adjacent scope without adding provider abstractions.
• No new persisted truth: pass.
• No new state/status family: pass; P1/P2/P3/backlog is report-only taxonomy.
• UI/Productization coverage: pass; no planned UI surface impact. Any runtime UI fix must update this decision.
• Test governance: pass; browser lane is explicit and central to the gate.
• Proportionality: pass; the gate is narrower than a new feature or broad cleanup chain.

Project Structure

Expected Spec 340 artifact layout:

specs/340-post-scope-contract-browser-verification-gate/
├── spec.md
├── plan.md
├── tasks.md
├── checklists/
│   └── requirements.md
├── surface-inventory.md
├── scope-verification-matrix.md
├── findings.md
├── audit-report.md
└── artifacts/
    └── screenshots/

Optional implementation test:

apps/platform/tests/Browser/Spec340PostScopeContractVerificationSmokeTest.php

Data Model

No runtime data model change.

Spec-local artifact concepts:

• Surface inventory row: surface name, route/entry point, expected taxonomy, origin, filter support, related helper/code owner, verification status.
• Matrix row: surface, browser origin, URL/query, shell, sidebar, breadcrumb/header, visible filter evidence, reload/back-forward result, screenshot path, status, finding ID.
• Finding: ID, severity, expected behavior, actual behavior, evidence, likely owner, smallest next action, go/no-go impact.

Testing Strategy

• Use Pest 4 browser testing if automation is added.
• Browser tests must include assertNoJavaScriptErrors() where stable.
• Prefer targeted browser coverage over full-app smoke.
• Use specific HTTP assertions in any Feature probes (assertNotFound(), assertForbidden(), assertSuccessful()).
• Do not delete or relax existing Spec 322/338/339 tests.

Target commands for later implementation:

cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Browser --filter=Spec340
cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ProviderConnections --filter=ScopeHardening
git diff --check

If no automated browser test is added, the implementation close-out must say browser verification was manual/in-app and list exact routes checked, screenshots captured, and tooling limitations.

Filament / Livewire Contract

• Filament v5 remains on Livewire v4.0+.
• No panel provider registration change is planned; Laravel 12 providers remain in apps/platform/bootstrap/providers.php.
• Global search behavior is not changed. If a runtime fix later touches a globally searchable resource, the implementer must verify View/Edit page availability or disabled global search.
• Destructive/high-impact actions are not executed in this gate. Provider Connection actions are inspected for existing confirmation, authorization, and audit posture only.
• No registered Filament assets are added; filament:assets deployment posture is unchanged.

Deployment / Ops Impact

• Migrations: none.
• Env vars: none.
• Queues/scheduler: none.
• Storage/volumes: none, except local screenshot artifacts under the spec package if captured.
• Dokploy/Staging/Production: no runtime deployment impact unless a later bounded fix changes code.

Risk Controls

• Do not treat blocked checks as pass.
• Do not create follow-up specs automatically unless P1/P2 evidence proves a concrete gap.
• Do not rewrite completed specs.
• Do not broaden into customer review, localization, governance inbox, or commercial lifecycle productization.
• Do not add seeders or global browser fixtures unless the active spec is updated with the fixture-cost decision.

Phase Completion Criteria

• spec.md, plan.md, tasks.md, and checklists/requirements.md exist and are internally aligned.
• The implementation task list is ordered, small, and verification-first.
• No application implementation is included in preparation.
• The package is ready for a separate implementation loop.