wordpress-agent-kit 0.3.0 → 0.4.0

package/.github/skills/wp-abilities-verify/references/schema-lints.md

@@ -0,0 +1,118 @@
+# Schema Lints
+
+Static lints against an ability's `input_schema`. Schema hygiene is
+about *agent legibility*: orchestrating agents read the schema to
+figure out how to call the ability. A schema that's hard to parse,
+ambiguous, or misleading wastes turns even when the ability itself
+works.
+
+These lints are six small principles. Apply them by reading the
+schema, not by mechanically grepping — most plugins use enough
+formatting variety that grep recipes drift.
+
+## Lint 1 — `additionalProperties: false` for object schemas
+
+For top-level `'type' => 'object'` schemas, declare
+`'additionalProperties' => false` unless you deliberately accept
+extras. Without this, an agent passing a typo (`par_page` instead of
+`per_page`) gets accepted silently and falls through to the backing,
+which ignores the unknown key.
+
+- `additionalProperties: false` declared → OK.
+- `additionalProperties: true` declared → WARN, unless the schema is
+  for genuinely free-form metadata (payment custom fields, form
+  free-text); document the reason inline.
+- Not declared on an object schema → WARN.
+- Non-object root (string with enum, integer, etc.) → N/A. The lint
+  applies only to objects.
+
+## Lint 2 — every required field has a non-empty description
+
+For each entry in `required`, the matching `properties` entry must
+declare a non-empty `description`. Required fields are where agents
+most need guidance; an opaque required key forces the agent to guess
+from the field name alone. Empty / missing → FAIL.
+
+Optional-field descriptions are nice-to-have — absence is WARN.
+
+## Lint 3 — enums are non-empty
+
+`'enum' => []` accepts no values, rejecting every input. Almost always
+a bug. → FAIL.
+
+A single-value enum (`'enum' => [ 'pending' ]`) is legal but unusual;
+WARN and prompt for review — often a copy-paste that lost the other
+values.
+
+## Lint 4 — no `$ref`
+
+Agents read the schema via REST introspection. A `$ref` forces the
+agent to follow a reference to see the field shape — wastes a turn and
+often breaks because the referenced schema isn't in the same document.
+Inline the shape instead.
+
+Any `'$ref'` in the schema → FAIL.
+
+## Lint 5 — defaults are statically constant
+
+Each `'default'` value must evaluate to the same shape on every call:
+
+- Scalar literals — `true`, `false`, integer, float, quoted string,
+  `null` → OK.
+- Empty or all-literal arrays — `[]`, `array()`, `[ 'a', 'b' ]` → OK.
+- Literal cast to an empty object — `(object) array()`, `(object) []`
+  → OK. This is the recommended top-level default for zero-arg-allowed
+  abilities; see
+  `../../wp-abilities-api/references/input-schema-gotchas.md` §4.
+- `new stdClass()` with no arguments → OK.
+- A function call (`gmdate('c')`, `wp_generate_uuid4()`, `time()`),
+  variable reference, or other computed expression → FAIL.
+
+The principle: defaults that vary per call are both non-deterministic
+and surprising to agents that expect defaults to be static.
+
+## Lint 6 — `reference_ability: true` implies no required inputs
+
+If an audit doc is provided and an ability has
+`reference_ability: true`, its `input_schema.required` array must be
+empty or absent. The reference ability is the smallest, safest
+bootstrap call an implementer lands first; it must work with
+`execute([])`. Required inputs on the reference ability → FAIL.
+
+(No audit provided → this lint is skipped — no reference ability is
+declared.)
+
+## Cross-reference: gotchas 1-3 (callback hardening) and gotcha 4 (structural default)
+
+Static lints catch shape; the four runtime gotchas in
+`../../wp-abilities-api/references/input-schema-gotchas.md` split into
+two kinds.
+
+Gotchas 1-3 need defensive code in the execute callback —
+`array_key_exists` instead of `isset`-only for property defaults,
+pagination key translation, ID validation that accepts `"0"`. These
+are runtime behaviors the callback itself must handle; static schema
+lints can't enforce them.
+
+Gotcha 4 — the direct vs indirect invocation strictness — is what
+motivates the `(object) array()` top-level default that Lint 5
+explicitly accepts. This one IS structural and Lint 5 carries the
+enforcement.
+
+## Output format
+
+```markdown
+## Schema lints
+
+| Ability | Lint | Result | Detail |
+|---|---|---|---|
+| <ability> | additionalProperties (object schemas) | WARN | not declared on object schema |
+| <ability> | required-field descriptions | OK | 3/3 required fields documented |
+| <ability> | enum non-empty | OK | no enums |
+| <ability> | no $ref | OK | inline |
+| <ability> | static defaults | FAIL | `created_at` uses `gmdate('c')` |
+| <ability> | reference_ability implies no required | N/A | not reference ability |
+```
+
+A FAIL on any lint flips that ability to FAIL in the run summary.
+WARNs surface but don't block.

