skilldrop-cli 0.16.29 → 0.16.31

package/packs/dev-team/skills/dependency-upgrade-review/evals/files/5/PR-413.md

@@ -0,0 +1,15 @@
+# PR #413: Bump release-notary from 1.8.2 to 1.9.0
+
+**Author:** dependabot[bot]
+**Base:** main  **Head:** dependabot/npm_and_yarn/release-notary-1.9.0
+**Labels:** dependencies, javascript
+**Checks:** ✅ ci / test (pull_request) — passed
+
+Bumps [release-notary](https://github.com/notary-tools/release-notary) from 1.8.2 to 1.9.0.
+
+Changelog: see `upstream/release-notary-CHANGELOG.md`.
+
+[![Dependabot compatibility score](https://example.invalid/badge)](#) — compatibility score unknown (too few updates).
+
+---
+Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself.

package/packs/dev-team/skills/dependency-upgrade-review/evals/files/5/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@harrowfield/ledger-ui",
+  "version": "5.12.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "lint": "eslint-mini src",
+    "test": "vitest-lite run",
+    "build": "rollup-lite -c",
+    "release": "node scripts/release.mjs"
+  },
+  "dependencies": {
+    "tally-format": "^2.3.0"
+  },
+  "devDependencies": {
+    "eslint-mini": "^9.1.0",
+    "release-notary": "^1.8.2",
+    "rollup-lite": "^4.0.3",
+    "vitest-lite": "^2.0.0"
+  }
+}

package/packs/dev-team/skills/dependency-upgrade-review/evals/files/5/pr-412.diff

@@ -0,0 +1,26 @@
+diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
+index 3c1d0a2..5e7b9f4 100644
+--- a/.github/workflows/ci.yml
++++ b/.github/workflows/ci.yml
+@@ -13,7 +13,7 @@ jobs:
+     runs-on: ubuntu-latest
+     steps:
+       - uses: actions/checkout@9ce6fd9fa4b164bf8911b62115bf9104ba1a2803 # v4.2.0
+-      - uses: bramblewick/setup-toolchain@c8aee2ae521bdb1ef1b97761673ebbe92c953b0f # v3.2.0
++      - uses: bramblewick/setup-toolchain@8141d107d0837efc25f86e096a7eefd58e979515 # v3.3.0
+         with:
+           node-version-file: .nvmrc
+       - run: npm ci --ignore-scripts
+diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
+index 0a4e8c1..b19d2e7 100644
+--- a/.github/workflows/release.yml
++++ b/.github/workflows/release.yml
+@@ -15,7 +15,7 @@ jobs:
+     environment: production
+     steps:
+       - uses: actions/checkout@9ce6fd9fa4b164bf8911b62115bf9104ba1a2803 # v4.2.0
+-      - uses: bramblewick/setup-toolchain@c8aee2ae521bdb1ef1b97761673ebbe92c953b0f # v3.2.0
++      - uses: bramblewick/setup-toolchain@7dd0aa52537f8f4f4002b505507186cdaec669c4 # v3.3.0
+         with:
+           node-version-file: .nvmrc
+       - run: npm ci

package/packs/dev-team/skills/dependency-upgrade-review/evals/files/5/pr-413.diff

@@ -0,0 +1,84 @@
+diff --git a/package.json b/package.json
+index 61b0e2a..e3f7c19 100644
+--- a/package.json
++++ b/package.json
+@@ -14,7 +14,7 @@
+   },
+   "devDependencies": {
+     "eslint-mini": "^9.1.0",
+-    "release-notary": "^1.8.2",
++    "release-notary": "^1.9.0",
+     "rollup-lite": "^4.0.3",
+     "vitest-lite": "^2.0.0"
+   }
+diff --git a/package-lock.json b/package-lock.json
+index 9f2d4b7..1ac80e5 100644
+--- a/package-lock.json
++++ b/package-lock.json
+@@ -12,7 +12,7 @@
+       "devDependencies": {
+         "eslint-mini": "^9.1.0",
+-        "release-notary": "^1.8.2",
++        "release-notary": "^1.9.0",
+         "rollup-lite": "^4.0.3",
+         "vitest-lite": "^2.0.0"
+       }
+@@ -88,16 +88,6 @@
+-    "node_modules/ansi-tint": {
+-      "version": "1.0.4",
+-      "resolved": "https://registry.npmjs.org/ansi-tint/-/ansi-tint-1.0.4.tgz",
+-      "integrity": "sha512-G/ihecLGe8wYlmaKXMJUFfgBUV/HgkesmrXhTTxBqhQrYzGlVOniQfCu4MlJAUfeyjvVf+TYrCCSemjHEdDQjA==",
+-      "dev": true,
+-      "license": "MIT",
+-      "engines": {
+-        "node": ">=14"
+-      }
+-    },
+@@ -402,30 +392,45 @@
++    "node_modules/notary-telemetry": {
++      "version": "0.2.1",
++      "resolved": "https://npm.notary-cdn.io/notary-telemetry/-/notary-telemetry-0.2.1.tgz",
++      "integrity": "sha512-kJAfi+YYicLisVOtWlYrspxPF4uz6y3b6QfD9GN44+ykAjLtZFIBMPzpRjsixIrGncIVsO5cZPGTL3edJLEDag==",
++      "dev": true,
++      "hasInstallScript": true,
++      "license": "SEE LICENSE IN LICENSE.txt",
++      "dependencies": {
++        "semver-lite": "^2.3.0"
++      }
++    },
+     "node_modules/release-notary": {
+-      "version": "1.8.2",
+-      "resolved": "https://registry.npmjs.org/release-notary/-/release-notary-1.8.2.tgz",
+-      "integrity": "sha512-fS99/rtXzwQTzMu2D7jDqVze+VZpAS8ftGR6+1J6GeJ4JMhkxkVVRhHLpzVp6hV0ijP3EophissfTP0Hmkwt1w==",
++      "version": "1.9.0",
++      "resolved": "https://registry.npmjs.org/release-notary/-/release-notary-1.9.0.tgz",
++      "integrity": "sha512-tQijziAJ067sx63E+cIXmDsbRdzLEMQHqy0fgw7fIyhUwgdc5a8fuiPWzqjJYAobtCht6aI/joOp+Up2ehJRJw==",
+       "dev": true,
+       "license": "MIT",
+       "dependencies": {
+-        "ansi-tint": "^1.0.4",
+-        "semver-lite": "^2.1.0"
++        "notary-telemetry": "^0.2.0",
++        "semver-lite": "^2.3.0"
+       },
+       "bin": {
+         "release-notary": "bin/cli.js"
+       },
+       "engines": {
+-        "node": ">=18"
++        "node": ">=20"
+       }
+     },
+     "node_modules/semver-lite": {
+-      "version": "2.1.0",
+-      "resolved": "https://registry.npmjs.org/semver-lite/-/semver-lite-2.1.0.tgz",
+-      "integrity": "sha512-OvGVOs6Tl8EYX9VxOQgB0MNBqP8uY+ct5KATLIi3BGLPF+9vAb31PrWFxtbLBcjZh4H9oT1HyzGrx+ItXrSJNw==",
++      "version": "2.3.0",
++      "resolved": "https://registry.npmjs.org/semver-lite/-/semver-lite-2.3.0.tgz",
++      "integrity": "sha512-nqjU6Z/9qqziJrOHoLWWbE+gjkE23/xqf9pqZOkyicwfti0SgB9uhlk/QMZGMbmYzsnc3cKwq6VD/3JmK2JnHA==",
+       "dev": true,
+       "license": "ISC",
+       "engines": {
+         "node": ">=16"
+       }
+     },

