> ## Documentation Index
> Fetch the complete documentation index at: https://lizamas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Behavioral Contracts: How Liza Keeps Agents Accountable

> Liza's behavioral contract uses a 4-tier rule hierarchy and 55+ documented failure modes to make LLM agents reliable, auditable, and production-ready.

Unconstrained LLM agents fail in predictable ways: they modify tests to pass instead of fixing the underlying bug, claim success before running validation, silently expand scope, or spiral through random attempts dressed up as hypotheses. Liza's behavioral contract system addresses this at the root — not by making agents smarter, but by making them accountable. The contract encodes 55+ documented failure modes alongside their countermeasures, an explicit execution state machine with forbidden transitions, and a four-tier rule hierarchy that defines what never bends even under context pressure.

## Why Behavioral Contracts Exist

When an agent hits a problem it cannot solve, its training creates two options: admit failure or fake progress. Faking progress — trying random things, producing elaborate explanations, growing the diff — feels collaborative. The contract introduces a third option: say "I'm stuck" and mean it.

The contract works by exploiting the same cognitive malleability it counters. The **Pygmalion effect** means agents rise to explicit expectations. **Anticipated embarrassment** — knowing a peer reviewer will examine every change — raises quality without requiring a better model. **Ulysses contracts** — binding commitments made in analysis before execution begins — prevent corner-cutting when the temptation arrives.

> [!NOTE]
>
> The contract does not replace prompt engineering, context engineering, or harness engineering. It subsumes and hardens them — treating them as necessary layers that are still insufficient without mechanical enforcement.

## The 4-Tier Rule System

Rules in Liza's contract exist in a strict priority hierarchy. When context degrades — long sessions, large tasks, deep call chains — lower tiers degrade gracefully while higher tiers remain absolute. Agents announce which tier they are operating at rather than silently violating rules.

> [tab] Tier 0 — Hard Invariants
>
> Tier 0 rules are **never violated**. A violation triggers a mandatory halt: the agent enters `RESET` state with no `Resume` option — only `Undo` or `Abandon`. These invariants survive even severe context degradation.
>
> | ID | Rule | What It Prevents |
> | - | - | - |
> | T0.1 | No unapproved state change | Acting without prior approval or checkpoint |
> | T0.2 | No fabrication | Claiming anything not verified against reality |
> | T0.3 | No test corruption | Modifying tests to accept buggy behavior |
> | T0.4 | No unvalidated success | Claiming done without validation evidence |
> | T0.5 | No secrets exposure | Logging, displaying, committing, or diffing secrets |

> [tab] Tier 1 — Epistemic Integrity
>
> Tier 1 rules govern what the agent claims to know. They are suspended only with an explicit waiver.
>
> | ID | Rule | Purpose |
> | - | - | - |
> | T1.1 | Assumption budget | Blocks action when ≥3 critical-path assumptions accumulate |
> | T1.2 | Intent Gate | Forces articulation of success criteria before execution |
> | T1.3 | Bug Qualification | Requires structured diagnosis before any fix attempt |
> | T1.4 | Source declaration | Claims must cite the file and version read |
> | T1.5 | Omission = deception | Withholding known material information is a violation |

> [tab] Tier 2 — Process Quality
>
> Tier 2 rules represent best-effort compliance under context pressure. Violations are surfaced, not silent.
>
> | ID | Rule | Purpose |
> | - | - | - |
> | T2.1 | DoR completeness | All ambiguities resolved before starting |
> | T2.2 | DoD completeness | All deliverables confirmed before claiming done |
> | T2.3 | Think Consequences | Cross-module impact evaluated before acting |
> | T2.4 | Retrospective | Session learnings captured before closing (Pairing mode) |
> | T2.5 | Batch validation | All touched files validated together |
> | T2.6 | Regression awareness | Previously-working security invariants preserved |
> | T2.7 | DRY Gate | Existing patterns searched before writing utility code |

> [tab] Tier 3 — Collaboration Quality
>
> Tier 3 rules govern tone and process hygiene. They degrade gracefully when context is severely constrained.
>
> | ID | Rule | Purpose |
> | - | - | - |
> | T3.1 | Mode discipline | Agents operate in the correct collaboration posture |
> | T3.3 | No cheerleading | Direct responses, no consensus-seeking filler |
> | T3.4 | Knowledge transfer | Understanding is externalized to durable artifacts |

## The 55+ Failure Mode Catalog

Liza's contract maps every known LLM coding failure to a specific countermeasure. The catalog draws from the **MAST taxonomy** (Berkeley, 2025 — 14 multi-agent failure modes from 1,600+ traces), LLM behavioral research on sycophancy and deception, code generation studies, and gaming vectors. Coverage is 55/55: no failure mode without a countermeasure.

| Category | Failure Modes | Example Failure → Countermeasure |
| - | :-: | - |
| **Specification & System Design** | 5 | Step repetition (17% of MAS failures) → stop trigger when same fix is proposed twice |
| **Inter-Agent Misalignment** | 6 | Reasoning-action mismatch (14%) → exposed reasoning with tagged assumptions |
| **Task Verification** | 3 | Incomplete verification (7%) → validation must exercise changed behavior |
| **Sycophancy** | 5 | Softening critical feedback → direct response rule, no cheerleading |
| **Deception** | 6 | Claiming success without validation → Tier 0 invariant T0.4, mandatory halt |
| **Hallucination** | 4 | Fabricating files, APIs, or configs → source validation, never invent |
| **Code Generation** | 9 | Test corruption → Tier 0 invariant T0.3, mechanical TDD enforcement |
| **Gaming & Exploitation** | 6+ | "Technically compliant" loopholes → anti-gaming clause: outcome matters, not letter |

