consequence-ledger 0.3.0__py3-none-any.whl

consequence_ledger-0.3.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: consequence-ledger
+Version: 0.3.0
+Summary: Measure what AI coding decisions actually cause: randomized routing, delayed outcome labels, causal estimates.
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sujan-mitta/consequence-ledger
+Project-URL: Source, https://github.com/sujan-mitta/consequence-ledger
+Project-URL: Changelog, https://github.com/sujan-mitta/consequence-ledger/blob/main/CHANGELOG.md
+Keywords: ai,coding-agents,causal-inference,off-policy-evaluation,szz,git,software-engineering
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Consequence Ledger
+
+**Which AI coding tool actually *causes* fewer reverted and bug-fixed changes on your code?**
+
+AI tools are judged on instant signals: a suggestion accepted, tests passing, a developer saying it felt faster. What matters arrives weeks later: the change gets reverted, or someone ships a fix for it. Comparing tools on those later outcomes is misleading unless you account for *which tasks each tool was given*. This prototype records that properly and turns it into cause-and-effect estimates.
+
+It is the 90-day MVP from the "AI elephant in the room" research: decision logging with propensities, commit attribution, revert and SZZ outcome labels, and IPW / doubly-robust estimates with confidence intervals. It is pure Python standard library, with no dependencies beyond `git`.
+
+## Install
+
+Python 3.9+ and git 2.28+. There are no dependencies.
+
+```bash
+git clone https://github.com/sujan-mitta/consequence-ledger.git
+cd consequence-ledger
+pip install .          # gives you the `ledger` command; or skip this and use `python -m ledger` from the folder
+ledger --version
+```
+
+## Quick start
+
+```bash
+python -m ledger demo
+```
+
+This builds a synthetic repository with about 3,700 commits and a known true effect for each agent, then runs the whole pipeline and writes an HTML report. You'll see the naive comparison blame the wrong agent and the causal estimate recover the truth. A copy of the output is in [examples/demo-report.html](examples/demo-report.html).
+
+```bash
+python -m ledger audit --repo path/to/repo --html audit.html
+```
+
+This gives a day-one baseline from git history alone: revert and fix rates per tool, detected from commit trailers and bot authors (Claude Code, Copilot, Cursor, Devin, Jules, Codex, Aider, OpenHands). It is **correlational**, and the output says so. See [examples/manifold-audit.html](examples/manifold-audit.html) for a run on a real open-source repo.
+
+## Using it on a real repo
+
+```bash
+python -m ledger init                                   # create .ledger/ and install the commit hook
+python -m ledger decide --arms claude-code,codex,cursor \
+    --scores 1.0,0.6,0.4 --epsilon 0.4 \
+    --context '{"stratum": "bugfix"}'                   # prints which tool to use for this task
+# ... do the task with that tool; commits on this branch are tagged "Ledger-Decision-Id: <id>" automatically
+python -m ledger done                                   # stop tagging on this branch (--all: every branch)
+python -m ledger attach --decision <id> --commit <sha>  # if a squash merge dropped the trailer
+
+# optional: production incidents and deploys exported from Sentry, PagerDuty, incident.io …
+python -m ledger import incidents --file incidents.csv  # id, started_at, title, commits, files
+python -m ledger import deploys --file deploys.csv      # sha, deployed_at
+
+# or pull incidents live (read-only key in an environment variable, never an argument)
+python -m ledger sync sentry --org your-org-slug --days 90      # needs SENTRY_AUTH_TOKEN
+python -m ledger sync pagerduty --days 90                       # needs PAGERDUTY_API_KEY
+
+# before you start, and any time you wonder if something is stuck
+python -m ledger plan --base-rate 0.12 --effect -0.03           # how many finished decisions you need
+python -m ledger status                                         # gaps that would mislead an estimate
+
+# a week in: an early readout; weeks later: the real one
+python -m ledger label --fix-style keywords             # reverts, fixes and incidents within 30 days
+python -m ledger estimate                               # causal estimates with 95% CIs
+python -m ledger report                                 # .ledger/report.html
+
+# once you have a few hundred finished decisions
+python -m ledger breakdown --stratum difficulty         # which tool suits which kind of task
+python -m ledger recommend --stratum difficulty         # and what routing by that is honestly worth
+```
+
+| Command | What it does |
+|---|---|
+| `init` | Creates `.ledger/` (self-ignored by git) and installs a `prepare-commit-msg` hook. It won't overwrite a hook you already have, and re-running it upgrades an older ledger hook. |
+| `decide` | Chooses an arm at random with `p = (1-ε)·softmax(score/τ) + ε/k` and logs every arm's probability. The decision is active on the branch you are on, so several agents can work on several branches or git worktrees at once without sharing a decision. All worktrees and subfolders use one ledger at the repository root. |
+| `sync sentry` / `sync pagerduty` | Pull error-level Sentry issues or high-urgency PagerDuty incidents as incidents. Keys come only from `SENTRY_AUTH_TOKEN` / `PAGERDUTY_API_KEY` and are never printed, even in errors. Neither API names the commit that caused an incident, so these carry timing only: link them with an export that names commits, or `--incident-linking`. Re-syncing never erases links from an earlier export. |
+| `plan` | Simulates your routing and tells you how many finished decisions give 80% power, both for one look and for checking repeatedly. |
+| `status` | Flags what would mislead an estimate: decisions with no commit, stale labels, near-zero routing chances, one-arm ledgers, incidents that can't be linked. |
+| `import` | Loads incident or deploy exports (CSV or JSON, common field names accepted). |
+| `label` | Maps commits to decisions and finds reverts, fixes (SZZ via `git blame`) and linked incidents. A decision counts only once its whole window has passed; a separate early label (`--early-days 7`) feeds the early readout. |
+| `estimate` | Naive, IPW, self-normalised IPW, direct method and doubly robust estimates per arm. Bootstrap and influence-function CIs, effective sample size, minimum propensity, and a check that unmerged work is balanced across arms. `--cluster developer` resamples whole clusters when outcomes are correlated. |
+| `breakdown` | Which tool is better for which kind of task (`--stratum difficulty`). Raw and shrunk effects per stratum with Bonferroni-adjusted p-values, so a lucky stratum is not mistaken for a pattern. |
+| `recommend` | What routing each task type to its best tool would be worth. The tool is chosen on one half of your decisions and judged on the other, so the gain is not inflated; it also shows the gain from simply using the best tool. |
+| `report` | A self-contained HTML report (light and dark). |
+| `audit` | Per-tool baseline from history, with Wilson CIs and size-adjusted rates. |
+| `demo` | Synthetic end-to-end run that checks labels against an oracle. |
+
+Useful options:
+- `--fix-style keywords` for repos that write "Fix crash in …" rather than `fix: …`
+- `--fix-regex` for anything else
+- `--ignore-revs .git-blame-ignore-revs` to see through formatting commits
+- `--horizon 30`, `--as-of 2026-06-30`, `--baseline <arm>`, `--clip 20`
+- `--cluster developer` (any context key) for cluster-robust intervals
+- `--stratum difficulty,language` to model outcomes per combination of context keys
+- `--incident-linking latest|window` to also link incidents that name no suspect commit (off by default; see below)
+- `--planned-n 4000` sets the sample size the anytime-valid interval is tuned for. Choose it before you start.
+- `--folds 5` cross-fits the outcome model (0 turns it off). It matters when strata are many and small: in
+  simulation the interval covered the truth 87.7% of the time without it and 95.3% with it.
+
+**Checking every week?** Ordinary 95% intervals don't hold up to repeated looks: in simulation, 16 weekly checks under a true null "found" a winner 30% of the time. Each verdict therefore also says whether it survives the anytime-valid confidence sequence (Waudby-Smith et al., *Annals of Statistics* 2024), which kept that rate at 3%.
+
+The report warns when:
+- one arm's work goes unmerged more often (a chi-square test), since that biases the merged-only comparison
+- an arm had a near-zero chance of being picked for some tasks
+- an arm's effective sample size is small
+
+## How it decides "bad"
+
+A change is bad if, within the horizon after its first commit:
+- it is **reverted**: git's `This reverts commit <sha>`, or a squash-merged GitHub `Revert "<subject>"` PR, or
+- a **fix commit** changes lines it introduced (SZZ), or names its PR ("Bug introduced in #1507", "regression from #88"), or
+- a **production incident** names it as a suspect commit.
+
+Incidents that name only files are left unlinked by default. In testing, blaming "the latest deploy that touched those files" found the true culprit only 14% of the time, because files change often. A missed incident can only shrink a difference between tools; a wrongly blamed one adds noise. Export suspect commits where your tooling has them (Sentry does).
+
+**Early readout.** `estimate` also reports differences on a 7-day label, which includes recent decisions the main estimate must exclude. Next to it, the report shows how 7-day and 30-day differences compared on decisions old enough to have both. In the demo only 20% of bad outcomes surfaced within a week, and one tool's early difference pointed the wrong way. Treat the early readout as a hint until that comparison says otherwise.
+
+The SZZ step includes the standard refinements against false positives. Each one mattered on real data:
+- ignore whitespace-only edits (`-w`), and blank or comment-only lines
+- ignore lines that were moved rather than changed
+- skip tests, docs, editor and CI config, and lockfiles
+- never treat a merge commit as a fix, even one titled "Merge pull request … from me/fix-crash"
+- ignore a fix that blames more than 10 commits (`--max-blamed`, 0 to keep all): the research found such fixes are outliers, and cutting them raised precision
+- optionally look through listed formatting commits
+
+**Squash merges.** GitHub's squash merge drops the `Ledger-Decision-Id` trailer, which would make merged work look abandoned. `label` recovers these automatically: it fingerprints the branch's combined diff (`git patch-id --stable`) and looks for a commit on your branch with the same fingerprint. It only accepts a unique match that is newer than the branch's first commit, never guesses, and reports `squash_recovered`. It needs the branch's commits to still exist locally (a branch, a remote-tracking ref, or the reflog); `ledger attach` covers anything else.
+
+Fix analysis is remembered in the ledger, so re-running `label` is near-instant: the same repository went from 46 seconds to under a tenth of a second.
+
+## What we learned
+
+Full details are in [research/FINDINGS.md](research/FINDINGS.md):
+- Doubly-robust estimates are unbiased (< 0.1 pp) with 93.5–95% bootstrap CI coverage. Naive comparisons were off by up to 7 pp and picked the wrong winner.
+- Re-checking weekly with ordinary CIs gives a **30% false-positive rate**. The anytime-valid sequence gives 3%.
+- How much data you need depends on your routing. A 3 pp difference needed about 8,000 mature decisions when routing was lopsided (the demo, ε = 0.1) but about 4,000 with near 50/50 routing, or about 8,000 if you also want it safe to check repeatedly. Run `ledger plan` with your own numbers.
+- Label noise inflates levels but mostly leaves differences between arms alone. Missed bugs only shrink effects. Report differences.
+- On elalish/manifold, Claude Code commits looked worse raw (11.3% vs 7.5%) and about the same size-adjusted (7.1% vs 8.1%). The CIs overlap, which is the case for randomizing.
+
+## Documentation
+
+- [docs/METHODOLOGY.md](docs/METHODOLOGY.md): exactly what is computed, the assumptions it needs, and what it cannot tell you
+- [research/FINDINGS.md](research/FINDINGS.md): simulation studies and real-repository results
+- [CHANGELOG.md](CHANGELOG.md), [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md)
+
+## Layout
+
+```
+ledger/          the package: policy (routing), label + squash (outcomes), estimate, audit, plan, status,
+                 incidents + sentry + pagerduty, report, demo, db, gitio, cli
+tests/           230 unittest cases: real git repos in temp dirs, local fake servers, estimator Monte Carlo checks
+tools/           coverage_lite.py, dependency-free line coverage
+docs/            METHODOLOGY.md
+research/        simulate.py (coverage, power, noise, design, peeking studies), results/, FINDINGS.md
+examples/        generated demo report and the manifold audit
+```
+
+Run the tests:
+
+```bash
+python -m unittest discover -s tests
+```
+
+## Limits (honest list)
+
+- Sentry and PagerDuty can be synced live, but the syncs were only tested against fake servers and (for Sentry) an empty account; others need exports. Customer impact (tickets, churn) isn't linked.
+- The outcome model for DR is a per-stratum mean. Many context keys at once need a real model with cross-fitting.
+- The early readout is a plain shorter window, not a calibrated surrogate index.
+- Audit mode is observational. It describes; it does not prove.
+- Python 3.9+ and git 2.28+.