package/.github/skills/wp-abilities-verify/references/static-enumeration.md

@@ -0,0 +1,126 @@
+# Static Enumeration
+
+Enumerate a plugin's abilities from source, with no running
+environment. Static enumeration is necessarily best-effort — PHP's
+dynamism (variable indirection, runtime-conditional registration)
+means a complete inventory only comes from a live `wp_get_abilities()`
+call. When static and runtime inventories diverge, trust runtime;
+static drives the diff so the reviewer knows where to look.
+
+## Typical registration shape
+
+```php
+wp_register_ability(
+    '<plugin-slug>/<ability-name>',
+    array(
+        'label'               => __( '...', '<text-domain>' ),
+        'description'         => __( '...', '<text-domain>' ),
+        'category'            => '<category-slug>',
+        'input_schema'        => array( /* ... */ ),
+        'execute_callback'    => array( self::class, 'execute_my_ability' ),
+        'permission_callback' => array( self::class, 'check_permission' ),
+        'meta'                => array(
+            'annotations' => array(
+                'readonly'    => true,
+                'destructive' => false,
+                'idempotent'  => true,
+            ),
+            'show_in_rest' => true,
+        ),
+    )
+);
+```
+
+## Step 1 — find every registration call
+
+```bash
+grep -rn --include='*.php' 'wp_register_ability\s*(' <plugin-root>/
+```
+
+Zero hits → return a clear "no abilities registered" report per
+SKILL.md "Failure modes." Don't fabricate an empty inventory.
+
+## Step 2 — extract each ability name
+
+The first argument is the ability name — usually a literal string.
+Real-world formatting splits the call across lines (the example
+above is itself multi-line), so single-line regexes miss common
+cases. Use a multi-line tool:
+
+```bash
+# ripgrep with --multiline + PCRE2 captures the name regardless of line break:
+rg --multiline --pcre2 --type=php -n \
+   "wp_register_ability\s*\(\s*['\"]([^'\"]+)['\"]" <plugin-root>/
+
+# Fallbacks: pcregrep -M, perl -0777.
+```
+
+If the first argument is a variable or constant
+(`wp_register_ability( $name, ... )`,
+`wp_register_ability( MyPlugin\NAME, ... )`), trace it: a recent
+assignment in the same function or a class constant usually resolves;
+a name computed in a loop won't, in which case flag the limitation and
+recommend runtime mode for authoritative enumeration.
+
+## Step 3 — extract the annotation block
+
+Annotations live at `meta.annotations.{readonly,destructive,idempotent}`.
+For each registration, read the array literal forward until the
+matching close. Common shapes:
+
+- Multi-line literal (most common).
+- Short-form one-liner.
+- Helper method (`'annotations' => self::annotations_for_read()`) —
+  resolve the helper if it returns a literal; otherwise mark
+  `<unresolved>` and run the adversarial check against the callback
+  alone.
+- Class constant (`'annotations' => self::READONLY_ANNOTATIONS`) —
+  resolve the constant.
+
+Record `ability_name → declared_annotations`.
+
+## Step 4 — follow `execute_callback` to its body
+
+`execute_callback` is one of:
+
+```php
+'execute_callback' => array( self::class, 'execute_get_things' ),
+'execute_callback' => array( My_Class::class, 'execute_get_things' ),
+'execute_callback' => array( $this, 'execute_get_things' ),
+'execute_callback' => 'my_plugin_execute_get_things',  // top-level function
+'execute_callback' => function ( $input ) { /* ... */ },  // closure
+```
+
+Resolve the reference to its source location: file + start line + end
+line. The annotation-correctness, schema-lint, and permission checks
+all operate on that byte range.
+
+## Limits of static enumeration
+
+Cases where the inventory is incomplete or ambiguous:
+
+- Variable-indirected names (`foreach` over a slug list).
+- Variable-indirected annotations (built from config).
+- Conditional registration (`if ( feature_enabled() )`).
+- Variable-indirected callbacks (`array( $this, $callback_name )`).
+
+Record each in the report's "Static enumeration limitations" section
+and recommend a runtime-mode rerun for the authoritative inventory.
+
+## Output format
+
+```markdown
+## Static inventory
+
+Found <N> ability registrations across <M> files:
+
+| Ability | Source file | Registration line | Callback file | Callback lines |
+|---|---|---|---|---|
+| myplugin/get-foo | src/Abilities.php | 42 | src/Abilities.php | 102-134 |
+| myplugin/submit-bar | src/Abilities.php | 68 | src/Services/Bar.php | 58-91 |
+
+### Limitations
+
+- <ability>: annotations built dynamically in `annotations_for_read()`;
+  recommend runtime mode for annotation cross-check.
+```

