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