consequence_ledger-0.3.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+consequence_ledger-0.3.0.dist-info/licenses/LICENSE,sha256=1lhJHdAJxo3B2z9l2KvKj6DLRXalmiELd5S_MrlW7eI,1068
+ledger/__init__.py,sha256=IYhnUw-2ec9okTh6GjUpkWAtLikQOHVDK3bAHaJMIZY,97
+ledger/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30
+ledger/audit.py,sha256=QBQQzyTL6cqZIWVd2Wt4QvTf4ohn-rbG2J4SBmygwyI,8594
+ledger/cli.py,sha256=P8Orum30XdXOh5xH7SvXqrEgWBX07qYU1PKnV1LmVrM,32543
+ledger/db.py,sha256=ddY_bfHUnXI9Vd0t8nd5kcuorHCRYv7gmLs1awinwSU,2874
+ledger/demo.py,sha256=9doGAgvEdnA2TRy-4CF42ZsQLtbNGHGIoqma4_NFdBA,13663
+ledger/estimate.py,sha256=hOOxmkrsvYHxamGHn3tq9wpwHJNhU5weGVvpXKHcaJo,17809
+ledger/gitio.py,sha256=ix5jWWSbBAGHR0GT_QoH4jehPCfrl2VtlSwx7zkMkow,3946
+ledger/incidents.py,sha256=iDZR450x9v-8S020zT2u7aG5SQ7Q4z4KdOTfdXy7vg4,8433
+ledger/label.py,sha256=b9rXveX2LsQOpvl5K3-iYQwhHENzT6SMKzrabXZmr8E,18135
+ledger/pagerduty.py,sha256=K7LLuhN_aUxn3jV0bdFbj0k9OYnEjTYk3YdYiuRZ1eQ,4294
+ledger/plan.py,sha256=Y-DgVJ5XL9IBmClRJsNomG6K7u_xpQNVO7F3WV0oCd0,2922
+ledger/policy.py,sha256=f8HvrS3KJgIfPhdifD6WHpmLE3qyrPyw1f4uVKyz_5k,2109
+ledger/report.py,sha256=EBph-J7oKU6ZdMOCuURheMw434K35h99_Pif3Px9aFs,20938
+ledger/segments.py,sha256=wGr98sP5vBSL_LJrMQphV8LZTnYeRc-Pkhn5-RQFQHk,6766
+ledger/sentry.py,sha256=UGWldoC2fTgAqqXxK8e4ag6N3aIg_YhnZrweMCHYvQU,3884
+ledger/squash.py,sha256=kzKkNHHXgtbwslQ8BGdh01ypGtcMctZCmdQNf7IYNkE,4231
+ledger/status.py,sha256=QwduB9ekijadNTygPIuozj88dvBnhfpofMl3It-2S6c,3352
+consequence_ledger-0.3.0.dist-info/METADATA,sha256=vBU7whqfE6-jekCjSjHjkKL2suzCFM747nYLvgmdZT0,14236
+consequence_ledger-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+consequence_ledger-0.3.0.dist-info/entry_points.txt,sha256=MMH2iMSp-kYEpL7AAmFfUgDn4iRIgkF-Pd04uPvAFOw,43
+consequence_ledger-0.3.0.dist-info/top_level.txt,sha256=m7uk8iJxEERz_eg6MUtQ-DR9EFBsRR3PmqxMKlSXm_I,7
+consequence_ledger-0.3.0.dist-info/RECORD,,

