rogee/superpowers
1
0
Fork 0
mirror of https://github.com/obra/superpowers.git synced 2026-08-07 22:59:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: plan Hermes version-bump wiring

Browse Source 
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.
This commit is contained in:
Drew Ritter
2026-08-06 14:42:08 -07:00
committed by Jesse Vincent
parent 3e1ecde38f
commit 707b155a38
2 changed files with 317 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
docs/superpowers/specs/2026-08-05-hermes-version-bump-wiring-design.md
View File

@@ -2,7 +2,7 @@
**Date:** 2026-08-05
**Revised:** 2026-08-06
**Status:** Draft for Drew review
**Status:** Approved
## Goal
@@ -21,11 +21,11 @@ to process YAML without implementing a YAML parser in Bash.
are out of scope.
- Route `--check`, `--audit`, and version updates through the same small
read/write dispatcher.
- Before any non-help command, run one read-only preflight that validates the
required tools and configured extensions, then reads every present declared
manifest. 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`.
- 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.
@@ -35,12 +35,15 @@ transactional or redesign its existing audit and error-status behavior.
Three focused behavioral tests run the real script against an isolated
temporary fixture and prove:
- aligned JSON and YAML pass `--check`, and a bump updates both formats;
- a preflight failure leaves every manifest unchanged; and
- 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 the existing Hermes tests, shell lint, and
`scripts/bump-version.sh --check` against the repository.
Verification also runs shell lint and `scripts/bump-version.sh --check` against
the repository.
## Non-Goals