@sdotwinter/openclaw-deterministic 0.4.1 → 0.5.1

package/bin/doctor.js

@@ -2,58 +2,102 @@
 
 const fs = require("fs");
 const path = require("path");
-const os = require("os");
 
-const pkg = require("../package.json");
+const HOME = process.env.HOME;
+const workspace = path.join(HOME, ".openclaw", "workspace");
 
-const OPENCLAW_DIR = path.join(os.homedir(), ".openclaw");
-const WORKSPACE_DIR = path.join(OPENCLAW_DIR, "workspace");
+const paths = {
+  operating: path.join(workspace, "OPERATING_RULES.md"),
+  soul: path.join(workspace, "SOUL.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"),
+};
 
-function checkFile(filePath, label) {
-  if (!fs.existsSync(filePath)) {
-    console.log(`❌ Missing: ${label}`);
-    return;
-  }
+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 content = fs.readFileSync(filePath, "utf8");
+const HARD_LIMIT = 1200;
+const RISK_THRESHOLD = 1020;
 
-  if (!content.includes("Installed by openclaw-deterministic")) {
-    console.log(`⚠️  ${label} exists but is not deterministic-managed.`);
-    return;
+function exists(p) {
+  try {
+    fs.accessSync(p);
+    return true;
+  } catch {
+    return false;
   }
+}
 
-  if (!content.includes(`v${pkg.version}`)) {
-    console.log(`⚠️  ${label} version drift detected.`);
-    return;
-  }
+function read(p) {
+  return fs.readFileSync(p, "utf8");
+}
 
-  console.log(`✅ ${label} OK (v${pkg.version})`);
+// 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 runDoctor() {
-  console.log("Running deterministic doctor...\n");
+function ok(msg) { console.log(`✅ ${msg}`); }
+function warn(msg) { console.log(`⚠ ${msg}`); }
+function fail(msg) { console.log(`❌ ${msg}`); }
 
-  if (!fs.existsSync(OPENCLAW_DIR)) {
-    console.log("❌ OpenClaw not installed.");
-    process.exit(1);
-  }
+console.log("\nRunning deterministic doctor...\n");
+
+// --- 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.");
 
-  checkFile(
-    path.join(WORKSPACE_DIR, "OPERATING_RULES.md"),
-    "OPERATING_RULES.md"
-  );
+// 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);
+}
 
-  checkFile(
-    path.join(WORKSPACE_DIR, "SOUL.deterministic.md"),
-    "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).");
 
-  checkFile(
-    path.join(WORKSPACE_DIR, "skills", "memory-compactor", "SKILL.md"),
-    "memory-compactor SKILL.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).");
 
-  console.log("\nDoctor complete.");
+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 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) {
+    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.");
+  } else {
+    ok("Semantic memory within safe bounds.");
+  }
+} else {
+  console.log("\nℹ No semantic memory file detected (ok).");
 }
 
-runDoctor();
+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.4.1",
+  "version": "0.5.1",
   "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