TenantAtlas/docs/audits/semantic-clarity-audit.md

# Semantic Clarity & Operator-Language Audit

**Product:** TenantPilot / TenantAtlas  
**Date:** 2026-03-21  
**Scope:** System-wide audit of operator-facing semantics, terminology collisions, technical leakage, false urgency, and missing semantic separation  
**Auditor role:** Senior Staff Engineer / Enterprise SaaS UX Architect  

---

## 1. Executive Summary

**Severity: HIGH — systemic, not localized.**

TenantPilot has a **pervasive semantic collision problem** where at least 5–7 distinct meaning axes are collapsed into the same small vocabulary of terms. The product uses ~12 overloaded words ("failed", "partial", "missing", "gaps", "unsupported", "stale", "blocked", "complete", "ready", "reference only", "metadata only", "needs attention") to communicate fundamentally different things across different domains.

**Why it matters for enterprise/MSP trust:**

1. **False alarm risk is real and frequent.** An operator scanning a baseline snapshot sees "Unsupported" (gray badge) and "Gaps present" (yellow badge) and cannot distinguish a product renderer limitation from a genuine governance gap. Every scan of every resource containing fallback-rendered policy types will surface these warnings, training operators to ignore them — which then masks real issues.

2. **The problem is structural, not cosmetic.** The badge system (`BadgeDomain`, 43 domains, ~500 case values) is architecturally sound and well-centralized. But it maps heterogeneous semantic axes onto a single severity/color channel (success/warning/danger/gray). The infrastructure is good; the taxonomy feeding it is wrong.

3. **The problem spans every major domain.** Operations, Baselines, Evidence, Findings, Reviews, Inventory, Restore, Onboarding, and Alerts all exhibit the same pattern: a single status badge or label is asked to communicate execution outcome + data quality + product support maturity + operator urgency simultaneously.

4. **The heaviest damage is in three areas:**
   - **Baseline Snapshots** — "Unsupported", "Reference only", "Partial", "Gaps present" all describe product/renderer limitations but read as data quality failures
   - **Restore Runs** — "Partial", "Manual required", "Dry run", "Completed with errors", "Skipped" create a 5-way ambiguity about what actually happened
   - **Evidence/Review Completeness** — "Partial", "Missing", "Stale" collapse three distinct axes (coverage, age, depth) into one badge

**Estimated impact:** ~60% of warning-colored badges in the product communicate something that is NOT a governance problem. This erodes the signal-to-noise ratio for the badges that actually matter.

---

## 2. Semantic Taxonomy Problems

The product needs to distinguish **at minimum 8 independent meaning axes**. Currently it conflates most of them.

### 2.1 Required Semantic Axes

| # | Axis | What it answers | Who cares |
|---|------|----------------|-----------|
| 1 | **Execution outcome** | Did the operation run succeed, fail, or partially complete? | Operator |
| 2 | **Data completeness** | Is the captured data set complete for the scope requested? | Operator |
| 3 | **Evidence depth / fidelity** | How much detail was captured per item (full settings vs. metadata envelope)? | Auditor / Compliance |
| 4 | **Product support maturity** | Does TenantPilot have a specialized renderer/handler for this policy type or is it using a generic fallback? | Product team (not operator) |
| 5 | **Governance deviation** | Is this finding, drift, or posture gap a real compliance/security concern? | Risk officer |
| 6 | **Publication readiness** | Can this review/report be published to stakeholders? | Review author |
| 7 | **Data freshness** | When was this data last updated, and is it still within acceptable thresholds? | Operator |
| 8 | **Operator actionability** | Does this state require operator intervention, or is it informational? | Operator |

### 2.2 Where They Are Currently Conflated

| Conflation | Example | Axes mixed |
|-----------|---------|------------|
| Baseline snapshot with fallback renderer shows "Unsupported" badge + "Gaps present" | Axes 4 + 5 | Product support maturity presented as governance deviation |
| Evidence completeness shows "Missing" (red/danger) when no findings exist yet | Axes 2 + 8 | Completeness treated as urgency |
| Restore run shows "Partial" (yellow) | Axes 1 + 2 | Execution outcome mixed with scope completion |
| Review completeness shows "Stale" | Axes 2 + 7 | Completeness mixed with freshness |
| Operation outcome "Partially succeeded" | Axes 1 + 2 | Execution result mixed with item-level coverage |
| "Blocked" used for both operation outcomes and verification reports | Axes 1 + 8 | Execution state mixed with actionability |
| "Failed" used for 10+ different badge domains | Axes 1 + 4 + 5 | Everything that isn't success collapses to "failed" |

