refactor(lint): retrofit vale-run to the ADR-0020 context contract

Description 654 -> 294 chars, Gotchas 36% -> 19%. Body 698 -> 642 words:
up from the first pass, because a clean-context audit found four defects
whose fixes are net-additive text.

The suppression-markup warning covered only one of the two paths that
write it -- the list is case-based, so a recurring false positive goes
straight to step 3 and never read step 2's warning. Hoisted above both.

The CI-failure trigger, which the description advertises, had no path to
the file holding its answer: the negative diagnosis 'if the alerts are
warnings, Vale is not what failed the build' survived only in
troubleshooting.md, which no CI-entered invocation loads. An agent would
confidently prescribe --no-exit for a failure Vale never caused.

The description had lost every prose-domain word -- no 'prose', no
'linter' -- while vale-config kept all of them, so 'check prose style'
routed to the wrong skill of the pair.

Accepts two soft SUGGESTIONs rather than dropping restored content;
neither fails the gate.

Refs #99

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 |

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
+  Use when running Vale (a prose/style linter) on a project that already has a
-  already-configured project — one that already has a .vale.ini — and interpreting
+  .vale.ini and acting on its output — even when the user does not say "Vale",
-  or reporting its results: choosing an output format for humans vs. CI, filtering
+  as in "lint the docs", "check prose style", or "why is CI failing on the docs
-  by severity, handling Vale's exit codes in scripts, or resolving common runtime
+  check". Not setting up Vale config or styles -> `vale-config`.
-  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.
 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'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.
-- `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`.
+- 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.
-- 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 `.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.
 
 ## 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. `<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->` ... `= 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. `<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->` ... `= 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`.

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:

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 |

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
+  Use when running Vale (a prose/style linter) on a project that already has a
-  already-configured project — one that already has a .vale.ini — and interpreting
+  .vale.ini and acting on its output — even when the user does not say "Vale",
-  or reporting its results: choosing an output format for humans vs. CI, filtering
+  as in "lint the docs", "check prose style", or "why is CI failing on the docs
-  by severity, handling Vale's exit codes in scripts, or resolving common runtime
+  check". Not setting up Vale config or styles -> `vale-config`.
-  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.
 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'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.
-- `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`.
+- 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.
-- 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 `.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.
 
 ## 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. `<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->` ... `= 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. `<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->` ... `= 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`.

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: