update spec candidate

docs/product/spec-candidates.md

@@ -4,7 +4,7 @@ # Spec Candidates
 > **Last reviewed:** 2026-05-15
 > **Use for:** The active repo-based queue of spec candidates that may still need new or refreshed specs
 > **Do not use for:** Proof that a candidate is already specced, implemented, or prioritized above the roadmap without repo verification
-> **Scoped maintenance:** 2026-05-15 Spec 310 product-truth/docs-drift reconciliation after Specs 307-309; 2026-05-15 Spec 309 RBAC role matrix and access boundary hardening update; 2026-05-15 Spec 308 customer-safe Decision Summary and Review Pack inclusion update; 2026-05-15 Spec 307 Decision Register proof-link implementation update; 2026-05-15 Spec 306 Decision Register reconciliation update; 2026-05-15 Spec 304 Tenant Panel dead-code retirement guardrail update; 2026-05-12 admin workspace navigation and tenant-owned surface repair candidate intake after the repo-verified navigation/panel audit; 2026-05-06 cross-domain progress and indicator semantics candidate intake; 2026-05-04 OperationRun progress maturity plus Tenant Dashboard active-operations summary candidate intake; 2026-05-03 OperationRun activity feedback candidate intake plus the 2026-05-02 repo-based queue re-audit and enterprise-SaaS deep-research alignment against current `specs/` truth, including Specs 263 and current-branch 264.
+> **Scoped maintenance:** 2026-05-15 post-Spec-311 legacy/productization/scope follow-up candidate update; 2026-05-15 Spec 310 product-truth/docs-drift reconciliation after Specs 307-309; 2026-05-15 Spec 309 RBAC role matrix and access boundary hardening update; 2026-05-15 Spec 308 customer-safe Decision Summary and Review Pack inclusion update; 2026-05-15 Spec 307 Decision Register proof-link implementation update; 2026-05-15 Spec 306 Decision Register reconciliation update; 2026-05-15 Spec 304 Tenant Panel dead-code retirement guardrail update; 2026-05-12 admin workspace navigation and tenant-owned surface repair candidate intake after the repo-verified navigation/panel audit; 2026-05-06 cross-domain progress and indicator semantics candidate intake; 2026-05-04 OperationRun progress maturity plus Tenant Dashboard active-operations summary candidate intake; 2026-05-03 OperationRun activity feedback candidate intake plus the 2026-05-02 repo-based queue re-audit and enterprise-SaaS deep-research alignment against current `specs/` truth, including Specs 263 and current-branch 264.
 >
 > Repo-based next-spec queue for TenantPilot.
 > This file is not a wishlist. It tracks only open gaps that are still worth turning into new or refreshed specs.
@@ -41,7 +41,7 @@ ### Customer Review Workspace v1
 
 - **Status markers**: repo-verified, productization gap
 - **Roadmap lane**: Next
-- **Current repo truth**: Specs 249 and 258, plus Spec 308 customer-safe Decision Summary / Review Pack inclusion, the implementation ledger, and current review surfaces, already prove the foundational path for customer-safe review consumption.
+- **Current repo truth**: Specs 249 and 258, plus Spec 308 customer-safe Decision Summary / Review Pack inclusion, Spec 311 Workspace / Environment Surface Scope Contract, the implementation ledger, and current review surfaces, already prove the foundational path for customer-safe review consumption.
 - **Problem**: Customer-safe review consumption remains the clearest sellability gap whenever calm status, reason, impact, evidence basis, accepted risks, decision summary, review-pack download, and one primary next action still require operator translation.
 - **Deep-Research-derived sharpening**: Keep the lane focused on one customer-safe read-only review surface, findings summary, accepted-risk visibility, evidence viewer, review-pack download, management summary, RBAC/capability enforcement, and audit trail.
 - **Non-goals**: no generic customer portal, no helpdesk surface, no raw diagnostics by default, no admin mirror.
@@ -152,6 +152,10 @@ ## Active Candidate Queue
 - `Decision Register Customer-Safe Summary / Review-Pack Inclusion` -> Spec 308, completed historical customer-safe summary and review-pack inclusion
 - `RBAC Role Matrix & Access Boundary Audit` -> Spec 309, completed scoped security hardening
 
+Spec 311 is also treated as completed foundation on the current repo artifacts:
+
+- `Workspace / Environment Surface Scope Contract` -> Spec 311, completed shell/scope foundation for route-owned workspace-wide versus environment-bound context. Follow-up work must not reopen shell/sidebar/topbar scope unless fresh repo evidence shows regression.
+
 Two manual-promotion items have since moved out of backlog status on the current repo state:
 
 - `Auditor Pack Delivery & Executive Export v1` -> Spec 263
@@ -163,18 +167,307 @@ ## Promotable Candidate Backlog
 
 **Boundary**: manual promotion only, not auto-prep. These items are intentionally outside `next-best-prep` and require an explicit product decision before any future spec refresh or follow-up work.
 
-### Recommended Next Spec Sequence After Spec 310
+### Recommended Next Candidate Sequence After Spec 311
 
-| Order | Recommended next spec | Candidate status | Boundary |
-|---:|---|---|---|
-| 311 | `customer-review-workspace-v1-completion` | open gap / P1 | Complete customer-safe review consumption without claiming a generic customer portal. |
-| 312 | `localization-v1-customer-facing-surfaces` | open gap / P1 | Productize DE/EN customer-facing review, pack, notification, reason, impact, and next-action language over the existing localization foundation. |
-| 313 | `decision-based-governance-inbox-v1` | open gap / P1 | Extend decision-centered operator workflow over existing Governance Inbox and Decision Register truth; do not rebuild the Decision Register. |
-| 314 | `commercial-entitlements-billing-state-maturity` | open gap / P1/P2 | Mature commercial lifecycle and billing-state truth after customer-facing surfaces are clearer. |
-| 315 | `cross-tenant-compare-promotion-execution` | spec-backed / open execution maturity | Continue the governance-first compare/promotion execution path if Spec 264 still needs runtime/product refresh. |
-| 316 | `governance-artifact-lifecycle-retention` | open gap / P2 | Productize artifact lifecycle and retention runtime over existing taxonomy/truth foundations. |
-| 317 | `external-support-desk-psa-handoff` | repo-real foundation / open productization | Productize support-desk/PSA handoff only after higher-priority review and decision paths settle. |
-| 318 | `private-ai-execution-governance-foundation` | foundation/open / P3 | Promote only as a bounded governed runtime consumer, not as an AI feature island. |
+No new spec numbers are assigned here. This table is a manual-promotion sequence only.
+
+| Order | Recommended next candidate | Candidate status | Boundary | Depends on |
+|---:|---|---|---|---|
+| 1 | `customer-review-workspace-v1-completion` | open gap / P1 | Complete customer-safe review consumption without claiming a generic customer portal or reopening shell/sidebar scope. | Spec 311 |
+| 2 | `provider-connection-scope-hardening` | open gap / P1 | Harden workspace/provider-level provider connection scope and credential authority. | Spec 311 |
+| 3 | `canonical-link-query-cleanup` | open gap / P1 | Clean route/link/query semantics after the surface scope contract. | Spec 311; provider hardening preferred |
+| 4 | `product-truth-docs-drift-cleanup` | open gap / P2 | Align docs/templates/product truth with retired `/admin/t` and route-scope contract. | Spec 311 |
+| 5 | `environment-resource-context-follow-through` | open gap / P2 | Reduce hidden Filament tenant fallback in selected canonical environment resources. | Spec 311; canonical link cleanup preferred |
+| 6 | `legacy-compatibility-dead-code-retirement` | open gap / P2 | Remove or classify confirmed stale compatibility leftovers while keeping guard tests. | product truth cleanup preferred |
+| 7 | `tenant-helper-naming-cleanup` | open gap / P3 | Rename or isolate tenant-named helpers that now encode legacy mental models. | canonical link cleanup; product truth cleanup preferred |
+| 8 | `localization-v1-customer-facing-surfaces` | existing open gap / P1 | Productize DE/EN customer-facing review, pack, notification, reason, impact, and next-action language over the existing localization foundation. | customer review completion preferred |
+| 9 | `decision-based-governance-inbox-v1` | existing open gap / P1 | Extend decision-centered operator workflow over existing Governance Inbox and Decision Register truth; do not rebuild the Decision Register. | customer review completion preferred |
+| 10 | `commercial-entitlements-billing-state-maturity` | existing open gap / P1/P2 | Mature commercial lifecycle and billing-state truth after customer-facing surfaces are clearer. | productization lanes |
+
+### Post-311 Legacy / Productization / Scope follow-up candidates
+
+These candidates are concrete follow-ups after Spec 311. They must not be merged into one umbrella spec. Spec 311 is the completed foundation: route scope determines shell/sidebar/topbar/breadcrumb; page filters determine data inside the current surface.
+
+#### Customer Review Workspace v1 Completion
+
+- **Priority**: P1
+- **Complexity**: M
+- **Impact**: High
+- **Type**: Productization / customer-safe review consumption
+- **Depends on**: Workspace / Environment Surface Scope Contract
+- **Problem**: Customer Review Workspace can now build on a stable workspace-wide shell/sidebar contract, but the actual customer-safe productization remains incomplete: latest released review, Decision Summary, accepted risks, evidence basis, review pack status, download state, and clear empty states still need to be made coherent.
+- **Why now**: Spec 311 removed the shell/sidebar ambiguity, so the next narrow step can focus on customer-safe consumption rather than scope repair.
+- **Risk**: High productization risk if deferred, because review value still requires operator translation and the workspace could remain "repo-real" but not sellable.
+- **Goal**: make Customer Review Workspace a workspace-wide hub for customer-safe released review consumption. Environment selection remains a page-level filter, not global context.
+- **Repo evidence**:
+  - `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`
+  - `apps/platform/resources/views/filament/pages/reviews/customer-review-workspace.blade.php`
+  - `apps/platform/app/Filament/Resources/EnvironmentReviewResource.php`
+  - `apps/platform/app/Filament/Resources/ReviewPackResource.php`
+  - `apps/platform/app/Jobs/GenerateReviewPackJob.php`
+  - `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php`
+  - `specs/308-decision-register-summary-review-pack/spec.md`
+  - `specs/311-workspace-environment-surface-scope-contract/spec.md`
+- **Scope**:
+  - Customer Review Workspace overview
+  - latest released review section
+  - review pack status and download availability
+  - customer-safe Decision Summary
+  - accepted risks and customer-safe evidence basis
+  - empty states for no released review, filtered no results, no decisions requiring awareness, incomplete evidence, and pack missing/generating/expired
+  - focused tests and browser smoke when UI changes
+- **Non-scope**:
+  - no shell, sidebar, topbar, `OperateHubShell`, `TenantPageCategory`, or `NavigationScope` work
+  - no RBAC changes, migrations, new tables, or new `OperationRun` types
+  - no Provider Connection scope work
+  - no Product Truth broad cleanup
+  - no AI summary
+- **Acceptance criteria**:
+  - released reviews are understandable and customer-safe
+  - environment filter is shown as a filter, not global context
+  - latest review, Decision Summary, accepted risks, evidence basis, and pack status are visible
+  - no internal IDs, fingerprints, `OperationRun` URLs, debug data, or internal reason families leak
+  - no approve, reject, renew, revoke, expire, or regenerate actions appear on the customer-safe surface
+  - existing authorization remains intact
+
+#### Provider Connection Scope Hardening
+
+- **Priority**: P1
+- **Complexity**: M
+- **Impact**: High
+- **Type**: Security / scope / provider boundary
+- **Depends on**: Workspace / Environment Surface Scope Contract
+- **Problem**: Provider Connections are workspace/provider-level, but legacy audit evidence shows they can still be influenced by hidden context such as remembered tenant, `lastTenantId`, Filament tenant, or query filters. This is high-risk because the surface sits near credentials, consent, permissions, and target connection logic.
+- **Why now**: Spec 311 establishes the workspace-wide shell contract, but Provider Connections still need their own authority and filter semantics hardened before credential-adjacent work grows.
+- **Risk**: High security/scope risk if hidden context can influence credential-level authority or connection operations.
+- **Goal**: Provider Connections are unambiguously workspace/provider-level. Environment is an explicit filter or record relationship, not hidden shell/session context. Create/edit/verify/delete/rotate/disconnect actions are capability- and scope-safe.
+- **Repo evidence**:
+  - `apps/platform/app/Filament/Resources/ProviderConnectionResource.php`
+  - `apps/platform/app/Policies/ProviderConnectionPolicy.php`
+  - `apps/platform/app/Support/ManagedEnvironmentLinks.php`
+  - `apps/platform/app/Support/Workspaces/WorkspaceContext.php`
+  - `apps/platform/tests/Feature/ProviderConnections/*`
+  - `specs/309-rbac-role-matrix-access-boundary-audit/tasks.md`
+  - `specs/311-workspace-environment-surface-scope-contract/spec.md`
+- **Scope**:
+  - Provider Connection list, view, create, edit, and credential-adjacent actions
+  - `ProviderConnectionPolicy`
+  - Provider Connection filters and `managed_environment_id` query behavior
+  - remembered tenant / Filament tenant fallback review
+  - Owner, Manager, Operator, and Readonly behavior
+  - wrong workspace and wrong environment tests
+- **Non-scope**:
+  - no new provider registry rebuild
+  - no new ProviderConnection table
+  - no Graph contract policy
+  - no new credential rotation feature expansion
+  - no billing or entitlement work
+  - no broad provider UX redesign
+  - no environment resource cutover
+- **Acceptance criteria**:
+  - Provider Connection list, view, and action scopes are workspace-safe
+  - `managed_environment_id` is an explicit filter, not hidden context
+  - `lastTenantId` / remembered tenant does not decide credential-level authority
+  - non-member and out-of-scope access remains denied
+  - Manager/Operator cannot perform credential-level actions unless repo-real policy explicitly permits it
+  - legitimate existing Provider Connection flows remain green
+
+#### Canonical Link / Query Cleanup
+
+- **Priority**: P1
+- **Complexity**: M
+- **Impact**: High
+- **Type**: Route hygiene / link canonicalization
+- **Depends on**: Workspace / Environment Surface Scope Contract; Provider Connection Scope Hardening preferred
+- **Problem**: Link and query seams still contain ambiguous or legacy-shaped names such as `tenantPrefilterUrl`, `?tenant=...`, `tenantScopedUrl`, raw `/admin/...` URLs, mixed `tenant` versus `managed_environment_id`, and helper names that encode the old tenant mental model.
+- **Why now**: Once scope is route-owned, links and query keys need to stop teaching future specs the old tenant-context model.
+- **Risk**: Medium/high regression risk if new productization work keeps copying legacy helper names or query semantics.
+- **Goal**: Links and query parameters are semantically explicit. Workspace-wide links stay workspace-wide; environment-owned details use canonical workspace/environment routes; environment filters use explicit environment filter query names; no `/admin/t` links are generated.
+- **Repo evidence**:
+  - `CustomerReviewWorkspace::tenantPrefilterUrl`
+  - `OperationRunLinks`
+  - `ManagedEnvironmentLinks`
+  - `WorkspaceScopedTenantRoutes`
+  - `EnvironmentReviewResource::tenantScopedUrl`
+  - Evidence, stored report, review pack, notification, and "View operation" links
+  - `EnsureFilamentTenantSelected` navigation links
+- **Scope**:
+  - link helper inventory
+  - query key standardization for page-level environment filters
+  - bounded raw URL replacement where route helpers exist
+  - canonical route assertions and no `/admin/t` guard tests
+  - test updates that stop asserting legacy query names where safe
+- **Non-scope**:
+  - no route restructuring
+  - no migrations
+  - no RBAC changes
+  - no Provider Connection security changes
+  - no environment resource cutover
+  - no UI redesign
+  - no full docs rewrite
+- **Acceptance criteria**:
+  - workspace-wide surfaces use explicit filter query names
+  - Customer Review, Review Register, Governance, and Operations links no longer rely on legacy tenant query semantics
+  - environment-owned detail links are canonical workspace/environment URLs
+  - `OperationRun` links remain canonical
+  - no `/admin/t` links are generated
+
+#### Product Truth / Docs Drift Cleanup
+
+- **Priority**: P2
+- **Complexity**: S/M
+- **Impact**: Medium/High
+- **Type**: Documentation / product truth / spec hygiene
+- **Depends on**: Workspace / Environment Surface Scope Contract
+- **Problem**: Repo docs and templates still contain stale route and naming guidance: `docs/HANDOVER.md` describes three panels including `/admin/t`, constitution/templates include `/admin/t` examples, older specs use Tenant Panel or tenant-context language, and implementation ledger entries still reference old class names.
+- **Why now**: Spec 311 finalizes the scope contract; docs/templates should not keep generating new specs with retired `/admin/t` examples or query-as-context language.
+- **Risk**: Medium/high process risk if stale templates continue to seed wrong route semantics into future specs.
+- **Goal**: docs, spec templates, and product truth reflect the current runtime: `/admin/t` is retired, `/admin` and `/system` are active panels, workspace-wide versus environment-bound scope is documented, and query filter versus context is explicit.
+- **Repo evidence**:
+  - `docs/HANDOVER.md`
+  - `.specify/memory/constitution.md`
+  - `.specify/templates/spec-template.md`
+  - `docs/product/implementation-ledger.md`
+  - `docs/product/spec-candidates.md`
+  - `docs/product/roadmap.md`
+  - `specs/279-*` through `specs/288-*`
+  - `specs/300+`
+  - `specs/311-workspace-environment-surface-scope-contract/*`
+- **Scope**:
+  - docs-only correction
+  - template updates
+  - constitution language cleanup
+  - implementation ledger alignment
+  - spec candidates alignment
+  - roadmap note update
+- **Non-scope**:
+  - no code changes
+  - no test changes unless docs validation already exists and requires it
+  - no product feature implementation
+  - no broad rewrite
+  - no new roadmap strategy
+- **Acceptance criteria**:
+  - no active docs/template guidance recommends `/admin/t` for new work
+  - workspace-wide versus environment-bound contract is documented
+  - product docs distinguish filter from context
+  - completed specs are not reopened as Greenfield
+  - open follow-ups remain clearly marked
+  - docs diff is minimal and reviewable
+
+#### Environment Resource Context Follow-through
+
+- **Priority**: P2
+- **Complexity**: L
+- **Impact**: High
+- **Type**: Route/resource cutover / context hardening
+- **Depends on**: Workspace / Environment Surface Scope Contract; Canonical Link / Query Cleanup preferred
+- **Problem**: Many environment-owned resources are already on canonical workspace/environment routes, but internally still rely on Filament tenant bridge, `getTenant` fallback, `tenantScopedUrl` naming, or legacy compatibility seams. That bridge is partly necessary today, but it is fragile as a hidden data source.
+- **Why now**: The canonical route family exists; the remaining risk is hidden fallback inside high-value resources, which should be reduced only after link/query semantics are cleaner.
+- **Risk**: Medium/high correctness risk if route params and hidden Filament/session context disagree.
+- **Goal**: selected high-value environment-owned resources derive primary context from canonical route parameters: workspace, managed environment, and record scope. Filament tenant bridge remains a controlled Filament integration layer, not hidden product truth.
+- **Repo evidence**:
+  - `apps/platform/app/Filament/Concerns/WorkspaceScopedTenantRoutes.php`
+  - `Filament::getTenant` usages
+  - `ManagedEnvironment::current`
+  - Policy and PolicyVersion resources
+  - Backup and Restore resources
+  - `EvidenceSnapshotResource`
+  - `StoredReportResource`
+  - `FindingExceptionResource`
+  - Required Permissions and Diagnostics pages
+  - related resource tests
+- **Scope**:
+  - inventory remaining environment-owned fallback usage
+  - bounded replacement in selected high-value resources
+  - route-param context tests
+  - reduce hidden Filament tenant dependency where safe
+  - keep canonical environment routes
+- **Non-scope**:
+  - no full rewrite of all resources
+  - no route family redesign
+  - no RBAC changes
+  - no migrations
+  - no customer review productization
+  - no helper-renaming-only work unless required for safety
+- **Acceptance criteria**:
+  - selected high-value environment resources work from canonical route context
+  - direct URLs with workspace/environment params resolve correctly
+  - hidden remembered tenant does not override canonical route params
+  - no `/admin/t` compatibility route is introduced
+  - existing resource tests remain green
+
+#### Legacy Compatibility / Dead Code Retirement
+
+- **Priority**: P2
+- **Complexity**: S/M
+- **Impact**: Medium
+- **Type**: Cleanup / dead code / guarded retirement
+- **Depends on**: Product Truth / Docs Drift Cleanup preferred
+- **Problem**: The active `/admin/t` runtime panel is removed, but stale or suspicious leftovers remain: `apps/platform/patch.diff`, TenantDashboard references, TenantPanelProvider references in docs/tests, ChooseTenant references, TenantRequiredPermissions docs, legacy redirect guards, and old compatibility examples. Some are valuable guardrails; some are stale artifacts.
+- **Why now**: After docs truth is corrected, remaining leftovers can be classified without confusing historical guardrails with active runtime dependencies.
+- **Risk**: Medium cleanup risk, because deleting guard tests or compatibility assertions without proof could weaken no-legacy protections.
+- **Goal**: classify and retire legacy compatibility leftovers without deleting active runtime behavior by accident.
+- **Repo evidence**:
+  - `apps/platform/patch.diff`
+  - `docs/HANDOVER.md`
+  - `tests/Feature/Guards/NoLegacyTenantPanelRuntimeTest.php`
+  - `tests/Feature/ProviderConnections/LegacyRedirectTest.php`
+  - `tests/Feature/ManagedEnvironment/LegacyTenantCoreGuardTest.php`
+  - implementation ledger references
+  - old specs/templates
+- **Scope**:
+  - dead-code inventory verification
+  - remove confirmed stale patch/docs leftovers
+  - keep guard tests
+  - update docs references where minimal
+  - ensure no runtime route resurrection
+- **Non-scope**:
+  - no active route cutover work
+  - no environment resource migration
+  - no RBAC changes
+  - no broad docs rewrite
+  - no test deletion without proof
+- **Acceptance criteria**:
+  - confirmed dead artifacts are removed or explicitly documented
+  - guard tests for retired routes remain
+  - no active runtime behavior changes
+  - no `/admin/t` route returns
+  - cleanup diff stays small and safe
+
+#### Tenant Helper Naming Cleanup
+
+- **Priority**: P3
+- **Complexity**: M
+- **Impact**: Medium
+- **Type**: Naming / domain language cleanup
+- **Depends on**: Canonical Link / Query Cleanup; Product Truth / Docs Drift Cleanup preferred
+- **Problem**: Many helpers and tests still use `tenant*` naming even though the target model is workspace/managed-environment first: `tenantScopedUrl`, `tenantPrefilterUrl`, `tenant` parameter names, tenant-bound wording in tests/docs, and helper aliases.
+- **Why now**: This should follow behavior cleanup, because renaming first would create churn without eliminating the underlying route/query ambiguity.
+- **Risk**: Medium terminology drift risk, but lower runtime risk than the P1/P2 scope and link candidates.
+- **Goal**: new public and internal helper names use managed-environment, environment, workspace, environment-scoped, and environment-filter semantics. Old names remain only as justified compatibility aliases.
+- **Repo evidence**:
+  - `tenantScopedUrl` usages
+  - `tenantPrefilterUrl` usages
+  - `WorkspaceScopedTenantRoutes`
+  - tests with tenant naming
+  - docs/spec templates
+- **Scope**:
+  - naming inventory
+  - safe internal renames in bounded helpers
+  - compatibility aliases only where required
+  - tests adjusted where names encode product semantics
+  - no behavior change
+- **Non-scope**:
+  - no route behavior changes
+  - no RBAC changes
+  - no migration
+  - no broad resource cutover
+  - no docs rewrite beyond touched names
+- **Acceptance criteria**:
+  - new helper names reflect ManagedEnvironment/Workspace semantics
+  - existing behavior remains unchanged
+  - tests prove no route/link behavior changed
+  - remaining tenant-named helpers are documented as compatibility or pending follow-up
 
 ### OperationRun Activity Feedback & UI Governance candidate group