TenantAtlas/specs/156-operator-outcome-taxonomy/plan.md

Implementation Plan: Operator Outcome Taxonomy and Cross-Domain State Separation

Branch: 156-operator-outcome-taxonomy | Date: 2026-03-21 | Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/156-operator-outcome-taxonomy/spec.md Input: Feature specification from /specs/156-operator-outcome-taxonomy/spec.md

Note: This template is filled in by the /speckit.plan command. See .specify/scripts/ for helper scripts.

Summary

Establish one shared operator outcome taxonomy that separates semantic axes, defines a canonical term dictionary and severity rules, classifies primary versus diagnostic state, and applies that foundation to a bounded first-slice adoption set. The implementation should leave the existing badge and Filament plumbing intact, add only minimal shared enforcement at the BadgeSpec and BadgeRenderer boundary, publish a canonical reference document for downstream specs, and migrate the highest-noise cross-domain states first: operations, baselines, restore, and one additional state family with valid-empty and freshness pressure.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12, Filament v5, Livewire v4, PostgreSQL, Laravel Sail, Pest v4
Storage: PostgreSQL-backed existing domain records; no new business-domain table is required for the first slice; shared taxonomy reference will live in repository documentation and code-level metadata
Testing: Pest feature tests, unit tests for badge contracts and taxonomy guards, existing architectural guard tests, focused Livewire or Filament surface tests where list/detail presentation is asserted
Target Platform: Laravel web application running locally via Sail and deployed via Dokploy
Project Type: Web application
Performance Goals: No render-time external calls; no material regression to list/detail render paths; taxonomy lookup remains constant-time and cacheable through existing badge infrastructure; Monitoring and other canonical views remain DB-only at render time
Constraints: Preserve BADGE-001 centralization, preserve RBAC 404 versus 403 semantics, avoid broad visual-system rewrites, keep domain-specific enum and DTO churn bounded to the first-slice adoption set, and do not introduce ad-hoc page-local labels as part of the rollout
Scale/Scope: Foundation spec plus first-slice adoption across operations, baseline snapshot semantics, restore semantics, and evidence or review completeness as the additional valid-empty and freshness pressure domain

Filament v5 Implementation Notes

• Livewire v4.0+ compliance: Maintained. This work changes operator-facing semantics in the existing Filament v5 + Livewire v4 stack and introduces no incompatible Livewire pattern.
• Provider registration location: No new panel is introduced. Existing panel providers remain registered in bootstrap/providers.php.
• Global search rule: No new globally searchable resource is added. Existing search behavior must stay tenant-safe when shared taxonomy-backed labels appear in canonical and tenant-context views.
• Destructive actions: No new destructive action family is introduced by the foundation itself. Existing destructive actions on adopted surfaces remain confirmation-protected and capability-gated.
• Asset strategy: No new global or on-demand assets are planned. Deployment remains unchanged, including php artisan filament:assets where already part of the deploy process.
• Testing plan: Add Pest coverage for taxonomy registry validity, badge severity guardrails, valid-empty and freshness classifications, cross-tenant non-leakage on canonical views, and focused assertion coverage on the first-slice adopted surfaces.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