---

## 3. Findings by Domain

### 3.1 Operations / Runs

**Affected components:**
- `OperationRunOutcome` enum + `OperationRunOutcomeBadge`
- `OperationUxPresenter` (terminal notifications)
- `SummaryCountsNormalizer` (run summary line)
- `RunFailureSanitizer` (failure message formatting)
- `OperationRunResource` (table, infolist)
- `OperationRunQueued` / `OperationRunCompleted` notifications

**Current problematic states:**

| State | Badge | Problem |
|-------|-------|---------|
| `PartiallySucceeded` | "Partially succeeded" (yellow) | Does not explain: how many items succeeded vs. failed, whether core operation goals were met, or what items need attention. Operator cannot distinguish "99 of 100 policies synced" from "1 of 100 policies synced." |
| `Blocked` | "Blocked" (yellow) | Same color as PartiallySucceeded. Does not explain: blocked by what (RBAC? provider? gate?), or what to do next. |
| `Failed` | "Failed" (red) | Reasonable for execution failure, but failure messages are truncated to 140 chars and sanitized to internal reason codes (`RateLimited`, `ProviderAuthFailed`). Operator gets "Failed. Rate limited." with no retry guidance. |

**Notification problems:**
- "Completed with warnings" — what warnings? Where are they?
- "Execution was blocked." — no explanation or recovery action
- Summary counts show raw keys like `errors_recorded`, `posture_score`, `report_deduped` without context
- Queued notification says "Running in the background" — no ETA or queue position

**Classification:** Systemic (affects all run types across all domains)  
**Operator impact:** HIGH — every failed or partial operation leaves operator uncertain about actual state

### 3.2 Baselines / Snapshots / Compare

**Affected components:**
- `FidelityState` enum (Full / Partial / ReferenceOnly / Unsupported)
- `BaselineSnapshotFidelityBadge`
- `BaselineSnapshotGapStatusBadge`
- `BaselineSnapshotPresenter` + `RenderedSnapshot*` DTOs
- `GapSummary` class
- `FallbackSnapshotTypeRenderer`
- `SnapshotTypeRendererRegistry`
- `baseline-snapshot-summary-table.blade.php`
- `baseline-snapshot-technical-detail.blade.php`
- `BaselineSnapshotResource`, `BaselineProfileResource`

**This is the single worst-affected domain.** Four separate problems compound:

**Problem 1: FidelityState mixes product maturity with data quality**

| FidelityState | What it actually means | What operator reads |
|--------------|----------------------|-------------------|
| `Full` | Specialized renderer produced structured output | "Data is complete" |
| `Partial` | Some items rendered fully, others fell back | "Data is partially missing" |
| `ReferenceOnly` | Only metadata envelope captured, no settings payload | "Only a reference exists" (alarming) |
| `Unsupported` | No specialized renderer exists; fallback used | "This policy type is broken" |

The `coverageHint` texts are better but still technical:
- "Mixed evidence fidelity across this group."
- "Metadata-only evidence is available."
- "Fallback metadata rendering is being used."

**Problem 2: "Gaps" conflates multiple causes**

`GapSummary` messages include:
- "Metadata-only evidence was captured for this item." — this is a capture depth choice, not a gap
- "A fallback renderer is being used for this item." — this is a product maturity issue, not a data gap
- Actual capture errors (e.g., Graph returned an error) — these ARE real gaps

All three are counted as "gaps" and surfaced under the same "Gaps present" (yellow) badge. An operator cannot distinguish "we chose to capture light" from "the API returned an error" from "we don't have a renderer for this type yet."

**Problem 3: "Captured with gaps" state label**

`BaselineSnapshotPresenter.stateLabel` returns either "Complete" or "Captured with gaps". This is the top-level snapshot state that operators see first. If any policy type uses a fallback renderer, the entire snapshot is labeled "Captured with gaps" — even if every single policy was successfully captured and the only "gap" is that the product's renderer coverage hasn't been built out yet.

**Problem 4: Technical detail exposure**

The `baseline-snapshot-technical-detail.blade.php` template includes the comment: "Technical payloads are secondary on purpose. Use them for debugging capture fidelity and renderer fallbacks." This is good intent, but the primary view still surfaces "Unsupported" and "Gaps present" badges that carry the same connotation.

**Classification:** P0 — actively damages operator trust  
**Operator impact:** CRITICAL — every baseline snapshot containing non-specialized policy types (which is most of them in a real tenant) will show yellow warnings that are not governance problems

