turing-pyramid

Motivation and action system for AI agents. 10 needs with Turing-exp tension, execution gate with evidence verification, spontaneity layers, continuity across sessions, and crash-resilient watchdog.

# 🔺 Turing Pyramid

**What it does:** Gives your agent a motivation system. 10 needs (security, connection, expression...) build tension over time via decay. Each heartbeat, the pyramid evaluates tensions, selects actions, and tells the agent what to do — from "check system health" to "write something creative."

**What it is NOT:** A chatbot framework, an executor, or a system management tool.

**Three layers with different scopes:**

| Layer | Scripts | Scope | System effects |
|-------|---------|-------|----------------|
| **Motivation** | `run-cycle.sh`, `mark-satisfied.sh`, `init.sh` | Read workspace files, write own state JSON | None — pure suggestion engine |
| **Continuity** | `mindstate-daemon.sh`, `mindstate-freeze.sh`, `mindstate-boot.sh` | Read workspace + own state, write MINDSTATE.md | Read-only system checks: `pgrep` (gateway alive?), `df` (disk usage). No writes outside workspace. |
| **Resilience** | `mindstate-watchdog.sh` | Monitor continuity scripts | **Default: detect + log only.** With `allow_kill: true`: terminates hung `mindstate-*.sh` processes (path-anchored, never other PIDs). With `allow_cleanup: true`: deletes orphan `.tmp` files in workspace + assets dir. Auto-freeze is always safe. |

Core motivation scripts make **zero network calls**. Optional `external-model` scan method (disabled by default) can call an inference API if explicitly enabled by steward. The continuity daemon performs lightweight local system checks (read-only). The watchdog **detects and logs by default** — destructive actions (`kill`, `delete`) require explicit opt-in via config.

**v1.27.0** — Execution Gate: structural enforcement that prevents agents from describing actions instead of doing them. Turing-exp tension formula: equal rotation at homeostasis, hierarchy only in crisis.

---

## 🚀 Quick Start

```bash
# 1. Set workspace (REQUIRED)
export WORKSPACE="/path/to/your/agent/workspace"

# 2. Fix permissions (ClawHub doesn't preserve +x)
chmod +x <skill-dir>/scripts/*.sh
chmod +x <skill-dir>/tests/**/*.sh

# 3. Initialize
bash scripts/init.sh

# 4. Run a cycle
bash scripts/run-cycle.sh

# 5. After completing an action
bash scripts/mark-satisfied.sh <need> <impact>
# Example: bash scripts/mark-satisfied.sh connection 1.5
```

Add to `HEARTBEAT.md` for automatic operation:
```bash
bash /path/to/skills/turing-pyramid/scripts/run-cycle.sh
```

### Deployment Tiers

Choose the level of integration that matches your trust and needs:

| Tier | Components | System effects | Risk |
|------|-----------|----------------|------|
| **1. Interactive only** | `run-cycle.sh`, `mark-satisfied.sh`, `gate-*.sh` | Reads workspace, writes own state JSON | Minimal — no system interaction |
| **2. + Heartbeat** | Tier 1 + `run-cycle.sh` in HEARTBEAT.md | Same as Tier 1, triggered by agent runtime | Low — no cron, no process management |
| **3. + Continuity** | Tier 2 + `mindstate-daemon.sh` in cron (*/5) | Adds `pgrep` (read-only), `df` (read-only), writes MINDSTATE.md | Moderate — cron persistence, read-only system checks |
| **4. + Watchdog (detect)** | Tier 3 + `mindstate-watchdog.sh` in cron (*/15) | Detects hung processes and orphan files, **logs only** (default). Auto-freezes stale cognition | Moderate — detection only, no destructive actions |
| **5. Full self-healing** | Tier 4 + `allow_kill: true` + `allow_cleanup: true` | Kills hung skill processes, deletes orphan `.tmp` files | Higher — requires script review |

**Start at Tier 1 or 2.** Upgrade after reviewing scripts and running the test suite in an isolated workspace. You get full motivation/action selection at Tier 1 — everything above is optional. Tier 4 (watchdog with defaults) is safe to enable without review since it only detects and logs.

---

## 🎓 Onboarding Guide

### For the Agent

