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)*

- [x] 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`
  - [x] `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.