turing-pyramid

by tensusds

Install this Skill

curl -fsSL -o turing-pyramid.zip https://skill.seembox.com/api/v1/skills/turing-pyramid/download && unzip turing-pyramid.zip

Download turing-pyramid.zip

SKILL.md About

---
name: turing-pyramid
description: Prioritized action selection for AI agents. 10 needs with tension scoring, execution-gate tracking, optional continuity scripts, and an opt-in watchdog. Use when an agent needs local stateful action prioritization inside an isolated WORKSPACE. Read the deployment tiers and security warnings before enabling cron, watchdog kill/cleanup, or optional external-model scanning.
metadata:
  clawdbot:
    emoji: "🔺"
    requires:
      env:
        - WORKSPACE
      optional_env:
        - MINDSTATE_ASSETS_DIR
        - SKIP_SCANS
        - SKIP_SPONTANEITY
        - TURING_CALLER
        - SKIP_GATE
      bins:
        - bash
        - jq
        - bc
        - grep
        - find
        - flock
        - pgrep
        - df
        - kill
        - gzip
---

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

⚠️ **Safety summary**
- This skill is **not stateless**. It writes its own state and audit files (`needs-state.json`, `audit.log`, `followups.jsonl`, `MINDSTATE.md`, watchdog logs).
- This skill reads files under `WORKSPACE`. If `WORKSPACE` points at a sensitive directory, the skill can scan sensitive files there.
- `allow_kill` and `allow_cleanup` are **off by default** and should be treated as elevated, opt-in features.
- `external-model` scanning is **off by default** and should only be enabled after explicitly documenting the credential source and intended API.

**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 **no network calls by default**. Some actions in needs-config.json are tagged `"external": true` (e.g., web search, check for updates) — these are text suggestions to the agent, not executed by the scripts themselves. The 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.

⚠️ **WORKSPACE isolation**: This skill reads and writes files inside the `WORKSPACE` directory. Never point `WORKSPACE` at your home directory, system folders, or any location containing credentials or sensitive files. Use an isolated workspace directory.

**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 only 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. Even detect-only watchdog/continuity modes should be reviewed before persistent cron deployment.

---

## 🎓 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
}
```

---

## ⚙️ 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

| Sat Level | Base P | Behavior |
|-----------|--------|----------|
| 0.5 crisis | 100% | Always act |
| 1.0 severe | 90% | Almost always |
| 1.5 deprived | 75% | Usually act |
| 2.0 slight | 50% | Coin flip |
| 2.5 ok | 25% | Occasionally |
| 3.0 perfect | 0% | Skip |

### Protection Mechanisms

| Mechanism | Purpose |
|-----------|---------|
| **Floor (0.5)** | Minimum satisfaction — prevents total collapse |
| **Ceiling (3.0)** | Maximum — prevents runaway satisfaction |
| **Starvation Guard** | Need at floor >48h without action → forced into cycle |
| **Action Staleness** | Recently-selected actions get 80% weight penalty (variety) |
| **Day/Night Mode** | Decay slows 50% at night (configurable) |

### Cross-Need Impact

Actions on one need can boost or drag others:

| Action on... | Boosts | Why |
|-------------|--------|-----|
| expression | recognition +0.25 | Express → noticed |
| connection | expression +0.20 | Social sparks ideas |
| competence | recognition +0.30 | Good work → respect |
| autonomy | integrity +0.20 | Act on values |
| closure | coherence +0.20 | Finished threads → order |
| security | autonomy +0.10 | Safety enables risk |

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

| Script | Purpose |
|--------|---------|
| `gate-propose.sh` | Register pending action (called by run-cycle.sh automatically) |
| `gate-resolve.sh` | Resolve with evidence, or defer with reason |
| `gate-check.sh` | Check if gate is clear (built into run-cycle.sh) |
| `gate-status.sh` | Human-readable status + execution rate analytics |

### Evidence Types

| Type | Trust | Verification |
|------|-------|-------------|
| `mark_satisfied` | HIGH | Was mark-satisfied.sh called? (audit.log check) |
| `file_created` | HIGH | Does expected file exist? |
| `file_modified` | HIGH | Was file modified since proposal? |
| `self_report` | LOW | Agent self-reports (counted separately in analytics) |

### Usage

```bash
# 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`

