feat(vale): take Vale 3.20.0, and spend the zones it makes affordable

#293 published the 3.20.0 platform packages; this pins them
(3.20.0-20260907164938) and takes what the binary actually changed.

THE RELEASE THAT MATTERS TO US IS NOT THE ONE ON THE TIN. 3.20.0's headline
is style-library authoring — rule inheritance, nested directories, scalar
tuning from config — and none of it is reachable here: our schema rejects any
`extends` that is not a check type, and a rule lives alone in its own
directory. What we get is one bugfix, `honor comment directives at any
indent`, which retires a workaround we shipped guidance for eight commits ago.

Measured, 3.19.0 vs 3.20.0, on the same fixture:

  inline pair at a continuation indent   3.19.0 reports 2, 3.20.0 reports 1
  the same pair over a `scope: raw` rule 3.19.0 reports 2, 3.20.0 reports 1

The first is the case 6c99c41 measured and answered by deleting both
directives: an inline pair failed CommonMark's HTML-block test, landed inside
the paragraph, and the NO/YES cancelled out before the block was linted. It
did nothing, silently. The second never worked at all, because `raw` rules run
after ResetComments. Both are now givens in `vale-vendor-contract.test.ts`,
which had no directive coverage before.

SO THE EXAMPLES COME BACK. Both worked examples that were reworded to dodge
`no-hedging` are restored to their natural wording, each inside a two-line
zone at the continuation indent. The zone is load-bearing rather than
decorative: the repo's own rule over the recipe reports 2 findings with the
directive lines stripped and 0 with them in place. What used to cost 176 lines
of prose to save two words now costs two lines.

THE LEDGER IS ONE CROSSING, NOT TWO. v0.11.0 vendors 3.18.0, so 3.19.0 never
reached a consumer and its Elixir and MDX changes arrive with these. The
changeset grows in place rather than gaining a sibling, `update.md` reads
3.18.0 → 3.20.0 with nine items instead of five, and MDX joins the ledger,
which it never did. Still `patch`: pre-1.0, and no released surface changes.

The format-tier table held — 95 probes, no row moved. That table cannot report
a format Vale LEARNS, so that was checked at the source instead: the
v3.19.0...v3.20.0 tree adds no format handler and no comment-extraction
language, and every existing one changes by a single import line from the org
rename. The docblock now says to repeat that check, since a green table is
silence about the dangerous direction rather than evidence against it.

Two findings from doing the work, both now documented:

- At `raw` scope the directive line is itself linted text, so a rule whose
  token appears in its own id reports a finding on the marker that silences
  it. `no-simply` looking for `simply` flags its own `= NO` line.
- `sequence` accepts `exceptions` as of 3.20.0, which the derived vocabulary
  picked up on its own.

Upstream also changed how a negated sequence token is satisfied at a sentence
boundary. No shape I tried separated the two binaries, so it is recorded the
way the ast-grep root-metavariable case already is: nothing to do unless you
see one.

  pnpm cli check   No issues found.

1325 tests pass, typecheck and lint clean.

Author: theCodeDrift

.changeset/vale-3-19-0.md

@@ -0,0 +1,37 @@
+---
+"@taskless/cli": patch
+---
+
+Vale moves to 3.20.0. The last release vendored 3.18.0, so 3.19.0 is part of
+this crossing too and no consumer sees it on its own.
+
+An exception zone that did nothing now takes effect. Vale records the region
+each `<!-- vale <id>.<id> = NO -->` and `= YES` pair covers and suppresses the
+alerts inside it, where an inline pair at a continuation indent used to be read
+once per block and cancel itself out silently. A marker already sitting in a
+project's documents was inert and is now live, so findings can disappear with
+nothing reporting the drop. `taskless agent update` says how to tell that from
+a rule that broke.
+
+Directives also reach `scope: raw` rules now, which they never did before. A
+rule about a shell command, a flag, or a package name was exempt-or-remove with
+nothing in between, and can be exempted case by case again. At `raw` scope the
+directive line is itself linted text, so a rule whose token appears in its own
+id reports a finding on the marker that silences it.
+
+`sequence` accepts `exceptions`, which the derived vocabulary picked up and the
+schema now allows.
+
+Carried over from 3.19.0: Elixir (`.ex`, `.exs`) gained comment and `@doc`
+extraction, so it leaves the plaintext fallback for the comment tier. This
+narrows what a Vale rule matching Elixir reports — the code body is no longer
+prose, and findings that came from it disappear silently. MDX gained coverage in
+the other direction, since a JSX element's children are read as the Markdown
+they are, so prose inside a wrapping component such as `<Steps>` or `<Aside>` is
+linted where it previously was skipped, and carries the component name as a
+`text.class.<name>` scope a rule can target.
+
+Every row of the format-tier table was re-probed against the 3.20.0 binary and
+none of them moved. The direction that table cannot report was checked at the
+source instead: the v3.19.0...v3.20.0 tree adds no format handler, so no format
+was learned.

