holocron/docs/spec/gates.md

Enforcement gates

Reference for this repo's pre-commit and pre-push hooks: what each one guards, what its numbers mean, and which shapes were tried and rejected. Read it when a gate fails, before changing anything in .pre-commit-config.yaml, or before "fixing" something that looks like an inconsistency — several of the oddities documented here are load-bearing and have already been re-litigated once.

AGENTS.md carries only the operative rules an agent needs in the moment. The reasoning lives here.

---

Running the gates

Command	Scope
pre-commit run --all-files	the commit-stage hooks
pre-commit run --hook-stage pre-push --all-files	the push gate, one command
pre-commit run skill-size-check --all-files	just the ADR-0020 size/context gates

Install hooks via pc-run, wiring all three stages. This repo's .pre-commit-config.yaml has no default_install_hook_types, so a plain install silently skips commit-msg (Conventional Commits) and pre-push (everything below).

The pre-push command reports 11 hooks, not 9. The extra two are pre-commit's own meta hooks, check-hooks-apply and check-useless-excludes: they declare no stages:, so they run at every stage including this one. Both are declared in this repo's .pre-commit-config.yaml like everything else — what separates them is repo: meta (pre-commit's own built-ins) from repo: local. Nine is the count of hooks this repo authors itself, and --hook-stage pre-push --all-files is a full rehearsal of all nine. A PR merged through Gitea's merge button runs none of them: no local push happens at all.

A real push has a gap of its own. When one git push carries several refs (git push origin a b, git push --all), pre-commit runs the pre-push stage once, for one ref. In pre-commit 4.6.1, _pre_push_ns in hook_impl.py skips delete lines and returns on the first remaining ref whose remote sha is non-zero and present locally; a ref whose remote sha is zero or unknown locally is returned only if it has commits that no remote-tracking ref of that remote has. The one hook that reads the pushed ref, check-skill-version-bump, therefore checks only that ref, and the others are pushed unchecked. When that ref's unpushed history reaches a root commit, pre-commit runs with all files and sets no PRE_COMMIT_TO_REF, so check-skill-version-bump checks HEAD, which is the pushed ref only if it is checked out. Push one ref at a time when the gate matters.

The pre-push gate

Nine hooks, grouped below by what they guard rather than by the order .pre-commit-config.yaml declares them in.

Core checks

Hook	Guards
run-tests	bash tests/run-tests.sh --strict — the whole suite, skips fatal (see Tests)

Generated-content drift gates

Hook	Guards
check-scope-walkup-sync	validate.sh, validate-provenance.sh, new-agent.sh and new-skill.sh's four independent $HOME/.git/apm.yml walk-up ports still agree behaviorally
check-executables-allow-sync	root apm.yml's executables.allow key names kyberforge's actual version (see apm gates)

check-executables-allow-sync is the odd one in this group: the drift it guards is in a hand-written key rather than in generated text, and it is a record-keeping gate — the grant itself is version-blind, so a stale key deploys fine (see apm gates).

Artifact validators

Hook	Guards
check-apm-agents-valid	runs factory-audit's validate.sh over every real plugins/*/.apm/agents/*.agent.md (see Agent files)
check-provenance-corpus	runs factory-audit's validate-provenance.sh over every real plugins/*/.apm/skills/*/ that has a references/sources.md, failing on any FAIL (see The provenance corpus sweep)

apm's own gates

Hook	Guards
apm-audit-ci	scripts/apm-audit-ci.sh — apm audit --ci once per manifest, root plus each of the seven plugin packages, waiving only a package's lockfile-exists (see below)
apm-pack-check-clean	apm pack --check-versions --check-clean --dry-run — the compiled marketplace still matches what apm.yml + .apm/ would generate, and per-package versions agree with the per_package strategy

Host validators (needs the claude CLI on PATH)

Hook	Guards
validate-marketplace	claude plugin validate --strict on the root marketplace manifest

Skill versioning (every push, any branch)

Hook	Guards
check-skill-version-bump	fails if a skill directory changed since the pushed commit's merge-base with main without its metadata.version rising above both the merge-base's and main's tip's (see below)

Two of these shell out to apm: apm-audit-ci and apm-pack-check-clean. The second is a bare apm … entry and the first is scripts/apm-audit-ci.sh, which calls apm once per manifest, so without the CLI on PATH the push dies on a "command not found" from inside the hook. Install with apm-install, or curl -sSL https://aka.ms/apm-unix | sh; verify with apm --version.

check-skill-version-bump

ADR-0022 makes metadata.version mandatory and says a skill change carries a bump; skill-size-check only checks the field's presence and shape, so this hook holds the bump itself.

• It runs on every push and under a manual pre-commit run --hook-stage pre-push. It does not read PRE_COMMIT_REMOTE_BRANCH, so the manual rehearsal really checks it. The pushed commit is PRE_COMMIT_TO_REF, or HEAD when that is unset.
• "Changed" is measured from the merge-bases of the pushed commit with origin/main (local main if origin/main does not resolve), resolved with git merge-base --all — all of them, not the single one git would otherwise pick. Readers install from main, so "changed" means changed against the main the branch started from. The remote branch tip is not the baseline: a second push would excuse an unbumped change the first push already carried.
• With more than one base, the changed-skill sets are intersected. A criss-cross history — main merges a branch while that branch merges a main commit — has two merge-bases, and which one a bare git merge-base prints is an implementation detail, so picking one made the verdict a coin flip: a skill already identical to main was reported (not above merge-base) whenever the losing base was chosen. A skill therefore counts as changed only when it differs from every base; differing from none of them, or from only some, means a base already carries the pushed content. A skill that does count as changed must then beat the version at every base it exists at. Both directions are conservative: the intersection cannot exempt a skill that changed since all of main's reachable history, and requiring every base keeps the ratchet.
• A changed skill's version must beat two baselines: its version at each merge-base and its version at the tip of the same main ref (ADR-0022's second 2026-09-16 amendment). The tip check stops two branches that make the same bump (1.0.0 → 1.0.1) with different content from both landing, since the identical version lines merge without a conflict. A skill absent at the tip is held to the merge-bases alone, and so is one whose directory at the pushed commit is the same tree object as at the tip — compared as object ids, because a tree id is the content whatever route the history took to it. That skill ships exactly what main ships, so there is nothing for a bump to announce. The intersection does not already cover it: it exempts only when some base carries the content, which a criss-cross history gives and a cherry-pick of a fix main already has does not. When main has not moved, the tip is itself a base and the skill is checked once. Each failure line names the baseline it missed: (not above merge-base), (not above merge-base <sha>) when there is more than one base to tell apart, or (not above origin/main tip). The tip is origin/main as last fetched.
• It fails closed when it has no trustworthy baseline: neither origin/main nor main resolves; there is no merge-base (shallow clone, unrelated history); or only local main resolves and the pushed commit is the merge-base, so local main already contains the pushed commit and says nothing independent about what shipped.
• A changed skill must end strictly above each baseline version, compared numerically (1.0.10 > 1.0.9). Any bump size passes. A missing or non-MAJOR.MINOR.PATCH version at the pushed ref fails, and so does a skill directory left without its SKILL.md. Each part is ASCII digits, at most nine of them, with no leading zero (1.0.08 is malformed) — the same shape skill-size-check enforces, so a Unicode digit, an overflowing part or an octal-looking part cannot pass as a bump. A leading UTF-8 BOM is ignored. A baseline with no valid version accepts any valid version. Skills absent at both baselines (new, renamed, merged) or at the pushed ref (deleted, or replaced by a symlink) are exempt. A file moved between skills counts as a change to both: renames are diffed as delete plus add. A mode-only change counts too.
• It also fails closed on read errors: a pushed ref that does not resolve to a commit (including a tag on a tree), or a SKILL.md that the tree names but git show or python3 cannot read, stops the push with a read-failure message rather than being reported as a missing version or treated as an absent skill. Presence is read from the tree, so a blob missing from a corrupt or partial clone cannot make a skill look new. Frontmatter that reads but does not parse counts as an invalid version.
• <skill>/tests/ is excluded: no agent loads it, so a test-only change ships nothing.
• It needs python3 and PyYAML to read the frontmatter, and fails with a clear message if either is missing, for the reasons in python3 and PyYAML are hard requirements.
• Known gaps: a PR merged through Gitea's merge button runs no local hook; and a multi-ref push checks only the one ref pre-commit selects, and a push reaching a root commit gets no PRE_COMMIT_TO_REF, so HEAD is checked (see Running the gates).
• An all-zeros PRE_COMMIT_TO_REF (a branch delete) exits 0. The branch is defensive: pre-commit 4.6.1 skips delete lines before it sets the variable.

Skill and agent context gates (ADR-0020)

The skill-size-check pre-commit hook, scoped to ^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$, runs scripts/skill-size-check.sh. Besides the ADR-0020 gates below, it also asserts required frontmatter is present: name, a non-empty description, and a metadata.version matching three-part semver (1.0.0) — folded in from a formerly standalone skill-frontmatter hook that parsed the same fields with a shell script.

Two things fall outside that scope, both deliberately. The [^/]+/SKILL\.md$ tail admits only a SKILL.md sitting directly in a skill directory under .apm/skills/:

• the plugins/kyberforge/docs/research/examples/ reference skills, which are vendored upstream corpus and not this repo's to gate;
• plugins/kyberforge/.apm/skills/skill-author/assets/templates/SKILL.md — inside .apm/skills/, but two directories deeper. It is the FILL IN: scaffold skill-author copies, so its description: > is a comment block rather than a description and every ADR-0020 measurement over it would be meaningless. A reader adjusting the pattern needs to know it is there.

Everything else it matches exactly, with nothing over- or under-caught. Re-derive both halves:

git ls-files | grep -cE '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$'          # the real skills
git ls-files | grep -E '^plugins/[^/]+/\.apm/skills/.*SKILL\.md$' \
             | grep -vE '^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$'          # the scaffold only

The first count equals the number of skill directories (ls -d plugins/*/.apm/skills/*/ | wc -l); the second returns exactly the template. Every other tracked SKILL.md in the tree is one of the four vendored plugins/kyberforge/docs/research/examples/skill-write/ corpus files, excluded by the .apm/skills/ segment — the first of the two deliberate exclusions above.

Two independent gate families, neither replaced the other

Family 1 — agentskills.io spec backstop (unchanged, conformance not quality):

Constant	Value	Measured over
MAX_LINES	500	whole file, frontmatter included
MAX_WORDS	2,770	whole file, frontmatter included

Family 2 — ADR-0020 context budget (measured differently, on purpose):

Check	SUGGESTION	FAIL	Measured over
description characters	250	400	the YAML-folded value
body words	600	900	body only — everything after the frontmatter's closing ---

Plus two hard FAILs with no suggestion tier:

• A missing, valueless or null description:. Not a skip. The description is the one field preloaded into every session, so a gate that declines to measure it reports green. (This is not hypothetical: description: with no value followed by model: sonnet let a line regex capture the next key, which looked non-empty, so the "missing or empty" branch never fired and every gate below early-returned on the genuinely empty folded value — exit 0, zero output, on a blocking gate.)
• Every references/<file>.md a body names must exist on disk. A dispatch table pointing at a file that was never written is a silently dead branch, and nothing else in the gate/audit/vale stack notices it.

A file can sit well inside one family and fail the other. 2,770 whole-file words is a conformance backstop; 900 body-only words is a quality gate. Conflating them is what produced the current state.

An unresolved routing target is not automatically a FAIL

A boundary-clause target that resolves to no skill or agent has three possible verdicts, not one (unresolved_targets() in scripts/skill-size-check.sh):

Verdict	When
SUGGESTION — the default	the target does not resolve and neither promotion condition below holds
blocking ERROR	the target is written in route notation — /name for any name, or any arrow form (a bare -> name only when the name is hyphenated, a backticked -> `name` for any — see the gap below); or it is a bare terminal name (not a compound modifier) corroborated by another target in the same sentence that does resolve
INFO, "DID NOT RUN"	no skill universe could be determined for the path at all — the targets are named and left unchecked, exit 0

The default is deliberately soft because a hyphenated word in a boundary clause is as likely to be a tool, a file format or an English compound as a route: "pre-commit hooks" is prose about a tool and never reaches the check at all, being a compound modifier rather than a terminal name. The SUGGESTION text says how to opt in — write it as /name or -> name and it gets checked properly.

The two promotion conditions are not symmetric, and the order matters. _add() decides notation first: when the name is written /name, or reached through any arrow form, the target is marked error-eligible there and the terminal test is never run. Terminality gates only the bare path — a name in prose earns its error from corroboration, and a compound modifier can never dangle. Reading the row as "terminal AND (notation OR corroborated)" gets the notation half backwards: it predicts that … Do not use for Y — use /no-such-skill afterwards. is a SUGGESTION, because afterwards is a follower outside FOLLOWER_OK. It exits 1. That was the defect — -> name reached _add() with strict=True from both its call sites and /name did not, so the one spelling ADR-0020 offers an author who wants a route checked unconditionally was the one spelling a stray follower could silence.

Known gap: a BARE arrow target must be hyphenated. Target extraction is built on NAME_HYPH in scripts/skill-size-check.sh, which requires at least one hyphen, and ARROW_BOUNDARY inherits that. So Not X -> gitea-prs is extracted and checked, while Not X -> triage yields no target. The exclusion is deliberate, not an oversight: research, triage, forge, prototype and tdd are all real skill names and ordinary English, so a bare single-word rule would flag most of the corpus. The marked spellings carry no such restriction — `triage` and /triage are both extracted — and are the forms to prefer. Both arrow spellings are recognised: ARROW_MARKED, ARROW_BOUNDARY and BOUNDARY_ARROW are each built from (?:->|→), so the unicode arrow → behaves exactly like -> in every case below. Cite these constants by symbol name, never by line number: the script moves often enough that a pinned line lands a reader in an unrelated comment block and reads as plausible.

The gap is no longer silent. It used to be exactly that — no ERROR, no SUGGESTION, exit 0 — which made the dangling-target SUGGESTION's own advice unsafe for a single-word skill: taking it silenced the finding instead of checking it. boundary_clause_status() now separates the case out and reports it as unparsed (see below), naming the parse failure and the two spellings that fix it. The target is still not resolved; the author is now told so rather than left with a green gate. tests/test-adr0020-targets.sh covers both directions (arrow-single-word-target and the silent control arrow-single-word-marked).

Corroboration is what makes the soft default safe: a sentence whose other target resolves is demonstrably a routing sentence, so a sibling that does not resolve is a typo rather than a noun, and gets promoted.

Target resolution walk

Resolution walks up from the file being checked — never from the script's own location. Deriving it from ${BASH_SOURCE} leaked holocron's own skill universe into every consumer repo running the hook through pre-commit, so a consumer skill routing to a holocron skill (skill-audit at the time, now factory-audit) resolved against a plugin it had never installed.

The walk finds an authoring root: the nearest ancestor holding plugins/*/.apm/skills or plugins/*/.apm/agents, falling back to the nearest ancestor holding .git. Two passes, not one interleaved walk, so a nested .git (a submodule, a sub-package worktree) cannot beat a real monorepo root further up.

The universe is then:

1. every skill and agent under <root>/plugins/*/ — sibling plugins resolve, which is what a monorepo means;
2. the checked file's own apm package;
3. the packages that package declares in its own apm.yml dependencies.apm.

The root manifest's dependencies: block is not read, and no plugin here declares a cross-plugin apm dependency — none needs to.

Deployed .claude/ / .agents/ trees are consulted only when the walk found no plugin monorepo root, whether it landed on a bare .git ancestor or on nothing at all. That is the consumer case.

The gate keys on which of the two passes matched, never on whether the root contributed a new name. A name-count delta looks equivalent and is not: _collect_authoring_root() re-collects the checked file's own plugin, whose names the earlier steps already added, so a single-plugin monorepo shows a delta of zero and would wrongly reach for the deployed trees — including the user's global ~/.claude/skills, making the verdict depend on what happens to be installed.

Why it matters: those trees are gitignored apm install output, present only on a machine that has run it. Four cross-plugin targets here (gitea-branches → git-branches, gitea-branches → git-history, gitea-issues → git-branches, gitea-workflow → git-workflow) once resolved through .claude/skills/ alone, so the same commit measured 2 dangling targets on a developer machine and 6 on a fresh clone. A gate shipping hot with no baseline cannot give two answers.

Verified: running the hook over a tree holding only plugins/ and the root apm.yml, with no .claude/ or .agents/ anywhere, produces findings identical to the working tree — confirming the two trees agree on the current corpus, independent of what happens to be installed locally.

Boundary-clause detection: three outcomes, not two

boundary_clause_status() returns one of three values, and the two findings get separate messages:

Status	When	Reported as
present	a prose marker (do not, instead, rather than, not for) or an arrow clause was found	nothing
absent	neither was found	SUGGESTION: add a boundary clause, in either form
unparsed	an arrow clause was found and no target could be read out of it	SUGGESTION: the clause is present — this is a parse failure, not a missing clause

The third had to be split out. Collapsing it into absent is a wrong finding, not a strict one: it sends the author to add a clause that is already there. Three of them instead reworded a correct clause until the regex accepted it, one stripping the very filename that discriminates the skill from its neighbour (#110).

unparsed is narrow and certain on purpose. It fires only on the arrow form, which always names a target, so zero targets means the name is written in a shape the extractor cannot see — in practice a bare single-word target, per the known gap above, and the message says to write it `name` or /name. A prose clause yielding no target is not reported at all: "Do not use for anything else" is a complete and legitimate boundary clause that names nowhere to go.

One arrow, one target. An arrow clause naming two or more targets draws its own SUGGESTION, quoting both names and asking for a split, because only the first is ever resolved: the conjunction continuation (CONT_MARKED / CONT_ANY) is wired to the prose route verbs and never to arrows. So Not X -> a or b resolved a, left b resolved by nothing and reported by nothing, and then let the audit print "1 of 1 boundary target(s) resolve" on a clause naming two — a gate under-reporting its own coverage, which is the one failure mode ADR-0020 says a gate must not have (#107). The clause is rejected rather than the arrow scan extended: extending it would widen the resolver's deliberately conservative false-positive tuning across every arrow in the corpus, where splitting costs the author one full stop. The convention is one arrow per target — Not X -> a. Not Y -> b. — already what every retrofitted gitea-* skill does in practice, now stated in skill-author's references/contract.md instead of being folklore.

Dotted filenames in a boundary clause now parse. CLAUSE_BODY — what may sit between Not and the arrow — used to be [^.;], a class that cannot cross a ., so every clause naming a dotted filename between the two (AGENTS.md, .vale.ini, .pre-commit-config.yaml) was invisible to both BOUNDARY_ARROW and ARROW_BOUNDARY. The two resulting failures were different sizes (#110):

• with a backticked target the clause was misdiagnosed. The backtick sweep still extracted the target, so the route was checked, but the gate reported "no boundary clause" on a clause that was present and working. That is the misdiagnosis the three rewordings above came from.
• with a bare target the clause was unchecked. ARROW_BOUNDARY is the only extractor for a bare arrow target, so Not AGENTS.md -> no-such-skill produced no target, no dangling report and no missing-clause SUGGESTION. Silence, not noise — the worse of the two.

CLAUSE_BODY is now (?:[^.;]|\.(?=\S)): a dot inside a filename is followed by a non-space, a sentence-ending dot by whitespace or end of string, so the class crosses AGENTS.md and still stops at a real sentence end. Read the second bullet forward as well as back: a bare target sitting after a dotted filename is now extracted, resolved, and a blocking ERROR when it dangles, where the same clause used to pass unchecked in silence.

Body-level routing targets (issue #124)

Everything above resolves targets named in the description — the one field boundary_targets() and unresolved_targets() read. Until issue #124, a target named in the body — a dispatch table or a "run X" step, both routine in a 900-word procedure — was checked by nothing: bin/write-docs routed twice to a deleted to-prd skill and bin/triage told an agent to run a nonexistent /setup-matt-pocock-skills, and both were found by reading, not by any gate (fixed in 03abcff; the gate itself is the ask this section documents).

body_targets() / unresolved_body_targets() (lib-boundary-resolver.sh) are a separate, narrower extractor, not a reuse of the description one at wider scope. A body is dispatch-table and procedure prose, not a one-to-three-sentence routing clause, so BOUNDARY_MARKER, the follower test and in-sentence corroboration all misfire on it in both directions — under-firing on a table row that carries no "do not"/"instead", over-firing on a procedure step that names a file, a CLI verb or a config key exactly the way a route names a skill. So the body gate reads only notation, already the description gate's own "always blocks" tier, and nothing softer:

Form	Pattern	Requires
/name	NOTATION_SLASH	a hyphen in name; not preceded by <
-> name / → name	ARROW_MARKED	the name backticked or slash-prefixed — NOTATION_ARROW's bare form is not used here

Both constraints exist because the corpus, not intuition, said so — each is a real false positive this gate produced once and was narrowed to remove:

• No SUGGESTION tier, no continuation, one arrow per target. Both forms are notation, and notation is unconditionally blocking — there is no ambiguous prose reading left to soften, so there is nothing to report at a softer tier. CONT_MARKED/CONT_ANY are not run either, so -> \a` or `b`resolves onlya`, same as the one-arrow-one-target convention #107 already states for descriptions — enforced here by construction instead of by a second SUGGESTION.
• A bare hyphenated word after any arrow is not notation here. NOTATION_ARROW (used for the description gate's own Not X -> name sweep) matches a bare -> name unconditionally, and a body is full of ordinary arrow prose that is not a route: caveman's own Inline obj prop -> new ref -> re-render. read as a dangling route to re-render under that pattern. ARROW_MARKED requires the target to be backticked or slash-prefixed, which the one real historical target (-> `to-prd`, per 03abcff's diff) already was, so the narrowing costs no real coverage.
• A single-word target is discarded, even in notation. `/fork` (forge/SKILL.md, contrasting context: fork with Claude Code's own /fork subagent command) and `/name` (skill-author/SKILL.md, "the user types /name" — a placeholder for the skill's own name, not a route) are both real corpus citations of a tool or a placeholder, not routes, and both hard-FAILed with no escape hatch before the hyphen requirement was added. This is a real, accepted recall loss: a body dispatch entry to a genuinely single-word skill (forge, research, triage, tdd, prototype) cannot be checked through this extractor. Same trade the description gate already makes for the bare form (the known gap above), extended here to notation as well because the body genre has no boundary-sentence signal to lean on instead.
• A name immediately preceded by < is a closing tag, not a route. grill-with-docs/SKILL.md uses XML-style prompt delimiters (<what-to-do>...</what-to-do>, <supporting-info>...), and </what-to-do> is indistinguishable from /what-to-do notation by every other rule above. No route is ever written directly after < in this corpus, so the guard costs nothing else.

Fenced code blocks are masked first (mask_fenced(), the same masking gotcha_stats() and the references/-pointer check already use): an illustrative ```/some-skill``` in skill-author or factory-audit — which document this very notation — is not a live dispatch entry.

Both consumers agree by construction: scripts/skill-size-check.sh and factory-audit/scripts/lib-checks-skill.sh each call body_targets()/unresolved_body_targets() independently, over the same known_targets() universe the description check already computed, so the "DID NOT RUN" INFO tier covers both description and body targets in one message rather than firing twice. tests/test-adr0020-targets.sh's "body-level routing targets (issue #124)" section pins both the two live true positives and every guard above; the corpus-wide dangling assertion (EXPECTED_DANGLING) covers body targets the same way it already covered description ones.

SUGGESTION-only checks

Deterministic to measure, judgment to act on:

• a description with no boundary clause at all (absent);
• an arrow clause whose target could not be read (unparsed);
• an arrow clause naming more than one target;
• a ## Gotchas section with more than five entries;
• a ## Gotchas section over 25% of the body.

Hand-invoked skills are exempt from the routing rules, and only those

A skill or agent whose frontmatter carries disable-model-invocation: true skips three checks:

• the boundary-clause check, absent and unparsed alike;
• the multi-target arrow check;
• the 250-character description target (hand_invoked() in scripts/skill-size-check.sh).

It keeps the 400-character description FAIL and both body word tiers, and if its description does happen to name a target, that target is still resolved and can still dangle.

Why the exemption is right: disable-model-invocation: true removes the skill from the model-visible listing entirely — it is not preloaded, and the Skill tool refuses to call it — so its description is never matched against user intent. ADR-0020 and skill-author's contract therefore give such a skill one plain human-facing sentence: no trigger list, no boundary clause. No validator knew the field existed (#108), so the boundary-clause SUGGESTION fired on exactly the shape the contract mandates, and its remedy — "so the router knows where NOT to send this skill" — was addressed to a router that cannot see the skill at all. An author who followed the advice made the file worse. There is no router to inform.

The half that does not lift is the point. The body is still loaded on invocation and still competes with the caller's live conversation, so neither body tier moves. The 400-character ceiling stands too: a hand-invoked description is not preloaded, but it is still the one line the user reads when choosing from the / menu, and that ceiling is an outlier stop rather than a routing-quality budget — which is precisely why the 250-character target is the tier that lifts.

The field is read as a boolean, not as a mention of the key. PyYAML already resolves the unquoted YAML 1.1 booleans, so the extra handling catches a quoted "true", which a host reads as truthy; disable-model-invocation: false is the model-invoked case written out longhand and buys nothing. A frontmatter parse failure returns false rather than raising — the flag is a modifier on other checks, and description_value() on the same text already reports the broken frontmatter, so raising here would diagnose one file twice two different ways.

caveman and zoom-out are the two carriers here. tests/test-skill-size-check.sh pins both halves — what the carve-out lifts, each with a flag-removed control, and what it must not.

verbose: true is load-bearing

The hook is declared verbose: true so the SUGGESTION tier is audible. pre-commit prints nothing at all for a passing hook, and a SUGGESTION deliberately does not fail — without verbose every suggestion is swallowed, which is exactly the invisibility ADR-0013 records for Vale warnings. ADR-0020's preload arithmetic depends on it: writing to the 400-char FAIL delivers roughly half the cut that writing to the 250-char SUGGESTION does, so the intended saving depends entirely on that tier being visible. The numbers, and the measurement method behind them, are not restated here — they live in ADR-0020's Consequences section, under "A ceiling does not produce an average", whose figures are pinned to the base commit the decision was taken on (f9b919d). Quoting them here would just create a second copy to go stale. It costs nothing on a clean file — the script prints only findings.

Duplicated constants

factory-audit holds a second copy of the four ADR-0020 constants (DESC_SUGGEST_CHARS / DESC_MAX_CHARS / BODY_SUGGEST_WORDS / BODY_MAX_WORDS). They are not in its validate.sh, which carries none of them: they live in the mode libraries it sources — scripts/lib-checks-skill.sh:313-316 carries all four, and scripts/lib-checks-agent.sh:164-165 carries the two description constants only. That split is the contract stated directly: the two description constants apply to both artifact types factory-audit handles, the two body constants only to skills. They are copied rather than imported because a skill's files may not reach outside that skill's own directory (the self-contained constraint in docs/spec/architecture.md, "Plugin model"), and scripts/skill-size-check.sh does not ship with the plugin. tests/test-skill-size-check.sh asserts the copies agree, so drift fails CI rather than silently letting an audit bless a skill the commit hook then rejects.

The shared boundary resolver is one copy (ADR-0025, then 2026-09-16). It lives between the BEGIN/END ADR-0020 SHARED BOUNDARY RESOLVER markers in factory-audit/scripts/lib-boundary-resolver.sh. ADR-0025 collapsed the two copies inside skill-audit's and agent-audit's validate.sh into that file. scripts/skill-size-check.sh kept an embedded, byte-identical third copy while it was also exported through .pre-commit-hooks.yaml, whose consumers could not reach a file inside the plugin. 4de5b6b retired that export (ADR-0014), so the hook now sources the library by path and fails closed if the library is missing or defines no resolver.

tests/test-adr0020-contract.sh pins that arrangement: the library carries the only marker pair, the hook carries none, the hook fails closed without the library, and a sentinel planted in a copied library proves the hook executes the library's text, and a later block pins every repo-authored pre-commit hook's entry and stages. One of its assertions was green on a defect it named. "validate.sh sources the resolver in both mode branches" was implemented as a file-wide grep -Ec … -ge 2, which cannot see a branch at all: delete the agent) arm's source line and duplicate the skill) arm's, and the file-wide count is still 2 and the assertion still passes, with the agent path running no resolver or some other one. It is now a per-arm structural check — each arm of validate.sh's case "$MODE" in block must carry exactly one source line inside its own body, and the file must carry exactly those two — with a mutation self-test that performs that exact count-preserving edit on a copy and requires the check to fail on it. The suite's case count runs 28 → 27 → 29 → 44, and is 44 at HEAD: 28 at 620f20b (the ADR-0025 merge), 27 after 4de5b6b retired the .pre-commit-hooks.yaml export, 29 after ef27c97 replaced the two-copy hash and its line-count floor with the six one-copy assertions above, and 44 after 384756b added the hook-wiring block. An earlier revision of this section stopped the chain at 29 and called that the figure at HEAD; it was written before 384756b. There are two 2026-09-16 changes here, not one, which is what an earlier revision of this section conflated. Each figure is bash tests/test-adr0020-contract.sh run at that commit — in a worktree for the historical ones — reading its Results: line. An earlier revision also opened the chain at 25; that predates the branch squash, no reachable commit reproduces it, and it is dropped as unverifiable rather than carried.

python3 and PyYAML are hard requirements

Both, and neither is a best-effort accelerator.

python3 because the script measures the folded description value. Most descriptions here are >-block scalars, so a regex over the raw lines measures indentation and newlines instead of the value. Missing it fails the hook with an install pointer rather than skipping the ADR-0020 checks, which would be a vacuous green — a gate that reports success without having checked anything. In practice it is already present — pre-commit is itself a Python application.

PyYAML because the hand-rolled fallback frontmatter reader has been removed deliberately. It disagreed with a real parser across the FAIL boundary — one corpus description measured 270 characters parsed and 412 unparsed — and a quoted "description" key or an explicit description: null returned empty from it, silently skipping the description and routing checks. A reader that mis-parses an unfamiliar scalar shape reports a clean pass on a file it never measured, which is the exact vacuous-green failure the python3 check exists to avoid. pip install pyyaml (or python3 -m pip install PyYAML, or the distro's python3-yaml) if the hook reports it missing.

Neither requirement generalises to every hook in this repo. check-rtk-prefix needs python3 but not PyYAML: it reads the markdown body and never touches frontmatter, so it has no scalar to fold. check-skill-version-bump needs both, for the same reason as skill-size-check: it parses metadata.version out of frontmatter.

Agent files take the description gates, not the body gate

check-apm-agents-valid runs factory-audit's validate.sh over every real plugins/*/.apm/agents/*.agent.md. It derives its expected file set from git ls-files — the pattern tests/run-bats.sh established — so an agent file deleted from the worktree but still tracked fails the run, and discovering zero agent files is an error, not a pass. An untracked new agent file is still validated: the derivation is one-directional on purpose, so uncommitted work is not blocked but also cannot bypass the gate.

The hook exists because validate.sh was previously exercised only by check-scope-walkup-sync, against synthetic mktemp fixtures — it had never run against the agent files it governs. That is how ADR-0016 could be amended to bless a disallowedTools frontmatter field while validate.sh's allowlist still rejected it: spec and enforcer disagreed and every gate stayed green.

Agents take the ADR-0020 description gates and, deliberately, no body word gate. The two description constants factory-audit applies to an agent live in scripts/lib-checks-agent.sh:164-165; an earlier revision of this line put them in its validate.sh, which carries none of them (see Duplicated constants). A skill body is loaded into the caller's context and competes with the live conversation; an agent body becomes the system prompt of a fresh context. The rationale for the 900-word FAIL does not transfer. A bats test pins that absence for the agent path of factory-audit's validator — adding a body gate there contradicts the ADR rather than fixing an inconsistency. The merge did not change this: the validator auto-detects the target type, and the body gate applies on the skill path only.

Be precise about the scope of that guarantee: it holds for the validator, not for the shared script. scripts/skill-size-check.sh applies its body gate to whatever path it is handed, and

bash scripts/skill-size-check.sh plugins/*/.apm/agents/*.agent.md

exits 1 today with 900-word body FAILs on git-orchestrate and gitea-orchestrate. (Counts are deliberately not pinned here — agent bodies are edited like any other file, and a figure in this paragraph goes stale the moment one is trimmed. Run the command.) Agent files escape only because the hook definitions filter on SKILL.md — a file-pattern accident that happens to implement the design, not the design itself. Do not "extend" that hook's files: pattern to cover agents on the assumption that the script already knows the difference; doing so silently enforces a gate ADR-0020 declines to set.

The three exit tiers of factory-audit's validators

validate.sh and validate-provenance.sh use the exit code to say whether an audit happened, not only what it found. The skill's flow references tell the auditor to surface a non-zero run's output verbatim as real findings, so the distinction is load-bearing rather than cosmetic:

Exit	Means
0	audited, and clean
1	audited, and there are findings — or the target is present but cannot be opened
2	nothing was audited. The checks never ran

Exit 2 covers: no arguments at all; a target that does not exist, with its own "does not exist" message; a target matching neither the skill nor the agent shape; a missing or unreadable lib-*.sh beside the entry script; and a missing python3 or PyYAML. Every one of those used to exit 1, so an install problem or a typo'd path arrived at the auditor as findings about the artifact. A missing target was the sharpest case: only the directory branch stats the target, so a typo'd *.agent.md path was classified on name alone, handed to python3, and came back as a FAIL about a file that was never there.

A dangling symlink or a symlink loop stays exit 1, deliberately. Both are false to -e and true to -L, and the existence guard tests both: something is at that path, it just cannot be opened, and "exists but unreadable" is a real finding the check suite reports as a FAIL naming the file. Catching them in the existence guard would replace that FAIL with a false "does not exist".

--help is exit 0 and now works with a library missing. validate-provenance.sh sourced both provenance libraries at the top of the file, so a partial install turned the one command that explains how to use the script into an exit 2; the libraries are now loaded only when a mode's half of the usage is actually printed, and when one is gone that half says so instead of the whole command failing. It also separates an empty positional from no positional — validate-provenance.sh "", an unquoted variable that expanded to nothing, used to be reported as "only flags were given", which sent the reader after a flag they never typed. Both are exit 2, with different messages.

All three entry scripts are CDPATH-safe. cd prints the directory whenever CDPATH supplied it, so a bare cd on a path starting with neither / nor . can both emit an extra line into whatever captures it and resolve to an unrelated tree. Every such site now does CDPATH='' cd -- …: SCRIPT_DIR and the target's parent-directory name in validate.sh and validate-provenance.sh, and both sites in vale-wrap.sh — its default --config resolution, and the directory-mirror walk below. The two bare cds left in vale-wrap.sh take absolute paths (mktemp -d output, and the mirror root derived from it), which CDPATH is never consulted for.

The second of vale-wrap.sh's two sites is not an asset lookup: its directory mirroring runs cd "$arg" && find -L . … -print0 on a path argument, which is relative whenever the caller passed a relative one. With an exported CDPATH holding a same-named directory, the cd emitted the decoy's path into the -print0 stream and the mirror was built from the decoy's files. It is cleared the same way now. Only the cd changed: the walk still mirrors the whole tree, prunes .git, and follows symlinks with find -L because vale does.

That one was latent, not a live gate defect. Neither published Vale hook reaches it: both filter on files: patterns that match single markdown files, and only the -d "$arg" branch mirrors a directory. The exposed caller is the hand-invoked vale-wrap.sh <dir>.

The provenance corpus sweep (ADR-0028)

check-provenance-corpus runs validate-provenance.sh over every real plugins/*/.apm/skills/*/ directory that has a references/sources.md, and fails on any FAIL. The set is discovered by glob, not counted, so a new skill is covered the moment it grows a sources.md, and discovering zero skills is an error, not a pass.

The hook exists because nothing else ran the validator over the real corpus. check-scope-walkup-sync invokes it only against synthetic mktemp fixtures, and factory-audit's bats suite does the same. So a Research doc: naming the wrong file, or a slug absent from its Research registry, could only be found by hand-running the validator in a loop. That is how 36 mismatches (#121) reported INFO while every gate stayed green. ADR-0028 promotes "the check ran and found a mismatch" from INFO to FAIL; without a caller across the corpus that FAIL tier would be inert.

It reuses the validators' exit contract (see the three exit tiers) and keeps the tiers apart:

Exit	Means
0	every skill validated. INFO-only findings are printed, never swallowed
1	at least one skill FAILed. The summary line names the failing skills
2	the gate could not run: the validator is missing, a skill's validator run exited 2 ("not auditable"), or no skill with a references/sources.md was found

A validator exit 2 is reported as a gate error, not as a FAIL about that skill: it says the audit never happened, and the skill has not been shown to be wrong.

An unresolvable Research doc: path stays INFO by design, because a deployed copy of a skill outside this repo will not carry the research docs (see skill-file-structure.md's sources.md exemption). This repo's own corpus is audited from the authoring source, where every path resolves, so an INFO printed here is worth reading. Needs no network; needs python3, which the validator's own preflight names.

Current retrofit status

The ADR-0020 gates ship hot, with no baseline file — a shrinking baseline was considered and rejected. The corpus is currently clean on both: 0 of 38 descriptions/bodies exceed their FAIL tier, 0 dangling targets, 0 Kyberforge.CompositionNote (Vale) errors. History: issue #99.

Nothing is grandfathered — a new skill, or an edit that crosses a FAIL tier, is blocked on first commit. SUGGESTION counts are not pinned here; they move with every edit. Measure and check both gates before starting work on a skill:

bash scripts/skill-size-check.sh plugins/*/.apm/skills/*/SKILL.md | grep -c '^SUGGESTION'
pre-commit run --all-files    # size AND Vale — skill-size-check alone can pass while Vale still blocks

The rtk prefix gate (ADR-0023)

check-rtk-prefix is a repo: local pre-commit hook running scripts/check-rtk-prefix.sh over ^plugins/[^/]+/\.apm/(skills/.*\.md|agents/.*\.agent\.md)$, with README.md excluded. It enforces ADR-0023 clause 1 and nothing else: an executable, instructed local git command in plugin skill or agent content is written rtk git.

It is wider in file scope than the ADR-0020 hooks — every markdown file under a plugin's .apm/skills/ and .apm/agents/, not SKILL.md alone — because the rule it enforces is about commands an agent runs, and most of those live in references/, which the ADR-0020 gates do not reach (the references/ blind spot).

What it can decide, and what it declines to

ADR-0023 has three clauses and only the first is a pattern:

Clause	Rule	Gated
1	executable + instructed → rtk git	yes
2	illustrative / referential → bare git	no — undecidable
3	machine-parsed or interactive → bare git	no — opt-out marker

Clause 2 is a judgement about what a sentence is doing. "Run git switch <branch>" and "git switch refuses rather than clobbering local edits" are the same token sequence. A gate that guessed would fire on correct prose, and a gate that fires on correct content gets added to SKIP — which disarms clause 1 along with it. So the hook looks only at the two contexts where a git mention is unambiguously an instruction to execute:

• a line inside a fenced code block whose info string names a shell — bash, sh, shell, zsh, console, shell-session. Fences tagged text, yaml, json, or tagged with nothing, are not checked;
• the opening backticked span of a "Run" column cell in a markdown dispatch table, and only the opening span.

That last narrowing is not fussiness. A Run cell routinely carries a command followed by prose about it, and the prose is clause 2. git-worktrees/SKILL.md has both shapes on adjacent rows — one cell reading `rtk git worktree add --track …` — always correct. `git worktree add <path> <branch>` expands to exactly this (instruction, then reference), and a **Never** … row whose Run cell is entirely explanation containing a bare git push. Checking every backticked span flags both; checking only a leading span flags neither, and still catches the ordinary | List | `git worktree list -v` | case the gate exists for.

The clause-3 opt-out

A command that is deliberately bare — because rtk rewrites the output the skill parses, or because the command is interactive — is exempted by putting the literal string ADR-0023 on the same line: in a shell comment for a code line, in the cell text for a table row.

Per line, never per block. A fenced procedure routinely mixes rtk git steps with one deliberately bare command (git-remotes/references/push.md does exactly that), and a block-level marker would silently disarm every checked line around the marked one. The cost is a repeated # bare per ADR-0023 in the three blocks of git-log-format.md where every line is deliberately bare; that repetition is the price of the marked line being the only line the marker speaks for.

The marker is a plain substring match, so a line that mentions ADR-0023 for an unrelated reason is also exempt. Accepted deliberately: the marker records an author's opt-out, it is not a security boundary, and a stricter form would only move the same trust to a different string.

What it deliberately does not cover

• Clause 2. Nothing checks that an illustrative mention stayed bare. A sweep that re-prefixes a referential git passes this gate. The inline reasons ADR-0023 requires on clause-3 sites are the only defence, and they are prose.
• Prose bullets. Most of branch-operations.md, merging.md and rewrite-history.md instruct in list items, not fences. Those are clause-1 sites the gate cannot see, because it cannot distinguish them from clause-2 mentions in the same list.
• README.md, excluded by pattern. The skill-directory READMEs the exclusion was first written for are deleted; what it still covers is the 12 README.md files inside a skill's scripts/, tests/ and assets/ subdirectories — consumer-facing prose no agent loads — and the git clone https://github.com/bats-core/… lines in the six tests/README.md files are setup instructions for a third party who has no rtk. Prefixing those would be actively wrong, not merely noisy — see ADR-0023's consumer section.
• Quoting. The line splitter breaks on ;, |, &&, ||, $( and backticks without tracking quotes, so a git command inside a quoted argument is decided by accident. rtk git submodule foreach 'git pull origin main || :' passes because the segment holding the inner command begins with rtk — the right answer for the wrong reason. Write foreach 'git a; git b' and the second inner command is a false positive needing the marker. ADR-0023 records this shape as one the rule itself does not decide.
• Non-git commands. Only git is checked. rtk fronts gh, docker, kubectl and others; no gate covers those, and the corpus does not currently instruct them.

tests/test-check-rtk-prefix.sh pins all of it, including the false-positive cases. Its first case reconstructs the plugin corpus as it stood on main before the #113 sweep and asserts the gate fails there with at least 20 findings, one of them the gitea-* git remote get-url origin drift the sweep missed — a gate that only passes on the already-fixed tree proves nothing about the drift it was written for.

Vale

Install the vale binary — brew install vale (macOS), snap install vale (Linux), choco install vale (Windows), or see https://vale.sh/docs/vale-cli/installation/. No vale sync is needed: the Kyberforge styles are committed under plugins/kyberforge/.apm/skills/factory-audit/assets/vale/styles/, not downloaded packages (ADR-0014).

One copy, one config

Wiring Vale as a deterministic prefilter for factory-audit's Description dimension (motivation: issue #84) is repo-specific, not part of the generic lint plugin, so it does not live in plugins/lint/ — and per ADR-0014 it no longer lives at the repo root either. It lives once, under plugins/kyberforge/.apm/skills/factory-audit/assets/vale/, carrying both the Kyberforge and KyberforgeCopilot styles and a single .vale.ini with all three glob sections: [**/SKILL.md], [**/agents/*.md], [**/*.agent.md].

