From afca873206f75303c31ce877d5edd4cd0163c2d2 Mon Sep 17 00:00:00 2001
From: Jakob Heuser <jakob@codedrift.com>
Date: Mon, 31 Aug 2026 13:47:05 -0700
Subject: [PATCH 1/3] chore(vale): take Vale 3.19.0, re-measured

Bumps VALE_VERSION to 3.19.0 and re-derives everything that is a claim
about the binary rather than about our code.

Every row of VALE_FORMAT_TIERS was re-probed against the 3.19.0 binary
and none moved; the generated vocabulary regenerates byte-identical
apart from its version string, and the corpus differential (panic shapes
included) still holds. What moved is what a table of existing rows
cannot report by construction:

- `.ex`/`.exs` gained comment and `@doc` extraction, so they leave the
  unnamed plaintext fallback for the comment tier. Measured both ways: a
  bare non-comment line fires on 3.18.0 and is silent on 3.19.0. This is
  a NARROWING, and a silent one, so `agent update` gains a ledger entry
  telling a reader why their Elixir findings disappeared.
- `.mdx` stays `markup` and changed underneath the tier: a JSX element's
  children are read as the Markdown they are, and carry the element name
  as a `text.class.<name>` scope. That family is already an open prefix
  in the schema, so it validates today.

Also fixes a latent bug in two recipes, which wrote "`.mdx` is supported
as of Vale v%(VALE_VERSION)s" with the version interpolated. Native MDX
arrived in 3.18.0, so raising the pin would have silently turned a true
sentence into a false one. Both now name the release that did it.
---
 .changeset/vale-3-19-0.md                     | 19 ++++++++++
 packages/cli/src/agent/create-vale-rule.txt   | 32 ++++++++++++-----
 packages/cli/src/agent/route.txt              | 15 +++++---
 packages/cli/src/agent/update.txt             | 17 +++++++--
 .../src/generated/vale-vocabulary-report.md   | 12 +++----
 packages/cli/src/generated/vale-vocabulary.ts | 14 ++++----
 packages/cli/src/rules/capabilities.ts        | 36 +++++++++++++++----
 packages/cli/src/schemas/vale-rule.ts         |  4 +--
 packages/cli/test/reconcile-marker.test.ts    |  2 +-
 .../cli/test/vale-vendor-contract.test.ts     |  2 ++
 10 files changed, 116 insertions(+), 37 deletions(-)
 create mode 100644 .changeset/vale-3-19-0.md

diff --git a/.changeset/vale-3-19-0.md b/.changeset/vale-3-19-0.md
new file mode 100644
index 00000000..66ea959b
--- /dev/null
+++ b/.changeset/vale-3-19-0.md
@@ -0,0 +1,19 @@
+---
+"@taskless/cli": patch
+---
+
+Vale moves to 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. `taskless agent update` explains the drop and
+where to take a rule that was relying on it.
+
+MDX gained coverage in the other direction — 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 other row of the format-tier table was re-probed against the 3.19.0
+binary and none of them moved.
diff --git a/packages/cli/src/agent/create-vale-rule.txt b/packages/cli/src/agent/create-vale-rule.txt
index 0a6eddbe..cabb02cc 100644
--- a/packages/cli/src/agent/create-vale-rule.txt
+++ b/packages/cli/src/agent/create-vale-rule.txt
@@ -532,18 +532,34 @@ it.
    matcher that takes `check` down the first time the repo grows a
    `.typ` file. Never put one of those extensions in a glob.
 
-   That example changed with Vale v%(VALE_VERSION)s, which is the point:
-   the dangerous extension is whichever one the list above says needs a
-   program, not the one you remember. `.mdx` was the example until this
+   That example changed with Vale v3.18.0, which is the point: the
+   dangerous extension is whichever one the list above says needs a
+   program, not the one you remember. `.mdx` was the example until that
    release parsed it natively, and `.typ` took its place.
 
