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

Feature Specification: Spec 329 - Evidence / Audit Log Disclosure Productization

Feature Branch: 329-evidence-audit-log-disclosure-productization Created: 2026-05-19 Status: Implemented Type: Runtime UI productization / evidence-proof surface / audit disclosure UX Runtime posture: Narrow runtime UI implementation. Repo-based. No invented backend foundation. Input: User-provided full Spec 329 draft.

Dependencies And Historical Context

Depends on:

• Spec 314 - Workspace Hub Navigation Context Contract.
• Spec 315 - Environment CTA Explicit Filter Contract.
• Spec 316 - Workspace Hub Clear Filter Contract.
• Spec 317 - Legacy Tenant / Environment Context Cleanup.
• Spec 318 - Admin Surface Scope & Shell Context Audit.
• Spec 319 - Environment-Owned Surface Routing & Shell Context Contract.
• Spec 320 - Workspace-Owned Analysis Surface Registration & Shell Cutover.
• Spec 321 - Alerts / Audit Log Environment Filter Contract Decision.
• Spec 322 - Browser No-Drift Regression Guard.
• Spec 325 - Screenshot-Anchored Strategic Target Images.
• Spec 326 - Customer Review Workspace v1 Productization.
• Spec 327 - Governance Inbox Decision-First Workbench Productization.
• Spec 328 - Operations Hub Decision-First Workbench Productization.

Repo truth adjustment: the user draft allowed /admin/evidence or an existing canonical route. Current repository truth is admin.evidence.overview at /admin/evidence/overview and admin.monitoring.audit-log at /admin/audit-log. Spec 329 productizes those existing routes and must not create replacement routes, new evidence/audit engines, new export pipelines, new persistence, or new compliance certification semantics.

Spec 325 target images are visual calibration only. They are not runtime truth for proof availability, export readiness, immutability, certification, RBAC, disclosure levels, evidence freshness, or audit event verification.

Spec Candidate Check

• Problem: Evidence Overview and Audit Log are repo-real, but they still risk reading as technical metadata and event tables instead of proof/disclosure surfaces that answer what proof exists and which event proves what happened.
• Today's failure: Evidence snapshots, review packs, operation proof, stored reports, actor/action/target/outcome/time, and raw metadata are not consistently ordered by decision value. Audit selected-event detail currently exposes technical metadata in the default selected-event view, and Evidence Overview is still table-first.
• User-visible improvement: Auditors, security reviewers, MSP operators, and service delivery teams can see scope, proof availability, evidence path, actor/action/target/outcome/time, related proof, disclosure posture, and diagnostics status before any raw metadata.
• Smallest enterprise-capable version: Productize only the existing Evidence Overview and Audit Log pages using existing EvidenceSnapshot, ReviewPack, StoredReport, OperationRun, AuditLog, policies/capabilities, related links, and workspace hub filter helpers. Tables remain secondary context.
• Explicit non-goals: No new audit engine, evidence store, immutable storage, legal attestation, compliance framework mapping, external auditor portal, export engine, report generation engine, retention/hold system, AI summarization, package, queue, scheduler, storage, env var, migration, seed, compatibility route, or legacy query alias.
• Permanent complexity imported: Feature-local page payloads, targeted Feature/Livewire tests, one Browser smoke, screenshots, and repo-truth-map.md. No new persisted truth, public abstraction, enum/status family, status taxonomy, or cross-domain UI framework.
• Why now: Specs 314-322 stabilized workspace/environment context. Specs 326-328 established the strategic productization pattern. Spec 328 explicitly deferred Evidence / Audit Log Disclosure Productization as the next proof/disclosure lane.
• Why not local: A column rename or small copy tweak would not change the first-read hierarchy. A new evidence/audit backend would overbuild. The narrow correct slice is a repo-truth-bounded productization pass on two existing pages.
• Approval class: Core Enterprise.
• Red flags triggered: Strategic UI productization and evidence/audit disclosure semantics. Defense: scope is limited to existing pages and existing truth sources, forbids new backend/state frameworks, and prevents false proof/certification claims.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 2 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 12/12
• Decision: approve.

Candidate Source And Completed-Spec Guardrail

• Candidate source: Direct user-provided manual promotion for Spec 329, aligned with the follow-up list in Specs 326, 327, and 328 and the Audit Log / Evidence Overview strategic rows in docs/ui-ux-enterprise-audit/.
• Current package check: No specs/329-* package, branch, or completed package existed before this preparation run.
• Related completed-spec check: Specs 314-328 include historical/completed foundation and productization signals. They are dependency context only and must not be rewritten by Spec 329.
• Close alternatives deferred: Environment Dashboard / Baseline Compare Productization, Restore Safety Workflow Productization, and Provider Readiness Productization remain follow-up candidates 330-332.
• Smallest viable implementation slice: Existing Evidence Overview and Audit Log only: header/scope, proof/event workbench, evidence path/event proof panel, export/report availability, table as secondary context, collapsed diagnostics, RBAC-aware links/actions, canonical environment_id filter behavior, empty states, and targeted tests/browser smoke.

Spec Scope Fields