ADR-0014 split this into two skill-scoped copies because a plugin's cache-install copies only each skill's own files and skill-audit could not reach across the skill boundary into agent-audit's copy. Merging the two audit skills removed the boundary, so the copy went with it and the single-file .vale.ini ADR-0014 split apart is restored (ADR-0025). KyberforgeCopilot stays scoped to .agent.md files alone, for the Copilot-only "Use proactively has no effect" check.

With one copy there is nothing left to diff, so the check-vale-style-sync pre-push hook, scripts/check-vale-style-sync.sh and tests/test-check-vale-style-sync.sh are deleted — one hook off the push gate. Read what went with it, not just what became vacuous. The script had 17 assertion sites. ADR-0025 maps each one; the short version follows.

Genuinely moot (6):

• the vale-wrap.sh diff and the styles/Kyberforge/ diff, which compared two copies that are now one;
• the four hard-fail guards that located those copies (REPO_ROOT is a directory, the .apm/ paths are not stale, neither copy is missing).

Its StylesPath and BasedOnStyles checks were not diffs. They were per-file greps of each .vale.ini, so they survive: case 0 below checks that the config loads, and case 28 checks that the Kyberforge style is actually loaded.

Rehomed or ported (11). The largest group is the six-row glob-coverage probe table, which invoked vale --config on one representative path per file shape. It was the only assertion anywhere that catches a .vale.ini glob typo ([**/SKILL.md] → [**/SKILLS.md]), the failure mode where every other check stays clean while Vale lints zero files. One config does not make that impossible: a typo in any one of the three sections still 0-file-skips that shape.

