ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
ebf88cd05b
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

226 lines
18 KiB
Markdown
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.
- [X] T001 Create curated artifact-truth fixture builders and case datasets in `tests/Feature/Concerns/BuildsGovernanceArtifactTruthFixtures.php` and `tests/Feature/Monitoring/ArtifactTruthManualCasesDataset.php`
- [X] 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`
- [X] 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.
- [X] 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`
- [X] T005 Implement family-specific truth resolution and next-action composition in `app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php`
- [X] 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`
- [X] T007 [P] Wire centralized reason translation into artifact-truth presentation in `app/Support/ReasonTranslation/ReasonPresenter.php` and `app/Support/ReasonTranslation/ReasonTranslator.php`
- [X] 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`
- [X] 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
- [X] 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`
- [X] 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
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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
- [X] 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`
- [X] 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
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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
- [X] 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`
- [X] 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
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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.
- [X] 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`
- [X] 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`
- [X] 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
```bash
# 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
```bash
# 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
```bash
# 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.
Reference in New Issue View Git Blame Copy Permalink