# Feature Specification: Governance Artifact Truthful Outcomes & Fidelity Semantics

**Feature Branch**: `158-artifact-truth-semantics`  
**Created**: 2026-03-22  
**Status**: Draft  
**Input**: User description: "Governance Artifact Truthful Outcomes & Fidelity Semantics"

## Spec Scope Fields *(mandatory)*

- **Scope**: workspace + tenant + canonical-view
- **Primary Routes**:
  - Workspace-scoped baseline snapshot list and detail surfaces
  - Tenant-scoped evidence snapshot list and detail surfaces
  - Workspace-scoped evidence overview surface
  - Tenant-scoped tenant-review list and detail surfaces
  - Workspace-scoped review register surface
  - Tenant-scoped review-pack list and detail surfaces where publication or export readiness is shown
  - Existing run-detail surfaces only when the run explains the truth state of a baseline, evidence, review, or review-pack artifact
- **Data Ownership**:
  - Workspace-owned records affected: baseline snapshots, baseline snapshot items, workspace-scoped review register summaries, and canonical evidence overview summaries.
  - Tenant-owned records affected: evidence snapshots, evidence snapshot items, tenant reviews, tenant review sections, review packs, and tenant-scoped artifact readiness summaries.
  - Workspace-owned `OperationRun` records remain the canonical observability layer for baseline capture, evidence generation, tenant review composition, and review-pack generation, but this feature only changes how those runs explain artifact truth.
  - This feature does not change ownership boundaries; it standardizes operator-facing truth semantics across existing artifact families.
- **RBAC**:
  - Workspace membership remains mandatory for every affected surface.
  - Workspace baseline surfaces continue to require the existing workspace baseline capabilities for list/detail visibility and management actions.
  - Evidence surfaces continue to require `evidence.view` and `evidence.manage`.
  - Tenant review surfaces continue to require `tenant_review.view` and `tenant_review.manage`.
  - Review-pack surfaces continue to require `review_pack.view` and `review_pack.manage`.
  - Non-members or wrong-scope users remain deny-as-not-found; in-scope members missing required capability remain forbidden.

For canonical-view specs, the spec MUST define:

- **Default filter behavior when tenant-context is active**: Canonical evidence and review register surfaces open prefiltered to the current tenant when entered from tenant context. Workspace-owned baseline snapshot surfaces remain workspace-scoped by default, but any tenant-linked drill-in or summary chip must stay limited to the current tenant context rather than broadening back to all tenants implicitly.
- **Explicit entitlement checks preventing cross-tenant leakage**: Badge labels, summary rows, readiness totals, filter values, and empty-state wording on canonical evidence and review surfaces must be derived only from authorized tenant records. Shared truth labels such as `Partial`, `Stale`, `Publishable`, `Blocked`, or `No data` must not allow operators to infer unauthorized tenant state.

## Operator Surface Contract *(mandatory when operator-facing surfaces are changed)*

| Surface | Primary Persona | Surface Type | Primary Operator Question | Default-visible Information | Diagnostics-only Information | Status Dimensions Used | Mutation Scope | Primary Actions | Dangerous Actions |
|---|---|---|---|---|---|---|---|---|---|
| Baseline snapshot list and detail | Workspace governance operator | List/detail | Is this baseline artifact trustworthy enough to compare or review? | Snapshot existence, fidelity or completeness state, freshness, whether comparison use is safe, next action when degraded | Renderer limitations, raw provenance fields, low-level capture counters, internal reason fragments | artifact existence, execution outcome, fidelity or completeness, support maturity, operator actionability | TenantPilot only / simulation only | View snapshot, open related compare or run detail | Existing destructive actions unchanged |
| Evidence snapshot list/detail and evidence overview | Tenant or workspace governance operator | List/detail/overview | What evidence exists, how complete is it, and is it still current? | Snapshot status, completeness, stale or missing dimensions, whether evidence is reviewable, next action | Raw dimension payloads, internal metric keys, technical source references | artifact existence, completeness, freshness, readiness, operator actionability | TenantPilot only | View snapshot, create or refresh snapshot where allowed | Existing expiration actions unchanged |
| Tenant review list/detail and review register | Tenant or workspace review owner | List/detail/register | Is this review merely present, or is it actually ready to publish or export? | Review status, completeness, readiness blockers, publishability, anchored evidence basis summary, next action | Raw section payloads, fingerprint data, internal readiness calculations | artifact existence, completeness, publication readiness, freshness, operator actionability | TenantPilot only | View review, create next review, refresh, publish when eligible | Existing archive action remains destructive |
| Review-pack list/detail | Tenant review operator | List/detail | Is this pack a trustworthy stakeholder output or only a draft or blocked derivative? | Pack existence, generation outcome, readiness source, blocking cause, export suitability, next action | Raw generation payloads, internal export options, technical error fragments | artifact existence, execution outcome, publication readiness, freshness, operator actionability | TenantPilot only | View pack, export pack, open source review | Existing archive or destructive actions unchanged |
| Artifact-targeted run detail | Governance operator | Detail | Did the run merely finish, or did it produce a trustworthy artifact? | Primary cause, whether the intended artifact was produced, whether the artifact is usable, next action | Raw context JSON, low-level reason codes, internal counters beyond the operator summary | execution outcome, artifact existence, fidelity or completeness, operator actionability | TenantPilot only / simulation only depending on run family | View related artifact, retry where already allowed | Existing dangerous rerun or mutation actions unchanged |

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Distinguish real artifact truth from cosmetic success (Priority: P1)