• Scope: workspace canonical-view proof/disclosure surfaces, optionally filtered by canonical environment_id.
• Primary Routes:
  • Existing Evidence Overview route: /admin/evidence/overview.
  • Existing Evidence route name: admin.evidence.overview.
  • Existing Evidence page class: apps/platform/app/Filament/Pages/Monitoring/EvidenceOverview.php.
  • Existing Evidence view: apps/platform/resources/views/filament/pages/monitoring/evidence-overview.blade.php.
  • Existing Audit Log route: /admin/audit-log.
  • Existing Audit route name: admin.monitoring.audit-log.
  • Existing Audit page class: apps/platform/app/Filament/Pages/Monitoring/AuditLog.php.
  • Existing Audit view: apps/platform/resources/views/filament/pages/monitoring/audit-log.blade.php.
  • Existing Audit selected-event partial: apps/platform/resources/views/filament/pages/monitoring/partials/audit-log-inspect-event.blade.php.
• Data Ownership:
  • Evidence truth: EvidenceSnapshot.status, completeness_state, summary, generated_at, expires_at, operation_run_id, workspace_id, and managed_environment_id.
  • Evidence path truth: EvidenceSnapshotItem, ReviewPack, StoredReport, EnvironmentReview, FindingExceptionEvidenceReference, and OperationRun links where existing relations/queries prove availability.
  • Audit truth: AuditLog.actor_*, actor_type, actor_label, action, resource_type, resource_id, target_label, status, outcome, summary, metadata, operation_run_id, recorded_at, workspace_id, and managed_environment_id.
  • Operation proof truth: OperationRunLinks::tenantlessView(), OperationRunLinks::related(), AuditLog::operationRun(), EvidenceSnapshot::operationRun(), and ReviewPack::operationRun().
  • Workspace/environment scope: WorkspaceContext, WorkspaceHubEnvironmentFilter, WorkspaceHubFilterStateResetter, CanonicalAdminEnvironmentFilterState, and the shared environment filter chip partial.
• RBAC:
  • Workspace membership required.
  • Evidence page data uses existing environment entitlement and evidence.view.
  • Evidence snapshot details use EvidenceSnapshotPolicy.
  • Review pack links/download/open states use review_pack.view / ReviewPackPolicy and existing download authorization.
  • Stored report links use report-type capabilities such as permission_posture.view and entra_roles.view.
  • Audit Log page access uses workspace membership and audit.view.
  • Operation proof links use existing operation visibility and related-route authorization.
  • Diagnostics/raw metadata visibility uses support_diagnostics.view or a stricter existing capability if implementation finds one.
  • Non-member or cross-workspace environment access remains deny-as-not-found.
  • Member with missing capability must not see protected records, raw metadata, or unauthorized actions.

For canonical-view specs:

• Default filter behavior when environment context is active: clean /admin/evidence/overview and /admin/audit-log remain workspace-wide and must not inherit remembered Environment context, Filament tenant context, session table filters, or legacy query aliases.
• Explicit entitlement checks preventing cross-environment leakage: ?environment_id= must resolve through the current workspace and actor entitlement. Cross-workspace or inaccessible IDs return safe no-access / 404.

UI Surface Impact

Does this spec add, remove, rename, or materially change any reachable UI surface?

• No UI surface impact
• Existing page changed
• New page/route added
• Navigation changed
• Filament panel/provider surface changed
• New modal/drawer/wizard/action added
• New table/form/state added
• Customer-facing surface changed
• Dangerous action changed
• Status/evidence/review presentation changed
• Workspace/environment context presentation changed

UI/Productization Coverage

