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

# Quickstart: Governance Artifact Truthful Outcomes & Fidelity Semantics

## Goal

Deliver the first truthful-artifact slice without widening scope beyond existing governance artifacts and artifact-targeted run detail.

## Implementation Phases

### Phase 1: Shared Truth Envelope

**Goal:** Centralize how governance artifacts express truth, degradation, readiness, and next steps.

1. Add or extend shared presenter support under existing `app/Support` or domain service namespaces.
2. Normalize which dimensions are primary vs diagnostic for:
   - baseline snapshot fidelity and gaps
   - evidence completeness and freshness
   - tenant review completeness and publication blockers
   - review-pack lifecycle vs provenance
   - artifact-targeted run outcome vs artifact result
3. Reuse `BadgeCatalog`, `BadgeRenderer`, `OperatorOutcomeTaxonomy`, and `ReasonPresenter` instead of page-local label logic.
4. Add targeted unit tests for any new or remapped badge or presenter semantics.

### Phase 2: Artifact Family Integration

**Goal:** Apply the truth envelope to existing resource lists and detail views.

1. Update baseline snapshot list/detail messaging so fidelity/support signals stay diagnostic while false-green capture outcomes are clearly degraded.
2. Update evidence snapshot list/detail and evidence overview rows so completeness, freshness, and next-step semantics are explicit.
3. Update tenant review list/detail and review register so review existence, completeness, and publication readiness are separated.
4. Update review-pack list/detail so file existence is separated from trustworthy stakeholder-output provenance.
5. Keep current action surfaces and authorization rules unchanged unless explanation or enablement reasons must reflect truth semantics.

### Phase 3: Canonical Run Detail Integration

**Goal:** Make artifact-targeted operation runs answer whether a trustworthy artifact was produced.

1. Extend the operation-run enterprise detail builder for:
   - `baseline_capture`
   - `tenant.evidence.snapshot.generate`
   - `tenant.review.compose`
   - `tenant.review_pack.generate`
2. Show a primary artifact-truth summary before raw JSON/context.
3. Reuse related links and reason translation for next-step guidance.
4. Preserve diagnostics as a secondary boundary.

### Phase 4: RBAC and Regression Coverage

**Goal:** Prove the slice is truthful and tenant-safe.

1. Add positive and negative authorization tests for canonical evidence and review pages.
2. Add focused coverage for:
   - false-green baseline examples
   - partial and stale evidence
   - non-publishable reviews
   - review-pack provenance and historical availability
   - empty-state distinctions for not-created, degraded, and historical-only cases
   - artifact-targeted run detail messaging
3. Run formatter and affected tests.
4. Review the affected list surfaces against `docs/product/standards/list-surface-review-checklist.md`.

## Curated Manual Validation Set

Validate 12 curated artifact cases before sign-off so the operator can answer from one inspection step whether the artifact exists, whether it is trustworthy, and whether action is required.

1. Healthy baseline artifact
2. False-green baseline with no trustworthy artifact
3. Historical baseline trace that is intentionally non-usable
4. Healthy evidence snapshot
5. Partial evidence snapshot with missing dimensions
6. Stale evidence snapshot with no further action required
7. Draft tenant review that is internally useful but not publishable
8. Blocked tenant review with explicit next step
9. Publishable tenant review
10. Historical review pack derived from a formerly publishable review
11. Current review pack blocked by regressed source readiness
12. Artifact-targeted run that completed but produced a degraded artifact

## Completed Validation Checklist

Validated on March 22, 2026 through the focused Spec 158 regression suite plus the canonical authorization and guard checks.

- [x] Healthy baseline artifact
- [x] False-green baseline with no trustworthy artifact
- [x] Historical baseline trace that is intentionally non-usable
- [x] Healthy evidence snapshot
- [x] Partial evidence snapshot with missing dimensions
- [x] Stale evidence snapshot with no further action required
- [x] Draft tenant review that is internally useful but not publishable
- [x] Blocked tenant review with explicit next step
- [x] Publishable tenant review
- [x] Historical review pack derived from a formerly publishable review
- [x] Current review pack blocked by regressed source readiness
- [x] Artifact-targeted run that completed but produced a degraded artifact

## List Surface Review Notes

- [x] Baseline snapshot list/detail keeps artifact truth separate from fidelity diagnostics while preserving the existing sortable/searchable structure.
- [x] Evidence overview remains a tenant-safe read-only summary with one drill-down action per row and explicit artifact-truth, freshness, and next-step columns.
- [x] Evidence snapshot, tenant review, review register, and review pack surfaces keep badge-based state rendering, domain-specific empty states, and authorization boundaries intact after the new truth columns were added.
- [x] Canonical evidence and review summaries continue to scope rows, tenant filters, and drill-down links to entitled tenants only.

## Likely File Inventory

### Modified Files

```text
app/Filament/Resources/BaselineSnapshotResource.php
app/Filament/Resources/EvidenceSnapshotResource.php
app/Filament/Resources/TenantReviewResource.php
app/Filament/Resources/ReviewPackResource.php
app/Filament/Resources/OperationRunResource.php
app/Filament/Pages/Monitoring/EvidenceOverview.php
app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
app/Filament/Pages/Reviews/ReviewRegister.php
app/Support/Badges/OperatorOutcomeTaxonomy.php
app/Support/Badges/BadgeCatalog.php
app/Support/Badges/Domains/*.php
app/Support/ReasonTranslation/*.php
app/Services/TenantReviews/TenantReviewReadinessGate.php
tests/Feature/Evidence/*.php
tests/Feature/TenantReview/*.php
tests/Feature/ReviewPack/*.php
tests/Feature/Monitoring/*.php
tests/Unit/**/*.php
```

### Possible New Helper Files

```text
app/Support/Ui/GovernanceArtifactTruth/*.php
app/Support/Badges/Domains/<new-or-remapped-domain>.php
tests/Unit/Badges/GovernanceArtifactTruthTest.php
```

## Verification Commands

```bash
vendor/bin/sail artisan test --compact tests/Feature/Evidence
vendor/bin/sail artisan test --compact tests/Feature/TenantReview
vendor/bin/sail artisan test --compact tests/Feature/ReviewPack
vendor/bin/sail artisan test --compact tests/Feature/Monitoring
vendor/bin/sail bin pint --dirty --format agent
```

## Verification Review Checklist

1. Review baseline snapshot, evidence snapshot, tenant review, review-pack, evidence overview, and review register list surfaces against `docs/product/standards/list-surface-review-checklist.md`.
2. Confirm empty-state wording distinguishes not-created, degraded, and historical-only cases where those states can appear.
3. Confirm canonical evidence/review list filters and counts remain tenant-safe for both allowed and disallowed tenants.

## Rollout Notes

- No migration is required unless implementation reveals a minimal summary/context enrichment need.
- If enrichment is needed, keep it additive to existing `summary` or `context` payloads and limit it to provenance or usability distinctions that cannot be derived safely at render time.
- No deploy-time asset change is expected beyond the existing Filament asset pipeline.
- Historical records must remain readable even if some new truth-envelope inputs are absent.