ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/345-platform-productization-readiness-roadmap-reconciliation-gate/plan.md
ahmido 1f3a8b5ed9 docs: platform productization readiness and roadmap reconciliation (spec 345) (#417) 
Added comprehensive documentation and planning artifacts for the platform productization readiness and roadmap reconciliation.

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #417
2026-06-02 10:47:29 +00:00

13 KiB
Raw Permalink Blame History

Implementation Plan: Spec 345 - Platform Productization Readiness & Roadmap Reconciliation Gate

Branch: 345-platform-productization-readiness-roadmap-reconciliation-gate | Date: 2026-06-02 | Spec: specs/345-platform-productization-readiness-roadmap-reconciliation-gate/spec.md Input: Feature specification from specs/345-platform-productization-readiness-roadmap-reconciliation-gate/spec.md

Summary

Spec 345 is a docs-only readiness gate. The implementation is a single repo-truth reconciliation pass across product docs, active spec packages, UI audits, current Filament surfaces, and existing tests/browser artifacts. No runtime code is changed. The deliverable is a completed decision package: readiness report, candidate reconciliation, roadmap reconciliation, app-boundary map, and next-spec recommendation.

Technical Context

Language/Version: Markdown documentation, shell inspection, Laravel 12.52 / Filament 5.2.1 / Livewire 4.1.4 as audited runtime context
Primary Dependencies: existing spec packages, docs/product/*, docs/ui-ux-enterprise-audit/*, Laravel Boost read-only inspection tools
Storage: N/A - no runtime storage change
Testing: none for runtime behavior; docs integrity checks only
Validation Lanes: N/A / docs-only
Target Platform: repository docs under specs/345-platform-productization-readiness-roadmap-reconciliation-gate/
Project Type: single Laravel/Filament product audit package
Performance Goals: complete one bounded reconciliation pass without spawning new implementation scope
Constraints: no runtime changes, no route/model/service/test edits, no candidate deletion without reason, no customer portal implementation
Scale/Scope: current product docs, recent spec packages, key UI audit reports, and read-only inspection of current apps/platform surfaces

UI / Surface Guardrail Plan

  • Guardrail scope: no operator-facing surface change
  • Affected routes/pages/actions/states/navigation/panel/provider surfaces: N/A - inspection only
  • No-impact class, if applicable: docs-only
  • Native vs custom classification summary: N/A
  • Shared-family relevance: review-only across existing shared families
  • State layers in scope: none changed; shell/page/detail/URL-query are audited only
  • Audience modes in scope: operator-MSP, support-platform, customer-safe output as audit targets only
  • Decision/diagnostic/raw hierarchy plan: evaluate current hierarchy, but do not change it
  • Raw/support gating plan: audit current behavior only
  • One-primary-action / duplicate-truth control: assess current surfaces and reflect remaining gaps in reports
  • Handling modes by drift class or surface: report-only
  • Repository-signal treatment: review-mandatory for stale roadmap/candidate claims, report-only for runtime findings outside scope
  • Special surface test profiles: N/A
  • Required tests or manual smoke: none required for this spec; existing browser/test evidence may be cited
  • Exception path and spread control: none
  • Active feature PR close-out entry: N/A
  • UI/Productization coverage decision: No UI surface impact
  • Coverage artifacts to update: none by default
  • No-impact rationale: this package audits current surfaces without changing rendered UI
  • Navigation / Filament provider-panel handling: read-only audit only
  • Screenshot or page-report need: no new screenshots required unless a future follow-up spec reruns browser audit work

Shared Pattern & System Fit

  • Cross-cutting feature marker: yes
  • Systems touched: docs/product/spec-candidates.md, docs/product/roadmap.md, docs/product/implementation-ledger.md, docs/ui-ux-enterprise-audit/*, recent spec repo-truth maps, recent implementation reports
  • Shared abstractions reused: repo-truth maps, readiness language, UI audit page reports, implementation-ledger maturity terms
  • New abstraction introduced? why?: none
  • Why the existing abstraction was sufficient or insufficient: sufficient as evidence sources, insufficient as a single current reconciliation answer after recent platform work
  • Bounded deviation / spread control: none; no new runtime or process framework is introduced

OperationRun UX Impact

  • Touches OperationRun start/completion/link UX?: no
  • Central contract reused: N/A
  • Delegated UX behaviors: N/A
  • Surface-owned behavior kept local: audit only
  • Queued DB-notification policy: N/A
  • Terminal notification path: N/A
  • Exception path: none

Provider Boundary & Portability Fit

  • Shared provider/platform boundary touched?: no runtime change
  • Provider-owned seams: audited only (ProviderConnectionResource, onboarding/readiness surfaces)
  • Platform-core seams: audited only (WorkspaceContext, workspace/environment shell, governance/evidence/review surfaces)
  • Neutral platform terms / contracts preserved: workspace, managed environment, provider connection, evidence, review pack, governance decision, customer-safe output
  • Retained provider-specific semantics and why: existing Microsoft-shaped runtime seams remain unchanged; the audit only flags where future work still risks spreading them further
  • Bounded extraction or follow-up path: future follow-up spec if readiness review shows provider-boundary work is still blocking productization

Constitution Check

Spec 345 is a docs-only gate and does not create runtime behaviors. Constitution-sensitive implications are therefore audit-only:

  • Inventory-first, read/write separation, RBAC, OperationRun, audit, and provider-boundary rules are checked as current repo truth, not changed.
  • No new persistence, abstraction, status family, or UI framework is introduced, so proportionality and anti-bloat rules pass by staying read-only.
  • No destructive actions, Graph calls, Filament panel changes, or global search changes are introduced.

Implementation Scope Gate

The implementation is limited to:

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

No other files are in scope unless the user explicitly asks for bounded candidate-doc updates later.

Repo Sources To Reconcile

Product docs

  • docs/product/spec-candidates.md
  • docs/product/roadmap.md
  • docs/product/implementation-ledger.md
  • docs/product/discoveries.md

UI audit inputs

  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/follow-up-specs/325-strategic-target-image-implementation-candidates.md
  • key page reports for workspace overview, environment dashboard, operations, governance inbox, decision register, customer review workspace, audit log, provider connections, reviews, and finding exceptions queue

Recent spec truth

  • specs/326-customer-review-workspace-v1-productization/
  • specs/327-governance-inbox-decision-first-workbench-productization/
  • specs/328-operations-hub-decision-first-workbench-productization/
  • specs/329-evidence-audit-log-disclosure-productization/
  • specs/337-evidence-review-pack-product-process-flow-alignment/
  • 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/

Runtime inspection surfaces (read-only)

  • apps/platform/app/Filament/Pages/
  • apps/platform/app/Filament/Resources/
  • apps/platform/resources/views/filament/pages/
  • apps/platform/tests/Feature/
  • apps/platform/tests/Browser/

Technical Approach

Phase 1 - Baseline and source discovery

Record current branch/worktree state, list candidate and roadmap sources, and explicitly separate active queue sources from historical or audit-only sources.

Phase 2 - Candidate reconciliation

Classify each discovered candidate lane into A-G, collapsing duplicate historical entries where the repo already shows a later spec or a superseding runtime slice. Do not silently delete history; instead, mark covered items as covered and active items as still open.

Phase 3 - Roadmap reconciliation

Map roadmap themes to current repo truth. Distinguish themes that are already repo-real from those that are still productization gaps, spec-only, or roadmap-only.

Phase 4 - Platform readiness audit

Use current code paths, recent spec close-outs, UI audit reports, and existing test/browser artifacts to score each major platform area. Report blockers and confidence level without pretending that unrun tests were re-validated in this spec.

Phase 5 - Boundary map and next-spec sequence

Separate platform work from customer portal, website, and system work. Use the readiness and candidate maps to pick one primary next spec and an ordered follow-up sequence.

Domain / Model Implications

No domain model or schema changes. The plan only references existing domain truth such as:

  • Workspace
  • ManagedEnvironment
  • EnvironmentReview
  • EnvironmentReviewAcknowledgement
  • EvidenceSnapshot
  • ReviewPack
  • StoredReport
  • Finding
  • FindingException
  • OperationRun
  • ProviderConnection

These models are evidence for readiness, not modification targets.

UI / Filament Implications

No Filament runtime code changes are planned. The plan audits current surfaces only. Filament v5 on Livewire v4 remains the runtime posture; provider registration remains in apps/platform/bootstrap/providers.php.

Livewire Implications

No Livewire runtime changes. Existing Livewire/Filament page behavior is assessed through repo truth only.

RBAC / Policy Implications

No authorization behavior changes. The reports must preserve and describe:

  • workspace membership as the first isolation boundary,
  • managed-environment or record-level entitlement as the second boundary where applicable,
  • 404 for out-of-scope/non-member access,
  • 403 for in-scope actors missing capability,
  • customer-safe output vs operator/support diagnostics separation.

Audit / Evidence / Operation Implications

No new audit events, evidence flows, or OperationRun behaviors are introduced. The plan only evaluates whether existing proof, evidence, review, and audit surfaces are productized enough.

Data / Migration Implications

None. No migrations, data backfills, schema changes, or compatibility work are allowed in Spec 345.

Test Strategy

Because Spec 345 is docs-only:

  • Do not run the full application test suite by default.
  • Reuse existing test and browser evidence from recent spec packages as repo truth.
  • Validate only documentation integrity and worktree safety:
    • git status --short --branch
    • git diff --stat
    • git diff --check

If the user later requests additional confidence, targeted runtime test commands can be proposed as a separate follow-up step, not assumed inside this spec.

Rollout Considerations

  • Runtime rollout: none
  • Deployment impact: none
  • Migration impact: none
  • Queue / scheduler impact: none
  • Storage / asset impact: none
  • Filament assets: unchanged; existing filament:assets deployment posture remains untouched

Risk Controls

  • Keep edits inside the Spec 345 package only.
  • Treat completed or implementation-closed specs as read-only historical evidence.
  • Do not reopen or normalize earlier spec history.
  • Mark uncertain themes as candidate only, roadmap only, or deferred instead of guessing implementation maturity.
  • Do not use the audit to justify unrequested runtime fixes.

Implementation Phases

  1. Baseline repo state and source discovery
  2. Candidate inventory and A-G classification
  3. Roadmap theme reconciliation
  4. Platform readiness scoring and blocker inventory
  5. App-boundary mapping
  6. Next-spec recommendation
  7. Docs-only validation and checklist close-out