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

218 lines
19 KiB
Markdown
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.
- [X] 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`
- [X] 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`
- [X] 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.
- [X] 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`
- [X] T005 Implement the root and child snapshot models, relationships, casts, and tenant/workspace scopes in `app/Models/EvidenceSnapshot.php` and `app/Models/EvidenceSnapshotItem.php`
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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
- [X] T011 [P] [US1] Add fingerprint reuse, supersede, and immutability coverage in `tests/Feature/Evidence/GenerateEvidenceSnapshotJobTest.php` and `tests/Unit/Evidence/EvidenceSnapshotFingerprintTest.php`
- [X] T012 [P] [US1] Add tenant evidence authorization and `404` versus `403` coverage in `tests/Feature/Evidence/EvidenceSnapshotResourceTest.php` and `tests/Feature/ManagedTenants/AuthorizationSemanticsTest.php`
- [X] 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`
- [X] 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
- [X] 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`
- [X] 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`
- [X] 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`
- [X] 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
- [X] T019 [P] [US2] Add completeness-precedence and badge-mapping coverage in `tests/Unit/Evidence/EvidenceCompletenessEvaluatorTest.php` and `tests/Unit/Evidence/EvidenceSnapshotBadgeTest.php`
- [X] T020 [P] [US2] Add snapshot-detail completeness and freshness coverage in `tests/Feature/Evidence/EvidenceSnapshotResourceTest.php` and `tests/Feature/Evidence/GenerateEvidenceSnapshotJobTest.php`
- [X] 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
- [X] T022 [US2] Implement completeness precedence and snapshot summary aggregation in `app/Services/Evidence/EvidenceCompletenessEvaluator.php` and `app/Models/EvidenceSnapshot.php`
- [X] 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`
- [X] 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
- [X] 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`
- [X] 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
- [X] 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`
- [X] 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`
- [X] T029 [US3] Refactor review-pack generation to resolve and consume evidence snapshots in `app/Services/ReviewPackService.php` and `app/Jobs/GenerateReviewPackJob.php`
- [X] 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.
- [X] 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`
- [X] 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`
- [X] 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`
- [X] T034 Run formatting with `vendor/bin/sail bin pint --dirty --format agent`
- [X] 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
```bash
# 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
```bash
# 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
```bash
# 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.
Reference in New Issue View Git Blame Copy Permalink