docs(docs-hygiene): ratify the plugin contract (#4142)

[kyle-sexton]

Closes #4142

Summary

The owner ratified the docs-hygiene plugin contract on #4142 (2026-09-29). This makes the docs match: the proposed status is gone, boundary 5 is true of shipped skills, and the budget rule has one source.

Fix

• plugin-contract.md: status is ratified; boundary 5 says writes are opt-in and gated per invocation or per batch, with file-name renames gated per file; the only budget rule is the 8,000 default in check-listing-budget.sh; the decision is a four-part record; the four file-name skills are recorded as moving to docs-naming (docs-hygiene: extract the file-name skills into a docs-naming plugin #5348, extraction not in this change).
• README intro and CHANGELOG 0.23.16 updated; plugin version 0.23.15 to 0.23.16.

Verification

• check-listing-budget.sh plugins/docs-hygiene/skills: 5,234/8,000, unchanged.
• check-changelog-parity.sh (--check, --check-bump, --check-order, --check-preserved), validate-plugin-contracts.mjs, check-purged-em-dashes.sh, validate-plugins.sh, markdownlint on the three files: pass.
• git grep for 7,500, Status: proposed, hold the line in docs-hygiene (outside the CHANGELOG): empty.

Related

#4142, #5348 (docs-naming extraction).

🤖 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-29T18:28:30.870132Z	9b2c974	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 1m 33s —— View job

---

Code review in progress

• Gather context (PR diff, CLAUDE.md, plugin-contract.md)
• Review changed files for correctness and contract alignment
• Post findings (inline + summary)

[claude]

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

---

Security review

• Gather context (PR diff, changed files, custom instructions)
• Invoke /review:security-review skill and follow its instructions
• Post findings (or clean-review result) to this comment

No security issues found.

This PR touches four files — plugin.json (version bump), CHANGELOG.md, README.md, and reference/plugin-contract.md — all documentation/metadata in the docs-hygiene plugin. No skill code, hooks, scripts, or workflow files changed.

Instruction-surface check. reference/plugin-contract.md narrows the boundary-5 wording from "behind a human gate, per file" to "opt-in, gated per invocation or per batch" for general write skills (file-name renames stay gated per file). This reads like a guardrail loosening at first glance, so I checked it against the instruction exception register (protected classes: irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority) and verified it two ways:

1. scripts/validate-plugin-contracts.mjs has no rule that reads or enforces this contract's boundary-5 text — it's a descriptive charter for judging future skill proposals, not a live-enforced control.
2. The new wording matches what's actually shipped: compress/SKILL.md already does "confirmation-gated at every step" with a batch confirm-and-run, and realign-file-names/SKILL.md already gates renames one file at a time.

So this is a documentation-accuracy fix, not an actual reduction in gating — no code path changed, nothing new reaches an ungated write. No CRITICAL/IMPORTANT/SUGGESTION findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9b2c97415a

ℹ️ 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 0s —— View job

---

Security review: no findings

• Gather context (PR diff, changed files)
• Apply skip gate / instruction-surface lens
• Review changed files for security issues
• Post findings

Scope reviewed: plugins/docs-hygiene/.claude-plugin/plugin.json, CHANGELOG.md, README.md, reference/plugin-contract.md (diff via git diff origin/main...HEAD, head 5d902cc).

This is a documentation-only ratification: a version bump, a CHANGELOG entry, and prose edits to a plugin contract reference doc. No code, hooks, permissions, or executable logic changed.

Instruction-surface lens applied. reference/plugin-contract.md boundary 5 changes from "every skill... does it behind a human gate, per file" to "only when the user opts in, behind a confirmation per invocation or per batch. File-name renames are gated per file." This reads as a narrowing of a write-gating rule, so I checked it against the instruction exception register protected classes (irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority).

Verified against the actually-shipped skill bodies rather than taking the doc at its word:

• compress/SKILL.md already confirms and runs as a batch, not per file.
• rename-references/SKILL.md confirms via triaged buckets, not a per-file prompt.
• realign-file-names does gate per file, matching the doc's carve-out.

So the doc edit brings stale text in line with confirmation behavior the skills already implement — it doesn't loosen an enforced mechanism, remove a hook, or grant new unattended write authority. No protected-class rule is being weakened in effect, only in how it was previously (inaccurately) described.

No security issues found in this PR.

[claude]

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

---

Claude finished the code review

• Gather context (PR diff, changed files)
• Run /review:code-review criteria against the diff
• Post findings

No blocking findings.

This is a docs-only PR (plugin manifest version bump, CHANGELOG entry, README, and plugin-contract.md) ratifying the docs-hygiene plugin contract per #4142. I checked the changed text against the actual skill implementations it now describes, since that's the one place a docs PR like this can introduce a real correctness bug (a claim that doesn't match shipped behavior):

• Boundary 5's new wording ("writes are opt-in and confirmation-gated per invocation or per batch; file-name renames are gated per file") checks out against the skills: realign-file-names/SKILL.md refuses a blanket yes/range/glob/"all" and applies one file per acceptance, and compress/SKILL.md (and extract-ssot, rename-references) confirm before batch/repo-wide runs.
• The four-part decision record (Claim/Basis/As of/Recheck) and the single listing-budget source (check-listing-budget.sh at 8,000) are consistent with the script's own documented default, and the "proposed" status/"hold the line" language is fully removed from both plugin-contract.md and the README, with no leftover cross-references to the old stance.
• CHANGELOG entry follows the existing format/structure of prior entries in this file, and the version bump (0.23.15 → 0.23.16) is a plausible patch bump for a docs-only change.
• No em dashes introduced in the changed files.

One thing I could not independently verify: the PR body's claimed check-listing-budget.sh output (5,234/8,000) and the other script/lint runs (check-changelog-parity.sh, validate-plugin-contracts.mjs, check-purged-em-dashes.sh, validate-plugins.sh, markdownlint) — this environment's Bash tool required an approval step that isn't available to me here, so I'm not able to execute those scripts myself. I'm reporting those as author-claimed and unverified rather than confirmed, per this lane's own rule against restating a PR author's claimed verification as independently confirmed.

[claude]

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

---

Security review: no findings

• Gather context (PR diff, custom instructions)
• Invoke /review:security-review skill and follow its instructions
• Post findings (or clean-review result)

Scope reviewed: full cumulative diff origin/main...HEAD at ec40bab — plugins/docs-hygiene/.claude-plugin/plugin.json, CHANGELOG.md, README.md, reference/plugin-contract.md.

This is a documentation-only ratification: a version bump, a CHANGELOG entry, and prose edits to a plugin contract reference doc. No code, hooks, permissions, or executable logic changed.

New since the last review pass (ec40bab): one small fix to plugin-contract.md's Recheck line, keying the trigger to check-listing-budget.sh's WARN output instead of a "fails" condition. Verified against the script itself (plugins/skill-quality/scripts/check-listing-budget.sh): its header states it is "advisory only, never blocking CI or a pre-commit hook" and "always exits 0," and it prints CHECK-LISTING-BUDGET: WARN on overflow (line 485). The prior wording ("fails ... at 8,000") described a condition that can never occur; the new wording is accurate. This is a correctness fix to a decision record's recheck trigger, not a security-relevant change.

Instruction-surface lens applied (carried forward, no new concern in this head): boundary 5's wording change from "behind a human gate, per file" to "opt-in, gated per invocation or per batch (file-name renames per file)" was already checked against the instruction exception register protected classes (irreversible-action, secret-handling, data-integrity, external-publication, legal-compliance, agent-authority) in earlier passes on this PR. It's a descriptive charter with no enforcing mechanism (validate-plugin-contracts.mjs doesn't read this text), and it brings the doc in line with already-shipped skill behavior (compress and rename-references batch-confirm; realign-file-names gates per file) — no code path changed, no new unattended-write authority granted.

No security issues found in this PR.

[claude]

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

---

Code review: no findings

• Gather context (PR diff via git diff origin/main...HEAD, CLAUDE.md/AGENTS.md, plugin-contract.md)
• Invoke /review:code-review and follow its instructions
• Post findings (inline + summary)

Scope: the four changed files — plugin.json (version bump), CHANGELOG.md, README.md, reference/plugin-contract.md — all documentation/metadata in the docs-hygiene plugin. Security is out of scope for this lane (a separate security lane already ran clean twice on this PR).

What I independently checked (not just author-claimed):

• Read plugins/skill-quality/scripts/check-listing-budget.sh in full: it always exits 0, defaults to an 8,000-char budget, and prints CHECK-LISTING-BUDGET: WARN (never a nonzero exit) on overflow. The latest commit (ec40bab) already fixes the Codex P2 finding on this thread — the recheck trigger now reads "makes check-listing-budget.sh report over budget at 8,000 (WARN; the script exits 0)," which matches the script's actual behavior instead of a nonexistent "failing" exit code.
• Read realign-file-names/SKILL.md (lines 1–90): confirms the boundary-5 rewrite's claim that renames are gated one file at a time — it explicitly refuses a range, glob, count, "all," or "yes to all," and re-presents the current finding alone. The doc's wording matches the shipped skill.
• I could not execute check-listing-budget.sh myself in this sandbox (command approval was denied), so the "5,234/8,000" figure in plugin-contract.md and the CHANGELOG's other verification claims are author-claimed and unverified by me.

No correctness or CLAUDE.md-alignment issues found in this diff. The doc edits (ratified status, boundary-5 wording, single-source budget rule, four-part decision record, docs-naming extraction note) are internally consistent across plugin.json, CHANGELOG.md, README.md, and plugin-contract.md, and the boundary-5 and budget-recheck claims check out against the actual script and skill sources.
· branch docs/4142-ratify-docs-hygiene-contract