TenantAtlas/specs/329-evidence-audit-log-disclosure-productization/plan.md

# Implementation Plan: Spec 329 - Evidence / Audit Log Disclosure Productization

**Branch**: `329-evidence-audit-log-disclosure-productization` | **Date**: 2026-05-19 | **Spec**: `specs/329-evidence-audit-log-disclosure-productization/spec.md`
**Input**: User-provided Spec 329 and repo inspection.

## Summary

Productize the existing Evidence Overview and Audit Log into proof-first and event-proof-first disclosure surfaces. The implementation must keep current routes, source truth, RBAC, and workspace/environment contracts, introduce no backend foundation, and make the first viewport answer:

```text
What proof is available for this scope?
Which event proves what happened?
```

Evidence Overview will elevate proof availability, freshness, evidence path, review/export/report state, and operation proof before its inventory table. Audit Log will elevate actor/action/target/outcome/time, selected/latest event proof, and related proof before raw metadata and the event table. Diagnostics and raw metadata stay collapsed and capability-aware.

## Implementation Close-Out

Implemented on 2026-05-19. The runtime change stayed inside the existing Evidence Overview and Audit Log routes/pages, added the existing Evidence Overview route to the Workspace Monitoring sidebar with the concise `Evidence` / `Nachweise` navigation label, removed the duplicated Evidence Overview route registration, kept the existing tables as secondary context, and added targeted Feature plus Pest Browser coverage. No route/archetype/coverage classification changed, so UI registry documents were not updated; the active spec package carries close-out proof through `repo-truth-map.md`, tasks, tests, and screenshots.

Post-review UI corrections on 2026-05-19 keep dynamic Environment display names unchanged even when they contain `Tenant`, replace implementation-heavy empty-snapshot copy with product-safe proof language, add an explicit `Proof incomplete` hierarchy for empty primary snapshots, keep right-panel Evidence Path badge labels short and unclipped (`Empty`, `Ready`, `Available`), and replace the static table search placeholder with `Search evidence or next step`.

## Technical Context

**Language/Version**: PHP 8.4.15, Laravel 12.52.0.
**Primary Dependencies**: Filament 5.2.1, Livewire 4.1.4, Pest 4.3.1, Tailwind CSS 4.2.2.
**Storage**: PostgreSQL; no schema change expected.
**Testing**: Pest 4 Feature/Livewire/Browser tests.
**Validation Lanes**: confidence and browser; targeted navigation guard tests.
**Target Platform**: Laravel Sail locally; Dokploy/container deployment posture unchanged.
**Project Type**: Laravel monolith under `apps/platform`.
**Performance Goals**: DB-only page render; no Graph/provider API calls during render; no broad new query family beyond existing source queries unless bounded/eager-loaded.
**Constraints**: No new persisted truth, migration, package, queue, scheduler, storage, env var, deployment asset, compatibility route, or legacy alias support.
**Scale/Scope**: Two existing Filament pages, their views/partial, feature-local payload helpers if needed, focused tests, and browser smoke.

## UI / Surface Guardrail Plan

- **Guardrail scope**: changed existing operator-facing strategic surfaces.
- **Affected routes/pages/actions/states/navigation/panel/provider surfaces**:
  - `/admin/evidence/overview`
  - `/admin/audit-log`
  - `apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php`
  - `apps/platform/app/Filament/Pages/Monitoring/AuditLog.php`
  - `apps/platform/resources/views/filament/pages/monitoring/evidence-overview.blade.php`
  - `apps/platform/resources/views/filament/pages/monitoring/audit-log.blade.php`
  - `apps/platform/resources/views/filament/pages/monitoring/partials/audit-log-inspect-event.blade.php`
