Skip to content

docs(plugin-diagnostics): tell existing installs to install plugin-diagnostics - #16597

Merged
kyle-sexton merged 2 commits into
mainfrom
docs/16591-install-plugin-diagnostics
Nov 16, 2026
Merged

kyle-sexton merged 2 commits into
mainfrom
docs/16591-install-plugin-diagnostics

Conversation

@kyle-sexton

Copy link
Copy Markdown
Member

Closes #16591

Summary

#16519 moved harness-ops' session hooks into session-telemetry (off by default) and plugin-diagnostics (on by default). A marketplace update does not install a default-on plugin where the marketplace is already installed, so an existing harness-ops user who updates gets no plugin-diagnostics, and nothing reports a hook that fails to launch. The docs said "on by default", which reads as nothing to do. This corrects the wording; no behavior changes (owner decision, control-hub#11: wording only, no plugin dependency).

Fix

  • plugins/plugin-diagnostics/README.md, opening paragraph: "on by default for a new install", and an existing install runs claude plugin install plugin-diagnostics@melodic-software.
  • plugins/harness-ops/README.md, "Session telemetry": the same for a user who installed harness-ops before the hooks moved out.
  • .changes/harness-ops/ and .changes/plugin-diagnostics/: a patch fragment each, under ### Fixed, saying the same where an upgrading user reads it. Released CHANGELOG.md entries are not edited.
  • Each statement links ADR 0109's probe record and names the row default-on-existing-users, without restating its result.