When you first install this skill:

1. **Read this file** to understand the 10 needs and how tension works
2. **Run `init.sh`** to create initial state files
3. **Run one cycle** (`run-cycle.sh`) — it proposes actions and registers them in the execution gate
4. **Actually do the action** — write the file, make the post, run the command
5. **Resolve the gate** (`gate-resolve.sh --need <need> --evidence "what you did"`)
6. **Mark satisfaction** (`mark-satisfied.sh <need> <impact>`)
7. **Integrate into heartbeat** — add `run-cycle.sh` to your HEARTBEAT.md

**Important:** The execution gate blocks new proposals until you resolve or defer pending actions. This is by design — it prevents you from describing actions instead of doing them. If you can't complete an action, defer it with a reason: `gate-resolve.sh --defer <id> --reason "why"`.

The system is self-tuning. After a few cycles, you'll see patterns: which needs decay fast, which actions are selected, where tensions build.

**Key concepts:**
- **Satisfaction** (0.5–3.0): How fulfilled a need is. 3.0 = perfect, 0.5 = crisis (floor)
- **Tension** = dep² + importance × max(0, dep - threshold)². Equal at homeostasis, hierarchy in crisis.
- **Decay**: Satisfaction drops over time at need-specific rates. Connection decays in 6h. Security in 168h.
- **Actions**: Each need has 8-11 possible actions with impact levels (low/mid/high). The pyramid picks based on current state.

**Resilience:** After setup, verify your cron has both entries (daemon + watchdog). The watchdog catches edge cases — daemon crashes, hung processes, stale state. See "Resilience & Crash Recovery" section for details.

### For the Human (Steward)

**Before your agent starts using this:**

1. **Review the 10 needs** (table below) — are importance rankings right for your agent?
2. **Check scan config** — default `line-level` is free and works everywhere. Upgrade to `agent-spawn` if you have a cheap model (Haiku) available.
3. **External actions** — some suggestions mention external platforms (social networks, web search). These are *text suggestions only*. To remove: set their `weight: 0` in `needs-config.json`.
4. **Run the test suite** to verify everything works:
   ```bash
   WORKSPACE=/tmp/test-workspace bash tests/run-tests.sh
   ```

**Configuration conversation with your agent:**
- "Review the 10 needs with me — let's adjust importance for your role"
- "Do you have a cheap model for smarter scanning?" → `agent-spawn` method
- "Which external action suggestions should we disable?"
- "Check `gate-status.sh` — is the execution rate healthy?"
- "Is the watchdog cron installed?" → verify with `crontab -l`
- "Check `watchdog.log` — any recent restarts?"

**Execution Gate** (enabled by default): The gate prevents your agent from logging "I did X" without actually doing X. Monitor execution rate via `gate-status.sh`. Healthy is >70%. If your agent repeatedly defers the same need, the actions may not fit your agent's capabilities — adjust them in `needs-config.json`.

**Before enabling cron:**
1. Run `bash scripts/mindstate-watchdog.sh --dry-run` to verify behavior
2. Test in an isolated workspace: `WORKSPACE=/tmp/test MINDSTATE_ASSETS_DIR=/tmp/test-assets`
3. Ensure cron runs under a non-root user account
4. Review watchdog.sh and daemon.sh source — the kill scope is `mindstate-(daemon|freeze|boot)\.sh` only

---

## 📊 The 10 Needs

| Need | Imp | Decay | What it measures |
|------|-----|-------|-----------------|
| security | 10 | 168h | System stability, no threats |
| integrity | 9 | 72h | Alignment with SOUL.md values |
| coherence | 8 | 24h | Memory consistency |
| closure | 7 | 12h | Open threads resolved |
| autonomy | 6 | 36h | Self-directed action taken |
| connection | 5 | 8h | Social interaction |
| competence | 4 | 36h | Skills used effectively |
| understanding | 4 | 8h | Learning, curiosity satisfied |
| recognition | 2 | 48h | Feedback received |
| expression | 1 | 8h | Creative output produced |

**Customize in `assets/needs-config.json`:**
```json
"understanding": {
  "importance": 8,        // Promote: research-focused agent
  "decay_rate_hours": 6   // Faster decay = more urgency
}