TenantAtlas/specs/413-focused-pilot-gate-recheck/plan.md

# 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.