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

.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