Metadata-Version: 2.4
Name: govern-kit
Version: 0.1.0
Summary: Governed maintenance automerge for any repo, any agent: receipts with re-runnable evidence, a measured-only calibration ledger, graduated per-class autonomy gates, signed rows, and a kill switch.
License: MIT
Project-URL: Homepage, https://signalbrain.ai
Project-URL: Source, https://github.com/whitestone1121-web/golf-student-16mb
Keywords: ai-governance,change-control,calibration,automerge,receipts,audit
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# govern — the missing layer, installable

Every AI coding agent ships code and asks you to trust it. `govern` makes the
trust measurable instead: **receipts with re-runnable evidence, a measured-only
calibration ledger, graduated per-class autonomy gates, and a kill switch** —
in any repo, with any agent (Claude Code, Cursor, Codex, humans). Stdlib-only
Python, no model, no cloud, nothing to phone home to.

Extracted from the production loop that governs the Titan repository, where
the same arithmetic earned three change classes automerge eligibility on
measured track record. The extraction is pinned byte-identical to the source
by a parity contract run in CI against the live 130+-row ledger.

## Install

```bash
pip install ./packages/govern     # or pipx install govern-kit
govern init                       # idempotent; never overwrites existing files
```

`init` drops: `.govern.toml` (conventions), a receipt template (the evidence
contract), an empty measured ledger, a CI workflow (gate as a PR check,
score-on-merge), and the `GOVERN_STOP` kill-switch doc.

## The loop

1. A change ships with a **receipt**: what changed, the claimed verdict, a
   confidence, and a `### How measured` block of hermetic commands.
2. After the receipt is **human-merged** (`govern check-merged` refuses
   working-tree or doctored copies), `govern score` re-runs the evidence
   verbatim against merged main and appends a `scored_by="measured"` row.
   Self-reported verdicts can never move the measured ledger.
3. `govern gate` computes TRUST/GATE overall and per change class: a class
   earns `auto-merge ELIGIBLE` only at ≥95% high-confidence hit-rate over a
   ≥10-claim recency window — judged per class, so one class's burst cannot
   evict another's track record.
4. `touch GOVERN_STOP` halts every gated automation instantly. The gate
   refusing while that file exists is the contract.

## Anti-gaming invariants (all inherited from production incidents)

- **Merged-only scoring** — no credit for work that never survived review.
- **Content-hash guard** — the scored receipt must be byte-identical to the
  merged one.
- **Invariant-pin exclusion** — a receipt measured only by tests its own PR
  introduced is a tautology: recorded, flagged, never counted toward TRUST.
- **In-place rescores** — rewriting a row preserves ledger order so the
  recency window cannot be gamed by remove-and-append.
- **Sticky pins** — automated rescores can never un-pin an adjudicated row.
- **Goodhart markers** — excluded receipts are dropped before windowing.

## Signature layers, honestly described

- **HMAC (`sig`)** — proves the ledger wasn't edited by anyone without the
  key. The key-holder is still you: this convinces your own CI, not an
  auditor at arm's length.
- **SSH (`ssh_sig`)** — anyone verifies rows against the public key you
  publish in `.govern/allowed_signers`, using stock `ssh-keygen`. Backdating
  detection relies on the ledger living in public git history; the signature
  alone proves authorship and integrity, not time.

## What this package is — and is not

This package is the **trust layer**: it scores receipts, keeps the measured
ledger, and computes graduated-autonomy gates. It contains no agent, no
model, and no execution engine. SignalBrain Forge runs governed change
control as a product; the Titan runtime that earned this kit's reference
track record is private. Installing `govern-kit` gives you the referee —
what you build on top of it is yours.

## Commands

```bash
govern score docs/improvements/0001-fix.md   # or --all, or --rescore
govern gate                                  # exit 0 = TRUST
govern gate --class bugfix                   # exit 0 = that class is ELIGIBLE
govern status                                # one-screen scoreboard
govern check-merged <receipt>                # Track-1 guard, exit 0 = scoreable
govern init                                  # install into this repo
```
