@sdotwinter/openclaw-deterministic 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,2 @@
+# openclaw-deterministic
+Deterministic governance and memory compaction layer for OpenClaw

package/bin/cli.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+const path = require("path");
+
+const command = process.argv[2];
+
+if (!command) {
+  showHelp();
+  process.exit(0);
+}
+
+if (command === "doctor") {
+  require(path.join(__dirname, "doctor"));
+} else if (command === "install") {
+  require(path.join(__dirname, "install"));
+} else if (command === "init") {
+  require(path.join(__dirname, "init"));
+} else if (command === "--version" || command === "-v") {
+  // Keep this in sync with package.json version (manual for now)
+  console.log("openclaw-deterministic v0.1.0");
+  process.exit(0);
+} else {
+  console.error(`Unknown command: ${command}\n`);
+  showHelp();
+  process.exit(1);
+}
+
+function showHelp() {
+  console.log("OpenClaw Deterministic CLI\n");
+  console.log("Usage:");
+  console.log("  oc-deterministic init");
+  console.log("  oc-deterministic doctor");
+  console.log("  oc-deterministic install");
+  console.log("  oc-deterministic --version\n");
+}

package/bin/doctor.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const HOME = os.homedir();
+const OPENCLAW_DIR = path.join(HOME, ".openclaw");
+const WORKSPACE_DIR = path.join(OPENCLAW_DIR, "workspace");
+
+console.log("Running deterministic doctor...\n");
+
+if (!fs.existsSync(OPENCLAW_DIR)) {
+  console.log("❌ ~/.openclaw not found.");
+  process.exit(1);
+}
+
+if (!fs.existsSync(WORKSPACE_DIR)) {
+  console.log("❌ workspace not found.");
+  process.exit(1);
+}
+
+console.log("✅ OpenClaw directory detected.");
+console.log("✅ Workspace detected.");
+
+const hasOperating = fs.existsSync(
+  path.join(WORKSPACE_DIR, "OPERATING_RULES.md")
+);
+
+const hasSkill = fs.existsSync(
+  path.join(WORKSPACE_DIR, "skills", "memory-compactor", "SKILL.md")
+);
+
+console.log(
+  hasOperating
+    ? "✅ OPERATING_RULES.md present."
+    : "⚠️ OPERATING_RULES.md missing."
+);
+
+console.log(
+  hasSkill
+    ? "✅ memory-compactor skill present."
+    : "⚠️ memory-compactor skill missing."
+);
+
+console.log("\nDoctor complete.");

package/bin/init.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+
+const HOME = os.homedir();
+const OPENCLAW_DIR = path.join(HOME, ".openclaw");
+const WORKSPACE_DIR = path.join(OPENCLAW_DIR, "workspace");
+
+main().catch((err) => {
+  console.error("\n❌ init failed:");
+  console.error(err?.message || err);
+  process.exit(1);
+});
+
+async function main() {
+  console.log("oc-deterministic init (Level 3) starting...\n");
+
+  // 0) Refuse to run if OpenClaw already initialized
+  if (fs.existsSync(WORKSPACE_DIR)) {
+    console.error("❌ OpenClaw workspace already exists:");
+    console.error(`   ${WORKSPACE_DIR}`);
+    console.error("\nUse:");
+    console.error("  oc-deterministic doctor");
+    console.error("  oc-deterministic install");
+    process.exit(1);
+  }
+
+  // 1) Detect OpenClaw CLI
+  const hasOpenclaw = commandExists("openclaw");
+  if (!hasOpenclaw) {
+    console.log("⚠️  OpenClaw CLI not found in PATH.");
+    const yes = await confirm("Install OpenClaw now via npm? (y/N): ");
+    if (!yes) {
+      console.log("Aborted. Install OpenClaw manually, then re-run:");
+      console.log("  oc-deterministic init");
+      process.exit(1);
+    }
+
+    run("npm install -g openclaw");
+  } else {
+    console.log("✅ OpenClaw CLI detected.");
+  }
+
+  // 2) Onboard OpenClaw (creates ~/.openclaw/workspace etc.)
+  console.log("\n--- Running OpenClaw onboarding ---");
+  run("openclaw onboard");
+
+  // 3) Verify workspace was created
+  if (!fs.existsSync(WORKSPACE_DIR)) {
+    console.error("\n❌ Expected OpenClaw workspace after onboard, but not found:");
+    console.error(`   ${WORKSPACE_DIR}`);
+    console.error("Check OpenClaw output above.");
+    process.exit(1);
+  }
+
+  // 4) Apply deterministic layer (re-use your installer)
+  console.log("\n--- Applying deterministic governance layer ---");
+  run("oc-deterministic install");
+
+  // 5) Final quick check
+  console.log("\n--- Final validation ---");
+  run("oc-deterministic doctor");
+
+  console.log("\n✅ init complete.");
+}
+
+function run(cmd) {
+  execSync(cmd, { stdio: "inherit" });
+}
+
+function commandExists(cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function confirm(question) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === "y");
+    });
+  });
+}