• Route/page/surface: /admin/evidence/overview, /admin/audit-log, EvidenceOverview, AuditLog, their Blade views, and Audit selected-event partial.
• Current or new page archetype: Evidence / Audit strategic surfaces, matching docs/ui-ux-enterprise-audit/route-inventory.md rows UI-025 and UI-044.
• Design depth: Strategic Surface.
• Repo-truth level: repo-verified route/page/model foundations; individual runtime elements are classified in repo-truth-map.md.
• Existing pattern reused: Filament Page, Filament table, Filament Sections where suitable, badges, shared environment filter chip, BadgeRenderer, ArtifactTruthPresenter, OperationRunLinks, resource policies, and current workspace hub resetter/filter helpers.
• New pattern required: no new runtime framework; page-local workbench composition only.
• Screenshot required: yes, Browser smoke screenshots under specs/329-evidence-audit-log-disclosure-productization/artifacts/screenshots/.
• Page audit required: no full new audit unless implementation materially changes route inventory or archetype. Evidence Overview is already UI-044 but lacks a page report; implementation may document no registry update if Spec 329 carries the page productization proof, or update UI coverage artifacts if the route/archetype state changes.
• Customer-safe review required: yes for default copy because evidence/audit surfaces are auditor-adjacent. Default views must avoid raw JSON, debug vocabulary, false certification, and unsupported verification claims.
• Dangerous-action review required: no dangerous actions expected. If implementation unexpectedly adds download/export/open support actions, they must remain navigation/download actions with existing authorization. Any destructive/high-impact action requires spec/plan update first and must use Action::make(...)->action(...), ->requiresConfirmation(), server-side authorization, audit, notification, and tests.
• Coverage files updated or explicitly not needed:
  • docs/ui-ux-enterprise-audit/route-inventory.md
  • docs/ui-ux-enterprise-audit/design-coverage-matrix.md
  • docs/ui-ux-enterprise-audit/page-reports/...
  • docs/ui-ux-enterprise-audit/strategic-surfaces.md
  • docs/ui-ux-enterprise-audit/grouped-follow-up-candidates.md
  • docs/ui-ux-enterprise-audit/unresolved-pages.md
  • N/A - no reachable UI surface impact
  • Active spec package must carry repo-truth map, tests, browser screenshots, and close-out coverage decision. Registry updates are required only if runtime changes alter route/archetype/coverage classification.

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes.
• Interaction class(es): evidence/report viewers, audit event detail, status messaging, proof links, OperationRun links, environment filter chip, diagnostics disclosure, table empty states, export/download/open actions.
• Systems touched: EvidenceOverview, AuditLog, audit event partial, EvidenceSnapshotResource, ReviewPackResource, StoredReportResource, OperationRunLinks, RelatedNavigationResolver, BadgeRenderer, ArtifactTruthPresenter, WorkspaceHubEnvironmentFilter, WorkspaceHubFilterStateResetter, CanonicalAdminEnvironmentFilterState, resource policies and capabilities.
• Existing pattern(s) to extend: existing evidence table, audit table, audit selected-event detail, environment chip, related navigation resolver, artifact truth presentation, OperationRun links, resource policies.
• Shared contract / presenter / builder / renderer to reuse: BadgeRenderer, ArtifactTruthPresenter, OperationRunLinks, RelatedNavigationResolver, WorkspaceHubEnvironmentFilter, WorkspaceHubFilterStateResetter, existing policy/capability resolvers.
• Why the existing shared path is sufficient or insufficient: Existing paths are sufficient for evidence snapshots, audit events, related operation links, badges, authorization, and filter/reset behavior. They are insufficient only in first-read hierarchy and default disclosure ordering on these pages.
• Allowed deviation and why: bounded page-local payload/view helpers are allowed if needed to reduce Blade complexity. New public evidence/audit disclosure frameworks, status taxonomies, presenter layers, or proof engines are not allowed.
• Consistency impact: Evidence, review pack, stored report, operation, audit, scope, diagnostic, export, and action labels must stay aligned across source resources and related links.
• Review focus: Verify no fake proof, no false green state, no raw diagnostics by default, no unauthorized links/actions, no shell-scope regression, no tenant platform copy, and no duplicate local truth layer.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: link and proof availability semantics only. No new OperationRun creation, queueing, dedupe, lifecycle transition, summary-count writer, or notification behavior.
• Shared OperationRun UX contract/layer reused: OperationRunLinks, OperationRunUrl, related resource links, existing operation visibility, and existing operation detail pages.
• Delegated start/completion UX behaviors: N/A - no operation start.
• Local surface-owned behavior that remains: show Operation proof available, Operation proof unavailable, or authorized open operation link based on existing relations/links.
• Queued DB-notification policy: unchanged / N/A.
• Terminal notification path: unchanged.
• Exception required?: none.

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: no new provider seam.
• Boundary classification: platform-core proof/disclosure views over existing provider-backed evidence and audit records.
• Seams affected: display/routing over evidence snapshots, review packs, stored reports, OperationRuns, audit events, environment filters, and diagnostics disclosure.
• Neutral platform terms preserved or introduced: workspace, environment, evidence, proof, audit event, actor, action, target, outcome, time, export artifact, diagnostics, raw metadata.
• Provider-specific semantics retained and why: Microsoft/Entra/Intune terms may appear only where the underlying provider record or report already uses them. Do not surface raw provider IDs, Graph payloads, provider responses, or provider diagnostics by default.
• Why this does not deepen provider coupling accidentally: no Graph calls, provider contracts, provider connection changes, provider-shaped persistence, or provider taxonomy changes.
• Follow-up path: Environment Dashboard / Baseline Compare, Restore Safety Workflow, and Provider Readiness remain separate specs.

UI / Surface Guardrail Impact

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Evidence Overview page	yes	Native Filament page plus existing Blade composition	evidence/report viewer, proof path, filter chip	page, URL query, table state, derived payload	no	Existing route only
Workspace sidebar Evidence entry	yes	Native Filament navigation item	workspace hub navigation	route/link state only	no	Existing route only
Audit Log page	yes	Native Filament page plus existing Blade composition	audit event proof, selected detail, filter chip	page, URL query, selected event, table state	no	Existing route only
Evidence proof workbench	yes	Filament sections / page-local Blade	proof status and artifact links	page payload	no	Derived from repo truth
Audit proof workbench	yes	Filament sections / page-local Blade	actor/action/target/outcome/time	page payload and selected event	no	Derived from repo truth
Evidence/Audit tables	yes	existing Filament tables	secondary evidence/event inventory	table state	no	Tables remain available
Diagnostics disclosure	yes	collapsed/progressive disclosure only	support/raw detail	detail links/action visibility	no	Authorized and collapsed by default