### 3.3 Evidence / Evidence Snapshots

**Affected components:**
- `EvidenceCompletenessState` enum (Complete / Partial / Missing / Stale)
- `EvidenceCompletenessBadge`
- `EvidenceSnapshotStatus` enum + `EvidenceSnapshotStatusBadge`
- `EvidenceCompletenessEvaluator`
- `EvidenceSnapshotResource`
- Evidence source classes (`FindingsSummarySource`, `OperationsSummarySource`)

**Current problematic states:**

| State | Badge Color | Problem |
|-------|------------|---------|
| `Missing` | Red/danger | Used when a required evidence dimension has no data. But "missing" could mean: never collected, collection failed, data source empty (no findings exist yet = no evidence to collect). A new tenant with zero findings will show "Missing" in red for the findings dimension, which reads as a failure. |
| `Partial` | Yellow/warning | Means some dimensions are incomplete. Does not explain which or why. |
| `Stale` | Gray | Evidence collected > 30 days ago. Gray color suggests it's fine / archived, but stale evidence is actually operationally risky. Wrong severity mapping. |

**Source-level problems:**
- `FindingsSummarySource`: returns `Complete` if findings exist, `Missing` otherwise. A tenant with no findings is not "missing evidence" — it has zero findings, which is valid.
- `OperationsSummarySource`: returns `Complete` if operations ran in last 30 days, `Missing` otherwise. A stable tenant with no recent operations is not "missing" — it's stable.

**Classification:** P0 — "Missing" (red) for valid empty states is a false alarm  
**Operator impact:** HIGH — new tenants or stable tenants will always show red/yellow completeness badges that are not problems

### 3.4 Findings / Exceptions / Risk Acceptance

**Affected components:**
- `FindingResource` (form, infolist, table)
- `FindingExceptionResource`
- `FindingStatusBadge`, `FindingSeverityBadge`
- `FindingExceptionStatusBadge`
- `FindingRiskGovernanceValidityBadge`

**Current problematic states:**

| Term | Location | Problem |
|------|----------|---------|
| "Validity" | Finding infolist | Label for governance validity badge. Values include `missing_support` which reads as a product defect, not a governance state. |
| "Missing support" | `FindingRiskGovernanceValidityBadge` | Means "no exception record exists for this risk-accepted finding." This is a governance gap, not a product support issue. Label suggests the product is broken. |
| "Exception status" | Finding infolist section | Section heading uses "exception" (internal concept) instead of operator-facing language like "Risk approval status" |
| "Risk governance" | Finding infolist section | Appropriate term but not explained; grouped with "Validity" which is confusing |

**Drift diff unavailable messages leak technical language:**
- "RBAC evidence unavailable — normalized role definition evidence is missing."
- "Diff unavailable — missing baseline policy version reference."
- "Diff unavailable — missing current policy version reference."

These are accurate but incomprehensible to operators. They should say what happened and what action to take.

**Classification:** P1 — confusing but less frequently seen than baselines/evidence  
**Operator impact:** MEDIUM — affects finding detail pages, which are high-attention moments

### 3.5 Tenant Reviews / Reports / Publication

**Affected components:**
- `TenantReviewStatus` enum + `TenantReviewStatusBadge`
- `TenantReviewCompletenessState` enum + badge
- `TenantReviewReadinessGate`
- `TenantReviewComposer` / `TenantReviewSectionFactory`
- `ReviewPackResource`, `TenantReviewResource`

**Current problematic states:**

| State | Problem |
|-------|---------|
| "Partial" completeness | Same conflation as Evidence: partial coverage vs. partial depth vs. partial freshness all collapsed |
| "Stale" completeness | A review section based on old evidence should be orange/yellow (action needed), not gray (archived/inert) |
| "{Section} is stale and must be refreshed before publication" | Accurate blocker message, but no guidance on HOW to refresh |
| "{Section} is missing" | Confuses "section text hasn't been generated yet" with "underlying data doesn't exist" |
| "Anchored evidence snapshot" | Used in form helper text and empty states — jargon for "the snapshot this review is based on" |

**Publication readiness gate is well-designed** — it correctly separates blockers from completeness. But the messages surfaced to operators still use the collapsed vocabulary.

**Highlight bullets are good:** "3 open risks from 12 tracked findings" is clear operator language. The recommended next actions are also well-written. This domain is ahead of baselines/evidence in semantic clarity.

**Classification:** P1 — partially solved, but completeness/freshness conflation remains  
**Operator impact:** MEDIUM — review authors are typically more sophisticated users

### 3.6 Restore Runs

**Affected components:**
- `RestoreRunStatus` enum + badge (13 states including legacy)
- `RestoreResultStatusBadge` (7 states)
- `RestorePreviewDecisionBadge` (5 states)
- `RestoreCheckSeverityBadge`
- `RestoreRunResource` (form, infolist)
- `restore-results.blade.php`
- `restore-run-checks.blade.php`

**This is the second-worst domain for semantic confusion.** The restore workflow has:

- **13 lifecycle states** (most products have 4-6) — including legacy states that are still displayable
- **7 result statuses** per item — three of which are yellow/warning with different meanings
- **5 preview decisions** — including "Created copy" (why?) and "Skipped" (intentional or forced?)

**Specific problems:**

| State | Badge | Problem |
|-------|-------|---------|
| `Partial` (run-level) | Yellow | "Some items restored; some failed." But which? How many? Is the tenant in a consistent state? |
| `CompletedWithErrors` | Yellow | Legacy state. Does "completed" mean all items were attempted, or all succeeded and errors are secondary? |
| `Partial` (item-level) | Yellow | Mean something different from run-level partial — "item partially applied" |
| `Manual required` | Yellow | What manual action? Where? By whom? |
| `Dry run` | Blue/info | Could be confused with success. "Applied" is green, "Dry run" is blue — but the operation did NOT apply. |
| `Skipped` | Yellow | Intentional skip (user chose to exclude) vs. forced skip (precondition failed) conflated |
| `Created copy` | Yellow | Implies a naming conflict was resolved by creating a copy. Warning color suggests this is bad, but it might be expected behavior. |

**Form helper text is especially problematic:**
- "Preview-only types stay in dry-run" — operators don't know what "preview-only types" are
- "Include foundations (scope tags, assignment filters) with policies to re-map IDs" — three jargon terms in one sentence
- "Paste the target Entra ID group Object ID (GUID)" — technical protocol language

**Restore check display:**
- "Blocking" (red) — operator may think the system is frozen, not that a validation check needs attention
- "Unmapped groups" — no explanation of what mapping means or how to do it

**Classification:** P0 — restore is a high-risk, high-attention operation where confusion has real consequences  
**Operator impact:** CRITICAL — incorrect interpretation of restore state can lead to incorrect remediation decisions

### 3.7 Inventory / Coverage / Sync / Provider Health

**Affected components:**
- `InventoryKpiBadges` / `InventoryKpiHeader` widget
- `InventoryCoverage` page
- `InventorySyncService`
- `PolicySnapshotModeBadge` ("Full" / "Metadata only")
- `ProviderConnectionStatusBadge`, `ProviderConnectionHealthBadge`
- `PolicyResource` (sync action, snapshot mode helper)

**Current problematic states:**

| State | Problem |
|-------|---------|
| "Partial" items (yellow) in KPI | Means "preview-only restore mode" — a product support maturity fact, not a data quality issue. |
| "Risk" items (red) in KPI | Correct usage — these are genuinely higher-risk policy types. |
| "Metadata only" snapshot mode (yellow + warning icon) | Technical capture mode presented as if something is wrong. For some policy types, metadata-only capture IS the correct behavior. |
| Sync error: "Inventory sync reported rate limited." | Mechanically constructed from error code (`str_replace('_', ' ', $errorCode)`). No retry guidance. |
| Provider "Needs consent" | No context about what consent, where to grant it, or who can grant it. |
| Provider "Degraded" | No detail on what is degraded or whether operations are affected. |

**Graph error leakage in PolicyResource:**
- "Graph returned {status} for this policy type. Only local metadata was saved; settings and restore are unavailable until Graph works again."
- This is accurate but uses internal API naming ("Graph") and makes the scope unclear (is restore blocked for one policy or all policies?).

**Classification:** P1 — inventory is read-frequently and yellow badges train operators to ignore warnings  
**Operator impact:** MEDIUM-HIGH — scanning inventory with perpetual yellow badges erodes warning credibility

### 3.8 Onboarding / Verification

**Affected components:**
- `VerificationReportOverall` + badge ("Ready" / "Needs attention" / "Blocked")
- `VerificationCheckStatus` + badge ("Pass" / "Fail" / "Warn" / "Skip")
- `ManagedTenantOnboardingVerificationStatusBadge`
- `VerificationAssistViewModelBuilder`
- `ManagedTenantOnboardingWizard` (notifications, modals)
- `verification-required-permissions-assist.blade.php`

