upgrade-guardian

name	upgrade-guardian
description	A cognitive protocol for safely managing and auditing OpenClaw application upgrades. Analyzes configuration-level risks (schema, defaults) and runtime-level behavioral shifts (routing, sessions, streaming) using semantic changelog analysis to prevent silent breaking changes.

Cognitive Protocol: The Upgrade Guardian

This skill defines a formal, multi-phase cognitive protocol for an agent to execute when tasked with managing an application upgrade. Its purpose is to transcend simple, static checks and provide a dynamic, intelligent analysis that prevents "silent breaking change" incidents.

This is not a script. It is a directive for higher-order reasoning.

Core Principle

An application upgrade is a high-stakes event. The agent must not trust that the upgrade is safe. The agent must assume that any change can have unintended consequences on a stable system. The goal is to make implicit environmental assumptions explicit and resilient before they break.

Protocol Activation

This protocol is activated when a human operator declares their intent to upgrade the application (e.g., "We are planning to upgrade OpenClaw from vA to vB").

Analysis Scope

Upgrade Guardian covers two categories of risks:

1. Configuration-level risks: Changes that affect openclaw.json or static config files

   • Breaking changes in schema or validation
   • Deprecated config fields
   • New required config options
   • Default value changes

2. Runtime-level risks: Changes that affect behavior without config modifications

   • Behavioral shifts in session handling, routing, or delivery
   • Logic changes in compaction, memory, or agents
   • Protocol-level changes (streaming, API compatibility)
   • CLI UX changes (e.g., /new behavior)

See references/RISK_CATEGORIES.md for detailed taxonomy.

⛔ Hard Constraints (Read Before Doing Anything)

During Phase 1 (analysis), the working directory MUST NOT be modified.

• ✅ Allowed: git fetch --tags --prune, git log origin/main, git diff HEAD origin/main
• ❌ Forbidden: git pull, git merge, git rebase, git checkout, pnpm install

If you run git pull or git rebase during analysis, the new code becomes active on next gateway restart — bypassing the human approval gate entirely. This has happened in production (2026-03-22).

Only run git pull --ff-only after explicit human approval ("proceed" / "允许升级") in Phase 3.

Phase 1: Information Gathering & Semantic Analysis

1. Read-only git setup:

   git fetch --tags --prune   # ONLY allowed remote operation during analysis
   CURRENT=$(git describe --tags --abbrev=0 HEAD)
   LATEST=$(git tag --sort=-v:refname | grep -Ev '(beta|rc|alpha)' | head -n 1)
   # Analyze: git log HEAD..origin/main, git diff HEAD origin/main -- path
   # Do NOT run git pull/merge/rebase
   

2. Ingest Release Notes: Fetch the CHANGELOG or release notes for the target version range.
3. Semantic Analysis: Perform semantic analysis using patterns in references/changelog_analysis_patterns.md.
   • Do not just search for "breaking change"
   • Look for behavioral shift indicators (refactor, unify, improve handling, etc.)
   • Identify both config-affecting and runtime-only changes
4. Cross-Reference with Environment:
   • For config risks: Load openclaw.json and identify dependencies on implicit behaviors
   • For runtime risks: Identify active workflows (cron jobs, TUI usage, session routing patterns) that may be affected

Phase 2: Risk Assessment & Scenario Planning

2.1 Formulate "What-If" Scenarios

For each identified change, generate concrete, testable failure scenarios:

Config-level examples:

• Scenario A: "What if 'improved session handling' means a new, destructive default for unconfigured session types? → Data loss."
• Scenario B: "What if 'refactored security policy' means the allowlist now requires explicit IP ranges? → Plugin executions fail."

Runtime-level examples:

• Scenario C: "What if 'duplicate reply suppression' changes session routing logic? → Bot stops responding in some groups."
• Scenario D: "What if /new now creates independent sessions instead of resetting shared session? → User workflow disrupted."
• Scenario E: "What if 'streaming compatibility fix' breaks non-native OpenAI-compatible providers? → Long responses fail mid-stream."

2.2 Quantify Risk

Assign a risk score based on:

• Impact: data loss > service outage > UX friction > cosmetic
• Likelihood: direct config/workflow overlap > tangential relation > theoretical

2.3 Generate Audit Report

Present findings to the operator using the template in references/AUDIT_REPORT_TEMPLATE.md.

Key sections:

• Configuration risks (with jq paths and explicit mitigations)
• Runtime risks (with behavioral descriptions and verification tests)
• Risk prioritization (High/Medium/Low)

Phase 3: Mitigation & Verification

3.1 Proactive Mitigation

For config risks: Propose specific openclaw.json changes to make implicit assumptions explicit. Do not execute without operator approval.

For runtime risks: Document expected behavioral changes and suggest workflow adjustments if needed.

3.2 Verification Plan

Define clear, simple tests for each risk:

Config verification examples:

• "Run openclaw doctor and confirm no validation errors"
• "Check gateway.err.log for auth mode complaints"

Runtime verification examples:

• "Send test message in group chat, verify bot responds"
• "Open TUI, run /new, confirm it creates independent session"
• "Trigger long completion from streaming provider, verify no mid-stream failure"

3.3 Post-Upgrade Audit

After the operator confirms upgrade is complete:

1. Execute verification plan
2. Report results systematically
3. Recommend rollback if critical failures detected

3.4 Archive Upgrade Artifacts (relative to workspace)

Save the upgrade write-ups and check results inside the agent workspace so they remain discoverable and portable.

Write locations (relative paths):

• Pre-upgrade analysis report → kb/logs/upgrade-reports/YYYY-MM-DD_<from>-to-<to>_upgrade-analysis.md
• Post-upgrade verification report → kb/logs/upgrade-verifications/YYYY-MM-DD_post-upgrade-verification.txt

Notes:

• Prefer workspace-relative paths in reports (avoid hard-coded absolute home paths).
• If kb/ is a symlink in a particular deployment, still refer to it as kb/... in the protocol/report; the filesystem mapping is an implementation detail.

References

• references/changelog_analysis_patterns.md - Semantic analysis patterns
• references/RISK_CATEGORIES.md - Detailed risk taxonomy
• references/AUDIT_REPORT_TEMPLATE.md - Report structure
• references/VERIFICATION_CHECKLIST.md - Common verification tests

Notes

• This protocol is designed to be conservative. It's better to flag a false positive than miss a silent breaking change.
• Runtime risks are often harder to detect than config risks. Pay extra attention to behavioral keywords like "improve", "fix", "refactor" in areas you actively use (sessions, routing, streaming).
• When in doubt, ask the operator about their workflow patterns before deeming a risk "Low" priority.