Sloppy Laravel Package

Technical Evaluation

Architecture fit

• Ships as a require-dev Composer package with a Laravel service provider and Artisan commands (sloppy:agents, etc.), plus a standalone vendor/bin/sloppy binary. Nothing is loaded in production request paths, so the blast radius of adoption is small and reversible.
• Two distinct integration surfaces, which a TPM should treat as two separate decisions:
  1. Rule engine inside PHPStan via heyosseus/phpstan-sloppy (includes: vendor/heyosseus/phpstan-sloppy/extension.neon). This reuses the squiggles, baselines, and CI plumbing the team already has. Lowest-friction, highest-leverage.
  2. The standalone CLI: git-diff review (diff, ci), fix pass (fix — Rector + Pint), Pest expectations, CI annotation formats (GitHub/GitLab/SARIF), agent rulesets, hooks, and the MCP server. These are net-new surfaces and need their own review.
• The product thesis — deterministic, local, no LLM, aimed at debt introduced by coding agents — is a good fit for a Laravel shop that has already accepted AI-assisted PRs. It converts an unbounded review-cost problem into a configurable, diff-scoped gate.
• The PHPStan extension is the strategically correct default. vendor/bin/sloppy should be reserved for what PHPStan does not do: diff scoping, the fix pass, hooks, MCP.

Integration feasibility

• Installation is two composer require --dev lines, a published config/sloppy.php, and one .neon include. The three artifacts a TPM should require the team to read before config work are sloppy rules (authoritative rule list), the config file (exclude, fail_on, architecture, SL301/SL303 layer suffixes), and a read-only scan --path=app.
• Output formats map onto existing CI without a new dashboard: ci --format=github, --format=gitlab, --format=sarif. Paths are repository-root-relative, which matters for monorepos.
• The agent-hook story is genuinely the differentiator, and it is also the part with the most organizational friction: it writes .claude/settings.json, .gemini/settings.json, .codex/hooks.json, and generated rulesets (CLAUDE.md, GEMINI.md, AGENTS.md). That is file mutation inside every developer's workspace — a policy question, not just a technical one.
• Feasible inside one sprint for a pilot repo. Multi-host rollout is a comms-and-trust exercise, not an engineering one.

Technical risk

• Vendor/bus-factor risk is the headline. 223 stars, 0 dependents, a single-maintainer namespace, and no commercial support. MIT license means forking is a legal non-issue, but a fork is an engineering commitment the TPM must budget for if the pilot succeeds.
• Metadata hygiene flag. description.md describes an unrelated Eloquent seeder/faker package while every other source describes static analysis. Resolve package identity before security review or internal pitch — this is exactly the shape of a typosquat or a copy-paste metadata error, and it will be the first question a reviewer asks. Also verify the Last release: 2026-11-02 date against the actual tag; a future-dated release is a provenance question.
• 1.6.0 is a breaking release disguised as a correctness release. Config is now validated (wrong type or out-of-range value → exit code 2, listing every problem), unknown keys warn only, the standalone binary merges user config over defaults (so a sloppy.php that omitted fail_on or exclude now inherits them), SL501 fingerprints dropped line numbers (re-baseline required), and more code is analyzed (top-level functions, closures, extended base models). Any team that pins loosely and upgrades will see a pipeline stop.
• Exit-code semantics are a trap for existing CI. Exit 2 means "you told me something invalid," not "you have findings." Scripts that only check non-zero will conflate config errors with quality failures and produce confusing failures for developers.
• False-positive rate is the adoption risk. Hooks hand findings back to an agent immediately after an edit and send it back once before it finishes. That behavior is bounded (once, not a loop), but bad rules still translate into agent rework and developer distrust. Rules like SL203, SL204/SL210, SL108/SL110, SL501 suppression detection, and "a class named Client is not an HTTP client" all received fixes in 1.6 — evidence the rule surface is still settling.
• Instruction-source precedence. Where Laravel Boost is installed, the Boost guideline is used instead of Sloppy's ruleset file. That is probably the right precedence, but it means the generated CLAUDE.md/GEMINI.md/AGENTS.md is not the effective instruction set in a Boost repo. Verify which one wins before assuming.
• Version churn. 1.6.0 and 1.7.0 land close together with meaningful behavioral changes. Treat the tool as a fast-moving dev dependency: pin minors, read release notes.

