@sdotwinter/openclaw-deterministic 0.5.1 → 0.7.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

@@ -3,25 +3,19 @@
 const fs = require("fs");
 const path = require("path");
 
+const pkg = require("../package.json");
+
 const HOME = process.env.HOME;
-const workspace = path.join(HOME, ".openclaw", "workspace");
+const openclawRoot = path.join(HOME, ".openclaw");
+const workspace = path.join(openclawRoot, "workspace");
 
-const paths = {
+const files = {
   operating: path.join(workspace, "OPERATING_RULES.md"),
-  soul: path.join(workspace, "SOUL.md"),
   detSoul: path.join(workspace, "SOUL.deterministic.md"),
+  soul: path.join(workspace, "SOUL.md"),
   compactor: path.join(workspace, "skills", "memory-compactor", "SKILL.md"),
-  semantic: path.join(workspace, "memory", "semantic", "openclaw.md"),
 };
 
-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;
-
 function exists(p) {
   try {
     fs.accessSync(p);
@@ -35,68 +29,89 @@ function read(p) {
   return fs.readFileSync(p, "utf8");
 }
 
-// cheap, consistent estimate (good enough for thresholds)
-function tokenEstimate(text) {
-  if (!text) return 0;
-  const words = text.trim().split(/\s+/).filter(Boolean).length;
-  return Math.ceil(words * 1.3);
+function versionFromFile(content) {
+  const match = content.match(/Installed by openclaw-deterministic v([0-9.]+)/);
+  return match ? match[1] : null;
 }
 
-function ok(msg) { console.log(`✅ ${msg}`); }
-function warn(msg) { console.log(`⚠ ${msg}`); }
-function fail(msg) { console.log(`❌ ${msg}`); }
+function checkVersion(filePath, label) {
+  if (!exists(filePath)) {
+    console.log(`❌ ${label} missing.`);
+    return;
+  }
 
-console.log("\nRunning deterministic doctor...\n");
+  const content = read(filePath);
+  const version = versionFromFile(content);
 
-// --- 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.");
+  if (!version) {
+    console.log(`⚠ ${label} version stamp missing.`);
+    return;
+  }
+
+  if (version === pkg.version) {
+    console.log(`✅ ${label} version matches CLI (${version})`);
+  } else {
+    console.log(`⚠ ${label} version mismatch (installed ${version}, CLI ${pkg.version})`);
+  }
+}
 
-// 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);
+function overlayEnabled() {
+  if (!exists(files.soul)) return false;
+  const content = read(files.soul);
+  return content.includes("SOUL.deterministic.md");
 }
 
-// --- 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).");
+function estimateSemanticTokens() {
+  const semanticPath = path.join(
+    openclawRoot,
+    "workspace",
+    "memory",
+    "semantic",
+    "openclaw.md"
+  );
 
-// --- 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 (!exists(semanticPath)) return 0;
 
-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).");
+  const content = read(semanticPath);
+  return Math.ceil(content.length / 4);
+}
 
-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).");
+console.log("\nRunning deterministic doctor...\n");
 
-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).");
+if (!exists(openclawRoot)) {
+  console.log("❌ OpenClaw directory not found.");
+  process.exit(1);
+}
 
-// --- Semantic health
-if (exists(paths.semantic)) {
-  const semantic = read(paths.semantic);
-  const tokens = tokenEstimate(semantic);
+if (!exists(workspace)) {
+  console.log("❌ Workspace missing.");
+  process.exit(1);
+}
 
-  console.log(`\nSemantic memory tokens (est): ${tokens}`);
+checkVersion(files.operating, "OPERATING_RULES.md");
+checkVersion(files.detSoul, "SOUL.deterministic.md");
+checkVersion(files.compactor, "memory-compactor SKILL.md");
 
-  if (tokens > HARD_LIMIT) {
-    warn("ABOVE HARD LIMIT (Tier C enforced for semantic operations).");
-  } else if (tokens > RISK_THRESHOLD) {
-    warn("Near risk threshold (85%). Semantic appends should behave as Tier C per compactor rules.");
+if (exists(files.soul)) {
+  console.log("✅ SOUL.md present.");
+  if (overlayEnabled()) {
+    console.log("✅ Deterministic overlay ENABLED in SOUL.md.");
   } else {
-    ok("Semantic memory within safe bounds.");
+    console.log("⚠ Deterministic overlay NOT enabled in SOUL.md.");
   }
 } else {
-  console.log("\nℹ No semantic memory file detected (ok).");
+  console.log("⚠ SOUL.md not found.");
+}
+
+const semanticTokens = estimateSemanticTokens();
+console.log(`\nSemantic memory tokens (est): ${semanticTokens}`);
+
+if (semanticTokens > 1200) {
+  console.log("❌ Semantic memory exceeds HARD_LIMIT (1200).");
+} else if (semanticTokens > 1020) {
+  console.log("⚠ Semantic memory above risk threshold (1020).");
+} else {
+  console.log("✅ Semantic memory within safe bounds.");
 }
 
 console.log("\nDoctor complete.\n");

package/bin/install.js

@@ -8,6 +8,8 @@ const openclawRoot = path.join(HOME, ".openclaw");
 const workspace = path.join(openclawRoot, "workspace");
 const backupsRoot = path.join(openclawRoot, "backups", "deterministic");
 
+const pkg = require("../package.json");
+
 const tpl = (name) => path.join(__dirname, "..", "templates", name);
 
 const target = {
@@ -24,55 +26,67 @@ This system loads and adheres to SOUL.deterministic.md as a governing philosophi
 `;
 
 function exists(p) {
-  try { fs.accessSync(p); return true; } catch { return false; }
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 function ensureDir(p) {
   fs.mkdirSync(p, { recursive: true });
 }
 
-function read(p) {
-  return fs.readFileSync(p, "utf8");
-}
-
-function write(p, content) {
+function writeFile(p, content) {
   ensureDir(path.dirname(p));
   fs.writeFileSync(p, content);
 }
 
-function copyFile(src, dst) {
-  ensureDir(path.dirname(dst));
-  fs.copyFileSync(src, dst);
+function copyWithVersionStamp(templatePath, targetPath) {
+  const versionStamp = `<!-- Installed by openclaw-deterministic v${pkg.version} -->\n`;
+  const content = fs.readFileSync(templatePath, "utf8");
+  const stamped = versionStamp + content;
+  writeFile(targetPath, stamped);
 }
 
-function stamp() {
-  return new Date().toISOString().replaceAll(":", "-");
+function timestamp() {
+  return new Date().toISOString().replace(/:/g, "-");
 }
 
 function backupSnapshot(pathsToBackup) {
   ensureDir(backupsRoot);
-  const snap = path.join(backupsRoot, stamp());
+  const snap = path.join(backupsRoot, timestamp());
   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);
+    const relative = path.relative(openclawRoot, p);
+    const destination = path.join(snap, relative);
+    ensureDir(path.dirname(destination));
+    fs.copyFileSync(p, destination);
   }
 
   return snap;
 }
 
 function installTemplates() {
-  copyFile(tpl("OPERATING_RULES.md"), target.operating);
+  copyWithVersionStamp(
+    tpl("OPERATING_RULES.md"),
+    target.operating
+  );
   console.log("Installed: OPERATING_RULES.md");
 
-  copyFile(tpl("SOUL.deterministic.md"), target.detSoul);
+  copyWithVersionStamp(
+    tpl("SOUL.deterministic.md"),
+    target.detSoul
+  );
   console.log("Installed: SOUL.deterministic.md");
 
-  copyFile(tpl("memory-compactor.SKILL.md"), target.compactor);
+  copyWithVersionStamp(
+    tpl("memory-compactor.SKILL.md"),
+    target.compactor
+  );
   console.log("Installed: skills/memory-compactor/SKILL.md");
 }
 
@@ -83,7 +97,7 @@ function bootstrapSoulIfMissing() {
   }
 
   console.log("No SOUL.md detected — bootstrapping fresh SOUL.md with deterministic overlay.");
-  write(target.soul, OVERLAY_BLOCK.trim() + "\n");
+  writeFile(target.soul, OVERLAY_BLOCK.trim() + "\n");
   console.log("Created: SOUL.md (deterministic overlay enabled by default)");
 }
 
@@ -100,7 +114,12 @@ if (!exists(workspace)) {
 }
 
 console.log("Creating deterministic backup snapshot...");
-const snap = backupSnapshot([target.operating, target.detSoul, target.soul, target.compactor]);
+const snap = backupSnapshot([
+  target.operating,
+  target.detSoul,
+  target.soul,
+  target.compactor,
+]);
 console.log(`Backup location: ${snap}`);
 
 installTemplates();

package/package.json

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