@sdotwinter/openclaw-deterministic 0.12.0 → 0.14.0

package/bin/doctor.js

@@ -1,38 +1,33 @@
 #!/usr/bin/env node
 
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 
-const pkg = require("../package.json");
+const JSON_MODE = process.argv.includes("--json");
 
-const args = process.argv.slice(2);
-const JSON_MODE = args.includes("--json");
-
-const HOME = process.env.HOME;
-const openclawRoot = path.join(HOME, ".openclaw");
-const workspace = path.join(openclawRoot, "workspace");
+const pkg = require(path.join(__dirname, "..", "package.json"));
+const CLI_VERSION = pkg.version;
 
 const DEFAULT_HARD_LIMIT = 1200;
-const DEFAULT_RISK_THRESHOLD = 1020;
+const DEFAULT_RISK_PERCENT = 85;
 
-const episodicLogPath = path.join(
-  openclawRoot,
-  "workspace",
-  "memory",
-  "episodic",
-  "governance-log.md"
-);
+const home = os.homedir();
+const openclawRoot = path.join(home, ".openclaw");
+const workspace = path.join(openclawRoot, "workspace");
 
-const files = {
+const paths = {
   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"),
+  semantic: path.join(workspace, "memory", "semantic", "openclaw.md"),
+  config: path.join(openclawRoot, ".deterministic.json"),
 };
 
 function exists(p) {
   try {
-    fs.accessSync(p);
+    fs.accessSync(p, fs.constants.F_OK);
     return true;
   } catch {
     return false;
@@ -43,201 +38,156 @@ function read(p) {
   return fs.readFileSync(p, "utf8");
 }
 
-function appendGovernanceEvent(event) {
+function readJsonSafe(p) {
   try {
-    const timestamp = new Date().toISOString();
-    const entry = `\n---\nTime: ${timestamp}\nType: ${event.type}\nDetails: ${event.details}\n---\n`;
-
-    fs.mkdirSync(path.dirname(episodicLogPath), { recursive: true });
-    fs.appendFileSync(episodicLogPath, entry);
+    if (!exists(p)) return null;
+    return JSON.parse(read(p));
   } catch {
-    // Logging must never crash doctor
+    return { __invalid: true };
   }
 }
 
-function versionFromFile(content) {
-  const match = content.match(/Installed by openclaw-deterministic v([0-9.]+)/);
-  return match ? match[1] : null;
+function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.split(/\s+/).length * 1.3);
 }
 
-function overlayEnabled() {
-  if (!exists(files.soul)) return false;
-  const content = read(files.soul);
-  return content.includes("SOUL.deterministic.md");
-}
-
-function estimateSemanticTokens() {
-  const semanticPath = path.join(
-    openclawRoot,
-    "workspace",
-    "memory",
-    "semantic",
-    "openclaw.md"
-  );
+function getLimits(cfg) {
+  const hard = cfg?.semantic?.HARD_LIMIT;
+  const pct = cfg?.semantic?.RISK_THRESHOLD_PERCENT;
 
-  if (!exists(semanticPath)) return 0;
+  const HARD_LIMIT = Number.isFinite(hard) ? hard : DEFAULT_HARD_LIMIT;
+  const PERCENT = Number.isFinite(pct) ? pct : DEFAULT_RISK_PERCENT;
+  const RISK_THRESHOLD = Math.floor((HARD_LIMIT * PERCENT) / 100);
 
-  const content = read(semanticPath);
-  return Math.ceil(content.length / 4);
+  return { HARD_LIMIT, RISK_THRESHOLD, PERCENT };
 }
 
-function evaluateVersion(filePath) {
-  if (!exists(filePath)) {
-    return { status: "missing", version: null };
-  }
-
-  const content = read(filePath);
-  const version = versionFromFile(content);
+function appendGovernanceEvent(event) {
+  try {
+    const episodicDir = path.join(workspace, "memory", "episodic");
+    if (!exists(episodicDir)) return;
 
-  if (!version) {
-    return { status: "no-stamp", version: null };
-  }
+    const file = path.join(
+      episodicDir,
+      `governance-${new Date().toISOString().slice(0, 10)}.md`
+    );
 
-  if (version === pkg.version) {
-    return { status: "match", version };
-  }
+    const entry = `
+## Governance Event — ${new Date().toISOString()}
 
-  return { status: "mismatch", version };
-}
+Type: ${event.type}
+Details: ${event.details}
 
-function parseHardLimit() {
-  if (!exists(files.compactor)) return null;
-  const content = read(files.compactor);
-  const match = content.match(/HARD_LIMIT[^0-9]*([0-9]+)/);
-  return match ? parseInt(match[1], 10) : null;
-}
+---
+`;
 
-function parseRiskThreshold() {
-  if (!exists(files.compactor)) return null;
-  const content = read(files.compactor);
-  const match = content.match(/RISK_THRESHOLD[^0-9]*([0-9]+)/);
-  return match ? parseInt(match[1], 10) : null;
+    fs.appendFileSync(file, entry);
+  } catch {
+    // never crash doctor
+  }
 }
 
 function evaluate() {
   const result = {
-    cliVersion: pkg.version,
+    cliVersion: CLI_VERSION,
     openclawDetected: exists(openclawRoot),
     workspaceDetected: exists(workspace),
-    files: {},
-    overlayEnabled: false,
-    semanticTokens: 0,
-    semanticStatus: "safe",
-    limits: {
-      hardLimitConfigured: null,
-      riskThresholdConfigured: null,
-      hardLimitDefault: DEFAULT_HARD_LIMIT,
-      riskThresholdDefault: DEFAULT_RISK_THRESHOLD,
-      coherent: true,
-    },
   };
 
   if (!result.openclawDetected || !result.workspaceDetected) {
     return result;
   }
 
-  result.files.operating = evaluateVersion(files.operating);
-  result.files.detSoul = evaluateVersion(files.detSoul);
-  result.files.compactor = evaluateVersion(files.compactor);
+  result.files = {
+    operating: exists(paths.operating),
+    detSoul: exists(paths.detSoul),
+    compactor: exists(paths.compactor),
+    soul: exists(paths.soul),
+  };
 
-  result.overlayEnabled = overlayEnabled();
+  const cfg = readJsonSafe(paths.config);
 
-  const tokens = estimateSemanticTokens();
-  result.semanticTokens = tokens;
+  result.config = {
+    present: exists(paths.config),
+    invalid: cfg?.__invalid === true,
+  };
 
-  const hardLimit = parseHardLimit();
-  const riskThreshold = parseRiskThreshold();
+  const limits = getLimits(cfg);
 
-  result.limits.hardLimitConfigured = hardLimit;
-  result.limits.riskThresholdConfigured = riskThreshold;
+  result.limits = limits;
 
-  if (hardLimit && hardLimit !== DEFAULT_HARD_LIMIT) {
-    result.limits.coherent = false;
-  }
+  if (exists(paths.semantic)) {
+    const tokens = estimateTokens(read(paths.semantic));
+    result.semanticTokens = tokens;
 
-  if (riskThreshold && riskThreshold !== DEFAULT_RISK_THRESHOLD) {
-    result.limits.coherent = false;
-  }
+    if (tokens > limits.HARD_LIMIT) {
+      result.semanticStatus = "hard-limit-exceeded";
 
-  const effectiveHardLimit = hardLimit || DEFAULT_HARD_LIMIT;
-  const effectiveRiskThreshold = riskThreshold || DEFAULT_RISK_THRESHOLD;
+      appendGovernanceEvent({
+        type: "semantic-hard-limit",
+        details: `Tokens ${tokens} > HARD_LIMIT ${limits.HARD_LIMIT}`,
+      });
+
+    } else if (tokens > limits.RISK_THRESHOLD) {
+      result.semanticStatus = "risk-threshold";
 
-  if (tokens > effectiveHardLimit) {
-    result.semanticStatus = "hard-limit-exceeded";
-  } else if (tokens > effectiveRiskThreshold) {
-    result.semanticStatus = "risk-threshold";
+      appendGovernanceEvent({
+        type: "semantic-risk-threshold",
+        details: `Tokens ${tokens} > RISK_THRESHOLD ${limits.RISK_THRESHOLD}`,
+      });
+
+    } else {
+      result.semanticStatus = "safe";
+    }
   } else {
+    result.semanticTokens = 0;
     result.semanticStatus = "safe";
   }
 
   return result;
 }
 
-function printHuman(result) {
+function printHuman(r) {
   console.log("\nRunning deterministic doctor...\n");
 
-  if (!result.openclawDetected) {
-    console.log("❌ OpenClaw directory not found.");
-    process.exit(1);
+  if (!r.openclawDetected) {
+    console.log("❌ OpenClaw not detected.");
+    return;
   }
 
-  if (!result.workspaceDetected) {
+  if (!r.workspaceDetected) {
     console.log("❌ Workspace missing.");
-    process.exit(1);
+    return;
   }
 
-  for (const [name, info] of Object.entries(result.files)) {
-    const label =
-      name === "operating"
-        ? "OPERATING_RULES.md"
-        : name === "detSoul"
-        ? "SOUL.deterministic.md"
-        : "memory-compactor SKILL.md";
-
-    if (info.status === "missing") {
-      console.log(`❌ ${label} missing.`);
-      appendGovernanceEvent({ type: "file-missing", details: label });
-    } else if (info.status === "no-stamp") {
-      console.log(`⚠ ${label} version stamp missing.`);
-      appendGovernanceEvent({ type: "no-version-stamp", details: label });
-    } else if (info.status === "mismatch") {
-      console.log(
-        `⚠ ${label} version mismatch (installed ${info.version}, CLI ${pkg.version})`
-      );
-      appendGovernanceEvent({
-        type: "version-mismatch",
-        details: `${label} installed ${info.version}, CLI ${pkg.version}`,
-      });
+  console.log(`CLI version: ${r.cliVersion}\n`);
+
+  for (const [key, present] of Object.entries(r.files)) {
+    if (present) {
+      console.log(`✅ ${key} present.`);
     } else {
-      console.log(`✅ ${label} version matches CLI (${info.version})`);
+      console.log(`⚠ ${key} missing.`);
     }
   }
 
-  console.log("✅ SOUL.md present.");
-  console.log(
-    result.overlayEnabled
-      ? "✅ Deterministic overlay ENABLED in SOUL.md."
-      : "⚠ Deterministic overlay NOT enabled in SOUL.md."
-  );
-
-  if (!result.limits.coherent) {
-    console.log("⚠ Threshold configuration drift detected in SKILL.md.");
-    appendGovernanceEvent({
-      type: "threshold-drift",
-      details: `HARD_LIMIT=${result.limits.hardLimitConfigured}, RISK_THRESHOLD=${result.limits.riskThresholdConfigured}`,
-    });
+  if (!r.config.present) {
+    console.log("⚠ Deterministic config missing. Using defaults.");
+  } else if (r.config.invalid) {
+    console.log("⚠ Deterministic config invalid JSON. Using defaults.");
+  } else {
+    console.log(
+      `✅ Config loaded. HARD_LIMIT=${r.limits.HARD_LIMIT}, ` +
+      `RISK_THRESHOLD=${r.limits.RISK_THRESHOLD} (${r.limits.PERCENT}%)`
+    );
   }
 
-  console.log(`\nSemantic memory tokens (est): ${result.semanticTokens}`);
+  console.log(`\nSemantic memory tokens (est): ${r.semanticTokens}`);
 
-  if (result.semanticStatus === "hard-limit-exceeded") {
-    console.log("❌ Semantic memory exceeds HARD_LIMIT.");
-    appendGovernanceEvent({
-      type: "semantic-hard-limit-exceeded",
-      details: `Tokens=${result.semanticTokens}`,
-    });
-  } else if (result.semanticStatus === "risk-threshold") {
-    console.log("⚠ Semantic memory above risk threshold.");
+  if (r.semanticStatus === "hard-limit-exceeded") {
+    console.log(`❌ Semantic memory exceeds HARD_LIMIT (${r.limits.HARD_LIMIT}).`);
+  } else if (r.semanticStatus === "risk-threshold") {
+    console.log(`⚠ Semantic memory above risk threshold (${r.limits.RISK_THRESHOLD}).`);
   } else {
     console.log("✅ Semantic memory within safe bounds.");
   }

package/bin/install.js

@@ -1,70 +1,93 @@
 #!/usr/bin/env node
 
 const fs = require("fs");
+const os = require("os");
 const path = require("path");
 
-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");
-
+// -----------------------------
+// Args
+// -----------------------------
 const args = process.argv.slice(2);
 const DRY_RUN = args.includes("--dry-run");
 
-const tpl = (name) => path.join(__dirname, "..", "templates", name);
+// -----------------------------
+// Version + markers
+// -----------------------------
+const pkg = require(path.join(__dirname, "..", "package.json"));
+const CLI_VERSION = pkg.version;
+
+const VERSION_STAMP = `<!-- Installed by openclaw-deterministic v${CLI_VERSION} -->`;
+
+// NOTE: This block is intentionally minimal and deterministic.
+// It only declares the overlay and does not replace user SOUL content.
+const OVERLAY_BLOCK = `
+## Deterministic Governance Overlay
+
+This system loads and adheres to SOUL.deterministic.md as a governing philosophical constraint.
+`.trim();
+
+// -----------------------------
+// Paths
+// -----------------------------
+const home = os.homedir();
+const openclawRoot = path.join(home, ".openclaw");
+const workspace = path.join(openclawRoot, "workspace");
+
+const backupsRoot = path.join(openclawRoot, "backups", "deterministic");
 
 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"),
+  config: path.join(openclawRoot, ".deterministic.json"),
 };
 
-const OVERLAY_BLOCK = `
-## Deterministic Governance Overlay
-
-This system loads and adheres to SOUL.deterministic.md as a governing philosophical constraint.
-`;
+function tpl(rel) {
+  return path.join(__dirname, "..", "templates", rel);
+}
 
+const configTemplatePath = path.join(
+  __dirname,
+  "..",
+  "templates",
+  "config",
+  ".deterministic.json"
+);
+
+// -----------------------------
+// Helpers
+// -----------------------------
 function exists(p) {
   try {
-    fs.accessSync(p);
+    fs.accessSync(p, fs.constants.F_OK);
     return true;
   } catch {
     return false;
   }
 }
 
-function ensureDir(p) {
-  if (!DRY_RUN) {
-    fs.mkdirSync(p, { recursive: true });
-  }
+function ensureDir(dirPath) {
+  if (exists(dirPath)) return;
+  if (DRY_RUN) return;
+  fs.mkdirSync(dirPath, { recursive: true });
 }
 
 function writeFile(p, content) {
+  ensureDir(path.dirname(p));
   if (DRY_RUN) {
     console.log(`[DRY-RUN] Would write: ${p}`);
     return;
   }
-  ensureDir(path.dirname(p));
-  fs.writeFileSync(p, content);
+  fs.writeFileSync(p, content, "utf8");
 }
 
-function copyWithVersionStamp(templatePath, targetPath) {
-  const versionStamp = `<!-- Installed by openclaw-deterministic v${pkg.version} -->\n`;
-  const content = fs.readFileSync(templatePath, "utf8");
-  const stamped = versionStamp + content;
-
-  if (DRY_RUN) {
-    console.log(`[DRY-RUN] Would install: ${targetPath}`);
-  }
-
-  writeFile(targetPath, stamped);
+function readFile(p) {
+  return fs.readFileSync(p, "utf8");
 }
 
 function timestamp() {
+  // keep filesystem-safe
   return new Date().toISOString().replace(/:/g, "-");
 }
 
@@ -91,29 +114,79 @@ function backupSnapshot(pathsToBackup) {
   return snap;
 }
 
+function copyWithVersionStamp(src, dest) {
+  const raw = readFile(src);
+  const stamped = `${VERSION_STAMP}\n${raw.replace(/^\uFEFF/, "")}`;
+  writeFile(dest, stamped);
+
+  if (!DRY_RUN) {
+    // keep output consistent with your CLI style
+    const pretty = dest.startsWith(workspace)
+      ? dest.replace(workspace + path.sep, "")
+      : dest;
+    console.log(`Installed: ${pretty}`);
+  } else {
+    console.log(`[DRY-RUN] Would install: ${dest}`);
+  }
+}
+
+// -----------------------------
+// Install steps
+// -----------------------------
 function installTemplates() {
+  // Ensure skill directory exists
+  ensureDir(path.dirname(target.compactor));
+
   copyWithVersionStamp(tpl("OPERATING_RULES.md"), target.operating);
   copyWithVersionStamp(tpl("SOUL.deterministic.md"), target.detSoul);
   copyWithVersionStamp(tpl("memory-compactor.SKILL.md"), target.compactor);
 }
 
+function installConfigIfMissing() {
+  if (exists(target.config)) {
+    console.log("Config exists — NOT modified.");
+    return;
+  }
+
+  if (!exists(configTemplatePath)) {
+    console.error(
+      `Config template missing in package: ${configTemplatePath}\n` +
+        "Refusing to create an empty config."
+    );
+    process.exit(1);
+  }
+
+  if (DRY_RUN) {
+    console.log(`[DRY-RUN] Would write: ${target.config}`);
+    return;
+  }
+
+  fs.copyFileSync(configTemplatePath, target.config);
+  console.log(`Installed: ${target.config}`);
+}
+
 function bootstrapSoulIfMissing() {
   if (exists(target.soul)) {
     console.log("User SOUL.md exists — NOT modified.");
     return;
   }
 
-  console.log("No SOUL.md detected — bootstrapping fresh SOUL.md with deterministic overlay.");
+  console.log(
+    "No SOUL.md detected — bootstrapping fresh SOUL.md with deterministic overlay."
+  );
 
   if (DRY_RUN) {
     console.log("[DRY-RUN] Would create SOUL.md with deterministic overlay.");
     return;
   }
 
-  writeFile(target.soul, OVERLAY_BLOCK.trim() + "\n");
+  writeFile(target.soul, OVERLAY_BLOCK + "\n");
   console.log("Created: SOUL.md (deterministic overlay enabled by default)");
 }
 
+// -----------------------------
+// Main
+// -----------------------------
 if (!exists(openclawRoot)) {
   console.error("OpenClaw not found at ~/.openclaw");
   process.exit(1);
@@ -126,28 +199,32 @@ if (!exists(workspace)) {
 
 if (DRY_RUN) {
   console.log("\nRunning deterministic install (dry-run mode)...\n");
-} else {
-  console.log("Creating deterministic backup snapshot...");
 }
 
-const snap = backupSnapshot([
+const pathsToBackup = [
   target.operating,
   target.detSoul,
-  target.soul,
   target.compactor,
-]);
+  // NOTE: we do NOT back up SOUL.md here because install never modifies it.
+  // If you later add an "enable" flow that edits SOUL.md, that command should back it up there.
+  target.config,
+];
+
+const snap = backupSnapshot(pathsToBackup);
 
-if (snap) {
+if (!DRY_RUN) {
+  console.log("Creating deterministic backup snapshot...");
   console.log(`Backup location: ${snap}`);
 }
 
 installTemplates();
+installConfigIfMissing();
 bootstrapSoulIfMissing();
 
 if (DRY_RUN) {
   console.log("\nDry-run complete. No changes were written.\n");
 } else {
-  console.log("\nDeterministic governance installed successfully.\n");
+  console.log("\nDeterministic governance installed successfully.");
 }
 
 process.exit(0);

package/package.json

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

package/templates/config/.deterministic.json

@@ -0,0 +1,10 @@
+{
+  "semantic": {
+    "HARD_LIMIT": 1200,
+    "RISK_THRESHOLD_PERCENT": 85
+  },
+  "governance": {
+    "strict_mode": false,
+    "violation_logging": true
+  }
+}