Garry's Opinionated OpenClaw/Hermes Agent Brain
deprecations.d
One file per planned removal or rename of something stable promises to keep
(see What stays the same on stable):
a command, a documented flag, an MCP tool or parameter, a documented config
key, a page-format rule, an exit code or a top-level --json field.
Before you remove or rename something
Keep the old name or behaviour working, and make it print a warning that names the replacement.
Add
deprecations.d/<id>.md, with an id in the same form as a behaviour-change id (lowercase letters, digits and_, starting with a letter), for exampleold_name_flag_1234:--- surface: cli-flag name: gbrain <command> --old-name replacement: gbrain <command> --new-name owner: <who removes it> remove_after: 2026-12-07 --- One plain paragraph for users: what changes, what to use instead, and what happens if they do nothing.surfaceis one ofcli-command,cli-flag,mcp-tool,mcp-param,config-key,page-format,exit-codeorjson-field.remove_afteris at least 14 days after the stable release that first carries the announcement.bun run check:public-surfacerefuses a new record whose date is less than 14 days after the day it is added; the stable-release part is checked in review. Once a record is merged, itssurfaceandnamestay as announced andremove_aftercan only move later; to cover something else, add a new record.Announce it in the same pull request: add a behaviour-change row with the same id (
behavior-changes.d/<id>.md, see its README) so the upgrade notice carries it, and say it in your changelog fragment (changelog.d/<slug>.md) so the release notes carry it.
Removing it
The removal is a separate pull request, made after remove_after and once
the announcement has been in at least two stable releases. It deletes the old
name and the warning, keeps this file (the history of what was removed and
when) and adds a second behaviour-change row, with an id of its own, saying the
old name is gone. That row's front matter is kind: breaking and
deprecation: <id>, naming this record. Until remove_after has passed, the
check refuses a pull request that drops a command, flag, MCP tool or
parameter, config key or exit code this record names. A cli-command record
also covers that command's flags, and an mcp-tool record its parameters,
so retiring a whole command or tool takes one record. A page-format rule or
--json field is not on the check's list, so its removal is checked in
review.
Security and data-loss fixes
A fix for a security hole or for something that loses data may change
behaviour at once, with no record here. Its behaviour-change row has
kind: breaking and exception: security or exception: data-loss, and
says what users need to do. The check lets the removal through when the
pull request adds that row.
Reverts and things that never reached stable
The promise covers what is on stable. The check compares with the list at
the current stable release (the stable tag), so a command, flag, tool,
config key or exit code added since then can be removed, or reverted, with
no record here. When the clone lacks the tag, the check fetches it; in CI a
fetch that fails or takes more than 20 seconds fails the check (rerun it).
Until a stable release carries the list, the check says so and counts
everything as on stable. A revert then adds a behaviour-change row with kind: breaking
and exception: revert whose text names the reverted pull request
(#<number>). Once stable carries the list, exception: revert no longer
covers anything on it.