Vet Laravel Package

Technical Evaluation

Architecture fit. Vet is a dev-only Composer dependency plus an Artisan command, so it slots in beside the pipeline rather than inside the application. The architecturally significant artifact is not the command but the committed vet.json at repository root: it converts dependency-adoption policy into a diffable, reviewable, revertable file that lives in the same PR as the change that motivated it. That is a governance capability, and it is the thing we would actually be adopting. Judge fit on whether we want version-age/trust policy expressed in version control instead of CI YAML or reviewer memory — not on whether the scanner is clever.

Integration feasibility. Low technical effort, high ambiguity cost. One composer require --dev laravel/vet, one php artisan vet invocation, one CI step. The undocumented parts are the ones that decide whether the integration is real: exit codes are claimed to be CI-friendly but are not enumerated anywhere in the provided sources, so the gate contract must be captured empirically ($? for pass, fail, and config-error) and asserted in a small CI test on the pinned version. Likewise, whether the command reads composer.lock or re-resolves, and whether it evaluates transitive dependencies or only direct require/require-dev, are unanswered — and both determine whether results are reproducible across machines.

Technical risk. Four risks dominate, in order:

1. Scope ambiguity (highest). The manifest description sells Laravel-aware static analysis — request input, mass assignment, queries, views, "PHPStan-powered." The changelog and config surface describe a Composer trust file whose only documented rule is minimum release age. These are different products with different buyers and different success criteria. Until someone reads src/ on the pinned version and answers which one ships, any roadmap statement is unfounded.
2. Pre-1.0 schema churn. A config schema under a 0.x version means a routine composer update can break the pipeline silently. Pin exact; treat each minor as a reviewable PR.
3. Unverified surface is the surface that matters. Private registries, path repositories, and VCS dependencies are the least likely to be audited and the most likely to be skipped. Whether those fail open or closed determines whether our enforcement is a control or a suggestion.
4. Data-integrity flag. The advertised last release date is 2026-09-27 — a future date. Verify with composer show laravel/vet before that number appears in any SLA, audit narrative, or exec deck.

Key questions. Which product ships in the version we pin? Are exit codes stable enough to gate on, and what are they for config-parse failure? Does an offline or egress-restricted runner fail open or closed? Does it cover transitive dependencies? Do private/VCS sources get skipped silently? Is the release-age threshold the only shipped rule, or is the "configurable rules" claim backed by implemented checks? Who owns vet.json, and is that person named before or after the pilot?

Integration Approach

Stack fit. Composer/Laravel/PHP with composer.lock committed. Dev dependency only — it must never reach production runtime. Fits as a discrete pipeline step in the same job that already runs composer install, so there is no new build stage and no new artifact to store.

Sequencing — this is the load-bearing decision. Vet governs which versions are admissible. composer audit governs what has CVEs. Dependabot/Renovate govern when we move. Deploy Vet after audit and the update bot, never before. Reversed, the first-week experience is "the new tool blocks security fixes," and the argument for keeping it is lost before the pilot produces any evidence.

Then ratchet in three bounded stages:

• Weeks 1–2 — report only. Run on every branch, fail on nothing. Measure runtime against the largest lockfile in the estate. Output is a diff of what the policy would have blocked: the baseline that makes the go/no-go decision arguable with data.
• Weeks 3–6 — fail only on dependency-touching PRs. Gate changes to composer.json / composer.lock. This bounds blast radius to the PRs that actually warrant scrutiny and keeps unrelated work fast.
• Week 7+ — all dependency merges gated, plus a scheduled weekly re-audit of untouched lockfiles to catch drift on repos nobody is pushing to.

Track blocked-bump rate across the ratchet. If bot-opened patch bumps are repeatedly blocked with no remedy, the threshold is too aggressive or the ordering is wrong — that is a threshold decision, not a tooling failure.

Migration path. Start with the smallest viable vet.json — since v0.2.1 a near-empty file holding only the minimum release age is legal. Threshold 7 days, moving to 14 or 30 once blocked-bump data exists. Add rules only when a fault motivates them; every extra rule is another thing to debug under pressure. First target is one non-critical repository where being wrong is cheap, not a portfolio mandate — pilot and portfolio rollout are two separate decisions and should not share a roadmap line.

Compatibility. Pin the exact version, no caret constraint. Pin the base image too if the check depends on network access to Packagist for release timestamps — test on a runner with egress restricted to the internal mirror before stage 2, and decide explicitly whether offline should fail open or closed. Monorepos with independently resolved lockfiles should get one vet.json per lockfile, but confirm how the command locates the file before standardising on a layout; that behaviour is undocumented.

Non-coverage must be stated in the PR template. Vet is not a CVE scanner and produces no SBOM. Describe it precisely as "version-age and package-trust policy." The word "audit" invites reviewers to assume advisory coverage that is not there, and that assumption is how a control gets credit it did not earn.

Operational Impact

Maintenance. Two recurring costs: pin-and-review on every minor (schema can move under us pre-1.0), and a possible fork. At 185 stars and zero dependents, we would be among the first production users. There is no community answer bank, so the fast debugging path is reading src/, and a needed fix may mean maintaining a fork rather than waiting on a merge. Upstream contribution has an unusual shape — .hod/ plus AGENTS.md, rules written for coding agents, a no-comments-in-code policy — which raises the cost of a quick upstream patch. Budget the fork line item at adoption, not at first incident.

Support. No vendor, no SLA, no stable public API. This is a volunteer-maintained pre-1.0 package with a single implied maintainer set. Acceptable only for an internal developer-productivity control, unacceptable for anything a compliance attestation leans on. Name an internal owner for vet.json — exceptions are a PR to that file, reviewed by that owner, dated and reversible, with no out-of-band Slack overrides.

Scaling. Cost scales with pipeline runs and lockfile size, not with headcount. The two scaling unknowns are runtime on the largest lockfile and Packagist metadata lookups per run. Both are measurable in week 1 of the pilot and both should be measured before enforcement. Network dependence is a real availability coupling: Packagist outages become build outages, and air-gapped or egress-restricted runners become blocked runners. Decide the offline posture deliberately rather than discovering it.

Failure modes to design against.

• Silent gate death — a minor bump changes exit codes and the CI step passes forever. Mitigation: assert exit codes in a tiny CI test on the pinned version.
• Fail-open on unverified sources — private registries and VCS dependencies skipped silently, giving false assurance in a security review. Mitigation: determine skip-vs-fail behaviour and whether it is configurable, before any review claims coverage.
• Blocking security fixes — sequencing mistake, discussed above; the most likely reason the pilot gets cancelled.
• Config drift — a vet.json that no longer parses or sits at a path the command does not expect (v0.2.1's empty-file fix exists because near-empty config was fragile). Mitigation: keep the file minimal, and bisect by removing rules rather than hunting for a verbose flag that is not documented.
• Incident-time improvisation — write the freeze and its rollback into the runbook together, while calm. A supply-chain scare should become a dated, attributed one-line vet.json commit with an obvious revert.

Ramp-up. Roughly an hour of source reading to resolve scope on the pinned version, plus a days-scale report-only pilot on one repo. That is cheap enough to justify on the "review evidence moves earlier and smaller" argument alone. What is not cheap is building process around the wrong product: do not put "AppSec scanner" on a roadmap slide, and do not spend six weeks on rollout before confirming the rule you actually want is implemented — write that policy in vet.json and let it fail; the failure is the answer, and it costs one commit instead of a quarter.