package/.github/skills/wp-playground/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wp-playground
-description: "Use for WordPress Playground workflows: fast disposable WP instances in the browser or locally via @wp-playground/cli (server, run-blueprint, build-snapshot), auto-mounting plugins/themes, switching WP/PHP versions, blueprints, and debugging (Xdebug)."
+description: "Use for WordPress Playground workflows: fast disposable WP instances in the browser or locally via @wp-playground/cli (server, run-blueprint, build-snapshot), auto-mounting plugins/themes, switching WP/PHP versions, blueprints, PHPUnit testing, E2E Playwright testing, programmatic runCLI API, and debugging (Xdebug)."
 license: GPL-2.0-or-later
 compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Playground CLI requires Node.js 20.18+; runs WP in WebAssembly with SQLite."
 ---
@@ -14,6 +14,9 @@ compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+). Playground CLI requires No
 - Build a reproducible snapshot of a site for sharing or CI.
 - Switch WP/PHP versions quickly to reproduce issues.
 - Debug plugin/theme code with Xdebug in an isolated Playground.
+- Run PHPUnit tests without a local database (no Docker, no MySQL).
+- Write E2E Playwright tests against a real WordPress instance.
+- Automate Playground in CI/CD pipelines via the programmatic `runCLI` API.
 
 ## Inputs required
 
@@ -82,6 +85,134 @@ npx @wp-playground/cli@latest build-snapshot --blueprint=<file> --outfile=./site
   - Query: `https://playground.wordpress.net/?blueprint-url=<public-url-or-zip>`
 - Use the live Blueprint Editor (playground.wordpress.net) to author blueprints with schema help; paste JSON and copy a shareable link.
 
