@linchpinagency/skills 0.1.11 → 0.1.12

package/README.md

@@ -12,7 +12,7 @@ GitHub Copilot, and other compatible coding agents.
 ![Zero dependencies](https://img.shields.io/badge/Dependencies-0-brightgreen)
 
 <!-- x-release-please-start-version -->
-### Latest release: 0.1.11
+### Latest release: 0.1.12
 <!-- x-release-please-end -->
 
 | Release | Skill standard | Install |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linchpinagency/skills",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Linchpin's library of reusable AI agent skills for WordPress projects.",
   "type": "module",
   "bin": {

package/skills/quality-gates/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: quality-gates
-description: Run a Linchpin project's own lint, coding-standards, static-analysis, and test gates before committing or opening a PR — detecting the toolchain from composer.json, package.json, phpcs.xml.dist and lint-staged rather than assuming it. Use when preparing to commit, when asked "is this ready to commit/ship", when CI lint or PHPCS is failing, when a pre-commit hook blocks you, or when a repo is missing the standard lint scripts. Not for writing the commit message — use `commit-and-release`.
-version: 1.0.0
+description: Run a Linchpin project's own lint, coding-standards, static-analysis, test and Plugin Check gates before committing or opening a PR — detecting the toolchain from composer.json, package.json, phpcs.xml.dist and lint-staged rather than assuming it. Use when preparing to commit, when asked "is this ready to commit/ship", when CI lint or PHPCS is failing, when a pre-commit hook blocks you, when a plugin has to pass Plugin Check before it ships, or when a repo is missing the standard lint scripts. Not for writing the commit message — use `commit-and-release`.
+version: 1.1.0
 ---
 
 # Quality gates
@@ -22,6 +22,7 @@ is checked but in what counts as a failure.
 - The user asks whether a change is ready to ship.
 - CI lint / PHPCS / PHPStan failed and you need to reproduce and fix it locally.
 - A husky pre-commit hook is blocking a commit.
+- A plugin is heading for WordPress.org, packagist.linchpin.com, or a release.
 - A repo is missing the house lint scripts and should get them.
 
 **Not this skill:** the commit message, branch, or release — [`commit-and-release`](../commit-and-release/SKILL.md).
@@ -47,6 +48,7 @@ the same conventions but expose different gates.
 | `package.json` → `scripts` | JS/CSS gates (`lint:js`, `lint:css`, `format`, `lint:check`) | Fall back to `eslint`/`prettier` only if configured |
 | `lint-staged.config.js` + `.husky/` | Pre-commit is already wired — **mirror those exact commands** | Run the scripts directly |
 | Nested `package.json` (e.g. `themes/*`, `plugins/*`, `src/`) | Gates run **in that workspace**, not the root | Root only |
+| A plugin header (`Plugin Name:`) plus `readme.txt`, or `.github/workflows/plugin-check.yml` | It is a distributed plugin → **Plugin Check applies** | Skip it; Plugin Check is meaningless for a theme or a site repo |
 | `.linchpin.json` | Project metadata and local environments | Not every repo has one |
 
 Full command matrix: [`references/toolchain.md`](references/toolchain.md).
@@ -68,7 +70,13 @@ Full command matrix: [`references/toolchain.md`](references/toolchain.md).
 5. **Fix, don't silence.** Auto-fixers first (`composer run phpcbf`, `composer run fixer`,
    `npm run format`), then re-run the gate; hand-fix what remains. → Gate passes with the
    fix in the code, not in the config.
-6. **Report gaps, then hand off.** State which gates ran, which were skipped and why. If the
+6. **Plugin Check gate** — distributed plugins only. `composer run plugin-check` where the
+   repo has it, otherwise the commands in
+   [`references/toolchain.md`](references/toolchain.md#plugin-check). It builds the
+   distributable and boots WordPress, so it is slower than the rest: run it before opening
+   the PR rather than on every commit. → Zero findings, **warnings included**, or each one
+   fixed or excluded with a stated reason.
+7. **Report gaps, then hand off.** State which gates ran, which were skipped and why. If the
    repo lacks a house script, propose it (see `references/toolchain.md`) and add it **only
    with approval**. → Then go to [`commit-and-release`](../commit-and-release/SKILL.md).
 
@@ -133,6 +141,14 @@ registered there hides exactly the bug the sniff exists to catch. Setting the sn
   dependency change ([`dependency-updates`](../dependency-updates/SKILL.md)), not a fix.
 - **Never** commit `vendor/`, `node_modules/`, or build output unless the repo already
   tracks it — check `.gitignore` and `.distignore` first.
+- **Never** read a green "Plugin Check" tick on a PR as a passing Plugin Check.
+  `wordpress/plugin-check-action` fails the job on *errors* only, so a plugin carrying
+  warnings — the ones WordPress.org review actually raises — shows a passing check. The
+  local run is the one that tells the truth, because it treats any finding as a failure.
+- **Never** assume `composer phpcs` covers Plugin Check. Plugin Check ships its own
+  `PluginCheck.*` sniffs inside the plugin-check plugin; they are not part of the Linchpin
+  standard, so `phpcs.xml.dist` cannot reference them and PHPCS runs green while Plugin
+  Check reports findings. Two gates, not one gate twice.
 - If a tool can't run (not installed, no config, requires Docker that isn't up), **say so
   explicitly**. A silently skipped gate reads as a passing gate.
 
@@ -143,5 +159,7 @@ registered there hides exactly the bug the sniff exists to catch. Setting the sn
 - [ ] JS/CSS gate passed in the owning workspace (or correctly not applicable).
 - [ ] Tests run for touched, covered code.
 - [ ] The changed-file annotation count is zero — warnings included, not just errors.
+- [ ] For a distributed plugin: Plugin Check run **locally** with zero findings, warnings
+      included — not merely a green badge on the PR.
 - [ ] No suppressions, config widenings, or `--no-verify` were used to get green.
 - [ ] Skipped gates and missing house scripts are named in the report.

package/skills/quality-gates/references/toolchain.md

@@ -58,6 +58,120 @@ it; running the root script may silently skip it.
   lint-staged rules deliberately skip.
 - A blocked commit means the gate found something real. Fix the code; never `--no-verify`.
 
+## Plugin Check
+
+Applies to **distributed plugins only** — anything with a plugin header that ships to
+WordPress.org, packagist.linchpin.com, or a client as a zip. Skip it for themes and site
+repos.
+
+### It is not PHPCS, and PHPCS cannot stand in for it
+
+Plugin Check ships its own PHPCS sniffs — the `PluginCheck.*` ruleset — **inside the
+plugin-check plugin**. They are not part of the Linchpin standard, so `phpcs.xml.dist` has
+no way to reference them. `composer run phpcs` therefore runs green on code Plugin Check
+reports on, and no amount of configuring PHPCS closes the gap.
+
+It also runs checks PHPCS has no concept of: readme structure, header fields, the stable
+tag, translations, enqueued-asset rules, image sizes in the zip.
+
+A worked example. This passes `composer run phpcs` and fails Plugin Check:
+
+```php
+// phpcs:disable WordPress.DB.PreparedSQL.NotPrepared, WordPress.DB.DirectDatabaseQuery.DirectQuery
+$ids = $wpdb->get_col( $wpdb->prepare( $sql, ...$values ) );
+```
+
+The `phpcs:disable` names the `WordPress.DB.*` sniffs, because those are the ones the local
+standard has. `PluginCheck.Security.DirectDB.UnescapedDBParameter` is not silenced, is not
+in the local standard, and fires only under Plugin Check.
+
+### A green badge is not a passing check
+
+`wordpress/plugin-check-action` fails the job on Plugin Check **errors** and not on
+**warnings**. A PR can show a passing "Plugin Check" tick while carrying warnings that
+WordPress.org review will raise — the check reports success and uploads the findings to an
+artifact nobody opens.
+
+So the local run is the authority, and it should treat **any finding as a failure**. When
+CI and local disagree here, local is right.
+
+This is the mirror image of *Green locally, red in CI* in
+[`../SKILL.md`](../SKILL.md#green-locally-red-in-ci). There the shared lint workflow
+annotates warnings a clean local run ignored; here CI ignores warnings a strict local run
+catches. Same underlying cause both times — the two ends disagree about what counts as a
+failure, not about what to check — so neither end is trustworthy on its own without knowing
+which way it leans.
+
+To see what CI actually found rather than trusting the tick:
+
+```bash
+gh run view <run-id> --log | grep -A5 'Run Plugin Check'
+gh run download <run-id> -n plugin-check-results   # the findings, in full
+```
+
+### Running it
+
+| Intent | Command |
+| --- | --- |
+| The gate | `composer run plugin-check` |
+| What CI saw | `gh run download <run-id> -n plugin-check-results` |
+
+When the repo has no script, the check needs a built plugin and a WordPress to run in:
+
+```bash
+# 1. Build the distributable — check what ships, not the source tree, or you
+#    get findings from tests/ that never ship and miss what the build breaks.
+composer run build
+
+# 2. Boot WordPress with the *built* plugin mapped in, on a port nothing else holds.
+#    wp-env defaults to 8888/8889, which any other project of yours already owns.
+mkdir -p build/plugin-check && cd build/plugin-check
+cat > .wp-env.json <<'JSON'
+{ "core": null, "plugins": [ "../<slug>" ], "port": 8973, "testsPort": 8974 }
+JSON
+npx wp-env start
+
+# 3. Check it, with the same flags as the workflow.
+npx wp-env run cli wp plugin install plugin-check --activate
+npx wp-env run cli wp plugin check <slug> \
+  --categories=general,performance,accessibility,security,plugin_repo \
+  --include-experimental \
+  --format=csv
+```
+
+Keep `--categories` and `--exclude-checks` in step with
+`.github/workflows/plugin-check.yml`. Two sets of flags that drift are two different gates,
+and the PR is judged by the one you did not run.
+
+### A finding you have decided to accept
+
+Some findings are architectural and correct — a migration tool that queries `wp_posts`
+directly because the post type it must reach is no longer registered, for instance. Those
+do not get a silent pass:
+
+1. Add the check id to `--exclude-checks` in **both** the local script and the workflow.
+2. Comment the reason where the exclusion lives, not in a commit message.
+3. Say so in the PR, because WordPress.org review will ask the same question.
+
+`stable_tag_mismatch` / `no_stable_tag` / `trunk_stable_tag` are the standard exclusions on
+a pre-release branch: release-please stamps the version on release, so before one the built
+`readme.txt` legitimately trails the tag.
+
+### The house script
+
+```jsonc
+// composer.json
+"scripts": {
+  "plugin-check": "bash scripts/plugin-check.sh"
+}
+```
+
+The script builds, boots wp-env against the built artifact, installs plugin-check, runs it
+with the workflow's flags, and **exits non-zero on any finding**. `linchpin/block-alchemy`
+carries the reference implementation. It needs `@wordpress/env` in `devDependencies` and
+Docker running; both are worth stating in the failure message, because a missing Docker
+looks like a passing gate otherwise.
+
 ## The house script set
 
 When a repo is missing these, propose adding them — matching the repo's existing tooling,