- **No-impact class, if applicable**: N/A.
- **Native vs custom classification summary**: Native Filament pages/tables plus existing Blade composition; no new UI framework.
- **Shared-family relevance**: evidence/report viewers, audit event detail, status messaging, proof links, OperationRun links, workspace/environment filter chip, diagnostics disclosure.
- **State layers in scope**: page payload, URL query (`environment_id`, `event`, `supportAccess` where existing), table state, selected audit event state, diagnostics disclosure.
- **Audience modes in scope**: auditor, customer-adjacent reviewer, operator-MSP, manager, support reviewer where authorized.
- **Decision/diagnostic/raw hierarchy plan**: proof/event first, evidence/context second, diagnostics collapsed third, raw/support hidden.
- **Raw/support gating plan**: collapsed by default and capability-gated through existing support diagnostics capability where any raw metadata is exposed.
- **One-primary-action / duplicate-truth control**: each workbench owns one proof/open next action; table and raw/detail helpers remain secondary.
- **Handling modes by drift class or surface**: review-mandatory for UI-025 and UI-044 strategic surfaces; document-in-feature for any UI coverage registry no-change decision.
- **Repository-signal treatment**: Spec 325 target images are visual direction only; runtime claims must be repo-verified or unavailable.
- **Special surface test profiles**: `global-context-shell`, `monitoring-state-page`, `shared-detail-family`.
- **Required tests or manual smoke**: Feature/Livewire tests for layout/RBAC/scope/disclosure plus Pest Browser smoke for clean/filtered/clear/reload/non-empty/empty/diagnostics/table-secondary behavior.
- **Exception path and spread control**: none expected. Any new dangerous action, export engine, schema, capability, or raw-disclosure mechanism requires spec/plan update first.
- **Active feature PR close-out entry**: Smoke Coverage.
- **UI/Productization coverage decision**: active spec package carries productization proof. Update UI coverage registry only if route/archetype/coverage classification changes; otherwise document why UI-025/UI-044 plus Spec 329 artifacts are sufficient.
- **Coverage artifacts to update**: none expected unless implementation changes route/archetype state.
- **Navigation / Filament provider-panel handling**: no panel provider registration changes expected. Laravel 12 panel providers remain in `apps/platform/bootstrap/providers.php`.
- **Navigation update**: add the existing Evidence Overview route to the Workspace Monitoring sidebar through the manual `WorkspaceSidebarNavigation` path and the admin panel's default workspace navigation items using a concise area label; no panel provider registration change.
- **Screenshot or page-report need**: screenshots required; full page report optional unless implementation materially changes coverage classification.

## Shared Pattern & System Fit

- **Cross-cutting feature marker**: yes.
- **Systems touched**: Evidence/Audit pages, EvidenceSnapshot/ReviewPack/StoredReport/OperationRun/AuditLog models, resource policies, `OperationRunLinks`, `RelatedNavigationResolver`, `BadgeRenderer`, `ArtifactTruthPresenter`, workspace hub filter/reset helpers.
- **Shared abstractions reused**: existing policies/capabilities, `WorkspaceHubEnvironmentFilter`, `WorkspaceHubFilterStateResetter`, `CanonicalAdminEnvironmentFilterState`, `OperationRunLinks`, `RelatedNavigationResolver`, `BadgeRenderer`, `ArtifactTruthPresenter`.
- **New abstraction introduced? why?**: none. Page-local private helpers only if needed to keep pages/views reviewable.
- **Why the existing abstraction was sufficient or insufficient**: existing paths already provide truth, authorization, related links, and filters. They do not currently impose the proof-first/event-proof-first hierarchy.
- **Bounded deviation / spread control**: no public reusable disclosure system; keep presentation local to these two surfaces.

## OperationRun UX Impact

- **Touches OperationRun start/completion/link UX?**: link/proof presentation only.
- **Central contract reused**: `OperationRunLinks`, `OperationRunUrl`, existing OperationRun policies and detail routes.
- **Delegated UX behaviors**: open operation/proof links only where existing link helpers and authorization allow.
- **Surface-owned behavior kept local**: proof availability labels and unavailable states.
- **Queued DB-notification policy**: unchanged / N/A.
- **Terminal notification path**: unchanged.
- **Exception path**: none.

## Provider Boundary & Portability Fit

