# 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:

1. Operations outcomes, notifications, summaries, widgets, and run detail copy
2. Evidence and tenant-review completeness plus freshness semantics
3. Baseline fidelity, diagnostic notes, and gap-status presentation
4. Restore run, preview, item-result, and safety-check semantics
5. 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":

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

## Focused Validation Commands

Run all commands through Sail.

```bash
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:

```bash
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.