@sdotwinter/openclaw-deterministic 0.17.6 → 0.17.9

package/README.md

@@ -1,8 +1,8 @@
-# OpenClaw Deterministic
+# OpenClaw Deterministic (OCD)
 
-A deterministic execution, memory governance, and integrity enforcement framework for OpenClaw.
+Deterministic governance, memory discipline, and integrity enforcement framework for OpenClaw.
 
-OpenClaw Deterministic enforces canonical template integrity, semantic memory limits, and execution discipline to transform OpenClaw into a predictable, auditable system suitable for long-running agent deployments.
+OpenClaw Deterministic transforms OpenClaw into a predictable, auditable execution system suitable for long-running agent deployments and CI environments.
 
 This is not an assistant plugin.
 
@@ -14,32 +14,69 @@ It is a governance layer.
 
 Install globally:
 
+```bash
 npm install -g @sdotwinter/openclaw-deterministic
+```
 
-Then initialize governance inside your OpenClaw workspace:
+Add to your PATH (optional but recommended):
 
+```bash
+export PATH="$PATH:$(npm root -g)/@sdotwinter/openclaw-deterministic/bin"
+```
+
+Or create a symlink:
+
+```bash
+sudo ln -s $(npm root -g)/@sdotwinter/openclaw-deterministic/bin/oc-deterministic /usr/local/bin/
+```
+
+Apply deterministic governance to an existing OpenClaw workspace:
+
+```bash
 oc-deterministic install
+```
 
 Verify installation:
 
+```bash
 oc-deterministic doctor
+```
 
-Concise health summary:
+Concise health summary (CI-friendly):
 
+```bash
 oc-deterministic status
+```
+
+---
+
+## Safety Guarantees
+
+OpenClaw Deterministic enforces execution discipline with explicit safety guarantees:
+
+- Does not overwrite an existing SOUL.md
+- Verifies canonical integrity before upgrade
+- Refuses to upgrade drifted files (unless --force)
+- Creates deterministic backup snapshots before mutation
+- Supports structured revert to previous snapshot
+- Exposes machine-readable health status
+- Blocks silent structural mutation
+
+This system assumes drift is inevitable.
+
+It makes drift visible.
 
 ---
 
 ## What This Solves
 
-AI systems drift.
+AI systems drift over time:
 
-They drift in:
-- Memory usage
-- Execution classification
-- File modification behavior
-- Configuration alignment
-- Contract integrity
+- Memory growth
+- File mutation
+- Execution misclassification
+- Configuration divergence
+- Contract ambiguity
 
 OpenClaw Deterministic enforces:
 
@@ -48,9 +85,9 @@ OpenClaw Deterministic enforces:
 - Semantic memory limits
 - Config-driven thresholds
 - Governance event logging
-- Structured machine-readable health reporting
+- Structured health reporting
 
-The goal:
+The objective:
 
 Predictable execution under defined constraints.
 
@@ -60,14 +97,15 @@ Predictable execution under defined constraints.
 
 ### Deterministic Execution Tiers
 
-Execution is classified into three tiers:
+Execution is classified into:
 
 Tier A — Safe  
 Tier B — Governed Modification  
 Tier C — Destructive / Structural  
 
 Each tier defines:
-- Whether diffs are required
+
+- Whether a diff preview is required
 - Whether confirmation is required
 - Whether auto-execution is allowed
 
@@ -79,7 +117,7 @@ This prevents silent behavioral drift.
 
 Deterministic templates embed canonical SHA256 hashes.
 
-`doctor` verifies:
+doctor verifies:
 
 - Template presence
 - Version alignment
@@ -87,7 +125,39 @@ Deterministic templates embed canonical SHA256 hashes.
 
 If a file is manually edited outside deterministic flow, the system detects it.
 
-This enables tamper visibility.
+Tamper visibility is enforced.
+
+---
+
+### Upgrade Integrity Gate
+
+oc-deterministic upgrade:
+
+- Verifies canonical integrity before applying changes
+- Refuses overwrite if drift is detected
+- Supports --force override
+- Supports --dry-run
+
+Upgrade is governed mutation — not blind overwrite.
+
+---
+
+### Deterministic Backup + Revert
+
+Before template mutation:
+
+Snapshots are stored at:
+
+~/.openclaw/backups/deterministic/<timestamp>/
+
+Revert commands:
+
+oc-deterministic revert --list  
+oc-deterministic revert --to <timestamp>
+
+Revert restores deterministic files from snapshot.
+
+This enables safe experimentation without state loss.
 
 ---
 
@@ -100,22 +170,23 @@ Semantic memory is:
 - Evaluated against risk thresholds
 - Logged on violation
 
-Configuration:
+Configuration file:
 
 ~/.openclaw/.deterministic.json
 
 Example:
 
