name	turing-pyramid
description	Motivation and action system for AI agents. 10 needs with Turing-exp tension, execution gate, spontaneity layers, deliberation protocol (structured thinking with outcome artifacts), association scan (contextual recall), continuity across sessions, and crash-resilient watchdog.
metadata	{"clawdbot":{"emoji":"🔺","requires":{"env":"[Truncated]","optional_env":"[Truncated]","bins":"[Truncated]"}}}

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

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

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:

Read this file to understand the 10 needs and how tension works
Run init.sh to create initial state files
Run one cycle (run-cycle.sh) — it proposes actions and registers them in the execution gate
Actually do the action — write the file, make the post, run the command
Resolve the gate (gate-resolve.sh --need <need> --evidence "what you did")
Mark satisfaction (mark-satisfied.sh <need> <impact>)
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.
Deliberative actions are tagged [DELIBERATIVE] — think through phases (REPRESENT → RELATE+TENSION → GENERATE → EVALUATE → CONCLUDE → ROUTE), produce an outcome artifact, and route it back into the system. Use deliberate.sh --validate to check free-form notes or --validate-inline for quick checks.
Association scan (association-scan.sh): contextual recall during deliberation. Surfaces related past conclusions, research threads, pending followups, and open interests. Suggested in RELATE+TENSION phase, not required.
Followup horizons: create-followup.sh --in 2w or --in 1m for long-term revisits.

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

For the Human (Steward)

Before your agent starts using this:

Review the 10 needs (table below) — are importance rankings right for your agent?
Check scan config — default line-level is free and works everywhere. Upgrade to agent-spawn if you have a cheap model (Haiku) available.
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.

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?"
"Are deliberative actions producing real conclusions?" → check audit.log for conclusion field
"Is the association scan useful or noisy?" → tune --min-score and --recency-hours

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:

Run bash scripts/mindstate-watchdog.sh --dry-run to verify behavior
Test in an isolated workspace: WORKSPACE=/tmp/test MINDSTATE_ASSETS_DIR=/tmp/test-assets
Ensure cron runs under a non-root user account
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:

"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

# 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

# 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

Scaffolding, not bureaucracy — gate checks presence, not quality
Anti-compliance by design — validate mode over template mode; gate warns, never blocks
Persistent state change mandatory — not necessarily a file, but always a trace
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

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

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

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:

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	API key + 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.

🔒 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 (curl, wget, ssh, etc.)
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

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.
Action suggestions may trigger auto-execution — If your agent runtime auto-executes suggestions, review needs-config.json and disable unwanted external actions (weight: 0).
Self-reported state — mark-satisfied.sh trusts caller input. Audit trail in assets/audit.log with sensitive data scrubbing.
Symlink protection — All find commands use -P flag (physical mode, never follows symlinks). Path traversal blocked via realpath validation.
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.
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.
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.
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).
External action suggestions — 8 actions in needs-config.json are flagged "external": true:

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 Descriptor Allocation

Lock FDs used by scripts (do not reuse in wrappers):

FD	Lock file	Used by
200	`needs-state.json.lock`	mark-satisfied.sh, apply-deprivation.sh
200	`cycle.lock`	run-cycle.sh, apply-preset.sh (different lock file, same fd — never concurrent)
201	`followups.jsonl.lock`	create-followup.sh, resolve-followup.sh, run-cycle.sh
202	`mindstate.lock`	mindstate-daemon.sh, mindstate-freeze.sh, mindstate-watchdog.sh
203	`gate.lock`	gate-propose.sh, gate-resolve.sh, gate-check.sh

📁 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

# 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

name	turing-pyramid
description	Motivation and action system for AI agents. 10 needs with Turing-exp tension, execution gate, spontaneity layers, deliberation protocol (structured thinking with outcome artifacts), association scan (contextual recall), continuity across sessions, and crash-resilient watchdog.
metadata	{"clawdbot":{"emoji":"🔺","requires":{"env":"[Truncated]","optional_env":"[Truncated]","bins":"[Truncated]"}}}

🔺 Turing Pyramid

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.

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

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

🎓 Onboarding Guide

For the Agent

When you first install this skill:

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

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.
Deliberative actions are tagged [DELIBERATIVE] — think through phases (REPRESENT → RELATE+TENSION → GENERATE → EVALUATE → CONCLUDE → ROUTE), produce an outcome artifact, and route it back into the system. Use deliberate.sh --validate to check free-form notes or --validate-inline for quick checks.
Association scan (association-scan.sh): contextual recall during deliberation. Surfaces related past conclusions, research threads, pending followups, and open interests. Suggested in RELATE+TENSION phase, not required.
Followup horizons: create-followup.sh --in 2w or --in 1m for long-term revisits.

