docs: promote stranded conventions to path-scoped rules and nested AGENTS.md (#3388)

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.com/claude-code)

https://claude.ai/code/session_01THL7Bu9RBnbob7xMeiXTBU

---
_Generated by [Claude
Code](https://claude.ai/code/session_01THL7Bu9RBnbob7xMeiXTBU)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: kyle-sexton

.claude/rules/catalog-taxonomy.md

@@ -0,0 +1,12 @@
+---
+description: "Where the marketplace category taxonomy lives; read before adding or changing a plugin's category"
+paths:
+  - ".claude-plugin/marketplace.json"
+---
+
+# Catalog category taxonomy
+
+The category vocabulary for `.claude-plugin/marketplace.json` is maintained in
+[`docs/CATALOG-TAXONOMY.md`](../../docs/CATALOG-TAXONOMY.md). Read its Form rule, Assignment
+principle, and Singleton governance sections before assigning, renaming, or merging any plugin
+category; do not invent a category value from the existing entries alone.

.claude/rules/hook-budget.md

@@ -0,0 +1,13 @@
+---
+description: "Marketplace-wide latency budget for always-on hooks; read before adding or widening a hook"
+paths:
+  - "plugins/*/hooks/**"
+---
+
+# Hook budget
+
+This marketplace holds a fixed latency budget for always-on hooks, defined in
+[`docs/conventions/hook-budget/README.md`](../../docs/conventions/hook-budget/README.md). Read its
+Rules section before adding a hook or widening an existing one's matcher: the change must state
+its measured share of the budget in the plugin's README, and the budget never relaxes to absorb
+an overage.

.claude/rules/ruff-pin.md

@@ -0,0 +1,13 @@
+---
+description: "Python linting runs through the pinned ruff wrapper, never a bare ruff on PATH"
+paths:
+  - "**/*.py"
+---
+
+# Ruff pin
+
+Lint Python in this repo through `scripts/run-ruff.sh check <paths>` (the wrapper passes any
+ruff arguments through and resolves the CI-pinned ruff version); a bare `ruff` on PATH can
+disagree with CI in both directions, so never use it for verification here. Do not adopt a newer ruff's new rules in an
+unrelated change; bumping the pin is a deliberate Dependabot change. Full rationale:
+[`docs/CI-RUNNER-ROUTING.md`, "Local / workstation ruff"](../../docs/CI-RUNNER-ROUTING.md#local--workstation-ruff).

AGENTS.md

@@ -0,0 +1,26 @@
+# claude-code-plugins
+
+## Validate a change
+
+Validate with `scripts/affected-tests.sh --run` (add `--explain` to see why each suite was
+selected) instead of running every suite; CI still runs everything. A changed file that maps
+to zero suites is an error, never "nothing to run". Full contract, including the no-suite
+allowlist and the `NOT RUN` ecosystems: [README.md, "Validate a change"](README.md#validate-a-change).
+
+<!-- BEGIN GENERATED: instruction-placement rules index -->
+
+## Conventions that load on demand
+
+Each surface below enters context automatically when Claude reads a file it covers. That trigger
+does **not** fire inside subagents, and after a compaction it fires again only when a covered file
+is read again. When you are working on something an entry covers and its content is not already in
+context, read the file directly.
+
+| Surface | Covers | Topic |
+|---|---|---|
+| `.claude/rules/catalog-taxonomy.md` | `.claude-plugin/marketplace.json` | Where the marketplace category taxonomy lives; read before adding or changing a plugin's category |
+| `.claude/rules/hook-budget.md` | `plugins/*/hooks/**` | Marketplace-wide latency budget for always-on hooks; read before adding or widening a hook |
+| `.claude/rules/ruff-pin.md` | `**/*.py` | Python linting runs through the pinned ruff wrapper, never a bare ruff on PATH |
+| `plugins/machine-health/skills/audit/AGENTS.md` | `plugins/machine-health/skills/audit/**` | machine-health audit skill: contributor conventions |
+
+<!-- END GENERATED: instruction-placement rules index -->

plugins/machine-health/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "machine-health",
-  "version": "0.11.7",
+  "version": "0.11.8",
   "description": "Workstation health audit: OS-specific checks (disk, OS updates, security posture, CISA KEV correlation) run from a versioned catalog with trend-aware severity, approval-gated remediations, and dated markdown reports. Windows fully implemented; macOS/Linux scaffolded (report UNKNOWN and stop). Machine state persists in the plugin data directory; the report directory and check catalog are configurable.",
   "author": {
     "name": "Melodic Software",

plugins/machine-health/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to the `machine-health` plugin are documented here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning.
 
+## [0.11.8]
+
+### Added
+
+- **The audit skill's directory carries a nested `AGENTS.md` with its `CLAUDE.md` shim.** Three
+  contributor conventions from the human-only skill README (semantics-vs-implementation layout,
+  dual-invocation script contract, stateless-checks invariant) now load for Claude on any read
+  under `skills/audit/`, as pointers back to the README rather than copies. Applied from an
+  instruction-placement audit (findings IP-005 through IP-007); the README remains the single
+  source of truth.
+
 ## [0.11.7]
 
 ### Changed

plugins/machine-health/skills/audit/AGENTS.md

@@ -0,0 +1,27 @@
+# machine-health audit skill: contributor conventions
+
+Maintainer conventions for this skill live in [`README.md`](README.md); the sections below say
+when to read each one.
+
+## Layout: semantics vs implementation
+
+Before adding or moving anything under `references/` or `scripts/`, read
+[README.md, "Separation of semantics from implementation"](README.md#separation-of-semantics-from-implementation):
+OS-agnostic content belongs in `references/shared/`, per-OS detection in `references/<os>/`,
+and adding a new OS must be "populate two folders", never a refactor of the skill.
+
+## Check scripts run two ways
+
+Before writing or editing a check script, read
+[README.md, "Dual-invocation scripts"](README.md#dual-invocation-scripts): every check emits a
+single JSON object on stdout for Claude (schema in `references/shared/output-schema.md`) and
+takes `-Human` for readable output, using `Write-Host` in that mode so structured emitters keep
+working over pipelines.
+
+## Checks are stateless; the orchestrator owns state
+
+Before touching a check's inputs or anything involving `state/history.jsonl`, read
+[README.md, "Stateless checks, stateful orchestrator"](README.md#stateless-checks-stateful-orchestrator):
+checks take a current reading and return it, never reading `history.jsonl` directly; the
+orchestrator (`Invoke-MachineHealthCheck.ps1`) hands them a history slice over stdin and owns all
+trend, severity, timeout, remediation, and reporting logic.

plugins/machine-health/skills/audit/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md