**Current problematic states:**

| State | Problem |
|-------|---------|
| "Needs attention" | Non-specific. Used for both missing delegated permissions and stale data. |
| "Blocked" | Means "missing required application permissions" but reads as "system is blocked." |
| "Fail" check status | Ambiguous: check execution failed, or check assertion failed? Both are possible meanings. |
| Wizard notifications: "Tenant not available", "Draft is not resumable" | No explanation of why or what to do. |
| "Verification required" | No detail on what verification is needed or estimated effort. |

**The verification assist panel is well-designed** — it categorizes missing permissions by application vs. delegated and shows feature impact. This is a positive example of good semantic separation that could be replicated elsewhere.

**Classification:** P2 — onboarding is a one-time flow with guided steps  
**Operator impact:** LOW-MEDIUM — operators encounter this during setup, not daily operations

### 3.9 Alerts / Notifications

**Affected components:**
- `EmailAlertNotification`
- `AlertDeliveryStatusBadge`
- `AlertDestinationLastTestStatusBadge`

**Current problematic states:**

| State | Problem |
|-------|---------|
| Email body includes "Delivery ID: {id}" and "Event type: {type}" | Internal metadata exposed to operators without context. |
| "Failed" delivery status (red) | No distinction between transient (retry-able) and permanent failure. |
| Queued notification: "Running in the background." | No ETA, no queue position, no way to check progress until terminal notification arrives. |

**Classification:** P2 — alerts are less frequently viewed  
**Operator impact:** LOW — these are supplementary signals, not primary operator workflows

---

## 4. Cross-Cutting Terminology Map

### 4.1 Most Problematic Terms

| Term | Appearances | Meanings it carries | Why dangerous | Should belong to |
|------|-------------|-------------------|---------------|-----------------|
| **"Failed"** | OperationRunOutcome, RestoreRunStatus, RestoreResultStatus, ReviewPackStatus, EvidenceSnapshotStatus, AlertDeliveryStatus, TenantReviewStatus, AlertDestinationLastTestStatus, BackupSetStatus, TenantRbacStatus, AuditOutcome | (1) Operation execution failure, (2) validation check assertion failure, (3) generation/composition failure, (4) delivery failure, (5) catch-all for non-success | Undifferentiated — operator cannot assess severity, retryability, or scope without drilling in. Red badge for all cases regardless of impact. | Axis 1 (execution outcome) only. Other uses need distinct terms: "check failed" → "not met"; delivery failed → "undeliverable"; generation failed → "generation error" |
| **"Partial"** | OperationRunOutcome (PartiallySucceeded), RestoreRunStatus, RestoreResultStatus, EvidenceCompletenessState, TenantReviewCompletenessState, FidelityState, BackupSetStatus, AuditOutcome, InventoryKpiBadges | (1) Some items in a batch succeeded, others didn't, (2) evidence depth is limited, (3) capture coverage is incomplete, (4) product renderer coverage is partial, (5) restore mode is preview-only | 8+ different meanings across the product. Yellow badge always. An operator reading "Partial" has no way to know which kind without drilling into details. | Axis-specific terms: "N of M items processed" (Axis 1), "Limited detail" (Axis 3), "Incomplete coverage" (Axis 2), "Preview mode" (Axis 4) |
| **"Missing"** | EvidenceCompletenessState, TenantReviewCompletenessState, TenantPermissionStatus, ReferenceResolutionState (DeletedOrMissing), FindingRiskGovernanceValidity (missing_support) | (1) Evidence dimension has no data, (2) required review section not generated, (3) permission not granted, (4) referenced record deleted/not found, (5) no exception exists for risk-accepted finding | "Missing" in red across all uses. But "zero findings" is not "missing findings" — it's an empty valid state. | Separate into: "Not collected" (evidence), "Not generated" (sections), "Not granted" (permissions), "Not found" (references), "No exception" (governance) |
| **"Gaps"** | BaselineSnapshotGapStatus, GapSummary, BaselineSnapshotPresenter ("Captured with gaps") | (1) Fallback renderer was used, (2) metadata-only capture mode, (3) actual capture error, (4) missing coverage | Merges product limitation with data quality problem. Every snapshot with unsupported types shows "Gaps present" perpetually. | "Coverage notes" or "Capture notes" — with sub-categories for product limitation vs. actual data gap |
| **"Unsupported"** | FidelityState, ReferenceClass | (1) No specialized renderer for this policy type (product maturity), (2) reference class not recognized | Reads as "this policy type is broken" when it actually means "we haven't built a dedicated viewer yet, but the data is captured." | "Generic view" or "Standard rendering" — product support state should never be operator-alarming |
| **"Stale"** | EvidenceCompletenessState, TenantReviewCompletenessState, TenantRbacStatus | (1) Evidence older than 30 days, (2) review section based on old snapshot, (3) RBAC check results outdated | Gray badge color (passive) for freshness issues that may require action. Conflates with completeness (same enum). | Separate axis: "Last updated: 45 days ago" with age-based coloring. Not part of completeness axis. |
| **"Blocked"** | OperationRunOutcome, VerificationReportOverall, ExecutionDenialClass, RestoreCheckSeverity | (1) Operation prevented by gate/RBAC, (2) missing required permissions, (3) pre-flight check preventing execution | Reads as "system is frozen" regardless of cause. Yellow for operation outcome, red for verification, red for restore checks. | "Prevented" or "Requires action" with specific cause shown |
| **"Reference only"** | FidelityState | Only metadata envelope captured, no settings payload | Reads as "we only have a pointer, not the actual data" — technically correct but alarming. For some policy types, this IS the full capture because Graph doesn't expose settings. | "Metadata captured" or "Summary view" |
| **"Metadata only"** | PolicySnapshotMode, restore-results.blade.php | (1) Capture mode was metadata-only, (2) restore created policy shell without settings | Two different uses. In capture, it's a valid mode. In restore, it means manual work is needed. | Separate: "Summary capture" (mode) vs. "Shell created — configure settings manually" (restore result) |
| **"Ready"** | TenantReviewStatus, VerificationReportOverall, ReviewPackStatus, OnboardingLifecycleState (ReadyForActivation) | (1) Review cleared publication blockers, (2) permissions verified, (3) review pack downloadable, (4) onboarding ready for activation | Overloaded but less dangerous than others — context usually makes it clear. | Acceptable as-is, but should never be used alone without domain context |
| **"Complete"** | EvidenceCompletenessState, TenantReviewCompletenessState, OnboardingDraftStatus/Stage/Lifecycle, OperationRunStatus (Completed) | (1) All evidence dimensions collected, (2) all review sections generated, (3) onboarding finished, (4) operation execution finished | "Completed" operation does not mean "succeeded" — the outcome must be checked separately. | Keep for lifecycle completion. Don't use for quality — use "Full coverage" instead. |

