ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
platform-dev
TenantAtlas/specs/310-product-truth-docs-drift-reconciliation/tasks.md
ahmido 52bb4a0afc docs: reconcile product truth after specs 307-309 (#365) 
## Summary
- reconcile product-truth documentation after Specs 307, 308, and 309
- update the implementation ledger, roadmap, and spec-candidates queue to reflect completed Decision Register, review-pack, and RBAC hardening work
- add the Spec 310 reconciliation artifacts and close-out notes
- keep the slice docs-only with no runtime code changes

## Validation
- `git diff --name-only`
- `git diff --name-only | grep -vE '^(docs/|specs/|README\.md|AGENTS\.md|constitution\.md|\.specify/)' || true`
- `git diff --check`
- no Pest/PHP tests were required because this change is documentation-only

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #365
2026-05-15 14:54:08 +00:00

12 KiB
Raw Permalink Blame History

Tasks: Product Truth / Docs Drift Reconciliation

Input: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/spec.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/plan.md Prerequisites: Specs 307, 308, and 309 are completed context only. Scope: Documentation-only implementation. No application runtime changes.

Tests: No Pest/PHP tests are required because this is docs-only. Validation is git diff --check plus a changed-file guard.

Test Governance Checklist

  • Lane assignment is named and is the narrowest sufficient proof for the changed behavior: docs/prep validation.
  • New or changed tests stay in the smallest honest family: N/A, no tests changed.
  • Shared helpers, factories, seeds, fixtures, and context defaults stay unchanged.
  • Planned validation commands cover the change without pulling in unrelated lane cost.
  • The declared surface test profile is N/A because no runtime UI surface changes.
  • No material budget, baseline, trend, or escalation note is needed.

Format: [ID] [P?] [Story?] Description with file path

Phase 1: Setup and Read-Only Verification

Purpose: Confirm repo state and refresh repo truth before any product-doc edits.

  • T001 Confirm current branch is 310-product-truth-docs-drift-reconciliation and the working tree contains only expected Spec 310 prep files using git status --short --branch from /Users/ahmeddarrazi/Documents/projects/wt-plattform.
  • T002 Read /Users/ahmeddarrazi/Documents/projects/wt-plattform/.specify/memory/constitution.md before documentation edits.
  • T003 [P] Read /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md.
  • T004 [P] Read /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md.
  • T005 [P] Read /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/roadmap.md.
  • T006 [P] Check /Users/ahmeddarrazi/Documents/projects/wt-plattform/README.md, /Users/ahmeddarrazi/Documents/projects/wt-plattform/AGENTS.md, and /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/product-vision.md if present.
  • T007 [P] Read completed-context artifacts under /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/307-decision-register-evidence-operationrun-link-polish/.
  • T008 [P] Read completed-context artifacts under /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/308-decision-register-summary-review-pack/.
  • T009 [P] Read completed-context artifacts under /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/309-rbac-role-matrix-access-boundary-audit/.
  • T010 Run targeted docs/spec searches for Decision Register, proof links, OperationRun links, customer-safe Decision Summary, Review Pack Inclusion, Customer Review Workspace, RBAC, membership management, /admin, /system, Tenant, ManagedEnvironment, productization, sellable, fast sellable, foundation-only, planned, pending, historical, and superseded terms.

Phase 2: User Story 1 - Inventory Product Truth Drift (Priority: P1)

Goal: Produce a drift inventory before editing product-truth docs.

Independent Test: The inventory has document, section/line/term, current statement, repo truth, drift type, and action for each confirmed drift item.

  • T011 [US1] Refresh the prep-time drift inventory from /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/spec.md against current repo files.
  • T012 [US1] Record the implementation drift inventory in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/plan.md under a close-out or implementation notes section before product-doc edits.
  • T013 [US1] Classify each inventory item as stale, contradictory, too optimistic, too conservative, terminology outdated, status wrong, priority wrong, historical/completed, superseded, or unclear/needs decision.
  • T014 [US1] Add repo evidence paths for every major status change, preferring line references where practical, in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/plan.md.

Phase 3: User Story 2 - Reconcile Ledger, Queue, and Roadmap (Priority: P1)

Goal: Update the product-truth docs so completed work is historical and open gaps are still visible.

Independent Test: The ledger, spec-candidates, and roadmap agree on Spec 307, Spec 308, Spec 309, Customer Review Workspace, Localization, Decision Inbox, Billing, Cross-Tenant Promotion, Artifact Lifecycle, PSA Handoff, and AI follow-up status.

  • T015 [US2] Update scoped maintenance and status model language in /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md for Spec 310.
  • T016 [US2] Mark Spec 307 Decision Register proof/run link polish as repo-real in /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md.
  • T017 [US2] Mark Spec 308 customer-safe Decision Summary and Review Pack inclusion as repo-real in /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md.
  • T018 [US2] Mark Spec 309 RBAC Role Matrix / Access Boundary hardening as security-hardening completed in /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md if the implementation scan confirms the prep evidence still holds.
  • T019 [US2] Update Decision Register capability/status rows and narrative in /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md so the operator register, proof/run links, and customer-safe review-pack inclusion are not described as Greenfield or missing.
  • T020 [US2] Update Customer Review Workspace status in /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md so repo-real foundations are acknowledged but v1 completion remains open unless repo evidence proves full self-serve productization.
  • T021 [US2] Update open gaps and recommended promotions in /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/implementation-ledger.md, removing the completed Spec 308 gap and keeping Support Access Governance separate from Spec 309 hardening.
  • T022 [US2] Update /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md so Spec 307 proof/run link polish is historical/completed, not active next work.
  • T023 [US2] Update /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md so Spec 308 customer-safe summary/review-pack inclusion is historical/completed, not active next work.
  • T024 [US2] Update /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md so Spec 309 RBAC Role Matrix / Access Boundary Audit is historical/completed if listed or implied as active.
  • T025 [US2] Remove or downgrade any broad Decision Register v1 / Approval Workflow Greenfield active-candidate language in /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md.
  • T026 [US2] Promote or preserve Customer Review Workspace v1 Completion, Localization v1 Customer-facing Surfaces, and Decision-Based Governance Inbox v1 as the recommended near-term follow-ups in /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md.
  • T027 [US2] Preserve Commercial Entitlements / Billing-State Maturity, Cross-Tenant Compare / Promotion Execution, Governance Artifact Lifecycle / Retention, External Support Desk / PSA Handoff, and Private AI Execution Governance Foundation as separate later follow-ups in /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/spec-candidates.md.
  • T028 [US2] Update /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/roadmap.md with post-307/308/309 current state and the next priority order.
  • T029 [US2] Ensure /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/roadmap.md positions RBAC audit as completed scoped hardening while Support Access Governance remains separate.
  • T030 [US2] Ensure /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/roadmap.md does not claim Customer Review Workspace is fully sellable unless repo evidence proves complete customer-safe self-serve consumption.

Phase 4: User Story 3 - Preserve Docs-Only Boundaries (Priority: P1)

Goal: Keep implementation strictly documentation-only and preserve completed-spec history.

Independent Test: Changed-file guard outputs no forbidden runtime paths and completed specs retain close-out/validation history.

  • T031 [US3] Check /Users/ahmeddarrazi/Documents/projects/wt-plattform/README.md; edit only if a concrete active-spec, path, or command drift is found.
  • T032 [US3] Check /Users/ahmeddarrazi/Documents/projects/wt-plattform/AGENTS.md; edit only if agent instructions contradict current repo reality.
  • T033 [US3] Check /Users/ahmeddarrazi/Documents/projects/wt-plattform/.specify/memory/constitution.md; prefer no change unless a direct contradiction and clear product decision exist.
  • T034 [US3] If /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product/product-vision.md exists, check it for stale Decision Register, Review Pack, Customer Review Workspace, RBAC, AI, or commercial maturity statements and edit minimally only if drift is confirmed.
  • T035 [US3] Confirm completed specs 307, 308, and 309 were not rewritten as active requirements and their close-out/validation/completed task history remains intact.
  • T036 [US3] Confirm no files under /Users/ahmeddarrazi/Documents/projects/wt-plattform/apps/platform/ changed.

Phase 5: Validation and Close-Out

Purpose: Prove docs-only boundary and record remaining gaps.

  • T037 Run git diff --name-only from /Users/ahmeddarrazi/Documents/projects/wt-plattform.
  • T038 Run git diff --name-only | grep -vE '^(docs/|specs/|README\.md|AGENTS\.md|constitution\.md|\.specify/)' || true from /Users/ahmeddarrazi/Documents/projects/wt-plattform and confirm it outputs no forbidden runtime files.
  • T039 Run git diff --check from /Users/ahmeddarrazi/Documents/projects/wt-plattform.
  • T040 Run stale-claim searches for Decision Register v1, proof-link pending claims, customer-safe/review-pack inclusion open claims, and RBAC pending claims across /Users/ahmeddarrazi/Documents/projects/wt-plattform/docs/product and /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs.
  • T041 Update /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/plan.md with implementation close-out: changed files, drift categories fixed, completed/historical candidates, still-open gaps, deferred decisions, next recommended specs, validation commands, and no-runtime-change confirmation.
  • T042 Confirm no Pest/PHP tests were required because this is docs-only in /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/310-product-truth-docs-drift-reconciliation/plan.md.

Dependencies

  • T001-T010 must finish before any product-doc edit.
  • T011-T014 must finish before T015-T030.
  • T015-T030 can be grouped by file but should preserve cross-document consistency.
  • T031-T036 must finish before validation.
  • T037-T042 are final validation and close-out.

Parallel Work Examples

  • T003-T009 can run in parallel after T001-T002.
  • T015-T021, T022-T027, and T028-T030 can be worked as separate file groups after the drift inventory exists.
  • T031-T034 can run in parallel because each checks a distinct supporting doc.

Implementation Strategy

  1. Complete drift inventory first.
  2. Reconcile implementation-ledger.md.
  3. Reconcile spec-candidates.md.
  4. Reconcile roadmap.md.
  5. Touch supporting docs only for concrete drift.
  6. Validate changed files and whitespace.
  7. Record close-out and next spec sequence.