Skip to content
Skills Library
Programming · Review & audit

version-parity

/version-parity

Use when a release states one version in several manifests or pins.

Repository
Drift ↗
Licence
MIT
Last repository change
07.11.2026

Assessment and security

91/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability21 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 07.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when a release states one version in several manifests or pins.

Original author description

Use when a release states one version in several manifests or pins.

How it works

  1. The invariant
  2. The failure it prevents
  3. The probe
  4. The repair
  5. Pitfalls
  6. Claim-to-test
Original SKILL.md headings · 94 lines, 696 words
SKILL.md preview
---
name: version-parity
description: "Use when a release states one version in several manifests or pins."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [macos, linux]
category: Release
metadata:
  hermes:
    tags: [release, version, manifest, parity, pin]
    related_skills: [public-surface]
---

# Version Parity

A release states one version in several places: two manifests, a package file, a
descriptor a loader reads, and a pointer a distribution resolves. Most of them are
copied by hand.

## The invariant

**Every declaration of one version states the same value.**

A second invariant rides beside it, and it is a different relation: **a pointer
that names a release names one whose assets exist.**

## The failure it prevents

A parity failure is a release that installs one version and reports another. A
loader loads the artifact its pointer pins, the artifact reports its own version,
and a bug report names the wrong build - so every later diagnosis starts from a
false fact.

A pointer failure is worse because it is asymmetric. The version is bumped before
the assets are published, so the pointer names a release that does not exist yet,
and every install fails to download while the repository looks correct. The
ordering is the invariant: publish the assets, then move the pointer.

## The probe

Read every declaration through the one place in each file that states it, and
print `file: value` so a disagreement is one line long. The extractor depends on
the format - a line match for a manifest, a field read for a package file, the
first line for a pointer:

```sh
{ grep -H '^version' <manifests> | sed -E 's/version *= *"([^"]+)"/\1/'
  echo "<package-file>: $(jq -r '.version' <package-file>)"
  echo "<pointer>: $(head -1 <pointer>)"
} | awk -F': ' '{ print $2 }' | sort -u | wc -l
```

`1` is agreement. Anything else is drift, and the output above names which
declaration differs.

For the pointer, ask the distribution rather than the file:

```sh
gh release view <tag> --repo <owner>/<repo> --json assets -q '.assets[].name'
```

An empty list, or a 404, means the pointer is ahead of the release.

## The repair

There is no mechanical repair, deliberately. A disagreement does not say which
value is right: raising the manifests to the artifact's version and rewinding the
artifact to the manifests' are both repairs, and they mean different releases. The
probe names every value; the decision is a release decision.

The pointer has an order, not a repair:

1. Build and publish the assets for the new version.
2. Confirm they exist and their digests match what the release recorded.
3. Move the pointer last, in its own commit.

A pointer bumped first cannot be un-bumped without a second commit that will be
read as a rewind.

## Pitfalls

- **Two independent version lines are not one parity group.** A binary version and
  a plugin version move together but are not equal; a guard that compares them
  reports drift on every correct release. Group by what must be equal, not by what
  must move together.
- **A version embedded in a badge is a declaration.** A README badge that states
  the version is read by people and never by a tool, which is exactly why it is
  the last one to be updated and the first to be wrong.
- **A generated digest file may restate the version.** A `SHA256SUMS` header
  naming the version is a declaration; regenerate it rather than editing it.
- **A lockfile is not a declaration.** It records what was resolved, it is
  regenerated, and it is not the version the product states.
- **A prerelease suffix sorts differently from what a human expects.** `1.7.0-rc.1`
  is lower than `1.7.0`; a comparison that sorts strings will order them wrongly
  and a comparison that ignores the suffix will call them equal. State which one
  the guard means.

## Claim-to-test

| Claim | Probe | Pass condition |
| --- | --- | --- |
| Every declaration agrees | the `sort -u | wc -l` loop | `1` |
| The pointer names a real release | `gh release view <tag> --json assets` | the asset list is non-empty |
| The assets match the recorded digests | `shasum -a 256 -c SHA256SUMS.txt` | every line `OK` |
| The pointer moved last | `git log --oneline -- <pointer path>` | its commit is newer than the tag |

Versions

The database has no other skills named version-parity.

Database snapshot: 13.11.2026 · package version 4aa10e1c3916 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100check-version
    Use when the user asks whether the duolog version is consistent, what version this repository states, or whether a release tag matches it, and before cutting a release tag. Do not use to change the version; bump-version does that.
  • 90release-doctor
    **WORKFLOW SKILL** - Verify post-merge release readiness, unreleased commits, semver recommendations, and cross-manifest version parity before cutting a release. USE FOR: release doctor, release-doctor, needs release, release readiness check, version parity audit, semver…
  • 100add-to-changelog
    Use when you've shipped a feature, fix, or breaking change and need to update CHANGELOG.md — follows Keep a Changelog format and syncs version numbers across package manifests.
  • 90port-python-parity
    Port features from the official Python claude-agent-sdk to this Ruby gem for parity. Use when syncing with a new Python SDK release, running a gap analysis, or batching parity fixes.
  • 95release
    Cut a new version of the icon-composer plugin — bump the version across every manifest, relock, verify the CI gate locally, commit to main, and publish a GitHub release. Use this when the user asks to release, ship, cut, or tag a version ("release 1.2", "バージョン1.2を出して", "tag a…
  • 100bump-version
    Bump the Logic-Lens version across all six metadata locations at once (package.json, the four plugin manifests, and the README badge), then validate. Use when cutting a release or when `npm run validate` reports a version mismatch.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.