- **Shared provider/platform boundary touched?**: no new provider seam.
- **Provider-owned seams**: existing Microsoft/Entra/Intune terms only where existing source records use them.
- **Platform-core seams**: workspace, environment, evidence, audit, proof, operation, report, disclosure.
- **Neutral platform terms / contracts preserved**: workspace, environment, actor, action, target, outcome, time, proof, diagnostics, raw metadata.
- **Retained provider-specific semantics and why**: provider-specific report or audit target copy may remain where source data is explicitly provider-bound.
- **Bounded extraction or follow-up path**: none for Spec 329.

## Constitution Check

- **Inventory-first, snapshots-second**: Evidence snapshots remain explicit artifact truth. No new snapshot or inventory persistence is introduced.
- **Read/write separation by default**: Pages remain read-first. Any unexpected mutation or destructive action requires spec/plan update, confirmation, authorization, audit, notification, and tests.
- **Single Contract Path to Graph**: No Graph/provider API calls may be added to page render.
- **Deterministic Capabilities**: Reuse existing `Capabilities`, `CapabilityResolver`, `WorkspaceCapabilityResolver`, resource policies, and report-type capability mapping.
- **Proportionality / anti-bloat**: No new source of truth, persisted entity, enum/status family, public abstraction, proof engine, or cross-domain UI framework.
- **Workspace isolation**: Clean URLs stay workspace-wide. `environment_id` resolves through current workspace and actor entitlement.
- **Tenant/environment language**: Runtime copy must avoid tenant as platform context. Provider-specific tenant wording is allowed only where explicitly external/provider-bound.
- **OperationRun UX**: Deep links only through existing OperationRun link helpers; no operation start or lifecycle changes.
- **UI-COV-001**: Existing strategic surfaces UI-025 and UI-044 change. Active spec package must carry repo-truth map, tests, and browser screenshots; implementation close-out must decide whether route inventory/coverage matrix updates are needed.
- **TEST-GOV-001**: Targeted Feature and Browser tests are explicit; no broad heavy-governance lane unless implementation reveals structural risk.
- **Filament-native UI**: Use native Filament components and shared primitives first; custom Blade must preserve Filament visual language, accessibility, and disclosure hierarchy.
- **Filament v5 / Livewire v4**: Livewire v4.0+ compliance required. No Livewire v3 or Filament v3/v4 APIs.

## Current Repo Truth Summary

Existing verified surfaces:

- `EvidenceOverview` is a Filament `Page` at `/admin/evidence/overview`, with an existing table over latest active accessible `EvidenceSnapshot` records.
- Evidence page currently uses `EvidenceSnapshot`, `EnvironmentReview`, `ArtifactTruthPresenter`, `EvidenceSnapshotResource` links, `WorkspaceHubEnvironmentFilter`, and clear/reset helpers.
- `AuditLog` is a Filament `Page` at `/admin/audit-log`, with an existing table over scoped `AuditLog` records, event selection through `event`, support-access filter, related navigation links, and environment filter chip.
- `AuditLog` model derives actor snapshots, target snapshots, outcome labels, readable context items, and technical metadata.
- `AuditLog` selected-event partial currently renders `Technical metadata` directly when an event is selected; Spec 329 must move that behind collapsed/capability-aware disclosure.
- `EvidenceSnapshot`, `ReviewPack`, and `AuditLog` have `operationRun()` relations. `OperationRunLinks::related()` already maps evidence snapshot and review pack generation runs to artifact links.
- `StoredReportResource` supports permission posture and Entra admin role report types with capability checks and disabled global search.
- `WorkspaceHubEnvironmentFilter::fromRequest()` accepts canonical `environment_id`, scopes to current workspace, checks actor access, and rejects inaccessible/cross-workspace IDs.
- Navigation tests already cover canonical environment filter, clear filter, legacy alias rejection, and workspace hub no-drift behavior for several related surfaces.

Known productization gaps:

- Evidence Overview is table-first and does not yet show a proof readiness workbench, evidence path panel, export/report availability panel, or collapsed diagnostics affordance.
- Audit Log is summary-first but not yet event-proof-first; actor/action/target/outcome/time should dominate the first-read, and raw technical metadata must not be default-visible.
- Current Audit Log route middleware includes `ensure-environment-context-selected`; implementation must verify this does not force Environment shell ownership or remembered Environment fallback.
- `routes/web.php` contains a duplicated `/admin/evidence/overview` route registration; implementation may document or clean this only if safe and in scope.

