119 lines
5.0 KiB
Markdown
119 lines
5.0 KiB
Markdown
# 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.
|