+### 8) PHPUnit testing (no database required)
+
+Run PHPUnit inside Playground — every run starts with a clean WordPress install, fully isolated.
+
+Plugin:
+```bash
+npx @wp-playground/cli@latest php \
+  --auto-mount \
+  -- \
+  /wordpress/wp-content/plugins/MY_PLUGIN/vendor/bin/phpunit \
+  -c /wordpress/wp-content/plugins/MY_PLUGIN/phpunit.xml.dist
+```
+
+Theme (replace `plugins/` with `themes/`):
+```bash
+npx @wp-playground/cli@latest php \
+  --auto-mount \
+  -- \
+  /wordpress/wp-content/themes/MY_THEME/vendor/bin/phpunit \
+  -c /wordpress/wp-content/themes/MY_THEME/phpunit.xml.dist
+```
+
+- Requires PHPUnit installed via Composer in the project (`composer require --dev phpunit/phpunit`).
+- `--auto-mount` maps the current directory to the correct WP content path automatically.
+- Use `--php=8.1 --wp=6.5` flags to test against specific versions (PHP 7.4–8.5 supported).
+- Explicit mount: `--mount=.:/wordpress/wp-content/plugins/MY_PLUGIN`.
+
+### 9) E2E testing with Playwright
+
+Use `runCLI` from `@wp-playground/cli` to start a Playground server programmatically in Playwright tests. No Docker, no database.
+
+Install:
+```bash
+npm install --save-dev @playwright/test @wp-playground/cli
+npx playwright install chromium
+```
+
+Minimal `playwright.config.ts`:
+```ts
+import { defineConfig } from '@playwright/test';
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: false,
+  workers: 1,           // prevent port conflicts
+  timeout: 120_000,     // WP boot takes time
+  expect: { timeout: 30_000 },
+  use: { screenshot: 'only-on-failure', trace: 'on-first-retry' },
+});
+```
+
+First test (`tests/e2e/plugin.spec.ts`):
+```ts
+import { test, expect } from '@playwright/test';
+import { runCLI } from '@wp-playground/cli';
+
+let cli: Awaited<ReturnType<typeof runCLI>>;
+
+test.beforeAll(async () => {
+  cli = await runCLI({
+    command: 'server',
+    blueprint: {
+      preferredVersions: { php: '8.3', wp: 'latest' },
+      login: true,
+    },
+  });
+});
+
+test.afterAll(async () => { await cli?.server?.close(); });
+
+test('dashboard loads', async ({ page }) => {
+  await page.goto(`${cli.serverUrl}/wp-admin/`);
+  await expect(page.locator('#wpbody-content')).toBeVisible();
+});
+```
+
+Mount a local plugin:
+```ts
+cli = await runCLI({
+  command: 'server',
+  mount: { './': '/wordpress/wp-content/plugins/my-plugin' },
+  blueprint: {
+    preferredVersions: { php: '8.3', wp: 'latest' },
+    login: true,
+    steps: [{ step: 'activatePlugin', pluginPath: 'my-plugin/my-plugin.php' }],
+  },
+});
+```
+
+Locator priority (most to least preferred):
+1. `page.getByRole()` — buttons, headings, links, inputs
+2. `page.getByLabel()` — labeled form fields
+3. `page.getByText()` — visible text
+4. `page.getByTestId()` — your own `data-testid` attributes
+5. `page.locator()` — CSS/XPath last resort (WP core layout elements like `#wpadminbar`)
+
+Version matrix pattern:
+```ts
+const matrix = [{ php: '8.1', wp: '6.5' }, { php: '8.3', wp: 'latest' }];
+for (const { php, wp } of matrix) {
+  test.describe(`PHP ${php} + WP ${wp}`, () => {
+    // ... beforeAll/afterAll with those versions
+  });
+}
+```
+
+CI (GitHub Actions): see `references/e2e-playwright.md`.
+
+### 10) Programmatic `runCLI` API (scripts / Vitest integration)
+
+```ts
+import { runCLI } from '@wp-playground/cli';
+
+const server = await runCLI({
+  command: 'server',
+  php: '8.3',
+  wp: 'latest',
+  login: true,
+  mount: [{ hostPath: './my-plugin', vfsPath: '/wordpress/wp-content/plugins/my-plugin' }],
+  blueprint: { steps: [{ step: 'activatePlugin', pluginPath: 'my-plugin/plugin.php' }] },
+});
+
+// server.serverUrl — the base URL
+// server.server — the HTTP server instance (call .close() in afterEach)
+// server[Symbol.asyncDispose]() — cleanup in Vitest afterEach
+```
+
+Use `wordpressInstallMode: 'do-not-attempt-installing'` + `skipSqliteSetup: true` when testing pure PHP with no WordPress overhead.
+
 ## Verification
 
 - Verify mounted code is active (plugin listed/active; theme selected).

package/.github/skills/wp-playground/references/e2e-playwright.md

