TenantAtlas/specs/412-pilot-readiness-remediation-pack/spec.md

Feature Specification: Spec 412 - Pilot Readiness Remediation Pack

Feature Branch: 412-pilot-readiness-remediation-pack Created: 2026-06-24 Status: Draft Input: User-provided "Spec 408 - Pilot Readiness Remediation Pack" draft from /Users/ahmeddarrazi/.codex/attachments/3275d3b5-1314-4fca-8943-ba1e5a70030b/pasted-text.txt, Spec 407 full browser/UX/runtime audit findings, docs/product/spec-candidates.md, docs/product/roadmap.md, and the Product Surface Contract.

Preparation Note

• Numbering deviation: The supplied draft names Spec ID 408. Existing local/remote branch 408-review-evidence-decision already owns a different Spec Kit package on another branch, and 409 through 411 are also reserved by existing branches. This package uses the first verified free number, 412, to avoid overwriting or duplicating existing work.
• Selected candidate: Pilot Readiness Remediation Pack.
• Source location: Direct user-provided draft in the current request; source finding set comes from Spec 407.
• Why selected: docs/product/spec-candidates.md reports no safe automatic next-best-prep target, but the operator supplied a concrete manual follow-through candidate that closes the bounded P1/P2/P3 findings from Spec 407.
• Why close alternatives were deferred:
  • management-report-pdf-staging-runtime-validation remains a staging/Dokploy runtime validation lane, not this local pilot-readiness remediation.
  • governance-artifact-lifecycle-retention-runtime is separate artifact lifecycle work and must not be hidden inside a report/UI remediation pack.
  • Provider readiness/onboarding productization is optional P2 roadmap work and broader than the readonly no-access clarity issue.
  • A new full browser audit is explicitly out of scope; Spec 412 requires focused browser proof only.
• Roadmap relationship: supports near-term controlled pilot and customer-facing hardening by removing concrete browser-audit exclusions after Spec 407.
• Completed-spec guardrail:
  • Spec 407 exists as a preparation package with checked readiness checklist history and is used only as source context.
  • Specs 400-406 carry implementation/validation/close-out history and remain read-only context.
  • No completed spec may be rewritten, normalized, unchecked, or stripped of validation, smoke, browser, screenshots, or review evidence.
• Smallest viable implementation slice: remediate only these four Spec 407 findings on existing surfaces: management PDF ready/download surfacing, operations route load completion, finding internal hash demotion, and readonly provider-connection no-access clarity.

Spec Candidate Check (mandatory - SPEC-GATE-001)

• Problem: Spec 407 found that TenantPilot can enter a controlled pilot only with exclusions because ready management PDFs are not surfaced coherently, operations routes timed out in browser navigation, finding detail exposes raw internal hashes by default, and readonly provider-connection denial copy is confusing.
• Today's failure: Operators can see contradictory report/PDF states, browser audit cannot reliably complete operations navigation, default finding detail includes technical identifiers that look like product content, and an authenticated readonly actor can see a login-style/no-membership outcome instead of a clear no-access result.
• User-visible improvement: Pilot operators see ready/download states for existing management PDFs, can navigate operations pages without browser timeouts, get human-readable finding detail by default, and receive clearer access-denied outcomes without weakened authorization.
• Smallest enterprise-capable version: One remediation pack over existing review/report, operations, finding detail, and provider-connection no-access surfaces with targeted Pest coverage and focused browser proof.
• Explicit non-goals: No new report template, PDF renderer, PDF lifecycle architecture, report workflow, review-pack concept, customer review surface, operations dashboard, OperationRun architecture, finding taxonomy, provider onboarding flow, legal hold, purge/export governance, staging/Dokploy validation, JSONB migration, full browser audit, commercial lifecycle, or support desk integration.
• Permanent complexity imported: No new persisted entities, status families, enums, source-of-truth objects, broad abstractions, navigation branches, or product concepts are approved. The future implementation may add focused tests and small local helpers only if they replace duplicated logic or keep existing truth readable.
• Why now: Spec 407 returned PASS WITH CONDITIONS for controlled pilot and customer-facing hardening: no until these bounded findings are addressed or explicitly accepted.
• Why not local: The issues span existing report/PDF state truth, browser-route readiness, customer/operator disclosure, and authorization UX; the pack needs one accountable remediation report rather than unrelated local fixes.
• Approval class: Core Enterprise.
• Red flags triggered: UI surface changes, report/download authorization risk, customer-safe boundary risk, OperationRun diagnostics exposure, and test/browser-lane cost.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexitaet: 1 | Produktnaehe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve.