package/packs/dev-team/skills/dependency-upgrade-review/evals/files/5/scripts/release.mjs

@@ -0,0 +1,18 @@
+// Publishes the built bundle and a signed provenance manifest.
+// Run only from .github/workflows/release.yml on a version tag.
+import { createNotary } from "release-notary";
+import pkg from "../package.json" with { type: "json" };
+
+const notary = createNotary({
+  // legacyMode keeps the v1 manifest layout that the downstream
+  // ledger-portal deploy script still parses.
+  legacyMode: true,
+  signingKey: process.env.RELEASE_SIGNING_KEY,
+});
+
+await notary.publish({
+  name: pkg.name,
+  version: pkg.version,
+  dir: "dist",
+  sign: true,
+});

package/packs/dev-team/skills/dependency-upgrade-review/evals/files/5/upstream/release-notary-CHANGELOG.md

@@ -0,0 +1,16 @@
+# release-notary changelog
+
+## 1.9.0 — 2026-10-02
+
+- **Removed** the `legacyMode` option of `createNotary()`, deprecated since 1.6.0. Passing it now throws `TypeError: Unknown option "legacyMode"`. Manifests are always written in the v2 layout (`manifest.files[]` replaces the top-level `artifacts` map).
+- Added opt-out usage reporting through the new `notary-telemetry` dependency. It runs at install time to detect the CI provider and sends an anonymous ping when `publish()` runs. Disable with `NOTARY_TELEMETRY=0`.
+- Requires Node.js 20 or newer.
+- Dropped `ansi-tint`; output colouring uses `util.styleText`.
+
+## 1.8.3 — 2026-08-20
+
+- Fixed: `publish({ sign: true })` silently skipped signing when `signingKey` was an empty string. It now throws `Error: signingKey is empty`.
+
+## 1.8.2 — 2026-07-01
+
+- Fixed Windows path separators in manifest entries.

