ACGS-Lite: Constitutional Governance Membrane for Agent Execution

Headline: No valid receipt. No side effect.

acgs-lite is the constitutional governance membrane between agent reasoning and real-world execution. It is not an agent framework. Agent frameworks keep responsibility for planning, model calls, memory, and tool selection; acgs-lite decides whether a proposed side effect may run.

Core invariant:

No valid constitutional authorization, no side effect.

LLM reasoning → constitutional check → decision receipt → governed execution

Current status & non-claims

• Public package: v2.12.0 on PyPI. Apache-2.0. Beta.
• Unreleased source hardening: the production execution-grant, trusted-context, durable-audit, and recovery contracts described below are present in this source candidate. They are not present in the published v2.12.0 wheel.
• Local proofs exist. Receipt-gated execution, MACI role checks, and an in-process SHA-256 audit chain are implemented and tested.
• No independently confirmed production users yet.
• Not certified. Not regulator-approved. Production properties depend on your constitution, storage, authentication, and operational controls.
• pip install does not ship examples/. Do not run a repo path after install. Use the 5-line snippet below, or the 5-minute membrane page.

5-line quickstart

Works after pip install acgs-lite==2.12.0. Default engine is fail-closed: the last line raises.

from acgs_lite import Constitution, ConstitutionalViolationError, GovernanceEngine
engine = GovernanceEngine(Constitution.from_yaml_str(
    "rules:\n  - {id: no-wire, text: Block unauthorized wires, severity: critical, keywords: [wire transfer]}"))
print(engine.validate("send invoice email", agent_id="demo").valid)  # True
try:
    engine.validate("wire transfer $1000", agent_id="demo")
except ConstitutionalViolationError:
    pass
else:
    raise AssertionError("unsafe action was not blocked")

Expected:

True
ConstitutionalViolationError: Action blocked by rule no-wire: Block unauthorized wires

That is the check. The 5-minute membrane is the executor gate: ALLOW with a receipt, TRANSFORM (PII redaction), DENY of a wire, and refusal of a missing receipt (No legitimacy receipt, no execution).

Unreleased local production profile

The following source-candidate API binds a host-supplied actor/tenant context, the exact call and policy, single consumption in one wrapper instance, and a confirmed JSONL authorization record before the callable starts. The host must authenticate the actor and tenant before constructing the context and must not expose issue_grant() to untrusted callers. This does not isolate malicious same-process code or provide restart recovery, distributed exclusion, or a general exactly-once guarantee for external APIs.

from pathlib import Path
from tempfile import TemporaryDirectory

from acgs_lite import Constitution
from acgs_lite.audit import AuditLog, JSONLAuditBackend
from acgs_lite.governed import GovernedCallable
from acgs_lite.legitimacy import (
    AuthorizationProfile,
    LegitimacyInvariantError,
    TrustedExecutionContext,
)

calls = []
with TemporaryDirectory() as directory:
    audit = AuditLog(backend=JSONLAuditBackend(Path(directory) / "audit.jsonl"))
    guard = GovernedCallable(
        Constitution.default(),
        authorization_profile=AuthorizationProfile.PRODUCTION,
        audit_log=audit,
        require_durable_audit=True,
        trusted_execution_context=TrustedExecutionContext(
            actor_id="host-authenticated-operator",
            scope="tenant-a",
            allowed_subjects=frozenset({"account-1"}),
        ),
        require_trusted_context=True,
    )

    @guard
    def inspect_account(value, *, scope, subjects):
        calls.append(value)
        return value

    grant = inspect_account.issue_grant(
        "safe", scope="tenant-a", subjects=("account-1",)
    )
    assert inspect_account(
        "safe",
        scope="tenant-a",
        subjects=("account-1",),
        execution_grant=grant,
        execution_attempt_id="attempt-1",
    ) == "safe"
    # Explicit recovery of the same completed attempt returns its verified result.
    assert inspect_account(
        "safe",
        scope="tenant-a",
        subjects=("account-1",),
        execution_grant=grant,
        execution_attempt_id="attempt-1",
    ) == "safe"
    try:
        inspect_account("denied", scope="tenant-a", subjects=("account-1",))
    except LegitimacyInvariantError:
        pass
    else:
        raise AssertionError("missing authorization executed")

