From 18401479d22bcb5aba91d375cafa70f089879c40 Mon Sep 17 00:00:00 2001 From: Ahmed Darrazi Date: Fri, 15 May 2026 16:49:35 +0200 Subject: [PATCH] docs: reconcile product truth after specs 307-309 --- docs/product/implementation-ledger.md | 49 +- docs/product/roadmap.md | 56 ++- docs/product/spec-candidates.md | 75 ++- .../checklists/requirements.md | 48 ++ .../plan.md | 426 ++++++++++++++++++ .../spec.md | 317 +++++++++++++ .../tasks.md | 115 +++++ 7 files changed, 1022 insertions(+), 64 deletions(-) create mode 100644 specs/310-product-truth-docs-drift-reconciliation/checklists/requirements.md create mode 100644 specs/310-product-truth-docs-drift-reconciliation/plan.md create mode 100644 specs/310-product-truth-docs-drift-reconciliation/spec.md create mode 100644 specs/310-product-truth-docs-drift-reconciliation/tasks.md diff --git a/docs/product/implementation-ledger.md b/docs/product/implementation-ledger.md index 3f76cc3a..bcbdc6fb 100644 --- a/docs/product/implementation-ledger.md +++ b/docs/product/implementation-ledger.md @@ -4,7 +4,7 @@ # TenantPilot Implementation Ledger > **Last reviewed:** 2026-05-15 > **Use for:** Repo-based implementation status and product-surface maturity assessment > **Do not use for:** Roadmap priority, spec priority, or proof that tests were executed in the current branch -> **Scoped maintenance:** 2026-05-15 Decision Register proof-link implementation update after Spec 307; 2026-05-15 Decision Register reconciliation update after Spec 306; 2026-05-15 Tenant Panel dead-code retirement guardrail update after Spec 304; 2026-05-12 roadmap/ledger alignment after the admin workspace navigation and tenant-owned surface repair candidate intake from the repo-verified navigation/panel audit; 2026-05-06 ledger conflict cleanup plus alignment with `docs/product/roadmap.md` and `docs/product/spec-candidates.md` after the cross-domain indicator candidate intake and the current manual-promotion backlog review. +> **Scoped maintenance:** 2026-05-15 Spec 310 product-truth/docs-drift reconciliation after Specs 307-309; 2026-05-15 Spec 309 RBAC role matrix and access boundary hardening update; 2026-05-15 Spec 308 customer-safe Decision Summary and Review Pack inclusion update; 2026-05-15 Decision Register proof-link implementation update after Spec 307; 2026-05-15 Decision Register reconciliation update after Spec 306; 2026-05-15 Tenant Panel dead-code retirement guardrail update after Spec 304; 2026-05-12 roadmap/ledger alignment after the admin workspace navigation and tenant-owned surface repair candidate intake from the repo-verified navigation/panel audit; 2026-05-06 ledger conflict cleanup plus alignment with `docs/product/roadmap.md` and `docs/product/spec-candidates.md` after the cross-domain indicator candidate intake and the current manual-promotion backlog review. ## Purpose @@ -14,7 +14,7 @@ ## Purpose - Repo-basiert only: Aussagen zaehlen nur, wenn Code, Datenmodell, Workflow, UI-Adoption oder Test-Artefakte im Repo belastbar darauf hinweisen. - Keine Roadmap- oder Spec-Absicht ohne Repo-Evidence. -- Produkt-Posture wird nur mit `foundation-only`, `implemented but not productized`, `fast sellable`, `sellable` oder `not implemented` beschrieben. +- Produkt-Posture nutzt als Basis `foundation-only`, `implemented but not productized`, `fast sellable`, `sellable` oder `not implemented`; seit Spec 310 duerfen belegte Product-Truth-Labels wie `repo-real`, `open gap`, `historical` oder `security-hardening completed` in Statusnotizen oder kombinierten Tabellenzellen ergaenzen. - `sellable` wird nur dort verwendet, wo UI, Workflow, Datenmodell, RBAC/Audit und passende Test-Artefakte plausibel zusammenpassen. - `fast sellable` bedeutet: repo-real und kunden- oder operatornah genug, aber die letzte produktisierte Delivery-, Packaging- oder Self-Serve-Schicht fehlt noch. - `implemented but not productized` bedeutet: reale Oberflaechen oder Workflows existieren, aber sie sind noch nicht als ruhige, wiederholbare Produkt-Slice zusammengezogen. @@ -23,7 +23,7 @@ ## Purpose ## Current Product Position -TenantPilot ist aktuell ein starkes internes Governance- und Operations-Produkt mit belastbaren Foundations fuer Execution Truth, Baselines/Drift, Findings, Evidence, Reviews, Review Packs, Supportability, Telemetry, Safety Controls und eine repo-reale governed AI policy foundation. Darauf sitzen inzwischen mehrere repo-real productization slices: eine customer-safe Review-/Governance-Package-Surface im Admin-Kontext, released-review detail handoff, compliance interpretation overlays, bounded external support-desk handoff, commercial lifecycle state handling mit read-only gating, eine kanonische cross-tenant compare preview mit promotion preflight sowie ein repo-verifizierter operatorseitiger Decision Register ueber bestehender FindingException-Decision-Truth mit direkter proof/run link polish. Die Repo-Wahrheit liegt damit klar ueber einer simplen Lesart von "R1 done / R2 partial" und auch ueber einer rein foundation-only Interpretation fuer Reviews, Support und Portfolio-Preparation. Gleichzeitig ist das Produkt noch nicht voll als kundenseitig konsumierbare Portfolio- und Commercial-Plattform ausgereift: Es fehlen die letzte customer-safe self-serve productization ueber der Review-Surface, actual portfolio promotion execution, Decision-Register-Review-Pack-/customer-safe follow-through, wiederholbare Billing-/Subscription-Truth, eine klarere Stored-Reports-Surface und der erste governed AI runtime consumer ueber der bereits repo-realen AI policy foundation. +TenantPilot ist aktuell ein starkes internes Governance- und Operations-Produkt mit belastbaren Foundations fuer Execution Truth, Baselines/Drift, Findings, Evidence, Reviews, Review Packs, Supportability, Telemetry, Safety Controls und eine repo-reale governed AI policy foundation. Darauf sitzen inzwischen mehrere repo-real productization slices: eine customer-safe Review-/Governance-Package-Surface im Admin-Kontext, released-review detail handoff, customer-safe Decision Summary und Review Pack inclusion aus Spec 308, compliance interpretation overlays, bounded external support-desk handoff, commercial lifecycle state handling mit read-only gating, eine kanonische cross-tenant compare preview mit promotion preflight sowie ein repo-verifizierter operatorseitiger Decision Register ueber bestehender FindingException-Decision-Truth mit direkter proof/run link polish. Die Repo-Wahrheit liegt damit klar ueber einer simplen Lesart von "R1 done / R2 partial" und auch ueber einer rein foundation-only Interpretation fuer Reviews, Support und Portfolio-Preparation. Gleichzeitig ist das Produkt noch nicht voll als kundenseitig konsumierbare Portfolio- und Commercial-Plattform ausgereift: Es fehlen die letzte customer-safe self-serve productization ueber der Review-Surface, actual portfolio promotion execution, Decision-Based Governance Inbox completion, wiederholbare Billing-/Subscription-Truth, eine klarere Stored-Reports-Surface und der erste governed AI runtime consumer ueber der bereits repo-realen AI policy foundation. ## Runtime Guardrails @@ -37,6 +37,17 @@ ## Status Model - `sellable`: belastbare UI-, Workflow-, RBAC/Audit- und Test-Spur mit wiederholbarem Produktversprechen - `not implemented`: noch kein belastbarer repo-real Slice fuer das eigentliche Ziel +Spec-310-Truth-Labels fuer Statusnotizen: + +- `repo-real`: Code, Runtime-Oberflaeche, Tests oder akzeptierte Spec-Close-out-Evidence belegen den Slice im Repo +- `implemented`: Runtime existiert, Produktreife kann aber variieren +- `spec-backed`: formaler Spec existiert, Implementierung ist nicht automatisch vollstaendig +- `historical`: abgeschlossen, promoted oder nur noch Sequencing-Kontext +- `superseded`: durch spaetere Spec- oder Runtime-Wahrheit ersetzt +- `open gap`: braucht weiterhin Produkt- oder Technikarbeit +- `security-hardening completed`: Sicherheits-/Access-Hardening wurde spezifisch verifiziert und adressiert +- `decision needed`: Produkt- oder Architekturentscheidung vor Umsetzung noetig + Evidence-Level im Dokument: - `none`: keine belastbare Repo-Evidence @@ -49,9 +60,9 @@ ## Roadmap Coverage Summary | Roadmap Area | Product posture | Evidence Level | UI Ready | Tested | Sellable | Notes | |---|---|---:|---|---|---|---| | R1 Golden Master Governance | sellable | strong | yes | repo tests, not run | yes | Baselines, Drift, Findings und OperationRun-Truth sind breit im Produkt verankert. | -| R2 Tenant Reviews, Evidence & Control Foundation | fast sellable | strong | yes | repo tests, not run | yes | Reviews, Evidence, Review Packs, Customer Review Workspace, governance-package delivery, compliance interpretation overlays und Control-/Exception-Layer greifen als reale Governance-Surface zusammen; die letzte customer-safe self-serve productization bleibt offen. | +| R2 Tenant Reviews, Evidence & Control Foundation | fast sellable | strong | yes | repo tests, not run | yes | Reviews, Evidence, Review Packs, Customer Review Workspace, governance-package delivery, customer-safe Decision Summary / Review Pack inclusion, compliance interpretation overlays und Control-/Exception-Layer greifen als reale Governance-Surface zusammen; die letzte customer-safe self-serve productization bleibt offen. | | Alert escalation + notification routing | sellable | strong | partial | repo tests, not run | yes | Alert-Regeln, Dispatch, Cooldown und Quiet Hours sind real. | -| Governance & Architecture Hardening | foundation-only | strong | partial | repo tests, not run | no | Viele Hardening-Slices sind bereits im Code, die Lane bleibt als platform seam work aktiv. | +| Governance & Architecture Hardening | foundation-only | strong | partial | repo tests, not run | no | Viele Hardening-Slices sind bereits im Code; Spec 309 ist als `security-hardening completed` fuer RBAC role matrix und admin/system access boundary abgeschlossen, waehrend breitere Support Access Governance separat offen bleibt. | | UI & Product Maturity Polish | implemented but not productized | strong | partial | partial repo tests, not run | no | Empty States, Navigation, Localization und read-only Review-Polish sind real, aber kein geschlossenes Theme-Completion-Signal; admin workspace navigation drift remains explicit manual-promotion follow-through. | | Secret & Security Hardening | fast sellable | strong | yes | repo tests, not run | yes | Provider-Verifikation, Permission-Diagnostics und Redaction sind belastbar. | | Baseline Drift Engine (Cutover) | sellable | strong | yes | repo tests, not run | yes | Compare- und Drift-Workflow wirken als produktive Kernfunktion. | @@ -81,12 +92,14 @@ ## Implemented Capabilities | Drift findings and governance pressure | sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/Finding.php`; `app/Filament/Widgets/Dashboard/RecentDriftFindings.php`; `tests/Feature/Findings/*` | | Findings inboxes and governance inbox | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Filament/Pages/Findings/MyFindingsInbox.php`; `app/Filament/Pages/Findings/FindingsIntakeQueue.php`; `app/Filament/Pages/Governance/GovernanceInbox.php`; `tests/Feature/Findings/MyWorkInboxTest.php`; `tests/Feature/Governance/*` | | Finding exceptions and risk acceptance workflow | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/FindingException.php`; `app/Services/Findings/FindingExceptionService.php`; `app/Filament/Resources/FindingExceptionResource.php`; `tests/Feature/Findings/FindingExceptionWorkflowTest.php` | -| Decision Register operator surface | implemented but not productized | yes | yes | repo tests, run in Specs 306/307 | yes | no | `specs/265-decision-register-approval/spec.md`; `specs/307-decision-register-evidence-operationrun-link-polish/spec.md`; `app/Filament/Pages/Governance/DecisionRegister.php`; `app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php`; `tests/Feature/Governance/DecisionRegisterPageTest.php`; `tests/Feature/Findings/FindingExceptionDecisionRegisterNavigationTest.php`; `tests/Feature/Findings/FindingExceptionDecisionRegisterBoundariesTest.php` | +| Decision Register operator surface | implemented but not productized / repo-real | yes | yes | repo tests, run in Specs 306/307 | yes | no | `specs/265-decision-register-approval/spec.md`; `specs/306-decision-register-reconciliation/decision-register-reconciliation.md`; `specs/307-decision-register-evidence-operationrun-link-polish/spec.md`; `app/Filament/Pages/Governance/DecisionRegister.php`; `app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php`; `tests/Feature/Governance/DecisionRegisterPageTest.php`; `tests/Feature/Findings/FindingExceptionDecisionRegisterNavigationTest.php`; `tests/Feature/Findings/FindingExceptionDecisionRegisterBoundariesTest.php` | +| Decision Register proof/run links | fast sellable / repo-real | yes | yes | repo tests, run in Spec 307 | yes | no | `specs/307-decision-register-evidence-operationrun-link-polish/spec.md`; `specs/307-decision-register-evidence-operationrun-link-polish/tasks.md`; `app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php`; `app/Filament/Pages/Governance/DecisionRegister.php`; `tests/Unit/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilderTest.php`; `tests/Feature/Governance/DecisionRegisterPageTest.php` | | Restore workflow with safety gates | sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/OperationRun.php`; restore gates and tests in `tests/Feature/Restore/*` | | Evidence snapshots | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Models/EvidenceSnapshot.php`; `app/Services/Evidence/EvidenceSnapshotService.php`; `tests/Feature/Evidence/*` | | Tenant reviews | fast sellable | yes | yes | repo tests, not run | yes | yes | `app/Models/TenantReview.php`; `app/Services/TenantReviews/TenantReviewService.php`; `tests/Feature/TenantReview/*` | -| Review pack generation and export | implemented but not productized | yes | yes | repo tests, not run | yes | no | `specs/109-review-pack-export/spec.md`; `app/Models/ReviewPack.php`; `app/Services/ReviewPackService.php`; `tests/Feature/ReviewPack/*` | -| Customer review workspace | fast sellable | yes | yes | repo tests, not run | yes | yes | `specs/258-customer-review-productization/spec.md`; `app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`; `tests/Feature/Reviews/*`; `tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php` | +| Review pack generation and export | fast sellable | yes | yes | repo tests, not run here; Spec 308 validation recorded | yes | yes | `specs/109-review-pack-export/spec.md`; `specs/308-decision-register-summary-review-pack/plan.md`; `app/Models/ReviewPack.php`; `app/Services/ReviewPackService.php`; `app/Jobs/GenerateReviewPackJob.php`; `tests/Feature/ReviewPack/*` | +| Decision Summary in reviews and Review Packs | fast sellable / repo-real | yes | yes | repo tests, run in Spec 308 | yes | yes | `specs/308-decision-register-summary-review-pack/spec.md`; `specs/308-decision-register-summary-review-pack/plan.md`; `app/Services/EnvironmentReviews/EnvironmentReviewComposer.php`; `app/Jobs/GenerateReviewPackJob.php`; `tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php`; `tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php` | +| Customer review workspace | fast sellable / repo-real, v1 completion open gap | yes | yes | repo tests, not run here; Spec 308 validation recorded for summary/pack inclusion | yes | no | `specs/258-customer-review-productization/spec.md`; `specs/308-decision-register-summary-review-pack/spec.md`; `app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`; `tests/Feature/Reviews/*`; `tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php` | | Governance package delivery surface | implemented but not productized | yes | yes | repo tests, not run | yes | no | `specs/260-governance-service-packaging/spec.md`; `app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`; `app/Filament/Resources/TenantReviewResource.php`; `tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php`; `tests/Feature/TenantReview/TenantReviewExplanationSurfaceTest.php` | | Compliance evidence mapping overlay | implemented but not productized | yes | yes | repo tests, not run | partial | no | `specs/259-compliance-evidence-mapping/spec.md`; `app/Support/Governance/Controls/ComplianceEvidenceMappingV1.php`; `app/Services/TenantReviews/TenantReviewSectionFactory.php`; `tests/Feature/TenantReview/TenantReviewCanonicalControlReferenceTest.php` | | Alerts and notification routing | sellable | yes | partial | repo tests, not run | yes | yes | `app/Services/Alerts/AlertDispatchService.php`; `tests/Feature/*Alert*` | @@ -106,6 +119,7 @@ ## Implemented Capabilities | Workspace entitlements | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Services/Entitlements/WorkspaceEntitlementResolver.php`; `tests/Feature/Filament/Settings/WorkspaceEntitlementsSettingsPageTest.php` | | Commercial lifecycle state handling | foundation-only | yes | yes | repo tests, not run | yes | no | `specs/251-commercial-entitlements-billing-state/spec.md`; `app/Services/Entitlements/WorkspaceCommercialLifecycleResolver.php`; `app/Filament/System/Pages/Directory/ViewWorkspace.php`; `tests/Feature/System/ViewWorkspaceEntitlementsTest.php`; `tests/Unit/Entitlements/WorkspaceCommercialLifecycleResolverTest.php` | | Capability-first RBAC | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Services/Auth/CapabilityResolver.php`; `app/Services/Auth/RoleCapabilityMap.php`; many `tests/Feature/Rbac/*` | +| RBAC role matrix and access boundary hardening | security-hardening completed / repo-real | yes | yes | repo tests, run in Spec 309 | yes | no | `specs/309-rbac-role-matrix-access-boundary-audit/tasks.md`; `app/Services/Auth/WorkspaceRoleCapabilityMap.php`; `app/Models/User.php`; `tests/Feature/Rbac/RoleMatrix/ManagerAccessTest.php`; `tests/Feature/Rbac/PanelAccess/AdminPanelAccessBoundaryTest.php`; `tests/Feature/Rbac/PanelAccess/SystemPanelAccessBoundaryTest.php` | | Audit log foundation | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Models/AuditLog.php`; `app/Services/Audit/WorkspaceAuditLogger.php`; many audit-focused feature tests | | Canonical control catalog | foundation-only | yes | partial | repo tests, not run | partial | no | `app/Support/Governance/Controls/CanonicalControlCatalog.php`; `config/canonical_controls.php`; `tests/Unit/Governance/*` | | Portfolio triage continuity | foundation-only | yes | yes | repo tests, not run | yes | no | `app/Services/PortfolioTriage/TenantTriageReviewService.php`; `app/Support/PortfolioTriage/*`; `tests/Feature/Filament/TenantRegistryTriageReviewStateTest.php` | @@ -115,7 +129,7 @@ ## Foundation-Only Capabilities - OperationRun truth and canonical operation typing: starke Execution-Foundation, aber kein eigenstaendiger Kundennutzen-Surface. - Audit log foundation: breit genutzt und wichtig fuer Governance, aber allein nicht verkaufbar. -- Capability-first RBAC: belastbar und testnah, bleibt aber Enablement-Layer. +- Capability-first RBAC: belastbar und testnah, bleibt aber Enablement-Layer; Spec 309 ist die abgeschlossene `security-hardening completed` Korrektur fuer Owner-only membership management und admin/system panel boundaries, nicht die Support Access Governance Productization. - Workspace entitlements und commercial lifecycle policy engine: reale Gate-, Lifecycle- und Override-Logik, aber noch keine volle Billing-/Contract-Ops story. - Canonical control catalog: starke semantische Foundation fuer Evidence, Findings und Reviews. - Stored reports substrate: wichtig fuer Reports, Evidence und Diagnostics, aber kein eigenstaendiges Produktversprechen. @@ -128,9 +142,9 @@ ## Foundation-Only Capabilities ## Fast-Sellable Or Not-Yet-Productized Capabilities -- Customer-facing review consumption: Tenant Reviews, Evidence Snapshots, Review Packs, the Customer Review Workspace, the customer-safe released-review detail mode, governance-package delivery cues, compliance interpretation overlays, and commercial-lifecycle-aware access states are repo-real; broader lifecycle/governance taxonomy work remains separate. +- Customer-facing review consumption: Tenant Reviews, Evidence Snapshots, Review Packs, the Customer Review Workspace, the customer-safe released-review detail mode, governance-package delivery cues, Spec 308 Decision Summary / Review Pack inclusion, compliance interpretation overlays, and commercial-lifecycle-aware access states are repo-real; Customer Review Workspace v1 Completion remains an `open gap`. - Findings Workflow v2: Triage, Assignment, My Work, Intake, Governance Inbox, Exceptions, notifications, and the three queue-facing cleanup/hardening follow-through packages are now repo-backed; later cross-tenant action layers remain separate work. -- Decision Register: Spec 265 operator register runtime and Spec 307 direct evidence/report plus source/evidence OperationRun proof-link polish are repo-backed; customer-safe summary and review-pack inclusion remain separate follow-ups, not a Greenfield v1. +- Decision Register: Spec 265 operator register runtime, Spec 306 reconciliation, Spec 307 direct evidence/report plus source/evidence OperationRun proof-link polish, and Spec 308 customer-safe Decision Summary / Review Pack inclusion are repo-backed; the remaining gap is broader Decision-Based Governance Inbox / Customer Review Workspace completion, not a Greenfield v1. - Product scalability and self-service: Onboarding, Support, Help, Entitlements, commercial lifecycle state handling, and external support-desk handoff are repo-real; broader trial/demo and billing-subscription truth still remain. - MSP portfolio operations: Portfolio-Triage plus cross-tenant compare preview and promotion preflight are repo-real; actual promotion execution and broader portfolio action orchestration remain open. - Platform operations maturity: Control Tower und Ops Controls sind stark, aber einige geplante operatorseitige Drilldowns/Exports fehlen noch. @@ -176,7 +190,7 @@ ### Demo-ready ### Fast sellable -- Review-driven governance workflow rund um Tenant Reviews, Customer Review Workspace, governance-package delivery, compliance interpretation overlays, accepted risks und Review Packs, aber noch nicht als vollstaendig productisierte customer-safe consumption experience +- Review-driven governance workflow rund um Tenant Reviews, Customer Review Workspace, governance-package delivery, Spec 308 Decision Summary / Review Pack inclusion, compliance interpretation overlays, accepted risks und Review Packs, aber noch nicht als vollstaendig productisierte customer-safe consumption experience - Baseline drift and restore governance - Findings workflow mit persönlicher Inbox, Intake, Governance Inbox und Exception-Handling - Alerting and run visibility for governance operations @@ -227,7 +241,8 @@ ## Open Gaps & Blockers | Workspace-first / ManagedEnvironment core cutover is not started | Strategic architecture blocker | The repo still centers many governance, support, and portfolio surfaces on `Tenant` semantics, so future multi-provider work would otherwise accumulate more tenant- and Microsoft-centric core coupling | Platform core / provider-neutral posture | `Workspace-first / ManagedEnvironment Core Cutover` pack in `docs/product/spec-candidates.md` (planned as Specs 279-287) | | Auditor-ready executive export is still missing | Productization blocker | Review truth remains short of auditor-/executive-ready delivery, even though the dedicated follow-through is now spec-backed | R2 review delivery | `specs/263-auditor-pack-executive-export/spec.md` | | Cross-tenant promotion execution is still missing | Product blocker | Compare preview and preflight are repo-real, but the actual portfolio action remains absent even though the execution package is now spec-backed | MSP Portfolio & Operations | `specs/264-cross-tenant-promotion-execution/spec.md` | -| Decision Register customer-safe/review-pack inclusion is still missing | Productization gap | The operator register now exposes scoped proof/run links, but customer-safe consumption and review-pack inclusion remain separate product choices | Decision-based operating | `decision-register-review-pack-inclusion` or `decision-register-customer-safe-summary` | +| Customer Review Workspace v1 completion is still open | Productization gap | Repo-real review, Decision Summary, and Review Pack inclusion now exist, but a complete customer-safe self-serve workspace with calm status, reason, impact, evidence basis, accepted risks, decision summary, review-pack download, and one primary next action still needs productization | Customer review consumption | `311-customer-review-workspace-v1-completion` | +| Decision-Based Governance Inbox v1 remains open | Productization gap | The operator Decision Register is repo-real and not Greenfield, but a broader decision-centered governance inbox remains separate from the completed proof/link and customer-safe summary slices | Decision-based operating | `313-decision-based-governance-inbox-v1` | | Governance-artifact lifecycle runtime is still missing | Trust / auditability blocker | Lifecycle taxonomy and point retention rules exist, but governance artifacts still lack immutable-reference, hold, export, delete, and suspended/read-only runtime semantics | Lifecycle governance / enterprise trust | `Governance Artifact Lifecycle & Retention v1` | | Cross-domain progress and indicator semantics guardrail is still missing | UX / trust guardrail | Bars, percentages, scores, readiness, risk, usage, and generation-state hints still lack one shared taxonomy and standards layer above the OperationRun-specific rules | UI semantics / product trust | `Cross-Domain Progress / Indicator Semantics candidate group` | | Residual admin workspace navigation contract drift may remain | UX / IA repair follow-through | Specs 301-304 now cover Inventory cutover, the tenant-owned surface audit, Entra Groups cutover, and tenant-panel dead-code retirement. The remaining risk is shared contract drift between workspace-home cleanliness and environment-bound admin visibility if new regressions appear. | UI maturity / admin runtime contract | `navigation-contract-split`, only if post-Spec 301-304 drift remains | @@ -243,7 +258,9 @@ ## Recommended Manual Promotions - `Cross-Domain Progress / Indicator Semantics candidate group` -> anchored by `specs/268-operationrun-activity-feedback/spec.md`, `specs/270-operationrun-progress-contract/spec.md`, `specs/271-counted-progress-rollout/spec.md`, `specs/272-operationrun-phase-composite-progress/spec.md`, `docs/ui/tenantpilot-enterprise-ui-standards.md`, and the current progress-like UI seams called out in `docs/product/spec-candidates.md` - `Admin Workspace Navigation & Tenant-owned Surface Repair candidate group` -> anchored by `apps/platform/app/Filament/Clusters/Inventory/InventoryCluster.php`, `apps/platform/app/Filament/Pages/InventoryCoverage.php`, `apps/platform/app/Filament/Resources/InventoryItemResource.php`, `apps/platform/app/Filament/Resources/EntraGroupResource.php`, `apps/platform/app/Filament/Concerns/WorkspaceScopedTenantRoutes.php`, `apps/platform/app/Support/OperateHub/OperateHubShell.php`, and the navigation/runtime tests called out in `docs/product/spec-candidates.md`; Specs 301-304 now cover Inventory cutover, route-audit prep, groups cutover, and tenant-panel dead-code retirement, so only `navigation-contract-split` remains as a conditional follow-through if drift persists - `Workspace-first / ManagedEnvironment Core Cutover` pack -> anchored by `docs/product/spec-candidates.md`, `docs/product/roadmap.md`, `docs/product/implementation-ledger.md`, and the tenant-centric platform seams already visible across review, support, portfolio, and governance surfaces; keep it as a clean development-stage cutover pack rather than a compatibility-layer program -- `decision-register-review-pack-inclusion` / `decision-register-customer-safe-summary` -> anchored by `specs/265-decision-register-approval/spec.md`, `specs/306-decision-register-reconciliation/decision-register-reconciliation.md`, `specs/307-decision-register-evidence-operationrun-link-polish/spec.md`, `apps/platform/app/Filament/Pages/Governance/DecisionRegister.php`, `apps/platform/app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php`, and the focused Decision Register tests +- `Customer Review Workspace v1 Completion` -> anchored by `specs/258-customer-review-productization/spec.md`, `specs/308-decision-register-summary-review-pack/spec.md`, `apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php`, and the review/workspace tests +- `Localization v1 Customer-facing Surfaces` -> anchored by `specs/252-platform-localization-v1/spec.md`, `specs/258-customer-review-productization/spec.md`, and `specs/260-governance-service-packaging/spec.md` +- `Decision-Based Governance Inbox v1` -> anchored by `specs/250-decision-governance-inbox/spec.md`, `specs/257-governance-decision-convergence/spec.md`, `specs/265-decision-register-approval/spec.md`, `specs/306-decision-register-reconciliation/decision-register-reconciliation.md`, `specs/307-decision-register-evidence-operationrun-link-polish/spec.md`, `specs/308-decision-register-summary-review-pack/spec.md`, `apps/platform/app/Filament/Pages/Governance/DecisionRegister.php`, `apps/platform/app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php`, and the focused Decision Register tests - `Governance Artifact Lifecycle & Retention v1` -> anchored by `specs/158-artifact-truth-semantics/spec.md`, `specs/262-lifecycle-governance-taxonomy/spec.md`, and `docs/product/standards/lifecycle-governance.md` - `Billing & Subscription Truth Layer v1` -> anchored by `specs/247-plans-entitlements-billing-readiness/spec.md` and `specs/251-commercial-entitlements-billing-state/spec.md` - `Customer-Facing Localization Adoption v1` -> anchored by `specs/252-platform-localization-v1/spec.md`, `specs/258-customer-review-productization/spec.md`, and `specs/260-governance-service-packaging/spec.md` @@ -254,8 +271,8 @@ ## Recommended Manual Promotions ## Roadmap Drift Notes -- `docs/product/roadmap.md` and `docs/product/spec-candidates.md` are aligned through 2026-05-15, including Spec 304 tenant-panel dead-code retirement, Spec 306 Decision Register reconciliation, Spec 307 proof-link polish, the earlier admin workspace navigation / tenant-owned surface repair candidate intake, the cross-domain indicator candidate intake, the current manual-promotion backlog, and the resolved ledger conflict state. -- The remaining documentation risk is no longer queue drift alone; it is understating or overstating still-open follow-through slices such as admin workspace navigation repair, auditor-ready export, promotion execution, governance decision workflow, cross-domain indicator semantics, billing/subscription truth, stored reports surface, and the first governed AI runtime consumer. +- `docs/product/roadmap.md` and `docs/product/spec-candidates.md` are aligned through 2026-05-15, including Spec 304 tenant-panel dead-code retirement, Spec 306 Decision Register reconciliation, Spec 307 proof-link polish, Spec 308 customer-safe Decision Summary / Review Pack inclusion, Spec 309 RBAC role/access-boundary hardening, the earlier admin workspace navigation / tenant-owned surface repair candidate intake, the cross-domain indicator candidate intake, the current manual-promotion backlog, and the resolved ledger conflict state. +- The remaining documentation risk is no longer queue drift alone; it is understating or overstating still-open follow-through slices such as Customer Review Workspace v1 completion, localization adoption, Decision-Based Governance Inbox completion, admin workspace navigation repair, auditor-ready export, promotion execution, governance decision workflow, cross-domain indicator semantics, billing/subscription truth, stored reports surface, Support Access Governance, and the first governed AI runtime consumer. - This ledger therefore treats review-driven governance and portfolio preparation as `fast sellable` or `implemented but not productized`, not `sellable`, until those explicit manual-promotion slices land. - Tests referenced here remain repo-present only. They were not executed for this ledger update. diff --git a/docs/product/roadmap.md b/docs/product/roadmap.md index 6dfb0595..e97000e4 100644 --- a/docs/product/roadmap.md +++ b/docs/product/roadmap.md @@ -4,7 +4,7 @@ # Product Roadmap > **Last reviewed:** 2026-05-15 > **Use for:** Current product roadmap, release themes, and prioritization context > **Do not use for:** Implementation truth, spec completion status, or delivery guarantees without repo verification -> **Scoped maintenance:** 2026-05-15 Decision Register proof-link update after Spec 307; 2026-05-15 Decision Register reconciliation update after Spec 306; 2026-05-15 tenant-owned admin surface follow-through sync after Specs 301-304; 2026-05-12 roadmap alignment after the admin workspace navigation and tenant-owned surface repair candidate intake from the repo-verified navigation/panel audit; 2026-05-06 roadmap cleanup after ledger conflict resolution and cross-domain progress / indicator semantics candidate intake; 2026-05-02 repo-based roadmap drift correction, manual-promotion backlog alignment, and enterprise-SaaS deep-research calibration against current specs, standards, and product-truth docs. +> **Scoped maintenance:** 2026-05-15 Spec 310 product-truth/docs-drift reconciliation after Specs 307-309; 2026-05-15 Spec 309 RBAC role matrix and access boundary hardening update; 2026-05-15 Spec 308 customer-safe Decision Summary and Review Pack inclusion update; 2026-05-15 Decision Register proof-link update after Spec 307; 2026-05-15 Decision Register reconciliation update after Spec 306; 2026-05-15 tenant-owned admin surface follow-through sync after Specs 301-304; 2026-05-12 roadmap alignment after the admin workspace navigation and tenant-owned surface repair candidate intake from the repo-verified navigation/panel audit; 2026-05-06 roadmap cleanup after ledger conflict resolution and cross-domain progress / indicator semantics candidate intake; 2026-05-02 repo-based roadmap drift correction, manual-promotion backlog alignment, and enterprise-SaaS deep-research calibration against current specs, standards, and product-truth docs. > > Strategic thematic blocks and release trajectory. > This is the "big picture" — not individual specs. @@ -26,24 +26,30 @@ ## Current Productization & Moat Priorities This is the repo-based prioritization overlay for the next sellable lanes. The bottleneck is no longer raw backend truth alone. The next roadmap slices should make existing governance foundations customer-safe, decision-centered, auditable, and MSP-sellable before opening more backend-only islands. +Post-307/308/309 product truth: + +- Decision Register operator surface is repo-real and historical/non-Greenfield through Specs 265 and 306. +- Decision Register proof/run links are repo-real after Spec 307. +- Customer-safe Decision Summary in reviews and Review Pack inclusion are repo-real after Spec 308. +- RBAC role matrix and admin/system access boundary hardening are `security-hardening completed` after Spec 309. +- Customer Review Workspace v1 Completion remains open; Spec 308 did not turn the whole customer review workspace into a fully sellable self-serve product. +- Support Access Governance remains separate from Spec 309 hardening. + | Order | Theme | Alignment status | Repo truth | Why now | Queue posture | |---|---|---|---|---|---| -| 1 | Customer Review Workspace Productization v1 | repo-verified, productization gap | Customer-safe review consumption is repo-real through Specs 249, 258, 259, 260, and 263, but the calm sellable surface still needs final productization discipline | clearest sellability lever for Governance-of-Record without creating a parallel customer portal | spec-backed follow-through | -| 2 | Decision-Based Governance Inbox + Decision Register follow-up | repo-verified, productization gap, roadmap recommendation | Governance inbox, findings queues, alerts, review follow-up, Spec 265 operator Decision Register, Spec 306 reconciliation, and Spec 307 proof-link polish are repo-verified; only customer-safe/review-pack follow-through remains open | biggest remaining operator workflow gap and the cleanest defense against admin-tool sprawl | no Greenfield v1; manual promotion only for customer-safe/review-pack follow-through | -| 3 | Governance Artifact Lifecycle & Retention v1 | foundation-only, roadmap recommendation, spec candidate | Spec 262 and the lifecycle-governance standard provide taxonomy-first guardrails, but governance-artifact runtime semantics are not yet productized | new trust, auditability, export, and retention lever for evidence snapshots, stored reports, review packs, and decision records | manual promotion only | -| 4 | Commercial Entitlements & Billing-State Lifecycle v1 | repo-verified, foundation-only, productization gap | Specs 247 and 251 already resolve plan and lifecycle posture, but broader commercial-state-to-artifact-access rules and later billing truth remain open | SaaS trust and lifecycle maturity matter before broader packaging, scale, or AI work | spec-backed follow-through plus narrower billing follow-through | -| 5 | External Support Desk / PSA Handoff v1 | repo-verified, productization gap | Spec 256 and the current bounded handoff service already exist, but the portfolio-safe handoff story is still not fully productized | MSP integration should compress follow-through work without turning TenantPilot into a helpdesk | spec-backed follow-through | -| 6 | Customer-Facing Localization v1 | foundation-only, productization gap | Spec 252 and current locale resolution are repo-real; glossary completion and customer-facing adoption remain incomplete | customer-safe DACH/EU review consumption should start at glossary, labels, packs, and notifications rather than full operator-UI translation | manual promotion only | -| 7 | Cross-Tenant Compare & Promotion with Lineage v1 | repo-verified, productization gap | Spec 043 is repo-real for compare and preflight, and Spec 264 now carries the bounded execution follow-through on this branch | portfolio action matters, but it must stay governance-first with lineage, evidence, approval, and rollback references rather than raw push mechanics | spec-backed follow-through | -| 8 | Governance Service Packaging v1 | repo-verified, productization gap | Spec 260 and current governance-package delivery cues are repo-real, but recurring service packaging remains calmer in documentation than in repeatable delivery workflows | MSP value comes from repeatable services and customer-safe consumption, not just more admin pages | spec-backed follow-through | -| 9 | Enterprise Access Boundary & Support Access Governance v1 | roadmap recommendation, spec candidate | Break-glass and system-access seams exist in audits and handover docs, but no bounded support-access request, TTL, approval, and customer-visible audit package exists | tighten support access before broad SSO/SCIM expansion; keep SCIM and group-provisioning later | manual promotion only | -| 10 | Advanced APIs / Webhooks | later scale-layer, not-now | no bounded repo-ready package yet | useful integration layer, but it trails review, decision, artifact, and commercial clarity | not-now | -| 11 | Private AI Execution Governance Foundation v1 / governed runtime follow-through | repo-verified, foundation-only, later scale-layer | Spec 248 is implemented as a governed foundation; visible runtime consumers and broader budget/result governance are still deferred | AI should remain governed foundation-first and provider-auditable before any visible feature island ships | manual promotion only for runtime follow-through | -| 12 | AI-assisted Review Summaries / Translation / Next Action Drafting | roadmap recommendation, later scale-layer, not-now | depends on governed AI, review truth, and customer-safe localization/productization | later visible AI lane after review, decision, artifact, and commercial maturity | not-now | +| 1 | Customer Review Workspace v1 Completion | repo-real foundation, open gap, P1 | Customer-safe review consumption is repo-real through Specs 249, 258, 259, 260, 263, and Spec 308, but a complete self-serve workspace with calm status, reason, impact, evidence basis, accepted risks, decision summary, review-pack download, and one primary next action remains open | clearest sellability lever for Governance-of-Record without creating a parallel customer portal | recommend Spec 311 | +| 2 | Localization v1 Customer-facing Surfaces | foundation-only, open gap, P1 | Spec 252 and current locale resolution are repo-real; glossary completion and customer-facing review/pack/notification adoption remain incomplete | customer-safe DACH/EU review consumption should be understandable before broader workflow packaging | recommend Spec 312 | +| 3 | Decision-Based Governance Inbox v1 | repo-real foundation, open gap, P1 | Governance inbox, findings queues, alerts, review follow-up, Spec 265 operator Decision Register, Spec 306 reconciliation, Spec 307 proof-link polish, and Spec 308 customer-safe summary/export inclusion are repo-verified | biggest remaining operator workflow gap; the need is a broader decision-centered inbox, not a Decision Register rebuild | recommend Spec 313 | +| 4 | Commercial Entitlements / Billing-State Maturity | repo-real foundation, open gap, P1/P2 | Specs 247 and 251 already resolve entitlement and lifecycle posture, but durable billing/subscription truth and artifact access by commercial state remain open | SaaS trust and lifecycle maturity should follow customer-facing surface clarity | recommend Spec 314 | +| 5 | Cross-Tenant Compare & Promotion Execution | repo-real preview/preflight, spec-backed execution follow-up | Spec 043 is repo-real for compare and preflight, and Spec 264 carries bounded execution follow-through; actual portfolio action maturity remains open until runtime/product proof is complete | portfolio action matters, but it must stay governance-first with lineage, evidence, approval, and rollback references rather than raw push mechanics | recommend Spec 315 if refresh/execution follow-through remains needed | +| 6 | Governance Artifact Lifecycle & Retention | foundation-only, open gap, P2 | Spec 262 and lifecycle-governance standards provide taxonomy-first guardrails, but governance-artifact runtime semantics are not yet productized | trust, auditability, export, and retention become more urgent after review and decision artifacts are customer-consumed | recommend Spec 316 | +| 7 | External Support Desk / PSA Handoff | repo-real foundation, open productization gap, P2 | Spec 256 and the current bounded handoff service already exist, but portfolio-safe handoff is not fully productized | MSP integration should compress follow-through work without turning TenantPilot into a helpdesk | recommend Spec 317 | +| 8 | Private AI Execution Governance Foundation / governed runtime follow-through | repo-real foundation, later open gap, P3 | Spec 248 is implemented as a governed foundation; visible runtime consumers and broader budget/result governance are still deferred | AI should remain governed foundation-first and provider-auditable after review, decision, artifact, and commercial maturity | recommend Spec 318 only as a bounded governed runtime consumer | Explicit anti-sprawl boundaries for this priority set: - Do not reopen risk acceptance as a broad new foundation theme; reuse the existing exception/risk-acceptance workflow and productize its customer-safe accountability trail. +- Do not reopen Decision Register v1; operator register, proof/run links, and customer-safe summary/review-pack inclusion are repo-real, while Governance Inbox and Customer Review Workspace completion remain separate. - Do not reopen private AI as a fresh roadmap idea; the foundation already exists in `specs/248-private-ai-policy-foundation/spec.md`, and the open roadmap question is only when to promote the first governed runtime consumer. - Do not treat the promotable candidate backlog in `docs/product/spec-candidates.md` as an automatic prep queue; those items require explicit product decisions. - Do not prioritize Tenant Trust Score / public governance profile, insurance connectors, Copilot shadow-IT governance, local-first/on-prem proxy, or a standalone Betriebsrat mode before customer-safe review consumption, decision convergence, compliance mapping, governance packaging, and compare/promotion are materially clearer. @@ -56,6 +62,8 @@ ### Governance & Architecture Hardening Canonical run-view trust semantics, execution-time authorization continuity, tenant-owned query canon, findings workflow enforcement, Livewire trust-boundary reduction, operation-type canonicalization, provider-boundary hardening, target-scope neutrality, and governed-subject vocabulary enforcement. Goal: Turn the new audit constitution into enforceable backend and workflow guardrails before further governance surface area lands, while preventing the Governance-of-Record platform core from drifting into provider-specific or operation-type dual semantics. +Spec 309 completes the scoped RBAC role matrix and admin/system access boundary hardening. Support Access Governance remains a separate productization candidate, not an unresolved part of Spec 309. + **Active specs**: 144 **Specced follow-through (draft)**: 149 (queued execution reauthorization), 150 (tenant-owned query canon), 151 (findings workflow backstop), 152 (Livewire context locking), 214 (governance outcome compression), 216 (provider dispatch gate), 237 (provider boundary hardening). Next foundation candidates: Canonical Operation Type Source of Truth, Provider Identity & Target Scope Neutrality, Platform Vocabulary Boundary Enforcement for Governed Subject Keys. **Operator truth initiative** (sequenced): Operator Outcome Taxonomy (Spec 156) → Reason Code Translation (Spec 157) → Artifact Truth Semantics (Spec 158) → Governance Operator Outcome Compression (Spec 214, draft). Humanized Diagnostic Summaries for Governance Operations is now Spec 220 (draft) as the run-detail adoption slice, while Provider Dispatch Gate Unification is now Spec 216 (draft) as the adjacent hardening lane. @@ -102,7 +110,7 @@ ### R1.9 Platform Localization v1 (DE/EN) - Search/Sort/Filter auf kritischen Listen für locale-sensitives Verhalten prüfen - QA/Foundation: Missing-Key Detection, Locale Regression Tests, Pseudolocalization Smoke Tests für kritische Flows -**Queue status**: no standalone active candidate right now; the historical foundation package is `specs/252-platform-localization-v1/spec.md`, and the remaining follow-through is `Customer-Facing Localization Adoption v1` in `docs/product/spec-candidates.md` as manual promotion only, not auto-prep. +**Queue status**: recommended near-term Spec 312 after Customer Review Workspace v1 Completion; the historical foundation package is `specs/252-platform-localization-v1/spec.md`, and the remaining follow-through is `Localization v1 Customer-facing Surfaces` / `Customer-Facing Localization Adoption v1` in `docs/product/spec-candidates.md` as manual promotion only, not auto-prep. ### Product Scalability & Self-Service Foundation Self-service and supportability foundation that keeps TenantPilot operable as a low-headcount, AI-assisted SaaS instead of drifting into manual onboarding, manual support, and founder-dependent customer operations. @@ -445,7 +453,7 @@ ## Infrastructure & Platform Debt | Auditor-ready executive export is not yet productized | Review truth still stops short of calm auditor-/executive-ready delivery even though the spec package now exists | Covered by `specs/263-auditor-pack-executive-export/spec.md` | | Cross-tenant promotion execution is missing | Compare preview and preflight stop short of the actual portfolio action even though the execution spec package now exists on this branch | Covered by `specs/264-cross-tenant-promotion-execution/spec.md` | | Residual admin workspace navigation contract drift may remain | Specs 301-304 closed the Inventory cutover, route audit, groups cutover, and tenant-panel dead-code cleanup; only a later contract split may still be needed if new repo evidence shows workspace-home and environment-bound navigation rules colliding again | Covered by the conditional `navigation-contract-split` follow-up in `docs/product/spec-candidates.md` | -| Decision Register customer-safe/review-pack follow-through is still pending | The Spec 265 operator register, Spec 306 reconciliation, and Spec 307 proof/run-link polish exist, but customer-safe consumption and explicit review-pack inclusion remain unproductized | Covered by the narrow manual-promotion follow-up in `docs/product/spec-candidates.md` | +| Customer Review Workspace v1 completion is still open | Specs 258 and 308 make the workspace and customer-safe decision summary/review-pack inclusion repo-real, but the complete self-serve customer consumption experience is not yet fully productized | Covered by `311-customer-review-workspace-v1-completion` in `docs/product/spec-candidates.md` | | Customer-facing localization adoption is incomplete | Repo-real locale groundwork is not yet fully productized across customer-safe governance surfaces | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` | | Billing and subscription truth is missing | Commercial readiness still stops short of a durable billing/subscription truth layer | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` | | Stored reports still lack a clear product surface | Retained evidence and review artifacts remain harder to consume than they should be | Covered by the manual-promotion backlog in `docs/product/spec-candidates.md` | @@ -465,20 +473,20 @@ ## Infrastructure & Platform Debt ## Priority Ranking (Current Manual Promotion Order) -This ranking applies only to still-unspecced or still-manual follow-through items. Auditor-ready delivery and cross-tenant promotion execution already have spec packages and therefore no longer belong in the manual-promotion ordering list. +This ranking applies to the post-Spec-310 productization sequence. If a target already has an older spec package, treat the item as a refresh/execution follow-through only when current repo truth still leaves the product gap open. Parallel immediate guardrail lane: the Cross-Domain Progress / Indicator Semantics candidate group in `docs/product/spec-candidates.md` should be promoted alongside OperationRun maturity when UI semantic drift is the active concern. Spec 278 provides the audit inventory and standards-delta input; the remaining follow-up remains split across contract, component, quality-gate, and migration lanes. It stays outside the main sellability ordering below because it is a cross-cutting semantics and standards package rather than a standalone customer-facing delivery lane. Parallel immediate repair lane: the Admin Workspace Navigation & Tenant-owned Surface Repair candidate group in `docs/product/spec-candidates.md` is now mostly historical sequencing context after Specs 301-304. Promote only `navigation-contract-split`, and only when fresh repo evidence shows residual shared-contract drift between workspace-home cleanliness and environment-bound admin visibility. -1. Decision Register customer-safe summary / review-pack inclusion -2. Governance Artifact Lifecycle & Retention v1 -3. Billing & Subscription Truth Layer v1 -4. Customer-Facing Localization Adoption v1 -5. Enterprise Access Boundary & Support Access Governance v1 -6. Stored Reports Surface v1 -7. Workspace & Tenant Closure Lifecycle v1 -8. First Governed AI Runtime Consumer v1 +1. Customer Review Workspace v1 Completion +2. Localization v1 Customer-facing Surfaces +3. Decision-Based Governance Inbox v1 +4. Commercial Entitlements / Billing-State Maturity +5. Cross-Tenant Compare & Promotion Execution +6. Governance Artifact Lifecycle & Retention +7. External Support Desk / PSA Handoff +8. Private AI Execution Governance Foundation --- diff --git a/docs/product/spec-candidates.md b/docs/product/spec-candidates.md index 5eb1bc79..b8e2c41b 100644 --- a/docs/product/spec-candidates.md +++ b/docs/product/spec-candidates.md @@ -4,7 +4,7 @@ # Spec Candidates > **Last reviewed:** 2026-05-15 > **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-15 Spec 307 Decision Register proof-link implementation update; 2026-05-15 Spec 306 Decision Register reconciliation update; 2026-05-15 Spec 304 Tenant Panel dead-code retirement guardrail update; 2026-05-12 admin workspace navigation and tenant-owned surface repair candidate intake after the repo-verified navigation/panel audit; 2026-05-06 cross-domain progress and indicator semantics candidate intake; 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. +> **Scoped maintenance:** 2026-05-15 Spec 310 product-truth/docs-drift reconciliation after Specs 307-309; 2026-05-15 Spec 309 RBAC role matrix and access boundary hardening update; 2026-05-15 Spec 308 customer-safe Decision Summary and Review Pack inclusion update; 2026-05-15 Spec 307 Decision Register proof-link implementation update; 2026-05-15 Spec 306 Decision Register reconciliation update; 2026-05-15 Spec 304 Tenant Panel dead-code retirement guardrail update; 2026-05-12 admin workspace navigation and tenant-owned surface repair candidate intake after the repo-verified navigation/panel audit; 2026-05-06 cross-domain progress and indicator semantics candidate intake; 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. @@ -40,25 +40,25 @@ ## Deep-Research Alignment Reference (non-queue) ### 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. +- **Roadmap lane**: Next +- **Current repo truth**: Specs 249 and 258, plus Spec 308 customer-safe Decision Summary / Review Pack inclusion, the implementation ledger, and current review surfaces, already prove the foundational path for customer-safe review consumption. +- **Problem**: Customer-safe review consumption remains the clearest sellability gap whenever calm status, reason, impact, evidence basis, accepted risks, decision summary, review-pack download, and one primary next action 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 Follow-up - **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/257 already anchor the decision surface. Spec 265 plus Spec 307 runtime/tests now also prove the bounded operator Decision Register and direct proof/run link polish are not Greenfield. -- **Problem**: The remaining gap is narrower than the former v1 candidate: later customer-safe consumption or review-pack inclusion if productized. -- **Deep-Research-derived sharpening**: keep any next slice as a follow-up over Specs 265/307, not a new Decision Register or approval-engine rebuild. +- **Roadmap lane**: Next +- **Current repo truth**: governance inbox, findings queues, operations attention, review follow-up, and Specs 250/257 already anchor the decision surface. Specs 265, 306, 307, and 308 prove the bounded operator Decision Register, direct proof/run link polish, and customer-safe summary/review-pack inclusion are not Greenfield. +- **Problem**: The remaining gap is broader decision-centered operating discipline: a Governance Inbox / Customer Review Workspace completion slice, not customer-safe summary or review-pack inclusion. +- **Deep-Research-derived sharpening**: keep any next slice as a follow-up over Specs 250/257/265/306/307/308, not a new Decision Register or approval-engine rebuild. - **Non-goals**: no generic Kanban board, no PSA clone, no XDR incident console, no new decision table, no duplicate approval engine. ### Governance Artifact Lifecycle & Retention v1 - **Status markers**: foundation-only, roadmap recommendation, spec candidate -- **Roadmap lane**: Now +- **Roadmap lane**: Next / P2 after customer-facing review, localization, decision inbox, commercial truth, and promotion execution - **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. @@ -76,7 +76,7 @@ ### Commercial Entitlements & Billing-State Lifecycle v1 ### External Support Desk / PSA Handoff v1 - **Status markers**: repo-verified, productization gap -- **Roadmap lane**: Next +- **Roadmap lane**: P2 after customer-facing review, localization, decision inbox, commercial truth, promotion execution, and artifact lifecycle - **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. @@ -85,7 +85,7 @@ ### External Support Desk / PSA Handoff v1 ### Customer-Facing Localization v1 - **Status markers**: foundation-only, productization gap -- **Roadmap lane**: Next +- **Roadmap lane**: Now - **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. @@ -146,6 +146,12 @@ ## Active Candidate Queue 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`. +Specs 307, 308, and 309 have also moved out of candidate status on the current repo truth: + +- `Decision Register Evidence / OperationRun Link Polish` -> Spec 307, completed historical proof/run link polish +- `Decision Register Customer-Safe Summary / Review-Pack Inclusion` -> Spec 308, completed historical customer-safe summary and review-pack inclusion +- `RBAC Role Matrix & Access Boundary Audit` -> Spec 309, completed scoped security hardening + Two manual-promotion items have since moved out of backlog status on the current repo state: - `Auditor Pack Delivery & Executive Export v1` -> Spec 263 @@ -157,6 +163,19 @@ ## 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. +### Recommended Next Spec Sequence After Spec 310 + +| Order | Recommended next spec | Candidate status | Boundary | +|---:|---|---|---| +| 311 | `customer-review-workspace-v1-completion` | open gap / P1 | Complete customer-safe review consumption without claiming a generic customer portal. | +| 312 | `localization-v1-customer-facing-surfaces` | open gap / P1 | Productize DE/EN customer-facing review, pack, notification, reason, impact, and next-action language over the existing localization foundation. | +| 313 | `decision-based-governance-inbox-v1` | open gap / P1 | Extend decision-centered operator workflow over existing Governance Inbox and Decision Register truth; do not rebuild the Decision Register. | +| 314 | `commercial-entitlements-billing-state-maturity` | open gap / P1/P2 | Mature commercial lifecycle and billing-state truth after customer-facing surfaces are clearer. | +| 315 | `cross-tenant-compare-promotion-execution` | spec-backed / open execution maturity | Continue the governance-first compare/promotion execution path if Spec 264 still needs runtime/product refresh. | +| 316 | `governance-artifact-lifecycle-retention` | open gap / P2 | Productize artifact lifecycle and retention runtime over existing taxonomy/truth foundations. | +| 317 | `external-support-desk-psa-handoff` | repo-real foundation / open productization | Productize support-desk/PSA handoff only after higher-priority review and decision paths settle. | +| 318 | `private-ai-execution-governance-foundation` | foundation/open / P3 | Promote only as a bounded governed runtime consumer, not as an AI feature island. | + ### 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 @@ -1003,25 +1022,29 @@ ### Decision Register Evidence / OperationRun Link Polish - `specs/257-governance-decision-convergence/spec.md` - `docs/product/roadmap.md` -### Decision Register Customer-Safe Summary / Review-Pack Inclusion +### Decision Register Customer-Safe Summary / Review-Pack Inclusion (historical) -- **Priority**: 1 -- **Status**: open manual-promotion follow-up after Spec 307. Do not reopen Spec 265 or repackage the proof-link polish as a broader Decision Register rebuild. -- **Repo truth**: Spec 265 proves the bounded operator Decision Register, Spec 306 reconciles the current runtime, and Spec 307 closes direct evidence/report plus source/evidence `OperationRun` proof-link polish. `CustomerReviewWorkspace`, review-pack foundations, and governance-package delivery already summarize accepted-risk decisions, but there is still no explicit customer-safe Decision Register surface or review-pack inclusion contract. -- **Why promotable now**: the proof/run-link follow-up is complete, so the next remaining Decision Register productization question is whether accepted-risk decisions need a bounded customer-safe summary and/or explicit review-pack inclusion. -- **Why manual promotion only**: this is product-sensitive and must stay narrower than a new Decision Register v1. Reuse existing decision truth, customer-review foundations, and review-pack packaging instead of introducing a new workflow engine, duplicate decision summary, or customer portal. +- **Historical priority**: 1 +- **Status**: promoted to Spec 308 and implemented on 2026-05-15; keep this entry as historical sequencing context only. +- **Repo truth**: Spec 265 proves the bounded operator Decision Register, Spec 306 reconciles the current runtime, Spec 307 closes direct evidence/report plus source/evidence `OperationRun` proof-link polish, and Spec 308 adds repo-real customer-safe Decision Summary plus review-derived Review Pack inclusion. +- **Why no longer active**: the customer-safe summary/review-pack inclusion question has been answered by Spec 308. The remaining productization gap is Customer Review Workspace v1 Completion and broader Decision-Based Governance Inbox v1, not another Decision Register v1. +- **Why historical only**: reopening this would risk duplicating the completed summary/export contract or rebuilding the operator register instead of finishing the customer-facing workspace and decision workflow. - **Anchors**: - `specs/265-decision-register-approval/spec.md` - `specs/306-decision-register-reconciliation/decision-register-reconciliation.md` - `specs/307-decision-register-evidence-operationrun-link-polish/spec.md` + - `specs/308-decision-register-summary-review-pack/spec.md` + - `specs/308-decision-register-summary-review-pack/plan.md` - `specs/258-customer-review-productization/spec.md` - `specs/260-governance-service-packaging/spec.md` - `apps/platform/app/Filament/Pages/Governance/DecisionRegister.php` - `apps/platform/app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php` + - `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php` + - `apps/platform/app/Jobs/GenerateReviewPackJob.php` ### Governance Artifact Lifecycle & Retention v1 -- **Priority**: 2 +- **Priority**: 6 - **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. @@ -1032,7 +1055,7 @@ ### Governance Artifact Lifecycle & Retention v1 ### Billing & Subscription Truth Layer v1 -- **Priority**: 3 +- **Priority**: 4 - **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. @@ -1042,7 +1065,7 @@ ### Billing & Subscription Truth Layer v1 ### Customer-Facing Localization Adoption v1 -- **Priority**: 4 +- **Priority**: 2 - **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. @@ -1053,7 +1076,7 @@ ### Customer-Facing Localization Adoption v1 ### Enterprise Access Boundary & Support Access Governance v1 -- **Priority**: 5 +- **Priority**: 7 - **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. @@ -1065,7 +1088,7 @@ ### Enterprise Access Boundary & Support Access Governance v1 ### Stored Reports Surface v1 -- **Priority**: 6 +- **Priority**: P2 follow-up after customer-facing review, localization, decision inbox, commercial truth, promotion execution, and artifact lifecycle - **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. @@ -1077,7 +1100,7 @@ ### Stored Reports Surface v1 ### Workspace & Tenant Closure Lifecycle v1 -- **Priority**: 7 +- **Priority**: P2 follow-up after artifact lifecycle direction is settled - **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. @@ -1184,7 +1207,11 @@ ## Promoted to Spec - 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`) -- Decision Register & Approval Workflow v1 -> Spec 265 (`decision-register-approval`), reconciled by Spec 306 and proof-link-polished by Spec 307; broad Greenfield scope closed, later customer-safe/review-pack inclusion remains separate +- Decision Register & Approval Workflow v1 -> Spec 265 (`decision-register-approval`), reconciled by Spec 306, proof-link-polished by Spec 307, and customer-safe/review-pack-included by Spec 308; broad Greenfield scope closed, broader Governance Inbox / Customer Review Workspace completion remains separate +- Decision Register Reconciliation -> Spec 306 (`decision-register-reconciliation`) +- Decision Register Evidence / OperationRun Link Polish -> Spec 307 (`decision-register-evidence-operationrun-link-polish`) +- Decision Register Customer-Safe Summary / Review-Pack Inclusion -> Spec 308 (`decision-register-summary-review-pack`) +- RBAC Role Matrix & Access Boundary Audit -> Spec 309 (`rbac-role-matrix-access-boundary-audit`) - 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`) diff --git a/specs/310-product-truth-docs-drift-reconciliation/checklists/requirements.md b/specs/310-product-truth-docs-drift-reconciliation/checklists/requirements.md new file mode 100644 index 00000000..8388e278 --- /dev/null +++ b/specs/310-product-truth-docs-drift-reconciliation/checklists/requirements.md @@ -0,0 +1,48 @@ +# Specification Quality Checklist: Product Truth / Docs Drift Reconciliation + +**Purpose**: Validate specification completeness and quality before implementation +**Created**: 2026-05-15 +**Feature**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/spec.md` + +## Content Quality + +- [x] No application implementation details are required beyond docs-only affected paths and validation commands. +- [x] Focused on user/product value: accurate repo-based product truth after Specs 307, 308, and 309. +- [x] All mandatory repo-specific sections are completed or explicitly marked N/A. +- [x] The candidate check required by SPEC-GATE-001 is completed. + +## Requirement Completeness + +- [x] No `[NEEDS CLARIFICATION]` markers remain. +- [x] Requirements are testable and unambiguous. +- [x] Success criteria are measurable for a docs-only reconciliation. +- [x] Acceptance criteria cover drift inventory, ledger, spec-candidates, roadmap, no runtime changes, no overclaiming, and next-spec sequence. +- [x] Dependencies and assumptions are identified. + +## Scope Control + +- [x] Runtime code, tests, migrations, policies, services, jobs, Filament pages, routes, config, lang files, queue jobs, and UI components are explicitly out of scope. +- [x] Supporting root docs and constitution are edit-only-if-drift. +- [x] Completed specs 307, 308, and 309 are context only and must not be rewritten into active work. +- [x] Customer Review Workspace is preserved as an open productization target unless repo evidence proves otherwise. +- [x] Support Access Governance remains separate from scoped Spec 309 RBAC hardening. + +## Evidence And Traceability + +- [x] Major expected status changes cite repo evidence paths. +- [x] Drift inventory format requires current statement, repo truth, drift type, and action. +- [x] Status labels are defined and no feature may be upgraded to sellable without repo evidence. +- [x] Terminology reconciliation forbids blind `tenant` replacement. + +## Docs-Only Validation + +- [x] `git diff --check` is required. +- [x] A docs-only changed-file guard is required. +- [x] No Pest/PHP tests are required because no runtime behavior changes. +- [x] Close-out must record changed files, drift fixed, open gaps, deferred decisions, validation results, and next recommended specs. + +## Readiness Decision + +- [x] Candidate Selection Gate passes. +- [x] Spec Readiness Gate passes for a preparation package. +- [x] Ready for a later docs-only implementation loop. diff --git a/specs/310-product-truth-docs-drift-reconciliation/plan.md b/specs/310-product-truth-docs-drift-reconciliation/plan.md new file mode 100644 index 00000000..d0424020 --- /dev/null +++ b/specs/310-product-truth-docs-drift-reconciliation/plan.md @@ -0,0 +1,426 @@ +# Implementation Plan: Product Truth / Docs Drift Reconciliation + +**Branch**: `310-product-truth-docs-drift-reconciliation` | **Date**: 2026-05-15 | **Spec**: `specs/310-product-truth-docs-drift-reconciliation/spec.md` +**Input**: Feature specification from `/specs/310-product-truth-docs-drift-reconciliation/spec.md` + +## Summary + +Prepare and implement a documentation-only reconciliation pass after Specs 307, 308, and 309. The implementation must inventory drift first, then update only product-truth markdown where repo evidence proves the current docs are stale, too optimistic, too conservative, wrong-status, wrong-priority, superseded, historical, or unclear. + +## Technical Context + +**Language/Version**: Markdown documentation only; Laravel runtime is present but out of scope +**Primary Dependencies**: Git, Spec Kit markdown artifacts, product docs +**Storage**: N/A - no database or persisted runtime changes +**Testing**: Docs-only validation commands +**Validation Lanes**: docs/prep validation +**Target Platform**: Repository documentation +**Project Type**: Laravel monorepo with docs/specs reconciliation only +**Performance Goals**: N/A +**Constraints**: No runtime code, tests, migrations, policies, services, Filament pages, routes, config, lang files, queue jobs, or UI components +**Scale/Scope**: Targeted docs reconciliation across product docs and this Spec 310 package + +## UI / Surface Guardrail Plan + +- **Guardrail scope**: no operator-facing surface change. +- **Native vs custom classification summary**: N/A. +- **Shared-family relevance**: product-truth docs only. +- **State layers in scope**: none. +- **Audience modes in scope**: N/A. +- **Decision/diagnostic/raw hierarchy plan**: N/A. +- **Raw/support gating plan**: N/A. +- **One-primary-action / duplicate-truth control**: N/A. +- **Handling modes by drift class or surface**: documentation-required review for stale product status claims; report-only for files with no concrete drift. +- **Repository-signal treatment**: review-mandatory for any claim that promotes a capability to repo-real, fast sellable, sellable, historical, or security-hardening completed. +- **Special surface test profiles**: N/A. +- **Required tests or manual smoke**: N/A. +- **Exception path and spread control**: none. +- **Active feature PR close-out entry**: Product Truth / Docs Drift Reconciliation. + +## Shared Pattern & System Fit + +- **Cross-cutting feature marker**: no runtime feature. +- **Systems touched**: product docs and Spec Kit artifacts only. +- **Shared abstractions reused**: existing ledger, roadmap, candidate queue, and Spec Kit close-out patterns. +- **New abstraction introduced? why?**: none. +- **Why the existing abstraction was sufficient or insufficient**: The existing docs are the correct product-truth homes; they only need reconciliation. +- **Bounded deviation / spread control**: none. + +## OperationRun UX Impact + +- **Touches OperationRun start/completion/link UX?**: no runtime UX change. +- **Central contract reused**: N/A. +- **Delegated UX behaviors**: N/A. +- **Surface-owned behavior kept local**: N/A. +- **Queued DB-notification policy**: N/A. +- **Terminal notification path**: N/A. +- **Exception path**: none. + +## Provider Boundary & Portability Fit + +- **Shared provider/platform boundary touched?**: docs terminology only. +- **Provider-owned seams**: Microsoft tenant / Intune references where docs intentionally describe Microsoft-provider truth. +- **Platform-core seams**: Workspace, ManagedEnvironment, governance artifact, Decision Register, RBAC, customer-safe review consumption, and product status labels. +- **Neutral platform terms / contracts preserved**: Use `ManagedEnvironment` or `environment` where product-domain intent is provider-neutral. +- **Retained provider-specific semantics and why**: Keep `tenant` where it names Microsoft tenants, historical spec titles, existing code/test names, or repo-real domain terminology. +- **Bounded extraction or follow-up path**: document-in-feature for unclear terminology that needs future product decision. + +## Constitution Check + +- Inventory-first: PASS. No inventory/runtime truth changes. +- Read/write separation: PASS. Documentation-only. +- Graph contract path: PASS. No Graph calls. +- Deterministic capabilities: PASS. No capability derivation changes. +- RBAC-UX: PASS. Runtime RBAC is not changed; Spec 309 status must be documented accurately. +- Workspace isolation: PASS. No route/data changes. +- Tenant isolation: PASS. No route/data changes. +- Run observability: PASS. No OperationRun lifecycle changes. +- OperationRun start UX: PASS. No start/completion/link UX changes. +- Test governance: PASS. Docs-only, no test-suite impact. +- Proportionality: PASS. No new structure beyond markdown prep artifacts. +- No premature abstraction: PASS. No abstraction introduced. +- Persisted truth: PASS. No new persisted runtime truth. +- Behavioral state: PASS. No runtime state introduced. +- UI semantics: PASS. No UI semantics framework introduced. +- Shared pattern first: PASS. Existing docs locations are reused. +- Provider boundary: PASS if terminology changes remain evidence-based and targeted. +- V1 explicitness / few layers: PASS. Direct markdown reconciliation only. +- Spec discipline / bloat check: PASS. This cleanup spec groups related product-truth drift in one bounded pass. +- Filament-native UI: PASS. No Filament surface changes. +- UI/UX surface taxonomy: PASS. No UI surface changes. + +## Test Governance Check + +- **Test purpose / classification by changed surface**: N/A - docs-only. +- **Affected validation lanes**: docs/prep validation. +- **Why this lane mix is the narrowest sufficient proof**: Runtime behavior is not changed. Changed-file and whitespace validation prove the implementation boundary. +- **Narrowest proving command(s)**: + - `git status --short --branch` + - `git diff --stat` + - `git diff --name-only` + - `git diff --check` + - `git diff --name-only | grep -vE '^(docs/|specs/|README\.md|AGENTS\.md|constitution\.md|\.specify/)' || true` +- **Fixture / helper / factory / seed / context cost risks**: none. +- **Expensive defaults or shared helper growth introduced?**: no. +- **Heavy-family additions, promotions, or visibility changes**: none. +- **Surface-class relief / special coverage rule**: N/A. +- **Closing validation and reviewer handoff**: Reviewer should verify no forbidden runtime path changed and every major status update cites repo evidence. +- **Budget / baseline / trend follow-up**: none. +- **Review-stop questions**: scope creep into runtime files; overclaiming product maturity; rewriting completed specs. +- **Escalation path**: none unless runtime contradiction is discovered; then document as follow-up-spec or decision needed. +- **Active feature PR close-out entry**: Product Truth / Docs Drift Reconciliation. +- **Why no dedicated follow-up spec is needed**: The docs cleanup is bounded; future product work is listed as separate next specs. + +## Project Structure + +### Documentation (this feature) + +```text +specs/310-product-truth-docs-drift-reconciliation/ +├── spec.md +├── plan.md +├── tasks.md +└── checklists/ + └── requirements.md +``` + +### Product Docs Likely Affected In Implementation + +```text +docs/product/implementation-ledger.md +docs/product/spec-candidates.md +docs/product/roadmap.md +``` + +### Supporting Docs To Check, Edit Only If Concrete Drift Exists + +```text +README.md +AGENTS.md +.specify/memory/constitution.md +``` + +`docs/product/product-vision.md` was requested in the user draft but is not present in the current repo scan. If it appears before implementation, check it for concrete drift. + +### Forbidden Runtime Paths + +```text +apps/platform/app/** +apps/platform/database/** +apps/platform/routes/** +apps/platform/resources/**/*.php +apps/platform/resources/**/*.blade.php +apps/platform/tests/** +apps/platform/config/** +apps/platform/lang/** +``` + +**Structure Decision**: Documentation-only feature package plus targeted product-doc edits in the later implementation step. + +## Complexity Tracking + +| Violation | Why Needed | Simpler Alternative Rejected Because | +|---|---|---| +| None | N/A | N/A | + +## Proportionality Review + +- **Current operator problem**: stale product-truth docs can misdirect the next spec and overclaim or underclaim maturity. +- **Existing structure is insufficient because**: the drift crosses ledger, roadmap, candidate queue, and completed spec evidence. +- **Narrowest correct implementation**: markdown-only reconciliation with drift inventory and validation guard. +- **Ownership cost created**: minimal documentation maintenance. +- **Alternative intentionally rejected**: broad roadmap rewrite or runtime correction work. +- **Release truth**: current documentation truth after Specs 307-309. + +## Phase 0: Preparation Evidence + +Prep scan found these repo signals: + +- Spec 307 has completed task markers for builder/page/auth/boundary/browser validation in `specs/307-decision-register-evidence-operationrun-link-polish/tasks.md`. +- Spec 308 records implementation status, changed files, validation results, no-migration/no-asset status, browser smoke, and remaining out-of-scope gaps in `specs/308-decision-register-summary-review-pack/plan.md`. +- Spec 309 records RBAC inventory, confirmed membership-management contradictions fixed, validation results, and runtime/Filament compliance in `specs/309-rbac-role-matrix-access-boundary-audit/tasks.md`. +- Runtime evidence exists for Spec 308 `governance_package.decision_summary` and review-pack inclusion in `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php`, `apps/platform/app/Jobs/GenerateReviewPackJob.php`, `apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php`, and `apps/platform/tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php`. +- Runtime evidence exists for Spec 309 panel access hardening in `apps/platform/app/Models/User.php` and RBAC tests under `apps/platform/tests/Feature/Rbac/`. + +## Phase 1: Read-Only Drift Inventory + +Before editing product docs, refresh the prep-time inventory from `spec.md` against current files. + +Required reads: + +```text +docs/product/implementation-ledger.md +docs/product/spec-candidates.md +docs/product/roadmap.md +README.md +AGENTS.md +.specify/memory/constitution.md +specs/307-decision-register-evidence-operationrun-link-polish/spec.md +specs/307-decision-register-evidence-operationrun-link-polish/plan.md +specs/307-decision-register-evidence-operationrun-link-polish/tasks.md +specs/308-decision-register-summary-review-pack/spec.md +specs/308-decision-register-summary-review-pack/plan.md +specs/308-decision-register-summary-review-pack/tasks.md +specs/309-rbac-role-matrix-access-boundary-audit/spec.md +specs/309-rbac-role-matrix-access-boundary-audit/plan.md +specs/309-rbac-role-matrix-access-boundary-audit/tasks.md +``` + +Search targets: + +```text +Decision Register +Decision Register v1 +approval workflow +proof links +OperationRun links +customer-safe Decision Summary +Review Pack Inclusion +Customer Review Workspace +RBAC role matrix +access boundary +Manager membership management +Tenant membership management +Workspace membership management +/admin +/system +Tenant vs ManagedEnvironment terminology +Productization status +sellable / fast sellable / foundation-only labels +``` + +Required inventory format: + +| Document | Section / Line / Term | Current statement | Repo truth | Drift type | Action | +|---|---|---|---|---|---| +| `docs/product/implementation-ledger.md` | Scoped maintenance / current product position | Ledger is aligned only through Spec 307 and says Decision-Register review-pack/customer-safe follow-through still remains. | Spec 308 records completed implementation and validation in `specs/308-decision-register-summary-review-pack/plan.md`; runtime evidence exists in `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php`, `apps/platform/app/Jobs/GenerateReviewPackJob.php`, and review-pack/review tests. | stale / status wrong | Add Spec 310 maintenance note and mark Spec 308 customer-safe Decision Summary and Review Pack inclusion as repo-real. | +| `docs/product/implementation-ledger.md` | Decision Register capability/status rows | Decision Register is not Greenfield after Spec 306/307, but customer-safe inclusion is still treated as a follow-up. | Spec 265 introduced the operator register, Spec 306 reconciled it as non-Greenfield, Spec 307 added proof/run link polish, and Spec 308 carried customer-safe summary into reviews and review packs. | too conservative / historical completed | Keep operator register as repo-real but not fully productized; add proof/run link and customer-safe summary/review-pack repo-real classifications. | +| `docs/product/implementation-ledger.md` | Customer Review Workspace row | Workspace is marked sellable while text elsewhere says final customer-safe productization remains open. | Existing workspace and released-review detail are repo-real, but Spec 308 explicitly avoids implementing a complete customer portal/workspace v1 and leaves broader customer-safe consumption open. | too optimistic | Keep repo-real/fast-sellable foundation, but mark v1 completion as open and avoid full sellable wording. | +| `docs/product/implementation-ledger.md` | RBAC / access boundary status | Capability-first RBAC is foundation-only; Spec 309 hardening is not reflected. | Spec 309 tasks record Manager membership-management removal, admin/system panel access hardening, and focused tests in `specs/309-rbac-role-matrix-access-boundary-audit/tasks.md`; runtime evidence is in `apps/platform/app/Services/Auth/WorkspaceRoleCapabilityMap.php` and `apps/platform/app/Models/User.php`. | stale / security-hardening completed | Add security-hardening completed status while keeping Support Access Governance separate. | +| `docs/product/implementation-ledger.md` | Open gaps / manual promotions | `decision-register-review-pack-inclusion` and `decision-register-customer-safe-summary` remain recommended promotions. | These were promoted and completed as Spec 308. Remaining work is Customer Review Workspace v1 Completion and Decision-Based Governance Inbox v1. | historical / completed | Remove those as active gaps and replace with current productization gaps. | +| `docs/product/spec-candidates.md` | Scoped maintenance / deep research notes | Candidate queue still says later customer-safe consumption/review-pack inclusion remains after proof/run link polish. | Spec 308 is complete and repo-real. Remaining need is broader Customer Review Workspace completion and Decision-Based Governance Inbox, not the completed 308 slice. | stale / priority wrong | Update candidate notes and recommended ordering. | +| `docs/product/spec-candidates.md` | `Decision Register Customer-Safe Summary / Review-Pack Inclusion` candidate | Candidate is listed as active manual-promotion work. | Candidate was promoted to and completed by `specs/308-decision-register-summary-review-pack/`. | historical / completed | Mark historical/completed and remove from active next work. | +| `docs/product/spec-candidates.md` | Promoted / completed list | Promoted list does not include Specs 306, 307, 308, or 309 in the current completion trail. | Specs 306-309 now define Decision Register reconciliation, proof/run link polish, customer-safe review-pack inclusion, and RBAC hardening history. | too conservative / historical completed | Add these specs to the promoted/completed history. | +| `docs/product/roadmap.md` | Current priority order | Roadmap still orders artifact lifecycle, commercial maturity, PSA, and localization ahead of the new post-309 customer-facing path. | After 307-309, next priority should be Customer Review Workspace v1 Completion, Localization v1 Customer-facing Surfaces, Decision-Based Governance Inbox v1, Commercial Entitlements, Cross-Tenant Promotion, Artifact Lifecycle, PSA Handoff, and Private AI Governance. | priority wrong | Reorder near-term roadmap without broad rewrite. | +| `docs/product/roadmap.md` | Decision Register follow-up wording | Roadmap describes remaining Decision Register customer-safe/review-pack follow-through as open. | Spec 308 completed customer-safe Decision Summary and Review Pack inclusion; remaining gap is broader Decision-Based Governance Inbox and Customer Review Workspace completion. | stale / superseded | Replace completed follow-up wording with current gap wording. | +| `docs/product/roadmap.md` | RBAC audit / access boundary posture | Roadmap does not clearly state Spec 309 is completed scoped hardening. | Spec 309 completed RBAC role matrix and panel access boundary hardening; Support Access Governance remains a separate open candidate. | status wrong | Add post-309 truth and keep support access separate. | +| `README.md`, `AGENTS.md`, `.specify/memory/constitution.md`, `docs/product/product-vision.md` | Supporting docs | No concrete drift found in the checked supporting docs; `docs/product/product-vision.md` is absent. | Current drift is product-doc scope. The constitution already says closed specs should not be retroactively rewritten by default. | no drift | Do not edit unless validation later exposes a direct contradiction. | + +### Completed / Historical Items + +- Spec 307 Decision Register Evidence / OperationRun Link Polish is completed historical work with repo-real proof/run link polish. +- Spec 308 Decision Register Customer-Safe Summary / Review-Pack Inclusion is completed historical work with repo-real `governance_package.decision_summary` and review-pack summary/export inclusion. +- Spec 309 RBAC Role Matrix / Access Boundary Audit is completed scoped security hardening. It does not close Support Access Governance. + +### Still Open Product Gaps + +- Customer Review Workspace v1 Completion remains the next customer-facing productization gap. +- Localization v1 Customer-facing Surfaces remains open even though platform localization foundations are repo-real. +- Decision-Based Governance Inbox v1 remains open as a broader operator governance workflow, not as a Decision Register rebuild. +- Commercial Entitlements / Billing-State Maturity, Cross-Tenant Compare / Promotion Execution, Governance Artifact Lifecycle / Retention, External Support Desk / PSA Handoff, and Private AI Execution Governance remain separate follow-ups. + +### Proposed Minimal Docs Updates + +- Update `docs/product/implementation-ledger.md` for Spec 310 maintenance, Spec 307/308/309 status, corrected Customer Review Workspace maturity, open gaps, and recommended promotions. +- Update `docs/product/spec-candidates.md` to mark completed 307/308/309 items historical/promoted and add the recommended next-spec sequence. +- Update `docs/product/roadmap.md` to reflect post-307/308/309 truth and the current priority order. +- Leave README, AGENTS, constitution, and absent product vision unchanged unless a later validation pass finds direct drift. + +## Phase 2: Implementation Ledger Reconciliation + +Update only stale status areas in `docs/product/implementation-ledger.md`. + +Required outcomes: + +- Add a scoped maintenance note for Spec 310. +- Mark Spec 307 proof/run link polish as repo-real. +- Mark Spec 308 customer-safe Decision Summary and Review Pack inclusion as repo-real. +- Mark Spec 309 RBAC role/access-boundary hardening as `security-hardening completed` if repo evidence remains consistent. +- Update Decision Register status so it is not Greenfield and not overstated as fully productized. +- Update Customer Review Workspace status so v1 completion remains open unless repo evidence proves otherwise. +- Update open gaps and recommended promotions. +- Keep test-run language exact: repo-present tests are not the same as tests run in this branch. + +## Phase 3: Spec Candidate Queue Reconciliation + +Update `docs/product/spec-candidates.md` so completed/promoted items are not active next work. + +Required outcomes: + +- Move Spec 307 Decision Register Evidence / OperationRun Link Polish to historical/promoted/completed. +- Move Spec 308 Decision Register Customer-Safe Summary / Review-Pack Inclusion to historical/promoted/completed. +- Move Spec 309 RBAC Role Matrix & Access Boundary Audit to historical/promoted/completed if listed or implied as active. +- Remove or downgrade broad Decision Register v1 as active Greenfield. +- Keep Decision-Based Governance Inbox v1 open if still needed. +- Promote Customer Review Workspace v1 Completion and Localization v1 Customer-facing Surfaces as the next near-term candidates. +- Keep Commercial Entitlements / Billing-State, Cross-Tenant Compare / Promotion Execution, Governance Artifact Lifecycle, External Support Desk / PSA Handoff, and Private AI Execution Governance as distinct follow-ups. +- Add or refresh the recommended next-spec order. + +## Phase 4: Roadmap Reconciliation + +Update `docs/product/roadmap.md` to reflect current repo truth and remaining gaps. + +Required outcomes: + +- Current state clearly includes Spec 307 proof/run links, Spec 308 customer-safe summary/review-pack inclusion, and Spec 309 RBAC hardening. +- Roadmap sequence prioritizes: + 1. Customer Review Workspace v1 Completion + 2. Localization v1 Customer-facing Surfaces + 3. Decision-Based Governance Inbox v1 + 4. Commercial Entitlements / Billing-State Maturity + 5. Cross-Tenant Compare & Promotion Execution + 6. Governance Artifact Lifecycle & Retention + 7. External Support Desk / PSA Handoff + 8. Private AI Execution Governance Foundation +- RBAC audit is completed hardening, not an active blocker, while Support Access Governance remains separate. +- Customer Review Workspace is not claimed fully complete unless repo evidence proves complete self-serve consumption. + +## Phase 5: Supporting Docs Check + +- Check `README.md` only for stale active-spec or path statements; do not turn it into roadmap. +- Check `AGENTS.md` only for instructions that contradict repo reality; avoid broad rewrites. +- Prefer no constitution changes. Change `.specify/memory/constitution.md` only if it directly contradicts repo truth and the product decision is clear. +- If `docs/product/product-vision.md` exists by implementation time, check it for concrete drift and edit minimally. + +## Phase 6: Validation and Close-Out + +Required commands: + +```bash +git status --short --branch +git diff --stat +git diff --name-only +git diff --check +git diff --name-only | grep -vE '^(docs/|specs/|README\.md|AGENTS\.md|constitution\.md|\.specify/)' || true +``` + +Required close-out in this plan or a Spec 310 close-out section: + +- changed files +- drift categories fixed +- completed/historical candidates +- still-open gaps +- deferred decisions +- next recommended specs +- no runtime changes +- no tests required because docs-only + +## Implementation Close-Out + +### Changed Files + +- `docs/product/implementation-ledger.md` +- `docs/product/spec-candidates.md` +- `docs/product/roadmap.md` +- `specs/310-product-truth-docs-drift-reconciliation/spec.md` +- `specs/310-product-truth-docs-drift-reconciliation/plan.md` +- `specs/310-product-truth-docs-drift-reconciliation/tasks.md` +- `specs/310-product-truth-docs-drift-reconciliation/checklists/requirements.md` + +### Drift Categories Fixed + +- `stale`: Spec 308 customer-safe Decision Summary / Review Pack inclusion is no longer described as pending in product-truth docs. +- `status wrong`: Spec 309 RBAC role matrix / access boundary hardening is now positioned as completed scoped security hardening. +- `too optimistic`: Customer Review Workspace is repo-real, but v1 completion remains an open gap instead of being treated as fully sellable. +- `too conservative`: Decision Register proof/run links and customer-safe summary/review-pack inclusion are now acknowledged as repo-real where evidence supports them. +- `priority wrong`: Roadmap and candidate queue now list the post-310 priority sequence. +- `historical / completed`: Specs 307, 308, and 309 are marked as promoted/completed context, not active next work. +- `superseded`: Broad Decision Register v1 / approval-workflow Greenfield language is closed in favor of the existing operator register plus narrower follow-ups. + +### Completed / Historical Candidates + +- Spec 307 `decision-register-evidence-operationrun-link-polish`: repo-real Decision Register proof/run link polish. +- Spec 308 `decision-register-summary-review-pack`: repo-real customer-safe Decision Summary and Review Pack inclusion. +- Spec 309 `rbac-role-matrix-access-boundary-audit`: scoped `security-hardening completed` for owner-only membership boundaries and admin/system panel access boundaries. + +### Still-Open Gaps + +- Customer Review Workspace v1 Completion. +- Localization v1 Customer-facing Surfaces. +- Decision-Based Governance Inbox v1. +- Commercial Entitlements / Billing-State Maturity. +- Cross-Tenant Compare / Promotion Execution if current spec-backed execution work still lacks runtime/product proof. +- Governance Artifact Lifecycle & Retention. +- External Support Desk / PSA Handoff productization. +- Support Access Governance, separate from Spec 309 hardening. +- Private AI Execution Governance runtime consumer. + +### Supporting Docs + +- `README.md`: checked; no concrete Spec 310 drift found. +- `AGENTS.md`: checked; no concrete Spec 310 drift found. +- `.specify/memory/constitution.md`: checked; no change needed because Spec 309 aligned runtime to existing owner-only membership semantics. +- `docs/product/product-vision.md`: absent in this repo state. +- Completed specs 307, 308, and 309 were not rewritten as active requirements. + +### Validation Results + +- `git status --short --branch`: showed only tracked product-doc changes plus the new `specs/310-product-truth-docs-drift-reconciliation/` docs package. +- `git diff --stat`: product-doc tracked diff only, 116 insertions and 64 deletions. +- `git diff --name-only`: `docs/product/implementation-ledger.md`, `docs/product/roadmap.md`, `docs/product/spec-candidates.md`. +- `git diff --name-only | grep -vE '^(docs/|specs/|README\.md|AGENTS\.md|constitution\.md|\.specify/)' || true`: no output. +- `git status --short | awk '{print $2}' | grep -vE '^(docs/|specs/|README\.md|AGENTS\.md|constitution\.md|\.specify/)' || true`: no output, including untracked Spec 310 files. +- `git diff --check`: passed after close-out. +- Untracked Spec 310 markdown whitespace check using `git diff --check --no-index /dev/null ` for each untracked Spec 310 file: no output. +- Stale-claim search after product-doc edits found no active product-doc claim that Spec 308 customer-safe summary/review-pack inclusion remains pending. Remaining matches are intentional Spec 310 inventory/search-task text, historical completed-spec context, or anti-reopen guardrails. +- No Pest/PHP tests were required or run because this is docs-only and no runtime files changed. + +### Next Recommended Specs + +1. `311-customer-review-workspace-v1-completion` +2. `312-localization-v1-customer-facing-surfaces` +3. `313-decision-based-governance-inbox-v1` +4. `314-commercial-entitlements-billing-state-maturity` +5. `315-cross-tenant-compare-promotion-execution` +6. `316-governance-artifact-lifecycle-retention` +7. `317-external-support-desk-psa-handoff` +8. `318-private-ai-execution-governance-foundation` + +## Spec Readiness Gate + +- `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md` exist. +- Scope is documentation-only and explicitly forbids runtime paths. +- Drift inventory format and target documents are defined. +- Ledger, candidate queue, roadmap, supporting-doc, and validation phases are defined. +- RBAC, workspace/tenant isolation, OperationRun semantics, auditability, and Filament implications are N/A for runtime and are covered as documentation truth only. +- No open question blocks implementation. diff --git a/specs/310-product-truth-docs-drift-reconciliation/spec.md b/specs/310-product-truth-docs-drift-reconciliation/spec.md new file mode 100644 index 00000000..c8dd1e4e --- /dev/null +++ b/specs/310-product-truth-docs-drift-reconciliation/spec.md @@ -0,0 +1,317 @@ +# Feature Specification: Product Truth / Docs Drift Reconciliation + +**Feature Branch**: `310-product-truth-docs-drift-reconciliation` +**Created**: 2026-05-15 +**Status**: Draft +**Input**: User description: "310 should now be Product Truth / Docs Drift Reconciliation after Specs 307, 308, and 309." + +## Spec Candidate Check *(mandatory - SPEC-GATE-001)* + +- **Problem**: Product-truth documents may now understate completed Decision Register and RBAC work after Specs 307, 308, and 309, which can cause the next roadmap/spec decision to target solved work or overclaim unfinished productization. +- **Today's failure**: `docs/product/implementation-ledger.md` still says Decision Register customer-safe summary/review-pack inclusion is missing, and `docs/product/spec-candidates.md` still treats that same slice as open, while Spec 308 carries implementation close-out evidence. +- **User-visible improvement**: Operators and agents get a repo-based truth layer that clearly separates `repo-real`, `foundation-only`, `fast sellable`, `sellable`, `planned only`, `historical`, `superseded`, `open gap`, and `security-hardening completed`. +- **Smallest enterprise-capable version**: A docs-only reconciliation that inventories drift, updates only product-truth docs and Spec 310 close-out artifacts, and lists the next recommended specs without changing runtime behavior. +- **Explicit non-goals**: No runtime code, tests, migrations, policies, services, jobs, Filament pages, routes, config, lang files, localization runtime, billing runtime, artifact lifecycle runtime, Customer Review Workspace v1 implementation, or broad roadmap rewrite. +- **Permanent complexity imported**: None. This spec imports no model, table, state, enum, abstraction, service, UI concept, route, capability, or test family. +- **Why now**: Specs 307, 308, and 309 changed repo truth in close sequence; stale product docs would directly affect the proposed 311/312/313 sequence. +- **Why not local**: A one-line note in one doc would not fix the cross-document status conflict between the ledger, roadmap, spec-candidates queue, and completed spec evidence. +- **Approval class**: Cleanup. +- **Red flags triggered**: Documentation/roadmap drift only. No bloat red flags because this is docs-only and introduces no runtime machinery. +- **Score**: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 1 | Wiederverwendung: 2 | **Gesamt: 11/12** +- **Decision**: approve. + +## Spec Scope Fields *(mandatory)* + +- **Scope**: repository-docs / product-truth. +- **Primary Routes**: N/A - no runtime route or UI surface changes. +- **Data Ownership**: N/A - documentation only; no workspace-owned or managed-environment-owned records change. +- **RBAC**: N/A for runtime. The reconciliation must document Spec 309 RBAC hardening accurately and must not imply support-access governance is solved. + +For canonical-view specs, the spec MUST define: + +- **Default filter behavior when tenant-context is active**: N/A - no canonical runtime view changes. +- **Explicit entitlement checks preventing cross-tenant leakage**: N/A - no runtime entitlement logic changes. + +## Cross-Cutting / Shared Pattern Reuse *(mandatory)* + +- **Cross-cutting feature?**: no runtime feature. +- **Interaction class(es)**: N/A - product status labels in docs only. +- **Systems touched**: `docs/product/implementation-ledger.md`, `docs/product/spec-candidates.md`, `docs/product/roadmap.md`, and this Spec 310 package. +- **Existing pattern(s) to extend**: existing product-truth docs and Spec Kit close-out patterns. +- **Shared contract / presenter / builder / renderer to reuse**: N/A. +- **Why the existing shared path is sufficient or insufficient**: The existing product docs already own roadmap/ledger/candidate truth; this spec only reconciles their statements against repo evidence. +- **Allowed deviation and why**: none. +- **Consistency impact**: Status labels and next-spec sequence must stay consistent across ledger, roadmap, and candidate queue. +- **Review focus**: Confirm no runtime files changed and no completed specs were rewritten as active work. + +## OperationRun UX Impact *(mandatory)* + +- **Touches OperationRun start/completion/link UX?**: no runtime change. The docs may classify OperationRun proof-link polish from Spec 307 as repo-real. +- **Shared OperationRun UX contract/layer reused**: N/A. +- **Delegated start/completion UX behaviors**: N/A. +- **Local surface-owned behavior that remains**: N/A. +- **Queued DB-notification policy**: N/A. +- **Terminal notification path**: N/A. +- **Exception required?**: none. + +## Provider Boundary / Platform Core Check *(mandatory)* + +- **Shared provider/platform boundary touched?**: docs terminology only. +- **Boundary classification**: mixed docs-only review. +- **Seams affected**: product docs may mention Tenant, ManagedEnvironment, workspace, `/admin`, `/system`, Decision Register, customer-safe review consumption, and RBAC. +- **Neutral platform terms preserved or introduced**: Prefer `ManagedEnvironment` or `environment` when the product truth means provider-neutral managed target; keep `tenant` where Microsoft tenant, legacy spec title, test naming, or current code/domain truth requires it. +- **Provider-specific semantics retained and why**: Microsoft tenant/Intune terminology remains where the repo currently owns Microsoft-provider semantics. +- **Why this does not deepen provider coupling accidentally**: This spec updates documentation only and explicitly forbids blind terminology replacement. +- **Follow-up path**: document-in-feature for any unclear terms that need a later product decision. + +## UI / Surface Guardrail Impact *(mandatory)* + +| Surface / Change | Operator-facing surface change? | Native vs Custom | Shared-Family Relevance | State Layers Touched | Exception Needed? | Low-Impact / `N/A` Note | +|---|---:|---|---|---|---:|---| +| Product-truth docs | no | N/A | roadmap/ledger/candidate documentation | none | no | Docs-only reconciliation | + +## Decision-First Surface Role *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing surface change. + +## Audience-Aware Disclosure *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing surface change. + +## UI/UX Surface Classification *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing surface change. + +## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)* + +N/A - no operator-facing surface change. + +## Proportionality Review *(mandatory when structural complexity is introduced)* + +- **New source of truth?**: no. This reconciles existing documentation against repo evidence. +- **New persisted entity/table/artifact?**: no new runtime artifact. Spec Kit markdown files are preparation artifacts only. +- **New abstraction?**: no. +- **New enum/state/reason family?**: no. +- **New cross-domain UI framework/taxonomy?**: no runtime taxonomy. Status labels are documentation labels only. +- **Current operator problem**: Stale product docs can misdirect the next specs and overstate or understate product maturity. +- **Existing structure is insufficient because**: The existing docs are split by purpose and now need cross-document reconciliation after three completed specs. +- **Narrowest correct implementation**: Update only statements with verified drift in product docs and this Spec 310 close-out. +- **Ownership cost**: Minimal documentation upkeep. +- **Alternative intentionally rejected**: A broad roadmap rewrite is rejected because the problem is targeted drift after Specs 307-309. +- **Release truth**: Current-release documentation truth. + +### Compatibility posture + +This feature assumes a pre-production environment, but compatibility is irrelevant because no runtime behavior, data shape, route, or API contract changes. + +## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)* + +- **Test purpose / classification**: N/A - docs-only. +- **Validation lane(s)**: docs/prep validation only. +- **Why this classification and these lanes are sufficient**: The feature changes markdown truth statements only. `git diff --check` plus a docs-only changed-file guard proves the implementation boundary. +- **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**: N/A. +- **Reviewer handoff**: Verify no forbidden runtime files changed and each major status change cites repo evidence by path. +- **Budget / baseline / trend impact**: none. +- **Escalation needed**: none unless runtime contradictions are found. +- **Active feature PR close-out entry**: Product Truth / Docs Drift Reconciliation. +- **Planned validation commands**: + - `git status --short --branch` + - `git diff --stat` + - `git diff --name-only` + - `git diff --check` + - `git diff --name-only | grep -vE '^(docs/|specs/|README\.md|AGENTS\.md|constitution\.md|\.specify/)' || true` + +## Candidate Selection And Completed-Spec Guardrail + +- **Selected candidate**: Product Truth / Docs Drift Reconciliation. +- **Source**: User-provided Spec 310 draft plus repo evidence in `docs/product/implementation-ledger.md`, `docs/product/spec-candidates.md`, `docs/product/roadmap.md`, and Specs 307-309. +- **Why selected**: It is a cleanup gate before the next productization specs, and current docs contain confirmed drift after 308/309. +- **Close alternatives deferred**: + - Customer Review Workspace v1 Completion: should follow after docs truth is reconciled. + - Localization v1 Customer-facing Surfaces: should follow after customer-facing review truth is positioned correctly. + - Decision-Based Governance Inbox v1: should not be confused with the now repo-real operator Decision Register and Spec 308 review-pack inclusion. + - Billing, Artifact Lifecycle, PSA, and AI: remain separate later candidates. +- **Completed-spec check result**: + - Spec 307 is completed-context only because `specs/307-decision-register-evidence-operationrun-link-polish/tasks.md` has completed task markers through validation and browser smoke tasks. + - Spec 308 is completed-context only because `specs/308-decision-register-summary-review-pack/plan.md` records implementation status, changed files, validation results, and remaining gaps outside scope. + - Spec 309 is completed-context only because `specs/309-rbac-role-matrix-access-boundary-audit/tasks.md` records RBAC inventory, confirmed contradictions fixed, validation results, and Filament/runtime compliance. +- **Smallest viable implementation slice**: A docs-only reconciliation across ledger, candidate queue, roadmap, and Spec 310 close-out, with supporting root docs edited only when concrete drift is found. + +## Repo Evidence Snapshot + +| Repo truth | Evidence | +|---|---| +| Spec 307 Decision Register proof/run link polish is repo-real | `specs/307-decision-register-evidence-operationrun-link-polish/tasks.md`; `apps/platform/app/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilder.php`; `apps/platform/app/Filament/Pages/Governance/DecisionRegister.php`; `apps/platform/tests/Unit/Support/GovernanceDecisions/GovernanceDecisionRegisterBuilderTest.php`; `apps/platform/tests/Feature/Governance/DecisionRegisterPageTest.php`; `apps/platform/tests/Feature/Findings/FindingExceptionDecisionRegisterBoundariesTest.php` | +| Spec 308 customer-safe Decision Summary and Review Pack inclusion is repo-real | `specs/308-decision-register-summary-review-pack/plan.md`; `apps/platform/app/Services/EnvironmentReviews/EnvironmentReviewComposer.php`; `apps/platform/app/Jobs/GenerateReviewPackJob.php`; `apps/platform/tests/Feature/EnvironmentReview/EnvironmentReviewExecutivePackTest.php`; `apps/platform/tests/Feature/ReviewPack/EnvironmentReviewDerivedReviewPackTest.php` | +| Spec 309 Manager membership-management contradiction and panel boundary hardening are completed | `specs/309-rbac-role-matrix-access-boundary-audit/tasks.md`; `apps/platform/app/Services/Auth/WorkspaceRoleCapabilityMap.php`; `apps/platform/app/Models/User.php`; `apps/platform/tests/Feature/Rbac/RoleMatrix/ManagerAccessTest.php`; `apps/platform/tests/Feature/Rbac/AdminPanelAccessBoundaryTest.php`; `apps/platform/tests/Feature/Rbac/SystemPanelAccessBoundaryTest.php` | +| Customer Review Workspace remains an open productization target, not automatically sellable because 308 landed | `docs/product/roadmap.md`; `docs/product/implementation-ledger.md`; `specs/308-decision-register-summary-review-pack/plan.md` | +| Support Access Governance remains separate from Spec 309 RBAC hardening | `specs/309-rbac-role-matrix-access-boundary-audit/tasks.md`; `docs/product/spec-candidates.md`; `.specify/memory/constitution.md` | + +## Preparation Drift Inventory + +This is the prep-time inventory. The implementation pass must refresh it before editing product docs. + +| Document | Section / Line / Term | Current statement | Repo truth | Drift type | Action | +|---|---|---|---|---|---| +| `docs/product/implementation-ledger.md` | Fast-sellable section, Decision Register | Says customer-safe summary and review-pack inclusion remain separate follow-ups | Spec 308 close-out and runtime/tests show customer-safe `governance_package.decision_summary` and Review Pack JSON/Markdown inclusion are repo-real | too conservative / status wrong | Update Decision Register and Review Pack rows/status without claiming full Customer Review Workspace completion | +| `docs/product/implementation-ledger.md` | Open gaps | Lists Decision Register customer-safe/review-pack inclusion as missing | Spec 308 completed the narrow inclusion slice; broader Customer Review Workspace and Governance Inbox gaps remain | historical / completed | Move to completed/repo-real and replace gap with Customer Review Workspace v1 completion / Decision-Based Governance Inbox if still open | +| `docs/product/spec-candidates.md` | Decision Register Customer-Safe Summary / Review-Pack Inclusion | Marks the candidate as open manual promotion | Spec 308 is completed-context and implementation-close-out exists | historical / completed | Move to promoted/completed/historical; remove as active next work | +| `docs/product/roadmap.md` | Current priorities | Puts Decision Register customer-safe/review-pack follow-through as still open | Spec 308 closed that narrow follow-through; remaining work is Governance Inbox and Customer Review Workspace completion | priority wrong / too conservative | Reposition roadmap sequence after 307-309 | +| `docs/product/roadmap.md` | Current priorities | Does not yet reflect Spec 309 RBAC hardening as completed security hardening | Spec 309 close-out records Manager membership fixes and `/system`/`/admin` panel-boundary tests | stale | Move RBAC audit from active hardening blocker to completed hardening, with Support Access Governance separate | +| `README.md` / `AGENTS.md` | Repo instructions | No confirmed direct contradiction in prep scan | Current instructions remain useful and process-oriented | no drift found | Do not edit unless implementation scan finds concrete drift | +| `.specify/memory/constitution.md` | RBAC owner-only membership rule | Constitution already states Manager must not manage tenant memberships | Spec 309 aligned runtime to constitution | no drift found | Prefer no constitution changes | + +## User Scenarios & Testing *(mandatory)* + +### User Story 1 - Inventory Product Truth Drift (Priority: P1) + +As a product owner or agent preparing the next spec, I want a drift inventory that names stale product-truth statements and cites repo evidence so the next roadmap decision does not depend on stale documentation. + +**Why this priority**: No documentation edit should happen before the repo-truth mismatch is explicit. + +**Independent Test**: Review the Spec 310 close-out or plan notes and verify each drift row has document location, current statement, repo truth, drift type, and recommended action. + +**Acceptance Scenarios**: + +1. **Given** product docs contain stale status language, **When** the inventory is prepared, **Then** each stale statement is classified before any product doc edit occurs. +2. **Given** a status claim depends on runtime truth, **When** the inventory cites evidence, **Then** it references a spec, runtime file, or test file by path. + +--- + +### User Story 2 - Reconcile Ledger, Queue, and Roadmap (Priority: P1) + +As a roadmap reader, I want the implementation ledger, spec-candidate queue, and roadmap to agree about Specs 307, 308, and 309 so completed work is historical and open gaps are still visible. + +**Why this priority**: This is the core deliverable of Spec 310. + +**Independent Test**: Read `docs/product/implementation-ledger.md`, `docs/product/spec-candidates.md`, and `docs/product/roadmap.md` after implementation and verify that 307/308/309 are not still active next work, while Customer Review Workspace v1 Completion remains an open productization target. + +**Acceptance Scenarios**: + +1. **Given** Spec 308 is completed, **When** the candidate queue is reconciled, **Then** customer-safe summary/review-pack inclusion is historical or completed, not an active manual-promotion follow-up. +2. **Given** Spec 309 is completed, **When** the roadmap is reconciled, **Then** RBAC role matrix/access-boundary hardening is completed security hardening, while Support Access Governance remains open. +3. **Given** Customer Review Workspace foundations are repo-real, **When** product maturity is described, **Then** the docs do not claim the workspace is fully sellable unless self-serve customer consumption is repo-proven. + +--- + +### User Story 3 - Preserve Docs-Only Boundaries (Priority: P1) + +As a reviewer, I want proof that Spec 310 changed no runtime files and did not rewrite completed specs into active requirements so historical evidence and production behavior stay untouched. + +**Why this priority**: The spec is product-truth reconciliation only. Runtime edits would be scope creep. + +**Independent Test**: Run `git diff --name-only`, the docs-only guard, and `git diff --check`. + +**Acceptance Scenarios**: + +1. **Given** the implementation is complete, **When** changed files are listed, **Then** only docs/spec/root markdown files are changed. +2. **Given** completed specs 307, 308, and 309 are used as evidence, **When** they are touched, **Then** changes are limited to historical close-out markers or cross-references, not new implementation requirements. + +### Edge Cases + +- If the implementation scan finds no concrete drift in `README.md`, `AGENTS.md`, or `.specify/memory/constitution.md`, those files must remain unchanged. +- If a term such as `tenant` is historically or Microsoft-provider correct, it must not be blindly replaced with `ManagedEnvironment`. +- If a status cannot be proven from repo evidence, it must be marked `unclear` or `decision needed`, not upgraded to `repo-real` or `sellable`. +- If runtime contradictions are discovered, Spec 310 must document them as follow-up decisions rather than fixing runtime code. + +## Requirements *(mandatory)* + +### Functional Requirements + +- **FR-001**: The implementation MUST produce a drift inventory before editing product-truth docs. +- **FR-002**: The drift inventory MUST include document, section/line/term, current statement, repo truth, drift type, and action. +- **FR-003**: `docs/product/implementation-ledger.md` MUST be reconciled to mark Spec 307 proof/run link polish as repo-real. +- **FR-004**: `docs/product/implementation-ledger.md` MUST be reconciled to mark Spec 308 customer-safe Decision Summary and Review Pack inclusion as repo-real. +- **FR-005**: `docs/product/implementation-ledger.md` MUST be reconciled to mark Spec 309 RBAC role/access-boundary hardening as `security-hardening completed` when repo evidence remains consistent. +- **FR-006**: `docs/product/spec-candidates.md` MUST stop treating completed Spec 307, Spec 308, or Spec 309 work as active next work. +- **FR-007**: `docs/product/spec-candidates.md` MUST keep Customer Review Workspace v1 Completion, Localization v1 Customer-facing Surfaces, Decision-Based Governance Inbox v1, Commercial Entitlements/Billing-State Maturity, Cross-Tenant Compare/Promotion Execution, Governance Artifact Lifecycle/Retention, External Support Desk/PSA Handoff, and Private AI Execution Governance Foundation as distinct follow-up candidates where still repo-accurate. +- **FR-008**: `docs/product/roadmap.md` MUST reflect the post-307/308/309 priority sequence without reopening a broad Decision Register v1. +- **FR-009**: Product docs MUST distinguish `repo-real`, `implemented`, `foundation-only`, `fast sellable`, `sellable`, `planned only`, `spec-backed`, `historical`, `superseded`, `open gap`, `security-hardening completed`, and `decision needed` where those labels are relevant. +- **FR-010**: Product docs MUST NOT claim Customer Review Workspace is fully sellable unless the implementation scan proves completed customer-safe self-serve consumption. +- **FR-011**: Product docs MUST NOT claim RBAC is universally complete; they may only state that Spec 309 verified and fixed the scoped role-matrix/access-boundary issues it covered. +- **FR-012**: Product docs MUST NOT claim billing, artifact lifecycle, support access governance, or AI runtime readiness is complete because adjacent foundations exist. +- **FR-013**: Terminology reconciliation MUST be targeted and evidence-based; no blind `tenant` replacement is allowed. +- **FR-014**: `README.md`, `AGENTS.md`, and `.specify/memory/constitution.md` MAY be edited only when a concrete repo-truth contradiction is found. +- **FR-015**: Completed specs 307, 308, and 309 MUST NOT be rewritten as active work or have close-out/validation history removed. +- **FR-016**: The implementation close-out MUST list changed files, drift fixed, still-open gaps, deferred decisions, next recommended specs, and no-runtime-change confirmation. + +### Non-Functional Requirements + +- **NFR-001**: Changes MUST be minimal and targeted to confirmed product-truth drift. +- **NFR-002**: Every major status update MUST cite repo evidence by path; line numbers are preferred where practical. +- **NFR-003**: Documentation MUST avoid strategy bloat, marketing copy, or speculative roadmap expansion. +- **NFR-004**: The reconciliation MUST be repo-based. Unknowns must be labeled unclear or decision needed. +- **NFR-005**: Completed specs must remain historically accurate. +- **NFR-006**: The next-spec sequence MUST be concrete enough for immediate follow-up prep. + +### Forbidden Runtime Paths + +No files under these paths may change: + +```text +apps/platform/app/** +apps/platform/database/** +apps/platform/routes/** +apps/platform/resources/**/*.php +apps/platform/resources/**/*.blade.php +apps/platform/tests/** +apps/platform/config/** +apps/platform/lang/** +``` + +## Acceptance Criteria + +- **AC-001**: Drift inventory exists in Spec 310 close-out or plan notes before product-doc edits. +- **AC-002**: `implementation-ledger.md` reflects Specs 307, 308, and 309 correctly. +- **AC-003**: `spec-candidates.md` no longer treats completed 307/308/309 work as active next work. +- **AC-004**: `roadmap.md` reflects the current next priority sequence and repo truth. +- **AC-005**: No application runtime files, tests, migrations, config, services, policies, Filament pages, or lang files are changed. +- **AC-006**: Docs clearly distinguish repo-real, foundation-only, fast sellable, sellable, open gap, and follow-up candidate. +- **AC-007**: Customer Review Workspace is positioned as the next productization target, not as fully complete unless repo evidence proves otherwise. +- **AC-008**: Spec 309 is positioned as completed scoped security hardening, while Support Access Governance remains open. +- **AC-009**: `git diff --check` passes. +- **AC-010**: A docs-only changed-file guard returns no forbidden runtime paths. +- **AC-011**: The close-out lists the recommended next 5-8 specs in priority order. + +## Recommended Next Specs After 310 + +Expected sequence unless implementation discovers serious contradictions: + +1. `311-customer-review-workspace-v1-completion` +2. `312-localization-v1-customer-facing-surfaces` +3. `313-decision-based-governance-inbox-v1` +4. `314-commercial-entitlements-billing-state-maturity` +5. `315-cross-tenant-compare-promotion-execution` +6. `316-governance-artifact-lifecycle-retention` +7. `317-external-support-desk-psa-handoff` +8. `318-private-ai-execution-governance-foundation` + +## Success Criteria *(mandatory)* + +- **SC-001**: A reviewer can identify the current status of Decision Register operator surface, proof/run links, customer-safe summary/review-pack inclusion, Customer Review Workspace, and RBAC hardening from product docs without reading implementation code first. +- **SC-002**: The next spec queue no longer points to already-completed 307/308/309 slices. +- **SC-003**: The docs-only guard shows zero forbidden runtime files. +- **SC-004**: The next recommended spec sequence is explicit and matches the open productization gaps. + +## Assumptions + +- Specs 307, 308, and 309 are merged or represented cleanly in the current branch history. +- Product docs are allowed to change in the later implementation pass for this spec. +- `docs/product/product-vision.md` is not present in the current repo scan; if it appears before implementation, it should be checked for concrete drift. +- No Pest/PHP tests are required because the implementation is documentation-only. + +## Risks + +- **Overclaiming product maturity**: Mitigate with required status labels and evidence paths. +- **Erasing historical context**: Mitigate by marking completed/historical instead of rewriting completed specs. +- **Scope creep into runtime fixes**: Mitigate with forbidden paths and docs-only guard. +- **Blind terminology replacement**: Mitigate by requiring targeted, context-aware terminology changes. + +## Open Questions + +- None blocking preparation. +- If implementation finds contradictory runtime evidence for a 307/308/309 claim, document it as `unclear / needs decision` and stop before runtime changes. diff --git a/specs/310-product-truth-docs-drift-reconciliation/tasks.md b/specs/310-product-truth-docs-drift-reconciliation/tasks.md new file mode 100644 index 00000000..2a58af44 --- /dev/null +++ b/specs/310-product-truth-docs-drift-reconciliation/tasks.md @@ -0,0 +1,115 @@ +# Tasks: Product Truth / Docs Drift Reconciliation + +**Input**: `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/spec.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/plan.md` +**Prerequisites**: Specs 307, 308, and 309 are completed context only. +**Scope**: Documentation-only implementation. No application runtime changes. + +**Tests**: No Pest/PHP tests are required because this is docs-only. Validation is `git diff --check` plus a changed-file guard. + +## Test Governance Checklist + +- [x] Lane assignment is named and is the narrowest sufficient proof for the changed behavior: `docs/prep validation`. +- [x] New or changed tests stay in the smallest honest family: N/A, no tests changed. +- [x] Shared helpers, factories, seeds, fixtures, and context defaults stay unchanged. +- [x] Planned validation commands cover the change without pulling in unrelated lane cost. +- [x] The declared surface test profile is N/A because no runtime UI surface changes. +- [x] No material budget, baseline, trend, or escalation note is needed. + +## Format: `[ID] [P?] [Story?] Description with file path` + +## Phase 1: Setup and Read-Only Verification + +**Purpose**: Confirm repo state and refresh repo truth before any product-doc edits. + +- [x] T001 Confirm current branch is `310-product-truth-docs-drift-reconciliation` and the working tree contains only expected Spec 310 prep files using `git status --short --branch` from `/Users/ahmeddarrazi/Documents/projects/wt-plattform`. +- [x] T002 Read `/Users/ahmeddarrazi/Documents/projects/wt-plattform/.specify/memory/constitution.md` before documentation edits. +- [x] T003 [P] Read `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md`. +- [x] T004 [P] Read `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md`. +- [x] T005 [P] Read `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/roadmap.md`. +- [x] T006 [P] Check `/Users/ahmeddarrazi/Documents/projects/wt-plattform/README.md`, `/Users/ahmeddarrazi/Documents/projects/wt-plattform/AGENTS.md`, and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/product-vision.md` if present. +- [x] T007 [P] Read completed-context artifacts under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/307-decision-register-evidence-operationrun-link-polish/`. +- [x] T008 [P] Read completed-context artifacts under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/308-decision-register-summary-review-pack/`. +- [x] T009 [P] Read completed-context artifacts under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/309-rbac-role-matrix-access-boundary-audit/`. +- [x] T010 Run targeted docs/spec searches for Decision Register, proof links, OperationRun links, customer-safe Decision Summary, Review Pack Inclusion, Customer Review Workspace, RBAC, membership management, `/admin`, `/system`, Tenant, ManagedEnvironment, productization, sellable, fast sellable, foundation-only, planned, pending, historical, and superseded terms. + +## Phase 2: User Story 1 - Inventory Product Truth Drift (Priority: P1) + +**Goal**: Produce a drift inventory before editing product-truth docs. + +**Independent Test**: The inventory has document, section/line/term, current statement, repo truth, drift type, and action for each confirmed drift item. + +- [x] T011 [US1] Refresh the prep-time drift inventory from `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/spec.md` against current repo files. +- [x] T012 [US1] Record the implementation drift inventory in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/plan.md` under a close-out or implementation notes section before product-doc edits. +- [x] T013 [US1] Classify each inventory item as stale, contradictory, too optimistic, too conservative, terminology outdated, status wrong, priority wrong, historical/completed, superseded, or unclear/needs decision. +- [x] T014 [US1] Add repo evidence paths for every major status change, preferring line references where practical, in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/plan.md`. + +## Phase 3: User Story 2 - Reconcile Ledger, Queue, and Roadmap (Priority: P1) + +**Goal**: Update the product-truth docs so completed work is historical and open gaps are still visible. + +**Independent Test**: The ledger, spec-candidates, and roadmap agree on Spec 307, Spec 308, Spec 309, Customer Review Workspace, Localization, Decision Inbox, Billing, Cross-Tenant Promotion, Artifact Lifecycle, PSA Handoff, and AI follow-up status. + +- [x] T015 [US2] Update scoped maintenance and status model language in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md` for Spec 310. +- [x] T016 [US2] Mark Spec 307 Decision Register proof/run link polish as repo-real in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md`. +- [x] T017 [US2] Mark Spec 308 customer-safe Decision Summary and Review Pack inclusion as repo-real in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md`. +- [x] T018 [US2] Mark Spec 309 RBAC Role Matrix / Access Boundary hardening as `security-hardening completed` in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md` if the implementation scan confirms the prep evidence still holds. +- [x] T019 [US2] Update Decision Register capability/status rows and narrative in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md` so the operator register, proof/run links, and customer-safe review-pack inclusion are not described as Greenfield or missing. +- [x] T020 [US2] Update Customer Review Workspace status in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md` so repo-real foundations are acknowledged but v1 completion remains open unless repo evidence proves full self-serve productization. +- [x] T021 [US2] Update open gaps and recommended promotions in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md`, removing the completed Spec 308 gap and keeping Support Access Governance separate from Spec 309 hardening. +- [x] T022 [US2] Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md` so Spec 307 proof/run link polish is historical/completed, not active next work. +- [x] T023 [US2] Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md` so Spec 308 customer-safe summary/review-pack inclusion is historical/completed, not active next work. +- [x] T024 [US2] Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md` so Spec 309 RBAC Role Matrix / Access Boundary Audit is historical/completed if listed or implied as active. +- [x] T025 [US2] Remove or downgrade any broad Decision Register v1 / Approval Workflow Greenfield active-candidate language in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md`. +- [x] T026 [US2] Promote or preserve Customer Review Workspace v1 Completion, Localization v1 Customer-facing Surfaces, and Decision-Based Governance Inbox v1 as the recommended near-term follow-ups in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md`. +- [x] T027 [US2] Preserve Commercial Entitlements / Billing-State Maturity, Cross-Tenant Compare / Promotion Execution, Governance Artifact Lifecycle / Retention, External Support Desk / PSA Handoff, and Private AI Execution Governance Foundation as separate later follow-ups in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md`. +- [x] T028 [US2] Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/roadmap.md` with post-307/308/309 current state and the next priority order. +- [x] T029 [US2] Ensure `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/roadmap.md` positions RBAC audit as completed scoped hardening while Support Access Governance remains separate. +- [x] T030 [US2] Ensure `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/roadmap.md` does not claim Customer Review Workspace is fully sellable unless repo evidence proves complete customer-safe self-serve consumption. + +## Phase 4: User Story 3 - Preserve Docs-Only Boundaries (Priority: P1) + +**Goal**: Keep implementation strictly documentation-only and preserve completed-spec history. + +**Independent Test**: Changed-file guard outputs no forbidden runtime paths and completed specs retain close-out/validation history. + +- [x] T031 [US3] Check `/Users/ahmeddarrazi/Documents/projects/wt-plattform/README.md`; edit only if a concrete active-spec, path, or command drift is found. +- [x] T032 [US3] Check `/Users/ahmeddarrazi/Documents/projects/wt-plattform/AGENTS.md`; edit only if agent instructions contradict current repo reality. +- [x] T033 [US3] Check `/Users/ahmeddarrazi/Documents/projects/wt-plattform/.specify/memory/constitution.md`; prefer no change unless a direct contradiction and clear product decision exist. +- [x] T034 [US3] If `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/product-vision.md` exists, check it for stale Decision Register, Review Pack, Customer Review Workspace, RBAC, AI, or commercial maturity statements and edit minimally only if drift is confirmed. +- [x] T035 [US3] Confirm completed specs 307, 308, and 309 were not rewritten as active requirements and their close-out/validation/completed task history remains intact. +- [x] T036 [US3] Confirm no files under `/Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/` changed. + +## Phase 5: Validation and Close-Out + +**Purpose**: Prove docs-only boundary and record remaining gaps. + +- [x] T037 Run `git diff --name-only` from `/Users/ahmeddarrazi/Documents/projects/wt-plattform`. +- [x] T038 Run `git diff --name-only | grep -vE '^(docs/|specs/|README\.md|AGENTS\.md|constitution\.md|\.specify/)' || true` from `/Users/ahmeddarrazi/Documents/projects/wt-plattform` and confirm it outputs no forbidden runtime files. +- [x] T039 Run `git diff --check` from `/Users/ahmeddarrazi/Documents/projects/wt-plattform`. +- [x] T040 Run stale-claim searches for `Decision Register v1`, proof-link pending claims, customer-safe/review-pack inclusion open claims, and RBAC pending claims across `/Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product` and `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs`. +- [x] T041 Update `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/plan.md` with implementation close-out: changed files, drift categories fixed, completed/historical candidates, still-open gaps, deferred decisions, next recommended specs, validation commands, and no-runtime-change confirmation. +- [x] T042 Confirm no Pest/PHP tests were required because this is docs-only in `/Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/plan.md`. + +## Dependencies + +- T001-T010 must finish before any product-doc edit. +- T011-T014 must finish before T015-T030. +- T015-T030 can be grouped by file but should preserve cross-document consistency. +- T031-T036 must finish before validation. +- T037-T042 are final validation and close-out. + +## Parallel Work Examples + +- T003-T009 can run in parallel after T001-T002. +- T015-T021, T022-T027, and T028-T030 can be worked as separate file groups after the drift inventory exists. +- T031-T034 can run in parallel because each checks a distinct supporting doc. + +## Implementation Strategy + +1. Complete drift inventory first. +2. Reconcile `implementation-ledger.md`. +3. Reconcile `spec-candidates.md`. +4. Reconcile `roadmap.md`. +5. Touch supporting docs only for concrete drift. +6. Validate changed files and whitespace. +7. Record close-out and next spec sequence. -- 2.45.2