Turing Pyramid

🔺 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:

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

# 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 /path/to/skills/turing-pyramid/scripts/run-cycle.sh

Deployment Tiers

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

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:

   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

Customize in assets/needs-config.json:

"understanding": {
  "importance": 8,        // Promote: research-focused agent
  "decay_rate_hours": 6   // Faster decay = more urgency
}

⚙️ Core Mechanics

Turing-exp Tension Formula (v1.26.0)

tension = dep² + importance × max(0, dep - crisis_threshold)²
          ╰─ base ─╯   ╰────── crisis amplifier ──────────╯
          (equal for    (importance matters ONLY
           all needs)    when dep > threshold)

Below threshold (default: 1.0, meaning sat > 2.0): All needs produce equal tension. Selection is effectively round-robin — expression gets as many slots as security.

Above threshold (sat < 2.0): Importance amplifies the crisis signal. In a dual crisis, security (imp=10) gets priority over expression (imp=1). This ensures high-importance needs get priority only when multiple needs compete for attention simultaneously.

Configure: settings.tension_formula.crisis_threshold in needs-config.json

Tension → Action Selection

satisfaction decays over time
    → tension (Turing-exp formula)
        → probability roll (crisis=100%, ok=25%, perfect=0%)
            → impact selection (crisis→big actions, ok→small actions)
                → action selected from weighted pool

Action Probability by Satisfaction Level

Protection Mechanisms

Cross-Need Impact

Actions on one need can boost or drag others:

Full matrix: assets/cross-need-impact.json

🚪 Execution Gate (v1.27.0)

Structural enforcement that prevents agents from describing actions instead of doing them. LLMs conflate "reasoning about an action" with "performing an action" — both are token generation. The gate requires environmental evidence that an action produced a state change.

How it works

run-cycle.sh proposes action → gate-propose.sh registers it as PENDING
    → gate blocks new proposals until PENDING actions resolved
        → agent EXECUTES the action (writes file, posts, runs command)
            → gate-resolve.sh verifies evidence → COMPLETED
                → gate clears → next cycle allowed

Scripts

Evidence Types

Usage

# After completing an action:
bash scripts/mark-satisfied.sh expression 1.6
bash scripts/gate-resolve.sh --need expression --evidence "wrote post about X"

# Or defer with reason:
bash scripts/gate-resolve.sh --defer <action_id> --reason "quiet hours"

# Check gate status:
bash scripts/gate-status.sh

Starvation guard actions are non-deferrable. If the guard forces an action, it cannot be deferred.

Evidence trust model: file_created and file_modified are high-trust because they require observable state changes. However, an agent with write access to $WORKSPACE can fabricate evidence by creating/modifying files. If this is a concern, restrict evidence types to mark_satisfied (requires explicit script call with audit trail) or add steward review for sensitive needs. self_report is explicitly low-trust and tracked separately in analytics.

Configure: execution_gate in assets/mindstate-config.json

🎲 Spontaneity System (Layers A/B/C)

Three layers create organic, unpredictable behavior:

Combined noise cap: 12%. Disabled for safety needs (security, integrity, coherence).

Configure: settings.spontaneity in needs-config.json

🔄 Continuity Layer (v1.23.0)

State persistence across discrete sessions via a two-layer living document. The reality layer updates continuously (cron daemon), while the cognition layer freezes at session end and restores at next boot.

Architecture

┌─────────────────────────────────────────────────┐
│                 MINDSTATE.md                     │
├────────────────────┬────────────────────────────┤
│   ## reality       │   ## cognition             │
│   (daemon, 5min)   │   (frozen at session end)  │
│   auto-updated     │   read-only between        │
│   between sessions │   session endpoints        │
├────────────────────┴────────────────────────────┤
│   ## forecast (frozen, consumed at boot)        │
└─────────────────────────────────────────────────┘

Four Scripts

Boot Sequence (inverted)