As a governance operator, I want baseline, evidence, review, and review-pack surfaces to tell me whether a usable artifact truly exists, so that I do not mistake `completed` or `present` for `trustworthy and ready`.

**Why this priority**: This is the direct product-trust problem. False-green or ambiguous artifact states damage review credibility more than internal platform inconsistency that operators never see.

**Independent Test**: Can be fully tested by preparing examples where an artifact exists but is degraded, stale, blocked by prerequisites, metadata-only, or not publishable, then verifying that the primary surface distinguishes those cases from truly usable artifacts in one inspection step.

**Acceptance Scenarios**:

1. **Given** a baseline capture run completed without producing a credible baseline artifact, **When** the operator opens the related run detail or snapshot surface, **Then** the product states that no trustworthy baseline was produced and explains the next action.
2. **Given** an evidence snapshot exists but some required dimensions are stale or missing, **When** the operator views the snapshot or overview, **Then** the surface shows the snapshot as partial or stale rather than as fully ready.
3. **Given** a tenant review exists but is not ready to publish or export, **When** the operator views the review or review register, **Then** the product distinguishes `review exists` from `review is publishable` and names the blocking reason.

---

### User Story 2 - Understand fidelity and readiness without decoding diagnostics (Priority: P1)

As an operator, I want artifact surfaces to separate completeness, freshness, support limitations, and publication readiness, so that I can tell what is wrong and whether action is required without reading raw payloads or internal codes.

**Why this priority**: The product already contains the truth in many places, but it reaches operators as overloaded words such as `missing`, `stale`, `unsupported`, or `partial` without saying which dimension they belong to.

**Independent Test**: Can be fully tested by reviewing curated baseline, evidence, review, and review-pack examples containing mixed conditions and confirming that each degraded condition is shown on the correct semantic dimension with the correct next-action guidance.

**Acceptance Scenarios**:

1. **Given** an artifact is usable but stale, **When** the operator views it, **Then** freshness is shown as the primary issue and the artifact is not mislabeled as missing or broken.
2. **Given** an artifact is metadata-only, reference-only, or affected by renderer maturity limits, **When** the operator views it, **Then** those support facts are shown as diagnostics and do not replace the primary truth state.
3. **Given** an artifact is non-green but no operator action is required, **When** the operator views it, **Then** the surface explicitly says that no action is needed.

---

### User Story 3 - Reuse one truth model across the governance chain (Priority: P2)

As a product owner, I want baseline, evidence, review, and review-pack surfaces to share one truthful outcome and fidelity model, so that the governance chain reads as one coherent product rather than a set of locally invented status systems.

**Why this priority**: This turns the outcome taxonomy and reason translation foundations into visible product value. Without this adoption slice, the foundations remain theoretical.

**Independent Test**: Can be fully tested by reviewing the bounded adoption set and confirming that equivalent states such as `partial`, `stale`, `blocked by prerequisite`, `ready`, and `not publishable` keep the same meaning across artifact families.

**Acceptance Scenarios**:

1. **Given** two artifact families show comparable degraded states, **When** the operator moves between them, **Then** the same word keeps the same meaning and severity.
2. **Given** one artifact is present but not publishable and another is absent entirely, **When** the operator compares them, **Then** the surfaces distinguish existence from readiness rather than collapsing both into a generic warning.

### Edge Cases

