TenantAtlas/specs/158-artifact-truth-semantics/plan.md

# Implementation Plan: Governance Artifact Truthful Outcomes & Fidelity Semantics

**Branch**: `158-artifact-truth-semantics` | **Date**: 2026-03-22 | **Spec**: [spec.md](./spec.md)
**Input**: Feature specification from `/specs/158-artifact-truth-semantics/spec.md`

**Note**: This plan covers the first bounded adoption slice for truthful artifact semantics across baseline snapshots, evidence snapshots, tenant reviews, review packs, and artifact-targeted operation-run detail. It intentionally excludes provider dispatch gating, restore-lifecycle cleanup, and broad platform-wide status redesign.

## Summary

Implement a shared governance-artifact truth layer that separates artifact existence, execution outcome, completeness or fidelity, freshness, publication readiness, support maturity, and operator actionability across existing governance surfaces. The first slice is presentation-first: reuse current persisted enums, `summary` payloads, `context` payloads, badge domains, reason translation, and canonical RBAC filters wherever they already encode the truth, then add only targeted derived helpers or minimal summary/context enrichment when a surface cannot distinguish trustworthy vs merely present artifacts or cannot explain current-vs-historical artifact provenance. Integration lands in existing Filament resources and canonical pages, plus the tenantless `OperationRun` detail view, with focused regression coverage for false-green baselines, partial or stale evidence, non-publishable reviews, review-pack provenance, empty-state distinctions, and tenant-safe canonical summaries.

## Technical Context

**Language/Version**: PHP 8.4.15  
**Primary Dependencies**: Laravel 12, Filament v5, Livewire v4, Pest v4, existing `BadgeCatalog` / `BadgeRenderer` / `OperatorOutcomeTaxonomy`, `ReasonPresenter`, `OperationRunService`, `TenantReviewReadinessGate`, existing baseline/evidence/review/review-pack resources and canonical pages  
**Storage**: PostgreSQL with existing JSONB-backed `summary`, `summary_jsonb`, and `context` payloads on baseline snapshots, evidence snapshots, tenant reviews, review packs, and operation runs; no new primary storage required for the first slice, but minimal additive summary/context enrichment is allowed where truthful provenance cannot otherwise be derived  
**Testing**: Pest feature tests, Pest unit tests, and Livewire/Filament component tests  
**Target Platform**: Laravel Sail web application with Filament admin and tenant panels
**Project Type**: Web application monolith  
**Performance Goals**: All adopted list/detail surfaces remain DB-only at render time; canonical evidence/review pages keep entitlement filtering query-first; no added remote calls; artifact-truth presentation adds negligible overhead beyond current eager-loading and summary rendering  
**Constraints**: No new Microsoft Graph call path; no new artifact-producing operation family; existing destructive actions keep confirmation and audit semantics; `OperationRun.status` and `OperationRun.outcome` remain service-owned; canonical pages must not leak unauthorized tenant counts, filters, or labels  
**Scale/Scope**: First slice covers 8 existing surfaces across 4 artifact families plus tenantless run detail, using one shared truth vocabulary and preserving historical artifact intelligibility without widening into inventory, onboarding, or restore domains

## Constitution Check

*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*

