govrail
English | 中文
A language-agnostic governance plane for agent-driven development: coding agents work fast in parallel while machines — not vigilance — hold the quality line. The only runtime dependency is Python 3.
The plane ships two mechanisms: gates (any promise a command can check becomes a mechanical check) and notes (every non-trivial change records the decision, what it beat, and the consequences). Bilingual pairing keeps the external-presentation docs in sync.
What it changes
| Without govrail | With govrail |
|---|---|
| Agents follow rules "on their honor"; nothing is enforced | Every checkable promise is a gate that fails loud |
| "Why did we do this?" is lost or re-litigated | Each decision is a note with the alternatives it beat |
| Adopting tooling means a restructure or a new runtime | One command, zero restructure: gov init |
See a governed project in examples/demo-project — a living specimen exercising every feature (rubric, rejection cases, surfaces, decisions). Task-oriented recipes: docs/cookbook.md.
Install
pip install govrail # or: uv tool install govrail / pipx install govrail
This puts the gov CLI on your PATH (stdlib only — no third-party
dependencies). It has one subcommand per action:
gov init --project <path> # inject the plane into an existing project
gov init --project <path> --upgrade # show template drift (diffs, never writes)
gov init --project <path> --adopt all # land missing template files (never overwrites)
gov init --project <path> --adopt-new gates.json # merge new shipped gates into a customized gates.json
gov doctor # environment self-check (PATH, python, hooks, schema)
gov note new --class process --ref D6 "Title" # scaffold a note, pre-validated
gov init --project <path> --hooks --ci # also install a pre-push hook and CI
gov uninstall --project <path> # reverse it exactly
gov run # run the default mode's gate DAG (defaultMode)
gov run --base HEAD~1 # only the gates whose paths match the diff
gov run --gate pairing # rerun a single gate
gov self-test # rejection cases: the tools' + yours (.gov/rejections/)
gov run --json # machine-readable: [{gate, outcome, duration_ms, ...}]
gov verify-pairing --write # re-confirm a bilingual pair after editing one side
gov verify-pairing --write en:docs/a.md zh:docs/a_CN.md # register any naming
gov verify-note-presence # warn when a non-trivial diff carries no Agent Note
gov verify-rubric # check the review rubric's structure
gov verify-decisions # guard the decisions table (ids, alternatives)
gov verify-conflict-markers # fail when changed files carry git conflict markers
gov review --base <ref> --grade # dossier + interactive rubric grading
gov trend # gate duration trends from --record history
gov recall <terms> # retrieve notes, decisions, postmortems
gov audit-notes # staleness signals in implemented notes
gov change-scope --base <ref> # smallest sufficient set (.gov/surfaces.json maps paths)
init is non-invasive and idempotent: it creates .gov/rules.md, adds
gates.json, the notes README, and the agent skills (recall-first,
pre-push-checks, code-review, archive-agent-notes) only when missing,
appends one reference line to AGENTS.md, and never overwrites the
project's own files — including its own skills. --hooks/--ci can be
retrofitted later (gov init --hooks on an initialized project installs
just the add-on; customizations stay untouched). uninstall reverses
everything exactly; when a file drifted from its template it names the
file and requires --force to proceed (a genuine two-step). A fresh
install never goes red on its first run: the pairing gate ships advisory,
gov verify-pairing --write baselines the existing pairs, and removing
allowFailure turns it enforcing. enabled: false parks a gate without
deleting its definition.
What is inside
gov/— the Python package:gates(the DAG runner overgates.json),verify_notes(three required sections),verify_translation_pairing(git blob hashes),verify_note_presence,verify_rubric,recall(memory retrieval),audit_notes(staleness signals),change_scope,self_test,archive_notes.gov/templates/— the rules, defaultgates.json, notes format, and agent skills thatgov initinjects into a project..gov/rules.md— the single source of truth for the rules..agents/notes/— the decision-record format and lifecycle..agents/skills/— the triggers that send agents to the tools first:recall-first(memory before proposals),pre-push-checks(smallest sufficient set),code-review(rubric),archive-agent-notes.docs/review-rubric.md— how PRs are judged: the criteria gates cannot check, graded item by item.
Origin
The mechanisms are distilled from the DeepSeek Harness repository, whose gates-over-prose axiom shaped this template. Kept: the governance plane. Left to you: the product plane. The locked design decisions live in docs/decisions.md.
Star History
1 maintainer
Release files for govrail 0.16.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| govrail-0.16.0.tar.gz | 106.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| govrail-0.16.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 201.4 kB
Release files / govrail-0.16.0.tar.gz
| Download URL | govrail-0.16.0.tar.gz |
|---|---|
| Size | 106.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b5005d42da9a389c061549ea059d36134efe85342499af20d04a9f3b194587bc
|
|
BLAKE2b-256 checksum How to use checksums |
7c94558fcb5cacd903cc7bb7e39de97d9718751f79c10ba1b5ddee8ed5c32aa1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / govrail-0.16.0-py3-none-any.whl
| Download URL | govrail-0.16.0-py3-none-any.whl |
|---|---|
| Size | 95.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55fc8885559461e04b1edd4d2da276a274ab914691d68dab06534d71f9936ddb
|
|
BLAKE2b-256 checksum How to use checksums |
73c0c94b46277fd1b792484c8d3998740caa4b63f66affcc3f0a46c96112d1b3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
