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
151 lines
7.3 KiB
Markdown
151 lines
7.3 KiB
Markdown
# Data Model: Operator Outcome Taxonomy and Cross-Domain State Separation
|
|
|
|
This feature defines a shared semantic model rather than introducing a new business-domain table. The model below captures the entities that the implementation and guard coverage must agree on.
|
|
|
|
## Entities
|
|
|
|
### SemanticAxis
|
|
|
|
Represents one independent meaning dimension that operator-facing state is allowed to communicate.
|
|
|
|
**Fields**:
|
|
- `key` (string): stable identifier such as `execution_outcome`, `freshness`, or `product_support_maturity`
|
|
- `label` (string): human-readable axis name used in documentation
|
|
- `definition` (string): the exact semantic question this axis answers
|
|
- `allowedValues` (list<string>): canonical operator-facing values allowed on this axis
|
|
- `defaultPresentationLevel` (enum): `primary` or `diagnostic`
|
|
- `nextActionRequired` (bool): whether non-green states on this axis must always carry action guidance
|
|
|
|
**Validation rules**:
|
|
- Each operator-facing primary state belongs to exactly one axis.
|
|
- Different axes must not be flattened into one unqualified label.
|
|
- Diagnostic-only axes cannot use warning or danger as their default severity.
|
|
|
|
### TaxonomyTerm
|
|
|
|
Represents one canonical operator-facing term or phrase permitted by the taxonomy.
|
|
|
|
**Fields**:
|
|
- `term` (string): canonical label shown to operators
|
|
- `axisKey` (string): owning semantic axis
|
|
- `replaces` (list<string>): overloaded legacy terms or synonyms that must migrate away
|
|
- `requiresQualifier` (bool): whether the term must include a qualifier such as count, cause, or dimension
|
|
- `notes` (string): usage guidance and example contexts
|
|
|
|
**Validation rules**:
|
|
- A canonical term must have one meaning only.
|
|
- A term marked `requiresQualifier` is invalid when used bare.
|
|
- Legacy overloaded terms such as `Partial`, `Blocked`, `Missing`, and `Unsupported` must map to one or more canonical replacements.
|
|
|
|
### SeverityRule
|
|
|
|
Represents the shared meaning of severity colors and tones.
|
|
|
|
**Fields**:
|
|
- `severity` (enum): `danger`, `warning`, `info`, `success`, `gray`, `primary`
|
|
- `meaning` (string): semantic meaning of the severity across the product
|
|
- `allowedAxes` (list<string>): axes where this severity is allowed as a primary state
|
|
- `forbiddenAxes` (list<string>): axes where this severity must not be used
|
|
- `operatorExpectation` (string): what the operator should infer from seeing the severity
|
|
|
|
**Validation rules**:
|
|
- `danger` is reserved for execution failure, governance violation, or material risk.
|
|
- `warning` is reserved for action-recommended or mixed-outcome primary states.
|
|
- `gray` is reserved for neutral, archived, not applicable, or explicitly non-actionable context.
|
|
- Diagnostic-only states must not use `danger` or `warning`.
|
|
|
|
### PresentationClassification
|
|
|
|
Represents whether a state belongs in the operator's primary view or in diagnostics.
|
|
|
|
**Fields**:
|
|
- `level` (enum): `primary` or `diagnostic`
|
|
- `actionability` (enum): `action_required`, `action_recommended`, `no_action_needed`, `context_only`
|
|
- `explanationRequired` (bool): whether helper text or a next-step reference is mandatory
|
|
- `supportsRawDetails` (bool): whether raw technical detail may be shown as secondary detail
|
|
|
|
**Validation rules**:
|
|
- Every non-green, non-gray primary state requires explanation or an explicit no-action-needed note.
|
|
- Diagnostic classification never replaces the primary state for a surface that already exposes a primary state.
|
|
|
|
### TaxonomyEntry
|
|
|
|
Represents the complete classification of one raw domain state into taxonomy semantics.
|
|
|
|
**Fields**:
|
|
- `domain` (string): source domain such as `operation_run_outcome` or `evidence_completeness`
|
|
- `rawValue` (string): existing enum value or normalized source state
|
|
- `axisKey` (string): owning semantic axis
|
|
- `primaryLabel` (string): operator-facing label to render
|
|
- `severity` (enum): resolved severity band
|
|
- `classificationLevel` (enum): `primary` or `diagnostic`
|
|
- `legacyAliases` (list<string>): prior labels that must stop being used
|
|
- `nextActionPolicy` (enum): `required`, `optional`, `none`
|
|
- `diagnosticLabel` (optional string): secondary label for detailed views
|
|
- `notes` (string): human explanation of why the mapping exists
|
|
|
|
**Validation rules**:
|
|
- Every adopted raw state must have exactly one taxonomy entry.
|
|
- `classificationLevel = diagnostic` forbids `severity = warning|danger`.
|
|
- `nextActionPolicy = required` must be set for non-green, non-gray primary states.
|
|
|
|
### AdoptionTarget
|
|
|
|
Represents a bounded surface or domain family included in the first implementation slice.
|
|
|
|
**Fields**:
|
|
- `key` (string): stable target identifier
|
|
- `family` (enum): `operations`, `baselines`, `restore`, `evidence`, `reviews`, `inventory_provider`, `verification`
|
|
- `sourceArtifacts` (list<string>): enums, badge mappers, presenters, or views currently using overloaded semantics
|
|
- `surfaceTypes` (list<string>): examples such as `table`, `infolist`, `notification`, `widget`, `helper_copy`
|
|
- `priority` (enum): `P0`, `P1`, `P2`
|
|
- `rolloutStage` (int): ordered implementation stage
|
|
|
|
**Validation rules**:
|
|
- The first slice must include operations, baselines, restore, and at least one additional family.
|
|
- Each target must identify both shared-code adoption points and user-visible surfaces.
|
|
|
|
### RegressionGuardCase
|
|
|
|
Represents one reusable guard or regression test category enforcing the taxonomy.
|
|
|
|
**Fields**:
|
|
- `name` (string): guard case identifier
|
|
- `assertion` (string): invariant being enforced
|
|
- `scope` (enum): `unit`, `feature`, `architecture`
|
|
- `coversAxes` (list<string>): axes touched by the case
|
|
- `failureSignal` (string): what should cause CI to fail
|
|
|
|
**Validation rules**:
|
|
- The first slice must include guards for diagnostic severity misuse, valid-empty misclassification, freshness severity misuse, unqualified partial or blocked labels, and cross-tenant leakage in canonical views.
|
|
|
|
## Relationships
|
|
|
|
- `SemanticAxis` 1-to-many `TaxonomyTerm`
|
|
- `SemanticAxis` 1-to-many `SeverityRule` by allowed or forbidden usage
|
|
- `TaxonomyEntry` belongs to one `SemanticAxis`
|
|
- `TaxonomyEntry` belongs to one `PresentationClassification`
|
|
- `AdoptionTarget` consumes many `TaxonomyEntry` mappings
|
|
- `RegressionGuardCase` validates many `TaxonomyEntry` and `AdoptionTarget` combinations
|
|
|
|
## Initial First-Slice Adoption Set
|
|
|
|
### Operations
|
|
- Source artifacts: `OperationRunOutcomeBadge`, `OperationUxPresenter`, `SummaryCountsNormalizer`, operation notifications
|
|
- Primary axes involved: `execution_outcome`, `operator_actionability`
|
|
|
|
### Baseline snapshot semantics
|
|
- Source artifacts: `FidelityState`, `GapSummary`, `BaselineSnapshotFidelityBadge`, `BaselineSnapshotGapStatusBadge`
|
|
- Primary axes involved: `evidence_depth`, `data_coverage`, `product_support_maturity`
|
|
|
|
### Restore semantics
|
|
- Source artifacts: `RestoreRunStatusBadge`, `RestoreResultStatusBadge`, `RestorePreviewDecisionBadge`, `RestoreCheckSeverityBadge`
|
|
- Primary axes involved: `execution_lifecycle`, `item_result`, `operator_actionability`
|
|
|
|
### Evidence and review completeness
|
|
- Source artifacts: `EvidenceCompletenessState`, `TenantReviewCompletenessState`, their badge mappers, canonical review surfaces
|
|
- Primary axes involved: `data_coverage`, `data_freshness`
|
|
|
|
### Inventory or provider operability
|
|
- Source artifacts: `InventoryKpiBadges`, `PolicySnapshotModeBadge`, `ProviderConnectionStatusBadge`, `ProviderConnectionHealthBadge`, verification status helpers
|
|
- Primary axes involved: `product_support_maturity`, `operator_actionability`, `freshness` |