TenantAtlas/specs/156-operator-outcome-taxonomy/spec.md

Feature Specification: Operator Outcome Taxonomy and Cross-Domain State Separation

Feature Branch: 156-operator-outcome-taxonomy
Created: 2026-03-21
Status: Draft
Input: User description: "Operator Outcome Taxonomy and Cross-Domain State Separation"

Spec Scope Fields (mandatory)

• Scope: workspace + tenant + canonical-view
• Primary Routes:
  • /admin/operations
  • /admin/operations/{run}
  • /admin/t/{tenant}/... adopted tenant governance surfaces for evidence, review, baseline, and restore states that present status, outcome, completeness, freshness, or actionability
  • Workspace-scoped canonical views that aggregate the bounded first-slice states across operations, evidence or review completeness, baselines, and restore workflows
• Data Ownership:
  • This feature does not create a new business domain record; it defines the shared operator-facing meaning layer used when existing workspace-owned and tenant-owned records are presented.
  • Workspace-owned records affected include operation runs, system-console summaries, canonical lists, and shared cross-tenant presentation surfaces.
  • Tenant-owned records affected in the bounded first slice include baseline snapshots, evidence and review completeness summaries, and restore outcomes as they are rendered to operators.
  • Underlying source data ownership does not change; only the normalized operator-facing classification of that data changes.
• RBAC:
  • Existing workspace membership, tenant entitlement, and capability rules remain the only access boundary for affected surfaces.
  • This feature does not create a new privilege family; it standardizes how already-authorized operators interpret state once a record is visible.
  • Non-members and wrong-tenant users remain deny-as-not-found, and the taxonomy must not leak hidden tenant state through shared vocabulary, filter values, counts, badges, or summaries.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: When an operator enters a canonical workspace view from tenant context, the view opens prefiltered to the current tenant and only exposes taxonomy-backed state filters for tenants the operator is entitled to inspect.
• Explicit entitlement checks preventing cross-tenant leakage: State labels, badge counts, warning totals, empty-state wording, filter options, and aggregated summaries must be computed only from records inside the operator's authorized workspace and tenant scope. Unauthorized tenant states must not be inferable from shared labels such as Needs attention, Blocked, Stale, or Missing.

User Scenarios & Testing (mandatory)

User Story 1 - Distinguish Real Governance Risk From Diagnostics (Priority: P1)

As an operator, I want warning and error states to mean the same thing across the product, so that I can tell whether a record represents a real governance problem, a valid empty state, or only diagnostic product detail.

Why this priority: This is the trust-critical problem the candidate addresses. If warning colors and overloaded terms continue to mean different things across domains, later domain work keeps reproducing false alarms.

Independent Test: Can be fully tested by reviewing a curated set of adopted surfaces containing mixed examples such as blocked runs, stale data, valid-empty evidence, and product-support limitations, and verifying that each example is classified on the correct semantic axis with the correct severity.

Acceptance Scenarios:

1. Given a surface shows a valid empty state with no findings or no evidence collected yet, When the operator views the record, Then the state is rendered as neutral or informational rather than as a danger or warning condition.
2. Given a surface shows a real governance or execution problem, When the operator views the record, Then the state is rendered with the shared warning or error vocabulary and not with a domain-local synonym.
3. Given a surface contains product-support or renderer-maturity detail, When the operator views the record, Then that detail appears as secondary diagnostics rather than as a primary warning badge.

---

User Story 2 - Know What Happened And Whether Action Is Needed (Priority: P1)

As an operator, I want every non-green state to explain whether action is required and what kind of problem it is, so that I do not need to reverse-engineer ambiguous labels like Partial, Blocked, or Missing.

Why this priority: Even if colors are corrected, the system still fails operators when non-green states do not say whether the issue is execution failure, stale data, incomplete coverage, or a no-action-needed limitation.

Independent Test: Can be fully tested by checking adopted non-green examples and verifying that each one includes a cause-specific label plus either a next action, a link to the next action, or an explicit No action needed explanation.

Acceptance Scenarios:

1. Given a run or governance record is blocked by a prerequisite, When the operator opens the list or detail surface, Then the state names the blocking cause and points to the appropriate next action.
2. Given a record is stale but otherwise valid, When the operator views it, Then the state makes freshness the primary issue and does not imply the record is archived or broken.
3. Given a mixed or partial result is shown, When the operator inspects it, Then the state clarifies which dimension is partial instead of using an unqualified Partial label.

---

User Story 3 - Reuse One Vocabulary Across Domains (Priority: P2)

As a product owner, I want one shared operator outcome taxonomy used by every adopted domain, so that new governance surfaces do not invent local badge words, color rules, or severity meanings.

Why this priority: This converts a one-time semantic cleanup into a durable product standard. Without a shared taxonomy, every downstream spec reintroduces drift.

Independent Test: Can be fully tested by reviewing the bounded first-slice adoption set across operations, evidence and review completeness, baseline snapshots, and restore surfaces and confirming that the same shared term dictionary and axis rules are applied everywhere.

Acceptance Scenarios:

1. Given two adopted domains display comparable state concepts, When the operator moves between them, Then the same term keeps the same meaning and severity in both places.
2. Given a state belongs to a different semantic axis than the one currently shown, When the surface renders it, Then the system keeps those axes separate instead of flattening them into one overloaded badge.

Edge Cases

• A record has more than one degraded dimension at the same time, such as successful execution with stale data and partial coverage; the surface must separate those signals instead of collapsing them into one ambiguous warning.
• A valid empty tenant with no findings, no evidence snapshot, or no completed operation history must not appear as failed merely because no data exists yet.
• A domain still needs to preserve raw technical cause information for diagnostics; the taxonomy must allow secondary detail without letting that detail replace the primary operator message.
• The same record appears in both tenant-context and workspace-canonical views; the wording and severity must stay consistent while still respecting scope filtering.
• A condition is non-green but intentionally needs no operator action, such as a known product-support limitation; the state must say that no action is required.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no new Microsoft Graph calls and no new business-domain mutation flow. It defines a shared semantic contract for operator-facing state presentation across existing records and workflows. Where adopted surfaces already create OperationRun records, this spec may refine how those outcomes are named, grouped, and explained, but it does not create a second observability model. No safety-critical mutation is hidden behind semantics-only changes; any adopted destructive actions continue to use their existing preview, confirmation, audit, and tenant-isolation rules.

Constitution alignment (OPS-UX): This feature may change how existing OperationRun outcomes are translated and explained on list and detail surfaces, but it does not alter the three-surface feedback contract. Start surfaces remain intent-only. Progress remains confined to active-ops and canonical run detail. Terminal database notifications remain driven by the existing operation lifecycle. OperationRun.status and OperationRun.outcome transitions remain service-owned, while this spec only standardizes operator-facing meaning, explanation, and summary wording. Any summary-count language exposed to operators must remain numerically stable and semantically translated without leaking internal metric keys.

Constitution alignment (RBAC-UX): This feature affects operator-facing vocabulary in both tenant/admin and workspace-canonical views. Cross-plane access remains deny-as-not-found. Non-members or users outside workspace or tenant scope continue to receive 404, while in-scope users lacking required capabilities for the underlying resource continue to receive 403. Authorization is not delegated to semantics. The taxonomy must never cause a hidden record to become inferable via global search, filter values, counts, badges, or summary text. At least one positive and one negative authorization regression test must prove that shared state presentation remains non-member-safe.

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 foundation slice. All adopted status-like values must map through centralized semantics rather than page-local badge decisions. The taxonomy must define which categories are primary operator signals versus secondary diagnostics, and tests must cover any newly introduced or remapped values.

Constitution alignment (UI-NAMING-001): The target objects are operator-facing states shown for runs, baselines, evidence, findings, restore results, inventory or provider posture, and onboarding or verification summaries. Operator vocabulary must preserve one meaning per term across buttons, headers, notifications, helper copy, summaries, and audit prose. Implementation-first terms and backend-only codes must remain secondary details.