Decision-First Surface Role

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Evidence Overview	Primary proof availability surface	Reviewer decides whether this workspace/environment scope contains usable proof	scope, evidence availability, freshness, evidence path, review pack/export/report availability, operation proof state	evidence inventory table, snapshot detail, review pack detail/download, stored report detail, operation detail, diagnostics	Primary because it answers proof readiness before artifact inspection	Follows evidence/proof path, not storage object browsing	Prevents scanning raw snapshots first
Audit Log	Primary audit event proof surface	Reviewer decides which event proves what happened	scope, actor, action, target, outcome, time, related record/proof, disclosure status	selected event context, related record, operation detail, raw metadata diagnostics	Primary because it proves actor/action/target/outcome/time	Follows disclosure, not raw event history	Prevents raw metadata from becoming first-read
Existing tables	Secondary Context	Operator scans inventory/history after proof summary is clear	concise rows, filters, sort, inspect/open affordance	row detail/source route	Secondary because tables support investigation/history	Keeps existing monitoring power	Reduces table-first dominance
Diagnostics disclosure	Tertiary Evidence / Diagnostics	Support/operator inspects technical data after proof path	collapsed availability only	raw metadata, technical IDs, support diagnostics where authorized	Not primary; diagnostics support proof	Preserves debug depth	Prevents default raw-console experience

Audience-Aware Disclosure

Surface	Audience Modes In Scope	Decision-First Default-Visible Content	Operator Diagnostics	Support / Raw Evidence	One Dominant Next Action	Hidden / Gated By Default	Duplicate-Truth Prevention
Evidence Overview	auditor, security reviewer, operator-MSP, manager, support reviewer	proof availability, evidence freshness, evidence snapshot, review pack/export/report state, operation proof state, scope	secondary inventory table and artifact detail links	raw snapshot item payloads, raw Graph/provider data, stack traces, debug metadata	open evidence snapshot or review/export proof where authorized	raw metadata, provider payloads, unsupported verification claims, unauthorized links	top workbench states proof state once; table adds inventory context
Audit Log	auditor, security reviewer, operator-MSP, support reviewer	actor, action, target, outcome, time, scope, related proof, disclosure status	selected-event readable context and related links	raw metadata, technical IDs, internal exception/debug data, provider payloads	inspect/open selected event or related proof where authorized	raw metadata, diagnostics, provider payloads, secrets	workbench states event proof once; selected detail adds proof/context

UI/UX Surface Classification

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Evidence Overview	Workbench / Evidence	Proof-first evidence workspace	Open evidence proof or review/export artifact	explicit primary proof link plus existing table row detail	existing table row URL remains	proof panel/table links	none introduced	/admin/evidence/overview	existing evidence/review/report/operation detail routes	active workspace, optional environment_id chip	Evidence / Proof	scope, snapshot state, freshness, review/export/report/operation proof state	none
Audit Log	Workbench / Audit	Event-proof audit history	Inspect event or open related proof	selected event panel and inspect action	existing inspect action	proof panel/table actions	none introduced	/admin/audit-log	same route with event query and related routes	active workspace, optional environment_id chip	Audit Event	actor, action, target, outcome, time, scope	none
Diagnostics disclosure	Diagnostics / Support Raw	Collapsed diagnostic context	Expand or open diagnostics if authorized	disclosure/detail action	N/A	below/inside proof panel	none	same pages	existing authorized detail surfaces	authorized-only label	Diagnostics	collapsed status only	none

Operator Surface Contract

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Evidence Overview	Auditor / MSP operator / security reviewer	Decide whether current scope has proof and where to open it	Workspace evidence proof workbench	What proof is available for this scope?	scope, evidence snapshot, freshness, review pack/export, stored report, operation proof, evidence path, unavailable states	raw snapshot payloads, provider responses, debug metadata, raw OperationRun context	proof availability, freshness, artifact availability, disclosure state	none on page by default	open evidence snapshot, open review pack/report/operation proof where authorized	none introduced
Audit Log	Auditor / governance admin / support reviewer	Decide which event proves what happened	Workspace audit event proof workbench	Which event proves what happened?	actor, action, target, outcome, time, scope, related proof, disclosure level	raw metadata, technical IDs, provider payloads, stack traces, debug metadata	event outcome, actor type, target type, scope, proof availability, disclosure state	none on page by default	inspect event, open related proof/record where authorized	none introduced

Proportionality Review

