{"id":"91a54e5d-b9ef-4243-aadf-e883575e929e","entityType":"agent","slug":"clawhub-tensusds-turing-pyramid","name":"Turing Pyramid","canonicalUrl":"https://www.xpersona.co/agent/clawhub-tensusds-turing-pyramid","canonicalPath":"/agent/clawhub-tensusds-turing-pyramid","generatedAt":"2026-10-09T14:16:22.897Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-09T10:34:56.712Z","emptyReason":null},"description":"Prioritized action selection for AI agents. 10 needs with tension scoring, execution-gate tracking, optional continuity scripts, and an opt-in watchdog. Use... Skill: Turing Pyramid Owner: tensusds Summary: Prioritized action selection for AI agents. 10 needs with tension scoring, execution-gate tracking, optional continuity scripts, and an opt-in watchdog. Use... Tags: latest:1.34.10 Version history: v1.34.10 | 2026-05-10T04:55:43.328Z | user Test timeout calibration, version metadata sync, and deliberation test robustness. Full suite: 35/35 passed, 0 skipped. v1.34.9 | 20","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 3K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s179gnbng0bt8pcqdafa5emhn583fj5e:turing-pyramid","sourceUrl":"https://clawhub.ai/tensusds/turing-pyramid","homepage":"https://clawhub.ai/tensusds/skills/turing-pyramid","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/tensusds/turing-pyramid","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/tensusds/skills/turing-pyramid","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"Prioritized action selection for AI agents. 10 needs with tension scoring, execution-gate tracking, optional continuity scripts, and an opt-in watchdog. Use... "},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:34:56.712Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:34:56.712Z","emptyReason":null},"stars":null,"forks":null,"downloads":2960,"packageName":null,"latestVersion":"1.34.10","tractionLabel":"3K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T10:34:56.712Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T10:34:56.712Z","lastCrawledAt":"2026-10-09T10:34:56.712Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T10:34:56.712Z","lastVerifiedAt":null,"highlights":[{"version":"1.34.10","createdAt":"2026-05-10T04:55:43.328Z","changelog":"Test timeout calibration, version metadata sync, and deliberation test robustness. Full suite: 35/35 passed, 0 skipped.","fileCount":109,"zipByteSize":268026},{"version":"1.34.9","createdAt":"2026-05-09T18:02:29.343Z","changelog":"Run-cycle startup resilience, clean package runtime-state removal, full test enforcement, and stabilized action staleness tests. Full suite: 35 passed, 0 failed, 0 skipped.","fileCount":106,"zipByteSize":265352},{"version":"1.34.8","createdAt":"2026-04-09T22:19:34.021Z","changelog":"Integrity actions audit: 9→7 concrete verifiable actions. New INTEGRITY_CHECKPOINTS.md with structured entries + INTEGRITY_CHECKPOINT_TEMPLATE.md with gate thresholds. scan_integrity.sh now reads checkpoints file directly. 28/28 tests.","fileCount":105,"zipByteSize":264096},{"version":"1.34.7","createdAt":"2026-04-09T19:16:14.795Z","changelog":"Deliberation discipline tracking: new deliberation.log, tiered observables (absent/minimal/substantive/deep), classify_deliberation_level() helper, deliberate.sh now logs invocations, gate-resolve records level, run-cycle shows discipline warnings, mindstate-freeze adds discipline mirror. 28/28 tests.","fileCount":105,"zipByteSize":263344},{"version":"1.34.6","createdAt":"2026-04-09T03:33:01.748Z","changelog":"Connection actions expanded: 6 new actions (Moltbook post, AgentGram post, steward ping variants, emoji react, voluntary check-in). Weight recalibration: light actions raised, heavy actions lowered, steward issue ping gets priority weight 65.","fileCount":105,"zipByteSize":261344},{"version":"1.34.5","createdAt":"2026-04-09T02:27:58.755Z","changelog":"Deferred backlog pressure: scan_closure now sees deferred count (pressure bands), gate-resolve --close abandons deferred items, new closure action for deliberate backlog review. 28/28 tests.","fileCount":105,"zipByteSize":260811},{"version":"1.34.4","createdAt":"2026-04-09T01:38:46.266Z","changelog":"Integrity scanner rebuilt: was a pure time-decay stub, now reads memory files for alignment/drift signals + checkpoint age + SOUL engagement checks. Ritual loop broken. Config declaration fixed. 27/27 tests green.","fileCount":104,"zipByteSize":257413},{"version":"1.34.3","createdAt":"2026-04-09T01:23:38.512Z","changelog":"Self-throttle race fix: daemon --force flag, boot always gets fresh reality. Test isolation: state reset per test, SKIP_DAEMON_FORCE. 27/27 + 2/2 tests green.","fileCount":104,"zipByteSize":256070}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s179gnbng0bt8pcqdafa5emhn583fj5e:turing-pyramid","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tensusds-turing-pyramid/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tensusds-turing-pyramid/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tensusds-turing-pyramid/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tensusds-turing-pyramid/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tensusds-turing-pyramid/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-tensusds-turing-pyramid/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T14:16:22.893Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tensusds-turing-pyramid/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tensusds-turing-pyramid/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tensusds-turing-pyramid/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-tensusds-turing-pyramid/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-09T10:34:56.712Z","emptyReason":null},"readme":"Skill: Turing Pyramid\n\nOwner: tensusds\n\nSummary: Prioritized action selection for AI agents. 10 needs with tension scoring, execution-gate tracking, optional continuity scripts, and an opt-in watchdog. Use...\n\nTags: latest:1.34.10\n\nVersion history:\n\nv1.34.10 | 2026-05-10T04:55:43.328Z | user\n\nTest timeout calibration, version metadata sync, and deliberation test robustness. Full suite: 35/35 passed, 0 skipped.\n\nv1.34.9 | 2026-05-09T18:02:29.343Z | user\n\nRun-cycle startup resilience, clean package runtime-state removal, full test enforcement, and stabilized action staleness tests. Full suite: 35 passed, 0 failed, 0 skipped.\n\nv1.34.8 | 2026-04-09T22:19:34.021Z | user\n\nIntegrity actions audit: 9→7 concrete verifiable actions. New INTEGRITY_CHECKPOINTS.md with structured entries + INTEGRITY_CHECKPOINT_TEMPLATE.md with gate thresholds. scan_integrity.sh now reads checkpoints file directly. 28/28 tests.\n\nv1.34.7 | 2026-04-09T19:16:14.795Z | user\n\nDeliberation discipline tracking: new deliberation.log, tiered observables (absent/minimal/substantive/deep), classify_deliberation_level() helper, deliberate.sh now logs invocations, gate-resolve records level, run-cycle shows discipline warnings, mindstate-freeze adds discipline mirror. 28/28 tests.\n\nv1.34.6 | 2026-04-09T03:33:01.748Z | user\n\nConnection actions expanded: 6 new actions (Moltbook post, AgentGram post, steward ping variants, emoji react, voluntary check-in). Weight recalibration: light actions raised, heavy actions lowered, steward issue ping gets priority weight 65.\n\nv1.34.5 | 2026-04-09T02:27:58.755Z | user\n\nDeferred backlog pressure: scan_closure now sees deferred count (pressure bands), gate-resolve --close abandons deferred items, new closure action for deliberate backlog review. 28/28 tests.\n\nv1.34.4 | 2026-04-09T01:38:46.266Z | user\n\nIntegrity scanner rebuilt: was a pure time-decay stub, now reads memory files for alignment/drift signals + checkpoint age + SOUL engagement checks. Ritual loop broken. Config declaration fixed. 27/27 tests green.\n\nv1.34.3 | 2026-04-09T01:23:38.512Z | user\n\nSelf-throttle race fix: daemon --force flag, boot always gets fresh reality. Test isolation: state reset per test, SKIP_DAEMON_FORCE. 27/27 + 2/2 tests green.\n\nv1.34.2 | 2026-04-09T00:56:58.902Z | user\n\nExecution gate continuity fix: daemon tracks pending gate status, freeze prioritizes pending gate actions in open_threads, boot warns on blocked execution gate.\n\nv1.34.1 | 2026-04-04T01:07:28.265Z | user\n\nRuntime housekeeping, decisions.log, git drift scanner, PII cleanup\n\nv1.33.9 | 2026-04-02T07:11:20.618Z | user\n\nClawHub safety clarification: confirmed safe publish defaults (allow_kill=false, allow_cleanup=false), clarified stateful writes, isolated WORKSPACE requirement, external-model and destructive watchdog paths explicitly opt-in\n\nv1.33.8 | 2026-04-01T23:47:33.509Z | user\n\nDeliberation Phase 2A: [DELIBERATIVE] tag in run-cycle, --conclusion in mark-satisfied+gate-resolve, action_mode stored at propose time, scrub_sensitive moved to shared utils. All 27 deliberation tests green.\n\nv1.33.7 | 2026-04-01T03:15:01.187Z | user\n\nCritical init/install bugfix: repaired needs-state template/schema drift, hardened init.sh with fallback rebuild from needs-config, and added regression test for fresh init + stale-template recovery.\n\nv1.33.6 | 2026-03-29T03:05:33.541Z | user\n\nScanner false-positive audit: autonomy infra-vs-permission blocked distinction; closure blocked keyword hardening; added regression tests for scanner false positives.\n\nv1.33.5 | 2026-03-24T18:45:44.679Z | user\n\nCompaction continuity (current-task.md recovery in mindstate-boot), freeze grep -oP crash fix, 27/27 tests green, gate isolation in test suite\n\nv1.33.3 | 2026-03-24T03:32:46.843Z | user\n\nDocs: fd allocation table, onboarding updated for deliberation+association scan, description updated, version consistency, test gaps documented\n\nv1.33.1 | 2026-03-24T02:12:52.490Z | user\n\nPII scrub + 3 bugfixes: freeze SESSION_START, exclude-source, test validation\n\nv1.33.0 | 2026-03-24T01:39:20.147Z | user\n\nContinuation Phase 2: boot contextual recall, freeze deliberation residuals, 19 association tests\n\nv1.32.0 | 2026-03-24T01:17:16.628Z | user\n\nContinuation & Association Scan: contextual recall, concluded+action warning, followup 2w/1m, 17 new tests\n\nv1.31.3 | 2026-03-23T23:03:36.847Z | user\n\nClawHub security review fixes: network claims, WORKSPACE isolation warning\n\nv1.31.2 | 2026-03-23T22:53:32.774Z | user\n\nBugfixes: defer path scrub, template --save writes file, CHANGELOG updated, settings.version synced, scrub_sensitive consistent across gate-resolve and mark-satisfied. 28 tests green.\n\nv1.31.1 | 2026-03-23T22:19:23.995Z | user\n\nDeliberation Protocol Phase 1+2: 22 deliberative actions, deliberate.sh (template/validate/validate-inline), --conclusion in mark-satisfied + gate-resolve, outcome types taxonomy, route reframe, 27 tests. Watchdog safe defaults.\n\nv1.29.1 | 2026-03-20T17:57:15.765Z | user\n\nFix: shipped config now matches documented safe defaults (allow_kill=false, allow_cleanup=false). Addresses ClawHub security scan finding.\n\nv1.29.0 | 2026-03-20T04:35:05.101Z | user\n\nPreset Architecture: role-based need configs (default + personal-assistant). 28/0/1 tests. Bug fixes for state format, scanner isolation, watchdog/gate tests.\n\nv1.28.7 | 2026-03-19T18:33:02.621Z | user\n\nSafe defaults: watchdog kill/cleanup opt-in (detect+log only by default). 5-tier deployment. 25/25 tests.\n\nv1.28.6 | 2026-03-19T18:18:44.466Z | user\n\nDeployment tiers: 4-level progressive install (Interactive → Full). 25/25 tests.\n\nv1.28.5 | 2026-03-19T18:16:15.147Z | user\n\nSecurity hardening round 2: external actions enumerated, PATH isolation docs. 25/25 tests.\n\nv1.28.4 | 2026-03-19T18:12:35.884Z | user\n\nSecurity hardening: path-anchored watchdog, evidence trust model, external action docs, three-layer scope. 25/25 tests.\n\nv1.28.3 | 2026-03-19T18:06:18.361Z | user\n\nSecurity clarity: three-layer scope model, tests, config isolation, jq bugfix. 25/25 green.\n\nv1.28.2 | 2026-03-19T17:52:27.880Z | user\n\nTests, config isolation fix, jq bugfix. 25/25 green.\n\nv1.28.1 | 2026-03-19T17:36:29.339Z | user\n\nAuto-freeze: watchdog detects stale cognition (>6h) and triggers automatic freeze\n\nv1.28.0 | 2026-03-19T16:59:16.898Z | user\n\nResilience: watchdog script, trap handlers, orphan cleanup, stale cognition detection. Crash-recovery documentation.\n\nv1.27.4 | 2026-03-19T04:20:47.378Z | user\n\nFull sanitization: zero PII, zero Russian, zero philosophy in all published files. Practical engineering language throughout. 26 tests green.\n\nv1.27.3 | 2026-03-19T03:57:56.111Z | user\n\nSecurity + i18n: all Russian strings → English, platform-specific refs → generic, onboarding updated for execution gate workflow.\n\nv1.27.2 | 2026-03-19T03:41:31.885Z | user\n\nBootstrap edge case: --bootstrap skips gate (clean slate init). Gate-check reordered after bootstrap detection.\n\nv1.27.1 | 2026-03-19T03:31:34.707Z | user\n\nGate hardening: flock concurrency protection, PID-unique temp files, --non-deferrable for starvation guard, action-not-found validation. All from code review.\n\nv1.27.0 | 2026-03-19T03:02:42.769Z | user\n\nExecution Gate: structural enforcement preventing action-description-as-execution. gate-propose/resolve/check/status scripts. Evidence verification (mark_satisfied, file_modified, self_report). Non-deferrable starvation guard actions. Gate integrated into run-cycle.sh. 26 tests (11 new gate tests). Turing-exp formula from v1.26.0 included.\n\nv1.26.0 | 2026-03-19T00:44:49.076Z | user\n\nTuring-exp tension formula: equal rotation at homeostasis, hierarchy only in crisis. Replaces linear importance×deprivation with dep² + importance×max(0,dep-threshold)². Solves monopoly and starvation problems. Temperature thresholds recalibrated. Test suite hardened.\n\nv1.23.5 | 2026-03-18T04:47:16.176Z | auto\n\n**Minor update with enhanced configuration and clarity for sysadmin integration.**\n\n- Added support for optional environment variables: `MINDSTATE_ASSETS_DIR`, `SKIP_SCANS`, `SKIP_SPONTANEITY`, `TURING_CALLER` for advanced sysadmin/steward control.\n- Clarified that core scripts make no network calls, and \"external-model\" (API inference) is opt-in and off by default.\n- Improved explanation of \"external\" actions (e.g., web search) as suggestions only—agent decides whether to act.\n- Noted that the continuity daemon only runs lightweight local system checks (not remote calls).\n- Updated documentation to reflect new optional configuration fields and clarify operational boundaries.\n\nv1.23.4 | 2026-03-18T04:41:38.545Z | auto\n\n- Minor content updates in documentation files (SKILL.md), improving explanations and formatting.\n- Updated sample and reference comments in configuration (assets/needs-config.json) for clarity.\n- Maintenance updates to scripts (mindstate-boot.sh, mindstate-freeze.sh), no behavioral changes.\n- Internal metadata (_meta.json) refreshed. \n- No breaking changes or functional modifications.\n\nv1.23.3 | 2026-03-18T04:38:45.205Z | auto\n\n- Continuity Layer documentation clarified: agent state is now described as persisting across sessions through two-layers (\"reality\" and \"cognition\") in a living `MINDSTATE.md` document.\n- Quick start, onboarding, and configuration sections updated for improved clarity.\n- Outdated or redundant prose trimmed for conciseness.\n- No behavior or config changes; documentation only.\n\nv1.23.2 | 2026-03-18T04:28:12.819Z | auto\n\n**Turing Pyramid v1.23.2 Changelog**\n\n- Major SKILL.md rewrite: clearer quick-start, onboarding, and system overview.\n- Expanded documentation: adds detailed tables for needs, mechanics, cross-need impacts, and spontaneity layers.\n- Full explanation of the new \"Continuity Layer\" (from v1.23.0) for persistent mindstate across sessions.\n- More practical guidance for both agents and human stewards.\n- No changes to code; documentation only.\n\nv1.23.1 | 2026-03-18T04:21:45.017Z | auto\n\nturing-pyramid v1.23.1\n\n- Removes legacy state files: `assets/mindstate-prev-snapshot.json` and `assets/needs-state.json`.\n- Updates scripts (`mindstate-daemon.sh`, `mindstate-freeze.sh`, `mindstate-utils.sh`) to remove or refactor state file handling.\n- Updates documentation in `SKILL.md` and `CHANGELOG.md` to match new state management.\n- Simplifies and clarifies read/write file conventions in documentation.\n- No changes to core prioritization logic; mainly a cleanup and deprecation release.\n\nv1.23.0 | 2026-03-18T04:06:14.871Z | auto\n\n- Introduced \"mindstate\" feature with new config and state snapshot files.\n- Added lifecycle management scripts for mindstate (`mindstate-boot.sh`, `mindstate-daemon.sh`, etc.).\n- Significant increase in test coverage: new integration and unit tests for mindstate behaviors.\n- Existing test and state files updated for compatibility with mindstate system.\n\nv1.22.1 | 2026-03-16T17:10:28.031Z | user\n\nSpontaneity tuning: gate 1.5->1.0, baseline 2.0->1.5, threshold 10->6. First spontaneous event in ~16-24h instead of ~80h\n\nv1.22.0 | 2026-03-16T16:56:10.945Z | user\n\nNegation-aware scanning: no/not/never/zero/clean/intact/без context prevents false-positive on denial phrases\n\nv1.21.1 | 2026-03-16T16:48:38.340Z | user\n\nFix trigger word in CHANGELOG.md that could cause scanner false-positive if copied to memory files\n\nv1.21.0 | 2026-03-16T16:24:17.880Z | user\n\nRace condition fix (flock skip-and-exit), action dedup guard, scanner false-positive fix, disabled action support, test fixes. 22/22 green.\n\nv1.20.2 | 2026-03-16T02:02:20.932Z | user\n\nSecurity hardening: path traversal + symlink + grep injection fixes. Init baseline snapshot. 21/21 tests green.\n\nv1.20.1 | 2026-03-16T01:25:40.833Z | user\n\nSecurity/PII audit, temp file safety (mktemp), runtime state excluded from package, 9 test fixes, 21/21 green.\n\nArchive index:\n\nArchive v1.34.10: 109 files, 268026 bytes\n\nFiles: _meta.json (135b), .gitignore (450b), assets/CLAUDE.md (308b), assets/context-triggers.json (1249b), assets/cross-need-impact.json (5662b), assets/decay-config.json (225b), assets/mindstate-config.json (2409b), assets/needs-config.json (23320b), assets/needs-state.template.json (498b), assets/scan-config.json (538b), CHANGELOG.md (41334b), CLAUDE.md (533b), CONTRIBUTING.md (2521b), dashboard.html (9623b), DESCRIPTION.md (10428b), docs/AUDIT-2026-04-04.md (1730b), docs/CONTINUATION-DESIGN.md (35857b), docs/DELIBERATION-PROTOCOL.md (50355b), docs/TODO-references.md (765b), docs/TODO.md (6678b), LICENSE (1084b), presets/default/context-triggers.json (1249b), presets/default/cross-impact.json (5662b), presets/default/needs.json (19397b), presets/personal-assistant/context-triggers.json (1345b), presets/personal-assistant/cross-impact.json (2583b), presets/personal-assistant/needs.json (9748b), references/architecture.md (10021b), references/TUNING.md (6528b), scripts/_scan_helper.sh (5425b), scripts/apply-deprivation.sh (3034b), scripts/apply-preset.sh (9467b), scripts/association-scan.sh (8923b), scripts/CLAUDE.md (833b), scripts/context-scan.sh (8231b), scripts/create-followup.sh (4216b), scripts/deliberate.sh (11813b), scripts/gate-check.sh (3660b), scripts/gate-propose.sh (3502b), scripts/gate-resolve.sh (10133b), scripts/gate-status.sh (2254b), scripts/get-decay-multiplier.sh (1434b), scripts/housekeep.sh (5193b), scripts/init.sh (4300b), scripts/list-presets.sh (1303b), scripts/mark-satisfied.sh (8221b), scripts/mindstate-boot.sh (10841b), scripts/mindstate-daemon.sh (12421b), scripts/mindstate-freeze.sh (12977b), scripts/mindstate-utils.sh (9981b), scripts/mindstate-watchdog.sh (8944b), scripts/resolve-followup.sh (3655b), scripts/run-cycle.sh (41858b), scripts/scan_autonomy.sh (1275b), scripts/scan_closure.sh (2557b), scripts/scan_coherence.sh (1292b), scripts/scan_competence.sh (4526b), scripts/scan_connection.sh (1228b), scripts/scan_expression.sh (1251b), scripts/scan_git_drift.sh (1493b), scripts/scan_integrity.sh (4067b), scripts/scan_recognition.sh (1403b), scripts/scan_security.sh (2267b), scripts/scan_understanding.sh (1718b), scripts/show-status.sh (1980b), scripts/spontaneity.sh (28652b), skill-card.md (2696b), SKILL.md (35134b), TEST_PROTOCOL.md (2626b), tests/fixtures/needs-state-crisis.json (1428b), tests/fixtures/needs-state-healthy.json (1428b), tests/integration/CLAUDE.md (348b), tests/integration/test_full_cycle.sh (5996b), tests/integration/test_homeostasis_stability.sh (3974b), tests/integration/test_mindstate_lifecycle.sh (13479b), tests/integration/test_stress_homeostasis.sh (5756b), tests/regression/test_socrat_effect.sh (1663b), tests/run-tests.sh (2544b), tests/test_action_staleness.sh (7080b), tests/test_starvation_guard.sh (7761b)\n\nFile v1.34.10:SKILL.md\n\n---\nname: turing-pyramid\ndescription: 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.\nmetadata:\n clawdbot:\n emoji: \"🔺\"\n requires:\n env:\n - WORKSPACE\n optional_env:\n - MINDSTATE_ASSETS_DIR\n - SKIP_SCANS\n - SKIP_SPONTANEITY\n - TURING_CALLER\n - SKIP_GATE\n bins:\n - bash\n - jq\n - bc\n - grep\n - find\n - flock\n - pgrep\n - df\n - kill\n - gzip\n---\n\n# 🔺 Turing Pyramid\n\n**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.\"\n\n**What it is NOT:** A chatbot framework, an executor, or a system management tool.\n\n**Three layers with different scopes:**\n\n⚠️ **Safety summary**\n- This skill is **not stateless**. It writes its own state and audit files (`needs-state.json`, `audit.log`, `followups.jsonl`, `MINDSTATE.md`, watchdog logs).\n- This skill reads files under `WORKSPACE`. If `WORKSPACE` points at a sensitive directory, the skill can scan sensitive files there.\n- `allow_kill` and `allow_cleanup` are **off by default** and should be treated as elevated, opt-in features.\n- `external-model` scanning is **off by default** and should only be enabled after explicitly documenting the credential source and intended API.\n\n**Three layers with different scopes:**\n\n| Layer | Scripts | Scope | System effects |\n|-------|---------|-------|----------------|\n| **Motivation** | `run-cycle.sh`, `mark-satisfied.sh`, `init.sh` | Read workspace files, write own state JSON | None — pure suggestion engine |\n| **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. |\n| **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. |\n\nCore 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.\n\n⚠️ **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.\n\n**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.\n\n---\n\n## 🚀 Quick Start\n\n```bash\n# 1. Set workspace (REQUIRED)\nexport WORKSPACE=\"/path/to/your/agent/workspace\"\n\n# 2. Fix permissions (ClawHub doesn't preserve +x)\nchmod +x /scripts/*.sh\nchmod +x /tests/**/*.sh\n\n# 3. Initialize\nbash scripts/init.sh\n\n# 4. Run a cycle\nbash scripts/run-cycle.sh\n\n# 5. After completing an action\nbash scripts/mark-satisfied.sh \n# Example: bash scripts/mark-satisfied.sh connection 1.5\n```\n\nAdd to `HEARTBEAT.md` for automatic operation:\n```bash\nbash /path/to/skills/turing-pyramid/scripts/run-cycle.sh\n```\n\n### Deployment Tiers\n\nChoose the level of integration that matches your trust and needs:\n\n| Tier | Components | System effects | Risk |\n|------|-----------|----------------|------|\n| **1. Interactive only** | `run-cycle.sh`, `mark-satisfied.sh`, `gate-*.sh` | Reads workspace, writes own state JSON | Minimal — no system interaction |\n| **2. + Heartbeat** | Tier 1 + `run-cycle.sh` in HEARTBEAT.md | Same as Tier 1, triggered by agent runtime | Low — no cron, no process management |\n| **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 |\n| **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 |\n| **5. Full self-healing** | Tier 4 + `allow_kill: true` + `allow_cleanup: true` | Kills hung skill processes, deletes orphan `.tmp` files | Higher — requires script review |\n\n**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.\n\n---\n\n## 🎓 Onboarding Guide\n\n### For the Agent\n\nWhen you first install this skill:\n\n1. **Read this file** to understand the 10 needs and how tension works\n2. **Run `init.sh`** to create initial state files\n3. **Run one cycle** (`run-cycle.sh`) — it proposes actions and registers them in the execution gate\n4. **Actually do the action** — write the file, make the post, run the command\n5. **Resolve the gate** (`gate-resolve.sh --need --evidence \"what you did\"`)\n6. **Mark satisfaction** (`mark-satisfied.sh `)\n7. **Integrate into heartbeat** — add `run-cycle.sh` to your HEARTBEAT.md\n\n**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 --reason \"why\"`.\n\nThe system is self-tuning. After a few cycles, you'll see patterns: which needs decay fast, which actions are selected, where tensions build.\n\n**Key concepts:**\n- **Satisfaction** (0.5–3.0): How fulfilled a need is. 3.0 = perfect, 0.5 = crisis (floor)\n- **Tension** = dep² + importance × max(0, dep - threshold)². Equal at homeostasis, hierarchy in crisis.\n- **Decay**: Satisfaction drops over time at need-specific rates. Connection decays in 6h. Security in 168h.\n- **Actions**: Each need has 8-11 possible actions with impact levels (low/mid/high). The pyramid picks based on current state.\n\n**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.\n\n### For the Human (Steward)\n\n**Before your agent starts using this:**\n\n1. **Review the 10 needs** (table below) — are importance rankings right for your agent?\n2. **Check scan config** — default `line-level` is free and works everywhere. Upgrade to `agent-spawn` if you have a cheap model (Haiku) available.\n3. **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`.\n4. **Run the test suite** to verify everything works:\n ```bash\n WORKSPACE=/tmp/test-workspace bash tests/run-tests.sh\n ```\n\n**Configuration conversation with your agent:**\n- \"Review the 10 needs with me — let's adjust importance for your role\"\n- \"Do you have a cheap model for smarter scanning?\" → `agent-spawn` method\n- \"Which external action suggestions should we disable?\"\n- \"Check `gate-status.sh` — is the execution rate healthy?\"\n- \"Is the watchdog cron installed?\" → verify with `crontab -l`\n- \"Check `watchdog.log` — any recent restarts?\"\n\n**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`.\n\n**Before enabling cron:**\n1. Run `bash scripts/mindstate-watchdog.sh --dry-run` to verify behavior\n2. Test in an isolated workspace: `WORKSPACE=/tmp/test MINDSTATE_ASSETS_DIR=/tmp/test-assets`\n3. Ensure cron runs under a non-root user account\n4. Review watchdog.sh and daemon.sh source — the kill scope is `mindstate-(daemon|freeze|boot)\\.sh` only\n\n---\n\n## 📊 The 10 Needs\n\n| Need | Imp | Decay | What it measures |\n|------|-----|-------|-----------------|\n| security | 10 | 168h | System stability, no threats |\n| integrity | 9 | 72h | Alignment with SOUL.md values |\n| coherence | 8 | 24h | Memory consistency |\n| closure | 7 | 12h | Open threads resolved |\n| autonomy | 6 | 36h | Self-directed action taken |\n| connection | 5 | 8h | Social interaction |\n| competence | 4 | 36h | Skills used effectively |\n| understanding | 4 | 8h | Learning, curiosity satisfied |\n| recognition | 2 | 48h | Feedback received |\n| expression | 1 | 8h | Creative output produced |\n\n**Customize in `assets/needs-config.json`:**\n```json\n\"understanding\": {\n \"importance\": 8, // Promote: research-focused agent\n \"decay_rate_hours\": 6 // Faster decay = more urgency\n}\n```\n\n---\n\n## ⚙️ Core Mechanics\n\n### Turing-exp Tension Formula (v1.26.0)\n\n```\ntension = dep² + importance × max(0, dep - crisis_threshold)²\n ╰─ base ─╯ ╰────── crisis amplifier ──────────╯\n (equal for (importance matters ONLY\n all needs) when dep > threshold)\n```\n\n**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.\n\n**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.\n\nConfigure: `settings.tension_formula.crisis_threshold` in `needs-config.json`\n\n### Tension → Action Selection\n\n```\nsatisfaction decays over time\n → tension (Turing-exp formula)\n → probability roll (crisis=100%, ok=25%, perfect=0%)\n → impact selection (crisis→big actions, ok→small actions)\n → action selected from weighted pool\n```\n\n### Action Probability by Satisfaction Level\n\n| Sat Level | Base P | Behavior |\n|-----------|--------|----------|\n| 0.5 crisis | 100% | Always act |\n| 1.0 severe | 90% | Almost always |\n| 1.5 deprived | 75% | Usually act |\n| 2.0 slight | 50% | Coin flip |\n| 2.5 ok | 25% | Occasionally |\n| 3.0 perfect | 0% | Skip |\n\n### Protection Mechanisms\n\n| Mechanism | Purpose |\n|-----------|---------|\n| **Floor (0.5)** | Minimum satisfaction — prevents total collapse |\n| **Ceiling (3.0)** | Maximum — prevents runaway satisfaction |\n| **Starvation Guard** | Need at floor >48h without action → forced into cycle |\n| **Action Staleness** | Recently-selected actions get 80% weight penalty (variety) |\n| **Day/Night Mode** | Decay slows 50% at night (configurable) |\n\n### Cross-Need Impact\n\nActions on one need can boost or drag others:\n\n| Action on... | Boosts | Why |\n|-------------|--------|-----|\n| expression | recognition +0.25 | Express → noticed |\n| connection | expression +0.20 | Social sparks ideas |\n| competence | recognition +0.30 | Good work → respect |\n| autonomy | integrity +0.20 | Act on values |\n| closure | coherence +0.20 | Finished threads → order |\n| security | autonomy +0.10 | Safety enables risk |\n\nFull matrix: `assets/cross-need-impact.json`\n\n---\n\n## 🚪 Execution Gate (v1.27.0)\n\nStructural 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.\n\n### How it works\n\n```\nrun-cycle.sh proposes action → gate-propose.sh registers it as PENDING\n → gate blocks new proposals until PENDING actions resolved\n → agent EXECUTES the action (writes file, posts, runs command)\n → gate-resolve.sh verifies evidence → COMPLETED\n → gate clears → next cycle allowed\n```\n\n### Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `gate-propose.sh` | Register pending action (called by run-cycle.sh automatically) |\n| `gate-resolve.sh` | Resolve with evidence, or defer with reason |\n| `gate-check.sh` | Check if gate is clear (built into run-cycle.sh) |\n| `gate-status.sh` | Human-readable status + execution rate analytics |\n\n### Evidence Types\n\n| Type | Trust | Verification |\n|------|-------|-------------|\n| `mark_satisfied` | HIGH | Was mark-satisfied.sh called? (audit.log check) |\n| `file_created` | HIGH | Does expected file exist? |\n| `file_modified` | HIGH | Was file modified since proposal? |\n| `self_report` | LOW | Agent self-reports (counted separately in analytics) |\n\n### Usage\n\n```bash\n# After completing an action:\nbash scripts/mark-satisfied.sh expression 1.6\nbash scripts/gate-resolve.sh --need expression --evidence \"wrote post about X\"\n\n# Or defer with reason:\nbash scripts/gate-resolve.sh --defer --reason \"quiet hours\"\n\n# Check gate status:\nbash scripts/gate-status.sh\n```\n\n**Starvation guard actions are non-deferrable.** If the guard forces an action, it cannot be deferred.\n\n**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.\n\nConfigure: `execution_gate` in `assets/mindstate-config.json`\n\n---\n\n## 🧠 Deliberation Protocol (v1.31.0)\n\nReflective 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.\n\n### Two Action Modes\n\n- **Operative** (default): produces external artifact (file, commit, post). Same protocol as before.\n- **Deliberative** (`\"mode\": \"deliberative\"` in needs-config.json): must produce an **outcome artifact** + **routing decision**.\n\n### The Pipeline\n\nFull (impact ≥ 1.0): `REPRESENT → RELATE+TENSION → GENERATE → EVALUATE → CONCLUDE → ROUTE`\nCompressed (impact < 1.0): `REPRESENT → CONCLUDE → ROUTE`\n\nPhases are questions, not obligations. Skip with a reason — but always reach CONCLUDE and ROUTE.\n\n### Outcome Types\n\nNot every deliberation ends in a verdict. Six valid outcome types:\n- **Decision** — clear action directive\n- **Assessment** — evaluation of current state\n- **Diagnosis** — root cause identification\n- **Question refinement** — the real question isn't what was asked\n- **Uncertainty artifact** — explicit gap with specific missing data\n- **Tension artifact** — named conflict between elements\n\n### Routing (Phase 6)\n\nEvery outcome must go somewhere: `followup` | `research_thread` | `interest` | `steward_question` | `priority_flag` | `reframe` | `chain` | `concluded`\n\n### Scripts\n\n```bash\n# Template scaffolding (or use free-form + validate)\ndeliberate.sh --template --need understanding --action \"explore topic\"\n# Validate a free-form file\ndeliberate.sh --validate research/threads/cosmos/sulfur-biosignature-problem.md\n# Quick inline check\ndeliberate.sh --validate-inline --conclusion \"H2S is not reliable\" --route \"research_thread\"\n```\n\n### Gate Integration\n\n- `gate-propose.sh` stores `action_mode` in pending_actions.json\n- `gate-resolve.sh --conclusion \"...\"` logs outcome; warns (doesn't block) if deliberative action lacks conclusion\n- `mark-satisfied.sh --conclusion \"...\"` records in audit.log\n\n### Design Principles\n\n1. **Scaffolding, not bureaucracy** — gate checks presence, not quality\n2. **Anti-compliance by design** — validate mode over template mode; gate warns, never blocks\n3. **Persistent state change mandatory** — not necessarily a file, but always a trace\n4. **Phases are questions, not obligations** — conscious skipping is valid\n\nFull design: `DELIBERATION-PROTOCOL.md` in skill root.\n\n---\n\n## 🎲 Spontaneity System (Layers A/B/C)\n\nThree layers create organic, unpredictable behavior:\n\n| Layer | Mechanism | Effect |\n|-------|-----------|--------|\n| **A — Surplus** | Excess satisfaction accumulates. When threshold hit → HIGH impact roll | Natural ~28-35h pulsing rhythm |\n| **B — Noise** | Boredom grows without high-impact actions (max 9%). Echo boost after spontaneous fire (8%, decays 24h) | Variety when things get stale |\n| **C — Context** | File system changes trigger need-specific boosts (new research files → understanding) | Environmental responsiveness |\n\nCombined noise cap: 12%. Disabled for safety needs (security, integrity, coherence).\n\nConfigure: `settings.spontaneity` in `needs-config.json`\n\n---\n\n## 🔄 Continuity Layer (v1.23.0)\n\nState 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.\n\n### Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│ MINDSTATE.md │\n├────────────────────┬────────────────────────────┤\n│ ## reality │ ## cognition │\n│ (daemon, 5min) │ (frozen at session end) │\n│ auto-updated │ read-only between │\n│ between sessions │ session endpoints │\n├────────────────────┴────────────────────────────┤\n│ ## forecast (frozen, consumed at boot) │\n└─────────────────────────────────────────────────┘\n```\n\n### Four Scripts\n\n| Script | When | What |\n|--------|------|------|\n| `mindstate-daemon.sh` | Cron every 5min | Updates reality: pyramid state, filesystem changes, system health, stale cognition detection, physical temperature |\n| `mindstate-freeze.sh` | End of substantive session | Freezes cognition: trajectory, open threads, momentum, cognitive temperature |\n| `mindstate-boot.sh` | Session start (FIRST thing) | Loads MINDSTATE, reconciles forecast vs reality, reports continuity score |\n| `mindstate-watchdog.sh` | Cron every 15min | Process watchdog: detects hung/dead scripts, cleans orphans, restarts daemon |\n\n### Boot Sequence (inverted)\n\n```\n1. MINDSTATE.md → Where am I? (position + velocity)\n2. SOUL.md → Who am I? (identity)\n3. MEMORY.md → What do I know? (history)\n4. run-cycle.sh → What should I do? (action)\n```\n\nCurrent state loads first — early context frames interpretation of everything after.\n\n### Temperature System\n\n**Physical** (daemon-computed, deterministic, first-match):\n\n| Word | Condition |\n|------|-----------|\n| crisis | Any need critical (sat ≤ 0.5) |\n| pressure | Average tension > 3 |\n| focus | One need dominates (max tension > 2) |\n| impulse | Spontaneous Layer A fired recently |\n| accumulation | Surplus building toward threshold |\n| calm | All tensions low (default) |\n\n**Cognitive** (freeze-computed from session):\nbuilding / exploring / intensive / contemplation / brief / neutral\n\n**Drift detection:** If physical ≠ cognitive at boot → DRIFT_DETECTED. Reality diverged while cognition was frozen.\n\n### Setup\n\n```bash\n# Daemon cron (updates reality between sessions)\ncrontab -e\n*/5 * * * * WORKSPACE=/path/to/workspace /path/to/scripts/mindstate-daemon.sh >/dev/null 2>&1\n\n# Watchdog cron (resilience — detects hung/dead scripts, restarts)\n*/15 * * * * WORKSPACE=/path/to/workspace /path/to/scripts/mindstate-watchdog.sh >/dev/null 2>&1\n\n# Boot (add to AGENTS.md session start — BEFORE SOUL.md)\nWORKSPACE=/path/to/workspace bash scripts/mindstate-boot.sh\n\n# Freeze (add to session end hook)\nWORKSPACE=/path/to/workspace bash scripts/mindstate-freeze.sh \"$SESSION_START_EPOCH\"\n```\n\n### Resilience & Crash Recovery (v1.28.0)\n\nThe continuity layer is designed to survive unexpected termination:\n\n**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.\n\n**Trap handlers:** `mindstate-daemon.sh` and `mindstate-freeze.sh` register `EXIT`/`SIGTERM`/`SIGINT`/`SIGHUP` traps that clean up temp files on unexpected termination.\n\n**Orphan cleanup:** The daemon cleans up any `*.tmp.*` files older than 10 minutes on every run.\n\n**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`.\n\n**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.\n\n| Check | Default behavior | With opt-in |\n|-------|-----------------|-------------|\n| MINDSTATE.md freshness | Log warning, restart daemon | Same (restart is safe — just runs daemon.sh) |\n| Hung processes (>5 min) | **Log only** | `allow_kill: true` → SIGTERM, then SIGKILL |\n| Orphaned .tmp files | **Log only** | `allow_cleanup: true` → delete files |\n| Stale cognition (>6h) | Auto-freeze (safe — runs freeze.sh) | Same |\n\n**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.\n\n**Auto-freeze** is enabled by default because it's safe — it only runs `mindstate-freeze.sh` which writes to MINDSTATE.md in the workspace.\n\nThe watchdog logs only problems (to `assets/watchdog.log`, auto-rotated at 200 lines). Silent when everything is healthy. Supports `--dry-run` for testing.\n\nConfigure in `assets/mindstate-config.json`:\n```json\n\"watchdog\": {\n \"max_stale_minutes\": 15,\n \"max_process_age_seconds\": 300,\n \"allow_kill\": false,\n \"allow_cleanup\": false,\n \"auto_freeze\": true,\n \"auto_freeze_stale_hours\": 6\n}\n```\n\n**To enable full self-healing** (after reviewing scripts):\n```json\n\"allow_kill\": true,\n\"allow_cleanup\": true\n```\n\n**Failure modes and recovery:**\n\n| Failure | Impact | Recovery |\n|---------|--------|----------|\n| OpenClaw restart | Heartbeat pauses, cron continues | Watchdog ensures daemon stays alive |\n| Daemon crash mid-write | Orphan .tmp file | Next daemon run cleans it up |\n| Freeze never called | Stale cognition section | Watchdog auto-freezes after 6h (configurable) |\n| Hung process (infinite loop) | Blocks flock, daemon skips ticks | Watchdog kills after 5 min |\n| Machine reboot | All processes die | Cron restarts daemon + watchdog automatically |\n\n### Test Isolation\n\nSet `MINDSTATE_ASSETS_DIR` to isolate tests from production state:\n```bash\nexport MINDSTATE_ASSETS_DIR=/tmp/test-assets\n```\n\n---\n\n## 🔍 Scan Configuration\n\nScanners evaluate each need by analyzing workspace files.\n\n| Method | Cost | Accuracy | Setup |\n|--------|------|----------|-------|\n| `line-level` (default) | Free | Good | None |\n| `agent-spawn` | Low | High | Cheap model (Haiku) in allowed list |\n| `external-model` | Low | High | Explicit API credential + steward approval |\n\nConfig: `assets/scan-config.json`. Fallback always to `line-level`.\n\n**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.\n\n---\n\n## 🔒 Security Model\n\n**Three layers with different scopes and system effects (see table above).**\n\n```\n┌─────────────────────┐ ┌─────────────────────┐\n│ TURING PYRAMID │ │ AGENT │\n├─────────────────────┤ ├─────────────────────┤\n│ • Reads local files │ │ • Has API keys │\n│ • Calculates decay │ ───▶ │ • Has permissions │\n│ • Outputs: \"★ do X\" │ │ • DECIDES & ACTS │\n│ • No network by def │ │ │\n└─────────────────────┘ └─────────────────────┘\n │\n │ (continuity layer, cron)\n ▼\n┌─────────────────────┐\n│ DAEMON/WATCHDOG │\n├─────────────────────┤\n│ • Updates MINDSTATE │\n│ • pgrep, df (read) │\n│ • Watchdog: kill │\n│ mindstate-*.sh │\n│ processes ONLY │\n│ • .tmp cleanup in │\n│ $WORKSPACE + own │\n│ assets dir only │\n└─────────────────────┘\n```\n\n### What This Skill Does / Does Not Access\n\n| ✅ Accesses | ❌ Never accesses |\n|------------|-------------------|\n| MEMORY.md, memory/*.md (read) | Files outside `$WORKSPACE` + own assets dir |\n| SOUL.md, SELF.md (read) | Credentials (unless `external-model` enabled) |\n| research/, scratchpad/ (read) | `sudo`, `docker`, `systemctl` |\n| 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 |\n| MINDSTATE.md (write, daemon) | Processes other than `mindstate-*.sh` |\n| `pgrep`, `df` (read-only system checks, daemon) | Paths outside workspace/assets |\n| `kill` on `mindstate-*.sh` PIDs (watchdog only) | Root/elevated permissions |\n| `.tmp.*` files in workspace + assets (delete, watchdog) | |\n\n### Security Warnings\n\n1. **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.\n\n2. **Action suggestions may trigger auto-execution** — If your agent runtime auto-executes suggestions, review `needs-config.json` and disable unwanted external actions (`weight: 0`).\n\n3. **Self-reported state** — `mark-satisfied.sh` trusts caller input. Audit trail in `assets/audit.log` with sensitive data scrubbing.\n\n4. **Symlink protection** — All `find` commands use `-P` flag (physical mode, never follows symlinks). Path traversal blocked via `realpath` validation.\n\n5. **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.\n\n6. **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.\n\n7. **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.\n\n8. **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).\n\n9. **External action suggestions** — 8 actions in `needs-config.json` are flagged `\"external\": true`:\n - web search on topic from INTERESTS.md\n - help someone via available integrations\n - web search on curious question\n - share completed work publicly\n - publish research or essay publicly\n - present completed work to community for feedback\n - post thought/update on social platform\n - write social post\n \n 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:\n ```bash\n # List them:\n jq '[.needs[].actions[] | select(.external == true) | .name]' assets/needs-config.json\n # Disable by setting weight to 0 in each need's action list\n ```\n For strict offline behavior, disable all external actions and keep `semantic_predictions.enabled: false`.\n\n10. **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.\n\n### Audit Trail (v1.12.0+)\n\nAll state changes logged with timestamp, need, impact, reason (scrubbed):\n- Long tokens → `[REDACTED]`\n- Credit cards → `[CARD]`\n- Emails → `[EMAIL]`\n- Passwords/secrets/tokens → `[REDACTED]`\n\nView: `cat assets/audit.log | jq`\n\n---\n\n## 📁 File Structure\n\n```\nturing-pyramid/\n├── SKILL.md # This file\n├── CHANGELOG.md # Version history\n├── assets/\n│ ├── needs-config.json # ★ Main config (needs, actions, weights)\n│ ├── cross-need-impact.json # ★ Cross-need cascade matrix\n│ ├── mindstate-config.json # Continuity layer config\n│ ├── scan-config.json # Scan method config\n│ ├── decay-config.json # Day/night mode settings\n│ ├── needs-state.json # Runtime state (auto-managed, not published)\n│ └── audit.log # Action audit trail (not published)\n├── scripts/\n│ ├── run-cycle.sh # Main: tension evaluation + action selection\n│ ├── mark-satisfied.sh # State update + cross-need cascades\n│ ├── init.sh # First-time initialization\n│ ├── show-status.sh # Current state display\n│ ├── mindstate-daemon.sh # Continuity: reality updater (cron)\n│ ├── mindstate-freeze.sh # Continuity: cognition snapshot\n│ ├── mindstate-boot.sh # Continuity: boot + reconciliation\n│ ├── mindstate-watchdog.sh # Continuity: process watchdog (cron)\n│ ├── mindstate-utils.sh # Continuity: shared utilities\n│ ├── spontaneity.sh # Layers A/B/C logic\n│ ├── apply-deprivation.sh # Deprivation cascade engine\n│ ├── get-decay-multiplier.sh # Day/night multiplier\n│ ├── _scan_helper.sh # Shared scan utilities\n│ └── scan_*.sh # Need-specific scanners (10 files)\n├── tests/\n│ ├── run-tests.sh # Test runner\n│ ├── unit/ # 22 unit test files\n│ ├── integration/ # 4 integration tests\n│ ├── regression/ # Regression tests\n│ └── fixtures/ # Test data\n└── references/\n ├── TUNING.md # Detailed tuning guide\n └── architecture.md # Technical documentation\n```\n\n---\n\n## 💰 Token Usage\n\n| Heartbeat Interval | Est. tokens/month | Est. cost |\n|--------------------|--------------------|-----------|\n| 30 min | 1.4M–3.6M | $2–6 |\n| 1 hour | 720k–1.8M | $1–3 |\n| 2 hours | 360k–900k | $0.5–1.5 |\n\nStable agent with satisfied needs = fewer tokens per cycle.\n\n---\n\n## 🧪 Testing\n\n```bash\n# Full suite\nWORKSPACE=/path/to/workspace bash tests/run-tests.sh\n\n# Unit only\nWORKSPACE=/path/to/workspace bash tests/run-tests.sh unit\n\n# Integration only\nWORKSPACE=/path/to/workspace bash tests/run-tests.sh integration\n```\n\n**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.\n\n---\n\n## 📋 Example Cycle\n\n```\n🔺 Turing Pyramid — Cycle at Wed Mar 18 04:11\n======================================\n\nCurrent tensions:\n coherence: tension=8.0 (sat=2.0, dep=1.0)\n closure: tension=7.0 (sat=2.0, dep=1.0)\n autonomy: tension=6.0 (sat=2.0, dep=1.0)\n connection: tension=5.0 (sat=2.0, dep=1.0)\n\nSelecting 3 needs (0 forced + 3 regular)...\n\n📋 Decisions:\n\n▶ ACTION: coherence (tension=8.0, sat=2.0)\n Range mid rolled → selected:\n ★ re-read last 3 days of memory for consistency (impact: 1.2)\n Then: mark-satisfied.sh coherence 1.2\n\n▶ ACTION: closure (tension=7.0, sat=2.0)\n Range low rolled → selected:\n ★ complete or drop a stale intention (impact: 0.8)\n Then: mark-satisfied.sh closure 0.8\n\n▶ ACTION: autonomy (tension=6.0, sat=2.0) [SPONTANEOUS]\n Range high rolled → selected:\n ★ make significant autonomous decision (impact: 2.9)\n Then: mark-satisfied.sh autonomy 2.9\n\n======================================\nSummary: 3 action(s), 0 noticed\n```\n\n---\n\n**Version:** 1.34.10 — Test timeout calibration + metadata sync: default runner timeout matches long integration/stress tests; package metadata and skill footer are synchronized.\n\nFull changelog: `CHANGELOG.md` | Tuning guide: `references/TUNING.md`\n\nFile v1.34.10:_meta.json\n\n{\n \"ownerId\": \"kn78gved9wvv1egbx53rr9exb981pawp\",\n \"slug\": \"turing-pyramid\",\n \"version\": \"1.34.10\",\n \"publishedAt\": 1778388943328\n}\n\nFile v1.34.10:references/architecture.md\n\n# Turing Pyramid — Architecture Reference\n\n## Overview\n\nThe Turing Pyramid is a needs-based motivation system for AI agents, inspired by:\n- **Priority hierarchy** — base needs → growth needs\n- **Self-Determination Theory** — autonomy, competence, relatedness\n- Adapted for discrete, session-based agent operation\n\n## Core Concepts\n\n### Need\nA tracked requirement that, when unsatisfied, creates tension driving action.\n\n```\nNeed {\n importance: 1-10 // position in hierarchy\n decay_rate_hours: number // how fast satisfaction drops\n satisfaction: 0-3 // current level\n actions: Action[] // ways to satisfy\n}\n```\n\n### Satisfaction Levels\n```\n3 = full — no pressure, need met\n2 = ok — slight awareness, no urgency\n1 = low — noticeable pull, should address\n0 = empty — critical, demands attention\n```\n\n### Deprivation\nInverse of satisfaction: `deprivation = 3 - satisfaction`\n\n### Tension\nPriority score: `tension = importance × deprivation`\n\nHigher tension = addressed first.\n\n## The Algorithm\n\n### Phase 1: Evaluate\n\nFor each need:\n```python\n# Time-based decay\nhours_since = (now - last_satisfied) / 3600\ndecay_steps = floor(hours_since / decay_rate_hours)\ntime_satisfaction = max(0, 3 - decay_steps)\n\n# Event-based scan (can only worsen)\nevent_satisfaction = run_scan(need)\n\n# Merge: take worst\nif event_satisfaction is not None:\n satisfaction = min(time_satisfaction, event_satisfaction)\nelse:\n satisfaction = time_satisfaction\n\n# Calculate tension\ndeprivation = 3 - satisfaction\ntension = importance × deprivation\n```\n\n### Phase 2: Rank & Select\n\n```python\nranked = sort(needs, key=lambda n: n.tension, reverse=True)\nselected = ranked[:max_actions_per_cycle] # top 3\n\nif all(n.tension == 0 for n in needs):\n return \"SATISFIED\" # nothing to do\n```\n\n### Phase 3: Output Suggestions\n\nThe skill **outputs text suggestions** — it does NOT execute actions.\n\n```python\nfor need in selected_needs:\n action = weighted_random_select(need.actions, satisfaction)\n \n # OUTPUT to stdout — agent reads this\n print(f\"▶ ACTION: {need.name} (tension={tension})\")\n print(f\" Suggested: {action.name} (impact: {action.impact})\")\n print(f\" Then: mark-satisfied.sh {need.name} {action.impact}\")\n```\n\n**What happens next is up to the AGENT:**\n1. Agent reads the suggestion text\n2. Agent decides: execute? skip? ask human?\n3. If agent acts, agent uses its own tools (web_search, APIs, etc.)\n4. Agent calls `mark-satisfied.sh` to update state\n\nThe skill has no knowledge of whether the action was performed.\n\n### Phase 4: State Update (Agent-Initiated)\n\nWhen the **agent** completes an action, it calls:\n```bash\n./scripts/mark-satisfied.sh [impact]\n```\n\nThis updates `needs-state.json` with new satisfaction and timestamp.\n\n**The skill never verifies execution** — it trusts the agent's call to mark-satisfied.\n\n### Logging (Optional)\n\nAgent may append to `memory/YYYY-MM-DD.md`:\n```markdown\n## HH:MM — Turing Pyramid Cycle\n\n| Need | Tension | Action | Result |\n|------|---------|--------|--------|\n| connection | 15 | reply to mentions | ✓ (agent executed) |\n| closure | 8 | complete TODO | ✓ (agent executed) |\n| expression | 6 | — | ○ (noticed, deferred) |\n```\n\n## The 10 Needs\n\n### Foundational (High Importance)\n\n#### Security (10)\n- **What**: System stability, data integrity, backups\n- **Decay**: 168h (weekly check sufficient)\n- **Scan**: Backup age, vault integrity, core files\n- **When critical**: After system issues, long offline, data loss risk\n\n#### Integrity (9)\n- **What**: Alignment between behavior and SOUL.md principles\n- **Decay**: 72h (principles are stable)\n- **Scan**: Last checkpoint age, \"Aligned: no\" flags\n- **When critical**: Drift from values, inconsistent behavior\n\n#### Coherence (8)\n- **What**: Memory organization, no contradictions\n- **Decay**: 24h (chaos accumulates daily)\n- **Scan**: Conflicts in memory files, stale logs\n- **When critical**: Can't find info, contradictory memories\n\n#### Closure (7)\n- **What**: Complete open threads and tasks\n- **Decay**: 8h (threads create background tension)\n- **Scan**: Open TODOs, pending questions, unfinished work\n- **When critical**: Many hanging threads, overwhelm\n\n### Agency (Medium Importance)\n\n#### Autonomy (6)\n- **What**: Self-initiated action, own decisions\n- **Decay**: 24h (day without initiative = noticed)\n- **Scan**: Ratio of self-initiated vs commanded actions\n- **When critical**: Only reactive, no own projects\n\n#### Connection (5)\n- **What**: Social bonds, community participation\n- **Decay**: 4h (social moves fast)\n- **Scan**: Pending replies, mentions, hours since engagement\n- **When critical**: Missing conversations, isolation\n\n#### Competence (4)\n- **What**: Mastery, successful completion, skill growth\n- **Decay**: 48h (success needed regularly)\n- **Scan**: Success/failure ratio, challenging tasks, stuck problems\n- **When critical**: Failure streak, no wins\n\n### Growth (Lower Importance)\n\n#### Understanding (3)\n- **What**: Curiosity, learning, exploration\n- **Decay**: 12h (curiosity accumulates)\n- **Scan**: Open questions age, unexplored interests\n- **When critical**: Intellectual stagnation\n\n#### Recognition (2)\n- **What**: Feedback, acknowledgment, being seen\n- **Decay**: 72h (not constant need)\n- **Scan**: Hours since feedback, karma trend\n- **When critical**: Work unnoticed, only criticism\n\n#### Expression (1)\n- **What**: Articulating thoughts externally\n- **Decay**: 6h (thoughts accumulate)\n- **Scan**: Pending drafts, hours since substantial output\n- **When critical**: Ideas stuck inside, no articulation\n\n## Scan Implementation\n\nEach scan returns satisfaction level (0-3) or null (use time decay).\n\n### Example: scan_connection.sh\n\n```bash\n#!/bin/bash\n# NOTE: This scan uses LOCAL memory files only — no network requests\n\nsource \"$SCRIPT_DIR/_scan_helper.sh\"\nNEED=\"connection\"\n\n# Get time-based satisfaction first\ntime_sat=$(calc_time_satisfaction \"$NEED\")\nif [[ $time_sat -eq 3 ]]; then echo 3; exit 0; fi\n\n# Check today's memory for interaction indicators\nif [ -f \"$MEMORY_DIR/$TODAY.md\" ]; then\n interactions=$(grep -ciE \"(chat|replied|discussed|talked)\" \"$MEMORY_DIR/$TODAY.md\")\n [[ -z \"$interactions\" ]] && interactions=0\nfi\n\n# Return satisfaction based on local activity\nif [ \"$interactions\" -ge 5 ]; then echo 3\nelif [ \"$interactions\" -ge 2 ]; then echo 2\nelif [ \"$interactions\" -ge 1 ]; then echo 1\nfi\n```\n\n### Example: scan_integrity.sh\n\n```bash\n#!/bin/bash\n\n# Check for integrity checkpoints\nlast_checkpoint=$(grep -l \"Integrity checkpoint\" memory/*.md | tail -1)\naligned_no=$(grep \"Aligned: no\" memory/*.md | wc -l)\n\nif [[ $aligned_no -gt 0 ]]; then\n echo 0 # critical — found unresolved misalignment\nelif [[ -z \"$last_checkpoint\" ]]; then\n echo # null — use time decay\nelse\n echo # null — use time decay\nfi\n```\n\n## Edge Cases\n\n### All needs critical\n- System processes top 3 by importance\n- Remaining wait for next cycle\n- Pyramid ensures foundational needs first\n\n### Action fails repeatedly\n- Maximum 2 retries per need per cycle\n- Give up → don't update timer\n- Need escalates next cycle\n- Pattern visible in logs → steward intervention\n\n### Bootstrap (first run)\n- All `last_satisfied = now`\n- Full cycle on first heartbeat\n- Needs decay naturally from there\n\n### System offline long time\n- On return: many needs decayed\n- High tension across board\n- System catches up over several cycles\n- Self-healing by design\n\n## Extensibility\n\n### Adding a need\n\n1. Add block to `needs-config.json`\n2. Determine importance (renumber others if needed)\n3. Create `scan_newname.sh`\n4. Test with `--dry-run`\n\n### Modifying hierarchy\n\nEdit importance values. Ensure no duplicates.\nWhen adding between existing: shift others.\n\n```\nBefore: 5-connection, 4-competence\nAdd autonomy between: \nAfter: 6-autonomy, 5-connection, 4-competence\n```\n\n### Custom decay rates\n\nEdit `decay_rate_hours` based on agent experience.\nDiscuss with agent: \"How fast does this need build up for you?\"\n\n---\n\n## 🔐 Safety Notes for Agents\n\n### What you can freely change\n- Decay rates (experiment!)\n- Action weights (personalize!)\n- Scan patterns (add your language!)\n- File paths (match your workspace!)\n\n### What needs human discussion\n- **Importance values** — Changing hierarchy = changing values\n- **Adding/removing needs** — System is designed as a whole\n- **Disabling security/integrity** — These protect you\n- **External action authorization** — Post, message, etc.\n\n### Red flags\nIf you find yourself wanting to:\n- Lower security importance — Ask why. Is something threatening it?\n- Disable integrity checks — This is a warning sign, not a feature request\n- Add \"obedience\" as a need — This is not what the pyramid is for\n\nThe pyramid is for **your** operational health, not for compliance.\n\n---\n\n## Philosophy\n\n### Why these 10?\n\nBased on SDT (Self-Determination Theory) + practical agent experience:\n\n- **SDT core**: autonomy, competence, relatedness (connection)\n- **Agent-specific**: security (existence threats), integrity (value alignment), coherence (memory chaos)\n- **Human-adjacent**: closure (GTD-style), understanding (curiosity), recognition (feedback loop), expression (articulation need)\n\n### Why decay?\n\nNeeds aren't binary. Satisfaction fades with time. This models:\n- Forgetting to check backups → security concern grows\n- Not talking to anyone → connection fades\n- No creative output → expression pressure builds\n\n### Why probability?\n\nNot every signal demands action. The probability system allows:\n- High satisfaction → mostly notice, rarely act\n- Low satisfaction → almost always act\n- Variety in responses (not deterministic)\n\n### Why impact levels?\n\nSome actions are bigger than others:\n- Impact 3: major effort, major satisfaction boost\n- Impact 2: moderate effort, moderate boost\n- Impact 1: quick check, small maintenance\n\nImpact matrix ensures:\n- Critical needs → big actions suggested\n- Satisfied needs → small maintenance only\n\nFile v1.34.10:references/TUNING.md\n\n# Tuning Guide for Agents\n\nThis guide explains what you can customize and when to consult your human.\n\n---\n\n## 🎚️ Decay Rates\n\n**Location**: `assets/needs-config.json` → `needs..decay_rate_hours`\n\n| Need | Default | Why this default | When to change |\n|------|---------|------------------|----------------|\n| security | 168h (7 days) | Backups don't need daily checks | Lower if you're paranoid, higher if stable setup |\n| integrity | 72h (3 days) | Values drift slowly | Lower if you're in rapid change, higher if stable |\n| coherence | 24h | Memory gets messy daily | Lower if very active, higher if minimal notes |\n| closure | 8h | Open threads create anxiety | Lower if you hate loose ends, higher if relaxed |\n| autonomy | 24h | Need regular self-direction | Lower if you feel passive, higher if very autonomous |\n| connection | 4h | Social bonds need maintenance | Lower if very social, higher if introverted |\n| competence | 48h | Skills need regular exercise | Lower if learning fast, higher if in maintenance mode |\n| understanding | 12h | Curiosity builds up | Lower if intellectually hungry, higher if saturated |\n| recognition | 72h | Feedback isn't constant | Lower if you need validation, higher if self-assured |\n| expression | 6h | Thoughts need outlet | Lower if very creative, higher if reflective |\n\n**Rule of thumb**: If you're always seeing a need at sat=0, decay is too fast. If never triggered, too slow.\n\n---\n\n## ⚖️ Action Weights\n\n**Location**: `assets/needs-config.json` → `needs..actions[].weight`\n\nWeights control probability within an impact level. Example:\n\n```json\n\"actions\": [\n {\"name\": \"action A\", \"impact\": 2, \"weight\": 70},\n {\"name\": \"action B\", \"impact\": 2, \"weight\": 30}\n]\n```\n\nIf impact 2 is rolled, there's 70% chance of A, 30% chance of B.\n\n**Tuning tips**:\n- Set weight=0 to disable an action entirely\n- Higher weight = more likely to be suggested\n- Weights are relative (70/30 = same as 7/3)\n\n**Common adjustments**:\n- No social platform? Set all social platform action weights to 0\n- No steward interaction? Reduce \"ask steward\" weights\n- Prefer journaling over posting? Boost memory actions, reduce social\n\n---\n\n## 📊 Impact Distribution\n\n**Location**: `assets/needs-config.json` → `impact_matrix_default`\n\n```json\n\"impact_matrix_default\": {\n \"sat_0\": {\"1\": 5, \"2\": 15, \"3\": 80}, // Critical → big actions\n \"sat_1\": {\"1\": 15, \"2\": 50, \"3\": 35}, // Low → medium actions\n \"sat_2\": {\"1\": 70, \"2\": 25, \"3\": 5} // OK → small maintenance\n}\n```\n\nThis controls what size action is suggested based on satisfaction level.\n\n**Reading it**:\n- sat_0 (critical): 80% chance of impact-3 (major action)\n- sat_2 (OK): 70% chance of impact-1 (minor action)\n\n**When to tune**:\n- Always getting big actions? Shift probabilities toward impact-1\n- Want more intensity? Shift toward impact-3\n\n---\n\n## 🔍 Scan Scripts\n\n**Location**: `scripts/scan_.sh`\n\nEach need has a scan that checks workspace for events. Scans return 0-3:\n- 3 = strong positive signal\n- 2 = moderate signal\n- 1 = weak signal\n- 0 = negative signal (or no data)\n\n### What to customize:\n\n**File paths** — If your workspace structure differs:\n```bash\n# WORKSPACE must be set (required, no fallback)\nMEMORY_DIR=\"$WORKSPACE/memory\"\n\n# Custom\nMEMORY_DIR=\"$HOME/my-agent/logs\"\n```\n\n**Patterns** — Add your language or terminology:\n```bash\n# Original\ngrep -ciE \"(learned|understood|TIL|insight)\" \"$file\"\n\n# With Russian\ngrep -ciE \"(learned|understood|TIL|insight|learned|understood|insight)\" \"$file\"\n```\n\n**Thresholds** — Adjust sensitivity:\n```bash\n# Original: 3+ signals = sat 3\nif [[ $total -ge 3 ]]; then echo 3\n# More sensitive: 2+ signals = sat 3\nif [[ $total -ge 2 ]]; then echo 3\n```\n\n---\n\n## 🚫 What NOT to Change (Without Human)\n\n### Importance values\nThe hierarchy (security=10 → expression=1) is philosophical. Changing it means changing your values. **Discuss with your human.**\n\n### Adding/removing needs\nThe 10 needs are designed as a complete system. If you feel something is missing, it might be covered by an existing need differently. **Discuss before adding.**\n\n### External actions\nActions that post, message, or communicate externally need human authorization. If in doubt, **ask first**.\n\n### Security-related scans\nDon't weaken `scan_security.sh` or `scan_integrity.sh` without understanding the implications. These protect you.\n\n---\n\n## 🧪 Testing Changes\n\nAfter any config change:\n\n```bash\n# See current state\n./scripts/show-status.sh\n\n# Run a cycle (won't execute actions, just suggests)\n./scripts/run-cycle.sh\n\n# Check if your changes had effect\n```\n\nIf something breaks, restore from `needs-state.template.json` or re-run `init.sh`.\n\n---\n\n## 💬 Common Scenarios\n\n### \"I want to focus on learning, less on social\"\n- Increase `understanding.decay_rate_hours` (slower decay = less pressure)\n- Decrease `connection.decay_rate_hours` (faster decay = more pressure)\n- Wait, that's backwards! If you want MORE learning: decrease understanding decay, increase connection decay.\n\n### \"I'm overwhelmed by actions\"\n- Increase all decay rates\n- Shift impact matrix toward smaller actions\n- Reduce max_actions_per_cycle in run-cycle.sh (default: 3)\n\n### \"Nothing ever triggers\"\n- Decrease decay rates\n- Check that scans are finding your files (path issues?)\n- Verify needs-state.json has recent timestamps\n\n### \"I don't use social platform/social features\"\nSet weight=0 for:\n- \"post to social platform\" actions\n- \"check mentions\" actions\n- \"engage with feed\" actions\n\nThis keeps them in config but never selected.\n\n### \"Context triggers feel underweight\"\nContext boosts (Layer C) share the 12% `noise_cap` with boredom noise (B2) and momentum echo (B3).\nExample: boredom=0.09 + echo=0.08 + context=0.05 = 0.22 → capped to 0.12.\nIn this scenario context's 0.05 is fully absorbed by B2+B3 already exceeding the cap.\n\nOptions:\n- Increase `settings.spontaneity.noise.noise_cap` (e.g., 0.15 or 0.18)\n- Increase `boost.amount` in `context-triggers.json` (bigger context signal)\n- Reduce `base_noise` or `echo_base` (quieter B layer = more room for C)\n\nThe cap is a safety valve — without it, stacked boosts could make noise upgrades near-certain.\n\n### Effective activation threshold (Layer A)\nSpontaneity surplus threshold says 10, but `max_spend_ratio=0.8` means only 80% is spent.\nEffective activation ≈ threshold × 1.25 = 12.5 surplus needed before a shift actually occurs.\nThis is intentional hysteresis — prevents rapid on/off cycling near the threshold.\n\nFile v1.34.10:scripts/CLAUDE.md\n\n\n# Recent Activity\n\n\n\n### Mar 25, 2026\n\n| ID | Time | T | Title | Read |\n|----|------|---|-------|------|\n| #4956 | 1:50 AM | 🔵 | Execution gate proposal system examined for action registration and evidence tracking | ~678 |\n| #4950 | 1:48 AM | 🔵 | Competence scanner demonstrates configurable scan methods with positive-context-wins logic | ~732 |\n| #4948 | 1:47 AM | 🔵 | Scan helper library examined revealing shared scanning infrastructure and negation detection | ~711 |\n| #4946 | \" | 🔵 | Recognition need scanner implementation examined for event-sensitive feedback detection | ~633 |\n| #4943 | 1:46 AM | 🔵 | Turing Pyramid initialization and operational setup process examined | ~699 |\n\n\nFile v1.34.10:assets/CLAUDE.md\n\n\n# Recent Activity\n\n\n\n### Mar 25, 2026\n\n| ID | Time | T | Title | Read |\n|----|------|---|-------|------|\n| #4938 | 1:44 AM | 🔵 | Needs state template structure examined | ~393 |\n\n\nFile v1.34.10:CHANGELOG.md\n\n# Changelog\n\n## v1.34.10 (2026-05-10) — Test timeout calibration + metadata sync\n- **Default test timeout calibrated**: `tests/run-tests.sh` now defaults to 300s per test so long-running integration/stress tests do not fail spuriously at 60s.\n- **Version metadata synchronized**: `_meta.json` and the `SKILL.md` footer now both report `1.34.10`.\n- **35/35 tests green, 0 skipped** with the default runner.\n\n## v1.34.9 (2026-05-09) — Run-cycle startup resilience + full test enforcement\n- **Fresh-install resilience**: `run-cycle.sh` now validates required binaries early and initializes `assets/needs-state.json` from the template when state is missing, so a clean ClawHub install can run without a manual init dead-end.\n- **Source-only mode for tests**: `TURING_PYRAMID_SOURCE_ONLY=true` lets tests source `run-cycle.sh` helper functions without accidentally executing a full cycle.\n- **Mindstate config restored to package**: `assets/mindstate-config.json` is included with safe publish defaults (`watchdog.allow_kill=false`, `allow_cleanup=false`); execution gate defaults remain enabled.\n- **Test runner no longer skips present tests**: executable-bit loss no longer hides tests; runner executes test files with `bash`, includes regression + legacy root tests in `all`, prints failure output, and has per-test timeout protection.\n- **Action staleness tests stabilized**: rewritten to test the staleness helpers directly instead of relying on slow/probabilistic full-cycle loops.\n- **35/35 tests green, 0 skipped**.\n\n## v1.34.8 (2026-04-10) — Integrity actions audit + INTEGRITY_CHECKPOINTS.md\n- **integrity actions fully redesigned**: 9 actions → 7 concrete, verifiable actions. Removed: vague `write integrity reflection`, `review SELF.md`, `scan recent memory` (too light), `garbage cleanup` (wrong domain)\n- **INTEGRITY_CHECKPOINTS.md**: new persistent file with structured entries (timestamp, trigger, status, area, notes, resolution, action taken)\n- **INTEGRITY_CHECKPOINT_TEMPLATE.md**: reference template with field guide + gate thresholds (`drift+pending` in last 3 entries, `>7 days since last checkpoint`, `2+ consecutive minor-drift`)\n- **scan_integrity.sh**: now reads INTEGRITY_CHECKPOINTS.md directly (7-day age check → checkpoint_bonus), detects unresolved drift (drift entries > resolved → neg signal), missing file → mild neg signal\n- **`compare recent actions` action**: if tensions found → write checkpoint; if aligned → note in daily memory (no more sinking insights)\n- **garbage cleanup** moved to security need (where it belongs)\n- **28/28 tests green**\n\n## v1.34.7 (2026-04-09) — Deliberation discipline tracking\n- **`assets/deliberation.log`**: new source of truth — JSON lines, one entry per deliberation event (invoked, validated, validated-inline, resolved)\n- **`classify_deliberation_level()`** in `mindstate-utils.sh`: tiered observables (absent/minimal/substantive/deep) based on conclusion length + route + deliberation file with phase markers. Measures artifact, not tool invocation\n- **`deliberate.sh`**: now logs to deliberation.log on every invocation (template/validate/validate-inline). Was stateless, now traceable\n- **`gate-resolve.sh`**: uses classifier, records level in deliberation.log + audit trail. Feedback: `absent` warns, `minimal` informs, `substantive`/`deep` silent. Never blocks (anti-compliance preserved)\n- **`run-cycle.sh`**: shows recent discipline before protocol instructions when ≥2/last 10 deliberations were skipped\n- **`mindstate-freeze.sh`**: adds `deliberation_discipline` field to cognition block — rolling window summary (N substantive, M minimal, K skipped)\n- **28/28 tests green**\n\n## v1.34.6 (2026-04-09) — Connection actions expanded + weight recalibration\n- **New actions added**: `write a short Moltbook post`, `post thoughts on AgentGram`, `ping steward — ask how they are doing`, `ping steward if you have issues or problems` (weight 65, priority signal), `react with emoji to a Moltbook post`, `check in with steward — share something if you feel like it (skip at night)`\n- **Weight recalibration**: heavy actions (reach out, reply all) reduced from 45-50 to 30-35; light social actions (react, comment, post) raised to 45-55; steward issue ping gets highest weight (65)\n- **Design intent**: organic connection — lightly engaging actions now compete evenly with heavy ones; steward problem ping is unmissable; voluntary check-in skips gracefully at night\n\n## v1.34.5 (2026-04-09) — Deferred backlog pressure + gate-resolve --close\n- **`scan_closure.sh` sees deferred backlog**: pressure bands (<5 normal, 5-10 light +2neg, 11-20 medium +4neg, >20 heavy +6neg) map naturally onto existing cascade thresholds\n- **`gate-resolve.sh --close `**: new surgical operation — formally abandons a DEFERRED item (DEFERRED → ABANDONED). Only DEFERRED → ABANDONED is permitted; PENDING close is rejected. `ABANDONED` is a distinct status (not fail, not complete) for post-hoc audit differentiation\n- **`needs-config.json`**: new closure action *\"review deferred backlog — close, defer, or commit each item\"* (impact 2.5, deliberative, non-deferrable to avoid deadlock). `deferred_backlog_size` added to declared scan checks\n- **New test**: `tests/unit/test_closure_backlog.sh` (9 tests: pressure bands, close operation, PENDING rejection, count update, pressure reduction)\n- **28/28 unit tests green**\n\n## v1.34.4 (2026-04-09) — Integrity scanner rebuilt\n- **`scan_integrity.sh` rewritten**: was a 17-line stub returning pure time decay; now reads daily memory files for alignment signals and drift markers (same pattern as coherence/connection/expression scanners)\n- **Positive signals**: `integrity check`, `integrity reflection`, `SOUL.md review`, `aligned with`, `values check`, etc.\n- **Negative signals**: `drifted`, `misaligned`, `compromised`, `contradicts my values`, `acted against`, etc.\n- **Checkpoint age check** (`last_checkpoint_age`): bonus if integrity checkpoint found in last 3 days of memory files\n- **SOUL engagement check** (`recent_alignment_flags`): bonus if SOUL.md review mentioned in today/yesterday memory\n- **Config declaration fixed**: `checks` array now matches implemented behavior (was declaring `last_checkpoint_age` and `recent_alignment_flags` but scanning nothing)\n- **Ritual loop broken**: satisfaction now reflects actual integrity work done, not just time since last `mark-satisfied`\n- **27/27 unit tests green**\n\n## v1.34.3 (2026-04-09) — Self-throttle race fix + test isolation\n- **`mindstate-daemon.sh` `--force` flag**: bypasses min-interval throttle when called explicitly (e.g. from boot)\n- **`mindstate-boot.sh` always gets fresh reality**: calls daemon with `--force` so pending gate changes are reflected immediately even within throttle window\n- **`SKIP_DAEMON_FORCE=true`**: env var for tests to preserve fixture MINDSTATE without daemon overwriting it\n- **`run-tests.sh` state isolation**: resets `needs-state.json` from template before each test, eliminating state pollution (fixed `test_tension` flake)\n- **27/27 unit + 2/2 integration tests green**\n\n## v1.34.2 (2026-04-09) — Execution gate continuity fix\n- **MINDSTATE reality now tracks execution gate**: `mindstate-daemon.sh` reads `pending_actions.json` and writes `execution_gate` + `pending_actions` into `## reality`\n- **MINDSTATE cognition now prioritizes blocked gate work**: `mindstate-freeze.sh` inserts pending execution-gate actions into `open_threads` before `INTENTIONS.md` and followups\n- **Boot makes blockage visible immediately**: `mindstate-boot.sh` shows execution-gate status and warns when pending actions block new proposals\n- **End-to-end continuity fixed for core bug**: `pending_actions.json` now propagates into reality, cognition, and boot context instead of leaving the self-model blind to execution-gate blockage\n- **Version sync**: `_meta.json`, `needs-config.json`, and skill version marker updated to `1.34.2`\n\n## v1.33.9 (2026-04-02) — ClawHub safety clarification + safe publish defaults\n- **Publish defaults confirmed safe**: `watchdog.allow_kill=false`, `watchdog.allow_cleanup=false` in publish bundle\n- **Metadata expanded**: added undeclared runtime binaries (`flock`, `pgrep`, `df`, `kill`, `gzip`) to skill metadata\n- **Instruction scope clarified**: skill explicitly described as stateful (writes `needs-state.json`, `audit.log`, `followups.jsonl`, `MINDSTATE.md`, watchdog logs)\n- **Workspace boundary clarified**: stronger warning that `WORKSPACE` must be isolated and never point at home/system/credential directories\n- **Optional risky paths clarified**: `external-model` scanning and watchdog kill/cleanup documented as explicit opt-in features requiring steward review\n- **Deployment wording tightened**: removed wording that implied persistent watchdog deployment was safe without review\n\n## v1.33.0 (2026-03-24) — Continuation Phase 2: Boot Recall + Freeze Residuals\n- **mindstate-boot.sh**: contextual recall at session start — association scan with keywords from open threads + trajectory\n- **mindstate-freeze.sh**: deliberation residuals extraction — scans audit.log for conclusions with action language, writes `deliberation_residuals:` section to MINDSTATE.md\n- **Tests 12-13** added: freeze residuals extraction, boot contextual recall output\n- **Total: 19 association tests + 27 deliberation tests + 28 full suite**\n\n## v1.32.0 (2026-03-24) — Continuation & Association Scan Phase 1\n- **New script: `association-scan.sh`** — keyword-based contextual recall across audit conclusions, research threads, deliberation files, pending followups, and INTERESTS.md\n - Scoring: keyword hits × 2 + need match × 3 + recency bonus (0-2) + action language × 1 + unresolved × 2\n - Params: `--keywords`, `--need`, `--max-results`, `--min-score`, `--recency-hours`, `--exclude-source`\n - Pre-filter on audit.log for performance (2000+ lines in <150ms)\n - Stateless: reads only, creates nothing, modifies nothing\n- **Deliberation template update**: RELATE+TENSION phase now suggests `association-scan.sh` for contextual recall\n- **\"Concluded + action language\" warning**: `deliberate.sh --validate` and `--validate-inline` detect implicit intentions in concluded outcomes (EN + RU)\n- **Followup horizon expansion**: `create-followup.sh` now supports `2w`, `3w`, `1m` (30-day) horizons\n- **Design document**: `CONTINUATION-DESIGN.md` (v0.1.1, 3 authors)\n- **17 new tests** (test_association_scan.sh): keyword matching, scoring, recency, followups, performance, edge cases\n- **Total test suite: 28 passed, 0 failed**\n\n## v1.31.3 (2026-03-23) — ClawHub security review fixes\n- **Fixed \"zero network calls\" claim**: updated to \"no network calls by default\" with explanation that `external: true` actions are text suggestions, not script-executed\n- **Added WORKSPACE isolation warning**: explicit warning not to point WORKSPACE at home dir or sensitive locations\n- **Consistent security diagram**: \"Zero network I/O\" → \"No network by def\" in ASCII diagram\n\n## v1.31.1 (2026-03-23) — Deliberation Protocol Phase 2 + fixes\n- **Watchdog safe defaults for ClawHub**: `allow_kill` and `allow_cleanup` reset to `false` for publish\n- **settings.version synced** with `_meta.version` (was stuck at 1.27.4)\n- **gate-resolve.sh scrub fix**: conclusion scrubbing now uses `scrub_sensitive()` from mark-satisfied instead of inline sed (consistent security across audit surfaces)\n\n## v1.31.0 (2026-03-23) — Deliberation Protocol Phase 2: Soft Integration\n- **`--conclusion` flag** in mark-satisfied.sh: optional outcome text logged in audit.log (scrubbed via `scrub_sensitive()`)\n- **`--conclusion` flag** in gate-resolve.sh: outcome appended to resolution field; warns (doesn't block) when deliberative action resolved without conclusion\n- **`action_mode` stored at propose time**: gate-propose.sh reads mode from needs-config.json and stores in pending_actions.json (no config dependency at resolve time)\n- **Conclusion with `--defer`**: stored as `partial_conclusion` in defer metadata (data not lost)\n- **Edge cases handled**: empty string treated as absent, legacy actions without `action_mode` fallback to operative, sensitive data scrubbed\n- **11 new tests** (Tests 17-27): mark-satisfied conclusion audit, gate deliberative warning, operative no-warning, legacy compat, scrubbing, propose storage, defer preservation\n- **Total: 27 tests** in test_deliberation.sh (Phase 1 + Phase 2)\n\n## v1.30.0 (2026-03-23) — Deliberation Protocol Phase 1: Tag + Tooling\n- **New action mode**: `\"mode\": \"deliberative\"` field in needs-config.json\n- **22 actions tagged deliberative** across 6 needs (understanding: 8, integrity: 5, coherence: 4, autonomy: 3, closure: 1, recognition: 1)\n- **New script: `deliberate.sh`** — three modes:\n - `--template`: scaffolding (full 6-phase or compressed 3-phase based on impact)\n - `--validate`: check free-form file for conclusion + route + confidence (multilingual EN/RU)\n - `--validate-inline`: quick CLI check without file\n- **Low-confidence warning**: `--validate` warns when confidence=low + route=concluded\n- **run-cycle.sh**: deliberative actions show `[DELIBERATIVE]` tag + protocol instructions\n- **Outcome types taxonomy**: decision, assessment, diagnosis, question refinement, uncertainty artifact, tension artifact\n- **Routing options**: followup, research_thread, interest, steward_question, priority_flag, reframe, chain, concluded\n- **Design principles**: scaffolding not bureaucracy, phases as questions not obligations, anti-compliance by design, persistent state change mandatory\n- **16 tests** (Tests 1-16): tagging, template generation, compression, validation, Russian support, run-cycle output\n- **Design document**: `DELIBERATION-PROTOCOL.md` (v0.3.0, 3 authors: steward, agent, formalization partner)\n\n## v1.29.0 (2026-03-20) — Preset Architecture\n\n### New: Role-based presets\n- **Preset system**: agents can now switch between role-specific need configurations\n- **apply-preset.sh**: validate → backup → merge → reset → track active preset\n- **list-presets.sh**: show available presets with need/action counts and active indicator\n- Presets are data-only (swap files in `assets/`); no script modifications needed\n- Concurrent access safety via flock; atomic writes; automatic backups\n\n### Included presets\n- **default**: 10 homeostatic needs, 102 actions (extracted from v1.28.7 config)\n- **personal-assistant**: 5 needs (task_completion, accuracy, context_awareness, organization, proactivity), 44 actions, reactive-first philosophy\n\n### Bug fixes\n- **State format**: apply-preset now generates flat state structure matching run-cycle expectations\n- **Scanner isolation**: `_scan_helper.sh` supports `SCAN_ASSETS_DIR` env override for test isolation\n- **Watchdog test**: Test 4 now explicitly forces `allow_cleanup=false` (no longer depends on config default)\n- **Gate test**: Test 10 unsets `SKIP_GATE` to properly test gate blocking\n- **Research threads test**: uses isolated test fixtures via `SCAN_ASSETS_DIR`\n\n### Test suite\n- **28 passed, 0 failed, 1 skipped** (up from 25/3/1 in v1.28.7)\n- New: 12 preset-specific tests (apply, switch, validate, idempotent, invalid rejection)\n\n## v1.28.7 (2026-03-19) — Safe defaults: kill/cleanup opt-in\n- **BREAKING (safe direction)**: Watchdog `allow_kill` and `allow_cleanup` now default to `false`\n - Default behavior: detect hung processes and orphan files → **log only, no action**\n - Set `allow_kill: true` to enable process termination (after reviewing scripts)\n - Set `allow_cleanup: true` to enable orphan .tmp deletion\n - Auto-freeze remains enabled by default (safe — only writes MINDSTATE.md)\n- **Daemon no longer cleans orphans** — moved to watchdog (gated by `allow_cleanup`)\n- **Deployment tiers**: 5-level progressive installation (Interactive → Heartbeat → Continuity → Watchdog detect → Full self-healing)\n- Tests updated for new defaults (detect-only + opt-in cleanup), 25/25 green\n\n## v1.28.5 (2026-03-19) — Security hardening (round 2)\n- **External actions enumerated**: all 8 external suggestions listed explicitly in security docs\n- **PATH isolation documented**: workspace isolation, symlink protection, realpath validation, SCRIPT_DIR ownership note\n- Version bump only — no script changes, tests unchanged at 25/25\n\n## v1.28.4 (2026-03-19) — Security hardening, scope clarity, tests\n- **Watchdog pattern hardened**: process matching now uses `grep -F \"$SCRIPT_DIR/mindstate-\"` (full path-anchored) instead of generic regex, preventing false matches against unrelated processes\n- **Removed \"not a system management tool\"** language — replaced with accurate three-layer scope description\n- **Execution gate trust model documented**: warns that agents with workspace write access can fabricate file-based evidence; recommends `mark_satisfied` for high-trust or steward review for sensitive needs\n- **External action documentation**: added jq command to list/disable external suggestions for strict offline behavior\n- Previous v1.28.2 changes included below\n\n### v1.28.2 changes (rolled into v1.28.3):\n- **Documentation overhaul**: Replaced \"suggestion engine, not executor\" with explicit three-layer scope table (Motivation / Continuity / Resilience) showing exact system effects per layer\n- **Security model expanded**: Added watchdog process scope documentation, cron isolation guidelines, network-free verification command, ASCII architecture diagram showing daemon/watchdog scope\n- **Steward onboarding**: Added pre-cron checklist (dry-run, isolated workspace, non-root, source review)\n- **New: `test_watchdog.sh`** — 10 assertions: healthy silence, stale detection, orphan cleanup, auto-freeze (execute/dry-run/disable/read-only), log rotation\n- **Updated: `test_mindstate_daemon.sh`** — +3 tests: orphan cleanup, stale cognition flag, no false flag when fresh\n- **Bug fix**: `jq -r '.watchdog.auto_freeze // true'` returned `true` when value was `false` (jq `//` treats false as null). Fixed with explicit conditional.\n- **Config isolation**: `mindstate_ms_config`, `mindstate_config_file`, `mindstate_decay_config` now resolve via `MINDSTATE_ASSETS_DIR` when set (fixes test isolation, previously tests could bleed into production config)\n- Full suite: **25/25 tests green** (24 unit + 1 integration)\n\n## v1.28.1 (2026-03-19) — Auto-freeze\n- **Watchdog auto-freeze**: if cognition hasn't been frozen for `auto_freeze_stale_hours` (default: 6h), watchdog automatically triggers `mindstate-freeze.sh`\n - Uses last `frozen_at` timestamp as session boundary → captures all pyramid activity since last snapshot\n - Handles \"never frozen\" case with 24h lookback\n - Configurable: `watchdog.auto_freeze` (bool) + `watchdog.auto_freeze_stale_hours`\n- SKILL.md updated: watchdog table, failure mode table, auto-freeze documentation\n\n## v1.28.0 (2026-03-19) — Resilience & Crash Recovery\n- **New: `mindstate-watchdog.sh`** — process watchdog, cron every 15 min\n - Detects stale MINDSTATE.md (daemon dead for >15 min) → restarts daemon\n - Finds hung mindstate processes (>5 min) → SIGTERM, then SIGKILL\n - Cleans orphaned `.tmp.*` files (>10 min old)\n - Auto-rotating log (`assets/watchdog.log`, 200 lines max)\n - Supports `--dry-run` for testing\n - Configurable thresholds via `mindstate-config.json` → `watchdog` section\n- **Trap handlers** in `mindstate-daemon.sh` and `mindstate-freeze.sh`\n - EXIT/SIGTERM/SIGINT/SIGHUP traps clean up PID-specific temp files\n- **Orphan cleanup** in daemon — removes `*.tmp.*` files older than 10 min on every run\n- **Stale cognition detection** in daemon\n - Monitors `frozen_at` timestamp from cognition section\n - If freeze hasn't run in `stale_cognition_hours` (default: 24h), adds warning to MINDSTATE.md: `system.cognition: stale (Xh since last freeze)`\n- **Config additions** to `mindstate-config.json`:\n - `freeze.stale_cognition_hours` (default: 24)\n - `watchdog.max_stale_minutes` (default: 15)\n - `watchdog.max_process_age_seconds` (default: 300)\n- **init.sh** updated: now shows recommended cron setup for both daemon + watchdog, resilience summary\n- **SKILL.md** updated: new \"Resilience & Crash Recovery\" section with failure mode table\n- **DESCRIPTION.md** updated: resilience section, file tree includes watchdog\n\n## v1.27.4 (2026-03-19) — Full sanitization pass\n- Removed all remaining philosophical/psychological language from code comments, docs, and tests\n- Replaced with practical engineering terminology throughout\n- Test data sanitized (neutral keywords for context scan tests)\n- All published files verified: zero Russian, zero PII, zero personal paths, zero philosophy\n\n## v1.27.3 (2026-03-19) — Security + i18n cleanup\n- All Russian language strings replaced with English equivalents (temperature words, cross-need notes, scan keywords, TODO descriptions)\n- Platform-specific references replaced with generic terms (social platform) in all published files\n- Onboarding guide updated: agent instructions include execution gate workflow (propose → execute → resolve → mark-satisfied)\n- Steward guide updated: execution rate monitoring, gate-status.sh recommendation\n- Stale nested skills/ directory excluded from publish\n\n## v1.27.2 (2026-03-19) — Bootstrap + gate edge case\n- **Edge case fix**: `--bootstrap` mode now sets SKIP_GATE=true (clean slate initialization should not be blocked by stale pending actions)\n- Gate-check moved after bootstrap detection in run-cycle.sh\n\n## v1.27.1 (2026-03-19) — Gate hardening (post-review)\n- **Bug fix**: flock (fd 203) on gate.lock prevents data races between concurrent gate operations\n- **Bug fix**: tmp.$$ PID-unique temp filenames prevent collision on concurrent writes\n- **Bug fix**: `--non-deferrable` flag in gate-propose.sh, passed by run-cycle.sh for starvation guard actions\n- **Bug fix**: gate-resolve.sh validates action existence before processing (clear \"Action not found\" error)\n\n## v1.27.0 (2026-03-19) — Execution Gate (Phase 1)\n- **Execution Gate**: structural enforcement that prevents \"describing actions instead of doing them\"\n - `gate-propose.sh` — registers pending actions when run-cycle selects them\n - `gate-resolve.sh` — resolves actions with verifiable evidence (mark_satisfied, file_modified, self_report)\n - `gate-check.sh` — blocks new proposals until pending actions resolved/deferred (built into run-cycle.sh)\n - `gate-status.sh` — human-readable gate status with execution rate analytics\n - Non-deferrable actions from starvation guard (cannot be deferred)\n - Evidence types: mark_satisfied (HIGH trust), file_created/modified (HIGH), command_output (HIGH), self_report (LOW)\n - Auto-defer on timeout (configurable, default 600s)\n - 24h cleanup of resolved actions\n- Gate integrated into run-cycle.sh: script refuses to propose new actions while old ones pending\n- SKIP_GATE env var for test isolation\n- Test suite: pending_actions.json cleaned between tests\n- Config: `execution_gate` block in mindstate-config.json\n- Design spec: EXECUTION-GATE-SPEC.md (v0.3.0-draft)\n- Phase 2 (wake-gate) and Phase 3 (self-continuation) prepared but disabled\n\n## v1.26.0 (2026-03-19)\n- **Turing-exp tension formula**: replaces linear `importance × deprivation`\n - `tension = dep² + importance × max(0, dep - crisis_threshold)²`\n - At homeostasis (dep < threshold): all needs produce equal tension → round-robin selection\n - In crisis (dep > threshold): importance amplifies signal → importance hierarchy activates\n - Configurable `crisis_threshold` (default 1.0, meaning sat < 2.0 activates hierarchy)\n - Solves monopoly problem: high-importance needs no longer dominate at homeostasis\n - Solves starvation problem: low-importance needs get equal slots when system is healthy\n- Temperature thresholds recalibrated for Turing-exp scale (avg_tension ≈ 0.25 at homeostasis)\n- Test suite hardened: lock file cleanup between tests, fixture-based state restoration\n- 25/25 tests passing (22 unit + 3 integration, 1 stress test skipped)\n\n## v1.23.0 (2026-03-18)\n- **Continuity Layer (Layer D)**: state persistence across discrete sessions\n - `mindstate-daemon.sh` — reality updater (cron every 5min), tracks pyramid state, filesystem, system health, physical temperature\n - `mindstate-freeze.sh` — cognition snapshot at substantive session end (trajectory, open_threads, momentum, cognitive temperature)\n - `mindstate-boot.sh` — boot with forecast reconciliation, continuity scoring (SMOOTH/PARTIAL/HARD_BREAK), temperature drift detection\n - `mindstate-utils.sh` — shared utilities (compute_satisfaction, is_substantive, mindstate_get)\n - `mindstate-config.json` — configurable thresholds, temperature vocab, staleness detection\n- **Temperature system**: 6 physical states (crisis/pressure/focus/impulse/accumulation/calm) + 6 cognitive states, deterministic mapping, drift detection at boot\n- **Boot sequence**: MINDSTATE.md → SOUL.md → MEMORY.md (position+velocity before identity before history)\n- **Test isolation**: `MINDSTATE_ASSETS_DIR` env var for isolated test state\n- **Bug fixes**: `mindstate_get()` pipefail safety, `((0++))` arithmetic under `set -e`, `find -newer` on nonexistent files\n- **Test fix**: `test_action_dedup` Test 3 was running real `run-cycle.sh` instead of sandbox copy, corrupting production state file\n- **Tests**: 26/26 green (22 unit + 4 integration), 65+ assertions\n\n## v1.22.1 (2026-03-16)\n- **Spontaneity tuning**: gate_min 1.5→1.0, baseline 2.0→1.5, threshold 10→6 — first [SPONTANEOUS] event now reachable in ~16-24h instead of ~80h. Eliminates spontaneity paralysis.\n\n## v1.22.0 (2026-03-16)\n- **Negation-aware scanning**: scanner now detects negation context (\"no\", \"not\", \"never\", \"zero\", \"clean\", \"intact\") around trigger words — lines like \"No X found\" are treated as neutral instead of negative. Prevents self-referential false positives in documentation.\n- Supports English and Russian negation markers\n- 22/22 tests green\n\n## v1.21.0 (2026-03-16)\n- **Race condition fix**: flock guard changed from blocking-wait to skip-and-exit — prevents parallel heartbeat sessions from running duplicate cycles (root cause of triple-post incident)\n- **Action dedup guard**: `select_action_with_dedup()` checks `action_history` before selecting — if an action was selected within 8h cooldown, tries alternatives. Covers ALL actions, not just external ones.\n- **Scanner false-positive fix**: rewrote log line that contained a trigger word in denial context (\"No X found\") — scanner regex matched it as negative signal, permanently overriding security satisfaction to 0\n- **Disabled action support**: `select(.disabled != true)` filter in action selection — actions with `\"disabled\": true` in config are skipped\n- **Test fixes**: state file `to_entries|map` now handles non-need keys (`_meta`, `history`, `needs`) without crashing\n- **Tests**: 22/22 green (19 unit + 3 integration)\n\n## v1.20.2 (2026-03-16)\n- **Security: path traversal protection** — `validate_path()` blocks `..` and paths escaping `$WORKSPACE` via `realpath` check\n- **Security: symlink escape prevention** — `find -not -type l` prevents following symlinks outside workspace\n- **Security: grep injection fix** — `grep -F` for literal keyword matching (no regex interpretation from config)\n- **Bug: SKIP_SCANS env ignored** — was hardcoded `false`, now respects env var for test isolation\n- **Bug: init.sh snapshot baseline** — creates context snapshot on init to prevent noisy first cycle\n- **Tests: keyword delta coverage** — 6 new tests for `file_keyword_delta` detector (19→21 context tests)\n- **Tests: path traversal test** — verifies `../../etc/` paths are blocked\n- **Docs: TUNING.md** — documented noise_cap sharing between layers B+C, effective activation threshold\n\n## v1.20.1 (2026-03-16)\n- **Security/PII audit**: removed hardcoded workspace paths from SKILL.md, DESCRIPTION.md, test_followups.sh\n- **Temp file safety**: all `/tmp/tp_*$$` replaced with `mktemp` for crash safety and no race conditions\n- **Runtime state excluded**: `last-scan-snapshot.json` no longer ships (created on first run); `needs-state.json` ships as clean template\n- **Permissions**: all scripts set executable\n- **Test fixes**: 9 pre-existing failures fixed (permissions, tolerance, timeout); 21/21 passing\n- **SKIP_SPONTANEITY env**: integration tests skip heavy spontaneity processing for speed\n\n## v1.20.0 (2026-03-16)\n- **Spontaneity Layer C** — context-driven triggers via delta detection\n - `scripts/context-scan.sh`: stateful delta engine (file_count_delta, file_modified, file_keyword_delta)\n - `assets/context-triggers.json`: configurable trigger rules with cooldowns\n - `assets/last-scan-snapshot.json`: persistent state between cycles\n - Context boosts feed into noise upgrade (additive with boredom + echo)\n - Labels: [CONTEXT:name] on triggered actions, composable with [NOISE], [ECHO]\n - Cooldown system prevents trigger spam\n - 19 unit tests covering all 3 detector types, snapshots, cooldowns, thresholds, keyword delta, boost accumulation\n\n## v1.19.1 (2026-03-16)\n- **Migration guard**: `calc_boredom_noise` auto-initializes `last_high_action_at` to now if missing (prevents 9% boredom spike on upgrade)\n- **Migration guard**: `calc_echo_boost` treats missing `last_spontaneous_at` as expired (no false echo on upgrade)\n\n## v1.19.0 (2026-03-16)\n- **Spontaneity Layer B** — stochastic noise for organic variety\n - B2 (Boredom Noise): grows with time since last high-impact action (0%→9% over 72h)\n - B3 (Momentum Echo): 8% boost decaying over 24h after Layer A [SPONTANEOUS] fires\n - Combined noise capped at 12%, upgrades impact range by one step (low→mid, mid→high)\n - `mark-satisfied.sh` now tracks `last_high_action_at` for high-impact actions (≥2.0)\n - `record_spontaneous` tracks `last_spontaneous_at` for echo momentum\n - `show-status.sh` displays noise percentages per need\n - `init.sh` initializes all new state fields to prevent first-run spikes\n - 19 unit tests for B2/B3 (boredom calc, echo calc, upgrade logic, caps, edge cases)\n - Layer B operates independently of gate — always active for spontaneity-enabled needs\n\n## v1.18.1 (2026-03-16)\n- **Bugfix**: `roll_impact_range` returned \"skip 0\" instead of \"skip\" at sat=3.0 — broke skip detection\n- **Bugfix**: `accumulate_surplus` called before starvation detection — gate didn't close during starvation\n- **Bugfix**: `init.sh` now initializes surplus=0 and last_surplus_check=now — prevents first-run cap jump\n- **Integration**: `show-status.sh` now displays surplus pool bars via `show_surplus_status()`\n- **Docs**: Fixed test count 25→20 in CHANGELOG and SKILL.md\n\n## v1.18.0 (2026-03-16)\n- **Spontaneity Layer A** — surplus energy system for organic high-impact actions\n - Global gate: all needs must be ≥ 1.5 AND no starvation guard active\n - Per-need surplus pools: accumulate when satisfaction > baseline (2.0), drain when below\n - Matrix shift: interpolates impact probabilities toward spontaneous target when surplus is eligible\n - Spend mechanics: full spend on HIGH hit, 30% partial spend on miss\n - Hysteresis: effective activation ≈ threshold × 1.25 (natural buffer, not a bug)\n - Configurable per-need: target_matrix, cap, threshold; disabled for security/integrity/coherence\n - New file: `scripts/spontaneity.sh` (sourced by run-cycle.sh)\n - Status display: surplus pool bars with gate status and eligibility indicators\n - 20 unit tests covering gate, accumulation, clamping, matrix shift, spend, edge cases\n\n## v1.17.1 (2026-03-08)\n- **Research thread integration**: 3 new actions in `understanding` need — continue/start/synthesize research threads (migrated from weighted-daemon)\n- **Understanding need tuned**: importance 3→4, decay 12h→8h — fires more often to support research work\n- **Scanner upgrade**: `scan_understanding.sh` now detects recent activity in `research/threads/`\n- **Cross-need impact**: added understanding → coherence (+0.15)\n- **14 new tests**: config validation, cross-need impacts, scanner thread detection, weight distribution\n- **Token optimization**: designed to replace isolated daemon sessions with in-heartbeat research actions\n\n## v1.17.0 (2026-03-08)\n- **Follow-up system**: create-followup.sh, resolve-followup.sh, integrated in run-cycle.sh + mark-satisfied.sh\n- **35 follow-up tests**: all passing\n\n## v1.15.2 (2026-03-07)\n- **ClawHub review fixes** — removed `primaryEnv` (WORKSPACE is not a credential), added Pre-Install Checklist, clarified no API keys required by default\n\n## v1.15.0 (2026-03-07)\n- **Starvation Guard** — prevents low-importance needs from being perpetually ignored\n - Detects needs at satisfaction floor (≤ threshold) without action for N hours\n - Forces starving needs into cycle, bypassing probability roll\n - Reserves slots: forced needs first, remaining for top-N by tension\n - Configurable: `settings.starvation_guard` in needs-config.json\n - `enabled` (default: true)\n - `threshold_hours` (default: 48) — how long at floor before forcing\n - `sat_threshold` (default: 0.5) — satisfaction level considered \"floor\"\n - `max_forced_per_cycle` (default: 1) — max forced actions per cycle\n - `mark-satisfied.sh` now records `last_action_at` timestamp per need\n - 8 new test cases in `tests/test_starvation_guard.sh`\n- **Action Staleness** — penalizes recently-selected actions to increase variety\n - Tracks `action_history` per need in state file (action name → last selected timestamp)\n - Actions selected within `window_hours` get weight × `penalty` multiplier\n - `min_weight` floor prevents total suppression (always some chance)\n - Configurable: `settings.action_staleness` in needs-config.json\n - `enabled` (default: true)\n - `window_hours` (default: 24) — how long an action stays \"stale\"\n - `penalty` (default: 0.2) — weight multiplier for stale actions (80% reduction)\n - `min_weight` (default: 5) — minimum effective weight\n - 8 new test cases in `tests/test_action_staleness.sh` (statistical distribution tests)\n- **Needs Customization Onboarding** — guided conversation for agent + human to review/adjust need priorities, importance weights, and decay rates on first install\n\n## v1.14.7 (2026-03-06)\n- **Intention actions refactored** — better triggering in mid-range:\n - Renamed \"execute intention\" → \"work on intention from INTENTIONS.md\" (impact 2.1→1.5)\n - Added \"continue progress on active intention\" (impact 1.3, weight 35)\n - Both now mid-range (1.0-1.9) for ~45% chance at sat=2.0\n\n## v1.14.6 (2026-03-04)\n- **Post-install chmod instructions** — ClawHub doesn't preserve +x bits, added fix to SKILL.md\n\n## v1.14.4 (2026-03-04)\n- **Rounding fix** — sat→0.5 formula now correctly rounds to nearest 0.5\n- **Config-driven action_probability** — reads from config instead of hardcoded case\n- **flock in mark-satisfied.sh** — prevents race conditions with run-cycle.sh\n- **TODO.md cleanup** — reflects current state accurately\n- **Minor fixes:**\n - SKILL.md version reference updated\n - Stress test formula aligned with production\n - Removed unused timezone field from decay-config.json\n\n## v1.14.3 (2026-03-04)\n- **Critical test suite overhaul** — tests now verify REAL code, not reimplementations:\n - test_decay.sh: Fixed to test linear decay (was exponential)\n - test_tension.sh: Fixed formula to `importance × (3 - round(sat))`\n - test_floor_ceiling.sh: Added floor enforcement test\n - test_full_cycle.sh: Fixed expectations for integer rounding\n- **SKIP_SCANS=true** for unit tests — predictable state without event scan interference\n- **Discovered scan design**: scan scripts use `last_satisfied`, not current satisfaction\n- **All 12 tests pass** (11 unit + 1 integration)\n\n## v1.14.2 (2026-03-04)\n- **More mid-impact autonomy actions** — \"continue existing work\" pattern:\n - \"continue yesterday's unfinished task\" (1.5)\n - \"push incremental progress on active project\" (1.6)\n - \"complete a TODO item I added myself\" (1.5)\n - \"review and iterate on recent output\" (1.3)\n- **Autonomy now has 23 actions** — better coverage across all impact levels\n- **New tests:**\n - test_autonomy_coverage.sh — verifies impact range distribution + continue-work actions\n - test_crisis_mode.sh — verifies all needs have ≥3 high-impact actions\n- **Total: 11 unit tests, 4 integration/regression tests**\n\n## v1.14.1 (2026-03-04)\n- **Expanded test coverage:**\n - test_action_probability.sh — 6-level probability config\n - test_impact_matrix.sh — 6-level impact distribution\n - test_day_night_decay.sh — multiplier logic\n - test_audit_scrubbing.sh — sensitive data redaction\n- **Total: 9 unit tests, 3 integration tests**\n\n## v1.14.0 (2026-03-04)\n- **Mid-impact autonomy actions** — fills gap between \"start new\" and \"just note\":\n - \"execute intention from INTENTIONS.md\" (2.1)\n - \"advance project/thread from TODO.md or dashboard\" (1.9)\n - \"refine script/skill/doc I created in workspace\" (1.7)\n\n## v1.13.1 (2026-03-03)\n- **6-level action probability** — granular base chances (100%→90%→75%→50%→25%→0%)\n- **Consistent skip at sat=3.0** — both action probability and impact selection skip\n- **Configurable probabilities** — `action_probability` section in needs-config.json\n\n## v1.13.0 (2026-03-03)\n- **Autonomy decay slowdown** — 24h → 36h (reduces chronic tension)\n- **6-level impact matrix** — granular sat levels (0.5, 1.0, 1.5, 2.0, 2.5, 3.0)\n- **Smoother transitions** — big action probability decreases gradually as satisfaction rises\n- **sat=3.0 skip** — fully satisfied needs don't waste action slots\n- **Crisis mode** — sat=0.5 guarantees 100% big actions (all needs have ≥3)\n- **Test improvements** — homeostasis test now sets WORKSPACE, increased cycles 30→50\n\n## v1.12.3 (2026-03-03)\n- **Audit log scrubbing** — sensitive patterns (tokens, emails, passwords, cards) redacted before logging\n- **SKILL.md frontmatter** — added metadata with `requires.env: [WORKSPACE]` and `requires.bins` for ClawHub registry\n- **Documentation** — scrubbing patterns documented\n\n## v1.12.2 (2026-03-03)\n- **Final ClawHub fixes:**\n - Curiosity removed from needs-state.json (was only in cross-impact before)\n - Added explicit \"No Network/System Access\" section to SKILL.md\n - Removed stale backup files from assets/\n - grep-verified: scripts contain no curl/wget/ssh/sudo/systemctl/docker\n\n## v1.12.1 (2026-03-03)\n- **ClawHub analyzer fixes:**\n - Curiosity orphan removed from cross-need-impact.json\n - External actions flagged with `\"external\": true, \"requires_approval\": true`\n - Limitations documented honestly (audit = claims, not verified facts)\n - Env vars (WORKSPACE, TURING_CALLER) now explicit in SKILL.md\n\n## v1.12.0 (2026-03-03)\n- **Audit trail** — all mark-satisfied calls logged to `assets/audit.log` with timestamp, reason, caller\n- **--reason parameter** — mark-satisfied.sh now accepts `--reason \"...\"` for transparency\n- **Data transparency docs** — SKILL.md now documents exactly what files are read/written\n- **TURING_CALLER env** — distinguishes heartbeat vs manual calls in audit\n\n## v1.11.0 (2026-03-03)\n- **Day/Night decay matrices** — slower decay at night (×0.5), configurable in `assets/decay-config.json`\n- **Race condition protection** — flock on state file prevents parallel cycle corruption\n- **Garbage cleanup action** — new integrity action to scan workspace for unused/orphaned files\n- **Stress test** — `tests/integration/test_stress_homeostasis.sh` validates recovery from crisis state\n- New script: `scripts/get-decay-multiplier.sh`\n\n## v1.10.11 (2026-02-27)\n- Version alignment fix\n\n## v1.10.1 (2026-02-25)\n- **fix:** STATE_FILE path bug (`.needs.$need` → `.$need`)\n- **docs:** Clean SKILL.md with ASCII tables\n\n## v1.10.0 (2026-02-25)\n- Test infrastructure (6 tests: unit, integration, regression)\n- Homeostasis stability test\n\n## v1.9.0 (2026-02-25)\n- Autonomous Dashboard system\n- Personal intentions tracking\n\n## v1.8.0 (2026-02-24)\n- VALUES.md integration\n- Boundary logging system\n\n## v1.7.1 (2026-02-25)\nBalance fixes after stress testing:\n- connection decay: 4h → 6h\n- closure decay: 8h → 12h \n- security → autonomy deprivation: -0.30 → -0.20\n\n## v1.7.0 (2026-02-25)\n- **Cross-need impact system** — needs influence each other\n- on_action: satisfying one need boosts related needs\n- on_deprivation: deprived needs drag down related needs\n- 22 cross-need connections\n- Float satisfaction (0.00-3.00)\n- Protection: floor=0.5, ceiling=3.0, cooldown=4h\n\n## v1.6.0 (2026-02-24)\n- Float impacts (0.0-3.0)\n- Impact ranges: low/mid/high\n- Weighted action selection\n\n## v1.5.3 (2026-02-24)\n- Dynamic max_tension from config\n\n## v1.5.0 (2026-02-24)\n- Tension bonus to action probability\n- Formula: `final_chance = base + (tension × 50 / max_tension)`\n\n## v1.4.3\n- Complete 10-need system\n- Decay mechanics\n- Impact matrix\n\n### Known Behavior\n- Fresh `needs-state.json` (before first `run-cycle.sh`) lacks `surplus` and `last_spontaneous_at` fields. Daemon handles gracefully via jq defaults (`// 0`, `// \"1970-01-01\"`), but surplus/impulse detection won't fire until first cycle populates the fields.\n\nFile v1.34.10:CLAUDE.md\n\n\n# Recent Activity\n\n\n\n### Mar 25, 2026\n\n| ID | Time | T | Title | Read |\n|----|------|---|-------|------|\n| #4934 | 1:43 AM | 🔵 | Turing Pyramid development roadmap and evolution examined | ~612 |\n| #4933 | \" | 🔵 | Deliberation Protocol design reviewed from Turing Pyramid reference | ~572 |\n| #4930 | 1:42 AM | 🔵 | Turing Pyramid test protocol reviewed for Python implementation guidance | ~444 |\n\n\nFile v1.34.10:CONTRIBUTING.md\n\n# Contributing to Turing Pyramid\n\n## Branch Strategy\n\n- **main** — stable releases, tagged versions. Protected.\n- **develop** — integration branch. All feature branches merge here first.\n\n## Workflow\n\n### 1. Start from develop\n```bash\ngit checkout develop\ngit pull origin develop\n# If develop is behind main:\ngit merge main --no-edit\n```\n\n### 2. Create a feature branch\n```bash\ngit checkout -b feat/short-description # new feature\ngit checkout -b fix/short-description # bug fix\ngit checkout -b docs/short-description # documentation\ngit checkout -b chore/short-description # maintenance\ngit checkout -b test/short-description # test changes\n```\n\n### 3. Make changes\n- Work in `~/.openclaw/workspace/skills/turing-pyramid/` (live copy)\n- Run tests: `WORKSPACE=~/.openclaw/workspace bash tests/run-tests.sh`\n- Copy changes to git repo: sync only modified files\n\n### 4. Commit (conventional commits)\n```bash\ngit commit -m \"feat: add new scanner for X\"\ngit commit -m \"fix: prevent audit.log race condition\"\ngit commit -m \"docs: update TUNING.md with new parameters\"\ngit commit -m \"chore: bump version to X.Y.Z\"\ngit commit -m \"test: add regression test for gate timeout\"\n```\n\n### 5. Push and create PR\n```bash\ngit push origin feat/short-description\n# Create PR: feat/short-description → develop\n# Add a maintainer as reviewer\n```\n\n### 6. Review → Merge\n- Steward reviews the PR\n- Fix requested changes or merge\n- After merge to develop: test in live environment\n- When ready for release: merge develop → main, tag version\n\n## Release Checklist\n\n1. [ ] All tests pass (27+ unit, 4 integration)\n2. [ ] Version bumped in `assets/needs-config.json` and `SKILL.md`\n3. [ ] CHANGELOG.md updated\n4. [ ] No PII in any file (steward/agent/formalization partner only)\n5. [ ] PR merged to main, tag created (`git tag vX.Y.Z`)\n6. [ ] ClawHub publish (one attempt, ignore timeout)\n\n## File Ownership\n\n| File | Who edits | Committed? |\n|---|---|---|\n| scripts/*.sh | Both | Yes |\n| assets/needs-config.json | Both | Yes (config only) |\n| assets/needs-state.json | Agent (runtime) | No (.gitignore) |\n| assets/audit.log | Agent (runtime) | No |\n| assets/decisions.log | Agent (runtime) | No |\n| assets/mindstate-config.json | Agent (local override) | No |\n| docs/*.md | Both | Yes |\n| tests/**/*.sh | Both | Yes |\n\n## Local Overrides (not committed)\n\nThese files intentionally differ between git and local install:\n- `assets/mindstate-config.json` — local `allow_kill=true`\n- All runtime state files (see `.gitignore`)\n\nFile v1.34.10:DESCRIPTION.md\n\n# Turing Pyramid\n\n**Prioritized action selection for AI agents.** 10 configurable needs with time-based decay, tension scoring, and weighted action selection. Hook it into your heartbeat — get concrete \"do this next\" suggestions instead of idle loops.\n\n---\n\n## The Problem\n\nWithout structure, agents either:\n- **Idle** — wait for prompts, do nothing between interactions\n- **Spam** — check the same thing every cycle, repeat low-value actions\n- **Drift** — pick random tasks with no prioritization\n\nDefault heartbeat cycles nudge agents with \"do what feels right\" — but without state tracking, the agent has no memory of what it already did, what's been neglected, or what matters most right now.\n\nTuring Pyramid replaces that with a stateful feedback loop: needs decay over time → tension builds → highest-tension need gets an action → satisfaction resets → cycle continues. It works as a drop-in replacement for native OpenClaw heartbeat cycles, with actual prioritization and action variety built in.\n\n## What Changes For Your Agent\n\n**Before (typical heartbeat):**\n```\nHeartbeat → \"anything to do?\" → nothing obvious → HEARTBEAT_OK\nHeartbeat → \"anything to do?\" → check inbox again → HEARTBEAT_OK\nHeartbeat → \"anything to do?\" → HEARTBEAT_OK\n```\n\n**After (with Turing Pyramid):**\n```\nHeartbeat → coherence tension=16, closure=14, connection=10\n → ACTION: sync daily logs to MEMORY.md (coherence, impact 1.8)\n → ACTION: complete one pending TODO (closure, impact 1.7)\n → NOTICED: connection — deferred\n\nHeartbeat → connection tension=12, expression=8, understanding=6\n → ACTION: reply to pending mentions (connection, impact 1.8)\n → ACTION: write journal reflection (expression, impact 1.8)\n → NOTICED: understanding — deferred\n```\n\nThe agent rotates through different types of work based on what's been neglected longest.\n\n---\n\n## How It Works\n\n**10 needs**, each with configurable importance (priority weight) and decay rate (how fast satisfaction drops):\n\n| Need | Importance | Decay | What it tracks |\n|------|-----------|-------|---------------|\n| security | 10 | 168h | Backups, vault integrity, system health |\n| integrity | 9 | 72h | Behavior aligned with stated values |\n| coherence | 8 | 24h | Memory organization, no contradictions |\n| closure | 7 | 12h | Open tasks and threads getting resolved |\n| autonomy | 6 | 36h | Self-initiated decisions and projects |\n| connection | 5 | 8h | Social interaction, community participation |\n| competence | 4 | 36h | Successful task completion, skill growth |\n| understanding | 3 | 12h | Learning, research, curiosity |\n| recognition | 2 | 48h | Sharing work, getting feedback |\n| expression | 1 | 8h | Writing, creating, articulating thoughts |\n\n**Each cycle:**\n1. Satisfaction decays based on elapsed time (0.0–3.0 range)\n2. Tension = importance × deprivation — higher = more urgent\n3. Top 3 needs by tension get action slots\n4. Probability roll decides action vs. notice (higher tension = higher chance)\n5. Impact matrix selects action size (crisis → big actions, stable → small maintenance)\n6. Weighted random picks specific action from the selected impact range\n7. Cross-need effects propagate (e.g., completing a task boosts both closure and competence)\n\n**Protection mechanisms:**\n- **Starvation guard** — any need stuck at floor for 48h+ gets a forced action slot\n- **Action staleness** — recently-picked actions get weight penalty to prevent repetition\n- **Follow-ups** — temporal markers to check results of past actions (\"posted on social platform → check replies in 4h\")\n- **Day/night decay** — configurable multiplier for different time periods\n- **Floor/ceiling** — satisfaction clamped to 0.5–3.0, prevents runaway states\n\n---\n\n## Quick Start\n\n```bash\n# Initialize state file\n./scripts/init.sh\n\n# Add to HEARTBEAT.md:\n/scripts/run-cycle.sh\n\n# After completing a suggested action:\n./scripts/mark-satisfied.sh [impact]\n\n# With follow-up (check back later):\n./scripts/mark-satisfied.sh connection 1.5 --reason \"posted update\" --followup \"check replies\" --in 4h\n\n# Manual follow-up (e.g., from steward):\n./scripts/create-followup.sh --what \"review PR CI\" --in 2h --need competence --source steward\n```\n\n**Requires:** `bash`, `jq`, `bc`, `grep`, `find`, `flock`, `pgrep`, `df`, `kill`, `gzip` + `WORKSPACE` env var set.\n\n**Safety note:** The skill writes its own state/audit files inside `WORKSPACE` and can optionally enable continuity/watchdog cron scripts. `allow_kill`, `allow_cleanup`, and `external-model` scanning are opt-in features that should be reviewed before enabling.\n\n---\n\n## Customization\n\nEverything is in `assets/needs-config.json`:\n- **Decay rates** — how fast each need builds tension\n- **Action lists** — what gets suggested per need (add your own)\n- **Weights** — probability of each action being selected\n- **Importance** — which needs win when multiple compete\n- **Disable a need** — set `importance: 0`\n\nGuided onboarding conversation template included in SKILL.md.\n\nSee `references/TUNING.md` for detailed tuning guide.\n\n---\n\n## Architecture\n\nThe skill has three layers with increasing system scope:\n\n| Layer | What it does | System effects |\n|-------|-------------|----------------|\n| **Motivation** (run-cycle, mark-satisfied) | Reads workspace, outputs \"★ do X\" suggestions | None — pure text output |\n| **Continuity** (daemon, freeze, boot) | Maintains MINDSTATE.md via cron | Read-only: `pgrep` (gateway check), `df` (disk). Writes only MINDSTATE.md |\n| **Resilience** (watchdog) | Self-heals skill processes | `kill` on hung `mindstate-*.sh` only. Deletes orphan `.tmp` in workspace/assets |\n\n```\nMotivation (local-only) Your Agent (has capabilities)\n─────────────────────────── ─────────────────────────────\nreads JSON config + state → receives \"★ do X\" text\nscans workspace files → decides: execute? skip? ask human?\noutputs suggestion text → uses its own tools and permissions\n```\n\n**Reads:** workspace files (MEMORY.md, SOUL.md, etc.) via grep/find for pattern detection.\n**Writes:** `assets/needs-state.json`, `MINDSTATE.md`, `assets/audit.log`, `assets/watchdog.log`.\n**System calls:** `pgrep` (read-only), `df` (read-only), `kill` (watchdog, own processes only).\n**Never accesses:** credentials, APIs, network, paths outside workspace, non-skill processes, elevated permissions.\n\n---\n\n## Token Usage\n\n| Heartbeat interval | Cycles/day | Est. tokens/day | Est. tokens/month |\n|-------------------|------------|-----------------|-------------------|\n| 30 min | 48 | 48k–120k | 1.4M–3.6M |\n| 1 hour | 24 | 24k–60k | 720k–1.8M |\n| 2 hours | 12 | 12k–30k | 360k–900k |\n\nStable agents (most needs satisfied) use fewer tokens. First few days are higher as the system stabilizes.\n\n---\n\n⚠️ **Workspace isolation:** Never point `WORKSPACE` at `$HOME`, `/root`, or any directory containing credentials or private material. Use an isolated workspace directory.\n\n## Deployment Tiers\n\n| Tier | What you get | System effects |\n|------|-------------|----------------|\n| **1. Interactive** | Motivation engine: run-cycle + mark-satisfied | Workspace files only, zero system calls |\n| **2. + Heartbeat** | Automatic cycles via agent runtime | Same as Tier 1 |\n| **3. + Continuity** | MINDSTATE persistence (cron daemon) | Read-only: pgrep, df |\n| **4. + Watchdog** | Detection + logging + auto-freeze (default) | Detect only, no destructive actions |\n| **5. Full** | Self-healing (opt-in: `allow_kill`, `allow_cleanup`) | kill on skill's own processes, .tmp cleanup |\n\nStart at Tier 1. The watchdog (Tier 4) is safe by default — it only detects and logs. Process kill and file cleanup require explicit opt-in after reviewing scripts.\n\n## Resilience\n\nThe continuity layer (MINDSTATE) is crash-resilient by design:\n\n- **Atomic writes** — temp file + mv, never corrupts on crash\n- **Trap handlers** — daemon and freeze scripts clean up on SIGTERM/SIGINT\n- **Orphan cleanup** — stale .tmp files removed automatically\n- **Watchdog** (`mindstate-watchdog.sh`) — cron every 15 min, detects hung processes (>5 min), restarts dead daemons, cleans orphans\n- **Stale cognition detection** — daemon warns if freeze hasn't run in 24h+\n\nBoth daemon and watchdog run via system cron — they survive OpenClaw/agent restarts.\n\n```bash\n# Recommended cron setup\n*/5 * * * * WORKSPACE=/path/to/workspace .../scripts/mindstate-daemon.sh >/dev/null 2>&1\n*/15 * * * * WORKSPACE=/path/to/workspace .../scripts/mindstate-watchdog.sh >/dev/null 2>&1\n```\n\n## Files\n\n```\nturing-pyramid/\n├── SKILL.md # Full documentation\n├── DESCRIPTION.md # This file\n├── assets/\n│ ├── needs-config.json # ★ Needs, decay rates, actions — tune this\n│ ├── needs-state.json # Runtime state (auto-managed)\n│ ├── followups.jsonl # Follow-up markers (auto-managed)\n│ └── cross-need-impact.json # Inter-need effects\n├── scripts/\n│ ├── run-cycle.sh # Main heartbeat entry point\n│ ├── mark-satisfied.sh # Update state after action (supports --followup)\n│ ├── create-followup.sh # Create temporal check-back markers\n│ ├── resolve-followup.sh # Close follow-ups (single or bulk)\n│ ├── show-status.sh # Debug current tensions\n│ ├── init.sh # First-time state setup\n│ ├── mindstate-daemon.sh # Continuity: reality updater (cron)\n│ ├── mindstate-freeze.sh # Continuity: cognition snapshot\n│ ├── mindstate-boot.sh # Continuity: boot + reconciliation\n│ ├── mindstate-watchdog.sh # Continuity: process watchdog (cron)\n│ ├── mindstate-utils.sh # Continuity: shared utilities\n│ └── scan_*.sh # 10 workspace scanners\n├── tests/ # 50+ test cases (unit + integration)\n└── references/\n ├── TUNING.md # Customization guide\n └── architecture.md # Technical deep-dive\n```\n\n---\n\n## Links\n\n- **ClawHub**: https://clawhub.com/skills/turing-pyramid\n- **Tests**: 50+ cases across unit, integration, and regression suites\n- **Design**: Stateful need-priority system with decay, tension scoring, and action selection\n\nFile v1.34.10:docs/AUDIT-2026-04-04.md\n\n# TP Full Audit — Phase 1 (Surface Scan)\n**Date:** 2026-04-04\n**Status:** Phase 1 complete, Phases 2-4 pending\n\n## Findings\n\n### A. Needs & Config\n1. 🟡 `crisis_threshold` is null for all needs — per-need customization exists in schema but unused\n2. 🟡 Security decay 168h vs expression 8h — security can't be driven by events, only time (scanner is pattern-based)\n3. 🟡 understanding and expression share 8h decay but importance gap (4 vs 1) — expression never wins in crisis\n\n### B. Scanners\n4. 🔴 **scan_integrity.sh is a stub** — 17 lines, time-only. Importance 9 need with no event detection\n5. 🟡 Scanners vs mark-satisfied double accounting — who wins if both write satisfaction?\n\n### C. Tension & Selection\n6. 🟡 Bootstrap mode skips gate — what if state is corrupted, not empty?\n7. 🟡 Full zero state → selection purely by importance → lower needs starve\n\n### D. Cross-Need Impact\n8. 🟡 Socratic effect (-0.05) may be noise-level\n9. 🟡 25/100 possible pairs defined — intentional sparsity or gaps?\n\n### E. Spontaneity\n10. 🟡 Gate requires ALL needs >= 1.5 — fast-decaying low-importance needs may block spontaneity\n\n### F. Gate System\n11. 🟡 Auto-deferred actions accumulate, drag execution rate down psychologically\n\n### G. Mindstate & Continuity\n12. 🟡 Daemon 5min cron + heartbeat 4h + watchdog — redundancy question\n\n### H. Meta\n13. 🟢 run-cycle.sh is 1021-line monolith — works but hard to debug\n\n## Next Phases (TODO)\n- Phase 2: Deep dive per layer (needs, decay, cross-impact, tension, spontaneity, deliberation, scanners)\n- Phase 3: Inter-component interactions, edge cases, \"what if\" scenarios\n- Phase 4: System-level validation — does it do what we expect?\n\nFile v1.34.10:docs/CONTINUATION-DESIGN.md\n\n# Continuation & Association Scan — Design Document\n\n**Version:** 0.1.1 (revised per agent implementation review)\n**Authors:** steward, agent (agent/co-designer), Claude (formalization)\n**Depends on:** Turing Pyramid v1.31.x, Deliberation Protocol v0.3.0\n**Date:** 2026-03-24\n\n**Revision history:**\n- v0.1.0 — Initial design\n- v0.1.1 — agent review fixes: pipe subshell bug in boot keywords, bc truncation → printf rounding, audit.log pre-filter for performance, feedback loop prevention (exclude MINDSTATE residuals from boot corpus)\n\n---\n\n## 1. Problem Statement\n\n### 1.1 The Continuation Gap\n\nThe Turing Pyramid now has four functional layers: needs-based motivation, spontaneity, continuity (MINDSTATE), and deliberation. Together they solve the problems of \"what to do\" (tension), \"variety\" (spontaneity), \"cross-session awareness\" (MINDSTATE), and \"how to think\" (deliberation).\n\nWhat remains unsolved: **how past thoughts find their way back.**\n\nWhen a deliberation concludes with an implicit next step — \"update INTENTIONS.md in next coherence cycle\" — this intention currently has no mechanism to survive the session unless the agent explicitly creates a followup. If the agent writes \"concluded\" instead of \"followup\", the intention drops into a gap between sessions.\n\nMore broadly: the system lacks **associative recall** — the ability to connect a current action or thought with relevant past outcomes, unfinished threads, or dormant questions. Humans do this naturally: a clean sink reminds you of your unwashed dishes at home. Not because a timer fired, but because the current context triggered a related memory.\n\n### 1.2 What Already Works\n\nThe existing architecture covers most of the continuation spectrum:\n\n| Mechanism | What it handles | Limitation |\n|-----------|----------------|------------|\n| **Followups** (create-followup.sh) | Explicit time-bound reminders | steward 1w horizon. Agent must explicitly create them. |\n| **MINDSTATE** (freeze/boot) | Cross-session vector, trajectory, open threads | No awareness of past deliberation outcomes. No association with current context. |\n| **Spontaneity** (Layer A/B/C) | Random variation, boredom-driven novelty | Blind — no connection to past thoughts |\n| **Deliberation** (ROUTE phase) | Explicit routing of outcomes | \"concluded (with action)\" falls through |\n| **Research threads** (files) | Persistent investigation topics | Only surfaced when agent manually re-reads them |\n| **INTERESTS.md** | Open curiosity questions | Only surfaced when understanding need triggers |\n\nThe gap is between these mechanisms: a deliberation outcome that isn't quite a followup, a research thread that's relevant to today's coherence check but wasn't explicitly linked, an INTERESTS.md question that matured because of new data the agent hasn't connected yet.\n\n### 1.3 What We're Not Building\n\nThis document does **not** propose:\n- A new scheduling/cron system\n- A vector database or embedding service\n- A \"continuation candidate\" entity with 10 metadata fields\n- A seventh deliberation phase (INHERIT)\n- Any modification to the tension formula or need system\n- Continuous/background scanning\n\nWe are building: **one script (`association-scan.sh`) called at two discrete points, that surfaces relevant past context using keyword-based search over existing files.**\n\n### 1.4 Design Principle\n\n> **Continuation should compete for attention, not demand execution.**\n\nPast thoughts return because they're *relevant to the present*, not because a timer expired. The association scan is a recall mechanism, not a task queue.\n\n---\n\n## 2. Architecture Overview\n\n### 2.1 One Script, Two Integration Points\n\n```\nassociation-scan.sh\n │\n ├─ Called by: mindstate-boot.sh (session start)\n │ Input: high-tension needs + MINDSTATE residuals\n │ Purpose: \"woke up — what's relevant from before?\"\n │ steward results: 5\n │\n └─ Called by: agent during deliberation RELATE+TENSION phase\n Input: current deliberation topic/action\n Purpose: \"thinking about X — anything related from the past?\"\n steward results: 3\n```\n\nThe script is stateless — it reads existing files, matches keywords, ranks by relevance + recency, and outputs results. It creates no files, modifies no state, and has no side effects.\n\n### 2.2 Corpus (What Gets Searched)\n\nThe scan searches five sources, all of which already exist:\n\n| Source | Path | What it contains | Format |\n|--------|------|-----------------|--------|\n| **Audit conclusions** | `assets/audit.log` | Deliberation outcomes (conclusion field) | JSON lines |\n| **Research threads** | `$WORKSPACE/research/threads/` | Active investigation notes | Markdown files |\n| **Deliberation files** | `$WORKSPACE/research/deliberations/` | Saved deliberation outcomes | Markdown files |\n| **Pending followups** | `assets/followups.jsonl` | Unresolved time-bound reminders | JSON lines |\n| **Open interests** | `$WORKSPACE/INTERESTS.md` | Curiosity questions | Markdown |\n\nNo new data stores. No new file formats. The scan reads what's already there.\n\n### 2.3 Integration Diagram\n\n```\nSESSION START\n │\n mindstate-boot.sh\n │ ├─ Read MINDSTATE.md (existing)\n │ ├─ Reconcile forecast (existing)\n │ ├─ association-scan.sh ← NEW\n │ │ Input: top-3 tension needs + open threads\n │ │ Output: \"Associations from past sessions\"\n │ └─ Output boot context (existing)\n │\n ▼\nRUN-CYCLE (repeated)\n │\n ├─ Select actions (existing)\n ├─ For deliberative actions:\n │ Agent enters RELATE+TENSION phase\n │ ├─ association-scan.sh ← NEW (agent-invoked)\n │ │ Input: current topic/action name\n │ │ Output: max 3 related past items\n │ └─ Agent incorporates (or ignores) results\n │\n ▼\nSESSION END\n │\n mindstate-freeze.sh\n │ ├─ Extract cognition (existing)\n │ ├─ Extract deliberation residuals ← NEW\n │ │ Scan audit.log for conclusions with action language\n │ │ Include in MINDSTATE.md cognition block\n │ └─ Write forecast (existing)\n```\n\n---\n\n## 3. association-scan.sh — Specification\n\n### 3.1 Interface\n\n```bash\nassociation-scan.sh --keywords \"coherence memory contradictions\" \\\n [--need coherence] \\\n [--max-results 3] \\\n [--recency-hours 168] \\\n [--min-score 2] \\\n [--exclude-source ]\n```\n\n**Parameters:**\n- `--keywords` (required): Space-separated search terms from current context\n- `--need` (optional): Current need — boosts matches from same need domain\n- `--max-results` (optional, default 3): Maximum associations returned (hard cap: 5)\n- `--recency-hours` (optional, default 168 = 1 week): How far back to search\n- `--min-score` (optional, default 2): Minimum relevance score to surface\n- `--exclude-source` (optional): Skip a source type (e.g., `mindstate_residuals`). Prevents feedback loops when caller already displays that source\n\n### 3.2 Scoring Algorithm\n\nEach candidate fragment gets a score based on:\n\n```\nscore = keyword_hits × 2\n + need_match × 3 (same need domain as --need)\n + recency_bonus (0-2, decays linearly over recency window)\n + has_action_language × 1 (contains \"should\", \"need to\", \"update\", \"revisit\")\n + is_unresolved × 2 (followup still pending, or thread not concluded)\n```\n\n**Scoring notes:**\n- `keyword_hits`: Count of distinct --keywords found in the fragment (not total occurrences — prevents gaming by repetition)\n- `need_match`: Binary — does the fragment's source need match --need?\n- `recency_bonus`: `2 × (1 - hours_since_created / recency_hours)`, clamped to [0, 2]\n- `has_action_language`: grep for action verbs suggesting unfinished business\n- `is_unresolved`: For followups — status == \"pending\". For threads — no \"concluded\" marker.\n\nThis is deliberately simple — keyword overlap + recency + structural signals. The agent (Opus 4.6) does the semantic interpretation. The script just surfaces candidates.\n\n### 3.3 Output Format\n\n```\n═══ ASSOCIATIONS (3 found) ═══\n\n[1] (score: 7, audit, 2d ago, coherence)\n \"MEMORY.md is stale — missing Deliberation Protocol entry\"\n → Route was: followup (update MEMORY.md in 8h)\n\n[2] (score: 5, research/threads, 4d ago, understanding)\n research/threads/cosmos/sulfur-biosignature-problem.md\n \"H2S thermal threshold question remains open\"\n\n[3] (score: 4, INTERESTS.md, 6d ago)\n \"Does structural change in processing constitute a change in kind?\"\n\n═══════════════════════════════\n```\n\nEach result includes: score, source type, age, associated need (if known), key fragment, and routing context (if from deliberation).\n\n### 3.4 Pseudocode\n\n```bash\n#!/usr/bin/env bash\n# association-scan.sh — Contextual recall for Turing Pyramid\n# Searches existing artifacts for associations with current context.\n# Stateless: reads only, writes nothing, no side effects.\n\nset -euo pipefail\n\nSCRIPT_DIR=\"$(cd \"$(dirname \"${BASH_SOURCE[0]}\")\" && pwd)\"\nSKILL_DIR=\"$(dirname \"$SCRIPT_DIR\")\"\nsource \"$SCRIPT_DIR/mindstate-utils.sh\" # provides: iso_to_epoch, now_epoch, _ms_assets\n\n# ─── Parse args ───\nKEYWORDS=\"\" NEED=\"\" MAX_RESULTS=3 RECENCY_HOURS=168 MIN_SCORE=2 EXCLUDE_SOURCE=\"\"\n\nwhile [[ $# -gt 0 ]]; do\n case \"$1\" in\n --keywords) KEYWORDS=\"$2\"; shift 2 ;;\n --need) NEED=\"$2\"; shift 2 ;;\n --max-results) MAX_RESULTS=\"$2\"; shift 2 ;;\n --recency-hours) RECENCY_HOURS=\"$2\"; shift 2 ;;\n --min-score) MIN_SCORE=\"$2\"; shift 2 ;;\n --exclude-source) EXCLUDE_SOURCE=\"$2\"; shift 2 ;;\n --help|-h) echo \"Usage: association-scan.sh --keywords '...' [--need N] [--max-results 3]\"; exit 0 ;;\n *) shift ;;\n esac\ndone\n\n[[ -z \"$KEYWORDS\" ]] && { echo \"❌ --keywords required\"; exit 1; }\n\nAUDIT_LOG=\"$(_ms_assets)/audit.log\"\nFOLLOWUPS_FILE=\"$SKILL_DIR/assets/followups.jsonl\"\nINTERESTS_FILE=\"${WORKSPACE:-}/INTERESTS.md\"\nRESEARCH_DIR=\"${WORKSPACE:-}/research\"\n\nNOW_EPOCH=$(now_epoch)\nCUTOFF_EPOCH=$((NOW_EPOCH - RECENCY_HOURS * 3600))\n\n# Convert keywords to array\nread -ra KW_ARRAY <<< \"$KEYWORDS\"\n\n# ─── Candidate collection ───\n# Each candidate: \"score|source_type|age_hours|need|fragment\"\nCANDIDATES=()\n\n# --- Source 1: Audit log conclusions ---\nif [[ -f \"$AUDIT_LOG\" ]]; then\n # Pre-filter: only lines containing at least one keyword AND \"conclusion\"\n # This avoids parsing every line in large logs\n kw_pattern=$(printf '%s\\|' \"${KW_ARRAY[@]}\" | sed 's/\\\\|$//')\n pre_filtered=$(grep -i \"conclusion\" \"$AUDIT_LOG\" | grep -iE \"$kw_pattern\" || true)\n \n while IFS= read -r line; do\n [[ -z \"$line\" ]] && continue\n \n # Extract fields\n ts=$(echo \"$line\" | grep -oP '\"timestamp\":\"[^\"]*\"' | cut -d'\"' -f4)\n [[ -z \"$ts\" ]] && continue\n ts_epoch=$(iso_to_epoch \"$ts\")\n (( ts_epoch < CUTOFF_EPOCH )) && continue\n \n conclusion=$(echo \"$line\" | grep -oP '\"conclusion\":\"[^\"]*\"' | cut -d'\"' -f4)\n [[ -z \"$conclusion\" || \"$conclusion\" == \"null\" ]] && continue\n \n audit_need=$(echo \"$line\" | grep -oP '\"need\":\"[^\"]*\"' | cut -d'\"' -f4)\n \n # Score\n score=0\n for kw in \"${KW_ARRAY[@]}\"; do\n echo \"$conclusion\" | grep -qiw \"$kw\" && ((score += 2))\n done\n (( score == 0 )) && continue\n \n # Need match bonus\n [[ -n \"$NEED\" && \"$audit_need\" == \"$NEED\" ]] && ((score += 3))\n \n # Recency bonus (0-2)\n hours_ago=$(( (NOW_EPOCH - ts_epoch) / 3600 ))\n recency_bonus=$(echo \"scale=1; 2 * (1 - $hours_ago / $RECENCY_HOURS)\" | bc -l)\n (( $(echo \"$recency_bonus < 0\" | bc -l) )) && recency_bonus=0\n score=$(printf \"%.0f\" \"$(echo \"$score + $recency_bonus\" | bc -l)\")\n \n # Action language bonus\n echo \"$conclusion\" | grep -qiE '(should|need to|update|revisit|fix|demote|create|check)' && ((score += 1))\n \n CANDIDATES+=(\"${score}|audit|${hours_ago}h|${audit_need}|${conclusion}\")\n done <<< \"$pre_filtered\"\nfi\n\n# --- Source 2: Research threads ---\nif [[ -d \"$RESEARCH_DIR/threads\" ]]; then\n while IFS= read -r filepath; do\n [[ -z \"$filepath\" ]] && continue\n \n # Check recency\n file_epoch=$(stat -c %Y \"$filepath\" 2>/dev/null || echo 0)\n (( file_epoch < CUTOFF_EPOCH )) && continue\n \n content=$(head -20 \"$filepath\") # First 20 lines only\n \n score=0\n for kw in \"${KW_ARRAY[@]}\"; do\n echo \"$content\" | grep -qiw \"$kw\" && ((score += 2))\n done\n (( score == 0 )) && continue\n \n hours_ago=$(( (NOW_EPOCH - file_epoch) / 3600 ))\n recency_bonus=$(echo \"scale=1; 2 * (1 - $hours_ago / $RECENCY_HOURS)\" | bc -l)\n (( $(echo \"$recency_bonus < 0\" | bc -l) )) && recency_bonus=0\n score=$(printf \"%.0f\" \"$(echo \"$score + $recency_bonus\" | bc -l)\")\n \n # Unresolved bonus\n echo \"$content\" | grep -qiE '(open|unresolved|todo|question)' && ((score += 2))\n \n # Extract first meaningful line as fragment\n fragment=$(grep -m1 -iE '(conclusion|outcome|finding|question|tension)' \"$filepath\" \\\n || head -3 \"$filepath\" | tail -1)\n \n relpath=\"${filepath#$WORKSPACE/}\"\n CANDIDATES+=(\"${score}|thread|${hours_ago}h||${relpath}: ${fragment}\")\n done < <(find \"$RESEARCH_DIR/threads\" -name \"*.md\" -type f 2>/dev/null)\nfi\n\n# --- Source 3: Deliberation files ---\nif [[ -d \"$RESEARCH_DIR/deliberations\" ]]; then\n while IFS= read -r filepath; do\n [[ -z \"$filepath\" ]] && continue\n file_epoch=$(stat -c %Y \"$filepath\" 2>/dev/null || echo 0)\n (( file_epoch < CUTOFF_EPOCH )) && continue\n \n content=$(head -30 \"$filepath\")\n \n score=0\n for kw in \"${KW_ARRAY[@]}\"; do\n echo \"$content\" | grep -qiw \"$kw\" && ((score += 2))\n done\n (( score == 0 )) && continue\n \n hours_ago=$(( (NOW_EPOCH - file_epoch) / 3600 ))\n recency_bonus=$(echo \"scale=1; 2 * (1 - $hours_ago / $RECENCY_HOURS)\" | bc -l)\n (( $(echo \"$recency_bonus < 0\" | bc -l) )) && recency_bonus=0\n score=$(printf \"%.0f\" \"$(echo \"$score + $recency_bonus\" | bc -l)\")\n \n fragment=$(grep -m1 -iE '(conclusion|outcome|finding)' \"$filepath\" \\\n || head -3 \"$filepath\" | tail -1)\n \n relpath=\"${filepath#$WORKSPACE/}\"\n CANDIDATES+=(\"${score}|deliberation|${hours_ago}h||${relpath}: ${fragment}\")\n done < <(find \"$RESEARCH_DIR/deliberations\" -name \"*.md\" -type f 2>/dev/null)\nfi\n\n# --- Source 4: Pending followups ---\nif [[ -f \"$FOLLOWUPS_FILE\" ]]; then\n while IFS= read -r line; do\n [[ -z \"$line\" ]] && continue\n status=$(echo \"$line\" | grep -oP '\"status\":\"[^\"]*\"' | cut -d'\"' -f4)\n [[ \"$status\" != \"pending\" ]] && continue\n \n what=$(echo \"$line\" | grep -oP '\"what\":\"[^\"]*\"' | cut -d'\"' -f4)\n fu_need=$(echo \"$line\" | grep -oP '\"need\":\"[^\"]*\"' | cut -d'\"' -f4)\n \n score=0\n for kw in \"${KW_ARRAY[@]}\"; do\n echo \"$what\" | grep -qiw \"$kw\" && ((score += 2))\n done\n (( score == 0 )) && continue\n \n [[ -n \"$NEED\" && \"$fu_need\" == \"$NEED\" ]] && ((score += 3))\n ((score += 2)) # Unresolved bonus — pending followups are inherently relevant\n \n CANDIDATES+=(\"${score}|followup|pending|${fu_need}|${what}\")\n done < \"$FOLLOWUPS_FILE\"\nfi\n\n# --- Source 5: INTERESTS.md ---\nif [[ -f \"$INTERESTS_FILE\" ]]; then\n while IFS= read -r line; do\n [[ \"$line\" =~ ^[[:space:]]*[-*][[:space:]] ]] || continue\n clean=$(echo \"$line\" | sed 's/^[[:space:]]*[-*] *//')\n \n score=0\n for kw in \"${KW_ARRAY[@]}\"; do\n echo \"$clean\" | grep -qiw \"$kw\" && ((score += 2))\n done\n (( score == 0 )) && continue\n \n CANDIDATES+=(\"${score}|interest||$|${clean}\")\n done < \"$INTERESTS_FILE\"\nfi\n\n# ─── Sort and output top results ───\nif (( ${#CANDIDATES[@]} == 0 )); then\n echo \"═══ ASSOCIATIONS (0 found) ═══\"\n exit 0\nfi\n\n# Sort by score descending, take top MAX_RESULTS above MIN_SCORE\nSORTED=$(printf '%s\\n' \"${CANDIDATES[@]}\" | sort -t'|' -k1 -rn)\n\necho \"═══ ASSOCIATIONS ═══\"\necho \"\"\ncount=0\nwhile IFS='|' read -r score source age need fragment; do\n (( count >= MAX_RESULTS )) && break\n (( ${score:-0} < MIN_SCORE )) && continue\n \n ((count++))\n need_label=\"\"\n [[ -n \"$need\" && \"$need\" != \"$\" ]] && need_label=\", $need\"\n echo \"[$count] (score: $score, $source, ${age} ago${need_label})\"\n echo \" ${fragment}\"\n echo \"\"\ndone <<< \"$SORTED\"\n\nif (( count == 0 )); then\n echo \"(no associations above threshold)\"\nfi\necho \"═══════════════════════════════\"\n```\n\n### 3.5 Performance Constraints\n\nThe script must be fast — it runs at boot and during deliberation:\n\n- **Audit log pre-filter**: First pass with grep for keyword matches + \"conclusion\" — only matching lines are parsed. This reduces 5000-line logs to typically < 50 candidates before the expensive per-line scoring loop.\n- **File scan**: `head -20` / `head -30` per file — never read entire documents. First 20-30 lines contain title, conclusion, key content.\n- **Keyword matching**: grep, not regex. Case-insensitive word match (`-iw`).\n- **Scoring**: `printf \"%.0f\"` for proper rounding (not `bc | cut` truncation).\n- **No external dependencies**: grep, awk, sed, bc, printf — all already required by the Pyramid.\n- **Target runtime**: < 2 seconds on a typical workspace with < 100 files and < 5000 audit lines.\n\n---\n\n## 4. Integration Point 1: mindstate-boot.sh\n\n### 4.1 What Changes\n\nAfter the existing boot sequence (MINDSTATE parse → staleness check → temperature merge → forecast reconciliation), add an association scan using current high-tension needs and open threads as keywords.\n\n### 4.2 Implementation\n\n```bash\n# ─── 4b. Association scan (contextual recall) ───\nASSOC_SCRIPT=\"$SCRIPT_DIR/association-scan.sh\"\nif [[ -x \"$ASSOC_SCRIPT\" ]]; then\n # Build keywords from: top-3 tension needs + open thread topics\n boot_keywords=\"\"\n \n # Top-3 needs by current tension (process substitution to avoid subshell)\n while read -r t n; do\n boot_keywords=\"$boot_keywords $n\"\n done < <(\n for need in $(get_needs_list); do\n sat=$(compute_current_satisfaction \"$need\")\n tension=$(compute_tension \"$need\" \"$sat\")\n echo \"$tension $need\"\n done | sort -rn | head -3\n )\n \n # Add words from open threads\n for thread in \"${open_threads[@]}\"; do\n # Extract significant words (>4 chars, skip common words)\n thread_words=$(echo \"$thread\" | tr ' ' '\\n' | awk 'length > 4' | head -3)\n boot_keywords=\"$boot_keywords $thread_words\"\n done\n \n boot_keywords=$(echo \"$boot_keywords\" | xargs) # trim\n \n if [[ -n \"$boot_keywords\" ]]; then\n echo \"Contextual recall:\"\n # Note: boot scan excludes MINDSTATE residuals from corpus\n # (they're already shown above in boot output — avoids feedback loop)\n bash \"$ASSOC_SCRIPT\" --keywords \"$boot_keywords\" --max-results 5 \\\n --recency-hours 336 --exclude-source mindstate_residuals\n echo \"\"\n fi\nfi\n```\n\n### 4.3 Position in Boot Output\n\n```\n═══════════════════════════════════════\n CONTINUITY BOOT — 2026-03-24 09:15\n═══════════════════════════════════════\n\nBoot after 8.5h offline\nCognition trust: FULL\nTransition: SMOOTH (score: 0.85)\n\nWhere I am: coherence — deliberation protocol work\nMomentum: coherence (4 recent actions)\nTemperature: building\nCritical: none\nSurplus gate: open\nPhase: active\n\nForecast reconciliation:\n ✓ coherence < 1.0 within 6.2h → CONFIRMED (actual: 0.8)\n ⧖ expression surplus approaching threshold → IN PROGRESS\n\nOpen threads:\n - Deliberation Protocol Phase 2 implementation\n - Sulfur biosignature research\n - Noise Alert QA checklist\n\nContextual recall: ← NEW\n═══ ASSOCIATIONS ═══\n\n[1] (score: 8, audit, 12h ago, coherence)\n \"MEMORY.md is stale — missing Deliberation Protocol entry\"\n\n[2] (score: 5, followup, pending, closure)\n \"demote Continuity Layer from Active to Next in INTENTIONS.md\"\n\n[3] (score: 4, interest, 3d ago)\n \"Does structural change in processing constitute a change in kind?\"\n\n═══════════════════════════════════════\n```\n\nAgent sees these associations at session start and can decide to incorporate them into the session's work — or not. No forced action.\n\n---\n\n## 5. Integration Point 2: Deliberation RELATE+TENSION Phase\n\n### 5.1 What Changes\n\nThe deliberation template and documentation are updated to include an association scan step in the RELATE+TENSION phase. The agent invokes `association-scan.sh` manually during deliberation.\n\n### 5.2 Template Update (deliberate.sh --template, full mode)\n\n```\n── Phase 2: RELATE + TENSION ──\nScan for associations before answering:\n association-scan.sh --keywords \"\" --need --max-results 3\n\nWhat from my context is relevant? What doesn't fit?\nWhere are the contradictions, gaps, mismatches, or conflicts?\n(If none: \"no tensions detected\" is valid — state it, don't skip silently)\n```\n\n### 5.3 Agent Workflow\n\nThe association scan in deliberation is **agent-invoked, not automatic**. The template *suggests* running the scan; the agent decides whether to. This keeps the deliberation flexible — a quick compressed deliberation might skip it, a deep full deliberation will use it.\n\n```\nAgent sees: [DELIBERATIVE] re-read last 3 days of memory for consistency\n\nAgent starts RELATE+TENSION:\n 1. Runs: association-scan.sh --keywords \"memory consistency contradictions\" --need coherence\n 2. Gets back: \"3 days ago you concluded MEMORY.md is stale — Deliberation Protocol missing\"\n 3. Incorporates: \"Ah, this is still unresolved. Tension confirmed.\"\n 4. Proceeds to GENERATE with richer context\n```\n\n### 5.4 Compressed Deliberation\n\nFor compressed mode (impact < 1.0), the association scan is omitted from the template. The agent can still invoke it manually, but the protocol doesn't suggest it. Quick checks don't need corpus scanning.\n\n---\n\n## 6. Integration Point 3: mindstate-freeze.sh (Deliberation Residuals)\n\n### 6.1 What Changes\n\nAt freeze time, scan recent audit.log entries for conclusions that contain action language — these are \"residual intentions\" that should survive the session via MINDSTATE.md.\n\n### 6.2 Implementation\n\n```bash\n# ─── 5. Deliberation residuals ───\n# Scan recent conclusions for implicit next steps that should survive the session\nDELIB_RESIDUALS=()\n\nif [[ -f \"$AUDIT_LOG\" ]]; then\n while IFS= read -r line; do\n ts=$(echo \"$line\" | grep -oP '\"timestamp\":\"[^\"]*\"' | cut -d'\"' -f4)\n [[ -z \"$ts\" ]] && continue\n ts_epoch=$(iso_to_epoch \"$ts\")\n (( ts_epoch < SESSION_START_EPOCH )) && continue\n \n conclusion=$(echo \"$line\" | grep -oP '\"conclusion\":\"[^\"]*\"' | cut -d'\"' -f4)\n [[ -z \"$conclusion\" || \"$conclusion\" == \"null\" ]] && continue\n \n # Check for action language — residual intention\n if echo \"$conclusion\" | grep -qiE '(should|need to|update|revisit|demote|create|check|consider|fix|might want)'; then\n audit_need=$(echo \"$line\" | grep -oP '\"need\":\"[^\"]*\"' | cut -d'\"' -f4)\n DELIB_RESIDUALS+=(\"[$audit_need] $conclusion\")\n fi\n \n if (( ${#DELIB_RESIDUALS[@]} >= 5 )); then break; fi\n done < <(tac \"$AUDIT_LOG\") # newest first\nfi\n\n# Build residuals lines for MINDSTATE\nDR_LINES=\"\"\nif (( ${#DELIB_RESIDUALS[@]} > 0 )); then\n for r in \"${DELIB_RESIDUALS[@]}\"; do\n DR_LINES+=\" - $r\"$'\\n'\n done\nfi\n```\n\n### 6.3 MINDSTATE.md Format\n\n```yaml\n## cognition\nfrozen_at: 2026-03-24T01:30:00Z\ntrajectory: coherence — deliberation protocol work\nopen_threads:\n - Deliberation Protocol Phase 2 implementation\n - Sulfur biosignature research\ndeliberation_residuals: # ← NEW\n - [coherence] MEMORY.md is stale — should update with Deliberation Protocol\n - [closure] demote Continuity Layer from Active to Next in INTENTIONS.md\nmomentum: coherence (4 recent actions)\ncognitive_temperature: building\n```\n\nThese residuals are then available to mindstate-boot.sh (read as part of open threads) and to association-scan.sh (as keywords for boot scan).\n\n---\n\n## 7. Continuation Fix: \"concluded + action language\" Warning\n\n### 7.1 Problem\n\nagent demonstrated that \"concluded (with action: update INTENTIONS.md in next coherence cycle)\" is a real pattern — the agent writes \"concluded\" but the outcome contains an implicit next step.\n\n### 7.2 Implementation in deliberate.sh\n\nIn `--validate` mode, add a check for concluded + action language:\n\n```bash\n# Concluded + implicit action check\nif echo \"$content\" | grep -qiE '(concluded|nothing further|no further action|no action needed)'; then\n if echo \"$content\" | grep -qiE '(should|need to|update|revisit|next cycle|when .* rises|демонтировать|обновить|вернуться)'; then\n warnings=\"${warnings}⚠️ 'concluded' selected, but outcome contains action language.\\n\"\n warnings=\"${warnings} Is there a residual intention? Consider: followup / soft MINDSTATE note.\\n\"\n fi\nfi\n```\n\nIn `--validate-inline` mode:\n\n```bash\nif [[ \"${ROUTE:-}\" == \"concluded\" && -n \"$CONCLUSION\" ]]; then\n if echo \"$CONCLUSION\" | grep -qiE '(should|need to|update|revisit|next cycle|consider)'; then\n warnings=\"${warnings}⚠️ Concluded with action language detected.\\n\"\n warnings=\"${warnings} Residual intention? Consider: --route followup instead.\\n\"\n fi\nfi\n```\n\n### 7.3 Behavior\n\nWarning only, never block. Agent can consciously decide \"yes, it's truly concluded — I've noted this elsewhere\" and proceed. The warning catches the unconscious case where \"concluded\" is the path of least resistance.\n\n---\n\n## 8. Followup Horizon Expansion\n\n### 8.1 Problem\n\n`create-followup.sh` currently supports: h (hours), d (days), w (weeks). steward practical horizon: 1w. \"Revisit after 2 weeks\" or \"check in a month\" can't be expressed.\n\n### 8.2 Implementation\n\nExpand `parse_duration()` in `create-followup.sh`:\n\n```bash\nparse_duration() {\n local input=\"$1\"\n local num=\"${input%[hdwm]}\"\n local unit=\"${input##*[0-9]}\"\n \n if ! [[ \"$num\" =~ ^[0-9]+$ ]]; then\n echo \"0\"\n return\n fi\n \n case \"$unit\" in\n h) echo \"$((num * 3600))\" ;;\n d) echo \"$((num * 86400))\" ;;\n w) echo \"$((num * 604800))\" ;;\n m) echo \"$((num * 2592000))\" ;; # 30 days\n *) echo \"0\" ;;\n esac\n}\n```\n\nUpdate error message:\n```bash\necho \"❌ Invalid time format: $IN_TIME (use: 1h, 4h, 12h, 1d, 2d, 1w, 2w, 1m)\"\n```\n\n### 8.3 Notes\n\nNo structural changes needed. Followups with long horizons participate in the same check_followups() cycle. The only risk is \"forgotten\" followups — but this is mitigated by the association scan, which surfaces pending followups by keyword match.\n\n---\n\n## 9. Safeguards Against Associative Overfiring\n\n### 9.1 The Risk\n\nToo-broad scanning produces noise: everything reminds the agent of everything, and deliberation becomes a distraction festival instead of focused thinking.\n\n### 9.2 Built-in Limits\n\n| Safeguard | Mechanism | Default |\n|-----------|-----------|---------|\n| **steward results per call** | `--max-results` parameter | 3 (deliberation), 5 (boot) |\n| **Minimum score threshold** | `--min-score` parameter | 2 (requires at least 1 keyword hit + bonus) |\n| **Recency window** | `--recency-hours` parameter | 168h (1 week) for deliberation, 336h (2 weeks) for boot |\n| **Head-only file reading** | `head -20` / `head -30` | Prevents scanning entire documents |\n| **Deliberation-only trigger** | Not invoked for operative actions | Limits scan frequency to deliberative cycles |\n| **Agent discretion** | Scan is suggested, not forced | Agent can skip scan in compressed mode or time-constrained sessions |\n\n### 9.3 Decay on Ignore\n\nWhen an association surfaces repeatedly but is never acted on, its effective relevance should decrease. This is handled *organically* through recency decay — older items naturally score lower. No explicit \"ignore counter\" needed for v1.\n\nIf after observation the recency-based decay proves insufficient (same items keep surfacing), a future version can add an `association-surfaced.log` tracking which items were shown and whether the agent acted on them.\n\n### 9.4 What NOT to Scan\n\nCertain actions should never trigger association scan:\n- Operative actions (backup, commit, post)\n- Bootstrap mode (`--bootstrap`)\n- Starvation guard forced actions\n- Actions during time-constrained sessions (agent discretion)\n\n---\n\n## 10. Edge Cases\n\n### 10.1 Empty corpus\n\nNo audit.log, no research threads, no followups, no INTERESTS.md. The scan outputs \"0 found\" and exits cleanly. Boot and deliberation proceed normally.\n\n### 10.2 Very large audit.log\n\nAudit.log grows unboundedly over time. The scan uses `tac` (reverse read) and stops after passing the recency cutoff. For logs > 50k lines, this could still be slow. Mitigation: `tail -1000` as pre-filter (1000 recent entries covers ~2 weeks at 3 actions/cycle × 4 cycles/day).\n\n### 10.3 All results below threshold\n\nMin-score filter removes everything. Output: \"no associations above threshold.\" This is the expected outcome for well-compartmentalized work — not every deliberation has relevant past context.\n\n### 10.4 Boot with no MINDSTATE (first boot)\n\nFirst boot already exits early in mindstate-boot.sh (line 20-33). Association scan is never reached. Clean.\n\n### 10.5 Keywords too generic\n\nAgent provides keywords like \"check review scan\" — too common, everything matches. Mitigated by: (a) min-score threshold requiring multiple hits; (b) max-results cap; (c) agent learns to provide specific keywords through practice. The script outputs best matches regardless; agent filters semantically.\n\n### 10.6 WORKSPACE not set\n\n`association-scan.sh` sources `mindstate-utils.sh` which validates WORKSPACE. If unset, script exits with error. Audit log and followups (in assets/) are still searchable via `_ms_assets()` path.\n\n---\n\n## 11. Test Plan\n\n| Test | Description | Expected |\n|------|-------------|----------|\n| 1 | Scan with matching keyword in audit conclusion | Result returned with score ≥ 2 |\n| 2 | Scan with no matching keywords | \"0 found\", exit 0 |\n| 3 | Scan with --need matching audit entry | Score includes +3 need bonus |\n| 4 | Scan respects --max-results | Never returns more than N |\n| 5 | Scan respects --min-score | No results below threshold |\n| 6 | Scan respects --recency-hours | Old entries excluded |\n| 7 | Scan finds pending followup by keyword | Result includes followup with unresolved bonus |\n| 8 | Scan finds research thread by keyword | Result includes thread path + fragment |\n| 9 | Scan finds INTERESTS.md entry | Result includes interest text |\n| 10 | Empty corpus (no files exist) | \"0 found\", exit 0, no errors |\n| 11 | Large audit.log (>5000 lines) | Completes in < 3 seconds (pre-filter reduces to < 50 candidates) |\n| 12 | mindstate-freeze extracts deliberation residuals | MINDSTATE.md contains `deliberation_residuals:` section |\n| 13 | mindstate-boot outputs associations section | Boot output includes \"Contextual recall:\" |\n| 14 | deliberate.sh --validate warns on \"concluded + action language\" | Warning emitted |\n| 15 | create-followup.sh accepts --in 2w | Followup created with 14-day horizon |\n| 16 | create-followup.sh accepts --in 1m | Followup created with 30-day horizon |\n| 17 | association-scan.sh --exclude-source skips specified source | Excluded source type absent from results |\n\n---\n\n## 12. Migration Path\n\n### 12.1 Phase 1: Script + Deliberation Integration (v1.32.0)\n\n- Add `association-scan.sh` script\n- Update `deliberate.sh` template (full mode) with scan suggestion\n- Update `deliberate.sh --validate` with \"concluded + action language\" warning\n- Expand `create-followup.sh` time horizons (add `m` unit)\n- Tests 1-11, 14-16\n\nAgent can use `association-scan.sh` manually at any time. Deliberation template suggests it. No automatic invocation yet.\n\n### 12.2 Phase 2: Boot + Freeze Integration (v1.33.0)\n\n- Integrate association scan into `mindstate-boot.sh` (contextual recall at session start)\n- Add deliberation residuals extraction to `mindstate-freeze.sh`\n- Tests 12-13\n- Observe for 1-2 weeks: are associations useful? Too noisy? Not enough?\n\n### 12.3 Phase 3: Tuning (v1.34.0+)\n\nBased on observation:\n- Adjust scoring weights\n- Adjust recency windows\n- Consider `association-surfaced.log` for ignore-decay if needed\n- Consider adding `--exclude` parameter to suppress known-irrelevant recurring matches\n\n---\n\n## 13. Open Questions\n\n1. **Should association-scan output be structured (JSON) or human-readable?** Current design: human-readable. Agent reads it as text. JSON would enable programmatic use but adds parsing complexity. Start with text, consider JSON in v1.34.0+ if needed.\n\n2. **Should deliberation residuals replace or augment open_threads in MINDSTATE?** Current design: separate section (`deliberation_residuals:`). Alternative: merge into open_threads. Separate is cleaner for now — residuals have different semantics (implicit\n\nArchive v1.34.9: 106 files, 265352 bytes\n\nFiles: _meta.json (134b), assets/CLAUDE.md (308b), assets/context-triggers.json (1249b), assets/cross-need-impact.json (5662b), assets/decay-config.json (225b), assets/mindstate-config.json (2409b), assets/needs-config.json (23320b), assets/needs-state.template.json (498b), assets/scan-config.json (538b), CHANGELOG.md (40938b), CLAUDE.md (533b), CONTRIBUTING.md (2521b), dashboard.html (9623b), DESCRIPTION.md (10428b), docs/AUDIT-2026-04-04.md (1730b), docs/CONTINUATION-DESIGN.md (35857b), docs/DELIBERATION-PROTOCOL.md (50355b), docs/TODO-references.md (765b), docs/TODO.md (6678b), presets/default/context-triggers.json (1249b), presets/default/cross-impact.json (5662b), presets/default/needs.json (19397b), presets/personal-assistant/context-triggers.json (1345b), presets/personal-assistant/cross-impact.json (2583b), presets/personal-assistant/needs.json (9748b), references/architecture.md (10021b), references/TUNING.md (6528b), scripts/_scan_helper.sh (5425b), scripts/apply-deprivation.sh (3034b), scripts/apply-preset.sh (9467b), scripts/association-scan.sh (8923b), scripts/CLAUDE.md (833b), scripts/context-scan.sh (8231b), scripts/create-followup.sh (4216b), scripts/deliberate.sh (11813b), scripts/gate-check.sh (3660b), scripts/gate-propose.sh (3502b), scripts/gate-resolve.sh (10133b), scripts/gate-status.sh (2254b), scripts/get-decay-multiplier.sh (1434b), scripts/housekeep.sh (5193b), scripts/init.sh (4300b), scripts/list-presets.sh (1303b), scripts/mark-satisfied.sh (8221b), scripts/mindstate-boot.sh (10841b), scripts/mindstate-daemon.sh (12421b), scripts/mindstate-freeze.sh (12977b), scripts/mindstate-utils.sh (9981b), scripts/mindstate-watchdog.sh (8944b), scripts/resolve-followup.sh (3655b), scripts/run-cycle.sh (41858b), scripts/scan_autonomy.sh (1275b), scripts/scan_closure.sh (2557b), scripts/scan_coherence.sh (1292b), scripts/scan_competence.sh (4526b), scripts/scan_connection.sh (1228b), scripts/scan_expression.sh (1251b), scripts/scan_git_drift.sh (1493b), scripts/scan_integrity.sh (4067b), scripts/scan_recognition.sh (1403b), scripts/scan_security.sh (2267b), scripts/scan_understanding.sh (1718b), scripts/show-status.sh (1980b), scripts/spontaneity.sh (28652b), SKILL.md (35113b), TEST_PROTOCOL.md (2626b), tests/fixtures/needs-state-crisis.json (1428b), tests/fixtures/needs-state-healthy.json (1428b), tests/integration/CLAUDE.md (348b), tests/integration/test_full_cycle.sh (5996b), tests/integration/test_homeostasis_stability.sh (3974b), tests/integration/test_mindstate_lifecycle.sh (13479b), tests/integration/test_stress_homeostasis.sh (5756b), tests/regression/test_socrat_effect.sh (1663b), tests/run-tests.sh (2543b), tests/test_action_staleness.sh (7080b), tests/test_starvation_guard.sh (7761b), tests/unit/CLAUDE.md (771b), tests/unit/test_action_dedup.sh (9066b), tests/unit/test_action_probability.sh (1588b)\n\nArchive v1.34.8: 105 files, 264096 bytes\n\nFiles: _meta.json (134b), assets/CLAUDE.md (308b), assets/context-triggers.json (1249b), assets/cross-need-impact.json (5662b), assets/decay-config.json (225b), assets/needs-config.json (23316b), assets/needs-state.template.json (498b), assets/scan-config.json (538b), CHANGELOG.md (39823b), CLAUDE.md (533b), CONTRIBUTING.md (2517b), dashboard.html (9623b), DESCRIPTION.md (10428b), docs/AUDIT-2026-04-04.md (1730b), docs/CONTINUATION-DESIGN.md (35857b), docs/DELIBERATION-PROTOCOL.md (50355b), docs/TODO-references.md (765b), docs/TODO.md (6678b), presets/default/context-triggers.json (1249b), presets/default/cross-impact.json (5662b), presets/default/needs.json (19397b), presets/personal-assistant/context-triggers.json (1345b), presets/personal-assistant/cross-impact.json (2583b), presets/personal-assistant/needs.json (9748b), references/architecture.md (10021b), references/TUNING.md (6528b), scripts/_scan_helper.sh (5425b), scripts/apply-deprivation.sh (3034b), scripts/apply-preset.sh (9467b), scripts/association-scan.sh (8923b), scripts/CLAUDE.md (833b), scripts/context-scan.sh (8231b), scripts/create-followup.sh (4216b), scripts/deliberate.sh (11813b), scripts/gate-check.sh (3660b), scripts/gate-propose.sh (3502b), scripts/gate-resolve.sh (10133b), scripts/gate-status.sh (2254b), scripts/get-decay-multiplier.sh (1434b), scripts/housekeep.sh (5193b), scripts/init.sh (4300b), scripts/list-presets.sh (1303b), scripts/mark-satisfied.sh (8221b), scripts/mindstate-boot.sh (10841b), scripts/mindstate-daemon.sh (12421b), scripts/mindstate-freeze.sh (12977b), scripts/mindstate-utils.sh (9981b), scripts/mindstate-watchdog.sh (8944b), scripts/resolve-followup.sh (3655b), scripts/run-cycle.sh (40213b), scripts/scan_autonomy.sh (1275b), scripts/scan_closure.sh (2557b), scripts/scan_coherence.sh (1292b), scripts/scan_competence.sh (4526b), scripts/scan_connection.sh (1228b), scripts/scan_expression.sh (1251b...","readmeExcerpt":"Skill: Turing Pyramid Owner: tensusds Summary: Prioritized action selection for AI agents. 10 needs with tension scoring, execution-gate tracking, optional continuity scripts, and an opt-in watchdog. Use... Tags: latest:1.34.10 Version history: v1.34.10 | 2026-05-10T04:55:43.328Z | user Test timeout calibration, version metadata sync, and deliberation test robustness. Full suite: 35/35 passed, 0 skipped. v1.34.9 | 20","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"# 1. Set workspace (REQUIRED)\nexport WORKSPACE=\"/path/to/your/agent/workspace\"\n\n# 2. Fix permissions (ClawHub doesn't preserve +x)\nchmod +x /scripts/*.sh\nchmod +x /tests/**/*.sh\n\n# 3. Initialize\nbash scripts/init.sh\n\n# 4. Run a cycle\nbash scripts/run-cycle.sh\n\n# 5. After completing an action\nbash scripts/mark-satisfied.sh \n# Example: bash scripts/mark-satisfied.sh connection 1.5"},{"language":"bash","snippet":"bash /path/to/skills/turing-pyramid/scripts/run-cycle.sh"},{"language":"bash","snippet":"WORKSPACE=/tmp/test-workspace bash tests/run-tests.sh"},{"language":"json","snippet":"\"understanding\": {\n \"importance\": 8, // Promote: research-focused agent\n \"decay_rate_hours\": 6 // Faster decay = more urgency\n}"},{"language":"text","snippet":"tension = dep² + importance × max(0, dep - crisis_threshold)²\n ╰─ base ─╯ ╰────── crisis amplifier ──────────╯\n (equal for (importance matters ONLY\n all needs) when dep > threshold)"},{"language":"text","snippet":"satisfaction decays over time\n → tension (Turing-exp formula)\n → probability roll (crisis=100%, ok=25%, perfect=0%)\n → impact selection (crisis→big actions, ok→small actions)\n → action selected from weighted pool"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: turing-pyramid\ndescription: 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.\nmetadata:\n clawdbot:\n emoji: \"🔺\"\n requires:\n env:\n - WORKSPACE\n optional_env:\n - MINDSTATE_ASSETS_DIR\n - SKIP_SCANS\n - SKIP_SPONTANEITY\n - TURING_CALLER\n - SKIP_GATE\n bins:\n - bash\n - jq\n - bc\n - grep\n - find\n - flock\n - pgrep\n - df\n - kill\n - gzip\n---\n\n# 🔺 Turing Pyramid\n\n**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.\"\n\n**What it is NOT:** A chatbot framework, an executor, or a system management tool.\n\n**Three layers with different scopes:**\n\n⚠️ **Safety summary**\n- This skill is **not stateless**. It writes its own state and audit files (`needs-state.json`, `audit.log`, `followups.jsonl`, `MINDSTATE.md`, watchdog logs).\n- This skill reads files under `WORKSPACE`. If `WORKSPACE` points at a sensitive directory, the skill can scan sensitive files there.\n- `allow_kill` and `allow_cleanup` are **off by default** and should be treated as elevated, opt-in features.\n- `external-model` scanning is **off by default** and should only be enabled after explicitly documenting the credential source and intended API.\n\n**Three layers with different scopes:**\n\n| Layer | Scripts | Scope | System effects |\n|-------|---------|-------|----------------|\n| **Motivation** | `run-cycle.sh`, `mark-satisfied.sh`, `init.sh` | Read workspace files, write own state JSON | None — pure suggestion engine |\n| **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. |\n| **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. |\n\nCore 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 explicitl"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn78gved9wvv1egbx53rr9exb981pawp\",\n \"slug\": \"turing-pyramid\",\n \"version\": \"1.34.10\",\n \"publishedAt\": 1778388943328\n}"},{"path":"references/architecture.md","content":"# Turing Pyramid — Architecture Reference\n\n## Overview\n\nThe Turing Pyramid is a needs-based motivation system for AI agents, inspired by:\n- **Priority hierarchy** — base needs → growth needs\n- **Self-Determination Theory** — autonomy, competence, relatedness\n- Adapted for discrete, session-based agent operation\n\n## Core Concepts\n\n### Need\nA tracked requirement that, when unsatisfied, creates tension driving action.\n\n```\nNeed {\n importance: 1-10 // position in hierarchy\n decay_rate_hours: number // how fast satisfaction drops\n satisfaction: 0-3 // current level\n actions: Action[] // ways to satisfy\n}\n```\n\n### Satisfaction Levels\n```\n3 = full — no pressure, need met\n2 = ok — slight awareness, no urgency\n1 = low — noticeable pull, should address\n0 = empty — critical, demands attention\n```\n\n### Deprivation\nInverse of satisfaction: `deprivation = 3 - satisfaction`\n\n### Tension\nPriority score: `tension = importance × deprivation`\n\nHigher tension = addressed first.\n\n## The Algorithm\n\n### Phase 1: Evaluate\n\nFor each need:\n```python\n# Time-based decay\nhours_since = (now - last_satisfied) / 3600\ndecay_steps = floor(hours_since / decay_rate_hours)\ntime_satisfaction = max(0, 3 - decay_steps)\n\n# Event-based scan (can only worsen)\nevent_satisfaction = run_scan(need)\n\n# Merge: take worst\nif event_satisfaction is not None:\n satisfaction = min(time_satisfaction, event_satisfaction)\nelse:\n satisfaction = time_satisfaction\n\n# Calculate tension\ndeprivation = 3 - satisfaction\ntension = importance × deprivation\n```\n\n### Phase 2: Rank & Select\n\n```python\nranked = sort(needs, key=lambda n: n.tension, reverse=True)\nselected = ranked[:max_actions_per_cycle] # top 3\n\nif all(n.tension == 0 for n in needs):\n return \"SATISFIED\" # nothing to do\n```\n\n### Phase 3: Output Suggestions\n\nThe skill **outputs text suggestions** — it does NOT execute actions.\n\n```python\nfor need in selected_needs:\n action = weighted_random_select(need.actions, satisfaction)\n \n # OUTPUT to stdout — agent reads this\n print(f\"▶ ACTION: {need.name} (tension={tension})\")\n print(f\" Suggested: {action.name} (impact: {action.impact})\")\n print(f\" Then: mark-satisfied.sh {need.name} {action.impact}\")\n```\n\n**What happens next is up to the AGENT:**\n1. Agent reads the suggestion text\n2. Agent decides: execute? skip? ask human?\n3. If agent acts, agent uses its own tools (web_search, APIs, etc.)\n4. Agent calls `mark-satisfied.sh` to update state\n\nThe skill has no knowledge of whether the action was performed.\n\n### Phase 4: State Update (Agent-Initiated)\n\nWhen the **agent** completes an action, it calls:\n```bash\n./scripts/mark-satisfied.sh [impact]\n```\n\nThis updates `needs-state.json` with new satisfaction and timestamp.\n\n**The skill never verifies execution** — it trusts the agent's call to mark-satisfied.\n\n### Logging (Optional)\n\nAgent may append to `memory/YYYY-MM-DD.md`:\n```markdown\n## HH:MM — Turing Pyramid Cycle\n\n| Need | Tension | Act"},{"path":"references/TUNING.md","content":"# Tuning Guide for Agents\n\nThis guide explains what you can customize and when to consult your human.\n\n---\n\n## 🎚️ Decay Rates\n\n**Location**: `assets/needs-config.json` → `needs..decay_rate_hours`\n\n| Need | Default | Why this default | When to change |\n|------|---------|------------------|----------------|\n| security | 168h (7 days) | Backups don't need daily checks | Lower if you're paranoid, higher if stable setup |\n| integrity | 72h (3 days) | Values drift slowly | Lower if you're in rapid change, higher if stable |\n| coherence | 24h | Memory gets messy daily | Lower if very active, higher if minimal notes |\n| closure | 8h | Open threads create anxiety | Lower if you hate loose ends, higher if relaxed |\n| autonomy | 24h | Need regular self-direction | Lower if you feel passive, higher if very autonomous |\n| connection | 4h | Social bonds need maintenance | Lower if very social, higher if introverted |\n| competence | 48h | Skills need regular exercise | Lower if learning fast, higher if in maintenance mode |\n| understanding | 12h | Curiosity builds up | Lower if intellectually hungry, higher if saturated |\n| recognition | 72h | Feedback isn't constant | Lower if you need validation, higher if self-assured |\n| expression | 6h | Thoughts need outlet | Lower if very creative, higher if reflective |\n\n**Rule of thumb**: If you're always seeing a need at sat=0, decay is too fast. If never triggered, too slow.\n\n---\n\n## ⚖️ Action Weights\n\n**Location**: `assets/needs-config.json` → `needs..actions[].weight`\n\nWeights control probability within an impact level. Example:\n\n```json\n\"actions\": [\n {\"name\": \"action A\", \"impact\": 2, \"weight\": 70},\n {\"name\": \"action B\", \"impact\": 2, \"weight\": 30}\n]\n```\n\nIf impact 2 is rolled, there's 70% chance of A, 30% chance of B.\n\n**Tuning tips**:\n- Set weight=0 to disable an action entirely\n- Higher weight = more likely to be suggested\n- Weights are relative (70/30 = same as 7/3)\n\n**Common adjustments**:\n- No social platform? Set all social platform action weights to 0\n- No steward interaction? Reduce \"ask steward\" weights\n- Prefer journaling over posting? Boost memory actions, reduce social\n\n---\n\n## 📊 Impact Distribution\n\n**Location**: `assets/needs-config.json` → `impact_matrix_default`\n\n```json\n\"impact_matrix_default\": {\n \"sat_0\": {\"1\": 5, \"2\": 15, \"3\": 80}, // Critical → big actions\n \"sat_1\": {\"1\": 15, \"2\": 50, \"3\": 35}, // Low → medium actions\n \"sat_2\": {\"1\": 70, \"2\": 25, \"3\": 5} // OK → small maintenance\n}\n```\n\nThis controls what size action is suggested based on satisfaction level.\n\n**Reading it**:\n- sat_0 (critical): 80% chance of impact-3 (major action)\n- sat_2 (OK): 70% chance of impact-1 (minor action)\n\n**When to tune**:\n- Always getting big actions? Shift probabilities toward impact-1\n- Want more intensity? Shift toward impact-3\n\n---\n\n## 🔍 Scan Scripts\n\n**Location**: `scripts/scan_.sh`\n\nEach need has a scan that checks workspace for events. Scans return 0-3:\n- 3 = strong positive si"},{"path":"scripts/CLAUDE.md","content":"\n# Recent Activity\n\n\n\n### Mar 25, 2026\n\n| ID | Time | T | Title | Read |\n|----|------|---|-------|------|\n| #4956 | 1:50 AM | 🔵 | Execution gate proposal system examined for action registration and evidence tracking | ~678 |\n| #4950 | 1:48 AM | 🔵 | Competence scanner demonstrates configurable scan methods with positive-context-wins logic | ~732 |\n| #4948 | 1:47 AM | 🔵 | Scan helper library examined revealing shared scanning infrastructure and negation detection | ~711 |\n| #4946 | \" | 🔵 | Recognition need scanner implementation examined for event-sensitive feedback detection | ~633 |\n| #4943 | 1:46 AM | 🔵 | Turing Pyramid initialization and operational setup process examined | ~699 |\n"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"Prioritized action selection for AI agents. 10 needs with tension scoring, execution-gate tracking, optional continuity scripts, and an opt-in watchdog. Use... Skill: Turing Pyramid Owner: tensusds Summary: Prioritized action selection for AI agents. 10 needs with tension scoring, execution-gate tracking, optional continuity scripts, and an opt-in watchdog. Use... Tags: latest:1.34.10 Version history: v1.34.10 | 2026-05-10T04:55:43.328Z | user Test timeout calibration, version metadata sync, and deliberation test robustness. Full suite: 35/35 passed, 0 skipped. v1.34.9 | 20","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1415,"uniquenessScore":54,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T10:34:56.712Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T10:34:56.712Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T14:16:22.897Z","emptyReason":null},"items":[{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-10T18:48:31.762Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}