---

## 🧠 Deliberation Protocol (v1.31.0)

Reflective actions ("re-read notes", "review SELF.md", "explore topic") previously collapsed into read → mark-satisfied → done. The Deliberation Protocol adds structured thinking with outcome artifacts.

### Two Action Modes

- **Operative** (default): produces external artifact (file, commit, post). Same protocol as before.
- **Deliberative** (`"mode": "deliberative"` in needs-config.json): must produce an **outcome artifact** + **routing decision**.

### The Pipeline

Full (impact ≥ 1.0): `REPRESENT → RELATE+TENSION → GENERATE → EVALUATE → CONCLUDE → ROUTE`
Compressed (impact < 1.0): `REPRESENT → CONCLUDE → ROUTE`

Phases are questions, not obligations. Skip with a reason — but always reach CONCLUDE and ROUTE.

### Outcome Types

Not every deliberation ends in a verdict. Six valid outcome types:
- **Decision** — clear action directive
- **Assessment** — evaluation of current state
- **Diagnosis** — root cause identification
- **Question refinement** — the real question isn't what was asked
- **Uncertainty artifact** — explicit gap with specific missing data
- **Tension artifact** — named conflict between elements

### Routing (Phase 6)

### Scripts

```bash
# Template scaffolding (or use free-form + validate)
deliberate.sh --template --need understanding --action "explore topic"
# Validate a free-form file
deliberate.sh --validate research/threads/cosmos/sulfur-biosignature-problem.md
# Quick inline check
deliberate.sh --validate-inline --conclusion "H2S is not reliable" --route "research_thread"
```

### Gate Integration