### 4.2 Terms That Are Correctly Used

| Term | Domain | Assessment |
|------|--------|-----------|
| "Drift" | Findings | Clear, domain-appropriate |
| "Superseded" | Reviews, Snapshots | Correct lifecycle term |
| "Archived" | Multiple | Consistent and clear |
| "New" / "Triaged" / "In progress" / "Resolved" | Findings | Standard issue lifecycle |
| "Risk accepted" | Findings | Precise governance term |
| "Applied" / "Mapped" | Restore results | Clear restore outcomes |
| "Pass" / "Warn" | Verification checks | Appropriate for boolean checks |

---

## 5. Priority Ranking

### P0 — Actively damages operator trust / causes false alarms

| # | Issue | Domain | Description |
|---|-------|--------|-------------|
| P0-1 | **FidelityState "Unsupported" displayed as badge** | Baselines | Every snapshot with a fallback-rendered policy type shows "Unsupported" (gray) and "Gaps present" (yellow). This is a product maturity fact, not operator-actionable. |
| P0-2 | **"Captured with gaps" top-level snapshot state** | Baselines | One fallback renderer taints the entire snapshot label. Most snapshots will show this. |
| P0-3 | **Evidence "Missing" (red) for valid empty states** | Evidence | A new tenant with zero findings shows red "Missing" badge. Zero findings is a valid state, not missing evidence. |
| P0-4 | **Restore "Partial" ambiguity at run and item level** | Restore | Operator cannot determine scope of partial success or whether tenant is in consistent state. |
| P0-5 | **OperationRunOutcome "Partially succeeded" with no item breakdown** | Operations | Yellow badge with no way to assess impact without drilling into run details. |

### P1 — Strongly confusing, should be fixed soon

