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
- [x] Existing page changed
- [ ] New page/route added
- [x] Navigation changed
- [ ] Filament panel/provider surface changed
- [ ] New modal/drawer/wizard/action added
- [x] New table/form/state added
- [ ] Customer-facing surface changed
- [ ] Dangerous action changed
- [x] Status/evidence/review presentation changed
- [x] 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`
  - [x] 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:

```text
What proof is available for this scope?
```

and:

```text
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:

```text
?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:

```text
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.