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

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)

specs/310-product-truth-docs-drift-reconciliation/
├── spec.md
├── plan.md
├── tasks.md
└── checklists/
    └── requirements.md

Product Docs Likely Affected In Implementation

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

Supporting Docs To Check, Edit Only If Concrete Drift Exists

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

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:

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:

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:

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