@@ -0,0 +1,115 @@
+# E2E Testing with Playwright + WordPress Playground
+
+## Install
+
+```bash
+npm install --save-dev @playwright/test @wp-playground/cli
+npx playwright install chromium
+```
+
+## playwright.config.ts
+
+```ts
+import { defineConfig } from '@playwright/test';
+export default defineConfig({
+  testDir: './tests/e2e',
+  fullyParallel: false,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: 1,
+  reporter: 'html',
+  timeout: 120_000,
+  expect: { timeout: 30_000 },
+  use: { screenshot: 'only-on-failure', trace: 'on-first-retry' },
+});
+```
+
+## Server lifecycle
+
+**Shared** (faster, tests can affect each other — use for read-only tests):
+```ts
+test.beforeAll(async () => { cli = await runCLI({ command: 'server', blueprint }); });
+test.afterAll(async () => { await cli?.server?.close(); });
+```
+
+**Per-test** (isolated, slower — use when tests modify state):
+```ts
+test.beforeEach(async () => { cli = await runCLI({ command: 'server', blueprint }); });
+test.afterEach(async () => { await cli?.server?.close(); });
+```
+
+## Blueprint fixtures
+
+Installing from wordpress.org:
+```ts
+steps: [{ step: 'installPlugin', pluginData: { resource: 'wordpress.org/plugins', slug: 'contact-form-7' } }]
+```
+
+Creating content:
+```ts
+steps: [{ step: 'runPHP', code: `<?php require '/wordpress/wp-load.php'; wp_insert_post([...]);` }]
+```
+
+## WordPress-specific locator guidance
+
+- `page.getByRole('button', { name: 'Save Changes' })` — works for standard WP buttons
+- `page.getByLabel('API Key')` — works for labeled form fields
+- `page.locator('#wpadminbar')` — CSS required for WP core layout elements (no ARIA)
+- Add `data-testid` to your own plugin markup for stable selectors
+- Run `npx playwright codegen localhost:9400/wp-admin/` to auto-generate locators
+
+## Page Object Model
+
+```ts
+// tests/e2e/pages/plugin-settings.ts
+export class PluginSettingsPage {
+  constructor(readonly page: Page) {}
+  async goto(baseUrl: string) { await this.page.goto(`${baseUrl}/wp-admin/options-general.php?page=my-plugin`); }
+  async setApiKey(key: string) {
+    await this.page.getByLabel('API Key').fill(key);
+    await this.page.getByRole('button', { name: 'Save Changes' }).click();
+  }
+  async expectSaved() { await expect(this.page.getByText('Settings saved')).toBeVisible(); }
+}
+```
+
+## GitHub Actions CI
+
+```yaml
+name: E2E Tests
+on:
+  push: { branches: [main] }
+  pull_request: { branches: [main] }
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, cache: 'npm' }
+      - run: npm ci
+      - uses: actions/cache@v4
+        id: playwright-cache
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ hashFiles('package-lock.json') }}
+      - if: steps.playwright-cache.outputs.cache-hit != 'true'
+        run: npx playwright install chromium --with-deps
+      - run: npx playwright test
+      - uses: actions/upload-artifact@v4
+        if: ${{ !cancelled() }}
+        with: { name: playwright-report, path: playwright-report/, retention-days: 30 }
+```
+
+## Troubleshooting
+
+- **Timeout errors** — increase `timeout` in config; CI needs 120–180s
+- **Port conflicts** — don't hardcode ports; use `cli.serverUrl`
+- **Browser not found** — run `npx playwright install chromium`
+- **Passes locally, fails CI** — increase timeouts, ensure `workers: 1`
+- **Debug** — `npx playwright test --debug` or `--ui` for interactive mode
+
+## Docs
+
+- https://wordpress.github.io/wordpress-playground/guides/e2e-testing-with-playwright
+- https://wordpress.github.io/wordpress-playground/guides/programmatic-playground-cli