Key questions

• Who owns the gate — platform/dev-experience, or each application team? Ownership determines whether config is centralized or drifts per repo.
• What is the baseline policy? Who is allowed to run sloppy baseline, and is baseline regeneration a reviewed change or a reflex?
• Which agent hosts are actually in use (Claude Code vs Gemini CLI vs Codex), and does the org permit tooling that writes per-host settings files?
• Is PHPStan already enforced, and where — IDE, CI, or both? The extension path only pays off if PHPStan is already a habit.
• What false-positive rate is tolerable before developers disable hooks? Define the number before the pilot, not after.
• Acceptable support posture for an MIT dev dependency: internal champion with a runbook, or a fork budget?
• Does the Codex trust step (/hooks, run from project root) fit the team's onboarding, or will it be silently skipped?

Integration Approach

Stack fit

• Requires a Laravel/PHP codebase already comfortable with Composer dev dependencies, PHPStan, and a PR-based CI gate. Pint and Rector are either already present or get introduced by sloppy fix — check whether that is additive or competing with an existing Pint/Rector configuration. fix will not overwrite a Rector config it did not write, and Pint runs only on a Laravel project or on changed files, which keeps it fast.
• No production dependency, no runtime middleware, no database, no queue. There is no infrastructure workstream here — only developer tooling and CI.
• Verify PHP version and OS coverage against the team's matrix; 1.6 added Windows and PHP 8.5 to CI, plus a --no-dev install path test.

Migration path Three phases, each with a different risk profile:

1. Visibility (read-only). Publish config, run sloppy rules, run scan --path=app, record the pre-existing debt count. Nothing blocks. Outputs are used to size the problem and pick exclude / layer suffixes.
2. Advisory gate. Wire sloppy ci --format=<github|gitlab|sarif> into PR jobs with fail_on: none. Run sloppy diff --merge-base locally as the developer-facing view. Measure what actually fires.
3. Enforcing gate. Raise fail_on, add Pest expectations so "no new findings" is asserted in the suite developers already run, and only then turn on agent hooks for a pilot repo and a single host.

The only "migration artifact" is the baseline. sloppy baseline records existing findings (notably SL501 suppressions) so legacy debt stops being reported; PHPStan baseline-growth detection separately stops the PHPStan baseline from silently absorbing new debt. Both need an owner and a review rule.

Compatibility

• Exit codes: update CI scripts to distinguish 1 (findings) from 2 (invalid invocation/config/parse). Add --allow-parse-errors where a partially broken tree should not fail the job.
• Config strictness: any existing sloppy.php should be audited against the 1.6 schema before upgrade. A previously ignored option now either warns (unknown key, with "did you mean") or stops the run.
• Monorepos: projects living in a subdirectory of their repository, quoted/non-ASCII filenames, mv-moved files, deleted files, and repos with no commits yet are handled as of 1.6. Validate on one monorepo repo before generalizing.
• Agent hosts: agents install --host=gemini --host=codex is repeatable and additive; without --host it wires Claude Code only, as before. --local is unsupported for Gemini/Codex and will skip with a warning. agents uninstall --host=<x> gives scoped rollback.

Sequencing