Case 0 runs before any Vale-dependent case and needs no Vale binary. It asserts that the shipped .vale.ini exists and is readable, sets a StylesPath that resolves to a directory, and names only styles that ship. A config that cannot load used to surface as nine generic "vale printed no summary line" failures across cases 28–31. It now fails once, names the cause, and holds the Vale-dependent cases back.

The probes now live in tests/test-vale-wrap.sh (cases 28–30), rehomed against the merged config: one representative path per file shape, each asserted to produce a Vale scan of more than zero files and a Kyberforge alert (case 28). Case 28 also checks that each probe path is in scope of a published vale hook, and that every .vale.ini section has a probe row. Its Part B drops Kyberforge from each section's BasedOnStyles in a copy and requires that section's probes to fail as "style not loaded". Case 29 is a mutation case: it typos each section in a copy of the assets and requires that section's isolating probes to drop to zero. Case 30 asserts that KyberforgeCopilot reaches .agent.md files alone. Its Part B requires both an unload (dropped from [**/*.agent.md]) and a leak (added to [**/SKILL.md]) to fail. Case 31 is the third class that went with the script and is not a glob probe at all: the per-rule override allowlist, which pins every Kyberforge rule at a blocking bare YES/error. It is not redundant with the probes above — those key on Kyberforge.VagueWording and KyberforgeCopilot.ProactivePhrase, so the other four rules (DescriptionOpener, PaddingPhrase, SentenceOpenerThereIs, CompositionNote) can each be overridden out of error underneath a passing probe. That gap is closed.

