TenantAtlas/docs/product/operator-semantic-taxonomy.md

# Operator Semantic Taxonomy

> Canonical operator-facing state reference for the first implementation slice.
> Downstream specs and badge mappings must reuse this vocabulary instead of inventing local synonyms.

**Last reviewed**: 2026-03-21

---

## Core Rules

1. One primary label means one thing everywhere it appears.
2. Semantic axes stay separate. Execution outcome, coverage, freshness, evidence depth, and actionability are not interchangeable.
3. Diagnostic-only states never use `warning` or `danger`.
4. Primary `warning` and `danger` states must carry an operator next-action policy.
5. Valid-empty and support-limit states are not failures unless a separate governance or execution rule says otherwise.

## Semantic Axes

| Axis | Question it answers |
|---|---|
| `execution_lifecycle` | Where a run sits in its execution flow |
| `execution_outcome` | What happened when execution finished or stopped |
| `item_result` | How one restore or preview item resolved |
| `data_coverage` | Whether the expected data or sections are present |
| `evidence_depth` | How much structured evidence detail is available |
| `product_support_maturity` | Whether TenantPilot can represent the source faithfully |
| `data_freshness` | Whether the available data is still current enough to trust |
| `operator_actionability` | Whether an operator needs to do anything next |
| `publication_readiness` | Whether the record is ready for stakeholder delivery |
| `governance_deviation` | Whether the record represents a real governance problem |

## Severity Rules

| Band | Meaning |
|---|---|
| `danger` | Execution failure, material risk, or a stop-before-proceed condition |
| `warning` | Operator attention or follow-up is recommended or required |
| `info` | In-progress or context-heavy states that are not failures by themselves |
| `success` | Intended outcome achieved with no further operator action required |
| `gray` | Neutral, diagnostic, archived, not applicable, or intentionally non-actionable context |
| `primary` | Reserved for badge-system compatibility only; avoid for first-slice operator states |

## Presentation Levels

| Level | Use |
|---|---|
| `primary` | The first label an operator uses to decide what happened and whether action is needed |
| `diagnostic` | Secondary detail that preserves technical truth without replacing the primary meaning |

## Next-Action Policy

| Policy | Meaning |
|---|---|
| `required` | Operator must act before retrying or relying on the result |
| `optional` | Review is recommended, but the state is not a hard stop |
| `none` | No operator action is needed |

## Migration Guidance

Do not ship bare first-slice labels such as `Blocked`, `Partial`, `Missing`, `Unsupported`, `Stale`, `Warning`, or `Safe`.

Use these qualified replacements instead:

| Legacy term | Adopted replacement |
|---|---|
| `Blocked` | `Blocked by prerequisite` or `Fix before running` |
| `Partial` | `Completed with follow-up`, `Coverage incomplete`, `Partially applied`, or `Mixed evidence detail` |
| `Missing` | `Not collected yet` or `Review input pending` |
| `Stale` | `Refresh recommended` or `Refresh review inputs` |
| `Unsupported` | `Support limited` |
| `Warning` | `Review before running` |
| `Safe` | `Ready to continue` |

## First-Slice Canonical Mappings

### Operations

| Raw state | Primary label | Axis | Band | Next action |
|---|---|---|---|---|
| `queued` | `Queued for execution` | `execution_lifecycle` | `info` | `none` |
| `running` | `In progress` | `execution_lifecycle` | `info` | `none` |
| `succeeded` | `Completed successfully` | `execution_outcome` | `success` | `none` |
| `partially_succeeded` | `Completed with follow-up` | `execution_outcome` | `warning` | `optional` |
| `blocked` | `Blocked by prerequisite` | `execution_outcome` | `warning` | `required` |
| `failed` | `Execution failed` | `execution_outcome` | `danger` | `required` |

### Evidence And Review Completeness

| Domain | Raw state | Primary label | Axis | Band | Next action |
|---|---|---|---|---|---|
| Evidence | `complete` | `Coverage ready` | `data_coverage` | `success` | `none` |
| Evidence | `partial` | `Coverage incomplete` | `data_coverage` | `warning` | `required` |
| Evidence | `missing` | `Not collected yet` | `data_coverage` | `info` | `optional` |
| Evidence | `stale` | `Refresh recommended` | `data_freshness` | `warning` | `optional` |
| Review | `complete` | `Review inputs ready` | `data_coverage` | `success` | `none` |
| Review | `partial` | `Review inputs incomplete` | `data_coverage` | `warning` | `required` |
| Review | `missing` | `Review input pending` | `data_coverage` | `info` | `optional` |
| Review | `stale` | `Refresh review inputs` | `data_freshness` | `warning` | `optional` |

### Baseline Semantics

| Domain | Raw state | Primary label | Level | Axis | Band |
|---|---|---|---|---|---|
| Fidelity | `full` | `Detailed evidence` | `diagnostic` | `evidence_depth` | `success` |
| Fidelity | `partial` | `Mixed evidence detail` | `diagnostic` | `evidence_depth` | `info` |
| Fidelity | `reference_only` | `Metadata only` | `diagnostic` | `evidence_depth` | `info` |
| Fidelity | `unsupported` | `Support limited` | `diagnostic` | `product_support_maturity` | `gray` |
| Gap status | `clear` | `No follow-up needed` | `primary` | `data_coverage` | `success` |
| Gap status | `gaps_present` | `Coverage gaps need review` | `primary` | `data_coverage` | `warning` |

`meta_fallback` remains diagnostic context. It does not count as a primary coverage gap by itself.

### Restore Semantics

| Domain | Raw state | Primary label | Axis | Band | Next action |
|---|---|---|---|---|---|
| Run | `completed` | `Applied successfully` | `execution_outcome` | `success` | `none` |
| Run | `partial` | `Applied with follow-up` | `execution_outcome` | `warning` | `optional` |
| Run | `completed_with_errors` | `Applied with follow-up` | `execution_outcome` | `warning` | `optional` |
| Run | `failed` | `Restore failed` | `execution_outcome` | `danger` | `required` |
| Run | `aborted` | `Stopped early` | `execution_outcome` | `gray` | `none` |
| Result | `manual_required` | `Manual follow-up needed` | `operator_actionability` | `warning` | `required` |
| Result | `mapped` | `Mapped to existing item` | `item_result` | `info` | `none` |
| Result | `skipped` | `Not applied` | `item_result` | `gray` | `optional` |
| Preview | `created` | `Will create` | `item_result` | `success` | `none` |
| Preview | `created_copy` | `Will create copy` | `item_result` | `warning` | `optional` |
| Preview | `mapped_existing` | `Will map existing` | `item_result` | `info` | `none` |
| Preview | `skipped` | `Will skip` | `item_result` | `gray` | `optional` |
| Check | `blocking` | `Fix before running` | `operator_actionability` | `danger` | `required` |
| Check | `warning` | `Review before running` | `operator_actionability` | `warning` | `optional` |
| Check | `safe` | `Ready to continue` | `operator_actionability` | `success` | `none` |

## Curated Examples

The first-slice guard rubric scores these twelve examples:

1. Operation blocked by missing prerequisite
2. Operation completed with follow-up
3. Operation completed successfully
4. Evidence not collected yet
5. Evidence refresh recommended
6. Review input pending
7. Mixed evidence detail stays diagnostic
8. Support limited stays diagnostic
9. Coverage gaps need review
10. Restore preview blocked by a check
11. Restore run applied with follow-up
12. Restore item requires manual follow-up

## Cross-View Safety Rules

- First-slice resources that do not expose an edit or view lifecycle through global search stay out of global search.
- Taxonomy-backed filter labels, badge counts, and summaries must be derived from already-authorized workspace and tenant scope only.
- Canonical views may reuse the same vocabulary as tenant-context views, but they must not reveal hidden tenant names, counts, or filter hints.