feat(skill_manager): honor metadata.hermes.locked frontmatter flag

[unimatrix27]

Summary

Adds _locked_guard() as the edit-side counterpart to _pinned_guard(). A skill opts in by setting metadata.hermes.locked: true in its SKILL.md frontmatter; subsequent skill_manage write actions (edit, patch, delete, write_file, remove_file) are refused with a message instructing the user — not the agent — to lift the lock by hand. Read actions are unaffected.

The default behaviour (no flag, or locked: false) is preserved exactly.

_pinned_guard  blocks: delete
               opt-in: `hermes curator pin <name>`
_locked_guard  blocks: edit, patch, delete, write_file, remove_file
               opt-in: `metadata.hermes.locked: true` in SKILL.md

Motivation

The background self-improvement loop (_spawn_background_review) plus the in-conversation skill_manage schema (which actively encourages patching during the run) can silently rewrite any user skill. For skills that gate real-world side effects — financial transfers, device control, message dispatch — silent drift is unsafe. This was filed previously as #20273 (background-review + curator overwriting bundled/hub skills) and the user-facing concern is the same as in #17583 (no distinction between "user authored, do not touch" and "agent generated, fair game").

A concrete failure mode I hit while building a Mode-B style stub skill: between two runs, the SKILL.md was rewritten by the agent to match the latest cron prompt's overrides — the city changed, the data source changed, the deterministic side-effect script was deleted from the workflow, and a new hard rule "no device control, ever, in this skill version" appeared. Nothing was logged beyond a single 💾 Skill patched line. The next run executed the rewritten version as if it were the user's design.

That is exactly the drift pattern this flag prevents.

Why this PR is compatible with the wontfix reasoning on #21315

#21315 proposed skills.evolution_mode = auto|confirm|readonly. It was closed (NOT_PLANNED) on three grounds:

1. No new UX surface needed — every mutation already goes through skills_guard and the curator takes snapshots that can be rolled back from.
2. readonly disables a headline feature — making self-improvement gateable globally is "fighting the product, not extending it."
3. Precision over gating — bad patches should be fixed by improving the reviewer's heuristics, not by asking the user to triage every patch.

This PR is deliberately a much smaller change shaped to fit those constraints:

• No new UX surface. No pending queue, no /skills review slash command, no diff prompts, no platform confirm/reject flow. The lock is a single frontmatter boolean checked at the existing tool boundary.
• Does not disable the self-improvement loop. The default behaviour is unchanged; 99% of skills remain mutable. Lock is opt-in per skill, intended for the rare ones that gate side effects the user cannot afford to have rewritten.
• Does not ask the user to triage every patch. The user authors the lock once when they create the sensitive skill. There is no per-run interaction, no notification queue, no review backlog.
• Symmetric with an existing mechanism. _pinned_guard already guards deletes via the same shape (advisory check, opt-in per skill, fails open on broken metadata). This adds the missing edit-side counterpart that Pin should protect against deletion, not prevent edits #18354 essentially argued for ("two different concerns that should not be conflated"). Where Pin should protect against deletion, not prevent edits #18354 wanted pin split into delete-protection + edit-protection, this PR keeps pin as-is and introduces lock as the separate edit-protection axis.

It also addresses #20273's narrower bug surface for user-authored skills: a locked skill cannot be silently rewritten by the background-review agent even when it passes the security guard. (Bundled-skill protection per PR #19379 is orthogonal; this PR does not touch that path.)

What this PR deliberately does NOT do

• Does not add a config-level kill switch for the background reviewer (per [Feature]: Add skills.evolution_mode — confirmation gate for autonomous skill evolution #21315's Support passing morph snapshot id #2).
• Does not add cryptographic provenance for skill mutations (out of scope; see Receipts for self-improving agents: proving which skill version produced which output #11692 for that conversation).
• Does not change pin semantics. Pin still means delete-protection only.
• Does not change _create_skill. create cannot target an existing skill so there is nothing to protect at create-time; the newly-created skill IS subject to the lock once it exists.

Implementation

1. New _locked_guard(name) in tools/skill_manager_tool.py, placed next to _pinned_guard for visible symmetry. Reads the target skill's SKILL.md frontmatter via the existing agent.skill_utils.parse_frontmatter helper; checks metadata.hermes.locked is True.
2. One dispatch hook in skill_manage() before the action handlers run, gating the five write actions.
3. Schema docstring updated alongside the existing "Pinned skills are protected from deletion" paragraph so the agent knows what to expect when a write is refused.
4. Fails open on missing or unparseable frontmatter — mirrors _pinned_guard's broken-sidecar handling. A corrupted file should never trap the agent.

Net diff: +229 / -1 across two files. The non-test portion is +72 / -1 in skill_manager_tool.py: the function (~40 lines), the dispatch hook (5 lines), the schema-doc update (8 lines), plus blank lines.

Tests

tests/tools/test_skill_manager_tool.py::TestLockedGuard — 9 cases mirroring TestPinnedGuard's structure:

• One refusal test per blocked action (edit, patch, delete, write_file, remove_file).
• test_unlocked_skills_still_editable — sanity check that only the explicitly-locked skill is refused; siblings work.
• test_locked_false_does_not_block — explicit locked: false behaves identically to omitting the flag.
• test_create_is_exempt_but_subsequent_edits_blocked — create-time bypass + post-create lock enforcement.
• test_broken_frontmatter_fails_open — unparseable YAML does not falsely trigger the lock.

All 95 tests in test_skill_manager_tool.py pass locally (8 existing pin tests + 9 new lock tests + 78 unrelated). No existing test was modified.

Related

• [Feature]: Add skills.evolution_mode — confirmation gate for autonomous skill evolution #21315 — RFC (closed wontfix). Same concern, larger surface. This PR is the smallest change I could shape to address the underlying problem while staying compatible with the maintainers' three objections.
• [Bug]: Background review agent and curator can overwrite bundled/hub skills via skill_manage #20273 — Bug report on background-review writing bundled skills. Lock addresses the user-authored-skill side of the same surface (bundled is PR fix(security): add code-level guard against modifying bundled/hub skills via skill_manage #19379's territory).
• Skills: user-locked vs self-improving tiers + user-feedback-driven skill updates #17583 — Earlier RFC for user-locked vs self-improving tiers. Same conceptual split; this PR implements only the per-skill opt-in lock, no global tier system.
• Pin should protect against deletion, not prevent edits #18354 — Argued pin should split into delete-protection + edit-protection. This PR resolves the underlying tension by adding lock as the edit-protection axis rather than splitting pin.

Test plan

• pytest tests/tools/test_skill_manager_tool.py::TestLockedGuard passes (9/9).
• pytest tests/tools/test_skill_manager_tool.py::TestPinnedGuard still passes (8/8) — no regression in the existing guard.
• pytest tests/tools/test_skill_manager_tool.py full file passes (95/95).
• Manual smoke test: add metadata.hermes.locked: true to a real skill and attempt patch from a chat session — expect refusal.