Constitution alignment (Filament Action Surfaces): This feature modifies operator-facing meaning on existing Filament pages and resources but does not introduce a new destructive action family. The Action Surface Contract remains satisfied when adopted surfaces preserve canonical inspect affordances, keep mutation actions capability-gated and auditable, and use the shared taxonomy only to clarify state meaning rather than to hide action consequences.

Constitution alignment (UX-001 — Layout & Information Architecture): This feature is primarily a semantic and presentation foundation. Existing screens retain their current page categories and layouts unless a downstream adoption spec changes them. For adopted screens, status badges, empty states, search filters, and summary sections must use the taxonomy consistently. Valid-empty states must have specific explanatory copy and exactly one clear next-step or No action needed signal.

Functional Requirements

• FR-156-001: The system MUST define one shared operator outcome taxonomy that separates at least execution lifecycle, execution outcome, item-level result, data coverage, evidence depth, product support tier, data freshness, and operator actionability into distinct semantic axes.
• FR-156-002: The system MUST ensure that a term used as a primary operator label has exactly one meaning across all adopted domains.
• FR-156-003: The system MUST prevent different semantic axes from being flattened into one overloaded badge, label, or state unless the surface explicitly presents each axis separately.
• FR-156-004: The system MUST define shared severity and color decision rules so that danger means execution failure, governance breach, or material risk; warning means operator attention is recommended; informational means in-progress or context-only signals; success means the intended outcome was achieved; and neutral means archived, not applicable, or expected non-actionable context.
• FR-156-005: The system MUST forbid product-support maturity, renderer tier, and other implementation-limitation facts from appearing as primary warning or danger states.
• FR-156-006: The system MUST classify every adopted state signal as either primary operator meaning or secondary diagnostic detail.
• FR-156-007: The system MUST require every adopted non-green, non-neutral primary state to include either a next action, a resolution link, or an explicit explanation that no operator action is required.
• FR-156-008: The system MUST treat valid-empty conditions such as zero findings, no evidence yet collected, or no completed work yet as non-failure states unless a separate adopted rule explicitly says otherwise.
• FR-156-009: The system MUST require that Blocked, Partial, Missing, Unsupported, Stale, and similar historically overloaded labels be replaced or qualified so the operator can tell which semantic axis is being described.
• FR-156-010: The system MUST make freshness a distinct axis from completeness, so stale data is not rendered as archival or product-maturity context.
• FR-156-011: The system MUST make partiality a qualified state that states what is partial, such as execution coverage, data coverage, or evidence depth, rather than allowing an unqualified partial label.
• FR-156-012: The system MUST make blocked states cause-specific and action-oriented rather than using bare blocked wording.
• FR-156-013: The system MUST preserve raw technical reasons and backend precision for diagnostics, but those details MUST remain secondary to the shared operator-facing label.
• FR-156-014: The system MUST provide one shared taxonomy reference that downstream domain specs and adopted surfaces can consume as the source of truth for operator-facing state semantics.
• FR-156-015: The first implementation slice MUST apply the taxonomy to a defined adoption set that includes operations, baseline-related surfaces, restore-related surfaces, and evidence plus review completeness as the additional cross-domain family.
• FR-156-016: The first implementation slice MUST define migration guidance for existing overloaded labels so downstream domain work can replace local synonyms without inventing new ones.
• FR-156-017: Adopted canonical views and tenant-context views MUST apply the same term dictionary and severity rules while still respecting tenant-scope filtering and deny-as-not-found behavior.
• FR-156-018: Global search, cross-tenant counts, filter chips, and summary badges MUST remain non-member-safe when they adopt the shared taxonomy.
• FR-156-019: The feature MUST include at least one positive and one negative authorization regression test proving that taxonomy-backed presentation does not leak unauthorized tenant state.
• FR-156-020: The feature MUST include regression coverage for valid-empty states, freshness states, blocked states, partial states, and product-support diagnostics so that future domain work cannot silently reintroduce overloaded semantics.

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
Operations index and detail	Existing operations list and run detail surfaces	Existing controls unchanged	Existing canonical run inspection remains primary	None added by this feature	None added by this feature	Existing CTA unchanged	Existing run actions unchanged	N/A	Existing audit model unchanged	This feature changes state meaning, summary wording, and next-action clarity, not the action set
Baseline, restore, evidence, and review surfaces	Existing tenant and workspace governance surfaces inside the bounded first slice	Existing controls unchanged	Existing row or detail inspection unchanged	None added by this feature	None added by this feature	Existing CTA unchanged unless empty-state wording must be corrected	Existing actions unchanged	N/A	Existing audit model unchanged	Shared taxonomy applies to badges, summaries, filters, helper copy, and empty states across the adopted bounded slice
Cross-domain canonical views	Workspace-scoped aggregated views using shared state filters	Existing filters and scope controls unchanged	Existing list inspection unchanged	None added by this feature	None added by this feature	Existing CTA unchanged	Existing actions unchanged	N/A	Existing audit model unchanged	The key requirement is non-member-safe state aggregation and consistent severity meaning