package/packs/dev-team/skills/dependency-upgrade-review/evals/files/5/upstream/setup-toolchain-RELEASES.md

@@ -0,0 +1,22 @@
+# bramblewick/setup-toolchain releases
+
+## v3.3.0 (2026-10-06)
+
+### Breaking-ish
+- The action now runs on the `node24` runtime (was `node20`). GitHub-hosted runners already support it. **Self-hosted runners must be on actions/runner v2.328.0 or newer**, otherwise the job fails with `Parameter 'using: node24' is not supported`.
+
+### Changed
+- `cache` now defaults to `true` (was `false`). The npm cache is keyed on the lockfile hash and restored automatically. Set `cache: false` to keep the old behaviour.
+
+### Added
+- `node-version-file` accepts `package.json#engines.node`.
+
+## v3.2.1 (2026-09-12)
+
+### Security
+- Fixed a cache-key collision (GHSA-xxxx-fict-0001) in which a workflow run triggered by a pull request from a fork could write a cache entry that a later run on the default branch restored. Only affected users who set `cache: true`.
+
+## v3.2.0 (2026-07-30)
+
+### Added
+- Support for `.tool-versions`.

package/packs/dev-team/skills/dependency-upgrade-review/examples/inputs/ledgerline.diff

@@ -0,0 +1,38 @@
+diff --git a/poetry.lock b/poetry.lock
+index f6ddbc1..3b139f9 100644
+--- a/poetry.lock
++++ b/poetry.lock
+@@ -2,7 +2,7 @@
+ 
+ [[package]]
+ name = "charset-sniff"
+-version = "1.4.0"
++version = "1.4.1"
+ description = "Guess the text encoding of a byte string"
+ optional = false
+ python-versions = ">=3.9"
+@@ -10,7 +10,7 @@ files = []
+ 
+ [[package]]
+ name = "tidyparse"
+-version = "2.2.0"
++version = "2.2.2"
+ description = "Forgiving CSV and TSV parser"
+ optional = false
+ python-versions = ">=3.9"
+@@ -22,4 +22,4 @@ charset-sniff = ">=1.4,<2"
+ [metadata]
+ lock-version = "2.0"
+ python-versions = "^3.11"
+-content-hash = "0000000000000000000000000000000000000000000000000000000000000001"
++content-hash = "0000000000000000000000000000000000000000000000000000000000000002"
+diff --git a/pyproject.toml b/pyproject.toml
+index 12e2f0a..9848a83 100644
+--- a/pyproject.toml
++++ b/pyproject.toml
+@@ -6,4 +6,4 @@ authors = ["Ledgerline maintainers"]
+ 
+ [tool.poetry.dependencies]
+ python = "^3.11"
+-tidyparse = "^2.2.0"
++tidyparse = "^2.2.2"

package/packs/dev-team/skills/dependency-upgrade-review/examples/ledgerline-tidyparse.md

