The State of Comprehension Debt 2026

The number your dashboards don't have

In September 2025, Jason Gorman gave a name to something engineering leaders had been feeling for a couple of years. He called it comprehension debt: the growing gap between how much code exists in your system and how much of it any human being genuinely understands. His essay sat on the front page of Hacker News for a day, and when Addy Osmani picked the term up in March 2026 it crossed into the mainstream of engineering leadership. AI assistants write more of the code. Humans review less of it, and the authors move on to other things. Meanwhile every dashboard you own says things are fine, because velocity and DORA metrics measure output, and output is the one thing that keeps improving.

The term caught on. The measurement didn't exist, so I built it.

The Grasp Score is computed entirely from data every repository already has (git history and pull-request metadata, with no source code contents required). For every module it asks four questions:

1. Living knowledge: What share of recent lines is held by authors weighted by how recently they were last here, full weight the day they commit, half weight after 180 quiet days? The binary 90-day version ships beside it.
2. AI attribution: What share carries hard evidence of AI authorship, meaning agent co-author trailers and bot accounts?
3. Review depth: Were large changes actually reviewed by a human? Approved in minutes? Or only ever reviewed by other AIs?
4. Heat and concentration: Is poorly-understood code still changing, and how few people hold what remains?

Then I ran it on 22 well-known repositories across five groups: AI-era agent tools, AI-era applications, AI vendor SDKs, modern human-led projects, and pre-AI controls.

Finding 1: The most-installed AI libraries are machine-written on purpose

The client libraries millions of developers install first, openai-python and anthropic-sdk-python, carry the highest machine authorship in the benchmark: 87% and 77% of their lines are attributable to automated codegen pipelines and bot accounts in the public repository history. Nothing else comes close. The next-highest repository of the 22 sits at 45%, and the median across the benchmark is 2%. Living commit-authorship runs correspondingly low, 19% and 22%, on six and twelve active human contributors respectively; the living figure counts the engineers named in the pipeline's own co-author trailers, since a present human who steers generated code still counts as present.

Both libraries are generated from API specifications. That is a deliberate engineering choice, an industry-standard one, and it says nothing about whether the engineers at either company understand their own products. The interesting part is what it does to the measurement: when the pipeline is the author, comprehension doesn't vanish, it relocates. It moves into the generator and the spec, where repository metrics, review records and every conventional dashboard are blind to it.

That is the structural problem, and it belongs to every company adopting generated code, not to these two. They are simply the clearest public example: the most-installed AI client libraries in the world, and no standard tooling can audit either of them. The contrast within their own group settles it: vercel/ai is largely hand-written, at 8% machine-attributable and 81% living authorship.

Finding 2: Comprehension debt is older than AI

My pre-AI control group split cleanly in two, and this was the part that surprised me.

I expected curl to score near the bottom. It is 25 years old and hundreds of contributors have come and gone from it. Instead it came back at 92% living knowledge, 52 active contributors, held by a genuinely wide bench; nothing in the benchmark scores higher. My first assumption was a bug in my own engine. The number survived every recheck I could throw at it: a second weighting scheme reads it at 92%, the binary 90-day variant published beside every headline reads 96%, and that variant swept across five different definitions of "currently active" stays between 93% and 97%. That is about as load-bearing as a single data point gets.

Requests scored 71% and Flask 62%, and here the engine did something I want to show rather than hide. It labelled Flask volatile and Requests moderate while calling curl stable, on its own, before I had looked at any of them. Flask has exactly one active contributor, and the binary variant of its score shows what that means: 78% at a ninety-day window, zero at sixty, one person's last commit deciding which. The headline prices that person's recency as a curve instead, so it moves in steps rather than plunges, and the volatile label still travels with the number so a reader knows how much of it is one human being. So the weight goes on curl, and the pattern among well-maintained old projects is a tendency worth naming rather than a law worth proving.

Express is the other half of the split. The framework sitting under an enormous fraction of the web scored 56% living commit-authorship, with three fifths of its recent change belonging to contributors quiet past the 90-day window (10 active humans, out of 386 who ever contributed). Gin scored 49%. To be clear, none of this criticizes the current maintainers. The score describes how much accumulated authorship has aged out from under them, which is precisely the burden they carry.

One more instrument reading belongs with those three, because the window itself is part of the story. The churn score describes the work of the last three years, and in a slow-moving repository that is a thin slice: the window holds about two percent of the recorded work in Requests, and every scan states this coverage figure and flags anything under half. The whole-tree view is the survivorship analysis, which attributes every line that currently ships, and it reads Requests at 38%, Flask at 51%, and Express at 2%. The pairing is the point. In these old projects the people still present tend the recent surface while the deep stack under it belongs to authors long gone, so the churn view answers where risk is accumulating now and the survivorship view weighs the asset as it stands. Express is the starkest case: just over half of its recent change is living, and almost none of its standing code is.

