feat: check-only setup carve-out for userConfig-only plugins (bug-report, miro)

[kyle-sexton]

Summary

Resolves the wave #314 design question (raised in the issue before mass-refactoring bug-report/miro): where a plugin's entire configuration surface is native userConfig — no tracked project config, no prerequisite an install could resolve — an apply action would have nothing to write except the pluginConfigs the setup contract itself forbids.

• Doctrine (docs/PLUGIN-PHILOSOPHY.md, setup section): one added sentence sanctioning the check-only shape for exactly that case. Kept in its own PR so the doctrine change is reviewable in isolation.
• bug-report 0.5.0: check is the sole action; the interactive "ask whether reports should be private or repo-resident" step becomes a stated tradeoff with a recommendation (non-interactive); reconfigure guidance states --config's fresh-install-only semantics; rechecks defer to a fresh session since the rendered value is injected at load.
• miro 0.2.0: check [verify-api] — the optional read-only credential probe (list one board, count only) becomes an explicit argument instead of an in-flow question; token never read, printed, or persisted (unchanged). MCP server version realigned across package.json, the server Implementation version, the lockfile, and the rebuilt committed bundle (drift check + typecheck green; lockfile delta is the two version fields).

With this, 29 of 31 wave plugins conform. Remaining: disk-hygiene + guardrails (deferred behind the #286/#305 lanes) and the closing contract-gate rule.

Verification

validate-plugins.sh, validate-plugin-contracts.mjs, markdownlint, typos, miro bundle drift check + typecheck: all green locally.

Related

• Part of Conformance wave: setup-contract adoption (31 plugins) #314
• Part of Epic: plugin fleet conformance audit — 50-plugin doctrine matrix and remediation waves #313

No linked issue: carve-out slice of #314 — the issue closes with the wave's final tranche.

🤖 Generated with Claude Code

[claude]

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

---

PR Review: feat: check-only setup carve-out for userConfig-only plugins

• Gather context and understand request
• Read changed files
• Review doctrine change (docs/PLUGIN-PHILOSOPHY.md)
• Review bug-report plugin changes (SKILL.md, plugin.json, CHANGELOG)
• Review miro plugin changes (SKILL.md, plugin.json, src, dist, package files, CHANGELOG)
• Synthesize findings and post review

---

Summary

This PR is clean, well-scoped, and correctly implements the check-only setup carve-out doctrine for two userConfig-only plugins. No blocking issues found. A few minor observations are noted below.

---

docs/PLUGIN-PHILOSOPHY.md — Doctrine change

The added sentence fits naturally into the existing paragraph and is logically tight. The three-part carve-out condition — "nothing but userConfig, no tracked project config, no external prerequisite setup can resolve" — correctly identifies all the cases where an apply action would have nothing to write. The conclusion that apply "would have nothing to write except the pluginConfigs this contract forbids" is accurate.

No issues. ✅

---

plugins/bug-report — 0.4.0 → 0.5.0

SKILL.md:

• argument-hint correctly changed from the interactive placeholder to "check".
• The ## Task section renamed to ## `check` (read-only, the only action) — clear and accurate.
• Step 3 change from interactive question to "state the tradeoff instead of asking" correctly makes the skill non-interactive.
• Step 4: The new --config fresh-install-only semantics note (uninstall then reinstall to reconfigure) is accurate and important consumer guidance.
• Step 5: The fresh-session caveat for rechecks is correct — ${user_config.*} is injected at load time; a recheck in the same session would observe the old rendered value.

Minor observation: The argument-hint: "check" doesn't signal to the user that this is optional (it's the only action, so there's nothing else to pass). Users could invoke /bug-report:setup without arguments. This is cosmetic — the description already covers it clearly. Optional improvement →

Minor observation: Line 14 embeds ≥ 2.1.207 as a factual version reference for when pluginConfigs was ignored in project/local settings. This is useful consumer context, but it's inside a skill file that will outlive this version. It's accurate and justified here; just note it will need updating if the behavior changes.

No blocking issues. ✅

---

plugins/miro — 0.1.2 → 0.2.0

SKILL.md:

The verify-api argument change is the correct approach. The previous shape — "Offer an optional credential check. Only after the user explicitly accepts..." — was interactive and unsafe in headless/automated contexts. Moving the opt-in to an explicit invocation argument (check verify-api) makes automation safe: a headless run can never accidentally trigger an API call unless explicitly requested.

The disable-model-invocation: true flag + argument model is consistent: /miro:setup check verify-api triggers step 5, /miro:setup check or /miro:setup does not. ✅

Version alignment — all four locations consistently updated to 0.2.0:

Location	Before	After
plugin.json	0.1.2	0.2.0 ✅
package.json	0.1.2	0.2.0 ✅
package-lock.json	0.1.2	0.2.0 ✅
src/index.ts McpServer	0.1.2	0.2.0 ✅
dist/index.min.js (bundle)	0.1.2	0.2.0 ✅

Security boundaries unchanged and correct: token never read/echoed/logged, no mutating Miro tools called during setup, pluginConfigs never touched. ✅

No blocking issues. ✅

---

Verdict

Approve. The doctrine change is minimal, precise, and correctly positioned in the philosophy doc. Both plugin updates faithfully implement the check-only carve-out and the non-interactive contract. The miro version drift is fully resolved. The PR achieves its stated scope (29/31 wave conformance) and correctly defers the remaining two.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b6e87c335c

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

[chatgpt-codex-connector]

Document the verify-api invocation

The plugin README still tells users to run /miro:setup and then provide an explicit confirmation for an API check (plugins/miro/README.md:29-31), but this change explicitly forbids in-flow confirmation and only runs the probe when the command receives verify-api. Consequently, users following the documented setup flow can no longer perform the advertised credential check; update the README to show /miro:setup check verify-api.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Update the Miro setup API-probe evaluation

The existing second setup eval invokes /miro:setup followed by natural-language verification text and expects an in-flow confirmation prompt before miro_list_boards. Under this new rule, that invocation lacks verify-api, so the skill must neither ask nor call the API and the eval no longer tests valid behavior. Change the eval prompt and expectations to use check verify-api and assert the direct read-only probe.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Update the bug-report setup evaluation

The first setup eval still expects the skill to ask whether reports should stay private or use a repository location (plugins/bug-report/skills/setup/evals/evals.json:8), but this change replaces that question with a required non-interactive tradeoff statement. The evaluation is now asserting the retired behavior, so it can reward a regression and should instead assert that the recommendation is reported without blocking on a question.

Useful? React with 👍 / 👎.