Laravel Ai Verify Laravel Package

Technical Evaluation

Architecture fit. v0.6.0 is a distribution change, not an engine change: the package's existing verification, graph, and receipt capabilities are now reachable as MCP tool calls through Laravel Boost's MCP server. This shifts the package from "a CLI an agent shells out to" to "a capability an agent can discover and invoke natively." For teams already running agentic workflows inside a Laravel codebase, that is the difference between a tool the agent can use and one it reliably uses — discovery, typed parameters, and structured returns replace prompt-engineered shell invocations. The three tools map cleanly to distinct product surfaces: ai-verify (verdict/gate), ai-graph (structural inspection), ai-verify-receipt (auditability). Those are exactly the primitives a TPM would want to expose to an autonomous loop.

Integration feasibility. Low friction by design. Registration is conditional on laravel/mcp being present and routed through Boost's own boost.mcp.tools.include list, so the package does not fight Boost's tool registry or invent a parallel one. Nothing changes for teams without Boost. Return payloads are identical to the --json CLI output, which means existing parsing, dashboards, and CI consumers keep working and the MCP path is not a second contract to maintain. The two documented escape hatches (AI_VERIFY_MCP_BOOST=false env var, ai-verify.mcp.boost config key) give per-environment control without code changes — important because env-var opt-out is what makes this safe to disable in CI or air-gapped contexts.

Technical risk. Low, and mostly operational rather than architectural:

• Per-call process spawn. Boost runs each tool call in a fresh process so the agent sees the latest edits. That is the correct freshness tradeoff, but it means every verify invocation pays full bootstrap cost. On large suites this is where the 180-second Boost default becomes a real constraint — the exposed timeout parameter exists precisely because that default will be too short for real projects.
• Verdict semantics. Documenting that a fail verdict is an answer, not a tool error is the single most consequential design decision in this release. If fail had surfaced as an MCP error, agents would retry, swallow, or misinterpret the result. Worth confirming this holds for all three tools and not just ai-verify.
• Version coupling. Three moving parts now: this package, laravel/mcp, and Boost's include list contract. That list is a Boost-owned extension point; if it changes shape, discovery silently degrades to "tools not offered" rather than failing loudly.
• Config precedence. Two opt-out mechanisms (env + config) require a documented precedence rule, or operators will disable it in one place and be surprised it still runs.

Key questions.

1. Is the MCP surface versioned in lockstep with the CLI --json schema, and is that schema a public contract?
2. What happens when laravel/mcp is installed but Boost is absent — silent no-op, or a warning?
3. Does fail-as-answer hold uniformly across ai-verify, ai-graph, and ai-verify-receipt, including partial/timeout outcomes?
4. Is there a recommended timeout value for large suites, and does exceeding it return a structured MCP error?
5. Does the fresh-process model have any shared state, cache, or artifact directory that concurrent tool calls could contend on?
6. Is env-vs-config precedence documented, and is opt-out observable (log line / health check) or silent?

Integration Approach

Stack fit. Assumes a Laravel app with laravel/mcp, and optionally Laravel Boost. All three are additive conditions — the package remains usable as a standalone CLI in environments with none of them. For a TPM, this means the rollout decision is scoped to the agent tooling layer, not the application runtime.

Migration path. There is no migration. v0.6.0 adds an opt-in surface and leaves the CLI as the source of truth. Teams can adopt in either order: CLI first for CI gates, MCP second for interactive agent loops — or MCP-only for teams that never built a shell-invocation habit. No config changes are required to upgrade; the include registration is automatic when preconditions are met.

Compatibility. Backward compatible with prior versions on the evidence available. Forward compatibility depends on Boost's boost.mcp.tools.include contract remaining stable. Return payloads matching --json output eliminates the classic dual-contract drift between CLI and tool-call consumers.

Sequencing. Recommended order:

1. Upgrade the package with Boost/MCP disabled, confirm CLI behavior and JSON output are unchanged.
2. Enable laravel/mcp in a non-production environment; confirm the three tools appear in Boost's tool list and that AI_VERIFY_MCP_BOOST=false cleanly removes them.
3. Tune timeout against the largest suite you intend to run under agent control, using the 180-second Boost default as the baseline to beat.
4. Update the team's agent guideline/skill references to name the tools rather than the shell commands — the release already updates the package's own guideline and skill, so this is about aligning internal prompts and runbooks.
5. Roll to production, with the env-var opt-out wired into any environment where agent-driven verification is inappropriate.

Operational Impact

Maintenance. Marginal. One new integration seam to track (Boost's include contract) alongside the existing CLI surface. The dual opt-out means disabling is a config change, not a rollback — a meaningful reduction in maintenance blast radius.

Support. Expect the first wave of tickets to be about tool visibility ("the tools aren't showing up") and timeouts. Both have deterministic causes — missing laravel/mcp, Boost absent, opt-out still set, or a suite exceeding the configured timeout. A short diagnostic checklist covering those four covers most of the volume. The fail-is-not-an-error semantic should be called out explicitly in support docs, since it looks like a defect to anyone expecting tool errors on failure.

Scaling. Per-call process spawn means cost scales with call frequency, not just suite size. Agents in tight edit-verify loops will generate many invocations; a fresh process each time is correct for freshness but wasteful for repeated unchanged verification. Worth monitoring invocation counts per session and steering agents toward batched or gated verification patterns. Concurrency is the open question — parallel tool calls spawning parallel processes against large suites could contend on CPU and any shared artifact directory.

Failure modes.

• Timeout on large suites — most likely failure; mitigated by the timeout parameter, but requires deliberate tuning.
• Silent non-registration — if the Boost include contract shifts or a precondition is unmet, tools simply don't appear. Degrades quietly rather than erroring, which is safe but hard to debug.
• Misread verdicts — an agent treating fail as an error and retrying indefinitely. Documented, but prompt-level behavior is not guaranteed by the package.
• Stale results — mitigated by design (fresh process per call), which is the correct default and worth preserving even at the cost of throughput.
• Opt-out confusion — env and config disagreeing; resolves to a documented precedence rule.

Ramp-up. Low for individual developers — the tools return the same JSON they already know from --json. The real ramp-up is organizational: agent guidelines, skills, and runbooks must be updated to reference the tools instead of shell commands, and the timeout budget for agent-driven verification needs a team-level decision rather than a per-developer one. Budget a short enablement pass alongside the upgrade rather than treating it as a drop-in patch.