For the Human (Steward)

Before your agent starts using this:

Review the 10 needs (table below) — are importance rankings right for your agent?
Check scan config — default line-level is free and works everywhere. Upgrade to agent-spawn if you have a cheap model (Haiku) available.
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.

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?"
"Are deliberative actions producing real conclusions?" → check audit.log for conclusion field
"Is the association scan useful or noisy?" → tune --min-score and --recency-hours

Before enabling cron:

Run bash scripts/mindstate-watchdog.sh --dry-run to verify behavior
Test in an isolated workspace: WORKSPACE=/tmp/test MINDSTATE_ASSETS_DIR=/tmp/test-assets
Ensure cron runs under a non-root user account
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:

"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.

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)

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

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

Configure: execution_gate in assets/mindstate-config.json

🧠 Deliberation Protocol (v1.31.0+)

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

# 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

Scaffolding, not bureaucracy — gate checks presence, not quality
Anti-compliance by design — validate mode over template mode; gate warns, never blocks
Persistent state change mandatory — not necessarily a file, but always a trace
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)

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

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

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

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:

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:

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	API key + 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.

🔒 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 (curl, wget, ssh, etc.)
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

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.
Action suggestions may trigger auto-execution — If your agent runtime auto-executes suggestions, review needs-config.json and disable unwanted external actions (weight: 0).
Self-reported state — mark-satisfied.sh trusts caller input. Audit trail in assets/audit.log with sensitive data scrubbing.
Symlink protection — All find commands use -P flag (physical mode, never follows symlinks). Path traversal blocked via realpath validation.
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.
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.
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.
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).
External action suggestions — 8 actions in needs-config.json are flagged "external": true:

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 Descriptor Allocation

Lock FDs used by scripts (do not reuse in wrappers):

FD	Lock file	Used by
200	`needs-state.json.lock`	mark-satisfied.sh, apply-deprivation.sh
200	`cycle.lock`	run-cycle.sh, apply-preset.sh (different lock file, same fd — never concurrent)
201	`followups.jsonl.lock`	create-followup.sh, resolve-followup.sh, run-cycle.sh
202	`mindstate.lock`	mindstate-daemon.sh, mindstate-freeze.sh, mindstate-watchdog.sh
203	`gate.lock`	gate-propose.sh, gate-resolve.sh, gate-check.sh

📁 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

# 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

📋 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

turing-pyramid

معلومات المصدر

خيارات التثبيت

مراجعة ملفات المصدر

المزيد من هذا المستودع

المزيد من هذا المستودع

🔺 Turing Pyramid

🚀 Quick Start

Deployment Tiers

🎓 Onboarding Guide

For the Agent

For the Human (Steward)

📊 The 10 Needs

⚙️ Core Mechanics

Turing-exp Tension Formula (v1.26.0)

Tension → Action Selection

Action Probability by Satisfaction Level

Protection Mechanisms

Cross-Need Impact

🚪 Execution Gate (v1.27.0)

How it works

Scripts

Evidence Types

Usage

🧠 Deliberation Protocol (v1.31.0+)

Two Action Modes

The Pipeline

Outcome Types

Routing (Phase 6)

Scripts

Gate Integration

Design Principles

🎲 Spontaneity System (Layers A/B/C)

🔄 Continuity Layer (v1.23.0)

Architecture

Four Scripts

Boot Sequence (inverted)

Temperature System

Setup

Resilience & Crash Recovery (v1.28.0)

Test Isolation

🔍 Scan Configuration

🔒 Security Model

What This Skill Does / Does Not Access

Security Warnings

Audit Trail (v1.12.0+)

File Descriptor Allocation

📁 File Structure

💰 Token Usage

🧪 Testing

📋 Example Cycle

🔺 Turing Pyramid

🚀 Quick Start

Deployment Tiers

🎓 Onboarding Guide

For the Agent

For the Human (Steward)

📊 The 10 Needs

⚙️ Core Mechanics

Turing-exp Tension Formula (v1.26.0)

Tension → Action Selection

Action Probability by Satisfaction Level

Protection Mechanisms

Cross-Need Impact

🚪 Execution Gate (v1.27.0)

How it works

Scripts

Evidence Types

Usage

🧠 Deliberation Protocol (v1.31.0+)

Two Action Modes

The Pipeline

Outcome Types

Routing (Phase 6)

Scripts

Gate Integration

Design Principles

🎲 Spontaneity System (Layers A/B/C)

🔄 Continuity Layer (v1.23.0)

Architecture