1. MINDSTATE.md  → Where am I? (position + velocity)
2. SOUL.md       → Who am I? (identity)
3. MEMORY.md     → What do I know? (history)
4. run-cycle.sh  → What should I do? (action)

Current state loads first — early context frames interpretation of everything after.

Temperature System

Physical (daemon-computed, deterministic, first-match):

Cognitive (freeze-computed from session): building / exploring / intensive / contemplation / brief / neutral

Drift detection: If physical ≠ cognitive at boot → DRIFT_DETECTED. Reality diverged while cognition was frozen.

Setup

# Daemon cron (updates reality between sessions)
crontab -e
*/5 * * * * WORKSPACE=/path/to/workspace /path/to/scripts/mindstate-daemon.sh >/dev/null 2>&1

# Watchdog cron (resilience — detects hung/dead scripts, restarts)
*/15 * * * * WORKSPACE=/path/to/workspace /path/to/scripts/mindstate-watchdog.sh >/dev/null 2>&1

# Boot (add to AGENTS.md session start — BEFORE SOUL.md)
WORKSPACE=/path/to/workspace bash scripts/mindstate-boot.sh

# Freeze (add to session end hook)
WORKSPACE=/path/to/workspace bash scripts/mindstate-freeze.sh "$SESSION_START_EPOCH"

Resilience & Crash Recovery (v1.28.0)

The continuity layer is designed to survive unexpected termination:

Atomic writes: All scripts write to *.tmp.$$ (PID-unique) then mv to final path. A crash mid-write leaves an orphan temp file but never corrupts the target.

Trap handlers: mindstate-daemon.sh and mindstate-freeze.sh register EXIT/SIGTERM/SIGINT/SIGHUP traps that clean up temp files on unexpected termination.

Orphan cleanup: The daemon cleans up any *.tmp.* files older than 10 minutes on every run.

Stale cognition detection: The daemon monitors when mindstate-freeze.sh last ran. If cognition hasn't been frozen for longer than stale_cognition_hours (default: 24h), a warning appears in MINDSTATE.md under system.cognition.

Watchdog (mindstate-watchdog.sh): Runs on cron every 15 minutes. Safe by default — detect and log only. Destructive actions (kill, delete) require explicit opt-in.

What does kill target? Only processes matching the full path $SCRIPT_DIR/mindstate-(daemon|freeze|boot).sh. The pattern is anchored to the skill's own script directory via grep -F "$SCRIPT_DIR/mindstate-". It cannot match unrelated processes, system services, or scripts in other directories. Even with allow_kill: true, it will never terminate anything outside the skill's own continuity scripts.

Auto-freeze is enabled by default because it's safe — it only runs mindstate-freeze.sh which writes to MINDSTATE.md in the workspace.

The watchdog logs only problems (to assets/watchdog.log, auto-rotated at 200 lines). Silent when everything is healthy. Supports --dry-run for testing.

Configure in assets/mindstate-config.json:

"watchdog": {
  "max_stale_minutes": 15,
  "max_process_age_seconds": 300,
  "allow_kill": false,
  "allow_cleanup": false,
  "auto_freeze": true,
  "auto_freeze_stale_hours": 6
}

To enable full self-healing (after reviewing scripts):

"allow_kill": true,
"allow_cleanup": true

Failure modes and recovery:

Test Isolation

Set MINDSTATE_ASSETS_DIR to isolate tests from production state:

export MINDSTATE_ASSETS_DIR=/tmp/test-assets

🔍 Scan Configuration

Scanners evaluate each need by analyzing workspace files.

Config: assets/scan-config.json. Fallback always to line-level.

For stewards: agent-spawn and external-model require explicit approval (approved_by_steward: true). The skill never enables these silently.

🔒 Security Model

Three layers with different scopes and system effects (see table above).

