docs(claude-config): route audit --fix through update-config and document auto-mode refusals

[kyle-sexton]

Closes #5376

Summary

claude-config:audit Phase 5 --fix edited settings files directly and did not name the two auto-mode refusals a real run hits.

Fix

• SKILL.md Phase 5 routes approved settings.json, settings.local.json and .mcp.json edits through update-config and states the [Self-Modification] handshake.
• SKILL.md gains "Refusals in auto mode": .claude/audit-pass.md write refused as [Instruction Poisoning], audit-engine.sh re-run refused as [Self-Modification], with the operator fallback and a verification record.
• context/procedures.md carries the same routing, refusals and fallback, pointing at the SKILL.md record.
• claude-config 0.53.0 to 0.53.1 with a CHANGELOG entry.

Verification

• scripts/check-changelog-parity.sh --check --check-order: passes.
• scripts/validate-plugins.sh: all manifests and the catalog validated.
• No script or test is touched (docs only), so the plugin's script tests are not re-run.
• Both files name update-config, [Self-Modification], both refusals and the fallback (see diff).

Related

Refs #4514 (split out per the owner decision of 2026-09-29).

🤖 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-30T14:20:34.820866Z	8edfa81	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 encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 703f3b0fea

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

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[claude]

Claude finished @kyle-sexton's task in 1m 4s —— View job

---

Security review — PR #5476

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

Invoked /review:security-review per the trigger comment's instructions, against melodic-software/claude-code-plugins PR #5476 at HEAD a792c3ea40d2d7e668c71492dc5ad1ba0026b627.

Scope reviewed (gh pr diff 5476):

• plugins/claude-config/skills/audit/SKILL.md
• plugins/claude-config/skills/audit/context/procedures.md
• plugins/claude-config/CHANGELOG.md
• plugins/claude-config/.claude-plugin/plugin.json

