docs: rename docs/ and plugin reference files to lower-kebab-case and gate the rule

[kyle-sexton]

No related issue: repo-wide docs naming consistency, mirrors claude-code-plugins #4097.

Summary

Renames uppercase docs and plugin reference files to lower-kebab-case and adds a gate so new ones cannot appear. Exceptions mirror claude-code-plugins ADR 0034: README, AGENTS, CLAUDE, CHANGELOG, LICENSE, SKILL, CONTRIBUTING, SECURITY, REVIEW, CODE_OF_CONDUCT.

Fix

• docs/MIGRATION-PLAYBOOK.md, OFFICIAL-DOCS.md, PLUGIN-PHILOSOPHY.md -> migration-playbook.md, official-docs.md, plugin-philosophy.md.
• plugins/{automations,capabilities,plugin-ops}/reference/DOC-SOURCES.md -> doc-sources.md; plugins/automations/reference/LANES.md -> lanes.md.
• Every reference repointed (README, AGENTS.md, plugin READMEs, skills, cross-links).
• Patch bumps for the plugins whose shipped files changed: automations 0.1.1, capabilities 0.1.1, plugin-ops 0.2.1.
• New scripts/check-docs-naming.sh (basename regex plus case-collision check over docs/ and plugins/*/reference/) with scripts/test-check-docs-naming.sh, both run in the test-shell job; AGENTS.md records the rule.

Verification

• bash scripts/check-docs-naming.sh --check: clean.
• bash scripts/test-check-docs-naming.sh: 8/8 cases pass.
• bash scripts/test-sync-local.sh: 73 passed, 0 failed.
• shellcheck scripts/*.sh .cursor/install.sh: zero findings; manifests parse with jq empty.
• grep for the old names finds no remaining reference.

Related

claude-code-plugins PR #4097 and ADR 0034.

🤖 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-10-10T21:29:24.831101Z	5add4f6	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 59s —— View job

---

Security Review

• Gather context (PR diff, changed files, custom instructions)
• Invoke /review:security-review per custom instructions
• Post findings

Result: no security-relevant surface — skip gate applies.

This PR is a pure documentation rename + CI gate addition:

• 20 of 24 changed files are renames (UPPER-KEBAB.md → lower-kebab.md) or reference-only updates to the new paths (AGENTS.md, README.md, plugin README.md/SKILL.md/plugin.json files). No logic changes, no removed guardrails — I specifically checked AGENTS.md under the instruction-surface-deletion lens and it only renames doc paths and adds a new rule ("Name docs/ and plugins/*/reference/ files in lower-kebab-case"), nothing is weakened or dropped.
• scripts/check-docs-naming.sh is a new read-only lint script: it runs git ls-files over docs/ and plugins/*/reference/, matches basenames against a fixed regex, and exits non-zero on offenders. It takes no untrusted external input (operates only on the repo's own tracked paths), does no eval/source of file contents, and all variables are quoted — no injection surface.
• scripts/test-check-docs-naming.sh exercises that script against throwaway repos under mktemp -d, same pattern as the existing test-sync-local.sh suite — no secrets or network access.
• .github/workflows/pr-require-checks.yml adds two run: steps that only invoke the two scripts above inside the existing test-shell job — no trigger changes (pull_request_target/workflow_run), no permissions: widening, no new secrets, no expression injection into run: blocks, and no change to action pins. Out of scope for this lane per the zizmor-advisory boundary even if it were security-relevant.

No CRITICAL / IMPORTANT / SUGGESTION findings.

[claude]

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

---

Claude code review — complete

• Gather context (PR diff, changed files, AGENTS.md/CLAUDE.md, REVIEW.md)
• Review new scripts/check-docs-naming.sh and its test suite
• Review renames and reference updates for correctness
• Review CI workflow and plugin.json version bumps
• Adversarially verify candidate findings
• Post inline findings and final summary

No blocking findings. This is a clean, mechanical rename with good guard-rail coverage.

What I checked:

• scripts/check-docs-naming.sh (blob): the name_re/exempt_re pair, the docs/ + :(glob)plugins/*/reference/** pathspec, and the case-collision pass all trace through correctly. I confirmed the pathspec resolves to exactly the 7 intended files (git ls-files -- docs/ ':(glob)plugins/*/reference/**') and that the case-collision fold (tr | sort | uniq -d) currently reports zero collisions against the renamed tree — matches the "clean" claim.
• scripts/test-check-docs-naming.sh: 8 cases cover upper-kebab, mixed-case, snake_case, empty-segment (foo..md), nested offender/exempt, a directory-case collision, and a reference/ offender via a ../ path trick to land the fixture outside docs/. Traced the regex and mkdir/: > mechanics by hand for the trickier cases (foo..md, the ../plugins/... fixture) — they resolve the way the comments claim.
• Renames: used --find-renames per-file (the combined multi-path git diff otherwise mis-pairs same-named renames across plugins, which is just a diff-tool quirk, not a PR issue) and confirmed each rename is link-only (docs/migration-playbook.md similarity 95%, docs/official-docs.md 89%, docs/plugin-philosophy.md 95%, the four reference/doc-sources.md/lanes.md renames 95–98%). No stray content changes.
• Reference updates: AGENTS.md, README.md, all three plugin README.mds, and all affected SKILL.md bodies follow the doc-conventions split correctly (resolvable relative links in README/docs, bare repo-root-relative code spans inside SKILL.md bodies). A repo-wide grep for the old uppercase names (PLUGIN-PHILOSOPHY|MIGRATION-PLAYBOOK|OFFICIAL-DOCS|DOC-SOURCES|LANES\.md) only matches the test fixture's intentionally-uppercase sample names, no leftover stale references.
• CI wiring: the two new steps land inside the test-shell job, before the psscriptanalyzer job boundary — correctly scoped.
• Version bumps: automations 0.1.0→0.1.1, capabilities 0.1.0→0.1.1, plugin-ops 0.2.0→0.2.1 — each is a plugin whose shipped reference//README.md files actually changed; no plugin bumped without a corresponding shipped-file change and none missing a bump.
• Anchor integrity: the doc-sources fetch status anchor link in plugins/plugin-ops/reference/doc-sources.md still resolves after the rename (the heading itself is untouched).

Not independently run (script execution and gh api/shellcheck lookups required approval not available to this bot in this session; verification was done by static trace instead): bash scripts/test-check-docs-naming.sh, bash scripts/check-docs-naming.sh --check, bash scripts/test-sync-local.sh, shellcheck. The PR body's own claimed results for these (8/8, clean, 73 passed) are author-claimed and unverified by me — flagging per this lane's rule against restating a author's own verification as independently confirmed.

[github-actions]

claude-security-review has reviewed this pull request through 5add4f6; a later push is reviewed from there.

[claude]

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

---

Security review — no issues found

Scope (incremental): per lane instructions, this lane already reviewed everything in PR #101 through 4bdb6ed. This pass covers only the diff since then, in:

• scripts/check-docs-naming.sh
• scripts/test-check-docs-naming.sh

What changed: both files replace cd "${BASH_SOURCE[0]%/*}/.." / $(cd "${BASH_SOURCE[0]%/*}" && pwd) with a guarded src_dir that falls back to . when ${BASH_SOURCE[0]%/*} is a no-op (i.e. the script was invoked with a bare filename, no directory component, so %/* leaves the string unchanged and the old code would cd into a non-existent <script-name>/.. and bail with exit 2). The test file also adds one new fixture case, dir-case-collision, exercising the existing case-insensitive-collision detector with files under Guides/ vs guides/.

Analysis: this is a pure robustness/portability fix for script self-location, not a change in trust boundary:

• BASH_SOURCE[0] is the script's own invocation path, not attacker-influenced input from the PR diff or repo content.
• The new fallback only ever substitutes . for an unchanged (no-slash) prefix — it cannot introduce path traversal, injection, or widen what cd/git ls-files operate over; scope=(docs/ ...) is unchanged.
• The added test case constructs its fixture files from a hardcoded literal list in the test script, same pattern as the other run_case lines — no new untrusted-input path.
• No injection, authz, secret-handling, or GitHub Actions trust-boundary surface is touched by this diff.

No CRITICAL / IMPORTANT / SUGGESTION findings for the changed lines in this incremental scope.

Todo

• Read incremental diff (.claude-lane/incremental.diff)
• Read scripts/check-docs-naming.sh and scripts/test-check-docs-naming.sh
• Hunt for security issues (injection, path traversal, unsafe handling)
• Adversarial verification of any candidates (none raised, nothing to verify)
• Post final findings

[github-actions]

claude-review has reviewed this pull request through 5add4f6; a later push is reviewed from there.