ahmido
3c3daae405
## 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
156 lines
7.8 KiB
Markdown
156 lines
7.8 KiB
Markdown
# 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.
|