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