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

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.