• New source of truth?: no.
• New persisted entity/table/artifact?: no. repo-truth-map.md is a Spec Kit preparation artifact, not runtime truth.
• New abstraction?: no public abstraction. Page-local private helpers are allowed only when they reduce Blade complexity and stay feature-local.
• New enum/state/reason family?: no domain state. Display states must derive from existing snapshot, review pack, stored report, operation, audit, policy, and capability truth.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: Existing Evidence and Audit pages must answer proof/disclosure questions without forcing raw table/metadata inspection first.
• Existing structure is insufficient because: Current pages expose tables and selected-event detail but do not consistently prioritize proof path, actor/action/target/outcome/time, availability, freshness, and disclosure hierarchy before raw metadata.
• Narrowest correct implementation: Refactor existing page layout and derived payloads, bind to existing sources, keep diagnostics collapsed, and add targeted tests/browser smoke.
• Ownership cost: Feature-local layout/payload tests, one Browser smoke, screenshots, and spec truth map. No durable backend model or new framework cost.
• Alternative intentionally rejected: new evidence engine, new audit ingestion, new compliance/certification layer, new export engine, raw log viewer, AI summary, broad design system work, or route replacement.
• Release truth: current-release runtime UI productization over existing evidence/audit foundations.

Compatibility posture

This feature assumes pre-production runtime posture. Backward compatibility, historical aliases, migration shims, dual-write logic, legacy route redirects, and legacy query aliases are out of scope. Existing legacy query aliases (tenant, tenant_id, managed_environment_id, environment, tenant_scope, tableFilters) must not be supported for Evidence Overview or Audit Log filtering.

Testing / Lane / Runtime Impact

• Test purpose / classification: Feature, Filament/Livewire/HTTP, Browser.
• Validation lane(s): confidence plus browser for critical workspace/environment UI/scope smoke.
• Why this classification and these lanes are sufficient: The change is user-facing Filament page productization with RBAC, evidence truth, audit event truth, scope, and disclosure behavior. Feature tests prove data/scope/action rules; Browser smoke proves rendered shell/filter/reload/disclosure/table hierarchy behavior.
• New or expanded test families: additions under tests/Feature/Monitoring, tests/Feature/Evidence, tests/Feature/Audit, tests/Feature/Navigation, and tests/Browser/Spec329EvidenceAuditDisclosureSmokeTest.php.
• Fixture / helper cost impact: reuse existing factories/helpers for EvidenceSnapshot, ReviewPack, StoredReport, OperationRun, AuditLog, workspace/environment session context, and navigation filter tests. Do not widen expensive defaults.
• Heavy-family visibility / justification: browser addition is explicit and named for Spec 329.
• Special surface test profile: global-context-shell, monitoring-state-page, and shared-detail-family.
• Standard-native relief or required special coverage: special coverage required for canonical filter, clear/reload, evidence path, event proof first-read, diagnostics hidden, RBAC action visibility, empty/non-empty states, and no platform-context tenant copy.
• Reviewer handoff: confirm diagnostics are collapsed, raw metadata hidden, RBAC actions hidden/disabled correctly, no false proof/certification claims, clean workspace entry, canonical filter, clear filter, cross-workspace guard, and table/history remain secondary context.
• Budget / baseline / trend impact: no expected material lane-cost shift beyond one targeted browser smoke.
• Escalation needed: document-in-feature if browser coverage becomes too expensive or requires fixture broadening.
• Active feature PR close-out entry: Smoke Coverage.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Feature/Monitoring tests/Feature/Evidence tests/Feature/Audit tests/Feature/Navigation/WorkspaceHubEnvironmentFilterContractTest.php tests/Feature/Navigation/WorkspaceHubClearFilterContractTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test tests/Browser/Spec329EvidenceAuditDisclosureSmokeTest.php --compact
  • cd apps/platform && ./vendor/bin/sail artisan test --filter='Evidence|AuditLog|WorkspaceHub|EnvironmentFilter|ClearFilter|LegacyTenant|Spec322' --compact
  • cd apps/platform && ./vendor/bin/sail pint --dirty
  • git diff --check

Summary

Productize TenantPilot's existing Evidence Overview and Audit Log into proof-first and disclosure-aware workspaces.

The pages must answer:

What proof is available for this scope?

and:

Which event proves what happened?

The implementation must lead with scope, proof availability, actor/action/target/outcome/time, evidence path, export/report availability where repo-supported, disclosure posture, and collapsed diagnostics. Existing tables remain available as secondary context.

Product Context

TenantPilot is a governance-of-record platform. Evidence snapshots, review packs, stored reports, OperationRuns, audit logs, and accepted-risk/review records turn technical state and operations into proof consumable by MSP operators, security reviewers, customer stakeholders, auditors, service delivery managers, and support.

Evidence-first does not mean raw evidence first. It means proof path, provenance, scope, freshness, and disclosure level appear before raw technical details.

Problem Statement

Evidence and Audit foundations exist, but the current UI can still drift into admin-tool patterns:

• Evidence Overview is still primarily a snapshot table.
• Audit event inspection can show technical metadata by default.
• Scope, freshness, review/export availability, OperationRun proof, and raw disclosure hierarchy are not first-read.
• Customer/auditor-safe proof language and operator-only diagnostics can be mixed too early.
• Unsupported immutability, verification, health, or certification claims must be prevented.

Product Decision

Evidence Overview and Audit Log are workspace-owned proof/disclosure surfaces.

They may optionally be filtered by Environment using:

?environment_id={id}

When filtered:

• Shell remains Workspace-only.
• Visible Environment filter chip appears.
• Clear filter returns to clean workspace-wide surface.
• Reload/back/forward remain aligned.

