ahmido 3c3daae405 feat: normalize operator outcome taxonomy (#186 )

## Summary
- introduce a shared operator outcome taxonomy with semantic axes, severity bands, and next-action policy
- apply the taxonomy to operations, evidence/review completeness, baseline semantics, and restore semantics
- harden badge rendering, tenant-safe filtering/search behavior, and operator-facing summary/notification wording
- add the spec kit artifacts, reference documentation, and regression coverage for diagnostic-vs-primary state handling

## Testing
- focused Pest coverage for taxonomy registry and badge guardrails
- operations presentation and notification tests
- evidence, baseline, restore, and tenant-scope regression tests

## Notes
- Livewire v4.0+ compliance is preserved in the existing Filament v5 stack
- panel provider registration remains unchanged in bootstrap/providers.php
- no new globally searchable resource was added; adopted resources remain tenant-safe and out of global search where required
- no new destructive action family was introduced; existing actions keep their current authorization and confirmation behavior
- no new frontend asset strategy was introduced; existing deploy flow with filament:assets remains unchanged

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #186

2026-03-22 12:13:34 +00:00

7.8 KiB

Raw Blame History

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

One primary label means one thing everywhere it appears.
Semantic axes stay separate. Execution outcome, coverage, freshness, evidence depth, and actionability are not interchangeable.
Diagnostic-only states never use warning or danger.
Primary warning and danger states must carry an operator next-action policy.
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:

Operation blocked by missing prerequisite
Operation completed with follow-up
Operation completed successfully
Evidence not collected yet
Evidence refresh recommended
Review input pending
Mixed evidence detail stays diagnostic
Support limited stays diagnostic
Coverage gaps need review
Restore preview blocked by a check
Restore run applied with follow-up
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.

7.8 KiB Raw Blame History