diff --git a/plugins/lint/.apm/skills/vale-run/README.md b/plugins/lint/.apm/skills/vale-run/README.md index 8572456..459c68a 100644 --- a/plugins/lint/.apm/skills/vale-run/README.md +++ b/plugins/lint/.apm/skills/vale-run/README.md @@ -19,5 +19,5 @@ Describe what you want to lint and how (human-readable output, CI/JSON output, f | File | Purpose | |------|---------| | `SKILL.md` | Core invocation, key flags, output format guidance, false-positive triage order | -| `references/troubleshooting.md` | Inline suppression syntax, rule-specific disabling, spelling ignore lists, pre-commit integration, CI edge cases | +| `references/troubleshooting.md` | Load when a rule appears not to apply, when writing inline suppression or spelling-ignore syntax, or when wiring Vale into pre-commit: resolved-config diagnostic (`vale ls-config`), format-specific suppression markup, rule-specific disabling, spelling ignore lists, pre-commit integration, CI edge cases | | `references/sources.md` | Research provenance | diff --git a/plugins/lint/.apm/skills/vale-run/SKILL.md b/plugins/lint/.apm/skills/vale-run/SKILL.md index 11f443a..2ceb78d 100644 --- a/plugins/lint/.apm/skills/vale-run/SKILL.md +++ b/plugins/lint/.apm/skills/vale-run/SKILL.md @@ -1,17 +1,12 @@ --- name: vale-run description: > - 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. + Use when running Vale (a prose/style linter) on a project that already has a + .vale.ini and acting on its output — even when the user does not say "Vale", + as in "lint the docs", "check prose style", or "why is CI failing on the docs + check". Not setting up Vale config or styles -> `vale-config`. metadata: - version: "0.1.1" + version: "0.1.2" category: lint source_keys: - context7-websites-vale-sh @@ -19,10 +14,8 @@ metadata: ## Gotchas -- Vale's exit code is driven by `error`-level alerts only. `warning` and `suggestion` alerts are reported but still exit `0`. `MinAlertLevel` and `--minAlertLevel` control display, never the exit code — no flag makes warnings fail. A rule that must gate CI or a commit hook has to be `level: error`. This is the single most common way a Vale gate silently passes everything. -- `vale ls-config` prints 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 `` / ``, MDX uses `{/* vale off */}` / `{/* vale on */}`, Org mode uses `# vale off` / `# vale on`. The MDX form does nothing in a plain `.md` file — the alert still fires. Don't assume one syntax works across formats. -- Before calling the `vale` binary directly, check whether the target repo documents its own wrapper script for Vale (look in its README, CONTRIBUTING docs, pre-commit config, or a `scripts/` directory). Some projects wrap `vale` to work around real bugs — e.g. a scope that silently stops matching multi-line YAML block-scalar frontmatter fields — and calling bare `vale` in 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 calling `vale` directly; otherwise fall back to the default below. +- Vale's exit code keys off `error`-level alerts only — `warning` and `suggestion` alerts print and still exit `0`, and `MinAlertLevel`/`--minAlertLevel` filter what is displayed, never the exit code — no flag makes warnings fail. A rule that must gate CI or a commit hook has to be `level: error`. This is the most common way a Vale gate silently passes everything. +- Check whether the target repo documents its own `vale` wrapper script (README, CONTRIBUTING, pre-commit config, `scripts/`) before calling the binary. Some projects wrap `vale` to work around real bugs — e.g. a scope that silently stops matching multi-line YAML block-scalar frontmatter — so bare `vale` skips whatever the wrapper fixes. Invoke the documented wrapper with the same arguments. ## Running vale @@ -41,17 +34,19 @@ Key flags: | `--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. +`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, check `vale ls-config` to confirm what actually loaded before concluding it is a sync problem — an unrun `vale sync` is the usual cause, and 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 +Before writing any inline suppression markup (steps 2 and 3 below), read `references/troubleshooting.md` for your file's format: the markup is format-specific, and the wrong form suppresses nothing while Vale reports no error — the Markdown HTML-comment form is inert in an MDX file. + Scope the fix as narrowly as possible, in this order: 1. **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. 2. **One-off**: inline-suppress the specific text run with the format's `vale off`/`vale on` markup. -3. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (e.g. `` ... `= YES`), rather than the whole rule. +3. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (in Markdown, e.g. `` ... `= YES`), rather than the whole rule. 4. **Known project term failing spell check**: add it to the style's `ignore` list, 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. @@ -60,4 +55,4 @@ If output looks wrong because Vale mis-parsed a file's format, rerun with `--ign 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`. +If a rule appears not to apply, if you need the spelling-ignore syntax, if a CI failure still needs diagnosing, or if setting Vale up as a pre-commit hook, read `references/troubleshooting.md`. diff --git a/plugins/lint/.apm/skills/vale-run/references/troubleshooting.md b/plugins/lint/.apm/skills/vale-run/references/troubleshooting.md index 093280f..c7b601a 100644 --- a/plugins/lint/.apm/skills/vale-run/references/troubleshooting.md +++ b/plugins/lint/.apm/skills/vale-run/references/troubleshooting.md @@ -5,6 +5,13 @@ source_keys: # Vale troubleshooting reference +## Why a rule isn't applying + +`vale ls-config` prints the fully-resolved, currently active configuration as JSON. Check that +before rereading `.vale.ini` — what is written in the config file is not necessarily what is +active, and the resolved output is the fastest way to see which styles and rules a run actually +loaded. + ## Inline suppression syntax by format Markdown uses HTML comments — the MDX `{/* */}` form does not suppress anything in a plain `.md` file: diff --git a/plugins/lint/skills/vale-run/README.md b/plugins/lint/skills/vale-run/README.md index 8572456..459c68a 100644 --- a/plugins/lint/skills/vale-run/README.md +++ b/plugins/lint/skills/vale-run/README.md @@ -19,5 +19,5 @@ Describe what you want to lint and how (human-readable output, CI/JSON output, f | File | Purpose | |------|---------| | `SKILL.md` | Core invocation, key flags, output format guidance, false-positive triage order | -| `references/troubleshooting.md` | Inline suppression syntax, rule-specific disabling, spelling ignore lists, pre-commit integration, CI edge cases | +| `references/troubleshooting.md` | Load when a rule appears not to apply, when writing inline suppression or spelling-ignore syntax, or when wiring Vale into pre-commit: resolved-config diagnostic (`vale ls-config`), format-specific suppression markup, rule-specific disabling, spelling ignore lists, pre-commit integration, CI edge cases | | `references/sources.md` | Research provenance | diff --git a/plugins/lint/skills/vale-run/SKILL.md b/plugins/lint/skills/vale-run/SKILL.md index 11f443a..2ceb78d 100644 --- a/plugins/lint/skills/vale-run/SKILL.md +++ b/plugins/lint/skills/vale-run/SKILL.md @@ -1,17 +1,12 @@ --- name: vale-run description: > - 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. + Use when running Vale (a prose/style linter) on a project that already has a + .vale.ini and acting on its output — even when the user does not say "Vale", + as in "lint the docs", "check prose style", or "why is CI failing on the docs + check". Not setting up Vale config or styles -> `vale-config`. metadata: - version: "0.1.1" + version: "0.1.2" category: lint source_keys: - context7-websites-vale-sh @@ -19,10 +14,8 @@ metadata: ## Gotchas -- Vale's exit code is driven by `error`-level alerts only. `warning` and `suggestion` alerts are reported but still exit `0`. `MinAlertLevel` and `--minAlertLevel` control display, never the exit code — no flag makes warnings fail. A rule that must gate CI or a commit hook has to be `level: error`. This is the single most common way a Vale gate silently passes everything. -- `vale ls-config` prints 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 `` / ``, MDX uses `{/* vale off */}` / `{/* vale on */}`, Org mode uses `# vale off` / `# vale on`. The MDX form does nothing in a plain `.md` file — the alert still fires. Don't assume one syntax works across formats. -- Before calling the `vale` binary directly, check whether the target repo documents its own wrapper script for Vale (look in its README, CONTRIBUTING docs, pre-commit config, or a `scripts/` directory). Some projects wrap `vale` to work around real bugs — e.g. a scope that silently stops matching multi-line YAML block-scalar frontmatter fields — and calling bare `vale` in 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 calling `vale` directly; otherwise fall back to the default below. +- Vale's exit code keys off `error`-level alerts only — `warning` and `suggestion` alerts print and still exit `0`, and `MinAlertLevel`/`--minAlertLevel` filter what is displayed, never the exit code — no flag makes warnings fail. A rule that must gate CI or a commit hook has to be `level: error`. This is the most common way a Vale gate silently passes everything. +- Check whether the target repo documents its own `vale` wrapper script (README, CONTRIBUTING, pre-commit config, `scripts/`) before calling the binary. Some projects wrap `vale` to work around real bugs — e.g. a scope that silently stops matching multi-line YAML block-scalar frontmatter — so bare `vale` skips whatever the wrapper fixes. Invoke the documented wrapper with the same arguments. ## Running vale @@ -41,17 +34,19 @@ Key flags: | `--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. +`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, check `vale ls-config` to confirm what actually loaded before concluding it is a sync problem — an unrun `vale sync` is the usual cause, and 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 +Before writing any inline suppression markup (steps 2 and 3 below), read `references/troubleshooting.md` for your file's format: the markup is format-specific, and the wrong form suppresses nothing while Vale reports no error — the Markdown HTML-comment form is inert in an MDX file. + Scope the fix as narrowly as possible, in this order: 1. **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. 2. **One-off**: inline-suppress the specific text run with the format's `vale off`/`vale on` markup. -3. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (e.g. `` ... `= YES`), rather than the whole rule. +3. **Recurring known-exception string, one rule**: disable that specific rule for that specific match inline (in Markdown, e.g. `` ... `= YES`), rather than the whole rule. 4. **Known project term failing spell check**: add it to the style's `ignore` list, 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. @@ -60,4 +55,4 @@ If output looks wrong because Vale mis-parsed a file's format, rerun with `--ign 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`. +If a rule appears not to apply, if you need the spelling-ignore syntax, if a CI failure still needs diagnosing, or if setting Vale up as a pre-commit hook, read `references/troubleshooting.md`. diff --git a/plugins/lint/skills/vale-run/references/troubleshooting.md b/plugins/lint/skills/vale-run/references/troubleshooting.md index 093280f..c7b601a 100644 --- a/plugins/lint/skills/vale-run/references/troubleshooting.md +++ b/plugins/lint/skills/vale-run/references/troubleshooting.md @@ -5,6 +5,13 @@ source_keys: # Vale troubleshooting reference +## Why a rule isn't applying + +`vale ls-config` prints the fully-resolved, currently active configuration as JSON. Check that +before rereading `.vale.ini` — what is written in the config file is not necessarily what is +active, and the resolved output is the fastest way to see which styles and rules a run actually +loaded. + ## Inline suppression syntax by format Markdown uses HTML comments — the MDX `{/* */}` form does not suppress anything in a plain `.md` file: