TenantAtlas/docs/product/spec-candidates.md

# Spec Candidates

> **Status:** Active  
> **Last reviewed:** 2026-05-01  
> **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-01 repo-based queue re-audit against current `specs/` truth, including refreshed Spec 043 and Specs 251-260; stale active candidates were cleared and no new candidate was promoted.
>
> 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.

## 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`.

`Workspace, Tenant & Managed Object Lifecycle Governance v1` remains deferred below and still requires an explicit product decision before it becomes a safe prep target.

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

### Workspace, Tenant & Managed Object Lifecycle Governance v1

- **Priority**: P2 — Important hardening / enterprise trust
- **Status**: Strategic candidate, not ready for immediate implementation
- **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 it stays deferred after the queue cleanup**: 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. The remaining lifecycle-governance question is still broader than the current automatic queue and must stay taxonomy-first rather than opportunistically selected.
- **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**: Keep as strategic candidate. Do not let near-term policy fixes expand into a general ghost-policy, deletion, or retention model before the lifecycle taxonomy is agreed. The bounded policy-only exception is now Spec 261 (`provider-missing-policy-visibility`); keep that spec isolated to provider-missing truth and restore continuity rather than treating it as partial completion of this broader taxonomy.

- `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`)
- 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.