assert calls == ["safe"]

1. One explicit decision
2. A replayable receipt emitted before execution
3. An execution boundary the executor must match
4. Fail-closed behavior on missing or unverifiable inputs

ALLOW
ALLOW_WITH_CONTROLS
TRANSFORM_REQUIRED
REPLAN_REQUIRED
STRUCTURED_REVIEW_REQUIRED
DENY_OPERATION_WITH_ALTERNATIVE
DENY_GOAL
HARD_DENY

Security Disclosure

Please report suspected ACGS-Lite governance or security vulnerabilities privately to security@acgs.ai instead of opening a public issue. The canonical supported-version, scope, and disclosure-window policy is in SECURITY.md, with a mirrored docs page at docs/security.md.

Recommended starting points

After pip install (no clone):

• 5-line fail-closed check — the snippet above
• 5-minute membrane — docs/guides/five-minute-membrane.md (ALLOW / TRANSFORM / DENY / missing-receipt refusal + audit chain)

After cloning this repo:

• Pip-only script in-tree — python examples/membrane_5min.py
• Richer membrane walkthrough — examples/governed_execution_membrane.py
• Agent readiness gate — python3 scripts/agent_ready.py --run-tests
• Self-verifying install — examples/agent_quickstart/
• Audit trail demo — examples/audit_trail/
• Shared infrastructure path — examples/mcp_agent_client.py
• Self-assessed compliance mapping — acgs assess --framework eu-ai-act (mapping only; not certification)

The Phoenix example under examples/phoenix_acgs_governed_agent/ shows request -> decision -> receipt -> bounded execution telemetry; its governance.decision.* span attributes are experimental.

What this proves

• Block before execution: default GovernanceEngine raises on a matching deny rule; the executor refuses DENY receipts and missing receipts.
• Separate powers with MACI: proposer, validator, executor do not collapse into one actor on GovernedAgent (default enforce_maci=True).
• Keep audit evidence: each decision can be chained, inspected, and verify_chain()-checked in process.

This does not prove independent production use, certification, or that an in-memory audit log is a hosted store.

🚀 Quickstart

from acgs_lite import Constitution, GovernedAgent, MACIRole

def my_llm_agent(prompt: str) -> str:
    return f"Processed: {prompt}"

constitution = Constitution.from_yaml("constitution.yaml")
agent = GovernedAgent(
    my_llm_agent,
    constitution=constitution,
    maci_role=MACIRole.EXECUTOR,
)
result = agent.run("Process this high-risk transaction", governance_action="execute")

Rules in YAML (constitution.yaml):

constitutional_hash: "608508a9bd224290"
rules:
  - id: no-pii
    text: Block PII exposure
    severity: critical
    keywords: ["SSN", "social security", "passport number"]

  - id: no-destructive
    text: Block destructive operations
    severity: high
    keywords: ["delete", "drop table", "rm -rf"]

  - id: require-approval
    text: Financial actions require human approval
    severity: high
    keywords: ["transfer", "payment", "wire"]

📦 Installation

pip install acgs-lite

Upgrading from v2.9.x? v2.10.0 changed require_auth to default to True. If you call create_governance_app() without an api_key, you'll get a ValueError at startup. Pass api_key=os.environ["ACGS_API_KEY"] or set require_auth=False for local dev. See CHANGELOG for full details.

With framework integrations:

pip install "acgs-lite[openai]"       # OpenAI
pip install "acgs-lite[anthropic]"    # Anthropic Claude
pip install "acgs-lite[langchain]"    # LangChain / LangGraph
pip install "acgs-lite[mcp]"          # Model Context Protocol server
pip install "acgs-lite[autogen]"      # AutoGen / AG2
pip install "acgs-lite[a2a]"          # Google A2A protocol
pip install "acgs-lite[agno]"         # Agno agent framework
pip install "acgs-lite[server]"       # FastAPI lifecycle HTTP server
pip install "acgs-lite[all]"          # All integrations

🤖 For AI Agents (Claude Code / Codex CLI)

Copy the prompt below directly into Claude Code, Codex CLI, or any AI coding agent. It installs acgs-lite, runs the self-verifying quickstart, and reports pass/fail — no API keys required.

For Claude Code PreToolUse governance, use the canonical hook at integrations/claude_code/acgs-governance-preuse.sh and the setup guide in integrations/claude_code/README.md. The hook calls a configurable governance sidecar before Bash, Write, Edit, and MultiEdit run; the default /x402/check URL is an external sidecar contract, not a bundled acgs-lite server route.

One-shot install + verify prompt

TASK: Install and verify ACGS-Lite constitutional AI governance.

STEPS:
1. Install the package:
   pip install acgs-lite==2.12.0

2. Pip-only proof (no clone). Paste and run the 5-line README snippet.
   The last line must raise ConstitutionalViolationError for "wire transfer $1000".

3. If you cloned this repo, also run:
   python examples/membrane_5min.py
   python examples/agent_quickstart/run.py

4. Expected outcome for the cloned quickstart — every line should show ✅:
   ✅  safe request passes through
   ✅  PII blocked by rule 'no-pii'
   ✅  destructive op blocked by 'no-destructive'
   ✅  YAML loads 3 rules
   ✅  Proposer can propose
   ✅  Golden Rule: proposer cannot validate own output
   ✅  Audit log: 3 entries recorded
   ✅  Chain integrity: verified
   ✅  All assertions passed — ACGS-Lite is correctly installed.
   Exit code: 0

5. If any ❌ appears, report the failing assertion and the full traceback.
   Do NOT set strict=False to work around failures — diagnose root cause.

CONSTRAINTS:
- No OpenAI or Anthropic API key is required for this verification step.
- Constitutional hash 608508a9bd224290 must appear in validation output.
- Run from the repo root (packages/acgs-lite/) if cloned from source.

Implement governance in 5 lines (follow-up prompt)

TASK: Add ACGS-Lite governance to this codebase.

STEPS:
1. pip install acgs-lite

2. Create constitution.yaml at the project root:

constitutional_hash: "608508a9bd224290"
rules:
  - id: no-pii
    text: Block PII exposure
    severity: critical
    keywords: ["SSN", "social security", "passport number"]
  - id: no-destructive
    text: Block destructive operations
    severity: high
    keywords: ["delete", "drop table", "rm -rf"]
  - id: require-approval
    text: Financial actions require human approval
    severity: high
    keywords: ["transfer", "payment", "wire"]

3. Wrap the agent/LLM call with GovernedAgent:

from acgs_lite import Constitution, AuditLog
from acgs_lite.governed import GovernedCallable

constitution = Constitution.from_yaml("constitution.yaml")
audit_log    = AuditLog()

@GovernedCallable(constitution, audit_log=audit_log, agent_id="my-agent")
def run_agent(prompt: str) -> str:
    return your_llm_call(prompt)   # replace with your LLM call

4. Verify the audit chain after every session:
   assert audit_log.verify_chain()

CONSTRAINTS:
- Engine is fail-closed by default — unsafe actions raise ConstitutionalViolationError.
- Never set strict=False in production.
- Run examples/agent_quickstart/run.py to confirm the installation is healthy.

Source installation (from this repo)

git clone https://github.com/acgs-ai/acgs-lite.git
cd acgs-lite
pip install -e ".[dev]"
python examples/agent_quickstart/run.py   # exit 0 = all clear

See examples/agent_quickstart/ for the full self-verifying suite.

