Edit Tool Compat Guard

Indexed Reference Map

• @[SKILL.md#L1-L116] Frontmatter, scope, trigger rules, SOP, retirement contract.
• @[references/INDEX.md#L1-L17] Reading order and document inventory.
• @[references/QUICK_REFERENCE.md#L1-L34] Fast decision checklist and do/don't rules.
• @[references/CORE_API.md#L1-L57] Runtime contract, affected-version gating, and fallback policy.
• @[references/PATTERNS.md#L1-L43] Canonical payload patterns, retry discipline, and escalation rules.
• @[references/EXAMPLES.md#L1-L49] Good/bad payload examples and reporting examples.
• @[references/AI_WORKFLOW.md#L1-L17] Operational sequence for future models.
• @[references/RETIREMENT_CHECKLIST.md#L1-L16] Short gate for removing/deactivating the skill after runtime fix verification.

Scope

• In-scope:
  • Guarding edit tool usage when runtime wrapper behavior may diverge from core tool contract.
  • Preventing mixed semantic payloads (edits[] plus top-level oldText/newText).
  • Choosing fallback to read + write when edit reliability is uncertain.
  • Version-aware retirement when the runtime/upstream fix is verified.
• Out-of-scope:
  • Changing the core edit contract.
  • Silently hiding invalid payloads that should fail.
  • Permanent workarounds after the runtime has a verified upstream fix.

KB Mode Notes

• 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/AI_WORKFLOW.md
  7. references/RETIREMENT_CHECKLIST.md
• Coverage Matrix:
  • version gate / retirement -> references/CORE_API.md
  • canonical payload rules -> references/PATTERNS.md
  • examples -> references/EXAMPLES.md
  • execution sequence -> references/AI_WORKFLOW.md
  • retirement decision gate -> references/RETIREMENT_CHECKLIST.md
• Portability note:
  • Version markers in this skill are local operational gates for the current OpenClaw workspace; verify actual upstream/runtime behavior before porting to another host.

Trigger Rules

• Positive:
  • A task may invoke edit.
  • The user asks to fix a file with exact replacement or multiple disjoint replacements.
  • There is evidence of edit validation errors, mode-conflict errors, alias drift, or uncertain wrapper/runtime behavior.
• Negative:
  • No file mutation is needed.
  • The task uses only read or only write with full replacement and there is no edit uncertainty.
  • The runtime has already been verified to contain the upstream fix and the local retirement condition is satisfied.
• Escalation:
  • If runtime behavior is uncertain and the change is important, prefer read + write over speculative edit retries.
  • If verification cannot prove the runtime fix, keep this guard active.

SOP

1. Check whether the task intends single replacement mode or multi-edit mode.
2. Normalize the plan to the core XOR contract:
   • single replacement: path + oldText + newText
   • multi-edit: path + edits[]
3. Never mix edits[] with top-level oldText/newText in one request.
4. Prefer canonical fields (path, oldText, newText, edits) even if aliases may be accepted.
5. If the runtime is in the affected-version window or not yet verified fixed:
   • issue at most one clean edit attempt
   • if validation drifts or retries would require mixed semantics, switch to read + write
6. If edit returns a validation/mode error:
   • identify whether the first failure is wrapper validation or core validation
   • do not keep retrying the same malformed shape
   • either send one corrected canonical payload or fall back to read + write
7. When a runtime upgrade claims to fix this area, verify with a minimal repro before retiring the skill.
8. If the repro proves the fix, mark the skill for removal/retirement rather than leaving a stale workaround in the routing pool.

Error Handling

• Missing required parameters: oldText alias, newText alias on edits[]-only:
  • Treat as wrapper/runtime validation drift.
  • Retry once with a clean canonical payload only if the original payload was malformed; otherwise use read + write or verify runtime fix state.
• Use either edits or single replacement mode, not both.:
  • Treat as a semantic payload bug.
  • Remove mixed-mode fields; do not append more aliases.
• Alias uncertainty:
  • Prefer canonical fields.
  • Do not rely on alias spellings to rescue a malformed semantic payload.
• Runtime upgraded:
  • run minimal repro
  • if PASS on clean canonical single and clean canonical multi without workaround, retire the skill.

Output Contract

• Artifact:
  • chosen mutation mode (single-edit | multi-edit | fallback-read-write)
  • whether runtime is affected | verified-fixed | unknown
  • if fallback was used, why
• Validation:
  • request shape matches core XOR contract
  • no mixed semantic payload
  • retirement decision tied to actual repro evidence
• Compliance Verdict:
  • PASS when the chosen workflow respects XOR contract and version gate
  • PARTIAL when fallback was needed due to runtime uncertainty
  • FAIL when mixed semantics or repeated malformed retries were used

Retirement Condition

Retire/remove this skill when all of the following are true:

1. The active OpenClaw runtime version includes a verified upstream fix for edit wrapper validation drift.
2. Minimal repro passes for:
   • canonical single replacement
   • canonical edits[] multi-edit without local workaround logic.
3. No recent runtime/session evidence shows the old wrapper error pattern.
4. A maintainer explicitly removes or deactivates the skill after verification.