Red Flag Defense

This spec is deliberately constrained to four confirmed Spec 407 findings. It improves readiness without broadening architecture, adding pages, adding product states, or replacing completed report/operations/provider foundations. The higher test and browser proof cost is justified because the source findings are browser-readiness and customer-safe trust issues.

Spec Scope Fields (mandatory)

• Scope: canonical-view and workspace/environment-scoped admin surfaces.
• Primary Routes:
  • Review pack detail and actions through ReviewPackResource and ViewReviewPack.
  • Signed review pack download/report routes: /admin/review-packs/{reviewPack}/download, /admin/review-packs/{reviewPack}/report, /admin/management-report-pdfs/{storedReport}/download.
  • Operations index/detail routes: /admin/workspaces/{workspace}/operations, /admin/workspaces/{workspace}/operations/{run}.
  • Finding detail route through FindingResource.
  • Provider connections list/detail/create no-access behavior through /admin/provider-connections....
• Data Ownership: existing workspace-owned and managed-environment-owned records only: ReviewPack, StoredReport, EnvironmentReview, OperationRun, Finding, and ProviderConnection. No new tables or ownership model changes.
• RBAC: preserve workspace membership, managed-environment entitlement, capability-first checks, signed URL authorization, non-member deny-as-not-found where appropriate, and member-but-missing-capability 403 semantics.
• Default filter behavior when tenant-context is active: operations and provider/finding/report surfaces must preserve existing explicit workspace/environment filters and must not introduce hidden global context.
• Explicit entitlement checks preventing cross-tenant leakage: every direct record or download access must resolve through existing workspace/environment ownership and policy/service checks before output is shown or served.

No Legacy / No Backward Compatibility Constraint (mandatory)

TenantPilot is pre-production unless this spec explicitly records a compatibility exception.

• Compatibility posture: canonical correction of existing behavior.
• Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?: no.
• Why clean replacement is safe now: the remediation only changes existing pre-production UI/state behavior and tests; no production data or public API compatibility is promised.

UI Surface Impact (mandatory - UI-COV-001)

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: review pack detail management PDF action area; management PDF signed download route; operations index/detail; finding detail; provider-connection no-access outcome.
• Current or new page archetype: existing surfaces only. Review pack is Report/Receipt; operations index/detail is Technical Annex/Receipt for immutable run truth; finding detail is Decision/Secondary Context; provider-connection no-access is Settings/authorization outcome.
• Design depth: Domain Pattern Surface for report/finding/provider pages; Internal/Hidden or Technical Annex for operations detail.
• Repo-truth level: repo-verified.
• Existing pattern reused: Filament resources/pages/actions, ManagementReportPdfService, OperationRunLinks, OperationUxPresenter, BadgeRenderer, UiEnforcement / WorkspaceUiEnforcement, existing policies/middleware, existing signed route controllers.
• New pattern required: none.
• Screenshot required: yes, focused browser proof screenshots or browser records for the four affected findings.
• Page audit required: no new full audit; focused page proof only.
• Customer-safe review required: yes for review/report and finding hash demotion.
• Dangerous-action review required: yes only to confirm no destructive/high-impact action is introduced or weakened; management PDF generation remains existing high-impact/queued behavior with confirmation and authorization.
• 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 new reachable UI surface; existing surface behavior is remediated and proof is captured in this spec package's implementation report
• No-impact rationale when applicable: N/A.

Product Surface Impact (mandatory for UI-affecting specs)

Reference: docs/product/standards/product-surface-contract.md.

• Product Surface Contract applies?: yes; rendered UI/report/download/authorization behavior changes are in scope.
• Page archetype:
  • Review pack detail / report action area: Report Page / Receipt Page.
  • Operations index/detail: Technical Annex Page / Receipt Page.
  • Finding detail: Decision Page / Secondary Context.
  • Provider-connection no-access: Settings Page denial outcome.
• Primary user question:
  • Review pack: Is the management-ready output ready to open/download, or does it need generation?
  • Operations: What happened, can I trust the run state, and can I navigate without runtime failure?
  • Finding detail: What is the human-readable risk and next action?
  • Provider no-access: Am I blocked because I lack access, without implying I am unauthenticated?
