open source · MIT license

Enforce module boundaries in Python.
Catch violations in CI.

Define allowed dependencies between modules in a governance.toml. Run it locally, in CI, or let an LLM tell you what to fix.

View on GitHub

terminal

30-second setup

Three commands. That's it.

Generate

Scans your source code, detects modules, and maps every real import.

governance-ast --generate --source-root src/

Configure

Review the generated governance.toml. Adjust boundaries to match your intended architecture.

[[modules]]
name = "api"
depends_on = ["core", "auth"]

Enforce

Run locally or in CI. Violations fail the build. No more silent boundary erosion.

governance-ast

what it catches

Five rules, zero ambiguity

🔗

enforce_depends_on

Module imports something not in its allowed dependency list.

🔄

no_cycles

Circular dependency detected. A imports B, B imports A.

📐

enforce_layers

Lower architectural layer imports from a higher one.

📢

max_public_surface

Too many symbols exposed to other modules. Keep your API tight.

🧲

min_cohesion

Module imports more from outside than from itself. It might belong elsewhere.

CI integration

Catches violations in your PR

Add one GitHub Action. Get violation reports as PR comments with LLM-powered fix suggestions.

❌ Governance — 1 violation, 1 new module

🔴 🔗 core: Undeclared dependency: 'core' imports 'db' (allowed: [])

core/service.py:2

📦 New module exporters (exporters/) — not in governance.toml

Reply /governance fix to apply.

🤖 AI: The core→db import creates tight coupling. Extract shared types into a common module, or add "db" to core's depends_on.

Reply /governance fix on the PR and the bot auto-updates your governance.toml with correct depends_on and commits to your branch.

Adopting on an existing codebase? Save a baseline and only fail on new violations:

governance-ast --save-baseline .governance-baseline.json
governance-ast --baseline .governance-baseline.json

- uses: actions/checkout@v4
- name: Governance
  uses: useparadigm/code-governance@main
  with:
    config: governance.toml
    diff: origin/main
    advise: true
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

LLM advice

Don't just find violations — understand them

Pass --advise and get architectural recommendations powered by OpenAI or Anthropic.

$ governance-ast --advise

🤖 Architectural advice:

The api → billing dependency suggests checkout logic is reaching into the billing module directly. Consider:

1. Extract charge_customer() into a shared interface in core
2. Or explicitly add "billing" to api's depends_on — this is a legitimate dependency if api owns the checkout flow

The payments ↔ notifications cycle is more concerning. Break it with an event bus or move send_receipt into the payments module.

○ OpenAI (gpt-4o)

○ Anthropic (claude-sonnet)

honest comparison

vs import-linter

import-linter is the established tool for this. Here's an honest comparison.

	code-governance	import-linter
Setup	--generate creates config from source	Manual contract definition
Diff mode	✓ only check changed files	✗
Baseline	✓ accept existing, fail on new	✗
CI comments	✓ PR comments + fix suggestions	✗
Auto-fix	✓ /governance fix	✗
LLM advice	✓ architectural recommendations	✗
Module metrics	✓ cohesion, surface, symbol count	✗
HTML report	✓ dependency matrix viewer	separate browser UI
Transitive imports	direct only	✓ transitive chains
Forbidden contracts	✗	✓
Speed (Django, 902 files)	~1.2s	~0.1s
Package needs installing	No — scans source directly	Yes — must be importable

Choose import-linter if you need transitive import detection. Choose code-governance if you want CI integration, auto-fix, LLM advice, or zero-config setup.

Enforce module boundaries in Python.Catch violations in CI.

Codebases rot from the inside