| # | Issue | Domain | Description |
|---|-------|--------|-------------|
| P1-1 | **"Stale" gray badge for time-sensitive freshness** | Evidence, Reviews | Gray implies inert/archived; stale data requires action. Wrong color mapping. |
| P1-2 | **"Blocked" with no explanation across 4 domains** | Operations, Verification, Restore, Execution | Operator reads "blocked" and cannot determine cause or action. |
| P1-3 | **"Metadata only" in snapshot mode (yellow warning)** | Inventory, Policies | Valid capture mode presented as if something is wrong. |
| P1-4 | **Restore "Manual required" without specifying what** | Restore | Yellow badge with no link to instructions or affected items. |
| P1-5 | **"Gaps present" conflates 3+ causes** | Baselines | Renderer fallback, metadata-only capture, and actual errors all counted as "gaps." |
| P1-6 | **"Missing support" in governance validity** | Findings | Means "no exception exists" but reads as "product doesn't support this." |
| P1-7 | **Technical diff-unavailable messages** | Findings | "normalized role definition evidence is missing" is incomprehensible to operators. |
| P1-8 | **Graph error codes in restore results** | Restore | "Graph error: {message} Code: {code}" shown directly to operators. |
| P1-9 | **"Partial" in inventory KPI for preview-only types** | Inventory | Product maturity fact displayed as data quality warning. |

### P2 — Quality issue, not urgent

| # | Issue | Domain | Description |
|---|-------|--------|-------------|
| P2-1 | **Notification failure messages truncated to 140 chars** | Operations | Important context may be lost. Sanitized reason codes are still technical. |
| P2-2 | **"Needs attention" without specifying what** | Onboarding, Verification | Non-specific label across multiple domains. |
| P2-3 | **"Dry run" in blue/info for restore results** | Restore | Could be confused with success. Should be more clearly distinct. |
| P2-4 | **"Anchored evidence snapshot" jargon** | Reviews | Used in form helpers and empty states without explanation. |
| P2-5 | **Empty state messages lack next-step guidance** | Multiple | Most empty states describe what the feature does, not how to start. |
| P2-6 | **Queued notifications lack progress indicators** | Operations | "Running in the background" with no ETA or monitoring guidance. |
| P2-7 | **Email alerts include raw internal IDs** | Alerts | "Delivery ID: {id}" and "Event type: {type}" shown to operators. |

### P3 — Polish / later cleanup

| # | Issue | Domain | Description |
|---|-------|--------|-------------|
| P3-1 | **"Archiving is permanent in v1"** | Baselines | Version reference in modal text. |
| P3-2 | **"foundations" term unexplained** | Baselines, Restore | Internal grouping concept used in helper text. |
| P3-3 | **"Skipped" in restore without intent distinction** | Restore | Intentional vs. forced skip use same badge. |
| P3-4 | **Summary count keys like "report_deduped"** | Operations | Internal metric name in operator-facing summary. |

---

## 6. Recommended Target Model

### 6.1 State Axes — Mandatory Separation

The product must maintain **independent** state tracking for these axes. They must never be flattened into a single badge or single enum:

| Axis | Scope | Operator-facing? | Values |
|------|-------|-----------------|--------|
| **Execution lifecycle** | Per operation run | Yes | Queued → Running → Completed |
| **Execution outcome** | Per operation run | Yes | Succeeded / Completed with issues / Failed / Prevented |
| **Item-level result** | Per item in a run | Yes (on drill-in) | Applied / Skipped (with reason) / Failed (with reason) |
| **Data coverage** | Per evidence/review dimension | Yes | Full / Incomplete / Not collected |
| **Evidence depth** | Per captured item | Yes (secondary) | Detailed / Summary / Metadata envelope |
| **Product support tier** | Per policy type | Diagnostics only | Dedicated renderer / Standard renderer |
| **Data freshness** | Per evidence item/dimension | Yes (separate from coverage) | Current (< N days) / Aging / Overdue |
| **Governance status** | Per finding/exception | Yes | Valid / Expiring / Expired / None |
| **Publication readiness** | Per review | Yes | Publishable / Blocked (with reasons) |
| **Operator actionability** | Cross-cutting | Yes (determines badge urgency color) | Action required / Informational / No action needed |

### 6.2 Diagnostic-Only Terms (Never in Primary Operator View)

These terms should appear ONLY in expandable/collapsible diagnostic panels, never in primary badges or summary text:

- "Fallback renderer" → show "Standard rendering" in diagnostic, nothing in primary
- "Metadata only" (as capture detail) → show "Summary view" in primary, mode detail in diagnostic
- "Renderer registry" → never shown
- "FidelityState" → replaced by "Evidence depth" in operator language
- "Gap summary" → replaced by "Coverage notes"
- Raw Graph error codes → replaced by categorized operator messages
- Delivery IDs, event type codes → never in email body
- `errors_recorded`, `report_deduped` → never in summary line; use operator terms

