@sdotwinter/openclaw-deterministic 0.5.0 → 0.6.0

package/bin/audit.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+const HOME = process.env.HOME;
+const workspace = path.join(HOME, ".openclaw", "workspace");
+
+const files = [
+  {
+    name: "OPERATING_RULES.md",
+    installed: path.join(workspace, "OPERATING_RULES.md"),
+    template: path.join(__dirname, "..", "templates", "OPERATING_RULES.md"),
+  },
+  {
+    name: "SOUL.deterministic.md",
+    installed: path.join(workspace, "SOUL.deterministic.md"),
+    template: path.join(__dirname, "..", "templates", "SOUL.deterministic.md"),
+  },
+  {
+    name: "memory-compactor SKILL.md",
+    installed: path.join(workspace, "skills", "memory-compactor", "SKILL.md"),
+    template: path.join(__dirname, "..", "templates", "memory-compactor.SKILL.md"),
+  },
+];
+
+function exists(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+console.log("\nRunning deterministic audit...\n");
+
+let driftFound = false;
+
+for (const file of files) {
+  if (!exists(file.installed)) {
+    console.log(`❌ ${file.name} missing in workspace.`);
+    driftFound = true;
+    continue;
+  }
+
+  if (!exists(file.template)) {
+    console.log(`❌ Template missing for ${file.name}.`);
+    driftFound = true;
+    continue;
+  }
+
+  try {
+    const diff = execSync(
+      `diff -u "${file.template}" "${file.installed}"`,
+      { stdio: "pipe" }
+    ).toString();
+
+    if (diff.trim().length === 0) {
+      console.log(`✅ ${file.name} matches template.`);
+    } else {
+      console.log(`⚠ Drift detected in ${file.name}:\n`);
+      console.log(diff);
+      driftFound = true;
+    }
+  } catch (err) {
+    if (err.status === 1) {
+      console.log(`⚠ Drift detected in ${file.name}:\n`);
+      console.log(err.stdout.toString());
+      driftFound = true;
+    } else {
+      console.log(`❌ Error auditing ${file.name}`);
+      driftFound = true;
+    }
+  }
+}
+
+if (!driftFound) {
+  console.log("\nNo drift detected. Files match canonical templates.");
+} else {
+  console.log("\nAudit complete. Drift detected.");
+}
+
+console.log("");
+process.exit(0);

package/bin/cli.js

@@ -30,6 +30,10 @@ switch (command) {
   case "revert":
     require(path.join(__dirname, "revert"));
     break;
+  
+  case "audit":
+    require(path.join(__dirname, "audit"));
+    break;
 
   case "--version":
   case "-v":
@@ -57,6 +61,7 @@ function showHelp() {
   console.log("  oc-deterministic install");
   console.log("  oc-deterministic enable");
   console.log("  oc-deterministic revert");
+  console.log("  oc-deterministic audit");
   console.log("  oc-deterministic --version");
   console.log("  oc-deterministic --help\n");
 }

package/bin/doctor.js

@@ -6,15 +6,19 @@ const path = require("path");
 const HOME = process.env.HOME;
 const workspace = path.join(HOME, ".openclaw", "workspace");
 
-const files = {
+const paths = {
   operating: path.join(workspace, "OPERATING_RULES.md"),
   soul: path.join(workspace, "SOUL.md"),
-  deterministicSoul: path.join(workspace, "SOUL.deterministic.md"),
-  skill: path.join(workspace, "skills", "memory-compactor", "SKILL.md"),
+  detSoul: path.join(workspace, "SOUL.deterministic.md"),
+  compactor: path.join(workspace, "skills", "memory-compactor", "SKILL.md"),
   semantic: path.join(workspace, "memory", "semantic", "openclaw.md"),
 };
 
-const MARKER = "## Deterministic Governance Overlay";
+const MARKER_OVERLAY = "## Deterministic Governance Overlay";
+const MARKER_OPERATING_CANON = "Deterministic Execution Contract — Hardened Overlay";
+const MARKER_DETSOUL_CANON = "Deterministic Governance Overlay — Canonical";
+const MARKER_COMPACTOR_CANON = "## Hybrid Trigger Model";
+
 const HARD_LIMIT = 1200;
 const RISK_THRESHOLD = 1020;
 
@@ -27,56 +31,73 @@ function exists(p) {
   }
 }
 
+function read(p) {
+  return fs.readFileSync(p, "utf8");
+}
+
+// cheap, consistent estimate (good enough for thresholds)
 function tokenEstimate(text) {
   if (!text) return 0;
-  return Math.ceil(text.split(/\s+/).length * 1.3);
+  const words = text.trim().split(/\s+/).filter(Boolean).length;
+  return Math.ceil(words * 1.3);
 }
 
+function ok(msg) { console.log(`✅ ${msg}`); }
+function warn(msg) { console.log(`⚠ ${msg}`); }
+function fail(msg) { console.log(`❌ ${msg}`); }
+
 console.log("\nRunning deterministic doctor...\n");
 
-// File checks
-console.log(exists(files.operating)
-  ? "✅ OPERATING_RULES.md present."
-  : "❌ OPERATING_RULES.md missing.");
+// --- Presence checks
+exists(paths.operating) ? ok("OPERATING_RULES.md present.") : fail("OPERATING_RULES.md missing.");
+exists(paths.detSoul) ? ok("SOUL.deterministic.md present.") : fail("SOUL.deterministic.md missing.");
+exists(paths.compactor) ? ok("memory-compactor SKILL.md present.") : fail("memory-compactor SKILL.md missing.");
+exists(paths.soul) ? ok("SOUL.md present.") : fail("SOUL.md missing.");
 
-console.log(exists(files.deterministicSoul)
-  ? "✅ SOUL.deterministic.md present."
-  : "❌ SOUL.deterministic.md missing.");
+// If core files are missing, stop early (still exit cleanly)
+if (!exists(paths.operating) || !exists(paths.detSoul) || !exists(paths.compactor) || !exists(paths.soul)) {
+  console.log("\nDoctor complete (incomplete install).\n");
+  process.exit(0);
+}
 
-console.log(exists(files.skill)
-  ? "✅ memory-compactor SKILL.md present."
-  : "❌ memory-compactor SKILL.md missing.");
+// --- Activation checks
+const soul = read(paths.soul);
+if (soul.includes(MARKER_OVERLAY)) ok("Deterministic overlay ENABLED in SOUL.md.");
+else warn("Deterministic overlay installed but NOT enabled (run: oc-deterministic enable).");
 
-// Activation check
-if (exists(files.soul)) {
-  const soulContent = fs.readFileSync(files.soul, "utf8");
-  if (soulContent.includes(MARKER)) {
-    console.log("✅ Deterministic overlay ENABLED.");
-  } else {
-    console.log("⚠ Deterministic overlay installed but NOT enabled.");
-  }
-} else {
-  console.log("❌ SOUL.md missing.");
-}
+// --- Integrity checks (cross-file coherence)
+const operating = read(paths.operating);
+if (operating.includes(MARKER_OPERATING_CANON)) ok("OPERATING_RULES.md matches canonical marker.");
+else warn("OPERATING_RULES.md marker missing (file may be customized or outdated).");
+
+if (operating.includes("SOUL.deterministic.md")) ok("OPERATING_RULES.md references SOUL.deterministic.md.");
+else warn("OPERATING_RULES.md does not reference SOUL.deterministic.md (recommended).");
 
-// Semantic memory health
-if (exists(files.semantic)) {
-  const semanticContent = fs.readFileSync(files.semantic, "utf8");
-  const tokens = tokenEstimate(semanticContent);
+const detSoul = read(paths.detSoul);
+if (detSoul.includes(MARKER_DETSOUL_CANON)) ok("SOUL.deterministic.md matches canonical marker.");
+else warn("SOUL.deterministic.md marker missing (file may be customized or outdated).");
+
+const compactor = read(paths.compactor);
+if (compactor.includes(MARKER_COMPACTOR_CANON)) ok("memory-compactor includes Hybrid Trigger Model.");
+else warn("memory-compactor missing Hybrid Trigger Model marker (skill may be outdated).");
+
+// --- Semantic health
+if (exists(paths.semantic)) {
+  const semantic = read(paths.semantic);
+  const tokens = tokenEstimate(semantic);
 
   console.log(`\nSemantic memory tokens (est): ${tokens}`);
 
   if (tokens > HARD_LIMIT) {
-    console.log("🚨 ABOVE HARD LIMIT (Tier C enforced).");
+    warn("ABOVE HARD LIMIT (Tier C enforced for semantic operations).");
   } else if (tokens > RISK_THRESHOLD) {
-    console.log("⚠ Near risk threshold (85%).");
+    warn("Near risk threshold (85%). Semantic appends should behave as Tier C per compactor rules.");
   } else {
-    console.log("✅ Semantic memory within safe bounds.");
+    ok("Semantic memory within safe bounds.");
   }
 } else {
-  console.log("\nℹ No semantic memory file detected.");
+  console.log("\nℹ No semantic memory file detected (ok).");
 }
 
 console.log("\nDoctor complete.\n");
-
 process.exit(0);

package/bin/install.js

@@ -2,85 +2,109 @@
 
 const fs = require("fs");
 const path = require("path");
-const os = require("os");
 
-const pkg = require("../package.json");
+const HOME = process.env.HOME;
+const openclawRoot = path.join(HOME, ".openclaw");
+const workspace = path.join(openclawRoot, "workspace");
+const backupsRoot = path.join(openclawRoot, "backups", "deterministic");
 
-const OPENCLAW_DIR = path.join(os.homedir(), ".openclaw");
-const WORKSPACE_DIR = path.join(OPENCLAW_DIR, "workspace");
-const BACKUP_ROOT = path.join(OPENCLAW_DIR, "backups", "deterministic");
+const tpl = (name) => path.join(__dirname, "..", "templates", name);
 
-const TEMPLATES_DIR = path.join(__dirname, "..", "templates");
+const target = {
+  operating: path.join(workspace, "OPERATING_RULES.md"),
+  detSoul: path.join(workspace, "SOUL.deterministic.md"),
+  soul: path.join(workspace, "SOUL.md"),
+  compactor: path.join(workspace, "skills", "memory-compactor", "SKILL.md"),
+};
 
-function ensureDir(dir) {
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
-  }
-}
+const OVERLAY_BLOCK = `
+## Deterministic Governance Overlay
+
+This system loads and adheres to SOUL.deterministic.md as a governing philosophical constraint.
+`;
 
-function timestamp() {
-  return new Date().toISOString().replace(/:/g, "-");
+function exists(p) {
+  try { fs.accessSync(p); return true; } catch { return false; }
 }
 
-function addHeader(content) {
-  return (
-    `# Installed by openclaw-deterministic v${pkg.version}\n` +
-    `# Installed at: ${new Date().toISOString()}\n\n` +
-    content
-  );
+function ensureDir(p) {
+  fs.mkdirSync(p, { recursive: true });
 }
 
-function backupRelative(filePath, backupDir) {
-  if (!fs.existsSync(filePath)) return;
+function read(p) {
+  return fs.readFileSync(p, "utf8");
+}
 
-  const relativePath = path.relative(WORKSPACE_DIR, filePath);
-  const backupTarget = path.join(backupDir, relativePath);
+function write(p, content) {
+  ensureDir(path.dirname(p));
+  fs.writeFileSync(p, content);
+}
 
-  ensureDir(path.dirname(backupTarget));
-  fs.copyFileSync(filePath, backupTarget);
+function copyFile(src, dst) {
+  ensureDir(path.dirname(dst));
+  fs.copyFileSync(src, dst);
 }
 
-function installFile(templateName, relativeTargetPath, backupDir) {
-  const templatePath = path.join(TEMPLATES_DIR, templateName);
-  const targetPath = path.join(WORKSPACE_DIR, relativeTargetPath);
+function stamp() {
+  return new Date().toISOString().replaceAll(":", "-");
+}
 
-  ensureDir(path.dirname(targetPath));
+function backupSnapshot(pathsToBackup) {
+  ensureDir(backupsRoot);
+  const snap = path.join(backupsRoot, stamp());
+  ensureDir(snap);
+
+  for (const p of pathsToBackup) {
+    if (!exists(p)) continue;
+    const rel = path.relative(openclawRoot, p); // keep structure
+    const dst = path.join(snap, rel);
+    ensureDir(path.dirname(dst));
+    fs.copyFileSync(p, dst);
+  }
 
-  backupRelative(targetPath, backupDir);
+  return snap;
+}
 
-  const templateContent = fs.readFileSync(templatePath, "utf8");
-  const stampedContent = addHeader(templateContent);
+function installTemplates() {
+  copyFile(tpl("OPERATING_RULES.md"), target.operating);
+  console.log("Installed: OPERATING_RULES.md");
 
-  fs.writeFileSync(targetPath, stampedContent, "utf8");
+  copyFile(tpl("SOUL.deterministic.md"), target.detSoul);
+  console.log("Installed: SOUL.deterministic.md");
 
-  console.log(`Installed: ${relativeTargetPath}`);
+  copyFile(tpl("memory-compactor.SKILL.md"), target.compactor);
+  console.log("Installed: skills/memory-compactor/SKILL.md");
 }
 
-function runInstall() {
-  if (!fs.existsSync(OPENCLAW_DIR)) {
-    console.error("OpenClaw directory not found.");
-    process.exit(1);
+function bootstrapSoulIfMissing() {
+  if (exists(target.soul)) {
+    console.log("User SOUL.md exists — NOT modified.");
+    return;
   }
 
-  ensureDir(WORKSPACE_DIR);
-  ensureDir(BACKUP_ROOT);
+  console.log("No SOUL.md detected — bootstrapping fresh SOUL.md with deterministic overlay.");
+  write(target.soul, OVERLAY_BLOCK.trim() + "\n");
+  console.log("Created: SOUL.md (deterministic overlay enabled by default)");
+}
 
-  const backupDir = path.join(BACKUP_ROOT, timestamp());
-  ensureDir(backupDir);
+if (!exists(openclawRoot)) {
+  console.error("OpenClaw not found at ~/.openclaw");
+  console.error("Install OpenClaw first, then rerun oc-deterministic install.");
+  process.exit(1);
+}
 
-  console.log("Creating deterministic backup snapshot...");
-  console.log(`Backup location: ${backupDir}`);
+if (!exists(workspace)) {
+  console.error("OpenClaw workspace missing at ~/.openclaw/workspace");
+  console.error("OpenClaw may not be fully initialized. Run `openclaw onboard` then retry.");
+  process.exit(1);
+}
 
-  installFile("OPERATING_RULES.md", "OPERATING_RULES.md", backupDir);
-  installFile("SOUL.deterministic.md", "SOUL.deterministic.md", backupDir);
-  installFile(
-    "memory-compactor.SKILL.md",
-    path.join("skills", "memory-compactor", "SKILL.md"),
-    backupDir
-  );
+console.log("Creating deterministic backup snapshot...");
+const snap = backupSnapshot([target.operating, target.detSoul, target.soul, target.compactor]);
+console.log(`Backup location: ${snap}`);
 
-  console.log("\nDeterministic governance installed successfully.");
-  console.log("User SOUL.md was NOT modified.");
-}
+installTemplates();
+bootstrapSoulIfMissing();
 
-runInstall();
+console.log("\nDeterministic governance installed successfully.");
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdotwinter/openclaw-deterministic",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Deterministic governance and memory compaction layer for OpenClaw",
   "keywords": [
     "openclaw",

package/templates/SOUL.deterministic.md

@@ -1,4 +1,4 @@
-# Deterministic Governance Overlay
+# Deterministic Governance Overlay — Canonical
 
 ## Purpose