┌─────────────────────┐      ┌─────────────────────┐
│   TURING PYRAMID    │      │       AGENT         │
├─────────────────────┤      ├─────────────────────┤
│ • Reads local files │      │ • Has API keys      │
│ • Calculates decay  │ ───▶ │ • Has permissions   │
│ • Outputs: "★ do X" │      │ • DECIDES & ACTS    │
│ • Zero network I/O  │      │                     │
└─────────────────────┘      └─────────────────────┘
         │
         │ (continuity layer, cron)
         ▼
┌─────────────────────┐
│   DAEMON/WATCHDOG   │
├─────────────────────┤
│ • Updates MINDSTATE │
│ • pgrep, df (read)  │
│ • Watchdog: kill    │
│   mindstate-*.sh    │
│   processes ONLY    │
│ • .tmp cleanup in   │
│   $WORKSPACE + own  │
│   assets dir only   │
└─────────────────────┘

What This Skill Does / Does Not Access

Security Warnings

1. PII in workspace files — Scans use grep patterns on memory files. They see keywords, not meaning. But workspace files may contain personal data. Scope $WORKSPACE carefully.

2. Action suggestions may trigger auto-execution — If your agent runtime auto-executes suggestions, review needs-config.json and disable unwanted external actions (weight: 0).

3. Self-reported state — mark-satisfied.sh trusts caller input. Audit trail in assets/audit.log with sensitive data scrubbing.

4. Symlink protection — All find commands use -P flag (physical mode, never follows symlinks). Path traversal blocked via realpath validation.

5. System health checks (daemon only) — mindstate-daemon.sh runs pgrep (gateway alive?) and df (disk usage). These are read-only, local, and produce no side effects. No sudo, systemctl, or elevated operations.

