Turing Pyramid

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.

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)

text

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

text

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

text

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)

Every outcome must go somewhere: followup | research_thread | interest | steward_question | priority_flag | reframe | chain | concluded

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

text

┌─────────────────────────────────────────────────┐
│                 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)

text

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

text

┌─────────────────────┐      ┌─────────────────────┐
│   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

text

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

text

🔺 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.10 — Test timeout calibration + metadata sync: default runner timeout matches long integration/stress tests; package metadata and skill footer are synchronized.

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