ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
a74ab12f04
TenantAtlas/specs/153-evidence-domain-foundation/tasks.md
ahmido a74ab12f04 feat: implement evidence domain foundation (#183) 
## Summary
- add the Evidence Snapshot domain with immutable tenant-scoped snapshots, per-dimension items, queued generation, audit actions, badge mappings, and Filament list/detail surfaces
- add the workspace evidence overview, capability and policy wiring, Livewire update-path hardening, and review-pack integration through explicit evidence snapshot resolution
- add spec 153 artifacts, migrations, factories, and focused Pest coverage for evidence, review-pack reuse, authorization, action-surface regressions, and audit behavior

## Testing
- `vendor/bin/sail artisan test --compact --stop-on-failure`
- `CI=1 vendor/bin/sail artisan test --compact`
- `vendor/bin/sail bin pint --dirty --format agent`

## Notes
- branch: `153-evidence-domain-foundation`
- commit: `b7dfa279`
- spec: `specs/153-evidence-domain-foundation/`

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #183
2026-03-19 13:32:52 +00:00

19 KiB
Raw Blame History

Tasks: Evidence Domain Foundation

Input: Design documents from /specs/153-evidence-domain-foundation/ Prerequisites: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/, quickstart.md

Tests: Tests are REQUIRED for this feature because it changes runtime data modeling, queued operations, tenant/workspace authorization, downstream review-pack behavior, and Filament evidence surfaces in a Laravel/Pest codebase. Operations: This feature introduces a new queued OperationRun family for evidence snapshot generation. Tasks below keep OperationRun.status and OperationRun.outcome service-owned via OperationRunService, preserve initiator-only terminal notifications, keep live progress limited to the active-ops widget and Monitoring run detail, and ensure summary_counts remain flat numeric values using canonical keys only. RBAC: This feature changes authorization in tenant-context admin surfaces and a workspace-scoped Monitoring overview. Tasks below preserve 404 for non-members or non-entitled actors, 403 for in-scope capability denials, canonical capability-registry usage, confirmed destructive expiration actions, and explicit downstream resolver authorization. UI Naming: Operator-facing copy must stay aligned to Create snapshot, Refresh evidence, View snapshot, and Expire snapshot across actions, run titles, notifications, and audit prose. Filament UI Action Surfaces: This feature adds a tenant evidence resource and a workspace evidence overview page. Tasks below enforce clickable-row inspection, no lone View row action, confirmed destructive actions, empty-state CTA behavior, and Action Surface contract coverage. Filament UI UX-001: Snapshot detail must use an Infolist-style inspection surface. Snapshot creation remains a modal action exemption rather than a CRUD create page. Badges: Snapshot status and completeness state must use centralized badge semantics via BadgeCatalog and BadgeRenderer, with mapping tests for every introduced value. Contract Artifacts: /Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/153-evidence-domain-foundation/contracts/evidence-domain.openapi.yaml is an internal planning contract that must stay aligned with the implemented resource, page, and downstream resolver behavior.

Organization: Tasks are grouped by user story so each story can be implemented and tested independently.

Phase 1: Setup (Shared Infrastructure)

Purpose: Prepare the evidence-domain test targets and implementation scaffolding used across all stories.

  • T001 [P] Create the feature-test skeletons for evidence list/detail, overview, job behavior, and audit coverage in tests/Feature/Evidence/EvidenceSnapshotResourceTest.php, tests/Feature/Evidence/EvidenceOverviewPageTest.php, tests/Feature/Evidence/GenerateEvidenceSnapshotJobTest.php, and tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php
  • T002 [P] Create the unit-test skeletons for fingerprinting, completeness, and resolver behavior in tests/Unit/Evidence/EvidenceSnapshotFingerprintTest.php, tests/Unit/Evidence/EvidenceCompletenessEvaluatorTest.php, tests/Unit/Evidence/EvidenceSnapshotResolverTest.php, and tests/Unit/Evidence/EvidenceSnapshotBadgeTest.php
  • T003 [P] Create the evidence-domain scaffolding stubs in app/Models/EvidenceSnapshot.php, app/Models/EvidenceSnapshotItem.php, app/Jobs/GenerateEvidenceSnapshotJob.php, app/Services/Evidence/EvidenceSnapshotService.php, and app/Services/Evidence/EvidenceSnapshotResolver.php

Phase 2: Foundational (Blocking Prerequisites)

Purpose: Establish the shared schema, domain types, resolver contracts, and operation/audit seams required before any user story work starts.

⚠️ CRITICAL: No user story work should begin until this phase is complete.

  • T004 Create the evidence snapshot schema and indexes in database/migrations/2026_03_19_000000_create_evidence_snapshots_table.php and database/migrations/2026_03_19_000001_create_evidence_snapshot_items_table.php
  • T005 Implement the root and child snapshot models, relationships, casts, and tenant/workspace scopes in app/Models/EvidenceSnapshot.php and app/Models/EvidenceSnapshotItem.php
  • T006 [P] Add evidence status and completeness domain types plus centralized badge mappings in app/Support/Evidence/EvidenceSnapshotStatus.php, app/Support/Evidence/EvidenceCompletenessState.php, app/Support/Badges/Domains/EvidenceSnapshotStatusBadge.php, and app/Support/Badges/Domains/EvidenceCompletenessBadge.php
  • T007 [P] Register the new evidence capabilities, operation-run type, and audit action ids in app/Support/Auth/Capabilities.php, app/Support/OperationRunType.php, and app/Support/Audit/AuditActionId.php
  • T008 [P] Implement the reusable fingerprinting, completeness-evaluation, and resolution DTO contracts in app/Services/Evidence/EvidenceSnapshotFingerprint.php, app/Services/Evidence/EvidenceCompletenessEvaluator.php, app/Services/Evidence/EvidenceResolutionRequest.php, and app/Services/Evidence/EvidenceResolutionResult.php
  • T009 [P] Define the first-slice evidence-source contract and collector classes, including the explicit operations_summary rollup scope, in app/Services/Evidence/Contracts/EvidenceSourceProvider.php, app/Services/Evidence/Sources/FindingsSummarySource.php, app/Services/Evidence/Sources/PermissionPostureSource.php, app/Services/Evidence/Sources/EntraAdminRolesSource.php, app/Services/Evidence/Sources/BaselineDriftPostureSource.php, and app/Services/Evidence/Sources/OperationsSummarySource.php
  • T010 Implement the service-owned orchestration seam for snapshot generation and expiration in app/Services/Evidence/EvidenceSnapshotService.php and app/Jobs/GenerateEvidenceSnapshotJob.php

Checkpoint: Foundation ready. The repo now has the evidence schema, domain types, source-collector seams, and queued-operation/audit entrypoints needed for all user stories.

Phase 3: User Story 1 - Create an immutable evidence snapshot (Priority: P1) 🎯 MVP

Goal: Let an authorized operator create one immutable, reproducible evidence snapshot for a tenant and inspect it later without live-source drift changing the captured truth.

Independent Test: Generate a snapshot from existing findings and reports, change the live source records afterward, and confirm the original snapshot remains unchanged while repeat requests reuse or supersede snapshots according to fingerprint state.

Tests for User Story 1

  • T011 [P] [US1] Add fingerprint reuse, supersede, and immutability coverage in tests/Feature/Evidence/GenerateEvidenceSnapshotJobTest.php and tests/Unit/Evidence/EvidenceSnapshotFingerprintTest.php
  • T012 [P] [US1] Add tenant evidence authorization and 404 versus 403 coverage in tests/Feature/Evidence/EvidenceSnapshotResourceTest.php and tests/Feature/ManagedTenants/AuthorizationSemanticsTest.php
  • T013 [P] [US1] Add action-surface and Ops-UX regression coverage for create, refresh, and expire flows in tests/Feature/Evidence/EvidenceSnapshotResourceTest.php and tests/Feature/Guards/ActionSurfaceContractTest.php
  • T014 [P] [US1] Add audit-log regression coverage for snapshot create, refresh, and expire flows in tests/Feature/Evidence/EvidenceSnapshotAuditLogTest.php

Implementation for User Story 1

  • T015 [US1] Implement the first-slice collectors and curated snapshot-item payload assembly in app/Services/Evidence/Sources/FindingsSummarySource.php, app/Services/Evidence/Sources/PermissionPostureSource.php, app/Services/Evidence/Sources/EntraAdminRolesSource.php, app/Services/Evidence/Sources/BaselineDriftPostureSource.php, app/Services/Evidence/Sources/OperationsSummarySource.php, and app/Jobs/GenerateEvidenceSnapshotJob.php
  • T016 [US1] Implement queued snapshot generation, fingerprint dedupe, supersede transitions, and flat summary_counts handling in app/Services/Evidence/EvidenceSnapshotService.php and app/Jobs/GenerateEvidenceSnapshotJob.php
  • T017 [US1] Implement the tenant evidence Filament resource and list/view pages in app/Filament/Resources/EvidenceSnapshotResource.php, app/Filament/Resources/EvidenceSnapshotResource/Pages/ListEvidenceSnapshots.php, and app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php
  • T018 [US1] Implement confirmed create, refresh, and expire actions with canonical run links and audit entries in app/Filament/Resources/EvidenceSnapshotResource.php and app/Services/Audit/WorkspaceAuditLogger.php

Checkpoint: User Story 1 is complete when authorized operators can create, inspect, refresh, and expire tenant evidence snapshots without any snapshot mutating after it becomes active.

Phase 4: User Story 2 - Understand evidence completeness before downstream reporting (Priority: P1)

Goal: Show operators which evidence dimensions are complete, partial, missing, or stale before they generate downstream outputs.

Independent Test: Prepare complete, partial, and stale evidence inputs for multiple tenants and confirm both the tenant detail surface and workspace overview display the correct completeness and freshness state without leaking unauthorized tenant detail.

Tests for User Story 2

  • T019 [P] [US2] Add completeness-precedence and badge-mapping coverage in tests/Unit/Evidence/EvidenceCompletenessEvaluatorTest.php and tests/Unit/Evidence/EvidenceSnapshotBadgeTest.php
  • T020 [P] [US2] Add snapshot-detail completeness and freshness coverage in tests/Feature/Evidence/EvidenceSnapshotResourceTest.php and tests/Feature/Evidence/GenerateEvidenceSnapshotJobTest.php
  • T021 [P] [US2] Add workspace-overview authorization, entitled-tenant prefilter, and cross-tenant suppression coverage in tests/Feature/Evidence/EvidenceOverviewPageTest.php and tests/Feature/ManagedTenants/AuthorizationSemanticsTest.php

Implementation for User Story 2

  • T022 [US2] Implement completeness precedence and snapshot summary aggregation in app/Services/Evidence/EvidenceCompletenessEvaluator.php and app/Models/EvidenceSnapshot.php
  • T023 [US2] Implement evidence badge rendering and snapshot-detail infolist sections plus canonical run-detail links in app/Support/Badges/Domains/EvidenceSnapshotStatusBadge.php, app/Support/Badges/Domains/EvidenceCompletenessBadge.php, and app/Filament/Resources/EvidenceSnapshotResource.php
  • T024 [US2] Implement the workspace evidence overview page, authorized tenant filtering, entitled-tenant prefilter carryover, and empty-state/filter behavior in app/Filament/Pages/Monitoring/EvidenceOverview.php and resources/views/filament/pages/monitoring/evidence-overview.blade.php

Checkpoint: User Story 2 is complete when operators can identify completeness and freshness gaps from a single tenant snapshot view or the workspace overview without checking multiple source pages.

Phase 5: User Story 3 - Reuse one evidence package across downstream consumers (Priority: P2)

Goal: Make downstream consumers, starting with review packs, resolve curated evidence snapshots explicitly instead of rebuilding equivalent live evidence bundles.

Independent Test: Generate a snapshot, run review-pack generation, and verify the downstream flow resolves an eligible snapshot or fails explicitly with missing_snapshot or snapshot_ineligible instead of silently falling back to live assembly.

Tests for User Story 3

  • T025 [P] [US3] Add resolver result coverage for resolved, missing_snapshot, and snapshot_ineligible outcomes in tests/Unit/Evidence/EvidenceSnapshotResolverTest.php and tests/Feature/Evidence/GenerateEvidenceSnapshotJobTest.php
  • T026 [P] [US3] Add review-pack reuse and no-live-fallback coverage in tests/Feature/ReviewPack/ReviewPackGenerationTest.php and tests/Feature/ReviewPack/ReviewPackResourceTest.php

Implementation for User Story 3

  • T027 [US3] Persist review-pack-to-snapshot linkage in database/migrations/2026_03_19_000002_add_evidence_snapshot_id_to_review_packs_table.php and app/Models/ReviewPack.php
  • T028 [US3] Implement the explicit snapshot resolver contract in app/Services/Evidence/EvidenceSnapshotResolver.php, app/Services/Evidence/EvidenceResolutionRequest.php, and app/Services/Evidence/EvidenceResolutionResult.php
  • T029 [US3] Refactor review-pack generation to resolve and consume evidence snapshots in app/Services/ReviewPackService.php and app/Jobs/GenerateReviewPackJob.php
  • T030 [US3] Surface snapshot provenance and downstream eligibility details in app/Filament/Resources/ReviewPackResource.php and app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php

Checkpoint: User Story 3 is complete when review packs and other first-slice consumers depend on explicit snapshot resolution instead of reconstructing evidence from live source records.

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Finalize contract alignment, regression coverage, formatting, and manual validation across all stories.

  • T031 [P] Align the planning contract and design notes with the implementation in specs/153-evidence-domain-foundation/contracts/evidence-domain.openapi.yaml and specs/153-evidence-domain-foundation/research.md
  • T032 [P] Align the manual validation flow and focused test commands in specs/153-evidence-domain-foundation/quickstart.md and specs/153-evidence-domain-foundation/plan.md
  • T033 Run the focused Pest suite from specs/153-evidence-domain-foundation/quickstart.md covering tests/Feature/Evidence, tests/Unit/Evidence, and tests/Feature/ReviewPack
  • T034 Run formatting with vendor/bin/sail bin pint --dirty --format agent
  • T035 [P] Validate the manual smoke checklist in specs/153-evidence-domain-foundation/quickstart.md against /admin/t/{tenant}/evidence, /admin/t/{tenant}/evidence/{snapshot}, /admin/evidence/overview, and review-pack generation

Dependencies & Execution Order

Phase Dependencies

  • Phase 1: Setup has no dependencies and can start immediately.
  • Phase 2: Foundational depends on Phase 1 and blocks all user stories.
  • Phase 3: User Story 1 depends on Phase 2 and delivers the MVP.
  • Phase 4: User Story 2 depends on Phase 2 and can proceed after the foundational layer exists, though it benefits from US1 data-generation paths landing first.
  • Phase 5: User Story 3 depends on Phase 2 and should follow US1 so real snapshots exist for downstream reuse.
  • Phase 6: Polish depends on all desired user stories being complete.

User Story Dependencies

  • US1 (P1): No dependency on other stories. This is the recommended MVP slice.
  • US2 (P1): Depends only on the foundational schema, badges, and snapshot generation contracts, but is easiest to validate after US1 produces real snapshots.
  • US3 (P2): Depends on the foundational resolver contracts and on US1 snapshot generation being complete.

Within Each User Story

  • Write or extend tests first and confirm they fail before implementation.
  • Models, enums, and collector contracts must land before Filament surfaces or downstream consumer integration.
  • Service-owned OperationRun transitions and audit hooks must land before action-surface work is considered complete.
  • Workspace overview and downstream integration work should consume the same canonical snapshot/query layer rather than duplicating evidence assembly logic.

Parallel Opportunities

  • T001, T002, and T003 can run in parallel.
  • T006, T007, T008, and T009 can run in parallel after T004 and T005 define the schema and models.
  • T011, T012, T013, and T014 can run in parallel within User Story 1.
  • T019, T020, and T021 can run in parallel within User Story 2.
  • T025 and T026 can run in parallel within User Story 3.
  • T031, T032, and T035 can run in parallel after implementation is complete.

Parallel Example: User Story 1

# Launch the US1 regression additions together:
Task: "Add fingerprint reuse, supersede, and immutability coverage in tests/Feature/Evidence/GenerateEvidenceSnapshotJobTest.php and tests/Unit/Evidence/EvidenceSnapshotFingerprintTest.php"
Task: "Add tenant evidence authorization and 404 versus 403 coverage in tests/Feature/Evidence/EvidenceSnapshotResourceTest.php and tests/Feature/ManagedTenants/AuthorizationSemanticsTest.php"
Task: "Add action-surface and Ops-UX regression coverage for create, refresh, and expire flows in tests/Feature/Evidence/EvidenceSnapshotResourceTest.php and tests/Feature/Guards/ActionSurfaceContractTest.php"

Parallel Example: User Story 2

# Split completeness and overview validation:
Task: "Add completeness-precedence and badge-mapping coverage in tests/Unit/Evidence/EvidenceCompletenessEvaluatorTest.php and tests/Unit/Evidence/EvidenceSnapshotBadgeTest.php"
Task: "Add workspace-overview authorization and cross-tenant suppression coverage in tests/Feature/Evidence/EvidenceOverviewPageTest.php and tests/Feature/ManagedTenants/AuthorizationSemanticsTest.php"
Task: "Add snapshot-detail completeness and freshness coverage in tests/Feature/Evidence/EvidenceSnapshotResourceTest.php and tests/Feature/Evidence/GenerateEvidenceSnapshotJobTest.php"

Parallel Example: User Story 3

# Split resolver and downstream-consumer regression work:
Task: "Add resolver result coverage for resolved, missing_snapshot, and snapshot_ineligible outcomes in tests/Unit/Evidence/EvidenceSnapshotResolverTest.php and tests/Feature/Evidence/GenerateEvidenceSnapshotJobTest.php"
Task: "Add review-pack reuse and no-live-fallback coverage in tests/Feature/ReviewPack/ReviewPackGenerationTest.php and tests/Feature/ReviewPack/ReviewPackResourceTest.php"

Implementation Strategy

MVP First

  1. Complete Phase 1: Setup.
  2. Complete Phase 2: Foundational.
  3. Complete Phase 3: User Story 1.
  4. Stop and validate that immutable evidence snapshots can be created, reused, superseded, and inspected safely.

Incremental Delivery

  1. Land the evidence schema, domain types, collector contracts, and queued-operation seams.
  2. Deliver User Story 1 to establish immutable tenant evidence snapshots.
  3. Deliver User Story 2 to expose completeness and freshness truth on tenant and workspace surfaces.
  4. Deliver User Story 3 to make review packs and future consumers depend on explicit snapshot resolution.
  5. Finish with contract alignment, focused tests, formatting, and manual smoke validation.

Team Strategy

  1. One engineer lands the schema, models, badges, capabilities, and collector contracts in Phase 2.
  2. A second engineer can prepare the US1 and US2 regression tests in parallel once the foundational types are clear.
  3. Review-pack integration can proceed as a separate stream after snapshot generation is stable.

Notes

  • [P] tasks touch separate files and can be executed in parallel.
  • US1 is the recommended MVP because it establishes the immutable evidence package the later stories depend on.
  • Global search remains disabled for the new evidence resource unless a later iteration explicitly adds a compliant View/Edit search target.
  • No new panel provider registration is expected; Laravel 11+/12 provider registration remains in bootstrap/providers.php if discovery changes become necessary later.