-   **`.mdx` is supported** as of Vale v%(VALE_VERSION)s, which parses it
-   natively rather than shelling out. `[*.{md,mdx}]` is a legitimate
-   matcher again, the example this recipe used to warn about is no
-   longer the broken one. Check the lists above rather than reaching for
-   that memory: `.typ` moved the opposite way in the same release, so a
+   **`.mdx` is supported** as of Vale v3.18.0, which parses it natively
+   rather than shelling out. `[*.{md,mdx}]` is a legitimate matcher
+   again, the example this recipe used to warn about is no longer the
+   broken one. Check the lists above rather than reaching for that
+   memory: `.typ` moved the opposite way in the same release, so a
    matcher covering Typst is now the one that takes the run down.
 
+   **In `.mdx`, a component's children are prose as of v3.19.0.** Vale
+   reads a JSX element's children as the Markdown they are, so text
+   inside a wrapping component (`<Steps>`, `<Tabs>`, `<Aside>`) is
+   linted at its own source position. Only tags, attributes, `{...}`
+   expressions, self-closing elements, and an element opened and closed
+   on one standalone line are still treated as code.
+
+   Two consequences for a rule you write against MDX. Coverage grew,
+   so a rule can now fire in prose it never reached before, which is a
+   finding count that moves without the rule changing. And the children
+   carry the element's name as a class scope, exactly as MyST and
+   Quarto directives do, so `scope: text.class.Aside` targets one
+   component's content. That is an open family: `verify` accepts any
+   `text.class.<name>` tail, because the set of component names is the
+   author's, not Vale's.
+
 5. **Write the fixtures.** Two directories inside the rule, both flat.
    Vale lints the whole fixture tree, so a document nested a level
    deeper would be linted and never checked against either bucket, which
diff --git a/packages/cli/src/agent/route.txt b/packages/cli/src/agent/route.txt
index d76fdfd0..925ccb86 100644
--- a/packages/cli/src/agent/route.txt
+++ b/packages/cli/src/agent/route.txt
@@ -178,13 +178,18 @@ answered together.
        unreported. A matcher written as `[*.{md,typ}]` is not a wider
        `[*.md]`. It is a broken one.
 
-       **`.mdx` is supported** as of Vale v%(VALE_VERSION)s, which
-       parses it natively. It needs no external program and belongs
-       with the other markup formats above. `.typ` moved the other way
-       in the same release: Typst now parses through `typst2vast`, so a
-       Typst file is excluded rather than read as prose the way it was
+       **`.mdx` is supported** as of Vale v3.18.0, which parses it
+       natively. It needs no external program and belongs with the
+       other markup formats above. `.typ` moved the other way in the
+       same release: Typst now parses through `typst2vast`, so a Typst
+       file is excluded rather than read as prose the way it was
        before. Both are measured, not assumed.
 
+       As of v3.19.0 an MDX component's children are read as Markdown
+       too, so prose wrapped in `<Steps>` or `<Aside>` is linted where
+       it previously was not. That widens what a Vale rule covers in
+       `.mdx`; it does not change which extensions are safe to match.
+
    **A language on neither list does not route to runtime by default.**
    Check `create-legacy-rule` first: the repo may already run a linter
    that speaks it, and that linter's own dialect is a local destination
diff --git a/packages/cli/src/agent/update.txt b/packages/cli/src/agent/update.txt
index da725b80..003b50ee 100644
--- a/packages/cli/src/agent/update.txt
+++ b/packages/cli/src/agent/update.txt
@@ -75,8 +75,21 @@ that you finished.
 
 ### Migrating to 0.11.x
 