- `gate-propose.sh` stores `action_mode` in pending_actions.json
- `gate-resolve.sh --conclusion "..."` logs outcome; warns (doesn't block) if deliberative action lacks conclusion
- `mark-satisfied.sh --conclusion "..."` records in audit.log

### Design Principles

1. **Scaffolding, not bureaucracy** — gate checks presence, not quality
2. **Anti-compliance by design** — validate mode over template mode; gate warns, never blocks
3. **Persistent state change mandatory** — not necessarily a file, but always a trace
4. **Phases are questions, not obligations** — conscious skipping is valid

Full design: `DELIBERATION-PROTOCOL.md` in skill root.

---

## 🎲 Spontaneity System (Layers A/B/C)

Three layers create organic, unpredictable behavior:

| Layer | Mechanism | Effect |
|-------|-----------|--------|
| **A — Surplus** | Excess satisfaction accumulates. When threshold hit → HIGH impact roll | Natural ~28-35h pulsing rhythm |
| **B — Noise** | Boredom grows without high-impact actions (max 9%). Echo boost after spontaneous fire (8%, decays 24h) | Variety when things get stale |
| **C — Context** | File system changes trigger need-specific boosts (new research files → understanding) | Environmental responsiveness |

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

| Script | When | What |
|--------|------|------|
| `mindstate-daemon.sh` | Cron every 5min | Updates reality: pyramid state, filesystem changes, system health, stale cognition detection, physical temperature |
| `mindstate-freeze.sh` | End of substantive session | Freezes cognition: trajectory, open threads, momentum, cognitive temperature |
| `mindstate-boot.sh` | Session start (FIRST thing) | Loads MINDSTATE, reconciles forecast vs reality, reports continuity score |
| `mindstate-watchdog.sh` | Cron every 15min | Process watchdog: detects hung/dead scripts, cleans orphans, restarts daemon |

### 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):

| Word | Condition |
|------|-----------|
| crisis | Any need critical (sat ≤ 0.5) |
| pressure | Average tension > 3 |
| focus | One need dominates (max tension > 2) |
| impulse | Spontaneous Layer A fired recently |
| accumulation | Surplus building toward threshold |
| calm | All tensions low (default) |

**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

```bash
# 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.

| Check | Default behavior | With opt-in |
|-------|-----------------|-------------|
| MINDSTATE.md freshness | Log warning, restart daemon | Same (restart is safe — just runs daemon.sh) |
| Hung processes (>5 min) | **Log only** | `allow_kill: true` → SIGTERM, then SIGKILL |
| Orphaned .tmp files | **Log only** | `allow_cleanup: true` → delete files |
| Stale cognition (>6h) | Auto-freeze (safe — runs freeze.sh) | Same |

**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`:
```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):
```json
"allow_kill": true,
"allow_cleanup": true
```

**Failure modes and recovery:**

| Failure | Impact | Recovery |
|---------|--------|----------|
| OpenClaw restart | Heartbeat pauses, cron continues | Watchdog ensures daemon stays alive |
| Daemon crash mid-write | Orphan .tmp file | Next daemon run cleans it up |
| Freeze never called | Stale cognition section | Watchdog auto-freezes after 6h (configurable) |
| Hung process (infinite loop) | Blocks flock, daemon skips ticks | Watchdog kills after 5 min |
| Machine reboot | All processes die | Cron restarts daemon + watchdog automatically |

### Test Isolation

Set `MINDSTATE_ASSETS_DIR` to isolate tests from production state:
```bash
export MINDSTATE_ASSETS_DIR=/tmp/test-assets
```

---

## 🔍 Scan Configuration

Scanners evaluate each need by analyzing workspace files.

| Method | Cost | Accuracy | Setup |
|--------|------|----------|-------|
| `line-level` (default) | Free | Good | None |
| `agent-spawn` | Low | High | Cheap model (Haiku) in allowed list |
| `external-model` | Low | High | Explicit API credential + steward approval |

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. If you enable `external-model`, document the exact credential source (env var or file), API endpoint, and approval path in your deployment before use.

---

## 🔒 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    │
│ • No network by def │      │                     │
└─────────────────────┘      └─────────────────────┘
         │
         │ (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

| ✅ Accesses | ❌ Never accesses |
|------------|-------------------|
| MEMORY.md, memory/*.md (read) | Files outside `$WORKSPACE` + own assets dir |
| SOUL.md, SELF.md (read) | Credentials (unless `external-model` enabled) |
| research/, scratchpad/ (read) | `sudo`, `docker`, `systemctl` |
| needs-state.json, audit.log (read/write) | Network by default (curl, wget, ssh, etc.). Optional `external-model` mode changes this and must be explicitly enabled |
| MINDSTATE.md (write, daemon) | Processes other than `mindstate-*.sh` |
| `pgrep`, `df` (read-only system checks, daemon) | Paths outside workspace/assets |
| `kill` on `mindstate-*.sh` PIDs (watchdog only) | Root/elevated permissions |
| `.tmp.*` files in workspace + assets (delete, watchdog) | |

### 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:
   ```bash
   # 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

| Heartbeat Interval | Est. tokens/month | Est. cost |
|--------------------|--------------------|-----------|
| 30 min | 1.4M–3.6M | $2–6 |
| 1 hour | 720k–1.8M | $1–3 |
| 2 hours | 360k–900k | $0.5–1.5 |

Stable agent with satisfied needs = fewer tokens per cycle.

---

## 🧪 Testing

```bash
# 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.34.8 — Self-throttle race fix: daemon --force flag, boot always gets fresh reality, test isolation improved (state reset + SKIP_DAEMON_FORCE).

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

_meta.json Metadata

{
  "ownerId": "kn78gved9wvv1egbx53rr9exb981pawp",
  "publishedAt": 1775773174021,
  "slug": "turing-pyramid",
  "version": "1.34.8"
}