TenantAtlas/specs/310-product-truth-docs-drift-reconciliation/spec.md

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:

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.