---
name: tenantpilot-workspace-scope-safety
description: Hard-gate workspace, managed-environment, provider-connection, and tenant-scope safety for TenantPilot changes.
---

## Purpose

Use this skill to prevent workspace, managed-environment, provider-connection, or tenant-scope leakage in runtime code, specs, tests, jobs, routes, downloads, exports, and review surfaces.

## Activate When

- Touching models, migrations, policies, queries, route model binding, relation managers, exports, downloads, jobs, or services with workspace or managed-environment data.
- Introducing or reading provider connection scope.
- Handling user-supplied IDs, route parameters, signed links, queued job payloads, or background operation context.
- Reviewing whether non-member access should be 404 and member-missing-capability should be 403.

## Do Not Activate When

- The task is docs-only and does not describe scope, ownership, authorization, or runtime data semantics.
- The task only reads completed historical artifacts as context.

## Maturity

L4 hard gate.

## Gate Type

hard-gate.

## Source Evidence

- `.specify/memory/constitution.md`
- `docs/security-guidelines.md`
- `docs/architecture-guidelines.md`
- `docs/ai-coding-rules.md`
- `specs/402-resource-policy-authorization-proof-matrix/implementation-report.md`
- `specs/415-generic-content-backed-capture/implementation-report.md`
- `apps/platform/app/Policies/ProviderConnectionPolicy.php`
- `apps/platform/app/Support/Rbac/UiEnforcement.php`
- `apps/platform/app/Support/Rbac/WorkspaceUiEnforcement.php`
- `apps/platform/tests/Feature/Rbac/ProviderConnectionAccessBoundaryTest.php`
- `apps/platform/tests/Feature/TenantConfiguration/Spec415ProviderConnectionScopeTest.php`

## External Anchors

Not applicable.

## Required Repo Context

- Owning model relationships and casts.
- Migrations and constraints for the touched tables.
- Existing policies/gates and capability registry usage.
- Query scopes, relation managers, route bindings, controller lookups, and queued job payloads.
- Positive and negative tests for same-workspace and cross-workspace behavior.

## Execution Checklist

- Resolve workspace before managed environment and provider connection.
- Verify provider connections are same-workspace and same-managed-environment when used for environment-owned work.
- Use scoped lookups instead of `find()` or fallback-to-first/latest behavior.
- Make non-member or wrong-scope access deny-as-not-found.
- Keep provider-native tenant identifiers as metadata, not platform-core ownership truth.
- Validate queued jobs re-resolve scope from trusted IDs before work.
- Add or update negative tests for guessed IDs, wrong workspace, wrong managed environment, and wrong provider connection where runtime behavior changes.

## Stop Conditions

- Runtime code introduces `tenant_id` as platform-core ownership truth.
- A lookup can resolve records outside the current workspace or managed environment.
- A provider connection can be attached to or used for the wrong workspace/environment.
- Code falls back to first, latest, default, or implicit records when scope cannot be resolved.
- Cross-workspace data can be rendered, exported, downloaded, queued, mutated, or linked.
- Scope-sensitive behavior lacks a negative test and the change is runtime/security-relevant.

## Required Evidence After Use

- Scoped lookup path and owner columns.
- Authorization result semantics for wrong-scope and missing-capability cases.
- Tests or static proof covering cross-workspace/cross-environment denial.
- Confirmation that no `tenant_id` platform-core ownership path was added.

## Common Failure Modes

- Treating a visible tenant selector as authorization.
- Reusing provider-native tenant IDs as database ownership.
- Allowing relation managers to attach unrelated records.
- Storing queue context that bypasses handle-time revalidation.
- Letting global search leak inaccessible labels or URLs.

## Quarantined Rules

Full Spec 416 quarantine list applies. Especially quarantined here: `tenant_id` as platform-core ownership truth; fallback readers; dual writes; fallback-to-latest evidence; historical audits as current truth.

## Review / Expiry

Review whenever ownership schema, workspace routing, provider connection scope, or RBAC semantics change. No planned expiry.