So age defends nothing, in either direction. The oldest project in the benchmark is the best-understood, and a 15-year-old pillar of the npm ecosystem has lost three fifths of its recent authorship and nearly all of its standing code. Comprehension debt turns out to be a maintenance phenomenon. AI just puts it on a faster clock.

Finding 3: The most AI-native projects have the fewest present authors

Median living knowledge by group:

The ends of that table survive nearly every choice I made. The headline itself is priced on a recency curve, so the 90-day line does not even enter it; the binary variant beside it was recomputed at five activity windows, 30 through 365 days, and the whole benchmark separately under both weighting schemes. Modern human-led projects come out highest at every setting. AI vendor SDKs come out lowest at every window of sixty days or longer; only at thirty days do the pre-AI controls dip below them under the binary variant, because a one-month bar on presence zeroes out mature projects whose maintainers commit in bursts. A gradient whose ends hold that broadly is not an artifact of where the lines were drawn, and the one setting that bends it is named here rather than hidden.

What does not survive is the middle. Agent tools, pre-AI controls and AI-era apps trade places as the window moves, so the gaps between those three rows are not findings and I won't present them as findings. Read the ends of that table, not the ordering.

One more number stopped me, and it survives every way I tried to soften it. LangChain has had 4,547 human contributors, a count that includes every person named only in co-author trailers. Forty-two committed in the last ninety days. Widen the definition to a full year, the most generous I can justify, and it is 342. Even then, more than nine in ten people who ever contributed to the most-forked AI framework of the decade are gone, and the stricter the window the worse it looks. That is not a threshold artifact. That is the shape of the project.

I also sampled review depth on one fast-moving AI-era repo: 34 merged pull requests, deliberately weighted toward the largest merges, of which 41% had no recorded human review and 35% were reviewed only by AI bots, including a 2,077-line change merged 24 minutes after opening. I am flagging this as the weakest evidence in the piece and the most likely to be over-read. It is one repository, a sample rather than a census, and the review record cannot see pairing, prior coordination, or review done anywhere but GitHub. It is a thread worth pulling, not a finding, and I would not build an argument on it.

Put the three findings together and you get the 2026 stack: AI-assisted code, increasingly reviewed by AI, sitting on frameworks whose original authors have moved on. No dashboard in standard use measures any layer of that.

What this means if you run an engineering org

Every metric you watch was designed to measure output. Comprehension debt is a stock rather than a flow. It accumulates silently while the output metrics improve, and it eventually presents as incidents nobody can explain, onboarding that takes longer every quarter, and the specific reluctance everyone feels about touching certain modules.

Both failure shapes from the open-source data exist inside companies too. There is dark code: fast-growing, AI-heavy modules with no living author, where the review record shows comment-free or AI-only approvals. You meet that one during an incident. Then there is concentration risk, where the knowledge is alive but resides in exactly one person, and you meet it the day that person resigns.

Neither shows up in a velocity dashboard. Both are computable this afternoon from data you already have.

Method and limits

Metadata only: commits, authorship, timestamps, diff stats, PR review events. Never file contents. AI attribution counts only hard evidence (co-author trailers and bot accounts), and is measured against hand-written source rather than everything in the repository, because the claim is about code: Gin reads as 30% machine-written across all its files and 1% across its source, the difference being a maintainer who co-authors release notes with an agent. Attribution also overlaps living knowledge rather than subtracting from it: an active human who ships attributed agent-assisted work counts as living, and the same lines count toward the minimum, because a metric of unnoticed risk must never price honesty as a defect. Work itself is counted as lines changed, additions plus deletions, so the person who prunes dead code is as visible as the person who adds it. Living authorship is not scoped that way. Tests and documentation are real work that someone has to understand, so every scan publishes its composition and both figures. Counting only hard evidence makes AI attribution a minimum, and a low one. Most machine authorship is simply never marked: when someone works with an agent in their editor and commits normally, git records a human author and nothing else. Even the most agent-heavy repositories here carry an attribution-capable signal on only a quarter to a half of their commits, and curl on under one in twenty-five; much of the spread between projects comes from platform squash conventions injecting trailers, not from agent use. Squash-merging strips some of the rest, though platform defaults preserve trailers on a quarter to a third of squash commits, which are credited. Read every AI figure as attributable rather than actual, and expect the gap to widen as agent use becomes ambient. "Inactive" in open source includes drive-by contributors, which overstates attrition relative to a company repo with a real roster; every scan reports how much of its inactive weight is that one-commit long tail (drive_by_share), so the tail is subtractable rather than guessed at. Inactive means silent in the window, not gone: most long-tenure contributors on mature projects have been silent for ninety days at some point and returned. And living authorship is a proxy for comprehension. Treat every score as a potential indicator that tells you where to look, not a diagnosis.