## Existing Repository Surfaces Likely Affected

Runtime files, only during later implementation:

- `apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php`
- `apps/platform/app/Filament/Pages/Monitoring/AuditLog.php`
- `apps/platform/resources/views/filament/pages/monitoring/evidence-overview.blade.php`
- `apps/platform/resources/views/filament/pages/monitoring/audit-log.blade.php`
- `apps/platform/resources/views/filament/pages/monitoring/partials/audit-log-inspect-event.blade.php`
- `apps/platform/resources/lang/en/*` and `apps/platform/resources/lang/de/*` only if surrounding page-copy conventions require localized strings.

Tests, only during later implementation:

- `apps/platform/tests/Feature/Evidence/EvidenceOverviewPageTest.php`
- `apps/platform/tests/Feature/Monitoring/EvidenceOverviewWorkspaceHubContractTest.php`
- `apps/platform/tests/Feature/Filament/EvidenceOverviewDerivedStateMemoizationTest.php`
- `apps/platform/tests/Feature/Filament/AuditLogPageTest.php`
- `apps/platform/tests/Feature/Filament/AuditLogDetailInspectionTest.php`
- `apps/platform/tests/Feature/Filament/AuditLogAuthorizationTest.php`
- `apps/platform/tests/Feature/Monitoring/AuditLogInspectFlowTest.php`
- `apps/platform/tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php`
- `apps/platform/tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php`
- `apps/platform/tests/Browser/Spec329EvidenceAuditDisclosureSmokeTest.php`

Spec/UI artifacts:

- `specs/329-evidence-audit-log-disclosure-productization/repo-truth-map.md`
- screenshot artifacts under `specs/329-evidence-audit-log-disclosure-productization/artifacts/screenshots/`
- optional UI coverage registry updates only if implementation materially changes route/archetype/coverage state.

## Domain / Model Implications

- No new model, table, migration, enum, status family, source of truth, or persisted display state.
- Evidence proof state must derive from:
  - `EvidenceSnapshot.status`, `completeness_state`, `summary`, `generated_at`, `expires_at`.
  - `EvidenceSnapshot::items()`, `reviewPacks()`, `environmentReviews()`, and `operationRun()`.
  - `ReviewPack.status`, `generated_at`, `expires_at`, `file_size`, and related review/snapshot/run.
  - `StoredReport.report_type`, `payload`, `fingerprint`, report-type capability, and environment/workspace scope.
  - Existing finding exception evidence references where linked and authorized.
- Audit proof state must derive from:
  - `AuditLog` actor snapshot, action, target snapshot, normalized outcome, recorded time, managed environment/workspace scope, operation run relation, readable context, and related navigation resolver.
- If exact evidence, report, export, operation, risk/decision, or proof link is missing, render explicit unavailable/missing/not generated/not applicable state.

## UI / Filament Implications

- Filament v5 and Livewire v4.0+ compliance must be preserved.
- Panel providers remain registered in `apps/platform/bootstrap/providers.php`; no panel provider changes expected.
- No globally searchable resource is added or changed. Related resources must remain disabled for global search or backed by safe View/Edit pages.
- Use Filament sections/tables/actions and shared badge/filter primitives where suitable.
- Avoid fake charts, fake compliance readiness, fake immutable/certified badges, and generic KPI dashboards.
- Main Evidence structure:
  - header/scope
  - proof readiness workbench
  - evidence path panel
  - export/report availability panel
  - evidence inventory/table as secondary context
  - collapsed diagnostics disclosure
- Main Audit structure:
  - header/scope
  - audit proof workbench
  - selected/latest event proof panel
  - actor/action/target/outcome/time first-read
  - audit event table as secondary context
  - collapsed raw metadata/diagnostics disclosure
- Right-side proof/disclosure panel should be desktop aside and mobile stack where practical.

## Livewire / Page State Implications

