Defame1297
149d564f6a
Round-3 review of PR #85 found the "enforcing" pre-commit hook enforced nothing. Vale's exit code keys on error-level alerts alone: five of the six rules were level: warning, so they exited 0, and pre-commit hides output from a passing hook — the alerts were invisible and blocked nothing. ADR-0013 rejected a report-only trial tier and then shipped one by accident. Flatten every rule to level: error. Vale's own exit code is then correct, so the hook entry drops to a bare vale-wrap.sh call and the graded error->FAIL / warning->SUGGESTION mapping disappears from both audit skills: every alert is a FAIL, in the gate and the audit alike. No ignorable tier, matching shellcheck, the test suite and conventional-pre-commit. Delete Kyberforge.VagueQualifier. Measured against the 41 skill/agent files as they stood before the rule ever ran: 2 hits. One marginal ("very different" -> "fundamentally different"), one an unfixable false positive — caveman/SKILL.md quotes "of course" as an example of filler, a mention not a use — which forced the only Vale suppression comments in the repo. Those four lines go with it; two of them were dead anyway, suppressing a frontmatter-scoped rule on a body line. Held-out prose (273 files) fired 15 times, 9 inside out-of-scope research examples and the rest one word in two idioms in a single doc. SentenceOpenerThereIs survives: 22 held-out hits, both in-corpus hits clean rewrites, zero suppressions. Widen .vale.ini's globs to [**/SKILL.md], [**/agents/*.md] and [**/*.agent.md]. The plugins/*/-prefixed globs scoped nothing — Vale's * crosses /, so they already matched docs/research/examples/**/agents/*.md and assets/templates/SKILL.md, the two paths CONTEXT.md claimed they excluded. Scoping is and was the hook's files: regex. The old globs also hid a silent false negative: a skill outside plugins/ matched no section, so Vale reported 0 files and exited 0, which both audits read as clean. They now treat a 0-file run as NOT RUN and fall back to full judgment. Also: - vale-wrap.sh resolves relative --config values and file arguments against the caller's cwd, as vale does, instead of the repo root, which hard-errored from a subdirectory and silently skipped flattening for file args that did not resolve from the root. Absolute paths inside the cwd are relativized so reports cite resolvable paths, not scratch ones. - vale-run's exit-code model was documented backwards ("exits non-zero whenever it finds an alert at or above MinAlertLevel") and would have led anyone following it to build a gate that passes everything. Its Markdown suppression syntax was MDX-only and does not suppress in .md; corrected in the skill and its troubleshooting reference, with backtick/fence exemption documented as the first resort. - skill-size-check.sh fails only above 500 lines, agreeing with skill-audit's validate.sh <= 500 pass. - ADR-0013 and CONTEXT.md amended to match, recording why graded severities cannot gate. Verified: 9 test scripts / 15 vale-wrap cases pass; vale-audit-prefilter, skill-size-check and shellcheck pass --all-files; check-manifests and claude plugin validate --strict clean. New tests fail against the old script (3 of them) and pass against the new one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MCQ648fLSFXPHGZdQ8gn58
5.2 KiB
5.2 KiB
name, description, metadata
| name | description | metadata | |||||||
|---|---|---|---|---|---|---|---|---|---|
| vale-run | Use when running Vale (a prose/style linter) against files or directories in an already-configured project — one that already has a .vale.ini — and interpreting or reporting its results: choosing an output format for humans vs. CI, filtering by severity, handling Vale's exit codes in scripts, or resolving common runtime issues like false positives and unexpected CI failures. Use even if the user doesn't say "vale" explicitly, e.g. "lint the docs", "check prose style", "run the style linter", "why is CI failing on the docs check". Do not use when the project has no .vale.ini yet, or needs styles installed/configured — that's the vale-config skill. |
|
Gotchas
- Vale's exit code is driven by
error-level alerts only.warningandsuggestionalerts are reported but still exit0.MinAlertLeveland--minAlertLevelcontrol display, never the exit code — no flag makes warnings fail. A rule that must gate CI or a commit hook has to belevel: error. This is the single most common way a Vale gate silently passes everything. vale ls-configprints the fully-resolved, currently active configuration as JSON — the fastest way to check why a rule "isn't applying" is what's actually active, not what's written in.vale.ini.- Inline suppression syntax is format-specific: Markdown uses HTML comments
<!-- vale off -->/<!-- vale on -->, MDX uses{/* vale off */}/{/* vale on */}, Org mode uses# vale off/# vale on. The MDX form does nothing in a plain.mdfile — the alert still fires. Don't assume one syntax works across formats. - Before calling the
valebinary directly, check whether the target repo documents its own wrapper script for Vale (look in its README, CONTRIBUTING docs, pre-commit config, or ascripts/directory). Some projects wrapvaleto work around real bugs — e.g. a scope that silently stops matching multi-line YAML block-scalar frontmatter fields — and calling barevalein a repo that has such a wrapper silently skips whatever the wrapper works around. If a wrapper is documented, invoke it with the same arguments instead of callingvaledirectly; otherwise fall back to the default below.
Running vale
Default invocation (when the target repo has no documented Vale wrapper — see Gotchas):
vale <path-or-glob>
Key flags:
| Flag | Purpose |
|---|---|
--output=<style> |
Output format/template: CLI (default, human-readable), line (compact, one alert per line, good for grep/piping), JSON (for programmatic parsing), or a custom template. |
--minAlertLevel=<suggestion|warning|error> |
Overrides MinAlertLevel from .vale.ini for this run only, without editing config. Filters what is displayed; does not affect the exit code. |
--no-exit |
Suppresses the nonzero exit that error-level alerts would otherwise cause; a no-op when no rule is error-level. Use in CI stages that should surface lint output without hard-failing the build. |
--ignore-syntax |
Treats input as plain text, skipping format-aware parsing — use when a file's syntax-aware parser produces noisy or wrong results. |
vale sync downloads the packages/styles declared in .vale.ini — that's a one-time-per-change setup step (vale-config's territory), not part of a normal lint run. If a run behaves as though no styles are active, that's a sign vale sync hasn't been run yet, not a vale-run problem.
Prefer --output=JSON whenever the caller (a script, a CI step, another agent) needs to act on individual alerts rather than just get a pass/fail signal — CLI and line are for humans reading the terminal.
Fixing false positives
Scope the fix as narrowly as possible, in this order:
- Mentioning banned phrasing rather than using it: wrap it in backticks or a fenced code block. Vale skips code spans and fences, so no suppression is needed at all. Try this before any suppression markup.
- One-off: inline-suppress the specific text run with the format's
vale off/vale onmarkup. - Recurring known-exception string, one rule: disable that specific rule for that specific match inline (e.g.
<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->...= YES), rather than the whole rule. - Known project term failing spell check: add it to the style's
ignorelist, not an inline suppression.
Never disable a rule project-wide to fix one false positive — editing .vale.ini/BasedOnStyles is vale-config's job, and it silences the rule everywhere, not just the false-positive case.
If output looks wrong because Vale mis-parsed a file's format, rerun with --ignore-syntax before assuming the rule itself is broken.
For CI that fails solely because Vale returned non-zero on error-level alerts — not because the content is wrong for that pipeline stage — add --no-exit rather than disabling the rule. If the failing alerts are warnings or suggestions, Vale is not what failed the build; look elsewhere.
If setting up Vale as a pre-commit hook or need the full inline-suppression/spelling-ignore syntax reference, read references/troubleshooting.md.