Arrange Act Assert

Jag Reehal's thoughts on things, mostly product development

Deterministic Complexity Gates for Humans and AI Agents

16 Nov 2026

Your coding agent says the feature works, and the tests pass. You still can’t tell whether it left the code easier or harder to change.

A complexity gate measures every function, gives the same score on every run, and stops complexity growing past limits you agree. For code already over those limits, a ratchet stops it getting any worse. This post explains the two numbers worth measuring and how to put a gate in front of your agent with AutoRatchet.

The problem with “looks fine to me”

You ask Claude Code to add express delivery to a shipping calculator. Two minutes later it reports success, and the tests are green. You skim the diff. Twenty lines changed, nothing jumps out, you merge.

The function before the change:

export function shippingCost(weightKg: number, country: string): number {
  if (country === 'GB') return weightKg * 2;
  return weightKg * 5;
}

The function after:

export function shippingCost(
  weightKg: number,
  country: string,
  express: boolean,
  member: boolean,
): number {
  if (country === 'GB') {
    if (express) {
      if (member) {
        return weightKg * 3;
      } else {
        return weightKg * 4;
      }
    } else {
      if (member && weightKg < 2) {
        return 0;
      }
      return weightKg * 2;
    }
  } else if (country === 'FR' || country === 'DE') {
    if (express) {
      return member ? weightKg * 6 : weightKg * 8;
    }
    return weightKg * 4;
  } else {
    if (express) {
      return weightKg * 10;
    }
    return weightKg * 5;
  }
}

It works. You also need a careful read to answer a question like “what does a German member pay for express?” Do that ten times a week across an agent’s output and the codebase gets harder for you and for the agent to change.

You could ask a second model to review it. That helps, and I run model reviews myself in Shepherd. A model gives you an opinion, though, and ask twice and you can get two opinions. For a merge decision you want evidence: a measurement that gives the same answer for the same code, every time you run it. That is what deterministic means here.

Two numbers for every function

Linters have measured function complexity for decades. A linter is a program that reads your code without running it and reports problems. Two measurements matter.

Cyclomatic complexity counts the decisions in a function. Each if, loop, &&, ||, ?: and catch adds one, and the function starts at one. The number counts the independent paths through a function, and gives you an indication of how much testing its control flow needs. The new shippingCost scores 11. The original scored 2.

Cognitive complexity scores how hard the function is to read. It also counts decisions, and it charges extra for each one nested inside another, because you have to hold every enclosing condition in your head to understand the inner one. The new shippingCost scores 21. The original scored 1.

Version Cyclomatic Cognitive
Before 2 1
After the agent’s change 11 21

In JavaScript and TypeScript, AutoRatchet uses Oxlint, an established linter, to measure cyclomatic complexity. It scores cognitive complexity with the same rules as Biome’s linter, and its scores match Biome’s on every one of 25,644 functions I compared.

AutoRatchet also reads Rust, Python and Go. For Python it matches radon and complexipy, and for Go it matches gocyclo and gocognit, so your scores agree with the tools Python and Go developers run.

No limit suits every codebase. ESLint’s complexity rule defaults to 20. AutoRatchet defaults to 10 for cyclomatic and 15 for cognitive, and the agent’s version breaks both.

Why measure both

The two numbers catch different kinds of mess. A flat list of ten guard clauses (if (!user) return false; and so on) scores 11 on cyclomatic, over its limit, and 10 on cognitive, inside its limit, because you can read each line on its own. Three if statements nested inside each other score 4 on cyclomatic and 6 on cognitive. Nest six deep and you get 7 on cyclomatic, inside its limit, and 21 on cognitive, past its limit of 15.

Cyclomatic complexity alone doesn’t penalise nesting, so the six-deep function above passes a cyclomatic gate. If you gate on cognitive alone, a function can pile up routes that each need a test. Gate on both and the agent has to produce code that is easy to test and easy to read.

Why a plain lint rule fails on real codebases

You could switch on the complexity rules in ESLint, Oxlint or Biome today. On a project that has been running a few years, they fail on hundreds of functions on day one. Teams then either leave the rules off, or record every existing failure as accepted, which tools call bulk suppressions.