.changeset/vale-3-20-0.md

@@ -89,11 +89,11 @@
     "@ast-grep/cli-win32-arm64-msvc": "0.45.2",
     "@ast-grep/cli-win32-ia32-msvc": "0.45.2",
     "@ast-grep/cli-win32-x64-msvc": "0.45.2",
-    "@taskless/vale-darwin-arm64": "3.19.0-20260901000817",
-    "@taskless/vale-darwin-x64": "3.19.0-20260901000817",
-    "@taskless/vale-linux-arm64": "3.19.0-20260901000817",
-    "@taskless/vale-linux-x64": "3.19.0-20260901000817",
-    "@taskless/vale-win32-arm64": "3.19.0-20260901000817",
-    "@taskless/vale-win32-x64": "3.19.0-20260901000817"
+    "@taskless/vale-darwin-arm64": "3.20.0-20260907164938",
+    "@taskless/vale-darwin-x64": "3.20.0-20260907164938",
+    "@taskless/vale-linux-arm64": "3.20.0-20260907164938",
+    "@taskless/vale-linux-x64": "3.20.0-20260907164938",
+    "@taskless/vale-win32-arm64": "3.20.0-20260907164938",
+    "@taskless/vale-win32-x64": "3.20.0-20260907164938"
   }
 }

packages/cli/package.json

@@ -1,4 +1,4 @@
-# Topic: create-vale-rule     (CLI v%(CLI_VERSION)s / topic v5)
+# Topic: create-vale-rule     (CLI v%(CLI_VERSION)s / topic v6)
 
 ## You are here
 This is `create-vale-rule`. It helps you write a Vale rule: a check over
@@ -220,44 +220,49 @@ it.
    the cause is in that rule's own `scope` and glob, never in a
    neighbour's.
 
-   **A `raw`-scoped rule cannot be turned off in a document.** Vale's
-   `<!-- vale <id>.<id> = NO -->` directive is applied to the *parsed*
-   document, and `raw` reads the unparsed one. Measured: a `text`-scoped
-   rule is silenced by the directive; the same rule at `raw` fires
-   through it. So a rule about a shell command, a flag, or a package name
-   needs `raw`, commands live in fenced blocks, which nothing else
-   reaches, and takes that trade: it can no longer be exempted case by
-   case, only removed.
-
-   **An exception zone is the size of a top-level block, and no smaller.**
-   A pair of directives turns a rule off for a region and back on:
-   `= NO` opens it and `= YES` closes it. Both lines have to start at
-   column 0, because Vale reads them as HTML blocks and an HTML block
-   begins at the left margin.
-
-   That constraint decides where a zone can go, and it is easy to get
-   wrong twice. Measured on Vale 3.19.0, in this file:
-
-   - At a list item's continuation indent the directive is not
-     recognised at all. The words stay reported and nothing says the
-     marker was ignored.
-   - At column 0 in the middle of a list, the directive is recognised
-     and it ends the list. The blocks after it reparse as indented code,
-     which are already outside a prose rule's reach, so coverage moves
-     rather than being restored where you meant to restore it.
-
-   So a zone wraps a whole numbered step, a whole section, or a whole
-   paragraph at the margin. Price it before reaching for one: exempting
-   the two steps of this recipe that quote hedging words would have put
-   176 lines of prose out of reach to keep two words of an example. Those
-   two examples were rewritten to use words the rule does not carry,
-   which cost three words and no coverage at all.
-
-   **Write a documented example indented, never at the margin.** A
-   directive at column 0 in a recipe takes effect on the recipe, and the
-   CLI strips it before serving so a reader never sees it. That is why
-   every directive quoted in this file sits inside a sentence or an
-   indented block: it is being shown, not run.
+   **A directive turns any rule off, `raw` included, as of Vale 3.20.0.**
+   `<!-- vale <id>.<id> = NO -->` opens a zone and `= YES` closes it.
+   Vale records the region each directive covers and suppresses any
+   alert located inside it, which reaches a `raw`-scoped rule too.
+   Through 3.19.0 a directive was applied to the *parsed* document and
+   `raw` reads the unparsed one, so a `raw` rule fired straight through
+   every zone: a rule about a shell command, a flag, or a package name
+   was exempt-or-remove with nothing in between. It is not any more.
+
+   One thing to know before writing one over a `raw` rule: at `raw`
+   scope the directive line is itself linted text. A rule whose token
+   appears in its own id matches the marker that silences it, and
+   reports a finding on the directive. Name the rule so its own id does
+   not contain the word it looks for.
+
+   **A zone is two lines, and no blank line may separate it from the
+   prose it wraps.** Measured on Vale 3.20.0:
+
+   - Inline at a list item's continuation indent works, and this is the
+     form to reach for. The pair covers the lines between it and
+     nothing else.
+   - At column 0 it works too, and it ends any list it interrupts.
+     Blocks that then reparse as indented code are already outside a
+     prose rule's reach, so a zone placed there can move coverage
+     rather than restore it.
+   - A pair separated from its prose by blank lines, at an indent past
+     the code-block threshold, suppresses nothing: what it wraps is not
+     prose any more. Nothing reports that, either.
+
+   Through 3.19.0 the first of those did nothing at all. An inline pair
+   was read once per block, so the `NO` and the `YES` cancelled out
+   before the paragraph was linted and the words stayed reported with
+   no error and no warning. A zone had to wrap a whole step or a whole
+   section at the margin, and exempting the two steps of this recipe
+   that quote hedging words would have put 176 lines of prose out of
+   reach to keep two words of an example. That price is gone.
+
+   **A shown directive has to be inline or fenced, never a bare line.**
+   A directive on a line of its own now takes effect on the recipe at
+   any indent, and the CLI strips it before serving so a reader never
+   sees it. Measured: a directive inside backticks and a directive
+   inside a fenced block are both inert, which is why every directive
+   quoted in this file is one or the other.
 
    **Then the fields the extension point adds**. This is where the rule
    actually lives, and each check reads only its own:
@@ -274,7 +279,7 @@ it.
 | `metric`         | `formula`, `condition`                                                       |
 | `readability`    | `metrics` (a list of formula names), `grade`                                 |
 | `spelling`       | `aff`, `dic`, `custom`, `filters`, `ignore`, `threshold`                     |
-| `sequence`       | `tokens` (each a `pattern`/`tag` map); `ignorecase`                          |
+| `sequence`       | `tokens` (each a `pattern`/`tag` map); `ignorecase`, `exceptions`             |
 | `script`         | `script` (Tengo source)                                                      |
 
    The list above is measured, not transcribed: every entry was added to
@@ -437,8 +442,10 @@ it.
      needs `nonword: true`.
 
    - **A bare word finds senses you did not mean.** `landed on` in a rule
-     about jargon also matches "the plane landed on time"; `clearly` in a
-     rule about hedging also matches "clearly labelled" in a spec.
+     <!-- vale no-hedging.no-hedging = NO -->
+     about jargon also matches "the plane landed on time"; `simply` in a
+     rule about hedging also matches "simply connected" in a maths doc.
+     <!-- vale no-hedging.no-hedging = YES -->
      Narrow the token to the **collocation** you actually object to
      (`landed on a decision`, not `landed on`), and check that you got it
      right by writing the `pass/` fixture from the literal sense *first*:
@@ -535,8 +542,10 @@ it.
      assumes; `scope: heading` has nothing to find outside it:
      %(VALE_MARKUP_FORMATS)s
    - **comment text only**: the comments are linted and the code body
+     <!-- vale no-hedging.no-hedging = NO -->
      is invisible, which is exactly right for "comments must not say
-     'TBD'":
+     'obviously'":
+     <!-- vale no-hedging.no-hedging = YES -->
      %(VALE_COMMENT_FORMATS)s
    - **plaintext fallback**: everything else, `.yml` `.toml` `.sh`
      `.sql` and every extension not named above included. There is no

packages/cli/src/agent/create-vale-rule.md

@@ -1,4 +1,4 @@
-# Topic: update     (CLI v%(CLI_VERSION)s / topic v4)
+# Topic: update     (CLI v%(CLI_VERSION)s / topic v5)
 
 ## You are here
 This is `update`. It tells you what an upgrade changed for the rules
