Add Officer Clancy Budget Guardian for AI agent resource management

README.md

@@ -134,12 +134,32 @@ uv run ralph --mcp --transport http --host 127.0.0.1 --port 8000
 
 - `ralph.sh` - Wrapper with preflight checks (`uv sync`, TaskMaster bootstrap, gitignore checks)
 - `ralph/` - Python implementation and CLI
+- `ralph/budget_guardian.py` - Officer Clancy budget guardian module
 - `OPERATIONS.md` - Operational reference
 - `.taskmaster/tasks/tasks.json` - TaskMaster task data
 - `skills/ralph-prd/` - Source for the `/ralph-prd` skill
 - `skills/ralph/` - Source for the `/ralph` conversion skill
+- `skills/officer-clancy/` - Source for the Officer Clancy budget guardian skill
 - `flowchart/` - Interactive visualization source
 
+## Officer Clancy: Budget Guardian
+
+Ralph includes Officer Clancy, a budget guardian that prevents runaway agent loops by:
+
+- **Tracking attempts**: Limits the number of task retry attempts
+- **Managing budgets**: Sets computational/time budgets with escalation alerts
+- **Preventing infinite loops**: Automatically stops execution when limits are exceeded
+
+Configure via environment variables:
+
+```bash
+export RALPH_BUDGET_ENABLED=true
+export RALPH_MAX_ATTEMPTS=10
+export RALPH_BUDGET_LIMIT=100.0
+```
+
+See [Officer Clancy skill documentation](skills/officer-clancy/SKILL.md) for detailed usage.
+
 ## Flowchart
 
 Flowchart source lives in `flowchart/`:

justfile

@@ -8,6 +8,10 @@ ralph TOOL ITERATIONS='10':
 ralph-test:
     uv run pytest tests/test_ralph*
 
+# Run budget guardian tests
+ralph-test-budget:
+    uv run pytest tests/test_budget_guardian.py -v
+
 # Type check and lint ralph module
 ralph-check:
     uv run mypy --strict ralph/ && uv run ruff check ralph/
@@ -56,6 +60,14 @@ ralph-tasks-active:
 ralph-dry-run TOOL='amp' ITERATIONS='10':
     uv run ralph run --tool {{TOOL}} --max-iterations {{ITERATIONS}} --dry-run
 
+# Run ralph with Officer Clancy budget limits
+ralph-budget TOOL='amp' ITERATIONS='10' MAX_ATTEMPTS='5' BUDGET='50':
+    RALPH_MAX_ATTEMPTS={{MAX_ATTEMPTS}} RALPH_BUDGET_LIMIT={{BUDGET}} uv run ralph run --tool {{TOOL}} --max-iterations {{ITERATIONS}}
+
+# Run ralph with budget guardian disabled
+ralph-no-budget TOOL='amp' ITERATIONS='10':
+    RALPH_BUDGET_ENABLED=false uv run ralph run --tool {{TOOL}} --max-iterations {{ITERATIONS}}
+
 # Run ralph as MCP server (stdio transport)
 ralph-mcp:
     uv run ralph --mcp

ralph/README.md

@@ -153,6 +153,20 @@ Ralph supports the following environment variables for configuration:
 | `OPENCODE_EXTRA_ARGS` | Additional opencode arguments | (empty) |
 | `TASKMASTER_URL` | TaskMaster server URL (if using MCP) | (empty, uses file-based) |
 
+### Officer Clancy Budget Guardian
+
+Ralph includes Officer Clancy, a budget guardian that prevents runaway agent loops. **Disabled by default** (opt-in):
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `RALPH_BUDGET_ENABLED` | Enable budget guardian | `false` |
+| `RALPH_MAX_ATTEMPTS` | Maximum task attempts | `10` |
+| `RALPH_BUDGET_LIMIT` | Total budget limit (abstract units) | `100.0` |
+| `RALPH_COST_PER_ATTEMPT` | Cost deducted per attempt | `10.0` |
+| `RALPH_BUDGET_ALLOW_OVERFLOW` | Allow exceeding budget with warning | `false` |
+
+See [Officer Clancy skill documentation](../skills/officer-clancy/SKILL.md) for detailed usage.
+
 ### Example: Custom Codex Configuration
 
 ```bash