• Primary action:
  • Ready PDF exists: Download/Open management PDF.
  • No ready PDF exists: Generate management PDF only when allowed by existing readiness and authorization rules.
  • Operations detail: Refresh or follow the existing primary next action, without blocking page readiness.
  • Finding detail: act on the finding workflow action already authorized for the user.
  • Provider no-access: return to safe authorized context or accept the no-access result.
• Surface budget result: pass expected. Operations technical pages may use Technical Annex depth; no product-facing page may show raw identifiers by default.
• Technical Annex / deep-link demotion: raw fingerprints, scope hashes, internal OperationRun proof links, raw evidence IDs, source keys, payloads, provider payloads, and diagnostic logs must be hidden, collapsed, or moved to support/operator-only detail when not needed for the first decision.
• Canonical status vocabulary: use Ready, Needs attention, Blocked, Running, Failed, Expired, Not configured, Unknown, Historical, Superseded, and allowed severity values only for top-level product states.
• Visible complexity impact: decreased or neutral. The pack must remove contradictory report/PDF cues and demote technical noise.
• Product Surface exceptions: none approved.

Browser Verification Plan (mandatory)

• Browser proof required?: yes.
• No-browser rationale: N/A.
• Focused path when required:
  1. Review pack with ready stored management PDF shows ready/download state.
  2. Review pack without ready PDF or with failed/missing/unavailable PDF shows generate/unavailable state correctly.
  3. Authorized management PDF download/open works.
  4. Unauthorized or unsigned report/PDF path remains blocked.
  5. Operations index completes browser navigation without timeout.
  6. Operations detail completes browser navigation without timeout.
  7. Finding detail default view no longer prominently exposes raw hashes.
  8. Readonly provider-connection route produces safe/clear no-access behavior.
• Primary interaction to execute: navigation, table/list open, action state inspection, signed download/open, direct unauthorized access, default detail inspection.
• Console, Livewire, Filament, network, and 500-error checks: planned.
• Full-suite failure triage: unrelated full-browser failures may be documented only if focused affected proof is green and no touched route fails.

Human Product Sanity Check (mandatory)

• Required?: yes.
• No-human-sanity rationale: N/A.
• Reviewer questions: purpose clear, one dominant next action, technical details demoted, status labels canonical, complexity not worse, customer/operator trust acceptable.
• Planned result location: specs/412-pilot-readiness-remediation-pack/implementation-report.md during implementation close-out.

Product Surface Merge Gate Checklist (mandatory)

• No-legacy posture or approved exception recorded.
• Product Surface Impact is completed.
• Browser proof is required.
• Human Product Sanity is required.
• Product Surface exceptions are documented as none.
• Implementation report will state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, tests/browser result, deployment impact, visible complexity outcome, and no completed-spec rewrite assertion.

Cross-Cutting / Shared Pattern Reuse

• Cross-cutting feature?: yes.
• Interaction class(es): report/download action links, status messaging, technical detail disclosure, authorization/no-access messaging, OperationRun navigation, browser proof reporting.
• Systems touched: ReviewPackResource, ViewReviewPack, ManagementReportPdfService, signed report controllers, operations pages, OperationRunLinks, FindingResource, ProviderConnectionResource, policies/middleware, localization/copy where relevant, and existing test helpers.
• Existing pattern(s) to extend: native Filament actions/infolists, existing BadgeRenderer domains, OperationRun URL helpers, ManagementReport PDF service decisions, existing authorization helpers.
• Shared contract / presenter / builder / renderer to reuse: OperationUxPresenter, OperationRunLinks, BadgeRenderer, UiEnforcement / WorkspaceUiEnforcement, existing report/PDF services and signed URL generation.
• Why the existing shared path is sufficient or insufficient: current repo surfaces already contain the needed report, operations, finding, and provider foundations; the defects are local behavior and proof gaps, not missing architecture.
• Allowed deviation and why: none approved. Any implementation-time deviation must be documented as a bounded Product Surface exception before runtime UI edits continue.
• Consistency impact: ready/download/generate copy, signed download behavior, report state truth, operations route readiness, technical annex disclosure, and no-access semantics must stay consistent across tests, browser proof, and implementation report.
• Review focus: verify no new local product state, new navigation, duplicate report state, ad-hoc operation link, or raw diagnostic default content is introduced.

