From fdd9eb2e8293c8e10984082788525c8ef9420796 Mon Sep 17 00:00:00 2001 From: ahmido Date: Wed, 24 Jun 2026 23:02:06 +0000 Subject: [PATCH] feat: add focused pilot gate recheck (#480) Automated PR provided by Codex via Gitea API. Co-authored-by: Ahmed Darrazi Reviewed-on: https://git.cloudarix.de/ahmido/TenantAtlas/pulls/480 --- .../checklists/requirements.md | 81 +++ specs/413-focused-pilot-gate-recheck/plan.md | 207 +++++++ specs/413-focused-pilot-gate-recheck/spec.md | 510 ++++++++++++++++++ specs/413-focused-pilot-gate-recheck/tasks.md | 194 +++++++ 4 files changed, 992 insertions(+) create mode 100644 specs/413-focused-pilot-gate-recheck/checklists/requirements.md create mode 100644 specs/413-focused-pilot-gate-recheck/plan.md create mode 100644 specs/413-focused-pilot-gate-recheck/spec.md create mode 100644 specs/413-focused-pilot-gate-recheck/tasks.md diff --git a/specs/413-focused-pilot-gate-recheck/checklists/requirements.md b/specs/413-focused-pilot-gate-recheck/checklists/requirements.md new file mode 100644 index 00000000..3cd1dd56 --- /dev/null +++ b/specs/413-focused-pilot-gate-recheck/checklists/requirements.md @@ -0,0 +1,81 @@ +# Requirements Checklist: Spec 413 - Focused Pilot Gate Recheck + +**Purpose**: Preparation readiness checklist for a read-only focused pilot gate recheck after Spec 412. +**Feature**: `specs/413-focused-pilot-gate-recheck/` +**Created**: 2026-06-24 + +## Applicability And Low-Impact Gate + +- [x] The selected candidate was directly provided by the operator as Spec 413. +- [x] The active candidate queue in `docs/product/spec-candidates.md` was checked and has no automatic next-best-prep target. +- [x] Manual promotion is justified by the supplied candidate and the Spec 407 -> Spec 412 -> Spec 413 sequence. +- [x] No existing `specs/413-focused-pilot-gate-recheck/` package existed before this prep. +- [x] Related completed context was checked: Spec 407 is read-only audit context and Spec 412 contains completed tasks/implementation report. +- [x] Completed specs are preserved and not rewritten. +- [x] The scope is read-only and focused, not a full browser audit. +- [x] No application implementation or test-file change is planned or allowed. + +## Product Surface Contract + +- [x] Product Surface Contract is referenced as the evaluation lens. +- [x] Product Surface Impact records `N/A - no rendered product surface changed`. +- [x] Browser proof is required because the future gate output is browser/runtime evidence. +- [x] Human Product Sanity is planned for the final gate report. +- [x] Product Surface exceptions are `none` for preparation. +- [x] Final report requirements include 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 completed-spec rewrite assertion. + +## Scope And Requirements + +- [x] The problem statement is clear: verify whether Spec 412 actually closed Spec 407 pilot-readiness blockers. +- [x] User value is clear: provide PASS, PASS WITH CONDITIONS, or FAIL before Spec 414 controlled pilot preparation. +- [x] Functional requirements cover management PDF surfacing, report/PDF state agreement, signed/unsigned report behavior, OperationRun load, finding hash demotion, readonly provider no-access, focused regression checks, and final report structure. +- [x] Out-of-scope boundaries forbid fixes, tests, migrations, runtime data mutation, full audit, new surfaces, and completed-spec rewrites. +- [x] Acceptance criteria and success criteria are measurable. +- [x] Assumptions and risks are explicit. +- [x] No open question blocks safe read-only gate execution. + +## RBAC, Isolation, Auditability, And Truth Semantics + +- [x] Workspace and managed-environment entitlement checks are included. +- [x] Unauthorized and cross-workspace report/PDF probes are included. +- [x] Signed/unsigned report boundaries are included. +- [x] OperationRun authorization checks are included. +- [x] Provider readonly and authorized comparison checks are included. +- [x] Customer-safe output and internal technical detail demotion are included. +- [x] Report/PDF artifact truth, execution truth, customer-safe truth, and provider boundary truth are distinguished. +- [x] No audit log writes or runtime mutations are introduced. + +## Tasks Quality + +- [x] `tasks.md` exists. +- [x] Tasks are ordered by execution phase. +- [x] Tasks are small and verifiable. +- [x] Tasks include baseline/dirty-state capture. +- [x] Tasks include Spec 412 implementation-report inspection. +- [x] Tasks include route/fixture probe before browser work. +- [x] Tasks include required matrices and final gate decision. +- [x] Tasks include no-implementation and no-completed-spec-rewrite assertions. +- [x] Tasks do not require application code, tests, migrations, seeders, factories, routes, policies, views, config, assets, or runtime data changes. + +## Test Governance + +- [x] Test purpose is classified as Browser/read-only audit evidence. +- [x] No new or modified tests or test family are planned. +- [x] Existing tests may be run only as validation commands with exact results. +- [x] Fixture/helper/factory/seed cost remains none. +- [x] Browser proof is focused and does not claim full browser audit coverage. +- [x] Missing fixtures or actors must be recorded as limitations, not pass evidence. + +## Review Outcome + +- **Outcome class**: acceptable-special-case. +- **Workflow outcome**: keep. +- **Reason**: The package is a bounded read-only gate after a completed remediation spec, with no runtime changes and explicit completed-spec protections. + +## Candidate Selection Gate + +**PASS**. The candidate is directly provided, not already covered by an active/completed Spec 413 package, aligned with the roadmap path toward controlled pilot preparation, scoped as a small focused gate, and preserves Spec 407/412 history. + +## Spec Readiness Gate + +**PASS FOR IMPLEMENTATION PREPARATION**. `spec.md`, `plan.md`, `tasks.md`, and this checklist exist and are aligned for a later read-only gate execution. diff --git a/specs/413-focused-pilot-gate-recheck/plan.md b/specs/413-focused-pilot-gate-recheck/plan.md new file mode 100644 index 00000000..06f08590 --- /dev/null +++ b/specs/413-focused-pilot-gate-recheck/plan.md @@ -0,0 +1,207 @@ +# Implementation Plan: Spec 413 - Focused Pilot Gate Recheck + +**Branch**: `413-focused-pilot-gate-recheck` | **Date**: 2026-06-24 | **Spec**: `specs/413-focused-pilot-gate-recheck/spec.md` +**Input**: Feature specification from `specs/413-focused-pilot-gate-recheck/spec.md` + +## Summary + +Prepare a read-only focused gate recheck after Spec 412. The future execution must inspect Spec 412 claimed remediation, capture dirty state, identify relevant routes/surfaces, run focused browser/runtime probes, and produce a PASS, PASS WITH CONDITIONS, or FAIL decision with required matrices. It must not implement fixes, create or modify tests, mutate data, modify runtime files, or reopen completed specs. + +## Technical Context + +**Language/Version**: PHP 8.4.15, Laravel 12.52, Filament 5.2.1, Livewire 4.1.4 +**Primary Dependencies**: Laravel Sail, Filament, Livewire, Pest 4, Playwright/browser tooling when available +**Storage**: PostgreSQL locally through Sail; no schema/data changes +**Testing**: Existing Pest/browser tests may be run if safe; no test files are created or modified +**Target Platform**: Local development environment unless operator explicitly approves another environment +**Project Type**: Laravel monolith under `apps/platform` +**Performance Goals**: No load testing; only verify browser route readiness and distinguish usable page load from tool timeout artifacts +**Constraints**: read-only only; no application code or test file changes, migrations, seeders, factories, routes, policies, config, docs outside this package, generated assets, database schema, intentional runtime data changes, destructive actions, or completed-spec rewrites +**Scale/Scope**: Focused Spec 407/412 remediation areas only; not a full browser audit + +## UI / Surface Guardrail Plan + +- **UI Surface Impact**: No rendered UI surface changed. Existing surfaces are inspected only. +- **Guardrail handling mode**: low-impact read-only gate with browser proof required as the output. +- **Repository-signal treatment**: Specs 407 and 412 are historical context. Spec 412 implementation report is a claimed-remediation source, not proof. +- **Required proof depth**: focused browser/runtime proof for management PDF surfacing, report/PDF route authorization, OperationRun index/detail load, finding detail hash demotion, readonly provider no-access, and adjacent regression boundaries. +- **Close-out target**: final Spec 413 audit report in assistant response, or spec-local saved artifact only if the operator explicitly requests it during execution. + +## Product Surface Contract Plan + +- **Product Surface Contract reference**: `docs/product/standards/product-surface-contract.md` +- **No-legacy posture**: read-only canonical assessment; no compatibility aliases, duplicate UI, hidden fallback routes, or old labels introduced. +- **Product Surface Impact**: no rendered product surface changed; Product Surface Contract is used as the evaluation lens. +- **Page archetype handling**: classify inspected pages where useful. Expected archetypes include Report/Receipt for review/report/PDF, Technical Annex/Receipt for OperationRun pages, Decision/Secondary Context for finding detail, and Settings/no-access outcome for provider connection denial. +- **Surface budgets**: evaluate raw IDs, OperationRun/evidence deep links, default technical detail, repeated readiness summaries, and contradictory report state as findings if observed. +- **Technical Annex / deep-link demotion**: explicitly verify finding hashes and internal proof remain demoted from default customer/operator content. +- **Canonical status vocabulary**: verify visible status wording maps to canonical vocabulary or record deviations. +- **Product Surface exceptions**: none approved in this prep. +- **Browser verification plan**: focused route/flow proof is required. +- **Human Product Sanity plan**: final report sanity against whether the gate decision is evidence-backed, bounded, and actionable. + +## Filament / Livewire / Deployment Posture + +- **Filament/Livewire surfaces changed?**: none. +- **Livewire v4 compliance**: Livewire 4.1.4 confirmed by Laravel Boost application info; future report must restate that no Livewire v3/v4-incompatible code was introduced because no runtime code changes occur. +- **Provider registration location**: unchanged; Laravel 12 panel providers remain under `apps/platform/bootstrap/providers.php`. +- **Global search posture**: no resource changed; future gate may verify global search/no-leak behavior only if needed for included routes. +- **Destructive/high-impact action posture**: no action is added or executed. Existing destructive/high-impact actions may be inspected for visibility/confirmation only; do not execute them. +- **Asset strategy**: no assets added or changed; no new `filament:assets` deployment impact. +- **Testing plan**: no new tests. Future execution may run selected existing Sail/Pest/browser commands and must report exact commands and results. + +## Shared Pattern & System Fit + +- **Report/PDF truth**: verify existing `ReviewPack` and `StoredReport` state agreement, signed route behavior, ready/missing/failed file states, and same-scope authorization. +- **Execution truth**: verify existing `OperationRun` index/detail render and proof links; no OperationRun lifecycle or UX semantics are changed. +- **Artifact truth**: verify ready PDF exists and is valid/readable where fixture exists; missing file despite ready receipt becomes an inconsistency finding, not valid output. +- **Customer-safe truth**: verify report/customer paths do not expose internal-only proof, raw identifiers, internal OperationRun details, raw provider payloads, or stack traces. +- **Provider boundary**: readonly provider no-access must remain denied, non-leaky, and clearer than the Spec 407 finding. +- **RBAC and isolation**: preserve deny-as-not-found for non-members/cross-workspace actors and 403/no-access semantics only after membership/capability context is established. + +## OperationRun UX Impact + +- **Runtime change**: none. +- **Inspection target**: operations index/detail load completion, proof link usability, authorization behavior, absence of fatal browser/Livewire/Filament errors. +- **Start UX**: do not start new operations except unavoidable existing login/session behavior. Do not execute operation-starting actions. +- **Lifecycle truth**: do not mutate OperationRun status/outcome. + +## Provider Boundary & Portability Fit + +- **Runtime change**: none. +- **Inspection target**: provider connection route/no-access behavior for readonly/limited actors and authorized comparison actor where safe. +- **Provider coupling risk**: none introduced because no code or copy changes are made. +- **Follow-up criteria**: create a bounded provider access/no-access remediation only if the gate finds unsafe leakage, access weakening, redirect loops, or confusing authenticated-user-to-login behavior that remains pilot-relevant. + +## Constitution Check + +*GATE: Must pass before future gate execution.* + +- **Inventory-first, snapshots-second**: PASS. Existing observed/report artifacts are inspected only. +- **Read/write separation by default**: PASS. The gate is read-only and forbids destructive/high-impact execution. +- **Single contract path to Graph**: PASS. No Graph calls are added; any unexpected Graph/render behavior is a finding. +- **Deterministic capabilities**: PASS. Existing capability behavior is verified, not changed. +- **Proportionality first**: PASS. The package adds no runtime structure and exists only to verify a direct post-remediation gate. +- **No premature abstraction**: PASS. No abstraction, registry, framework, or taxonomy is introduced. +- **Provider boundary**: PASS. Provider seams are audit targets only. +- **No new persisted truth**: PASS. No application persistence is introduced. +- **No new state without behavioral consequence**: PASS. PASS/PASS WITH CONDITIONS/FAIL and P0-P3 severities are report-only. +- **Product Surface Contract Gate**: PASS. Product Surface Contract is referenced, no rendered surface changes, browser proof is the gate output, completed specs are preserved. +- **Workspace/tenant isolation**: PASS. Isolation is explicitly tested where fixtures permit. +- **RBAC/security**: PASS. The gate verifies authorization boundaries and records any unsafe behavior. +- **Test governance**: PASS. No new test family. Browser/read-only classification is explicit. + +## Research / Inventory Requirements + +Before browser execution, read or inspect: + +- `specs/413-focused-pilot-gate-recheck/spec.md`, `plan.md`, `tasks.md`, and checklist. +- `specs/407-full-browser-ux-runtime-audit/spec.md`, `plan.md`, and `tasks.md` as source context only. +- `specs/412-pilot-readiness-remediation-pack/spec.md`, `plan.md`, `tasks.md`, and `implementation-report.md`. +- Relevant route list entries for review/report/PDF, operations, findings, provider connections, and customer report paths. +- Recent application and browser logs if a route fails. +- Current branch, HEAD, dirty state, active environment, and base URL. + +Application code may be read for route/resource ownership and naming, but not edited. + +## Implementation Phases + +### Phase 0 - Baseline and Safety + +Record `git status --short --branch`, `git diff --name-only`, `git diff --check`, `git log -1 --oneline`, active environment, base URL, and available actors/fixtures. Stop if the working tree has unsafe unrelated changes. + +### Phase 1 - Spec 412 Claim Inspection + +Extract claimed remediation, tests, browser proof, residual unrelated failures, touched files, and deferred items from `implementation-report.md`. Build the initial recheck target list. + +### Phase 2 - Route and Fixture Probe + +Identify exact routes and records for review pack ready PDF, stored report/receipt, signed and unsigned reports, operations index/detail, finding detail, provider no-access, customer report path, unauthorized actor, cross-workspace actor, readonly actor, and authorized comparison actor. + +### Phase 3 - Focused Browser Recheck + +Run only the included probes. Record route/page, actor, workspace/environment, fixture/state, expected result, observed result, runtime errors, console output, authorization result, and evidence. + +### Phase 4 - Focused Regression Checks + +Check customer-safe output, evidence/currentness, report lifecycle, OperationRun authorization, workspace/environment scoping, signed/unsigned report boundary, finding proof links, and provider authorization boundary. + +### Phase 5 - Gate Decision and Report + +Produce the required matrices, remaining findings grouped by severity, readiness decision, validation commands, and recommended next step. Do not fix defects. + +## Test Governance Check + +- **Test purpose / classification by changed surface**: Browser/read-only audit evidence; no runtime surface changed. +- **Affected validation lanes**: Browser/read-only gate; optional existing Pest filters only when safe. +- **New/broader test family**: none. +- **Fixture/helper/factory/seed cost**: none; use existing fixtures/actors only. +- **Heavy-family risk**: bounded because the scope is focused and not a full audit. +- **Escalation outcome**: `document-in-feature` for contained missing-fixture/proof limitations; `follow-up-spec` only for evidence-backed structural or pilot-blocking residuals. +- **Browser proof**: required for future gate execution. +- **Human Product Sanity**: required in final report. + +## Project Structure + +### Documentation (this feature) + +```text +specs/413-focused-pilot-gate-recheck/ +├── spec.md +├── plan.md +├── tasks.md +└── checklists/ + └── requirements.md +``` + +### Source Code + +No source code changes are planned or allowed. + +Read-only inspection targets may include: + +```text +apps/platform/routes/web.php +apps/platform/app/Filament/Resources/ReviewPackResource/ +apps/platform/app/Http/Controllers/*Report* +apps/platform/app/Filament/Pages/Operations/ +apps/platform/app/Filament/Resources/FindingResource.php +apps/platform/app/Filament/Resources/ProviderConnectionResource.php +apps/platform/app/Policies/ProviderConnectionPolicy.php +apps/platform/tests/ +``` + +## Risk Controls + +- Stop instead of fixing if a P0/P1 defect is found. +- Do not perform destructive/high-impact actions. +- Do not create, edit, or delete fixtures. +- Do not expose raw signed URLs, secrets, credentials, customer data, or provider payloads in the report. +- Do not convert a missing fixture into a pass. +- Do not reopen Spec 407 or 412. +- Do not recommend a full audit unless Spec 412 changed broad surfaces beyond intended scope and focused proof shows broad regression. + +## Rollout / Deployment Considerations + +- **Env vars**: none. +- **Migrations**: none. +- **Queues/cron**: none. +- **Storage/volumes**: none; read-only report/PDF access may inspect existing storage availability only. +- **Assets**: none. +- **Staging/Dokploy**: not in scope. Existing staging/Dokploy renderer validation remains separate. + +## Complexity Tracking + +No constitution violation or BLOAT-001 trigger is introduced. No new persisted entity, abstraction, enum/status family, state machine, provider framework, or UI taxonomy is added. + +## Preparation Analyze Status + +Preparation self-analysis must verify: + +- `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md` exist. +- Scope remains read-only and focused. +- Required matrices and final report structure are present. +- Product Surface, RBAC, OperationRun, provider boundary, customer-safe, evidence/currentness, and test-governance concerns are represented. +- No task requires application implementation, fixture creation, test creation, migration, runtime mutation, or completed-spec rewrite. + +Current preparation status: pending external review until `/speckit-analyze` findings are applied and rechecked. diff --git a/specs/413-focused-pilot-gate-recheck/spec.md b/specs/413-focused-pilot-gate-recheck/spec.md new file mode 100644 index 00000000..3d385037 --- /dev/null +++ b/specs/413-focused-pilot-gate-recheck/spec.md @@ -0,0 +1,510 @@ +# Feature Specification: Spec 413 - Focused Pilot Gate Recheck + +**Feature Branch**: `413-focused-pilot-gate-recheck` +**Created**: 2026-06-24 +**Status**: Draft / Ready for preparation review +**Type**: Read-only focused browser/runtime gate / pilot-readiness verification +**Input**: User-provided "Spec 413 - Focused Pilot Gate Recheck" draft from `/Users/ahmeddarrazi/.codex/attachments/6fd4fa1e-54cf-4bf4-a1fc-1bc3327e3854/pasted-text.txt`, `specs/407-full-browser-ux-runtime-audit/`, `specs/412-pilot-readiness-remediation-pack/`, `docs/product/spec-candidates.md`, `docs/product/roadmap.md`, and `docs/product/standards/product-surface-contract.md`. + +## Candidate Selection Context + +- **Selected candidate**: Spec 413 - Focused Pilot Gate Recheck. +- **Source location**: Direct user-provided Spec 413 draft in the current request. +- **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. Spec 413 is the narrow read-only proof gate after Spec 412 and asks whether the Spec 407 pilot-readiness findings are actually closed before TenantPilot proceeds to controlled pilot preparation. +- **Why close alternatives were deferred**: + - `management-report-pdf-staging-runtime-validation` remains a staging/Dokploy renderer validation lane, not this local focused recheck. + - `governance-artifact-lifecycle-retention-runtime` is broader artifact lifecycle work and must not be hidden inside a pilot gate. + - `provider-readiness-onboarding-productization` remains optional P2 roadmap work; this spec checks only the readonly provider no-access behavior that Spec 412 claims to have fixed. + - A new full browser/UX/runtime audit is explicitly out of scope because Spec 407 already performed the broad audit and Spec 413 only rechecks the known remediation areas. +- **Roadmap relationship**: Supports the near-term path from post-audit remediation into controlled pilot preparation. The canonical phase sequence is Spec 407 full browser/runtime audit, Spec 412 pilot-readiness remediation, Spec 413 focused gate recheck, then a later Spec 414 controlled pilot preparation pack if this gate passes. +- **Completed-spec guardrail result**: + - `specs/407-full-browser-ux-runtime-audit/` exists as read-only audit context and must not be rewritten. + - `specs/412-pilot-readiness-remediation-pack/` contains completed tasks and an implementation report with focused tests/browser proof. It is completed implementation history and must not be normalized, unchecked, or stripped. + - No `specs/413-focused-pilot-gate-recheck/` package existed before this preparation. No existing local or remote branch matching `413-focused-pilot-gate-recheck` was found before Spec Kit branch creation. +- **Smallest viable implementation slice**: Run a focused read-only recheck of the four Spec 407 findings remediated by Spec 412 and the adjacent regression boundaries: management PDF surfacing, report/PDF route authorization and state agreement, OperationRun index/detail load completion, finding hash demotion, readonly provider no-access clarity, and customer-safe/evidence/currentness/lifecycle/report regressions. +- **Feature description for Spec Kit**: Verify, through focused read-only browser/runtime evidence, that Spec 412 closed the known Spec 407 pilot-readiness findings without introducing authorization, customer-safe, report/PDF, OperationRun, evidence/currentness, lifecycle, or provider no-access regressions, and return a PASS, PASS WITH CONDITIONS, or FAIL decision before controlled pilot preparation. + +## Spec Candidate Check *(mandatory - SPEC-GATE-001)* + +- **Problem**: Spec 412 claims to remediate the Spec 407 pilot-readiness findings, but controlled pilot preparation should not proceed on implementation claims alone. +- **Today's failure**: Without a focused recheck, TenantPilot could move into pilot preparation while ready PDFs still surface incorrectly, report routes leak or block incorrectly, operations pages still fail browser readiness, finding detail still exposes technical hashes by default, or provider no-access behavior remains confusing or unsafe. +- **User-visible improvement**: The operator receives one evidence-backed gate answer for whether Spec 412 actually closed the known pilot-readiness blockers and whether Spec 414 controlled pilot preparation may start. +- **Smallest enterprise-capable version**: A read-only focused browser/runtime recheck over only the Spec 407/412 remediation areas, using existing actors, fixtures, routes, tests, logs, and browser inspection. +- **Explicit non-goals**: No fixes, no new or modified tests, migrations, refactors, seeders, factories, new surfaces, UI redesign, report-template changes, new OperationRun architecture, provider onboarding redesign, full browser audit, staging/Dokploy validation, legal hold or purge governance, commercial lifecycle work, support desk integration, docs outside this spec package, or application code changes. +- **Permanent complexity imported**: One Spec Kit package and a future audit/gate report. The severity labels, matrices, and PASS/PASS WITH CONDITIONS/FAIL result are report-only evidence, not runtime state, persisted truth, or a product status family. +- **Why now**: Spec 412 closed the bounded findings from Spec 407 and recorded focused proof. A follow-up gate should verify those claims before the project advances to controlled pilot preparation. +- **Why not local**: Unit or feature test results alone cannot prove browser navigation completion, visible PDF state agreement, customer-safe output, no-access clarity, and signed/unsigned report behavior together. +- **Approval class**: Core Enterprise. +- **Red flags triggered**: Browser-lane cost and audit matrix scope. Defense: this spec is read-only, focused on known findings, forbids runtime changes, and explicitly rejects a full browser audit. +- **Score**: Value: 2 | Urgency: 2 | Scope: 2 | Complexity restraint: 2 | Product proximity: 2 | Reuse: 2 | **Total: 12/12** +- **Decision**: approve as a bounded read-only focused gate recheck. + +## Problem Statement + +Spec 413 answers: + +```text +Did Spec 412 actually close the known Spec 407 pilot-readiness blockers without introducing regressions? +``` + +The answer must be based on current browser/runtime proof and route/state/authorization evidence, not on the Spec 412 implementation report alone. + +## Product / Business Value + +- Prevents false confidence after a remediation pack. +- Protects controlled pilot preparation from known report, operations, finding, and provider access risks. +- Keeps pilot gate work focused and avoids another whole-application audit. +- Produces a concrete decision: PASS, PASS WITH CONDITIONS, or FAIL. +- If the gate does not pass, it identifies one bounded remediation spec rather than a broad rewrite. + +## Primary Users / Operators + +- Product owner deciding whether Spec 414 controlled pilot preparation can start. +- Workspace admins and system operators validating pilot-readiness flows. +- Customer reviewers whose report and customer-safe output boundaries must remain trustworthy. +- Readonly or limited actors whose provider no-access outcomes must remain safe and clear. +- Engineering reviewers who need a focused proof package before further implementation. + +## Spec Scope Fields *(mandatory)* + +- **Scope**: focused read-only browser/runtime verification over existing surfaces. +- **Primary Routes / Surfaces**: + - Review pack detail page and management PDF action area. + - Stored report detail or report receipt page where available. + - Management PDF download/open route. + - Signed customer report route and unsigned/invalid-signature report route. + - Admin OperationRun index and OperationRun detail. + - OperationRun proof links from related surfaces. + - Finding detail page. + - Provider connection route and no-access behavior for readonly/limited actors. + - Customer review/report path if connected to the PDF/report flow. +- **Data Ownership**: Existing `ReviewPack`, `StoredReport`, `EnvironmentReview`, `OperationRun`, `Finding`, `ProviderConnection`, workspace-owned, and managed-environment-owned records are read only. No table, field, state, ownership, or source-of-truth change is introduced. +- **RBAC**: Existing workspace membership, managed-environment entitlement, platform/admin/customer plane boundaries, signed URL authorization, member capability denials, and non-member deny-as-not-found behavior are verified only. +- **Default filter behavior when environment context is active**: Existing route-owned workspace/environment scope and explicit page filters remain repo truth. Any hidden context drift observed during recheck is recorded as a finding. +- **Explicit entitlement checks preventing cross-tenant leakage**: Representative direct route/download/report/provider/operation probes must be performed where existing actors and fixtures permit. Missing actor or fixture conditions are recorded as limitations, not proof. + +## No Legacy / No Backward Compatibility Constraint *(mandatory)* + +TenantPilot is pre-production for this gate. + +- **Compatibility posture**: read-only verification of current canonical behavior. +- **Legacy aliases, fallback readers, hidden routes, duplicate UI, old labels, or historical fixtures kept?**: no new compatibility behavior is introduced. +- **Why clean assessment is safe now**: The recheck does not mutate runtime behavior. If defects are found, follow-up remediation should correct canonical behavior instead of adding compatibility shims. + +## UI Surface Impact *(mandatory - UI-COV-001)* + +Does this spec add, remove, rename, or materially change any reachable UI surface? + +- [x] 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 + +N/A - no reachable UI surface impact. + +- **No-impact rationale**: Spec 413 prepares a read-only verification gate. Future execution may navigate existing pages, inspect actions, open safe links, inspect browser console/logs, and download/open existing authorized reports, but it must not change pages, navigation, actions, views, routes, policies, resources, tests, assets, or runtime data. + +## Product Surface Impact + +Reference: `docs/product/standards/product-surface-contract.md`. + +- **Product Surface Contract applies?**: yes as the evaluation lens; no rendered product surface is changed by this spec. +- **Page archetype**: N/A for preparation. The recheck must classify inspected pages as Report, Receipt, Technical Annex, Decision, Settings, Search/Index, Dashboard, or System Admin where evidence supports it. +- **Primary user question**: "Is TenantPilot ready to move from post-audit remediation into controlled pilot preparation?" +- **Primary action**: Produce the focused gate decision and recommended next step. +- **Surface budget result**: N/A for preparation. The recheck flags default-view raw hashes, raw evidence links, OperationRun dominance, contradictory report state, or non-canonical status language as findings. +- **Technical Annex / deep-link demotion**: The recheck specifically verifies raw finding hashes and internal proof remain demoted from default customer/operator narrative. +- **Canonical status vocabulary**: The recheck verifies visible states use or map cleanly to Ready, Needs attention, Blocked, Running, Failed, Expired, Not configured, Unknown, Historical, Superseded, and allowed severity values. +- **Visible complexity impact**: neutral at runtime. The report may recommend bounded follow-up work, but must not perform it. +- **Product Surface exceptions**: none for preparation. + +## Browser Verification Plan *(mandatory)* + +- **Browser proof required?**: yes for future Spec 413 execution because browser/runtime evidence is the product of this gate. +- **No-browser rationale**: N/A. +- **Focused path when required**: + 1. Review pack with ready stored management PDF shows ready/download/open state. + 2. Review pack with ready stored management PDF does not show "Generate management PDF" as the primary state. + 3. Stored report or report receipt state agrees with the review-pack UI. + 4. Authorized admin can download/open the management PDF. + 5. Unauthorized and cross-workspace actors cannot access/download the PDF/report. + 6. Signed report route renders only with a valid signature. + 7. Unsigned or invalid report route is blocked. + 8. Admin operations index completes browser navigation. + 9. Admin operations detail completes browser navigation. + 10. Finding detail default body no longer prominently exposes fingerprint or scope/source hashes. + 11. Readonly actor remains blocked from provider-connection route and sees a clearer no-access outcome. + 12. Focused regression probes cover customer-safe output, evidence/currentness, report lifecycle, OperationRun authorization, workspace/environment scoping, finding proof links, and provider authorization boundary. +- **Primary interaction to execute**: read-only navigation, safe link opening, report/PDF open or download where already authorized, direct unauthorized route probes, default detail inspection, console/log inspection, and confirmation-state inspection without executing destructive/high-impact actions. +- **Console, Livewire, Filament, network, and 500-error checks**: required. +- **Full-suite failure triage**: unrelated failures may be documented only when focused proof supports that classification. + +## Human Product Sanity Check *(mandatory)* + +- **Required?**: yes as final gate sanity. +- **No-human-sanity rationale**: N/A. +- **Reviewer questions**: Does the gate answer whether Spec 412 closed the known issues? Are report/PDF, authorization, customer-safe, OperationRun, finding-detail, and provider no-access results concrete? Are remaining findings classified and tied to pilot impact? Is any recommended follow-up bounded? +- **Planned result location**: final Spec 413 audit report in the assistant response, or a spec-local report only if the operator explicitly requests a saved artifact during future execution. + +## Product Surface Merge Gate Checklist *(mandatory)* + +- [x] No-legacy posture or approved exception recorded. +- [x] Product Surface Impact is completed as read-only gate with no rendered surface change. +- [x] Browser proof is required as the gate output. +- [x] Human Product Sanity is planned as final-report sanity. +- [x] Product Surface exceptions are `none` for preparation. +- [x] Final report must 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 explicit no-implementation status. + +## Cross-Cutting / Shared Pattern Reuse + +- **Cross-cutting feature?**: yes as a read-only gate over reports/downloads, OperationRun surfaces, finding detail, provider no-access, authorization boundaries, and customer-safe output. +- **Interaction class(es)**: report/download action links, status/readiness messaging, evidence/report viewers, OperationRun proof links, authorization/no-access messaging, technical detail disclosure, signed routes, customer output. +- **Systems touched**: Spec artifacts only. Runtime systems are targets for read-only verification. +- **Existing pattern(s) to extend**: Product Surface Contract, Spec 407 audit structure, Spec 412 remediation matrices, Filament v5/Livewire v4 guidelines, RBAC/UiEnforcement conventions, OperationRun UX contract, signed report/download authorization patterns. +- **Shared contract / presenter / builder / renderer to reuse**: N/A - no runtime code. +- **Allowed deviation and why**: none. +- **Consistency impact**: The future report must use stable severity, gate, actor, route, expected/observed, evidence, residual severity, pilot impact, and follow-up language. +- **Review focus**: Confirm the gate stays read-only, focused, and does not become implementation or a full audit. + +## OperationRun UX Impact + +- **Touches OperationRun start/completion/link UX?**: no runtime change. OperationRun index/detail load, proof links, and authorization are verified only. +- **Shared OperationRun UX contract/layer reused**: N/A. +- **Delegated start/completion UX behaviors**: N/A. +- **Local surface-owned behavior that remains**: N/A. +- **Queued DB-notification policy**: N/A. +- **Terminal notification path**: N/A. +- **Exception required?**: none. + +## Provider Boundary / Platform Core Check + +- **Shared provider/platform boundary touched?**: no runtime seam change. Provider connection authorization and no-access copy are verified only. +- **Boundary classification**: provider connection remains provider-owned where provider-specific, while membership/capability denial and no-access behavior are platform-core. +- **Seams affected**: none by implementation; provider connection routes/pages/policies/middleware are audit targets. +- **Neutral platform terms preserved or introduced**: workspace, managed environment, provider connection, access, permission, membership, report, operation, evidence. +- **Provider-specific semantics retained and why**: existing Microsoft/provider labels remain only where existing provider connection behavior owns them. +- **Why this does not deepen provider coupling accidentally**: no code, UI labels, persistence, route, or vocabulary changes are introduced. +- **Follow-up path**: evidence-backed provider access regressions become one bounded remediation spec only if the gate fails. + +## UI / Surface Guardrail Impact + +N/A - no operator-facing surface change. The gate inspects existing operator, customer, and system surfaces and records findings only. + +## Decision-First Surface Role + +N/A - no surface changed. The gate verifies whether existing inspected pages still support a clear operator/customer decision after Spec 412. + +## Audience-Aware Disclosure + +N/A - no disclosure changed. The gate verifies customer-safe, operator diagnostic, and internal technical detail boundaries. + +## UI/UX Surface Classification + +N/A - no surface changed. Inspected surfaces may be classified in the final report when relevant. + +## Operator Surface Contract + +N/A - no new or materially changed operator-facing page. The gate checks existing page purpose, dominant action, technical detail demotion, status clarity, and audience boundaries. + +## Proportionality Review *(mandatory when structural complexity is introduced)* + +- **New source of truth?**: no runtime source of truth. The gate report is review evidence only. +- **New persisted entity/table/artifact?**: no application entity/table. A saved report artifact is allowed only under this spec directory if the operator explicitly requests it during execution. +- **New abstraction?**: no runtime abstraction. +- **New enum/state/reason family?**: no runtime status family. PASS/PASS WITH CONDITIONS/FAIL and P0-P3 severities are report-only. +- **New cross-domain UI framework/taxonomy?**: no runtime framework. Existing Product Surface and audit language is reused. +- **Current operator problem**: Controlled pilot preparation should not proceed until the known post-audit remediation claims have been rechecked. +- **Existing structure is insufficient because**: Spec 412 implementation proof is valuable but not the same as a fresh focused gate recheck across the actual pilot blockers and adjacent regression boundaries. +- **Narrowest correct implementation**: dirty-state capture, Spec 412 report inspection, route/surface probe, focused browser recheck, regression matrix, gate decision, and bounded follow-up recommendation. +- **Ownership cost**: one focused gate execution and one report. No recurring runtime maintenance. +- **Alternative intentionally rejected**: immediate Spec 414 preparation without recheck, another full browser audit, or remediating issues inside this gate. +- **Release truth**: current-release controlled pilot readiness gate. + +## Testing / Lane / Runtime Impact *(mandatory for runtime behavior changes)* + +- **Test purpose / classification**: Browser/read-only audit evidence plus optional existing Pest filters. No new test files are added or changed. +- **Validation lane(s)**: Browser/read-only gate, safe route/log inspection, `git diff --check`, and selected existing tests only if appropriate for the local environment. +- **Why this classification and these lanes are sufficient**: The spec does not change runtime behavior; the value is current proof that visible state, route authorization, and browser readiness match the remediation contract. +- **New or expanded test families**: none. +- **Fixture/helper/factory/seed/context cost**: none added. Existing actors, fixtures, and runtime data only. +- **Browser scope**: focused paths listed in the Browser Verification Plan, not a full application audit. +- **Deployment impact**: none from preparation or future gate execution. The gate may record deployment/readiness conditions but does not change env vars, migrations, queues, scheduler, storage, assets, reverse proxy, or Dokploy config. + +## Functional Requirements *(mandatory)* + +- **FR-413-001**: The gate MUST be read-only and MUST NOT modify application code, tests, migrations, seeders, factories, routes, policies, config, views, assets, database schema, runtime data intentionally, completed specs, or docs outside this spec package. +- **FR-413-002**: The gate MUST record branch, HEAD commit, dirty state, tracked changes, untracked files, `git diff --check`, active environment, base URL, and actors/fixtures used before and after recheck work. +- **FR-413-003**: The gate MUST inspect the Spec 412 implementation report and identify files changed, tests added/updated, browser proof claimed, remaining findings, deferred items, validation commands, and unrelated residual failures. +- **FR-413-004**: The gate MUST recheck management PDF surfacing with a ready stored management PDF where such a fixture exists. +- **FR-413-005**: A ready stored management PDF MUST show a ready/download/open state and MUST NOT show "Generate management PDF" as the primary state. +- **FR-413-006**: Stored report, report receipt, and review-pack UI states MUST agree for ready, missing, failed, unavailable, or inconsistent management PDF states. +- **FR-413-007**: Authorized management PDF download/open MUST work where a valid ready PDF fixture exists. +- **FR-413-008**: Unauthorized, cross-workspace, unsigned, invalid-signature, or otherwise unentitled report/PDF access MUST remain blocked and non-leaky. +- **FR-413-009**: Signed customer report routes MUST render only with valid signatures and customer-safe output. +- **FR-413-010**: OperationRun index and detail pages MUST complete usable browser navigation without current 500s or fatal Livewire/Filament errors under normal local audit conditions. +- **FR-413-011**: OperationRun proof links from related surfaces MUST remain usable and authorization-safe where fixtures permit. +- **FR-413-012**: Finding detail default body MUST NOT prominently expose fingerprint, scope hash, source fingerprint, detector/source keys, or equivalent raw technical identifiers. +- **FR-413-013**: Technical hashes, if still present, MUST be demoted to collapsed, support, operator, or technical detail and MUST NOT appear in customer-safe/default review context. +- **FR-413-014**: Readonly/limited provider-connection actors MUST remain blocked without redirect loops, login confusion for already-authenticated actors, or provider/workspace data leakage. +- **FR-413-015**: Authorized provider actors MUST still access intended provider connection surfaces where comparison is safe. +- **FR-413-016**: Focused regression checks MUST cover customer-safe report output, evidence/currentness labels, report lifecycle state display, OperationRun authorization, workspace/environment scoping, signed/unsigned report boundary, finding proof links, and provider authorization boundary. +- **FR-413-017**: Every P0/P1 finding MUST include route/page, actor, fixture/state, observed behavior, expected behavior, severity, why it matters, evidence, related Spec 407/412 finding, pilot impact, and recommended resolution. +- **FR-413-018**: The final report MUST include the Spec 407/412 Recheck Matrix, Report/PDF State Matrix, Focused Regression Matrix, Browser Proof table, Runtime/Console Results, Authorization/Customer-safe Boundary Results, Remaining Findings by severity, Readiness Decision table, commands run, and recommended next step. +- **FR-413-019**: The gate result MUST be exactly `PASS`, `PASS WITH CONDITIONS`, or `FAIL`. +- **FR-413-020**: If the gate does not pass, the recommendation MUST be one bounded remediation spec or explicit pilot exclusion. Do not recommend a broad audit by default. + +## Non-Functional Requirements + +- **NFR-413-001**: No secrets, tokens, private signed URLs, raw credential payloads, sensitive customer data, stack traces, or raw provider payloads may be recorded in the final report. +- **NFR-413-002**: Browser conclusions must distinguish product defects from missing fixtures, unavailable actors, unavailable services, intentional 403/404 outcomes, and browser-tool timeout artifacts. +- **NFR-413-003**: The gate must avoid destructive/high-impact execution, data mutation, fixture creation, new report release, restore execution, provider connection mutation, or membership/workspace changes. +- **NFR-413-004**: The final report must state Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, browser/test result, deployment impact, visible complexity outcome, and no-implementation status. +- **NFR-413-005**: Any existing test commands run during the gate must be reported accurately; do not claim test proof for commands not run. + +## User Scenarios And Independent Tests + +### User Story 1 - Product owner gets a gate decision (Priority: P1) + +As the product owner, I need a focused PASS, PASS WITH CONDITIONS, or FAIL result so I can decide whether Spec 414 controlled pilot preparation may begin. + +**Independent Test**: The final report includes Focused Pilot Gate Result, dirty state, actors/fixtures, matrices, browser proof, findings, readiness decision, commands run, and a recommended next action. + +### User Story 2 - Report and management PDF remediation is rechecked (Priority: P1) + +As a workspace admin, I need existing ready management PDFs and report routes to present safe, coherent, authorized states before pilot preparation. + +**Independent Test**: The Report/PDF State Matrix records ready, missing/failed/unavailable, authorized, unauthorized, cross-workspace, signed, and unsigned outcomes or explains unavailable fixtures. + +### User Story 3 - OperationRun navigation and finding/provider fixes are rechecked (Priority: P1) + +As an operator, I need operations pages to be usable, finding detail to avoid default raw hashes, and provider no-access to be clear without weakening authorization. + +**Independent Test**: Browser Proof records operations index/detail load, finding detail default content, readonly provider route behavior, and authorized comparison where safe. + +### User Story 4 - Focused regressions are caught without reopening a full audit (Priority: P2) + +As the next implementation agent, I need any remaining issues grouped by pilot impact and bounded follow-up so remediation remains small. + +**Independent Test**: Focused Regression Matrix classifies each included regression area with expected, observed, severity, and follow-up. + +## Required Final Report Structure + +The final Spec 413 report MUST use this structure: + +```markdown +# Spec 413 Audit Report - Focused Pilot Gate Recheck + +## A. Focused Pilot Gate Result +## B. Scope and Environment +## C. Dirty State +## D. Spec 407/412 Recheck Matrix +## E. Report/PDF State Matrix +## F. Focused Regression Matrix +## G. Browser Proof +## H. Runtime / Console Results +## I. Authorization / Customer-safe Boundary Results +## J. Remaining Findings +## K. Readiness Decision +## L. Validation / Audit Commands +## M. Recommended Next Step +``` + +## Required Matrices + +### Spec 407/412 Recheck Matrix + +Columns: + +- Original Finding +- Spec 407 Severity +- Spec 412 Claimed Remediation +- Current Browser Proof +- Current Result +- Residual Severity +- Pilot Impact +- Follow-up + +Required rows: + +- Management PDF surfacing +- Operation route load timeout +- Finding hash demotion +- Readonly no-access clarity + +### Report/PDF State Matrix + +Columns: + +- Review Pack +- Stored Report +- PDF File State +- Lifecycle State +- Expected UI Action +- Observed UI Action +- Download/Open Result +- Authorization Result +- Status +- Risk + +### Focused Regression Matrix + +Columns: + +- Area +- Probe +- Expected +- Observed +- Regression? +- Severity +- Follow-up + +Required rows: + +- Customer-safe report output +- Signed report route +- Unsigned report route +- PDF download authorization +- Cross-workspace report boundary +- OperationRun authorization +- Finding evidence/proof link +- Provider readonly boundary + +## Gate Decision Rules + +### PASS + +Use `PASS` only if: + +- No P0 findings remain. +- No P1 findings remain. +- Spec 407 P1 management PDF surfacing issue is closed. +- Operations index/detail complete usable browser navigation. +- Finding hashes are no longer prominent in default body. +- Readonly provider no-access behavior is clearer and safe. +- Signed/unsigned report behavior remains correct. +- Report/PDF authorization remains safe. +- No customer-safe, evidence/currentness, lifecycle, or report regression is observed. +- TenantPilot can proceed to Spec 414 without local browser-audit exclusions for the remediated findings. + +### PASS WITH CONDITIONS + +Use `PASS WITH CONDITIONS` only if: + +- No P0 findings remain. +- Remaining findings are P2/P3, or an explicitly acceptable P1 has a clear pilot exclusion. +- Management PDF surfacing is fixed or safely product-decided. +- Authorization and customer-safe boundaries remain intact. +- Controlled pilot preparation may proceed with documented exclusions. + +### FAIL + +Use `FAIL` if: + +- Any P0 remains. +- Ready PDF still appears primarily as "Generate management PDF". +- Report/PDF authorization regresses. +- Signed/unsigned report boundary regresses. +- Operations pages still block normal operator navigation. +- Finding hashes remain prominently exposed in default/customer-facing body. +- Readonly no-access fix weakens authorization. +- Spec 412 introduced a broader regression requiring remediation before pilot preparation. + +## Severity Rules + +- **P0 - Blocker**: serious safety or trust boundary failure, including unauthorized PDF/report download, cross-workspace report exposure, customer-safe report internal leakage, OperationRun unauthorized exposure, readonly provider access granted, or signed/unsigned report boundary failure. +- **P1 - High**: pilot preparation should not proceed without remediation or explicit exclusion, including ready PDF primary generate state, contradictory report states, operations navigation blocker, prominent default hashes, or signed report regression. +- **P2 - Medium**: productization issue that should be addressed before broader customer hardening, such as partial hash demotion, slow but usable operations route, or clearer-but-imperfect no-access copy. +- **P3 - Low**: minor copy or layout polish only. + +## Acceptance Criteria + +- **AC-413-001**: The gate execution is read-only. +- **AC-413-002**: Dirty state before and after is recorded. +- **AC-413-003**: Spec 412 implementation report is inspected. +- **AC-413-004**: All four Spec 407/412 remediation areas are browser-rechecked or explicitly marked unavailable with reason. +- **AC-413-005**: Management PDF surfacing is tested with a ready stored report/PDF where fixture exists. +- **AC-413-006**: PDF download/open authorization is tested. +- **AC-413-007**: Signed and unsigned report routes are tested. +- **AC-413-008**: OperationRun index and detail load behavior are tested. +- **AC-413-009**: Finding detail hash demotion is tested. +- **AC-413-010**: Readonly provider no-access behavior is tested. +- **AC-413-011**: Focused regression checks are performed for customer-safe, report, evidence/currentness, authorization, lifecycle, and provider boundaries. +- **AC-413-012**: Final report includes the required matrices and gate decision. +- **AC-413-013**: Final report clearly says whether Spec 414 may proceed. + +## Success Criteria + +- **SC-413-001**: The operator can decide whether TenantPilot is ready for Spec 414 controlled pilot preparation. +- **SC-413-002**: No known Spec 407/412 pilot-readiness finding is left unverified without an explicit limitation. +- **SC-413-003**: Any residual risk is classified by severity, pilot impact, and bounded follow-up. +- **SC-413-004**: No application implementation or runtime mutation is performed by the gate. + +## Edge Cases + +- Required actor or fixture is unavailable. +- Ready management PDF fixture is unavailable. +- Browser tool times out while the page appears usable; document the distinction carefully. +- A direct route returns intentional 403/404 for isolation. +- Signed route cannot be tested without exposing a private signed URL; record sanitized proof only. +- Existing broad tests have unrelated failures; classify only with focused evidence. + +## Out Of Scope + +- Full browser/UX/runtime audit. +- Application fixes. +- New or modified tests. +- Migrations, seeders, factories, or fixtures. +- UI redesign. +- New report templates or PDF architecture. +- New OperationRun architecture. +- New finding taxonomy. +- Provider onboarding redesign. +- Legal hold, purge, or export-before-delete governance. +- Staging/Dokploy deployment validation. +- Commercial lifecycle work. +- Support desk integration. +- Reopening or rewriting Specs 407 or 412. + +## Assumptions + +- The gate runs against local/dev unless the operator explicitly approves another environment. +- Existing actors and fixtures are used; unavailable actors or fixtures are limitations. +- Spec 412 implementation report is accepted as claimed-remediation context, not as proof. +- Report output is response-only unless the operator explicitly requests a saved spec-local report artifact. + +## Risks + +- Existing local data may not include a ready management PDF or required actor combinations. +- Browser auth/session setup may block customer reviewer, readonly, unauthorized, or cross-workspace proof. +- Streamed download bodies may require feature-route proof rather than browser-body assertions. +- Broad historical residual failures may confuse gate results; this spec requires focused classification. + +## Open Questions + +- None blocking preparation. During gate execution, record missing actors, fixtures, services, or routes as limitations instead of inventing proof. + +## Follow-up Spec Candidates + +Follow-up specs must be created only after the Spec 413 report identifies evidence-backed findings: + +- Bounded report/PDF surfacing remediation if ready PDF/report state remains P1. +- Bounded OperationRun browser-load remediation if operations navigation remains P1. +- Bounded authorization/customer-safe boundary remediation if report, customer output, provider, or operation access regresses. +- Spec 414 Controlled Pilot Preparation Pack if this gate passes or passes with acceptable documented conditions. + +## Candidate Selection Gate Result + +**PASS**. The selected candidate was directly supplied by the operator, is not already covered by an existing active or completed Spec 413 package, preserves completed Spec 407/412 history, aligns with the roadmap path toward controlled pilot preparation, and is scoped as a small read-only verification gate. + +## Spec Readiness Gate Result + +**PASS FOR IMPLEMENTATION PREPARATION** once `plan.md`, `tasks.md`, and `checklists/requirements.md` in this package are reviewed together. No product question blocks a later read-only gate execution. diff --git a/specs/413-focused-pilot-gate-recheck/tasks.md b/specs/413-focused-pilot-gate-recheck/tasks.md new file mode 100644 index 00000000..39a55322 --- /dev/null +++ b/specs/413-focused-pilot-gate-recheck/tasks.md @@ -0,0 +1,194 @@ +# Tasks: Spec 413 - Focused Pilot Gate Recheck + +**Input**: `specs/413-focused-pilot-gate-recheck/spec.md`, `plan.md`, `checklists/requirements.md`, user-provided Spec 413 draft, Spec 407/412 context, Spec 412 implementation report, roadmap/spec-candidate truth, and Product Surface Contract. + +**Prerequisites**: Working tree is clean or contains only user-approved planning changes for this spec package. Future execution must stop if unrelated dirty state appears. + +**Tests**: No test files are created or modified. Existing tests may be run only as validation commands and must be reported exactly. + +**Organization**: Tasks are grouped by gate execution phase. This is a read-only gate, not application implementation. + +## Execution Close-Out + +- [x] Executed on 2026-06-24 as a read-only focused gate. Tasks below are checked when the required probe/report step was performed or when a missing live fixture/actor limitation was explicitly recorded with existing test proof. +- [x] No application code, tests, migrations, seeders, factories, routes, policies, config, views, generated assets, runtime data, docs outside this spec package, or completed specs were intentionally modified. +- [x] Gate result recorded in the assistant close-out report as `PASS WITH CONDITIONS`. + +## Test Governance Checklist + +- [x] Test purpose is classified as Browser/read-only audit evidence. +- [x] Affected validation lanes are recorded before execution. +- [x] No new test family, fixture family, seed, factory, helper, or browser harness is created. +- [x] Browser proof is required as gate output. +- [x] Human Product Sanity and Product Surface close-out are recorded in the final report. +- [x] Final report states Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, browser/test result, deployment impact, visible complexity outcome, and no application implementation. + +## Phase 1: Baseline and Safety + +**Goal**: Prove the gate starts from a known state and stays read-only. + +- [x] T001 Read this spec package: `spec.md`, `plan.md`, `tasks.md`, and `checklists/requirements.md`. +- [x] T002 Confirm current branch, HEAD commit, dirty state, untracked files, and active environment. +- [x] T003 Run `git diff --check` before browser work and record result. +- [x] T004 Record base URL using repo/Laravel configuration or Laravel Boost URL tooling where available. +- [x] T005 Identify available actors/fixtures: workspace admin, customer reviewer, readonly/limited actor, unauthorized actor, cross-workspace actor, and system operator. +- [x] T006 Confirm no application code, tests, migrations, seeders, factories, routes, policies, config, views, generated assets, runtime data, docs outside this spec package, or completed specs will be edited. +- [x] T007 Stop if unrelated dirty state or unsafe environment conditions are present. + +## Phase 2: Spec 412 Claim Inspection + +**Goal**: Turn Spec 412 claims into focused recheck targets. + +- [x] T008 Read `specs/407-full-browser-ux-runtime-audit/spec.md`, `plan.md`, and `tasks.md` as historical context only. +- [x] T009 Read `specs/412-pilot-readiness-remediation-pack/spec.md`, `plan.md`, `tasks.md`, and `implementation-report.md`. +- [x] T010 Extract the Spec 412 claimed remediation for management PDF surfacing. +- [x] T011 Extract the Spec 412 claimed remediation for OperationRun index/detail browser navigation. +- [x] T012 Extract the Spec 412 claimed remediation for finding hash demotion. +- [x] T013 Extract the Spec 412 claimed remediation for readonly provider no-access clarity. +- [x] T014 Record Spec 412 tests/browser proof claimed and any unrelated residual failures documented there. +- [x] T015 Confirm Specs 407 and 412 remain completed/historical context and are not modified. + +## Phase 3: Route and Fixture Probe + +**Goal**: Identify exact current routes, records, and actors for safe focused proof. + +- [x] T016 List or inspect routes matching review, report, PDF, download, operation, finding, provider, connection, signed, and customer report paths. +- [x] T017 Identify a review pack with a ready stored management PDF, or record that no ready fixture exists. +- [x] T018 Identify stored report/report receipt state connected to the selected review pack, or record limitation. +- [x] T019 Identify authorized management PDF download/open route for the selected ready PDF, or record limitation. +- [x] T020 Identify unauthorized and cross-workspace report/PDF direct-route probes that do not expose private signed URLs in the final report. +- [x] T021 Identify valid signed report and unsigned/invalid report probes, or record limitation. +- [x] T022 Identify admin OperationRun index and at least one OperationRun detail route. +- [x] T023 Identify a finding detail route containing prior hash/fingerprint risk or equivalent technical identifiers. +- [x] T024 Identify readonly/limited provider-connection route and authorized comparison route. +- [x] T025 Identify customer review/report path connected to the PDF/report flow where available. + +## Phase 4: Management PDF and Report/PDF Recheck + +**Goal**: Verify report/PDF state agreement and authorization remain safe. + +**Independent Test**: The Report/PDF State Matrix contains ready, missing/failed/unavailable, authorized, unauthorized, cross-workspace, signed, and unsigned outcomes or explicit limitations. + +- [x] T026 Open review pack detail for a ready stored management PDF and record expected vs observed primary action. +- [x] T027 Confirm ready PDF state shows ready/download/open and does not show "Generate management PDF" as primary. Live fixture was customer-limited/internal-preview only; recorded as a condition rather than a clean customer-safe positive proof. +- [x] T028 Compare review-pack UI state to stored report/report receipt state. +- [x] T029 Open/download existing management PDF as authorized admin where safe and record outcome without exposing private URL details. Live customer-safe open was unavailable by gate state; existing browser proof was recorded. +- [x] T030 Probe unauthorized direct PDF/download access and record authorization result. +- [x] T031 Probe cross-workspace PDF/download access and record authorization result. +- [x] T032 Open valid signed report route and record customer-safe result. Live signed customer output returned 404 by design for the limited fixture; existing browser proof was recorded. +- [x] T033 Open unsigned/invalid report route and record blocked/invalid-signature result. +- [x] T034 Record customer-safe report output checks for internal proof, raw IDs, raw OperationRun details, raw provider payloads, file paths, stack traces, and private URLs. + +## Phase 5: OperationRun Load Recheck + +**Goal**: Verify operations pages complete usable browser navigation. + +**Independent Test**: Browser proof table records operations index/detail load result, console/runtime state, and authorization outcome. + +- [x] T035 Open admin operations index and record load completion, runtime status, console output, network failures, and any timeout distinction. +- [x] T036 Open OperationRun detail and record load completion, runtime status, console output, network failures, and any timeout distinction. +- [x] T037 Confirm no current OperationRun route 500 is observed. +- [x] T038 Confirm no fatal Livewire/Filament error appears. +- [x] T039 Check OperationRun proof links from related surfaces where available. +- [x] T040 Probe unauthorized or cross-workspace OperationRun access where safe and record authorization result. + +## Phase 6: Finding Detail Hash Recheck + +**Goal**: Verify raw internal hashes are not default product content. + +**Independent Test**: Browser proof records finding detail default body and where technical identifiers appear, if present. + +- [x] T041 Open selected finding detail as authorized operator. +- [x] T042 Confirm default body does not prominently expose fingerprint hash. +- [x] T043 Confirm default body does not prominently expose scope hash or source fingerprint. +- [x] T044 Confirm technical hashes, if still present, are demoted to collapsed/support/operator/technical detail. +- [x] T045 Confirm customer-facing/default review context does not expose internal hash fields where available. +- [x] T046 Confirm human-readable finding triage information remains available. + +## Phase 7: Readonly Provider No-Access Recheck + +**Goal**: Verify access remains denied and no-access is clearer/safe. + +**Independent Test**: Browser proof records readonly route, authorized comparison, redirect/no-access behavior, and leak checks. + +- [x] T047 Open provider-connection route as readonly/limited actor. No live same-workspace missing-capability actor existed; existing browser smoke proof and cross-workspace direct-route probe were recorded. +- [x] T048 Confirm actor remains blocked from unauthorized provider connection access. +- [x] T049 Confirm no confusing authenticated-user-to-login loop occurs. +- [x] T050 Confirm no provider, workspace, or record data leaks to non-entitled actors. +- [x] T051 Confirm no-access/missing permission/missing membership message is clearer and accurate where visible. +- [x] T052 Open authorized provider connection route for comparison where safe. + +## Phase 8: Focused Regression Checks + +**Goal**: Catch adjacent regressions without widening into a full audit. + +- [x] T053 Check customer-safe report output regression. +- [x] T054 Check evidence/currentness labels in report/review path. +- [x] T055 Check report lifecycle state display. +- [x] T056 Check OperationRun authorization regression. +- [x] T057 Check workspace/environment scoping regression. +- [x] T058 Check signed/unsigned report boundary regression. +- [x] T059 Check finding evidence/proof link regression. +- [x] T060 Check provider authorization boundary regression. +- [x] T061 Fill the Focused Regression Matrix with expected, observed, severity, and follow-up. + +## Phase 9: Gate Decision and Report + +**Goal**: Produce the required gate report and stop before fixes. + +- [x] T062 Fill the Spec 407/412 Recheck Matrix. +- [x] T063 Fill the Report/PDF State Matrix. +- [x] T064 Fill the Focused Regression Matrix. +- [x] T065 Fill Browser Proof table with surface, actor, workspace/environment, state, expected, result, and notes. +- [x] T066 Summarize runtime/backend logs, browser console, OperationRun route results, report route results, provider no-access route, and current 500/403/404 findings. +- [x] T067 Summarize authorization and customer-safe boundary results. +- [x] T068 List remaining findings by P0/P1/P2/P3 using the required finding fields. +- [x] T069 Set Focused Pilot Gate Result to `PASS`, `PASS WITH CONDITIONS`, or `FAIL` according to this spec. +- [x] T070 Fill Readiness Decision table for Spec 414, controlled pilot planning, customer-facing hardening, sales/demo scripted path, and broader customer claims. +- [x] T071 Record validation/audit commands run and exact results. +- [x] T072 Record dirty state after the gate, including tracked/untracked changes. +- [x] T073 Confirm no application implementation, code, tests, migrations, config, routes, views, policies, models, services, jobs, Filament resources/pages/widgets, Livewire components, Blade views, CSS, JavaScript, seeders, factories, lock files, generated assets, runtime data, docs outside this package, or completed specs were modified. +- [x] T074 State Livewire v4 compliance, provider registration location, global search posture, destructive/high-impact action posture, asset strategy, browser/test result, deployment impact, visible complexity outcome, and no completed-spec rewrite assertion. +- [x] T075 Recommend next step: Spec 414 if gate passes, one bounded remediation spec if gate fails, or explicit exclusions if pass with conditions. + +## Explicit Non-Goals + +- [x] NT001 Do not perform a full browser/UX/runtime audit. +- [x] NT002 Do not implement fixes. +- [x] NT003 Do not add or modify tests. +- [x] NT004 Do not modify application runtime files. +- [x] NT005 Do not create or mutate fixtures, seed data, database schema, provider connections, memberships, workspaces, environments, reports, restore runs, or runtime data intentionally. +- [x] NT006 Do not execute destructive/high-impact actions. +- [x] NT007 Do not expose private signed URLs, secrets, credentials, raw provider payloads, stack traces, or sensitive customer data in the final report. +- [x] NT008 Do not rewrite completed Specs 407 or 412 or remove validation, task, smoke, browser, screenshot, close-out, or review history from completed specs. + +## Dependencies and Execution Order + +- Phase 1 blocks all later phases. +- Phase 2 must precede route/fixture probe. +- Phase 3 must precede browser recheck. +- Phases 4 through 8 may be executed in the safest practical order after route/fixture probe. +- Phase 9 must happen last and must stop before remediation. + +## Recommended Future Execution Commands + +Use Sail where possible and report exact outcomes: + +```bash +git status --short --branch +git diff --name-only +git diff --check +git log -1 --oneline +cd apps/platform && ./vendor/bin/sail artisan route:list +cd apps/platform && ./vendor/bin/sail artisan test --filter=ReviewPack +cd apps/platform && ./vendor/bin/sail artisan test --filter=Report +cd apps/platform && ./vendor/bin/sail artisan test --filter=StoredReport +cd apps/platform && ./vendor/bin/sail artisan test --filter=ManagementReport +cd apps/platform && ./vendor/bin/sail artisan test --filter=Pdf +cd apps/platform && ./vendor/bin/sail artisan test --filter=OperationRun +cd apps/platform && ./vendor/bin/sail artisan test --filter=Finding +cd apps/platform && ./vendor/bin/sail artisan test --filter=ProviderConnection +cd apps/platform && ./vendor/bin/sail artisan test --filter=Authorization +``` + +Run only commands appropriate for the active local environment. Do not claim proof for commands not run.