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

5.0 KiB

Raw Permalink Blame History

Quickstart: Operator Outcome Taxonomy and Cross-Domain State Separation

Goal

Validate and extend the shipped first-slice taxonomy without breaking RBAC, badge centralization, or the existing Ops-UX feedback contract.

Adopted Scope

The current slice covers:

Operations outcomes, notifications, summaries, widgets, and run detail copy
Evidence and tenant-review completeness plus freshness semantics
Baseline fidelity, diagnostic notes, and gap-status presentation
Restore run, preview, item-result, and safety-check semantics
Canonical-view and tenant-context filter labels that now resolve through BadgeCatalog

Curated Example Rubric

Score these 12 cases with a pass or fail for "action required is obvious in one inspection step":

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

Focused Validation Commands

Run all commands through Sail.

vendor/bin/sail artisan test --compact \
    tests/Unit/Badges/OperatorOutcomeTaxonomyTest.php \
    tests/Feature/Guards/NoDiagnosticWarningBadgesTest.php \
    tests/Unit/Badges/OperationRunBadgesTest.php \
    tests/Unit/Evidence/EvidenceSnapshotBadgeTest.php \
    tests/Unit/Support/Badges/BaselineSnapshotRenderingBadgeTest.php \
    tests/Unit/Badges/RestoreRunBadgesTest.php \
    tests/Feature/Notifications/OperationRunNotificationTest.php \
    tests/Feature/Filament/TenantGlobalSearchLifecycleScopeTest.php

Optional broader slice verification:

vendor/bin/sail artisan test --compact \
    tests/Feature/Evidence/EvidenceOverviewPageTest.php \
    tests/Feature/Evidence/EvidenceSnapshotResourceTest.php \
    tests/Feature/TenantReview/TenantReviewRegisterTest.php \
    tests/Feature/TenantReview/TenantReviewUiContractTest.php \
    tests/Unit/TenantReview/TenantReviewBadgeTest.php \
    tests/Unit/Baselines/SnapshotRendering/BaselineSnapshotPresenterTest.php \
    tests/Feature/Filament/BaselineSnapshotFidelityVisibilityTest.php \
    tests/Feature/Filament/SettingsCatalogRestoreApplySettingsPatchTest.php

vendor/bin/sail bin pint --dirty --format agent

Manual Smoke Checklist

`/admin/operations`

Queued runs show Queued for execution.
Blocked runs show Blocked by prerequisite and surface a next step or blocked-prerequisite guidance.
Partial runs show Completed with follow-up, not bare Partial.
Success copy can explicitly say No action needed.

`/admin/monitoring/evidence-overview`

Missing evidence shows Not collected yet, not a failure label.
Stale evidence shows Refresh recommended.
Operations summary language distinguishes execution failures from follow-up states.

`/admin/reviews`

Completeness states show Review input pending, Review inputs incomplete, or Refresh review inputs.
No tenant-review surface uses bare Missing or Stale as the primary operator label.

Baseline detail surfaces

Support limited and fallback notes appear as diagnostic-only detail.
Coverage gaps need review appears only for real coverage gaps.
Diagnostic-only fallback notes do not increment the primary gap count.
Clear baseline groups can show No follow-up needed.

Restore detail surfaces

Safety checks show Fix before running, Review before running, or Ready to continue.
Empty states read No preview has been generated yet. and No restore results have been recorded yet.
Preview actions use Will create, Will create copy, Will map existing, or Will skip.
Item results use Applied, Mapped to existing item, Not applied, Manual follow-up needed, or Apply failed.

Search and scope hardening

Operations, evidence snapshots, baseline snapshots, and tenant reviews remain out of global search.
Canonical summaries, badge counts, and filters only reflect authorized workspace and tenant scope.

Validation Checklist

Operators can distinguish actionable risk from diagnostics on each adopted surface.
Valid-empty states no longer render as failure.
Freshness states no longer render as archival or product-maturity context.
Partial and blocked states are qualified by cause or dimension.
Diagnostic-only baseline states never use warning or danger.
Canonical views do not reveal unauthorized tenant state through taxonomy-backed labels, counts, or filters.
Existing operations notifications still obey the queued, progress, and terminal feedback contract.
At least 11 of the 12 curated example cases make the required operator action obvious in one inspection step.

Rollout Note

Do not migrate unrelated badge domains opportunistically. Keep the slice bounded to operations, evidence and review completeness, baseline semantics, and restore semantics so semantic regressions stay attributable and reversible.

5.0 KiB Raw Permalink Blame History