crapkit

crapkit scores every function in your repo on complexity times uncovered risk, ranks the worst ones by how often the file changes, and blocks commits that add more. It reads TypeScript, TSX, JavaScript and Python through lizard, and joins per-function branch coverage from istanbul or coverage.py artifacts your own test command already produces. Every read-side command speaks JSON with a pinned schema, because half the callers are coding agents.

CRAP = ccn^2 * (1 - cov)^3 + ccn

ccn is the smaller of standard and modified cyclomatic complexity, both read off one lizard pass. cov is branch coverage inside the function's span; with no branches it falls back to statement coverage, and with no statements to invoked-or-not, so a half-executed straight-line function never reads as fully covered.

Above the ceiling, coverage cannot save you. Decompose. At the default target of 6, a function at ccn 7 with 100% coverage still scores 7 and still fails the gate. The only move that clears it is splitting the function.

crapkit scores git-tracked files only. Source you have not git added is invisible to it.

---

Install

pip install git+https://github.com/JeanFrancoisGagne/crapkit.git

From a clone of this repo, run at the clone root:

pip install .

Either install pulls one dependency, lizard. The pip install -e ".[dev]" under Development is a different thing: it adds the test extra and is for people changing crapkit.

Once the PyPI release lands, plain pip install crapkit will work too.

Requires Python 3.11 or newer. The one runtime dependency is lizard>=1.24.0, which comes from PyPI as a normal wheel, so a PyPI-only or offline-mirror environment installs fine and no git binary is needed for the dependency itself.

Check the install:

$ crapkit --version
crapkit 0.2.0

python -m crapkit works identically to the crapkit console script, and is what to use from a source checkout. Every subcommand accepts --repo PATH (default: the current directory), so you never have to cd into the repo you are scoring. The flag goes after the subcommand; Subcommands shows both orders.

---

Quickstart: Python

A repo with calc/grade.py, tests/test_grade.py, and a pyproject.toml. Commit first; crapkit reads git ls-files.

This is the step that stops most Python users: the lane crapkit init writes runs pytest --cov, and the --cov flags come from the pytest-cov package. Install it first:

pip install pytest-cov

1. Scaffold the config

$ crapkit init
wrote crapkit.toml with 1 scope(s): calc
detected 1 lane(s) from this repo's own files: py — next: run `crapkit coverage`
added to .gitignore: .crapkit/, .coverage, __pycache__/

init sniffs tracked source into one scope per top-level source directory, and detects a coverage lane from what the repo already has: a pytest marker file (pyproject.toml, pytest.ini, setup.cfg) writes a live [[lane]], and so does a test script or vitest/jest in package.json. Whatever it detects, it also leaves commented templates for the runners it did not find.

