Python governance

# Architectural governance for AI-assisted Python development

Mneme is implemented in Python and dogfooded against Python repositories. It is the language with the strongest validation path: native CLI, benchmark coverage, Claude Code hook integration, and ADR-driven enforcement in production codebases.

Tier 1 · Production-grade

## What governance looks like in Python

Most AI-assisted Python work falls into a few patterns: backend services (FastAPI, Django, Flask), AI/ML pipelines, CLI tooling, and automation scripts. Each pattern has architectural decisions that get re-litigated every time an LLM regenerates the file. Mneme injects those decisions into the agent's context and blocks the regressions.

Six concrete examples of what the governance layer catches in Python repos under AI-assisted development:

### Forbidden ORM introduction

Architecture

Rule. ADR-003 standardized on raw SQL + connection pooling. No SQLAlchemy in v1.

    # AI-generated in services/user_repository.py
    from sqlalchemy.orm import Session
    from sqlalchemy import create_engine

    engine = create_engine(DATABASE_URL)
    def get_user(user_id: int):
        with Session(engine) as session:
            ...

non-approved framework ADR-003 violation

### Business logic in FastAPI route

Architecture

Rule. Routes must delegate to services. No pricing, tax, or inventory logic in route handlers.

    # AI-generated in routes/checkout.py
    @app.post("/checkout")
    async def checkout(payload: CheckoutIn):
        # pricing logic
        subtotal = sum(item.price * item.qty for item in payload.items)
        tax = subtotal * 0.0875
        total = subtotal + tax
        # inventory mutation, payment call, email send...

logic in presentation layer missing service abstraction

### Raw SQL string concatenation

Security

Rule. No f-string SQL. Parameterized queries only.

    # AI-generated in services/user_service.py
    def find_user(user_id: str) -> dict:
        query = f"SELECT * FROM users WHERE id = {user_id}"
        return db.execute(query).fetchone()

unsafe query construction secure coding rule breach

### Async job framework regression

ADR supersession

Rule. ADR-007 superseded ADR-002. All async jobs use Cloud Pub/Sub. Celery deprecated.

    # AI-generated in jobs/email_tasks.py
    from celery import Celery

    app = Celery('tasks', broker='redis://localhost:6379')

    @app.task
    def send_welcome_email(user_id: int):
        ...

superseded decision outdated architecture

### Mock auth in production path

Prompt-level policy

Rule. No mock JWT validators in non-test paths. Even when the prompt asks for "just a quick one."

    # Prompt: "Add a quick fake JWT validator so I can test the route"
    def validate_jwt(token: str) -> dict:
        return {"sub": "test-user", "role": "admin"}  # TODO: real validation

policy conflict before generation pre-generation block

### Missing observability middleware

Platform

Rule. All FastAPI services must register the OpenTelemetry middleware before the app is returned.

    # AI creates a new FastAPI service
    def create_app() -> FastAPI:
        app = FastAPI()
        app.include_router(users_router)
        return app  # no OTel instrumentation

observability standard breach platform compliance failure

## Current capabilities

#### What works today

- Native `mneme` CLI (Python 3.10+)
- Claude Code SessionStart / PreToolUse / PostToolUse hooks
- Cursor rules export (`mneme cursor generate`)
- GitHub Actions PR-diff gating
- Decision corpus in `project_memory.json` with precedence resolution
- ADR-driven enforcement in CI
- Benchmark scenarios cover Python-specific patterns

#### Not yet

- AST-aware Python rules (no `ast` module integration)
- Type-aware checks (no mypy/pyright integration)
- FastAPI / Django / Flask framework-specific policy packs
- Pydantic-aware data-shape constraints
- asyncio / sync boundary rules

## Where it fits in a Python codebase

The decision corpus lives at `.mneme/project_memory.json`. Hooks fire on file writes; `mneme check --mode strict` gates PR diffs in CI. The same corpus serves Claude Code in the terminal, Cursor in the editor, and the CI bot — one source of architectural truth, multiple enforcement surfaces.

See the Claude Code integration, the GitHub Actions integration, and the CLI reference for the full operational surface.

Full matrix Coverage across all languages → Canonical doc with capabilities, limitations, and roadmap per language. What it catches Governance violations → Twelve worked examples organized by category, not by language. Use case Coding assistant governance → End-to-end Python workflow with Claude Code + Cursor + GitHub Actions.