Case 32 covers the prefilter hooks' own scope in .pre-commit-config.yaml, with three properties. Each vale hook's files: regex must still match at least one tracked file; every path it matches must be in that hook's own artifact class; and it must match every tracked file of that class under plugins/*/.apm/. A hook narrowed to zero files never runs, and pre-commit reports no error. A hook narrowed to one plugin still matches files of the right class, which is why the third property exists: narrowing vale-audit-prefilter-skill from ^plugins/[^/]+/... to ^plugins/kyberforge/... once left 6 of 38 skills prefiltered and the whole suite green. Part B narrows both regexes to zero files and Part C narrows both to one plugin, each in a copy of the config, and requires Part A to fail by hook name.

Case 32 used to have a partner, case 33, which compared each hook's files: regex against the published .pre-commit-hooks.yaml. It went with that manifest (ADR-0014's 2026-09-16 amendment), and its one guard that did not need a second manifest, the one-plugin narrowing, is case 32's third property.

Case 34 asks, statically and with no Vale binary, whether the shipped .vale.ini could load a style at all. Four assertions: every [glob] section declares a non-empty BasedOnStyles; every style any section names resolves to a real directory under StylesPath; that StylesPath is not absolute; and at least one [glob] section exists, so the check cannot pass vacuously on a config with nothing in it. A section whose BasedOnStyles is empty is the silent case — Vale lints every file that glob matches with no rule loaded, prints 0 errors and exits 0. The absolute-path clause is the one that is not obvious: an absolute StylesPath passes on the machine that wrote it and hard-fails for every repo that installs factory-audit, which is the only reason those styles ship with the skill at all. Part B is a mutation self-test against the same function Part A calls — it empties each section's BasedOnStyles in a copy of the assets, and absolutizes StylesPath in another pointed at that copy's own real styles/ directory, and requires each to fail by name.

It is not case 0 again. Case 0 reads BasedOnStyles lines file-wide and tolerates an absolute StylesPath; case 34 reads them per [glob] section and rejects one. Case 0 checks the config loads; case 34 checks that loading it arms anything.

What Vale owns, and what stays LLM judgment

Six rule files, six distinct rules:

Rule	Vale scope	Bans	From
Kyberforge.DescriptionOpener	text.frontmatter.description	non-imperative openers ("This skill/agent…")	issue #84
Kyberforge.VagueWording	text.frontmatter.description	vague capability wording ("helps with", "utilize", …)	issue #84
Kyberforge.PaddingPhrase	text	generic "see references/ for details" padding	issue #84
KyberforgeCopilot.ProactivePhrase	text.frontmatter.description	Use proactively (no effect in Copilot)	issue #84
Kyberforge.SentenceOpenerThereIs	sentence	"There is/are" sentence openers	ADR-0013
Kyberforge.CompositionNote	text.frontmatter.description	architecture and composition prose in a description	ADR-0020

Vale covers the pattern-matchable sub-checks named in issue #84 plus, per ADR-0013, one cherry-picked body-wide prose-pattern rule. Everything else stays LLM judgment: defaults-vs-menus, why-rationale, the non-pattern-matchable body-discipline calls, near-miss exclusion strength, and control calibration. New rules land directly in styles/Kyberforge and block immediately — there is no trial tier.

The cherry-pick record, so it is not re-litigated:

• Kyberforge.SentenceOpenerThereIs landed — 22 held-out hits, both in-corpus hits clean rewrites, zero suppressions needed.
• Kyberforge.VagueQualifier was cherry-picked and then deleted. 2 hits across the corpus as it stood on 2026-08-08 (before the .apm/ restructure): one marginal, and one unfixable false positive — caveman/SKILL.md quotes of course as an example of filler, a mention rather than a use — which forced the repo's only Vale suppression comments.
• governance.md and CONTROLS.md were evaluated as rule sources and excluded: nothing prose-pattern-matchable to mine.

Why every rule is level: error

Every alert is a FAIL, with no ignorable tier — same all-or-nothing model as shellcheck, the test suite, and conventional-pre-commit. Graded severities do not work here: Vale's exit code keys on error alerts alone, so a warning or suggestion rule exits 0, and pre-commit swallows a passing hook's output. Such a rule would be invisible and would block nothing.

MinAlertLevel and --minAlertLevel are correspondingly absent from both .vale.ini files and from the hook definitions. Under this model they are no-ops; adding one is not a missing knob.

The verbose: true escape hatch that makes skill-size-check's SUGGESTION tier audible has no analogue here — Vale has no tier to make audible.

Pre-commit

Two prefilter hooks, with .apm/-scoped files: patterns:

Hook	Pattern
vale-audit-prefilter-skill	^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$
vale-audit-prefilter-agent	^plugins/[^/]+/\.apm/agents/[^/]+\.agent\.md$

Only the authoring source triggers them. The skill-author scaffold template and the four vendored research-corpus SKILL.md files match neither pattern (see Skill and agent context gates, which uses the same scope for skill-size-check), so prose findings surface only when you edit a file this repo actually authors. Without the binary the hooks fail with a bare "command not found" and no install pointer.

Two hooks, not one combined hook — for a different reason than ADR-0014 gave. The original reason was mechanical: with a config per skill, a single hook could point at only one copy and would silently 0-file-skip the other file shape (see A 0-file Vale run is NOT RUN). One .vale.ini carrying all three sections removes that constraint. The split stays anyway because the files: regexes still have to differ — each hook hands Vale only the file shape it is scoped to. Both hooks name the same plugin-bundled factory-audit/scripts/vale-wrap.sh through repo: local; there is no second root copy.

The .vale.ini globs do no scoping

The .vale.ini's section globs are path-agnostic — [**/SKILL.md], [**/agents/*.md] and [**/*.agent.md] — and constrain filename shape, not location: Vale's * crosses /. A SKILL.md outside plugins/ (a project-scope .claude/skills/foo/SKILL.md, say) still matches [**/SKILL.md] and gets linted normally.

All scoping therefore comes from the pre-commit hooks' own files: regexes, which pin this repo's layout (see Pre-commit), and from factory-audit passing one explicit file per invocation — in this repo or in any repo that installs it, whatever that repo's layout.

Narrowing a .vale.ini glob to a plugins/-shaped path to "tighten" it breaks the consumer case: factory-audit run against a project-scope .claude/skills/ tree would lint nothing. check-vale-style-sync's probe set was built to catch exactly that; it moved to tests/test-vale-wrap.sh with the hook's deletion, and two of the six probes exist specifically to pin this location independence — see One copy, one config.

The blind spot: references/ is unlinted, for two independent reasons

Every references/*.md file in the corpus is outside the prose gate. Count them with git ls-files | grep -cE '^plugins/[^/]+/\.apm/skills/[^/]+/references/.*\.md$' rather than reading a figure here; it moves with every retrofit. This is the gap that matters most, because the context contract's own remedy for an over-long body is to move prose into references/ — the gate pushes text across its own boundary and then stops watching it. factory-audit is the live example. Its dispatch body keeps only the gotchas common to both flows, and the flow-specific gotchas live under ## Gotchas in references/skill-flow.md and references/agent-flow.md (ADR-0025). Handing both flow files to vale-wrap.sh prints 0 errors … in 0 files and exits 0.

Closing either cause alone changes nothing. There are two, and they are independent:

Cause	Where	Effect on a references/ file
the Kyberforge style is scoped [**/SKILL.md]	factory-audit/assets/vale/.vale.ini	matches no section, so Vale lints 0 files and exits 0
the hook's files: regex is ^plugins/[^/]+/\.apm/skills/[^/]+/SKILL\.md$	vale-audit-prefilter-skill in .pre-commit-config.yaml	the file is never handed to Vale at all

