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

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.

How a change ships

Rule 1 in motion: the smallest sufficient set runs per diff (a prose edit never pays the platform matrix), CI owns the full matrix, and a release-worthy merge publishes end to end — draft amended into the release commit, auto-merge armed, tag and PyPI unattended. A red PR never merges; the chain halts on evidence, not on hope.

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)

The full command surface, verbatim from gov --help:

commands:
  init             inject the plane into a project (--hooks/--ci add runners; --hooks --pre-commit adds the opt-in commit-stage gates; --adopt-new merges new shipped gates; --upgrade shows template drift)
  uninstall        reverse init
  run              run the project's gate DAG (args forwarded to gates.py; --receipt records a tamper-evident run receipt, #124; --merge preflights the union of parallel branches in a scratch worktree before landing)
  self-test        run governance rejection cases
  receipt          verifiable run receipts (verify/show): verify a cited receipt against a commit (issue #124/D42)
  verify-notes     check note format
  verify-pairing   check bilingual pairing (--write re-confirms; --staged checks the index; --explain prints the schema)
  verify-note-presence warn when a non-trivial diff carries no note (e.g. --base <ref>, --strict)
  verify-rubric    check the review rubric's structure (ids, fields, parity)
  verify-archive   verify the archived-notes seal (pinned sha256 per file)
  verify-decisions verify the decisions table (numbering, alternatives, orphans; --base checks branch collisions)
  decision         decision-row tooling (next free D-number; atomic validated add)
  verify-doc-sync  CHANGELOG ↔ HIGHLIGHTS pairing (every version has a section; --write drafts the missing ones from CHANGELOG)
  verify-conflict-markers fail when changed files carry git conflict markers (e.g. --base <ref>, --staged)
  review           assemble the review dossier for a diff (scope, notes, recall, rubric)
  trend            gate duration trends from .gov/history/ (p50 per window; --by-tag splits per caller, --cost rolls up caller-reported cost)
  stats            structural facts per language (lines, symbols, nesting depth) from the parse layer — facts, not verdicts; --record appends to the stats ledger
  check            syntax-class static checks over the parse layer (shipped + .gov/checks/ rules; suppressions counted; --strict makes warnings block)
  doctor           environment self-check (PATH, python, hooks, gates schema)
  note             note scaffold, read side, and pre-commit check (new/check/list/show; list --stale marks audit signals)
  whatsnew         usage-oriented highlights since a version
  recall           retrieve notes, decisions, and postmortems (all terms, ranked)
  audit-notes      report mechanical staleness signals in implemented notes
  change-scope     report touched surfaces (e.g. --base <ref>)
  archive-notes    seal the archived-notes manifest
  task             task cards for subagent briefs (new/check/close/claim/release/list; rules@hash pin + checklist + green-run receipt; claim/release lease a card so two workers cannot take one)
  preset           typed adoption bundles (list/show/apply): a project type's gates, skills, and manifest hints — additive, never overwriting (D53)
  acquire          take a lease lock on a resource (cross-process, cross-duration; busy exits 3; --wait S polls, --ttl S bounds the lease)
  release          release a lease you hold (--agent must match the holder)
  locks            list current lease locks in the git common dir (diagnostic only, never an admission decision)
  hooks            git-hook gate runners (the installed hooks delegate here; 'hooks pre-commit' runs the gates whose 'stages' include 'pre-commit' under their configured advisory/blocking contract)
  verify-plane     tamper-evidence for the plane's own config (rules.md, gates.json, pairing/decisions/surfaces, .gov/rejections/**; --write re-baselines — interactive consent, --confirm-unattended for agents)

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.

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 gov CLI governance plane, first published August 2026.

Star History