• Inventory-first: PASS. The feature changes operator-facing semantics only; it does not alter inventory versus snapshot ownership rules.
• Read/write separation: PASS. The foundation introduces no new write flow. Existing mutations on adopted surfaces remain preview-, confirmation-, and audit-governed by their owning specs.
• Graph contract path: PASS. No new Graph calls or contract-registry changes are introduced.
• Deterministic capabilities: PASS. Capability derivation remains unchanged and must continue to gate adopted surfaces server-side.
• RBAC-UX plane separation: PASS. The adoption set spans tenant-context and canonical workspace views while preserving 404 for non-members and 403 for in-scope capability denial.
• Workspace isolation: PASS. Shared taxonomy-backed labels, counts, and filter chips must be computed only from entitled workspace scope.
• Tenant isolation: PASS. Cross-tenant aggregation remains explicit and access-checked. Shared severity rules must not leak unauthorized tenant state.
• Destructive confirmation standard: PASS. No destructive semantics are weakened by this feature.
• Global search tenant safety: PASS WITH WORK. Taxonomy-backed labels must not surface inaccessible results or hint text; focused regression coverage is required.
• Run observability: PASS. Existing OperationRun usage remains canonical. This feature only changes how outcomes and summaries are interpreted and rendered.
• Ops-UX 3-surface feedback: PASS WITH WORK. Notification and summary wording for adopted operation states must stay within the existing toast/progress/terminal contract.
• Ops-UX lifecycle: PASS. OperationRun.status and OperationRun.outcome stay service-owned; this feature only changes presentation and translation rules.
• Ops-UX summary counts: PASS WITH WORK. SummaryCountsNormalizer already humanizes keys, but first-slice taxonomy rules must make operator-facing summary language clearer without changing the numeric contract.
• Ops-UX guards: PASS WITH WORK. Add guard coverage so diagnostic-only states cannot be rendered with warning or danger severity through badge mappings.
• Ops-UX system runs: PASS. No change to initiator-null notification semantics.
• Automation: PASS. No queue or retry contract changes.
• Data minimization: PASS. This feature should reduce operator exposure to raw internal reason strings by pushing them into diagnostics.
• Badge semantics (BADGE-001): PASS WITH WORK. This feature is the foundation slice that codifies badge meaning and must preserve centralization through BadgeCatalog and BadgeRenderer.
• UI naming (UI-NAMING-001): PASS WITH WORK. The taxonomy becomes the reference for consistent operator-facing state terms across badges, summaries, notifications, and helper copy.
• Filament UI Action Surface Contract: PASS. Existing action surfaces remain structurally intact; the rollout changes state meaning and helper copy rather than action topology.
• Filament UI UX-001: PASS WITH WORK. Adopted empty states, badges, and summary sections must align with the taxonomy, especially for valid-empty and freshness cases.

Phase 0 Gate Result: PASS

• The feature is bounded to semantic normalization and first-slice adoption, not broad infrastructure replacement.
• Existing badge plumbing is reusable, which keeps the foundation shippable.
• The largest risk is semantic drift during the bounded first-slice adoption set, not architecture viability.

Project Structure

Documentation (this feature)

specs/156-operator-outcome-taxonomy/
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
│   ├── operator-state-presentation.logical.openapi.yaml
│   └── operator-taxonomy-entry.schema.json
└── tasks.md

Source Code (repository root)

app/
├── Filament/
│   ├── Pages/
│   │   └── Reviews/
│   ├── Resources/
│   └── Widgets/
│       ├── Dashboard/
│       └── Tenant/
├── Notifications/
├── Services/
│   ├── Baselines/
│   │   └── SnapshotRendering/
│   └── Onboarding/
├── Support/
│   ├── Badges/
│   │   └── Domains/
│   ├── Evidence/
│   ├── Inventory/
│   ├── OpsUx/
│   └── Verification/
└── Models/

docs/
├── audits/
├── product/
└── ui/

resources/
└── views/
    └── filament/

tests/
├── Feature/
├── Unit/
└── Architecture/

Structure Decision: Use the existing Laravel web application structure. The foundation artifacts live under specs/156-operator-outcome-taxonomy/, while the planned implementation targets are concentrated in app/Support/Badges, app/Support/OpsUx, app/Services/Baselines/SnapshotRendering, app/Support/Evidence, the restore badge and Filament surface files for the bounded slice, and focused Pest coverage under tests/Feature, tests/Unit, and existing guard-oriented suites.

Phase 0 — Research (complete)

• Output: specs/156-operator-outcome-taxonomy/research.md
• Resolved key decisions:
  • Keep BadgeCatalog and BadgeRenderer as the canonical rendering plumbing; fix taxonomy input, not the rendering layer itself.
  • Publish the shared reference document under docs/product/operator-semantic-taxonomy.md so roadmap and downstream specs can reference one canonical source.
  • Add only minimal shared enforcement in the foundation slice: BadgeSpec and badge contract metadata may gain diagnostic-boundary semantics, but wide domain rewrites stay bounded to the first-slice adoption set.
  • First-slice adoption order is operations outcome wording, evidence and review completeness semantics, baseline snapshot semantics, and restore semantics.
  • Guard coverage must assert that diagnostic-only states cannot ship with warning or danger severity.