@@ -76,7 +76,7 @@ that you finished.
 ### Migrating to 0.11.x
 
 The vendored ast-grep moves from 0.41.0 to 0.45.2, and Vale from 3.18.0
-to 3.19.0. Five things follow for existing rules.
+to 3.20.0. Nine things follow for existing rules.
 
 **Elixir stopped being linted as prose.** Vale 3.19.0 reads `.ex` and
 `.exs` through a real parser, so it now sees comments and `@doc`
@@ -91,6 +91,52 @@ meant for prose, this is the behaviour you always wanted. If it was
 being used to catch something in the code itself, that is a job for an
 `sg` rule, and `%(TASKLESS_CLI)s rule create` will route it there.
 
+**MDX components' children are prose now, and new findings appear.**
+As of Vale 3.19.0 a JSX element's children are read as the Markdown
+they are, so a rule over `.mdx` covers prose inside a wrapping
+component such as `<Steps>` or `<Aside>` that it previously skipped.
+Those children also carry the component name as a `text.class.<name>`
+scope, which a rule can target.
+
+This is the opposite direction from Elixir: coverage grew, so a rule
+reports MORE than it did. Read the new findings as real, and narrow the
+rule's `scope` only if the component's prose was deliberately out of
+reach.
+
+**An exception zone that did nothing now takes effect, and findings
+disappear.** Vale 3.20.0 records the region each `<!-- vale <id>.<id> =
+NO -->` and `= YES` pair covers, and suppresses any alert located
+inside it. Through 3.19.0 an *inline* pair (at a list item's
+continuation indent, with no blank line between it and the prose it
+wraps) was read once per block, so the two halves cancelled out and the
+zone did nothing at all.
+
+So a marker already sitting in this project's documents was inert and
+is now live. Nothing errors: findings a document has reported for as
+long as the rule existed stop appearing, which reads as a rule that
+broke. Before treating a drop as a regression, look for the
+markers: `git grep -n '<!-- vale'`. Keep the zone if it was meant; if
+it was a half-finished experiment, delete the pair and the coverage
+comes back.
+
+**A `raw`-scoped rule can be exempted in a document now.** Directives
+reach `raw` rules as of 3.20.0. Before, they were applied to the parsed
+document only and a `raw` rule fired straight through every zone, so a
+rule about a shell command, a flag, or a package name could only be
+removed, never exempted case by case. A rule that was narrowed or
+abandoned for that reason is worth revisiting.
+
+One caveat comes with it: at `raw` scope the directive line is itself
+linted text, so a rule whose token appears in its own id reports a
+finding on the marker that silences it. Rename the rule, or scope it.
+
+**`sequence` accepts `exceptions`.** The field is new in 3.20.0 and
+purely additive: no existing rule changes behaviour, and a sequence
+rule that was over-firing on a known phrase can now carry it. Upstream
+also changed how a negated sequence token is satisfied at a sentence
+boundary. No shape we tried reproduced a difference between 3.19.0 and
+3.20.0, so there is nothing to do unless you see one.
+
 **A rewriter now requires `fix`.** `SerializableRewriter.required` goes
 from `["rule","id"]` to `["id","fix","rule"]`, so a `rewriters:` entry
 without a `fix:` is now rejected where it was accepted before.

packages/cli/src/agent/update.md

@@ -1,10 +1,10 @@
-# Vale 3.19.0 vocabulary: divergence report
+# Vale 3.20.0 vocabulary: divergence report
 
 GENERATED FILE — DO NOT EDIT. Produced by `pnpm generate:vale-schema`
 alongside `vale-vocabulary.ts`.
 
 Every value in the vocabulary is the recorded answer of the vendored Vale
-3.19.0 binary. This file is what the binary said that its own
+3.20.0 binary. This file is what the binary said that its own
 documentation does not, in both directions. A generator that dropped these
 would be quietly deciding which of the two to believe.
 
@@ -28,25 +28,25 @@ the worse failure.
 
 ### `scope: meta`
 
-Vale 3.19.0 documents this operand and it never fired, on any fixture probed (.md).
+Vale 3.20.0 documents this operand and it never fired, on any fixture probed (.md).
 
 **Consequence.** It is omitted from the vocabulary, so `verify` rejects it. A rule written from the documentation would otherwise load, run, and match nothing, with no error reported anywhere.
 
 ### `scope: meta.class.title`
 