I will also be explicit about something most metrics never admit: this one will age, by design. Living authorship is the right comprehension proxy today because authorship is still where comprehension mostly comes from. As agent-written code becomes the default, that assumption expires. In a mostly-agent-written repo, low human authorship becomes true of healthy teams too, and comprehension migrates into review, steering, and specification. When that happens, authorship share retires as the headline number and engagement share replaces it: human review depth on AI-authored change, steering patterns, authorship of specs and rules files. The engine already computes the candidate on every scan, the living share of steering artifacts and of follow-up on AI-touched work, and reads review depth where platform records exist; the candidate is promoted through a published study or not at all. The formula is versioned and will change. The question it answers, who still understands this system, will not.

One comparability limit deserves stating plainly. Projects that squash-merge collapse each pull request into a single commit by a single author, and they vary enormously in how much they do it: from 0% of commits to 99%. Squashing does not uniformly destroy co-authorship, since platform defaults preserve trailers in the squashed message; measured on the heaviest squashers here, 27% to 39% of squash commits carry them, and crediting those surfaced 959 otherwise invisible LangChain contributors. What it reliably erases from git is review-only participation, which survives on the hosting platform and is stated future work to read back. For what stays lost, a heavily squashed repository's concentration figures are an upper bound and its AI attribution is a lower one. What I can say is that it does not appear to drive the group pattern above. Squash rates range from 0% to 99% inside the pre-AI controls alone, and across all 22 repositories the correlation between squash rate and living knowledge is essentially zero (r = 0.01). Every report states the repository's squash rate so the reader can judge for themselves.

The Grasp Score is a windowed churn measure: it scores the work inside its stated window, not the whole tree. Every scan reports what share of the repository's recorded history the window contains and flags anything under half, because a thin window skews toward whoever is still around; the whole-tree question belongs to the survivorship view, and the two are designed to be read together. Two blunter limits sit next to that. Git history is self-reported: a repository records whatever author name and date the committer supplied, so a determined insider can manufacture apparent activity, and a scan measures the record, not the truth behind it. Wide cosmetic commits are the cheap version of the same move; a formatter pass that touches every file hands its author weight across the whole surface, so every scan reports the largest share of the window's changed files that one commit touched and flags it above a third. And merge commits are excluded from authorship counts, which across this benchmark leaves out at most about three percent of commits.

I also computed everything twice, using two weighting schemes that err in opposite directions. Line-weighting matches "what share of the code by volume has a living author," but it lets verbose and generated authorship dominate. Touch-weighting counts each file-touching commit once, which is closer to how comprehension actually forms, though it prices a 3,000-line generated commit the same as a one-line fix. The findings hold in both modes. The two codegen SDK repos score 19% and 22% line-weighted, 11% and 15% touch-weighted, with machine authorship between 77% and 90% under both; curl scores 92% in each; the group-by-group gradient keeps both of its ends. When two differently-biased instruments agree, the conclusion is stronger than either alone. Full methodology and per-repo data are in the report.

One thing this instrument does that I have not seen elsewhere is report its own error bars. Every scan states the share of commits carrying any attribution signal, the repository's squash rate, the share of lines held by its single largest commit, the mix of source against tests and documentation, and the binary variant recomputed at three activity windows with a stable, moderate or volatile label attached. Those are the numbers above, and they are why I can tell you which of my own findings to lean on and which to discount. The alternative is a single confident figure with the uncertainty stripped out, which is how most metrics are sold, and it is worth less.

The honest limit sits underneath all of it: none of these thresholds have been validated against an outcome. Nobody has shown that a low score causes incidents or slows onboarding, because that needs data linking repository history to incidents and ramp times, and no public dataset provides it. Building a proxy for it, counting bug-fix commits and calling them incidents, would look like evidence without being any, so what I can show is which conclusions survive changing the thresholds and which do not, and the methodology page publishes the full sweep, including the parts that went against me.

Scope of claims: every number derives from publicly available repository metadata analyzed with the disclosed method. Nothing here asserts misconduct, negligence, or lack of competence by any contributor, maintainer, or company, and nothing here is a claim about the quality, security, or fitness of any software. Project names identify public data sources; all trademarks belong to their owners. Believe a number is wrong? Verified errors are corrected and this report is versioned. Find one? Contact support@graspscore.com.

The Grasp Score is the first instrument for the Comprehension Index. The methodology is published in full because the aim is a public standard, one anyone can scrutinize. Scan your own repos at graspscore.com.