- Evidence clean entry must clear remembered/stale Environment-like table filters and session state.
- Audit clean entry must clear remembered/stale Environment-like table filters and session state.
- `environment_id` query state remains the only shareable environment filter key.
- Audit `event` query remains selected-event state and must be normalized against current query/table filters and authorization.
- `supportAccess` may remain existing Audit Log state if it does not conflict with disclosure hierarchy.
- Clear filter must remove `environment_id` and environment-like table/session state through existing helpers.

## RBAC / Policy Implications

Reuse existing authorization:

- Workspace page access through `WorkspaceContext` / `WorkspaceCapabilityResolver`.
- Environment access through current accessible environment queries and `User::canAccessTenant()`.
- Evidence visibility through `Capabilities::EVIDENCE_VIEW` and `EvidenceSnapshotPolicy`.
- Review pack visibility/download through `Capabilities::REVIEW_PACK_VIEW`, `ReviewPackPolicy`, and existing download route authorization.
- Stored report visibility through report-type capabilities in `StoredReportResource`.
- Audit page access through `Capabilities::AUDIT_VIEW`.
- Operation proof visibility through existing `OperationRunPolicy`, link helpers, and related resource policies.
- Diagnostics/raw metadata through `Capabilities::SUPPORT_DIAGNOSTICS_VIEW` or stricter existing capability.

No new permission semantics should be added unless implementation proves existing capabilities cannot express the action and spec/plan/tasks are updated first.

## Audit / Evidence / Disclosure Implications

- No new audit event is required for read-only page rendering unless current page-open audit conventions are extended repo-wide.
- Evidence should appear as proof path/state:
  - available
  - incomplete
  - stale
  - unavailable
  - not generated
  - not applicable
- Audit should appear as event proof:
  - actor
  - action
  - target
  - outcome
  - time
  - scope
  - related proof
- Do not show raw provider payloads, debug metadata, internal exception traces, provider secrets, raw OperationRun payloads, raw audit metadata blobs, or stack traces by default.
- If diagnostics disclosure is present, it must be collapsed and capability-aware.

## Data / Migration Implications

Expected outcome:

- No migrations.
- No seeders.
- No data backfills.
- No packages.
- No env vars.
- No queues/scheduler/storage changes.
- No deployment asset changes.
- No backwards compatibility layer.
- No legacy tenant query alias support.

If implementation discovers an actual schema need, stop and update spec/plan/tasks/repo-truth-map first. Default decision remains no migration.

## Localization / Copy Implications

- Runtime copy must be concise, customer/auditor-safe, and operator-readable.
- Stable visible strings should be EN/DE localized if current project pattern routes page copy through language files.
- Avoid platform-context `tenant` wording. Use `Workspace` and `Environment` for shell/filter/product context.
- Provider-bound tenant wording may remain only when describing an external Microsoft/Entra tenant identifier or provider payload outside the default decision view.

## Implementation Phases

### Phase 1 - Repo Truth And Current UI Audit

- Re-read spec, plan, tasks, and `repo-truth-map.md`.
- Inspect current Evidence Overview, Audit Log, selected-event partial, models, policies, related links, and tests.
- Update `repo-truth-map.md` before runtime changes if implementation discovers new source truth or gaps.
- Confirm no migration/package/env/queue/storage need.

### Phase 2 - Tests First

- Add tests for repo truth map existence.
- Add Feature/Livewire tests for evidence proof-first layout, audit event-proof-first layout, evidence path, raw metadata hidden, export/report availability, RBAC, canonical environment filter, legacy aliases, cross-workspace guard, and tenant-copy guard.

### Phase 3 - Evidence Overview Productization

- Refactor the existing page into proof-first layout.
- Bind to existing evidence snapshot, review pack, stored report, operation proof, review/decision/risk sources where repo-supported.
- Keep table available as secondary context.
- Keep diagnostics collapsed and raw metadata hidden.

### Phase 4 - Audit Log Productization

- Refactor the existing page into event-proof-first layout.
- Ensure actor/action/target/outcome/time/scope are first-read.
- Move selected-event technical metadata behind collapsed/capability-aware disclosure.
- Keep audit table available as secondary context.

