Essay 7.8 — The Plugin Kit, Part 8 of 9.

Essay 7.7 closed the kit’s anatomy — the smaller organs that round out specialized plugins, and the brain-root wiring file that decides which hooks ever fire. With every organ named, one question is left: how does any of this get edited safely once the plugins are alive? Cell walls, dual voices, hidden state, evolution narratives — every organ is also a surface that, mishandled, can corrupt the plugin or the agent’s whole enforcement layer. This sub-essay opens the ceremony that protects every edit.

The Parts of the Ceremony

Plugin code does not get edited the way ordinary files do. Each plugin’s hooks, scripts, tests, and code-bearing files have earned their current shape; the test suite enshrines that shape; any change pays the cost of opening the plugin, editing inside it, and re-passing the tests before the change commits. ⓘ

The parts of the ceremony form a closed loop: PLUGIN-LOCK opens an edit session, TEST-LOCK gates test edits inside it, safe-lock close-out commits or reverts on the test result, and the historian ratchet can refuse to open the lock at all when the plugin’s narrative has fallen behind. Each part guards a different risk; together they make plugin edits earn their landing.

[PLUGIN-LOCK] — Opens an Edit Session

The agent issues a structured AskUserQuestion prefixed [PLUGIN-LOCK] <plugin_name> with a body long enough to surface the cognitive work (currently a 100-word floor in the prototype, configurable) explaining what flaw is being fixed, what files will be touched, and what the plugin’s behavior will look like before vs after the edit. The operator approves; lock-manager.sh captures a git rev-parse HEAD SHA as checkpoint_ref and writes the unlocked plugin name into plugin_integrity's hidden data.json. From that moment, edits inside the unlocked plugin proceed; edits anywhere else under .claude/plugins/ are rejected. ⓘ

Two protected contexts for existing-plugin edits. Editing an existing plugin requires one of two protected contexts: (A) [GMODE] with a body long enough to surface the cognitive work (currently a 100-word floor in the prototype, configurable) — the operator’s deliberate maintenance lane; or (B) a focused job whose completion_requirements.plugin_lock_approval flag is set — established by the user confirming an agent-proposed [JOB-APPROVE-CREATION] question. New-plugin creation bypasses this gate: birth happens inside an OPEVC cycle’s EXECUTE phase because the new plugin’s code is being authored, not modified. The asymmetry codifies a real distinction — editing existing plugin code alters the agent’s own enforcement substrate, which is meta-cognitive work that needs explicit user authorization (either ambient via gmode, or scope-bounded via an approved job). ⓘ

[TEST-LOCK] — A Finer-Grained Sub-Session

By default, the unlocked plugin’s tests/ directory is frozen even inside the unlocked plugin. To edit a specific test-*.sh file, the agent issues [TEST-LOCK] <test_file>. The reason: it is too easy to silently rewrite a correctly-failing test to make a broken change look passing. Test edits demand explicit, named permission. ⓘ

Two-tier lock — PLUGIN-LOCK opens the cell; TEST-LOCK opens a specific test file inside the cell. The agent never gets a blanket "all tests editable while the plugin is unlocked" pass. Each test file the change touches earns its own ceremony. ⓘ

Safe-Lock Close-Out — Pass or Revert

Two scripts share the close-out duty. The agent invokes lock-cmd.sh when edits are done — the active path: the plugin’s full test suite runs at the lock boundary; on PASS the change commits and the lock clears; on FAIL the failures surface to stderr and the working tree is preserved (no revert) so the agent can fix and re-run. The defensive partner is safe-lock.sh, which fires automatically when the agent attempts a non-whitelisted operation while a plugin is unlocked — editing outside the plugin’s directory, transitioning phases, finalizing a job: on FAIL the working tree rolls back to the captured checkpoint_ref, the plugin’s hidden state records a structured revert entry, and a voice line writes to the operator’s terminal. The agent does not get to ship a plugin change that breaks the plugin’s own self-test. ⓘ

The cycle is symmetric to PLUGIN-LOCK: every lock opened gets closed by one of the two mechanisms above, with the test suite as the gate. There is no inline override; the deliberate [GMODE] route covered above (plus the user-approved-job route) are the only ways to admit an existing-plugin edit, and both leave an auditable trail. There is no "commit anyway"; there is no "I will fix it next session." Either the active-lock cycle leaves the agent looking at preserved failures it now has to fix, or the auto-revert cycle removes the broken edit from the working tree entirely. ⓘ

