/hermit-evolve

name: hermit-evolve
description: Evolves hermit configuration and templates after a plugin update. Detects version gaps and runs the upgrade (migrations, templates, new settings) in an isolated subagent. Run after updating the plugin.

Evolve Hermit

Upgrade the project's hermit configuration after a plugin update.

Commands

• `evolve-adopt`: `bun ${CLAUDE_PLUGIN_ROOT}/scripts/evolve-plan.ts .hermit adopt`
• `evolve-apply`: `bun ${CLAUDE_PLUGIN_ROOT}/scripts/evolve-plan.ts .hermit apply`
• `leftover-check`: `bun ${CLAUDE_PLUGIN_ROOT}/scripts/evolve-plan.ts .hermit leftover-check`

Execution routing

Every run of this skill (interactive or unattended) delegates steps 0–9 to the `hermitd:evolve-runner` subagent, so the upgrade's transient churn (changelog slice, migration execution, file diffs) never lands in the calling session. The main loop keeps only step 10 (summary + operator notification).

> **Tool note:** `hermitd:evolve-runner` is a **subagent** — invoke it via the Agent tool, never the Skill tool. The `plugin:name` form it shares with skills does not imply the Skill tool.

• **If you are running AS the `evolve-runner` subagent**, skip this section and execute steps 0–9 directly (you are the delegate — do not re-dispatch).
• **Otherwise (main loop, any mode):**

1. **Determine execution and delivery separately** and remember both for step 10:

• Positional argument `unattended` ⇒ execution *unattended*, delivery *automated-maintainer*.
• No `unattended` argument + an inbound `<channel source="...">` tag ⇒ execution *unattended*

(never block on `AskUserQuestion`), delivery *direct-channel-reply*.

• Otherwise ⇒ execution *interactive*, delivery *inline*.

Only the explicit `unattended` argument authorizes a proactive maintainer notification. A direct channel request must answer the channel that invoked it. 2. **Check the runner reference:** run `test -f "${CLAUDE_PLUGIN_ROOT}/skills/hermit-evolve/reference.md"`. If it fails, **abort** — log `"hermit-evolve aborted: plugin root unresolved; cannot dispatch evolve-runner."` and stop. Do not dispatch with a broken path. 3. **Record `<now>`** for step 10 as the current UTC time (`date -u +%FT%TZ`), then **dispatch** the `hermitd:evolve-runner` subagent via the Agent tool. Pass the report contract (below); the runner body supplies its own plugin root and Commands entries. Do **not** execute steps 0–9 yourself. 4. **Go to step 10** with the subagent's returned report.

Delegated mode

Steps 0–9 (in `reference.md`, read only by the `evolve-runner` subagent) are executed with no `AskUserQuestion` — the subagent cannot pause to ask. Each step's **"Delegated mode:"** note states the non-interactive behavior. The rule in every case: never guess on a destructive choice, never block.

• For any interactive choice with a safe non-destructive default (new settings, file deletions, `## Plan` strip, template conflicts, an `### Upgrade Instructions` step that names a single non-destructive command such as `deny ask-only`), take the default silently and report the outcome.
• For a genuine either/or with **no safe default** (an `### Upgrade Instructions` migration step in 2b/7 that poses a choice and names no default), **defer**: skip that step and record a verbatim deferred-migration block in the report (see the report contract in step 10). Never guess. Step 10 resolves it — interactive asks the operator; direct-channel and automated-maintainer execution relay it through their respective delivery routes. Never apply a deferred instruction that would write `.claude/settings*.json` from a channel session.

10. Report

After a successful upgrade, arm `/hermitd:later add 1d "doctor has no new failures after upgrading to <version>" | .hermit/bin/hermitd-run doctor-check .hermit --verdict --since <now>` (hermit origin, `--timeout-s 120`: the doctor run probes credentials and docker and gets the same budget as its routine). `<now>` is the time recorded before dispatch, so a failure that already existed before the upgrade does not count against it while one first seen during the runner's steps still does. The resolver form survives the next plugin update; a baked plugin path points at a cache directory that may be gone by the time the claim is checked.

**Step 10 runs in the main loop** (not the subagent), consuming the `evolve-runner`'s returned report. The subagent's report is the single source for what follows.

Build the Templates, Bin wrappers, Docker entrypoint and Docker templates lines from the runner's `evolve-apply` JSON receipt plus its completed `remaining` resolutions. A parked file is not a merged file.

**Report contract** — the subagent's final message is exactly this; non-deferred runs carry no deferred block, so the common payload is tiny:

Upgrade: vOLD -> vNEW | core current vNEW | blocked: <reason>
Settings added: <keys | none>
Templates: <refreshed/restored/kept-N/conflicts-parked-N | none>
Bin wrappers: <restored/replaced(.bak) | none>
Docker entrypoint: <refreshed | conflict-replaced(<backup path>) | migrated(<N> moved, <M> in <patch path>) | n/a>
Docker templates: <name merged(3-way[; reviewed[, n lines fixed] | ; n conflicts resolved]) | kept(bootstrap, upstream not merged: <path>) | conflict(<n | review | reason>): upstream copy at <path>; ... | report-only(<names>) | none>
Docker rebuild: <needed + order | base-patched | no>
Sibling hermits: <one or more of the following per sibling, space-separated, or "none">
  <name vOLD->vNEW>           (confirmed by finalizer — only from siblings_confirmed)
  <name current>              (no version gap)
  <name path-unresolved>      (in _hermit_versions but no project-effective plugin-list match)
  <name SKIPPED-by-finalizer> (finalizer's siblings_skipped — never report as upgraded)
Siblings detected but not activated: <name ... | none>
Siblings warnings: <one line per siblings_warnings entry | none>
Permissions added: <entries |