package/.github/skills/wp-plugin-directory-guidelines/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: wp-plugin-directory-guidelines
+description: "Use when reviewing WordPress plugins for GPL compliance, checking license headers or compatibility, evaluating upsell/freemium/trialware patterns, validating plugin naming or trademark rules, checking plugin slugs, understanding why a plugin was rejected from WordPress.org, or answering any question about the 18 WordPress.org Plugin Directory guidelines — even if the user doesn't mention 'guidelines' explicitly."
+license: GPL-2.0-or-later
+compatibility: "Targets WordPress 6.9+ (PHP 7.2.24+)."
+---
+
+## Overview
+
+Authoritative reference for the 18 WordPress.org Plugin Directory guidelines. Covers GPL licensing, plugin naming/trademark rules, trialware restrictions, and all other submission requirements.
+
+## When to use
+
+Use this skill when you need to:
+- Review a WordPress plugin for compliance with the WordPress.org Plugin Directory guidelines
+- Check GPL license compatibility for a plugin or its bundled libraries
+- Verify license headers in plugin files
+- Identify common guideline violations before submission
+- Answer questions about what is or is not allowed on WordPress.org
+- Evaluate premium/upsell flows, license checks, or freemium positioning
+- Review "teaser" or "preview" UI for trialware violations
+
+## Inputs required
+
+- Plugin source code (or specific files to review)
+- Optional: plugin readme and plugin header metadata for naming and license checks
+
+## Procedure
+
+1. Check the plugin's license header against the **Valid License Headers** section below.
+2. Walk through the **18 Guidelines** checklist, paying special attention to Guidelines 1, 4, 5, 7, 8, and 17.
+3. Confirm trialware/freemium compliance using the checklist in [guideline-review-checklist.md](references/guideline-review-checklist.md) (Guideline 5 section).
+4. For bundled third-party code, verify license compatibility against **GPL-Compatible Licenses (Quick)** below.
+5. Flag matches from **Common GPL Violations (Quick)** below.
+6. For edge cases, consult the detailed references and the [GNU GPL FAQ](https://www.gnu.org/licenses/gpl-faq.html).
+
+## 18-Guideline Review Checklist
+
+Use the detailed, per-guideline checklist in [guideline-review-checklist.md](references/guideline-review-checklist.md). Load this reference file only when a full guideline audit is requested.
+
+## GPL Compliance (Guideline 1 in Detail)
+
+Use [gpl-compliance.md](references/gpl-compliance.md) for full license tables, compatibility nuances, and examples. Keep this inline section as a quick decision aid.
+
+### Verification (Licensing)
+
+- Every licensing-related issue must cite **Guideline 1** and include the file path and exact license string.
+- Confirm compatibility claims against **GPL-Compatible Licenses (Quick)** and escalate ambiguous licenses.
+
+### Failure modes (Licensing)
+
+- If a license is not clearly GPL-compatible, do not guess. Check the [GNU license list](https://www.gnu.org/licenses/license-list.html).
+- For dual-license packages, verify both licenses and redistribution terms.
+
+### Quick Reference: WordPress GPL Requirements
+
+- WordPress is **GPLv2 or later**.
+- Plugins distributed on WordPress.org must be 100% GPL-compatible (code and assets).
+- Include a valid `License:` header and `License URI:` in the main plugin file.
+- Do not add restrictions that conflict with GPL freedoms.
+
+### Valid License Headers
+
+## GPL Versions Summary
+
+| Version | Year | Key Addition |
+|---------|------|--------------|
+| GPLv1 | 1989 | Base copyleft: share-alike for modifications |
+| GPLv2 | 1991 | "Liberty or death" clause (Section 7), clearer distribution terms |
+| GPLv3 | 2007 | Anti-tivoization, explicit patent grants, compatibility provisions |
+
+WordPress uses **GPLv2 or later**, meaning plugins can use GPLv2, GPLv3, or "GPLv2 or later".
+
+For full license texts, see:
+- [GNU General Public License v1](https://www.gnu.org/licenses/gpl-1.0.html)
+- [GNU General Public License v2](https://www.gnu.org/licenses/gpl-2.0.html)
+- [GNU General Public License v3](https://www.gnu.org/licenses/gpl-3.0.html)
+
+## License Compliance Checklist
+
+When reviewing a plugin, verify:
+
+- [ ] Main plugin file has a valid `License:` header (e.g., `GPL-2.0-or-later`, `GPL-2.0+`, `GPLv2 or later`)
+- [ ] Main plugin file has a `License URI:` header pointing to the GPL text
+- [ ] If bundled libraries exist, each has a GPL-compatible license
+- [ ] No "split licensing" (e.g., code GPL but premium features proprietary)
+- [ ] No additional restrictions beyond what GPL allows
+- [ ] No clauses restricting commercial use, modification, or redistribution
+- [ ] No obfuscated code (violates the spirit of source code availability)
+
+## Valid License Headers for WordPress Plugins
+
+```
+License: GPL-2.0-or-later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+```
+
+```text
+License: GPL-3.0-or-later
+License URI: https://www.gnu.org/licenses/gpl-3.0.html
+```
+
+```text
+License: GPLv2 or later
+License URI: https://www.gnu.org/licenses/gpl-2.0.html
+```
+
+### GPL-Compatible Licenses (Quick)
+
+- Safe defaults: GPL-2.0-or-later, GPL-3.0-or-later.
+- Commonly accepted permissive families: MIT/Expat, BSD, ISC, zlib, Boost.
+- Conditional compatibility requires care: Apache-2.0 and MPL-2.0 (verify usage context).
+- For full accepted and rejected identifiers, use [gpl-compliance.md](references/gpl-compliance.md).
+
+### Common GPL Violations (Quick)
+
+- Split licensing that restricts distributed code.
+- Obfuscated or non-corresponding source distribution.
+- Restrictive clauses (non-commercial, no-resale, forced backlink).
+- Bundling GPL-incompatible libraries or assets.
+
+## Plugin Naming Rules (Guideline 17)
+
+Use [naming-rules.md](references/naming-rules.md) for full trademark lists, slug blocks, and naming examples. Keep this inline checklist for quick screening.
+
+### Naming Checklist (Quick)
+
+- Name is not a placeholder and has at least 5 alphanumeric characters.
+- Header name and readme name match.
+- Name is specific and function-related; avoid keyword stuffing.
+- Trademark/project names appear only after connectors like `for`, `with`, `using`, `and`.
+- No banned/discouraged terms or trademark portmanteaus.
+- Slug is lowercase, hyphenated, <= 50 chars, and avoids blocked terms.