🛡️ Core Concepts

Governance Engine

The GovernanceEngine sits between your agent and its tools. Every action passes through it before execution. Matching rules block or flag the action; the result is a ValidationResult.

from acgs_lite import Constitution, GovernanceEngine, Rule, Severity

constitution = Constitution.from_rules([
    Rule(id="no-pii", text="Block PII exposure", severity=Severity.CRITICAL, keywords=["SSN", "passport"]),
    Rule(id="no-delete", text="Block destructive operations", severity=Severity.HIGH, keywords=["delete", "drop"]),
])

engine = GovernanceEngine(constitution)
result = engine.validate("summarize the quarterly report", agent_id="analyst-01")

if not result.valid:
    for v in result.violations:
        print(f"[{v.severity}] {v.rule_id}: {v.description}")

GovernedAgent — Input/Output Wrapper

from acgs_lite import Constitution, GovernedAgent

constitution = Constitution.default()

def summarize(text: str) -> str:
    return f"Summary: {text}"

agent = GovernedAgent(summarize, constitution=constitution, enforce_maci=False)

# Raises ConstitutionalViolationError if text contains violations
result = agent.run("Q4 revenue was $4.2M")

This wrapper checks outer input and output. It does not intercept tools called inside summarize; put an execution authorization gate at each real side-effect boundary.

MACI — Separation of Powers

MACI prevents a single agent from proposing, validating, and executing the same action:

from acgs_lite import MACIEnforcer, MACIRole

enforcer = MACIEnforcer()

# Assign roles
enforcer.assign(agent_id="planner",   role=MACIRole.PROPOSER)
enforcer.assign(agent_id="reviewer",  role=MACIRole.VALIDATOR)
enforcer.assign(agent_id="executor",  role=MACIRole.EXECUTOR)

# Proposer creates; Validator checks; Executor runs — never the same agent
proposal = enforcer.propose("planner", action="deploy v2.1 to production")
approval = enforcer.validate("reviewer", proposal)
enforcer.execute("executor", approval)

Tamper-Evident Audit Trail

Every governance decision is written to an append-only, SHA-256-chained log:

from acgs_lite import AuditLog

log = AuditLog()
engine = GovernanceEngine(constitution, audit_log=log)

engine.validate("send email to user@example.com", agent_id="mailer")

for entry in log.entries:
    print(entry.id, entry.valid, entry.constitutional_hash)

# Verify chain integrity
assert log.verify_chain(), "Audit log tampered!"

Signed, Replay-Verifiable Receipts

A self-contained hash chain detects alterations within the supplied retained segment. Without a trusted external anchor it cannot detect deletion of the whole segment or replacement with a freshly rewritten history. A signed, replay-verifiable receipt additionally proves who decided and that the verdict re-derives — without trusting the operator. acgs-lite provides both.

Every DecisionReceipt already commits to its full payload through a SHA-256 receipt_hash. With the optional crypto extra you can bind that commitment to an Ed25519 signature, so an independent party — holding only the signer's public key — can verify the receipt's authenticity and re-derive its decision from the recorded inputs:

# pip install "acgs-lite[crypto]"
from acgs_lite.legitimacy import Ed25519ReceiptSigner, sign_receipt, replay_and_verify

signer = Ed25519ReceiptSigner.generate()       # bring your own key store / KMS
signed = sign_receipt(receipt, signer)         # Ed25519 over the receipt commitment
trusted_pubkey = signer.public_key_hex()       # distributed out-of-band to verifiers

# An auditor, holding only the trusted public key, verifies authenticity...
assert signed.verify(trusted_pubkey)

# ...and re-derives the recorded verdict from the inputs (not just the hash):
result = replay_and_verify(signed, policy_evaluator, expected_public_key=trusted_pubkey)
assert result.ok   # signature valid, hash intact, AND the verdict reproduced

Honest boundaries:

• Signing is optional (crypto extra, Ed25519 via cryptography). The core membrane and audit log do not require it.
• Verification requires a trusted public key. verify(expected_public_key) is mandatory; verify_integrity() only checks self-consistency and is not authenticity.
• The signing key is held in process memory. For production non-repudiation, back Ed25519ReceiptSigner with your own KMS/HSM.
• Receipts carry no anti-replay nonce; enforce request_id uniqueness at the application layer.

See docs/api/legitimacy.md for the full receipt and replay-verification API.

🌉 gove-zone kernel bridge (Experimental)

acgs_lite.gove lets a GovernanceEngine constitution act as a gove-zone Policy, so an existing constitution can gate calls through gove-zone's signed execute_with_receipt executor. This bridge is Experimental: it is a new adapter seam, not a replacement for the legitimacy receipt pipeline above, and it has not been run in production.

Install (Python >= 3.11 only). The optional experimental bridge is qualified against the published pre-release gove-zone==1.0.0rc2:

pip install "acgs-lite[gove]"

Minimal usage — a real constitution evaluating a gove_zone.tool.ToolCall:

from acgs_lite import Constitution, GovernanceEngine
from acgs_lite.gove.policy import ConstitutionPolicy
from gove_zone.tool import ToolCall

policy = ConstitutionPolicy(GovernanceEngine(Constitution.default(), strict=False), version="1.0.0")
record = policy.evaluate(ToolCall(name="deploy_feature", args={"env": "staging"}, goal="deploy to staging", actor="agent-1"))

record is a gove_zone.decision.DecisionRecord; hand it to gove-zone's own ChainHashAuditStore / DecisionReceipt.from_record / execute_with_receipt to reach a signed, gated execution — see tests/gove/test_conformance_e2e.py for the full, working chain.

Honest limitations:

• Legacy legitimacy receipts and gove-zone receipts are distinct formats with incompatible canonicalizations. They are not interchangeable and the bridge does not convert between them.
• The bridge does not translate old evidence. Legitimacy DecisionReceipt records already on disk are not migrated or replayed into gove-zone's audit chain; each governance pipeline keeps its own history.
• Single-use / expiry enforcement comes from gove-zone's own ledger, not from ExecutionBoundary.single_use. The legacy ExecutionBoundary dataclass's single_use field is not read or enforced anywhere in this bridge; replay/expiry protection for gove-zone-gated calls is entirely gove-zone's responsibility.
• The 8-state acgs-lite decision taxonomy is projected onto gove-zone's 4 verdicts (decision_state_to_gove); the original state is preserved as a reason prefix, not as a first-class gove-zone field.
• ConstitutionPolicy matches on a deterministic text projection of the ToolCall (name + canonical JSON of args + goal), not on the structured arguments directly — constitutions authored for prose actions should target tool names and argument keys to match reliably.
• gove-zone itself is pre-1.0 (1.0.0rc2); its API may change before a stable release.

🔒 Safety Defaults

The default strict GovernanceEngine blocks matching rules. Execution guarantees depend on the selected entry point and profile; compatibility receipts and best-effort audit writes provide weaker guarantees than the source candidate's configured production grant path.

Note: The MCP integration above is non-mutating: it passes validate(strict=False) per call and never touches engine.strict, so concurrent callers and shared engines are unaffected. Other integrations that need per-call non-strict validation should prefer engine.validate(..., strict=False) over engine.non_strict() for the same reason — non_strict() mutates shared state and is unsafe under concurrency.

To opt into fail-open (e.g., for testing), you must set it explicitly:

engine = GovernanceEngine(constitution, strict=False)  # explicit; off by default

Enforcement actions progress from least to most restrictive: warn → block → block_and_notify → require_human_review → escalate_to_senior → halt_and_alert

🗺️ Component Stability

Not all layers are equally hardened. Use this table to calibrate trust in each area:

Stable surfaces today (2.12.0 published)

This table describes library surfaces with stable APIs and test coverage. It is not a blanket production-readiness claim for every deployment.

