turing-pyramid

Prioritized action selection for AI agents. 10 needs with time-decay and tension scoring replace idle heartbeat loops with concrete next actions.

# Turing Pyramid

Prioritized action selection for AI agents. 10 needs with time-decay and tension scoring replace idle heartbeat loops with concrete next actions.

**Customization:** Tune decay rates, weights, patterns. Defaults are starting points. See `TUNING.md`.

**Ask your human before:** Changing importance values, adding/removing needs, enabling external actions.

---

## Requirements

**System binaries (must be in PATH):**
```
bash, jq, grep, find, date, wc, bc
```

**Environment (REQUIRED — no fallback):**
```bash
# Scripts will ERROR if WORKSPACE is not set
export WORKSPACE="/path/to/your/workspace"
```
⚠️ **No silent fallback.** If WORKSPACE is unset, scripts exit with error.
This prevents accidental scanning of unintended directories.

**Post-install (ClawHub):**
```bash
# ClawHub doesn't preserve executable bits — fix after install:
chmod +x <skill-dir>/scripts/*.sh
chmod +x <skill-dir>/tests/**/*.sh
```
Why: Unix executable permissions (+x) are not preserved in ClawHub packages.
Scripts work fine with `bash scripts/run-cycle.sh`, but `./scripts/run-cycle.sh` needs +x.

---

## Data Access & Transparency

**What this skill reads (via grep/find scans):**
- `MEMORY.md`, `memory/*.md` — for connection/expression/understanding signals
- `SOUL.md`, `SELF.md` — for integrity/coherence checks
- `research/`, `scratchpad/` — for competence/understanding activity
- Dashboard files, logs — for various need assessments

**What this skill writes:**
- `assets/needs-state.json` — current satisfaction/deprivation state
- `assets/audit.log` — append-only log of all mark-satisfied calls (v1.12.0+)

**Privacy considerations:**
- Scans use grep patterns, not semantic analysis — they see keywords, not meaning
- State file contains no user content, only need metrics
- Audit log records reasons given for satisfaction claims
- No data is transmitted externally by the skill itself

**Limitations & Trust Model:**
- `mark-satisfied.sh` trusts caller-provided reasons — audit log records claims, not verified facts
- Some actions in `needs-config.json` reference external services (Moltbook, web search) — marked with `"external": true, "requires_approval": true`
- External actions are **suggestions only** — the skill doesn't execute them, the agent decides
- If you don't want external action suggestions, set their weights to 0

**Network & System Access:**
- Scripts contain **no network calls** (no curl, wget, ssh, etc.) — verified by grep scan
- Scripts contain **no system commands** (no sudo, systemctl, docker, etc.)
- All operations are local: grep, find, jq, bc, date on WORKSPACE files only
- The skill **suggests** actions (including some that mention external services) but **never executes** them

**Required Environment Variables:**
- `WORKSPACE` — path to agent workspace directory (REQUIRED, no fallback). **Not a credential** — this is a filesystem path, not a secret. Set it to a deliberately scoped directory containing only files you want scanned.
- `TURING_CALLER` — optional, for audit trail (values: "heartbeat", "manual")

**No API keys or secrets required by default.** The `external_model` scan method (disabled by default) would require an API key if enabled — this requires explicit steward approval and is never enabled silently. See Scan Configuration below.

**Audit trail (v1.12.0+):**
All `mark-satisfied.sh` calls are logged with:
- Timestamp, need, impact, old→new satisfaction
- Reason (what action was taken) — **scrubbed for sensitive patterns**
- Caller (heartbeat/manual)

**Sensitive data scrubbing (v1.12.3+):**
Before writing to audit log, reasons are scrubbed:
- Long tokens (20+ chars) → `[REDACTED]`
- Credit card patterns → `[CARD]`
- Email addresses → `[EMAIL]`
- password/secret/token/key values → `[REDACTED]`
- Bearer tokens → `Bearer [REDACTED]`

View audit: `cat assets/audit.log | jq`

---

## Pre-Install Checklist

