Laravel Toolkit Laravel Package

Technical Evaluation

Architecture fit. v0.4.0 confirms the package's role as a developer-workflow dependency, not a runtime one: Artisan commands (toolkit:tia, toolkit:preflight, toolkit:retry), Composer script orchestration, and a hook guard. None of this should appear in production deployments, so the architecture question is whether it belongs in require-dev only and whether the guard hooks are mandatory or opt-in. The new toolkit:tia command is the first genuine piece of state management in the package — it reads and writes Pest's TIA cache, publishes a baseline keyed to a target branch, and re-keys it per worktree path. That shifts the package from "convenience wrappers" to "owner of a correctness-sensitive artifact," which is a meaningful change in architectural weight for a 0.x tool.

Integration feasibility. Low effort. Consuming apps get the command via the package; the stated goal is that apps "stop carrying their own copy of it in scripts," so integration is mostly deletion of bespoke script logic plus adoption of toolkit:tia publish on merge and toolkit:tia inherit on branch creation. The --no-notify addition to toolkit:retry is a consistency fix and implies notification hooks are a shared concern across commands — worth confirming the flag matrix is uniform, because inconsistent flags are the usual source of CI/script drift.

Technical risk.

• Highest risk — silent under-testing. TIA selects tests by impact. An inherited baseline that is stale, incomplete, or recorded against the wrong base commit causes the suite to skip tests that the change actually breaks. The observable symptom is a green preflight on a red change, i.e. a false-negative quality gate rather than a crash. The release directly targets this (branch-scoped publish, per-worktree naming, "any base branch, not only main"), but the correctness proof is not evident from the notes — nothing describes what happens when inherit finds no baseline, a partial baseline, or a baseline for a different commit.
• Coupled to an upstream private format. The logic "tracks Pest's cache format." That is an explicit maintenance liability tied to Pest minor releases; a Pest upgrade can invalidate inherited baselines or corrupt behaviour in ways that manifest as wrong test selection, not as errors.
• False confidence in the new guardrail. toolkit:preflight refusing a coverage gate that disables TIA is a good, opinionated guard, but it is a behavioural change: existing pipelines passing --exclude-testsuite=Browser (or similar) into preflight will now fail or be rejected. That is effectively a soft breaking change for anyone with a filter in their preflight path, and it needs surfacing in upgrade notes.
• Pre-1.0 surface instability. v0.4.0 both adds commands and fixes a hook that was blocking a legitimate Pest flag; expect the CLI contract to keep moving.

Key questions.

1. What does toolkit:tia inherit do when no published baseline exists for the base branch — fail loudly, or silently fall back to a full run? Full-run fallback is acceptable; silent empty selection is not.
2. Is a baseline tagged with its source commit, and does inherit reject a baseline that does not match the base branch's current tip?
3. How is the Pest version pinned, and what happens on a Pest minor bump that changes cache layout — detection, or corruption?
4. Is the preflight filter rejection a hard error or an auto-strip? And is it documented as a behaviour change for existing users?
5. Are the guard hooks opt-in per repository, and can pest --baseline and other print-only invocations be exercised without disabling the hook wholesale?
6. Is there any CI signal proving an inherited baseline matches a full run (a shadow-run comparison), or is correctness asserted only by intent?

Integration Approach

Stack fit. Assumes Laravel + Artisan + Composer scripts + Pest with TIA enabled, plus PHPStan (the two fixed PHPStan errors imply larastan/phpstan is part of the toolkit's own gate and probably the consuming gate). The worktree model assumes a branch-per-ticket workflow where worktrees are cut from a base branch and land back into it — a pattern that maps well onto agent-assisted or parallel-ticket development. Teams not using worktrees get no benefit from the headline feature; teams not using Pest TIA get nothing at all from it. Scope the rollout decision accordingly.

Migration path. Two independent tracks, and they should be sequenced that way:

1. Low-risk, adopt now: --no-notify on toolkit:retry, the PHPStan fixes, and the guard-hook fix for pest --baseline. Pure defect relief.
2. Requires validation: replacing per-app TIA cache scripts with toolkit:tia check / inherit / publish. Existing copy-the-cache scripts should stay in place until a shadow comparison shows inherited baselines select the same tests as a full run on a representative sample of branches.
3. Requires coordination: the preflight filter rejection. Audit every CI job, Makefile, and Composer script that passes a selection filter (--exclude-testsuite, --testsuite, group filters) into toolkit:preflight before bumping, and move those invocations to plain composer test.

Compatibility. Dev-dependency only, so no runtime compatibility surface — the risk is entirely in dev/CI environments. Two constraints to pin: (a) the Pest version range the cache-format logic supports, and (b) the minimum package version where toolkit:tia exists, since scripts referencing it will fail hard on older pins. Note also the base-branch support is explicitly not main-only, which matters for teams on develop/release-branch models — verify the publish target is derivable automatically rather than hardcoded per repo.

Sequencing. Pin and adopt the tooling fixes → validate toolkit:tia in shadow mode on one repository → wire publish into the merge/land step of CI (this is the step most likely to be forgotten; without it, baselines are never refreshed and inherit degrades to nothing) → remove per-app cache scripts → audit and update filtered preflight invocations → roll out to remaining repos.

Operational Impact

Maintenance. The package now owns two pieces of external state: per-worktree TIA caches and per-branch published baselines. Both need lifecycle rules — where baselines live, how long they persist, when they are invalidated, and what prunes them. Add the Pest-format dependency to the upgrade checklist: any Pest bump triggers a re-validation of TIA inheritance. Because this is a 0.x dev tool, expect to track releases actively rather than pin-and-forget; a stale pin is safer than a silent behaviour change, so pin exact versions in require-dev.

Support. Support load will concentrate in one failure shape: "preflight passed but CI/main failed." Triage requires knowing which baseline was inherited, from which commit, and which tests were skipped — so a toolkit:tia check that prints the resolved baseline provenance, source commit, and selected-test count is the single most valuable support affordance. Without that output, every false-green is an unguided investigation. Secondary load: developers whose preflight now fails after the coverage-gate change; a clear error message pointing at the "Running Tests" guideline mitigates most of it.

Scaling. Scales well mechanically — per-worktree cache naming removes the contention of many tickets sharing one cache, which is the actual win for parallel/agent-driven workflows. Two scaling caveats: baseline publication must be safe under concurrent merges (last-writer-wins is usually fine, but a partially written baseline is not — check for atomic publish), and the number of published baselines grows with branch count, so retention needs a policy.

Failure modes to instrument.

• inherit finds nothing → ensure it degrades to a full run, never to an empty selection.
• Stale baseline after a base-branch force-push or rebase → detect via commit mismatch, or accept and document the false-negative window.
• publish never runs (merge path not wired) → baselines silently age; alert on baseline age per branch.
• Pest format drift → hard-fail on unrecognised cache layout rather than reading it leniently.
• Preflight filter rejection → fail fast with actionable message; do not auto-strip user intent silently.
• Guard hook over-blocking → keep an explicit allowlist for print-only Pest invocations, with the --baseline fix as precedent.

Ramp-up. Low for individuals: three commands, one of which (check) is diagnostic. The real ramp-up is process, not knowledge — the team must internalise that publishing on land is a required step, and that a passing preflight is only as trustworthy as the baseline behind it. Budget a short written runbook covering baseline lifecycle, the preflight filter rule, and the false-green triage path. Overall: worth adopting for worktree-heavy, Pest-TIA-enabled teams, contingent on demonstrating that an inherited baseline and a full run agree.