mirror of
https://github.com/obra/superpowers.git
synced 2026-08-07 22:59:20 +08:00
707b155a38
Record Drew's approved reduced design after the second staff review. Limit preflight to the mutating bump path, cover audit's independent read path, and require byte-for-byte proof that deterministic YAML failures cannot partially update earlier JSON manifests. Provide one TDD implementation task for the Hermes registry entry, jq/yq dispatch, focused preflight, and three behavioral checks. Explicitly defer rollback, audit-status changes, nested YAML, runtime changes, and broader release-tool refactoring.
57 lines
2.1 KiB
Markdown
57 lines
2.1 KiB
Markdown
# 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.
|