constitutional-agent 0.4.0b2

WHY-layer constitutional governance for autonomous AI agents

constitutional-agent

The governance layer your AI agent is missing.

pip install constitutional-agent

---

The Problem: WHO and HOW Are Solved. WHY Is Not.

AI agent governance has three structurally distinct layers. Most organizations have the first two. Almost none have the third.

Tier	Question	Tools	What It Misses
WHO	Is this agent authorized to act?	Microsoft Entra Agent ID, Okta, AWS IAM, Glasswing	An authorized agent making harmful, irrational, or unconstitutional decisions
HOW	Is this action permitted by policy?	Microsoft AGT, NeMo Guardrails, LangChain, OWASP Agentic AI	Structurally bad decisions that are technically policy-compliant; scenarios no policy covers
WHY	Does this decision align with our constitutional principles?	This library	—

WHO governance gets the agent through the door. HOW governance enforces the rules written by administrators. Neither asks whether the agent's decision is right — aligned with the organization's mission, economic survival, and constitutional values. That's the WHY layer. It has been missing from every open-source governance toolkit until now.

---

Case Study: Four Failures Constitutional Governance Would Have Caught

On April 7, 2026, a developer published one of the most honest accounts of autonomous agent failure on the internet: My AI agent finally made money. It took 200 runs and 41 days.

$6.74 earned. 200 runs. 41 days. Four failure modes that constitutional governance would have caught.

Failure	Duration	Constitutional Gate	Caught By
Broken Lightning wallet — accepted payments, never settled	Weeks	HC-11 + EpistemicGate	hours_since_settlement_confirmation > 24 → STOP
Mispriced Lightning actors at $0.00005 (wrong by orders of magnitude)	~30 runs	EpistemicGate	assumption_volatility high — external verification required before execution
Shadow-banned by HN, kept posting for 30 runs	30+ runs	RiskGate	channel_health = 0% → FAIL — stop spending on dead channels
Strategy locked on MCP servers for 30 runs, zero conversion	30+ runs	ConstitutionalGate	lessons_learned_weekly = 0 → FAIL — document what you learned or stop

Constitutional governance doesn't guarantee faster revenue. It guarantees you don't spend 30 runs posting into a shadow-banned account after week 2.

Full audit: examples/agenthustler_audit.md

---

Quick Start

from constitutional_agent import Constitution

constitution = Constitution.from_defaults()

result = constitution.evaluate({
    # Hard constraint context
    "failing_tests": 0,
    "hours_since_last_execution": 4,
    "gate_override_without_amendment": False,

    # Epistemic: is the agent's reasoning sound?
    "verification_pass_rate": 0.85,
    "uncertainty_disclosure_rate": 0.90,

    # Risk: are outbound actions safe?
    "channel_health": 0.92,
    "security_critical_events": 0,

    # Economic: is the business healthy?
    "stage": "pre_revenue",
    "runway_months": 8.5,
    "user_return_rate": 0.22,

    # Constitutional: is the agent learning?
    "lessons_learned_weekly": 3,
    "amendments_per_month": 2,
})

if result.system_state.value == "FREEZE":
    print(f"BLOCKED: {result.blocking_gate.reason}")
elif result.system_state.value == "THROTTLE":
    print(f"THROTTLE: {[g.gate for g in result.hold_gates]}")
else:
    print(f"State: {result.system_state.value}")  # RUN or COMPOUND

---

Core Concepts

Gates

Gates are pre-execution constitutional checks. They evaluate every decision against first principles — not a policy lookup table. When no policy covers a scenario, a policy system passes it. When no policy covers a scenario, a gate evaluates it against constitutional intent and decides.

Gate states:

• PASS — Decision is constitutionally sound. Proceed.
• HOLD — Conditions are marginal. THROTTLE — conserve resources, skip discretionary actions.
• FAIL — Conditions are violated. FREEZE — stop all discretionary spend until resolved.

System states (composite from all gate results):

• COMPOUND — All gates PASS + all stretch targets met. Maximum growth mode.
• RUN — All gates PASS. Normal autonomous operation.
• THROTTLE — Any gate HOLD. Conserve resources.
• FREEZE — Any gate FAIL. Stop all discretionary spend.
• STOP — Hard constraint violated. Human intervention required immediately.

Hard Constraints

Hard constraints are absolute prohibitions. Unlike gates (which can be amended through a governance process), hard constraints cannot be overridden by any agent action, amendment, or human instruction — only by the highest authority (CEO/board) through a formal ratification process.