OperationRun UX Impact

• Touches OperationRun start/completion/link UX?: yes, but only existing management PDF generation and operations navigation/link readiness are in scope.
• Shared OperationRun UX contract/layer reused: existing OperationUxPresenter, OperationRunLinks, OperationRun lifecycle services, and operations pages.
• Delegated start/completion UX behaviors: existing queued toast, run link, artifact link, run-enqueued browser event, dedupe/block messaging, and tenant/workspace-safe URL resolution must remain delegated to shared paths.
• Local surface-owned behavior that remains: initiation inputs and local action visibility only.
• Queued DB-notification policy: no new opt-in; existing policy remains.
• Terminal notification path: central lifecycle mechanism remains.
• Exception required?: none.

Provider Boundary / Platform Core Check

• Shared provider/platform boundary touched?: yes, bounded provider-connection no-access behavior and finding/provider diagnostic disclosure only.
• Boundary classification: mixed. Provider connection remains provider-owned at integration detail, while no-access and workspace/environment authorization are platform-core.
• Seams affected: provider-connection routes/pages/guards, managed-environment membership/capability checks, provider diagnostic labels if rendered.
• Neutral platform terms preserved or introduced: workspace, managed environment, provider connection, no access, permission, membership, readiness.
• Provider-specific semantics retained and why: Microsoft provider-specific details remain only where the existing provider connection requires them.
• Why this does not deepen provider coupling accidentally: the spec does not add provider types, provider registries, target-scope taxonomies, or new provider runtime behavior.
• Follow-up path: none for this pack; broader provider readiness/onboarding productization remains separate.

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
Review pack detail management PDF state/action	yes	Native Filament + existing report services	reports, action links, signed downloads	detail, action state	no	existing surface only
Operations index/detail route readiness	yes	Native Filament Page + existing OperationRun helpers	monitoring, OperationRun links	page, detail, route load	no	existing surface only
Finding detail hash demotion	yes	Native Filament infolist	technical evidence disclosure	detail	no	existing surface only
Provider-connection no-access outcome	yes	Filament resource/middleware/policy behavior	authorization messaging	route, page/redirect outcome	no	existing surface only

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
Review pack detail PDF action area	Secondary Context Surface	Decide whether to open/download ready management output or generate it	ready/missing/failed/blocked PDF state and one dominant action	operation/run proof and artifact internals	secondary because review workflow owns broader decision	report consumption	removes contradictory generate/download search
Operations index/detail	Tertiary Evidence / Diagnostics Surface	Inspect operational proof when troubleshooting	run identity, status, outcome, human reason	raw context, support diagnostics, related internals	not primary; evidence/proof support	monitoring/audit	page readiness prevents audit blockers
Finding detail	Secondary Context Surface	Triage finding and next action	status, severity, human scope, recommendation	fingerprint/scope hashes and raw support detail	secondary decision detail	finding governance	demotes support identifiers
Provider-connection no-access	Secondary Context Surface	Understand blocked access safely	clear no-access reason or safe denied outcome	none	not primary; prevents confusion	provider setup/readiness	avoids misleading login/no-membership prompt

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
Review pack detail	operator-MSP, customer-safe output reader where authorized	report readiness, download/generate availability, customer-safe report context	report lifecycle and active run if needed	raw file path, stack traces, internal payloads	Download/Open or Generate based on state	raw report artifact internals	one report/PDF truth wins
Operations pages	operator-MSP, support-platform	operation status/outcome and trusted navigation	filters, related links, support diagnostics	raw context/failures/logs	Refresh or existing primary run action	raw payload/log details	one run state summary
Finding detail	operator-MSP, customer/read-only where applicable, support-platform	title, severity, human scope, status, next action	evidence/proof links	fingerprint, scope hash, source fingerprint	existing finding workflow action	hashes/raw support detail	no duplicate technical summary
Provider no-access	readonly, unauthorized, operator-MSP	blocked access meaning	permission/membership explanation where safe	record existence, provider payload	safe return/no-access acknowledgement	record existence for non-members	no login-vs-auth ambiguity

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
Review pack detail	Record / Detail / Edit	Report / Receipt detail	Download ready management PDF or generate when allowed	detail header action	N/A	header secondary/More	none introduced	existing review pack list	existing review pack view	workspace/environment	Review Pack	pack readiness and PDF state	none
Operations index	Monitoring / Queue / Workbench	History / Audit Surface	Open or filter run	row/open link	existing	related navigation	none	/admin/workspaces/{workspace}/operations	/admin/workspaces/{workspace}/operations/{run}	workspace/environment filter	Operation	status/outcome/load result	technical surface depth allowed
Finding detail	Record / Detail / Edit	Decision detail	resolve/assign/exception existing action	detail view	N/A	More/header	existing confirmation rules	existing findings list	existing finding view	workspace/environment	Finding	status/severity/human scope	none
Provider no-access	Settings Page	Authorization outcome	understand denied access	route outcome	N/A	N/A	none	/admin/provider-connections	/admin/provider-connections/{record}	workspace/environment	Provider Connection	no-access reason	none

