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-decisions --base <ref>  # + parallel-branch number collisions
gov decision next --base <ref>     # next free D-number (branch-aware)
gov decision add --from FILE       # append a decision, validated + atomic
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 over gates.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, default gates.json, notes format, and agent skills that gov init injects 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

License
- OSI Approved :: MIT License
Operating System
- OS Independent
Programming Language
- Python :: 3

Release files for govrail 0.17.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for govrail 0.17.0
File	Size	Uploaded
govrail-0.17.0.tar.gz	114.8 kB	Sep 4, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for govrail 0.17.0
File	Interpreter	ABI	Platform	Reset
govrail-0.17.0-py3-none-any.whl 102.8 kB Sep 4, 2026	Python 3	none	any	Details

Total release size: 217.6 kB

Release files / govrail-0.17.0.tar.gz

Download URL	govrail-0.17.0.tar.gz
Size	114.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`c081ea80e3070b4ac5a2db8a5d7739543f19b540ba6613a874fe8744c7970bc2`
BLAKE2b-256 checksum How to use checksums	`4f0ed1554dac5b098a54f10f0ff67ba653b6b084fbbad57a1bbc591055ff9063`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`

Release files / govrail-0.17.0-py3-none-any.whl

Download URL	govrail-0.17.0-py3-none-any.whl
Size	102.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`865247e5e135a419bce120726a5273d3355a32d41c3ff6883b835624c54df5bd`
BLAKE2b-256 checksum How to use checksums	`4aa7358c9dba8072790fdb49c37e5ba253d1ef6e6526da4afe840d9a87b1537f`
Upload date	Sep 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.14`