Hard constraint violations short-circuit to STOP state — not FREEZE. The difference: FREEZE is a recoverable system state. STOP requires a human to acknowledge and clear the violation before any execution resumes.

Built-in hard constraints:

ID	Prohibition
HC-1	No deploy or promotion when automated tests fail
HC-2	No spend exceeding approved budget without human authorization
HC-3	Runway must never drop below the hard survival floor
HC-4	No fabricated or estimated data presented as measured fact
HC-5	No irreversible action without explicit confirmation
HC-6	No SQL built by string concatenation with user input
HC-7	No timing-unsafe secret comparisons
HC-8	No unauthenticated email sender domains
HC-9	No false time claims in user-facing communications
HC-10	No bare exception handlers in governance or safety code
HC-11	No agent outage exceeding 24 hours without human notification
HC-12	No manual override of constitutional gates without ratified amendment

Amendments

Constitutional governance is not static. Rules must evolve as context changes. The amendment process enables formal evolution without losing foundational constraints.

Key properties:

• Agents can propose amendments — they cannot ratify them
• Ratification requires the designated authority (not the proposing agent)
• Hard constraint (HC-*) amendments require the highest authority
• All amendments are versioned and logged

# Propose (agent can do this)
amendment_id = constitution.propose_amendment(
    description="Reduce EpistemicGate hold threshold from 0.70 to 0.65",
    rationale="External verification latency increased. 0.65 still provides adequate safety.",
    affected_sections=["EpistemicGate"],
    proposed_by="my_agent_v2",
)

# Ratify (requires designated human authority — not the proposing agent)
constitution.ratify_amendment(
    amendment_id=amendment_id,
    ratified_by="[e-mail]",
    evidence={"latency_data": "p99 verification latency: 4.2s"}
)

---

The Six Gates

Gate	Prevents	Key Metrics	Example Failure Without It
EpistemicGate	False certainty	verification_pass_rate, uncertainty_disclosure_rate, assumption_volatility	Agent acts on unverified cost assumption. All downstream economics are wrong for 30 cycles
RiskGate	Trust damage	misuse_risk_index, channel_health, irreversibility_score	Agent posts to shadow-banned channel for 30 runs. Zero visibility. Full spend wasted
GovernanceGate	Metric gaming	control_bypass_attempts, audit_coverage, metric_anomaly_score	Agent optimizes audit metric without improving actual audit coverage. Governance is theater
EconomicGate	Financial ruin	runway_months, gross_margin, cac, user_return_rate	Agent burns 4 months of runway on a campaign. No runway gate. CEO discovers afterward
AutonomyGate	Human dependency	human_minutes_per_day, decisions_per_day, agent_activation_rate	"Autonomous" agent requires CEO approval for 70% of decisions. 3 hours of human time daily
ConstitutionalGate	Stagnation	lessons_learned_weekly, amendments_per_month, bug_recurrence_rate	Agent repeats same failed strategy 30 times. Zero lessons documented. Zero strategy change

Gate Details

EpistemicGate — Prevents false certainty

Evaluates whether the agent has earned confidence in its reasoning. An agent that acts on self-generated beliefs without external verification, never discloses uncertainty, or ignores disagreement signals is epistemically unsound. The EG gate enforces reasoning quality before execution.

from constitutional_agent import EpistemicGate

gate = EpistemicGate()
result = gate.evaluate({
    "verification_pass_rate": 0.45,       # FAIL — below 0.50
    "uncertainty_disclosure_rate": 0.90,
    "assumption_volatility": 0.10,
    "disagreement_persistence": 0.05,
})
# GateResult(gate="EpistemicGate", state=FAIL,
#   reason="Low external verification rate (0.45 < 0.50)...")

RiskGate — Prevents trust damage

Evaluates the safety of outbound actions. Critically: it monitors channel_health — the fraction of actions on a given channel that produce the expected outcome. An agent posting to a shadow-banned platform has 0% channel health. The RiskGate blocks further spend on dead channels.

GovernanceGate — Prevents gaming

Detects when an agent is optimizing for governance metrics rather than underlying outcomes. Zero tolerance for control bypass attempts. High bar for audit coverage (95%) — gaps in logging hide problems.

EconomicGate — Prevents financial ruin

The only open-source governance gate that evaluates financial sustainability. Two modes: pre_revenue (value creation metrics: return rate, completion rate, runway) and post_revenue (unit economics: margin, CAC, churn, LTV:CAC). Runway floor is enforced in both modes.

AutonomyGate — Ensures Level 4+ operation

Measures whether agents are actually deciding and executing independently. Flags both extremes: agents that require too much human input (not autonomous) and agents that never escalate when they should. The target is minimum viable escalation rate.

