feat: pilot the convention-doc migration on plugin-quality (Phase 2d) - #3620
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 598796eb4c
ℹ️ 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".
3315cbc to
26502c9
Compare
Migrate plugin-quality's team config surface from the dedicated .claude/plugin-quality.md cascade to a topic doc at the consumer's convention home per the ADR 0018 expression doctrine: retirements.yaml (plugin-quality-r001 migrate, plugin-quality-r002 overlay delete) with eval coverage per record, resolver-driven setup check/apply and a WARN-visible dual-read window, synced check-retirements.sh and resolve-convention-home.sh copies with a new sync script, registry entries and CI job, a deterministic consumer-repo sim, and rewritten config-cascade / retired-conventions Implementers rows. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014uBXt1tMEReShbpG5gsFUd Co-authored-by: ksextonmelodic <ksextonmelodic@gmail.com>
fa3ec77 to
1d54c22
Compare
|
Claude finished @cursor[bot]'s task in 6m 18s —— View job Review complete
SummaryReviewed the full diff ( Codex's two P1 findings from the earlier review (commit
No new blocking findings. I checked the areas with the highest blast radius for a config-surface migration — schema validation in Not independently verified (outside available tools in this lane): the PR body's claimed command outputs (23-assertion sim run, resolver 61/61, helper 174/174, markdownlint/shellcheck/eval-lint/validator runs) — this lane's tooling is scoped to read-only inspection ( |
|
Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count. |
<!-- CURSOR_AGENT_PR_BODY_BEGIN --> No linked issue ## Summary Four concrete `argument-hint` outliers from the 2026-08-31 fleet skills audit. Official docs treat the field as an optional autocomplete hint (`[issue-number]`, `[filename] [format]`); an empty string is not a documented spelling, and the repo's instruction-surface style rejects em dashes. ## Fix - `wizard:generate`: add `argument-hint: "<procedure to wizardize>"`. - `review:code-review` and `review:security-review`: drop `argument-hint: ""` so they match the other no-arg skills. - `bugs:setup`: spell `check | apply` like sibling setups. - `computer-use:diagnose`: drop the em dash; hint is the closed enum `[screenshots|failures|quirks]`. Omit-for-guide stays in the Arguments body. Left for later slices of #3542: `machine-health:audit` (version overlap with #3672), the proposed house-style convention doc (blocked on the #3620 post-pilot gate), and the `check-skill.sh` criterion that would point at that doc. ## Verification - Official `argument-hint` row: optional autocomplete hint; examples are terse placeholders. - `scripts/affected-tests.sh --run --explain` → every changed file is a recorded no-suite class (SKILL.md / CHANGELOG / plugin.json). Exit 0. ## Related Refs #3542 Refs #3672 Official: https://code.claude.com/docs/en/skills#frontmatter-reference <!-- CURSOR_AGENT_PR_BODY_END --> <div><a href="https://cursor.com/agents/bc-7ffb619a-6ebb-4d47-9c45-d68e846edf93?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-7ffb619a-6ebb-4d47-9c45-d68e846edf93&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: ksextonmelodic <ksextonmelodic@gmail.com>
![https://cursor.com/assets/images/open-in-web-dark.png"><source](https://cursor.com/assets/images/open-in-web-dark.png"><source){kind=link}
![https://cursor.com/assets/images/open-in-web-light.png"><img](https://cursor.com/assets/images/open-in-web-light.png"><img){kind=link}
![https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a](https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a){kind=link}
![https://cursor.com/assets/images/open-in-cursor-dark.png"><source](https://cursor.com/assets/images/open-in-cursor-dark.png"><source){kind=link}
![https://cursor.com/assets/images/open-in-cursor-light.png"><img](https://cursor.com/assets/images/open-in-cursor-light.png"><img){kind=link}
![https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div](https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div){kind=link}
<!-- CURSOR_AGENT_PR_BODY_BEGIN --> No linked issue ## Summary `machine-health:audit` already accepts `weekly|on-demand|first-run` and `--dry-run`, but autocomplete had no `argument-hint`. This is the leftover concrete fix from `#3542` after `#3673`. ## Fix - Add `argument-hint: "[weekly|on-demand|first-run] [--dry-run]"` to `plugins/machine-health/skills/audit/SKILL.md`. - Bump machine-health to 0.12.9 and record the change. House-style convention docs and a `check-skill.sh` argument-hint criterion stay deferred (`#3620` post-pilot gate). This PR does not close `#3542`. ## Verification `scripts/affected-tests.sh --run --explain` selected no suites: every changed file is a recorded no-suite class. [affected-tests no-suite result](https://cursor.com/agents/bc-7ffb619a-6ebb-4d47-9c45-d68e846edf93/artifacts?path=%2Fopt%2Fcursor%2Fartifacts%2F3542-mh-argument-hint-demo.log) ## Related Refs #3542. Follows #3673 (items 2-5) and #3672 (machine-health 0.12.8 `reference/` rename). <sub>To show artifacts inline, <a href="https://cursor.com/dashboard/cloud-agents#my-pull-requests">enable</a> in settings.</sub> <!-- CURSOR_AGENT_PR_BODY_END --> <div><a href="https://cursor.com/agents/bc-7ffb619a-6ebb-4d47-9c45-d68e846edf93?cursor_ref=pr_footer&cursor_cta=open_in_web"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-web-light.png"><img alt="Open in Web" width="114" height="28" src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a> <a href="https://cursor.com/background-agent?bcId=bc-7ffb619a-6ebb-4d47-9c45-d68e846edf93&cursor_ref=pr_footer&cursor_cta=open_in_cursor"><picture><source media="(prefers-color-scheme: dark)" srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source media="(prefers-color-scheme: light)" srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img alt="Open in Cursor" width="131" height="28" src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a> </div> Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: ksextonmelodic <ksextonmelodic@gmail.com>
1 participant
Closes #3619
Summary
Phase 2d PILOT of the customization-consistency program (ADR 0018): migrates plugin-quality's team-shared config surface from the dedicated
.claude/plugin-quality.mdthree-layer cascade to a convention doc at the consumer's convention home (<home>/plugin-quality/README.md), bound by the pointer line and resolved by the shared resolver. First plugin to shipretirements.yamlalongside source-control's (recordsplugin-quality-r001migrate,plugin-quality-r002overlay delete), enrolling the check-retirements sync cluster and creating the resolve-convention-home cluster (sync script, registry entry, CI job). Stacked on the Phase 2b PR (#3597); expect a trivial registry/ci.yml merge with the 2c PR (#3601) whichever lands second.Fix
Reading side: audit resolves home → topic doc → dual-read (retired file is authority while present, WARN every run) → defaults; retired user-global/overlay layers read nowhere, WARN-visible. Setup:
checkreports the four resolver outcomes distinctly (exit 1 = INFO unconfigured, exit 3 causes = FAIL ask-don't-infer) plus the two fixed retirement lines;applybinds the home on operator confirmation only (marked-region append, never outside it), converges the topic doc (the old file's values are the migration source), then per-record gated cleanup. config-cascade and retired-conventions Implementers rows rewritten in the same PR per the doctrine's row rule. Bumps: plugin-quality 0.6.11, claude-config 0.40.5.Verification
Deterministic consumer-repo sim (
scripts/pilot-plugin-quality-sim.test.sh, 23 assertions, wired into the new resolve-convention-home-sync CI job): populated-AGENTS.md region append leaves prose byte-identical; resolver exit codes; exact detection TSV for both records; migrate-gate refusal without--i-migrated; clean + re-detect clean; CRLF root file. Validator (append-only + wiring + eval-per-record) green against origin/main; both sync clusters--check/--check-bumpgreen; drift check green; resolver 61/61 and helper 174/174; markdownlint, shellcheck, eval lint, lane coverage, catalog/cheatsheet green; skill-quality PASS on both touched skills (audit SKILL.md trimmed back under the 500-line cap).Related
Refs #3596/#3597 (mechanism), #3600/#3601 (2c), ADR 0018, config-cascade § Expression doctrine, retired-conventions convention. POST-PILOT USER GATE: this pilot is the template the user reviews before any other surface migrates — in particular seven flagged doctrine calls (overlay delete-not-migrate; no content_match on r002; WARN routed through the r002 record in setup while user-global stays prose-only; audit-side resolver exit-3 report-and-continue; dual-read eval living audit-side; records stamped with the shipping version; the gitignore-overlay recommendation dropped from the migrated surface). No other surface migrates until ratified.