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)

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:

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.