- A baseline snapshot exists and a related run is marked complete, but the snapshot was built from zero in-scope subjects or an unusable upstream source; the surface must say that the artifact is not trustworthy.
- An evidence snapshot is present but only contains metadata or reference placeholders for one or more dimensions; the surface must not present those dimensions as fully collected evidence.
- A tenant review is draft because required sections are incomplete, but the review itself is still useful for internal preparation; the surface must distinguish internal usability from stakeholder readiness.
- A review pack exists from a prior publishable review, but the latest review has regressed and is no longer publishable; historical pack availability must not mask current readiness regression.
- A surface must show more than one degraded dimension at once, such as `artifact exists`, `freshness stale`, and `publication blocked`; the dimensions must remain separate instead of collapsing into one badge.
- Canonical evidence or review surfaces are opened by an operator entitled to only a subset of tenants; state filters and counts must not expose foreign-tenant degraded artifacts.

## Requirements *(mandatory)*

**Constitution alignment (required):** This feature introduces no new Microsoft Graph call path and no new artifact-producing operation family. It standardizes the operator-facing truth contract for existing baseline capture, evidence generation, tenant review composition, and review-pack generation flows. Existing safety gates, audit logging, and tenant isolation remain mandatory. If an adopted surface relies on DB-only lifecycle changes such as publish or archive, those actions continue to require audit history and existing confirmation rules.

**Constitution alignment (OPS-UX):** This feature reuses existing `OperationRun` families for baseline capture, evidence generation, tenant review composition, and review-pack generation. It does not change the Ops-UX three-surface contract or create a parallel progress surface. `OperationRun.status` and `OperationRun.outcome` remain service-owned. The feature changes how artifact-targeted runs communicate whether the intended artifact was produced, whether it is usable, and what the operator should do next. Any summary-count wording shown to operators must stay compatible with numeric-only summary keys while avoiding false-green interpretations.

**Constitution alignment (RBAC-UX):** This feature affects workspace-admin baseline views, tenant-admin evidence and review surfaces, and workspace-scoped canonical evidence and review surfaces. Cross-plane access remains deny-as-not-found. Non-members or wrong-scope users remain `404`; in-scope users missing capability remain `403`. Artifact truth labels, readiness badges, filter values, and next-step hints must not reveal unauthorized tenant state. Existing server-side policies remain the source of truth for all view and mutation permissions.

**Constitution alignment (OPS-EX-AUTH-001):** Not applicable. This feature does not touch authentication handshakes.

**Constitution alignment (BADGE-001):** This feature is a direct BADGE-001 adoption slice. Baseline fidelity, evidence completeness, review readiness, publication readiness, and artifact-targeted run truth states must consume centralized semantics rather than page-local mappings. Tests must cover new or remapped values introduced by this feature.

**Constitution alignment (UI-NAMING-001):** Target objects are baseline snapshots, evidence snapshots, tenant reviews, review packs, and artifact-targeted runs. Operator vocabulary must preserve one meaning per term across list badges, detail headers, helper copy, notifications, and readiness messages. Implementation-first wording such as `render fallback`, `metadata projection`, `section composer`, or `fingerprint mismatch` remains diagnostics-only.

**Constitution alignment (OPSURF-001):** This feature materially refines existing operator-facing governance surfaces. Default-visible content must stay operator-first and answer: does the artifact exist, is it trustworthy, is it current, is it publishable, and what should I do next? Raw payloads, internal provenance, low-level counters, and machine-oriented reasons remain explicit secondary diagnostics.

**Constitution alignment (Filament Action Surfaces):** This feature changes existing Filament resources and pages but does not add a new mutation family. The Action Surface Contract remains satisfied when affected pages keep their existing inspect affordances, preserve capability-gated mutations, and apply the new truth model only to status, helper copy, readiness messaging, and related action enablement reasons.

**Constitution alignment (UX-001 — Layout & Information Architecture):** Affected list and detail screens keep their existing layouts, but status badges, readiness chips, summary panels, and empty states must reflect the truthful artifact model. Empty states must distinguish `artifact not created yet`, `artifact exists but is not ready`, and `no action needed` scenarios instead of treating all three as one generic absence state.

**Constitution alignment (UI-STD-001 list surfaces):** Because this feature modifies existing list surfaces for baseline snapshots, evidence snapshots, tenant reviews, review packs, and canonical review/evidence summaries, implementation and verification MUST reference `docs/product/standards/list-surface-review-checklist.md` so inspection affordances, filters, empty states, and row semantics remain compliant while truth messaging changes.