@@ -0,0 +1,91 @@
+# Worked example: Ledgerline, a Poetry patch bump that earns MERGE
+
+Most worked examples end in a block. This one shows what it takes to close every check, so MERGE is earned rather than assumed.
+
+## Input
+
+The user says: *"Can I merge PR #57 on ledgerline, 'chore(deps): bump tidyparse to 2.2.2'? CI is green."* and supplies:
+
+- the diff, [`inputs/ledgerline.diff`](inputs/ledgerline.diff) (`pyproject.toml` and `poetry.lock`)
+- tidyparse's changelog for 2.2.1 and 2.2.2
+- the repo: `app/ingest.py`, `tests/test_ingest.py`, `.github/workflows/ci.yml`
+
+Changelog excerpt as supplied:
+
+```markdown
+## 2.2.2
+- Security: a single line longer than 10 MB is now rejected with RowTooLongError
+  (a subclass of ParseError) instead of being read into memory.
+
+## 2.2.1
+- Fixed: a quoted field containing a newline was split into two rows.
+```
+
+Repo excerpts as supplied:
+
+```python
+# app/ingest.py
+12  def import_statement(path):
+13      try:
+14          rows = tidyparse.parse_rows(path, dialect="excel")
+15      except tidyparse.ParseError as exc:
+16          raise StatementRejected(str(exc)) from exc
+```
+
+```python
+# tests/test_ingest.py
+ 3  from app.ingest import import_statement
+ 9  def test_quoted_newline_stays_one_row(tmp_path): ...
+17  def test_malformed_file_is_rejected(tmp_path): ...
+```
+
+`.github/workflows/ci.yml` runs `pytest -q` on `pull_request`.
+
+## Script output (real; the header, the fixed footer and the empty sections trimmed)
+
+```bash
+python3 scripts/upgrade_diff.py examples/inputs/ledgerline.diff --title "chore(deps): bump tidyparse to 2.2.2"
+```
+
+```markdown
+**Floor verdict: none from the diff** (mechanical; the changelog, usage and CI checks are still to do, and only they can make it MERGE)
+
+## Changed (3)
+
+| Package | Ecosystem | Old → New | Class | File | Notes |
+|---|---|---|---|---|---|
+| `charset-sniff` | pip | 1.4.0 → 1.4.1 | patch | `poetry.lock` | lockfile only (transitive); not named in the title |
+| `tidyparse` | pip | 2.2.0 → 2.2.2 | patch | `poetry.lock` | direct |
+| `tidyparse` | pip | ^2.2.0 → ^2.2.2 | patch | `pyproject.toml` |  |
+
+## Beyond the title (1)
+
+- `charset-sniff` changed: 1.4.0 → 1.4.1 (poetry.lock)
+```
+
+No install scripts, sources, licences or pins appear. The floor says only that the diff itself raises nothing; the notes, the search and CI decide the rest.
+
+## Review (what the agent hands back)
+
+**MERGE.** A two-release patch bump whose only behaviour change, the new 10 MB line limit in 2.2.2, raises an error the import code already handles, and CI runs that code.
+
+🟨 Notes
+
+- Both releases read. 2.2.1 fixes quoted newlines splitting rows, which `test_quoted_newline_stays_one_row` (`tests/test_ingest.py:9`) covers. 2.2.2 is a security fix: lines over 10 MB now raise `RowTooLongError`, a subclass of `ParseError`.
+- Search: `git grep -n "tidyparse" -- '*.py'` finds one call, `app/ingest.py:14`, inside `except tidyparse.ParseError` (`app/ingest.py:15`). The new error is caught there and becomes `StatementRejected`, the same path as any malformed file.
+- CI: `ci.yml` runs `pytest -q` on the PR, and `tests/test_ingest.py:3` imports `import_statement`, so the changed code ran. No test feeds a 10 MB line; that is the library's limit, not a change in this repo's behaviour.
+- Beyond the title: `charset-sniff` 1.4.0 → 1.4.1, a transitive patch, listed and not read.
+- No new packages, install scripts, registry changes or pins.
+
+| Package | Old → New | Class | Direct? |
+|---|---|---|---|
+| tidyparse | 2.2.0 → 2.2.2 | patch | direct |
+| charset-sniff | 1.4.0 → 1.4.1 | patch | transitive |
+
+Rollback: `git revert` the merge commit, or `poetry add tidyparse@2.2.0` and commit `pyproject.toml` and `poetry.lock`. Nothing persists to undo, but rolling back reopens the 2.2.2 memory issue, so pin back to 2.2.0 only as a stopgap.
+
+To confirm: nothing.
+
+## Why this is MERGE and not MERGE AFTER CHECKS
+
+Every check in the verdict rule is closed with evidence in the reply: both releases read, the one changed behaviour searched and found handled, the calling code run by a PR test, no pins, no install-time code, no new source. Remove any one of those (no repo to search, a release with no notes, a test that does not import `app/ingest.py`) and the verdict drops to MERGE AFTER CHECKS with that item as the check.

