TenantAtlas/.agent/skills/repo-contracts/workspace-scope-safety/SKILL.md

name	description
tenantpilot-workspace-scope-safety	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.