-Vale 3.19.0 documents this operand and it never fired, on any fixture probed (.md).
+Vale 3.20.0 documents this operand and it never fired, on any fixture probed (.md).
 
 **Consequence.** It is omitted from the vocabulary, so `verify` rejects it. A rule written from the documentation would otherwise load, run, and match nothing, with no error reported anywhere.
 
 ### `scope: frontmatter`
 
-This operand fired and Vale 3.19.0 documents it nowhere.
+This operand fired and Vale 3.20.0 documents it nowhere.
 
 **Consequence.** It is included in the vocabulary. It is also the standing counterexample to trusting the candidate list: a real operand nobody proposes is simply absent, and the schema then rejects a rule the binary honors.
 
 ### `scope: frontmatter.title`
 
-This operand fired and Vale 3.19.0 documents it nowhere.
+This operand fired and Vale 3.20.0 documents it nowhere.
 
 **Consequence.** It is included in the vocabulary. It is also the standing counterexample to trusting the candidate list: a real operand nobody proposes is simply absent, and the schema then rejects a rule the binary honors.
 

packages/cli/src/generated/vale-vocabulary-report.md

@@ -6,7 +6,7 @@
  * `scripts/generate-vale-schema.ts`, and its header explains what each value
  * below was measured with and what it is worth.
  *
- * Derived against Vale 3.19.0. Every value here is the recorded answer
+ * Derived against Vale 3.20.0. Every value here is the recorded answer
  * of that binary to a rule the generator wrote and ran; nothing is transcribed
  * from documentation. Where the binary and the documentation disagree, the
  * disagreement is in `vale-vocabulary-report.md` rather than dropped.
@@ -15,7 +15,7 @@
  */
 
 /** The binary this vocabulary was derived from. */
-export const VALE_VOCABULARY_VERSION = "3.19.0";
+export const VALE_VOCABULARY_VERSION = "3.20.0";
 
 /**
  * Vale's check types, self-enumerated: an unknown `extends` makes the binary
@@ -133,7 +133,7 @@ export const VALE_CHECK_FIELDS = {
   readability: ["grade", "metrics"],
   repetition: ["alpha", "exceptions", "ignorecase", "max", "tokens", "vocab"],
   script: ["script"],
-  sequence: ["ignorecase", "tokens"],
+  sequence: ["exceptions", "ignorecase", "tokens"],
   substitution: [
     "capitalize",
     "exceptions",
@@ -193,7 +193,7 @@ export const VALE_SCOPE_OPERANDS = [
 export const VALE_SCOPE_PREFIXES = ["frontmatter.", "text.class."] as const;
 
 /**
- * Where Vale 3.19.0 and its documentation disagree.
+ * Where Vale 3.20.0 and its documentation disagree.
  *
  * Carried in the artifact rather than only in the report, so that a consumer
  * can render them and a reviewer cannot miss them in a diff.
@@ -202,26 +202,26 @@ export const VALE_DIVERGENCES = [
   {
     subject: "scope: meta",
     finding:
-      "Vale 3.19.0 documents this operand and it never fired, on any fixture probed (.md).",
+      "Vale 3.20.0 documents this operand and it never fired, on any fixture probed (.md).",
     consequence:
       "It is omitted from the vocabulary, so `verify` rejects it. A rule written from the documentation would otherwise load, run, and match nothing, with no error reported anywhere.",
   },
   {
     subject: "scope: meta.class.title",
     finding:
-      "Vale 3.19.0 documents this operand and it never fired, on any fixture probed (.md).",
+      "Vale 3.20.0 documents this operand and it never fired, on any fixture probed (.md).",
     consequence:
       "It is omitted from the vocabulary, so `verify` rejects it. A rule written from the documentation would otherwise load, run, and match nothing, with no error reported anywhere.",
   },
   {
     subject: "scope: frontmatter",
-    finding: "This operand fired and Vale 3.19.0 documents it nowhere.",
+    finding: "This operand fired and Vale 3.20.0 documents it nowhere.",
     consequence:
       "It is included in the vocabulary. It is also the standing counterexample to trusting the candidate list: a real operand nobody proposes is simply absent, and the schema then rejects a rule the binary honors.",
   },
   {
     subject: "scope: frontmatter.title",
-    finding: "This operand fired and Vale 3.19.0 documents it nowhere.",
+    finding: "This operand fired and Vale 3.20.0 documents it nowhere.",
     consequence:
       "It is included in the vocabulary. It is also the standing counterexample to trusting the candidate list: a real operand nobody proposes is simply absent, and the schema then rejects a rule the binary honors.",
   },