They are not Environment-owned pages, raw log viewers, compliance suites, export engines, or backend evidence/audit engines.

User Scenarios & Testing

User Story 1 - Evidence proof availability first-read (Priority: P1)

As an auditor or MSP operator, I can open Evidence Overview and immediately understand whether the current workspace or filtered environment has proof available, stale, incomplete, unavailable, or not generated.

Why this priority: Evidence Overview is the product proof surface. If it remains table-first, reviewers must reconstruct proof readiness from artifacts.

Independent Test: Render Evidence Overview with complete, stale, missing, and empty evidence fixtures. Assert the main proof question, evidence path, freshness/availability states, review/export/report/operation proof states, and secondary table are visible while raw metadata is absent by default.

Acceptance Scenarios:

1. Given a workspace has evidence snapshots, when the page loads cleanly, then the proof workbench shows proof availability and scope before the table.
2. Given a filtered environment has no evidence, when the page loads with environment_id, then the page shows a visible chip and honest no-evidence state without implying proof exists.
3. Given raw snapshot/provider/debug payloads exist in underlying records, when the page first renders, then those values are not visible by default.

User Story 2 - Audit event proof first-read (Priority: P1)

As a governance admin or security reviewer, I can open Audit Log and immediately see actor, action, target, outcome, time, scope, and related proof before raw metadata.

Why this priority: Audit Log is a core proof surface. Raw event history must not overpower who did what, when, against what target, and with what outcome.

Independent Test: Render Audit Log with selected and unselected event fixtures. Assert actor/action/target/outcome/time fields appear in the workbench/selected-event panel and raw metadata is collapsed/hidden by default.

Acceptance Scenarios:

1. Given audit events exist, when the page loads, then it answers which event proves what happened.
2. Given an event is selected through event, when it is visible in scope, then the selected panel shows actor, action, target, outcome, time, scope, and related proof before diagnostics.
3. Given a selected event is outside the active environment filter or workspace entitlement, then it is not displayed as selected proof.

User Story 3 - Scope and filter contract remains stable (Priority: P1)

As an operator, I can open clean and environment-filtered Evidence/Audit URLs without shell drift, remembered Environment fallback, legacy alias support, or cross-workspace leakage.

Why this priority: Specs 314-322 are prerequisite contracts. Proof and audit disclosure is unsafe if scope is ambiguous.

Independent Test: Open clean and ?environment_id= URLs for Evidence Overview and Audit Log, clear the filter, reload, use legacy aliases, and attempt cross-workspace environment IDs.

Acceptance Scenarios:

1. Given a clean URL, when Evidence or Audit loads, then the data is workspace-wide and no Environment chip appears.
2. Given a valid environment_id in the current workspace, when the page loads, then the chip appears and data is filtered where supported.
3. Given legacy aliases or table filters in the URL, when the page loads, then they do not create Environment filter state.
4. Given a cross-workspace Environment ID, when the page loads, then safe no-access / 404 is returned.

User Story 4 - RBAC-safe disclosure and proof links (Priority: P2)

As a least-privilege user, I only see evidence/audit/export/operation/diagnostic actions that I am allowed to access, and unavailable states do not leak sensitive raw data.

Why this priority: Evidence and audit content can contain sensitive operational proof, provider context, or support-only metadata.

Independent Test: Render the pages as users with and without evidence, audit, review pack, stored report, operation, and diagnostics capabilities. Assert protected actions are hidden/disabled and raw diagnostics remain hidden without support_diagnostics.view.

Acceptance Scenarios:

1. Given a user lacks audit.view, when they request Audit Log, then access is forbidden or denied according to existing workspace capability semantics.
2. Given a user lacks evidence/report/review/operation capability, when proof exists, then the proof state is unavailable or linkless without leaking records.
3. Given a user lacks diagnostics capability, when raw metadata exists, then raw/support disclosure is hidden by default and cannot be opened from the page.

Edge Cases

• No evidence snapshots exist in workspace.
• Evidence exists only in another workspace.
• Evidence snapshot exists but review pack does not.
• Review pack exists but is queued, generating, failed, expired, or unavailable.
• Stored reports exist only for report types the user cannot view.
• OperationRun proof relation is missing, unauthorized, or has no safe route.
• Audit events exist with null managed_environment_id and should appear only in workspace-wide Audit Log.
• Audit events have missing evolved actor/target/outcome fields but legacy metadata can derive readable labels.
• Selected audit event is invalid, unauthorized, outside filter, or cross-workspace.
• Raw metadata includes internal keys, provider payloads, stack trace-like text, or debug metadata.
• environment_id is malformed, array-valued, cross-workspace, or inaccessible.
• Legacy aliases appear with or without canonical environment_id.
• Existing route middleware or shell helpers must not force active Environment shell ownership on workspace hub pages.

Functional Requirements

