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 (F57). The gate grades itself on evidence — observe with no manifest, warn with a manifest but nothing running, deny once a phase is in_progress — 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.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 — CI's sweep and the lints in _output.py and _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 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 (F29, F39, F43 are one bug three times), and it is now a lint: _output.prose_number_claims() over every .py this repo keeps and _deps.doc_prose_numbers() over every .md — both sets derived off .gitignore, so a file added here is scanned by default and excluding one means a row in _output.PROSE_SCAN_EXEMPT with a reason. They fail the build on a present-tense cardinality (its N cases), persistence (`NAME` stayed at N) or completeness (all N of them, all N … have) claim — and the number may be spelled as a word, which is F59: _numeral_span() reads both spellings, for every shape, from one fixed table. 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.
• 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.