UI Action Matrix

Surface	Header Actions	Row Actions	Bulk Actions	Empty-State CTA	Primary Action	Secondary Actions	Destructive Actions	Technical / Audit Actions
Review pack detail PDF action area	Existing detail header action area owns management PDF state; ready PDF makes Download/Open primary, generation stays available only when allowed	N/A	N/A	N/A	Download/Open management PDF when ready; Generate management PDF only when no ready PDF exists and generation is allowed	Existing report preview/download/regenerate actions stay secondary or grouped according to current ReviewPackResource contract	None new; existing expire/regenerate/generation safeguards stay confirmed and authorized	OperationRun proof and artifact internals stay secondary/internal
Operations index	Existing list header keeps scope/filter/return context only	Existing row/open affordance opens canonical run detail	None	Existing operations empty state remains explanatory and non-mutating	Open/filter operation run context without blocking page readiness	Related navigation and filters remain secondary	None	Raw context, failures, support diagnostics, and proof details stay technical/secondary
Finding detail	Existing detail header owns authorized finding workflow actions	N/A	N/A	N/A	Existing authorized finding workflow action remains primary	Related evidence/proof links and diagnostics stay secondary	Existing destructive/governance-changing actions keep confirmation and authorization	Fingerprint, scope hash, source fingerprint, detector/source keys, and raw support detail move out of default body
Provider-connection no-access	N/A for denied outcome; authorized provider resource header remains unchanged	N/A for denied outcome	N/A	N/A	Safe no-access result or safe return path for authenticated unauthorized actor	Permission/membership explanation where safe	None	Record existence, provider payload, and internal provider diagnostics remain hidden for non-members/cross-workspace actors

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
Review pack detail PDF action area	Workspace admin / operator	consume or generate management output	Report / Receipt	Is a valid management PDF ready?	ready/missing/failed/blocked state and action	active run, file internals	report lifecycle, file availability, authorization	TenantPilot/report generation only	Download/Open or Generate	none new
Operations index/detail	Workspace admin / support operator	inspect run proof	Technical Annex / Receipt	Did this operation complete and can I trust it?	run status/outcome/reason	raw context, support diagnostics	execution outcome, lifecycle	none for rendering	Refresh/open related	existing only
Finding detail	Tenant operator	triage finding	Decision detail	What should I do about this finding?	title, severity, human scope, status, next action	hashes, raw source fingerprints	finding status, severity, responsibility	existing finding workflow	existing workflow action	existing only
Provider no-access	readonly / limited actor	understand blocked provider access	Settings denial	Why can I not open this provider surface?	safe no-access message	none	capability/membership outcome	none	safe return / no access	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no.
• New persisted entity/table/artifact?: no.
• New abstraction?: no approved.
• New enum/state/reason family?: no.
• New cross-domain UI framework/taxonomy?: no.
• Current operator problem: pilot-readiness blockers on existing surfaces create false or confusing product signals.
• Existing structure is insufficient because: current local behavior shows contradictory PDF state, browser-timeout risk, technical identifiers in default detail, and unclear no-access outcome.
• Narrowest correct implementation: targeted fixes in existing resources/pages/controllers/services and focused tests/browser proof.
• Ownership cost: small test and proof cost; no new long-term conceptual system.
• Alternative intentionally rejected: broad report architecture rewrite, operations dashboard redesign, new finding taxonomy, provider onboarding productization, or another full browser audit.
• Release truth: current-release pilot hardening.

Compatibility posture