### Functional Requirements

- **FR-158-001**: The system MUST define one governance-artifact truth model shared by baseline snapshots, evidence snapshots, tenant reviews, review packs, and artifact-targeted run summaries.
- **FR-158-002**: The shared model MUST separate at least execution outcome, artifact existence, fidelity or completeness, freshness, support maturity, publication readiness, and operator actionability into distinct dimensions.
- **FR-158-003**: An adopted surface MUST NOT treat `artifact exists` as equivalent to `artifact is trustworthy` or `artifact is ready`.
- **FR-158-004**: Baseline-related surfaces MUST distinguish a technically completed run from a run that produced a credible baseline artifact.
- **FR-158-005**: Baseline-related surfaces MUST treat zero-subject, unusable-upstream, blocked-upstream, or empty-snapshot outcomes as non-success artifact states unless the artifact is explicitly marked as non-usable historical trace.
- **FR-158-006**: Evidence surfaces MUST distinguish complete, partial, stale, missing-input, metadata-only, and reference-only conditions without collapsing them into one generic warning.
- **FR-158-007**: Review surfaces MUST distinguish review existence, review completeness, and review publication readiness as separate states.
- **FR-158-008**: Review-pack surfaces MUST distinguish pack existence, pack generation outcome, and whether the source review was actually publishable at the time the pack was generated.
- **FR-158-009**: Product-support or renderer-maturity facts MUST remain diagnostics-only and MUST NOT be shown as the primary warning or error state for an adopted artifact surface.
- **FR-158-010**: Every adopted non-green artifact state MUST include a cause-specific explanation and either a next action, a destination, or an explicit `No action needed` message.
- **FR-158-011**: Adopted surfaces MUST use the shared operator vocabulary established by Spec 156 and MUST consume humanized reasons from Spec 157 where cause wording is required.
- **FR-158-012**: Artifact-targeted run detail MUST state whether the intended artifact was produced, whether it is usable, and why it is degraded when the run outcome alone would otherwise read as ambiguous.
- **FR-158-013**: Canonical evidence and review overview surfaces MUST apply the same truth vocabulary as tenant-scoped detail surfaces while remaining entitlement-safe.
- **FR-158-014**: The first implementation slice MUST cover baseline snapshot list/detail, evidence snapshot list/detail, evidence overview, tenant review list/detail, review register, review-pack list/detail, and artifact-targeted run detail summaries.
- **FR-158-015**: The first implementation slice MUST explicitly exclude provider dispatch gating, restore lifecycle cleanup, and broad inventory or onboarding semantics beyond any existing artifact truth they already surface.
- **FR-158-016**: Adopted surfaces MUST preserve historical artifact intelligibility, so older evidence snapshots, reviews, and review packs remain understandable even when newer artifacts are more complete or more current.
- **FR-158-017**: The feature MUST define migration guidance for replacing overloaded labels such as `missing`, `stale`, `partial`, `unsupported`, `ready`, and `draft` with dimension-specific artifact truth messaging.
- **FR-158-018**: The feature MUST include regression coverage for false-green baseline outcomes, partial or stale evidence, non-publishable reviews, review-pack readiness provenance, and non-member-safe canonical summaries.
- **FR-158-019**: The feature MUST include at least one positive and one negative authorization test proving that truth labels, readiness counts, and filter values on canonical artifact surfaces do not leak unauthorized tenant state.
- **FR-158-020**: The feature MUST ensure that adopted empty states distinguish `not created yet`, `created but degraded`, and `historical artifact available but not current` where those distinctions matter to operator decisions.

## UI Action Matrix *(mandatory when Filament is changed)*

