code-quality skill

code-quality

Overview

One script, scripts/quality.ts, called by every entry point. It advises and never forbids: the plugin trusts the agent the way a good reviewer trusts a colleague. It measures, shows what it found, and says loudly when something is dangerous; the agent decides what to do and says why. No hook stops a commit, a push, a tool call or the end of a turn.

Every output starts with the red flags, one line each: RED FLAG: <what you are doing> -- <why it is dangerous>; check: <what to verify>. Then come the findings (FINDINGS (n), advice, nothing blocked:) or CLEAN, then notes. Old debt lives in a baseline and is not reported as a finding; a new finding on a changed line is. Jev (a classifier) and other reviewers write notes only.

entry point	when	what runs	time
pre-commit	git commit	check --staged on the staged change; prints the report, the commit goes ahead	10-20 s
commit-msg	git commit	AI attribution, glossary words in the message; a note, the commit goes ahead	< 1 s
pre-push	git push	tamper per pushed commit, tests touched by name and by import, diff coverage, Gitleaks, OSV audit; the push goes ahead	up to 1 min
agent Stop	the agent ends a turn	check against project.base; the turn ends as the agent chose, the report reaches the agent once, with its next message	10-20 s
shell guard	the agent runs git	a red flag next to the command's output when it skips the hooks (--no-verify, commit -n, core.hooksPath); the command runs	< 1 s
acceptance	a lead accepts a change	check --since <base> --tests: the change's touched tests with coverage, then the gate judges the change with that coverage	the touched tests + 10-20 s
mutant	proving the tests catch a bug	mutant: one exact mutation, the touched tests, a guaranteed restore, the verdict in the exit code	two runs of the touched tests
manual	to measure the repo	full gate, a debt measurement, not a verdict on a change: tests with coverage, mean CRAP, worklist, hotspots	3-6 min

The acceptance report on a change is check --since <base> --tests. The full gate reports old debt too, so its findings say nothing about one change; run it to measure the repo. check, the full gate and mutant exit 1 on findings so a script or CI can decide on its own; no hook turns that code into a stop.

CRAP needs fresh lcov (<out_dir>/lcov.info, by default .scratch/quality, with a matching fingerprint). Without it a fast entry point prints tests: not run, no fresh lcov and judges complexity only. A change of docs and config only (.md, .toml, .json, .yml outside project.src) prints scope: docs-only and skips the code checks.

The process around the gate, from the spec to landing, is the acceptance skill in this plugin: ../acceptance/SKILL.md.

Commands

Q=<plugin-root>/scripts/quality.ts
bun $Q install-hooks <repo>              # core.hooksPath for that repo only; repo hooks keep working
bun $Q uninstall-hooks <repo>            # put the previous core.hooksPath back
bun $Q --repo <repo> --update-baseline   # snapshot of the current debt (runs tests); repeat after a merge
bun $Q --repo <repo>                     # full report with tests and coverage
bun $Q --repo <repo> --skip-tests        # full report on the lcov already on disk (exit 2 when stale)
bun $Q check --repo <repo>               # fast report on the change (what the Stop hook runs)
bun $Q check --repo <repo> --staged      # the staged change (what pre-commit runs)
bun $Q check --repo <repo> --since <rev> # the diff rev..HEAD
bun $Q check --repo <repo> --all         # whole repo, baseline ignored: measure debt and noise
bun $Q check --repo <repo> --since <base> --tests   # acceptance: touched tests with coverage, then the report
bun $Q mutant --repo <repo> --file <path> --find <exact text> --replace <text> [--test <path>]...

check --tests needs exactly one --since. It selects the touched tests (by name, including <stem>.<anything>.test.<ext> such as X.render.test.ts for X.tsx; for TS every test that reaches the changed file through any chain of imports, re-exports, dynamic imports, require and quoted paths in tests, with modules resolved through relative paths, the nearest tsconfig.json paths and workspace packages; see references/config.md), runs all of them with coverage into a private <out_dir>/touched/run-*/ directory, and judges the change with that coverage: a red test is tests/red, a timeout tests/timeout, low coverage of added lines cov/diff. That coverage never feeds the full gate, --skip-tests or the baseline. Ctrl-C or SIGTERM during the run (or during pre-push tests) kills the test process group and exits 130 or 143; check --tests prints the kept run directory.

mutant runs the selected tests on the original file first, then with the one mutation: exit 0 MUTANT KILLED (a test failed), 1 MUTANT SURVIVED (they stayed green), 2 MUTANT ERROR (anything unclear). The file is restored and proven by sha256 on every outcome, including Ctrl-C; a run killed with SIGKILL is restored by the next mutant. Each run appends one JSON line to <out_dir>/mutants.log. A value that starts with - goes as --find=<text>.

Every test run the gate starts (full gate, --tests, pre-push, mutant) first waits while the 1-minute load is above [tests] max_load (twice the CPU count by default), up to [tests] load_wait_s, and prints tests: waited Ns for load X.X (max M).

Flags beat .quality.toml: --config, --baseline, --src a,b, --base <ref>, --test-cmd, --max-cc, --max-crap, --forbid from:to, --knip-ignore, --allow-red-tests, --no-deps.

Nothing is wired to one machine or one vendor: [project] base left empty is detected from origin/HEAD, then origin/main, origin/master, main (the report header says which). [project] out_dir moves every report, the baseline and the logs. [tools] overrides a pinned version or a binary path (jscpd = "5.3.0", gitleaks = "/opt/bin/gitleaks"). [review] jev_provider chooses the Jev endpoint. [security] registry_urls points a package registry at a mirror. Every key: references/config.md.

