docs(conventions): add plugin-data-reports keying convention

[kyle-sexton]

Fixes #2278.

Adds docs/conventions/plugin-data-reports/ governing how plugins name, key, retain, and overwrite artifacts under ${CLAUDE_PLUGIN_DATA}. Registers the convention in PLUGIN-PHILOSOPHY.md. Adoptions for audit-instructions and claude-memory:audit remain tracked in #2276 and #2277.

Related

• convention: no rule governs report keying, retention, or overwrite under CLAUDE_PLUGIN_DATA #2278

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 84a01d2e17

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude finished @kyle-sexton's task in 2m 30s —— View job

---

Claude Code Review

• Gather context (diff, CLAUDE.md, REVIEW.md)
• Understand the request (code review of this PR)
• Review changed files for correctness and alignment with conventions
• Post findings

Summary

This PR is superseded by already-merged work. PR #2335 (commit 970cfea, merged 2026-08-12T00:17 — four hours before this PR's commit at 03:42) closes the same issue (#2278) this PR targets, plus the two adoption issues (#2276, #2277) this PR's Adopters table lists as pending.

What's on main right now, that this branch doesn't have:

• docs/conventions/plugin-data-report-keying/README.md — a more complete version of this convention (adds Rule 2 retention-by-read-back, Rule 4 uninstall fragility, a shared lib/state-key.sh implementation with a 23-case test suite, and a fuller adoption table).
• docs/PLUGIN-PHILOSOPHY.md registry already has a row for it: main:docs/PLUGIN-PHILOSOPHY.md#L481.
• claude-config:audit-instructions and claude-memory:audit are both already keyed (closing fix(claude-config): audit-instructions writes one machine-global last-audit.md, then computes a token delta against another project's report #2276, fix(claude-memory): audit reads back a machine-global last-audit.md, so report and fix modes can serve another repository's findings #2277) — the two rows this PR's Adopters table still marks "pending" (flagged inline).

If merged as-is, this PR would land a second, competing convention doc at a different path (plugin-data-reports/ vs. plugin-data-report-keying/) with a second, differently-worded registry row describing the same rule, and stale claims about adoption status that are no longer true.

Recommendation: rebase this branch onto current main and either (a) close this PR as superseded/duplicate since #2335 already delivers a more complete version of the same convention, or (b) if this branch has content worth preserving beyond what #2335 shipped, fold it into docs/conventions/plugin-data-report-keying/ rather than publishing a second doc. Rework this PR →

Smaller notes

• The doc's own content (README + CHANGELOG) is well-written and internally consistent — the bug-report:write Step 2 anti-pattern reference checks out against the actual skill file, the registry row is alphabetically placed correctly, and the scheme description matches the audit-pass original. These are moot only because of the duplication above.

[github-actions]

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[kyle-sexton]

Superseded: docs/conventions/plugin-data-report-keying/ landed on main via #2335 with the same scope (#2278). Keeping one canonical convention path.