+```json
 {
   "semantic": {
     "HARD_LIMIT": 1200,
     "RISK_THRESHOLD_PERCENT": 85
   },
   "governance": {
-    "strict_mode": false,
     "violation_logging": true
   }
 }
+```
 
 This prevents uncontrolled memory expansion.
 
@@ -140,21 +211,7 @@ Supports:
 - Machine-readable JSON output
 - Deterministic backup snapshots
 - Governance event logging
-- CI integration
-
----
-
-## Upgrade Model
-
-Templates are version-stamped.
-
-Upgrade flow preserves:
-
-- Backups
-- Deterministic config
-- User SOUL.md
-
-Future releases include safe merge flows for template upgrades.
+- CI integration via exit codes
 
 ---
 
@@ -181,9 +238,9 @@ Designed for:
 - CI-integrated governance
 - Environments requiring auditability
 
-If you need experimentation, use OpenClaw alone.
+If you want experimentation, use OpenClaw alone.
 
-If you need discipline, use Deterministic.
+If you want discipline, use OpenClaw Deterministic.
 
 ---
 

package/ROADMAP.md

@@ -0,0 +1,81 @@
+# OpenClaw Deterministic (OCD) — Roadmap
+
+This roadmap outlines the next phases of deterministic governance evolution.
+
+The goal is not feature growth.
+
+The goal is stronger guarantees.
+
+---
+
+## Governance & Integrity
+
+- Safe template merge flow inside upgrade
+- Cooldown state visibility in doctor
+- Semantic shard suggestion automation
+
+---
+
+## Observability & Automation
+
+- Structured logging mode
+- Centralized governance event log (beyond episodic markdown)
+- Compaction activity log
+- Drift detection alerting mode
+
+(Status command complete)
+
+---
+
+## Memory System Enhancements
+
+- Deterministic shard splitting
+- Automatic semantic pressure warnings
+- Episodic summarization quality check
+- Manual compaction preview mode
+- Token estimation normalization
+- Memory integrity checksum tracking
+
+---
+
+## Install & Bootstrap
+
+- Fresh-install auto-enable refinement
+- Install confirmation summary report
+- Rollback preview mode
+- Backup pruning policy
+- Multi-workspace support
+
+---
+
+## CLI Improvements
+
+- enable --dry-run
+- revert --preview
+- Help polish
+- Command aliases
+
+(Exit codes already formalized via doctor/status)
+
+---
+
+## Architecture & Distribution
+
+- Governance flow diagram
+- Memory tier diagram
+- Upgrade policy documentation
+- Integration guide
+- Public positioning statement
+
+---
+
+## Advanced (Future)
+
+- Expanded governance config surface (.deterministic.json)
+- Policy enforcement plugin system
+- Multi-agent compatibility layer
+- External monitoring hook
+- Remote health reporting
+- Immutable governance lock mode
+- Strict mode blocking Tier B auto-execution
+- Deterministic sandbox testing mode

package/bin/audit.js

@@ -34,6 +34,14 @@ function exists(p) {
   }
 }
 
+function read(p) {
+  return fs.readFileSync(p, "utf8");
+}
+
+function stripHeaders(content) {
+  return content.replace(/<!--[\s\S]*?-->/g, "").trim();
+}
+
 console.log("\nRunning deterministic audit...\n");
 
 let driftFound = false;
@@ -52,11 +60,27 @@ for (const file of files) {
   }
 
   try {
+    const templateContent = stripHeaders(read(file.template));
+    const installedContent = stripHeaders(read(file.installed));
+
+    // Write stripped content to temp files for diff
+    const tmpDir = fs.mkdtempSync(path.join(require("os").tmpdir(), "audit-"));
+    const tmpTemplate = path.join(tmpDir, "template");
+    const tmpInstalled = path.join(tmpDir, "installed");
+
+    fs.writeFileSync(tmpTemplate, templateContent);
+    fs.writeFileSync(tmpInstalled, installedContent);
+
     const diff = execSync(
-      `diff -u "${file.template}" "${file.installed}"`,
+      `diff -u "${tmpTemplate}" "${tmpInstalled}"`,
       { stdio: "pipe" }
     ).toString();
 
+    // Cleanup temp files
+    fs.unlinkSync(tmpTemplate);
+    fs.unlinkSync(tmpInstalled);
+    fs.rmdirSync(tmpDir);
+
     if (diff.trim().length === 0) {
       console.log(`✅ ${file.name} matches template.`);
     } else {

package/package.json

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

package/templates/config/.deterministic.json

@@ -4,7 +4,6 @@
     "RISK_THRESHOLD_PERCENT": 85
   },
   "governance": {
-    "strict_mode": false,
     "violation_logging": true
   }
 }