Every lane it writes reports into .crapkit/cov/, so the only .gitignore lines it needs are .crapkit/ and what the runner drops elsewhere in the tree (a pytest lane's .coverage and __pycache__/). Point the JUnit report and any lane you add by hand at .crapkit/ too: see Where artifacts live.

The generated crapkit.toml:

[crapkit]
target = 6

[[scope]]
name = "calc"
paths = ["calc"]
languages = ["python"]

[exclude]
globs = ["**/node_modules/**", "**/dist/**", "**/build/**", "**/vendor/**", "**/*.test.*", "**/*.spec.*", "**/test_*.py", "**/*_test.py", "**/conftest.py", "*.config.ts", "*.config.js", "*.config.mts", "**/*.config.ts", "**/*.config.js", "**/*.config.mts"]

[[lane]]
name = "py"
command = "python -m pytest --cov --cov-branch --cov-report=json:.crapkit/cov/py.json"
artifact = ".crapkit/cov/py.json"
parser = "coveragepy"
scopes = ["calc"]

# Declare one [[lane]] per coverage command, then run `crapkit coverage`.
# [[lane]]
# name = "js"
# command = "npx vitest run --coverage --coverage.reportsDirectory=.crapkit/cov/js"
# artifact = ".crapkit/cov/js/coverage-final.json"
# parser = "istanbul"
# scopes = ["<your-scope>"]

# `crapkit test-scoped FILES` runs one command per scope, with {files}
# replaced by that scope's files, each quoted.
[crapkit.scoped_tests]
calc = "python -m pytest {files} -q -p no:cacheprovider"

The last block is the one an agent loop needs: crapkit test-scoped exits 3 for a file whose scope declares no template, and AGENTS.md makes it step 4 of the burn-down loop. init writes the entry live when it detected the runner (a pytest marker proves the python command); a scope whose runner init could not confirm gets a commented template to fill in, and doctor warns while it stays empty.

Every key is in docs/configuration.md.

2. Check the config against the repo

$ crapkit doctor
ok   config keys all recognized
ok   scope 'calc': 1 files
ok   every tracked source file belongs to a scope
ok   1 lane(s) declared
ok   lizard 1.24.0
doctor: no problems found

doctor exits 1 only on a FAIL line. WARN and note report and exit 0.

3. Score the repo

$ crapkit coverage
run 1 @ fae4db93108: 2 functions scored — 2 measured / 0 untested / 0 no-lane / 0 cc-only, 1 over target 6, CRAP load 41.0, grade F

coverage runs the lane commands, parses their artifacts, joins coverage onto a fresh complexity inventory, and writes a scored run into .crapkit/crap.sqlite.

4. Read the queue

$ crapkit worklist
worklist @ fae4db93108 (run 1, floor ccn>=5, churn 12mo) — 1 active, 0 dormant
  risk      0.0  ccn  14 ( 14 std)    1c/1a w   0.00  calc/grade.py:7  classify( score , attempts , late , bonus )

Columns: risk, then ccn with the standard-only ccn in parentheses, then <commits>c/<authors>a in the churn window and w<weight>, then path:line and the function's long name, and last a marker on rows the burn-down queue will not hand out: ok for a function already at or under its ceiling, no-lane for one no lane measures.

floor ccn>=5 in the header orders the list; it never withholds debt. A function whose CRAP is over its ceiling is listed whatever its ccn, so an empty worklist on a repo coverage just graded F is not a thing crapkit can print.

worklist is the risk map, not a to-do list. It ranks every function it admits, finished ones included, so it does not empty when the burn-down finishes — the ok markers are what a done repo looks like here. next-item is the other view: same run, same admission floor, but it drops the no-lane rows and ranks by crap descending instead of by risk. Its empty: true is the stop condition; the worklist has none.

Every risk is 0.0 here because this repo has one commit: the churn weight is recency-weighted against the log's own span, and a log with no span has no recency to weight. Ranking then falls back to ccn order. It takes a second commit at a different second to end that, not days of history: see Risk.

5. Take the top item

$ crapkit next-item
{"commit": "fae4db93108b4841a00959f9117430679e7250ca", "empty": false, "item": {"authors": 1, "ccn": 14, "ccn_std": 14, "cognitive": 13, "commits": 1, "cov": 0.5, "crap": 38.5, "end": 28, "est_splits": 3, "est_uncovered_paths": 7, "flag": "measured", "function": "classify( score , attempts , late , bonus )", "nesting": 8, "nloc": 22, "path": "calc/grade.py", "remedy": "decompose", "scope": "calc", "start": 7, "target": 6, "uncovered_lines": [9, 11, 15, 17, 19, 24, 25, 26, 27, 28]}, "run_id": 1, "schema": 1, "skipped_no_lane": 0}

remedy: "decompose", est_splits: 3 (this needs roughly three pieces to fit under 6), and uncovered_lines naming the ten lines no test walks. Every field is in docs/agent-json.md.

6. Seed the ratchet

Arm the debt gate before fixing anything: ratchet seed records every over-target function at its current score, and from then on nothing may get worse.

$ crapkit ratchet seed
crapkit-ratchet.tsv: added 1, tightened 0 — 1 mark(s) vs run 1 (fae4db93108)

$ git add crapkit.toml crapkit-ratchet.tsv .gitignore && git commit -m "adopt crapkit"

7. Fix it and verify

Extract until every piece sits at or under the ceiling. Here classify became _validate, _adjusted, _band and a classify that only sequences them, with the table of cases pushed into parametrized tests. Commit the fix, then:

$ crapkit verify
verify OK @ 8d10c13303d vs baseline fae4db93108 (5 changed files)

A passing verify tightens crapkit-ratchet.tsv in place (the repaid mark leaves the file), so follow up with git commit -am "ratchet: classify repaid" — or amend, if the fix commit is still unpushed. The full mark lifecycle is in docs/ratchet.md.

verify reruns the lanes and checks three things against the trusted baseline: every function the diff touched sits at or under its ceiling, no marked function got worse, and no test that passed in the baseline fails now. Exit 0 advances the baseline and tightens the ratchet.

$ crapkit coverage
run 3 @ 8d10c13303d: 5 functions scored — 5 measured / 0 untested / 0 no-lane / 0 cc-only, 0 over target 6, CRAP load 19.0, grade A+

CRAP load 41.0 to 19.0, grade F to A+, and the queue is empty:

$ crapkit next-item
{"commit": "8d10c13303dfd9ef4172d9f736582ff4ffa96e60", "empty": true, "reasons": {"all_remaining_at_or_under_target": 4, "below_floor": 1, "churn_window_months": 12, "excluded_by_flag": 0, "no_churn_in_window": 0, "no_lane": 0, "no_lane_over_target": 0}, "run_id": 3, "schema": 1, "skipped_no_lane": 0}

empty: true is most of the stop condition: nothing the queue admits is over target, and all_remaining_at_or_under_target: 4 says the queue emptied because the work is done rather than because a filter ate it. Two siblings finish the rule. no_lane_over_target: 0 says no scope is holding debt no lane measures, and skipped_claimed is absent, which is how the payload says no claim hid a row. AGENTS.md states the whole condition and reads the rest of reasons.

---

Quickstart: TypeScript

A vitest repo with src/grade.ts and test/grade.test.ts.

1. Scaffold the config

$ crapkit init
wrote crapkit.toml with 1 scope(s): src
detected 1 lane(s) from this repo's own files: js — next: run `crapkit coverage`
added to .gitignore: .crapkit/

The lane init wrote is npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js. It reads vitest's json reporter from .crapkit/cov/js/coverage-final.json; the reportsDirectory flag is what keeps that report out of your root. Anything that produces an istanbul coverage-final.json works; see docs/lanes.md for jest, pytest, monorepo and per-package recipes.

2. Install a coverage provider

This is the step that stops most TypeScript users. vitest ships no coverage provider by default. Without one, init and doctor are both happy and coverage dies:

$ crapkit coverage
crapkit: lane 'js' FAILED: lane 'js' produced no artifact at .crapkit/cov/js/coverage-final.json (command exit 1); last output: $ npm run test -- --coverage --coverage.reportsDirectory=.crapkit/cov/js

> tsproj@0.1.0 test
> vitest run --coverage --coverage.reportsDirectory=.crapkit/cov/js

 MISSING DEPENDENCY  Cannot find dependency '@vitest/coverage-v8'

(exit 1)
crapkit: every lane failed: ...

Exit 5. Install the provider, pinned to your vitest major or npm refuses the peer dependency (on vitest 2: npm i -D "@vitest/coverage-v8@2"):

npm i -D @vitest/coverage-v8

Three things about that package:

Question	Answer
Which provider?	Either works. @vitest/coverage-v8 is vitest's default and needs no config. @vitest/coverage-istanbul also works and needs coverage.provider = "istanbul" in your vitest config.
Which crapkit parser?	Both feed parser = "istanbul". The provider name and the parser name are unrelated: v8 output is remapped to the istanbul JSON schema before it is written.
Which version?	It must match your vitest major. npm refuses the install otherwise (peer vitest@"4.x" from @vitest/coverage-v8@4.x). On vitest 2, npm i -D "@vitest/coverage-v8@2".

The artifact crapkit wants is coverage-final.json, written by vitest's json coverage reporter, which is on by default. If your vitest config sets coverage.reporter explicitly, keep "json" in the list. The lane's --coverage.reportsDirectory flag decides where the report lands, and init points it at .crapkit/cov/js/.

One more vitest default worth flipping now: it writes no coverage report at all when the run fails, so a single red test becomes a missing artifact and a lane failure. Set coverage.reportOnFailure = true. Details and the full config block are in docs/lanes.md.

3. Score the repo

$ crapkit coverage
run 1 @ 8bfbe613fcd: 2 functions scored — 2 measured / 0 untested / 0 no-lane / 0 cc-only, 1 over target 6, CRAP load 56.68, grade F

$ crapkit worklist
worklist @ 8bfbe613fcd (run 1, floor ccn>=5, churn 12mo) — 1 active, 0 dormant
  risk      0.0  ccn  15 ( 15 std)    1c/1a w   0.00  src/grade.ts:8  classify ( row Row )

classify is ccn 15 against a ceiling of 6: one function holding the late-and-retry penalty, the letter bands, the demotion rule and the null case.

4. Seed the ratchet and commit

ratchet seed records every over-target function at the score it has today, so nothing can get worse while you burn this one down.

$ crapkit ratchet seed
crapkit-ratchet.tsv: added 1, tightened 0 — 1 mark(s) vs run 1 (8bfbe613fcd)

$ git add crapkit.toml crapkit-ratchet.tsv .gitignore && git commit -m "adopt crapkit"

5. Fix it

Above the ceiling, coverage cannot help, so classify gets split rather than tested. penalty, band and demote come out as their own exported functions, and classify keeps the null case and the bonus:

export function classify(row: Row): string {
  if (row.score === null) {
    return "N/A";
  }
  let score = row.score - penalty(row.attempts, row.late);
  if (row.bonus && score < 90) {
    score += 3;
  }
  return demote(band(score), row);
}

rescore --gate judges that edit on complexity alone, before the slow step:

$ crapkit rescore src/grade.ts --gate
rescore vs run 1 @ 8bfbe613fcd (coverage STALE, complexity fresh)
   ccn   cov     crap  remedy     function
     5    0%     30.0  add-tests  src/grade.ts:22  band ( score )
     5    0%     30.0  add-tests  src/grade.ts:38  demote ( letter , row Row )
     4    0%     20.0  add-tests  src/grade.ts:8  penalty ( attempts , late )
     4   45%      6.7  add-tests  src/grade.ts:48  classify ( row Row )
     4   75%      4.2  ok         src/grade.ts:59  average ( scores Array )

Exit 0: every piece is at or under 6. The crap column is loud because its coverage half is still run 1's, from before three of those functions existed, and add-tests is the literal instruction for step 6.

6. Cover the new pieces

rescore --gate passed on complexity, not on coverage. penalty, band and demote are three functions no test has ever called, so each gets a table test:

describe("band", () => {
  it.each([
    [95, "A"],
    [85, "B"],
    [75, "C"],
    [65, "D"],
    [10, "F"],
  ])("scores %i as %s", (score, expected) => {
    expect(band(score)).toBe(expected);
  });
});

Run the suite once before the slow step:

$ npx vitest run
 ✓ test/grade.test.ts (21 tests) 2ms

 Test Files  1 passed (1)
      Tests  21 passed (21)

Skip this step and step 7 fails rather than passes. Run on a copy of this repo with step 6 left out, verify reruns the lanes against the real tree and three functions the old suite never called come back over the ceiling:

$ crapkit verify
verify FAILED @ 0296156ff21 vs baseline 0e646697946 (1 changed files)
  GATE  crap     17.8  ccn   5 cov 20%  src/grade.ts:38  demote ( letter , row Row )  -> add-tests
  GATE  crap     12.4  ccn   5 cov 33%  src/grade.ts:22  band ( score )  -> add-tests
  GATE  crap     10.8  ccn   4 cov 25%  src/grade.ts:8  penalty ( attempts , late )  -> add-tests

7. Verify

$ crapkit verify
verify OK @ 2af3433d979 vs baseline 8bfbe613fcd (3 changed files)

$ crapkit coverage
run 3 @ 2af3433d979: 5 functions scored — 5 measured / 0 untested / 0 no-lane / 0 cc-only, 0 over target 6, CRAP load 22.0, grade A+

CRAP load 56.68 to 22.0, grade F to A+, and the mark seeded in step 4 is gone: verify dropped it once classify scored under the ceiling, rewriting the tracked crapkit-ratchet.tsv in place — commit it with your change. Marks only ever fall.

A verify may also print warning: N changed line(s) have no coverage above its verdict; that block is advisory unless diff_uncovered_max is set (docs/configuration.md).

---

Installing the gate

crapkit hook-precommit reads every staged blob in one git cat-file --batch, analyzes it without touching the repo-wide cache, and refuses the commit when a staged function exceeds its scope ceiling. It needs no coverage data and no snapshot, so it costs the size of the commit, not the size of the repo.

Two limits to know. The gate judges files a [[scope]] claims; a staged source file no scope claims is not gated, and the hook says so on stderr (N staged file(s) belong to no scope and were not gated) so the hole is visible the moment a new top-level directory appears. And git runs hooks outside your shell's activated venv: bare python must resolve to an interpreter that has crapkit installed, or use the absolute form (exec /path/to/venv/Scripts/python -m crapkit hook-precommit).

Route 1: .git/hooks/pre-commit (local, not committed)

cat > .git/hooks/pre-commit <<'EOF'
#!/bin/sh
exec python -m crapkit hook-precommit
EOF
chmod +x .git/hooks/pre-commit

Route 2: a committed hooks directory

The whole route, from a repo that has no githooks/ yet:

mkdir -p githooks
cat > githooks/pre-commit <<'EOF'
#!/bin/sh
exec python -m crapkit hook-precommit
EOF
chmod +x githooks/pre-commit
printf 'githooks/pre-commit text eol=lf\n' >> .gitattributes
git add .gitattributes githooks/pre-commit
git update-index --chmod=+x githooks/pre-commit
git commit -m "add crapkit gate hook"
git config core.hooksPath githooks

The --chmod goes between the add and the commit. It writes the executable bit to the index, so a commit that already happened does not carry it: run it after and git ls-tree HEAD still says 100644, which is a hook Unix checkouts silently skip. The .gitattributes line is the harder half of the same failure — under Windows' default core.autocrlf the hook checks out CRLF and #!/bin/sh\r dies on Linux and macOS with a bad-interpreter error. crapkit doctor warns when a file under core.hooksPath is not 100755 in the index and prints the update-index line for it.

Git will not read a hooks path out of a committed file, so that git config line belongs in your CONTRIBUTING setup steps. Every clone arms the gate with it.

Route 3: the pre-commit framework

crapkit ships a .pre-commit-hooks.yaml declaring id: crapkit-gate. In your .pre-commit-config.yaml:

repos:
  - repo: https://github.com/JeanFrancoisGagne/crapkit
    rev: 5ffd6361605469a4e7e1212876ab19177354b37b
    hooks:
      - id: crapkit-gate

rev is a git ref pre-commit resolves against that remote, and the repo carries no tags yet, so pin a commit sha. The first release will ship a v0.1.0 tag; pin that instead once it exists, since pre-commit autoupdate only moves between tags.

What a refusal looks like

$ git commit -m "add route"
crapkit gate: 1 staged function(s) exceed the complexity ceiling of 6:
  ccn   7  app/m.py:9  route( a , b , c , d )
decompose before committing (coverage cannot save a function above the target).

Run directly, crapkit hook-precommit exits 6 on a violation and 0 otherwise.

Route 4: CI

A CI job runs on a fresh clone, which has no .crapkit/ store, so bare crapkit verify exits 1 — and running coverage first would make the PR's own tree the baseline, a gate that can never fail. The portable baseline is the mechanism:

# on the default branch, after a passing verify — commit this file
crapkit verify --emit-baseline crapkit-baseline.tsv

# in the PR job, against the committed baseline
crapkit verify --baseline-tsv crapkit-baseline.tsv --github

--github emits ::error file=... annotations that land on the PR diff; --sarif PATH writes SARIF 2.1.0 for code-scanning upload. Refresh the committed baseline whenever the default branch's verify passes.

CRAPKIT_OVERRIDE_REASON is not a bypass. Setting it routes the commit through the full three-record audit: an alert line through alert_command, a ratchet entry staged into the commit, and a row in the override log. All three land or nothing does, and an unset alert_command refuses the override outright. See docs/ratchet.md.

---

Reading the output

Flags: why a coverage number is missing

Flag	Meaning	Scored
measured	A lane artifact spoke about this function.	Real cov.
untested	A lane covers the scope, but its artifact is silent on this function, which normally means no test imports the file.	cov = 0. A testing gap, and uncovered_lines comes back null because no artifact can name lines it never saw.
no-lane	No lane's scopes list names this function's scope.	cov = 0. A tooling gap, not a testing gap. next-item never hands one out and counts them in skipped_no_lane; worklist ranks them and marks the row no-lane, because a wiring gap is a risk you have to see.
cc-only	The scope sets coverage_optional = true, so no coverage number can exist.	crap = ccn, and remedy can only be ok or decompose. uncovered_lines comes back null with a note naming that setting.

The coverage summary counts all four as measured / untested / no_lane / cc_only.

Remedy: what to do about it

Remedy	Condition	Action
decompose	ccn > ceiling	Split it. No amount of coverage clears this.
add-tests	ccn <= ceiling and crap > ceiling	Cover the branches.
ok	crap <= ceiling	Nothing.

Grade: over-target density

A letter for the fraction of functions over their ceiling. A+ is reserved for zero.

Grade	Over-target share
A+	exactly 0
A	under 2%
B	2% to under 5%
C	5% to under 10%
D	10% to under 20%
F	20% or more

crap_load beside it is the plain sum of every function's CRAP score, so it moves when a function gets better even if the grade does not.

Risk: what ranks the worklist

risk = ccn * churn weight. The weight is a time-weighted sum over the file's commits in the churn window: each commit contributes a logistic weight rising to 0.5 for the newest commit in the log and falling to near zero for the oldest, so five edits last month outrank fifty from two years ago. The window anchors on the newest commit, never on the wall clock, so a fixed tree ranks identically forever.

Age is not the input, position in the log is. A file only the oldest commit ever touched reads 0.0, and a log whose commits all share one timestamp reads 0.0 everywhere. Commits minutes apart already rank. This repo was eight commits old, all of them made the same day:

$ crapkit worklist --scope util
worklist @ a7c5c85ac37 (run 1, floor ccn>=5, churn 12mo) — 3 active, 0 dormant
  risk      5.4  ccn   5 (  5 std)    5c/1a w   1.08  util/stats.py:1  bucket( value , low , high )
  risk      4.5  ccn   9 (  9 std)    1c/1a w   0.50  util/curve.py:1  curve( scores , mode , floor , ceiling , skip_none )
  risk      4.3  ccn   4 (  4 std)    5c/1a w   1.08  util/stats.py:13  spread( values , cap )  ok

bucket at ccn 5 outranks curve at ccn 9 because five commits touched it and one touched curve. That is the whole point of weighting by churn. spread carries the ok marker: it is already at or under its ceiling, and the risk map lists it anyway — next-item would not hand it out.

worklist splits its output in two: active (files with commits in the window) and dormant (zero churn, kept out of the queue but counted). Two rules reach under the worklist_floor. A file whose churn weight sits in the top 10% is promoted down to ccn 3, so heavily edited simple code cannot hide under the floor: that is why spread is in the list above at ccn 4, under the floor of 5. And a function scoring over its ceiling is admitted whatever its ccn, so the floor can never hold back debt.

The trusted baseline

Every verify measures the working tree against one earlier run, the trusted baseline. Three rules decide which run that is, and one escape overrides them. crapkit runs list marks the answer.

Which runs qualify. A coverage run, or a verify run that passed. A failed verify never qualifies, and neither does a partial run (a lane failed, so some scope fell back to no-lane) nor a hook override record, which carries no scored rows at all. In runs list, verdict=- marks a run that produces no verdict rather than one that failed: only verify renders a verdict.

What advances it. Any qualifying run. coverage writes one wherever HEAD is, so a dashboard cron advances the baseline exactly as CI does. A passing verify advances it too, and tightens the ratchet on the way.

The taint rule. A failed verify recorded findings against a tree. Until some verify passes, runs made after that failure do not become the baseline: choosing one would move the comparison point past the findings, the flagged function would stop counting as touched, and nothing would ever look at it again. verify says which run it refused and falls back to the newest run in front of the failure.

$ crapkit runs list
run   1 @ 88012a148f6 2026-08-23T09:27:46Z coverage  verdict=-      lanes=py  baseline
run   2 @ 803bdde8556 2026-08-23T09:27:53Z verify    verdict=FAILED lanes=py
run   3 @ 803bdde8556 2026-08-23T09:28:02Z coverage  verdict=-      lanes=py

$ crapkit verify
warning: run 3 is not the baseline: verify run 2 FAILED with 1 finding(s) and no passing verify has cleared it since — measuring against run 1 @ 88012a148f6 instead, so those findings stay visible. Fix them, or pass `--baseline 3` to accept the newer run deliberately.
verify FAILED @ d89068de7f3 vs baseline 88012a148f6 (2 changed files)
  GATE  crap     72.0  ccn   8 cov 0%  calc/legacy.py:7  legacy_router( a , b , c , d , e )  -> decompose
  findings: 1 committed / 0 dirty (uncommitted tracked edits)

Run 3 is a coverage run somebody took on the tree run 2 refused, and it scores the same ccn-8 function. Without the rule it would have become the baseline, legacy_router would have stopped being a touched function, and that gate line would never print again.

The escape, twice. Fix the findings and let a verify pass, which clears the taint for good. Or accept the newer run on purpose with verify --baseline 3: an explicit id bypasses the rule, and the run history records which run the verdict used. Nothing here touches a repo that has never run verify — with no failure to protect, coverage alone always advances the baseline.

---

Exit codes

Code	Meaning
0	OK. For verify and hook-precommit: the gate passed.
1	Overloaded. Three unrelated things, listed below the table.
2	Usage error from argparse: unknown flag, missing positional. Raised before crapkit's own error handling.
3	Config error: crapkit.toml missing or unparseable, an unknown language or parser, a ratchet metric-stamp mismatch, a test-scoped file under no scope or under a scope with no template.
4	Git error: not a repository, a baseline commit rewritten out of the history.
5	Tool error: lizard not importable, a lane produced no artifact, a lane timed out past its retries, an override alert command failed.
6	Gate violation. A function the diff touched is over its ceiling, or rescore --gate found one, or hook-precommit did.
7	Ratchet regression. A marked function scores worse than its recorded high-water mark, touched or not.
8	New test failures against the baseline run. Failures the baseline already had do not count.
9	Diff-coverage ceiling breached: diff_uncovered_max is set and more changed lines than that never ran.

Exit 1 means one of three things

CI cannot tell a crash from a clean policy verdict on the code alone. Which one you got depends on the command:

Command	What exit 1 means
doctor	A FAIL finding. This is a verdict, not a crash. A WARN (an unmeasured directory, or a lane writing its artifact at the repo root) and a note (a file over max_file_bytes, or no lanes declared) both exit 0.
ratchet report --enforce	The debt policy was breached. Also a verdict.
anything else	An unexpected error: "no snapshot yet, run crapkit coverage first", a brief name that matches no function, a test-scoped runner that exited non-zero.

Precedence

verify reports the first of 6, 7, 8, 9 that fires, in that order. A gate violation and a ratchet regression together report 6. A run that takes any of them fails, so it neither advances the baseline nor tightens the ratchet, exit 9 included.

---

Subcommands

Every subcommand takes --repo PATH (default .), and the flag goes after the subcommand:

$ crapkit worklist --repo /path/to/repo --scope util --top 1
worklist @ a7c5c85ac37 (run 1, floor ccn>=5, churn 12mo) — 1 active, 0 dormant
  risk      5.4  ccn   5 (  5 std)    5c/1a w   1.08  util/stats.py:1  bucket( value , low , high )

Before it, argparse reads the path as the subcommand name and exits 2 without ever mentioning --repo:

$ crapkit --repo /path/to/repo worklist --top 1
crapkit: error: argument command: invalid choice: '/path/to/repo' (choose from 'inventory', 'coverage', ...)

--json prints one sorted-keys JSON object on stdout, always carrying a schema field.

Command	What it does
init	Sniffs tracked source into per-directory scopes, writes a self-validated starter crapkit.toml whose lanes report into .crapkit/cov/, and appends .crapkit/ plus each runner's own droppings to .gitignore. Writes a live [[lane]] when it can detect the test runner, otherwise a commented template. Refuses to clobber an existing config.
doctor [--show-files] [--json] [--tune]	Checks the config still describes the repo: unknown keys (with the accepted spellings), zero-file scopes, tracked source no scope claims, scopes no lane covers, lane cwds and commands that no longer resolve, lizard importable, oversized files, lanes writing their artifacts at the repo root instead of under .crapkit/ (WARN), committed hooks under core.hooksPath that are not executable in the index (WARN), directories whose functions are all untested while their tests exist (WARN), and scopes a lane measures with no [crapkit.scoped_tests] template behind them (WARN), which is the loop's step 4 with nothing to run. --tune prints suggested parallelism knobs and writes nothing. See docs/agent-json.md.
inventory [--db PATH] [--export PATH] [--json]	Two lizard passes over every in-scope file into a SQLite snapshot run, cached by content hash. --db is the only way to point crapkit at a store outside .crapkit/, and only this command accepts it.
coverage [--lane NAME] [--reuse-artifacts] [--reuse-unchanged] [--export PATH] [--sarif PATH] [--github] [--json]	Runs the lanes, joins branch coverage onto a fresh inventory, writes a scored run. A failed lane is recorded, not fatal: its scopes fall back to no-lane and the run is typed partial, so it can never serve as a baseline. See docs/lanes.md.
verify [--baseline ID | --base REF | --baseline-tsv PATH] [--emit-baseline PATH] [--override REASON] [--reuse-artifacts] [--reuse-unchanged] [--sarif PATH] [--github] [--json]	The full verdict against the trusted baseline: gate on touched functions, ratchet, no new test failures, optional diff-coverage ceiling. The three baseline selectors are mutually exclusive; --baseline ID also bypasses the taint rule (The trusted baseline), and --baseline-tsv reads a commit-stamped file so a fresh clone verifies with no store. Findings a dirty tree produced are tagged dirty and counted apart.
worklist [--top N] [--scope NAME] [--batches N] [--json]	The risk map: every admitted function ranked by ccn * churn weight, floored by worklist_floor, with hot simple code and anything over its ceiling admitted past that floor. It ranks finished rows and no-lane rows too, marked ok and no-lane, so it never empties; next-item carries the stop condition. --scope NAME (repeatable) is exact, not a substring. --batches N adds a batches[] view cutting the active list into at most N file-disjoint batches with co-changing files kept together; the normal keys stay.
next-item [--top N] [--exclude FRAG] [--scope NAME] [--claim]	The actionable queue as JSON, with churn, budget estimates and uncovered lines. Same run and same admission floor as worklist, a different view of it: no-lane rows are skipped and counted in skipped_no_lane, and what is left is ranked by crap descending rather than by risk, so the item it hands out is often not the worklist's first row. --exclude FRAG (repeatable) skips items whose path or function name contains FRAG; --scope NAME (repeatable) is exact, not a substring. --claim holds what it hands out so a second session skips it. stale is true when the ranked run's commit is not HEAD, the same field worklist carries. Every item carries a handle: the bare identifier, or (anonymous)#N for a function with no name, which is the name form that survives the edit the item asks for.
claims [list | release PATH NAME | release --all] [--json]	The open claims, and the way to hand one back without waiting for a verify. release takes the bare identifier, the whole long name, or the handle the claim was taken under, which is the only one that picks out a single (anonymous) claim.
brief FILE NAME [--batch N] [--json]	The start-editing packet for one function: its own source text, every function in the file, the scored row and the scope ceiling, the ratchet mark and what the gate will bind on, uncovered lines, duplication twins, file churn, coupling partners, the config's notes, and the literal commands for the rest of the loop. Plus handle, remedy and the same est_splits / est_uncovered_paths the queue prints, and a commands.refresh that writes a run (refresh_writes_run) rather than re-reading the stale one. NAME takes the bare identifier, the long name next-item printed, the function's start line, or (anonymous)#N for a function printed (anonymous), counting the file's anonymous functions from the top. --batch N drops the positionals and emits packets[] instead: the top N of the queue, built from one read of the store.
explain FILE NAME [--history] [--tests] [--json]	A function's score across runs plus its mark. --history adds the commits that touched it (git log -L), each carrying its message body, --tests the tests that covered it, which needs coverage.py contexts turned on (recipe). --json emits the same content as one schema 1 object.
rescore FILE ... [--gate] [--json]	Fresh complexity for named files over the latest run's stale coverage, joined by name. Advisory: it writes no run. --gate applies the pre-commit hook's policy to the same selection the hook uses (functions the tree changed since HEAD), minus functions a ratchet mark already covers, and exits 6.
ratchet seed | prune | merge | move | report [--enforce] [--json]	The mark lifecycle: seed new debt, prune gone code (a mark whose file git renamed follows it), merge as a git driver, move re-paths marks, report reads burn-down from the file's own git history. See docs/ratchet.md.
runs [list | prune [--keep N]] [--json]	Run history, and retention. list marks the run verify compares against today baseline, and prints verdict=- for a run that produces no verdict rather than one that failed. See The trusted baseline. --keep (default 5) is a floor on the newest trusted runs, not a cap: the digest pair, every passing verify baseline, every run an override names, and the newest non-hook run are kept too. prune VACUUMs afterwards.
overrides [--json]	The override audit trail: who granted what, when, and why.
trend [--json]	Totals per trusted run: functions, over-target count, CRAP load, average, per-scope rollup.
digest [--alert]	The delta between the two newest runs with identical lane sets. Silent when nothing changed. --alert pipes the body to alert_command on stdin. Plain lines, never JSON.
duplication [--min-lines N] [--similarity F] [--top N] [--json]	Near-duplicate functions by normalized line shingles with containment scoring. Defaults: --min-lines 8, --similarity 0.8, --top 50. --top truncates the list.
coupling [--min-support N] [--min-confidence F] [--top N] [--json]	File pairs that keep landing in the same commits. Defaults: --min-support 5 shared commits, --min-confidence 0.5 max-direction ratio, --top 50. Bulk commits never couple pairs, and a young repo returns nothing at the default support.
mutate [--files F ...] [--max-mutants N] [--json]	Diff-scoped mutation testing: flips comparisons, boundary shifts, boolean connectives and boolean literals on changed lines, runs mutation_command per mutant, lists survivors. --files replaces diff scope with the whole file. --max-mutants (default 100) caps the run and the cap warning goes to stderr only, so mutants in --json is the capped count.
test-scoped FILE ...	Runs each owning scope's [crapkit.scoped_tests] template on the files (quoted, longest-prefix scope wins). A template with no {files} runs as written, which is how a scope whose tests live outside its own paths runs its whole suite. Exit code only; a nonzero runner exits 1.
hook-precommit	The cc-only gate on staged blobs. No coverage, no snapshot, no repo-wide cache. Exit 6 on a violation.
watch [--interval SECONDS] [--cycles N]	Rescores tracked files as they change (mtime polling, default 2s, subprocess-isolated so a half-saved syntax error never kills the watcher). --cycles N polls exactly N times and exits 0; without it the loop runs until ctrl-c.
mcp	A dependency-free stdio MCP server (newline JSON-RPC 2.0) exposing nine read-only tools. See docs/agent-json.md.

Documentation

Page	Covers
docs/handbook.html	The illustrated handbook: what crapkit is, how every piece works, and where each command earns its keep. Self-contained HTML — open it straight from a clone.
docs/configuration.md	Every crapkit.toml key: type, default, and what it does.
docs/lanes.md	The lane model, vitest and jest and pytest recipes, artifact reuse, flake retest, containers.
docs/ratchet.md	Seeding, pruning, the git merge driver, metric stamps, debt policy, overrides.
docs/agent-json.md	The machine surface: schema, every payload field, real captured examples.
docs/adoption.md	The judgment layer over the quickstarts: scope granularity, exclude vs lane, scoped_tests wiring, the first-verify taint hazard.
skills/	Agent skills shipped with the repo (crapkit, crapkit-recover, crapkit-onboard) — install by copying to your agent runtime's skills directory.

crapkit.schema.json is the authority on the config file shape.

Development

pip install -e ".[dev]"
pip install pytest-xdist
git config core.hooksPath git-hooks
python -m pytest -q

pytest-xdist is not optional: tests/fixtures/mini_repo declares a lane that shells out to pytest ... -n 2, and without it that subprocess dies on an unrecognized -n. The git config line arms the complexity gate on your own commits. Same steps, with what each one buys, in CONTRIBUTING.md.

License

MIT. See LICENSE.