Verified both ways. Handing factory-audit's vale-wrap.sh a reference file directly — bypassing pre-commit entirely, so only the style scope is in play — prints 0 errors … in 0 files and exits 0, where the same wrapper on a SKILL.md reports in 1 file. And the hook's files: regex, applied to git ls-files, selects only the skill-directory SKILL.md files scoped at the top of this page, so pre-commit never hands Vale a reference file to begin with. Widening the glob to [**/*.md] would still lint nothing through the hook; widening the hook's files: alone would hand Vale files its own config declines to match, which is the 0-file NOT RUN shape — a green run that measured nothing. Issue #117 records the style-scope half; the hook half has to land in the same change or the fix is cosmetic.

vale-wrap.sh, never bare vale

factory-audit's Step 1 and both pre-commit hooks call factory-audit/scripts/vale-wrap.sh, not vale. It works around a confirmed Vale 3.15.2 limitation: text.frontmatter.description silently stops matching on most — not all — multi-line descriptions.

Verified by reproduction on a deliberately-bad fixture, not assumed:

Description scalar spanning 2+ lines	Vale's behaviour
> folded block	0 alerts, exit 0 — broken
plain (unquoted) continuation lines	0 alerts, exit 0 — broken
single- or double-quoted, wrapped	0 alerts, exit 0 — broken
| literal block	alerts fire, exit 1 — lints normally

The wrapper flattens the three broken forms to a single-line scalar in a scratch copy — or, for the rare value no inline scalar can spell verbatim, a |- block with one content line — padding with blank lines so every other line number is unchanged. | literal blocks and single-line descriptions pass through untouched. Most descriptions in this repo are > blocks, so before the wrapper a bad description in any of the three broken forms sailed straight through the prefilter.

The --config argv defect

Handed no --config at all, the wrapper falls back to its own sibling assets/vale/.vale.ini, located from ${BASH_SOURCE[0]} rather than from the cwd. That is why both hooks' entry: is the bare script path with no argument after it.

pre-commit prefixes only entry[0] with the hook-repo clone path (cmd = (prefix.path(cmd[0]), *cmd[1:])), so every later argument resolves against the consuming repo's root. A --config in the since-retired .pre-commit-hooks.yaml therefore pointed at a path no consumer has and hard-failed every external run with E100 [--config] Runtime error.

.pre-commit-config.yaml drops the argument too, deliberately matching that entry. The local repo: local hook resolved its --config correctly only because the consuming repo was this repo — and that divergence is why three review rounds exercised a path no external consumer takes and missed the defect. Do not reintroduce a --config to either hook to make the local run "explicit", and keep a restored published manifest to entry[0] alone (ADR-0014).

An explicit --config from any other caller still wins, in all three argv forms (--config X, --config=/abs, --config=rel), and a relative one resolves against the caller's cwd — matching bare vale, not the repo root.

factory-audit's Step 1 passes no --config either. Step 1 resolves the script relative to the skill's own directory so the call works from an installed plugin cache; a relative --config alongside it would resolve against the cwd instead, yielding E100 Runtime error … does not exist and exit 2 — which the skill's fallback misreads as "vale unavailable" and silently downgrades to full LLM judgment. An earlier revision wrote this paragraph in the plural, for the skill-audit / agent-audit pair ADR-0025 merged; there is one Step 1 now.

tests/test-vale-wrap.sh regression-tests this against factory-audit's copy — the only one left. Its fixtures are all SKILL.md-shaped, and that copy's .vale.ini carries the matching glob section along with the two agent ones.

A 0-file Vale run is NOT RUN

Vale reports 0 files only when the path it is handed matches no glob section at all — a differently-named file, or a directory argument holding nothing that matches. That run prints

✔ 0 errors ... in 0 files.

and exits 0, indistinguishable from a clean pass. Both audits therefore treat a 0-file Vale run as NOT RUN and fall back to full LLM judgment rather than reporting the Description dimension clean.

Pre-push

vale is still a pre-push dependency, but no longer through a hook of its own. check-vale-style-sync — the hook that ran the six glob probes, and whose CHECK_VALE_STYLE_SYNC_ALLOW_MISSING_VALE=1 opt-out downgraded them audibly rather than skipping the hook — is deleted with the second Vale copy (ADR-0025). The six glob probes survive it inside test-vale-wrap.sh, so run-tests --strict is now the gate that runs them. That is also what keeps vale a pre-push requirement: test-vale-wrap.sh exits 77 without the binary once its static cases pass, and a skip fails the push.

test-vale-wrap.sh without Vale skips only its Vale-dependent cases, not the whole suite. The cases that are plain greps and awk over the Vale config and .pre-commit-config.yaml still run: case 0, 16, 26, 27, the static half of 28, 31 Parts A and B, 32, 34 and the static half of 35. A static failure exits 1, because a real defect is not a setup error. Only an all-static-pass run exits 77.

Mentioning banned phrasing without tripping the rule

House convention: banned phrasing that must be mentioned rather than used goes in backticks or a fenced code block. Vale skips code spans and fences, so no suppression is needed — which is why this document quotes Use proactively and "There is/are" the way it does.

Inline <!-- vale Rule = NO --> is the fallback only where backticking is impossible. Use the HTML-comment form; the MDX {/* */} form does not work in plain Markdown. The one time a rule forced suppression comments, the rule was deleted instead (see the VagueQualifier entry above).

Tests

bash tests/run-tests.sh              # every test-*.sh plus the bats suite
bash tests/run-tests.sh --bats-only  # just bats

First run auto-initializes the bats submodules; no manual git submodule update needed.

Exit 77 = SKIPPED. A suite that skips because a dependency is missing does not fail an ad-hoc run. The pre-push hook invokes the same script as --strict (RUN_TESTS_STRICT=1 is equivalent), where a skip does fail the push: at pre-push a skip means one of the documented dependencies is absent on this machine, so the gate would otherwise report success having run fewer suites than it appears to. Without --strict the gate once went green having verified 15 of 17 suites on a vale-less PATH, with the skip list swallowed. Without vale, one suite skips — test-vale-wrap.sh — and the strict failure names it and what to install. (It was three until test-check-vale-style-sync.sh was deleted with its hook — see One copy, one config — and test-vale-hooks-consumer.sh with the published hook manifest.)

Output assertions use a here-string, never a pipe. Write grep -q PATTERN <<< "$OUT", not echo "$OUT" | grep -q PATTERN. Under set -o pipefail the pipe form fails depending on timing: grep -q exits on its first match, echo takes SIGPIPE on its next write, and pipefail reports that as the pipeline failing, so output that matched reads as "no match". It showed up as a push gate that failed about once in 670 runs, on a different suite each time.

tests/test-no-pipefail-early-exit-grep.sh is the static guard. What it scans is the tracked *.sh, *.bats and *.bash files, minus itself — git ls-files -- '*.sh' '*.bats' '*.bash' — and, within each one that sets pipefail, it fails on the pipe form. Every tracked shell file in this tree carries one of those three extensions today, so "every tracked shell file" is true in effect, but it is a property of the tree and not of the scan: a shell script tracked under any other name is not reached. It checks its own scanner against fixtures before trusting a clean result.

What the pattern models, after a review widened it on four axes and narrowed it on one:

• The reader is grep, egrep or fgrep — behind a path prefix (/bin/grep), a command prefix, or env-var assignments (LC_ALL=C grep) — taking -q, -m, -l, -L, --quiet, --silent, --max-count or --files-with. (The last two match the regex and were missing from this list.)
• Intermediate stages are seen. echo x | filter | grep -q y is a site; only the two-stage form used to be.
• Both line continuations are joined before matching: a trailing backslash, and a trailing |, which is equally legal in a pipeline. The hit is reported at the line the command starts on.
• pipefail may sit anywhere in a set line, so set -o errexit -o pipefail arms the file. It previously had to follow the first -o, and a file-level miss skips every site in that file rather than one — which is why that test is deliberately loose.
• A bare & ends a segment, so echo ok && other | grep -q x — whose writer is other, not the echo — is not a site. & followed by a digit is kept, so 2>&1 does not end one.

The widening turned up five live vulnerable sites in tests/test-apm-current-hook.sh that the narrower scanner never saw while the suite reported green; all five are converted, and the scanner now reports zero over the tree. Its fixtures went from 4 vulnerable spellings to 12, plus near-miss negatives it must leave alone, and the suite from 5 cases to 7.

Remit: early-exiting GREP readers only. head, sed -n 1p and a bare read exit early too, and an echo or printf feeding any of them is the same race. Those are guarded by convention — absorb the writer's status with || true, or take the verdict from a here-string — and deliberately not by this test: most legitimate uses of them in this tree are already absorbed, and the scanner cannot see absorption from the pipeline text alone, so flagging them would be noise. The three live grep … | head -1 sites in tests/test-vale-wrap.sh — in unguarded_expansions(), in case 20B's --output line line-number read, and in case 28's per-file RESULTS28 lookup — carry that idiom by hand. Pipes from a non-builtin writer (run_wrap … | grep -q) are out of scope for the same reason: in practice they either absorb the writer's exit status with || true or write only once, at exit.

Known limitation: heredoc bodies are scanned as code. A cat <<'EOF' body containing a vulnerable-looking line would be reported as a real site. There are none in the tree today.

tests/run-bats.sh derives the set of .bats files it expects from git ls-files, so a .bats file deleted from the worktree but still tracked in the index fails the run rather than silently shrinking the suite. Remove one with git rm (or stage the deletion) when intentional; an untracked new .bats file is picked up and needs no ceremony.

Both discovery walks (tests/run-bats.sh and tests/run-tests.sh) exclude apm_modules/: apm install materializes a full copy of every plugin there, and running a dependency's copy of a .bats file breaks its relative path to the bats helpers — 167 spurious failures before the exclusion landed.

apm gates

apm-audit-ci

scripts/apm-audit-ci.sh runs apm audit --ci once per manifest — the root one and each of the seven plugin packages — because the root-only invocation audits the marketplace manifest and nothing else, and apm-pack-check-clean does not parse plugin dependencies: blocks either. Verified: a malformed dependency entry passes apm pack --check-versions --check-clean --dry-run and fails apm audit --ci in that package's directory. Costs ~0.5s per package.

What it actually runs is asymmetric, and the two manifest classes are not comparable. Verified by running apm audit --ci (apm 0.28.0) at the repo root and in plugins/lint/, reading the check names straight off its own compliance table:

On the root manifest, 10 checks: lockfile-exists, ref-consistency, deployment-ledger-owners, deployed-files-present, no-orphaned-packages, skill-subset-consistency, config-consistency, content-integrity, includes-consent, drift.

