Improvement Executor

当需要把已批准的改进候选应用到目标文件、回滚之前的变更、或预览变更效果时使用。支持 4 种 action（append/replace/insert_before/update_yaml），每次变更前自动备份。不用于打分（用 improvement-discriminator）或门禁验证（用 improvemen...

Security Scan

The skill's code, runtime instructions, and requested environment are coherent with its stated purpose (applying and rolling back low-risk document improvements); it performs filesystem modifications and backups but does not request unrelated credentials or network access.

Purpose & Capability

The name/description (apply accepted candidates, rollback, preview) matches the included scripts (execute.py, rollback.py) and tests. The actions are document-focused (append/replace/insert/update YAML frontmatter) which align with required behavior; nothing extraneous (no cloud or unrelated service credentials) is requested.

Instruction Scope

The SKILL.md CLI exactly matches the scripts and describes using a ranking artifact and candidate-id. The scripts will read and write arbitrary filesystem target paths provided in the ranking artifact (create backups first). This is expected for an executor but is high-impact: you must only run it with trusted ranking.json / candidate inputs and an appropriate state-root to avoid unintended file modifications.

Install Mechanism

Instruction-only skill with no install spec. The package includes Python scripts and tests; nothing is downloaded or extracted at install time.

Credentials

No required env vars are declared. The code does optionally read OPENCLAW_ROOT (rollback.py) to form a default DEFAULT_ROOT under the user's home if present; PyYAML is imported at runtime in update_yaml_frontmatter (falls back to an error status if missing). These implicit dependencies are reasonable but not declared in SKILL.md (minor mismatch).

Persistence & Privilege

always is false and the skill does not request permanent platform-wide privileges. It writes artifacts into a specified state-root (or default under ~/.openclaw) and does not modify other skills' configuration. Autonomous invocation is allowed by default but not unusual for a toollike skill.

Assessment

This skill is internally consistent and appears to do what it says: it applies and reverts document-style improvements by writing to files and creating backups. Before installing or running it: (1) ensure the ranking.json / candidate inputs are trusted — the script will modify whatever target path is specified; (2) choose an explicit --state-root (or verify the default ~/.openclaw path) so backups and executions are written where you expect; (3) be aware update_yaml_frontmatter requires PyYAML to actually modify frontmatter; if you plan to run rollback, note the script will look under OPENCLAW_ROOT if set; (4) review the repo's lib.common and lib.state_machine implementations in your environment (these are imported but not included here) because they control backup behavior and state updates. If any of those dependencies or inputs are untrusted, run with --dry-run first or in an isolated environment.

Applies accepted candidates with automatic backup and rollback.

When to Use

• 把已批准的改进候选应用到目标文件
• 回滚之前的变更（通过 receipt）
• 用 --dry-run 预览变更

When NOT to Use

• 给候选打分 → use improvement-discriminator
• 门禁验证 → use improvement-gate
• 全流程编排 → use improvement-orchestrator

CLI

# Apply a candidate (requires ranking artifact + candidate ID)
python3 scripts/execute.py \
  --input ranking.json \           # REQUIRED: ranking artifact from discriminator
  --candidate-id cand-01-docs \    # REQUIRED: which candidate to execute
  --state-root /path/to/state \    # default: lib/state_machine.DEFAULT_STATE_ROOT
  --output result.json \           # default: {state-root}/executions/{run-id}-{candidate-id}.json
  --force                          # execute even if recommendation != accept_for_execution

# Rollback a previous change
python3 scripts/rollback.py --receipt receipt.json [--dry-run]

Param	Default	When to change
--input	(required)	Always: path to ranking artifact JSON from discriminator
--candidate-id	(required)	Always: the id field of the candidate to execute
--force	false	Use to execute candidates with recommendation=hold (bypasses critic check)
--output	auto	Set for custom output location

4 Action Types

Action	Trigger	Behavior
append_markdown_section	execution_plan.action	Appends heading + bulleted content lines at EOF. No-op if heading already exists
replace_markdown_section	execution_plan.action	Finds section by heading match, replaces all lines until next same-or-higher-level heading
insert_before_section	execution_plan.action	Inserts content lines before a matched heading
update_yaml_frontmatter	execution_plan.action	Merges frontmatter_updates dict into YAML frontmatter (requires PyYAML)

Backup Mechanism

Every execution creates a backup at {state-root}/executions/backups/{run-id}/{candidate-id}-{filename} BEFORE modifying the target. The backup path is stored in result.rollback_pointer.backup_path for gate-driven rollback.

Safety Guards

1. Recommendation check: refuses to execute if recommendation != accept_for_execution (use --force to override)
2. Category check: only EXECUTOR_SUPPORTED_CATEGORIES (docs, reference, guardrail) are auto-executable; others return status=unsupported
3. File existence: target file must exist, otherwise SystemExit
4. Execution trace: every run captures a structured execution_trace dict with action, status, diff_summary for GEPA feedback loop

<example> 正确: 执行一个 docs 类候选 $ python3 scripts/execute.py --input ranking.json --candidate-id cand-01-docs --state-root ./state → Backup: ./state/executions/backups/run001/cand-01-docs-README.md → Appended "## Operator Notes" section → stdout: ./state/executions/run001-cand-01-docs.json </example> <anti-example> 错误: 跳过 discriminator 直接执行 medium-risk candidate $ python3 scripts/execute.py --input ranking.json --candidate-id cand-04-prompt --force → category=prompt 不在 EXECUTOR_SUPPORTED_CATEGORIES → status=unsupported → medium/high risk 必须经 gate 走 pending_promote → 人工审批 </anti-example>

Output Artifact

{"stage": "executed", "status": "success", "candidate_id": "cand-01-docs",
 "result": {"status": "success", "modified": true, "diff": "--- a/...",
   "backup_path": "...", "rollback_pointer": {"method": "restore_backup_file",
     "backup_path": "...", "target_path": "..."}},
 "execution_trace": {"type": "execution_trace", "action": "append_markdown_section", ...},
 "next_step": "apply_gate", "next_owner": "gate"}

Related Skills

• improvement-discriminator: Scores candidates → executor only runs accept_for_execution ones
• improvement-gate: Validates execution results → may trigger rollback via rollback_pointer
• improvement-orchestrator: Calls executor as stage 4, passes ranking artifact + candidate ID