version-sentinel
Skill6 starsChanged 2 days agoMITView on GitHub
Use when adding, bumping, or changing a dependency in package.json, requirements*.txt, constraints*.txt, pyproject.toml, Cargo.toml, *.csproj, *.fsproj, or *.vbproj. Triggered automatically by version-sentinel's PreToolUse hook (where the host supports hooks) — this skill explains how to satisfy the block and record a version check.
- Installs packages
In this repository6 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- audit-dependenciesSkill
- version-sentinelSkill
- audit-dependenciesSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 4 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 20
If a tool call exits 2 with BLOCKED: version-sentinel, you must:
- Distinctive: line 35
If web search is unavailable, fetch the registry URL directly, or consult a current documentation tool for the package.
- Very specific: line 43
Retry with the verified version: If the blocked input omitted the version or used a floating tag such as latest, rewrite it first.
- Distinctive: line 49
If you genuinely intend to install an older version (CVE mitigation or compatibility), record with:
- Very specific: line 53
After a successful online check and current audit, this can pass the hook and is flagged as intentional-pin (not DRIFT) in the audit output.
- Distinctive: line 57
Don't fake a source URL you didn't actually see.
- Distinctive: line 58
Don't try to bypass the hook with git commit --no-verify or similar.
- Very specific: line 59
Don't unset VS_DISABLE without the user's awareness.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Version Sentinel — Workflow
The version-sentinel setup blocks dependency changes until you've verified the package version against its upstream registry. Here's the required flow. On hosts without hook support, follow the same flow whenever you change a manifest or run an install command.
Mandatory startup audit
From the project directory, run the bundled scripts/check-versions.sh at startup and after manifests or lockfiles change. Hooks require successful current project evidence before dependency work. Registry lookup failure blocks; newer-release drift is reported without upgrading dependencies. File inspection, user questions, audit retries, and version recording remain available.
Handle deterministic tool compatibility issues automatically when existing file contents, dependency selectors, and sources can be preserved. Flat npm overrides strings and $direct-dependency references are parsed and audited automatically; they do not require manifest repair or user input. Do not remove overrides or bypass online checks. Nested and version-qualified override keys remain blocked until the parser can track their full intent. Report parser limitations as tool limitations, not damaged manifests; preserve the manifest.
If a required manifest is missing or invalid, ask Daniel before recreating or repairing that exact file. Do not guess dependencies. Only after actual consent, run bash <plugin-root>/scripts/recover-manifest.sh approve FILE --user-confirmed 'REASON'. This records an attestation; it does not obtain approval or create contents. Online-verify proposed dependencies before writing approved contents, then rerun the audit. Do not use the consent flag without approval.
When you see a BLOCKED message
If a tool call exits 2 with BLOCKED: version-sentinel, you must:
- Resolve the intended dependency. Identify the ecosystem and package. For a public package without a version, treat it as a latest-version request and look up the current release. Ask the user only when the dependency is ambiguous or private. Private registries are unsupported by the canonical verifier; explain the limitation and stop dependency work instead of guessing a public source.
Verify the version. For a latest-version request, look up the current release. For a deliberate pin, verify that the requested version exists and record the reason as described below. Use a web search first:
npm: search"<pkg> latest version site:npmjs.com"pip/pyproject: search"<pkg> latest version site:pypi.org"csproj: search"<pkg> latest version site:nuget.org"cargo: search"<pkg> latest version site:crates.io"
If web search is unavailable, fetch the registry URL directly, or consult a current documentation tool for the package.
Record the check. From the user's project directory, locate this plugin's bundled
scripts/vs-record.shand run:bash <plugin-root>/scripts/vs-record.sh <ecosystem> <pkg> <version-you-intend-to-install> <source-url>The source must be the canonical
https://package page or upstream URL, orintentional:followed by a nonempty reason for a deliberate pin. The recorder makes its own successful online upstream request and verifies that the exact intended version exists. Older pins need both online evidence and a reason.- Retry with the verified version. If the blocked input omitted the version or used a floating tag such as
latest, rewrite it first. For example, usenpm install lodash@4.17.21, notnpm install lodashornpm install lodash@latest.
Local paths, URLs, git sources, and workspace dependencies are outside registry-version checks. A NuGet PackageReference without Version may use Central Package Management, so the manifest gate ignores that form.
Intentional non-latest pins
If you genuinely intend to install an older version (CVE mitigation or compatibility), record with:
bash <plugin-root>/scripts/vs-record.sh <ecosystem> <pkg> <version> "intentional: <brief reason>"After a successful online check and current audit, this can pass the hook and is flagged as intentional-pin (not DRIFT) in the audit output.
What NOT to do
- Don't fake a source URL you didn't actually see. The recorder validates canonical upstream data; a URL string alone is not evidence.
- Don't try to bypass the hook with
git commit --no-verifyor similar. The hook runs on file edits and terminal commands, not on git. - Don't
unset VS_DISABLEwithout the user's awareness; that's an escape hatch for throwaway sessions, not normal flow.
Audit command
From the user's project directory, run bash <plugin-root>/scripts/check-versions.sh. It scans manifests within four directory levels and reports drift. Run it before tagging a release.
Legacy URL-only records, automatic post-install records, and stale offline responses cannot authorize dependency changes. Private registries are not supported by the current canonical verifier; a reason cannot bypass online verification. Hooks do not intercept arbitrary shell/Python file writes. See docs/enforcement.md for scan scope, recovery trust, and host activation limits.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

