ahmido b159dacd36 feat: clean up legacy tenant environment context (#372 )

## Summary
- remove legacy tenant-scoped routing and middleware paths in favor of the current environment/workspace context flow
- update Filament pages and resources to use the cleaned-up admin surface and environment filter context
- add the related spec 317 artifacts and targeted tests for environment filter state and legacy context cleanup

## Testing
- not run as part of this commit/push/PR workflow

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #372

2026-05-16 18:25:36 +00:00

114 KiB

Raw Blame History

Spec Candidates

Status: Active 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 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.

Basis: implementation-ledger.md, roadmap.md, current specs/ truth

Candidate Rules

Work repo-based, not roadmap-aspirational.
Do not keep implemented features as active candidates.
Do not keep already-specced foundations as active candidates unless a narrower follow-up gap remains.
P0 is reserved for blockers to the next sellable release.
P1 is for enterprise and product maturity gaps.
P2 is for commercial and scale readiness.
P3 is for later platform ambitions after current release blockers close.
Existing candidate history is preserved through Promoted to Spec, Deferred, and Superseded / Removed notes rather than silent deletion.

Current Source-Of-Truth Boundary

This file is the active candidate queue.
roadmap.md provides strategic themes and release framing, not the canonical candidate queue.
discoveries.md is a staging area for findings that may later be promoted here.
implementation-ledger.md is maturity evidence, not a prioritization queue.
Audit-derived candidate packages under docs/audits/ are historical inputs only unless they are explicitly promoted into this file.
The deep-research alignment reference below sharpens naming, status markers, and target sequencing without reopening already-promoted specs as active queue items.

Deep-Research Alignment Reference (non-queue)

This section is a deep-research-derived calibration layer. It is intentionally not the active queue. Use it to keep candidate naming, scope, and status language aligned with current repo truth.

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

Decision-Based Governance Inbox + Decision Register Follow-up

Status markers: repo-verified, productization gap, roadmap recommendation
Roadmap lane: Next
Current repo truth: governance inbox, findings queues, operations attention, review follow-up, and Specs 250/257 already anchor the decision surface. Specs 265, 306, 307, and 308 prove the bounded operator Decision Register, direct proof/run link polish, and customer-safe summary/review-pack inclusion are not Greenfield.
Problem: The remaining gap is broader decision-centered operating discipline: a Governance Inbox / Customer Review Workspace completion slice, not customer-safe summary or review-pack inclusion.
Deep-Research-derived sharpening: keep any next slice as a follow-up over Specs 250/257/265/306/307/308, not a new Decision Register or approval-engine rebuild.
Non-goals: no generic Kanban board, no PSA clone, no XDR incident console, no new decision table, no duplicate approval engine.

Governance Artifact Lifecycle & Retention v1

Status markers: foundation-only, roadmap recommendation, spec candidate
Roadmap lane: Next / P2 after customer-facing review, localization, decision inbox, commercial truth, and promotion execution
Current repo truth: Spec 262, the lifecycle-governance standard, review-pack retention, and artifact-truth semantics provide taxonomy-first foundations, but not a productized governance-artifact lifecycle.
Problem: Evidence snapshots, stored reports, review packs, and future decision records are governance artifacts and must not be treated like short-lived operational rows.
Roadmap Recommendation: v1 should cover artifact-type registry, immutable artifact reference, artifact state, retention state, export bundle, preserve or hold state, soft delete or hard delete semantics, suspended/read-only workspace behavior, and audit trail for export/delete/hold.
Non-goals: no legal case management, no full eDiscovery system, no Purview clone.

Commercial Entitlements & Billing-State Lifecycle v1

Status markers: repo-verified, foundation-only, productization gap
Roadmap lane: Now
Current repo truth: Specs 247 and 251 already ground workspace entitlements, lifecycle state handling, and read-only gating.
Problem: Workspace, plan, and billing state still need clearer artifact-access, archive, scheduled-deletion, and customer-trust semantics.
Deep-Research-derived sharpening: keep the lane framed as commercial lifecycle, workspace read-only behavior, artifact access by state, capability gating, and audited state change semantics rather than payment-engine work.
Non-goals: no payment gateway, no invoicing engine, no tax engine.

External Support Desk / PSA Handoff v1

Status markers: repo-verified, productization gap
Roadmap lane: P2 after customer-facing review, localization, decision inbox, commercial truth, promotion execution, and artifact lifecycle
Current repo truth: Spec 256 and the current support-request handoff already prove a bounded create/link model.
Problem: MSP governance work still needs cleaner PSA/ITSM handoff with external reference continuity, evidence/context transfer, due date/status mapping, closure sync or manual reconciliation, audit trail, and webhook-ready shape.
Deep-Research-derived sharpening: keep PSA/ITSM as integration and handoff, not as a TenantPilot-native helpdesk.
Non-goals: no PSA clone, no project-management suite, no generic helpdesk.

Customer-Facing Localization v1

Status markers: foundation-only, productization gap
Roadmap lane: Now
Current repo truth: Spec 252 and the locale resolver already provide the foundation.
Problem: DE/EN customer-facing review consumption still lacks full glossary discipline, customer-safe labels, review-pack templates, notification text, and fallback confidence.
Deep-Research-derived sharpening: v1 means glossary, review-workspace strings, review-pack templates, evidence labels, status/reason/impact/next-action labels, locale-aware formatting, fallback behavior, and missing-key tests.
Non-goals: no full operator-UI localization in v1, no marketing translation project, no uncontrolled string extraction.

Cross-Tenant Compare & Promotion with Lineage v1

Status markers: repo-verified, productization gap
Roadmap lane: Next
Current repo truth: Spec 043 is already repo-real for compare and preflight, and Spec 264 now carries the execution follow-through on this branch.
Problem: portfolio action still needs governance-first execution with impact preview, promotion proposal, approval, OperationRun trace, before/after evidence, baseline lineage, rollback reference, and decision-record linkage.
Deep-Research-derived sharpening: keep this lane governance-first. It is not a generic policy-push or settings-sync surface.
Non-goals: no unmanaged mass remediation, no generic settings push, no admin mirror.

Governance Service Packaging v1

Status markers: repo-verified, productization gap
Roadmap lane: Next
Current repo truth: Spec 260 and current governance-package delivery cues already exist.
Problem: MSPs need repeatable governance-service packages with review cadence, included controls/reports, stakeholder mapping, schedule, package-specific review-pack semantics, and entitlement binding.
Deep-Research-derived sharpening: productize packaging as a repeatable governance service, not as one-off executive exports or bespoke customer projects.
Non-goals: no CRM, no PSA, no billing system.

Enterprise Access Boundary & Support Access Governance v1

Status markers: roadmap recommendation, spec candidate
Roadmap lane: Next when support-access gaps turn operationally acute; otherwise Later
Current repo truth: audit docs and handover material already show break-glass, system access, and platform support seams, but not a bounded support-access governance package.
Problem: support access, delegated access, and future impersonation need customer-safe auditability, reason capture, TTL, approval, operator-context banner, and exportable access logs before broader SSO/SCIM work.
Roadmap Recommendation: prioritize support-access request, reason required, time-limited access, capability-bound access, customer-visible audit trail, optional approval, break-glass separation, operator context banner, and exportable access log.
Non-goals: no full IAM suite, no immediate SCIM requirement unless separately promoted, no unrestricted impersonation.

Private AI Execution Governance Foundation v1

Status markers: repo-verified, foundation-only, later scale-layer
Roadmap lane: Later
Current repo truth: Spec 248 is already implemented as a governed AI foundation.
Problem: visible AI work must still avoid feature-island drift and should only ship on top of governed use-case, provider-class, policy, audit, and approval boundaries.
Deep-Research-derived sharpening: keep AI foundation-first. The next visible candidate is a bounded governed runtime consumer or AI-assisted review-drafting lane, not a new foundation reboot.
Non-goals: no public LLM by default, no autonomous remediation, no chatbot over raw tenant data, no AI without audit and policy boundaries.

Active Candidate Queue

2026-05-01 queue re-audit result: no safe automatic next-best-prep target remains in the active queue.

The previous P0-P2 candidates were removed from the active queue because current specs/ truth already covers them as prepared or implemented packages:

Customer Review Workspace Productization v1 -> Spec 258
Governance Decision Surface Convergence -> Spec 257
Cross-Tenant Compare and Promotion v1 -> refreshed Spec 043
Remove Findings Lifecycle Backfill Runtime Surfaces -> Spec 253
Remove Legacy Acknowledged Finding Status Compatibility -> Spec 254
Enforce Creation-Time Finding Invariants -> Spec 255
Commercial Entitlements and Billing-State Maturity -> Spec 251
Compliance Evidence Mapping v1 -> Spec 259
Governance-as-a-Service Packaging v1 -> Spec 260
External Support Desk / PSA Handoff -> Spec 256

These packages already provide the needed preparation surface, and several now carry completed task checklists or implementation close-out history. They must not be auto-selected again by next-best-prep.

Specs 307, 308, and 309 have also moved out of candidate status on the current repo truth:

Decision Register Evidence / OperationRun Link Polish -> Spec 307, completed historical proof/run link polish
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
Cross-Tenant Promotion Execution v1 -> Spec 264

The historical record for Workspace, Tenant & Managed Object Lifecycle Governance v1 remains below because it was promoted intentionally, not automatically, into Spec 262 and must not re-enter the active auto-prep queue.

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 Candidate Sequence After Spec 311

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, AdminSurfaceScope, 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 Environment switcher state, Filament Environment context, 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 Environment / Filament Environment 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
- remembered Environment switcher state 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 must stay explicit after the Workspace/Environment cleanup: Environment filters use environment_id, Workspace-wide links stay workspace-wide, provider Tenant identifiers stay provider-boundary, and raw /admin/... URLs should not bypass canonical helpers.
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::environmentFilterUrl
- OperationRunLinks
- ManagedEnvironmentLinks
- WorkspaceScopedEnvironmentRoutes
- EnvironmentReviewResource::environmentScopedUrl
- Evidence, stored report, review pack, notification, and "View operation" links
- EnsureEnvironmentContextSelected 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 rely on canonical environment_id query semantics only
- 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, environmentScopedUrl 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/WorkspaceScopedEnvironmentRoutes.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 environment 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

Environment Helper Naming Follow-through

Priority: P3
Complexity: M
Impact: Medium
Type: Naming / domain language cleanup
Depends on: Canonical Link / Query Cleanup; Product Truth / Docs Drift Cleanup preferred
Problem: Some helper and test names still inherit framework/domain tenant* vocabulary even when the target model is Workspace/Managed Environment first. The current contract is Workspace-first, Environment-second, with provider Tenant terminology reserved for Microsoft/Entra/provider identity.
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. No compatibility aliases are added for platform-context helper names.
Repo evidence:
- Environment-owned resource route helpers
- Customer Review Workspace Environment filter links
- Workspace-scoped Environment route trait usage
- tests with tenant naming
- docs/spec templates
Scope:
- naming inventory
- safe internal renames in bounded helpers
- no compatibility aliases for platform-context names
- 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

Priority posture: immediate manual-promotion pair, then sequenced execution-truth maturity follow-ups, then longer-horizon adjacent work
Repo truth: OperationRun is already the execution-truth layer in repo-real code and tests through OperationUxPresenter, OperationStatusNormalizer, OperationRunLinks, OperationRunUrl, active-run coverage, notification link contracts, dashboard drill-throughs, and the existing BulkOperationProgress Livewire plus poller path. The current progress widget is also a known overlap and UI-drift seam rather than a neutral pattern.
Why promotable now: this is the clearest repo-based UX consistency gap around platform execution truth and the best bounded way to stop more surfaces from inventing their own run-state cards, fake progress patterns, or dismiss semantics.
Why manual promotion only: the right cut is product-sensitive. The first safe promotion should bundle one bounded v1 execution slice with one durable UI guardrail, while keeping the larger tray, lifecycle, and acknowledgement questions as explicit follow-up candidates instead of hiding them inside the first spec.
Primary manual-promotion target (promote together):
- OperationRun UI Standards & Constitution Guardrail
  - capture the shared OperationRun Activity Feedback Pattern in docs/ui/tenantpilot-enterprise-ui-standards.md
  - codify progressbar rules, canonical View operation links, dashboard limits, hide/collapse boundaries, and anti-patterns such as fake percentages or floating overlays that cover primary actions
  - optionally add a constitution-level pointer later if run-surface drift keeps reappearing, but do not block the standards update on a larger constitution rewrite
- OperationRun Activity Feedback v1
  - introduce one shared activity/view-model layer over the existing run-status and guidance semantics
  - introduce one shared compact Filament-native run activity component
  - adopt that layer in dashboard/start surfaces with at most 1-3 prioritized items
  - allow determinate progress only from operation-owned counts; otherwise show indeterminate or status-only treatment
  - support session-local hide/collapse only for non-critical running or queued hints
  - move BulkOperationProgress onto the same model/component family so it stops behaving like a separate visual world
Guardrails for the primary slice:
- OperationRun remains the only run-state truth; dashboards, widgets, notifications, and overlays must not invent a second lifecycle or severity model.
- Progressbars are valid only when total > 0, completed <= total, and the percentage is derived from deterministic run-owned data.
- failed, blocked, attention_required, and equivalent follow-up states must not become permanently dismissible.
- Dashboard and start surfaces stay decision-first; Operations Hub and run detail stay diagnostics-first.
- Every run hint uses the canonical View operation link contract.

OperationRun / Execution Truth maturity follow-up queue

Repo starting point: Spec 268 created the in-shell active operation surface, but the repo audit still shows follow-up maturity gaps around terminal outcome semantics, canonical progress truth, counted-progress rollout, and truthful phase/composite treatment.
Recommended promotion order:
1. 269 — OperationRun Terminal Outcome Feedback
2. 273 — Tenant Dashboard Active Operations Summary Card, if dashboard feedback drift is visible after Spec 268; otherwise keep it as a small follow-up after the core progress semantics queue
3. 270 — OperationRun Progress Contract v1
4. 271 — Counted Progress Rollout v1
5. 272 — OperationRun Phase & Composite Progress v1
Rationale: 269 closes the immediate post-Spec-268 UX semantics gap. 273 keeps the Tenant Dashboard calm and governance-first while restoring a trustworthy tenant-scoped execution signal if operators lose confidence after starting work. 270 formalizes the reusable contract and blocks future fake progress. 271 adds real counted progress where stable work units exist. 272 is optional and should follow only after counted and terminal semantics are stable.

269 — OperationRun Terminal Outcome Feedback

Classification:
- repo-verified foundation: OperationRun Truth Layer, ActiveRuns, BulkOperationProgress, OperationUxPresenter
- gap: terminal outcome semantics in the activity surface
- maturity: small productization fix
- sellability impact: medium, because it increases operator trust
Problem: Spec 268 correctly introduced activity feedback for queued and running work, but terminal states still need stricter UX semantics. Completed, failed, blocked, cancelled, or follow-up-required runs must not look like they are still progressing.
Goal: complete the OperationRun feedback loop by separating active work from terminal outcome.
Scope:
- active queued and running work may show activity or progress
- running with trustworthy processed and total may show determinate progress
- queued or running without trustworthy counts may show indeterminate activity
- completed successfully shows a short success confirmation, not a progress or activity line
- failed, blocked, cancelled, or follow-up-required states show decision or follow-up guidance, not progress
- tertiary action wording depends on lifecycle:
  - queued or running: Hide activity
  - completed successfully: Close or Dismiss
  - failed, blocked, cancelled, or follow-up-required: Acknowledge or Review
- successful terminal state may auto-dismiss after a short grace period
- failed, blocked, cancelled, or follow-up-required states must not disappear silently
Out of scope:
- new OperationRun widget system
- new top-level page
- fake percentage progress
- broad layout redesign
- run-type count rollout
Acceptance criteria:
- terminal success does not render determinate or indeterminate progress
- terminal failed, blocked, cancelled, or follow-up-required states do not render progress
- active queued or running work without counts still renders indeterminate activity
- active running work with processed and total still renders determinate progress
- action wording matches lifecycle state
- existing placement, KPI agreement, overflow, and browser row-action tests remain green

273 — Tenant Dashboard Active Operations Summary Card

Classification:
- repo-verified foundation: OperationRun Truth Layer, ActiveRuns, OperationRunLinks, OperationUxPresenter, Tenant Dashboard Productization
- gap: Tenant Dashboard currently lacks a dashboard-native active operations summary when the full shell banner is intentionally not shown
- maturity: small productization follow-up
- sellability impact: medium, because it improves operator confidence without turning the dashboard into an operations console
Problem: The Tenant Dashboard is a governance overview, not an operations console. Showing the full Spec 268 shell activity banner there can make the dashboard noisy and too operational. But showing nothing when OperationRun values are queued or running creates feedback drift: an operator may start an Inventory Sync or other tenant-scoped operation and then see no clear signal on the dashboard.
Goal: add a dashboard-native Active Operations summary card that keeps the Tenant Dashboard calm while still reflecting OperationRun execution truth.
Scope:
- add a compact dashboard card or panel for active tenant-scoped OperationRun values
- do not render the full Spec 268 expanded shell activity banner on the Tenant Dashboard by default
- use the same OperationRun truth source as the shell activity feedback, preferably the existing ActiveRuns, OperationRunLinks, and OperationUxPresenter family
- show a concise summary:
  - 1 active operation or localized equivalent
  - primary active run label, for example Inventory sync
  - status chip, for example Waiting for worker, In progress, Likely stale, or Follow-up required
  - short guidance, for example No action needed yet. or Review required.
  - primary CTA: View operation
  - secondary link: Show all operations
- keep normal queued and running work calm and small
- make failed, blocked, stale, or follow-up-required runs more visible than healthy queued and running work
- respect workspace and tenant isolation
- respect operation-view permissions and capabilities
- avoid raw diagnostics by default
Out of scope:
- new Operations page
- new OperationRun widget system
- full shell activity banner redesign
- counted progress rollout
- phase and composite progress model
- customer-facing review workspace changes
- raw logs or payloads on the dashboard
UX rules:
- the Tenant Dashboard remains decision-first and governance-focused
- active operations are a secondary status signal, not the primary page focus
- the card should fit naturally into the dashboard grid, preferably near operational health, recent operations, or the right-side status column
- do not create a large full-width activity banner on the dashboard
- do not hide active operations completely
- terminal failed, blocked, stale, or follow-up-required states should remain actionable
- completed successful runs may appear briefly or be represented in Recent Operations, but should not clutter the dashboard
Acceptance criteria:
- Tenant Dashboard shows a compact Active Operations summary when one or more tenant-scoped OperationRun values are queued, running, or require follow-up
- normal queued and running work is calm and non-obstructive
- failed, blocked, stale, or follow-up-required work receives clearer visual priority
- the summary card uses canonical OperationRun links
- View operation opens the relevant run detail
- Show all operations opens the canonical Operations view filtered to the current tenant or context where applicable
- the card respects RBAC and capabilities
- the card is hidden or replaced by an empty or calm state when there are no active or follow-up OperationRun values
- existing Tenant Dashboard KPI and action layout remains stable
- no duplicate or conflicting OperationRun truth source is introduced
- tests cover:
  - no active operations state
  - queued or running operation state
  - stale or follow-up-required state
  - canonical links
  - permission and capability visibility
  - tenant and workspace isolation
Priority note: place this after Spec 268 terminal semantics and before the broader progress-contract and counted-progress rollout if dashboard feedback drift is visible in the product. Otherwise keep it as a small follow-up candidate after the core progress semantics specs.
Rationale: this keeps Spec 268 narrow and avoids mixing global shell activity feedback with Tenant Dashboard information architecture. The Tenant Dashboard should stay calm and governance-first, but it still needs a trustworthy OperationRun signal so users do not lose confidence after starting tenant-scoped work.

270 — OperationRun Progress Contract v1

Classification:
- repo-verified foundation: OperationRunService, summary_counts, SummaryCountsNormalizer, OperationSummaryKeys, ActiveRuns
- gap: progress semantics are not yet formalized as a reusable contract
- maturity: enterprise foundation
- sellability impact: medium-high, because it improves execution-truth credibility
Problem: progress rendering is currently mostly encoded in the activity feedback view and summary_counts conventions. Enterprise maturity requires a canonical product contract that defines when progress is allowed, what it means, and how each run type declares its progress capability.
Goal: create a canonical OperationRun progress semantics layer so the UI never invents progress and future run types use one consistent contract.
Scope:
- introduce or formalize a progress contract or presenter for OperationRun
- define progress capability categories:
  - none: no progress representation
  - activity: running or queued only, no measurable progress
  - counted: trustworthy processed and total exists
  - phased: true persisted phase or step state exists
  - composite: parent run with child or fan-out progress
- determine render model:
  - terminal outcome
  - indeterminate activity
  - determinate counted progress
  - phase text
  - composite or child summary
- keep summary_counts.processed and summary_counts.total as the only v1 determinate progress source
- do not derive percentage from status, duration, stale state, succeeded, failed, skipped, or lifecycle heuristics
- define how outcome counters relate to progress counters:
  - processed = progress
  - succeeded, failed, and skipped = outcome
  - outcome counters must not silently replace processed
- add tests that prevent fake progress
- update UI standards and developer guidance
Out of scope:
- broad rollout of new counts across all run types
- new database-heavy telemetry model unless strictly required
- AI summaries
- customer-facing review changes
Acceptance criteria:
- one canonical helper or presenter decides progress display semantics
- the activity banner no longer owns progress semantics ad hoc
- tests prove:
  - no fake percentage from running status
  - no fake percentage from succeeded, failed, or skipped
  - no progress line for terminal outcome
  - determinate progress only from trustworthy processed and total
  - phased and composite states do not masquerade as counted percentages
- docs describe the progress contract clearly

271 — Counted Progress Rollout v1

Classification:
- repo-verified foundation: OperationRunService::incrementSummaryCounts(), OperationRunService::maybeCompleteBulkRun(), backup and restore fan-out patterns, summary_counts whitelist
- gap: many run types are terminal-summary-only
- maturity: productization and operational maturity
- sellability impact: medium-high for MSP and operator trust
Problem: many OperationRun types currently have lifecycle truth and terminal summaries, but not live counted progress. The shell can only show real progress when run writers persist trustworthy processed and total counts. Enterprise operators benefit from real progress on long-running or high-value jobs.
Goal: add real counted progress to selected high-value run types where stable work units exist.
Prioritized v1 run types:
1. inventory sync
2. review pack generation and export
3. evidence snapshot generation
4. baseline compare
5. restore and backup fan-out standardization where already partially present
Scope:
- for each selected run type, identify stable work units
- set summary_counts.total before or at the start of measurable processing where possible
- increment summary_counts.processed as units complete
- keep succeeded, failed, and skipped as outcome counters
- do not use outcome counters as hidden progress substitutes unless explicitly mapped through the progress contract
- use existing OperationRunService helpers where possible
- add run-type-specific tests for count integrity
- ensure terminal outcomes still summarize final counts
- preserve workspace and tenant isolation
Out of scope:
- forcing counts onto short or non-quantifiable jobs
- fake totals for API operations where the total is unknowable
- rewriting all OperationRun writers
- new UI redesign beyond consuming the progress contract
Acceptance criteria:
- selected run types emit trustworthy processed and total counts during execution
- activity feedback shows determinate progress only for those run types when counts exist
- jobs with unknown totals still show indeterminate activity
- tests cover:
  - total initialized correctly
  - processed increments safely
  - processed never exceeds total
  - failed, skipped, and succeeded remain outcome counters
  - terminal summary remains correct
- existing fan-out backup and restore progress behavior is standardized, not duplicated

272 — OperationRun Phase & Composite Progress v1

Classification:
- repo-verified foundation: OperationRun context, OperationRunService, OperationUxPresenter, child and fan-out patterns
- gap: no canonical persisted phase or composite progress contract
- maturity: optional enterprise hardening
- sellability impact: medium, especially for complex MSP operations
Problem: some OperationRun values are not naturally countable but are still long-running or complex. For those, forcing processed and total creates fake precision. Enterprise UX needs a separate way to show real phase or composite progress without pretending it is percentage progress.
Goal: introduce a truthful phase and composite progress model for long-running non-countable or orchestrated OperationRun values.
Scope:
- define persisted phase or step metadata for selected run types:
  - preparing
  - fetching
  - processing
  - persisting
  - finalizing
- define phase labels as user-safe operator copy, not raw technical internals
- add optional composite progress for parent and child OperationRun values:
  - parent status
  - child counts
  - failed child summary
  - next action
- UI shows phase text and optional child summary
- do not convert phases into fake percentages unless a real step contract exists and is explicitly approved
- add tests that phase and composite progress are not confused with counted progress
Candidate run types:
- evidence snapshot generation
- tenant review compose
- review pack generation
- baseline compare and capture
- provider health and support diagnostics
Out of scope:
- full workflow engine
- new top-level monitoring page
- customer-facing raw diagnostics
- AI-generated progress explanations
Acceptance criteria:
- non-countable long-running jobs can expose true phase or status copy
- composite parent jobs can summarize child state without fake percentages
- activity feedback can render phase or composite state through the progress contract
- terminal outcome behavior remains separate from progress
- tests prove phase states do not render counted progressbars unless processed and total exist
Adjacent longer-horizon follow-up candidates (after the execution-truth queue):
1. Host Widget Operation State Migration Pass
  - migrate run-state snippets in host widgets onto the shared inline component without flattening the widget's business role
2. Polling & UI Calmness Standard for Operations
  - centralize when polling is allowed, reduce parallel widget polling, and define calm/stale semantics for long-running runs
3. Notification & Operation Activity Lifecycle Standard
  - separate toast, DB notification, activity surface, dashboard, Operations Hub, and run-detail responsibilities without creating a second run truth
4. OperationRun Activity Center / Tray v2
  - replace or absorb the floating overlay into a calmer, prioritized, non-obstructive activity surface once the shared v1 model exists
5. OperationRun Reviewed / Investigated Semantics v2
  - model audited, capability-gated server-side follow-through for problem states without conflating it with session-local hide/collapse
Anchors:
- apps/platform/app/Support/OpsUx/OperationUxPresenter.php
- apps/platform/app/Support/OpsUx/OperationStatusNormalizer.php
- apps/platform/app/Support/OperationRunLinks.php
- apps/platform/app/Support/OpsUx/OperationRunUrl.php
- apps/platform/app/Livewire/BulkOperationProgress.php
- apps/platform/public/js/tenantpilot/ops-ux-progress-widget-poller.js
- apps/platform/tests/Feature/OpsUx/ActiveRunsTest.php
- apps/platform/tests/Feature/OpsUx/BulkOperationProgressDbOnlyTest.php
- apps/platform/tests/Feature/OpsUx/CanonicalViewRunLinksTest.php
- apps/platform/tests/Feature/OpsUx/NotificationViewRunLinkTest.php
- apps/platform/tests/Feature/OpsUx/ProgressWidgetOverflowTest.php
- apps/platform/tests/Feature/Notifications/OperationRunNotificationTest.php
- apps/platform/tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php

Cross-Domain Progress / Indicator Semantics candidate group

Priority posture: immediate manual-promotion audit plus standards guardrail in parallel with OperationRun Activity Feedback, then contract, shared components, quality gates, and domain migration
Repo truth: Specs 268, 270, 271, and 272 now sharpen OperationRun-specific execution semantics, but the repo already contains other progress-like seams with different meanings: execution activity in BulkOperationProgress, coverage truth in InventoryKpiHeader, readiness messaging in RecoveryReadiness and CustomerReviewWorkspace, coverage summaries in BaselineSnapshotPresenter, and usage signals passed through ReviewPackService. docs/ui/tenantpilot-enterprise-ui-standards.md currently codifies the OperationRun activity-feedback pattern, but it does not yet provide one product-wide indicator taxonomy above those domain slices.
Why promotable now: the OperationRun candidates close run-specific UI drift, but they do not yet tell TenantPilot how to distinguish execution progress from coverage, completion, readiness, risk, pressure, usage, score, and generation state across the rest of the product.
Why manual promotion only: the first safe slice must stay taxonomy-first and repo-grounded. It should inventory and classify existing indicators before introducing a shared contract or component family, and it must not silently turn into a charting project, analytics rewrite, score recalculation program, or broad design-system reboot.
Primary manual-promotion target (promote together):
- Candidate 8 — Cross-Domain Progress Indicator Semantics Audit
  - inventory every progress-like bar, percentage, score, health meter, readiness label, usage indicator, and generation-state hint across current repo surfaces
  - classify each instance as execution progress, activity state, coverage, completion, health/readiness, risk/pressure, usage/capacity, score, generation state, or unknown/ambiguous
  - produce the inventory table, risk matrix, cleanup list, shared-component recommendation set, and standards-delta input that later specs can reuse
- Candidate 13 — Cross-Domain UI Standards & Constitution Patch
  - extend docs/ui/tenantpilot-enterprise-ui-standards.md with product-wide indicator semantics rules that sit above individual domains
  - define allowed indicator categories, direction rules, determinate-progress eligibility, missing/stale-data rules, dashboard constraints, customer-safe wording, and anti-patterns such as fake progress or usage bars that look like success progress
  - add a constitution pointer only if repeated indicator drift proves the standards patch alone is not enough
Recommended promotion order after the audit pair:
1. Candidate 9 — Metric & Indicator Contract Foundation
2. Candidate 10 — Shared Progress / Indicator Component System
3. Candidate 12 — Progress / Indicator Quality Gates
4. Candidate 11 — Domain Progress Cleanup & Migration Pass
Spec 278 audit output: specs/278-cross-domain-indicator-audit/inventory.md, follow-up-map.md, and standards-delta.md are the repo-based input for the follow-up lanes. Later work must reuse the five lane names from the map instead of opening a broad catch-all cleanup:
- standards patch lane: patch product/UI standards and spec templates so each new indicator states category, denominator, freshness, missing-data behavior, provider boundary, and customer-safe wording.
- metric/indicator contract foundation: define the provider-neutral contract fields and direction/freshness semantics before component or migration work.
- shared indicator component system: create Filament-compatible renderers only after the contract exists, with category-specific visuals rather than one universal progress bar.
- quality gate lane: add review checks, scans, tests, and browser-smoke obligations for new/changed indicator surfaces.
- domain migration lane: migrate current domains from the audit inventory in bounded passes, starting with copy-only ambiguities and dashboard/readiness surfaces.

Candidate 8 — Cross-Domain Progress Indicator Semantics Audit

Classification:
- repo-verified audit candidate over existing indicator surfaces
- gap: the product has multiple progress-like cues with different meanings, but no single inventory or semantics classification
- maturity: immediate enterprise UX audit and cleanup foundation
Problem: the same percentage or bar can currently mean incompatible things depending on the surface: execution progress, coverage, review completion, readiness, health, usage, or risk. Without an explicit inventory and classification pass, later component or contract work will still miss ambiguous surfaces and repeat local interpretation drift.
Goal: inventory every current progress-like indicator repo-based and classify what it actually measures.
Scope:
- include OperationRuns, dashboard and tenant dashboard surfaces, workspace or tenant overview, operations-adjacent widgets, baseline compare and drift surfaces, evidence and review surfaces, provider health/readiness, permissions posture, stored reports, supportability, commercial entitlements, and cross-tenant or portfolio views where current repo truth already exposes indicator-like cues
- for every discovered indicator capture: file or component, surface, domain, visible label, visual pattern, data source, calculation basis, category, determinism, likely user interpretation, misunderstanding risk, and recommendation
- classify each instance into exactly one of: execution progress, activity state, coverage, completion, health, readiness, risk, pressure, usage, capacity, score, generation state, or unknown/ambiguous
Out of scope:
- no component migration yet
- no score recalculation program
- no analytics module or charting layer
Acceptance criteria:
- every progress-like indicator found in current repo surfaces is inventoried repo-based
- every inventoried indicator has a documented semantic category
- ambiguous indicators are explicitly marked for cleanup or product decision follow-up
- OperationRun progress is clearly separated from coverage, readiness, risk, score, usage, and generation-state semantics

Candidate 9 — Metric & Indicator Contract Foundation

Classification:
- foundation candidate
- gap: new and existing indicators can still render naked values with no contract for interpretation, freshness, or next action
- maturity: enterprise UX and correctness foundation
Problem: a percentage or score without category, direction, freshness, and explanation invites the wrong operator conclusion. 80% can read as success, risk, consumption, or incomplete work depending on context, and the UI has no shared contract to disambiguate it.
Goal: define one provider-neutral indicator contract so values carry their semantics with them.
Core contract fields:
- id, domain, label, description, category, value, unit, max_value, percentage, direction, severity, freshness, source, calculation_basis, confidence, missing_data_reason, reason, impact, next_action_label, next_action_url, last_updated_at
Required semantics:
- categories must distinguish execution progress, activity state, coverage, completion, health, readiness, risk, pressure, usage, capacity, score, and generation state
- direction must state whether higher is better, lower is better, threshold-based, neutral, inverted, or not numeric
- freshness must state whether data is fresh, stale, unknown, or not applicable
- missing or stale data must not render as a healthy 0% default
Acceptance criteria:
- one documented contract exists as DTO, presenter, view model, or value object chosen repo-based
- new indicator work must use that contract or document why not
- category, direction, and stale/missing-data semantics become explicit instead of local conventions

Candidate 10 — Shared Progress / Indicator Component System

Classification:
- shared-component candidate
- gap: even with a contract, domains can still reinvent visuals and blur semantics again
- maturity: Filament-native UX system follow-through
Problem: once indicator semantics are defined, local Blade, Livewire, or widget implementations can still drift visually if every domain builds its own bars, colors, and labels.
Goal: create a small family of Filament-compatible indicator components chosen by category, not one universal bar.
Proposed family:
- execution progress indicator
- activity state indicator
- coverage indicator
- completion tracker
- health/readiness indicator
- risk/pressure indicator
- usage/capacity indicator
- score indicator
- generation-state indicator
Guardrails:
- category determines which component is allowed
- color semantics must follow direction and category instead of one generic fill rule
- dashboards stay decision-first and summary-first; detail belongs on detail pages
- accessibility must not depend on color alone
Acceptance criteria:
- categories are visually distinguishable
- components consume the shared indicator contract
- no component family implies fake execution progress for risk, health, usage, or generation states without deterministic data

Candidate 11 — Domain Progress Cleanup & Migration Pass

Classification:
- migration and cleanup candidate
- gap: the audit and shared system are not useful if legacy domain surfaces keep their old ad hoc indicators
- maturity: bounded adoption rollout
Problem: old domain-specific indicators will continue to confuse operators unless the product migrates or explicitly retires them after the shared semantics work lands.
Goal: migrate existing domains in bounded passes from the audit inventory onto the new contract and component family.
Scope strategy:
- derive one migration inventory from Candidate 8 with classes such as quick fix, component migration, copy-only change, needs product decision, or defer
- implement the rollout domain by domain instead of in one giant PR
- preferred order: dashboard and tenant dashboard, operations-adjacent widgets, evidence and reviews, provider health and permissions, governance and drift, customer health, commercial entitlements, portfolio or cross-tenant views, and reports or supportability
Guardrails:
- domains keep their own product meaning; they only adopt shared indicator semantics
- label cleanup must prefer specific nouns such as evidence coverage, review completion, provider readiness, permission risk, plan usage, and report generation over generic Progress or Score
Acceptance criteria:
- ambiguous indicators from the audit are either migrated or explicitly deferred with a reason
- progressbar semantics are no longer misused for risk, pressure, readiness, or usage in migrated domains
- dashboard surfaces remain calm and customer-safe where required

Candidate 12 — Progress / Indicator Quality Gates

Classification:
- guardrail and quality-gate candidate
- gap: later contributors can reintroduce local indicator drift even after the first migration wave
- maturity: prevention and regression safety
Problem: without review and test guardrails, new surfaces can still ship their own percentages, widths, and score visuals with no shared meaning.
Goal: make new or changed indicator drift visible early through static checks, contract tests, smoke coverage, and review guidance.
Candidate guardrails:
- static scan for progress-like UI primitives and keywords
- shared component usage rule for new indicator surfaces
- contract tests that reject invalid determinate progress or missing semantics
- focused browser smoke checks on key dashboard, review, provider, and commercial surfaces
- UX checklist that asks what is measured, whether higher is better, how fresh the data is, what happens when data is missing, and what action the operator should take next
Acceptance criteria:
- new or changed indicator surfaces surface deviations visibly
- invalid determinate progress, missing semantics, and stale-data handling are testable
- legacy findings are advisory until migrated, but new or changed work is expected to follow the shared rules

Candidate 13 — Cross-Domain UI Standards & Constitution Patch

Classification:
- documentation and standards candidate
- gap: current standards document has OperationRun-specific progress rules but no durable product-wide indicator taxonomy
- maturity: immediate guardrail follow-through
Problem: without a written product-wide standard, later specs and implementations will keep encoding indicator meaning locally.
Goal: patch docs/ui/tenantpilot-enterprise-ui-standards.md with the canonical cross-domain rules for bars, percentages, scores, meters, readiness states, risk indicators, and generation states.
Patch focus:
- principle: every indicator must state what it measures and how to interpret it
- allowed indicator categories
- direction rules
- determinate-progress eligibility rules
- missing and stale data treatment
- dashboard and customer-safe indicator rules
- anti-patterns such as fake progressbars, unexplained scores, stale data shown as current truth, and usage bars that read like success progress
Acceptance criteria:
- docs/ui/tenantpilot-enterprise-ui-standards.md becomes the canonical reference for cross-domain indicator semantics
- future specs can reference one durable standard instead of rewriting indicator rules locally
Anchors:
- specs/268-operationrun-activity-feedback/spec.md
- specs/270-operationrun-progress-contract/spec.md
- specs/271-counted-progress-rollout/spec.md
- specs/272-operationrun-phase-composite-progress/spec.md
- apps/platform/app/Livewire/BulkOperationProgress.php
- apps/platform/app/Filament/Widgets/Inventory/InventoryKpiHeader.php
- apps/platform/app/Filament/Widgets/Dashboard/RecoveryReadiness.php
- apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php
- apps/platform/app/Services/Baselines/SnapshotRendering/BaselineSnapshotPresenter.php
- apps/platform/app/Services/ReviewPackService.php
- docs/ui/tenantpilot-enterprise-ui-standards.md

Workspace-first / ManagedEnvironment Core Cutover candidate pack

Priority posture: deliberate manual-promotion cutover pack, sequenced as one architecture series rather than reopened through local compatibility slices
Positioning: this is explicitly not a "rename Tenant" candidate. It is a workspace-first / managed-environment core cutover series.
Repo truth: current repo language, pages, reviews, supportability, portfolio, and governance surfaces still rely heavily on Workspace plus Tenant as the central managed boundary. There is no repo-real ManagedEnvironment core yet, while the roadmap and backlog already point toward broader provider-neutral evolution.
Why promotable now: the platform is still in development, with no promised production-data migration or compatibility guarantees, so a clean cutover is safer now than after more tenant-centric and Microsoft-specific core seams accumulate.
Why manual promotion only: this is a strategic architecture pack. It must be promoted deliberately from docs and backlog, not auto-prepped as one giant implementation umbrella or fragmented into dual-read, dual-write, alias, or compatibility-route work.
Numbering note: spec slots 279-287 are currently free and are reserved here for this pack.
Anchors:
- docs/product/roadmap.md
- docs/product/implementation-ledger.md
- specs/043-cross-tenant-compare-and-promotion/spec.md
- specs/247-plans-entitlements-billing-readiness/spec.md
- specs/248-private-ai-policy-foundation/spec.md
- specs/251-commercial-entitlements-billing-state/spec.md
- specs/252-platform-localization-v1/spec.md
- specs/262-lifecycle-governance-taxonomy/spec.md
- specs/264-cross-tenant-promotion-execution/spec.md

Global Cutover Rules

This candidate pack is allowed to perform a clean development-stage cutover.

Hard rules:

No legacy Tenant compatibility layer.
No /admin/t/{tenant} compatibility route.
No dual-read from tenant_id and managed_environment_id.
No dual-write.
No production-data backfill.
No deprecated Tenant model left behind as active domain model.
No new Microsoft-specific fields on ManagedEnvironment.
The term tenant may only remain in provider-specific Microsoft copy, payload metadata, or external terminology such as Microsoft Entra Tenant ID.
Filament tenant context MUST be Workspace.
ManagedEnvironment MUST be a secondary domain context inside a Workspace.

Recommended promotion order

279 Workspace-first Managed Environment Core Cutover
280 Filament Workspace Tenancy & Environment Routing Cutover
281 Provider Connection, Provider Scope & Microsoft Profile Extraction
282 Governance Artifact Retargeting to ManagedEnvironment
283 Provider Capability Registry v1
284 Provider-neutral Artifact Source Taxonomy v1
285 Workspace-first RBAC & Environment Access Scoping
286 UI Copy, IA & Localization Neutralization
287 Cutover Quality Gates & No-Legacy Enforcement

Follow-on candidates after the cutover pack

288 Package Execution Contract v1
289 Guided Operations Recommendation Layer v1
290 Microsoft Governance Package Starter Pack v1
291 Virtual Consultant / External Portal Guidance v1

279 — Workspace-first Managed Environment Core Cutover

Goal: replace the current Tenant-centric core with a provider-agnostic ManagedEnvironment core while keeping Workspace as the primary SaaS and organization context.
Scope:
- introduce App\Models\ManagedEnvironment
- introduce the managed_environments table with workspace_id, external_id or slug, name, display_name, kind, lifecycle_status, metadata, timestamps
- establish Workspace -> ManagedEnvironment as the new core relationship
- replace or remove the active Tenant core model, table, factories, policies, route bindings, and Filament tenancy usage
- move core relations from tenant_id to managed_environment_id
- keep Microsoft-specific identity, Graph, and Intune fields out of ManagedEnvironment
Non-goals:
- no package execution engine
- no guided operations engine
- no virtual consultant
- no new providers beyond re-homing the current Microsoft integration into the new core shape
- no legacy backfill, compatibility routes, dual-schema support, or tenant alias model
Acceptance criteria:
- no active App\Models\Tenant remains
- no core tenants table remains
- core tables reference managed_environment_id instead of tenant_id
- ManagedEnvironment has no Microsoft-specific identity, Graph, or Intune fields
- tests, factories, policies, and seeders use ManagedEnvironment
- repo search for tenant_id finds no active core use

280 — Filament Workspace Tenancy & Environment Routing Cutover

Goal: make the Filament admin panel consistently workspace-first, with Workspace as the Filament tenant and ManagedEnvironment as a nested domain context.
Scope:
- switch Filament tenant context to Workspace
- remove the /admin/t/{tenant} route family
- introduce workspace-first environment routing such as /admin/workspaces/{workspace}/environments/{environment}
- add a workspace dashboard for workspace-wide signals
- add a managed-environment dashboard for environment-scoped signals
- make /admin/workspaces/{workspace}/operations the canonical operations route and link environment pages into it via filters
- align navigation and breadcrumbs to Workspace -> Managed Environment -> domain page
Non-goals:
- no customer portal cutover
- no package engine
- no guided operations rollout
- no legacy /admin/t route
- no second Filament tenancy on the environment level
Acceptance criteria:
- Filament tenant context is Workspace
- ManagedEnvironment is not used as the Filament tenant
- /admin/t/{tenant} no longer exists
- all environment pages live under a workspace path
- operations hub is workspace-level canonical
- breadcrumbs show Workspace -> Managed Environment -> domain page

281 — Provider Connection, Provider Scope & Microsoft Profile Extraction

Goal: move provider-specific identity, scope, permission, and portal semantics out of the core and bind them to provider-aware connection and profile surfaces.
Scope:
- replace provider_connections.tenant_id with provider_connections.managed_environment_id
- standardize a generic provider-scope contract with provider_key, target_scope_kind, target_scope_identifier, external_account_id, and provider_metadata
- extract Microsoft-specific data such as entra_tenant_id, domains, consent state, Graph client identifiers, portal links, and required permissions out of the core
- allow those Microsoft-specific details only in provider metadata, provider credentials, or dedicated Microsoft provider profiles
- update OperationRun start context to use workspace_id, managed_environment_id, provider_connection_id, provider_key, target_scope_kind, and target_scope_identifier
Non-goals:
- no new package engine
- no new provider implementations
- no UI polish pass
- no fallback on tenant_id
- no backfill
Acceptance criteria:
- ProviderConnection references ManagedEnvironment
- provider-specific identity does not live on ManagedEnvironment
- OperationRun context contains provider-neutral scope fields
- Microsoft-specific scope logic sits in Microsoft provider code
- the provider-scope contract can later absorb AWS, Google, or Okta without core changes

282 — Governance Artifact Retargeting to ManagedEnvironment

Goal: move governance-relevant artifacts from tenant semantics to managed-environment semantics while keeping explicit workspace-level artifacts on workspace_id only.
Scope:
- move operation_runs to workspace_id required and managed_environment_id nullable
- retarget inventory, policies, policy versions, backup sets, backup items, restore runs, findings, evidence snapshots, reviews, review packs, and stored reports to managed_environment_id where environment-scoped
- rename tenant-scoped review concepts toward governance- or environment-aware review naming where the current table names are still tenant-bound
- update link builders and URL resolvers to workspace-first and environment-aware routes
- remove remaining links to /admin/t
Non-goals:
- no legacy review type carry-over
- no tenant_id aliases
- no dual relations
- no historical data migration
- no new report engine
Acceptance criteria:
- governance artifacts use managed_environment_id or intentionally only workspace_id
- no active tenant_id foreign keys remain in core governance tables
- operation detail pages work workspace-first
- reviews, evidence, findings, and reports are environment-aware
- canonical URLs contain workspace and optional environment context

283 — Provider Capability Registry v1

Goal: model provider requirements through provider-neutral capability keys so later packages and guided operations do not depend directly on Microsoft permission constants.
Scope:
- introduce a provider capability contract with provider_capability_key, status, reason_code, provider_requirement_key, last_checked_at, and metadata
- use statuses supported, missing, blocked, unknown, and not_applicable
- define business-facing capability keys such as endpoint_inventory_read, endpoint_configuration_read, identity_access_policy_read, identity_admin_role_read, evidence_snapshot_write, review_publish, and provider_permission_check
- evaluate capabilities through provider-specific adapters
- make OperationRun start gates check capability keys instead of raw Microsoft permissions
- show a provider-neutral capability plus a provider-specific remediation hint in the UI
Non-goals:
- no package engine
- no user RBAC rewrite
- no end-user permission management layer
- no AWS or Google implementation yet
- no auto-consent flow
Acceptance criteria:
- provider operations can declare business-facing capability keys
- Microsoft Graph permissions remain mapping details
- capability results are audit-friendly
- later package execution can depend on capability keys instead of provider-specific constants

284 — Provider-neutral Artifact Source Taxonomy v1

Goal: give findings, evidence, stored reports, inventory, and later package outputs a provider-neutral source, detector, and control taxonomy.
Scope:
- standardize source_family, source_kind, provider_key, provider_connection_id, managed_environment_id, source_target_kind, source_target_identifier, detector_key, control_key, and optional package_run_id
- stop treating Entra or Intune type names as core-domain truth in findings and evidence
- represent Microsoft-specific detector details as provider keys, provider object types, or detector keys
- separate canonical domain type, provider object type, and provider display type for inventory metadata
- align stored reports to source-family semantics
Non-goals:
- no new compliance engine
- no full control-catalog expansion
- no historical backfill
- no UI-polish-first scope
Acceptance criteria:
- findings, evidence, and reports can be interpreted provider-neutrally
- Microsoft types remain provider object types or detector keys, not core truth
- later package execution can build on source_family, canonical_type, and control_key
- existing Microsoft outputs remain valid as Microsoft provider sources

285 — Workspace-first RBAC & Environment Access Scoping

Goal: align RBAC with workspace-first tenancy and optional managed-environment scoping.
Scope:
- make WorkspaceMembership the primary access truth
- route workspace access through workspace membership
- prepare optional environment access scopes without requiring environment-level ACL complexity in v1
- update capability resolution for workspace context, optional managed-environment context, and provider capability context
- retarget policies for ManagedEnvironment, ProviderConnection, OperationRun, Finding, EvidenceSnapshot, and governance review surfaces
- keep future customer-safe roles such as Workspace Admin, Governance Operator, Reviewer, Customer Viewer, Support Operator, and Billing Admin feasible
Non-goals:
- no full role productization
- no customer portal RBAC migration
- no mandatory environment-level ACL in v1
- no legacy TenantMembership
Acceptance criteria:
- TenantMembership is removed or fully replaced by WorkspaceMembership
- Filament access is based on WorkspaceMembership
- policies use managed-environment context where appropriate
- later environment scoping can be added without rebuilding the core model

286 — UI Copy, IA & Localization Neutralization

Goal: neutralize generic platform copy, information architecture, and localization keys around workspace-first and provider-neutral vocabulary.
Scope:
- use Workspace, Managed Environment, Provider Connection, Inventory, Evidence, Review, Operation, Finding, and Governance across generic platform surfaces
- keep Tenant, Intune, Microsoft Graph, and Entra only inside Microsoft-provider-specific contexts
- align workspace and environment navigation to workspace-first information architecture
- replace localization keys such as tenant, tenant_review, tenant_dashboard, and managed_tenant with managed-environment or governance-review language
- rewrite empty states toward provider-neutral wording
Non-goals:
- no new design-system spec
- no customer portal redesign
- no new guided operations UX
- no legacy translation-key aliases
Acceptance criteria:
- core UI uses provider-neutral language
- Microsoft-specific terms appear only in Microsoft provider contexts
- navigation is workspace-first
- localization keys no longer carry old tenant-core terminology
- empty states support multi-provider positioning

287 — Cutover Quality Gates & No-Legacy Enforcement

Goal: protect the cutover with tests, static searches, and architecture guardrails so tenant- and Microsoft-core legacy cannot silently return.
Scope:
- add static search gates for App\Models\Tenant, tenant_id, /admin/t, TenantResource, TenantMembership, Microsoft-specific fields on ManagedEnvironment, and Microsoft permission constants inside future package or guidance core code
- keep a narrow allowlist for Microsoft provider adapters, Microsoft translations, external payload metadata, test fixtures, and docs about removed legacy
- add architecture tests for workspace-first tenancy, managed-environment ownership, provider-connection ownership, workspace plus optional environment run scoping, and Microsoft-field exclusion from core models
- add route tests for workspace dashboards, environment dashboards, workspace-level operations, and /admin/t/{tenant} returning 404
- add policy tests for workspace membership, managed-environment access, and cross-workspace denial
- add provider-boundary tests so capability keys stay provider-neutral and Microsoft permission constants remain mapping details
Non-goals:
- no new feature delivery
- no UI polish pass
- no package engine
- no compatibility tests for legacy routes beyond asserting they are gone
Acceptance criteria:
- CI fails when tenant-core terms re-enter the platform core
- CI fails when /admin/t reappears
- CI fails when Microsoft-specific fields land on ManagedEnvironment
- architecture tests document workspace-first and managed-environment-first as the new platform boundary

Priority posture: historical promotion sequence now runs through Specs 301-304; only the conditional navigation-contract-split follow-up remains if post-cutover drift still shows one shared test/registration contract fighting both workspace-home cleanliness and environment-bound admin visibility.
Repo truth: the current runtime is already admin plus system, workspace-first environment routing is repo-real, and Specs 301, 302, 303, and 304 now cover the Inventory cutover, tenant-owned surface audit, Entra Groups cutover, and tenant-panel dead-code guardrail cleanup. The remaining question is whether any residual shared navigation-contract drift still justifies a dedicated split.
Why promotable now: this group remains useful as historical sequencing context and as the home for one bounded residual follow-through candidate. The immediate Inventory break is no longer the active next slice.
Why manual promotion only: any further work should happen only if fresh repo evidence proves the remaining drift. It should stay narrower than reopening the earlier migration sequence or bundling unrelated admin IA decisions.
Anchors:
- docs/product/implementation-ledger.md
- apps/platform/app/Filament/Clusters/Inventory/InventoryCluster.php
- apps/platform/app/Filament/Pages/InventoryCoverage.php
- apps/platform/app/Filament/Resources/InventoryItemResource.php
- apps/platform/app/Filament/Resources/EntraGroupResource.php
- apps/platform/app/Filament/Concerns/WorkspaceScopedEnvironmentRoutes.php
- apps/platform/app/Support/OperateHub/OperateHubShell.php
- apps/platform/tests/Feature/Filament/PanelNavigationSegregationTest.php
- apps/platform/tests/Feature/Filament/InventoryCoverageAdminTenantParityTest.php
- apps/platform/tests/Feature/Filament/EntraGroupAdminScopeTest.php
Recommended promotion order:
1. admin-inventory-navigation-cutover -> Spec 301
2. tenant-owned-surface-route-audit -> Spec 302
3. admin-directory-groups-cutover -> Spec 303
4. tenant-panel-dead-code-retirement -> Spec 304
5. navigation-contract-split, only if drift remains after Specs 301-304

`admin-inventory-navigation-cutover`

Status: promoted to Spec 301 on 2026-05-14. Keep this entry as historical sequencing context unless the Inventory visibility contract regresses.
Goal: restore Inventory as a workspace-environment-scoped admin surface without reopening the workspace-home sidebar or broadening the repair into other tenant-owned domains.
Scope:
- remove the blanket admin-hidden navigation behavior for Inventory only where a real admin workspace environment context exists
- keep the workspace-home sidebar clean when no environment context is active
- align InventoryCoverage with the canonical admin workspace/environment route and remembered environment-context contract instead of preserving an older hide-first navigation seam
- narrow the current navigation and segregation tests so they no longer protect the blanket rule that admin can never see Inventory
Non-goals:
- no Entra Groups navigation decision
- no generic tenant-owned surface audit
- no tenant-panel dead-code retirement
- no system-panel or workspace-home information-architecture overhaul
Acceptance criteria:
- Inventory Items and Inventory Coverage are reachable and visible from an environment-bound admin context
- Inventory remains absent from the workspace-home sidebar when no environment context is active
- InventoryCoverage follows the canonical admin context contract instead of relying on a hide-first admin navigation assumption
- tests distinguish workspace-home cleanliness from environment-context visibility for Inventory

`tenant-owned-surface-route-audit`

Status: promoted to Spec 302 on 2026-05-14. Keep this entry as historical sequencing context unless the audit findings need a refreshed follow-up after new tenant-owned surfaces land.
Goal: produce a repo-verified audit and repair-prep inventory of admin-reachable tenant-owned surfaces that are fully migrated, partially migrated, stale-nav hidden, product-decision blocked, or still legacy dependent.
Scope:
- audit routes, shouldRegisterNavigation(), context resolution, global search, and high-signal runtime tests across tenant-owned admin surfaces
- classify each audited surface as migrated, partial cutover, stale panel logic, valid context gate, valid RBAC, ambiguous product IA, or dead-code dependent
- produce one bounded repair-prep order with explicit blockers and no broad runtime enablement
Non-goals:
- no mass re-enablement of hidden navigation
- no broad runtime migration bundle
- no information-architecture decision for groups, support, or diagnostics surfaces beyond explicit classification
- no dead-code deletion except documenting remaining dependencies
Acceptance criteria:
- one repo-verified audit matrix exists for tenant-owned admin surfaces
- every audited surface is assigned one migration state and one recommended next action
- follow-up work is split into bounded candidates instead of one umbrella migration spec

`admin-directory-groups-cutover`

Status: promoted to Spec 303 on 2026-05-14. Keep this entry as historical sequencing context unless the chosen Directory/Groups contract regresses.
Goal: decide and implement the correct admin workspace role for Directory / Entra Groups after an explicit information-architecture decision.
Scope:
- decide whether groups belong in primary navigation, a secondary Identity/Directory lane, or only contextual entry points from diagnostics, permissions, providers, or policy detail
- align navigation, route/context handling, and search/detail entry behavior with that chosen contract
- update tests so they enforce the chosen admin contract instead of the current blanket hide assumption
Non-goals:
- no generic M365 Admin mirror
- no broad identity-center product surface
- no bundling with the Inventory repair slice
- no tenant-panel dead-code cleanup in the same spec
Acceptance criteria:
- the admin role of Directory / Entra Groups is explicit and documented in the spec
- list, detail, and search behavior all align with that chosen contract
- navigation and tests no longer conflict with repo-real admin runtime access

`navigation-contract-split`

Status: conditional follow-up only after Specs 301-304. Promote this only if fresh repo evidence still shows workspace-home cleanliness and environment-bound admin visibility fighting through one shared contract.
Goal: separate workspace-home clean-sidebar rules from environment-bound tenant-owned navigation rules so future repairs do not keep fighting one shared test contract.
Scope:
- split tests and guards for workspace-home navigation, environment-shell navigation, and surface-specific registration behavior
- normalize the distinction between tenant-sensitive home-sidebar entries and legitimate environment-bound admin surfaces
- promote only if post-Inventory, post-audit, and post-groups work still shows residual contract drift
Non-goals:
- no broad feature rollout by itself
- no new information architecture by itself
- no dead-code retirement
- no generic navigation redesign unrelated to the split contract
Acceptance criteria:
- workspace-home cleanliness and environment-context visibility are enforced independently
- one failing contract no longer forces blanket hidden assertions onto unrelated admin environment surfaces

`tenant-panel-dead-code-retirement`

Status: promoted to Spec 304 and implemented as a cleanup/guardrail slice on 2026-05-15. Keep this entry as historical sequencing context unless a future repo audit shows the retired Tenant Panel runtime or /admin/t route family has regressed.
Goal: remove remaining dead tenant-panel and /admin/t artifacts only after active surfaces and tests no longer rely on them.
Scope:
- delete legacy tenant-panel provider and obsolete /admin/t compatibility anchors that are no longer needed after the cutover follow-through
- tighten tests and guardrails around no retired tenant panel, no /admin/t runtime route, and no stale admin-hidden assumptions that only existed for the former panel split
- keep any remaining historical references explicitly documented as historical only
Non-goals:
- no primary runtime migration
- no feature-surface enablement
- no mixed compatibility layer or phased legacy bridge
Acceptance criteria:
- no active runtime dependency on the tenant panel remains
- docs and tests clearly separate historical references from live runtime contracts
- guardrails fail if /admin/t or retired tenant-panel runtime logic returns

Decision Register Evidence / OperationRun Link Polish

Historical priority: 1
Status: promoted to Spec 307 and implemented as a narrow productization follow-up on 2026-05-15; keep this entry as historical sequencing context unless proof/run link polish regresses.
Repo truth: Spec 265, Spec 307, DecisionRegister, GovernanceDecisionRegisterBuilder, FindingException detail handoff, evidence/report proof links, source/evidence OperationRun links, and focused tests are repo-verified. The broad Decision Register & Approval Workflow v1 candidate is no longer an open Greenfield candidate.
Why promoted: Spec 306 classified the current register as partial productization and identified the narrowest next step as proof-link polish, not a rebuild.
Why manual promotion only: this must stay a deliberate product choice because the follow-up should only expose existing evidence/report and OperationRun truth where it already exists, preserve existing approval/closure ownership, and avoid a new workflow engine.
Anchors:
- specs/265-decision-register-approval/spec.md
- specs/307-decision-register-evidence-operationrun-link-polish/spec.md
- specs/306-decision-register-reconciliation/decision-register-reconciliation.md
- specs/250-decision-governance-inbox/spec.md
- specs/257-governance-decision-convergence/spec.md
- docs/product/roadmap.md

Decision Register Customer-Safe Summary / Review-Pack Inclusion (historical)

Historical priority: 1
Status: promoted to Spec 308 and implemented on 2026-05-15; keep this entry as historical sequencing context only.
Repo truth: Spec 265 proves the bounded operator Decision Register, Spec 306 reconciles the current runtime, Spec 307 closes direct evidence/report plus source/evidence OperationRun proof-link polish, and Spec 308 adds repo-real customer-safe Decision Summary plus review-derived Review Pack inclusion.
Why no longer active: the customer-safe summary/review-pack inclusion question has been answered by Spec 308. The remaining productization gap is Customer Review Workspace v1 Completion and broader Decision-Based Governance Inbox v1, not another Decision Register v1.
Why historical only: reopening this would risk duplicating the completed summary/export contract or rebuilding the operator register instead of finishing the customer-facing workspace and decision workflow.
Anchors:
- specs/265-decision-register-approval/spec.md
- specs/306-decision-register-reconciliation/decision-register-reconciliation.md
- specs/307-decision-register-evidence-operationrun-link-polish/spec.md
- specs/308-decision-register-summary-review-pack/spec.md
- specs/308-decision-register-summary-review-pack/plan.md
- specs/258-customer-review-productization/spec.md
- specs/260-governance-service-packaging/spec.md
- apps/platform/app/Filament/Pages/Governance/DecisionRegister.php
- apps/platform/app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php
- apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php
- apps/platform/app/Jobs/GenerateReviewPackJob.php

Governance Artifact Lifecycle & Retention v1

Priority: 6
Repo truth: lifecycle taxonomy, artifact-truth semantics, and point retention rules already exist, but governance artifacts still lack one productized lifecycle runtime contract.
Why promotable now: this is the clearest new trust and auditability gap highlighted by the deep research.
Why manual promotion only: it crosses lifecycle, artifact, export, retention, and suspension semantics and therefore needs an explicit product boundary rather than automatic prep.
Anchors:
- specs/158-artifact-truth-semantics/spec.md
- specs/262-lifecycle-governance-taxonomy/spec.md
- docs/product/standards/lifecycle-governance.md

Billing & Subscription Truth Layer v1

Priority: 4
Repo truth: plans, entitlements, and commercial lifecycle maturity are already spec-backed, but the billing/subscription truth layer is still missing.
Why promotable now: deep-research alignment moves commercial trust and lifecycle closer to the now lane, even though the remaining unspecced slice is still the narrower billing/subscription follow-through.
Why manual promotion only: the broad readiness work is already covered, so this should not reappear as an automatic foundation candidate.
Anchors:
- specs/247-plans-entitlements-billing-readiness/spec.md
- specs/251-commercial-entitlements-billing-state/spec.md

Customer-Facing Localization Adoption v1

Priority: 2
Repo truth: the localization foundation is already spec-backed; the open gap is customer-facing adoption, glossary completion, and productized surface coverage.
Why promotable now: localization is now a productization follow-through task, not a greenfield foundation.
Why manual promotion only: the broad foundation is already covered, so only a narrower adoption slice should be promoted deliberately.
Anchors:
- specs/252-platform-localization-v1/spec.md
- specs/258-customer-review-productization/spec.md
- specs/260-governance-service-packaging/spec.md

Enterprise Access Boundary & Support Access Governance v1

Priority: 7
Repo truth: break-glass and platform access seams are documented, but no bounded support-access governance package currently exists.
Why promotable now: this is the narrow early access-governance slice that should happen before broad SSO/SCIM ambitions if support access and customer-visible auditability become pressing.
Why manual promotion only: the right cut is product-sensitive and must stay tightly bounded around support access, delegated access, TTL, approval, audit trail, and operator-context visibility.
Anchors:
- docs/audits/2026-03-09-enterprise-rbac-scope-audit.md
- docs/HANDOVER.md
- specs/065-tenant-rbac-v1/spec.md
- specs/066-rbac-ui-enforcement-helper/spec.md

Stored Reports Surface v1

Priority: P2 follow-up after customer-facing review, localization, decision inbox, commercial truth, promotion execution, and artifact lifecycle
Repo truth: the stored-reports substrate is already grounded by evidence and review foundations, but the product surface remains incomplete.
Why promotable now: this is the cleanest path from retained governance artifacts to a customer- and operator-usable surface.
Why manual promotion only: this is a focused product-surface follow-up, not an unprepared foundation gap.
Anchors:
- specs/153-evidence-domain-foundation/spec.md
- specs/155-tenant-review-layer/spec.md
- specs/260-governance-service-packaging/spec.md
- docs/product/implementation-ledger.md

Workspace & Tenant Closure Lifecycle v1

Priority: P2 follow-up after artifact lifecycle direction is settled
Repo truth: lifecycle taxonomy is already explicitly captured as a spec-backed foundation, but closure/runtime follow-through is still open.
Why promotable now: it is the next bounded runtime slice after the taxonomy-first package.
Why manual promotion only: it must remain a deliberate follow-up and not collapse back into an automatic reopening of the broader taxonomy work.
Anchors:
- specs/262-lifecycle-governance-taxonomy/spec.md

First Governed AI Runtime Consumer v1

Priority: 8
Repo truth: the private AI governance foundation is already spec-backed, but there is still no first real governed runtime consumer.
Why promotable now: it is the clearest bounded follow-up once higher-priority sellability, promotion, and commercial-truth gaps are addressed.
Why manual promotion only: the foundation already exists, so the next move must be an explicit runtime-use-case decision rather than a repeated foundation-prep cycle.
Anchors:
- specs/248-private-ai-policy-foundation/spec.md

Deferred / Existing Drafts Outside the Current Queue

These items are still useful, but they are not the next best open specs from the current repo state.

2026-05-01 explicit promotion note: Workspace, Tenant & Managed Object Lifecycle Governance v1 was promoted intentionally, not automatically, into Spec 262 (lifecycle-governance-taxonomy). The history below is retained so the manual-promotion rationale and the auto-prep boundary remain visible.

Workspace, Tenant & Managed Object Lifecycle Governance v1

Priority: P2 — Important hardening / enterprise trust
Status: Promoted intentionally via explicit product decision -> Spec 262 (lifecycle-governance-taxonomy)
Do not auto-prep from next-best-prep: this candidate stays intentionally outside the active queue even after the 2026-05-01 repo re-audit. Promote it only through an explicit roadmap/product decision.
Why the retained history still sits outside the active queue: the repo now has spec-backed follow-through for customer review productization, governance convergence, compare/preflight, commercial lifecycle maturity, compliance mapping, governance packaging, support-desk handoff, and the findings cleanup trio. This lifecycle-governance work was promoted intentionally as a taxonomy-first package and must remain outside the automatic queue rather than being treated as an opportunistic next-best-prep target.
Why this replaces Policy Lifecycle / Ghost Policies: A policy-only ghost lifecycle spec risks introducing local deletion semantics, Laravel SoftDeletes, or overloaded ignored_at behavior before TenantPilot has a clear platform lifecycle taxonomy. The real roadmap-fit problem is broader: TenantPilot needs consistent lifecycle truth for workspaces, tenants, managed provider objects, evidence, backups, restoreability, export, retention, and purge.
Problem: Lifecycle concerns currently appear across separate product areas such as policies, restore flows, commercial state, workspace entitlements, backup history, evidence snapshots, audit, support, and workspace administration. Without one shared taxonomy, local fixes can collapse different meanings into the same field or UI label: provider object missing, local TenantPilot record deleted, operator ignored the item, workspace suspended, data retained for compliance, data eligible for purge, or restore no longer possible.
Product goal: Define an enterprise-grade lifecycle model before implementing destructive or retention-sensitive workflows. TenantPilot must distinguish at least these dimensions:
- Local record lifecycle: active, archived, locally removed, purge scheduled, purged
- Provider presence lifecycle: present, missing from provider, provider deleted, reappeared
- Operator suppression lifecycle: visible, ignored / suppressed, restored to visibility
- Commercial / workspace lifecycle: trial, active, grace, suspended read-only, closed
- Retention / compliance lifecycle: retained, export requested, deletion requested, deletion scheduled, legal hold / retention hold, purge due, purged
- Restoreability lifecycle: restorable, metadata only, blocked by dependency, not restorable, expired by retention
Smallest useful v1: Do not implement deletion flows immediately. First define the lifecycle taxonomy, naming rules, state boundaries, audit expectations, OperationRun expectations, retention boundaries, and implementation guardrails for future specs.
Questions v1 must answer:
- What does “deleted” mean in TenantPilot?
- What does “missing from provider” mean?
- What does “ignored” mean?
- What happens when a tenant is removed from a workspace?
- What happens when a workspace is suspended or closed?
- What data remains visible in read-only or suspended states?
- What data must be exportable before deletion?
- What data is retained for audit, evidence, or legal reasons?
- What can be purged, and what must never be purged automatically?
- Which lifecycle transitions require explicit human confirmation?
- Which transitions require audit events?
- Which transitions require OperationRun truth?
- Which transitions affect restore eligibility?
Explicit non-goals for v1:
- no immediate workspace deletion implementation
- no immediate tenant deletion implementation
- no purge engine
- no hard-delete workflow
- no policy-only ghost lifecycle patch
- no Laravel SoftDeletes rollout
- no migration that reinterprets existing ignored_at data
- no new lifecycle dashboard or workboard
- no new restore engine
- no payment-provider or billing integration
Expected follow-up specs after taxonomy approval:
1. Provider-Missing Managed Object Truth v1 — explicit provider-missing state for policies and later other managed objects, no local deletion semantics, restore continuity where backup-backed history exists.
2. Workspace & Tenant Closure Lifecycle v1 — close workspace, remove tenant from workspace, define read-only / suspended / closed behavior, no destructive purge yet.
3. Data Export Before Deletion v1 — export customer-owned evidence, reports, audit-relevant artifacts, restore metadata, and tenant/workspace records before deletion.
4. Retention & Purge Governance v1 — retention periods, legal hold, purge eligibility, irreversible deletion confirmation, and audit trail.
5. Restoreability Expiry & Evidence Retention v1 — distinguish restorable backup payloads from retained evidence/audit metadata and define when restore is no longer possible but evidence remains retained.
Roadmap fit: This is not a P0 sales feature. It is a P2 enterprise trust and compliance hardening candidate that becomes important before serious production customer offboarding, destructive data operations, or regulated retention commitments. It must not block Customer Review Workspace Productization, Governance Decision Surface Convergence, or Cross-Tenant Compare & Promotion.
Candidate decision: Explicitly promoted as Spec 262 (lifecycle-governance-taxonomy) through a manual product decision. Keep the promotion taxonomy-first and keep near-term policy fixes, closure flows, export-before-delete, retention/purge, and restoreability expiry as separate follow-up slices rather than treating Spec 262 as a runtime umbrella implementation.
Workspace-level PII override for review packs: bounded deferred follow-up from Spec 109.
CSV export for filtered run metadata: valid system-console follow-up, but not near the top of the queue.
Raw error/context drilldowns for system console: useful operator enhancement, but not ahead of current P0-P2 gaps.
UI polish snippets such as dashboard sparklines, density toggles, louder attention cards, or chooser refinements: keep out of the active spec queue until they become bounded release work.

Promoted to Spec

Historical ledger for candidates that are no longer open. Keep them here so prioritization stays clean without losing decision history.

Cross-Tenant Compare and Promotion v1 -> Spec 043 (cross-tenant-compare-and-promotion)
Canonical Operation Type Source of Truth -> Spec 239 (canonical-operation-type-source-of-truth)
Self-Service Tenant Onboarding & Connection Readiness -> Spec 240 (tenant-onboarding-readiness)
Support Diagnostic Pack -> Spec 241 (support-diagnostic-pack)
Operational Controls & Feature Flags -> Spec 242 (operational-controls)
Product Usage & Adoption Telemetry -> Spec 243 (product-usage-adoption-telemetry)
Product Knowledge & Contextual Help -> Spec 244 (product-knowledge-contextual-help)
Customer Health Score -> Spec 245 (customer-health-score)
In-App Support Request with Context -> Spec 246 (support-request-context)
Plans, Entitlements & Billing Readiness -> Spec 247 (plans-entitlements-billing-readiness)
Private AI Execution & Policy Foundation -> Spec 248 (private-ai-policy-foundation)
Customer Review Workspace v1 -> Spec 249 (customer-review-workspace)
Decision-Based Governance Inbox v1 -> Spec 250 (decision-governance-inbox)
Commercial Entitlements and Billing-State Maturity -> Spec 251 (commercial-entitlements-billing-state)
Remove Findings Lifecycle Backfill Runtime Surfaces -> Spec 253 (remove-findings-backfill-runtime-surfaces)
Remove Legacy Acknowledged Finding Status Compatibility -> Spec 254 (remove-acknowledged-compat)
Enforce Creation-Time Finding Invariants -> Spec 255 (enforce-finding-creation-invariants)
External Support Desk / PSA Handoff -> Spec 256 (external-support-desk-handoff)
Governance Decision Surface Convergence -> Spec 257 (governance-decision-convergence)
Customer Review Workspace Productization v1 -> Spec 258 (customer-review-productization)
Compliance Evidence Mapping v1 -> Spec 259 (compliance-evidence-mapping)
Governance-as-a-Service Packaging v1 -> Spec 260 (governance-service-packaging)
Provider-Missing Policy Visibility & Restore Continuity v1 -> Spec 261 (provider-missing-policy-visibility)
Workspace, Tenant & Managed Object Lifecycle Governance v1 -> Spec 262 (lifecycle-governance-taxonomy)
Auditor Pack Delivery & Executive Export v1 -> Spec 263 (auditor-pack-executive-export)
Cross-Tenant Promotion Execution v1 -> Spec 264 (cross-tenant-promotion-execution)
Decision Register & Approval Workflow v1 -> Spec 265 (decision-register-approval), reconciled by Spec 306, proof-link-polished by Spec 307, and customer-safe/review-pack-included by Spec 308; broad Greenfield scope closed, broader Governance Inbox / Customer Review Workspace completion remains separate
Decision Register Reconciliation -> Spec 306 (decision-register-reconciliation)
Decision Register Evidence / OperationRun Link Polish -> Spec 307 (decision-register-evidence-operationrun-link-polish)
Decision Register Customer-Safe Summary / Review-Pack Inclusion -> Spec 308 (decision-register-summary-review-pack)
RBAC Role Matrix & Access Boundary Audit -> Spec 309 (rbac-role-matrix-access-boundary-audit)
Queued Execution Reauthorization and Scope Continuity -> Spec 149 (queued-execution-reauthorization)
Livewire Context Locking and Trusted-State Reduction -> Spec 152 (livewire-context-locking)
Evidence Domain Foundation -> Spec 153 (evidence-domain-foundation)
Exception / Risk-Acceptance Workflow for Findings -> Spec 154 (finding-risk-acceptance)
Operator Outcome Taxonomy and Cross-Domain State Separation -> Spec 156 (operator-outcome-taxonomy)
Operator Reason Code Translation and Humanization Contract -> Spec 157 (reason-code-translation)
Governance Artifact Truthful Outcomes & Fidelity Semantics -> Spec 158 (artifact-truth-semantics)
Operator Explanation Layer for Degraded / Partial / Suppressed Results -> Spec 161 (operator-explanation-layer)
Request-Scoped Derived State and Resolver Memoization -> Spec 167 (derived-state-memoization)
Tenant Governance Aggregate Contract -> Spec 168 (tenant-governance-aggregate-contract)
Record Page Header Discipline & Contextual Navigation -> Spec 192 (record-header-discipline)
Monitoring Surface Action Hierarchy & Workbench Semantics -> Spec 193 (monitoring-action-hierarchy)
Governance Friction & Operator Vocabulary Hardening -> Spec 194 (governance-friction-hardening)
Governance Operator Outcome Compression -> Spec 214 (governance-outcome-compression)
Provider-Backed Action Preflight and Dispatch Gate Unification -> Spec 216 (provider-dispatch-gate)
Finding Ownership Semantics Clarification -> Spec 219 (finding-ownership-semantics)
Humanized Diagnostic Summaries for Governance Operations -> Spec 220 (governance-run-summaries)
Findings Operator Inbox v1 -> Spec 221 (findings-operator-inbox)
Findings Intake & Team Queue v1 -> Spec 222 (findings-intake-team-queue)
Findings Notifications & Escalation v1 -> Spec 224 (findings-notifications-escalation)
Assignment Hygiene & Stale Work Detection -> Spec 225 (assignment-hygiene)
Findings Notification Presentation Convergence -> Spec 230 (findings-notification-convergence)
Finding Outcome Taxonomy & Verification Semantics -> Spec 231 (finding-outcome-taxonomy)
Operation Run Link Contract Enforcement -> Spec 232 (operation-run-link-contract)
Operation Run Active-State Visibility & Stale Escalation -> Spec 233 (stale-run-visibility)
Provider Boundary Hardening -> Spec 237 (provider-boundary-hardening)

Superseded / Removed From Active Queue

These items were previously open candidates or roadmap-fit ideas, but should no longer stay in the active queue.

The former 2026-04-30 active P0-P2 queue was cleared on 2026-05-01 because refreshed Spec 043 and Specs 251-260 now cover those slices, and several of those packages already include implementation close-out or completed-task history.
R2.0 Canonical Control Catalog Foundation: remove from active candidates because the ledger shows a repo-real catalog, config, bindings, review integration, and test coverage. This is no longer an open candidate; it is an implemented foundation.
Self-Service Tenant Onboarding & Connection Readiness: remove from active candidates because it is already Spec 240 and the repo already shows meaningful adoption.
Support Diagnostic Pack: remove from active candidates because it is already Spec 241 and repo-adopted.
Operational Controls & Feature Flags: remove from active candidates because it is already Spec 242 and repo-adopted.
Product Usage & Adoption Telemetry: remove from active candidates because it is already Spec 243 and repo-adopted.
Product Knowledge & Contextual Help: remove from active candidates because it is already Spec 244; any remaining work should be narrower follow-ups, not a repeated top-level candidate.
Customer Health Score: remove from active candidates because it is already Spec 245 and repo-adopted.
In-App Support Request with Context: remove from active candidates because it is already Spec 246 and repo-implemented.
Plans, Entitlements & Billing Readiness: remove as a broad active candidate because Spec 247 already exists and the remaining open gap is narrower commercial lifecycle maturity.
Private AI Execution & Policy Foundation: remove from the active queue because Spec 248 already exists.
Localization v1: remove as a broad active candidate because the locale foundation is already repo-real; the remaining work is surface adoption, copy/glossary completion, and customer-facing polish inside narrower productization or UI-maturity follow-ups.
Company-ops items such as Lead Capture & CRM Pipeline, AVV / DPA / TOM / Legal Pack, Vendor Questionnaire Answer Bank, Business Continuity / Founder Backup Plan, and similar operating artifacts should remain outside the active product-spec queue unless a concrete product slice emerges.

114 KiB Raw Blame History

Spec Candidates

Candidate Rules

Current Source-Of-Truth Boundary

Deep-Research Alignment Reference (non-queue)

Customer Review Workspace v1

Decision-Based Governance Inbox + Decision Register Follow-up

Governance Artifact Lifecycle & Retention v1

Commercial Entitlements & Billing-State Lifecycle v1

External Support Desk / PSA Handoff v1

Customer-Facing Localization v1

Cross-Tenant Compare & Promotion with Lineage v1

Governance Service Packaging v1

Enterprise Access Boundary & Support Access Governance v1

Private AI Execution Governance Foundation v1

Active Candidate Queue

Promotable Candidate Backlog

Recommended Next Candidate Sequence After Spec 311

Post-311 Legacy / Productization / Scope follow-up candidates

Customer Review Workspace v1 Completion

Provider Connection Scope Hardening

Canonical Link / Query Cleanup

Product Truth / Docs Drift Cleanup

Environment Resource Context Follow-through

Legacy Compatibility / Dead Code Retirement

Environment Helper Naming Follow-through

OperationRun Activity Feedback & UI Governance candidate group

OperationRun / Execution Truth maturity follow-up queue

269 — OperationRun Terminal Outcome Feedback

273 — Tenant Dashboard Active Operations Summary Card

270 — OperationRun Progress Contract v1

271 — Counted Progress Rollout v1

272 — OperationRun Phase & Composite Progress v1

Cross-Domain Progress / Indicator Semantics candidate group

Candidate 8 — Cross-Domain Progress Indicator Semantics Audit

Candidate 9 — Metric & Indicator Contract Foundation

Candidate 10 — Shared Progress / Indicator Component System

Candidate 11 — Domain Progress Cleanup & Migration Pass

Candidate 12 — Progress / Indicator Quality Gates

Candidate 13 — Cross-Domain UI Standards & Constitution Patch

Workspace-first / ManagedEnvironment Core Cutover candidate pack

Global Cutover Rules

Recommended promotion order

Follow-on candidates after the cutover pack

279 — Workspace-first Managed Environment Core Cutover

280 — Filament Workspace Tenancy & Environment Routing Cutover

281 — Provider Connection, Provider Scope & Microsoft Profile Extraction

282 — Governance Artifact Retargeting to ManagedEnvironment

283 — Provider Capability Registry v1

284 — Provider-neutral Artifact Source Taxonomy v1

285 — Workspace-first RBAC & Environment Access Scoping

286 — UI Copy, IA & Localization Neutralization

287 — Cutover Quality Gates & No-Legacy Enforcement

Admin Workspace Navigation & Tenant-owned Surface Repair candidate group

admin-inventory-navigation-cutover

tenant-owned-surface-route-audit

admin-directory-groups-cutover

navigation-contract-split

tenant-panel-dead-code-retirement

Decision Register Evidence / OperationRun Link Polish

Decision Register Customer-Safe Summary / Review-Pack Inclusion (historical)

Governance Artifact Lifecycle & Retention v1

Billing & Subscription Truth Layer v1

Customer-Facing Localization Adoption v1

Enterprise Access Boundary & Support Access Governance v1

Stored Reports Surface v1

Workspace & Tenant Closure Lifecycle v1

First Governed AI Runtime Consumer v1

Deferred / Existing Drafts Outside the Current Queue

Workspace, Tenant & Managed Object Lifecycle Governance v1

Promoted to Spec

Superseded / Removed From Active Queue

114 KiB

Raw Blame History

`admin-inventory-navigation-cutover`

`tenant-owned-surface-route-audit`

`admin-directory-groups-cutover`

`navigation-contract-split`

`tenant-panel-dead-code-retirement`