Suppressions count how many functions break the rule in each file. A function already on the list can then grow from 19 to 40 and CI stays green, because the count did not change. Your agent finds that gap within a week, without meaning to.

A ratchet compares each function with its past self

A ratchet is a tool that turns one way. AutoRatchet applies that idea to complexity. It measures every function in your pull request, measures the same function on your main branch, and applies three rules:

  1. A new function must stay within the limits.
  2. A function already over a limit may not get any worse.
  3. A function under the limit may grow, up to the limit.

You never maintain a baseline file. Your main branch is the baseline. You can install AutoRatchet on a ten-year-old codebase today without fixing a single function first. From then on, a function already over the limit cannot get more complex unless a person approves an exception.

With the cyclomatic limit at 10:

Score on main Score in the pull request Result
new function 10 Pass: inside the limit
new function 11 Fail: over the limit
7 10 Pass: grew, up to the limit
7 11 Fail: grew past the limit
25 25 Pass: legacy code, no worse
25 26 Fail: legacy code got worse
25 22 Pass: improved
22 23 Fail: 22 is the new ceiling

The last two rows show the ratchet turning. Once you merge the improvement from 25 to 22, main holds 22, and the next pull request has to stay at 22 or below. A plain lint rule cannot tell those rows apart. It fails all four legacy rows, or, with suppressions, passes all four.

The rule fits in one line:

current <= Math.max(previous ?? 0, threshold);

previous is the score on main, or nothing for a new function. threshold is 10 for cyclomatic and 15 for cognitive.

Try it on your machine

AutoRatchet needs a git repository. In a JavaScript or TypeScript project, install it as a development dependency and compare your work with main:

npm install -D autoratchet
npx autoratchet check --base main

In a Rust, Python or Go project, download the autoratchet binary from a GitHub release and run the same command, with no Node.js needed. The ratchet and the GitHub Action work the same way in every language. The AutoRatchet README shows how Rust, Python and Go name functions and write overrides.

Run against the agent’s shippingCost change, it prints:

Complexity regressions detected:

shipping.ts
  shippingCost
    cyclomatic: 2 → 11 (+9)
    cognitive: 1 → 21 (+20)

Quality gate failed.

The command exits with code 1, so any script or CI job that runs it fails. Uncommitted changes count, and files your .gitignore excludes do not. To check one folder, add it at the end: npx autoratchet check --base main src.

AutoRatchet fails closed. If it cannot measure a function, because a file does not parse or a score matches no function it can name, the check exits with code 3 and lists what it missed. A function the tool never measured counts as a failure, so an agent cannot get past the gate by leaving a file half written.

Now ask the agent to fix the code. A good fix pulls the prices into a table and the country rules into a small helper:

type Zone = 'GB' | 'EU' | 'WORLD';
type Rates = { standard: number; express: number; memberExpress: number };

const RATES: Record<Zone, Rates> = {
  GB: { standard: 2, express: 4, memberExpress: 3 },
  EU: { standard: 4, express: 8, memberExpress: 6 },
  WORLD: { standard: 5, express: 10, memberExpress: 10 },
};

function zoneFor(country: string): Zone {
  if (country === 'GB') return 'GB';
  if (country === 'FR' || country === 'DE') return 'EU';
  return 'WORLD';
}

export function shippingCost(
  weightKg: number,
  country: string,
  express: boolean,
  member: boolean,
): number {
  const zone = zoneFor(country);
  if (zone === 'GB' && member && !express && weightKg < 2) return 0;
  const rates = RATES[zone];
  if (!express) return weightKg * rates.standard;
  return weightKg * (member ? rates.memberExpress : rates.express);
}
Function Cyclomatic Cognitive
shippingCost 7 4
zoneFor (new) 4 3

Both sit inside the limits, and the check passes. You can answer “what does a German member pay for express?” from one row of the table.

Put the gate in your pull requests

You will forget to run a check on your laptop. Add it to GitHub Actions and every pull request gets it, whether you or an agent wrote the code:

# .github/workflows/autoratchet.yml
name: AutoRatchet
on:
  pull_request:
  pull_request_review:
    types: [submitted, dismissed]

permissions:
  contents: read
  pull-requests: write

jobs:
  ratchet:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: jagreehal/autoratchet@v0.4.6
        with:
          path: src
          override-approval: review

