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 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)

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)

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.