Image pending — The safe-lock cycle’s pass-or-revert branch
Prompt: ASSET: images/lock-ceremony-b7-8.png Style: Match opevc-cycle-blackboard.png exactly. Dark slate chalkboard background; hand-drawn chalk boxes and arrows; pastel chalk for box fills (cyan, green, orange, pink, magenta — same palette as the cycle image); white chalk for ALL labels and arrows; faint chalk dust at the edges; chalk sticks resting along the bottom. IMPORTANT: Use only the literal text strings listed below. Do not invent or substitute any other state names, command names, or descriptors. Layout: Five hand-drawn chalk boxes arranged in a vertical flow down the center of the board, each labeled IN WHITE CHALK with its exact text: Box 1 (cyan fill, top): "[PLUGIN-LOCK] approved" Box 2 (green fill): "edits inside unlocked plugin only" Box 3 (orange fill): "lock-cmd.sh OR safe-lock.sh fires" Box 4 (pink fill): "run plugin test suite" Box 5 (no fill, decision diamond drawn as a chalk rhombus): "all tests pass?" Single white-chalk arrows connect Box 1 → Box 2 → Box 3 → Box 4 → Box 5. From Box 5, two arrows fan out to two terminal boxes side-by-side at the bottom: Left arrow labeled IN WHITE CHALK exactly "yes" → magenta box labeled "commit + clear unlocked_plugin" Right arrow labeled IN WHITE CHALK exactly "no" → orange box (warmer chalk) labeled "revert to checkpoint_ref + log revert" Below the two terminal boxes, draw a small chalk note IN WHITE CHALK reading exactly: "no override". Keep every line hand-drawn and slightly imperfect, never ruler-straight. STRICT NAME WHITELIST — the image must contain only these literal text strings as labels: "[PLUGIN-LOCK] approved", "edits inside unlocked plugin only", "lock-cmd.sh OR safe-lock.sh fires", "run plugin test suite", "all tests pass?", "yes", "no", "commit + clear unlocked_plugin", "revert to checkpoint_ref + log revert", "no override", plus the caption below. No other words, file names, folders, or state descriptors may appear.
Image 7.8. Test pass-or-revert. Every plugin edit passes through the same gate.

The Historian Ratchet — Refuses the Lock

The lock can be refused before it opens. Each plugin keeps the 2000-word-capped docs/evolution.md narrative covered in Essay 7.5; drift-check.sh counts commits landed against the plugin since evolution.md was last touched. If drift exceeds threshold, lock-manager.sh rejects the [PLUGIN-LOCK] approval and tells the agent to dispatch the plugin’s historian subagent first. The historian re-narrates the cycles since last sync, commits the refreshed evolution.md, and the drift counter resets. Only then does the lock open. A plugin cannot be edited indefinitely without periodically forcing its own history to be re-told. ⓘ

A Closed Loop — The Only Way to Evolve a Plugin Is to Have Already Understood It

PLUGIN-LOCK gates the operator-approved entry. TEST-LOCK forces deliberate test edits. Safe-lock makes every commit conditional on tests passing or reverts the working tree. The historian ratchet refuses unlock when the plugin’s narrative has fallen behind.

Each part, a risk closed: - An edit landing without operator approval (closed by PLUGIN-LOCK). - A correctly-failing test silently rewritten to mask a broken change (closed by TEST-LOCK). - A change committing despite a failing test (closed by safe-lock). - A plugin getting edited without anyone re-reading the cycles that produced its current shape (closed by the historian ratchet).

Plugin_integrity itself follows the same ceremony when its own hooks are edited — there is no privileged path. The plugin that enforces the ceremony submits to it. That is what makes the ceremony credible: it is not enforcement that lives outside the system; it is enforcement built into the same cell membrane every other plugin lives behind. ⓘ

A research lab’s seed could install the same ceremony around an experiment-protocol plugin — [PROTOCOL-LOCK] opens the edit session; [REVIEWER-LOCK] gates changes to the validator tests; the safe-lock cycle reverts if the IRB-checklist tests fail; the historian ratchet forces re-narration of the protocol’s evolution before another edit lands.

The ceremony is the safety rail. The next sub-essay puts it on the track — a walkthrough of what guiding your seed to create a brand-new plugin actually looks like in motion, with every lock fired in the order the plugin needs it.

Essay 7.8 — The Plugin Kit, Part 8 of 9.

Previous: Essay 7.7 — Smaller Organs and Brain-Root Wiring — config, tests, template, e2e, and the wiring file that lives outside every cell wall. Next: Essay 7.9 — Building a New Plugin — the tier-3 walkthrough; the lock ceremony exercised through a real birth.