• FR-001: Evidence Overview MUST have a proof-first layout before the evidence inventory/table.
• FR-002: Evidence Overview MUST show the stable question What proof is available for this scope?.
• FR-003: Evidence Overview MUST show scope, evidence snapshot state, freshness/availability, review pack/export availability, stored report/export availability where repo-supported, OperationRun proof availability, and evidence path.
• FR-004: Evidence Overview MUST show honest states only: evidence available, evidence incomplete, evidence unavailable, evidence stale, review pack unavailable, export available, export unavailable, not generated, not applicable, or unavailable.
• FR-005: Evidence Overview MUST keep the existing evidence inventory/table available as secondary context.
• FR-006: Audit Log MUST have an event-proof-first layout before the audit event table.
• FR-007: Audit Log MUST show the stable question Which event proves what happened?.
• FR-008: Audit Log default first-read MUST emphasize actor, action, target, outcome, time, and scope.
• FR-009: Audit Log selected/latest event proof panel MUST show related record/proof where repo-supported and authorized.
• FR-010: Audit Log MUST keep the existing audit event table available as secondary context.
• FR-011: Raw metadata, raw payloads, provider responses, stack traces, provider secrets, internal exception traces, debug metadata, raw OperationRun payloads, and raw audit metadata blobs MUST NOT be visible by default.
• FR-012: Diagnostics disclosure MUST be collapsed and capability-aware wherever exposed.
• FR-013: Evidence and Audit pages MUST show the shared disclosure hierarchy: decision/proof visible, evidence/event visible, diagnostics collapsed, raw/support hidden.
• FR-014: Visible runtime elements MUST be backed by repo-verified, foundation-real, derived from existing model, empty/unavailable state, or deferred future capability classification in repo-truth-map.md.
• FR-015: No visible UI copy may claim immutable, certified, legally attested, tamper-proof, auditor-approved, compliance-ready, fully verified, 100 percent verified, or health-complete states unless repo truth explicitly proves them.
• FR-016: Clean Evidence and Audit URLs MUST be workspace-wide, with Workspace shell only and no Environment chip.
• FR-017: Filtered Evidence and Audit URLs MUST use only environment_id, show the visible Environment chip, filter data where supported, and keep Workspace shell ownership.
• FR-018: Clear filter MUST return to a clean workspace URL and clear URL, Livewire, Filament table, deferred table, and persisted session Environment-like state.
• FR-019: Legacy aliases tenant, tenant_id, managed_environment_id, environment, tenant_scope, and tableFilters as URL source MUST NOT create Environment filter state.
• FR-020: Cross-workspace or unauthorized environment_id MUST return safe no-access / 404 and MUST NOT switch Workspace.
• FR-021: Evidence link/actions MUST respect evidence.view, EvidenceSnapshotPolicy, environment entitlement, and workspace membership.
• FR-022: Review pack/open/download link/actions MUST respect review_pack.view, ReviewPackPolicy, and existing download authorization.
• FR-023: Stored report link/actions MUST respect existing report-type capabilities and StoredReportResource visibility.
• FR-024: Audit access MUST respect workspace membership and audit.view.
• FR-025: Operation proof links MUST route through existing operation link helpers and authorization.
• FR-026: Diagnostics/raw metadata access MUST require support_diagnostics.view or stricter existing support/raw capability.
• FR-027: Unauthorized actions MUST be hidden, disabled with existing convention, or replaced with safe unavailable state.
• FR-028: No migration, seeder, package, env var, queue, scheduler, storage, deployment asset, compatibility route, or legacy alias support may be introduced unless spec/plan/tasks are updated before implementation.
• FR-029: Filament v5 and Livewire v4.0+ patterns MUST be preserved. No Filament v3/v4 APIs or Livewire v3 references are allowed.
• FR-030: No Graph calls or provider API calls may occur during page render.

Non-Functional Requirements

• NFR-001: Workspace and Environment isolation MUST remain enforceable in queries and authorization.
• NFR-002: Evidence/audit pages MUST remain DB-only render paths over existing persisted records.
• NFR-003: Page copy MUST use customer/auditor-safe disclosure language and avoid platform-context tenant wording.
• NFR-003a: Dynamic Environment display names are data and MAY contain Tenant; static platform-context copy MUST avoid retired tenant-first wording.
• NFR-003b: Empty primary evidence snapshots MUST use product-safe proof language, show Proof incomplete, explain that the primary evidence snapshot is empty, and make supporting proof impact explicit without exposing implementation-heavy artifact-row language.
• NFR-004: Page layouts MUST prefer native Filament components and shared primitives before custom Blade/Tailwind.
• NFR-005: The change MUST not create a new cross-surface disclosure framework, proof state engine, or status taxonomy.
• NFR-006: Browser verification MUST cover clean, filtered, clear, reload, non-empty, empty, diagnostics collapsed, table secondary, and tenant-copy guard states.

Out Of Scope

• New evidence backend.
• New audit event ingestion.
• New immutable storage implementation.
• New legal attestation/certification engine.
• New compliance framework mapping.
• New external auditor portal.
• New export pipeline.
• New report generation engine.
• New retention/hold system.
• AI summarization.
• Customer Review Workspace redesign.
• Operations Hub redesign.
• Governance Inbox redesign.
• New migrations by default.
• New packages, env vars, queues, scheduler, storage, deployment assets, or external services.

Required Repo Truth Map

