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

# Feature Specification: Spec 340 - Post-Scope Contract Browser Verification Gate

**Feature Branch**: `340-post-scope-contract-browser-verification-gate`
**Created**: 2026-05-31
**Status**: Draft
**Input**: User-provided Spec 340 draft from attachment plus repo inspection after Specs 338 and 339.

## Spec Candidate Check *(mandatory — SPEC-GATE-001)*

- **Problem**: Specs 338 and 339 hardened the workspace/environment scope contract and Provider Connection authority, but the original risk was browser-level product confusion: operators could misread workspace-wide hubs as environment-owned pages, topbar context as a hidden filter, or credential-adjacent Provider Connection create behavior as implicitly authorized.
- **Today's failure**: Automated Feature tests prove many policy/query contracts, but they do not prove that the actual browser experience consistently shows whether the user is in Workspace mode, Environment mode, or a Workspace Hub filtered by `environment_id`.
- **User-visible improvement**: Before opening new feature or cleanup specs, operators and reviewers get a concrete browser go/no-go report proving whether the current UI communicates the scope contract correctly across Workspace Sidebar, Environment Sidebar, Topbar, hub filters, environment-to-hub links, Provider Connections, Baselines, Evidence, Operations, Alerts, Audit Log, Reviews, Governance Inbox, and Decision Register.
- **Smallest enterprise-capable version**: A verification-first gate that produces a repo-based surface inventory, browser matrix, screenshot evidence where useful, P1/P2/P3/backlog findings, and explicit go/no-go status. It does not redesign surfaces or introduce new runtime features.
- **Explicit non-goals**: No broad UI redesign, no new product feature, no schema changes, no provider/OAuth redesign, no reopening completed Specs 313/322/338/339, no automatic chain of 341+ follow-up specs, no runtime fix unless a Spec 340 browser or test reproduction proves a narrow in-scope contract break and the active artifacts are updated first.
- **Permanent complexity imported**: One bounded QA/spec package and optional focused browser regression coverage; no new persisted truth, status family, domain abstraction, provider framework, or UI taxonomy.
- **Why now**: The user-provided draft and latest branch context state that after Spec 339 the next safe step is a browser/IA verification gate, not another feature or cleanup spec. This prevents feature work from building on unclear scope semantics.
- **Why not local**: Checking one page locally would miss cross-surface drift. The contract must be verified through representative browser paths from Workspace origin, Environment origin, filtered hub entry, reload/back-forward state, and credential-adjacent Provider Connection flows.
- **Approval class**: Core Enterprise (scope/RBAC/credential-adjacent trust gate).
- **Red flags triggered**: Many surfaces + browser coverage. **Defense**: this is verification-first, bounded to current repo truth, imports no new runtime model, and escalates concrete drift instead of broad refactoring.
- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 2 | Produktnähe: 2 | Wiederverwendung: 1 | **Gesamt: 11/12**
- **Decision**: approve.

## Summary

Spec 340 is a post-scope-contract browser verification gate. It verifies whether the current product experience matches the contracts hardened by Specs 338 and 339:

- Workspace shell and sidebar show workspace-owned, workspace-hub, portfolio, and system surfaces.
- Environment shell and sidebar show environment-owned detail surfaces as primary context.
- Workspace Hubs use explicit local filters such as `environment_id`, not remembered environment or topbar magic.
- Environment pages link to Workspace Hubs through explicit filtered links when a narrowed view is intended.
- Provider Connections require explicit environment authority for create and record-derived authority for view/edit/actions.
- Findings are classified into P1, P2, P3, and backlog, with a go/no-go recommendation before new feature work resumes.

## Completed-Spec Guardrail Result

Related existing specs are context only:

- `specs/313-workspace-environment-context-browser-verification/` already contains completed browser audit tasks and artifacts. It is not a refresh target.
- `specs/322-browser-no-drift-regression-guard/` already contains completed regression-guard tasks and validation notes. It is not a refresh target.
- `specs/338-workspace-environment-resource-scope-contract/` has completed implementation task markers for the scope/link/query contract. It is not modified.
- `specs/339-provider-connection-scope-hardening/` has completed implementation task markers for Provider Connection authority hardening. It is not modified.

Spec 340 uses these packages as dependency evidence only and preserves their implementation history.

## Spec Scope Fields *(mandatory)*

- **Scope**: canonical-view / browser verification gate.
- **Primary routes and surfaces**:
  - Workspace shell/sidebar and Workspace Overview.
  - Environment Dashboard and environment-owned detail routes.
  - Workspace Hubs: Operations, Alerts, Audit Log, Evidence Overview, Provider Connections, Review Register, Customer Review Workspace, Governance Inbox, Decision Register, Finding Exceptions Queue where reachable.
  - Workspace-owned portfolio/configuration surfaces: Baseline Profiles, Baseline Snapshots, Managed Environments, Workspace Settings, Alert Rules, Alert Destinations.
  - Provider Connections list, create, view, edit, and credential-adjacent actions where reachable in browser verification.
- **Data Ownership**: no data model or schema change. Verification distinguishes workspace-owned records, environment-owned records, workspace hub filters, and credential-adjacent provider records.
- **RBAC**: no new capabilities. Browser verification must respect existing workspace membership, managed-environment entitlement, and capability enforcement. Out-of-scope/non-member access remains deny-as-not-found; member-missing-capability remains forbidden where current policy requires it.

For canonical-view verification:

- **Default filter behavior when environment context is active**: Workspace Hubs must not silently infer a filter from remembered environment or the topbar. If narrowed by environment, the page must expose explicit `environment_id` query/filter state or visible filter affordance.
- **Explicit entitlement checks preventing cross-environment leakage**: Any `environment_id` used in a hub URL must be validated against current workspace and actor entitlement by existing runtime code; browser verification records whether wrong or missing context is blocked safely.

## Verification Taxonomy

### A. Workspace-owned source of truth

Examples: Workspace Overview, Managed Environments, Alert Rules, Alert Destinations, Workspace Settings, Baseline Profiles, Baseline Snapshots.

Expected browser signal: workspace shell/sidebar; no environment-owned claim; links to environment details remain explicit.

### B. Workspace Hub with local environment filter

Examples: Operations, Alerts, Audit Log, Evidence Overview, Provider Connections, Review Register, Customer Review Workspace, Governance Inbox, Decision Register, Finding Exceptions Queue.

Expected browser signal: workspace shell/sidebar; visible local filter or URL query when narrowed; no hidden topbar/remembered-environment filtering.

### C. Environment-owned detail surface

Examples: Environment Dashboard and environment route-owned child/detail surfaces.

Expected browser signal: environment in route and shell; primary Environment Sidebar entries are environment-owned.

### D. Credential-adjacent provider surface

Example: Provider Connections.

Expected browser signal: list/view/actions derive authority from workspace context, explicit `environment_id`, or record ownership; create without explicit environment is blocked or guided safely.

## UI Surface Impact *(mandatory — UI-COV-001)*

Does this spec add, remove, rename, or materially change any reachable UI surface?

- [x] No UI surface impact
- [ ] Existing page changed
- [ ] New page/route added
- [ ] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [ ] New table/form/state added
- [ ] Customer-facing surface changed
- [ ] Dangerous action changed
- [ ] Status/evidence/review presentation changed
- [ ] Workspace/environment context presentation changed

No-impact rationale: Spec 340 prepares and later executes a verification gate over existing reachable surfaces. If implementation evidence proves a narrow runtime UI fix is necessary, the implementer must first update the active spec/plan/tasks UI impact decision or split a follow-up spec before changing runtime UI.

## UI/Productization Coverage *(mandatory)*

N/A - no planned reachable UI surface impact. The feature verifies existing UI/productization coverage rather than adding or materially changing a surface.

If browser evidence reveals contract drift:

- P1/P2 drift must be documented with page, URL, origin, screenshot path, expected contract, actual behavior, and the smallest safe next action.
- Runtime fixes require an updated UI impact decision in this active package or a follow-up spec.
- Completed historical specs must not be rewritten to remove close-out, validation, or completed-task evidence.

## Cross-Cutting / Shared Pattern Reuse *(mandatory)*

- **Cross-cutting feature?**: yes, verification touches navigation, scope presentation, deep links, filters, Provider Connection authority, and browser evidence.
- **Interaction classes**: navigation entry points, status/scope messaging, action links, hub filters, credential-adjacent action affordances.
- **Existing patterns to verify/reuse**:
  - `AdminSurfaceScope`
  - `WorkspaceHubRegistry`
  - `WorkspaceHubEnvironmentFilter`
  - `WorkspaceSidebarNavigation`
  - `ManagedEnvironmentLinks`
  - `OperationRunLinks`
  - `WorkspaceContext`
  - `ProviderConnectionPolicy`
  - `ProviderConnectionResource`
  - existing Spec 322 browser harness/patterns where reuse is cheaper than new fixture setup.
- **Allowed deviation and why**: none for preparation. Runtime deviation requires a documented P1/P2 finding and bounded fix decision.
- **Consistency impact**: route owns shell, query owns local filter, record owns Provider Connection action authority, and topbar context must not become hidden authorization.
- **Review focus**: evidence must distinguish actual product drift from missing seed data, blocked access, or historical wording in completed specs.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: no new start/completion semantics.
- **Verification relevance**: Operations hub and OperationRun links are verified for scope and filter presentation only.
- **Queued DB-notification policy**: N/A.
- **Terminal notification path**: N/A.
- **Exception required?**: none.

## Provider Boundary / Platform Core Check

- **Shared provider/platform boundary touched?**: verification touches Provider Connections and Microsoft-adjacent vocabulary, but does not change provider contracts.
- **Boundary classification**: platform-core scope authority (`workspace`, `environment_id`, record ownership) plus provider-owned Microsoft identity detail.
- **Why this does not deepen provider coupling accidentally**: Spec 340 verifies that Provider Connections do not treat remembered environment, Filament tenant, or legacy tenant query aliases as platform authority.
- **Follow-up path**: document in the go/no-go report if browser evidence shows provider-boundary vocabulary or authority drift.

## UI / Surface Guardrail Impact

| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note |
|---|---|---|---|---|---|---|
| Spec 340 verification artifacts | no | N/A | navigation, filters, browser evidence | shell, page, URL-query inspected only | no | Verification gate; no planned runtime UI change |

## Decision-First Surface Role

N/A - no operator-facing surface is added or materially changed. The verification gate checks whether existing surfaces expose the correct decision context.

## Audience-Aware Disclosure

N/A - no detail/status surface is added or materially changed. Browser findings must still record whether existing customer/operator surfaces expose raw diagnostics, internal IDs, or misleading scope signals.

## UI/UX Surface Classification

N/A - no new or modified operator-facing list/detail/queue/audit/config/report surface is planned. Existing surfaces are classified in the browser matrix by their expected taxonomy role.

## Operator Surface Contract

N/A - no new surface contract is introduced. Spec 340 verifies existing shell/page/filter/action contracts.

## Proportionality Review *(mandatory when structural complexity is introduced)*

- **New source of truth?**: no.
- **New persisted entity/table/artifact?**: no persisted runtime artifact. Spec-local verification artifacts may be created under `specs/340-post-scope-contract-browser-verification-gate/`.
- **New abstraction?**: no.
- **New enum/state/reason family?**: no runtime enum/state. P1/P2/P3/backlog is a report taxonomy only.
- **New cross-domain UI framework/taxonomy?**: no new runtime taxonomy. Verification reuses the existing workspace/environment scope taxonomy.
- **Current operator problem**: operators need proof that the browser experience matches scope authority before new work compounds any drift.
- **Existing structure is insufficient because**: completed Feature tests and prior audits do not prove the combined post-338/339 browser experience.
- **Narrowest correct implementation**: one verification gate with matrix/report artifacts and optional focused browser regression coverage.
- **Ownership cost**: bounded browser/test maintenance if automation is added; no runtime model maintenance.
- **Alternative intentionally rejected**: starting the next feature/cleanup candidate without browser proof.
- **Release truth**: current-release verification before further roadmap work.

### Compatibility posture

This feature assumes a pre-production environment. No migration shim, compatibility path, legacy alias, or production-data preservation behavior is introduced.

## Testing / Lane / Runtime Impact *(mandatory)*

- **Test purpose / classification**: Browser verification + optional focused Feature tests only if needed to classify a browser finding.
- **Validation lanes**: browser, optional fast-feedback for route/query/authorization probes, no PostgreSQL lane unless a follow-up runtime fix changes DB behavior.
- **Why this classification and these lanes are sufficient**: The risk is browser-level scope communication and credential-adjacent authority perception. Browser verification is the primary proof; targeted Feature tests can classify suspected policy/query drift without broad suite cost.
- **New or expanded test families**: optional `Spec340` browser smoke or manifest-based regression test; fixture setup must reuse existing browser test patterns where possible.
- **Fixture/helper cost impact**: keep workspace/environment/browser fixtures explicit and opt-in. Do not add seeders unless browser verification is blocked and the spec is updated first.
- **Heavy-family visibility / justification**: browser coverage is explicit and central to the gate, not accidental.
- **Special surface test profile**: global-context-shell.
- **Reviewer handoff**: reviewers must verify that browser evidence covers clean workspace origin, environment origin, filtered hub entry, reload/back-forward state, topbar semantics, and Provider Connections authority.
- **Budget / baseline / trend impact**: no expected broad suite cost unless automated browser coverage expands; record any expansion in the go/no-go report.
- **Escalation needed**: P1/P2 drift becomes `follow-up-spec` or a bounded in-scope fix only after active artifact update.
- **Planned validation commands**:
  - `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`

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Verify Workspace and Environment mode clarity (Priority: P1)

As an operator moving between workspace and environment areas, I can always tell whether I am in Workspace mode, Environment mode, or a Workspace Hub filtered by environment.

**Why this priority**: The scope contract is only trustworthy if the browser shell, sidebar, breadcrumb/header, and visible filter state communicate the same ownership model.

**Independent Test**: Open representative Workspace and Environment origins, navigate through sidebar/global entries, reload, and record shell/sidebar/header/filter evidence in the matrix.

**Acceptance Scenarios**:

1. **Given** a Workspace origin with no active environment route, **When** the operator opens Workspace Hubs, **Then** the shell/sidebar remains workspace-mode and any environment narrowing is represented as an explicit local filter.
2. **Given** an Environment Dashboard origin, **When** the operator opens environment-owned detail surfaces, **Then** the route and shell clearly carry that environment.
3. **Given** an Environment Dashboard origin, **When** the operator opens workspace-wide hubs, **Then** the page does not pretend to be environment-owned.

---

### User Story 2 - Verify workspace hub filters and topbar semantics (Priority: P1)

As an operator, topbar environment selection and local hub filters do not silently become each other.

**Why this priority**: A hidden topbar/session filter can create false confidence and cross-scope misunderstandings.

**Independent Test**: From clean, remembered-environment, and filtered-entry states, verify Operations, Alerts, Audit Log, Evidence Overview, Provider Connections, Reviews, Customer Review Workspace, Governance Inbox, and Decision Register where reachable.

**Acceptance Scenarios**:

1. **Given** a remembered environment, **When** the operator opens a clean Workspace Hub URL, **Then** the hub does not silently filter to that environment.
2. **Given** an explicit `environment_id`, **When** the operator opens a filterable Workspace Hub, **Then** the page exposes a visible filter/chip/banner or equivalent local filter evidence.
3. **Given** a filtered hub entry, **When** the operator clears the filter, reloads, or uses browser back/forward, **Then** the visible scope state remains truthful.

