Zero-Downtime Cutover (Default for Critical Services)

Scope

• In-scope: critical service refactor/update with zero-downtime + auto-rollback guard.
• Out-of-scope: destructive/live mutation without shadow verify/rollback.

SOP

1. Determine whether the request is within the skill scope.
2. Execute the skill's main workflow/instructions in safe order.
3. Check results, state validation, and next steps.

Indexed Reference Map

• @[SKILL.md#L1-L97] Standard frontmatter (name, description).
• @[SKILL.md#L6-L97] Zero-Downtime Cutover (Default for Critical Services).
• @[SKILL.md#L8-L97] When to use (mandatory).
• @[SKILL.md#L15-L97] Goals.
• @[SKILL.md#L21-L97] Mandatory process (10 steps).
• @[SKILL.md#L46-L97] Hard guardrails.
• @[SKILL.md#L51-L97] Default stop-loss.
• @[SKILL.md#L56-L97] Required output.
• @[SKILL.md#L62-L97] References.

Supporting files

• @[references/cutover-checklist.md#L1-L22] Reference/rulebook for technical decisions.
• @[templates/guard.sh.template#L1-L28] Template used to scaffold/patch quickly.
• @[templates/rollback.sh.template#L1-L24] Template used to scaffold/patch quickly.

When to use (mandatory)

Use this skill before any change to critical services that can break model paths or gateway connectivity:

• cli-proxy-api
• openclaw gateway
• background services that provide API/model routes to agent/session
• plugin/hook/config changes that can cause gateway boot failure (plugin path, plugin schema, loadPaths, entries)

Goals

1. Do not touch live files directly at the start.
2. Have rollback script armed before cutover.
3. Have guard process to monitor health and auto-rollback on failure.
4. Atomic switch + minimal downtime.

Mandatory process (10 steps)

1. Backup + checksum current runtime/module.
2. Stage .new files in parallel (*.new), do not overwrite live files.
3. Preflight plugin/config path (no restart):
   • verify required files exist (openclaw.plugin.json, package.json, index.js)
   • verify plugins.loadPaths does not point to deleted path
4. Shadow test with proved filesystem isolation:
   • do not rely on --profile alone for external plugin shadow installs
   • use a dedicated shadow home/staging root when plugin install/discovery paths matter
   • verify the resolved install/discovery path stays inside the shadow root
   • proceed only when shadow is clean and isolation is proved
5. Validate before cutover:
   • sh -n / syntax check
   • path/permission
   • dependency checks
6. Pre-arm rollback script:
   • restore file backup
   • restart old service
   • verify health endpoint
7. Start guard watcher (60-120s):
   • poll health
   • fail N consecutive times => auto rollback
8. Atomic switch (mv file .new -> live).
9. Single restart + health verify immediately after switch.
10. Disarm guard once health is stable; write report.

Hard guardrails

• Do not refactor as “tear down and rebuild” while service is alive.
• Do not change live binary/config before arming rollback.
• If health does not come up in stop-loss window -> rollback immediately.

Default stop-loss

• Probe interval: 3-5s
• Consecutive fail threshold: 3
• Total guard window: 60-120s

Required output

• cutover plan
• rollback path
• health evidence (before/after)
• verdict: PASS or ROLLED_BACK

References

• references/cutover-checklist.md
• templates/rollback.sh.template
• templates/guard.sh.template

Trigger Rules

• Positive: Activate when user request matches zero-downtime-cutover by description: Standardize refactor/update of critical services (especially model-path like cli-proxy-api/openclaw) with Zero-Downtime + Auto-Rollback Guard to avoid lost connectivity and hung session.
• Negative: Do not activate for out-of-scope requests or when this skill's workflow/expertise is not needed.
• Escalation: If there is external action/network write or sensitive operations, add an approval checkpoint before execution.

Output Contract

• Deliverable: result aligned with zero-downtime-cutover objective; clearly state artifact/path/steps performed (if any).
• Validation: report PASS/FAIL status with key checks run.
• Failure mode: when failing, state root cause + proposed remediation.

Error Handling

• If missing input/permissions: state what is missing and request clear additions.
• If runtime/tool errors: return short error + possible cause + proposed remediation.
• If policy/safety risk exists: stop and escalate via approval checkpoint.