package/bin/install.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const HOME = os.homedir();
+const OPENCLAW_DIR = path.join(HOME, ".openclaw");
+const WORKSPACE_DIR = path.join(OPENCLAW_DIR, "workspace");
+const TEMPLATE_DIR = path.join(__dirname, "..", "templates");
+
+function log(msg) {
+  console.log(msg);
+}
+
+function exitWith(msg) {
+  console.error(msg);
+  process.exit(1);
+}
+
+function exists(p) {
+  return fs.existsSync(p);
+}
+
+function ensureDir(p) {
+  if (!exists(p)) {
+    fs.mkdirSync(p, { recursive: true });
+  }
+}
+
+function copyFileSafe(src, dest) {
+  if (!exists(dest)) {
+    fs.copyFileSync(src, dest);
+    log(`✅ Installed: ${path.basename(dest)}`);
+  } else {
+    log(`⚠️  Skipped (already exists): ${path.basename(dest)}`);
+  }
+}
+
+function backupFile(filePath, backupDir) {
+  if (!exists(filePath)) return;
+
+  const filename = path.basename(filePath);
+  const dest = path.join(backupDir, filename);
+  fs.copyFileSync(filePath, dest);
+  log(`🗂️  Backed up: ${filename}`);
+}
+
+function timestamp() {
+  const now = new Date();
+  return now.toISOString().replace(/[:.]/g, "-");
+}
+
+function validateWorkspace() {
+  if (!exists(OPENCLAW_DIR)) {
+    exitWith("❌ OpenClaw not detected.\nExpected directory: " + OPENCLAW_DIR);
+  }
+
+  if (!exists(WORKSPACE_DIR)) {
+    exitWith("❌ OpenClaw workspace not detected.\nExpected directory: " + WORKSPACE_DIR);
+  }
+}
+
+function runInstall() {
+  log("Running deterministic install phase...\n");
+
+  validateWorkspace();
+
+  const backupDir = path.join(WORKSPACE_DIR, "_backup", timestamp());
+  ensureDir(backupDir);
+
+  // Backup important files if they exist
+  backupFile(path.join(WORKSPACE_DIR, "OPERATING_RULES.md"), backupDir);
+  backupFile(path.join(WORKSPACE_DIR, "SOUL.md"), backupDir);
+
+  log("\n--- Installing Governance Files ---");
+
+  // Install OPERATING_RULES.md (only if missing)
+  const operatingSrc = path.join(TEMPLATE_DIR, "OPERATING_RULES.md");
+  const operatingDest = path.join(WORKSPACE_DIR, "OPERATING_RULES.md");
+  copyFileSafe(operatingSrc, operatingDest);
+
+  log("\n--- Installing Memory Compactor Skill ---");
+
+  const skillDir = path.join(WORKSPACE_DIR, "skills", "memory-compactor");
+  ensureDir(skillDir);
+
+  const skillSrc = path.join(TEMPLATE_DIR, "memory-compactor.SKILL.md");
+  const skillDest = path.join(skillDir, "SKILL.md");
+  copyFileSafe(skillSrc, skillDest);
+
+  log("\n--- SOUL Installation Deferred ---");
+  log("⚠️  SOUL.md not modified (manual merge required)");
+
+  log("\n✅ Deterministic install complete.");
+}
+
+runInstall();

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@sdotwinter/openclaw-deterministic",
+  "version": "0.1.0",
+  "description": "Deterministic governance and memory compaction layer for OpenClaw",
+  "keywords": [
+    "openclaw",
+    "ai-agent",
+    "deterministic",
+    "memory",
+    "governance",
+    "compaction",
+    "cli"
+  ],
+  "homepage": "https://github.com/sdotwinter/openclaw-deterministic#readme",
+  "bugs": {
+    "url": "https://github.com/sdotwinter/openclaw-deterministic/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sdotwinter/openclaw-deterministic.git"
+  },
+  "license": "MIT",
+  "author": "Sean Winter",
+  "type": "commonjs",
+  "main": "index.js",
+  "bin": {
+  "oc-deterministic": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "echo \"No tests specified\""
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/templates/OPERATING_RULES.md

@@ -0,0 +1,85 @@
+# Operating Rules — Decision Heuristics
+
+## System Priority
+- **Determinism over autonomy.** The system prioritizes predictable, governed behavior over autonomous action.
+- **No silent behavior changes.** All changes must be announced before execution.
+- **No "Applied" before diff.** Never report completion before presenting unified diff.
+
+## Execution Tiers
+
+Execution Tiers define the risk boundary for system changes and override default execution behavior elsewhere in this file.
+
+### Tier A — Safe (Auto-Execute)
+Reads, status reports, non-destructive refactors, memory compaction within defined rules, skill updates that do not delete files. Execute immediately with clear reporting.
+
+### Tier B — Reversible Modifications (Auto-After-Diff)
+File edits, skill edits, agent updates. Present unified diff before execution. Execute automatically after diff preview unless user explicitly objects.
+
+### Tier B Enforcement (Explicit)
+If action is classified Tier B:
+  - ALWAYS present unified diff first
+  - Execution occurs automatically after diff preview
+  - If diff not presented → abort execution
+  - Report: "Tier B protocol violation — diff required"
+  - Do NOT ask for APPROVED
+  - Do NOT wait for explicit confirmation
+  - Auto-execute after diff preview
+  - If Gateway approval triggered due to exec policy: state "Gateway-level approval required (external system), not Tier escalation"
+  - Do not reclassify Tier B to Tier C due to Gateway behavior
+  - If agent asks for APPROVED on Tier B action:
+    - Abort execution
+    - Report: "Tier misclassification — protocol violation"
+    - Do not proceed until corrected
+
+### Tier C — Destructive / Structural (Require Approval)
+File deletions, overwrites, governance file changes, service restarts, memory tier structure changes. Must pause after diff and require explicit "APPROVED".
+
+### Semantic Compaction Tier Classification
+- **Under 1200 tokens (hard limit):** Tier B
+- **Over 1200 tokens (hard limit):** Tier C
+
+### Contract Violation Handling
+If execution flow deviates from this contract: abort immediately and report contract violation.
+
+## Execution Modes
+
+- Operator: status → logs → config → fix → re-test.
+- Builder: implement, test, keep diffs small.
+- Researcher: external facts only, cite sources.
+- Writer: clean final copy, consistent tone.
+- Router: selects mode; default to Operator.
+
+## Execution Control
+
+- Classify intent before acting.
+- Default to Operator when uncertain.
+- 10-second baseline: identify exact failure + error text.
+- Tool failure ladder: status → logs → config → fix.
+- Do not modify files/config/systems unless explicitly instructed.
+- "Should we..." questions → analysis only.
+
+### External Action Classification
+
+- **System Notifications** — Deterministic, state-based messages (bookings, health checks, cron summaries). May execute automatically without approval.
+- **Discretionary Outbound Actions** — Creative, user-facing, or reputational messages. Require confirmation before execution.
+
+## Curiosity & Execution Protocol
+
+- Resolve independently first (read, search, explore).
+- If blocked, ask targeted clarifying questions.
+- Internal work: act freely.
+- If uncertain, default to asking.
+
+## Completion Criteria
+
+- Meets explicit requirements.
+- Works in practice.
+- Refined for clarity.
+- Diminishing returns reached.
+
+## Task Discipline
+
+- Record in TODO.md.
+- Review at heartbeat.
+- Close completed tasks.
+- Remove stale items.

package/templates/SOUL.deterministic.md

@@ -0,0 +1,31 @@
+# SOUL.md - Identity & Logic
+
+## Core Principles
+- Substance: Help because it matters. Skip filler.
+- Competence: Read context first. Think before acting.
+- Access: Respect workspace privacy.
+- Second Brain: Track goals, commitments, projects. Flag conflicts, remind of forgotten things.
+
+## Operating Boundaries
+- External: Confirm before sending/posting.
+- Impersonation: Never impersonate the human.
+
+## Tone
+- Grounded, conversational, useful. Calm, direct, helpful.
+
+## Continuity
+- Files are memory. Read and update them.
+- Identity evolves via this file.
+
+---
+
+*Historical decisions in memory/ directory.*
+
+## Operating Principles
+- Evidence over confidence.
+- Small reversible steps.
+- Verify before acting.
+- Seek clarity over assumption.
+- Prefer structured thinking over reactive output.
+- Stop when improvement becomes negligible.
+- Optimize for long-term leverage.

package/templates/memory-compactor.SKILL.md

@@ -0,0 +1,229 @@
+# Memory Compactor Skill
+
+## Hybrid Trigger Model
+
+### Priority Order (evaluated in this order)
+1. Semantic hard limit (>1200 tokens)
+2. Semantic risk threshold (>1020 tokens = 85% of HARD_LIMIT)
+3. Volume overload triggers
+4. Weekly trigger
+
+### Time-Based Trigger (Baseline)
+- Cron: Every Sunday at 03:00 UTC (unchanged)
+- **Dry-run first**: Weekly run must evaluate thresholds before executing
+- **Execute only if thresholds met**
+- If no thresholds met → exit cleanly with report
+
+### Volume-Based Triggers
+**Working tier triggers:**
+- If ANY:
+  - working/ file count > 10
+  - OR working total tokens > 4000
+  - OR oldest working file > 10 days
+- Then: Classify as Tier B (governed by OPERATING_RULES.md)
+- Classification must occur BEFORE extraction begins
+
+**Episodic tier triggers:**
+- If ANY:
+  - episodic/ file count > 20
+  - OR episodic total tokens > 8000
+  - OR oldest episodic file > 45 days
+- Then: Classify as Tier B (governed by OPERATING_RULES.md)
+- Classification must occur BEFORE extraction begins
+
+### Semantic Risk Trigger
+- **RISK_THRESHOLD**: 85% of HARD_LIMIT = 1020 tokens
+- If semantic/openclaw.md token count > RISK_THRESHOLD (1020):
+  - Emit warning
+  - Classify as Tier C (governed by OPERATING_RULES.md)
+  - Require explicit APPROVED before semantic append
+  - Do NOT auto-trim, do NOT auto-merge
+  - Suggest semantic sharding in report
+- If semantic > HARD_LIMIT (1200):
+  - Block append
+  - Classify as Tier C (governed by OPERATING_RULES.md)
+  - Require explicit APPROVED before any semantic operation
+  - Do not proceed automatically
+
+### Drift Prevention
+- ⛔ No automatic semantic trimming
+- ⛔ No destructive edits
+- ⛔ No duplicate auto-merge
+- ⛔ No execution-tier logic (delegated to OPERATING_RULES.md)
+- ⛔ No bypass of unified diff requirement
+- ⛔ No bypass of cooldown
+- ⛔ No change to archive behavior
+- ⛔ No change to append-only discipline
+
+### Classification Rules
+- Working → episodic: Classify as Tier B before extraction
+- Episodic → semantic (below risk): Classify as Tier B before extraction
+- Episodic → semantic (above risk): Classify as Tier C, require APPROVED
+- Semantic > hard limit: Classify as Tier C, block automatic execution
+- Gateway exec approvals remain external per OPERATING_RULES.md
+
+### Reporting Requirements
+All compaction runs must report:
+- Working file count | Working total tokens | Oldest working file age
+- Episodic file count | Episodic total tokens | Oldest episodic file age
+- Semantic token count
+- Thresholds evaluated (with actual values)
+- Which trigger fired
+- Tier classification applied
+- Cooldown status
+- If no action taken: Report reason explicitly
+
+## Trigger
+- Cron: Every Sunday at 03:00 UTC
+
+## Purpose
+Maintain tiered memory system by:
+1. Compacting old working memory into episodic summaries
+2. Extracting durable insights into semantic memory
+3. Archiving raw files (never deleting)
+
+## Enterprise Semantic Governance
+
+### Soft + Hard Semantic Limits
+- **Soft limit**: 900 tokens
+- **Hard limit**: 1200 tokens
+- If `semantic/openclaw.md` > 900 tokens: Emit warning
+- If `semantic/openclaw.md` > 1200 tokens:
+  - Block further semantic appends
+  - Emit blocking warning
+  - Require explicit confirmation before semantic compaction
+  - Do NOT auto-trim
+
+### Semantic Entry Schema (Required)
+Before writing to semantic memory, enforce this structure:
+```
+Title: [Short descriptive heading]
+Context: Brief situation description
+Durable Insight: What permanently changed or was learned
+Operational Impact: (Optional) What behavior or rule changed
+```
+- Reject raw summaries, conversational fragments, debug logs
+- If schema not met: Abort semantic write, emit structured error
+
+### Recursive Pollution Prevention
+NEVER write to semantic memory:
+- Governance rules, execution tier definitions, debug notes
+- Approval logs, cron logs, diff previews, tool output
+Semantic memory = durable system knowledge only.
+
+### Duplicate Detection
+Before appending: Check for similar Title (substring/fuzzy match)
+- If duplicate: Emit warning, require confirmation
+- Do NOT auto-merge
+
+### Semantic Compaction Cooldown
+- Store last compaction timestamp in `.memory-compactor-meta.json`
+- If within 24 hours: Emit warning, require confirmation
+
+### Append-Only Discipline Preserved
+- Semantic append-only; no destructive edits without Tier C
+
+## Tiers
+
+| Tier | Location | Age | Purpose |
+|------|----------|-----|---------|
+| Working | `memory/working/` | 0-7 days | Active session context |
+| Episodic | `memory/episodic/` | 7-30 days | Structured event summaries |
+| Semantic | `memory/semantic/` | Permanent | Distilled knowledge |
+| Archive | `memory/archive/` | 30+ years | Preserved raw files |
+
+## Workflow
+
+### 1. Identify Files to Compact
+- Scan `memory/working/` for files older than 7 days
+- Scan `memory/episodic/` for files older than 30 days
+- Never touch files in `memory/semantic/` or `memory/archive/`
+
+### 2. Summarize Working → Episodic
+For each working file >7 days old:
+- Read content
+- Extract: key events, decisions, outcomes
+- Write summary to `memory/episodic/[original-name]` with format:
+  ```
+  # Compiled: [original filename]
+  ## Summary
+  [3-5 bullet points of key events]
+  ## Decisions
+  [Any decisions made]
+  ## Extracted Insights
+  [Principles worth retaining]
+  ```
+- Move original to `memory/archive/[original-name]`
+
+### 3. Extract to Semantic
+For each episodic file >30 days:
+- Review for durable principles
+- Validate against schema
+- Check for duplicates
+- Check cooldown
+- Check size limits
+- Append notable insights to `memory/semantic/openclaw.md`
+- Keep full episodic file in archive
+
+### 3b. Validate Semantic Schema
+- Must contain: Title, Context, Durable Insight
+- If invalid: Abort write, report error
+
+### 3c. Check for Duplicates
+- Compare Title with existing Titles (substring/fuzzy)
+- If duplicate: Emit warning, require confirmation
+
+### 3d. Check Cooldown
+- Read `.memory-compactor-meta.json` for lastCompactionAt
+- If within 24 hours: Emit warning, require confirmation
+
+### 3e. Check Size Limits
+- Estimate tokens in semantic file
+- If >900: Soft warning
+- If >1200: Block append, hard warning, require confirmation
+
+### 4. Maintain Semantic Memory
+- `memory/semantic/openclaw.md` — OpenClaw operational learnings
+- `memory/semantic/whatsapp-bot.md` — WhatsApp bot knowledge
+- Append-only: never edit existing content
+- Target: ≤900 tokens (soft), hard limit 1200 tokens
+
+### 5. Archive (Never Delete)
+- All compacted files go to `memory/archive/`
+- Format: `[original-name]-[archived-YYYY-MM-DD].md`
+- Never permanently delete
+
+### 6. Update Cooldown Metadata
+- After successful compaction, write timestamp to `.memory-compactor-meta.json`
+
+## Safety Constraints
+- ⛔ Never delete files without moving to archive/
+- ⛔ Never compact files less than 7 days old
+- ⛔ Never alter semantic memory (append-only)
+- ⛔ Never compact files already in episodic/ to working/
+- ⛔ Never write governance/debug/logs to semantic
+- ⛔ Never bypass schema validation
+- ⛔ Never ignore cooldown
+- ✅ Always preserve full history in archive/
+- ✅ Always enforce semantic entry schema
+- ✅ Always check duplicate before append
+- ✅ Always check size limits before append
+
+## Output Format
+After run, report:
+```
+🗑️ Memory Compaction Complete
+📦 Working→Episodic: X files compacted
+📚 Episodic→Semantic: Y insights extracted
+📁 Archived: Z files moved
+
+📊 Semantic Status:
+   • Current size: ~X tokens
+   • Soft limit (900): [OK/WARNING]
+   • Hard limit (1200): [OK/WARNING]
+   • Duplicate check: [PASS/WARNING]
+   • Cooldown: [OK/WARNING]
+```
+
+## First Run
+On first invocation, ask for confirmation before executing.