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 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 --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
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 verify-decisions --json    # machine-readable: {violations, orphans, overdue, ...}
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 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 close T-0001          # run the gates; the green run becomes the completion receipt

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 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.21.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.21.0
File	Size	Uploaded
govrail-0.21.0.tar.gz	131.7 kB	Sep 4, 2026	Details

Built distribution (wheel)

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

Total release size: 247.6 kB

Release files / govrail-0.21.0.tar.gz

Download URL	govrail-0.21.0.tar.gz
Size	131.7 kB
Tags	Source
SHA-256 checksum How to use checksums	`646270680bbb036ee48dba3c583ae34cbdf2063fcb74b2e5f78f5cf31cf7a186`
BLAKE2b-256 checksum How to use checksums	`6e8838d70787368393b22cbce8d09d0f31bc4d6293e23eec8ab656c5950788fb`
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.21.0-py3-none-any.whl

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