ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects 1 Releases Wiki Activity
55aef627aa
TenantAtlas/specs/166-finding-governance-health/data-model.md
ahmido 55aef627aa feat: harden finding governance health surfaces (#197) 
## Summary
- harden findings and finding-exception Filament surfaces so workflow state, governance validity, overdue urgency, and next action are operator-first
- add tenant stats widgets, segmented tabs, richer governance warnings, and baseline/dashboard attention propagation for overdue and lapsed governance states
- add Spec 166 artifacts plus regression coverage for findings, badges, baseline summaries, tenantless operation viewer behavior, and critical table standards

## Verification
- `vendor/bin/sail bin pint --dirty --format agent`
- `vendor/bin/sail artisan test --compact`

## Filament Notes
- Livewire v4.0+ compliance: yes, implementation stays on Filament v5 / Livewire v4 APIs only
- Provider registration: unchanged, Laravel 12 panel/provider registration remains in `bootstrap/providers.php`
- Global search: unchanged in this slice; `FindingExceptionResource` stays not globally searchable, no new globally searchable resource was introduced
- Destructive actions: existing revoke/reject/approve/renew/workflow mutations remain capability-gated and confirmation-gated where already defined
- Asset strategy: no new assets added; existing deploy process remains unchanged, including `php artisan filament:assets` when registered assets are used
- Testing plan delivered: findings list/detail, exception register, dashboard attention, baseline summary, badge semantics, and tenantless operation viewer coverage

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #197
2026-03-28 10:11:12 +00:00

6.9 KiB
Raw Blame History

Data Model: Finding Governance Health & Resolution Semantics Surface Hardening

1. Finding

  • Purpose: Tenant-owned issue record that carries workflow lifecycle, severity, due state, ownership, and evidence-backed diagnostic context.
  • Ownership: Tenant-owned (workspace_id + tenant_id already exist).
  • Relevant existing fields:
    • id
    • workspace_id
    • tenant_id
    • finding_type
    • status: new, acknowledged, triaged, in_progress, reopened, resolved, closed, risk_accepted
    • severity
    • owner_user_id
    • assignee_user_id
    • due_at
    • sla_days
    • resolved_at, resolved_reason
    • closed_at, closed_reason, closed_by_user_id
    • reopened_at, triaged_at, in_progress_at
    • current_operation_run_id, baseline_operation_run_id
    • evidence_jsonb
  • Relationships:
    • belongs to Tenant
    • has one current FindingException
    • belongs to owner, assignee, acknowledged-by, and closed-by users
  • Existing invariants preserved:
    • Workflow status remains the source of lifecycle truth.
    • risk_accepted remains a finding workflow state, not proof of healthy governance by itself.
    • Open-status and terminal-status helper behavior does not change in this slice.

2. FindingException

  • Purpose: Tenant-owned governance record that determines whether accepted risk is currently backed by valid, expiring, expired, revoked, rejected, or missing-support governance.
  • Ownership: Tenant-owned (workspace_id + tenant_id already exist).
  • Relevant existing fields:
    • id
    • workspace_id
    • tenant_id
    • finding_id
    • status: pending, active, expiring, expired, rejected, revoked, superseded
    • current_validity_state: valid, expiring, expired, revoked, rejected, missing_support
    • requested_by_user_id
    • owner_user_id
    • approved_by_user_id
    • request_reason, approval_reason, rejection_reason, revocation_reason
    • requested_at, approved_at, rejected_at, revoked_at
    • effective_from, review_due_at, expires_at
    • current_decision_id
    • evidence_summary
  • Relationships:
    • belongs to Finding
    • belongs to requester, owner, approver, and current decision
    • has many decisions and evidence references
  • Existing invariants preserved:
    • Governance validity remains derived from exception state and timing.
    • The exception remains the authoritative source for healthy versus lapsed governance.

3. Derived Surface Projection: Finding Governance Surface State

  • Purpose: Non-persisted operator-facing projection used by findings list, finding detail, exception surfaces, and summary widgets.
  • Derived from:
    • Finding.status
    • Finding.severity
    • Finding.owner_user_id, Finding.assignee_user_id, Finding.due_at
    • linked FindingException
    • FindingRiskGovernanceResolver::resolveFindingState()
    • FindingRiskGovernanceResolver::resolveWarningMessage()
  • Proposed derived fields:
    • workflow_status: current finding status value
    • workflow_family: active, accepted_risk, or historical
    • governance_validity: valid, expiring, expired, revoked, rejected, missing_support, or null
    • governance_attention: healthy, attention_needed, or not_applicable
    • governance_warning: nullable operator-readable warning message
    • due_attention: overdue, due_soon, none
    • ownership_attention: assigned, owner_missing, assignee_missing, or both_missing where relevant
    • resolution_context: nullable secondary text such as no longer observed when derivable
    • primary_next_action: derived operator guidance such as inspect exception, renew governance, review overdue finding, or review historical closure
  • Invariant:
    • This projection is derived only. It must not become a new stored truth or a replacement status enum.

4. Derived Surface Projection: Finding Detail Status Zone

  • Purpose: Non-persisted grouping for the leading zone on finding detail.
  • Derived from:
    • the Finding Governance Surface State
    • existing finding severity and related owner or assignee relationships
    • existing exception owner or approver details when relevant
  • Required visible fields:
    • lifecycle status
    • severity or priority
    • governance validity and warning when applicable
    • owner and assignee context
    • due or SLA urgency
    • next-step guidance
  • Invariant:
    • This zone reorganizes existing truth only; it does not add a new domain layer.

5. Derived Surface Projection: Tenant Governance Attention Summary

  • Purpose: Non-persisted aggregate for dashboard and baseline-compare summary surfaces.
  • Derived from:
    • findings with open or terminal statuses
    • overdue findings in open workflow states
    • accepted-risk findings whose governance projection resolves to expiring, expired, revoked, rejected, or missing-support states
    • existing compare summary state from BaselineCompareStats
  • Proposed aggregate values:
    • overdue_open_findings_count
    • expiring_governance_count
    • lapsed_governance_count
    • active_non_new_findings_count
    • high_severity_active_findings_count
    • healthy_checks fallback only when none of the above require attention
  • Invariant:
    • Summary surfaces remain glance-first and DB-only. They surface operator-critical truth without becoming a new reporting system.

Surface State Families

Finding workflow families

  • active: new, acknowledged, triaged, in_progress, reopened
  • accepted_risk: risk_accepted
  • historical: resolved, closed

Governance-health families

  • healthy: accepted risk with valid governance
  • attention_needed: accepted risk with expiring, expired, revoked, rejected, or missing_support governance
  • not_applicable: active or historical findings without current governance relevance

Urgency families

  • overdue: open finding with due date in the past
  • due_soon: open finding approaching due threshold if current UI supports it
  • none: no immediate due urgency signal

Relationship Rules

  • A finding can exist without an exception.
  • A finding in risk_accepted status without a valid linked exception must project as governance attention, not as healthy accepted risk.
  • A finding outside risk_accepted may still have historical exception context, but workflow lifecycle remains the primary status dimension.
  • Exception surfaces and finding surfaces must render the same governance truth for the same finding or exception combination.

Behavioral Invariants For This Spec

  • No new persisted entity, table, enum, or status family is introduced.
  • resolved and closed remain workflow states and do not gain implicit technical-remediation meaning.
  • Governance validity remains derived from exception truth, not from finding status alone.
  • Summary attention must not count only new findings when overdue or lapsed-governance conditions already exist.