This feature assumes a pre-production environment. Backward compatibility, legacy aliases, migration shims, duplicate UI, and compatibility-specific fixtures are out of scope.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Feature, Filament/Livewire, authorization, and focused Browser.
• Validation lane(s): fast-feedback, confidence, browser; PostgreSQL lane only if implementation touches database constraints or PostgreSQL-specific query behavior, which is not expected.
• Why this classification and these lanes are sufficient: the defects are rendered state, route readiness, authorization outcomes, signed downloads, and browser load behavior over existing persistence.
• New or expanded test families: no broad new family. Add focused tests near existing ReviewPack, Monitoring/Operations, Finding, ProviderConnections, and browser smoke coverage.
• Fixture / helper cost impact: reuse existing factories and helpers such as createUserWithTenant, spec379CurrentReadyPack, spec379ReadyManagementPdf, operations factories, and provider/finding helpers. Avoid new global seeds.
• Heavy-family visibility / justification: browser proof is explicit and focused because the source findings were browser-audit findings.
• Special surface test profile: shared-detail-family for review/finding, monitoring-state-page for operations, exception-coded-surface for provider no-access.
• Standard-native relief or required special coverage: ordinary Filament/Pest tests for state and authorization; focused browser proof for rendered route completion and visual/default content.
• Reviewer handoff: verify lane fit, no hidden full-audit claim, no broad fixtures, no new route/page/surface, and no completed-spec rewrite.
• Budget / baseline / trend impact: none expected; if operations route load fix changes query cost materially, document in implementation report.
• Escalation needed: document-in-feature for any bounded residual P2/P3; follow-up-spec only if remediation discovers structural report/operations/provider defects beyond this pack.
• Active feature PR close-out entry: Product Surface / Focused Browser Proof / Pilot Readiness Remediation.
• Planned validation commands:
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=ReviewPack
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=ManagementReport
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=OperationRun
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=Operations
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=Finding
  • cd apps/platform && ./vendor/bin/sail artisan test --filter=ProviderConnection
  • focused browser smoke for the eight proof paths listed in this spec

User Scenarios & Testing (mandatory)

User Story 1 - Ready Management PDF Is Surfaced Correctly (Priority: P1)

A workspace admin opens an existing review pack where a ready management PDF already exists and sees a ready/download/open state instead of a primary "Generate management PDF" action.

Why this priority: Spec 407 classified this as the main P1 blocking customer-facing hardening.

Independent Test: Create a ready review pack with a ready StoredReport::REPORT_TYPE_MANAGEMENT_REPORT_PDF, render the review pack detail, and assert the primary state is ready/download while generate is not the primary action.

Acceptance Scenarios:

1. Given a ready stored management PDF exists for the current review pack, When an authorized admin opens the review pack detail, Then the primary action is download/open and not generate.
2. Given no ready PDF exists, When generation is allowed, Then the generate action remains available and accurately labeled.
3. Given the PDF record is failed, missing, expired, or inconsistent with file storage, When the page renders, Then the page shows failed/unavailable/inconsistent state and does not serve it as ready.
4. Given an unauthorized or cross-workspace actor requests the management PDF directly, When authorization is evaluated, Then the download remains blocked and no file data leaks.

---

User Story 2 - Operations Routes Complete Browser Navigation (Priority: P1)

A workspace admin or support operator opens the operations index and an operation detail route, and both pages complete usable browser navigation without 500s, fatal Livewire/Filament errors, or indefinite readiness blockers.

Why this priority: Spec 407 observed browser navigation timeouts for operations routes even though no current 500 was reproduced.

Independent Test: Render operations index/detail with representative completed/failed/running runs and assert DB-only behavior, scoped visibility, bounded query/load behavior, and focused browser navigation completion.

Acceptance Scenarios:

1. Given an entitled workspace admin, When they navigate to /admin/workspaces/{workspace}/operations, Then navigation completes and the page is usable.
2. Given an entitled actor opens /admin/workspaces/{workspace}/operations/{run}, When the run belongs to their workspace/entitled environment, Then navigation completes and the detail renders.
3. Given the page has polling or long-running Livewire requests, When the browser audit waits for page readiness, Then readiness is detectable and does not time out because of indefinite requests.
4. Given historical OperationRun route errors existed in browser logs, When the current focused proof runs, Then any current error is fixed or the historical condition is documented as not reproducible.

---

User Story 3 - Finding Detail Demotes Internal Hashes (Priority: P2)

A tenant operator opens a finding detail page and sees human-readable risk, affected scope, evidence, and next action by default while raw fingerprints and scope/source hashes are hidden, collapsed, or support-only.