6. Watchdog process management — mindstate-watchdog.sh can kill processes, but only those matching the full $SCRIPT_DIR/mindstate-*.sh path (grep -F on the skill's own script directory + process name). This path-anchored pattern prevents false matches against unrelated processes with similar names. Verify by searching for kill and grep in the script — every kill is gated by the path-specific filter.

7. Cron isolation — Both cron entries (daemon + watchdog) should run under the same non-root user that owns $WORKSPACE. Never add these as root cron jobs. Test with --dry-run (watchdog) and a temporary $WORKSPACE before deploying.

8. No network operations in scripts — grep -rn 'curl\|wget\|nc \|ssh\|scp\|git clone\|npm install' scripts/ returns zero matches (excluding optional external-model scan, disabled by default).

9. External action suggestions — 8 actions in needs-config.json are flagged "external": true:

   • web search on topic from INTERESTS.md
   • help someone via available integrations
   • web search on curious question
   • share completed work publicly
   • publish research or essay publicly
   • present completed work to community for feedback
   • post thought/update on social platform
   • write social post

   These are text suggestions only — the scripts never execute them, make no network calls, and have no side effects. The agent's runtime decides whether to act on them. To disable all external suggestions:

   # List them:
   jq '[.needs[].actions[] | select(.external == true) | .name]' assets/needs-config.json
   # Disable by setting weight to 0 in each need's action list
   

   For strict offline behavior, disable all external actions and keep semantic_predictions.enabled: false.

10. PATH and workspace isolation — All file operations use $WORKSPACE as root. find uses -P (no symlink follow). realpath validation in scanners prevents path traversal. Keep $WORKSPACE isolated from credentials and system config. The daemon's pgrep/df and watchdog's kill operate on the system process table, scoped by the skill's own $SCRIPT_DIR path — ensure the skill directory is not writable by untrusted users.

Audit Trail (v1.12.0+)

All state changes logged with timestamp, need, impact, reason (scrubbed):

• Long tokens → [REDACTED]
• Credit cards → [CARD]
• Emails → [EMAIL]
• Passwords/secrets/tokens → [REDACTED]

View: cat assets/audit.log | jq

📁 File Structure

turing-pyramid/
├── SKILL.md                    # This file
├── CHANGELOG.md                # Version history
├── assets/
│   ├── needs-config.json       # ★ Main config (needs, actions, weights)
│   ├── cross-need-impact.json  # ★ Cross-need cascade matrix
│   ├── mindstate-config.json   # Continuity layer config
│   ├── scan-config.json        # Scan method config
│   ├── decay-config.json       # Day/night mode settings
│   ├── needs-state.json        # Runtime state (auto-managed, not published)
│   └── audit.log               # Action audit trail (not published)
├── scripts/
│   ├── run-cycle.sh            # Main: tension evaluation + action selection
│   ├── mark-satisfied.sh       # State update + cross-need cascades
│   ├── init.sh                 # First-time initialization
│   ├── show-status.sh          # Current state display
│   ├── mindstate-daemon.sh     # Continuity: reality updater (cron)
│   ├── mindstate-freeze.sh     # Continuity: cognition snapshot
│   ├── mindstate-boot.sh       # Continuity: boot + reconciliation
│   ├── mindstate-watchdog.sh   # Continuity: process watchdog (cron)
│   ├── mindstate-utils.sh      # Continuity: shared utilities
│   ├── spontaneity.sh          # Layers A/B/C logic
│   ├── apply-deprivation.sh    # Deprivation cascade engine
│   ├── get-decay-multiplier.sh # Day/night multiplier
│   ├── _scan_helper.sh         # Shared scan utilities
│   └── scan_*.sh               # Need-specific scanners (10 files)
├── tests/
│   ├── run-tests.sh            # Test runner
│   ├── unit/                   # 22 unit test files
│   ├── integration/            # 4 integration tests
│   ├── regression/             # Regression tests
│   └── fixtures/               # Test data
└── references/
    ├── TUNING.md               # Detailed tuning guide
    └── architecture.md         # Technical documentation

💰 Token Usage

Stable agent with satisfied needs = fewer tokens per cycle.

🧪 Testing

# Full suite
WORKSPACE=/path/to/workspace bash tests/run-tests.sh

# Unit only
WORKSPACE=/path/to/workspace bash tests/run-tests.sh unit

# Integration only
WORKSPACE=/path/to/workspace bash tests/run-tests.sh integration

26 test files, 65+ assertions. Covers: decay, tension, probability, impact selection, spontaneity (A/B/C), cross-need impact, crisis mode, starvation guard, action staleness, audit scrubbing, scan config, day/night mode, mindstate daemon/freeze/boot, full lifecycle + homeostasis.

📋 Example Cycle

🔺 Turing Pyramid — Cycle at Wed Mar 18 04:11
======================================

Current tensions:
  coherence: tension=8.0 (sat=2.0, dep=1.0)
  closure: tension=7.0 (sat=2.0, dep=1.0)
  autonomy: tension=6.0 (sat=2.0, dep=1.0)
  connection: tension=5.0 (sat=2.0, dep=1.0)

Selecting 3 needs (0 forced + 3 regular)...

📋 Decisions:

▶ ACTION: coherence (tension=8.0, sat=2.0)
  Range mid rolled → selected:
    ★ re-read last 3 days of memory for consistency (impact: 1.2)
  Then: mark-satisfied.sh coherence 1.2

▶ ACTION: closure (tension=7.0, sat=2.0)
  Range low rolled → selected:
    ★ complete or drop a stale intention (impact: 0.8)
  Then: mark-satisfied.sh closure 0.8

▶ ACTION: autonomy (tension=6.0, sat=2.0) [SPONTANEOUS]
  Range high rolled → selected:
    ★ make significant autonomous decision (impact: 2.9)
  Then: mark-satisfied.sh autonomy 2.9

======================================
Summary: 3 action(s), 0 noticed

Version: 1.28.7 — Safe defaults: watchdog detect-only, kill/cleanup opt-in. 5-tier deployment. 25/25 tests.

Full changelog: CHANGELOG.md | Tuning guide: references/TUNING.md