### Phase 5 - Shared Disclosure UX

- Add consistent disclosure rule panel/affordance across both pages:
  - decision/proof visible
  - evidence/event visible
  - diagnostics collapsed
  - raw/support hidden
- Show unavailable/deferred states honestly.

### Phase 6 - Scope / Filter Integration

- Preserve clean workspace-wide entry.
- Preserve `?environment_id=` filter, visible chip, clear filter, reload/back/forward behavior.
- Preserve legacy alias rejection and cross-workspace guard.
- Verify Audit Log route middleware does not force Environment shell ownership.

### Phase 7 - Browser Smoke And Screenshots

- Add targeted Browser smoke for evidence clean/filtered/clear/reload/non-empty/empty, audit clean/filtered/clear/reload/non-empty/empty, diagnostics hidden, table secondary, and no platform-context tenant wording.
- Save screenshots under the spec artifacts path when generated.

### Phase 8 - Validation And Close-Out

- Run targeted Feature/navigation tests, Browser smoke, filtered guard tests, `pint --dirty`, and `git diff --check`.
- Report full suite status honestly if not run.
- Record no migrations/seeders/packages/env/queues/scheduler/storage/deployment asset/backcompat/legacy alias support.

## Testing Strategy

Required tests:

- `it('documents_evidence_audit_log_repo_truth_map')`
- `it('renders_evidence_overview_proof_first_layout')`
- `it('renders_audit_log_event_proof_first_layout')`
- `it('shows_evidence_path_without_raw_metadata_by_default')`
- `it('shows_audit_actor_action_target_outcome_time_before_raw_metadata')`
- `it('shows_export_or_report_availability_only_when_repo_supported')`
- `it('hides_evidence_and_audit_raw_diagnostics_by_default')`
- `it('respects_evidence_audit_and_diagnostics_capabilities')`
- `it('evidence_overview_supports_canonical_environment_filter')`
- `it('audit_log_supports_canonical_environment_filter')`
- `it('evidence_and_audit_reject_legacy_environment_aliases')`
- `it('evidence_and_audit_reject_cross_workspace_environment_filter')`
- `it('evidence_and_audit_do_not_use_tenant_as_platform_context_copy')`
- `tests/Browser/Spec329EvidenceAuditDisclosureSmokeTest.php`

Required Browser smoke:

- Evidence Overview clean workspace.
- Evidence Overview environment-filtered.
- Evidence clear filter and reload.
- Audit Log clean workspace.
- Audit Log environment-filtered.
- Audit clear filter and reload.
- Evidence non-empty proof state.
- Audit non-empty event state.
- Evidence empty state.
- Audit empty state.
- Diagnostics hidden by default.
- Tables remain secondary.
- No platform-context tenant wording.

## Rollout / Deployment Considerations

- No env vars expected.
- No migrations expected.
- No queue/scheduler changes expected.
- No storage/volume changes expected.
- No deployment asset changes expected unless implementation registers new Filament assets, which is not expected. If assets are registered, deployment must include `cd apps/platform && php artisan filament:assets`.
- Staging validation should include targeted Browser smoke for light mode, workspace/environment filter behavior, and disclosure hierarchy before production promotion.

## Risk Controls

- Do not implement before `repo-truth-map.md` exists.
- Do not show any metric, proof state, export state, operation proof, review/risk link, or diagnostic affordance unless mapped to repo truth.
- If a planned UI element has no safe source or authorization path, render unavailable/not generated/not applicable or omit it.
- Do not introduce backend foundation to make a UI card true.
- Do not support legacy query aliases.
- Do not rewrite completed Specs 314-328.

## Candidate Selection Gate

Passed. The candidate was directly user-provided as Spec 329, explicitly deferred by Specs 326-328, not already present as an active/completed package, aligned with UI-025/UI-044 strategic surface coverage, and scoped to two existing proof/disclosure pages.

## Spec Readiness Gate

Expected pass after `spec.md`, `plan.md`, `tasks.md`, `repo-truth-map.md`, and `checklists/requirements.md` are created and preparation analysis has no blocking findings.