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:

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