docs(rules): fix stale 5-plugin claims and make plugin inventory drift-resistant (#557)

* docs: fix stale 5-plugin claims and make inventory drift-resistant

.claude/rules/plugin-docs.md is loaded into every session's context, so its
"## The 5 Plugins" section was actively steering plugin work away from
claude-setup, skill-management, and spec-workflow. The repo has had 8 plugins
for some time; the root CLAUDE.md already said 8, so the two contradicted
each other.

Rather than just correcting 5 to 8 (which drifts again on the next addition),
both files now name packages/plugins/ and .claude-plugin/marketplace.json as
the source of truth, give an enumeration command, and state that the
enumerated output wins over the inline snapshot.

- plugin-docs.md: rewrite "The 5 Plugins" as "The Plugins" with a
  source-of-truth block, an enumeration command, a one-line parity check
  between the directories and marketplace.json, and a dated snapshot that
  readers are told to repair on mismatch
- plugin-docs.md: "Each of the 5 plugins has its own section" -> "Each plugin"
- CLAUDE.md: same de-hardcoding for the inventory bullet and the same
  "Each of the 5 plugins" phrasing in the Notion sync section

Left .plan/DEV-218-implementation.md alone: its "5 plugins" is a point-in-time
justification in a completed migration plan, and rewriting it would make it
wrong about the state it describes.

No files under packages/plugins/ changed, so no plugin version bump applies.

* docs: check marketplace source paths, not just names, in parity check

The parity check compared .plugins[].name against the directory names. That
passes even when an entry's `source` is stale or copy-pasted, because `name`
is not the field that determines what loads.

.github/actions/validate-plugins/action.yml:64-71 resolves .plugins[i].source
into PLUGIN_PATH and validates that path; `name` is only used for log output.
So an entry named `foo` whose source still points at `./packages/plugins/
skill-management` makes the validator check skill-management twice while `foo`
goes unreferenced - and the old check certified that as parity.

Reproduced against a scratch fixture: names-vs-dirs passed, sources-vs-dirs
caught it.

Replaced with two checks: (1) resolved source paths against the directories on
disk, (2) each entry's name against its own source basename. Both verified
silent against the current marketplace.json, and executed verbatim as
extracted from the rendered file to confirm the jq escapes survive prettier.

Author: wkoutre

.claude/rules/plugin-docs.md

@@ -16,7 +16,7 @@ After ANY changes to `packages/plugins/`, you MUST update the Notion Plugin Mark
 
 1. **Plugin inventory changes**: When skills, agents, commands, or MCP servers are added, removed, or renamed
 2. **Component counts**: The overview section shows totals for Skills, Agents, and Commands - keep these accurate
-3. **Per-plugin sections**: Each of the 5 plugins has its own section listing components - update the relevant section(s)
+3. **Per-plugin sections**: Each plugin has its own section listing components - update the relevant section(s)
 4. **Descriptions**: Update component descriptions when functionality changes significantly
 
 ### 2. Update Plugin CLAUDE.md Files
@@ -36,15 +36,47 @@ Before completing plugin-related work, verify:
 - [ ] Plugin `CLAUDE.md` reflects current structure
 - [ ] Notion marketplace doc is updated (if inventory changed)
 
-## The 5 Plugins
+## The Plugins
 
-For reference, these are the plugin directories:
+**Source of truth**: the directories under `packages/plugins/` and the `plugins` array in
+`.claude-plugin/marketplace.json`. Never rely on a count written in prose - including the
+snapshot below. Enumerate before acting:
 
-1. `packages/plugins/development-planning/`
-2. `packages/plugins/development-pr-workflow/`
-3. `packages/plugins/development-codebase-tools/`
-4. `packages/plugins/development-productivity/`
-5. `packages/plugins/uniswap-integrations/`
+```bash
+find packages/plugins -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | sort
+```
+
+The two must always agree: every plugin directory needs a matching `marketplace.json` entry, and
+vice versa. Check `source`, not just `name` - `.github/actions/validate-plugins/action.yml`
+resolves `.plugins[].source` to decide which directory to load and validate, so a copied or stale
+`source` points the marketplace at the wrong directory even when `name` looks right. Two checks:
+
+```bash
+# 1. Every source resolves to a real plugin directory, and every directory is referenced once.
+diff <(find packages/plugins -mindepth 1 -maxdepth 1 -type d | sort) \
+     <(jq -r '.plugins[].source | sub("^\\./"; "")' .claude-plugin/marketplace.json | sort)
+
+# 2. Every entry's name agrees with its own source directory.
+jq -r '.plugins[] | select((.source | sub("^\\./packages/plugins/"; "")) != .name)
+       | "MISMATCH: name=\(.name) source=\(.source)"' .claude-plugin/marketplace.json
+```
+
+Both silent means the inventory is consistent. Any output means it is not - fix that before
+continuing.
+
+**Snapshot** (accurate as of 2026-07-30, verify with the commands above):
+
+1. `packages/plugins/claude-setup/`
+2. `packages/plugins/development-codebase-tools/`
+3. `packages/plugins/development-planning/`
+4. `packages/plugins/development-pr-workflow/`
+5. `packages/plugins/development-productivity/`
+6. `packages/plugins/skill-management/`
+7. `packages/plugins/spec-workflow/`
+8. `packages/plugins/uniswap-integrations/`
+
+If the enumerated output above differs from this snapshot, the enumerated output wins - update
+this snapshot (and the plugin table in the root `CLAUDE.md`) as part of your change.
 
 ## When to Skip Notion Updates
 

CLAUDE.md

@@ -163,7 +163,8 @@ The repository uses a plugin-based architecture where Claude Code capabilities a
 - Plugins are stored in `./packages/plugins/<plugin-name>/`
 - Each plugin is a self-contained Nx package with its own `package.json`, `project.json`, and `.claude-plugin/plugin.json`
 - The `.claude-plugin/marketplace.json` file references plugins via relative paths: `"./packages/plugins/<plugin-name>"`
-- There are 8 plugins: claude-setup, development-codebase-tools, development-planning, development-pr-workflow, development-productivity, skill-management, spec-workflow, uniswap-integrations
+- The authoritative plugin inventory is the set of directories under `packages/plugins/` and the `plugins` array in `.claude-plugin/marketplace.json` - the two must always agree. Enumerate rather than trusting a count written in prose: `find packages/plugins -mindepth 1 -maxdepth 1 -type d -exec basename {} \; | sort`. See `.claude/rules/plugin-docs.md` for the parity check.
+- As of 2026-07-30 there are 8 plugins: claude-setup, development-codebase-tools, development-planning, development-pr-workflow, development-productivity, skill-management, spec-workflow, uniswap-integrations. If the enumerated output differs, it wins - update this list and the table below.
 
 **Plugin Validation:**
 
@@ -364,7 +365,7 @@ After making any changes to files in this repository, Claude Code MUST:
 
 3. **Keep stats accurate**: The overview section contains counts of total Skills, Agents, and Commands - ensure these numbers stay accurate
 
-4. **Maintain per-plugin sections**: Each of the 5 plugins has its own section listing components - update the relevant section(s) when plugins change
+4. **Maintain per-plugin sections**: Each plugin has its own section listing components - update the relevant section(s) when plugins change
 
 This ensures the external documentation stays synchronized with the actual plugin codebase.