Before runtime changes, repo-truth-map.md MUST exist under this spec directory and map each UI element to:

• UI element.
• Surface.
• Source model/service/page.
• Status source.
• Authorization/capability.
• Workspace/Environment scope.
• OperationRun/evidence/audit/export link.
• Fallback/empty state.
• Classification.

Required data areas:

• Evidence Snapshots.
• Review Packs.
• Stored Reports / export artifacts.
• OperationRuns.
• Audit Log events.
• Actor/action/target/outcome/time fields.
• Risk/Decision links if present.
• Customer Review Workspace evidence links.
• Governance Inbox evidence links.
• Operations proof links.
• Environment filter state.
• Diagnostics/raw metadata availability.

Acceptance Criteria

Evidence Overview

• Evidence Overview has proof-first layout.
• Main proof question is visible.
• Evidence path is visible.
• Evidence snapshot state is visible.
• Review pack/export state is visible where repo-supported.
• Stored report/export state is visible where repo-supported.
• OperationRun proof state is visible where repo-supported.
• Evidence inventory/table remains available as secondary context.
• Raw metadata is hidden by default.

Audit Log

• Audit Log has event-proof-first layout.
• Main audit proof question is visible.
• Actor/action/target/outcome/time are first-read.
• Selected/latest event proof panel exists.
• Audit event table remains available as secondary context.
• Raw metadata is hidden by default.

Disclosure Safety

• Diagnostics are collapsed by default.
• Raw payloads are hidden by default.
• Provider secrets are not visible.
• Internal exception/debug text is not visible.
• No false immutability/certification/health/compliance claims are introduced.
• No false green success state is introduced.

Scope

• Clean URLs are workspace-wide.
• Shell is Workspace-only.
• Environment filter uses environment_id.
• Visible Environment chip appears when filtered.
• Clear filter works.
• Reload after clear is safe.
• Legacy aliases do not create filter state.
• Cross-workspace Environment is rejected.

RBAC

• Unauthorized user cannot access protected evidence/audit data.
• Unauthorized actions are hidden/disabled/unavailable.
• Evidence export/open respects capability.
• Audit detail access respects capability.
• Diagnostics/raw metadata access respects capability.
• OperationRun proof access respects capability.

UI / Visual

• Layout uses Spec 325 direction without treating target images as runtime truth.
• Filament light mode remains readable.
• No heavy one-off CSS.
• Right-side proof/disclosure panel exists on desktop where suitable.
• Tables are not the only default experience.
• Page remains responsive enough for Filament shell.
• Native Filament components are preferred where suitable.

Tests / Validation

• Repo truth map exists.
• Required Feature tests pass.
• Required Browser smoke passes.
• Relevant Spec 314-322 guards still pass.
• pint --dirty passes.
• git diff --check passes.
• No broad rebaseline.
• Full suite status is honestly reported if run/not run.

Success Criteria

• SC-001: A reviewer can determine proof availability on Evidence Overview without opening raw artifact details.
• SC-002: A reviewer can identify actor/action/target/outcome/time on Audit Log before seeing technical metadata.
• SC-003: Browser smoke confirms clean, filtered, clear/reload, non-empty, empty, diagnostics-collapsed, table-secondary, and tenant-copy guard states.
• SC-004: Tests prove raw diagnostic strings are absent by default.
• SC-005: No migration, package, env var, queue, scheduler, storage, deployment asset, compatibility route, or legacy alias support is added.

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

Browser Verification Required

Screenshots may be saved under:

specs/329-evidence-audit-log-disclosure-productization/artifacts/screenshots/

Required screenshots:

• evidence-overview-proof-workbench.png
• evidence-overview-filtered.png
• audit-log-event-proof-workbench.png
• audit-log-filtered.png

Optional screenshots:

• evidence-overview-empty.png
• audit-log-empty.png
• evidence-overview-after-clear.png
• audit-log-after-clear.png

Risks

• Existing Audit Log route currently includes environment-context middleware; implementation must verify it does not force Environment shell ownership or remembered fallback for a workspace hub.
• Evidence route is duplicated in routes/web.php; implementation may leave it alone if harmless or document a bounded cleanup task if needed.
• Audit selected-event detail currently renders Technical metadata directly; moving it behind disclosure must preserve authorized proof inspection.
• Evidence proof path may not have all links for every environment. Unsupported links must render unavailable or be omitted.
• Browser smoke may need focused fixtures to avoid broad lane cost.

Assumptions

• No production data migration compatibility is needed under the repo's pre-production posture.
• Evidence and audit data already persisted in the repo are sufficient for v1 productization.
• Existing policies/capabilities are authoritative; new capability strings are not expected.
• EN/DE localization is added only if implementation follows existing stable-copy localization patterns for these pages.

Open Questions

No open question blocks implementation. Implementation must update this spec/plan/tasks first if repo truth shows a required backend, schema, capability, export, or route contract change.

Follow-Up Spec Candidates

• Spec 330 - Environment Dashboard / Baseline Compare Productization.
• Spec 331 - Restore Safety Workflow Productization.
• Spec 332 - Provider Readiness Productization.

Do not start these inside Spec 329.