Problem
.github/scripts/check-sdk-version-pins.py (added in #98 / PR #106) compares
versions between manifests. A version written in prose is invisible to it,
and two are already stale.
sdk/PUBLISHING.md, in the "After publishing" section:
- Line ~213 names
go get .../sdk/go/contextgraph@v0.1.0 as part of the
acceptance bar to re-run. The Go SDK's only tag is sdk/go/v0.1.0, so that
command is not wrong today — but it is pinned prose beside two sibling
commands that are unpinned (npm install @contextgraphprotocol/typescript-sdk,
pip install contextgraph-sdk), and the repo is on 2.0.0. A reader cannot
tell whether v0.1.0 is deliberate or left behind.
- Line ~15 says Python is "✅ published 0.1.0 (2026-07-31)".
sdk/python/pyproject.toml
ships 2.0.0. Whether that line is a historical record of the first publish
or a status field that should track the current version is exactly the
ambiguity worth removing.
The Go SDK also has no in-tree package version at all — a Go module is
versioned by its git tag, so sdk/go/go.mod has nothing for a guard to read.
That is recorded as out of scope in
docs/adr/0012-sdk-version-pins-share-a-major.md, and it means the Go SDK is
the one SDK whose published version can drift from the repo with nothing at all
watching.
How to reproduce
rg -n 'v0\.1\.0|published 0\.1\.0' sdk/PUBLISHING.md
python3 .github/scripts/check-sdk-version-pins.py # green: it reads no prose
git tag -l 'sdk/go/*'
What done looks like
sdk/PUBLISHING.md's status table and acceptance-bar commands either state
the current versions or say plainly that they are a historical record of the
first publish. Pick one convention and apply it to all three rows.
- A decision, written in the ADR or a comment, on whether the Go SDK's tag
should be checked against Cargo.toml's [workspace.package] version —
the "SDKs move in lockstep with the crates" rule in MIGRATION.md §5.4
names the SDKs without excluding Go. If yes, the check reads git tag -l 'sdk/go/v*', which means it can only run where tags are fetched
(fetch-depth: 0 or an explicit git fetch --tags).
- Optionally, extend
check-sdk-version-pins.py to install commands in
markdown — npm install <pkg>@<version>, pip install <pkg>==<version>,
go get <module>@<version> — resolving each against the manifest that owns
the package. Historical records need an exemption list, the way
check-deploy-hygiene.py exempts docs/adr/ and CHANGELOG.md.
Constraints
Found while adding the version-pin guard in #98 / PR #106.
Problem
.github/scripts/check-sdk-version-pins.py(added in #98 / PR #106) comparesversions between manifests. A version written in prose is invisible to it,
and two are already stale.
sdk/PUBLISHING.md, in the "After publishing" section:go get .../sdk/go/contextgraph@v0.1.0as part of theacceptance bar to re-run. The Go SDK's only tag is
sdk/go/v0.1.0, so thatcommand is not wrong today — but it is pinned prose beside two sibling
commands that are unpinned (
npm install @contextgraphprotocol/typescript-sdk,pip install contextgraph-sdk), and the repo is on2.0.0. A reader cannottell whether
v0.1.0is deliberate or left behind.sdk/python/pyproject.tomlships
2.0.0. Whether that line is a historical record of the first publishor a status field that should track the current version is exactly the
ambiguity worth removing.
The Go SDK also has no in-tree package version at all — a Go module is
versioned by its git tag, so
sdk/go/go.modhas nothing for a guard to read.That is recorded as out of scope in
docs/adr/0012-sdk-version-pins-share-a-major.md, and it means the Go SDK isthe one SDK whose published version can drift from the repo with nothing at all
watching.
How to reproduce
What done looks like
sdk/PUBLISHING.md's status table and acceptance-bar commands either statethe current versions or say plainly that they are a historical record of the
first publish. Pick one convention and apply it to all three rows.
should be checked against
Cargo.toml's[workspace.package] version—the "SDKs move in lockstep with the crates" rule in
MIGRATION.md§5.4names the SDKs without excluding Go. If yes, the check reads
git tag -l 'sdk/go/v*', which means it can only run where tags are fetched(
fetch-depth: 0or an explicitgit fetch --tags).check-sdk-version-pins.pyto install commands inmarkdown —
npm install <pkg>@<version>,pip install <pkg>==<version>,go get <module>@<version>— resolving each against the manifest that ownsthe package. Historical records need an exemption list, the way
check-deploy-hygiene.pyexemptsdocs/adr/andCHANGELOG.md.Constraints
schema/reference-vectors.ndjson. Its"version": "1.0.0"strings are provider versions inside fixtures; rewriting them changes the
bytes the reference vectors pin.
MIGRATION.md§2 pins atag that was never cut) are the same family of problem in different files.
Read both before choosing a convention; do not invent a fourth.
Found while adding the version-pin guard in #98 / PR #106.