16gagent/upgrade-playbook.md

# Upgrade Playbook

> Migration strategy for upgrading OpenClaw core while maintaining protocol compatibility.
> Part of COMPATIBILITY-STRATEGY.md §F.

---

## §1 Pre-Upgrade Checklist

Before any upgrade:

```markdown
- [ ] Run `node scripts/upgrade-test.mjs` — record baseline PASS count
- [ ] Run `node scripts/audit-all.mjs` — record baseline WARN/FAIL counts
- [ ] Commit all outstanding changes (`git status` should be clean)
- [ ] Read OpenClaw changelog for the target version
- [ ] Check version-contract.md §3 Required Interfaces for changes
```

---

## §2 Patch Upgrade (v0.9.1 → v0.9.2)

**Definition:** Bugfix release. No breaking changes.

### Procedure

```
1. Upgrade OpenClaw          ← per OpenClaw install instructions
2. Run upgrade-test          ← node scripts/upgrade-test.mjs
3. Run full audit            ← node scripts/audit-all.mjs
4. Verify                    ← all PASS, no regressions
```

**Expected changes:** 0 files modified.

**Rollback:** `openclaw restart` with previous version.

---

## §3 Minor Upgrade (v0.9.x → v0.10.x)

**Definition:** Feature release. Possible tool name additions, config format changes.

### Procedure

```text
PRE-CHECK
├─ Read OpenClaw changelog for:
│   ├─ Tool name changes
│   ├─ Cron format changes
│   └─ Config format changes
├─ Run baseline tests (upgrade-test + audit-all)
└─ git stash or commit

MIGRATION
├─ [IF tool names changed]  Update AGENTS.md §3b, §6, §CPB
│   ├─ s/old_name/new_name/  in ctx_search references
│   └─ s/old_name/new_name/  in memory_search references
├─ [IF cron format changed]  Re-register Dream Cycle job:
│   cron(action="remove", ...) → cron(action="add", ...)
├─ [IF config format changed] Update `.openclaw/` config files
└─ git commit -m "chore: adapt to OpenClaw v0.10.x"

VERIFICATION
├─ node scripts/upgrade-test.mjs   ← all PASS
├─ node scripts/audit-all.mjs      ← baseline match
└─ Manual: verify Dream Cycle runs at next scheduled time

ROLLBACK
├─ git revert the migration commit
├─ Re-register old cron job format
└─ openclaw restart
```

### Common Minor Upgrade Actions

| Change | Affects | Action |
|--------|---------|--------|
| Tool API signature change | AGENTS.md §3b | Update search parameter format |
| New tool addition | — | Optional: add to protocol if relevant |
| Cron syntax change | .openclaw/cron/ | Re-register all jobs |
| Memory format change | None (protocol uses abstract) | No action |

---

## §4 Major Upgrade (v0.x → v1.0)

**Definition:** Breaking change release. Requires full compatibility review.

### Procedure

```text
PRE-CHECK
├─ Same as minor upgrade, PLUS:
├─ Read full migration guide from OpenClaw
├─ Review COMPATIBILITY-STRATEGY.md §A (Surface Map)
├─ Review version-contract.md §3 (Required Interfaces)
├─ Review version-contract.md §4 (Forbidden Interfaces)
└─ Create recovery branch: git checkout -b upgrade/v1.0-prep

MIGRATION
├─ Phase 1: Update tool references
│   ├─ Update all tool name references in AGENTS.md
│   ├─ Update guard-memory-backend.mjs string comparisons
│   └─ Run: node scripts/upgrade-test.mjs
│
├─ Phase 2: Update cron integration
│   ├─ List current cron jobs: cron(action="list")
│   ├─ Remove all: cron(action="remove", ...)
│   ├─ Re-register with new format
│   └─ Verify: cron(action="list")
│
├─ Phase 3: Update runtime if needed
│   ├─ Check if runtime.mjs still compiles
│   ├─ Check src/agent-runtime/* imports
│   └─ Update import paths if needed
│
├─ Phase 4: Run full verification
│   ├─ node scripts/upgrade-test.mjs   ← must PASS all
│   ├─ node scripts/audit-all.mjs      ← 0 FAIL, baseline WARN
│   └─ Manual walkthrough of one complex task
│
└─ git commit -m "chore: migrate to OpenClaw v1.0"

VERIFICATION
├─ Same as minor, PLUS:
├─ Verify all 3 protocol layers are self-consistent
├─ Verify audit-report.md generates correctly
└─ Mark tested version in version-contract.md §1

ROLLBACK
├─ git checkout main (pre-upgrade branch)
├─ Restore .openclaw/cron/ from git backup
├─ openclaw restart
└─ Note: Any data created during v1.0 may be incompatible
```

### Major Upgrade Risk Areas

| Area | Breakage Likelihood | Recovery Difficulty |
|------|---------------------|---------------------|
| Tool names | MEDIUM (known to be stable) | LOW (5 refs to update) |
| Cron format | LOW | LOW (re-register) |
| Session context | LOW (not relied upon) | NONE |
| runtime.mjs imports | MEDIUM | MEDIUM (port to new API) |
| LLM behavior changes | MEDIUM (prompt sensitivity) | LOW (adjust prompts) |

---

## §5 OpenClaw Deprecation / Self-Host Mode

**Definition:** OpenClaw core is no longer available or maintained.

### Procedure

```text
PRE-CHECK
├─ Read SELF-HOSTING READINESS in COMPATIBILITY-STRATEGY.md §G
├─ Score is 80/100 — protocol layer is portable
└─ Identify which features to maintain vs drop

MIGRATION OPTIONS
├─ Option A: Replace with basic CLI
│   ├─ Audit scripts run via: node scripts/audit-all.mjs (STILL WORKS)
│   ├─ Protocol docs are static markdown (readable anywhere)
│   └─ Lost: memory_search, ctx_search, cron-Triggered Dream Cycle
│
├─ Option B: Replace with custom agent runtime
│   ├─ Build minimal tool executor (5-10 tools)
│   ├─ Use system cron or launchd for Dream Cycle
│   ├─ Use grep/ripgrep + sqlite for memory search (reduced capability)
│   └─ Keep: all protocol docs, audit scripts, templates
│
└─ Option C: Hybrid
    ├─ Keep protocol docs and audit scripts
    ├─ Replace only cron + memory with POSIX equivalents
    └─ Import protocol docs into new toolchain

SELF-HOSTED VERIFICATION
├─ node scripts/upgrade-test.mjs   ← all PASS (no OpenClaw dep!)
├─ node scripts/audit-all.mjs      ← all PASS
└─ Manual: verify cron/launchd triggers Dream Cycle
```

---

## §6 Upgrade History Log

| Date | From | To | Type | Changed Files | Duration | Issues |
|------|------|----|------|---------------|----------|--------|
| — | — | — | — | — | — | — |

*(Populate on each upgrade)*