- **Pre-Phase-0 Gate: PASS**
- Inventory-first: PASS. The feature reclassifies existing baseline, evidence, review, and review-pack artifacts; it does not change the inventory/evidence collection model or promote snapshots over last-observed state.
- Read/write separation: PASS. The slice is primarily presentational. Existing writes such as refresh, publish, export, archive, and expire remain explicit, confirmed where destructive, audited where already required, and tested.
- Graph contract path: PASS. No new Graph calls or contract changes are introduced.
- Deterministic capabilities: PASS. Existing capabilities remain canonical (`workspace baselines`, `evidence.view/manage`, `tenant_review.view/manage`, `review_pack.view/manage`); no raw role checks are added.
- RBAC-UX and isolation: PASS. Tenant detail remains tenant-scoped; workspace canonical evidence/review pages stay query-scoped to entitled tenants only; non-members remain 404, in-scope capability denials remain 403.
- Global search: PASS. All affected resources are already non-globally-searchable or unchanged in search behavior; no new global-search surface is added.
- Run observability: PASS. Existing artifact-producing operations already use `OperationRun`; this slice only improves how run detail communicates artifact truth.
- Ops-UX 3-surface feedback: PASS. No new feedback surface is introduced; run detail remains the canonical live/terminal interpretation surface.
- Ops-UX lifecycle ownership: PASS. No direct `status` or `outcome` transitions are introduced outside `OperationRunService`.
- Ops-UX summary counts: PASS. Existing numeric summary counts remain canonical; artifact-truth interpretation may consume them but will not replace them with free-text metrics.
- Data minimization: PASS. The design prefers derived truth envelopes over new raw payload persistence.
- BADGE-001: PASS. Shared semantics must flow through centralized badge domains or presenter helpers, not page-local label/color mappings.
- UI-NAMING-001 and OPSURF-001: PASS. Operator-facing surfaces lead with trustworthy artifact answers and keep renderer/support limitations in secondary diagnostics.
- Filament Action Surface Contract: PASS. The first slice changes status messaging, helper copy, empty states, and action-enable explanations on existing resources/pages without expanding mutation surface area.
- Filament UX-001: PASS. Existing list/detail patterns remain intact; truth messaging is layered into current Infolists, tables, and canonical pages.
- UI-STD-001 list surface checklist: PASS WITH REQUIRED REVIEW. Because existing baseline, evidence, tenant review, review-pack, and canonical summary list surfaces are modified, implementation and validation must reference `docs/product/standards/list-surface-review-checklist.md`.

**Post-Phase-1 Re-check: PASS**
- The proposed design keeps the slice presentation-first, respects tenant/workspace ownership, avoids new remote work, reuses existing canonical action surfaces, and introduces no constitution violations.

## Project Structure

### Documentation (this feature)

```text
specs/158-artifact-truth-semantics/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   └── artifact-truth.openapi.yaml
├── checklists/
│   └── requirements.md
└── tasks.md
```

### Source Code (repository root)

```text
app/
├── Filament/
│   ├── Pages/
│   │   ├── Monitoring/
│   │   ├── Operations/
│   │   └── Reviews/
│   └── Resources/
│       ├── BaselineSnapshotResource.php
│       ├── EvidenceSnapshotResource.php
│       ├── ReviewPackResource.php
│       ├── TenantReviewResource.php
│       └── OperationRunResource.php
├── Models/
│   ├── EvidenceSnapshot.php
│   ├── ReviewPack.php
│   ├── TenantReview.php
│   └── OperationRun.php
├── Services/
│   ├── Baselines/
│   ├── Evidence/
│   └── TenantReviews/
└── Support/
    ├── Badges/
    ├── ReasonTranslation/
    ├── Ui/
    └── Operations/

resources/
└── views/
    └── filament/

tests/
├── Feature/
│   ├── Evidence/
│   ├── TenantReview/
│   ├── ReviewPack/
│   ├── Monitoring/
│   └── ManagedTenants/
└── Unit/
    ├── Evidence/
    ├── TenantReview/
    ├── ReviewPack/
    └── Badges/
```

**Structure Decision**: Keep the existing Laravel monolith structure and deliver the slice by modifying existing resources/pages, shared badge or presenter support, and focused tests. No new base folders or new runtime subsystems are required. Any new helper should live under existing `app/Support` or domain service namespaces rather than introducing a new module root.

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| None | N/A | N/A |

## Filament v5 Agent Output Contract

1. **Livewire v4.0+ compliance**: Yes. The plan stays within Filament v5 + Livewire v4 components and helpers already present in the repo.
2. **Provider registration**: No new panel is introduced. Existing panel providers remain registered in `bootstrap/providers.php`.
3. **Global search**: Affected resources remain non-globally-searchable in this slice, so the Edit/View-page rule is unchanged. No new globally searchable resource is added.
4. **Destructive actions**: Existing destructive actions remain the only destructive actions in scope: evidence snapshot expire, review archive, review-pack expire, and any existing destructive baseline actions. They continue to use `->action(...)`, confirmation, and server-side authorization.
5. **Asset strategy**: No new custom assets are planned. The slice uses existing Filament rendering, badges, and Blade views. Deployment still relies on the existing Filament asset pipeline, including `vendor/bin/sail artisan filament:assets` where registered assets are deployed.
6. **Testing plan**: Cover unit semantics for badge or truth mapping, Livewire or feature tests for modified baseline/evidence/review/review-pack Filament resources and canonical pages, canonical RBAC regression tests for evidence/review summaries, operation-run detail regression tests for artifact-targeted truth messaging, empty-state distinctions, and the 12-case curated manual validation set captured in `quickstart.md`.