On each plugin manifest, 1 check: lockfile-exists. Conditional, and vacuous while every plugin apm.yml declared dependencies: {apm: [], mcp: []} — it reports No dependencies declared -- lockfile not required. An earlier revision of this section said it would arm the moment one did not. It has armed. plugins/onedev is the first plugin package to declare a real dependency — it pins code.onedev.io/onedev/tod#v4.3.4 so the marketplace can redistribute OneDev's TOD skills — and the check now fires on it for real. Everything else in the list above is root-only, because it is the root install that has a lockfile, a deployment ledger and deployed files to check.

A plugin package that declares dependencies has no green state, so the hook waives exactly one failure. Verified against apm 0.28.0 in plugins/onedev/:

• Without a package apm.lock.yaml, lockfile-exists fails — apm.yml declares dependencies but apm.lock.yaml is absent — reported as 1 of 1 check(s) failed.
• With one, generated by apm lock in the package directory, lockfile-exists passes and thereby arms the other nine checks; drift then fails reporting 8 unintegrated files at .agents/skills/<name>/SKILL.md, i.e. demanding the dependency's skills be deployed inside the package. apm lock also leaves an apm_modules/ tree inside the package.

The cause is that apm treats any directory holding both apm.yml and apm.lock.yaml as an install root, and a plugin package is not one. scripts/apm-audit-ci.sh therefore waives lockfile-exists and nothing else, and only for a non-root manifest: it asserts the string 1 of 1 check(s) failed, so any second failing check changes the count and the run fails normally, and output it does not recognise fails closed. The root manifest is never waived. Recorded as ADR-0026.

Dropping --ci for package directories was considered and rejected. It is the smaller change and it is wrong. Verified on apm 0.28.0 against a scratch package whose dependency entry carried no git/path/registry field: apm audit --ci exits 1 naming the field, while plain apm audit prints No apm.lock.yaml found -- nothing to scan and exits 0. Malformed-dependency detection is the reason this section gives for auditing packages at all, and a package with dependencies is the only kind that can carry a malformed dependency entry — so dropping --ci would discard the check precisely where it earns its keep.

Known weak point: the waiver matches on apm's stdout. An apm upgrade that rewords either line turns the waiver off. That fails the push rather than hiding a defect; re-verify against the new output and update the patterns rather than widening them.

manifest-parse is not a named check in apm 0.28.0's output, and an earlier revision of this section listed it as one. Parsing is still enforced — a dependency entry missing its git/path/registry field fails with Cannot parse apm.yml — but it fails the invocation before the table is built rather than appearing as a row in it.

The hook needs a completed apm install. deployed-files-present checks the install output on disk, so on a fresh clone it fails with 303 deployed file(s) missing and takes the push with it. That is not a defect in the gate; it is the gate correctly reporting that nothing has been installed yet. Run apm install before the first push from a new checkout.

It does not enforce an org policy. apm discovers one from the git remote and only understands github.com and Azure DevOps, so against this repo's self-hosted Gitea remote it prints:

No org policy found at unknown; enforcement skipped

Do not "fix" that with policy.fetch_failure_default: block in apm.yml. apm's own message suggests it; it was tried on a scratch copy and rejected. With no reachable policy source it does not make the check meaningful, it makes it permanently red — apm audit --ci exits 1 with No org policy found at unknown (policy.fetch_failure_default=block) on every push, forever. A gate that can never go green is not a gate. Revisit only if this repo gains a policy source apm can reach.

It does scan for hidden Unicode. An earlier revision of this section said the opposite. The content-integrity check in the root table is that scan — it reports No critical hidden Unicode or hash drift detected — so the root invocation already covers it and nothing needs adding. What remains true is that the standalone mode is different: plain apm audit (--ci refuses to combine with --file/--strip/--dry-run/PACKAGE) run in a plugin directory reports No apm.lock.yaml found -- nothing to scan and exits 0, because only the root has a lockfile. Plugin manifests get lockfile-exists and nothing else; they are not Unicode-scanned. That holds because no package carries an apm.lock.yaml — one would arm the other nine checks, content-integrity among them, which is the state ADR-0026 rules out rather than a second scan worth having.

check-executables-allow-sync

apm gates a package's hooks/ and bin/ on root apm.yml's executables.allow (apm_cli/security/executables.py). is_package_approved is itself an exact dictionary lookup, but it is never called with a single key: install/exec_gate.py builds a candidate list that includes the version-blind name alongside <package>#<version>, and materialize_exec_map stores every approved key under its version-blind name as well. _map_grants matches the same three ways.

Correction (2026-09-19): verified against apm 0.28.0, a kyberforge version bump therefore does not stop the entry matching — approving owner/repo#2.0.0 also covers owner/repo#2.1.0 through the version-blind alias. The earlier claim here ("no wildcard and no version-less form", so the entry silently stops matching and the SessionStart hook stops deploying) described apm's behaviour wrongly, and ADR-0019 carries the same correction.

The gate is still required, for a repo-level reason rather than an apm-level one: scripts/check-executables-allow-sync.sh asserts the key matches plugins/kyberforge/apm.yml's version:, so a bump without a key edit fails this repo's pre-push, and the key stays an accurate record of what was approved.

scripts/check-executables-allow-sync.sh parses version: out of plugins/kyberforge/apm.yml and asserts root apm.yml carries the matching kyberforge#<version> key. A comment in the executables: block stays as the human-facing pointer; the hook is what actually holds. It parses with PyYAML where importable and falls back to a two-shape scan otherwise, so a missing pip package cannot become the thing that blocks every push.

.claude/settings.json

apm owns this file. Nothing repo-authored goes in it.

apm audit --ci replays the install into a scratch tree and diffs the result byte-for-byte, so anything apm would not have written there — an enabledPlugins block, a real hooks entry — is permanent drift that fails apm-audit-ci. A hook you want in this repo is authored in plugins/<name>/.apm/hooks/ and deployed by apm, never hand-written here.

Its committed content is whatever apm last wrote, which today is the merged SessionStart entry for kyberforge's check-apm-current.sh. That is apm's own output and it belongs in the commit (ADR-0019; ADR-0018's statement that the committed content is exactly {"hooks": {}} is superseded on that point only). Machine-specific settings go in the gitignored .claude/settings.local.json, which apm does not deploy and the replay does not compare; shared enforcement belongs in .pre-commit-config.yaml.

Why it is excluded from pretty-format-json

It is in the second and last alternation in that hook's exclude: pattern, and that alternation is the only one there for a reason other than "generated manifest". Mind which number you are quoting: the pattern is ^(\.claude-plugin/marketplace\.json|\.claude/(settings|apm-hooks)\.json)$ — two top-level alternations, expanding to three real tracked files: .claude-plugin/marketplace.json, this one, and its committed .claude/apm-hooks.json sidecar, which is apm output under the same byte-for-byte replay and is excluded for the same reason.

pretty-format-json --autofix sorts object keys unless --no-sort-keys is passed, while apm's hook integrator emits insertion order (matcher before hooks, type before command). Leaving the file in that hook's scope therefore rewrites apm's output into a form apm would never produce on the way into every commit, and apm-audit-ci then reports permanent drift on a file with an empty git diff — exactly what happened when the SessionStart hook first landed in 2e395a4. Re-running apm install fixes the file; leaving it in scope would re-break it on the very commit carrying the fix.

Load-bearing. Do not tidy it out of that list (see LESSONS.md, 2026-08-14).

Pushing without a network

No pre-push hook needs the network once apm install has populated apm_modules/. Every entry in root apm.yml's marketplace.packages[] resolves from a local ./plugins/<name> path, so apm-pack-check-clean never calls git ls-remote.

apm-audit-ci calls apm too, and its org-policy discovery resolves nothing on this remote before any network call. But it is local only against a populated install: drift and config-consistency replay the install to diff scratch against the working tree, and that replay is cache-only — [>] Replaying install (cache-only) — which is exactly why it costs no network here. On a fresh clone there is no cache to replay from, so the replay clones from the holocron remote and those two checks fail offline, with deployed-files-present already failing for the same reason (see apm-audit-ci above). The offline guarantee is a property of a populated apm_modules/, not of the hook set: run apm install once on a new checkout and it holds from then on.

---

See also

• docs/adr/0020-skill-description-and-body-context-contract.md — the context contract, its enforcement table (deterministic vs. auditor judgment), and every rejected alternative
• docs/adr/0019-session-start-hook-keeps-the-apm-install-current.md — the SessionStart hook, the executable-trust gate, and the version-pinned allow key
• docs/adr/0024-apm-is-the-only-supported-install-path.md — apm as the sole install path, and the deletion of the flat content mirror and its check-plugin-content-sync gate. It supersedes docs/adr/0017-plugin-content-mirror-bridges-apm-to-host-discovery.md (superseded — plugin content sync, kept as the historical record)
• docs/adr/0015-apm-replaces-plugin-marketplace-authoring.md, docs/adr/0014-vale-prefilter-ships-from-the-plugin.md — apm-generated manifests, committed Vale styles
• docs/adr/0025-skill-audit-and-agent-audit-merge-into-factory-audit.md — the audit-pair merge that collapsed the two Vale copies to one, removed the check-vale-style-sync hook, and took the shared boundary resolver from three copies to two (one since ef27c97). It amends ADR-0014 and ADR-0020 on those points
• docs/spec/architecture.md — directory structure, install pipeline, what is generated and what is hand-authored
• .pre-commit-config.yaml — the hooks themselves, with inline rationale comments