---

### User Story 3 - Verify Provider Connection authority in the browser (Priority: P1)

As an operator near credential-adjacent Provider Connections, I can see that create/manage behavior requires explicit environment authority or record ownership, not hidden context.

**Why this priority**: Provider Connections sit near credentials, consent, permissions, and provider operations.

**Independent Test**: Verify Provider Connections list/create/view/edit/action affordances from clean, filtered, remembered-environment, missing-environment, and wrong-environment states.

**Acceptance Scenarios**:

1. **Given** a Provider Connections list, **When** an explicit `environment_id` is present, **Then** the filter and create path are tied to that environment.
2. **Given** no explicit `environment_id`, **When** the operator attempts create, **Then** create is blocked or guided safely without relying on remembered environment.
3. **Given** an existing Provider Connection record, **When** the operator views or manages it, **Then** scope context comes from record ownership and capability enforcement.

---

### User Story 4 - Produce a go/no-go report (Priority: P2)

As a product/engineering reviewer, I receive a compact report that says whether new feature work may continue or which concrete scope drift must be fixed first.

**Why this priority**: The output must prevent vague “looks okay” conclusions and avoid automatic follow-up sprawl.

**Independent Test**: Review the final report and matrix; every P1/P2 finding includes evidence, expected/actual behavior, affected files or routes, and a recommended next action.

**Acceptance Scenarios**:

1. **Given** browser verification is complete, **When** no P1/P2 drift is found, **Then** the report gives a clear go recommendation for new feature work.
2. **Given** P1/P2 drift is found, **When** the report is reviewed, **Then** it names the smallest safe follow-up or bounded fix and blocks unrelated feature work.
3. **Given** missing data or unavailable routes block a check, **When** the report is reviewed, **Then** the limitation is explicit and not reported as a pass.

## Functional Requirements

- **FR-340-001**: The verification must inventory every in-scope surface, expected taxonomy class, route, origin path, filter capability, and evidence status.
- **FR-340-002**: The verification must check Workspace Sidebar behavior from a clean Workspace origin.
- **FR-340-003**: The verification must check Environment Sidebar behavior from at least one Environment Dashboard origin.
- **FR-340-004**: The verification must check that Workspace Hubs use explicit local filters and do not silently consume topbar/remembered environment state.
- **FR-340-005**: The verification must check environment-to-hub links for explicit `environment_id` when the link intends a filtered hub view.
- **FR-340-006**: The verification must check Topbar workspace selector and environment selector semantics and record whether they navigate, filter, or change context.
- **FR-340-007**: The verification must check Provider Connections create/list/view/edit/action affordances against explicit environment and record-derived authority.
- **FR-340-008**: The verification must include Baseline Profiles/Snapshots as workspace-owned surfaces and must not reopen their ownership unless browser evidence proves regression.
- **FR-340-009**: The verification must record reload and browser back/forward behavior for representative filtered hubs.
- **FR-340-010**: The verification must classify each finding as P1, P2, P3, backlog, pass, blocked, or not applicable.
- **FR-340-011**: The final report must include go/no-go status, exact commands or browser tooling used, screenshot paths where captured, blocked checks, and next recommended action.
- **FR-340-012**: The implementation must not modify completed Spec 313/322/338/339 artifacts except as read-only context.
- **FR-340-013**: Any runtime change discovered during implementation must be preceded by an active artifact update or split into a follow-up spec.
- **FR-340-014**: The verification must not create new persisted entities, migrations, providers, capabilities, OperationRun types, or product features.

## Non-Functional Requirements