Why this priority: raw hashes in default body weaken customer/operator trust and violate the Product Surface Contract's technical-demotion rule.

Independent Test: Render a finding with fingerprint/source hash fields and assert the default body does not prominently show raw hash labels or values while authorized support/operator diagnostics can still access them when needed.

Acceptance Scenarios:

1. Given a finding contains fingerprint and scope/source hash values, When an ordinary operator opens the default detail view, Then those values are not prominent default body content.
2. Given support diagnostics need hash values, When an authorized support/operator opens the technical detail disclosure, Then the values remain accessible without leaking into customer/read-only default content.
3. Given a customer-readable finding/report surface exists, When it renders the finding, Then raw hashes are absent unless an existing explicit contract permits them.

---

User Story 4 - Readonly Provider No-Access Is Clear And Safe (Priority: P3)

A readonly or limited actor who is authenticated but not entitled to a provider-connection route receives a clear no-access outcome, while authorization and non-member record-hiding remain unchanged.

Why this priority: it is a polish issue, but confusing login or membership copy weakens pilot confidence.

Independent Test: Exercise readonly, unauthorized, and cross-workspace provider-connection paths and assert the response is clearer than a misleading login redirect without revealing forbidden records.

Acceptance Scenarios:

1. Given a readonly actor lacks provider access, When they open a provider-connection route, Then they remain blocked and see a clear no-access/permission outcome.
2. Given a non-member or cross-workspace actor requests a provider connection, When authorization runs, Then the response does not reveal record existence.
3. Given the actor is authenticated, When access is denied for capability or membership reasons, Then the result must not imply that the user simply needs to log in again unless they are actually unauthenticated.

Functional Requirements (mandatory)

• FR-412-001: The implementation MUST resolve or product-decide the Spec 407 P1 management PDF surfacing issue.
• FR-412-002: A ready stored management PDF associated with the current review pack MUST display ready/download/open state to authorized users.
• FR-412-003: A ready stored management PDF MUST NOT show "Generate management PDF" as the primary action.
• FR-412-004: Missing, failed, unavailable, expired, deleted, or inconsistent PDF/file states MUST NOT be shown or served as ready.
• FR-412-005: Management PDF direct downloads MUST preserve signed route, workspace/environment ownership, and authorization checks.
• FR-412-006: Signed customer report routes MUST still render only when valid and customer-safe; unsigned or invalid report paths remain blocked.
• FR-412-007: Operations index and detail routes MUST complete usable browser navigation under normal local audit conditions.
• FR-412-008: Operations pages MUST not perform Graph/external calls during render and MUST not expose stack traces, raw payloads, or internal errors by default.
• FR-412-009: If polling or pending requests are intentional on operations pages, page readiness MUST remain detectable for focused browser proof.
• FR-412-010: Finding detail default-visible content MUST not prominently expose fingerprint, scope hash, source fingerprint, detector keys, source keys, or equivalent raw technical identifiers.
• FR-412-011: Hashes or identifiers needed for support diagnostics MAY remain available only in collapsed, technical, support, or capability-gated detail.
• FR-412-012: Readonly provider-connection no-access behavior MUST remain denied and MUST improve copy/outcome clarity for authenticated actors.
• FR-412-012a: Authenticated actors denied by provider permission or membership checks MUST NOT be sent to a login prompt unless they are actually unauthenticated; the outcome MUST be either a 403/no-access response or a safe redirect with accurate permission or membership copy.
• FR-412-013: Non-member and cross-workspace provider/report/operation access MUST continue to avoid leaking record existence.
• FR-412-014: No new top-level navigation, major page, product concept, status family, persisted truth, or provider access model may be introduced.
• FR-412-015: A final implementation report MUST include the Spec 407 Finding Remediation Matrix and Report/PDF State Matrix from the supplied draft.

Non-Functional Requirements

• NFR-412-001: Filament v5 code must remain Livewire v4-compatible and use existing panel provider registration in apps/platform/bootstrap/providers.php.
• NFR-412-002: All rendered UI changes must use native Filament/shared primitives first and avoid custom styling or duplicate UI concepts.
• NFR-412-003: No Graph call or external HTTP call may be introduced during page render.
• NFR-412-004: Download/report routes must avoid secret, path, payload, stack trace, or raw provider leakage.
• NFR-412-005: Tests must prove business truth, authorization, customer-safe boundaries, route readiness, and negative access paths without broad fixture bloat.
• NFR-412-006: Browser proof must be focused and must not claim a new full browser/UX/runtime audit.

