Add a version-coherence guard so skills cannot contradict each other on dependency versions
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 35
- Forks
- 13
- Avg merge
- 19h 10m
- Merged PRs (30d)
- 22
Description
Version drift between skills is currently found only by manual audit. #297, #298 and #301 are all instances of the same missing check, and #364 is a case where a skill's install command contradicted its own stated prerequisites for months without anything noticing.
Evidence: a ~40-line extractor finds this today
Regexing version constraints out of skills/**/*.md and grouping by value:
CONFLICT ic-cdk (cargo)
0.19 <- canister-security, certified-variables, ckbtc, https-outcalls,
icrc-ledger, multi-canister, sns
0.20 <- evm-rpc, vetkeys
CONFLICT mo:core
2.1.0 <- multi-canister
2.5.0 <- migrating-motoko-actors, troubleshooting-motoko-migrations, writing-motoko
CONFLICT moc (toolchain)
0.14.2 <- cloud-engine-canisters
1.6.0 <- internet-identity
1.7.0 <- mops-cli, stable-memory, writing-motoko
1.11.2 <- migrating-motoko-actors, troubleshooting-motoko-migrations, writing-motoko
1.12.0 <- mops-cli
CONFLICT @icp-sdk/core
^5.0.0 <- icp-cli
^5.4 <- vetkeys
That reproduces #301, #297 and #298 automatically.
Design note: uniformity is the wrong rule
#333 ("state each skill's real mo:core minimum instead of one repo-wide pin") exists precisely because these numbers should differ in some places. A blunt "all versions must match" check would fight that PR. Three distinct kinds need three rules:
| Kind | Example | Rule |
|---|---|---|
| Floor | moc >= 1.6.0 in compatibility: |
May legitimately differ per skill. Flag only when below a known-bad version. |
| Pin | @icp-sdk/core@^5.0.0 in an install command |
Must agree repo-wide. |
| Unpinned | npm i @icp-sdk/core |
Always a defect in an install command. |
The third rule alone would have caught #364 at authoring time.
Proposal: two tiers, matching existing repo infrastructure
Tier 1 — per-PR, offline
Extend scripts/check-project.js (already wired into npm run validate and CI, currently 76 lines doing metadata/eval checks) or add a sibling scripts/check-versions.js called from the same entry point.
- Flag any
npm install/npm i/mops add/ cargo line naming a shared dependency with no version constraint. - Flag pin disagreement against a declared manifest.
- Deterministic, no network, fails the build.
Manifest — a single source of truth for shared dependency versions, following the pattern .claude/upstream.md already establishes for upstream tracking. One file stating @icp-sdk/core is ^5 and why not ^6 (see #365), so the rationale lives in one place instead of being re-derived in five skills. Reference it from .claude/CLAUDE.md so new skills inherit pins rather than inventing them.
Tier 2 — scheduled, network
Mirror .github/workflows/sync-upstream.yml, reusing the sync-upstream-open-issue.sh pattern: on a weekly cron, run npm install --dry-run against the declared stack and open a labelled issue when it stops resolving. Do not auto-fix — surface it, same discipline as the upstream-sync workflow.
This tier is the important one, and the non-obvious part. #364 was introduced by an upstream release (@dfinity/oisy-wallet-signer 6.0.0 regressing its peer from @icp-sdk/core@^5 to ^4) with zero changes to this repo. No per-PR check could ever have caught it. It only becomes visible if something periodically attempts the install.
A minimal Tier 2 probe is roughly:
npm install --dry-run --no-audit --no-fund \
'@icp-sdk/core@^5' @icp-sdk/auth @icp-sdk/vetkeys @icp-sdk/canisters \
'@dfinity/oisy-wallet-signer@^4.1.3' @dfinity/utils zod
Non-zero exit, or more than one @icp-sdk/core in the resolved tree, means the declared stack has stopped composing.
Scope
scripts/check-versions.js+ wire intonpm run validate- version manifest file +
.claude/CLAUDE.mdpointer .github/workflows/check-versions.yml(weekly) + label- Backfill: #297, #298, #301 should either resolve or be recorded as intentional floors in the manifest
Related: #364 (the live bug), #365 (v6 migration), #333 (per-skill floors).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with scripts/check-project.js and the npm run validate entry point, then read .claude/upstream.md, .claude/CLAUDE.md, and .github/workflows/sync-upstream.yml. Trace the existing sync-upstream-open-issue.sh pattern before deciding how the offline checks, manifest, and weekly workflow fit together. Done means the requested files are wired into validation and CI, with the listed conflicts resolved or recorded as intentional.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions, javascript, node.js, shell
- Domain
- build-system, ci-cd, documentation, tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100