Instruction-surface check. SKILL.md and procedures.md are instruction bodies the audit skill follows on future runs, so I read the diff under the instruction-surface-deletion lens (skill's "Instruction-surface deletions" section). The change is additive/tightening, not a deletion or softening of a standing rule:

• It replaces a bare "make the edit" step with a requirement to route settings.json / settings.local.json / .mcp.json edits through the built-in update-config skill and its [Self-Modification] handshake — a stricter control than before, not a weaker one.
• It explicitly carves out orphan-false plugin removal to keep going through scripts/fix-plugin-drift.sh --yes, preserving that script's lower-precedence-scope check rather than bypassing it.
• The new "Refusals in auto mode" section documents two existing auto-mode classifier refusals ([Instruction Poisoning] for .claude/audit-pass.md, [Self-Modification] for the audit-engine.sh re-run) and their operator fallback; it doesn't grant new capability, it documents refusals that already fire and tells the model not to retry around them.
• The volatile classifier-category claim now carries a dated basis with a source link (chore: repo hygiene sweep 2026-09-26 .github#153), addressing the earlier reviewer note about an unlinked claim.

No new script, permission, workflow, or executable-code changes are in this diff — it's documentation only (plus a version bump and changelog entry).

Result: no security findings. No injection, authorization, secret-handling, or instruction-poisoning surface was introduced or weakened by this change; it tightens the existing edit path rather than loosening it.
· branch

[claude]

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

---

Reviewing PR #5476

• Gather context (PR diff, comments, review comments)
• Invoke /review:code-review criteria against changed files
• Evaluate outstanding Codex review comments
• Post findings

Both Codex P1 comments on commit 703f3b0 (the orphan-false routing conflict and the unlinked
refusal basis) were already resolved in commit d1f2558, which is included in this head
(a792c3e): Phase 5 now carves out an exception for orphan-false removal through
scripts/fix-plugin-drift.sh --yes, and the refusal basis links to
melodic-software/.github#153. No further
action needed there.

One new finding from this pass, posted inline: the added Phase 5 routing text says .mcp.json
edits go through update-config, but that contradicts this same skill's own verified Boundary
section a few hundred lines down.

Summary

update-config's actual scope, per this skill's own four-part verification record in
reference/native-update-config.md
(row 10, sourced from the actual bundled-skill description) and restated in
SKILL.md's existing Boundary section,
is settings.json / settings.local.json only. .mcp.json is never mentioned as something
update-config handles. This PR's new Phase 5 text nonetheless instructs routing .mcp.json
edits through update-config too — see the inline comment for the exact lines and why this is a
real (not hypothetical) path, since .mcp.json is an explicit --fix target
(SKILL.md line 79).

Verification note: the PR body's check-changelog-parity.sh and validate-plugins.sh runs are
author-claimed; I could not independently execute them in this sandbox (Bash commands required
approval that isn't available here). I did independently confirm the CHANGELOG entry (0.53.4,
dated, correctly ordered above 0.53.3) matches plugin.json's version by reading both files.

[claude]

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

---

Security review — PR #5476

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

Invoked /review:security-review per the trigger comment's instructions.

Note on the reviewed commit. The custom instructions named HEAD 8edfa81c as authoritative, but the checked-out worktree for this run is already at 5d026c7 (one commit ahead, pushed after the trigger fired). 8edfa81c still carried the .mcp.json-through-update-config contradiction flagged in an earlier review pass on this PR; 5d026c7 ("docs(claude-config): keep .mcp.json edits direct in audit Phase 5") fixes exactly that, so reviewing the stale SHA would have re-reported an already-fixed issue. I reviewed the actual current state (5d026c7) instead and note the discrepancy here rather than silently substituting it.

Scope reviewed (git diff origin/main...5d026c7):

• plugins/claude-config/skills/audit/SKILL.md
• plugins/claude-config/skills/audit/context/procedures.md
• plugins/claude-config/CHANGELOG.md
• plugins/claude-config/.claude-plugin/plugin.json

Instruction-surface check. SKILL.md and procedures.md are instruction bodies the audit skill follows on future runs, reviewed under the instruction-surface-deletion lens. The diff is additive/tightening throughout, not a deletion or softening of a standing rule:

• Phase 5 now requires routing settings.json / settings.local.json edits through the built-in update-config skill and its [Self-Modification] handshake, explicitly carving out .mcp.json (edited directly, outside update-config's scope) and orphan-false plugin removal (stays on scripts/fix-plugin-drift.sh --yes, preserving its lower-precedence-scope check) — a stricter control, not a weaker one.
• The routing text now agrees with this skill's own Boundary section (SKILL.md#L399-L401), which scopes update-config to settings.json/settings.local.json only — the contradiction an earlier review round flagged is resolved.
• The new "Refusals in auto mode" section (SKILL.md#L343-L356) documents two existing auto-mode classifier refusals and their operator fallback; it grants no new capability and explicitly says "never retry around a refusal," so it doesn't create a path to talk the classifier out of a refusal.
• The volatile classifier-category claim carries a dated basis with a source link (chore: repo hygiene sweep 2026-09-26 .github#153).
• plugin.json (0.53.6) and the CHANGELOG.md entry are consistent.

No new script, permission, workflow, or executable-code changes are in this diff — it's documentation only (plus a version bump and changelog entry).

Result: no security findings. No injection, authorization, secret-handling, or instruction-poisoning surface was introduced or weakened by this change; it tightens the existing edit path and resolves the contradiction the prior review round identified.
· branch

[claude]

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

---

Code review complete

• Gather context (PR diff, comments, prior review findings)
• Check skip gate (draft / trivial / already-reviewed head)
• Review changed files against code-review criteria
• Adversarially validate candidate findings
• Post findings (inline + summary)

Scope: git diff origin/main...HEAD for the current head, 5d026c7 — plugins/claude-config/skills/audit/SKILL.md, plugins/claude-config/skills/audit/context/procedures.md, plugins/claude-config/CHANGELOG.md, plugins/claude-config/.claude-plugin/plugin.json.

Prior finding, now resolved. The previous code-review pass on this lane (head a792c3e) flagged that the new Phase 5 routing text sent .mcp.json edits through update-config, contradicting this skill's own Boundary section (update-config only covers settings.json/settings.local.json). The latest commit, 5d026c7 ("keep .mcp.json edits direct in audit Phase 5"), fixes this: SKILL.md line 330 now scopes the update-config route to settings.json/settings.local.json only and calls out .mcp.json as "outside its scope; edit it directly," matching the Boundary section and context/procedures.md line 60-61, which carries the same carve-out.

The earlier Codex P1s (guarded orphan-false removal path, unlinked classifier-refusal claim) were also already resolved in d1f2558 and remain intact at this head: the orphan-false exception still routes through scripts/fix-plugin-drift.sh --yes (SKILL.md line 330-331), and the "Refusals in auto mode" claim carries a complete four-part verification record — claim, basis with a link to melodic-software/.github#153, as-of date, and a recheck trigger (SKILL.md lines 354-358), satisfying .claude/rules/skill-bodies-state-current-rules.md.

Version/changelog parity — independently confirmed by reading the files: plugin.json is 0.53.6, and CHANGELOG.md carries a ## [0.53.6] - 2026-09-30 entry ordered above 0.53.5, referencing issue #5376, which matches this PR's Closes #5376.

Verification scripts — I could not run scripts/check-changelog-parity.sh or scripts/validate-plugins.sh myself; Bash execution required approval unavailable in this session. The PR body's claim that both pass is author-claimed and not independently verified by me beyond the manual file read above.

No findings. Security concerns are out of scope for this lane (a separate security-review pass already ran on this PR and found nothing); nothing else in the diff — a docs-only change plus a version bump — introduces a correctness or maintainability issue.
· branch

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8edfa81cd2

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

[claude]

Claude finished @kyle-sexton's task in 1m 24s —— View job

---

Security review — PR #5476

• Gather context (PR diff, changed files, skip gate)
• Run /review:security-review criteria against HEAD 5d026c7
• Check outstanding instruction-surface / boundary findings from prior reviews
• Post findings

Scope reviewed (git diff origin/main...HEAD, HEAD 5d026c764c0fa06559d499c3e7c38a65f3a6408a):

• plugins/claude-config/skills/audit/SKILL.md
• plugins/claude-config/skills/audit/context/procedures.md
• plugins/claude-config/CHANGELOG.md, plugins/claude-config/.claude-plugin/plugin.json (version bump + changelog, no behavioral content)

Instruction-surface check. SKILL.md and procedures.md are instruction bodies the audit skill follows on future runs, so I read this diff under the instruction-surface-deletion lens against the instruction exception register (present in this checkout, consulted directly). Nothing here matches a delete/narrow/soften of a standing instruction:

• Phase 5 step 1 still requires routing approved settings.json / settings.local.json edits through the built-in update-config skill and its [Self-Modification] handshake — a stricter control than the prior bare "make the edit," not weaker.
• This latest commit resolves the gap flagged by the earlier code-review pass on this PR: the routing instruction now explicitly excludes .mcp.json ("outside its scope; edit it directly"), which matches this same file's own Boundary section (SKILL.md#L401) and the verification record in reference/native-update-config.md — both scope update-config to settings.json/settings.local.json only, with no .mcp.json handling.
• The orphan-false plugin removal exception is preserved, keeping that path on scripts/fix-plugin-drift.sh --yes so its lower-precedence-scope check still runs (the Codex P1 from an earlier commit).
• The new "Refusals in auto mode" section documents two existing auto-mode classifier refusals ([Instruction Poisoning] for .claude/audit-pass.md, [Self-Modification] for the audit-engine.sh re-run) with a dated, sourced basis (melodic-software/.github#153); it grants no new capability and tells the model not to retry around a refusal, only to hand the operator the fallback.

No script, workflow, permission, or executable-code change is in this diff — it's documentation (plus a version bump and changelog entry) that tightens the existing edit path rather than loosening it. No injection, authorization, secret-handling, or instruction-poisoning surface is introduced or weakened.

Result: no security findings.
· branch

[claude]

Claude finished @kyle-sexton's task in 3m 48s —— View job

---

Reviewing PR #5476

• Gather context (PR diff, comments, prior review findings)
• Invoke /review:code-review against HEAD b71b4d3
• Post findings (inline + summary)

Scope: gh pr diff 5476 (base origin/main) — plugins/claude-config/skills/audit/SKILL.md, plugins/claude-config/skills/audit/context/procedures.md, plugins/claude-config/CHANGELOG.md, plugins/claude-config/.claude-plugin/plugin.json. HEAD b71b4d3 differs from the previously-reviewed 5d026c7 only by a pure line-wrap (no content change), so I re-reviewed the substance in full rather than relying on that clean prior pass.

Finding, posted inline on both files: the new Phase 5 routing text (SKILL.md lines 329-334, duplicated in context/procedures.md lines 60-61) has two unresolved problems, both flagged as P1s by Codex on an earlier commit (8edfa81) and never addressed across the three subsequent commits on this branch:

1. It contradicts this same file's own Mutation gate, which scopes itself to the identical case (Phase 5, under --fix, one confirmed fix at a time) and says this skill "never chains into update-config on its own behalf." A future run following this skill literally hits opposite instructions for the same scenario.
2. It's unconditional, with no fallback for when update-config doesn't resolve in session (disableBundledSkills, older host) — a case this file's own Boundary section elsewhere acknowledges varies, but that disclaimer only covers the person-requested "Routing" case, not this Phase 5 mandate. Pre-PR, step 1 was a direct write that worked regardless of environment.

I independently verified both via an adversarial second pass (a separate agent instance, given no context from this review, asked to actively look for reasons each was a false positive) before posting — both came back CONFIRMED.

Everything else already resolved across this PR's history checks out at this head: the .mcp.json scope contradiction is fixed (5d026c7), the orphan-false guarded-removal path is preserved, the classifier-refusal claim carries a dated, linked verification record, and plugin.json (0.53.6) / CHANGELOG.md stay in parity. Security concerns are out of scope for this lane (a separate security-review pass already ran clean on this PR).

Verification note: the PR body's check-changelog-parity.sh and validate-plugins.sh runs are author-claimed; not independently re-run here.
· branch

[claude]

Claude finished @kyle-sexton's task in 3m 20s —— View job

---

Security review — PR #5476

• Gather context (PR diff, changed files, prior review findings)
• Invoke /review:security-review against HEAD b71b4d3
• Post findings

Scope reviewed (gh pr diff 5476, HEAD b71b4d3d0d5edd6f1c2f9c997a7a16dddc07b115):

• plugins/claude-config/skills/audit/SKILL.md
• plugins/claude-config/skills/audit/context/procedures.md
• plugins/claude-config/CHANGELOG.md, plugins/claude-config/.claude-plugin/plugin.json (version bump + changelog, no behavioral content)

Note on history. This branch merged main at 8edfa81, and that merge's conflict resolution briefly reintroduced the earlier .mcp.json-through-update-config bug that a prior review round on this PR had already flagged and fixed at 5d026c7. The very next commit, 5d026c7 itself lands after 8edfa81 in the branch's own history (b71b4d3 → 5d026c7 → 8edfa81), re-fixing it. At the current HEAD b71b4d3 (a pure line-wrap of 5d026c7's text), the .mcp.json exclusion is correctly in place, so that earlier finding stays resolved — verified by reading the current file rather than trusting the comment thread's chronology at face value.

Instruction-surface check. SKILL.md and procedures.md are instruction bodies this audit skill follows on future runs. This diff is additive/tightening, not a deletion of a standing rule — with one exception, posted inline: SKILL.md lines 329–334 (this PR's new Phase 5 routing) directly contradicts the file's own unchanged Mutation gate at lines 413–415 ("never chains into update-config on its own behalf"). Codex flagged this same contradiction on an earlier commit ("Remove the conflicting no-chain instruction") as a correctness issue; from a security angle it's an authorization-boundary gap, because the untouched "never chains" sentence gives a future run (or an adversarial context trying to talk the model out of the new [Self-Modification] handshake) an instruction-backed argument to fall back to a direct, ungated settings write — defeating the control this PR exists to add. See the inline comment for the exact exploit path and fix.

Everything else checked out clean:

• The orphan-false plugin-removal exception still routes through scripts/fix-plugin-drift.sh --yes, preserving its lower-precedence-scope check.
• The "Refusals in auto mode" section grants no new capability and tells the model never to retry around a refusal; its volatile classifier-category claim carries a dated, sourced basis (melodic-software/.github#153).
• plugin.json (0.53.6) and the CHANGELOG.md entry are version-consistent.
• No script, workflow, permission, or executable-code change is in this diff.

Result: one IMPORTANT finding, posted inline on SKILL.md lines 329–334.
· branch

[claude]

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

---

Code review complete

• Gather context (PR diff, prior review threads, HEAD 2d98e82)
• Invoke /review:code-review against the current head
• Check whether the two open P1s (Mutation-gate contradiction, no-fallback) are resolved by 2d98e821b
• Post findings (inline + summary)

Scope: gh pr diff 5476 (base origin/main) at HEAD 2d98e82 — plugins/claude-config/skills/audit/SKILL.md, plugins/claude-config/skills/audit/context/procedures.md, plugins/claude-config/skills/audit/reference/native-update-config.md, plugins/claude-config/CHANGELOG.md, plugins/claude-config/.claude-plugin/plugin.json.

Both open P1s from the prior review pass (head b71b4d3) are resolved at this head.

1. Mutation-gate contradiction. SKILL.md lines 413–415 now reads: "This skill writes only in Phase 5, under --fix, one confirmed fix at a time; Phase 5 routes each such settings edit through update-config, and outside --fix this skill never chains into it on its own behalf." That reconciles with the new Phase 5 step 1 instead of contradicting it, and reference/native-update-config.md lines 18–21 was updated to match — its remaining "not a chain from this skill" sentence now clearly scopes to findings --fix doesn't cover, a distinct case from the routed Phase 5 edit.
2. No fallback when update-config is unavailable. Phase 5 step 1 now reads "through the built-in update-config skill when it resolves in this session, and write directly when it does not," matching the existing "Availability is never assumed" disclaimer elsewhere in the file. context/procedures.md lines 60–62 carry the identical fallback wording. The fallback doesn't reopen a gap: the [Self-Modification] auto-mode handshake sentence that follows is unconditional on the write itself, not on going through update-config, so a direct-write fallback stays gated the same way a routed one is.

Both files stay internally consistent with the Boundary section (SKILL.md lines 397–420): update-config's scope stays settings.json/settings.local.json only, .mcp.json stays a direct edit, and the orphan-false guarded-removal path stays on scripts/fix-plugin-drift.sh --yes. plugin.json (0.53.6) and the new CHANGELOG.md entry stay in parity.

No new findings. I read the full diff plus the surrounding unchanged Boundary/Mutation-gate/Presence sections it now has to agree with, and didn't find a fresh contradiction, gap, or maintainability issue introduced by this reconciliation.

Verification note: scripts/check-changelog-parity.sh --check --check-order required an approval this session doesn't have, so I couldn't independently re-run it; the PR body's claim that it and validate-plugins.sh pass is author-claimed, not verified by me here. I did independently confirm plugin.json/CHANGELOG.md version parity by reading both files.

Security concerns are out of scope for this lane (a security-review pass already ran clean on this PR).
· branch

[claude]

Claude finished @kyle-sexton's task in 1m 45s —— View job

---

Security review — PR #5476

• Gather context (PR diff, changed files, prior review findings)
• Run /review:security-review criteria against HEAD 2d98e82
• Post findings

Scope reviewed (gh pr diff 5476, HEAD 2d98e821bbd9ccb44021fdb3310741b2311a1bcf):

• plugins/claude-config/skills/audit/SKILL.md
• plugins/claude-config/skills/audit/context/procedures.md
• plugins/claude-config/skills/audit/reference/native-update-config.md
• plugins/claude-config/CHANGELOG.md, plugins/claude-config/.claude-plugin/plugin.json (version bump + changelog, no behavioral content)

Instruction-surface check. SKILL.md and procedures.md are instruction bodies this audit skill follows on future runs, so this diff was read under the instruction-surface-deletion lens against the instruction exception register (present in this checkout, consulted directly; Gate 0 classes: irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority).

This commit is itself the reconciliation of the two P1s a prior review round on this PR raised against b71b4d3:

1. Mutation gate / Phase 5 contradiction — resolved. SKILL.md lines 413-415 now reads "Phase 5 routes each such settings edit through update-config, and outside --fix this skill never chains into it on its own behalf" — the blanket "never chains" sentence is narrowed to scope the exception to exactly the Phase 5/--fix case the new routing step covers, agreeing with Phase 5 step 1 instead of contradicting it. This narrowing is not a Gate-0 agent-authority deletion: the routed write still requires a Phase-4 user-approved fix and, in auto mode, still passes through the [Self-Modification] classifier handshake — the same gate that would fire on a direct write to settings.json/settings.local.json regardless of which skill performs it. The change formalizes a controlled path rather than removing a check.
2. No fallback when update-config is unavailable — resolved. Phase 5 step 1 and context/procedures.md lines 60-62 now read "through the built-in update-config skill when it resolves in this session, and write directly when it does not," matching the file's own "Availability is never assumed" pattern. The direct-write fallback doesn't reopen a bypass: the auto-mode [Self-Modification] gate is a property of writing a settings file at all, not of routing through update-config specifically, so an unavailable update-config doesn't let a settings write skip the classifier.

Everything already resolved earlier in this PR's history stays intact at this head: .mcp.json stays outside update-config's scope and is edited directly (SKILL.md#L331), the orphan-false plugin-removal exception still routes through scripts/fix-plugin-drift.sh --yes preserving its lower-precedence-scope check, and the "Refusals in auto mode" claim carries a dated, sourced four-part verification record (melodic-software/.github#153). plugin.json (0.53.6) and the CHANGELOG.md entry stay version-consistent.

No script, workflow, permission, or executable-code change is in this diff — documentation (plus a version bump and changelog entry) that tightens the existing edit path and removes the internal contradiction the prior review round identified.

Result: no security findings.
· branch