Wire llm-friendly-qa-wrappers in as a major dependency (redirect raw QA tool calls → wrapper + jq guidance)

[edmondscommerce]

Summary

Adopt edmondscommerce/llm-friendly-qa-wrappers as a major dependency of the hooks daemon, and build handlers that redirect raw QA tool invocations to the wrapper version, then guide the agent to parse the JSON output with jq.

The wrapper repo provides thin wrappers around common QA / static-analysis tools (ESLint, Prettier, Jest, TSC, Vitest, Biome, PHPStan, PHP-CS-Fixer, PHPUnit, ShellCheck, shfmt, Ruff, pytest, MyPy) that print a terse 1–5 line terminal summary and write full JSON details to a temp file for jq querying — exactly the output contract an LLM agent wants instead of human-formatted tool noise.

This generalises the existing npm_command interception pattern (raw npm/npx → llm:-prefixed) across every wrapped tool and language.

What we want to build

1. Redirect handler(s) (PreToolUse) — detect a raw wrapped-tool Bash command (e.g. eslint src/) and redirect to the wrapper equivalent (llm-eslint.js src/), with get_claude_md() guidance that names the wrapper invocation and teaches reading the JSON temp file with jq.
2. A single machine-readable mapping raw command → wrapper invocation as the SSOT — handlers read it via a tool/language-aware Strategy + Registry (no hardcoded if/elif chains), consistent with our existing QA-suppression / security-antipattern registries.
3. Graceful degradation — when a project hasn't installed the wrapper, advise rather than hard-block.

php-qa-ci integration (secondary strand)

Our PHP estate runs lts/php-qa-ci (org lts = LongTermSupport, first-party) — a Bash pipeline (bin/qa) orchestrating Rector, PHP-CS-Fixer, PHPStan, PHPUnit, Infection across four phases. Rather than wrapping each PHP tool individually and re-implementing the orchestration, we likely want a global --json mode on php-qa-ci that drives every underlying tool into its JSON output mode and emits one aggregate machine-readable result document, surfaced through the wrapper repo's conventions.

Open question (tracked in the plan): does the JSON aggregation live in php-qa-ci itself (a --json flag — we control lts), in a dedicated llm-php-qa-ci wrapper, or both?

Pre-work: full audit

Before depending on it, the wrapper repo gets a thorough critical engineering audit (completeness vs. advertised tools, output-contract consistency, code correctness, temp-file path determinism, install/dependency surface, test coverage, stability/maturity, and gaps/risks specific to our redirect use case). Adoption is gated on the audit's readiness verdict; blockers get filed upstream (we own edmondscommerce).

Tracking

Tracked in this repo under CLAUDE/Plan/00129-llm-qa-wrappers-integration/ — see PLAN.md for phased tasks and AUDIT-llm-friendly-qa-wrappers.md for the audit report.

Phases

• Phase 1 — Audit & consumption decision (submodule / vendored / pinned release / package; pin a version)
• Phase 2 — Redirect mapping SSOT (schema-validated, Strategy + Registry)
• Phase 3 — Redirect handler(s) (TDD, 95%+ coverage, acceptance tests, dogfooded)
• Phase 4 — php-qa-ci global JSON integration
• Phase 5 — Documentation & rollout (config-gated, conservative default)

[edmondscommerce]

Audit complete — verdict: NOT READY (adopt with upstream fixes; small subset usable today)

Full report: CLAUDE/Plan/00129-llm-qa-wrappers-integration/AUDIT-llm-friendly-qa-wrappers.md.

edmondscommerce/llm-friendly-qa-wrappers is a brand-new v0.1.0 repo (single tag, 0 issues/PRs, no CI, no LICENSE file despite MIT claim). The core terse-output + JSON-temp-file contract genuinely works (ShellCheck wrapper verified end-to-end), but it is not a safe major dependency as-published.

Upstream blockers (file against edmondscommerce/llm-friendly-qa-wrappers — first-party, we own it)

1. No LICENSE file — hard blocker for vendoring (claims MIT).
2. Two incompatible dependency models — Node/PHP wrappers run the tool from the wrapper's OWN bundled node_modules/vendor (lints with the wrapper's tool version, not the project's); Python/Bash wrappers run from PATH. Redirecting eslint src/ would silently swap in the wrapper's ESLint.
3. No machine-readable raw command → wrapper manifest — our redirect-mapping SSOT can't be sourced from the repo; best fixed upstream so the map is shared rather than hand-maintained here.
4. No uniform JSON shape — every tool emits a different structure, so a caller can't write one jq pass/fail query. The one reliable uniform signal is the stdout token (details: /tmp/<tool>-<hex>.json); a redirect handler must capture stdout and parse that token (path is non-deterministic). Exit-2 errors emit no details path.
5. Correctness bugs — PHPStan fail-branch under-reports config-level errors (prints "0 errors found" while exiting 1); tsc invoked per-file bypasses tsconfig.json; shfmt lossy; pytest brittle stdout-regex parsing.
6. No CI; per-wrapper READMEs missing on all 14; no aggregate test runner; temp files never cleaned up.

Usable as-is today

ShellCheck, Ruff, MyPy (PATH model, native JSON, clean) — behind a defensive handler that parses the (details:) token and falls back on exit 2.

Plan adjustments

• Consumption decision gated on the LICENSE fix; pin a future hardened release, not v0.1.0.
• Push the redirect-mapping manifest upstream into the wrapper repo.
• Phase 3 first handler targets the 3 clean tools behind a (details:)-token parser + exit-2 fallback, not the Node/PHP wrappers until the dependency-model split is resolved.

[edmondscommerce]

Plan committed

Plan 00129 (and the wrapper-repo audit) committed and pushed to main:

• Commit: 7f6fdb6 — Plan 00129: Wire llm-friendly-qa-wrappers in as a major dependency (tracking)
• Plan: CLAUDE/Plan/00129-llm-qa-wrappers-integration/PLAN.md
• Audit: CLAUDE/Plan/00129-llm-qa-wrappers-integration/AUDIT-llm-friendly-qa-wrappers.md

Status: Not Started — adoption gated on the audit's upstream blockers (LICENSE, dependency-model split, shared raw→wrapper manifest). Flagged by the maintainer as non-trivial; pending a design decision before Phase 1 kicks off.