claude-plugins: Instructions file for Claude Code

Working on this repo

A Claude Code plugin marketplace (quality-gates → plugin audit). Python here is hooks and CLI scripts, not a package: there is no [project] table, nothing is installed, nothing is published. It dogfoods its own plugin, so its hooks fire on your edits.

Which tier the plan gate is in is not a property this file may assert. The gate grades itself on evidence — observe with no manifest, warn with a manifest holding no phase, deny past the free file once it holds phases, running or not — and this sentence used to say edits "run under" it, which reads as the denying tier while only the weakest reading was true: the dogfood manifest's phases were all finished when that was written, so the gate was advisory here and had been for releases. That is exactly the kind of fact a document cannot keep. A document that names a gate owes the reader its tier or should not name the gate, and the tier is computed rather than written down — so ask the thing that computes it:

/audit:doctor          # prints which tier is active and what put it there

The TDD reminder is unconditional and non-blocking, so it needs no tier.

CONTRIBUTING.md is the rulebook and PLUGIN-BUILD-GUIDE.md is the architecture. This file states only what you must know before an edit; it deliberately restates no procedure, because two copies of a procedure is one copy and one lie.

Hard rules

• Stdlib only in plugins/audit/{hooks,scripts}/. A guard that needs pip install is a guard that is off on most machines. py-launch.sh stays POSIX-sh builtins only.
• No typing, no dataclasses, no annotations, no walrus, no from __future__. Not a style guide — _output_lints.house_style_violations() reads the AST and fails the build. The 3.8 floor and hooks that must start fast on every tool call are the reason.
• Python 3.8 floor, held by vermin -t=3.8- in CI. Formatting is %-style throughout; the tree contains no f-strings.
• Every .py under hooks/ and scripts/ is scanned wherever it sits — the coverage classifier and the lints in tools/lints/ (_output_lints.py, _deps.py) all walk recursively. The old rule saying files must stay one directory deep existed only because those scanners were flat, so a file in a subdirectory silently stopped being tested; that reason is gone. The one cost is that a .py basename must be unique across the whole of scripts/, since import and _loader both resolve by basename — layer_violations() reports a collision by name. scripts/ui/ still holds no .py.
• _output.py is the anchor and never moves. SCRIPTS_DIR, PLUGIN_ROOT, HOOKS_DIR, TESTS_DIR, LINTS_DIR and REPO_ROOT live there and nowhere else; install_path() puts scripts/ and every subdirectory of it holding a .py on sys.path. The folders are labels, not namespaces — one flat name-space, every module reached by bare basename. No other .py under scripts/ may read __file__ outside the pinned preamble (depth_sensitive_paths()).
• Fail-open for advisory paths, fail-loud for guards — the table is in SECURITY.md.
• Every claim in output carries the basis that makes it true, and when the basis is missing, that is the thing to say. Never fall back to a default to fill the gap; a basis with no claim is noise. See CONTRIBUTING.md for the worked example (cost, and the five surfaces that render it).
• Do not write a number into prose when something already prints it. This is the repo's most frequent defect (the same bug, found three separate times), and it is now a lint: _output_lints.prose_number_claims() over every .py this repo keeps and _deps.doc_prose_numbers() over every .md (both in tools/lints/) — both sets derived off what git tracks, or off .gitignore where git cannot answer, so a file added here is scanned by default and excluding one means a row in _output_lints.PROSE_SCAN_EXEMPT with a reason. They fail the build on a present-tense cardinality (its N cases), persistence (`NAME` stayed at N), completeness (all N of them, all N … have) or ratio (N of M <noun> — the tally a command prints, quoted with no command beside it) claim — and the number may be spelled as a word: _numeral_span() reads both spellings, for every shape it knows, from one fixed table — except that a bare word under ten (one case, two cases) is off by default, because it is ordinary English and only a shape that supplies its own bound (N of M <noun>) may ask for it; _numeral_span()'s docstring carries the measurement. Three things stay legal on purpose: history (it stood at N that day), a number carrying the command that re-derives it — the basis may sit on the next line, because prose wraps — and the repair itself, which is to delete the number and keep the pointer. CONTRIBUTING.md's Writing a count that is allowed states those three affirmatively, with one example each; read it before writing a number rather than after a build refuses one. When a number really is informative, carry the basis; a basis makes a claim checkable, but only deleting the number stops it rotting.
• The lint does not cover the whole class, and the part it leaves is yours. A plain the N <noun> with an ordinary noun — five claims deep — is author-enforced in both spellings, and so is a ratio you wrote yourself rather than quoted (N of the M <noun> carries an article no formatter emits). This is a refusal, not a gap waiting to be closed: the noun is unbounded, so reading it means reading every count in every sentence, and both widenings were measured over this tree and found to report honest prose almost exclusively — which is how a lint gets routed around. prose_number_claims()'s WHAT IT CANNOT SEE is the full list with the measurement behind each refusal, and pn31 is the case that goes red if somebody widens one. So a green build is not evidence that a number you wrote is safe; it is evidence that none of the shapes the lint knows matched.
• Every command that mutates the manifest revalidates via scripts/manifest/validate-manifest.py.
• COMPATIBILITY.md is a contract, not a description. It promises that a meta.version the plugin accepts keeps being accepted and that a config key it reads keeps being read. So removing either, or changing which of two keys wins, is no longer a judgement call — it is a major release. Adding is always free. The document also names what is deliberately not promised; extend that list rather than quietly widening the promise.