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:

```text
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:

```text
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:

```bash
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.