The Problem

AI‑generated code often lands directly in the codebase without a traceable decision record, making reviews, audits, and roll‑backs painful. Teams lose visibility into why a change was made, which design alternatives were considered, and whether the implementation satisfies the original intent.

What This Does

govctl introduces a governance‑as‑code layer that lives alongside source files in the gov/ directory. RFCs, ADRs, work‑item definitions, and verification guards are stored as version‑controlled TOML artifacts (e.g., gov/rfc/RFC-0002/rfc.toml, gov/adr/ADR-0005-cli-output-color-scheme-and-formatting.toml). The CLI (src/cmd/*.rs) provides first‑class commands—list, show, edit, adr accept, rfc advance, etc.—that operate on these artifacts, ensuring every AI‑driven patch is anchored to a reviewed specification before it is merged.

How It Is Wired

Execution starts at the binary generated from src/main.rs (implicitly created by Cargo) which registers sub‑commands defined in src/cmd/. For example, the agent command is implemented in src/cmd/agent.rs and routes to agent::run. That function parses the user’s intent, loads the relevant TOML file via gov::config::load (found in gov/config.toml), and invokes the edit engine in build_support/edit_ops_spec.rs. The edit engine validates the mutation against the schema defined in gov/conformance/ and writes back the updated artifact, preserving a diff‑able format.

Key call chain for a typical govctl edit operation:

  1. Binary entry – cargo run -- <subcommand> → src/main.rs → clap dispatch.
  2. Command handler – src/cmd/edit.rs (not listed but follows same pattern) → edit::execute.
  3. Config load – gov::config::load reads gov/config.toml.
  4. Edit spec – build_support/edit_ops_spec.rs::apply validates the edit against gov/conformance/*.
  5. File write – gov::io::write_toml (in src/lib.rs) persists the change.

The gov/guard/ TOML files (e.g., gov/guard/govctl-check.toml) are consulted by the guard runner in src/cmd/check.rs, which executes verification steps defined in gov/guard/*. The guard runner is the only component that interacts with external tools (e.g., cargo test) and therefore has the widest blast radius; all other commands are pure file manipulations.

How To Use It

# Clone the repository
git clone https://github.com/moses-y/govctl
cd govctl

# Build the CLI (Rust toolchain required)
cargo build --release

# Show help for the top‑level command
./target/release/govctl --help

# List all RFCs
./target/release/govctl list rfc

# Edit a work‑item (opens the TOML in $EDITOR)
./target/release/govctl edit workitem my-feature-123

Configuration resides in gov/config.toml; no additional environment variables are required for basic operation. CI is defined in .github/workflows/ci.yml and runs cargo test and the guard suite.

Real‑World Use

A team using an LLM‑based code assistant can first create an RFC (govctl rfc new) describing the desired behavior. An ADR is added to capture design trade‑offs (govctl adr add). The AI generates a patch, which the developer commits only after the associated work‑item passes all guards (govctl work run --guard). The entire lifecycle—from idea to verified implementation—is visible in PR diffs.

Code Health & Issues

  • Low – No structural red flags – tests, CI workflow, license, and lockfile are present.
  • Low – Large TOML surface – 416 TOML files increase diff noise; consider consolidating where possible.
  • Low – Express detection – a Node express dependency appears in the repo but is not referenced by Rust code; it may be leftover and can be removed.

No critical bugs or missing CI components were observed.

The Bottom Line

govctl provides a concrete, file‑based governance framework that integrates tightly with a Rust CLI, making AI‑assisted changes auditable and gate‑controlled. It is well‑tested and CI‑protected, but the sheer number of TOML artifacts may require disciplined naming conventions. Ideal for teams that already use Rust tooling and need formal governance without a separate web service.