Hermes Version-Bump Wiring Design

Date: 2026-08-05 Revised: 2026-08-06 Status: Approved

Goal

Keep .hermes-plugin/plugin.yaml in lockstep with the repository version by registering it in .version-bump.json and teaching scripts/bump-version.sh to process YAML without implementing a YAML parser in Bash.

Design

• Add \{ "path": ".hermes-plugin/plugin.yaml", "field": "version" \} to .version-bump.json.
• Route .json through the existing jq helpers and .yaml through Mike Farah yq v4. The YAML key and value are passed as data, not interpolated into the expression.
• Support only a present top-level YAML string field. Nested fields and .yml are out of scope.
• Route --check, --audit, and version updates through the same small read/write dispatcher.
• Before a version bump writes any manifest, run one read-only preflight that validates the required tools and reads every present declared manifest through the dispatcher. This prevents a deterministic YAML failure from occurring after earlier JSON files have already been updated. Missing-file behavior remains unchanged, and --help still works without jq or yq.

The preflight is the only reliability addition. It does not make the script transactional or redesign its existing audit and error-status behavior.

Tests

Three focused behavioral tests run the real script against an isolated temporary fixture and prove:

• aligned JSON and YAML pass --check and --audit, and a bump updates both formats;
• an actual bump with JSON declared first and a later YAML manifest whose top-level version is not a string exits nonzero and leaves every manifest byte-for-byte unchanged; and
• the real .version-bump.json registers the Hermes manifest.

Verification also runs shell lint and scripts/bump-version.sh --check against the repository.

Non-Goals

• No hand-written YAML parser.
• No .yml or nested-YAML support.
• No Hermes runtime changes.
• No rollback framework, general config-schema layer, audit/status refactor, or exhaustive failure matrix.
• No change to the separate version-validation and JSON-expression issue found during review.