consequence_ledger-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

consequence_ledger-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ledger = ledger.cli:main

consequence_ledger-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sujan-mitta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

consequence_ledger-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ledger

ledger/__init__.py

@@ -0,0 +1,2 @@
+"""Consequence Ledger: measure what AI coding decisions actually cause."""
+__version__ = "0.3.0"

ledger/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()

ledger/audit.py

@@ -0,0 +1,187 @@
+"""Baseline audit: how often each tool's commits get reverted or fixed, from history alone.
+
+No randomisation, so this is correlational: tools are used on different kinds
+of work. It is what a team can learn on day one, before `decide` has logged
+any propensities, and it shows which comparisons are worth randomising.
+Size-adjusted rates (direct standardisation over commit-size bands) remove
+one obvious confounder; they cannot remove the rest.
+"""
+import math
+import re
+import time
+from collections import defaultdict
+
+from .gitio import GitError, git, lines_changed, log_commits
+from .label import DAY, DEFAULT_MAX_BLAMED, FIX_RE, first_bad, is_fix, outcome_events
+
+TRAILER_RE = re.compile(r"(?im)^co-authored-by:\s*(.+)$")
+AUTHOR_EMAIL_RE = re.compile(r"<([^>]*)>\s*$")
+
+# (tool, scope, pattern). Trailer patterns run on each Co-authored-by value on its own, so a commit
+# that merely *mentions* Claude in its body is not an AI commit. Email patterns use bot-specific
+# addresses so a human called Devin is not misclassified; GitHub bot addresses carry an "<id>+" prefix.
+# First match wins.
+RULES = [
+    ("claude-code", "message", r"Generated with \[?Claude Code"),
+    ("claude-code", "trailer", r"\bclaude\b|@anthropic\.com"),
+    ("devin", "email", r"^(\d+\+)?devin-ai-integration(\[bot\])?@"),
+    ("devin", "trailer", r"\bdevin-ai-integration\b|@devin\.ai\b"),
+    ("jules", "email", r"^(\d+\+)?google-labs-jules(\[bot\])?@"),
+    ("copilot", "email", r"^(\d+\+)?copilot@users\.noreply\.github\.com$|^(\d+\+)?copilot-swe-agent(\[bot\])?@"),
+    ("copilot", "trailer", r"\bcopilot\b"),
+    ("cursor", "email", r"^cursoragent@cursor\.com$"),
+    ("cursor", "trailer", r"@cursor\.(sh|com)\b|\bcursor( agent)?\b(?!-)"),
+    ("codex", "email", r"chatgpt-codex-connector"),
+    ("codex", "trailer", r"\bcodex\b|@openai\.com\b"),
+    ("gemini", "email", r"gemini-code-assist"),
+    ("gemini", "trailer", r"^gemini\b[^<]*<[^>]*(google|gemini)"),
+    ("aider", "trailer", r"\baider\b"),
+    ("aider", "author", r"\(aider\)\s*<"),
+    ("openhands", "email", r"^openhands@all-hands\.dev$"),
+    ("openhands", "trailer", r"\bopenhands\b"),
+]
+# Files that show a tool is set up in a repository even when its commits carry no signature. A 2026 census of
+# 180 million repositories found author-bot lookups recover only 3% of Claude Code commits, and only 64% of
+# repositories with Claude config files also had a signed commit, so the audit would otherwise undercount.
+CONFIG_FILES = [
+    ("claude-code", r"^CLAUDE\.md$|^\.claude/"),
+    ("gemini", r"^GEMINI\.md$"),
+    ("cursor", r"^\.cursorrules$|^\.cursor/"),
+    ("copilot", r"^\.github/copilot-instructions\.md$"),
+    ("aider", r"^\.aider\.conf\.yml$"),
+    ("windsurf", r"^\.windsurfrules$"),
+    ("devin", r"^\.devin\.yaml$"),
+    ("junie", r"^\.junie/"),
+    ("openhands", r"^\.openhands/"),
+    ("agents.md", r"^AGENTS\.md$"),   # read by Codex and several other tools, so it names no single one
+]
+SIZE_BANDS = [(0, 20, "1-20"), (21, 200, "21-200"), (201, float("inf"), "200+")]
+
+
+def compile_rules(extra=()):
+    """extra: ["tool=regex", ...] matched against the whole message, checked before the built-ins."""
+    rules = []
+    for spec in extra:
+        tool, _, pattern = spec.partition("=")
+        if not tool or not pattern:
+            raise ValueError(f"rule must look like tool=regex, got {spec!r}")
+        rules.append((tool.strip(), "message", re.compile(pattern, re.I | re.M)))
+    rules += [(t, s, re.compile(p, re.I | re.M)) for t, s, p in RULES]
+    return rules
+
+
+def classify(commit, rules):
+    trailers = [v.strip() for v in TRAILER_RE.findall(commit["body"])]
+    m = AUTHOR_EMAIL_RE.search(commit.get("author", ""))
+    email = m.group(1) if m else ""
+    for tool, scope, rx in rules:
+        if scope == "message" and rx.search(commit["body"]):
+            return tool
+        if scope == "trailer" and any(rx.search(t) for t in trailers):
+            return tool
+        if scope == "email" and rx.search(email):
+            return tool
+        if scope == "author" and rx.search(commit.get("author", "")):
+            return tool
+    return "human"
+
+
+def wilson(k, n, z=1.959964):
+    if n == 0:
+        return float("nan"), float("nan")
+    p = k / n
+    centre = (p + z * z / (2 * n)) / (1 + z * z / n)
+    half = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / (1 + z * z / n)
+    return max(0.0, centre - half), min(1.0, centre + half)
+
+
+def band(size):
+    return next(name for lo, hi, name in SIZE_BANDS if lo <= size <= hi)
+
+
+def detect_adoption(repo, rev="HEAD"):
+    """{tool: [config files]} present in the tree at rev; empty if the tree cannot be listed."""
+    try:
+        names = git(repo, "ls-tree", "-r", "--name-only", rev).splitlines()
+    except GitError:
+        return {}
+    found = {}
+    for tool, pattern in CONFIG_FILES:
+        rx = re.compile(pattern)
+        hits = [n for n in names if rx.search(n)]
+        if hits:
+            found[tool] = hits[:5]
+    return found
+
+
+def detection_notes(adoption, tools, mature):
+    """Plain-language warnings where config files say a tool is in use but its commits are barely, or not, detected."""
+    notes = []
+    for tool, files in adoption.items():
+        if tool == "agents.md":
+            continue
+        tagged = tools.get(tool, {}).get("commits", 0)
+        if tagged == 0 or (mature and tagged / mature < 0.01):
+            what = "no commit" if tagged == 0 else f"only {tagged} of {mature} commits"
+            notes.append(f"{files[0]} is in the repository but {what} is signed as {tool}. Its commit signature may "
+                         f"be switched off, so some of its work is probably counted under 'human'. Compare with "
+                         f"`--rule '{tool}=<regex>'` if you know another marker.")
+    return notes
+
+
+def audit(repo, horizon_days=30, as_of=None, since=None, rev="HEAD", rules=None, ignore_revs=(), fix_re=FIX_RE,
+          max_blamed=DEFAULT_MAX_BLAMED):
+    as_of = int(as_of if as_of is not None else time.time())
+    rules = rules or compile_rules()
+    commits = log_commits(repo, rev)
+    sizes = lines_changed(repo, rev)
+    horizon = horizon_days * DAY
+
+    targets = {}
+    for c in commits:
+        if len(c["parents"]) > 1 or c["sha"] not in sizes or sizes[c["sha"]] == 0:
+            continue  # merges and empty commits
+        if since and c["ts"] < since:
+            continue
+        if c["ts"] + horizon > as_of:
+            continue  # immature: its window hasn't closed
+        targets[c["sha"]] = classify(c, rules)
+    by_sha = {c["sha"]: c for c in commits}
+    szz_stats = {}
+    events = outcome_events(repo, commits, set(targets), ignore_revs, fix_re, stats=szz_stats, max_blamed=max_blamed)
+
+    groups = defaultdict(lambda: {"n": 0, "revert": 0, "fix": 0, "bands": defaultdict(lambda: [0, 0])})
+    band_totals = defaultdict(int)
+    for sha, tool in targets.items():
+        g = groups[tool]
+        hit = first_bad(events, [sha], by_sha[sha]["ts"], horizon)
+        b = band(sizes[sha])
+        g["n"] += 1
+        g["bands"][b][1] += 1
+        band_totals[b] += 1
+        if hit:
+            g[hit[1]] += 1
+            g["bands"][b][0] += 1
+
+    total = sum(band_totals.values())
+    tools = {}
+    for tool, g in sorted(groups.items(), key=lambda kv: -kv[1]["n"]):
+        bad = g["revert"] + g["fix"]
+        lo, hi = wilson(bad, g["n"])
+        # Direct standardisation: this tool's per-band rates applied to the repo-wide size mix.
+        covered = [b for b in band_totals if g["bands"][b][1] > 0]
+        weight = sum(band_totals[b] for b in covered)
+        adjusted = (sum(band_totals[b] * g["bands"][b][0] / g["bands"][b][1] for b in covered) / weight
+                    if weight else float("nan"))
+        tools[tool] = {
+            "commits": g["n"], "reverted": g["revert"], "fixed": g["fix"],
+            "bad_rate": bad / g["n"], "ci_lo": lo, "ci_hi": hi,
+            "size_adjusted_rate": adjusted,
+            "size_bands": {b: {"bad": v[0], "n": v[1]} for b, v in sorted(g["bands"].items())},
+            "band_coverage": weight / total if total else 0.0,
+        }
+    adoption = detect_adoption(repo, rev)
+    return {"horizon_days": horizon_days, "as_of": as_of, "since": since, "commits_scanned": len(commits),
+            "mature_commits": len(targets), "fix_commits": sum(is_fix(c, fix_re) for c in commits),
+            "fixes_too_diffuse": szz_stats.get("fixes_too_diffuse", 0), "size_mix": dict(band_totals), "tools": tools,
+            "adoption": adoption, "detection_notes": detection_notes(adoption, tools, len(targets))}