### 6.3 Warning vs. Info vs. Error — Decision Rules

| Color | When to use | Never use for |
|-------|------------|--------------|
| **Red (danger)** | Execution failed, governance violation active, permission denied, data loss risk | Product support limitations, empty valid states, expired but inactive records |
| **Yellow (warning)** | Operator action recommended, approaching threshold, mixed outcome | Product maturity facts, informational states, things the operator cannot change |
| **Blue (info)** | In progress, background activity, informational detail | States that could be confused with success outcomes |
| **Green (success)** | Operation succeeded, check passed, data complete | States that could change (success should be stable) |
| **Gray (neutral)** | Archived, not applicable, skipped | Stale data (should be yellow/orange), degraded states that need attention |

### 6.4 Where "Next Action" Is Mandatory

Every state that is NOT green or gray MUST include either:
- An inline explanation (1 sentence) of what happened and whether action is needed
- A link to a resolution path
- An explicit "No action needed — this is expected" label

Mandatory coverage:
- Failed operations → what failed, is it retryable, link to run details
- Partial operations → N of M items processed, link to item-level details
- Blocked operations → what blocked it, link to resolution (permissions page, provider settings, etc.)
- Missing evidence → why missing (no data source, not yet collected, collection error), link to trigger collection
- Stale data → when last updated, link to refresh action
- Publication blockers → which sections, link directly to each section's refresh action

---

## 7. Spec Candidate Recommendations

### Recommended approach: **Foundation spec + domain follow-up specs**

The problem has two layers:
1. A **cross-cutting taxonomy problem** that must be solved once, centrally, before domains can adopt it
2. **Domain-specific adoption** that requires touching each resource/presenter/badge/view

### Spec Package

| Spec | Scope | Priority | Dependencies |
|------|-------|----------|-------------|
| **Spec: Operator Semantic Taxonomy** | Define the target state axes, term dictionary, color rules, diagnostic vs. primary classification, and "next action" policy. Produce a shared reference that all domain specs reference. Update `FidelityState`, `EvidenceCompletenessState`, `TenantReviewCompletenessState` enums to align with new taxonomy. Restructure `GapSummary` into axis-separated notes. | P0 | None |
| **Spec: Baseline Snapshot Semantic Cleanup** | Apply taxonomy to BaselineSnapshotPresenter, FidelityState badge, GapSummary, snapshot summary table. Move renderer-tier info to diagnostics. Redefine "gaps" as categorized coverage notes. Fix "Captured with gaps" label. | P0 | Taxonomy spec |
| **Spec: Evidence Completeness Reclassification** | Fix "Missing" for valid-empty states. Separate freshness from coverage. Add "Not applicable" state for dimensions with no expected data. Fix "Stale" color. | P0 | Taxonomy spec |
| **Spec: Operation Outcome Clarity** | Replace "Partially succeeded" with item-breakdown-aware messaging. Add cause-specific "Blocked" explanations. Add next-action guidance to terminal notifications. Sanitize failure messages to operator language. | P1 | Taxonomy spec |
| **Spec: Restore Semantic Cleanup** | Reduce 13 states to clear operator lifecycle. Distinguish intentional vs. forced skips. Replace "Manual required" with specific guidance. Fix "Partial" ambiguity. Move Graph errors behind diagnostic expandable. | P1 | Taxonomy spec |
| **Spec: Inventory Coverage Language** | Replace "Partial" KPI badge for preview-only types. Replace "Metadata only" warning badge with neutral product-tier indicator. Fix sync error messages. | P1 | Taxonomy spec |
| **Spec: Finding Governance Language** | Replace "missing_support", fix diff-unavailable messages, clarify "Validity" section. | P2 | Taxonomy spec |
| **Spec: Notifications & Alerts Language** | Remove internal IDs from emails, add next-action to terminal notifications, fix summary count keys. | P2 | Taxonomy spec |

### Recommended approach summary:

**Foundation spec first** (Operator Semantic Taxonomy) that establishes the shared vocabulary, color rules, and diagnostic/primary boundary. Then **6–7 domain specs** that apply the taxonomy to each area. The foundation spec should be small and decisive — it defines rules, not implementations. The domain specs do the actual refactoring.

This avoids a monolithic spec that would be too large to review or implement incrementally, while ensuring consistency through the shared taxonomy.