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/ gained two new rule files, cherry-picked from write-good/alex as low-noise against this repo's corpus: VagueQualifier.yml and SentenceOpenerThereIs.yml.
• A new pre-commit hook, skill-size-check (scripts/skill-size-check.sh), enforces the 500-line/5,000-token SKILL.md ceiling, sibling to skill-frontmatter.
• styles/KyberforgeTrial/ and .vale.trial.ini were deliberately not created — noted here so a future reader doesn't wonder if a trial tier was forgotten.
• The styles-portability question — whether styles/ and .vale.ini should move into plugins/lint/ so the prefilter also works for repos that install kyberforge@holocron as an external plugin, rather than living at this repo's root — was deliberately deferred, not fixed, in this pass. This repo-root placement remains intentional: this ADR's "File scope stays the same" framing is specific to Kyberforge's own authoring conventions in this repo, not a generic lint-plugin feature. Portability is a known limitation, tracked for a separate future session, not silently forgotten.

What this ADR's implementation pass did: synced and trialed write-good/alex against the existing SKILL.md/agent-file corpus, cherry-picked the two low-noise rules above into styles/Kyberforge, wrote scripts/skill-size-check.sh and its pre-commit hook, fixed the resulting corpus violations, and landed the rule changes and corpus fixes as one atomic commit — matching the enforcement model described above (no partial or opt-in state).