# Research: Governance Artifact Truthful Outcomes & Fidelity Semantics ## Decision 1: Implement the first slice as a shared presentation/read-model layer over existing persisted artifact fields - **Decision**: Introduce a shared artifact-truth presenter or view-model layer that composes current persisted artifact state from existing enums, badge domains, `summary` payloads, and `OperationRun.context` rather than adding a new database table in the first slice. - **Rationale**: Baseline snapshots already expose fidelity and gap summaries, evidence snapshots already persist completeness plus missing/stale counts, tenant reviews already persist completeness and publish blockers, and review packs already persist generation state plus source review/evidence metadata. The main problem is inconsistent operator interpretation, not missing primary persistence. - **Alternatives considered**: - Add a new `artifact_truth_states` table: rejected because the first slice would duplicate existing truth and risk divergence. - Hard-code per-page label logic: rejected because it would regress BADGE-001 and Spec 156. ## Decision 2: Reuse centralized badge semantics and reason translation instead of creating a parallel truth taxonomy - **Decision**: Build the truth envelope on top of `BadgeCatalog`, `BadgeRenderer`, `OperatorOutcomeTaxonomy`, and `ReasonPresenter`, extending or remapping badge domains only where existing domains still collapse artifact meanings. - **Rationale**: Evidence completeness and tenant review completeness already consume the taxonomy, baseline fidelity already uses a centralized badge domain, and run detail already translates blocked reasons through `ReasonPresenter`. This creates visible adoption of Specs 156 and 157 instead of inventing a competing presentation model. - **Alternatives considered**: - Create dedicated per-artifact truth enums for every surface: rejected because it would fragment semantics and duplicate the taxonomy. - Rely only on free-form helper text: rejected because operator consistency would remain untestable. ## Decision 3: Keep canonical workspace summaries entitlement-safe by filtering tenants before deriving labels, counts, and filter options - **Decision**: Preserve the current query-first tenant filtering pattern on canonical workspace pages and derive truth labels, readiness counts, and filter options only from the already-authorized record set. - **Rationale**: `EvidenceOverview` builds rows only from tenants for which the user can `evidence.view`, and `ReviewRegister` limits both the query and tenant filter options to entitled tenants via `TenantReviewRegisterService` and `CanonicalAdminTenantFilterState`. This is the correct security boundary for Spec 158's non-leakage requirements. - **Alternatives considered**: - Precompute workspace-wide aggregate truth counts and hide unauthorized rows later: rejected because counts and filter options would become leakage-prone. - Allow canonical pages to read all tenant rows and filter in Blade/Livewire: rejected because that would weaken 404/403 semantics and be harder to regression-test. ## Decision 4: Attach artifact-truth messaging to tenantless run detail via the existing enterprise-detail builder and related-link model - **Decision**: Extend `OperationRunResource::enterpriseDetailPage()` and the tenantless run viewer to add an artifact-truth section for baseline capture, evidence generation, tenant review composition, and review-pack generation, reusing `OperationRunLinks` and `ReasonPresenter`. - **Rationale**: The canonical run detail page already leads with operator-first state, exposes related links, and has operation-type-specific sections for baseline compare and baseline capture evidence. Adding artifact-produced/usable/degraded interpretation there stays aligned with the existing Ops-UX reference implementation. - **Alternatives considered**: - Add a separate artifact-truth run detail page: rejected because it would violate the single canonical run-detail surface. - Expose only raw `context` or failure JSON: rejected because it does not satisfy FR-158-012. ## Decision 5: Use targeted summary enrichment only where current persisted fields cannot explain truthful artifact provenance - **Decision**: Preserve existing models as the primary source, but allow small, backward-compatible enrichment of existing `summary` or `context` payloads when current fields cannot truthfully answer whether an artifact is usable, current, or publishable. - **Rationale**: Some families already have enough persisted state, while others, especially review packs and baseline-capture runs, may need a stable provenance or degraded-artifact explanation beyond the lifecycle enum alone. Enriching current JSON payloads is lower-risk than adding new tables or widening operation types. - **Alternatives considered**: - Force the entire slice to use current fields only: rejected because some false-green cases would stay ambiguous. - Redesign underlying artifact schemas first: rejected because it would turn a bounded truth-semantics slice into a domain rewrite. ## Decision 6: Review-pack truth should derive from pack lifecycle plus source review and evidence provenance, not from pack status alone - **Decision**: Model review-pack truth as a composition of pack lifecycle (`queued`, `generating`, `ready`, `failed`, `expired`), source review readiness or publication state, anchored evidence completeness, and freshness/provenance metadata already persisted in `summary`. - **Rationale**: `ReviewPackStatusBadge` currently treats `ready` as if it were enough, but the spec explicitly requires operators to know whether the pack is a trustworthy export of a publishable review or only a historical derivative. - **Alternatives considered**: - Keep `ReviewPackStatus` as the sole operator state: rejected because it cannot distinguish “pack file exists” from “pack is a trustworthy stakeholder output.” - Add a second lifecycle enum to `ReviewPack`: rejected for the first slice because provenance can be derived from existing linked models and summary payloads. ## Decision 7: Migration guidance is semantic migration, not data migration, for the first slice - **Decision**: Treat FR-158-017 as a semantic migration of labels, helper copy, badge usage, and empty-state wording rather than a schema or record backfill migration. - **Rationale**: The current ambiguity stems from overloaded labels such as `missing`, `partial`, `ready`, and `draft`. Existing records remain valid if the new truth layer interprets them more precisely and, where needed, supplements them with cause-specific explanation. - **Alternatives considered**: - Backfill historical records with new truth fields: rejected because current records can be interpreted through derived envelopes. - Leave old wording in place for backward compatibility: rejected because the feature's core value is truthful operator meaning.