TenantAtlas/specs/345-platform-productization-readiness-roadmap-reconciliation-gate/spec.md

Feature Specification: Spec 345 - Platform Productization Readiness & Roadmap Reconciliation Gate

Feature Branch: 345-platform-productization-readiness-roadmap-reconciliation-gate
Created: 2026-06-02
Status: Draft
Type: Readiness audit / roadmap reconciliation / productization gate / backlog governance
Runtime posture: Read-only first. No feature implementation. Documentation, classification, and follow-up scoping only.
Input: User-provided Spec 345 draft plus repo truth from docs/product/*, specs/*, docs/ui-ux-enterprise-audit/*, and current apps/platform surfaces.

Spec Candidate Check (mandatory — SPEC-GATE-001)

• Problem: TenantPilot has accumulated many real platform slices, follow-up candidates, and roadmap themes, but the repo lacks one current-answer package for productization readiness, backlog hygiene, and app-boundary discipline after recent Specs 338, 342, 343, and 344.
• Today's failure: The product can keep shipping feature-by-feature while candidate status, roadmap wording, and real runtime maturity drift apart. That creates a concrete risk of starting /customerportal too early, duplicating already-finished work, or prioritizing the wrong next spec.
• User-visible improvement: Product direction becomes explicit and reviewable: the repo gets one source package that says what is already productized, what is merely repo-real, what is still missing before a sellable MSP/operator platform, what belongs in /platform, and what must stay deferred to /customerportal or /website.
• Smallest enterprise-capable version: One bounded, docs-only reconciliation pass that inspects current repo truth, classifies candidates, maps roadmap themes to implementation state, scores platform readiness, and recommends the next 3-7 specs without adding any runtime feature.
• Explicit non-goals: No routes, migrations, models, services, jobs, Filament resources/pages, views, tests, assets, or customer portal work. No navigation rebuild. No backlog deletion without explanation. No "analysis paralysis" multi-pass program.
• Permanent complexity imported: One spec package with readiness and reconciliation reports only. No new persisted truth, enum family, abstraction layer, or runtime taxonomy.
• Why now: Recent specs materially improved the platform, especially Customer Review Workspace, but docs/product/spec-candidates.md, docs/product/roadmap.md, and older product-truth artifacts predate that latest repo state. The next spec choice should be made from current truth, not stale backlog wording.
• Why not local: Fixing one candidate note or one roadmap paragraph would not answer the core question: whether the platform is productized enough to keep pushing /platform work or should pivot to a different app boundary.
• Approval class: Core Enterprise.
• Red flags triggered: Broad audit scope, cross-document reconciliation, and potential taxonomy drift. Defense: this spec is bounded to one read-only pass, reuses existing repo vocabulary, and forbids runtime expansion.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Candidate source: Directly user-provided as Spec 345; supported by docs/product/spec-candidates.md, docs/product/roadmap.md, docs/product/implementation-ledger.md, and UI audit follow-up ledgers.
• Completed-spec check: No specs/345-* package or 345-* branch existed before this work. Completed or implementation-closed specs are context only and must not be rewritten or normalized back into prep state.
• Related completed context:
  • specs/338-workspace-environment-resource-scope-contract/
  • specs/339-provider-connection-scope-hardening/
  • specs/340-post-scope-contract-browser-verification-gate/
  • specs/341-canonical-link-query-cleanup/
  • specs/342-customer-review-workspace-final-consumption-productization/
  • specs/343-customer-review-attestation-accepted-risk-lifecycle/
  • specs/344-customer-review-workspace-density-audience-polish/
• Close alternatives deferred:
  • starting a new feature spec without reconciling backlog truth,
  • starting /customerportal work inside Filament /platform,
  • broad roadmap rewrite without file-level repo evidence,
  • runtime cleanup disguised as a planning spec.

Spec Scope Fields (mandatory)

• Scope: canonical-view
• Primary Routes:
  • Audited surfaces only; no route changes:
    • /admin
    • /admin/workspaces/{workspace}/overview
    • /admin/workspaces/{workspace}/environments/{environment}
    • /admin/reviews/workspace
    • /admin/governance/inbox
    • /admin/governance/decisions
    • /admin/workspaces/{workspace}/operations
    • /admin/evidence/overview
    • /admin/audit-log
    • /admin/provider-connections
• Data Ownership: No data model or ownership change. This spec only audits current workspace-owned, environment-owned, review-owned, and system-owned surfaces.
• RBAC: No authorization behavior changes. The reports must verify existing membership/capability boundaries and keep /platform, /customerportal, /website, and /system responsibilities explicit.

For canonical-view handling:

• Default filter behavior when tenant-context is active: Preserve current repo truth only. Workspace hubs remain workspace-owned and may narrow through explicit page-local filters such as environment_id; environment-bound pages stay route-owned.
• Explicit entitlement checks preventing cross-tenant leakage: Audit and document existing deny-as-not-found and capability posture only. No new checks are introduced by Spec 345.

UI Surface Impact (mandatory — UI-COV-001)

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage (mandatory when UI Surface Impact is not "No UI surface impact"; otherwise write N/A - no reachable UI surface impact plus rationale)

• Route/page/surface: N/A - no reachable UI surface impact
• Current or new page archetype: N/A
• Design depth: N/A
• Repo-truth level: repo-verified docs-only work
• Existing pattern reused: existing productization audit and spec-artifact patterns
• New pattern required: none
• Screenshot required: no; screenshots remain optional unless a future browser audit reruns evidence capture
• Page audit required: no new page audit; existing page reports are read-only inputs
• Customer-safe review required: yes, as an audit lens only
• Dangerous-action review required: yes, as an audit lens only; no runtime action changes
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - no reachable UI surface impact
• No-impact rationale when applicable: Spec 345 inspects current UI surfaces and productization evidence but does not change runtime UI, navigation, copy, actions, or state.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): navigation entry points, evidence/report viewers, governance decision surfaces, dashboard/workbench maturity, productization/audit follow-up lanes
• Systems touched: docs/product/spec-candidates.md, docs/product/roadmap.md, docs/product/implementation-ledger.md, docs/ui-ux-enterprise-audit/*, recent spec packages, and current Filament pages/resources as read-only evidence
• Existing pattern(s) to extend: repo-truth maps, spec close-out artifacts, UI audit page reports, implementation ledger maturity language
• Shared contract / presenter / builder / renderer to reuse: none in runtime; this is documentation-level reuse only
• Why the existing shared path is sufficient or insufficient: existing artifacts already contain the needed evidence, but no single package currently reconciles them after recent platform productization work
• Allowed deviation and why: none
• Consistency impact: keep vocabulary stable across repo truth: workspace/environment, customer-safe output, evidence, review pack, accepted risk, governance inbox, decision register, provider readiness, monitoring, /platform, /customerportal, /website, /system
• Review focus: prevent duplicate or stale candidate wording from being treated as active truth once repo evidence shows the work is already implemented or belongs to a different boundary

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: no
• Shared OperationRun UX contract/layer reused: N/A
• Delegated start/completion UX behaviors: N/A
• Local surface-owned behavior that remains: audit-only classification of existing OperationRun-linked surfaces
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• Shared provider/platform boundary touched?: no runtime boundary change
• Boundary classification: N/A - audit only
• Seams affected: provider readiness, provider connections, and workspace/environment boundary docs are inspected as existing truth only
• Neutral platform terms preserved or introduced: /platform, /customerportal, /website, /system, workspace, managed environment, provider connection, evidence, review pack, governance decision
• Provider-specific semantics retained and why: existing Microsoft-shaped runtime seams remain as-is; this spec only documents where follow-up work still deepens or avoids that coupling
• Why this does not deepen provider coupling accidentally: no code, model, or taxonomy changes are introduced
• Follow-up path: document-in-feature only

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

N/A - no operator-facing surface change.

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no runtime artifact; docs-only report files inside the spec package only
• New abstraction?: no
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: no; reuse existing bucket language from the user-provided spec
• Current operator problem: unclear productization status and stale backlog wording make it hard to choose the next safe platform spec
• Existing structure is insufficient because: the evidence exists, but it is spread across spec packages, candidate ledgers, roadmap themes, and UI audit files without one current reconciliation
• Narrowest correct implementation: one documentation-only reconciliation pass with explicit reports and a next-spec recommendation
• Ownership cost: limited to keeping the Spec 345 package current if future roadmap/productization reviews reuse it
• Alternative intentionally rejected: a broad roadmap rewrite or runtime cleanup pass, because either would expand beyond the immediate decision need
• Release truth: current-release truth

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by a later implementation spec.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: N/A
• Validation lane(s): N/A
• Why this classification and these lanes are sufficient: Spec 345 is docs-only. Validation is limited to repo inspection and documentation integrity checks.
• New or expanded test families: none
• Fixture / helper cost impact: none
• Heavy-family visibility / justification: none
• Special surface test profile: N/A
• Standard-native relief or required special coverage: none
• Reviewer handoff: verify report consistency and that no runtime files changed
• Budget / baseline / trend impact: none
• Escalation needed: none
• Active feature PR close-out entry: N/A
• Planned validation commands:
  • git status --short --branch
  • git diff --stat
  • git diff --check

Summary

TenantPilot should answer one product question before starting the next major feature slice:

Is the current /platform control plane productized enough for MSP/operator use, and which backlog items are still real after recent specs?

Spec 345 is the readiness gate for that answer. It:

1. builds a repo-truth readiness view for the current platform,
2. reconciles spec candidates and roadmap themes against actual repo state,
3. separates /platform, /customerportal, /website, and /system boundaries, and
4. recommends the next implementation specs without starting a new runtime feature.

Problem Statement

TenantPilot now has strong repo-real foundations and several productized strategic surfaces, but product direction is vulnerable to drift because:

• newer specs have closed or narrowed older backlog items,
• roadmap wording still reflects pre-342/343/344 product gaps,
• customer-safe consumption work could be misread as a cue to start a full customer portal,
• some candidate groups are already covered, while others are still only prepared or still truly open,
• the platform may be demoable before it is fully sellable, and those are not the same decision.

Without a reconciliation gate, /platform, /customerportal, /website, and /system responsibilities can blur and the next spec can be chosen from stale assumptions.

Product Intent

Immediate priority:

Make the platform control plane sellable and MSP/operator usable before opening a separate customer portal product surface.

The platform should first provide stable, trusted outputs:

• review packages
• evidence summaries
• findings and accepted-risk states
• governance decisions
• operations/proof links
• customer-safe handoff data
• clear workspace/environment scope
• operator-ready workflows

Only after those outputs are stable should /customerportal consume them.

Goals

G1 - Establish a platform productization readiness view

Assess whether the current /platform app is productized enough for MSP/operator usage, covering at minimum:

• Workspace/Environment shell
• Customer Review Workspace
• Evidence Overview / Review Packs
• Governance Inbox / Decision Register
• Findings / Accepted Risks
• Provider Readiness / Onboarding
• Monitoring / Operations / Alerts / Audit
• Localization / copy quality
• Test and browser confidence

G2 - Reconcile spec candidates

Classify every discovered candidate into:

• A - Now platform-critical
• B - Platform productization
• C - Feature expansion
• D - Customer Portal / /customerportal
• E - Website / /website
• F - Covered / obsolete / duplicate
• G - Research / roadmap only

G3 - Reconcile roadmap vs repo truth

Map roadmap themes to actual repo state:

• repo-real and productized
• repo-real but not productized
• partially implemented
• candidate only
• roadmap only
• deferred / external app

G4 - Separate app boundaries

Clarify what future work belongs to:

• /platform
• /customerportal
• /website
• /system

G5 - Recommend the next implementation specs

Recommend the next 3-7 specs and clearly separate:

• must-do-before-sellable
• should-do-next
• defer
• do-not-build-now
• move-to-customerportal
• move-to-website

G6 - Avoid creating new product scope

This spec is a gate, not a new feature slice. It must not create runtime behavior.

Non-Goals

This spec must not:

• build Customer Portal
• add new customer-facing routes
• implement a new Filament page or dashboard
• add new database tables
• refactor workspace/environment routing
• change app runtime behavior
• rebuild navigation
• fix all UI findings
• implement PSA/ITSM handoff
• implement Provider Readiness runtime changes
• implement Localization overhaul
• implement AI runtime consumers
• delete candidate history without explanation

Inputs

The audit must inspect and reconcile:

• current specs under specs/
• at minimum recent Specs 338, 343, and 344 plus adjacent productization specs
• docs/product/spec-candidates.md
• docs/product/roadmap.md
• docs/product/implementation-ledger.md
• docs/product/discoveries.md
• docs/ui-ux-enterprise-audit/*
• read-only runtime surfaces under apps/platform/app/Filament/, apps/platform/resources/views/filament/, and apps/platform/tests/

Output Artifacts

Required outputs in specs/345-platform-productization-readiness-roadmap-reconciliation-gate/:

• spec.md
• plan.md
• tasks.md
• repo-truth-map.md
• platform-readiness-report.md
• candidate-reconciliation.md
• roadmap-reconciliation.md
• app-boundary-map.md
• next-spec-recommendation.md
• checklists/requirements.md

Optional:

• artifacts/screenshots/ only if a future browser audit captures new screenshots

Classification Model

Candidate buckets

• A - Now platform-critical: required before the platform can be considered sellable/MSP-ready
• B - Platform productization: improves existing platform surfaces without creating major new features
• C - Feature expansion: useful capability, but not required for immediate platform sellability
• D - Customer Portal: belongs to future /customerportal, not Filament /platform
• E - Website: belongs to /website
• F - Covered / obsolete / duplicate: already implemented, replaced, or superseded
• G - Research / roadmap only: not ready for implementation

Readiness states

• 1 - Productized
• 2 - Functional but not productized
• 3 - Partially implemented
• 4 - Candidate only
• 5 - Roadmap only
• 6 - Deferred / external app

Platform Areas To Assess

Assess and report on:

• Workspace / Environment shell
• Customer Review Workspace
• Evidence / Review Pack outputs
• Governance Inbox / Decision Register
• Findings / Accepted Risks
• Provider Connections / Readiness / Onboarding
• Monitoring / Operations / Alerts / Audit
• Localization / Copy / Customer-safe language
• Test and browser confidence

App Boundary Rules

/platform

Internal MSP/operator/admin control plane. Allowed: Filament, operations, evidence generation, review workspace, governance inbox, accepted risks, findings workflow, provider readiness, audit log, internal acknowledgement, and customer-safe output preparation.

/customerportal

External customer consumption plane. Allowed later: customer-facing review summaries, evidence downloads, accepted-risk summaries, findings/follow-ups, review history, customer-safe documents, branding, and customer language.

/website

Marketing and public product website. Allowed later: landing pages, pricing, docs, lead generation.

/system

Platform operator / break-glass / system administration. Keep separate from /platform tenant/workspace behavior.

Required Reports

Spec 345 must produce:

• repo-truth-map.md
• platform-readiness-report.md
• candidate-reconciliation.md
• roadmap-reconciliation.md
• app-boundary-map.md
• next-spec-recommendation.md
• checklists/requirements.md

Each report must stay repo-grounded and distinguish current runtime truth from candidate-only or roadmap-only ideas.

Acceptance Criteria

AC1 - Read-only posture preserved

No runtime app files are changed.

AC2 - Every candidate classified

All discovered candidates are classified into A-G with no unknown remainder.

AC3 - Roadmap reconciled to repo truth

Roadmap themes are mapped to implemented/productized/partial/candidate-only/roadmap-only/deferred states.

AC4 - App boundaries are explicit

Reports clearly separate /platform, /customerportal, /website, and /system.

AC5 - Platform readiness is assessed

The package answers:

• Is the platform ready for MSP/operator daily use?
• Is it demoable?
• Is it sellable?
• What blocks it?

AC6 - Next spec recommendation is concrete

One primary next spec and a follow-up sequence are named with rationale.

AC7 - No feature expansion sneaks in

No routes, migrations, controllers, Filament pages, customer portal pages, services, models, or runtime UI changes are introduced.

AC8 - Known quality risks are documented

Broad merge-readiness or full-suite readiness must not be claimed without evidence.

AC9 - Requirements checklist passes

checklists/requirements.md confirms the package is complete and internally consistent.

Risks

• Analysis paralysis: mitigate by limiting the work to one reconciliation pass and one next-spec recommendation.
• Candidate volume: mitigate by merging duplicate themes and classifying at candidate-lane level where the repo already groups them that way.
• Customer Portal drift: mitigate by explicit boundary mapping and by not selecting /customerportal as the default next spec.
• Runtime changes sneaking in: mitigate with read-only guard and git diff --check.
• Roadmap rewrite without repo truth: mitigate by citing real specs, code paths, tests, and audit artifacts.

Validation Commands

Required:

• git status --short --branch
• git diff --stat
• git diff --check

No runtime test suite is required for this docs-only spec unless explicitly requested later.

Definition Of Done

Spec 345 is complete when:

• the full spec package exists,
• candidate, roadmap, and readiness reports are filled from repo truth,
• app boundaries are explicit,
• the next-spec recommendation is concrete,
• platform blockers are prioritized,
• no runtime files changed,
• git diff --check passes,
• and the final response states the recommended next implementation spec and why.