ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
59fc90a4db
TenantAtlas/specs/158-artifact-truth-semantics/tasks.md
ahmido e7c9b4b853 feat: implement governance artifact truth semantics (#188) 
## Summary
- add shared governance artifact truth presentation and badge taxonomy
- integrate artifact-truth messaging across baseline, evidence, tenant review, review pack, and operation run surfaces
- add focused regression coverage and spec artifacts for artifact truth semantics

## Testing
- not run in this step

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #188
2026-03-23 00:13:57 +00:00

18 KiB
Raw Blame History

Tasks: Governance Artifact Truthful Outcomes & Fidelity Semantics

Input: Design documents from /specs/158-artifact-truth-semantics/ Prerequisites: plan.md, spec.md, research.md, data-model.md, contracts/artifact-truth.openapi.yaml, quickstart.md

Tests: Tests are REQUIRED for this feature because it changes runtime behavior and operator-visible semantics across existing Laravel/Filament surfaces. Organization: Tasks are grouped by user story so each story can be implemented and validated independently.

Phase 1: Setup (Shared Infrastructure)

Purpose: Establish setup scaffolding, curated validation cases, and failing test shells for artifact-truth work.

  • T001 Create curated artifact-truth fixture builders and case datasets in tests/Feature/Concerns/BuildsGovernanceArtifactTruthFixtures.php and tests/Feature/Monitoring/ArtifactTruthManualCasesDataset.php
  • T002 [P] Create failing test shells for the shared truth layer and adopted surfaces in tests/Unit/Badges/GovernanceArtifactTruthTest.php, tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php, tests/Feature/Filament/BaselineSnapshotDegradedStateTest.php, tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, tests/Feature/TenantReview/TenantReviewUiContractTest.php, and tests/Feature/ReviewPack/ReviewPackResourceTest.php
  • T003 [P] Capture the 12-case manual validation matrix and first-slice verification targets in specs/158-artifact-truth-semantics/quickstart.md

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Build the shared truth model and cross-cutting helpers that every story depends on.

⚠️ CRITICAL: No user story work can begin until this phase is complete.

  • T004 Implement the ArtifactTruthEnvelope, ArtifactTruthDimension, and ArtifactTruthCause read-model DTOs in app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthEnvelope.php, app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthDimension.php, and app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthCause.php
  • T005 Implement family-specific truth resolution and next-action composition in app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php
  • T006 [P] Extend shared taxonomy and badge registration for artifact-truth axes in app/Support/Badges/OperatorOutcomeTaxonomy.php, app/Support/Badges/BadgeCatalog.php, and app/Support/Badges/BadgeDomain.php
  • T007 [P] Wire centralized reason translation into artifact-truth presentation in app/Support/ReasonTranslation/ReasonPresenter.php and app/Support/ReasonTranslation/ReasonTranslator.php
  • T008 [P] Add canonical artifact/run navigation helpers and a conditional summary/context enrichment seam for the truth layer in app/Support/OperationRunLinks.php, app/Support/OperationCatalog.php, app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php, and app/Models/OperationRun.php
  • T009 [P] Add foundational unit coverage for truth-envelope mapping and badge remaps in tests/Unit/Badges/GovernanceArtifactTruthTest.php, tests/Unit/Evidence/EvidenceSnapshotBadgeTest.php, and tests/Unit/TenantReview/TenantReviewBadgeTest.php

Checkpoint: Shared truth foundation is ready; user story work can now proceed.

Phase 3: User Story 1 - Distinguish Real Artifact Truth From Cosmetic Success (Priority: P1) 🎯 MVP

Goal: Make baseline, evidence, review, and review-pack surfaces clearly distinguish artifact existence from trustworthy usability.

Independent Test: Prepare degraded and healthy examples for each artifact family and verify that one inspection step answers whether a trustworthy artifact exists.

Tests for User Story 1

  • T010 [P] [US1] Add false-green baseline list/detail and artifact-targeted run-detail regressions in tests/Feature/Filament/BaselineSnapshotDegradedStateTest.php, tests/Feature/Filament/BaselineSnapshotFidelityVisibilityTest.php, tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php, and tests/Feature/Monitoring/OperationsCanonicalUrlsTest.php
  • T011 [P] [US1] Add truthful artifact-existence feature coverage for evidence, reviews, and review packs in tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, tests/Feature/TenantReview/TenantReviewLifecycleTest.php, and tests/Feature/ReviewPack/ReviewPackResourceTest.php

Implementation for User Story 1

  • T012 [US1] Apply baseline artifact-existence and trust messaging to list/detail surfaces in app/Filament/Resources/BaselineSnapshotResource.php, app/Filament/Resources/BaselineSnapshotResource/Pages/ListBaselineSnapshots.php, and app/Filament/Resources/BaselineSnapshotResource/Pages/ViewBaselineSnapshot.php
  • T013 [US1] Apply evidence artifact-existence and trust messaging to tenant evidence list/detail surfaces in app/Filament/Resources/EvidenceSnapshotResource.php, app/Filament/Resources/EvidenceSnapshotResource/Pages/ListEvidenceSnapshots.php, and app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
  • T014 [US1] Apply review existence-versus-publishability messaging to tenant review list/detail surfaces in app/Filament/Resources/TenantReviewResource.php, app/Filament/Resources/TenantReviewResource/Pages/ListTenantReviews.php, and app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php
  • T015 [US1] Apply review-pack existence-versus-trustworthy-output messaging to pack list/detail surfaces in app/Filament/Resources/ReviewPackResource.php, app/Filament/Resources/ReviewPackResource/Pages/ListReviewPacks.php, and app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php
  • T016 [US1] Add artifact-produced and artifact-usable summaries to canonical run detail in app/Filament/Resources/OperationRunResource.php and app/Filament/Pages/Operations/TenantlessOperationRunViewer.php

Checkpoint: User Story 1 is complete when each adopted surface clearly distinguishes “artifact exists” from “artifact is trustworthy and usable.”

Phase 4: User Story 2 - Understand Fidelity And Readiness Without Decoding Diagnostics (Priority: P1)

Goal: Separate completeness, freshness, support limitations, and publication readiness so operators understand the degraded dimension and required action.

Independent Test: Review mixed-condition examples and confirm that primary vs diagnostic state, blocker guidance, and “No action needed” semantics are rendered correctly.

Tests for User Story 2

  • T017 [P] [US2] Add mixed-dimension and diagnostic-boundary tests in tests/Unit/Badges/GovernanceArtifactTruthTest.php, tests/Feature/Evidence/EvidenceOverviewPageTest.php, and tests/Feature/ReviewPack/ReviewPackResourceTest.php
  • T018 [P] [US2] Add blocker-guidance, evidence empty-state, historical-artifact, and explicit no-action-needed regressions in tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, tests/Feature/Evidence/EvidenceOverviewPageTest.php, tests/Feature/TenantReview/TenantReviewUiContractTest.php, tests/Feature/ReviewPack/ReviewPackResourceTest.php, and tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php

Implementation for User Story 2

  • T019 [US2] Separate primary versus diagnostic baseline fidelity semantics in app/Filament/Resources/BaselineSnapshotResource.php, app/Support/Badges/Domains/BaselineSnapshotFidelityBadge.php, and app/Services/Baselines/SnapshotRendering/FidelityState.php
  • T020 [US2] Separate evidence completeness, freshness, metadata-only, and reference-only semantics in app/Filament/Resources/EvidenceSnapshotResource.php, app/Filament/Pages/Monitoring/EvidenceOverview.php, and app/Models/EvidenceSnapshot.php
  • T021 [US2] Separate review completeness, publication readiness, and blocker guidance in app/Filament/Resources/TenantReviewResource.php, app/Filament/Pages/Reviews/ReviewRegister.php, app/Models/TenantReview.php, and app/Services/TenantReviews/TenantReviewReadinessGate.php
  • T022 [US2] Separate review-pack lifecycle from provenance and readiness semantics in app/Filament/Resources/ReviewPackResource.php, app/Models/ReviewPack.php, and app/Support/Badges/Domains/ReviewPackStatusBadge.php
  • T023 [US2] Add explicit next-step and “No action needed” handling to the shared truth layer and run detail in app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php, app/Support/ReasonTranslation/ReasonPresenter.php, and app/Filament/Resources/OperationRunResource.php

Checkpoint: User Story 2 is complete when degraded states are dimension-specific, diagnostics stay secondary, and operator follow-up guidance is explicit.

Phase 5: User Story 3 - Reuse One Truth Model Across The Governance Chain (Priority: P2)

Goal: Keep equivalent artifact states semantically consistent across baseline, evidence, review, review-pack, and canonical workspace summaries.

Independent Test: Compare equivalent artifact conditions across the adopted surfaces and verify that labels, severity, and count/filter behavior remain consistent and tenant-safe.

Tests for User Story 3

  • T024 [P] [US3] Add cross-surface vocabulary consistency coverage in tests/Feature/Evidence/EvidenceOverviewPageTest.php, tests/Feature/TenantReview/TenantReviewRegisterTest.php, tests/Feature/ReviewPack/TenantReviewDerivedReviewPackTest.php, and tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php
  • T025 [P] [US3] Add explicit positive and negative canonical authorization tests for truth labels, counts, and filter values in tests/Feature/ManagedTenants/AuthorizationSemanticsTest.php, tests/Feature/TenantReview/TenantReviewRegisterRbacTest.php, and tests/Feature/TenantReview/TenantReviewRegisterPrefilterTest.php

Implementation for User Story 3

  • T026 [US3] Normalize shared artifact vocabulary and semantic labels across badge domains in app/Support/Badges/OperatorOutcomeTaxonomy.php, app/Support/Badges/Domains/EvidenceCompletenessBadge.php, app/Support/Badges/Domains/TenantReviewCompletenessStateBadge.php, app/Support/Badges/Domains/TenantReviewStatusBadge.php, and app/Support/Badges/Domains/ReviewPackStatusBadge.php
  • T027 [US3] Apply the shared truth vocabulary to canonical evidence and review summaries without leaking unauthorized tenant state in app/Filament/Pages/Monitoring/EvidenceOverview.php, app/Filament/Pages/Reviews/ReviewRegister.php, app/Services/TenantReviews/TenantReviewRegisterService.php, and app/Support/Filament/CanonicalAdminTenantFilterState.php
  • T028 [US3] Align related run and artifact navigation with the shared truth model in app/Support/OperationRunLinks.php, app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php, app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php, and app/Filament/Resources/ReviewPackResource.php
  • T029 [US3] Apply semantic migration away from overloaded labels in app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php, app/Filament/Resources/BaselineSnapshotResource.php, app/Filament/Resources/EvidenceSnapshotResource.php, app/Filament/Resources/TenantReviewResource.php, and app/Filament/Resources/ReviewPackResource.php

Checkpoint: User Story 3 is complete when equivalent artifact states read consistently across all adopted governance surfaces and canonical summaries remain entitlement-safe.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Final regression coverage, guard validation, and formatting.

  • T030 [P] Run and stabilize focused artifact-truth regression suites in tests/Feature/Filament/BaselineSnapshotDegradedStateTest.php, tests/Feature/Filament/BaselineSnapshotFidelityVisibilityTest.php, tests/Feature/Evidence/EvidenceOverviewPageTest.php, tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, tests/Feature/TenantReview/TenantReviewRegisterTest.php, tests/Feature/TenantReview/TenantReviewUiContractTest.php, tests/Feature/ReviewPack/ReviewPackResourceTest.php, and tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php
  • T031 [P] Run and stabilize guard and authorization regressions in tests/Feature/Guards/ActionSurfaceContractTest.php, tests/Feature/Guards/FilamentTableStandardsGuardTest.php, and tests/Feature/ManagedTenants/AuthorizationSemanticsTest.php
  • T032 Run formatting, complete the 12-case quickstart validation checklist, and review affected list surfaces against docs/product/standards/list-surface-review-checklist.md for specs/158-artifact-truth-semantics/quickstart.md and the modified PHP files under app/ and tests/

Dependencies & Execution Order

Phase Dependencies

  • Phase 1: Setup: No dependencies; start immediately.
  • Phase 2: Foundational: Depends on Phase 1; blocks all user stories.
  • Phase 3: User Story 1: Depends on Phase 2.
  • Phase 4: User Story 2: Depends on Phase 2 and is best executed after User Story 1 because it refines the same surfaces and helpers.
  • Phase 5: User Story 3: Depends on Phase 2 and is best executed after User Stories 1 and 2 because it normalizes the completed semantics across surfaces.
  • Phase 6: Polish: Depends on all desired user stories being complete.

User Story Dependencies

  • US1 (P1): Primary MVP slice; no user-story dependency after foundational work.
  • US2 (P1): Logically depends on the shared truth layer and overlaps the same surfaces as US1, so sequence after US1 to reduce merge and semantic conflicts.
  • US3 (P2): Depends on the shared truth layer and the adopted semantics from US1 and US2 so it can normalize them across canonical and tenant surfaces.

Within Each User Story

  • Tests should be added first and observed failing before implementation.
  • Shared presenter or badge changes come before surface adoption.
  • Resource/page changes come before canonical run-detail polish.
  • Canonical RBAC regression coverage must pass before the story is considered complete.

Parallel Opportunities

  • T002, T003 can run in parallel during setup after the fixture dataset exists.
  • T006, T007, T008, T009 can run in parallel during foundational work once the support classes exist.
  • Test tasks marked [P] within each story can run in parallel.
  • T012 through T015 can be split across developers after T005 through T008 are complete, but T016 should follow once family-specific truth semantics are available.
  • T030 and T031 can run in parallel during final validation.

Parallel Example: User Story 1

# Parallel test authoring
T010 tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php
T011 tests/Feature/Evidence/EvidenceSnapshotResourceTest.php + tests/Feature/TenantReview/TenantReviewLifecycleTest.php + tests/Feature/ReviewPack/ReviewPackResourceTest.php

# Parallel surface adoption after shared truth foundation is ready
T012 app/Filament/Resources/BaselineSnapshotResource.php
T013 app/Filament/Resources/EvidenceSnapshotResource.php
T014 app/Filament/Resources/TenantReviewResource.php
T015 app/Filament/Resources/ReviewPackResource.php

Parallel Example: User Story 2

# Parallel diagnostic/readiness coverage
T017 tests/Unit/Badges/GovernanceArtifactTruthTest.php + tests/Feature/Evidence/EvidenceOverviewPageTest.php + tests/Feature/ReviewPack/ReviewPackResourceTest.php
T018 tests/Feature/Evidence/EvidenceSnapshotResourceTest.php + tests/Feature/Evidence/EvidenceOverviewPageTest.php + tests/Feature/TenantReview/TenantReviewUiContractTest.php + tests/Feature/Monitoring/ArtifactTruthRunDetailTest.php

# Parallel semantic refinement by domain
T019 app/Support/Badges/Domains/BaselineSnapshotFidelityBadge.php
T020 app/Models/EvidenceSnapshot.php + app/Filament/Pages/Monitoring/EvidenceOverview.php
T021 app/Models/TenantReview.php + app/Services/TenantReviews/TenantReviewReadinessGate.php
T022 app/Models/ReviewPack.php + app/Support/Badges/Domains/ReviewPackStatusBadge.php

Parallel Example: User Story 3

# Parallel canonical safety and vocabulary checks
T024 tests/Feature/Evidence/EvidenceOverviewPageTest.php + tests/Feature/TenantReview/TenantReviewRegisterTest.php
T025 tests/Feature/ManagedTenants/AuthorizationSemanticsTest.php + tests/Feature/TenantReview/TenantReviewRegisterRbacTest.php

# Parallel cross-surface normalization
T026 app/Support/Badges/OperatorOutcomeTaxonomy.php
T027 app/Filament/Pages/Monitoring/EvidenceOverview.php + app/Filament/Pages/Reviews/ReviewRegister.php
T028 app/Support/OperationRunLinks.php

Implementation Strategy

MVP First (User Story 1 Only)

  1. Complete Phase 1: Setup.
  2. Complete Phase 2: Foundational shared truth support.
  3. Complete Phase 3: User Story 1.
  4. STOP and VALIDATE: Run the User Story 1 regression tasks and confirm that artifact existence vs trust semantics are clear on all four artifact families plus run detail.
  5. Demo the bounded trust slice before refining diagnostics and cross-surface normalization.

Incremental Delivery

  1. Setup + Foundational → shared truth layer ready.
  2. Add US1 → artifact trust becomes explicit across core surfaces.
  3. Add US2 → fidelity, freshness, readiness, and diagnostics become dimensionally correct.
  4. Add US3 → vocabulary and canonical tenant-safe summaries become consistent across the governance chain.
  5. Finish with guard coverage, focused tests, and formatting.

Parallel Team Strategy

  1. One developer owns Phase 2 shared truth presenter and badge foundation.
  2. After foundation is ready, split surface adoption by family:
    • Developer A: baseline + run detail
    • Developer B: evidence + evidence overview
    • Developer C: tenant review + review register + review packs
  3. Recombine in US3 for vocabulary normalization and canonical safety validation.

Notes

  • [P] tasks touch separate files or can be executed independently.
  • Story labels map tasks directly to spec user stories for traceability.
  • This task list intentionally avoids provider dispatch gating, restore cleanup, and broad operation-status redesign.
  • Existing destructive actions remain in scope only for truthful messaging, confirmation preservation, and authorization regression coverage.