If a function gets worse, the job fails, the diff marks the function, and a single comment on the pull request lists each regression with its before and after scores. In your repository settings, make the job a required status check so nobody can merge past it.

Let the agent see the gate while it works

CI reports the problem after the agent has finished. Claude Code hooks catch it during the work. A hook is a script that Claude Code runs at set moments, such as after each file edit. If the script exits with code 2, Claude Code hands the script’s message back to the agent as feedback to act on.

AutoRatchet ships two hooks:

mkdir -p .claude/hooks
cp node_modules/autoratchet/agent-hooks/claude-code/complexity-check.sh .claude/hooks/
cp node_modules/autoratchet/agent-hooks/claude-code/settings.json .claude/settings.json

If you already have a .claude/settings.json, merge its hooks block into yours. The hooks need git and jq installed.

After every edit, the first hook checks the edited file against your last commit. Before the agent hands back to you, the second checks every changed file. On a regression the agent reads the report, plus a nudge toward guard clauses, lookup tables and named conditions, and fixes the code before you see it. The shippingCost refactor above is the kind of change you get.

Treat the hooks as a fast feedback loop and the CI job as the rule. The hooks run on the author’s machine, where anyone can switch them off.

The CI job has limits of its own, so set it up with care:

This is the approach from AI Code Needs Rules, Not Rituals: you constrain the output with a tool that gives the same answer every time, instead of hoping a prompt in CLAUDE.md holds.

When a high score is fine

Some functions score high and read well. An options object with ten defaults scores 12 on cyclomatic and has no logic in it. A parser that follows a specification step by step reads best as one function. For those, you add an override comment above the function with a reason:

// oxlint-disable-next-line complexity -- options bag: each default is one line, no logic
export function createChart({ width = 640, height = 400 /* … */ } = {}) {

complexity covers the cyclomatic score. For the cognitive score, name sonarjs/cognitive-complexity, the rule’s standard ESLint name: // eslint-disable-next-line sonarjs/cognitive-complexity -- <reason>. Name both rules, comma-separated, to cover both.

Python and Go use the comments their developers write today. In Python, # noqa: C901 covers the cyclomatic score and # complexipy: ignore the cognitive one. In Go, write //nolint:gocyclo,gocognit.

An override approves one score on one function. AutoRatchet keeps measuring the function, and the approved score becomes its ceiling. Say you approve createChart at 12. A later pull request that takes it to 13 fails. Bring it down to 11 and 11 becomes the ceiling. Bring it under 10 and the function goes back to the normal limit of 10. A metric the comment does not name stays enforced. Most linters treat a disable comment as a permanent exemption, and the function behind it can grow without limit.

An agent that hits the gate might try to write that comment itself. The hooks block any new override and tell the agent to stop and ask you. In CI, override-approval: review passes a new override only when someone other than the author, with write access, approves the pull request’s latest commit. The agent can propose an exception. A person has to grant it.

What the gate does not tell you

A complexity score measures shape. It says nothing about whether the code does the right thing, so you still need tests. A function with a score of 3 can charge the wrong price.

An agent can also pass the gate by splitting a function into smaller ones at arbitrary points, which leaves the code no easier to follow. A pass tells you the code met a constraint. You still judge the design, and the review of the pull request is where you do it.

The scores also have blind spots. AutoRatchet identifies a function by its file and name, so if the agent renames a function or moves it to another file, the function counts as new and must meet the limits for new code. AutoRatchet reads JavaScript, TypeScript, Rust, Python and Go.

Within those limits, you get a number per function that you, your CI and your agent all agree on, and a function over the limit can’t get worse.

Agents let you write code faster than you can review it. That makes checks with a fixed answer more valuable, because they keep up with the agent and give the same verdict on the hundredth pull request as on the first.

Start with one command

Run npx autoratchet check --base main on a branch your agent wrote last week. If it passes, add the workflow and the hooks, and you have a gate. If it fails, you have found where to look.

To learn the two metrics in depth, with runnable examples, false positives worth overriding and the ways teams game quality gates, read Cyclomatic and cognitive complexity, explained. For turning repeated review comments into new lint rules, see Your coding agents need a gardener.

aiai-agentstypescripttesting