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