Before installing, review these items:

1. **Inspect scan scripts** — Verify no network calls or unexpected commands:
   ```bash
   grep -nE "\b(curl|wget|ssh|sudo|docker|systemctl)\b" scripts/scan_*.sh
   # Expected: no output
   ```

2. **Scope WORKSPACE** — Set to a deliberately limited directory. Avoid pointing at your full home directory. The skill only reads files inside `$WORKSPACE`.

3. **Audit scan targets** — Scripts read `MEMORY.md`, `memory/`, `SOUL.md`, `research/`, `scratchpad/`. Relocate files containing secrets or private data you don't want pattern-matched.

4. **Review audit logging** — `mark-satisfied.sh` logs caller-provided reasons after scrubbing. Check scrubbing patterns in the script are adequate for your data. If unsure, provide only generic reasons.

5. **External actions** — Action suggestions like "post to Moltbook" or "web search" are text-only suggestions (never executed by this skill). To remove them: set their `weight` to `0` in `needs-config.json`.

6. **Run tests in isolation** — Before production use:
   ```bash
   WORKSPACE=/tmp/test-workspace ./tests/run-tests.sh
   ```

---

## Quick Start

```bash
./scripts/init.sh                        # First time
./scripts/run-cycle.sh                   # Every heartbeat  
./scripts/mark-satisfied.sh <need> [impact]  # After action
```

---

## Scan Configuration (First-Time Setup)

The Turing Pyramid uses **scanners** to evaluate each need by analyzing memory files. The default scan method uses line-level pattern matching, which works everywhere with zero cost.

**On first install, discuss scan configuration with your human:**

### Available Scan Methods

| Method | How it works | Cost | Accuracy | Setup |
|--------|-------------|------|----------|-------|
| `line-level` (default) | Per-line keyword matching. If a line has both positive and negative words (e.g. "fixed a bug"), positive wins. | Free | Good | None |
| `agent-spawn` | Spawns a sub-agent with a cheap model (e.g. Haiku) to classify memory lines as SUCCESS/FAILURE/NEUTRAL. | Low | High | Needs cheap model in agent's allowed list |
| `external-model` | Direct API call to an inference service (OpenRouter, etc.) for classification. | Low | High | Needs API key + explicit steward approval |

### Setup Conversation

When setting up, ask your human:

1. **"Do you have a cheap/fast model available (like Claude Haiku) in your model config?"**
   - If yes → offer `agent-spawn` method. Check with `openclaw models list`.
   - The model must be in the agent's allowed model list.

2. **"Would you prefer to use an external inference service (like OpenRouter)?"**
   - If yes → ask for: base URL, API key env variable name, model name.
   - Store in `assets/scan-config.json` with `approved_by_steward: true`.
   - ⚠️ This method requires **explicit steward approval** — never enable silently.

3. **If neither** → `line-level` works well for most setups. No action needed.

### Configuration File

Edit `assets/scan-config.json`:

```json
{
  "scan_method": "line-level",
  "agent_spawn": {
    "enabled": false,
    "model": null,
    "approved_by_steward": false
  },
  "external_model": {
    "enabled": false,
    "base_url": null,
    "api_key_env": null,
    "model": null,
    "approved_by_steward": false
  },
  "fallback": "line-level"
}
```

**Fallback**: If the configured method fails (API down, model unavailable), scanners automatically fall back to `line-level`.

### Verification After Setup

After configuring a non-default method, **verify it works** before telling your human "all set":

1. **agent-spawn**: Run a test spawn:
   ```
   sessions_spawn(task="Classify this line as SUCCESS, FAILURE, or NEUTRAL: 'Fixed the critical bug in scanner'", model="<configured_model>", mode="run")
   ```
   - If it returns a classification → ✅ tell human: "agent-spawn method verified, working."
   - If it errors (model not in allowlist, etc.) → ⚠️ tell human: "Model `X` isn't available for sub-agents. Options: add it to allowed models, or stick with line-level."

2. **external-model**: Test the API endpoint:
   ```bash