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 runtime is Python 3 (>= 3.10) plus the tree-sitter parsers that
power the code-stat layer — all installed by pip install govrail, no
other tooling required.
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
On a lagging pip mirror the wheel can be missing while pip index versions
already lists it (the JSON API updates before the simple index). Install
from the official index then: pip install govrail --index-url https://pypi.org/simple.
This puts the gov CLI on your PATH (Python + tree-sitter, nothing
else). 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 preset list # shipped presets (D53): agent-heavy, python-lib,
# docs-bilingual — typed adoption bundles
gov preset show python-lib # read-only: exactly what a preset lands
gov preset apply docs-bilingual --project <path> # land its gates + skills + hints,
# additive and idempotent (never overwrites)
gov init --project <path> --preset agent-heavy # init, then apply the preset in one command
gov doctor # environment self-check (PATH, python, parse layer, hooks, schema, unadopted gates)
gov doctor --json # machine-readable: {status, checks, problems}
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 --merge a b --base origin/master # preflight the union of parallel branches:
# merge each into a scratch worktree, gates run on every
# step's tree; conflict or red step keeps the scene (D51)
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, detail,
# selected_by, scoped_out, ...}] — the whole gate set, incl. scoped-out
gov verify-pairing --write # re-confirm a bilingual pair after editing one side
# (names the field values it wrote; the record's
# comments state the field semantics — #150)
gov verify-pairing --write en:docs/a.md zh:docs/a_CN.md # register any naming
gov verify-pairing --explain # the record schema + conventions, read-only
gov verify-note-presence # warn when a non-trivial diff carries no Agent Note
# (task receipts exempt; manifest note_presence_exempt names more)
gov verify-rubric # check the review rubric's structure
gov verify-decisions # guard the decisions table (ids, alternatives)
gov verify-decisions --base <ref> # + parallel-branch number collisions
gov verify-decisions --json # machine-readable: {violations, orphans, overdue, ...}
gov decision next --base <ref> # next free D-number (branch-aware; warns on a stale base)
gov decision add --from FILE # append a decision, validated + atomic (--against = --base)
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 stats # structural facts per language (lines, symbols, nesting depth) — facts, not verdicts
gov check # syntax-class checks over the parse layer; suppressions counted, never invisible
gov receipt verify <commit> # was a full green run recorded on this tree? (#124)
gov recall <terms> # retrieve notes, decisions, postmortems (--any relaxes the AND)
gov audit-notes # staleness signals in implemented notes
gov audit-notes --json # machine-readable: {findings: [{file, signal}], ...}
gov change-scope --base <ref> # smallest sufficient set (.gov/surfaces.json maps paths)
gov task new "Title" --check "criterion" # task card: one-line rules@<hash> pin for a subagent brief
gov task check # after a rules adoption: name the stale cards
gov task claim T-0001 --agent w1 --ttl 20m # lease an open card for one worker
# (two workers cannot take one; busy → exit 3)
gov task release T-0001 --agent w1 # release the card lease you hold
gov task close T-0001 # run the gates; the green run becomes the completion receipt
gov task list --json # cards as [{id, title, status, rules, claim}] — claim read
# from the lease file; expired reads as unclaimed
gov acquire reports/summary.md --agent w1 # lease a shared resource (busy → exit 3;
# --wait S polls, --ttl S bounds the lease;
# both outcomes announce the lock root)
gov release reports/summary.md --agent w1 # release a lease you hold (never on another
# holder's behalf)
gov locks # list current leases (diagnostic only)
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); --hooks --pre-commit
additionally installs the optional pre-commit hook — the cheap content
gates (pairing sidecar freshness, conflict markers) on the staged files,
so pair drift surfaces at git commit with the scoped fix command
inline instead of one stage later at push (#110). 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
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.
On the name: this project is unrelated to haocn-ops/govrail (a Cloudflare Workers agent control plane, archived). Both chose the name independently; this repository is the Python
govCLI governance plane, first published August 2026.
Star History
1 maintainer
Release files for govrail 0.30.7
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.30.7.tar.gz | 301.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| govrail-0.30.7-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 547.6 kB
Release files / govrail-0.30.7.tar.gz
| Download URL | govrail-0.30.7.tar.gz |
|---|---|
| Size | 301.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
82e7f44362f604b4ca1c25d8dff80857487fd78fdbdc629ab56d893ed3f77985
|
|
BLAKE2b-256 checksum How to use checksums |
f0c02b30e76030db6735d8ecdbb515e84b8f7dc95ab01252fd3833c88244dedd
|
| 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.30.7-py3-none-any.whl
| Download URL | govrail-0.30.7-py3-none-any.whl |
|---|---|
| Size | 246.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
72f3bd671a848aba18a698a1833a45728fb84b90e1e29a62e5a03d1a9e09a8b0
|
|
BLAKE2b-256 checksum How to use checksums |
b70e2577ec328560eca55ba988a42a8bf03df5874af455c2ddfee5193331e2eb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