| Surface | Location | Header Actions | Inspect Affordance (List/Table) | Row Actions (max 2 visible) | Bulk Actions (grouped) | Empty-State CTA(s) | View Header Actions | Create/Edit Save+Cancel | Audit log? | Notes / Exemptions |
|---|---|---|---|---|---|---|---|---|---|---|
| Baseline snapshot list/detail | Existing workspace baseline snapshot resource | Existing actions unchanged | Existing clickable inspection remains primary | None added by this feature | None added by this feature | Existing CTA unchanged | Existing actions unchanged | N/A | Existing audit model unchanged | This feature changes fidelity, truth, and next-action messaging only |
| Evidence snapshot list/detail | Existing tenant evidence snapshot resource | `Create snapshot` remains existing entry point | Existing clickable inspection remains primary | Existing row actions unchanged | None added by this feature | `Create first snapshot` remains | Existing actions unchanged | N/A | Existing audit model unchanged | Status, empty-state wording, and readiness explanation change |
| Evidence overview | Existing workspace evidence overview page | `Clear filters` | Existing drill-down link remains primary | None | None | `Clear filters` when filtered | N/A | N/A | No new mutation | Canonical summary rows adopt truthful completeness and freshness semantics |
| Tenant review list/detail and review register | Existing tenant review resource and workspace review register | Existing `Create review` and `Clear filters` entry points remain | Existing clickable inspection remains primary | Existing row actions unchanged | None added by this feature | Existing single CTA pattern remains | Existing `Refresh review`, `Publish review`, `Export executive pack`, `Archive review` remain | N/A | Existing audit model unchanged | This feature clarifies existence vs readiness vs publication truth |
| Review-pack list/detail | Existing review-pack resource | Existing actions unchanged | Existing clickable inspection remains primary | Existing row actions unchanged | None added by this feature | Existing CTA unchanged | Existing actions unchanged | N/A | Existing audit model unchanged | Pack truth and provenance messaging change without adding new actions |

### Key Entities *(include if feature involves data)*

- **Governance Artifact Truth State**: The operator-facing envelope that explains whether an artifact exists, whether it is usable, whether it is current, and what to do next.
- **Artifact Fidelity or Completeness State**: The dimension that explains how complete, trustworthy, or degraded the artifact content is without conflating that with execution outcome or readiness.
- **Publication Readiness State**: The dimension that explains whether a review or review-derived pack is suitable for stakeholder publication or export.
- **Artifact Support Maturity Signal**: Diagnostic-only information about renderer or interpretation capability that must not replace the primary artifact truth state.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-158-001**: In the first implementation slice, 100% of adopted artifact surfaces show artifact existence, fidelity or completeness, and readiness as separate meanings whenever more than one of those dimensions is relevant.
- **SC-158-002**: In focused regression coverage, 100% of false-green baseline examples are rendered as non-success artifact states unless explicitly marked as non-usable historical traces.
- **SC-158-003**: In focused regression coverage, 100% of adopted evidence and review examples with stale, partial, or blocked conditions include a next action or an explicit `No action needed` marker.
- **SC-158-004**: In a manual review set of 12 curated artifact cases across baseline, evidence, review, and review-pack surfaces, operators can correctly answer whether the artifact exists, whether it is trustworthy, and whether action is required in at least 11 of 12 cases from one inspection step.
- **SC-158-005**: In focused authorization regression coverage, 100% of canonical evidence and review summaries suppress unauthorized tenant labels, counts, and truth-state filter values.
- **SC-158-006**: In the first implementation slice, no adopted artifact surface uses a renderer limitation or support-tier fact as the primary warning or error signal.

## Assumptions

- Spec 156 provides the shared outcome vocabulary, and Spec 157 provides the humanized cause wording that this feature consumes.
- Existing baseline, evidence, review, and review-pack artifact models are stable enough that this slice can focus on truthful presentation rather than reworking domain ownership.
- The first rollout is intentionally bounded to governance artifacts and their immediate run summaries, not to all product status systems.
- Historical artifacts remain valuable even when newer artifacts are more complete, so the truth model must explain staleness or partiality without making historical records unintelligible.

## Dependencies

- Spec 118 - Baseline Drift Engine
- Spec 153 - Evidence Domain Foundation
- Spec 155 - Tenant Review Layer
- Spec 156 - Operator Outcome Taxonomy and Cross-Domain State Separation
- Spec 157 - Operator Reason Code Translation and Humanization Contract
- Existing baseline snapshot, evidence snapshot, tenant review, review-pack, and operation-run surfaces in the current admin panel

## Non-Goals

- Extending provider-backed action preflight or dispatch gating
- Performing a broad restore lifecycle semantics cleanup outside artifact truth that already appears on adopted governance surfaces
- Redefining every platform-wide `OperationRun` outcome
- Redesigning the visual system or component library
- Creating new artifact families or new long-running operation families

## Final Direction

This spec makes the outcome taxonomy and reason translation foundations visible in TenantPilot's most trust-sensitive product surfaces: baselines, evidence, reviews, and review packs. It focuses on the governance chain that customers actually evaluate in demos, audits, and day-to-day review work. The goal is not merely cleaner wording, but a stricter product guarantee that operators can tell whether an artifact exists, whether it is trustworthy, whether it is current, whether it is publishable, and what to do next.