TenantAtlas/specs/166-finding-governance-health/plan.md

Implementation Plan: Finding Governance Health & Resolution Semantics Surface Hardening

Branch: 166-finding-governance-health | Date: 2026-03-27 | Spec: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/166-finding-governance-health/spec.md Input: Feature specification from /specs/166-finding-governance-health/spec.md

Summary

Harden findings, exception, and tenant-summary surfaces so operators can quickly distinguish active findings, accepted risk with healthy governance, accepted risk with governance attention needed, historical resolved or closed workflow states, and overdue work. The implementation stays deliberately narrow: it reuses existing Finding, FindingException, FindingRiskGovernanceResolver, centralized badge and filter catalogs, and current Filament surfaces rather than adding schema, new status families, or a presenter framework.

The work is primarily surface hardening across the tenant findings list, finding detail, tenant exception register, canonical exception queue, tenant dashboard attention widget, and baseline-compare summary surfaces. The design keeps workflow lifecycle and governance validity as separate visible dimensions, promotes due and ownership urgency ahead of diagnostics, and adds cross-surface tests that enforce semantic consistency.

Technical Context

Language/Version: PHP 8.4.15
Primary Dependencies: Laravel 12, Filament v5, Livewire v4, Pest v4, Tailwind CSS v4, existing Finding, FindingException, FindingRiskGovernanceResolver, BadgeCatalog, BadgeRenderer, FilterOptionCatalog, and tenant dashboard widgets
Storage: PostgreSQL using existing findings, finding_exceptions, related decision tables, and existing DB-backed summary sources; no schema changes required
Testing: Pest feature tests, Pest unit tests, and Livewire or Filament component tests
Target Platform: Laravel Sail web application on PostgreSQL Project Type: Web application monolith
Performance Goals: Findings list, exception list, dashboard widgets, and baseline-compare summary remain DB-only at render time; added governance cues must preserve scan-first list behavior and avoid disproportionate query cost; no new background processing is introduced
Constraints: No new schema or enum; no new Microsoft Graph calls; no new OperationRun; no competing governance truth; destructive actions keep existing confirmation and audit behavior; tenant and workspace isolation semantics must remain unchanged; avoid new presenter or semantic-framework layers
Scale/Scope: One tenant findings resource, one finding detail, one tenant exception register, one canonical exception queue, one tenant attention widget, and one baseline-compare summary surface, plus shared badge, filter, and resolver semantics with focused regression coverage

Constitution Check

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

• Pre-Phase-0 Gate: PASS
• Inventory-first: PASS. The feature changes how existing findings and exception truth is surfaced; it does not redefine inventory, snapshots, or backup truth.
• Read/write separation: PASS. Existing writes stay unchanged and confirmation-gated where already required; this slice is mostly read-surface hardening.
• Graph contract path: PASS. No Graph calls are introduced.
• Deterministic capabilities: PASS. Existing capability registry and RBAC helpers remain the sole authorization source.
• RBAC-UX / workspace / tenant isolation: PASS. Tenant findings and exception surfaces remain tenant-scoped, canonical queue remains entitlement-filtered, non-members remain 404, and in-scope capability denials remain 403.
• Global search: PASS. This slice does not expand global-search exposure.
• Run observability: PASS by non-applicability. No new long-running or remote work is introduced.
• Ops-UX 3-surface feedback: PASS by non-applicability. No new OperationRun flow is added.
• Data minimization: PASS. Surface hardening reuses current DB-backed truth and does not add new stored payloads.
• Proportionality / no premature abstraction / persisted truth / state / UI semantics / few layers: PASS. The feature explicitly avoids new persistence, new state families, and a new semantic framework. The narrow implementation is to tighten existing list, detail, queue, and summary mappings.
• BADGE-001: PASS. The plan reuses existing centralized badge domains for finding status, severity, exception status, and governance validity.
• UI-FIL-001: PASS. Native Filament resources, infolists, tables, widgets, and existing shared primitives remain the implementation path.
• UI-NAMING-001: PASS. The work sharpens existing operator language instead of inventing new labels.
• OPSURF-001: PASS. The plan explicitly separates workflow lifecycle, governance validity, and due urgency, and keeps diagnostics secondary.
• Filament UI Action Surface Contract: PASS. Existing inspection affordances and action groups remain; the main change is semantic emphasis, not new mutation inventory.
• Filament UI UX-001: PASS. The design promotes a clearer leading status zone on view pages, retains searchable and filterable tables, and keeps summary widgets scan-first.

Post-Phase-1 Re-check: PASS

• The design introduces no new stored truth, no new resolver layer, and no new status family.
• All proposed contracts and data models remain derived from existing Finding, FindingException, centralized badge semantics, and current tenant or workspace queries.
• The testing strategy protects business truth across findings list, finding detail, exception surfaces, and summary widgets instead of snapshotting a new presentation framework.

Project Structure

Documentation (this feature)

specs/166-finding-governance-health/
├── checklists/
│   └── requirements.md
├── spec.md
├── plan.md
├── research.md
├── data-model.md
├── quickstart.md
├── contracts/
└── tasks.md

Source Code (repository root)

app/
├── Filament/
│   ├── Pages/
│   │   ├── Monitoring/
│   │   └── TenantDashboard.php
│   ├── Resources/
│   │   ├── FindingResource.php
│   │   ├── FindingResource/
│   │   └── FindingExceptionResource/
│   └── Widgets/
│       ├── Dashboard/
│       ├── Tenant/
│       └── Workspace/
├── Models/
├── Services/
│   └── Findings/
└── Support/
    ├── Badges/
    └── Filament/

resources/
└── views/
    └── filament/
        ├── pages/
        └── widgets/

tests/
├── Feature/
│   ├── Findings/
│   ├── Filament/
│   ├── Authorization/
│   └── Evidence/
└── Unit/
    └── Badges/

Structure Decision: Keep the existing Laravel monolith structure. The implementation should stay inside the current findings and exception resources, current dashboard and baseline-compare surfaces, the existing findings governance resolver, and centralized badge or filter helpers. Regression coverage should extend current Findings, Filament, Authorization, Evidence, and Badge test suites rather than creating a new surface framework or test package.

Complexity Tracking

No constitution violations require justification. The plan intentionally avoids adding persistence, new abstractions, or new state families.

Implementation confirmation (2026-03-27): delivery stayed within the planned narrow slice. No additional semantic gap was discovered that would require a new resolver layer, persistence field, or extra follow-up spec beyond the already documented resolution-origin candidate.

Phase 0 — Research Output

• research.md

Phase 1 — Design Output

• data-model.md
• quickstart.md
• contracts/finding-governance-health.openapi.yaml

Phase 2 — Implementation Planning

The implementation task plan covers these execution slices:

1. Findings list hardening so lifecycle state, governance validity, overdue urgency, and ownership become scan-first without degrading filterability or list density.
2. Finding detail restructuring so an operator-first status and governance zone appears above diagnostics, and resolved or closed copy becomes semantically cautious.
3. Exception-surface alignment so tenant register and canonical queue carry the same healthy versus attention-needed governance signals as finding surfaces.
4. Tenant-summary propagation so NeedsAttention, BaselineCompareNow, and baseline-compare landing surfaces include overdue and unhealthy governance truth instead of relying only on new findings.
5. Shared semantics tightening so FindingRiskGovernanceResolver, BadgeCatalog, BadgeRenderer, and FilterOptionCatalog remain the sole truth sources for status and governance vocabulary.
6. Cross-surface regression coverage spanning findings list, finding detail, exception register, canonical queue, dashboard attention, baseline-compare summary, and badge-domain semantics.