feat(2026-05-03-perform-code-optimization-and-document-cleanup): followup Fix CI pnpm version conflict in check.yml

docs/DEVELOPMENT.md

@@ -43,6 +43,7 @@ pnpm run check
 | `pnpm run verify:docs` | markdownlint + offline link-check + docs-flow verifier |
 | `pnpm run verify:docs:online` | Same as `verify:docs` but with full external link checking |
 | `pnpm run verify:generated` | Assert generated output freshness (stub; fleshed out in M3) |
+| `pnpm run verify:ci` | Assert CI workflow files carry no pnpm version pins (see [pnpm version pinning](#pnpm-version-pinning)) |
 | `pnpm run check` | Aggregate: run every gate above and report a summary |
 
 ## Quality tooling (added in M1)
@@ -167,6 +168,7 @@ PASS  verify:pi
 PASS  verify:reviewers
 PASS  verify:docs
 PASS  verify:generated
+PASS  verify:ci
 ```
 
 This is the only acceptable state for merge.  Any failure on a check not in
@@ -415,7 +417,8 @@ Two GitHub Actions workflows live in `.github/workflows/`:
 2. Installs `shellcheck` via `apt-get` (Ubuntu) or `brew` (macOS).
 3. Installs `ripgrep` via `apt-get` (Ubuntu only; pre-installed on macOS runners).
 4. Installs Node.js 22 via `actions/setup-node`.
-5. Installs pnpm 10 via `pnpm/action-setup`.
+5. Installs pnpm via `pnpm/action-setup@v4` — **no `version:` key is set**; the action reads the version from
+   `package.json#packageManager` (currently `pnpm@10.18.1+sha512…`), which is the single source of truth.
 6. Runs `pnpm install --frozen-lockfile`.
 7. Runs `pnpm run check` (the same command contributors run locally).
 
@@ -423,6 +426,24 @@ The matrix runs both `ubuntu-latest` and `macos-latest` to guard against
 platform-specific regressions. Because M2 made all shell scripts portable
 across BSD and GNU coreutils, both runners should stay green.
 
+### pnpm version pinning
+
+The pnpm version is pinned **exclusively** in `package.json#packageManager`:
+
+```json
+"packageManager": "pnpm@10.18.1+sha512.77a884a..."
+```
+
+This field carries an exact version *and* an integrity hash, giving stronger
+reproducibility than a floating major like `version: "10"`.  The
+`pnpm/action-setup@v4` step in `check.yml` reads this field automatically;
+do **not** add a `with.version` key to that step.
+
+`pnpm run verify:ci` (backed by `scripts/lib/assert-no-pnpm-version-pin.mjs`)
+greps every `.github/workflows/*.yml` for `pnpm/action-setup` blocks that
+carry a `version:` key and fails if any are found.  This prevents
+reintroduction of the conflict that caused `pnpm/action-setup@v4` to error.
+
 ### Adding new prerequisites to CI
 
 If a new tool is required (e.g. a new binary called by a verify script),