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:

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.