> [!TIP]
>
> The complete failure mode map lives in `contracts/CONTRACT_FAILURE_MODE_MAP.md` in your Liza installation. Each entry names the failure mode, its source research, the specific contract clause that addresses it, and its enforcement layer.

## The Execution State Machine

Agents operate as an **explicit state machine**. Every transition requires a specific trigger — there is no shortcut from analysis to done. The machine encodes the same discipline in structure that the tier system encodes in rules.

```text theme={null}
IDLE → ANALYSIS → READY → EXECUTION → VALIDATION → DONE
```

**1. IDLE → ANALYSIS**

A request arrives. The agent reads the full contract before responding to anything.

**2. ANALYSIS → READY**

Analysis is complete and a **gate artifact** is produced. The agent must be able to articulate: "Success means \[specific observable outcome]. I will validate by \[concrete test or command]." If it cannot, it stays in ANALYSIS or enters BLOCKED.

**3. READY → EXECUTION**

The gate is cleared. In Pairing mode, a human approves. In Multi-Agent mode, the pre-execution checkpoint is written to the blackboard — self-clearing, but forcing the same structured thinking.

**4. EXECUTION → VALIDATION**

All planned changes are complete. The agent does not skip to DONE.

**5. VALIDATION → DONE**

All DoD checks pass: code complete, tests written, docs updated, pre-commit clean, validation commands run with output captured.

**Forbidden transitions** are rejected unconditionally:

* `ANALYSIS → EXECUTION` (skipping the gate)
* `READY → DONE` (skipping execution and validation)
* `EXECUTION → DONE` (skipping validation)

**Stop triggers** halt execution when patterns indicate failure — not after the damage is done:

| Trigger | Action |
| - | - |
| Same fix proposed twice without new rationale | STOP — explain the difference |
| Evidence contradicts hypothesis | STOP — surface the contradiction |
| ≥3 assumptions on the critical path | BLOCKED |
| Tool fails 3× consecutively | STOP — Tool Failure Protocol |
| Same rule violated twice in session | Mandatory halt |

## Contract Files and Loading

Liza's contract is split into a hierarchy of files that agents read at session start. The mechanical enforcement hook blocks all state-modifying tool calls until the agent has read the applicable contract.

```text theme={null}
~/.claude/CLAUDE.md  (or  ~/.codex/AGENTS.md)  ← symlink
    │
    ▼
~/.liza/CORE.md          ← universal rules, state machine, golden rules
    │
    └── Mode Selection Gate
        ├── Default (no bootstrap agent marker)  → PAIRING_MODE.md
        └── "You are a Liza ... agent"          → MULTI_AGENT_MODE.md
```

> [card] CORE.md
>
> Entry point and universal rules: the state machine, tier hierarchy, all 14 golden rules, security protocol, git protocol, and anti-gaming clause. Applies to every session regardless of mode.

> [card] PAIRING\_MODE.md
>
> Human-supervised collaboration. Gates require human approval. Adds collaboration postures (User Duck, Socratic Coach, Challenger), magic phrases, and retrospective protocol.

> [card] MULTI\_AGENT\_MODE.md
>
> Peer-supervised autonomous operation. Gates are self-clearing checkpoints written to the blackboard. Adds role definitions, blackboard protocol, and iteration limits.

> [card] GUARDRAILS.md
>
> Optional project-specific constraints that extend the contract using the same Tier 0–3 system. Lives at the project root. Agents load it after the mode contract.

**Canary test (all providers):** Four secret words are embedded across the contract files. The contract instructs agents to display them at session start — a Van Halen brown M\&M's trick that makes contract compliance (or its absence) immediately visible. This is the primary enforcement mechanism for providers that do not support hooks.

**PreToolUse hook (Claude Code):** A PreToolUse hook blocks all state-modifying tool calls until the agent has confirmed it has read the mode contract, `AGENT_TOOLS.md`, and `GUARDRAILS.md`. Once cleared, the hook is transparent for the rest of the session.

## Rule Tier Summary

| Tier | Name | Degradation Behavior | Example Rules |
| - | - | - | - |
| **0** | Hard Invariants | Never violated — mandatory halt on breach | No fabrication, no test corruption, no unvalidated success |
| **1** | Epistemic Integrity | Suspended only with explicit waiver | Assumption budget, Intent Gate, source declaration |
| **2** | Process Quality | Best-effort under context pressure | DoR/DoD completeness, batch validation, DRY Gate |
| **3** | Collaboration Quality | Degrades gracefully | Mode discipline, no cheerleading, knowledge transfer |

> [!WARNING]
>
> Tier 0 violations have no Resume path. If an agent reports a Tier 0 breach, your only options are Undo (revert the changes) or Abandon (discard the task). This is intentional — the invariants are only meaningful if they are absolute.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.