governor-application 2.0.0

# rust-cargo-governor

![unsafe forbidden](https://img.shields.io/badge/unsafe-forbidden-success.svg)
![license](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue)

Governance and release automation tooling for Rust Cargo workspaces.

Version `2.0.0` introduces a versioned machine contract for CLI output,
an application-layer API, and agent-facing documentation and MCP support.

## Overview

`cargo-governor` provides governance and release automation for Rust
projects:

- **`owners`** — Declarative crate ownership management through
  `Cargo.toml`
- **`release`** — Automated versioning, changelog generation, and
  publishing

Define ownership, release policies, and quality gates as code directly
in your `Cargo.toml` files. All policies are version-controlled, reviewed
through code review, and enforced in CI.

## Installation

```bash
cargo install cargo-governor
```

Then authenticate with crates.io once:

```bash
cargo login
```

## Usage

### Owners

Manage crate ownership declaratively:

```bash
# Show computed owner list
cargo-governor owners show

# Sync with crates.io
cargo-governor owners sync

# Check for drift
cargo-governor owners check
```

### Release

Normal release UX:

```bash
# 1. Make changes
# 2. Commit them with Conventional Commits
git commit -m "feat: add release guardrails"

# 3. Preview the full release
cargo-governor --dry-run release full --format json

# 4. Let cargo-governor do the rest
cargo-governor release full --format json
```

Advanced commands remain available for inspection or recovery:

```bash
cargo-governor release status --format json
cargo-governor release analyze --format json
cargo-governor release plan --format json
cargo-governor release bump --format json
cargo-governor release publish --format json
```

`cargo-governor` now refuses the confusing workflow where versions are
pre-bumped in manifests before release, and mutating release commands
also require a clean working tree by default.

`CHANGELOG.md` is generated from Conventional Commit messages since the
last release tag, so release notes follow the same commit range and
semantic analysis as the version bump itself.

### Coding Agents

`cargo-governor` now ships a machine-readable agent contract and MCP
adapter:

```bash
# Load agent context
cargo-governor agent context --format json

# Generate repo-local agent docs and schemas
cargo-governor agent export-docs --output-dir .

# Serve read-only and dry-run tools over MCP stdio
cargo-governor mcp serve
```

Recommended agent flow:

```bash
cargo-governor agent context --format json
cargo-governor release status --format json
cargo-governor release analyze --format json
cargo-governor --dry-run release plan --format json
cargo-governor --dry-run release full --format json
```

## Configuration

### Workspace defaults

```toml
[workspace.metadata.governor.owners]
default_users = ["org-bot"]

[workspace.metadata.governor.owners.groups]
core = ["alice", "github:myorg:core-team"]
maintainers = ["bob", "carol", "github:myorg:maintainers"]
```

### Package configuration

```toml
[package.metadata.governor.owners]
users = ["alice", "bob"]
teams = ["github:myorg:core-team"]

[package.metadata.governor.owners.groups]
inherit = ["core", "maintainers"]
```

## Conventional Commits

Version bump detection follows conventional commits:

- `feat:` → minor bump
- `fix:` → patch bump
- `feat!:` or `BREAKING CHANGE:` → major bump

## CI/CD Integration

```yaml
- name: Release
  run: cargo-governor --dry-run release plan --format json
```

For mutating CI release jobs, gate `release bump`, `release publish`, and
`release full` behind explicit approval.

No token needed — uses credentials from `cargo login`.

## Development

```bash
just build    # Build project
just test     # Run tests
just check    # Format + lint
just fix      # Auto-fix issues
just audit    # Security audit
```

## Project Structure

```text
crates/
├── cargo-governor/       # CLI, presenters, MCP transport, composition root
├── governor-application/ # Use cases and machine contracts
├── governor-cargo/       # Cargo metadata, command, changelog adapters
├── governor-core/        # Domain model and port interfaces
├── governor-cratesio/    # crates.io registry adapter
├── governor-git/         # Git adapter
├── governor-checkpoint/  # Checkpoint/resume adapter
└── governor-owners/      # Owners domain and policies
```

## License

MIT OR Apache-2.0

## Repository

- **Primary**: <https://gitlab.opentc.ru/opentc/rust-cargo-governor>
- **Mirror**: <https://github.com/opentc/rust-cargo-governor>