safe-update-merge_skill

Overview

This skill safely merges upstream OpenClaw updates into a fork while preserving plugin/skill injections, custom UI tabs, workspace features, and other local customizations. It orchestrates a pre-flight analysis, agent-guided conflict resolution using the configured model, build-time validation, backups with redacted secrets, and a clear report of results. The merge always runs on a dated branch and never modifies main directly.

How this skill works

First, a pre-flight step fetches upstream, computes divergence, lists conflicts, and produces a JSON report. The configured agent model resolves each conflict using a per-file merge manifest and an interactive prompt template; secrets are redacted before any content is sent to the model and restored from an in-memory map after resolution. After resolution the skill runs install/build/validation checks and scans protected files for must-preserve patterns, then commits results to a safe-merge-YYYY-MM-DD branch and reports back to the user.

When to use it

• Your fork is behind upstream and you need to incorporate changes without losing local customizations.
• Upstream has refactors that could accidentally remove injected plugins, UI tabs, or workspace controllers.
• You want automated conflict assistance but still require human/agent judgment on sensitive merges.
• You need a merge workflow that backs up redacted copies and validates builds before finalizing.

Best practices

• Run the pre-flight report and review upstream package.json diffs before allowing pnpm install.
• Execute the full merge in an isolated environment (container, VM, or disposable clone) for maximum safety.
• Provide or select the desired merge model via SAFE_MERGE_MODEL or the UI dropdown to control AI behavior.
• Keep the fd 3 redaction map protocol intact so secret redaction/restoration never writes secrets to disk or stderr.
• After the merge, run pnpm ui:build and restart the gateway service, then verify UI tabs and protected patterns.

Example use cases

• Integrating a major upstream update that adds schema strictness while preserving fork-specific schema extensions.
• Merging upstream control UI changes without losing custom tabs or CSP connect-src extensions required by local features.
• Responding to a security or bugfix release from upstream while ensuring local controllers and plugins remain intact.
• Running periodic maintenance merges where many files auto-merge but protected files still require verification.