Done-when, item by item:

  1. Both READMEs say an existing install must run claude plugin install plugin-diagnostics@melodic-software, and that "on by default" applies to a new install. Delivered.
  2. The same is said in a changelog fragment for harness-ops and one for plugin-diagnostics; no released entry is rewritten. Delivered.
  3. Each statement points at the ADR 0109 probe row (#probe-record-claude-code-21325-2026-11-15, row default-on-existing-users) and does not restate it. Delivered.
  4. No behavior changes: only two READMEs and two fragments change. Delivered.

Verification

  • scripts/check-changelog-fragments.sh --check: all 12 fragments valid.
  • Pre-push check-affected passes.

Related

🤖 Generated with Claude Code

https://claude.ai/code/session_015XWwmbLtFcfditeagftLrv

…agnostics

A marketplace update does not install a default-on plugin where the
marketplace was already installed (ADR 0109, probe row
default-on-existing-users), so a harness-ops user upgrading past the
hook split gets no plugin-diagnostics. The harness-ops and
plugin-diagnostics READMEs, and a fragment for each, now say "on by
default" applies to a new install and give the install command.

Closes #16591

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015XWwmbLtFcfditeagftLrv
@kyle-sexton
kyle-sexton marked this pull request as ready for review November 16, 2026 18:34
@kyle-sexton

Copy link
Copy Markdown
Member Author

Owner: the control-hub session "Plugin Presets" watches and merges this pull request; it waits on CI Status and the review lanes on head 8dc654d. Review findings go to it, and the build session (plugin-profiles-build-5) fixes them.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 16, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

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

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-16T18:36:10.671660Z 8dc654d 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.

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/fix-docs
Model rung 0
Leg handoff
Run job success
Activity step success
Commits pushed none (read lane)
Run 43930394040

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions

Copy link
Copy Markdown
Contributor

Lane run report

Field Value
Activity pr-refine/apply-patch
Model rung 0
Leg base
Run job success
Activity step success
Commits pushed 3fccab7
Run 43930394040

Failed GitHub API calls

Method Path Status
GET /repos/{repo}/git/ref/tags/* 404

@github-actions

Copy link
Copy Markdown
Contributor

claude-security-review reviewed 3fccab71b41575fd277244bb4f0a7a8b4a1dd45a: read 4 of 4 changed file(s); 0 finding(s), 0 as inline comments.

Security review: PR #16597

No security issues found.

This pull request changes documentation only, in four files, and I read every hunk of each:

  • plugins/plugin-diagnostics/README.md: the opening paragraph now says "on by default" applies only to a new install, and tells an existing install to run claude plugin install plugin-diagnostics@melodic-software. It also fixes a stray line break before a period.
  • plugins/harness-ops/README.md: a new paragraph in "Session telemetry" gives harness-ops users who upgrade the same instruction.
  • .changes/harness-ops/…-4b7f2c90.md and .changes/plugin-diagnostics/…-9e2a5d13.md: new patch-bump changelog fragments under ### Fixed that say the same thing.

What I checked:

  • Trusted paths: none of the changed files match a TRUSTED PATHS: glob.
  • Plugin manifests: no plugin.json or marketplace.json changes, so there are no manifest lines.
  • Instruction surface: no standing instruction is deleted, narrowed or softened (no CLAUDE.md, AGENTS.md, rules file, skill or agent body, or hook list is touched). The READMEs are user-facing docs.
  • Install command: the command the docs recommend installs a plugin from this repository's own marketplace (@melodic-software). It points users at no outside source, and it is a step the user runs, not something that runs automatically on update.
  • Links: every link is relative (../../docs/adr/0109-…) or points at this repository's own GitHub blob URLs.
  • Pull request text: the PR context has no embedded instructions aimed at the lane.

Prior findings: this lane has not reviewed an earlier head (blocking only: no), so this is a full review.

critical-findings: 0

@github-actions

Copy link
Copy Markdown
Contributor

claude-review reviewed 3fccab71b41575fd277244bb4f0a7a8b4a1dd45a: read 4 of 4 changed file(s); 0 finding(s), 0 as inline comments.

Code review: no findings

This PR only changes wording: two README paragraphs and two patch changelog fragments. It tells users who installed before the hook split that plugin-diagnostics is on by default only for a new install, and that they must run claude plugin install plugin-diagnostics@melodic-software. I read every hunk of all 4 changed files.

Checks I ran with Read and Grep:

  • ADR link target. The anchor #probe-record-claude-code-21325-2026-11-15 matches the heading ### Probe record (Claude Code 2.1.325, 2026-11-15) in ADR 0109 L51. The row default-on-existing-users is at L63. The relative README links point at the right path.
  • Install command. The marketplace name melodic-software and the plugin entry plugin-diagnostics both exist in .claude-plugin/marketplace.json, so plugin-diagnostics@melodic-software is a valid identifier.
  • Version reference. harness-ops is at 10.0.0 in its plugin.json, which fits the fragment's "Upgrading from before 10.0.0".
  • "These hooks" in harness-ops. The new paragraph comes right after the "Session telemetry" paragraph that names the hooks that moved out, so "these hooks" has a clear antecedent.
  • Punctuation fix. The stray line-leading . in the plugin-diagnostics hook-failure audit paragraph is fixed correctly.

Closing issue #16591, Done when:

  1. Both READMEs give the install command and say "on by default" applies to a new install: met.
  2. There is one fragment each for harness-ops and plugin-diagnostics, and no released CHANGELOG.md entry is edited: met.
  3. Each statement links the probe row by name: met. It still says "a marketplace update does not install it", which criterion 1 needs.
  4. No behavior changes, since only docs and fragments change: met.

These criteria are about wording, so no test could fail on them. I did not count that as a finding. The author says scripts/check-changelog-fragments.sh --check and check-affected passed; I did not run either.

No manifest changes, no paved-path or path-scoped rule hits, and nothing in the PR context is aimed at the review lane. This change spends nothing billable.

Verifier dropped 0 of 0 candidates.

@kyle-sexton
kyle-sexton added this pull request to the merge queue Nov 16, 2026
Merged via the queue into main with commit f3db800 Nov 16, 2026
46 checks passed
@kyle-sexton
kyle-sexton deleted the docs/16591-install-plugin-diagnostics branch November 16, 2026 19:09
@github-actions github-actions Bot added the merge-path: owner-agent Post-merge accounting record (README.md, Merge paths) label Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-path: owner-agent Post-merge accounting record (README.md, Merge paths)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Tell existing users to install plugin-diagnostics after the hook split

1 participant