Phase 1 — Design & Contracts (complete)

• Output: data-model.md defines the semantic-axis, term, severity, classification, and adoption-target model used by the implementation.
• Output: contracts/operator-state-presentation.logical.openapi.yaml captures the logical resolution contract between raw domain state, taxonomy lookup, and operator-facing state presentation.
• Output: contracts/operator-taxonomy-entry.schema.json defines the shape of one taxonomy entry and its severity and diagnostic constraints.
• Output: quickstart.md documents implementation order, reference-document creation, and focused validation commands.

Post-design Constitution Re-check

• PASS: No new panel, route family, Graph path, or business-domain store is introduced.
• PASS: The design preserves Filament v5 + Livewire v4 and keeps provider registration unchanged in bootstrap/providers.php.
• PASS WITH WORK: The first-slice adoption set touches high-noise domains, so rollout must remain staged and test-backed to avoid semantic churn.
• PASS WITH WORK: Operations notifications and summary lines need focused validation so the taxonomy improves wording without violating the existing Ops-UX contract.
• PASS WITH WORK: Canonical views and tenant-context views need explicit non-member regression coverage because shared labels and filter chips are part of the leak surface.

Phase 2 — Implementation Planning

tasks.md should cover:

• Publishing the canonical reference document at docs/product/operator-semantic-taxonomy.md with semantic axes, term dictionary, severity rules, diagnostic boundary, and next-action policy.
• Extending shared badge contracts so taxonomy metadata can distinguish primary versus diagnostic states and can reject warning or danger severity for diagnostic-only values.
• Aligning operations outcome presentation: OperationRunOutcome badge mapping, OperationUxPresenter, SummaryCountsNormalizer, and notification wording.
• Aligning valid-empty and freshness semantics in EvidenceCompletenessState and TenantReviewCompletenessState, including badge, empty-state, and canonical view updates.
• Aligning baseline snapshot fidelity and gap presentation so product-support tier becomes diagnostic and true coverage problems remain primary.
• Aligning restore run, item, and preview semantics so partial, blocked, manual, and dry-run states are axis-specific and action-oriented.
• Adding explicit tenant-safe global-search and authorization regression coverage for taxonomy-backed labels, counts, and filters on adopted canonical and tenant-context surfaces.
• Adding Pest guard tests that fail when diagnostic-only taxonomy values map to warning or danger badges.
• Adding positive and negative authorization regression coverage for canonical views that adopt taxonomy-backed labels, counts, and filters.

Contract Implementation Note

• The OpenAPI file is logical, not transport-prescriptive. It documents how existing Filament, presenter, and notification flows should resolve raw state into operator-facing state.
• The JSON schema is documentation-first and guard-friendly. It can be enforced through curated fixtures, unit tests, or static registry declarations rather than a new runtime parser in the first slice.
• The preferred rollout is to add taxonomy metadata centrally and then migrate first-slice domains to consume it, rather than pushing page-local label overrides.

Deployment Sequencing Note

• No migration is expected in the foundation slice.
• No asset publish change is expected.
• Rollout should start with the reference document and shared badge contract, then the operations adoption slice, then evidence and review completeness semantics, then baseline semantics, then restore semantics, with each stop point guarded before broadening the slice.

Story Delivery Note

• User Stories 1 and 2 are both P1. The executable delivery order should start with User Story 2 because operations are the proving ground for the shared actionability vocabulary, then continue with User Story 1 for valid-empty and diagnostic-boundary cleanup, and finish with User Story 3 for restore convergence plus cross-view safety hardening.
• Provider, inventory, onboarding, verification, and finding-specific vocabulary changes remain out of the first implementation slice unless required only for shared guard coverage.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
None	Not applicable	Not applicable