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 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

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)

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)

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