Metadata-Version: 2.4
Name: comprehension-debt
Version: 0.13.2
Summary: Measure — and catch at creation — code your team no longer understands.
License: Apache-2.0
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: lizard>=1.17
Requires-Dist: numpy>=1.21

```
   ____ ____  _____ ____ _____
  / ___|  _ \| ____| __ )_   _|
 | |   | | | |  _| |  _ \ | |
 | |___| |_| | |___| |_) || |
  \____|____/|_____|____/ |_|
```
**know which code nobody on your team understands — before it pages you at 2 a.m.**

---

## what is this

AI writes code 5–7× faster than anyone can actually read it. Tests pass, velocity looks great, everyone's happy — until something breaks and you realize *nobody* can explain the file it broke in. That gap has a name now (Google's Addy Osmani called it **comprehension debt** in March 2026), and `cdebt` is a tool that measures it, blocks it at the door, and helps you pay it off in ~3 minutes per file.

It's not another linter. It doesn't care if your code is "clean." It cares whether a **named human can prove they understand it**.

One formula, no magic:

```
debt(file) = difficulty × exposure × (1 − verified understanding)
```

Every score comes with the evidence that produced it. If the data doesn't exist, the component stays silent — honest by default.

## get it running (60 seconds)

```bash
git clone https://github.com/RonaldSit/comprehension-debt && cd comprehension-debt
pip install .
cd /path/to/any/git/repo

cdebt scan .                      # 0–100 risk per file, with the WHY
cdebt scan . --html report.html   # same thing, but pretty
```

Python ≥ 3.9. Two deps (lizard, numpy). No server, no account, no network — everything runs locally on your git history. Works on a local folder **or** straight off a URL: `cdebt scan https://github.com/org/repo`.

## how you'd actually use it

**You're a dev.** The gate runs in CI (`action.yml` is included). Clean PRs pass silently. When it blocks you, that means you shipped something complex that nobody has demonstrably understood — so:

```bash
cdebt repay .                 # drafts an ADR + 3 questions about YOUR file
cdebt confirm . thefile.py -i # answer in your own words; answers get graded against the code
```

Generic AI-pasted answers score 0 (they never name the file's actual identifiers — that's their tell). "I don't know" also scores 0, and that's fine: the honest signal is the point. Learn the file first (ask Claude to walk you through it!), *then* confirm what you verified.

**You're the lead.** Once a week:

```bash
cdebt scan . --save-baseline   # remember today
cdebt trend                    # is the dark stuff growing?
cdebt repay . --path scary.py  # schedule the worst file into the sprint
```

Repo full of AI code with no commit trailers? Declare it honestly: `echo '{"assume_ai": true}' > cdebt.json && cdebt scan . --config cdebt.json`. Files someone already verified are exempt — we never punish the people who did the right thing.

**Something's on fire.** Wire Sentry/PagerDuty into `cdebt serve`, or `cdebt ingest . --payload incident.json`. The moment an incident lands, the terminal tells you **who actually understood the blamed file** and shows their explanation, in their words. Then `cdebt calibrate .` scores the score itself against *your* incident history — including a Miss Ledger of every bug it under-rated, with its likely blind spot. We keep our own receipts.

## receipts (run them yourself, please)

- **54 self-checks, one command, no network, ~1 min:** `python tests/test_suite.py` — covers every command, the anti-faking grader, corrupt stores, concurrency, unicode filenames, the works.
- **Real-bug benchmark, zero lookahead:** on **84 real historical bugs** from the peer-reviewed [BugsInPy](https://github.com/soarsmu/BugsInPy) dataset (tqdm, thefuck, fastapi, youtube-dl), the buggy file ranked in our **top quartile 93% of the time — 3.7× random**. fastapi and youtube-dl: 16/16 and 43/43. Reproduce it:

```bash
git clone --depth 1 https://github.com/soarsmu/BugsInPy /tmp/BugsInPy
python benchmarks/bugsinpy_bench.py --bugsinpy /tmp/BugsInPy --project fastapi
```

- **Scale:** 100,000-file monorepo → cold scan 22 s, warm 6 s, ~540 MB RAM, deterministic.
- **Multi-user:** concurrent confirms are lock-protected; 4 parallel writers, zero lost updates (it's check #54).

## what it costs

**$0.** Local git + AST + numpy. The only optional paid bit is `--llm` (Claude drafts the ADR and grades answers against the code) — that reads **your own** `ANTHROPIC_API_KEY`, ≈ $0.02–0.03 per confirmation, and everything works without it.

## what it deliberately does NOT do

It doesn't find bugs (SAST does that). It doesn't judge style (linters do that). It doesn't replace review bots (it consumes their output as a signal). And it can't catch "simple but wrong" — a trivial file with a wrong constant scores low, and when one of those causes an incident, the Miss Ledger says so out loud. See `VALIDITY.md` for exactly what the score claims and what it doesn't.

## the 15 commands

`scan` · `gate` · `report` · `audit` · `trend` · `repay` · `confirm` · `reverify` · `calibrate` · `ingest` · `serve` · `recalibrate` · `reviews` · `explain` · `prsignals` — each has `--help`. Longer walkthrough in `USAGE.md`.

---

Apache-2.0. Built solo, bug ledger currently at 27 (every one has a regression test now). If it breaks, open an issue — I answer.
