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?

• 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.