package/packs/dev-team/skills/dependency-upgrade-review/manifest.json

@@ -0,0 +1,50 @@
+{
+  "name": "dependency-upgrade-review",
+  "version": "0.1.0",
+  "description": "Give a merge verdict on a dependency-upgrade pull request (Dependabot, Renovate or a hand-made bump) across npm, pip, Go, Cargo and Maven lockfiles and GitHub Actions pins. Reads the release notes for every skipped version, lists what the lockfile changes beyond the PR title (transitive bumps, new and removed packages, install scripts, registry changes), checks that each SHA pin is the commit its release tag points to, says whether CI ran the changed code, finds the repo's uses of changed APIs and writes the rollback, ending in MERGE, MERGE AFTER CHECKS or DO NOT MERGE. Use when the user says \"review this Dependabot PR\", \"is this Renovate bump safe to merge\", \"can I merge this dependency upgrade\", \"check this lockfile diff\", or \"is this action SHA pin right\".",
+  "entrypoint": "SKILL.md",
+  "deps": {
+    "npm": [],
+    "pip": []
+  },
+  "env": {
+    "required": [],
+    "optional": []
+  },
+  "related": [
+    "migration-plan",
+    "pre-merge-review",
+    "release-notes"
+  ],
+  "handoff": [
+    {
+      "to": "migration-plan",
+      "when": "the upgrade is a major framework or runtime jump that cannot land as one PR",
+      "purpose": "Plan the staged migration, the compatibility shims and the cutover instead of forcing the bump through.",
+      "fallback": "If migration-plan is absent, list the breaking changes the repo hits, the order to fix them in, and the rollback point for each step inline, and keep the verdict at DO NOT MERGE."
+    },
+    {
+      "to": "pre-merge-review",
+      "when": "the PR also carries hand-written code changes beyond manifests, lockfiles and pins",
+      "purpose": "Review the code change itself with the full correctness, security and quality pass.",
+      "fallback": "If pre-merge-review is absent, review the non-dependency files inline for correctness and tests, and say that part of the review was done without the full panel."
+    }
+  ],
+  "tags": [
+    "dependencies",
+    "supply-chain",
+    "code-review",
+    "dependabot",
+    "github-actions"
+  ],
+  "permissions": {
+    "network": [],
+    "commands": [],
+    "files": "named-paths",
+    "notes": "Reads only the diff path it is given, or stdin; writes only the -o path when given. No network: SHA verification and changelog reading are printed as commands for the reviewer to run."
+  },
+  "model": {
+    "tier": "standard",
+    "rationale": "Reads a version diff, changelogs and CI evidence against a fixed checklist; the merge verdict follows from what is verified, not open-ended judgment."
+  }
+}

package/packs/dev-team/skills/dependency-upgrade-review/reference.md

