TenantAtlas/specs/153-evidence-domain-foundation/plan.md

# Implementation Plan: Evidence Domain Foundation

**Branch**: `153-evidence-domain-foundation` | **Date**: 2026-03-19 | **Spec**: [/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/153-evidence-domain-foundation/spec.md](/Users/ahmeddarrazi/Documents/projects/TenantAtlas/specs/153-evidence-domain-foundation/spec.md)
**Input**: Feature specification from `/specs/153-evidence-domain-foundation/spec.md`

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

## Summary

Introduce a tenant-scoped Evidence Snapshot domain that curates existing internal governance artifacts into immutable, reusable snapshots. Implementation uses PostgreSQL-backed snapshot and snapshot-item tables, a DB-only queued `OperationRun` for snapshot generation, tenant-context Filament list/detail surfaces, a workspace-scoped evidence overview, and an explicit downstream resolver contract so review-pack and future readiness/reporting features consume curated snapshots instead of rebuilding ad hoc evidence bundles.

Implemented routes and surfaces center on the tenant-context evidence resource at `/admin/t/{tenant}/evidence`, the snapshot detail route at `/admin/t/{tenant}/evidence/{snapshot}`, and the canonical workspace overview at `/admin/evidence/overview`.

## Technical Context

<!--
  ACTION REQUIRED: Replace the content in this section with the technical details
  for the project. The structure here is presented in advisory capacity to guide
  the iteration process.
-->

**Language/Version**: PHP 8.4.15  
**Primary Dependencies**: Laravel 12, Filament v5, Livewire v4, Pest v4, existing `StoredReport`, `Finding`, `OperationRun`, and `AuditLog` infrastructure  
**Storage**: PostgreSQL with JSONB-backed snapshot metadata; existing private storage remains a downstream-consumer concern, not a primary evidence-foundation store  
**Testing**: Pest feature tests, Pest unit tests, and Livewire/Filament component tests  
**Target Platform**: Laravel Sail web application on PostgreSQL
**Project Type**: Web application monolith  
**Performance Goals**: Evidence snapshot generation completes in the background within 120 seconds for a medium tenant; tenant evidence pages remain DB-only at render time; dedupe and active-snapshot lookup are index-backed  
**Constraints**: No Microsoft Graph calls during snapshot generation; successful snapshots are immutable; all tenant/workspace authorization is server-side; `OperationRun.status` and `OperationRun.outcome` remain service-owned; status-like UI uses centralized badge semantics  
**Scale/Scope**: First rollout supports five evidence dimensions, one active snapshot per tenant scope, explicit downstream reuse by review-pack and future readiness consumers, and tenant/workspace evidence surfaces only

## Constitution Check

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

- **Pre-Phase-0 Gate: PASS**
- Inventory-first: PASS. Snapshot generation curates existing last-observed artifacts (`StoredReport`, `Finding`, baseline/drift summaries, recent `OperationRun` summaries) and does not recollect live state.
- Read/write separation: PASS. The only write is internal snapshot materialization; it is explicit, queued, auditable, and confirmation-gated for expiration. No remote tenant mutation is introduced.
- Graph contract path: PASS. No new Graph calls are added; snapshot generation is DB-only.
- Deterministic capabilities: PASS. New `evidence.view` and `evidence.manage` capabilities are added to the canonical registry and tested through existing RBAC patterns.
- RBAC-UX / workspace / tenant isolation: PASS. Tenant evidence detail stays tenant-scoped, workspace overview is explicit and aggregate-only, non-members are 404, in-scope capability denials are 403.
- Global search: PASS. No global-search expansion is required in the first slice.
- Run observability: PASS. Snapshot generation uses a dedicated `OperationRun` type and existing `OperationRunService` patterns.
- Ops-UX 3-surface feedback: PASS. Queue intent uses the standard presenter, live progress remains limited to the active-ops widget and Monitoring run detail, and snapshot detail links to the canonical run detail without adding a fourth progress surface.
- Ops-UX lifecycle and summary counts: PASS. Status/outcome changes remain service-owned; summary counts use existing canonical keys (`created`, `report_count`, `finding_count`, `operation_count`, `errors_recorded`).
- Data minimization: PASS. Snapshot items store curated references and summary payloads, not raw Graph payloads or secrets.
- BADGE-001: PASS. New snapshot-status and completeness values will be added via centralized badge semantics with tests.
- UI-NAMING-001: PASS. Operator-facing vocabulary remains `Create snapshot`, `Refresh evidence`, `Expire snapshot`, `View snapshot`.
- Filament Action Surface Contract: PASS. Tenant evidence list uses clickable rows, explicit header action, confirmed destructive action, and no lone View button.
- UX-001: PASS with explicit exemption. Snapshot creation is a modal operation trigger rather than a CRUD create page; detail view uses Infolists.

**Post-Phase-1 Re-check: PASS**
- The proposed design preserves workspace/tenant ownership boundaries, keeps successful snapshots immutable, uses DB-only generation, and routes all lifecycle transitions through existing run/audit infrastructure without introducing constitution violations.
## Project Structure

### Documentation (this feature)

```text
specs/[###-feature]/
├── plan.md              # This file (/speckit.plan command output)
├── research.md          # Phase 0 output (/speckit.plan command)
├── data-model.md        # Phase 1 output (/speckit.plan command)
├── quickstart.md        # Phase 1 output (/speckit.plan command)
├── contracts/           # Phase 1 output (/speckit.plan command)
└── tasks.md             # Phase 2 output (/speckit.tasks command - NOT created by /speckit.plan)
```

### Source Code (repository root)
<!--
  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
  for this feature. Delete unused options and expand the chosen structure with
  real paths (e.g., apps/admin, packages/something). The delivered plan must
  not include Option labels.
-->

```text
app/
├── Filament/
│   ├── Pages/
│   │   └── Monitoring/
│   ├── Resources/
│   └── Widgets/
├── Jobs/
├── Models/
├── Services/
│   ├── Audit/
│   └── Evidence/
└── Support/
  ├── Auth/
  ├── Badges/
  └── OpsUx/

database/
└── migrations/

routes/
└── web.php

tests/
├── Feature/
│   └── Evidence/
└── Unit/
  └── Evidence/
```

**Structure Decision**: Keep the existing Laravel monolith structure. Add the new domain under `app/Models`, `app/Services/Evidence`, `app/Jobs`, and tenant/admin Filament surfaces under `app/Filament`. Persist schema in `database/migrations` and cover behavior with focused Pest feature/unit tests under `tests/Feature/Evidence` and `tests/Unit/Evidence`.

Focused verification now includes the downstream review-pack integration and the shared authorization/action-surface regressions in `tests/Feature/ReviewPack`, `tests/Feature/ManagedTenants/AuthorizationSemanticsTest.php`, and `tests/Feature/Guards/ActionSurfaceContractTest.php`.

## Complexity Tracking

> **Fill ONLY if Constitution Check has violations that must be justified**

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|