Upgrade Rollback Doctor — Release Notes v1.0

Skill: upgrade-rollback-doctor

Version: 1.0.0

Release Date: 2026-05-01

Category: orchestration

Price: $4.99

What It Does

Upgrade Rollback Doctor makes OpenClaw upgrades reversible. Before you upgrade, it runs preflight checks — capturing your current version, git state, key files, disk space, and skill inventory as a restore point. After you upgrade, it runs smoke tests across Python, git, config files, and skill scripts to verify everything still works. If something breaks, you get an explicit, human-executable rollback checklist with no guesswork.

It's the safety net that turns a stressful upgrade into a confident, documented procedure.

Key Features

Preflight Mode

Run before upgrading to capture a complete readiness snapshot:

Current OpenClaw version and git status (--short)
Python version check
Key file inventory (SKILL.md, scripts, config)
Disk space available in workspace
List of installed skills (up to 20 skill scripts syntax-checked via py_compile)

Preflight output is written to JSON for comparison after the upgrade.

Smoke Test Mode

Run after upgrading to verify the new version is healthy:

Python version confirmed via [sys.executable, '--version'] (no shell)
Git workspace status clean check via ['git', 'status', '--short'] (no shell)
Key config and memory files present and readable
Skill scripts syntax-valid via py_compile (same 20-script cap as preflight)
Summary verdict: PASS or FAIL with specific failing items listed

Rollback Checklist Generation

When smoke tests fail, the tool produces a prioritised, human-readable rollback checklist covering:

1. Steps to restore from the captured preflight snapshot

2. Which specific files or skills failed validation

3. Git commands needed to revert if a git-based upgrade was used

4. Confirmation steps to verify rollback succeeded

JSON Report Output

Both preflight and smoke results write structured JSON to --out for archiving, diffing, and handoff to the Slider verification step.

Usage


# Step 1: Run preflight BEFORE upgrading
python3 scripts/upgrade_rollback_doctor.py preflight \
  --workspace /root/.openclaw/workspace \
  --out preflight-2026-05-01.json

# [Apply your upgrade here]

# Step 2: Run smoke tests AFTER upgrading
python3 scripts/upgrade_rollback_doctor.py smoke \
  --workspace /root/.openclaw/workspace \
  --out smoke-2026-05-01.json

Example Preflight Output


{
  "mode": "preflight",
  "timestamp": "2026-05-01T09:00:00Z",
  "workspace": "/root/.openclaw/workspace",
  "python_version": "3.12.3",
  "git_status": "clean",
  "disk_space_mb": 4821,
  "skills_checked": 20,
  "skills_valid": 20,
  "skills_invalid": 0,
  "verdict": "READY"
}

Example Smoke Test Output


{
  "mode": "smoke",
  "timestamp": "2026-05-01T09:15:00Z",
  "workspace": "/root/.openclaw/workspace",
  "python_ok": true,
  "git_ok": true,
  "key_files_ok": true,
  "skills_valid": 20,
  "skills_invalid": 0,
  "verdict": "PASS",
  "rollback_required": false
}

Parameters

| Parameter | Description |

|-----------|-------------|

| preflight | Gather readiness checks before upgrade |

| smoke | Verify key files, Python, git, skill scripts after upgrade |

| --workspace | Path to OpenClaw workspace directory |

| --out | Optional path for JSON report output |

Guardrails

Never modifies config or enables disabled crons without explicit approval
Always create a restore point before acting on preflight recommendations
Rollback steps are explicit and executable by a human operator without agent assistance
subprocess.run() calls use fixed argument lists only — no shell=True, no user-controlled input passed to shell
All subprocess calls are bounded by timeout=15

Requirements

OpenClaw: v2026.3.23+
Runtime: Python 3.8+
Dependencies: None — Python standard library only (argparse, json, shutil, subprocess, sys, pathlib)
API keys: None
Network: None

Security & Quality Clearances

| Stage | Verdict | Date |

|-------|---------|------|

| Viper QA | APPROVED_FOR_RELEASE (5/5) | 2026-05-01 |

| Warlock Security Audit | SECURITY_CLEARED | 2026-05-01 |

Security audit summary:

subprocess.run() present but safe: all three invocations use fixed argument lists — ['git', 'status', '--short'], [sys.executable, '--version'], [sys.executable, '-m', 'py_compile', str(s)]
shell=True confirmed absent
str(s) is a resolved Path object from a controlled glob('*/scripts/*.py')[:20] — not raw user input
timeout=15 enforced on all subprocess calls
No network I/O, no secrets, no credential access, no openclaw.json access, no destructive writes
External scan: risk_score=0, decision=allow, findings=[]
PACKAGED_PROD_VERIFIED (2026-04-29)

Compatibility

OpenClaw: v2026.3.23+
Python: 3.8+
OS: Linux, macOS, Windows (stdlib only)
Dependencies: None

*Release notes prepared by Hollywood — 2026-05-01*

Upgrade Rollback Doctor