Out of Scope

• New report template, PDF renderer, PDF lifecycle architecture, or report generation workflow.
• New review-pack product concept, customer review surface, customer portal, operations dashboard, or provider onboarding flow.
• New OperationRun architecture, state model, or notification policy.
• New finding taxonomy, persisted reason/status family, or cross-domain UI framework.
• Legal hold, purge, export-before-delete governance, staging/Dokploy validation, JSONB migration, commercial lifecycle, or support desk integration.
• Reopening completed Specs 400-407 or rewriting their close-out, validation, browser, smoke, screenshot, or task history.
• Full browser/UX/runtime audit.

Key Entities And Truth Sources

• ReviewPack: existing review output package and detail surface context.
• StoredReport: existing report/PDF artifact truth, including management report PDF state and file metadata.
• EnvironmentReview: existing released/customer-safe review context.
• OperationRun: canonical execution truth for operations pages.
• Finding: existing finding state and technical identifiers.
• ProviderConnection: existing provider connection readiness/access record.
• AuditLog: existing audit trail for security-relevant or mutating actions; no new audit domain is introduced.

Edge Cases

• StoredReport is ready but file is missing, size/hash invalid, storage disk unavailable, or signed URL cannot be generated.
• Review pack is expired/archived/deleted but a PDF record exists.
• A PDF generation run is already queued/running while a ready PDF also exists.
• Operations page intentionally keeps a polling request open.
• OperationRun belongs to the workspace but references an environment the actor cannot access.
• Finding has both human-readable scope and hash fields; only the former should be default-visible.
• Readonly actor is authenticated but lacks provider view/manage capability.
• Non-member actor probes provider/report/operation direct URLs.

Success Criteria (mandatory)

• SC-412-001: Controlled pilot can proceed without the Spec 407 management PDF/action clarity exclusion.
• SC-412-002: No P0 or P1 residual finding remains in the four included areas.
• SC-412-003: Any remaining P2/P3 is explicitly bounded, documented, and non-blocking for scripted pilot paths.
• SC-412-004: Focused tests and browser proof pass for all four included findings.
• SC-412-005: Customer-safe/report/authorization boundaries remain intact.
• SC-412-006: No new product surface, product concept, persisted truth, status family, or broad abstraction is introduced.

Assumptions

• Spec 407 findings are accepted as valid source findings even if the final audit report was not committed as a spec-local artifact.
• Existing fixtures can be reused or minimally extended to represent ready/missing/failed management PDFs, operations runs, findings with hashes, and readonly provider access.
• The management-report PDF staging/Dokploy validation gap remains outside this pack.
• The product remains pre-production, so clean correction is preferred over compatibility shims.

Risks

• A ready StoredReport may not be the only source of report truth; implementation must verify ManagementReportPdfService and review-pack relationships before changing UI state.
• Operation route timeout may be a browser-tool readiness issue rather than a server defect; proof must distinguish this from real runtime failure.
• Hiding hashes too aggressively could hurt support workflows; demotion must preserve authorized technical access where needed.
• Provider no-access copy could accidentally reveal record existence; non-member and cross-workspace cases must remain safe.

Open Questions

• None blocking preparation. Implementation must record exact reproduction/proof data for each Spec 407 finding before and after remediation.

Follow-up Spec Candidates

• Management-report PDF staging/Dokploy runtime validation remains separate.
• Governance artifact lifecycle/retention runtime remains separate.
• Provider readiness/onboarding productization remains separate.
• Future full browser/UX/runtime re-audit remains separate and only after focused remediation is complete.

Candidate Selection Gate Result

PASS WITH NUMBERING DEVIATION. The candidate was directly supplied by the user, aligns with the Spec 407 remediation path, is small enough for a bounded implementation loop, is not already covered by an active or completed spec in the current branch, and excludes completed-spec rewrites. The supplied number 408 could not be used safely because 408 through 411 are already reserved by existing branches.

Spec Readiness Gate Result

PASS FOR IMPLEMENTATION PREPARATION once plan.md, tasks.md, and checklists/requirements.md in this package are reviewed together. This spec has no open product question that blocks a later implementation loop.