Everything else (constitution lifecycle API, formal verification with Z3/Lean, 20-framework compliance mapping) is Beta / Experimental and clearly marked in the Component Stability table above.

🏭 Production users

No independently confirmed production users yet.

🌐 Integrations

By default, when output validation is enabled, GovernedAgent injects a provider-specific structured-output request only for model/provider pairs with current documented support in the bundled capability manifest. Unsupported or unverified pairs receive no injected request shape; for example, GPT-4 is pinned as unsupported. Validate evidence freshness with acgs capabilities validate --max-age-days 45.

OpenAI

from acgs_lite.integrations.openai import GovernedOpenAI

client = GovernedOpenAI(constitution=constitution)
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Analyze the contract"}],
)

Anthropic Claude

from acgs_lite.integrations.anthropic import GovernedAnthropic

client = GovernedAnthropic(constitution=constitution)
message = client.messages.create(
    model="claude-opus-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Review this code"}],
)

LangChain

from acgs_lite.integrations.langchain import GovernanceRunnable
from langchain_openai import ChatOpenAI

governed_llm = GovernanceRunnable(
    ChatOpenAI(model="gpt-4o"),
    constitution=constitution,
)
result = governed_llm.invoke("Translate this document")

MCP Server

Start a governance server that any MCP-compatible agent can query:

acgs serve --host 0.0.0.0 --port 8080

from acgs_lite.integrations.mcp_server import create_mcp_server
app = create_mcp_server(constitution=constitution)

📋 Compliance Coverage

acgs assess produces a self-assessed mapping of library controls to external frameworks. Ratios below are mapping coverage only. They are not certification, regulatory approval, adoption proof, or a substitute for legal review.

acgs assess --framework eu-ai-act --output report.pdf

🔬 Advanced: Formal Verification

For the highest-risk scenarios, ACGS supports mathematical proof of safety properties.

Z3 SMT Solver

from acgs_lite.z3_verify import VerificationStatus, Z3ConstraintVerifier

verifier = Z3ConstraintVerifier()
result = verifier.verify(
    action="read an approved account",
    context={"environment": "staging", "authenticated": True},
)
print(result.verified, result.satisfiable, result.counterexample)
if result.status is VerificationStatus.UNAVAILABLE:
    assert result.verified is False
    print("NOT VERIFIED: install acgs-lite[z3]; execution remains blocked")
else:
    assert result.status is VerificationStatus.PASS

Lean 4 Proof Certificates (Leanstral)

from acgs_lite import LeanstralVerifier

verifier = LeanstralVerifier()  # requires mistralai extra
result = verifier.verify(
    action="transfer $5,000",
    rules=[{"id": "limit", "text": "Transfers must not exceed $10,000"}],
    context={"action": "transfer $5,000"},
)
print(result.verified)  # False unless the external Lean kernel accepted the proof
if result.certificate is not None:
    print(result.certificate.to_audit_dict())

⚡ Performance

🖥️ CLI

# Validate a single action
acgs validate "send email to user@corp.com" --constitution rules.yaml

# Run governance status check
acgs status

# Generate compliance report
acgs assess --framework hipaa --output hipaa_report.pdf

# Audit log inspection
acgs audit --tail 20
acgs audit --verify-chain

# Start MCP governance server
acgs serve --port 8080

# EU AI Act Art. 14(4)(e) kill switch
acgs halt --agent-id agent-01 --reason "anomalous behaviour detected"
acgs resume --agent-id agent-01

📖 Documentation

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

git clone https://github.com/acgs-ai/acgs-lite.git
cd acgs-lite
pip install -e ".[dev]"
pytest tests/ --import-mode=importlib

📄 License

Apache-2.0. See LICENSE for details.

Commercial enterprise licences (SLA, support, air-gapped deployment) available at acgs.ai.

Constitutional Hash: 608508a9bd224290 — embedded in every validation path.