code-quality
Overview
One script, scripts/quality.ts, called by every entry point. Only deterministic checks decide the exit code. Old debt lives in a baseline and does not block; a new finding on a changed line does. 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 |
10-20 s |
commit-msg |
git commit |
AI attribution, glossary words in the message |
< 1 s |
pre-push |
git push |
tamper per pushed commit, tests touched by name and by import, diff coverage, Gitleaks, OSV audit |
up to 1 min |
| agent Stop |
the agent ends a turn |
check against project.base; red = one round of fixes |
10-20 s |
| manual |
before a large push, or to measure |
full gate: tests with coverage, mean CRAP, worklist, hotspots |
3-6 min |
CRAP needs fresh lcov (.scratch/quality/lcov.info 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.
Commands
Q=~/.claude/skills/code-quality/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 gate with tests and coverage
bun $Q --repo <repo> --skip-tests # full gate on the lcov already on disk (exit 2 when stale)
bun $Q check --repo <repo> # fast gate 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
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.
Wire a repo
- Add
.quality.toml to the repo root. Minimum: [project] src and base. Samples: examples/typescript.quality.toml, examples/python.quality.toml. Keys: references/config.md.
- Add
.scratch/ to .gitignore; reports go there.
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.
bun $Q install-hooks <repo>. Existing hooks (husky, Git LFS) are chained, see references/hook-chain.md.
- Optional: Stop hooks for Claude Code, Codex and pi, adapters/ENABLE.md.
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 blocks |
Why these numbers, and how CRAP is computed: references/checks.md.
What blocks
| 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 (blocks in the full gate and pre-push) |
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, new vulnerability, too-young lock entry |
doc/*, glossary, commit/attribution |
dead path or symbol in docs, banned word, AI attribution in a commit |
Notes only: 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 and never changes the exit code.
Full rule table with how each one works: references/checks.md. Languages and adapters: references/languages.md.
Bypasses
Every bypass needs a reason and leaves a note: bypass <rule> <source> <reason> line in the report.
- Deleting a test block:
qg:test-removed <reason> in the commit message (or in .scratch/quality/allow.md for check --staged and Stop).
pre-push with no test found: qg:no-test <reason> in a pushed commit message.
- A deliberate secret in a fixture:
qg:allow <reason> or gitleaks:allow <reason> on the line.
- Changing
src, thresholds, [security], [hooks], [review], [knip], [layers], [docs], [glossary] allow together with source code is blocked; change them in a separate commit.
Jev
An optional classifier for added test hunks: five yes/no questions with a calibrated probability, notes only, [review] jev = true and OPENROUTER_API_KEY. Details: references/jev.md.
Common mistakes
- Reading
GATE PASS as "tests green": a fast entry point never runs tests. Check the tests: line.
- Judging the mean CRAP: it is a note. What blocks is changed functions and ratchet findings.
- A partial
git add -p: pre-commit refuses a file that also has unstaged edits. Stage it whole.
- 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 do not block until then.
- Updating the baseline in the same commit as code:
tamper/baseline-touched blocks it by design.
More limits: references/limits.md. Report layout: references/report.md. Measured noise on real repos: references/measurements.md. Evaluation against sabotages: references/evaluation.md.
1---2name: code-quality3description: "Quality gate for a repo: one bun script behind git hooks (pre-commit, commit-msg, pre-push) and the Stop hooks of Claude Code, Codex and pi. Blocks test tampering, CRAP and complexity over the bar on changed functions, low diff coverage, new cycles, dead code, clones, secrets, vulnerable dependencies and AI attribution in commits. 12 languages, one .quality.toml per repo. Use when: quality gate, CRAP, complexity, ratchet, baseline, hotspots, dead code, import cycles, wire a repo into the gate, install quality hooks, .quality.toml, Stop hook for quality. Not for running ordinary tests, lint or typecheck."4metadata:5 source: https://skillmd.com/skills/smixs/code-quality6---78# code-quality910## Overview1112One script, `scripts/quality.ts`, called by every entry point. Only deterministic checks decide the exit code. Old debt lives in a baseline and does not block; a new finding on a changed line does. Jev (a classifier) and other reviewers write notes only.1314| entry point | when | what runs | time |15|---|---|---|---|16| `pre-commit` | `git commit` | `check --staged` on the staged change | 10-20 s |17| `commit-msg` | `git commit` | AI attribution, glossary words in the message | < 1 s |18| `pre-push` | `git push` | tamper per pushed commit, tests touched by name and by import, diff coverage, Gitleaks, OSV audit | up to 1 min |19| agent Stop | the agent ends a turn | `check` against `project.base`; red = one round of fixes | 10-20 s |20| manual | before a large push, or to measure | full gate: tests with coverage, mean CRAP, worklist, hotspots | 3-6 min |2122CRAP needs fresh lcov (`.scratch/quality/lcov.info` 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.2324## Commands2526```bash27Q=~/.claude/skills/code-quality/scripts/quality.ts28bun $Q install-hooks <repo> # core.hooksPath for that repo only; repo hooks keep working29bun $Q uninstall-hooks <repo> # put the previous core.hooksPath back30bun $Q --repo <repo> --update-baseline # snapshot of the current debt (runs tests); repeat after a merge31bun $Q --repo <repo> # full gate with tests and coverage32bun $Q --repo <repo> --skip-tests # full gate on the lcov already on disk (exit 2 when stale)33bun $Q check --repo <repo> # fast gate on the change (what the Stop hook runs)34bun $Q check --repo <repo> --staged # the staged change (what pre-commit runs)35bun $Q check --repo <repo> --since <rev> # the diff rev..HEAD36bun $Q check --repo <repo> --all # whole repo, baseline ignored: measure debt and noise37```3839Flags 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`.4041## Wire a repo42431. Add `.quality.toml` to the repo root. Minimum: `[project] src` and `base`. Samples: `examples/typescript.quality.toml`, `examples/python.quality.toml`. Keys: [references/config.md](references/config.md).442. Add `.scratch/` to `.gitignore`; reports go there.453. `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.464. `bun $Q install-hooks <repo>`. Existing hooks (husky, Git LFS) are chained, see [references/hook-chain.md](references/hook-chain.md).475. Optional: Stop hooks for Claude Code, Codex and pi, [adapters/ENABLE.md](adapters/ENABLE.md).4849## Thresholds5051One bar for every repo, in `[thresholds]`:5253| key | value | holds where |54|---|---|---|55| `max_cc` | 10 | a changed function above it gets split |56| `max_crap` | 30 | a changed function above it needs tests or a split |57| `max_mean_crap` | 5 | warning only: `note: crap/mean` when above and rising |58| `cognitive_complexity` | 15 | changed functions |59| `max_depth`, `max_params` | 4, 4 | changed functions |60| `max_lines_per_function` | 80 | without blanks and comments |61| `dup_min_tokens` | 70 | jscpd |62| `diff_coverage` | 0.8 | covered share of added executable lines |63| `min_release_age_days` | 1 | a new lock entry younger than this blocks |6465Why these numbers, and how CRAP is computed: [references/checks.md](references/checks.md).6667## What blocks6869| rule family | catches |70|---|---|71| `crap`, `form/*` | complexity, CRAP, cognitive complexity, size and params over the bar on changed functions |72| `cov/diff` | added executable lines covered below `diff_coverage` (blocks in the full gate and `pre-push`) |73| `tamper/*` | deleted or skipped test, weakened assertion, baseline or guarded config changed with code, no tests ran |74| `deps/cycle`, `dead/*`, `dup/jscpd`, `ast/*` | new cycle, new unused export, new clone, empty catch, catch that only logs, textual test |75| `secret/*`, `secret/gitleaks`, `deps/audit`, `deps/lock-age` | tokens and keys, history secrets, new vulnerability, too-young lock entry |76| `doc/*`, `glossary`, `commit/attribution` | dead path or symbol in docs, banned word, AI attribution in a commit |7778Notes only: `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 and never changes the exit code.7980Full rule table with how each one works: [references/checks.md](references/checks.md). Languages and adapters: [references/languages.md](references/languages.md).8182## Bypasses8384Every bypass needs a reason and leaves a `note: bypass <rule> <source> <reason>` line in the report.8586- Deleting a test block: `qg:test-removed <reason>` in the commit message (or in `.scratch/quality/allow.md` for `check --staged` and Stop).87- `pre-push` with no test found: `qg:no-test <reason>` in a pushed commit message.88- A deliberate secret in a fixture: `qg:allow <reason>` or `gitleaks:allow <reason>` on the line.89- Changing `src`, thresholds, `[security]`, `[hooks]`, `[review]`, `[knip]`, `[layers]`, `[docs]`, `[glossary] allow` together with source code is blocked; change them in a separate commit.9091## Jev9293An optional classifier for added test hunks: five yes/no questions with a calibrated probability, notes only, `[review] jev = true` and `OPENROUTER_API_KEY`. Details: [references/jev.md](references/jev.md).9495## Common mistakes9697- Reading `GATE PASS` as "tests green": a fast entry point never runs tests. Check the `tests:` line.98- Judging the mean CRAP: it is a note. What blocks is changed functions and ratchet findings.99- A partial `git add -p`: `pre-commit` refuses a file that also has unstaged edits. Stage it whole.100- husky in `npm install` rewrites `core.hooksPath`: run `install-hooks` again after installing dependencies.101- Skipping `--update-baseline` after updating the skill: the new adapter lists do not block until then.102- Updating the baseline in the same commit as code: `tamper/baseline-touched` blocks it by design.103104More limits: [references/limits.md](references/limits.md). Report layout: [references/report.md](references/report.md). Measured noise on real repos: [references/measurements.md](references/measurements.md). Evaluation against sabotages: [references/evaluation.md](references/evaluation.md).