-The vendored ast-grep moves from 0.41.0 to 0.45.2, and Vale is at
-3.18.0. Four things follow for existing rules.
+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.
+
+**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`
+attributes and nothing else. On 3.18.0 those files had no parser and
+were linted whole, so a Vale rule matching `[*.ex]` fired on function
+names, atoms, and string literals as well as on comments.
+
+Those findings are gone, and nothing errors or warns. A rule that
+reported on Elixir code bodies now reports less, which is a drop you
+would otherwise notice only as a suspiciously clean run. If the rule was
+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.
 
 **A rewriter now requires `fix`.** `SerializableRewriter.required` goes
 from `["rule","id"]` to `["id","fix","rule"]`, so a `rewriters:` entry
diff --git a/packages/cli/src/generated/vale-vocabulary-report.md b/packages/cli/src/generated/vale-vocabulary-report.md
index b42675ce..c1d5546f 100644
--- a/packages/cli/src/generated/vale-vocabulary-report.md
+++ b/packages/cli/src/generated/vale-vocabulary-report.md
@@ -1,10 +1,10 @@
-# Vale 3.18.0 vocabulary: divergence report
+# Vale 3.19.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.18.0 binary. This file is what the binary said that its own
+3.19.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.18.0 documents this operand and it never fired, on any fixture probed (.md).
+Vale 3.19.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.18.0 documents this operand and it never fired, on any fixture probed (.md).
+Vale 3.19.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.18.0 documents it nowhere.
+This operand fired and Vale 3.19.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.18.0 documents it nowhere.
+This operand fired and Vale 3.19.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.
 
diff --git a/packages/cli/src/generated/vale-vocabulary.ts b/packages/cli/src/generated/vale-vocabulary.ts
index d4f14795..5ba39929 100644
--- a/packages/cli/src/generated/vale-vocabulary.ts
+++ b/packages/cli/src/generated/vale-vocabulary.ts
@@ -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.18.0. Every value here is the recorded answer
+ * Derived against Vale 3.19.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.18.0";
+export const VALE_VOCABULARY_VERSION = "3.19.0";
 
 /**
  * Vale's check types, self-enumerated: an unknown `extends` makes the binary
@@ -193,7 +193,7 @@ export const VALE_SCOPE_OPERANDS = [
 export const VALE_SCOPE_PREFIXES = ["frontmatter.", "text.class."] as const;
 
 /**
- * Where Vale 3.18.0 and its documentation disagree.
+ * Where Vale 3.19.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.18.0 documents this operand and it never fired, on any fixture probed (.md).",
+      "Vale 3.19.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.18.0 documents this operand and it never fired, on any fixture probed (.md).",
+      "Vale 3.19.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.18.0 documents it nowhere.",
+    finding: "This operand fired and Vale 3.19.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.18.0 documents it nowhere.",
+    finding: "This operand fired and Vale 3.19.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.",
   },
diff --git a/packages/cli/src/rules/capabilities.ts b/packages/cli/src/rules/capabilities.ts
index 5fc04bc6..50b02f63 100644
--- a/packages/cli/src/rules/capabilities.ts
+++ b/packages/cli/src/rules/capabilities.ts
@@ -196,12 +196,12 @@ export const AST_GREP_TSX_SPLIT: Readonly<
 /**
  * The Vale release carried by the `@taskless/vale-<platform>` packages pinned
  * in `packages/cli/package.json`. Their npm versions append a build stamp
- * (`3.17.1-20260810052605`); this is the version Vale itself reports.
+ * (`3.18.0-20260824195610`); this is the version Vale itself reports.
  *
  * Pinned against the binary by `test/vale-vendor-contract.test.ts`
  * ("engine capabilities" → "reports the pinned version").
  */
-export const VALE_VERSION = "3.18.0";
+export const VALE_VERSION = "3.19.0";
 
 /**
  * Which tier Vale routes an extension to.
@@ -263,9 +263,31 @@ const CONVERTER_TIER_PREFIX = "converter:";
  * plain text today, but the moment Vale routes it to a converter the same
  * omission is a crash that takes down every Vale rule in the run.
  *
- * The 3.17.1 → 3.18.0 bump is what that warning looks like in practice. Every
- * row below was re-probed against the 3.18.0 binary, and eight moved, in three
- * different directions — which is why "re-measure" is not boilerplate here:
+ * THE TABLE HELD ACROSS 3.18.0 → 3.19.0, AND THAT IS NOT THE SAME AS THE BUMP
+ * BEING FREE. Every row below was re-probed against the 3.19.0 binary and not
+ * one of them moved. What moved was a format Vale *learned*, which is precisely
+ * the case a table of existing rows cannot report: `.ex` and `.exs` gained
+ * comment and doc-attribute extraction, so they left the unnamed plaintext
+ * fallback for the `comment` tier and are new rows below.
+ *
+ * Read that direction carefully, because it is a narrowing rather than a gain.
+ * On 3.18.0 an Elixir file was linted as one block of prose, so a rule matching
+ * `[*.ex]` fired on identifiers and string literals as readily as on comments.
+ * On 3.19.0 the code body is invisible and only comments and `@doc` attributes
+ * are read. Findings disappear, no error is raised, and nothing but a re-probe
+ * would have told us. A format Vale learns is never a no-op: the benign version
+ * of it is this one, and the dangerous version is a converter (see `.typ`).
+ *
+ * `.mdx` stayed `markup` and changed underneath the tier: a JSX element's
+ * children are now read as the Markdown they are, so a Vale rule covers prose
+ * inside `<Steps>` or `<Aside>` that it previously skipped, and those children
+ * carry the element name as a `text.class.<name>` scope. The tier is the wrong
+ * instrument for that kind of change — it says a parser exists, not what the
+ * parser sees — which is the second reason a bump needs more than this table.
+ *
+ * The 3.17.1 → 3.18.0 bump is what the dangerous case looks like in practice.
+ * Every row was re-probed against the 3.18.0 binary then too, and eight moved,
+ * in three different directions — which is why "re-measure" is not boilerplate:
  *
  * - `.mdx` gained a native parser: `converter:mdx2vast` → `markup`. It is
  *   supported now, and `[*.{md,mdx}]` is a legitimate matcher again.
@@ -315,6 +337,8 @@ export const VALE_FORMAT_TIERS: Readonly<Record<string, ValeFormatTier>> = {
   ".css": "comment",
   ".csx": "comment",
   ".cxx": "comment",
+  ".ex": "comment",
+  ".exs": "comment",
   ".go": "comment",
   ".h": "comment",
   ".h++": "comment",
@@ -353,7 +377,7 @@ export const VALE_FORMAT_TIERS: Readonly<Record<string, ValeFormatTier>> = {
   ".mkdn": "plaintext",
   ".tex": "plaintext",
   // plaintext HERE, though Vale's own docs list it as comment-tier. Measured on
-  // the pinned 3.18.0 binary a bare non-comment line lints, which is the
+  // the pinned 3.19.0 binary a bare non-comment line lints, which is the
   // plaintext signature. `.qml` and `.scss` sat here for the same reason until
   // 3.18.0 made the docs true for them; `.pyi` is the row where transcribing
   // the docs would still ship the wrong tier — the case for probing rather than
diff --git a/packages/cli/src/schemas/vale-rule.ts b/packages/cli/src/schemas/vale-rule.ts
index d9c26527..69d0372b 100644
--- a/packages/cli/src/schemas/vale-rule.ts
+++ b/packages/cli/src/schemas/vale-rule.ts
@@ -458,7 +458,7 @@ const CHECK_FIELDS = VALE_CHECK_FIELDS;
  *
  * These are not field-table facts, which is why they sit apart from the union:
  * every key involved is a legal field of its check. It is the *shape* that is
- * fatal. Measured against Vale 3.18.0, each of the shapes below ends the
+ * fatal. Measured against Vale 3.19.0, each of the shapes below ends the
  * process with a Go stack trace. The two `sequence` shapes fail while the rule
  * is compiled:
  *
@@ -511,7 +511,7 @@ function fatalShapeMessages(
 
   if (rule.extends === "metric" && rule.formula !== undefined) {
     // Structural, like the `sequence` arm above, because "was the key
-    // supplied" is the wrong question. Measured against 3.18.0, the panic
+    // supplied" is the wrong question. Measured against 3.19.0, the panic
     // follows the *value*: an absent `condition`, a `condition:` written with
     // no value (YAML parses that to null, which is not `undefined`), and a
     // blank string all reach the same panic. Other types are not this guard's
diff --git a/packages/cli/test/reconcile-marker.test.ts b/packages/cli/test/reconcile-marker.test.ts
index 54256df9..8725c8e4 100644
--- a/packages/cli/test/reconcile-marker.test.ts
+++ b/packages/cli/test/reconcile-marker.test.ts
@@ -86,7 +86,7 @@ describe("recording a rules reconciliation", () => {
     expect(rules?.reconciledTo).toBe(version);
     // Engine versions are the input a later differential needs. Recorded here
     // and nowhere else, so an upgrade cannot silently refresh them.
-    expect(rules?.engines).toEqual({ sg: "0.45.2", vale: "3.18.0" });
+    expect(rules?.engines).toEqual({ sg: "0.45.2", vale: "3.19.0" });
   });
 
   it("reports the marker through info", async () => {
diff --git a/packages/cli/test/vale-vendor-contract.test.ts b/packages/cli/test/vale-vendor-contract.test.ts
index bd6a900c..7a25a4c6 100644
--- a/packages/cli/test/vale-vendor-contract.test.ts
+++ b/packages/cli/test/vale-vendor-contract.test.ts
@@ -407,6 +407,8 @@ withVale("Vale vendor contract", () => {
  */
 function comment(extension: string): string {
   const HASH = new Set([
+    ".ex",
+    ".exs",
     ".jl",
     ".pl",
     ".pm",

From 9d8c229eb53dd461f8a908b311db4b0f897e1d51 Mon Sep 17 00:00:00 2001
From: Jakob Heuser <jakob@codedrift.com>
Date: Mon, 31 Aug 2026 17:14:50 -0700
Subject: [PATCH 2/3] chore(vale): pin the published 3.19.0 platform packages

Bumps the six `@taskless/vale-*` pins from 3.18.0-20260824195610 to
3.19.0-20260901000817, the stamp release-vale.yml minted on the push to
main that merged #223.

This is the commit the rest of the branch was waiting on. Everything
else here was measured against a 3.19.0 binary fetched from upstream and
verified against the manifest digest; the vendor contract could not
agree, because the installed package was still 3.18.0 and the contract
refuses to certify a claim against a binary other than the pinned one.
That refusal is the guard working, and it is why this branch was a
draft.

The whole suite now runs against the published binary rather than a
hand-placed one: the pinned-version assertion and the two new `.ex`/
`.exs` probes pass on the artifact a user will actually install.
---
 packages/cli/package.json | 12 ++++----
 pnpm-lock.yaml            | 60 +++++++++++++++++++--------------------
 2 files changed, 36 insertions(+), 36 deletions(-)

diff --git a/packages/cli/package.json b/packages/cli/package.json
index 09c49f2d..b7b0a20e 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -74,11 +74,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.18.0-20260824195610",
-    "@taskless/vale-darwin-x64": "3.18.0-20260824195610",
-    "@taskless/vale-linux-arm64": "3.18.0-20260824195610",
-    "@taskless/vale-linux-x64": "3.18.0-20260824195610",
-    "@taskless/vale-win32-arm64": "3.18.0-20260824195610",
-    "@taskless/vale-win32-x64": "3.18.0-20260824195610"
+    "@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"
   }
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 90f6c0ff..c309a80c 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -152,23 +152,23 @@ importers:
         specifier: 0.45.2
         version: 0.45.2
       '@taskless/vale-darwin-arm64':
-        specifier: 3.18.0-20260824195610
-        version: 3.18.0-20260824195610
+        specifier: 3.19.0-20260901000817
+        version: 3.19.0-20260901000817
       '@taskless/vale-darwin-x64':
-        specifier: 3.18.0-20260824195610
-        version: 3.18.0-20260824195610
+        specifier: 3.19.0-20260901000817
+        version: 3.19.0-20260901000817
       '@taskless/vale-linux-arm64':
-        specifier: 3.18.0-20260824195610
-        version: 3.18.0-20260824195610
+        specifier: 3.19.0-20260901000817
+        version: 3.19.0-20260901000817
       '@taskless/vale-linux-x64':
-        specifier: 3.18.0-20260824195610
-        version: 3.18.0-20260824195610
+        specifier: 3.19.0-20260901000817
+        version: 3.19.0-20260901000817
       '@taskless/vale-win32-arm64':
-        specifier: 3.18.0-20260824195610
-        version: 3.18.0-20260824195610
+        specifier: 3.19.0-20260901000817
+        version: 3.19.0-20260901000817
       '@taskless/vale-win32-x64':
-        specifier: 3.18.0-20260824195610
-        version: 3.18.0-20260824195610
+        specifier: 3.19.0-20260901000817
+        version: 3.19.0-20260901000817
 
   packages/vale-darwin-arm64: {}
 
@@ -831,33 +831,33 @@ packages:
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
-  '@taskless/vale-darwin-arm64@3.18.0-20260824195610':
-    resolution: {integrity: sha512-5CYshnFck8eFrvlDk33ObSFepFKlRJBeXZBLfDt5yLtjzHaBaOILwXlLMao4d1trbppN+ryb21btInJCteamVQ==}
+  '@taskless/vale-darwin-arm64@3.19.0-20260901000817':
+    resolution: {integrity: sha512-TdLh/XUDJgGc0l+jYFsg82eR9K+01c1tepLlVSirB7QQuqzSb0C6mSotojLNire2mp2YeRMt/CMWBu7wHGdUIg==}
     cpu: [arm64]
     os: [darwin]
 
-  '@taskless/vale-darwin-x64@3.18.0-20260824195610':
-    resolution: {integrity: sha512-WX2KWjE7/srXfIXrb2+p/KvB8wt76iQsB4r34c88GUiYidLmwjlN4sPcfCFyKgzcU9vsVwd9ycHpuACqtR51tw==}
+  '@taskless/vale-darwin-x64@3.19.0-20260901000817':
+    resolution: {integrity: sha512-cBCL0avqtJSqOTseTIqKNofbfj8ULvNLGg3icK/Hej+ExqYfLL/4wehVSHwsOgLburoRG7rCiks3h4QibqyA2Q==}
     cpu: [x64]
     os: [darwin]
 
-  '@taskless/vale-linux-arm64@3.18.0-20260824195610':
-    resolution: {integrity: sha512-tAi4ys1wR+HJ6JQucExrGxg/DzVWc+Lx4+CixPLPgmIP+vw8E9DXdkY7vyIwMAMmxXUS3/cl7TNFv2J/Su3QhA==}
+  '@taskless/vale-linux-arm64@3.19.0-20260901000817':
+    resolution: {integrity: sha512-C2f0Ndraq+mmURISRCyoR7GAzhBGwPOlfaxqzqedPd1zdD72E0sRjSRR7KCeT+P7uKM+kclUuYu9oCXkohE1yA==}
     cpu: [arm64]
     os: [linux]
 
-  '@taskless/vale-linux-x64@3.18.0-20260824195610':
-    resolution: {integrity: sha512-Ae+fGfXGy6QlzuDLyh0FFkjrsbp52oxCQtRzKG6CfUIVc80O4Hh/yZIh+xi4UwTL9zJ69xS4LNDQ1MLoR/DQYQ==}
+  '@taskless/vale-linux-x64@3.19.0-20260901000817':
+    resolution: {integrity: sha512-j6MIcOv9vDbLme0bv7vc/QgB4BoeRJGtK+QESqF8ivdOvC/XliBLvOg4OJzsRrzWR/cNcxvdzMU3UgLhGVR4Vg==}
     cpu: [x64]
     os: [linux]
 
-  '@taskless/vale-win32-arm64@3.18.0-20260824195610':
-    resolution: {integrity: sha512-FSYdG2KRuv2cI2ulJMVlRdtKI1rAd2ScqyERlF6MAnqCu/0TY95I/Po3YBpKA4Ms3l4YBk2dP1viphm68y/L1g==}
+  '@taskless/vale-win32-arm64@3.19.0-20260901000817':
+    resolution: {integrity: sha512-IoTanJ4mPhza1LKTVexkR8gwZkZGTJiFj2uEtW8uH3ZSYp/qTTXtmi3rJh1Am1b+jlnzI2WsTP0qCyCX9suQ9Q==}
     cpu: [arm64]
     os: [win32]
 
-  '@taskless/vale-win32-x64@3.18.0-20260824195610':
-    resolution: {integrity: sha512-xpIADyagcUUSL0+MXuR5557W2DzC7jYrttN6V6NqNjdYQ3/T2vxZ97B4+syMhbSgyfm9ratLLasuGfVNj+KS3w==}
+  '@taskless/vale-win32-x64@3.19.0-20260901000817':
+    resolution: {integrity: sha512-xBBfF+ZyRHZ+XTksSXlVR6BREqgqJU9UlI3H4a22txpNAhAYLseEYNwp1LTBBF4fQy3v3p7GnOkRavG0NoG8zQ==}
     cpu: [x64]
     os: [win32]
 
@@ -3087,22 +3087,22 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
-  '@taskless/vale-darwin-arm64@3.18.0-20260824195610':
+  '@taskless/vale-darwin-arm64@3.19.0-20260901000817':
     optional: true
 
-  '@taskless/vale-darwin-x64@3.18.0-20260824195610':
+  '@taskless/vale-darwin-x64@3.19.0-20260901000817':
     optional: true
 
-  '@taskless/vale-linux-arm64@3.18.0-20260824195610':
+  '@taskless/vale-linux-arm64@3.19.0-20260901000817':
     optional: true
 
-  '@taskless/vale-linux-x64@3.18.0-20260824195610':
+  '@taskless/vale-linux-x64@3.19.0-20260901000817':
     optional: true
 
-  '@taskless/vale-win32-arm64@3.18.0-20260824195610':
+  '@taskless/vale-win32-arm64@3.19.0-20260901000817':
     optional: true
 
-  '@taskless/vale-win32-x64@3.18.0-20260824195610':
+  '@taskless/vale-win32-x64@3.19.0-20260901000817':
     optional: true
 
   '@types/chai@5.2.3':

From c6f5927b09489b11eaa3083f2a99fd833d78c733 Mon Sep 17 00:00:00 2001
From: Jakob Heuser <jakob@codedrift.com>
Date: Mon, 31 Aug 2026 19:38:32 -0700
Subject: [PATCH 3/3] docs(vale): stop hand-carrying a build stamp that goes
 stale

Review feedback on #226.

The `VALE_VERSION` docblock illustrated the npm build stamp with a
literal, and this diff moved it from 3.17.1-... to 3.18.0-... while the
constant below it went to 3.19.0 and the package pins went to
3.19.0-20260901000817. So it shipped one release behind, which is the
second time: the prior state had the same off-by-one.

Twice makes it a class rather than an instance, so the literal is gone
and the docblock names the shape, `<valeVersion>-<yyyymmddhhmmss>`, and
where it is minted. A stamp that has to be hand-carried on every bump is
worse than no example, because it reads as the current pin and is not
one. `packages/cli/package.json` holds the real values, where a reader
sees all six at once and cannot be handed a stale one.
---
 packages/cli/src/rules/capabilities.ts | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/cli/src/rules/capabilities.ts b/packages/cli/src/rules/capabilities.ts
index 50b02f63..13a9e9b1 100644
--- a/packages/cli/src/rules/capabilities.ts
+++ b/packages/cli/src/rules/capabilities.ts
@@ -195,8 +195,16 @@ export const AST_GREP_TSX_SPLIT: Readonly<
 
 /**
  * The Vale release carried by the `@taskless/vale-<platform>` packages pinned
- * in `packages/cli/package.json`. Their npm versions append a build stamp
- * (`3.18.0-20260824195610`); this is the version Vale itself reports.
+ * in `packages/cli/package.json`. Their npm versions append a build stamp,
+ * `<valeVersion>-<yyyymmddhhmmss>`, minted per publish by
+ * `.github/workflows/release-vale.yml`; this is the version Vale itself
+ * reports.
+ *
+ * The SHAPE rather than an example, deliberately. A literal stamp here has to
+ * be hand-carried on every bump, and it has gone one release out of date twice
+ * now, which is worse than no example: it reads as the current pin and is not
+ * one. The real value lives in `packages/cli/package.json`, where a reader can
+ * see all six at once and cannot be told a stale one.
  *
  * Pinned against the binary by `test/vale-vendor-contract.test.ts`
  * ("engine capabilities" → "reports the pinned version").