fix(architecture): correct improve Gotcha on CLAUDE_PLUGIN_DATA

[kyle-sexton]

Fixes #2207.

Related

• fix(architecture): improve's Gotcha asserts ${CLAUDE_PLUGIN_DATA} does not substitute in skill content — plugins-reference says it does #2207 — CLAUDE_PLUGIN_DATA improve Gotcha correction

[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.

[claude]

Claude finished @kyle-sexton's task in 23s —— View job

---

Security Review

Scope: plugins/architecture/CHANGELOG.md and plugins/architecture/skills/improve/SKILL.md (both changed files in this PR).

• Fetch PR diff (origin/main...HEAD)
• Review changed files for security issues
• Report findings

Result: No security issues found.

This PR is a documentation-only change (+8/-1 across a CHANGELOG entry and one sentence in a skill's "Gotchas" section). It clarifies why ${CLAUDE_PLUGIN_DATA} is the wrong location for per-project durable artifacts — no code, scripts, workflows, or configuration are touched, so there's no injection surface, no credential/token handling, no authorization logic, and no GitHub Actions trigger/permission changes to evaluate.

Notably, the added text itself reinforces good security hygiene by explaining that .claude/ generated output must stay out of version control (avoiding leaking scan output into git) — consistent with the change's intent rather than introducing any new risk.

No findings to report at any severity.

[claude]

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

---

Code review

• Gather context (PR diff, changed files)
• Read repo CLAUDE.md / REVIEW.md guidelines
• Review plugins/architecture/skills/improve/SKILL.md change
• Review plugins/architecture/CHANGELOG.md change
• Post findings

Scope note: this repo's REVIEW.md splits security out to a dedicated claude-security-review lane; this review covers correctness/design/conventions/docs only. No security-relevant surface in this diff anyway (docs-only change).

Findings

🔴 Important — CHANGELOG documents a version the manifest never reached (blocking CI). Left as an inline comment on plugins/architecture/CHANGELOG.md. The new ## [0.5.2] heading isn't matched by a version bump in plugins/architecture/.claude-plugin/plugin.json (still "0.5.1") — verified the diff (git diff 2b1a9d1...HEAD) touches only CHANGELOG.md and SKILL.md. This repo's required CI gate scripts/check-changelog-parity.sh --check (.github/workflows/ci.yml:523-524) fails with CHANGELOG AHEAD OF MANIFEST in exactly this situation, so this PR will fail CI as-is. Fix: bump plugin.json version to 0.5.2.

Content check (verified against repo docs, not just author claim)

The substantive change — the SKILL.md Gotcha bullet now explains ${CLAUDE_PLUGIN_DATA} is wrong for the durable candidate artifact because it "points at a plugin-global dir with no project dimension" and "uninstalling from the last remaining scope deletes the directory" — checks out against this repo's own documented conventions:

• "deps/caches/generated machine state" as the documented use of ${CLAUDE_PLUGIN_DATA} is stated in docs/MIGRATION-PLAYBOOK.md:257-259 and docs/PLUGIN-PHILOSOPHY.md:242.
• The uninstall-deletes-the-directory claim matches docs/conventions/plugin-data-report-keying/README.md:25-26 and :156 verbatim ("Uninstalling from the last scope deletes the whole data directory unless --keep-data is passed").

No other issues found in the diff — this is a small, well-sourced doc fix, apart from the missing version bump above.

[github-actions]

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

[github-actions]

Warning

Automated security review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

• Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/31579063534
• Failure class: other
• Last SDK result: (no execution file was produced)

The check is green on purpose, and it is not evidence. It certifies that a security pass ran, and this one did not complete — but the cause is outside this PR's control, so merging is deliberately left unblocked rather than locking every merge for the length of the outage. Nothing was reviewed at this head. Where this check is required, it is satisfied without that evidence; a human should review security-sensitive changes here before merging.

Re-run the job to retry the review; a new push also retries it only if the caller's pull_request triggers include synchronize (the canonical security caller keeps it). An automatic retry may already have run — it is skipped when a partial review could duplicate comments, or when the failure class needs an operator.

Re-running does NOT help for every class:

• rate-limit that persists across re-runs, or auth — the credential or usage budget needs an operator; retrying will not clear it.
• a run that exhausted its turn budget ("subtype":"error_max_turns" above) will exhaust it again. As the PR author, split the change into smaller PRs; raising --max-turns is a change to the caller workflow, not something you can set on this PR.

[github-actions]

Warning

Automated review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

• Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/31579063538
• Failure class: other
• Last SDK result: (no execution file was produced)

Re-run the job to retry the review. A new push re-triggers this lane only if the caller's pull_request triggers include synchronize (the canonical caller omits it).
An automatic retry may already have run — it is skipped when a partial review could duplicate comments, or when the failure class needs an operator (auth).