ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
a7df5c9adb
TenantAtlas/docs/product/spec-candidates.md
Ahmed Darrazi a7df5c9adb
Some checks failed
PR Fast Feedback / fast-feedback (pull_request) Failing after 8m56s
Details
chore: commit all changes (automated)
2026-05-04 14:09:40 +02:00

672 lines
52 KiB
Markdown
Raw Blame History

# Spec Candidates
> **Status:** Active
> **Last reviewed:** 2026-05-04
> **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-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**: Now
- **Current repo truth**: Specs 249 and 258, plus the implementation ledger and current review surfaces, already prove the foundational and productization path for customer-safe review consumption.
- **Problem**: Customer-safe review consumption remains the clearest sellability gap whenever review truth, accepted risks, evidence, and package delivery 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 v1
- **Status markers**: repo-verified, productization gap, roadmap recommendation
- **Roadmap lane**: Now
- **Current repo truth**: governance inbox, findings queues, operations attention, review follow-up, and Specs 250 and 257 already anchor the decision surface, but there is still no bounded decision-register follow-through.
- **Problem**: Findings, alerts, runs, and reviews still need one calmer decision layer with ownership, due state, reason, impact, next action, linked evidence, linked `OperationRun`, accepted-risk path, closure reason, and escalation hooks.
- **Deep-Research-derived sharpening**: treat the missing slice as decision-register and approval/closure follow-through over current inbox foundations, not as another queue page.
- **Non-goals**: no generic Kanban board, no PSA clone, no XDR incident console.
### Governance Artifact Lifecycle & Retention v1
- **Status markers**: foundation-only, roadmap recommendation, spec candidate
- **Roadmap lane**: Now
- **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**: Next
- **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**: Next
- **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`.
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.
### 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`
### Decision Register & Approval Workflow v1
- **Priority**: 1
- **Repo truth**: governance inbox and convergence are spec-backed and partly repo-real, but the bounded decision-register and approval workflow is still a distinct follow-up gap.
- **Why promotable now**: it is the highest-value unspecced operator follow-through once inbox and review consumption are already grounded.
- **Why manual promotion only**: this must stay a deliberate product choice because v1 should remain narrow: owner, due date, status, reason, impact, next action, linked evidence, linked `OperationRun`, accepted-risk path, closure reason, escalation hook, and optional approval or closure semantics without autonomous remediation.
- **Anchors**:
- `specs/250-decision-governance-inbox/spec.md`
- `specs/257-governance-decision-convergence/spec.md`
- `docs/product/roadmap.md`
### Governance Artifact Lifecycle & Retention v1
- **Priority**: 2
- **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**: 3
- **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**: 4
- **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**: 5
- **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**: 6
- **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**: 7
- **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`)
- 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.
Reference in New Issue View Git Blame Copy Permalink