Key Entities (include if feature involves data)

• Operator Outcome Taxonomy: The shared meaning layer that defines state axes, term dictionary, severity rules, and primary-versus-diagnostic presentation rules.
• State Axis: One independent dimension of meaning, such as execution outcome, freshness, coverage, or actionability, that must not be collapsed into a different dimension's label.
• Primary Operator Signal: The first-class label or badge an operator uses to decide whether attention or action is required.
• Diagnostic Detail: Secondary explanatory context that preserves technical precision without replacing the primary operator signal.

Success Criteria (mandatory)

Measurable Outcomes

• SC-156-001: In the defined first-slice adoption set, 100% of adopted primary states map to one declared semantic axis and one shared severity rule.
• SC-156-002: In focused regression coverage, 100% of adopted valid-empty examples render without warning or danger severity.
• SC-156-003: In focused regression coverage, 100% of adopted blocked and partial examples include cause-specific or dimension-specific wording rather than bare overloaded labels.
• SC-156-004: In focused review of 12 curated example cases drawn from operations, evidence or review completeness, baseline snapshots, and restore results, operators can determine whether action is required from the primary state presentation in one inspection step for at least 11 of 12 cases, using the quickstart smoke checklist as the scoring rubric.
• SC-156-005: In focused authorization regression coverage, 100% of taxonomy-backed canonical views suppress unauthorized tenant labels, counts, and filter values.
• SC-156-006: In the first implementation slice, no adopted surface uses product-support or renderer-maturity facts as a primary warning or danger signal.

Assumptions

• Existing badge and presentation infrastructure is stable enough to consume a corrected taxonomy without a full visual-system rewrite.
• Downstream domain follow-up specs will apply this foundation incrementally rather than requiring all product surfaces to migrate in one release.
• Existing reason-code and run-summary work can be aligned to this taxonomy without changing the underlying machine-readable contracts.
• The bounded first slice is limited to operations, evidence or review completeness, baseline snapshot semantics, and restore semantics; broader provider, inventory, onboarding, and verification adoption follows in later specs.

Dependencies

• Existing operator-facing status and badge infrastructure
• Existing operations, baseline, restore, evidence, and review surfaces that will adopt the taxonomy in the bounded first slice
• BADGE-001 and UI naming enforcement work already in flight across the product

Non-Goals

• Redesigning the visual theme or component library
• Refactoring every operator-facing surface in one release
• Changing the underlying business meaning of existing domain records
• Replacing raw diagnostic data with simplified summaries only; diagnostics remain available as secondary detail
• Applying the taxonomy to provider health, onboarding, verification, findings, or inventory beyond shared guard coverage in this first slice

Final Direction

This spec is the strategically first follow-up because it fixes the product-wide meaning system, not a single domain symptom. It establishes one shared operator vocabulary and severity model so later work on reason-code translation, provider preflight states, baseline semantics, restore clarity, and evidence presentation can converge instead of creating new local interpretations.