holocron/docs/adr/0013-vale-harness-scope-and-rule-sources.md

Vale audit prefilter expands into a plugin-content harness, scoped to prose-pattern rules only

Issue #84 wired Vale as a deterministic prefilter for skill-audit/agent-audit, scoped to exactly four pattern-matchable checks (imperative description opener, vague capability wording, generic reference-pointer padding, Copilot's dead Use proactively phrasing), documented only in CONTEXT.md's "Vale audit prefilter" section — never its own ADR — and explicitly excluding body discipline, near-miss exclusion strength, and control calibration as non-goals. This ADR records a deferred PR #85 review item to broaden that coverage, retroactively captures #84's own rationale (since it was never recorded as a decision in its own right), and layers the expansion on top without reversing or weakening the original four rules.

File scope stays the same. SKILL.md plus agent files (plugins/*/agents/*.md, plugins/*/agents/*.agent.md) only — matching the existing prefilter's globs. Skill-level README.md files and plugin.json manifests are not added: README.md files are navigational, not spec-governed content, and plugin.json is JSON, not prose Vale can meaningfully lint.

Rule categories are prose-pattern-matchable only. Structural, schema, and security concerns stay out of this Vale-based harness because this repo already has dedicated tools for them: skill-frontmatter (required frontmatter fields), validate-plugins/validate-marketplace (claude plugin validate --strict, schema), and gitleaks/detect-private-key (secrets). Duplicating those concerns as Vale rules would fight tools that already own them better.

Governance docs are excluded as a rule source. docs/research/governance_principles/CONTROLS.md and governance.md were investigated and found to contribute nothing minable: CONTROLS.md is org/CI-infrastructure controls (secret scanning, dependency/license scanning, agent permission scoping, audit logging, human approval gates, periodic reviews) — none of it is a prose pattern expressible as a Vale rule against SKILL.md/agent-file text, and what it does cover is either already handled elsewhere (gitleaks) or genuinely out of scope for a plugin-content prose harness (dependency/license scanning is a code-dependency concern, not skill authoring).

Spec-derived custom rules stay mostly as-is. Re-reading agentskills.io's optimizing-descriptions.md and skill-authoring.md, plus claude-code-plugins/agent-definition.md and github-copilot-plugins/agent-definition.md, found that the existing four Kyberforge rules already cover the pattern-matchable surface those specs describe. The remaining spec guidance — calibrating control vs. giving freedom, avoiding menus of options, coherent skill scope, moderate detail level — is semantic judgment, already skill-audit's job via LLM review, not new lintable rules. One confirmation surfaced: Claude Code's Use proactively phrasing is meaningful for .md agent files (it triggers auto-invocation), unlike Copilot's .agent.md files where it's dead phrasing — so KyberforgeCopilot/ProactivePhrase's existing .agent.md-only scope is correct and must not be extended to .md files.

write-good/alex are trialed, not adopted wholesale. These built-in/third-party Vale packages are tuned for general blog-style prose (passive voice, weasel words, wordy phrases) and are expected to be noisy against this repo's terse, imperative instruction-file corpus. Only individual rules proven low-noise against the existing corpus get cherry-picked into styles/Kyberforge; the packages are never referenced wholesale in BasedOnStyles.

A new non-Vale check closes a real gap. skill-authoring.md states SKILL.md should stay under 500 lines / 5,000 tokens — currently unenforced anywhere in this repo. This is a whole-file length ceiling, not a text pattern, so it isn't a Vale rule — it becomes a new deterministic script and pre-commit hook, sibling to the existing skill-frontmatter hook.

Rules land directly in styles/Kyberforge, enforcing immediately. No trial/report-only tier is introduced (see Considered Options). The implementation pass finalizes the cherry-picked write-good/alex rules and any new spec-derived rule wording, runs the full set against the existing SKILL.md/agent-file corpus, fixes any resulting violations across that corpus, and lands the rule changes and the corpus fixes as one atomic commit — the same enforcement model as the original four rules, never a partial or opt-in state.

Considered options

Phased rollout via a separate trial style + config (rejected). A styles/KyberforgeTrial/ directory plus a parallel .vale.trial.ini (mirroring the root config's globs but with BasedOnStyles = Kyberforge, KyberforgeTrial) would let new rules be swept report-only via lint-runner/vale-run before promotion into the enforcing styles/Kyberforge + root .vale.ini. This was considered because BasedOnStyles = Kyberforge activates every rule file under that directory automatically — there's no partial/opt-in application within a style, so a rule dropped straight into styles/Kyberforge goes live in the blocking pre-commit hook immediately. Rejected in favor of finalizing rules directly and fixing violations via subagent before committing: simpler, no new trial-config machinery to build or maintain — at the cost of no standing report-only tier for future candidate rules.

Consequences

• styles/Kyberforge/ will gain new rule files once the (separate, later) implementation pass finalizes the exact cherry-picked write-good/alex rules and any new wording — none are named by this ADR, since none have been chosen yet.
• A new pre-commit hook (name TBD by the implementer) enforces the 500-line/5,000-token SKILL.md ceiling, sibling to skill-frontmatter.
• styles/KyberforgeTrial/ and .vale.trial.ini are deliberately not created — noted here so a future reader doesn't wonder if a trial tier was forgotten.
• Follow-up work — not part of this ADR — is: syncing and trialing write-good/alex, cherry-picking low-noise rules, writing the size-ceiling script and hook, fixing existing corpus violations, and the atomic commit landing all of it.