Plugin Cutover Guardian

Indexed Reference Map

• @[SKILL.md#L1-L84] Frontmatter + trigger rules + SOP + output contract
• @[references/INDEX.md#L1-L17] Reading order and document map
• @[references/QUICK_REFERENCE.md#L1-L41] Decision map and fast checklist
• @[references/CORE_API.md#L1-L51] OpenClaw plugin config semantics relevant to cutover
• @[references/PATTERNS.md#L1-L73] Safe patterns and anti-patterns
• @[references/EXAMPLES.md#L1-L73] Example flows including invalid-isolation cleanup and rollback
• @[references/STATE_MANIFEST_EXAMPLE.md#L1-L63] Attempt-state manifest schema/example for shadow verification and cleanup
• @[references/AI_WORKFLOW.md#L1-L42] AI execution workflow and verification discipline

Scope

• In-scope: external plugin update/cutover, npm install provenance, shadow/live compare, backup-first swap, post-cutover verification, duplicate plugin id cleanup, rollback planning.
• Out-of-scope: authoring plugin source code, upstream bugfixing plugin internals, destructive system service changes, unverified network writes beyond the requested plugin update flow.

Reading Order

1. references/INDEX.md
2. references/QUICK_REFERENCE.md
3. references/CORE_API.md
4. references/PATTERNS.md
5. references/EXAMPLES.md
6. references/STATE_MANIFEST_EXAMPLE.md
7. references/AI_WORKFLOW.md

Coverage Matrix

• Config semantics (plugins.entries / plugins.installs / plugins.slots) -> references/CORE_API.md
• Safe cutover path -> references/QUICK_REFERENCE.md, references/PATTERNS.md
• Known failure classes -> references/PATTERNS.md, references/EXAMPLES.md
• AI execution and verification discipline -> references/AI_WORKFLOW.md
• Gaps: plugin-specific upstream API details must still be verified from local OpenClaw docs or the plugin package itself.

Hard Rules

• Workspace ops artifacts must use taxonomy .ops/*:
  • rollback assets -> workspace/.ops/backups/
  • shadow candidates -> workspace/.ops/staging/
  • temp scripts/json/shims -> workspace/.ops/tmp/
  • manifests/checkpoints -> workspace/.ops/state/
• Do not create ad hoc namespaces like .backup, .backups, .tmp-bin in the new workflow.
• On Android module hosts, lifecycle/service verify must prioritize local contract (openclaw.service ...) when restarting/status is required; Only use openclaw gateway ... when it does not conflict with the local wrapper contract.
• Backup/plugin copies cannot be in the extension scan path if there is an entrypoint.

Trigger Rules

• Positive: Use when user asks to update/install/cut over an OpenClaw plugin and reliability matters; when a plugin shadow install already exists and needs promotion; when fixing duplicate plugin id warnings caused by backup dirs in scan paths; when patching plugins.installs safely.
• Negative: Do not use for ordinary config reads, bundled plugin toggles without install provenance, or unrelated shell-quoting issues outside plugin cutover context.
• Escalation: If the flow requires external publication, credential mutation, system-level service changes, or deleting the only good live copy without backup, stop and require explicit approval.

SOP

1. Inspect current live state: plugins info <id>, local service/gateway health, relevant plugins.entries / plugins.installs / plugins.slots.
2. Verify target version/source before touching live state.
3. Run schema-required preflight for the target plugin:
   • if plugin schema has required config keys (especially memory plugins with required embedding), prepare a minimal valid shadow config payload before expecting install-persist to pass.
4. Prepare the shadow candidate under workspace/.ops/staging/<task-id>/ using a dedicated shadow home; for plugin cutover, prefer explicit HOME + OPENCLAW_HOME isolation over --profile-only isolation.
5. Prove shadow isolation before accepting the candidate: verify the resolved plugin install path and discovery root stay inside the dedicated shadow home.
6. If the resolved install path touches the live extension root, classify the attempt as invalid-isolation, clean/quarantine the partial shadow artifact immediately, and stop that shadow path.
7. Create rollback assets first: backup config + live plugin dir under workspace/.ops/backups/<task-id>/, always outside plugin scan roots.
8. Patch install provenance safely using a temp script/file under workspace/.ops/tmp/<task-id>/; avoid complex inline Python inside nested shell quoting.
9. Record every shadow attempt and cleanup outcome under workspace/.ops/state/<task-id>/, including shadow method, resolved install path, verdict, and cleanup status.
10. Perform atomic switch (.new -> live) with at most one planned restart/apply.
11. Verify immediately: plugins info <id>, local service/gateway health, runtime warnings, and duplicate plugin id absence.
12. Report dual verdicts for clarity:

• runtime_functional: PASS|PARTIAL|FAIL
• install_provenance: PASS|WARN|FAIL

13. If a backup dir remains under ~/.openclaw/extensions, move it out of scan path at once.
14. If verification fails, restore config/plugin dir from backup and re-verify.
15. Report final compliance verdict as PASS/WARN/ROLLBACK with concrete evidence.

Error Handling

• Shell quoting / inline Python patch fails: stop, preserve current live state, switch to temp script or temp JSON patch file under workspace/.ops/tmp/, then retry.
• Required-config install-persist failure (example: must have required property 'embedding'): treat as a schema-preflight miss; apply minimal valid config in shadow, then re-run install/verify lane.
• Repeating config-warning loops or stack overflow (Maximum call stack size exceeded): stop retry loop immediately, capture logs/evidence, classify attempt as blocked-installer-flow, and do not continue blind retries.
• Duplicate plugin id warning after cutover: inspect for backup dirs like .prev under plugin scan path; move them to workspace/.ops/backups/ or workspace/.ops/trash/ and re-verify.
• plugins info version mismatch after cutover: check plugins.installs record, install path, and whether live dir actually switched.
• Gateway/RPC probe fail after cutover: rollback immediately using pre-created backups, then inspect logs before another attempt.
• Profile-only shadow attempt leaves ~/.openclaw-<profile> behind: treat it as an incomplete artifact; either remove it or quarantine it into workspace/.ops/trash/<task-id>/ before concluding.
• Isolation proof mismatch: if shadow metadata/config looks isolated but the resolved plugin install path still touches live ~/.openclaw/extensions, classify the attempt as invalid-isolation, stop, clean up, and do not count it as shadow verification.

Output Contract

• Artifact: cutover plan, backup/staging/state locations, changed config keys/paths, verification evidence, rollback path.
• Validation: live plugin version/source matches target, local runtime health ok, no duplicate plugin id warning from backup scan-path mistakes.
• Mandatory dual-verdict fields:
  • runtime_functional: PASS|PARTIAL|FAIL
  • install_provenance: PASS|WARN|FAIL
• Compliance Verdict: PASS / WARN / ROLLBACK with explicit cause.