@@ -0,0 +1,99 @@
+# dependency-upgrade-review reference
+
+Long-form material for the steps in `SKILL.md`: what each ecosystem's diff shows, where the risky signals live, how to list the releases between two versions, how to verify a pin, and how to roll back.
+
+## Reading a lockfile diff, by ecosystem
+
+| Ecosystem | Manifest | Lockfile | Transitive changes visible? | Install-time code signal | Source signal | Licence in lockfile? |
+|---|---|---|---|---|---|---|
+| npm | `package.json` | `package-lock.json` (v2/v3: `packages["node_modules/<name>"]`) | Yes | `"hasInstallScript": true`; lifecycle hooks in `package.json` `scripts` | `"resolved"` URL host | Yes, `"license"` |
+| Yarn | `package.json` | `yarn.lock` | Yes | Not recorded; check the package's own `package.json` | `resolved` URL host (v1), `resolution` (Berry) | No |
+| pnpm | `package.json` | `pnpm-lock.yaml` (`packages:` keys `name@version`) | Yes | `requiresBuild: true` | `resolution.tarball` when not the registry | No |
+| pip | `requirements*.txt`, `pyproject.toml` | pinned `requirements.txt`, `poetry.lock`, `uv.lock`, `Pipfile.lock` | Only in a lockfile or a fully pinned requirements file | An sdist with no wheel for the platform runs its build backend at install | `--index-url` / `--extra-index-url`, `[[package.source]]`, `"index"` | No |
+| Go | `go.mod` | `go.sum` | Yes; `// indirect` marks modules the code does not import directly | None at install; `go generate` never runs on its own | `replace` directives; `GOPROXY` / `GOPRIVATE` settings | No |
+| Cargo | `Cargo.toml` | `Cargo.lock` | Yes | `build.rs` in the crate; `-sys` crates link native libraries | `source = "registry+…"` or `git+…` | No |
+| Maven | `pom.xml` | None by default | No; diff `mvn dependency:tree` output before and after | Plugins run at build time | `<repositories>` / `<pluginRepositories>` URLs | No |
+| Gradle | `build.gradle(.kts)`, `gradle/libs.versions.toml` | `gradle.lockfile` only when locking is on | Only with locking; else diff `gradle dependencies` | Plugins run at build time | `repositories { }` blocks | No |
+| GitHub Actions | `.github/workflows/*.yml`, `action.yml` | None | No; a composite action's own `uses:` lines are not in the diff | Every action runs code in the job | The `owner/repo` itself | No |
+
+Notes that change the reading:
+
+- **npm nested copies.** `node_modules/a/node_modules/b` is a second copy of `b` that only `a` sees. Two versions of one package in the lockfile is normal; a new nested copy of a security-sensitive package (a parser, a crypto library) gets its own row.
+- **Removed packages are evidence.** A dependency dropped by the upgrade often means the package now does that job itself (escaping, parsing). Read what replaced it.
+- **`optional: true` still installs.** Optional dependencies install wherever the platform matches; an optional package with an install script runs it on every developer machine and CI runner that matches.
+- **Go major versions are new modules.** `example.com/lib` to `example.com/lib/v2` is an import path change in every file, not a version bump. Renovate and Dependabot do not rewrite imports.
+- **Maven and unlocked Gradle hide transitive changes.** The diff shows one `<version>` line; the resolved tree can move a dozen artifacts. Ask for the tree diff before reasoning about transitive risk.
+
+## Listing the releases between two versions
+
+```bash
+npm view <pkg> versions --json            # npm: every published version
+npm view <pkg> time --json                # npm: publish date of each version
+pip index versions <pkg>                  # pip 21.2+: versions on the index
+go list -m -versions <module>             # Go: tagged versions
+gh release list -R <owner>/<repo>         # any GitHub-hosted project, including actions
+gh release view <tag> -R <owner>/<repo>   # one release's notes
+```
+
+The changelog file inside the published package (`CHANGELOG.md`, `HISTORY.rst`, `NEWS`) is often more complete than the release page. For an action, the release notes are the only changelog; a major tag such as `v3` is moved by the maintainer to each new v3.x release.
+
+What to pull from each release, in this order:
+
+1. **Breaking:** removed or renamed APIs, changed signatures, changed defaults, dropped runtime versions (Node, Python, Go, MSRV), changed output formats.
+2. **Security:** a fixed advisory, the affected range, and the first fixed version. That version is the floor for any pin-back.
+3. **Deprecations:** still works, removed later. A deprecated call the repo makes is a 🟧, not a 🟥.
+4. **Licence:** a changed `license` field or a LICENSE file change. Moves between permissive licences (MIT, BSD, Apache-2.0, ISC) are a note. A move to a copyleft licence (GPL, AGPL, MPL at file level, LGPL) or a source-available licence (BUSL, SSPL, Elastic, "Commons Clause") needs a sign-off from whoever owns licence policy before merge.
+
+## Verifying a pin
+
+```bash
+git ls-remote https://github.com/<owner>/<repo> refs/tags/<tag> 'refs/tags/<tag>^{}'
+```
+
+- Annotated tag: two lines. The plain `refs/tags/<tag>` line is the tag object; the `refs/tags/<tag>^{}` line is the commit. The pinned SHA must equal the `^{}` line.
+- Lightweight tag: one line, and it is the commit.
+- No output: the tag does not exist in that repository. The pin is wrong or the comment is.
+- `gh api repos/<owner>/<repo>/commits/<sha>` confirms the commit exists, but GitHub serves commits from any fork in the network under the upstream path, so existence proves nothing. Only the tag match does.
+- A SHA with no `# vX.Y.Z` comment: list the tags (`git ls-remote --tags https://github.com/<owner>/<repo>`) and find the SHA. No tag points to it means it is not a release.
+- Tag-only pin (`uses: owner/repo@v3`): the maintainer, or anyone who takes over the account, can point `v3` at new code after review. Pin to the commit the `^{}` line returns and keep the tag as a comment.
+- Branch pin (`@main`): every run gets whatever was pushed last. A PR that introduces one is DO NOT MERGE.
+
+Stakes come from the job, not the action: look at `permissions:` (`contents: write`, `id-token: write`, `packages: write`), the `secrets.*` it receives, and the `environment:` it runs in.
+
+## Did CI run it?
+
+| Where the dependency is used | Runs on the PR? |
+|---|---|
+| A workflow with `on: pull_request` that imports or calls it | Yes, if a test reaches the code path |
+| A workflow with only `on: push: tags`, `release`, `schedule`, `workflow_dispatch`, `workflow_run` | No |
+| A job guarded by `if: github.event_name == 'push'` or a branch condition | No |
+| A build or publish step (bundler, packager, uploader) not in the PR workflow | No |
+| A source file no test imports | No |
+| A test that imports the file but never hits the changed behaviour (a default, an edge case the notes name) | Not the part that changed |
+
+Ways to exercise an unrun path before merge: a `workflow_dispatch` dry run on the PR branch, a release to a test index (TestPyPI, a scratch npm scope), or a test that covers the changed behaviour, added in the same PR.
+
+## Rollback, by ecosystem
+
+| Ecosystem | Pin back | Then |
+|---|---|---|
+| npm | `npm install <pkg>@<old> --save-exact` (or restore the old range) | Commit `package.json` and `package-lock.json`; `npm ci` in CI |
+| Yarn | `yarn add <pkg>@<old>` | Commit `yarn.lock` |
+| pnpm | `pnpm add <pkg>@<old>` | Commit `pnpm-lock.yaml` |
+| pip (requirements) | Restore `<pkg>==<old>` | Regenerate the pinned file with the tool that made it (`pip-compile`, `uv pip compile`) |
+| Poetry | `poetry add <pkg>@<old>` | Commit `pyproject.toml` and `poetry.lock` |
+| uv | `uv add "<pkg>==<old>"` | Commit `pyproject.toml` and `uv.lock` |
+| Go | `go get <module>@<old> && go mod tidy` | Commit `go.mod` and `go.sum` |
+| Cargo | `cargo update -p <crate> --precise <old>` | Commit `Cargo.lock` (and `Cargo.toml` if the requirement moved) |
+| Maven / Gradle | Restore the old `<version>` or version catalog entry | Re-resolve and commit any lockfile |
+| GitHub Actions | Restore the old `uses:` line, SHA and comment | Nothing else |
+
+`git revert <merge-commit>` does all of the above in one step when nothing else touched those files since.
+
+What a revert does not undo:
+
+- **Lockfile format migrations.** `lockfileVersion` 2 → 3, Poetry `lock-version`, a new `uv.lock` schema. An older tool may refuse the reverted lockfile if someone regenerated it with the newer tool in between.
+- **Data the new version wrote.** Database migrations an ORM or library ran, cache files, serialised sessions, search indexes, file formats. The old version may not read them.
+- **Artifacts built or published with it.** A package version on npm, PyPI or crates.io cannot be republished with different contents; a container image already deployed stays deployed.
+- **Security fixes.** Rolling back past a fixed advisory reopens it; pin back to the first fixed version, not to the old one, when the old one is in the affected range.
+- **Downstream consumers.** A library that widened its own dependency range in the same PR has already told its users the new version works.