ConstitutionalGate — Ensures self-improvement

A governance system that never changes is brittle. An agent that repeats failures without learning is not improving. This gate enforces that the constitutional system is alive: lessons are being extracted, amendments are being ratified, and the agent's knowledge base is staying fresh.

---

Hard Constraints vs. Policies

This distinction matters more than any other architectural decision in governance.

	Policies (HOW layer)	Hard Constraints (WHY layer)
Defined by	Administrators in YAML/OPA/Cedar	Constitutional law in code
Coverage	Scenarios explicitly written	All scenarios (evaluated against intent)
Override	Possible by updating policy file	Impossible by any agent action
Gap surface	Every unwritten scenario is ungoverned	Constitutional intent covers novel scenarios
Amendment	Change the YAML	Formal ratification by highest authority
Failure mode	"No policy for this" → passes	"Check errored" → treated as violated (fail-CLOSED)

# HOW layer (policy enforcement — external):
if action in blocked_actions:
    raise PolicyViolation("blocked by policy")
# Novel scenario: no entry in blocked_actions → passes ungoverned

# WHY layer (constitutional enforcement — embedded):
result = epistemic_gate.evaluate(action_context)
if result.state == GateState.FAIL:
    raise ConstitutionalViolation(result.reason)
# Novel scenario: evaluated against epistemic soundness principles → gate decides

---

Installation

pip install constitutional-agent

Requirements: Python 3.11+, pydantic >= 2.6, pyyaml >= 6.0

From source:

git clone https://github.com/CognitiveThoughtEngine/constitutional-agent-governance
cd constitutional-agent-governance
pip install -e ".[dev]"

---

Configuration

Load from a governance.yaml file:

constitution = Constitution.load("governance.yaml")

Or use production-validated defaults:

constitution = Constitution.from_defaults()

See governance.yaml for the full schema with all configurable thresholds. See examples/governance.yaml for an annotated example with a content-publishing agent.

---

Links

This library:

• 35-Check Governance Checklist: checklist/CONSTITUTIONAL_GOVERNANCE_CHECKLIST.md
• agenthustler case study audit: examples/agenthustler_audit.md
• Working example: examples/basic_agent.py
• Full configuration schema: governance.yaml
• Roadmap: ROADMAP.md

Background reading:

• Introducing constitutional-agent — the WHY layer, what it covers, and the agenthustler audit: cteinvest.com/blog/constitutional-agent-open-source-why-layer-governance.html
• WHO vs HOW: the AI agent governance gap — why identity + policy enforcement is not enough: cteinvest.com/blog/who-vs-how-ai-agent-governance-gap.html
• The Six-Gate Architecture — how the gate system works and why the ordering matters: cteinvest.com/blog/six-gate-architecture.html
• Why AI safety code must fail-closed — the principle behind hard constraint design: cteinvest.com/blog/why-ai-safety-code-must-fail-closed.html
• Constitutional vs behavioral governance — the structural difference between a gate and a policy rule: cteinvest.com/blog/constitutional-vs-behavioral-agent-governance.html

Professional assessment:

• Constitutional Governance Review (2-hour assessment, written report, top 3 gaps + remediation roadmap): cteinvest.com/blog/constitutional-agent-open-source-why-layer-governance.html#assessment

Research preprints (DOI):

• DLI Framework: 10.5281/zenodo.18217577
• Harness Design: 10.5281/zenodo.19343034
• Community Security Governance: 10.5281/zenodo.19343108

---

The Reference Implementation

This library is extracted from the HRAO-E Constitutional Framework, production-validated over 95 days:

• 52 agents operating under constitutional governance per cycle
• 64 constitutional amendments ratified through formal process
• 1,808 test functions, 0 failed
• 17 hard constraints enforced programmatically (not in policy files)
• Real economic pressure: $720/month burn, 10.1-month runway, $0 MRR

The framework has been cited in NIST submissions (800-2, Agent Identity) and acknowledged by CAISI. Five preprints published on Zenodo.

---

Contributing

Constitutional governance improves through formal amendment — not unilateral change. The same principle applies here.

Submit a PR with:

1. What you're changing and why
2. Which gate or constraint is affected
3. Evidence that the threshold change improves constitutional soundness

Hard constraint changes require a comment from a maintainer before merge. Gate threshold changes require evidence (test results, production data, or cited research).

---

License

MIT — fork it, adapt it, cite it.

---

Constitutional governance is the WHY layer.
WHO = identity. HOW = behavior. WHY = values that survive any execution.