- **NFR-340-001**: Browser evidence must be reproducible from documented local/Sail commands or explicitly marked as manually verified with tool limitations.
- **NFR-340-002**: The report must distinguish verified pass, verified drift, insufficient seed data, inaccessible route, and authorization-blocked states.
- **NFR-340-003**: Browser/test additions must keep fixture cost explicit and avoid broad seed/global setup changes.
- **NFR-340-004**: No secrets, raw credential payloads, or sensitive Graph data may be captured in screenshots or reports.
- **NFR-340-005**: Verification must remain compatible with Filament v5 and Livewire v4 conventions.

## Required Artifacts

Implementation of this spec should create or update only Spec 340 artifacts and optional focused tests:

- `specs/340-post-scope-contract-browser-verification-gate/surface-inventory.md`
- `specs/340-post-scope-contract-browser-verification-gate/scope-verification-matrix.md`
- `specs/340-post-scope-contract-browser-verification-gate/findings.md`
- `specs/340-post-scope-contract-browser-verification-gate/audit-report.md`
- `specs/340-post-scope-contract-browser-verification-gate/artifacts/screenshots/` when screenshot evidence is useful
- optional `apps/platform/tests/Browser/Spec340PostScopeContractVerificationSmokeTest.php` if automation is stable and bounded

## Acceptance Criteria

- **AC1**: All in-scope surfaces are inventoried and classified against the verification taxonomy.
- **AC2**: Browser evidence covers clean Workspace origin, Environment origin, filtered hub entry, topbar context changes, reload, and back/forward for representative hubs.
- **AC3**: Provider Connections browser behavior is verified for explicit environment create authority and record-derived action authority.
- **AC4**: Findings are classified with evidence and no P1/P2 issue is left ambiguous or silently deferred.
- **AC5**: Completed related specs are not rewritten.
- **AC6**: No application implementation is performed during preparation; later implementation remains bounded by `tasks.md`.

## Success Criteria

- **SC-340-001**: The final go/no-go report can be reviewed without replaying the entire browser session.
- **SC-340-002**: If no P1/P2 drift exists, the report clearly permits the next roadmap feature/cleanup candidate.
- **SC-340-003**: If P1/P2 drift exists, the report blocks unrelated feature work and names the smallest safe follow-up or bounded fix.
- **SC-340-004**: Browser verification does not introduce unstable global fixtures, hidden seed dependencies, or broad regression-suite cost.

## Out of Scope

- Sidebar/topbar redesign.
- Provider Connection redesign or OAuth/provider registry changes.
- Broad canonical link/query cleanup beyond concrete browser findings.
- New product feature work.
- Schema, migration, model, service, policy, job, route, or runtime behavior changes during preparation.
- Rewriting or normalizing completed spec close-out/history.

## Risks

- Browser automation may be blocked by local app/session/data availability; blocked checks must be reported instead of treated as passes.
- Existing seed data may not cover every surface; report limitations and add only bounded fixture/test tasks if needed.
- A true P1/P2 finding may require a follow-up spec instead of being fixed inside the verification gate.
- The verification could become too broad; tasks keep the scope to scope/IA/authority evidence only.

## Assumptions

- The branch starts from current `platform-dev` after Spec 339 integration evidence.
- Local development uses Sail where runtime/browser verification is needed.
- Existing browser test patterns and smoke-login helpers can be reused if automation is added.
- Spec 340 preparation is allowed to create Spec Kit artifacts but not application implementation.

## Open Questions

None blocking. If browser tooling or seed data cannot prove a surface, implementation must mark the check as blocked and recommend the smallest next action.

## Follow-up Spec Candidates

Only create or promote a follow-up if Spec 340 evidence proves it is needed:

- `canonical-link-query-cleanup` for broad link/query drift not safely fixable inside Spec 340.
- `environment-resource-context-follow-through` for hidden Filament/environment context reliance beyond browser-visible contract issues.
- `provider-connection-scope-hardening-follow-up` only if Spec 339 browser verification reveals remaining credential-adjacent authority drift.
- Customer Review Workspace, Localization, Governance Inbox, and commercial lifecycle candidates remain deferred until this gate gives a go decision.