Metadata-Version: 2.4
Name: commensa-audit
Version: 0.3.1
Summary: Earlier public Commensa git-audit snapshot; current Report and Cockpit at commensa.ai/visibility.
Author: Matt Buscher
License: MIT License
        
        Copyright (c) 2026 Matt Buscher
        
        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.
        
Project-URL: Product, https://commensa.ai/visibility
Project-URL: Documentation, https://commensa.ai/docs
Project-URL: Company, https://commensa.ai/
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: jinja2>=3.1
Dynamic: license-file

# commensa-audit

> **Current status:** This package is an earlier public snapshot of the
> deterministic git-audit method behind today's **Commensa Report**. Version
> 0.3.1 clarifies the product identity and public links; it does not contain the
> current private Commensa engine, Cockpit, Commensa Manager, Project X-Ray, or
> other licensed capabilities.

The current product is [Commensa Report + Cockpit](https://commensa.ai/visibility).
See the [current documentation](https://commensa.ai/docs) for supported
installation, terminology, capabilities, privacy boundaries, and purchasing.

`commensa-audit` reads GitHub pull-request history and produces a local,
self-contained snapshot containing:

- corrective share by pull request and changed line;
- superseded merged work;
- attempts closed without merging;
- chains of pull requests rewriting earlier work;
- line survival;
- corrective hotspots by module; and
- a lower-bound count of explicit coding-agent markers.

The current product calls the corrective share of changed lines the
**Commensa Drift Index**. This historical package predates parts of the current
vocabulary, evidence model, local-clone workflow, and product architecture.

## Install & run

```
pip install commensa-audit
commensa-audit --repo owner/name --token $GH_TOKEN
```

Output: `report_<repo>.html` (self-contained, forwardable), `audit_<repo>.json` (raw numbers), `units.csv` (per-PR data).

### Scoping large repos

By default the audit covers the **newest 500 PRs** — a safety cap so a naive run on a huge repo stays fast and bounded. When it truncates, the run prints a notice telling you how to raise it. Two optional flags control the window (both newest-first):

```
commensa-audit --repo frappe/erpnext --since 2026-03-14 --max-prs 150
```

- `--since YYYY-MM-DD` — only PRs created on/after this UTC date
- `--max-prs N` — cap to the N newest PRs (default `500`; use `--max-prs 0` for no cap)

Both early-stop pagination, so `--max-prs 150` costs ~150 PRs' worth of API calls, not the repo's entire history. Run with no flags on a repo under 500 PRs and you get everything, exactly as before.

## Privacy boundary of this snapshot

- **Read-only.** GET requests only; a token with read scope is sufficient.
- **Local output.** Reports are generated on your machine. The package sends no
  telemetry to Commensa; repository mode calls GitHub's API with the token and
  repository name you provide.
- **Inspectable distribution.** The published wheel and source distribution
  contain the snapshot's Python source and its declared dependencies.

## How classification works (and its honest limits)

Every PR is classified by a transparent signal cascade — explicit corrective titles/reverts → self-correction (a PR predominantly undoing lines added in the prior N days) → churn-cluster membership → otherwise generative. Every classification in the output carries the signal that fired and a human-readable why. Thresholds live in one config block; tune them and re-run offline with `--reuse`.

Known limits (also printed in the report footer): classification is heuristic; squash merges blur attribution; survival windows mean young repos read optimistic; agent-marked share is a lower bound — absence of a marker is not evidence of human authorship. We grade our own certainty rather than fake precision — that's the whole point of the project.

## Where this fits now

Commensa is the management system for AI. Report and Cockpit give the
accountable person evidence and visibility for understanding AI-assisted work.
Commensa Manager is a separate product that carries human management practice
into AI delegation. This historical package is part of the Report lineage; it
is not Commensa Manager and does not represent the complete current product
system.

- [Report + Cockpit](https://commensa.ai/visibility)
- [Commensa product system](https://commensa.ai/products)
- [Documentation](https://commensa.ai/docs)
- [Commensa](https://commensa.ai/)

**measure the durable work, not the noise.**

MIT licensed.