Wire a repo

1. Add .quality.toml to the repo root. Minimum: [project] src and base. Samples: TypeScript, Python. Keys: references/config.md.
2. Add .scratch/ to .gitignore; reports go there ([project] out_dir moves them).
3. bun $Q --repo <repo> --update-baseline. The baseline lives in the main checkout, shared by worktrees. Without it the gate compares against project.base and says so. Run it again after updating the skill.
4. bun $Q install-hooks <repo>. Existing hooks (husky, Git LFS) are chained, see references/hook-chain.md.
5. Install the plugin for the agent as described in the repository README. Its Stop, next-prompt (agent-notes) and shell guard hooks load with the package.

Thresholds

One bar for every repo, in [thresholds]:

key	value	holds where
max_cc	10	a changed function above it gets split
max_crap	30	a changed function above it needs tests or a split
max_mean_crap	5	warning only: note: crap/mean when above and rising
cognitive_complexity	15	changed functions
max_depth, max_params	4, 4	changed functions
max_lines_per_function	80	without blanks and comments
dup_min_tokens	70	jscpd
diff_coverage	0.8	covered share of added executable lines
min_release_age_days	1	a new lock entry younger than this is a finding

Why these numbers, and how CRAP is computed: references/checks.md.

Red flags

Printed first, loud, never blocking. Each says what the agent is doing, why it is dangerous and what to verify:

red flag	where
a secret in the change (secret/token, secret/env-file) or in the pushed history (secret/gitleaks)	every check, pre-commit, pre-push, Stop
a test deleted, skipped or weakened, an inline suppression, the baseline or guarded config changed with code (tamper/* except tamper/no-tests-ran)	every check, pre-commit, pre-push, Stop
red touched tests on push	pre-push
a git command that skips the hooks: --no-verify, commit -n, -c core.hooksPath, git config core.hooksPath	shell guard ([hooks] flag_bypass = false silences it)

What it reports

rule family	catches
crap, form/*	complexity, CRAP, cognitive complexity, size and params over the bar on changed functions
cov/diff	added executable lines covered below diff_coverage (in the full gate, pre-push and check --tests)
tests/red, tests/timeout	a touched test fails or runs over [tests] touched_timeout_s in check --tests
tamper/*	deleted or skipped test, weakened assertion, baseline or guarded config changed with code, no tests ran
deps/cycle, dead/*, dup/jscpd, ast/*	new cycle, new unused export, new clone, empty catch, catch that only logs, textual test
secret/*, secret/gitleaks, deps/audit, deps/lock-age	tokens and keys, history secrets (red flags), a machine path, new vulnerability, too-young lock entry
doc/*, glossary, commit/attribution	dead path or symbol in docs, banned word, AI attribution in a commit

Notes, without a count: tamper/mock-added, deps/new-package, crap/mean, security/semgrep, every note: jev. A missing tool prints one not run line with the install command.

Full rule table with how each one works: references/checks.md. Languages and adapters: references/languages.md.

Saying why

Nothing needs a bypass to go through. A reason turns a finding into a traced decision: the finding leaves the list and the report keeps a note: bypass <rule> <source> <reason> line.

• Deleting a test block: qg:test-removed <reason> in the commit message (or in <out_dir>/allow.md for check --staged and Stop).
• pre-push or check --since <rev> --tests with no test found: qg:no-test <reason> in a commit message of the change. With --tests no tests run then, changed functions are judged by complexity only and cov/diff prints not run.
• A deliberate secret in a fixture: qg:allow <reason> or gitleaks:allow <reason> on the line.
• Changing src, thresholds, [security], [hooks], [tests], [review], [knip], [layers], [docs], [glossary] allow together with source code raises tamper/baseline-touched; a separate commit keeps the two apart.

Jev

An optional classifier: five yes/no questions on added test hunks, change_untested on changed source hunks, spec_incomplete against [review] spec or $QG_SPEC, opt-in UX and agent packs ([review] ux_globs, agent_globs) and project questions ([[review.jev_questions]]); calibrated probabilities, notes only, [review] jev = true plus a key: TYPESAFE_API_KEY for the TypeSafe API or OPENROUTER_API_KEY for OpenRouter, picked by [review] jev_provider (default auto). Details: references/jev.md.

Common mistakes

• Reading CLEAN as "tests green": a fast entry point never runs tests. Check the tests: line; check --tests is the one that runs them.
• Scrolling past a RED FLAG because the commit went through: nothing blocks, so the flag is the only signal. Answer it: fix, or say why in the commit message.
• Running the full report to accept a change: it measures debt. Accept with check --since <base> --tests.
• Mutating by hand with cp and sed: mutant does the one exact edit and always restores.
• Pushing another branch from this checkout: pre-push runs the touched tests on the checked-out tree, so it skips them with touched tests not run unless the checkout is at the pushed commit and the files those tests read are committed. Push from that branch's worktree to have them run.
• Judging the mean CRAP: it is a note. The findings are changed functions and ratchet findings.
• A partial git add -p: pre-commit reads the working tree, so a file that also has unstaged edits is reported by its working-tree text (a note: partly staged line says so). Stage it whole for a report on the commit.
• husky in npm install rewrites core.hooksPath: run install-hooks again after installing dependencies.
• Skipping --update-baseline after updating the skill: the new adapter lists are not judged until then.
• Updating the baseline in the same commit as code: tamper/baseline-touched flags it by design.

More limits: references/limits.md. Report layout: references/report.md.