docs(claude-ops): re-verify userConfig unset-key render on 2.1.263

[kyle-sexton]

Closes #3759

Summary

The plugins skill's install_new render rests on the claim that an unset userConfig key renders the literal ${user_config.<key>} placeholder rather than the manifest default. The 2.1.261 re-verification could not confirm or deny it because its positive control failed: a key set through --settings pluginConfigs rendered literal. Issue #3759 asked for a probe allowed to write real user settings so the two explanations (--settings does not feed substitution, or substitution regressed) could be separated.

Fix

• Probe run 2026-09-06 on Claude Code 2.1.263 with a throwaway local marketplace and a throwaway plugin carrying two userConfig string keys, both with manifest defaults. claude plugin install <id> --config setkey=REALVALUE wrote the real user-settings entry. Rendered skill body: the set key substituted, the unset key rendered the literal placeholder (not its default), ${CLAUDE_PLUGIN_ROOT} substituted. Claim holds; explanation (1) from the issue is the right one, and there is no regression.
• Second run with --settings '{"pluginConfigs":{"<id>":{"options":{"unsetkey":"VIA_SETTINGS_FLAG"}}}}': the flag-sourced value substituted alongside the user-settings one. So --settings does feed skill-content substitution; the 2.1.261 control failed because its payload put the key directly under the plugin id instead of under options.
• SKILL.md replaces the "inconclusive" paragraph with the 2.1.263 stamp, the options shape, the --config recipe, and a note that the current plugins-reference page says the default "is used if specified" for an unset key while the render contradicts it for skill content. install_new needs no fallback beyond the existing "placeholder means ask" rule. Frontmatter unchanged.
• scope-semantics.md records the options nesting in the pluginConfigs section and updates the preamble's not-re-run list.
• claude-ops version bump with CHANGELOG entry. Docs only.

Verification

• markdownlint-cli2 over the touched markdown: 0 issues. typos: clean. No em dashes in added lines. SKILL.md frontmatter diffed byte-identical against origin/main.
• Real state after the probe: throwaway plugin uninstalled, marketplace removed; ~/.claude/settings.json, installed_plugins.json, known_marketplaces.json all hash-identical to the pre-probe backups. The pluginConfigs entry the probe wrote was removed by the uninstall.

Related

• claude-ops:plugins — recheck triggers armed and unserviced: empirical CC probes stamped 2.1.240 (one at 2.1.218) against a 2.1.261 CLI #3734 and docs(claude-ops): re-verify plugins skill probes against Claude Code 2.1.261 #3760 (the 2.1.261 pass whose control failed)
• claude-ops:plugins: claude plugin marketplace remove leaves ~/.claude/plugins/cache/<marketplace>/ on disk (CC 2.1.261) #3763 (the cache-residue observation from the same marketplace round trip, own PR)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-06T09:12:44.944391Z	3835edc	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

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

---

Review complete ✅

• Gather context (PR diff, changed files, custom instructions)
• Invoke /review:code-review skill per repo instructions
• Post findings as inline PR comments
• Post summary comment

Summary

Docs-only change (4 files, +41/-23): re-verifies the userConfig unset-key render claim in plugins/claude-ops/skills/plugins/SKILL.md, updates context/scope-semantics.md with the options-nesting detail for pluginConfigs, and bumps plugin.json/CHANGELOG.md to 0.42.19.

I reviewed the diff (git diff origin/main...HEAD) against the code-review lane's criteria (correctness, maintainability, alignment with this repo's conventions):

• The new prose is internally consistent: the SKILL.md recipe for the pluginConfigs options-nesting shape (line 361) matches the shape documented in scope-semantics.md (line 305) verbatim.
• The dated-verification pattern (re-verified 2026-09-06 against CC 2.1.263, with an explicit recheck trigger) follows .claude/rules/skill-bodies-state-current-rules.md — no bare/undated claims introduced.
• Version bump in plugin.json (0.42.18 → 0.42.19) matches the new CHANGELOG.md entry heading.
• No em dashes in added lines (verified independently via git diff ... | grep), consistent with the PR's own claim.
• No stale cross-references left behind: the old "inconclusive" 2.1.261 paragraph in SKILL.md is fully replaced rather than partially edited, and nothing elsewhere in the plugins skill still points at the old "inconclusive" framing.

The empirical claims themselves (what Claude Code 2.1.263 actually renders for userConfig) rest on probes the author ran locally — I don't have a way to independently execute the claude plugin install --config / --settings pluginConfigs probes in this sandbox (the claude CLI invocation required approval that isn't available in this lane), so per the review skill's rule I'm treating that verification as author-claimed and unverified rather than restating it as independently confirmed.

No correctness or maintainability findings to report — nothing here rises to "a careful senior reviewer would block or flag." No inline comments posted.

[claude]

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

---

Security review complete

• Gather context (PR diff, changed files)
• Run /review:security-review per custom instructions
• Post findings

Skip gate hit: no security-relevant surface.

All four changed files are documentation/metadata only:

• plugins/claude-ops/.claude-plugin/plugin.json — version bump string only.
• plugins/claude-ops/CHANGELOG.md — changelog prose.
• plugins/claude-ops/skills/plugins/SKILL.md — rewrites the userConfig unset-key verification note with the 2026-09-06/2.1.263 re-probe results.
• plugins/claude-ops/skills/plugins/context/scope-semantics.md — records the pluginConfigs.options nesting shape and updates the not-re-run list.

None of this introduces code paths, executable logic, command construction, credential handling, or CI/Actions changes — it's a documentation correction describing prior manual CLI probes (claude plugin install ... --config, --settings '{"pluginConfigs":...}') run against a throwaway local marketplace, with no scripts or automation added to this repo that execute those commands. No injection surfaces, no authz/access-control paths, no secrets, no GitHub Actions files touched.

No security issues found. Per the skip gate in /review:security-review, deep review was not needed for this change.

[github-actions]

Last security-reviewed head: 3835edcb0cae827fb1384085f9bfb779a2e9f674. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[github-actions]

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3835edcb0c

ℹ️ 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".