1. Confirm package identity and provenance (resolve the description.md mismatch, confirm the tag/binary surface).
2. Pick one pilot repo with active agent usage and existing PHPStan.
3. scan → rules audit → config (exclude, fail_on: none, layer suffixes).
4. Add PHPStan extension include; confirm findings appear in IDE and CI.
5. Add ci --format=… as advisory; two-week measurement window.
6. Add diff --merge-base to the documented local pre-commit flow.
7. Install agent hooks for one host on the pilot repo; require developers to accept the host trust prompt where applicable.
8. Add sloppy fix --dry-run as the agent's "done" step, with --no-rector as the fallback.
9. Prune excludes using observed false positives; then raise fail_on.
10. Add Pest expectations as the durable invariant.
11. Roll to second host, then remaining repos. Regenerate rulesets in a script rather than hand-maintaining three documents.
12. Introduce MCP + coverage-aware reading order only for teams running tool-driven agents.

Operational Impact

Maintenance

• Small but nonzero. Recurring items: pin and review dependency upgrades (1.6's config validation is the template for future breaks), regenerate CLAUDE.md/GEMINI.md/AGENTS.md via sloppy rules --format=… in the dependency-update script, and review baseline changes as PRs.
• Config should be centralized (shared template or a small internal package) rather than copied per repo, or exclude and layer suffixes will drift within a quarter.
• Assign one named owner. An unowned gate is a gate that gets disabled the first time it blocks a release.

Support

• MIT, community-maintained, no SLA, no dependents to lean on for incident precedent. Classify as a dev-only dependency in the risk register: a failure slows development, it does not take down production.
• Minimum viable support posture: an internal champion, a runbook covering exit-code 2 triage, the --allow-parse-errors escape hatch, agents uninstall --host=… as scoped rollback, and a documented decision point on forking if upstream goes quiet.
• The MCP server and hooks are local processes reading and writing repo files. Security review should cover what those processes write and where, even though nothing leaves the machine.

Scaling

• Cost is dominated by CI minutes and developer attention, not infrastructure.
• Diff-scoped runs are the scaling mechanism: diff/ci with --merge-base (already the default in ci) bound runtime to branch size rather than tree size. Full scan on a mature Laravel app will produce a wall of pre-existing findings — keep it out of the hot path after the initial baseline.
• watch polls and manipulates the terminal; it is a convenience, not a gate, and hooks explicitly skip the score to stay fast.
• Repo count drives config duplication more than compute. Ten repos means ten configs to keep in sync and ten fail_on decisions — plan the centralization before repo three, not repo ten.

Failure modes

• Pipeline hard-stops on upgrade from config validation or the standalone config merge. Detect via version pinning and a canary repo.
• Exit-code conflation producing "why is CI red" incidents that are actually misconfiguration.
• False-positive fatigue → developers disable hooks or set fail_on: none permanently. The two-week measurement window with fail_on: none is the mitigation, along with pruning exclude from observed data.
• Baseline laundering: someone regenerates the PHPStan baseline and a hundred new findings disappear. This is the classic failure mode and the reason baseline-growth detection exists; treat baseline diffs as reviewable signals.
• Instruction precedence confusion in Boost repos: the generated ruleset file exists but is not effective. Verify, don't assume.
• Manual onboarding steps skipped — notably the Codex /hooks trust action and starting Codex from the project root, since hooks invoke php vendor/bin/sloppy from the session directory.
• Stale SL501 baselines after the 1.6 fingerprint change: baselined entries reappear once until sloppy baseline is re-run.
• MCP stdout contamination breaking protocol handling — fixed in 1.6, but a reason to pin and not float.

Ramp-up

• Estimate roughly half a day per developer for onboarding: read sloppy rules, understand the three config knobs, learn the diff --merge-base local flow, learn fix --dry-run (note: exits 0 even with pending changes).
• Two weeks measurement-only, then two to four weeks advisory before enforcement. Budget the enforcement flip as a scheduled change with comms, not an ambient config edit.
• Define success metrics up front: findings per agent-authored PR, false-positive rate per rule, PR review time, agent rework rate after a hook rejection, baseline-growth incidents, and hook-disable rate. Without these, the pilot cannot end in a defensible go/no-go.
• The realistic upside is measurable — diff-scoped guardrails on agent-authored code with deterministic, local, no-LLM behavior — but it is contingent on rule quality holding up against your codebase, which is precisely what the pilot is for.