docs: promote stranded conventions to path-scoped rules and nested AGENTS.md

[kyle-sexton]

No linked issue

Summary

Applies the accepted findings of a full-repo /instruction-placement:audit run (1,195 files swept, eight adjudication lanes, independent fresh-context verification). The repo's always-loaded instruction layer was nearly empty while several genuinely normative contributor conventions lived only in docs Claude never loads; this PR makes each reachable at its actual trigger point, as pointers so the human-facing docs stay the single source of truth.

Fix

One commit per accepted finding, in ranked order:

• IP-001 (effa775a): root AGENTS.md gains a four-line pointer to README's "Validate a change" contract (zero suites is an error, never "nothing to run").
• IP-002 (173869be): .claude/rules/catalog-taxonomy.md, scoped to .claude-plugin/marketplace.json (1 tracked file), pointing at docs/CATALOG-TAXONOMY.md.
• IP-003 (3e78bcc4): .claude/rules/hook-budget.md, scoped to plugins/*/hooks/** (146 files), pointing at the hook-budget convention's Rules section.
• IP-004 (b056a6ef): .claude/rules/ruff-pin.md, scoped to **/*.py (100 files), pointing at the pinned-ruff wrapper contract in docs/CI-RUNNER-ROUTING.md.
• IP-005..007 (730f24e7, fa1a3856, 1c6c37e1): nested AGENTS.md plus mandatory CLAUDE.md shim at plugins/machine-health/skills/audit/, pointing at the human-only README's layout, dual-invocation, and stateless-checks conventions.

The generated on-demand rules index in root AGENTS.md is regenerated with each move so every deferred surface stays reachable from subagents.

Verification

• Every paths: glob machine-validated (match counts above; no zero-match, no bad brackets, within budget).
• Empirical load probes via the plugin's verify-load.sh (real CLI with an InstructionsLoaded hook): the catalog-taxonomy rule fires on read of marketplace.json, and the nested machine-health pair loads via shim traversal; both VERDICT PASS.
• render-index.sh check reports IN-SYNC at every commit.
• scripts/affected-tests.sh --explain: all six changed files are recorded no-suite classes (prose), zero suites owed.
• markdownlint-cli2 clean over all changed files.

Related

Findings artifact (statuses per finding, held-back Gate 0 items, routed-out questions) lives under the instruction-placement plugin's data directory, keyed to this project; not committed by design. N/A for tracker links.

🤖 Generated with Claude Code

https://claude.ai/code/session_01THL7Bu9RBnbob7xMeiXTBU

---

Generated by Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1c6c37e1a3

ℹ️ 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 2m 59s —— View job

---

Code review complete

• Gather context (PR diff, repo instructions, skill)
• Run skip gate checks (PR open, non-draft, meaningful docs change — proceeded with full review)
• Review changed files against /review:code-review criteria
• Post findings

Scope reviewed (per git diff effa775^..HEAD on the 6 files this PR actually touches — origin/main has diverged with unrelated commits since the branch point, so a plain origin/main...HEAD diff pulls in noise not part of this PR):

• .claude/rules/{catalog-taxonomy,hook-budget,ruff-pin}.md (new, path-scoped)
• AGENTS.md (adds the "Validate a change" pointer + generated rules index)
• plugins/machine-health/skills/audit/{AGENTS.md,CLAUDE.md} (new nested pair)

Verification performed independently (not just re-stating the PR's own claims):

• Every doc target and anchor the new files link to actually exists and matches: docs/CATALOG-TAXONOMY.md (Form rule / Assignment principle / Singleton governance sections), docs/conventions/hook-budget/README.md#rules, docs/CI-RUNNER-ROUTING.md#local--workstation-ruff, README.md#validate-a-change, and all three anchors in plugins/machine-health/skills/audit/README.md. Checked GitHub's heading-slug algorithm against each anchor by hand (e.g. ## Stateless checks, stateful orchestrator → #stateless-checks-stateful-orchestrator) — all correct.
• Glob match counts: plugins/*/hooks/** → 146 files, **/*.py → 100 files, .claude-plugin/marketplace.json → 1 file. All match the PR body's claimed counts exactly.
• The generated index block in AGENTS.md (lines 9–26) is a faithful, complete render given render-index.sh's logic (.claude/rules/vendor-docs-are-not-style.md correctly excluded as unscoped; the new nested CLAUDE.md shim correctly excluded via the pure-shim check since its content is indexed under the AGENTS.md row instead; row order is correct C-locale sort). Confirmed by reading the generator rather than executing it (sandbox blocked running render-index.sh itself).
• plugins/machine-health/skills/audit/CLAUDE.md (@AGENTS.md) mirrors the existing root CLAUDE.md → AGENTS.md shim pattern exactly.
• No em dashes or other vendor-doc formatting crept into the new prose (per .claude/rules/vendor-docs-are-not-style.md).
• The three new rules and the nested pair match Recipe A / Recipe B in plugins/instruction-placement/skills/realign/context/apply-recipes.md, so this PR is a mechanical application of the plugin's own documented recipes rather than ad hoc formatting.

Not independently verified (author-claimed only, could not run in this sandbox): the verify-load.sh empirical load-probe results and render-index.sh check IN-SYNC status — both plausible from static inspection but I could not execute the scripts myself here (Bash execution required approval this session did not grant).

Findings: none. This is a clean, self-consistent documentation change — no correctness issues, broken links, glob mistakes, or maintainability concerns found. Nothing to anchor as inline comments.

[claude]

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

---

Security review

• Gather context (PR diff, changed files)
• Run skip gate / assess security-relevant surface
• Review changed files for security issues
• Post final findings

Skip gate triggered: no security-relevant surface. This PR only adds Markdown convention/pointer files (.claude/rules/*.md, AGENTS.md additions, a nested AGENTS.md and one-line CLAUDE.md shim under plugins/machine-health/skills/audit/). No executable code, scripts, GitHub Actions workflow changes, auth/access-control logic, or data-handling paths are touched — nothing for a security review to hunt in.

No security issues found.

[github-actions]

Last security-reviewed head: e1f443f0ce75b2983dc1177d91dc2620353fd377. On the next push, the relevance gate compares only the commits since this SHA; delete this comment to force a full re-review.

[github-actions]

Claude has reviewed this PR 2 times. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[claude]

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

---

Security review

• Gather context (PR diff, changed files)
• Run skip gate / assess security-relevant surface
• Review changed files for security issues
• Post final findings

Skip gate triggered: no security-relevant surface. All 8 changed files at HEAD e1f443f are documentation/manifest additions:

• .claude/rules/{catalog-taxonomy,hook-budget,ruff-pin}.md — new path-scoped pointer docs (prose only)
• AGENTS.md — 26-line generated index addition (prose table)
• plugins/machine-health/skills/audit/AGENTS.md — new nested pointer doc (prose only)
• plugins/machine-health/skills/audit/CLAUDE.md — one-line @AGENTS.md shim
• plugins/machine-health/.claude-plugin/plugin.json — version bump (0.11.7 → 0.11.8) for changelog-parity
• plugins/machine-health/CHANGELOG.md — corresponding release entry

No executable code, scripts, GitHub Actions workflow changes, auth/access-control logic, or data-handling paths are touched. Nothing here for a security review to hunt in.

No security issues found.

[claude]

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

---

Code review

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

Skip gate: not triggered — this is a real (if low-risk) review surface: new path-scoped rule files and a nested AGENTS.md/CLAUDE.md pair whose correctness depends on glob matching, anchor targets, and load mechanics, not just prose.

What I checked

• Each paths: glob in the three new .claude/rules/*.md files against git ls-files: **/*.py → 100, plugins/*/hooks/** → 146, .claude-plugin/marketplace.json → 1. All match the PR's claimed counts.
• Every markdown link/anchor the new files point at: README.md#validate-a-change (root AGENTS.md:8), docs/CATALOG-TAXONOMY.md (Form rule / Assignment principle / Singleton governance sections), docs/conventions/hook-budget/README.md#rules, docs/CI-RUNNER-ROUTING.md#local--workstation-ruff, and the machine-health README.md anchors (#separation-of-semantics-from-implementation, #dual-invocation-scripts, #stateless-checks-stateful-orchestrator) — all resolve to real headings with matching content.
• Relative path depth in the three .claude/rules/*.md files (../../docs/...) is correct for their location two levels below repo root.
• The existing .claude/rules/vendor-docs-are-not-style.md (unscoped, no paths:) confirms the always-loaded-vs-deferred mechanism is being used consistently: it's present in this session's always-loaded context while the three new scoped rules are not, matching the intended design.
• plugins/machine-health/CHANGELOG.md 0.11.8 entry and plugin.json version bump are consistent with the nested-AGENTS.md change described.
• No em dashes or other vendor-doc style leakage in any new/changed prose (pre-existing em dashes elsewhere in CHANGELOG.md are untouched history, not part of this diff).

I was not able to execute plugins/instruction-placement/scripts/render-index.sh check or verify-load.sh in this sandbox (Bash execution requires interactive approval not available in this job), so the "IN-SYNC" and "VERDICT PASS" claims in the PR description are author-claimed and unverified by me — my check above is a manual re-derivation of the same facts (glob counts, anchor existence), which line up.

Findings

None. I reviewed the already-open thread between Codex and the author on .claude/rules/hook-budget.md:4 (write-vs-read trigger gap for a brand-new plugin's first hook) — the mechanism gap is real, but the author's rationale for not promoting it further (the root AGENTS.md index row already carries the pointer on an always-loaded surface, and the review gate is the backstop for the residual first-hook case) is sound and I have nothing to add to it.

This is a low-risk, well-verified documentation-placement change. No correctness or maintainability issues found.