From 5925f6bb29ee0e16a794066f74ced3c258d5dfd0 Mon Sep 17 00:00:00 2001
From: Jakob Heuser <jakob@codedrift.com>
Date: Mon, 21 Sep 2026 16:05:39 -0700
Subject: [PATCH 1/5] chore(vale): move VALE_VERSION to 3.22.0 and regenerate
 the vocabulary

The pin bump in #368 left VALE_VERSION at 3.21.0, which is what
engine-version-consistency fails on. The vocabulary re-derived against
the 3.22.0 binary changes only in its version stamp: no operand, prefix
or divergence moved. The v3.21.0...v3.22.0 tree adds no
internal/lint/<format>.go, so no tier row moves either; the docblock on
the tier table records the check and points at what did change.
---
 .../cli/src/generated/vale-vocabulary-report.md   | 12 ++++++------
 packages/cli/src/generated/vale-vocabulary.ts     | 14 +++++++-------
 packages/cli/src/rules/capabilities.ts            | 15 ++++++++++++++-
 packages/cli/test/reconcile-marker.test.ts        |  2 +-
 4 files changed, 28 insertions(+), 15 deletions(-)

diff --git a/packages/cli/src/generated/vale-vocabulary-report.md b/packages/cli/src/generated/vale-vocabulary-report.md
index dc9bb6ff..f4ba997f 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.21.0 vocabulary: divergence report
+# Vale 3.22.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.21.0 binary. This file is what the binary said that its own
+3.22.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.21.0 documents this operand and it never fired, on any fixture probed (.md).
+Vale 3.22.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.21.0 documents this operand and it never fired, on any fixture probed (.md).
+Vale 3.22.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.21.0 documents it nowhere.
+This operand fired and Vale 3.22.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.21.0 documents it nowhere.
+This operand fired and Vale 3.22.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 d15dd834..e13aa712 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.21.0. Every value here is the recorded answer
+ * Derived against Vale 3.22.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.21.0";
+export const VALE_VOCABULARY_VERSION = "3.22.0";
 
 /**
  * Vale's check types, self-enumerated: an unknown `extends` makes the binary
@@ -197,7 +197,7 @@ export const VALE_SCOPE_PREFIXES = [
 ] as const;
 
 /**
- * Where Vale 3.21.0 and its documentation disagree.
+ * Where Vale 3.22.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.
@@ -206,26 +206,26 @@ export const VALE_DIVERGENCES = [
   {
     subject: "scope: meta",
     finding:
-      "Vale 3.21.0 documents this operand and it never fired, on any fixture probed (.md).",
+      "Vale 3.22.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.21.0 documents this operand and it never fired, on any fixture probed (.md).",
+      "Vale 3.22.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.21.0 documents it nowhere.",
+    finding: "This operand fired and Vale 3.22.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.21.0 documents it nowhere.",
+    finding: "This operand fired and Vale 3.22.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 036e030a..40b08b3e 100644
--- a/packages/cli/src/rules/capabilities.ts
+++ b/packages/cli/src/rules/capabilities.ts
@@ -209,7 +209,7 @@ export const AST_GREP_TSX_SPLIT: Readonly<
  * Pinned against the binary by `test/vale-vendor-contract.test.ts`
  * ("engine capabilities" → "reports the pinned version").
  */
-export const VALE_VERSION = "3.21.0";
+export const VALE_VERSION = "3.22.0";
 
 /**
  * Which tier Vale routes an extension to.
@@ -271,6 +271,19 @@ 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.
  *
+ * 3.21.0 → 3.22.0 LEARNED NO FORMAT. Every row was re-probed against the
+ * 3.22.0 binary and none moved. The v3.21.0...v3.22.0 tree adds no
+ * `internal/lint/<format>.go` (its additions there are two `_test.go` files);
+ * `md.go`, `mdx.go`, `html.go`, `dita.go`, `code.go` and `metadata.go` change
+ * in what they do with a file, not in which files reach them. What did move
+ * is beside this table: an empty `BasedOnStyles` in a rule's `.vale.ini`
+ * clears every earlier matcher's settings for the file (see
+ * `src/schemas/vale-config.ts`, which now refuses the key, and migration
+ * 0008), a negated inline scope blanks the element's text out of its block,
+ * a `[formats]` key may be a file name or glob, and `lint.go`'s directory walk
+ * now skips the `StylesPath` tree unless a path inside it is named. All of it
+ * is pinned in `test/vale-vendor-contract.test.ts`.
+ *
  * 3.20.0 → 3.21.0 LEARNED ONE FORMAT, AND THE SOURCE CHECK IS WHAT FOUND IT.
  * Every existing row was re-probed against the 3.21.0 binary and none moved.
  * The v3.20.0...v3.21.0 tree adds `internal/lint/notebook.go` and routes
diff --git a/packages/cli/test/reconcile-marker.test.ts b/packages/cli/test/reconcile-marker.test.ts
index 14c81425..db50fd48 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.3", vale: "3.21.0" });
+    expect(rules?.engines).toEqual({ sg: "0.45.3", vale: "3.22.0" });
   });
 
   it("reports the marker through info", async () => {

From 76ce6d930242afad1810c350a114b9dc260332c3 Mon Sep 17 00:00:00 2001
From: Jakob Heuser <jakob@codedrift.com>
Date: Mon, 21 Sep 2026 16:05:56 -0700
Subject: [PATCH 2/5] feat(vale): reject BasedOnStyles in a rule config and
 migrate installed rules

Vale 3.22.0 gives an empty BasedOnStyles a meaning (upstream c2d62437):
it clears every setting a file inherited from an earlier matcher. The
assembled run config is every rule's matchers in id order, and the
recipe wrote BasedOnStyles = into every one of them, so on 3.22.0 a rule
under [docs/**] silences every alphabetically earlier rule under docs/,
and [*.md] beside another rule's [*.{md,markdown}] silences the first on
every .md file. Measured on both binaries against the exact layout
assembleValeConfig writes; only byte-identical globs, which Vale merges,
escape, which is why this repository's own five rules did not notice.

The schema now refuses the key with any value under
vale-config-no-based-on-styles (renamed from -based-on-styles-empty,
never released), and migration 0008 deletes the line from every
installed .taskless/rules/vale/*/.vale.ini, touching no other byte.
check and verify already refuse a scaffold behind the current version
and name init, which applies it. This repository's own .taskless/ is
migrated here by pnpm cli init.

The three isolating configs stop writing the line too. Their docblocks
claimed it kept Vale.Spelling from firing on a fixture; measured on both
binaries with a baited document, nothing fires without the key and the
control naming Vale fires all of it. No bundled style loads unless a
run-level BasedOnStyles names one.
---
 .../comments-record-not-forecast/.vale.ini    |   1 -
 .taskless/rules/vale/docs-npx-cli/.vale.ini   |   2 -
 .../rules/vale/no-blocklist-phrases/.vale.ini |   6 -
 .taskless/rules/vale/no-em-dashes/.vale.ini   |   6 -
 .taskless/rules/vale/no-hedging/.vale.ini     |   6 -
 .taskless/taskless.json                       |   4 +-
 .../.taskless/rules/vale/no-simply/.vale.ini  |   1 -
 packages/cli/assets/demo-vale/.vale.ini       |   1 -
 packages/cli/assets/reference.json            |  12 +-
 packages/cli/scripts/generate-vale-schema.ts  |  22 +-
 packages/cli/src/filesystem/migrate.ts        |   2 +
 .../migrations/0008-drop-based-on-styles.ts   |  72 +++++++
 packages/cli/src/rules/assemble.ts            |  10 +
 packages/cli/src/rules/constraints.ts         |  10 +-
 packages/cli/src/rules/vale/verify.ts         |  13 +-
 packages/cli/src/schemas/vale-config.ts       |  24 ++-
 packages/cli/test/assemble.test.ts            |   2 +-
 packages/cli/test/check.test.ts               |   2 +-
 packages/cli/test/constraints.test.ts         |  19 +-
 .../rules/vale/no-obviously/.vale.ini         |   1 -
 .../.taskless/rules/vale/no-simply/.vale.ini  |   1 -
 .../test/fixtures/vale-config/bad-value.ini   |   1 -
 .../vale-config/based-on-styles-named.ini     |   4 +
 .../fixtures/vale-config/based-on-styles.ini  |   2 +-
 .../vale-config/blank-inside-matcher.ini      |   1 -
 .../cli/test/fixtures/vale-config/dogfood.ini |   2 -
 .../test/fixtures/vale-config/foreign-key.ini |   1 -
 .../fixtures/vale-config/never-enabled.ini    |   1 -
 .../fixtures/vale-config/no-before-yes.ini    |   1 -
 .../fixtures/vale-config/no-breadcrumb.ini    |   1 -
 .../repeat-across-sections-still-enabled.ini  |   1 -
 .../vale-config/repeat-across-sections.ini    |   1 -
 .../vale-config/repeat-key-still-enabled.ini  |   1 -
 .../test/fixtures/vale-config/repeat-key.ini  |   1 -
 .../test/fixtures/vale-config/root-keys.ini   |   1 -
 .../cli/test/fixtures/vale-config/star.ini    |   1 -
 .../test/fixtures/vale-config/stray-key.ini   |   1 -
 .../fixtures/vale-config/taskless-tree.ini    |   1 -
 .../cli/test/fixtures/vale-config/valid.ini   |   1 -
 .../fixtures/vale-config/wrong-breadcrumb.ini |   1 -
 .../test/migrate-drop-based-on-styles.test.ts | 189 ++++++++++++++++++
 .../test/migrate-ignore-scratch-files.test.ts |   8 +-
 packages/cli/test/mixed-engine-check.test.ts  |  12 +-
 packages/cli/test/vale-config-schema.test.ts  |  77 +++++--
 packages/cli/test/vale-formats.test.ts        |   2 +-
 packages/cli/test/vale-orchestration.test.ts  |   6 +-
 .../cli/test/vale-schema-contract.test.ts     |   9 +-
 packages/cli/test/vale-verify.test.ts         |  12 +-
 .../cli/test/verify-test-commands.test.ts     |  10 +-
 49 files changed, 430 insertions(+), 136 deletions(-)
 create mode 100644 packages/cli/src/filesystem/migrations/0008-drop-based-on-styles.ts
 create mode 100644 packages/cli/test/fixtures/vale-config/based-on-styles-named.ini
 create mode 100644 packages/cli/test/migrate-drop-based-on-styles.test.ts

diff --git a/.taskless/rules/vale/comments-record-not-forecast/.vale.ini b/.taskless/rules/vale/comments-record-not-forecast/.vale.ini
index 48d29942..5d2d33b1 100644
--- a/.taskless/rules/vale/comments-record-not-forecast/.vale.ini
+++ b/.taskless/rules/vale/comments-record-not-forecast/.vale.ini
@@ -2,5 +2,4 @@
 # code body is invisible, so this rule can never fire on an identifier.
 [packages/cli/src/**/*.ts]
 tskl) rule = comments-record-not-forecast
-BasedOnStyles =
 comments-record-not-forecast.comments-record-not-forecast = YES
diff --git a/.taskless/rules/vale/docs-npx-cli/.vale.ini b/.taskless/rules/vale/docs-npx-cli/.vale.ini
index d1acb470..e1924e65 100644
--- a/.taskless/rules/vale/docs-npx-cli/.vale.ini
+++ b/.taskless/rules/vale/docs-npx-cli/.vale.ini
@@ -12,11 +12,9 @@
 # invocation, and the rule keeps its full reach.
 [**/README.md]
 tskl) rule = docs-npx-cli
-BasedOnStyles =
 docs-npx-cli.docs-npx-cli = YES
 
 # Test fixtures are inputs to the CLI's own suite, not documentation.
 [**/test/fixtures/**/README.md]
 tskl) rule = docs-npx-cli
-BasedOnStyles =
 docs-npx-cli.docs-npx-cli = NO
diff --git a/.taskless/rules/vale/no-blocklist-phrases/.vale.ini b/.taskless/rules/vale/no-blocklist-phrases/.vale.ini
index 83d3b005..37b7bfce 100644
--- a/.taskless/rules/vale/no-blocklist-phrases/.vale.ini
+++ b/.taskless/rules/vale/no-blocklist-phrases/.vale.ini
@@ -2,19 +2,16 @@
 # is a separate decision with a large remediation attached.
 [**/README.md]
 tskl) rule = no-blocklist-phrases
-BasedOnStyles =
 no-blocklist-phrases.no-blocklist-phrases = YES
 
 # Agent-facing instructions and the house conventions. Read as often as the
 # READMEs are, by both people and agents, and small enough to keep conforming.
 [CLAUDE.md]
 tskl) rule = no-blocklist-phrases
-BasedOnStyles =
 no-blocklist-phrases.no-blocklist-phrases = YES
 
 [.conventions/*.md]
 tskl) rule = no-blocklist-phrases
-BasedOnStyles =
 no-blocklist-phrases.no-blocklist-phrases = YES
 
 # Test fixtures are inputs to the CLI's own suite, not documentation.
@@ -30,12 +27,10 @@ no-blocklist-phrases.no-blocklist-phrases = YES
 # the size of the thing that earned one.
 [packages/cli/src/agent/*.md]
 tskl) rule = no-blocklist-phrases
-BasedOnStyles =
 no-blocklist-phrases.no-blocklist-phrases = YES
 
 [**/test/fixtures/**/README.md]
 tskl) rule = no-blocklist-phrases
-BasedOnStyles =
 no-blocklist-phrases.no-blocklist-phrases = NO
 
 # Root prose docs that are not READMEs. `dotagents.md` explains the agent
@@ -43,5 +38,4 @@ no-blocklist-phrases.no-blocklist-phrases = NO
 # outside the team exactly as a README is, and held to the same standard.
 [dotagents.md]
 tskl) rule = no-blocklist-phrases
-BasedOnStyles =
 no-blocklist-phrases.no-blocklist-phrases = YES
diff --git a/.taskless/rules/vale/no-em-dashes/.vale.ini b/.taskless/rules/vale/no-em-dashes/.vale.ini
index 3271b045..e970eeea 100644
--- a/.taskless/rules/vale/no-em-dashes/.vale.ini
+++ b/.taskless/rules/vale/no-em-dashes/.vale.ini
@@ -2,19 +2,16 @@
 # to source comments and openspec is a separate, much larger decision.
 [**/README.md]
 tskl) rule = no-em-dashes
-BasedOnStyles =
 no-em-dashes.no-em-dashes = YES
 
 # Agent-facing instructions and the house conventions. Read as often as the
 # READMEs are, by both people and agents, and small enough to keep conforming.
 [CLAUDE.md]
 tskl) rule = no-em-dashes
-BasedOnStyles =
 no-em-dashes.no-em-dashes = YES
 
 [.conventions/*.md]
 tskl) rule = no-em-dashes
-BasedOnStyles =
 no-em-dashes.no-em-dashes = YES
 
 # Test fixtures are inputs to the CLI's own suite, not documentation.
@@ -30,12 +27,10 @@ no-em-dashes.no-em-dashes = YES
 # the size of the thing that earned one.
 [packages/cli/src/agent/*.md]
 tskl) rule = no-em-dashes
-BasedOnStyles =
 no-em-dashes.no-em-dashes = YES
 
 [**/test/fixtures/**/README.md]
 tskl) rule = no-em-dashes
-BasedOnStyles =
 no-em-dashes.no-em-dashes = NO
 
 # Root prose docs that are not READMEs. `dotagents.md` explains the agent
@@ -43,5 +38,4 @@ no-em-dashes.no-em-dashes = NO
 # outside the team exactly as a README is, and held to the same standard.
 [dotagents.md]
 tskl) rule = no-em-dashes
-BasedOnStyles =
 no-em-dashes.no-em-dashes = YES
diff --git a/.taskless/rules/vale/no-hedging/.vale.ini b/.taskless/rules/vale/no-hedging/.vale.ini
index 0d55d3b9..9b5a1ffa 100644
--- a/.taskless/rules/vale/no-hedging/.vale.ini
+++ b/.taskless/rules/vale/no-hedging/.vale.ini
@@ -2,21 +2,17 @@
 # blocks are not prose, so this rule never sees a command or an identifier.
 [**/README.md]
 tskl) rule = no-hedging
-BasedOnStyles =
 no-hedging.no-hedging = YES
 
 [CLAUDE.md]
 tskl) rule = no-hedging
-BasedOnStyles =
 no-hedging.no-hedging = YES
 
 [.conventions/*.md]
 tskl) rule = no-hedging
-BasedOnStyles =
 no-hedging.no-hedging = YES
 [packages/cli/src/agent/*.md]
 tskl) rule = no-hedging
-BasedOnStyles =
 no-hedging.no-hedging = YES
 
 
@@ -56,7 +52,6 @@ no-hedging.no-hedging = YES
 
 [**/test/fixtures/**/README.md]
 tskl) rule = no-hedging
-BasedOnStyles =
 no-hedging.no-hedging = NO
 
 # Root prose docs that are not READMEs. `dotagents.md` explains the agent
@@ -64,5 +59,4 @@ no-hedging.no-hedging = NO
 # outside the team exactly as a README is, and held to the same standard.
 [dotagents.md]
 tskl) rule = no-hedging
-BasedOnStyles =
 no-hedging.no-hedging = YES
diff --git a/.taskless/taskless.json b/.taskless/taskless.json
index 72bd9028..b00f7c3b 100644
--- a/.taskless/taskless.json
+++ b/.taskless/taskless.json
@@ -1,5 +1,5 @@
 {
-  "version": 7,
+  "version": 8,
   "install": {
     "targets": {
       ".taskless": {
@@ -21,7 +21,7 @@
         "mode": "reference"
       }
     },
-    "cliVersion": "0.11.0",
+    "cliVersion": "0.11.2",
     "onboarded": true
   },
   "rules": {
diff --git a/example/.taskless/rules/vale/no-simply/.vale.ini b/example/.taskless/rules/vale/no-simply/.vale.ini
index a123e1f2..a97301bd 100644
--- a/example/.taskless/rules/vale/no-simply/.vale.ini
+++ b/example/.taskless/rules/vale/no-simply/.vale.ini
@@ -2,5 +2,4 @@
 # directory. That's the point of the layout.
 [*.{html,md}]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
diff --git a/packages/cli/assets/demo-vale/.vale.ini b/packages/cli/assets/demo-vale/.vale.ini
index eeeca4a3..2dd81677 100644
--- a/packages/cli/assets/demo-vale/.vale.ini
+++ b/packages/cli/assets/demo-vale/.vale.ini
@@ -2,5 +2,4 @@
 # should never widen its own scope into a project's source.
 [**/*.md]
 tskl) rule = prefer-use-over-utilize
-BasedOnStyles =
 prefer-use-over-utilize.prefer-use-over-utilize = YES
diff --git a/packages/cli/assets/reference.json b/packages/cli/assets/reference.json
index 3760d5a1..98ead6d6 100644
--- a/packages/cli/assets/reference.json
+++ b/packages/cli/assets/reference.json
@@ -100,7 +100,7 @@
       "id": "vale-config-own-key-only",
       "engine": "vale",
       "enforcedBy": "verify",
-      "summary": "Inside a matcher, the only assignments are the breadcrumb, an empty `BasedOnStyles`, and `<id>.<id>`.",
+      "summary": "Inside a matcher, the only assignments are the breadcrumb and `<id>.<id>`.",
       "rationale": "A `<style>.<check>` key naming any other rule is a cross-rule override, and a rule cannot know its own position in the assembled file, so whether the override wins depends on directory sort order. Any other key is a run-level or Vale-wide setting placed where it would apply to every rule after it. The per-rule layout exists to remove that coupling; this is what enforces it."
     },
     {
@@ -111,11 +111,11 @@
       "rationale": "Vale also accepts a level name here (`warning`, `error`) to override the style's own, which would make the rule's severity depend on its config rather than its style file, and it reads anything else as `NO` without saying so. A rule's scope is a yes-or-no question, and its level is answered once, in the style."
     },
     {
-      "id": "vale-config-based-on-styles-empty",
+      "id": "vale-config-no-based-on-styles",
       "engine": "vale",
       "enforcedBy": "verify",
-      "summary": "`BasedOnStyles` is empty in every matcher that sets it.",
-      "rationale": "`BasedOnStyles = Vale` loads a whole bundled style alongside the rule, so a fixture that fails on `Vale.Spelling` reads as the rule firing, and every other rule's matchers inherit the style wherever the globs overlap. The isolating config `test` runs sets it empty for the same reason. A rule enables itself by name, not by style."
+      "summary": "No matcher sets `BasedOnStyles`, empty or otherwise.",
+      "rationale": "Measured on Vale 3.22.0, an empty `BasedOnStyles` clears every setting a file inherited from an earlier matcher (upstream c2d62437), and the assembled run config interleaves every rule's matchers in id order. A rule writing `BasedOnStyles =` under `[docs/**]` therefore silences every alphabetically earlier rule under `docs/`, and only byte-identical globs, which Vale merges into one section, escape it. Through 3.21.0 the line was inert. A non-empty value was always refused: `BasedOnStyles = Vale` loads a whole bundled style alongside the rule and reaches every rule whose matchers overlap. Neither value was ever needed. Vale loads no bundled style unless a run-level `BasedOnStyles` names one, and the assembled header names none, so a rule enables itself by name and the key has no job in a rule's config."
     },
     {
       "id": "vale-config-matcher-required",
@@ -129,7 +129,7 @@
       "engine": "vale",
       "enforcedBy": "verify",
       "summary": "Some matcher assigns `<id>.<id> = YES`.",
-      "rationale": "With `BasedOnStyles` empty a rule is off until a matcher turns it on. A config whose every matcher says `NO`, or none says anything, leaves the rule present but off: it verifies, it is assembled, and it reports nothing."
+      "rationale": "No style is loaded, so a rule is off until a matcher turns it on. A config whose every matcher says `NO`, or none says anything, leaves the rule present but off: it verifies, it is assembled, and it reports nothing."
     },
     {
       "id": "vale-config-disable-after-enable",
@@ -175,7 +175,7 @@
         },
         {
           "path": ".vale.ini",
-          "content": "# Scoped to markdown, which is where prose rules belong. A demonstration rule\n# should never widen its own scope into a project's source.\n[**/*.md]\ntskl) rule = prefer-use-over-utilize\nBasedOnStyles =\nprefer-use-over-utilize.prefer-use-over-utilize = YES\n"
+          "content": "# Scoped to markdown, which is where prose rules belong. A demonstration rule\n# should never widen its own scope into a project's source.\n[**/*.md]\ntskl) rule = prefer-use-over-utilize\nprefer-use-over-utilize.prefer-use-over-utilize = YES\n"
         }
       ],
       "tests": {
diff --git a/packages/cli/scripts/generate-vale-schema.ts b/packages/cli/scripts/generate-vale-schema.ts
index 657855cd..4ada9fb9 100644
--- a/packages/cli/scripts/generate-vale-schema.ts
+++ b/packages/cli/scripts/generate-vale-schema.ts
@@ -135,18 +135,26 @@ type ProbeOutcome =
 /**
  * Run one rule over one document in a config isolated from everything else.
  *
- * `BasedOnStyles =` is load-bearing. Without it Vale loads its bundled styles
- * and a control document can trip one of those, which a finding count cannot
- * tell apart from the rule under test firing.
+ * No `BasedOnStyles` line, and that is measured rather than assumed. The
+ * recipe used to write `BasedOnStyles =` on the claim that without it Vale
+ * loads its bundled styles and a control document trips one. Measured on
+ * 3.21.0 and 3.22.0 with a document baited for `Vale.Spelling`,
+ * `Vale.Repetition` and `Vale.Terms`: nothing but the probe fires when the
+ * key is absent, and the control (`BasedOnStyles = Vale`) fires all of them.
+ * Vale loads no bundled style unless a run-level `BasedOnStyles` names one.
+ * The line went when 3.22.0 gave an empty value a meaning (it clears a
+ * file's inherited settings), which is inert in a single-matcher config but
+ * is the shape the config schema now refuses in a rule's own `.vale.ini`.
  *
  * `--no-exit` suppresses the non-zero status Vale returns merely for *finding*
  * something, so a non-zero status here means the config itself failed.
  *
  * **This config is the sibling of `buildIsolatingConfig` in
  * `src/rules/vale/verify.ts`, and the two are kept deliberately separate.**
- * They agree on three details: `MinAlertLevel = suggestion`, an empty
- * `BasedOnStyles =`, and exactly one assignment of the enabled key in exactly
- * one matcher, the last two of which that docstring explains are load-bearing.
+ * They agree on three details: `MinAlertLevel = suggestion`, no
+ * `BasedOnStyles` line, and exactly one assignment of the enabled key in
+ * exactly one matcher, the last of which that docstring explains is
+ * load-bearing.
  * They differ on the fourth, which is why this is not a call to that function:
  * `buildIsolatingConfig` needs an absolute `StylesPath` because it writes its
  * config to a temp directory while the styles stay in the user's
@@ -171,7 +179,7 @@ function probe(
     writeFileSync(join(cwd, "styles", "probe", "probe.yml"), rule);
     writeFileSync(
       join(cwd, ".vale.ini"),
-      "StylesPath = styles\nMinAlertLevel = suggestion\n\n[*]\nBasedOnStyles =\nprobe.probe = YES\n"
+      "StylesPath = styles\nMinAlertLevel = suggestion\n\n[*]\nprobe.probe = YES\n"
     );
     writeFileSync(join(cwd, `doc.${extension}`), document);
 
diff --git a/packages/cli/src/filesystem/migrate.ts b/packages/cli/src/filesystem/migrate.ts
index 43af2310..7dc6d409 100644
--- a/packages/cli/src/filesystem/migrate.ts
+++ b/packages/cli/src/filesystem/migrate.ts
@@ -14,6 +14,7 @@ import valeEngine from "./migrations/0004-vale-engine";
 import ruleDirectories from "./migrations/0005-rule-directories";
 import refreshReadme from "./migrations/0006-refresh-readme";
 import ignoreScratchFiles from "./migrations/0007-ignore-scratch-files";
+import dropBasedOnStyles from "./migrations/0008-drop-based-on-styles";
 
 export interface TasklessInstallTarget {
   skills?: string[];
@@ -78,6 +79,7 @@ const migrations: Migrations = {
   "5": ruleDirectories,
   "6": refreshReadme,
   "7": ignoreScratchFiles,
+  "8": dropBasedOnStyles,
 };
 
 /** Global flag that downgrades a too-new scaffold from an error to a skip. */
diff --git a/packages/cli/src/filesystem/migrations/0008-drop-based-on-styles.ts b/packages/cli/src/filesystem/migrations/0008-drop-based-on-styles.ts
new file mode 100644
index 00000000..e2339ac9
--- /dev/null
+++ b/packages/cli/src/filesystem/migrations/0008-drop-based-on-styles.ts
@@ -0,0 +1,72 @@
+import { readdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import type { Migration } from "../types";
+
+/**
+ * Delete every `BasedOnStyles` assignment from each Vale rule's `.vale.ini`.
+ *
+ * The `create-vale-rule` recipe told every author to write `BasedOnStyles =`
+ * in every matcher, and through Vale 3.21.0 the line was inert: no bundled
+ * style loads unless a run-level `BasedOnStyles` names one, and the assembled
+ * header names none. Vale 3.22.0 gave an empty value a meaning (upstream
+ * c2d62437): it clears every setting the file inherited from an earlier
+ * matcher. The assembled run config is every rule's matchers in id order, so
+ * a rule writing the line under `[docs/**]` silences every alphabetically
+ * earlier rule under `docs/`, and `[*.md]` beside `[*.{md,markdown}]` silences
+ * the first everywhere. Only byte-identical globs, which Vale merges into one
+ * section, escape. Measured on both binaries and pinned in
+ * `test/vale-vendor-contract.test.ts`.
+ *
+ * The config schema now refuses the key (`vale-config-no-based-on-styles`),
+ * so a rule still carrying it fails `verify` and refuses the Vale run at
+ * `check`. This migration is what keeps an upgrade from turning every
+ * existing project's `check` red: it deletes the line so the configs pass the
+ * schema they passed before, with the behaviour they had before.
+ *
+ * A line edit, deliberately, rather than a parse and re-serialize. The
+ * config schema reads the file as an AST for validation, and assembly writes
+ * the author's own bytes; the parser's `toString()` is measured not to round
+ * trip, so it is never called. Deleting whole lines is the one edit that
+ * leaves every other byte, comment and blank line where the author put it.
+ * The match is anchored on the key at the start of a line, so a comment that
+ * mentions `BasedOnStyles` is left alone.
+ *
+ * Idempotent: a config without the line is read and not rewritten, so a
+ * second run touches nothing and a project's `git status` stays clean.
+ */
+const migration: Migration = async (directory) => {
+  const valeRules = join(directory, "rules", "vale");
+  let entries;
+  try {
+    entries = await readdir(valeRules, { withFileTypes: true });
+  } catch {
+    // No Vale rules tree: nothing to rewrite. A project scaffolded before
+    // `0004` and never given a Vale rule has no such directory.
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const configPath = join(valeRules, entry.name, ".vale.ini");
+    let source: string;
+    try {
+      source = await readFile(configPath, "utf8");
+    } catch {
+      // A rule directory with no config declares no scope; `verify` reports
+      // that, and there is nothing here to delete.
+      continue;
+    }
+    const stripped = dropBasedOnStyles(source);
+    if (stripped !== source) await writeFile(configPath, stripped, "utf8");
+  }
+};
+
+/** Every `BasedOnStyles = …` assignment line, whatever its value. */
+const BASED_ON_STYLES_LINE = /^[ \t]*BasedOnStyles[ \t]*=.*(?:\r?\n|$)/gm;
+
+/** `source` with every `BasedOnStyles` assignment line removed. */
+export function dropBasedOnStyles(source: string): string {
+  return source.replaceAll(BASED_ON_STYLES_LINE, "");
+}
+
+export default migration;
diff --git a/packages/cli/src/rules/assemble.ts b/packages/cli/src/rules/assemble.ts
index 1ed94238..adf40c7c 100644
--- a/packages/cli/src/rules/assemble.ts
+++ b/packages/cli/src/rules/assemble.ts
@@ -32,6 +32,16 @@ import { RULE_TESTS_DIRECTORY, RULES_DIRECTORY } from "./layout";
  * A consequence worth naming: a rule cannot override another rule's matchers,
  * because it cannot know its own position in the assembled file. That coupling
  * is exactly what per-rule configs remove.
+ *
+ * **Interleaving is also why a rule's config may not carry `BasedOnStyles`.**
+ * Since Vale 3.22.0 an empty value clears every setting a file inherited from
+ * an earlier matcher, and here "earlier" means every other rule whose glob
+ * reaches the file, so a rule writing `BasedOnStyles =` under `[docs/**]`
+ * silences every alphabetically earlier rule under `docs/`. Only a
+ * byte-identical glob, which Vale merges into one section, escapes. The
+ * schema refuses the key (`vale-config-no-based-on-styles`) and migration
+ * 0008 deletes it from installed configs; `vale-vendor-contract.test.ts`
+ * pins the measurement on the exact layout this module writes.
  */
 
 /** Path within `.taskless/`, in the POSIX form both tools' configs expect. */
diff --git a/packages/cli/src/rules/constraints.ts b/packages/cli/src/rules/constraints.ts
index b386863e..75eca950 100644
--- a/packages/cli/src/rules/constraints.ts
+++ b/packages/cli/src/rules/constraints.ts
@@ -164,7 +164,7 @@ export const RULE_CONSTRAINTS = [
     engine: "vale",
     enforcedBy: "verify",
     summary:
-      "Inside a matcher, the only assignments are the breadcrumb, an empty `BasedOnStyles`, and `<id>.<id>`.",
+      "Inside a matcher, the only assignments are the breadcrumb and `<id>.<id>`.",
     rationale:
       "A `<style>.<check>` key naming any other rule is a cross-rule override, and a rule cannot know its own position in the assembled file, so whether the override wins depends on directory sort order. Any other key is a run-level or Vale-wide setting placed where it would apply to every rule after it. The per-rule layout exists to remove that coupling; this is what enforces it.",
   },
@@ -177,12 +177,12 @@ export const RULE_CONSTRAINTS = [
       "Vale also accepts a level name here (`warning`, `error`) to override the style's own, which would make the rule's severity depend on its config rather than its style file, and it reads anything else as `NO` without saying so. A rule's scope is a yes-or-no question, and its level is answered once, in the style.",
   },
   {
-    id: "vale-config-based-on-styles-empty",
+    id: "vale-config-no-based-on-styles",
     engine: "vale",
     enforcedBy: "verify",
-    summary: "`BasedOnStyles` is empty in every matcher that sets it.",
+    summary: "No matcher sets `BasedOnStyles`, empty or otherwise.",
     rationale:
-      "`BasedOnStyles = Vale` loads a whole bundled style alongside the rule, so a fixture that fails on `Vale.Spelling` reads as the rule firing, and every other rule's matchers inherit the style wherever the globs overlap. The isolating config `test` runs sets it empty for the same reason. A rule enables itself by name, not by style.",
+      "Measured on Vale 3.22.0, an empty `BasedOnStyles` clears every setting a file inherited from an earlier matcher (upstream c2d62437), and the assembled run config interleaves every rule's matchers in id order. A rule writing `BasedOnStyles =` under `[docs/**]` therefore silences every alphabetically earlier rule under `docs/`, and only byte-identical globs, which Vale merges into one section, escape it. Through 3.21.0 the line was inert. A non-empty value was always refused: `BasedOnStyles = Vale` loads a whole bundled style alongside the rule and reaches every rule whose matchers overlap. Neither value was ever needed. Vale loads no bundled style unless a run-level `BasedOnStyles` names one, and the assembled header names none, so a rule enables itself by name and the key has no job in a rule's config.",
   },
   {
     id: "vale-config-matcher-required",
@@ -198,7 +198,7 @@ export const RULE_CONSTRAINTS = [
     enforcedBy: "verify",
     summary: "Some matcher assigns `<id>.<id> = YES`.",
     rationale:
-      "With `BasedOnStyles` empty a rule is off until a matcher turns it on. A config whose every matcher says `NO`, or none says anything, leaves the rule present but off: it verifies, it is assembled, and it reports nothing.",
+      "No style is loaded, so a rule is off until a matcher turns it on. A config whose every matcher says `NO`, or none says anything, leaves the rule present but off: it verifies, it is assembled, and it reports nothing.",
   },
   {
     id: "vale-config-disable-after-enable",
diff --git a/packages/cli/src/rules/vale/verify.ts b/packages/cli/src/rules/vale/verify.ts
index a66a6927..5594d126 100644
--- a/packages/cli/src/rules/vale/verify.ts
+++ b/packages/cli/src/rules/vale/verify.ts
@@ -34,8 +34,16 @@ function stylesPath(cwd: string): string {
  * - `StylesPath` is absolute. The config is written to a temp directory, and
  *   Vale resolves StylesPath relative to the config file, so a relative path
  *   would look for styles beside the temp file.
- * - `BasedOnStyles =` is empty, so none of Vale's bundled styles load. Without
- *   it a fixture could fail on `Vale.Spelling` and be read as the rule firing.
+ * - No `BasedOnStyles` line. The config wrote `BasedOnStyles =` through Vale
+ *   3.21.0 on the claim that without it a fixture could fail on
+ *   `Vale.Spelling`. Measured on 3.21.0 and 3.22.0, with a document baited
+ *   for `Vale.Spelling`, `Vale.Repetition` and `Vale.Terms`: nothing fires
+ *   without the key, and every one of them fires under `BasedOnStyles = Vale`.
+ *   A bundled style loads only when a run-level `BasedOnStyles` names one.
+ *   The line went because 3.22.0 gave an empty value a meaning, clearing a
+ *   file's inherited settings, and the config schema refuses it in a rule's
+ *   own `.vale.ini` for that reason; the isolating config should not write
+ *   the shape `verify` refuses.
  * - Exactly one assignment of the key, in one matcher. Precedence here is
  *   positional in both directions (a later matcher wins, and since Vale
  *   3.21.0 so does a later repeat inside one matcher; through 3.20.0 the
@@ -54,7 +62,6 @@ export function buildIsolatingConfig(cwd: string, ruleId: string): string {
     "MinAlertLevel = suggestion",
     "",
     "[*]",
-    "BasedOnStyles =",
     `${ruleId}.${ruleId} = YES`,
     "",
   ].join("\n");
diff --git a/packages/cli/src/schemas/vale-config.ts b/packages/cli/src/schemas/vale-config.ts
index 3f6bb192..48ea4950 100644
--- a/packages/cli/src/schemas/vale-config.ts
+++ b/packages/cli/src/schemas/vale-config.ts
@@ -352,14 +352,16 @@ function valeRuleConfigSchema(ruleId: string) {
       for (const property of assignments) {
         if (property.key === VALE_BREADCRUMB_KEY) continue;
         if (property.key === BASED_ON_STYLES_KEY) {
-          if (property.value !== "") {
-            fail(
-              "vale-config-based-on-styles-empty",
-              path,
-              `${where(ruleId, property)} matcher ${label} sets BasedOnStyles = "${property.value}". ` +
-                `It must be empty: a bundled style loaded here fires alongside ${ruleId} and reaches every rule whose matchers overlap.`
-            );
-          }
+          fail(
+            "vale-config-no-based-on-styles",
+            path,
+            property.value === ""
+              ? `${where(ruleId, property)} matcher ${label} sets BasedOnStyles to empty. ` +
+                  `On Vale ${VALE_VERSION} an empty BasedOnStyles clears every earlier matcher's settings for a file this one reaches, ` +
+                  `which silences the other rules whose globs overlap. Delete the line: no bundled style loads unless a run-level BasedOnStyles names one.`
+              : `${where(ruleId, property)} matcher ${label} sets BasedOnStyles = "${property.value}". ` +
+                  `A bundled style loaded here fires alongside ${ruleId} and reaches every rule whose matchers overlap. Delete the line: a rule enables itself by name.`
+          );
           continue;
         }
         if (property.key !== ownKey) {
@@ -371,7 +373,7 @@ function valeRuleConfigSchema(ruleId: string) {
               ? `${where(ruleId, property)} matcher ${label} assigns "${property.key}", which names another rule. ` +
                   `A rule's config may only enable or disable itself, as ${ownKey}; anything else is a cross-rule override.`
               : `${where(ruleId, property)} matcher ${label} assigns "${property.key}", which is not a per-rule setting. ` +
-                  `Inside a matcher a rule's config carries only "${VALE_BREADCRUMB_KEY}", an empty BasedOnStyles, and ${ownKey}.`
+                  `Inside a matcher a rule's config carries only "${VALE_BREADCRUMB_KEY}" and ${ownKey}.`
           );
           continue;
         }
@@ -402,8 +404,8 @@ function valeRuleConfigSchema(ruleId: string) {
       return;
     }
 
-    // Ordering: a NO-verdict matcher before every YES-verdict matcher. With
-    // BasedOnStyles empty the rule is off until a YES, so such a NO is dead
+    // Ordering: a NO-verdict matcher before every YES-verdict matcher. No
+    // style is loaded, so the rule is off until a YES, and such a NO is dead
     // where nothing else matches and overridden where the later YES does.
     // Reported against the first YES, which is the one that re-enables it.
     const enabler = final[firstYes]?.section;
diff --git a/packages/cli/test/assemble.test.ts b/packages/cli/test/assemble.test.ts
index b1dbf529..48fc30fd 100644
--- a/packages/cli/test/assemble.test.ts
+++ b/packages/cli/test/assemble.test.ts
@@ -203,7 +203,7 @@ describe("Vale config assembly", () => {
   // the schema reads it as an AST, Vale reads the author's own bytes.
   it("writes an accepted config verbatim under its breadcrumb", async () => {
     const source =
-      "# scope\n[docs/**]\ntskl) rule = no-simply\nBasedOnStyles =\n\nno-simply.no-simply = YES   \n";
+      "# scope\n[docs/**]\ntskl) rule = no-simply\n\nno-simply.no-simply = YES   \n";
     await valeRule("no-simply", source);
     const assembled = await assembleValeConfig(cwd);
     expect(assembled?.status).toBe("ok");
diff --git a/packages/cli/test/check.test.ts b/packages/cli/test/check.test.ts
index c56e490f..13efe40f 100644
--- a/packages/cli/test/check.test.ts
+++ b/packages/cli/test/check.test.ts
@@ -94,7 +94,7 @@ describe("check", () => {
     );
     await writeFile(
       join(temporaryDirectory, ".taskless", "vale", ".vale.ini"),
-      "StylesPath = .\nMinAlertLevel = suggestion\n\n[*.md]\nBasedOnStyles =\nrules.no-simply = YES\n"
+      "StylesPath = .\nMinAlertLevel = suggestion\n\n[*.md]\nrules.no-simply = YES\n"
     );
     await writeFile(join(temporaryDirectory, "doc.md"), "Just simply do it.\n");
 
diff --git a/packages/cli/test/constraints.test.ts b/packages/cli/test/constraints.test.ts
index b7277444..a1241a62 100644
--- a/packages/cli/test/constraints.test.ts
+++ b/packages/cli/test/constraints.test.ts
@@ -143,7 +143,7 @@ async function verifyValeConfig(
 
 /** The config every Vale scenario below is a mutation of. */
 const VALID_VALE_CONFIG =
-  "[*.md]\ntskl) rule = probe-rule\nBasedOnStyles =\nprobe-rule.probe-rule = YES\n";
+  "[*.md]\ntskl) rule = probe-rule\nprobe-rule.probe-rule = YES\n";
 
 /**
  * The scenario that must violate each documented constraint.
@@ -235,10 +235,7 @@ const VIOLATIONS: Record<string, Scenario> = {
     names: /"StylesPath" is assigned above the first \[matcher\]/,
   },
   "vale-config-breadcrumb-required": {
-    run: () =>
-      verifyValeConfig(
-        "[*.md]\nBasedOnStyles =\nprobe-rule.probe-rule = YES\n"
-      ),
+    run: () => verifyValeConfig("[*.md]\nprobe-rule.probe-rule = YES\n"),
     names: /has no "tskl\) rule = probe-rule" breadcrumb/,
   },
   "vale-config-own-key-only": {
@@ -249,16 +246,16 @@ const VIOLATIONS: Record<string, Scenario> = {
   "vale-config-value-yes-no": {
     run: () =>
       verifyValeConfig(
-        "[*.md]\ntskl) rule = probe-rule\nBasedOnStyles =\nprobe-rule.probe-rule = warning\n"
+        "[*.md]\ntskl) rule = probe-rule\nprobe-rule.probe-rule = warning\n"
       ),
     names: /probe-rule\.probe-rule = "warning" is not YES or NO/,
   },
-  "vale-config-based-on-styles-empty": {
+  "vale-config-no-based-on-styles": {
     run: () =>
       verifyValeConfig(
-        "[*.md]\ntskl) rule = probe-rule\nBasedOnStyles = Vale\nprobe-rule.probe-rule = YES\n"
+        "[*.md]\ntskl) rule = probe-rule\nBasedOnStyles =\nprobe-rule.probe-rule = YES\n"
       ),
-    names: /sets BasedOnStyles = "Vale"/,
+    names: /sets BasedOnStyles to empty/,
   },
   "vale-config-matcher-required": {
     run: () => verifyValeConfig("# nothing here\n"),
@@ -267,7 +264,7 @@ const VIOLATIONS: Record<string, Scenario> = {
   "vale-config-enabled-somewhere": {
     run: () =>
       verifyValeConfig(
-        "[*.md]\ntskl) rule = probe-rule\nBasedOnStyles =\nprobe-rule.probe-rule = NO\n"
+        "[*.md]\ntskl) rule = probe-rule\nprobe-rule.probe-rule = NO\n"
       ),
     names:
       /never enables probe-rule\.probe-rule, so the rule is present but off/,
@@ -276,7 +273,7 @@ const VIOLATIONS: Record<string, Scenario> = {
     run: () =>
       verifyValeConfig(
         "[docs/legacy/**]\ntskl) rule = probe-rule\nprobe-rule.probe-rule = NO\n\n" +
-          "[docs/**]\ntskl) rule = probe-rule\nBasedOnStyles =\nprobe-rule.probe-rule = YES\n"
+          "[docs/**]\ntskl) rule = probe-rule\nprobe-rule.probe-rule = YES\n"
       ),
     names: /disables probe-rule before any matcher enables it/,
   },
diff --git a/packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-obviously/.vale.ini b/packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-obviously/.vale.ini
index f59145a3..628d2902 100644
--- a/packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-obviously/.vale.ini
+++ b/packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-obviously/.vale.ini
@@ -1,4 +1,3 @@
 [*.md]
 tskl) rule = no-obviously
-BasedOnStyles =
 no-obviously.no-obviously = YES
diff --git a/packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-simply/.vale.ini b/packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-simply/.vale.ini
index 00b47ba3..dfeb3a5e 100644
--- a/packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-simply/.vale.ini
+++ b/packages/cli/test/fixtures/mixed-engines-project/.taskless/rules/vale/no-simply/.vale.ini
@@ -1,4 +1,3 @@
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
diff --git a/packages/cli/test/fixtures/vale-config/bad-value.ini b/packages/cli/test/fixtures/vale-config/bad-value.ini
index b0290be1..08c172fd 100644
--- a/packages/cli/test/fixtures/vale-config/bad-value.ini
+++ b/packages/cli/test/fixtures/vale-config/bad-value.ini
@@ -1,4 +1,3 @@
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = yes
diff --git a/packages/cli/test/fixtures/vale-config/based-on-styles-named.ini b/packages/cli/test/fixtures/vale-config/based-on-styles-named.ini
new file mode 100644
index 00000000..6e593840
--- /dev/null
+++ b/packages/cli/test/fixtures/vale-config/based-on-styles-named.ini
@@ -0,0 +1,4 @@
+[*.md]
+tskl) rule = no-simply
+BasedOnStyles = Vale
+no-simply.no-simply = YES
diff --git a/packages/cli/test/fixtures/vale-config/based-on-styles.ini b/packages/cli/test/fixtures/vale-config/based-on-styles.ini
index 6e593840..00b47ba3 100644
--- a/packages/cli/test/fixtures/vale-config/based-on-styles.ini
+++ b/packages/cli/test/fixtures/vale-config/based-on-styles.ini
@@ -1,4 +1,4 @@
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles = Vale
+BasedOnStyles =
 no-simply.no-simply = YES
diff --git a/packages/cli/test/fixtures/vale-config/blank-inside-matcher.ini b/packages/cli/test/fixtures/vale-config/blank-inside-matcher.ini
index 808f8b48..225e893b 100644
--- a/packages/cli/test/fixtures/vale-config/blank-inside-matcher.ini
+++ b/packages/cli/test/fixtures/vale-config/blank-inside-matcher.ini
@@ -1,6 +1,5 @@
 [*.md]
 tskl) rule = no-simply
 
-BasedOnStyles =
 
 no-simply.no-simply = YES
diff --git a/packages/cli/test/fixtures/vale-config/dogfood.ini b/packages/cli/test/fixtures/vale-config/dogfood.ini
index 8fe8cf44..47e91f8f 100644
--- a/packages/cli/test/fixtures/vale-config/dogfood.ini
+++ b/packages/cli/test/fixtures/vale-config/dogfood.ini
@@ -2,7 +2,6 @@
 # that check never needs.
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
 
 [2024/**]
@@ -11,7 +10,6 @@ no-simply.no-simply = NO
 
 [docs/[a-z]*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
 
 [.taskless/**]
diff --git a/packages/cli/test/fixtures/vale-config/foreign-key.ini b/packages/cli/test/fixtures/vale-config/foreign-key.ini
index 04c49c71..e46f7ea1 100644
--- a/packages/cli/test/fixtures/vale-config/foreign-key.ini
+++ b/packages/cli/test/fixtures/vale-config/foreign-key.ini
@@ -1,5 +1,4 @@
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
 no-hedging.no-hedging = NO
diff --git a/packages/cli/test/fixtures/vale-config/never-enabled.ini b/packages/cli/test/fixtures/vale-config/never-enabled.ini
index 723a17a6..b183bd4e 100644
--- a/packages/cli/test/fixtures/vale-config/never-enabled.ini
+++ b/packages/cli/test/fixtures/vale-config/never-enabled.ini
@@ -1,4 +1,3 @@
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = NO
diff --git a/packages/cli/test/fixtures/vale-config/no-before-yes.ini b/packages/cli/test/fixtures/vale-config/no-before-yes.ini
index 177f15ff..07d6e6b7 100644
--- a/packages/cli/test/fixtures/vale-config/no-before-yes.ini
+++ b/packages/cli/test/fixtures/vale-config/no-before-yes.ini
@@ -4,5 +4,4 @@ no-simply.no-simply = NO
 
 [docs/**]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
diff --git a/packages/cli/test/fixtures/vale-config/no-breadcrumb.ini b/packages/cli/test/fixtures/vale-config/no-breadcrumb.ini
index c3605776..02f82bb0 100644
--- a/packages/cli/test/fixtures/vale-config/no-breadcrumb.ini
+++ b/packages/cli/test/fixtures/vale-config/no-breadcrumb.ini
@@ -1,3 +1,2 @@
 [*.md]
-BasedOnStyles =
 no-simply.no-simply = YES
diff --git a/packages/cli/test/fixtures/vale-config/repeat-across-sections-still-enabled.ini b/packages/cli/test/fixtures/vale-config/repeat-across-sections-still-enabled.ini
index b7e7792a..9a89f35a 100644
--- a/packages/cli/test/fixtures/vale-config/repeat-across-sections-still-enabled.ini
+++ b/packages/cli/test/fixtures/vale-config/repeat-across-sections-still-enabled.ini
@@ -1,6 +1,5 @@
 [docs/**]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
 
 [*.md]
diff --git a/packages/cli/test/fixtures/vale-config/repeat-across-sections.ini b/packages/cli/test/fixtures/vale-config/repeat-across-sections.ini
index c17dcc21..f2a98114 100644
--- a/packages/cli/test/fixtures/vale-config/repeat-across-sections.ini
+++ b/packages/cli/test/fixtures/vale-config/repeat-across-sections.ini
@@ -1,6 +1,5 @@
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
 
 [*.md]
diff --git a/packages/cli/test/fixtures/vale-config/repeat-key-still-enabled.ini b/packages/cli/test/fixtures/vale-config/repeat-key-still-enabled.ini
index e2652633..b191babb 100644
--- a/packages/cli/test/fixtures/vale-config/repeat-key-still-enabled.ini
+++ b/packages/cli/test/fixtures/vale-config/repeat-key-still-enabled.ini
@@ -1,6 +1,5 @@
 [docs/**]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
 
 [*.md]
diff --git a/packages/cli/test/fixtures/vale-config/repeat-key.ini b/packages/cli/test/fixtures/vale-config/repeat-key.ini
index a7d64e07..e01310a5 100644
--- a/packages/cli/test/fixtures/vale-config/repeat-key.ini
+++ b/packages/cli/test/fixtures/vale-config/repeat-key.ini
@@ -1,5 +1,4 @@
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
 no-simply.no-simply = NO
diff --git a/packages/cli/test/fixtures/vale-config/root-keys.ini b/packages/cli/test/fixtures/vale-config/root-keys.ini
index 71f627c3..15d5047d 100644
--- a/packages/cli/test/fixtures/vale-config/root-keys.ini
+++ b/packages/cli/test/fixtures/vale-config/root-keys.ini
@@ -3,5 +3,4 @@ MinAlertLevel = suggestion
 
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
diff --git a/packages/cli/test/fixtures/vale-config/star.ini b/packages/cli/test/fixtures/vale-config/star.ini
index 69efd5c8..04357ca3 100644
--- a/packages/cli/test/fixtures/vale-config/star.ini
+++ b/packages/cli/test/fixtures/vale-config/star.ini
@@ -1,4 +1,3 @@
 [*]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
diff --git a/packages/cli/test/fixtures/vale-config/stray-key.ini b/packages/cli/test/fixtures/vale-config/stray-key.ini
index 2e03c849..bff4e25c 100644
--- a/packages/cli/test/fixtures/vale-config/stray-key.ini
+++ b/packages/cli/test/fixtures/vale-config/stray-key.ini
@@ -1,5 +1,4 @@
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 MinAlertLevel = error
 no-simply.no-simply = YES
diff --git a/packages/cli/test/fixtures/vale-config/taskless-tree.ini b/packages/cli/test/fixtures/vale-config/taskless-tree.ini
index 59238ffb..18c3013d 100644
--- a/packages/cli/test/fixtures/vale-config/taskless-tree.ini
+++ b/packages/cli/test/fixtures/vale-config/taskless-tree.ini
@@ -1,6 +1,5 @@
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
 
 [.taskless/**]
diff --git a/packages/cli/test/fixtures/vale-config/valid.ini b/packages/cli/test/fixtures/vale-config/valid.ini
index e8e01467..3ea59a7a 100644
--- a/packages/cli/test/fixtures/vale-config/valid.ini
+++ b/packages/cli/test/fixtures/vale-config/valid.ini
@@ -1,6 +1,5 @@
 [*.md]
 tskl) rule = no-simply
-BasedOnStyles =
 no-simply.no-simply = YES
 
 [docs/legacy/**]
diff --git a/packages/cli/test/fixtures/vale-config/wrong-breadcrumb.ini b/packages/cli/test/fixtures/vale-config/wrong-breadcrumb.ini
index 5278401f..a694733c 100644
--- a/packages/cli/test/fixtures/vale-config/wrong-breadcrumb.ini
+++ b/packages/cli/test/fixtures/vale-config/wrong-breadcrumb.ini
@@ -1,4 +1,3 @@
 [*.md]
 tskl) rule = no-hedging
-BasedOnStyles =
 no-simply.no-simply = YES
diff --git a/packages/cli/test/migrate-drop-based-on-styles.test.ts b/packages/cli/test/migrate-drop-based-on-styles.test.ts
new file mode 100644
index 00000000..c48bc7f0
--- /dev/null
+++ b/packages/cli/test/migrate-drop-based-on-styles.test.ts
@@ -0,0 +1,189 @@
+import {
+  mkdir,
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { ensureTasklessDirectory } from "../src/filesystem/directory";
+import { LATEST_SCHEMA_VERSION } from "../src/filesystem/migrate";
+import migration, {
+  dropBasedOnStyles,
+} from "../src/filesystem/migrations/0008-drop-based-on-styles";
+import { validateValeRuleConfig } from "../src/schemas/vale-config";
+
+/**
+ * Migration 0008 deletes every `BasedOnStyles` line from each Vale rule's
+ * `.vale.ini`.
+ *
+ * `migrate-install.test.ts` proves every prior version reaches the latest
+ * counter and never reads a rule config, so a 0008 that stopped rewriting
+ * would pass there. This file reads the configs, and holds the rewritten
+ * shape to the schema that refuses the old one: the migration exists so an
+ * upgraded project's `check` stays green, which is a claim about the schema,
+ * not about the bytes.
+ */
+describe("migration 0008 drops BasedOnStyles from rule configs", () => {
+  let directory: string;
+  let taskless: string;
+
+  beforeEach(async () => {
+    directory = await mkdtemp(join(tmpdir(), "tskl-0008-"));
+    taskless = join(directory, ".taskless");
+  });
+
+  afterEach(async () => {
+    await rm(directory, { recursive: true, force: true });
+  });
+
+  async function rule(id: string, config: string): Promise<string> {
+    const ruleDirectory = join(taskless, "rules", "vale", id);
+    await mkdir(ruleDirectory, { recursive: true });
+    const path = join(ruleDirectory, ".vale.ini");
+    await writeFile(path, config, "utf8");
+    return path;
+  }
+
+  const THREE_MATCHERS =
+    "# Every markdown file.\n" +
+    "[*.md]\n" +
+    "tskl) rule = no-simply\n" +
+    "BasedOnStyles =\n" +
+    "no-simply.no-simply = YES\n" +
+    "\n" +
+    "[docs/**]\n" +
+    "tskl) rule = no-simply\n" +
+    "  BasedOnStyles = \n" +
+    "no-simply.no-simply = YES\n" +
+    "\n" +
+    "# The changelog quotes release notes verbatim.\n" +
+    "[CHANGELOG.md]\n" +
+    "tskl) rule = no-simply\n" +
+    "BasedOnStyles = Vale\n" +
+    "no-simply.no-simply = NO\n";
+
+  const THREE_MATCHERS_STRIPPED =
+    "# Every markdown file.\n" +
+    "[*.md]\n" +
+    "tskl) rule = no-simply\n" +
+    "no-simply.no-simply = YES\n" +
+    "\n" +
+    "[docs/**]\n" +
+    "tskl) rule = no-simply\n" +
+    "no-simply.no-simply = YES\n" +
+    "\n" +
+    "# The changelog quotes release notes verbatim.\n" +
+    "[CHANGELOG.md]\n" +
+    "tskl) rule = no-simply\n" +
+    "no-simply.no-simply = NO\n";
+
+  it("removes the line from every matcher and leaves every other byte", async () => {
+    const path = await rule("no-simply", THREE_MATCHERS);
+    await migration(taskless);
+    expect(await readFile(path, "utf8")).toBe(THREE_MATCHERS_STRIPPED);
+  });
+
+  it("produces a config the schema accepts, from one it refuses", async () => {
+    // The point of the migration. A rewrite that left the schema unhappy
+    // would turn an upgrade into a red `check` on every project.
+    expect(
+      validateValeRuleConfig("no-simply", THREE_MATCHERS).rejections.map(
+        (rejection) => rejection.constraintId
+      )
+    ).toEqual([
+      "vale-config-no-based-on-styles",
+      "vale-config-no-based-on-styles",
+      "vale-config-no-based-on-styles",
+    ]);
+    const path = await rule("no-simply", THREE_MATCHERS);
+    await migration(taskless);
+    const verdict = validateValeRuleConfig(
+      "no-simply",
+      await readFile(path, "utf8")
+    );
+    expect(verdict.rejections).toEqual([]);
+    expect(verdict.sections).toEqual(["*.md", "docs/**", "CHANGELOG.md"]);
+  });
+
+  it("does not rewrite a config without the line", async () => {
+    const path = await rule(
+      "no-hedging",
+      "[*.md]\ntskl) rule = no-hedging\nno-hedging.no-hedging = YES\n"
+    );
+    const before = await stat(path);
+    await new Promise((resolve) => setTimeout(resolve, 20));
+    await migration(taskless);
+    const after = await stat(path);
+    // Untouched, not merely unchanged: a rewrite of identical bytes would
+    // still show up in a watcher and in `git status` on some filesystems.
+    expect(after.mtimeMs).toBe(before.mtimeMs);
+  });
+
+  it("leaves a comment that mentions BasedOnStyles alone", async () => {
+    const source =
+      "# BasedOnStyles = Vale would load a whole bundled style; never write it.\n" +
+      "; BasedOnStyles is not a per-rule setting either.\n" +
+      "[*.md]\n" +
+      "tskl) rule = no-simply\n" +
+      "BasedOnStyles =\n" +
+      "no-simply.no-simply = YES\n";
+    const path = await rule("no-simply", source);
+    await migration(taskless);
+    expect(await readFile(path, "utf8")).toBe(
+      "# BasedOnStyles = Vale would load a whole bundled style; never write it.\n" +
+        "; BasedOnStyles is not a per-rule setting either.\n" +
+        "[*.md]\n" +
+        "tskl) rule = no-simply\n" +
+        "no-simply.no-simply = YES\n"
+    );
+  });
+
+  it("is idempotent", async () => {
+    const path = await rule("no-simply", THREE_MATCHERS);
+    await migration(taskless);
+    const once = await readFile(path, "utf8");
+    await migration(taskless);
+    expect(await readFile(path, "utf8")).toBe(once);
+  });
+
+  it("keeps CRLF line endings and a line with no trailing newline", () => {
+    expect(
+      dropBasedOnStyles("[*.md]\r\nBasedOnStyles =\r\nr.r = YES\r\n")
+    ).toBe("[*.md]\r\nr.r = YES\r\n");
+    expect(dropBasedOnStyles("[*.md]\nr.r = YES\nBasedOnStyles =")).toBe(
+      "[*.md]\nr.r = YES\n"
+    );
+  });
+
+  it("does nothing on a project with no Vale rules", async () => {
+    await mkdir(taskless, { recursive: true });
+    await expect(migration(taskless)).resolves.toBeUndefined();
+  });
+
+  it("runs on a version-7 scaffold through the runner and records the latest version", async () => {
+    await mkdir(taskless, { recursive: true });
+    await writeFile(
+      join(taskless, "taskless.json"),
+      JSON.stringify({ version: 7, install: {} }),
+      "utf8"
+    );
+    const path = await rule("no-simply", THREE_MATCHERS);
+
+    await ensureTasklessDirectory(directory, { onNotice: () => {} });
+
+    expect(await readFile(path, "utf8")).toBe(THREE_MATCHERS_STRIPPED);
+    const manifest = JSON.parse(
+      await readFile(join(taskless, "taskless.json"), "utf8")
+    ) as { version: number };
+    // Latest rather than 8: the runner applies everything above 7, and a
+    // literal here is what broke the 0007 test when this migration landed.
+    expect(manifest.version).toBe(LATEST_SCHEMA_VERSION);
+    expect(LATEST_SCHEMA_VERSION).toBeGreaterThanOrEqual(8);
+  });
+});
diff --git a/packages/cli/test/migrate-ignore-scratch-files.test.ts b/packages/cli/test/migrate-ignore-scratch-files.test.ts
index 0d5d30e7..748968b4 100644
--- a/packages/cli/test/migrate-ignore-scratch-files.test.ts
+++ b/packages/cli/test/migrate-ignore-scratch-files.test.ts
@@ -35,7 +35,7 @@ describe("migration 0007 ignores scratch request files", () => {
     return content.split("\n").filter(Boolean);
   }
 
-  it("adds the line to a version-6 scaffold and records 7", async () => {
+  it("adds the line to a version-6 scaffold and records the latest version", async () => {
     await mkdir(taskless, { recursive: true });
     await writeFile(
       join(taskless, "taskless.json"),
@@ -60,7 +60,11 @@ describe("migration 0007 ignores scratch request files", () => {
     const manifest = JSON.parse(
       await readFile(join(taskless, "taskless.json"), "utf8")
     ) as { version: number };
-    expect(manifest.version).toBe(7);
+    // The runner applies every migration above 6, so the manifest lands on
+    // whatever is latest, not on 7. Asserting 7 here failed the day 0008
+    // shipped, which is the literal-pinning trap `LATEST_SCHEMA_VERSION`
+    // exists to close.
+    expect(manifest.version).toBe(LATEST_SCHEMA_VERSION);
     expect(LATEST_SCHEMA_VERSION).toBeGreaterThanOrEqual(7);
   });
 
diff --git a/packages/cli/test/mixed-engine-check.test.ts b/packages/cli/test/mixed-engine-check.test.ts
index 6df841dc..be5bbd46 100644
--- a/packages/cli/test/mixed-engine-check.test.ts
+++ b/packages/cli/test/mixed-engine-check.test.ts
@@ -269,7 +269,7 @@ describe("check over a project with both engines", () => {
         );
         await writeFile(
           join(ruleDirectory, ".vale.ini"),
-          "[*.md]\ntskl) rule = no-simply\nBasedOnStyles =\nno-simply.no-simply = YES\n"
+          "[*.md]\ntskl) rule = no-simply\nno-simply.no-simply = YES\n"
         );
         await writeFile(join(scaffold, "doc.md"), "Just simply do it.\n");
 
@@ -305,7 +305,7 @@ describe("check over a project with both engines", () => {
       // checks `verify` used to run passed this; the schema does not.
       await writeFile(
         join(rule, ".vale.ini"),
-        "no-simply.no-simply = YES\n[*.md]\ntskl) rule = no-simply\nBasedOnStyles =\n"
+        "no-simply.no-simply = YES\n[*.md]\ntskl) rule = no-simply\n"
       );
 
       const verified = await runCli(["verify", "-d", project, "--json"]);
@@ -357,7 +357,7 @@ describe("check over a project with both engines", () => {
       const rule = join(project, ".taskless", "rules", "vale", "no-simply");
       await writeFile(
         join(rule, ".vale.ini"),
-        "[*.md]\ntskl) rule = no-simply\nBasedOnStyles =\nno-simply.no-simply = YES\nno-obviously.no-obviously = NO\n"
+        "[*.md]\ntskl) rule = no-simply\nno-simply.no-simply = YES\nno-obviously.no-obviously = NO\n"
       );
 
       const { stdout, exitCode } = await runCli([
@@ -373,7 +373,7 @@ describe("check over a project with both engines", () => {
       expect(exitCode).toBe(1);
       expect(output.failures).toHaveLength(1);
       expect(output.failures?.[0]).toContain("the config of no-simply was");
-      expect(output.failures?.[0]).toContain("no-simply/.vale.ini line 5:");
+      expect(output.failures?.[0]).toContain("no-simply/.vale.ini line 4:");
       expect(output.failures?.[0]).toContain("no-obviously.no-obviously");
       expect(output.failures?.[0]).not.toContain("config of no-obviously");
 
@@ -388,7 +388,7 @@ describe("check over a project with both engines", () => {
       const rule = join(project, ".taskless", "rules", "vale", "no-simply");
       await writeFile(
         join(rule, ".vale.ini"),
-        "[*.md]\ntskl) rule = no-simply\nBasedOnStyles =\nno-simply.no-simply = YES\n\n[.taskless/**]\ntskl) rule = no-simply\nno-simply.no-simply = NO\n"
+        "[*.md]\ntskl) rule = no-simply\nno-simply.no-simply = YES\n\n[.taskless/**]\ntskl) rule = no-simply\nno-simply.no-simply = NO\n"
       );
 
       const { stdout } = await runCli(["check", "-d", project, "--json"]);
@@ -424,7 +424,7 @@ describe("check over a project with both engines", () => {
         );
         await writeFile(
           join(rule, ".vale.ini"),
-          "[*.md]\ntskl) rule = no-simply\nBasedOnStyles =\nno-simply.no-simply = YES\n"
+          "[*.md]\ntskl) rule = no-simply\nno-simply.no-simply = YES\n"
         );
 
         const blog = join(scaffold, "content", "blog");
diff --git a/packages/cli/test/vale-config-schema.test.ts b/packages/cli/test/vale-config-schema.test.ts
index b2a02950..f2c90a49 100644
--- a/packages/cli/test/vale-config-schema.test.ts
+++ b/packages/cli/test/vale-config-schema.test.ts
@@ -13,9 +13,10 @@ import {
  * The config schema, over an ini fixture set.
  *
  * One fixture per rejection and per advisory, plus the dogfood shape the
- * schema was written against: three matchers carrying the breadcrumb, an empty
- * `BasedOnStyles`, `<id>.<id> = YES`, and the trailing `.taskless/**` block
- * that `check` never needs. Every message is asserted on its text as well as
+ * schema was written against: three matchers carrying the breadcrumb and
+ * `<id>.<id> = YES`, and the trailing `.taskless/**` block that `check` never
+ * needs. The `BasedOnStyles =` those matchers used to carry is now its own
+ * rejection fixture. Every message is asserted on its text as well as
  * its constraint id, so a fixture refused for some unrelated reason fails here
  * rather than passing quietly.
  *
@@ -98,7 +99,7 @@ describe("parseValeRuleConfig", () => {
       ast.sections[0]?.nodes.map((node) =>
         node.kind === "property" ? node.key : node.text
       )
-    ).toEqual(["tskl) rule", "BasedOnStyles", "no-simply.no-simply"]);
+    ).toEqual(["tskl) rule", "no-simply.no-simply"]);
   });
 
   it("attaches the source line to every header and property", () => {
@@ -109,10 +110,10 @@ describe("parseValeRuleConfig", () => {
     ]);
     expect(lines).toEqual([
       [undefined, [1, 2]],
-      [3, [4, 5, 6]],
-      [8, [9, 10]],
-      [12, [13, 14, 15]],
-      [17, [18, 19]],
+      [3, [4, 5]],
+      [7, [8, 9]],
+      [11, [12, 13]],
+      [15, [16, 17]],
     ]);
   });
 
@@ -127,7 +128,7 @@ describe("validateValeRuleConfig accepts", () => {
     expect(result.rejections).toEqual([]);
     expect(result.advisories).toHaveLength(1);
     expect(result.advisories[0]).toMatch(
-      /line 17: matcher \[\.taskless\/\*\*\]/
+      /line 15: matcher \[\.taskless\/\*\*\]/
     );
     expect(result.sections).toEqual([
       "*.md",
@@ -201,7 +202,7 @@ describe("validateValeRuleConfig rejects", () => {
     const result = verdict("foreign-key");
     expect(ids(result)).toEqual(["vale-config-own-key-only"]);
     expect(result.rejections[0]?.message).toBe(
-      'no-simply/.vale.ini line 5: matcher [*.md] assigns "no-hedging.no-hedging", which names another rule. ' +
+      'no-simply/.vale.ini line 4: matcher [*.md] assigns "no-hedging.no-hedging", which names another rule. ' +
         "A rule's config may only enable or disable itself, as no-simply.no-simply; anything else is a cross-rule override."
     );
   });
@@ -210,8 +211,8 @@ describe("validateValeRuleConfig rejects", () => {
     const result = verdict("stray-key");
     expect(ids(result)).toEqual(["vale-config-own-key-only"]);
     expect(result.rejections[0]?.message).toBe(
-      'no-simply/.vale.ini line 4: matcher [*.md] assigns "MinAlertLevel", which is not a per-rule setting. ' +
-        'Inside a matcher a rule\'s config carries only "tskl) rule", an empty BasedOnStyles, and no-simply.no-simply.'
+      'no-simply/.vale.ini line 3: matcher [*.md] assigns "MinAlertLevel", which is not a per-rule setting. ' +
+        'Inside a matcher a rule\'s config carries only "tskl) rule" and no-simply.no-simply.'
     );
   });
 
@@ -224,16 +225,52 @@ describe("validateValeRuleConfig rejects", () => {
       "vale-config-enabled-somewhere",
     ]);
     expect(result.rejections[0]?.message).toMatch(
-      /^no-simply\/\.vale\.ini line 4: no-simply\.no-simply = "yes" is not YES or NO\. Vale [\d.]+ reads a level name here/
+      /^no-simply\/\.vale\.ini line 3: no-simply\.no-simply = "yes" is not YES or NO\. Vale [\d.]+ reads a level name here/
     );
   });
 
-  it("a non-empty BasedOnStyles", () => {
+  it("an empty BasedOnStyles", () => {
+    // Rejected since Vale 3.22.0, where it was inert before. Measured on
+    // that binary: an empty `BasedOnStyles` in a later matcher clears every
+    // setting the file inherited from an earlier one, and the assembled run
+    // config is every rule's matchers in id order, so the line silences the
+    // other rules under whatever the matcher reaches. Only a byte-identical
+    // glob, which Vale merges into one section, escapes. Pinned in
+    // `vale-vendor-contract.test.ts`; migration 0008 deletes the line.
     const result = verdict("based-on-styles");
-    expect(ids(result)).toEqual(["vale-config-based-on-styles-empty"]);
+    expect(ids(result)).toEqual(["vale-config-no-based-on-styles"]);
+    expect(result.rejections[0]?.message).toBe(
+      "no-simply/.vale.ini line 3: matcher [*.md] sets BasedOnStyles to empty. " +
+        `On Vale ${VALE_VERSION} an empty BasedOnStyles clears every earlier matcher's settings for a file this one reaches, ` +
+        "which silences the other rules whose globs overlap. Delete the line: no bundled style loads unless a run-level BasedOnStyles names one."
+    );
+  });
+
+  it("a [formats] section, as a matcher it cannot be", () => {
+    // Vale 3.22.0 lets a `[formats]` key be a file name or a glob, which
+    // moves a file between parser tiers. The schema has no notion of the
+    // section: it is a matcher named `formats` with no breadcrumb and a
+    // foreign key, so it is refused on both counts and the tier table's
+    // extension-decides-the-parser claim stays true of every assembled run.
+    const result = validateValeRuleConfig(
+      RULE,
+      "[formats]\nNOTES = md\n\n[*.md]\ntskl) rule = no-simply\nno-simply.no-simply = YES\n"
+    );
+    expect(ids(result)).toEqual([
+      "vale-config-breadcrumb-required",
+      "vale-config-own-key-only",
+    ]);
+    expect(result.rejections[1]?.message).toMatch(
+      /line 2: matcher \[formats\] assigns "NOTES", which is not a per-rule setting/
+    );
+  });
+
+  it("a BasedOnStyles naming a style", () => {
+    const result = verdict("based-on-styles-named");
+    expect(ids(result)).toEqual(["vale-config-no-based-on-styles"]);
     expect(result.rejections[0]?.message).toBe(
       'no-simply/.vale.ini line 3: matcher [*.md] sets BasedOnStyles = "Vale". ' +
-        "It must be empty: a bundled style loaded here fires alongside no-simply and reaches every rule whose matchers overlap."
+        "A bundled style loaded here fires alongside no-simply and reaches every rule whose matchers overlap. Delete the line: a rule enables itself by name."
     );
   });
 
@@ -280,7 +317,7 @@ describe("validateValeRuleConfig rejects", () => {
     const result = validateValeRuleConfig(
       RULE,
       "[docs/legacy/**]\ntskl) rule = no-simply\nno-simply.no-simply = YES\nno-simply.no-simply = NO\n\n" +
-        "[docs/**]\ntskl) rule = no-simply\nBasedOnStyles =\nno-simply.no-simply = YES\n"
+        "[docs/**]\ntskl) rule = no-simply\nno-simply.no-simply = YES\n"
     );
     expect(ids(result)).toEqual(["vale-config-disable-after-enable"]);
     expect(result.rejections[0]?.message).toMatch(
@@ -315,7 +352,7 @@ describe("validateValeRuleConfig advises, without rejecting", () => {
     const result = verdict("repeat-key-still-enabled");
     expect(result.rejections).toEqual([]);
     expect(result.advisories).toEqual([
-      "no-simply/.vale.ini line 9: matcher [*.md] assigns no-simply.no-simply again (first line 8). " +
+      "no-simply/.vale.ini line 8: matcher [*.md] assigns no-simply.no-simply again (first line 7). " +
         `Vale ${VALE_VERSION} keeps the last assignment, "NO"; through 3.20.0 it kept the first.`,
     ]);
   });
@@ -326,7 +363,7 @@ describe("validateValeRuleConfig advises, without rejecting", () => {
     expect(result.rejections).toEqual([]);
     expect(result.advisories).toHaveLength(1);
     expect(result.advisories[0]).toMatch(
-      /line 12: matcher \[\*\.md\] assigns no-simply\.no-simply again \(first line 8\)/
+      /line 11: matcher \[\*\.md\] assigns no-simply\.no-simply again \(first line 7\)/
     );
     // Every header is still reported as a section: the AST is the file's.
     expect(result.sections).toEqual(["docs/**", "*.md", "*.md"]);
@@ -345,7 +382,7 @@ describe("validateValeRuleConfig advises, without rejecting", () => {
     const result = verdict("taskless-tree");
     expect(result.rejections).toEqual([]);
     expect(result.advisories).toEqual([
-      "no-simply/.vale.ini line 6: matcher [.taskless/**] is unnecessary: check excludes .taskless/ before Vale runs, " +
+      "no-simply/.vale.ini line 5: matcher [.taskless/**] is unnecessary: check excludes .taskless/ before Vale runs, " +
         "so it acts only under a bare vale invocation.",
     ]);
   });
diff --git a/packages/cli/test/vale-formats.test.ts b/packages/cli/test/vale-formats.test.ts
index ad098f95..e9b5805e 100644
--- a/packages/cli/test/vale-formats.test.ts
+++ b/packages/cli/test/vale-formats.test.ts
@@ -62,7 +62,7 @@ function makeProject(documents: Record<string, string>): string {
   );
   writeFileSync(
     join(cwd, ".taskless", ".vale.ini"),
-    "StylesPath = rules/vale\nMinAlertLevel = suggestion\n\n[*]\nBasedOnStyles =\nno-simply.no-simply = YES\n"
+    "StylesPath = rules/vale\nMinAlertLevel = suggestion\n\n[*]\nno-simply.no-simply = YES\n"
   );
   for (const [path, body] of Object.entries(documents)) {
     const full = join(cwd, path);
diff --git a/packages/cli/test/vale-orchestration.test.ts b/packages/cli/test/vale-orchestration.test.ts
index 8efca0a4..84aadfd0 100644
--- a/packages/cli/test/vale-orchestration.test.ts
+++ b/packages/cli/test/vale-orchestration.test.ts
@@ -83,7 +83,7 @@ function makeMixedProject(options?: {
   if (valeRules && valeConfig) {
     writeFileSync(
       join(cwd, ".taskless", "rules", "vale", "no-simply", ".vale.ini"),
-      "[*.md]\ntskl) rule = no-simply\nBasedOnStyles =\nno-simply.no-simply = YES\n"
+      "[*.md]\ntskl) rule = no-simply\nno-simply.no-simply = YES\n"
     );
   }
 
@@ -420,7 +420,7 @@ describe("config advisories ride on every Vale outcome", () => {
   // Vale is mocked because the shape under test is dispatch's merge, not the
   // binary; each case drives one branch of `runValeEngine`.
   const ADVISED_CONFIG =
-    "[*.md]\ntskl) rule = no-simply\nBasedOnStyles =\nno-simply.no-simply = YES\n\n" +
+    "[*.md]\ntskl) rule = no-simply\nno-simply.no-simply = YES\n\n" +
     "[.taskless/**]\ntskl) rule = no-simply\nno-simply.no-simply = NO\n";
 
   async function dispatchWithAdvisory(
@@ -539,7 +539,7 @@ withVale("a repository containing a converter-dependent file", () => {
     // while every matcher is Markdown-only.
     writeFileSync(
       join(cwd, ".taskless", "rules", "vale", "no-simply", ".vale.ini"),
-      "[*]\ntskl) rule = no-simply\nBasedOnStyles =\nno-simply.no-simply = YES\n"
+      "[*]\ntskl) rule = no-simply\nno-simply.no-simply = YES\n"
     );
     writeFileSync(join(cwd, "guide.adoc"), "= Guide\n\nJust simply do it.\n");
     mkdirSync(join(cwd, "docs"), { recursive: true });
diff --git a/packages/cli/test/vale-schema-contract.test.ts b/packages/cli/test/vale-schema-contract.test.ts
index 3347cb25..5e0e2908 100644
--- a/packages/cli/test/vale-schema-contract.test.ts
+++ b/packages/cli/test/vale-schema-contract.test.ts
@@ -57,7 +57,7 @@ const RULE_ID = "corpus";
  * **This is the third copy of the isolating-config recipe**, alongside
  * `probe()` in `scripts/generate-vale-schema.ts` and `buildIsolatingConfig` in
  * `src/rules/vale/verify.ts`, whose docstrings cross-reference each other. All
- * three agree on `MinAlertLevel = suggestion`, an empty `BasedOnStyles =`, and
+ * three agree on `MinAlertLevel = suggestion`, no `BasedOnStyles` line, and
  * exactly one assignment of the enabled key in exactly one matcher. This copy
  * differs from `buildIsolatingConfig` the same way `probe()` does: it owns its
  * whole temp directory, so it has no absolute `StylesPath` to hand over, and
@@ -78,9 +78,10 @@ function runOne(rule: string, control: string, extension: string): ValeVerdict {
     writeFileSync(join(cwd, "styles", RULE_ID, `${RULE_ID}.yml`), rule);
     writeFileSync(
       join(cwd, ".vale.ini"),
-      // `BasedOnStyles =` is load-bearing: without it a control could trip a
-      // bundled style and be read as the rule under test firing.
-      `StylesPath = styles\nMinAlertLevel = suggestion\n\n[*]\nBasedOnStyles =\n${RULE_ID}.${RULE_ID} = YES\n`
+      // No `BasedOnStyles` line. Measured on 3.21.0 and 3.22.0: no bundled
+      // style fires without one, so a control cannot be read as the rule
+      // under test firing. `probe()` in the generator has the measurement.
+      `StylesPath = styles\nMinAlertLevel = suggestion\n\n[*]\n${RULE_ID}.${RULE_ID} = YES\n`
     );
     writeFileSync(join(cwd, `doc.${extension}`), control);
 
diff --git a/packages/cli/test/vale-verify.test.ts b/packages/cli/test/vale-verify.test.ts
index f49245cd..744ba17f 100644
--- a/packages/cli/test/vale-verify.test.ts
+++ b/packages/cli/test/vale-verify.test.ts
@@ -123,10 +123,14 @@ describe("buildIsolatingConfig", () => {
     expect(config).toContain("StylesPath = /proj/.taskless/rules/vale");
   });
 
-  it("loads no bundled styles", () => {
-    // Without this a fixture could trip Vale.Spelling and be counted as the
-    // rule under test firing.
-    expect(buildIsolatingConfig("/proj", "r")).toContain("BasedOnStyles =");
+  it("names no style, and writes no BasedOnStyles line", () => {
+    // Measured on Vale 3.21.0 and 3.22.0: a bundled style loads only when a
+    // run-level `BasedOnStyles` names one, so a fixture cannot trip
+    // `Vale.Spelling` here. The config used to write `BasedOnStyles =` on the
+    // opposite belief; since 3.22.0 an empty value clears a file's inherited
+    // settings, and the schema refuses it in a rule's own config, so the
+    // isolating config no longer writes the shape it refuses.
+    expect(buildIsolatingConfig("/proj", "r")).not.toContain("BasedOnStyles");
   });
 });
 
diff --git a/packages/cli/test/verify-test-commands.test.ts b/packages/cli/test/verify-test-commands.test.ts
index 9ace0a7f..c86888df 100644
--- a/packages/cli/test/verify-test-commands.test.ts
+++ b/packages/cli/test/verify-test-commands.test.ts
@@ -89,7 +89,7 @@ async function sgRule(directoryName: string, declaredId: string) {
   );
 }
 
-const SCOPED = `[*.md]\ntskl) rule = no-simply\nBasedOnStyles =\nno-simply.no-simply = YES\n`;
+const SCOPED = `[*.md]\ntskl) rule = no-simply\nno-simply.no-simply = YES\n`;
 
 describe("verify addresses rules by path", () => {
   it("resolves the engine from the path, not the file", async () => {
@@ -171,7 +171,7 @@ describe("verify checks components without requiring tests", () => {
 
   it("fails a Vale rule whose config never enables it", async () => {
     await valeRule("no-simply", {
-      config: "[*.md]\ntskl) rule = no-simply\nBasedOnStyles =\n",
+      config: "[*.md]\ntskl) rule = no-simply\n",
     });
     const result = await runCli(["verify", "-d", cwd, "--json"]);
     expect(result.exitCode).not.toBe(0);
@@ -196,7 +196,7 @@ describe("verify checks components without requiring tests", () => {
     expect(rule?.violations).toHaveLength(1);
     expect(rule?.violations[0]?.constraintId).toBe("vale-config-own-key-only");
     expect(rule?.violations[0]?.message).toMatch(
-      /line 5: matcher \[\*\.md\] assigns "no-hedging\.no-hedging", which names another rule/
+      /line 4: matcher \[\*\.md\] assigns "no-hedging\.no-hedging", which names another rule/
     );
     // Repeated verbatim in `errors`, so a consumer reading only that sees it.
     expect(rule?.errors).toContain(rule?.violations[0]?.message);
@@ -207,7 +207,7 @@ describe("verify checks components without requiring tests", () => {
     // the rule enabled somewhere, so the config is accepted with a notice.
     await valeRule("no-simply", {
       config:
-        "[docs/**]\ntskl) rule = no-simply\nBasedOnStyles =\nno-simply.no-simply = YES\n\n" +
+        "[docs/**]\ntskl) rule = no-simply\nno-simply.no-simply = YES\n\n" +
         `${SCOPED}no-simply.no-simply = NO\n`,
     });
     const result = await runCli(["verify", "-d", cwd, "--json"]);
@@ -416,7 +416,7 @@ withVale("verify schema-checks a Vale rule", () => {
     for (const [id, style] of Object.entries(recipeRules)) {
       await valeRule(id, {
         style,
-        config: `[*.md]\ntskl) rule = ${id}\nBasedOnStyles =\n${id}.${id} = YES\n`,
+        config: `[*.md]\ntskl) rule = ${id}\n${id}.${id} = YES\n`,
       });
     }
 

From a094a7767ffb9c85e386a352c47bddb89acf4713 Mon Sep 17 00:00:00 2001
From: Jakob Heuser <jakob@codedrift.com>
Date: Mon, 21 Sep 2026 16:06:07 -0700
Subject: [PATCH 3/5] test(vale): pin the 3.22.0 contract on the assembled
 layout

A Vale 3.22.0 block in the vendor contract, every case run against
3.21.0 as well with that answer in the comment: the BasedOnStyles table
(identical globs survive, any other overlap silences the earlier rule,
id order decides, a NO matcher carrying the key reaches every rule),
UNSET as a rule value and at the style level, that no bundled style
loads without the key, negated inline scopes blanking the element's text
with positions held, the release note's dotted spellings being inert,
[formats] by file name and glob against a fenced-block discriminator,
front-matter placement reporting every occurrence in a field, a rule
file's message and description being its only prose, a one-line MDX
element, and split: true.

Corpus rows for ~link and ~strong & ~emphasis (accepted; the control
proves the paragraph is still reached) and for text.raw and
paragraph.link (ignored, as the dotted forms the release note uses).
The timeout fixtures re-timed on 3.22.0 land within noise of 3.21.0.
---
 packages/cli/test/vale-corpus.ts              |  35 ++
 packages/cli/test/vale-run.test.ts            |   6 +-
 .../cli/test/vale-vendor-contract.test.ts     | 463 ++++++++++++++++++
 3 files changed, 502 insertions(+), 2 deletions(-)

diff --git a/packages/cli/test/vale-corpus.ts b/packages/cli/test/vale-corpus.ts
index e72082c4..b2fe65e6 100644
--- a/packages/cli/test/vale-corpus.ts
+++ b/packages/cli/test/vale-corpus.ts
@@ -361,6 +361,24 @@ const SCOPES: ValeCorpusEntry[] = [
   // every one of these, which is worse than the gap the schema closes.
   { name: "scope/negation", scope: "~code", control: MIXED },
   { name: "scope/chain", scope: "text & ~code", control: MIXED },
+  // A negated INLINE element, which Vale 3.22.0 gave a second meaning: the
+  // rule still runs on the paragraph, and the element's text is blanked out
+  // of it. `link`, `strong` and `emphasis` are the operands that changed
+  // (`code` too, but inline code was never in prose text to begin with). The
+  // grammar accepted every one of these before, so nothing here is new to
+  // the schema; the rows exist so the control, which carries prose OUTSIDE
+  // the element, keeps proving the rule reaches the paragraph at all.
+  // `vale-vendor-contract.test.ts` pins what the negation subtracts.
+  {
+    name: "scope/negated-link",
+    scope: "~link",
+    control: "Prose simply here, see [the link](https://example.com).\n",
+  },
+  {
+    name: "scope/negated-strong-and-emphasis",
+    scope: "~strong & ~emphasis",
+    control: "Prose simply here, **bold** and *italic*.\n",
+  },
   // `doc(<selector>)`, new in Vale 3.21.0: elements of the document by CSS
   // selector, where a heading and everything under it is a `section`. Four
   // shapes, because they behave differently and the schema accepts all four:
@@ -433,6 +451,23 @@ const INVALID_SCOPES: ValeCorpusEntry[] = [
   // term as a dotted operand it does not have, and the rule is inert. The
   // schema rejects it for the same reason it rejects `fenced`.
   { name: "scope/doc-unclosed", scope: "doc(h1", control: HEADINGS },
+  // The 3.22.0 release note describes inline negation as "`text.raw`,
+  // `paragraph.link`, and so on". Measured on that binary, neither dotted
+  // spelling is an operand: bare, the rule is inert; negated, it subtracts
+  // nothing. The operands that negate an inline element are the bare
+  // `link`, `strong`, `emphasis` and `code`, above. The schema keeps
+  // rejecting the dotted forms, which is what an author who copied the
+  // release note needs to hear.
+  {
+    name: "scope/text.raw",
+    scope: "text.raw",
+    control: "Prose simply here.\n\n```\nsimply fenced\n```\n",
+  },
+  {
+    name: "scope/paragraph.link",
+    scope: "paragraph.link",
+    control: "See [simply link](https://example.com).\n",
+  },
 ].map(({ name, scope, control }) => ({
   name,
   construct: `scope: ${scope}`,
diff --git a/packages/cli/test/vale-run.test.ts b/packages/cli/test/vale-run.test.ts
index b510aba1..1bfe82dd 100644
--- a/packages/cli/test/vale-run.test.ts
+++ b/packages/cli/test/vale-run.test.ts
@@ -237,7 +237,7 @@ withVale("runVale against the real binary", () => {
     // the notice path has to stay pinned for the diagnostics the schema cannot
     // foresee, and W101 is the one Vale is known to emit on a zero exit.
     const cwd = makeProject(
-      `${header}rules.no-simply = YES\n\n[*.md]\nBasedOnStyles =\n`,
+      `${header}rules.no-simply = YES\n\n[*.md]\n`,
       { "no-simply": existenceRule("simply", "Avoid 'simply'") },
       { "doc.md": "Just simply do it.\n" }
     );
@@ -317,7 +317,9 @@ withVale("runVale against the real binary", () => {
     //
     // 350,000 restores the ~900ms headroom the 8,000 fixture had on 3.20.0.
     // The cost scales linearly (~2.8µs per repetition), so the next bump can
-    // pick a number from one timing rather than a search. It is chosen over
+    // pick a number from one timing rather than a search. Re-measured on
+    // 3.22.0 the same way: 80,000 at ~240ms, 350,000 at ~980ms, 1,000,000
+    // at ~2,970ms, within noise of 3.21.0, so the fixture stands. It is chosen over
     // the sibling's 1,000,000 for the same reason 8,000 was chosen over
     // 17,000: this test asserts the message rather than the blocking flag,
     // which the sibling covers with the larger fixture.
diff --git a/packages/cli/test/vale-vendor-contract.test.ts b/packages/cli/test/vale-vendor-contract.test.ts
index b72f6b94..d7428d29 100644
--- a/packages/cli/test/vale-vendor-contract.test.ts
+++ b/packages/cli/test/vale-vendor-contract.test.ts
@@ -164,6 +164,70 @@ const hedge = (scope: string) =>
 const budget = (scope: string) =>
   `extends: metric\nmessage: "%s words"\nlevel: error\nscope: '${scope}'\nformula: words\ncondition: "> 8"\n`;
 
+/**
+ * Two rules on the assembled layout, `a-rule` then `b-rule`, in id order
+ * as `assembleValeConfig` emits them, each matcher carrying the
+ * breadcrumb and whatever `extra` lines the case puts beside it. The
+ * config is written where the assembler writes it (`.taskless/.vale.ini`,
+ * `StylesPath = rules/vale`), so a rule at `rules/vale/<id>/<id>.yml`
+ * resolves as `<id>.<id>` exactly as it does under `check`.
+ */
+function assembled(
+  sections: string
+): Record<"doc.md" | "docs/inner.md" | "doc.markdown", string[]> {
+  const cwd = mkdtempSync(join(tmpdir(), "vale-contract-"));
+  workspaces.push(cwd);
+  for (const id of ["a-rule", "b-rule"]) {
+    mkdirSync(join(cwd, ".taskless", "rules", "vale", id), {
+      recursive: true,
+    });
+    writeFileSync(
+      join(cwd, ".taskless", "rules", "vale", id, `${id}.yml`),
+      existence(id === "a-rule" ? "alpha" : "bravo")
+    );
+  }
+  writeFileSync(
+    join(cwd, ".taskless", ".vale.ini"),
+    `StylesPath = rules/vale\nMinAlertLevel = suggestion\n\n${sections}`
+  );
+  mkdirSync(join(cwd, "docs"));
+  const body = "Just alpha and bravo here.\n";
+  const names = ["doc.md", "docs/inner.md", "doc.markdown"] as const;
+  for (const name of names) writeFileSync(join(cwd, name), body);
+  const result = spawnSync(
+    binary as string,
+    [
+      "--config",
+      ".taskless/.vale.ini",
+      "--output=JSON",
+      "--no-exit",
+      "--",
+      ...names,
+    ],
+    { cwd, encoding: "utf8" }
+  );
+  expect(result.status, result.stderr).toBe(0);
+  const parsed = JSON.parse(result.stdout || "{}") as Record<
+    string,
+    Array<{ Check: string }>
+  >;
+  return {
+    "doc.md": (parsed["doc.md"] ?? []).map((finding) => finding.Check),
+    "docs/inner.md": (parsed["docs/inner.md"] ?? []).map(
+      (finding) => finding.Check
+    ),
+    "doc.markdown": (parsed["doc.markdown"] ?? []).map(
+      (finding) => finding.Check
+    ),
+  };
+}
+const matcher = (glob: string, id: string, ...extra: string[]) =>
+  [`[${glob}]`, `tskl) rule = ${id}`, ...extra, `${id}.${id} = YES`, ""].join(
+    "\n"
+  );
+const A = "a-rule.a-rule";
+const B = "b-rule.b-rule";
+
 withVale("Vale vendor contract", () => {
   it("reports its own name in --version", () => {
     // Depended on by: PlatformBinarySpec.identity (/vale/i). If Vale stops
@@ -841,6 +905,405 @@ withVale("Vale vendor contract", () => {
       });
     });
   });
+
+  /**
+   * What 3.22.0 changed under a rule this CLI assembles, and what it added.
+   *
+   * The first group is the one that moved the config schema: every case is
+   * measured against the exact shape `assembleValeConfig` writes, because the
+   * question is not "what does Vale do with `BasedOnStyles`" but "what does
+   * Vale do with the file this CLI hands it". Every case here was run against
+   * the 3.21.0 binary as well, and the comments record what that one said.
+   */
+  describe("Vale 3.22.0", () => {
+    describe("an empty BasedOnStyles clears what a file inherited from earlier matchers", () => {
+      // Depended on by: `vale-config-no-based-on-styles` in
+      // `src/schemas/vale-config.ts`, migration 0008, and the recipe's
+      // `.vale.ini` template, which through 3.21.0 told every author to
+      // write `BasedOnStyles =` in every matcher. Upstream c2d62437, "let an
+      // empty BasedOnStyles reset a file's inherited rule settings". The
+      // word doing the damage is INHERITED: it is not only bundled styles
+      // that are cleared but every `<id>.<id> = YES` an earlier matcher set
+      // for the file, and the assembled config is every rule's matchers in
+      // id order. Measured on 3.21.0, every case in this group fired both
+      // rules on every file both globs reach.
+
+      it("spares two rules whose globs are byte-identical, which Vale merges", () => {
+        // The shape the recipe's template produces when every rule uses
+        // `[*.md]`, and the reason this repository's own five rules did not
+        // notice: duplicate section headers fold into one section, so there
+        // is no earlier section to inherit from.
+        const findings = assembled(
+          matcher("*.md", "a-rule", "BasedOnStyles =") +
+            "\n" +
+            matcher("*.md", "b-rule", "BasedOnStyles =")
+        );
+        expect(findings["doc.md"]).toEqual([A, B]);
+        expect(findings["docs/inner.md"]).toEqual([A, B]);
+      });
+
+      it("silences the earlier rule wherever a later, different glob also matches", () => {
+        // `[*.md]` and `[*.{md,markdown}]` reach the same `.md` files and
+        // are not the same section, so b-rule's `BasedOnStyles =` clears
+        // a-rule's enable on every one of them. 3.21.0: both fire on doc.md.
+        const findings = assembled(
+          matcher("*.md", "a-rule", "BasedOnStyles =") +
+            "\n" +
+            matcher("*.{md,markdown}", "b-rule", "BasedOnStyles =")
+        );
+        expect(findings["doc.md"]).toEqual([B]);
+        expect(findings["docs/inner.md"]).toEqual([B]);
+        expect(findings["doc.markdown"]).toEqual([B]);
+      });
+
+      it("silences the earlier rule under a narrower later glob", () => {
+        // 3.21.0: docs/inner.md reported both.
+        const findings = assembled(
+          matcher("*.md", "a-rule", "BasedOnStyles =") +
+            "\n" +
+            matcher("docs/**", "b-rule", "BasedOnStyles =")
+        );
+        expect(findings["doc.md"]).toEqual([A]);
+        expect(findings["docs/inner.md"]).toEqual([B]);
+      });
+
+      it("is decided by position, so id order decides which rule survives", () => {
+        // The same two matchers with the ids swapped: now `[docs/**]` comes
+        // first and `[*.md]` clears IT under docs/. Which rule a project
+        // loses depends on how its rule ids sort, which is the property
+        // that made this a schema rejection rather than a documented trap.
+        // 3.21.0: docs/inner.md reported both.
+        const findings = assembled(
+          matcher("docs/**", "a-rule", "BasedOnStyles =") +
+            "\n" +
+            matcher("*.md", "b-rule", "BasedOnStyles =")
+        );
+        expect(findings["doc.md"]).toEqual([B]);
+        expect(findings["docs/inner.md"]).toEqual([B]);
+      });
+
+      it("does nothing when neither rule writes the key", () => {
+        // What migration 0008 leaves behind, and what the schema now
+        // requires. Same answer on 3.21.0.
+        const findings = assembled(
+          matcher("*.md", "a-rule") + "\n" + matcher("docs/**", "b-rule")
+        );
+        expect(findings["doc.md"]).toEqual([A]);
+        expect(findings["docs/inner.md"]).toEqual([A, B]);
+      });
+
+      it("turns a rule off under its own later matcher that carries only the key", () => {
+        // A single rule's second matcher with `BasedOnStyles =` and no
+        // assignment at all: the rule is off under docs/. 3.21.0: on.
+        const findings = assembled(
+          matcher("*.md", "a-rule", "BasedOnStyles =") +
+            "\n[docs/**]\ntskl) rule = a-rule\nBasedOnStyles =\n"
+        );
+        expect(findings["doc.md"]).toEqual([A]);
+        expect(findings["docs/inner.md"]).toEqual([]);
+      });
+
+      it("reaches every rule when a NO matcher carries the key", () => {
+        // The recipe's exclusion shape with the key copied into the NO
+        // block: a-rule's `[docs/**] NO` also silences b-rule under docs/.
+        // Without the key, the same config reports b-rule there, on both
+        // binaries.
+        const withKey = assembled(
+          matcher("*.md", "a-rule", "BasedOnStyles =") +
+            "\n" +
+            matcher("*.md", "b-rule", "BasedOnStyles =") +
+            "\n[docs/**]\ntskl) rule = a-rule\nBasedOnStyles =\na-rule.a-rule = NO\n"
+        );
+        expect(withKey["docs/inner.md"]).toEqual([]);
+        const without = assembled(
+          matcher("*.md", "a-rule") +
+            "\n" +
+            matcher("*.md", "b-rule") +
+            "\n[docs/**]\ntskl) rule = a-rule\na-rule.a-rule = NO\n"
+        );
+        expect(without["docs/inner.md"]).toEqual([B]);
+      });
+    });
+
+    describe("UNSET", () => {
+      // The same upstream commit's second half. Recorded because the schema
+      // accepts only YES and NO as a value, and an author reading the release
+      // notes will ask whether UNSET should be a third. Measured: as a
+      // rule's value it behaves as NO on both binaries (3.21.0 reads any
+      // value that is not YES as off), and at the STYLE level, the shape
+      // the release note describes, it does not reach a rule this CLI
+      // enabled by name. Nothing here is a reason to accept it.
+
+      it("as a rule's value turns the rule off, like NO", () => {
+        const findings = assembled(
+          matcher("*.md", "a-rule") +
+            "\n" +
+            matcher("*.md", "b-rule") +
+            "\n[docs/**]\na-rule.a-rule = UNSET\n"
+        );
+        expect(findings["doc.md"]).toEqual([A, B]);
+        expect(findings["docs/inner.md"]).toEqual([B]);
+      });
+
+      it("at the style level leaves a rule enabled by name alone", () => {
+        const findings = assembled(
+          matcher("*.md", "a-rule") +
+            "\n" +
+            matcher("*.md", "b-rule") +
+            "\n[docs/**]\na-rule = UNSET\n"
+        );
+        expect(findings["docs/inner.md"]).toEqual([A, B]);
+      });
+    });
+
+    it("loads no bundled style when no BasedOnStyles is written anywhere", () => {
+      // Depended on by: `buildIsolatingConfig`, the generator's `probe()`
+      // and `runOne` in `vale-schema-contract.test.ts`, which wrote
+      // `BasedOnStyles =` on the belief that its absence let `Vale.Spelling`
+      // fire on a fixture. It never did; measured the same on 3.21.0. The
+      // control proves the bait works: naming the style fires all of it.
+      const bait =
+        "Teh alpha is very very good, so utilize it. Recieve the the thing.\n";
+      const checks = (section: string) => {
+        const cwd = project(
+          `${header}\n[*.md]\n${section}rules.no-alpha = YES\n`,
+          { "no-alpha": existence("alpha") },
+          { "doc.md": bait }
+        );
+        const parsed = JSON.parse(
+          runRaw(cwd, ["doc.md"], ["--no-exit"]).stdout
+        ) as Record<string, Array<{ Check: string }>>;
+        return [
+          ...new Set((parsed["doc.md"] ?? []).map((finding) => finding.Check)),
+        ].toSorted();
+      };
+      expect(checks("")).toEqual(["rules.no-alpha"]);
+      expect(checks("BasedOnStyles = Vale\n")).toEqual([
+        "Vale.Repetition",
+        "Vale.Spelling",
+        "rules.no-alpha",
+      ]);
+    });
+
+    describe("a negated inline scope blanks the element's text out of the block", () => {
+      // Depended on by: the recipe's scope guidance and the `~link` /
+      // `~strong` / `~emphasis` corpus rows. Upstream 79a48752. Through
+      // 3.21.0 `~link` only kept the rule off the link's own fragment; the
+      // paragraph the link sits in still carried the link text, so a token
+      // inside the link was reported from the paragraph. 3.22.0 blanks the
+      // element out of the paragraph, rune for rune, so positions after it
+      // hold. The inline scopes it applies to are `link`, `strong`,
+      // `emphasis` and `code`, from `inlineScopes` in
+      // `internal/check/scope.go`; the release note's `text.raw` and
+      // `paragraph.link` are not operands on either binary, and the corpus
+      // records both as inert.
+      const document =
+        "Plain bogus one. See [bogus link](http://x) and **bogus strong** and *bogus em* and `bogus code`.\n\n# Heading bogus\n";
+      const at = (scope: string) =>
+        lines(hedge(scope).replace("worth noting", "bogus"), document).lines;
+      /** The spans on line 1 at `scope`, for the rune-for-rune claim. */
+      const spans = (scope: string) => {
+        const cwd = project(
+          `${header}\n[*]\nrules.r = YES\n`,
+          { r: hedge(scope).replace("worth noting", "bogus") },
+          { "doc.md": document }
+        );
+        const parsed = JSON.parse(
+          runRaw(cwd, ["doc.md"], ["--no-exit"]).stdout
+        ) as Record<string, Array<{ Line: number; Span: [number, number] }>>;
+        return (parsed["doc.md"] ?? [])
+          .filter((finding) => finding.Line === 1)
+          .map((finding) => finding.Span);
+      };
+
+      it("reaches every prose occurrence at `text`", () => {
+        // Five: plain, link, strong, emphasis, heading. Inline code was
+        // never prose, on any version.
+        expect(at("text")).toEqual([1, 1, 1, 1, 3]);
+      });
+
+      it("drops the link text under ~link, keeping the paragraph", () => {
+        // 3.21.0: five.
+        expect(at("~link")).toEqual([1, 1, 1, 3]);
+        expect(at("text & ~link")).toEqual([1, 1, 1, 3]);
+      });
+
+      it("drops strong and emphasis text under their negations", () => {
+        // 3.21.0: five.
+        expect(at("~strong & ~emphasis")).toEqual([1, 1, 3]);
+      });
+
+      it("combines with a block negation", () => {
+        // `~heading` was already honored; `~link` now is too. 3.21.0: four.
+        expect(at("~heading & ~link")).toEqual([1, 1, 1]);
+      });
+
+      it("keeps the positions after a blanked element", () => {
+        // The strong text sits after the link. Its span is the same with
+        // and without the link blanked, which is the rune-for-rune claim.
+        expect(spans("~link")).toEqual([
+          [7, 11],
+          [51, 55],
+          [71, 75],
+        ]);
+        expect(spans("text")).toEqual([
+          [7, 11],
+          [23, 27],
+          [51, 55],
+          [71, 75],
+        ]);
+      });
+
+      it("does not know the release note's dotted spellings", () => {
+        expect(at("text.raw")).toEqual([]);
+        expect(at("~text.raw")).toEqual([1, 1, 1, 1, 3]);
+        expect(at("paragraph.link")).toEqual([]);
+        expect(at("~paragraph.link")).toEqual([1, 1, 1, 1, 3]);
+      });
+    });
+
+    describe("a [formats] key can be a file name or a glob", () => {
+      // Depended on by: nothing this CLI writes. The assembled header
+      // carries no `[formats]`, and a rule's own `.vale.ini` cannot: the
+      // schema reads `[formats]` as a matcher named `formats` and refuses
+      // it for the breadcrumb it lacks and the foreign key it assigns
+      // (`vale-config-schema.test.ts`). Pinned so the tier table's claim
+      // that an extension decides the parser stays a claim about THIS
+      // config: a `[formats]` line would move a file between tiers, and
+      // 3.22.0 widened what such a line can name. Upstream 6c2d99d9.
+      // Measured on 3.21.0: the file-name and glob keys were accepted and
+      // ignored, so NOTES was linted as plain text and the fence fired.
+      const fenced = "Prose simply.\n\n```\nsimply fenced\n```\n";
+      const under = (formats: string, name: string) => {
+        const cwd = project(
+          `${header}\n${formats}[*]\nrules.no-simply = YES\n`,
+          { "no-simply": existence("simply") },
+          { [name]: fenced }
+        );
+        const parsed = JSON.parse(
+          runRaw(cwd, [name], ["--no-exit"]).stdout
+        ) as Record<string, Array<{ Line: number }>>;
+        return (parsed[name] ?? []).map((finding) => finding.Line);
+      };
+
+      it("routes a file with no extension to Markdown by its name", () => {
+        expect(under("", "NOTES")).toEqual([1, 4]);
+        expect(under("[formats]\nNOTES = md\n\n", "NOTES")).toEqual([1]);
+      });
+
+      it("routes a glob's files to Markdown", () => {
+        expect(under("", "thing.special")).toEqual([1, 4]);
+        expect(under("[formats]\n*.special = md\n\n", "thing.special")).toEqual(
+          [1]
+        );
+      });
+
+      it("still routes by bare extension, the shape 3.21.0 had", () => {
+        expect(under("[formats]\nspecial = md\n\n", "thing.special")).toEqual([
+          1,
+        ]);
+      });
+    });
+
+    it("places a front-matter finding at the field's own position, every occurrence", () => {
+      // Depended on by: `toValeCheckResults`, which passes `Line` and `Span`
+      // through, and any `frontmatter` or `frontmatter.<key>` rule. Upstream
+      // 5ab91a5d: alerts were placed by searching the file for the field's
+      // text, so a token appearing twice in one field was found once (the
+      // first occurrence, on 3.21.0), and a value that also appeared earlier
+      // in the file could be placed on the wrong line. Now the field's own
+      // span is used.
+      const cwd = project(
+        `${header}\n[*]\nrules.r = YES\n`,
+        {
+          r: `extends: existence\nmessage: "%s"\nlevel: warning\nscope: frontmatter\ntokens:\n  - bogus\n`,
+        },
+        {
+          "doc.md":
+            "---\ntitle: bogus\ndescription: bogus twice bogus\n---\n\nbogus body.\n",
+        }
+      );
+      const parsed = JSON.parse(
+        runRaw(cwd, ["doc.md"], ["--no-exit"]).stdout
+      ) as Record<string, Array<{ Line: number; Span: [number, number] }>>;
+      expect(
+        (parsed["doc.md"] ?? []).map((finding) => [
+          finding.Line,
+          ...finding.Span,
+        ])
+      ).toEqual([
+        [2, 8, 12],
+        [3, 14, 18],
+        [3, 26, 30],
+      ]);
+    });
+
+    it("lints a rule file's message and description, not its patterns", () => {
+      // Depended on by: nothing under `check`, which excludes `.taskless/`
+      // before Vale runs, so `.taskless/rules/vale/<id>/<id>.yml` is never a
+      // target (`vale-run.test.ts` pins the exclusion). Pinned because a
+      // project that keeps other Vale styles outside `.taskless/` under a
+      // `[*.yml]` matcher now sees fewer findings from them. Upstream
+      // f2785853. Measured on 3.21.0: every line was prose, so `link`,
+      // `tokens` and `exceptions` fired too (six findings).
+      const style =
+        'extends: existence\nmessage: "Avoid bogus wording"\ndescription: |\n  A bogus description.\nlevel: warning\nlink: https://x/bogus\ntokens:\n  - bogus\n  - "(?i)bogus-pattern"\nexceptions:\n  - bogus-exception\n';
+      const cwd = project(
+        `${header}\n[*]\nrules.r = YES\n`,
+        { r: existence("bogus"), other: style },
+        {}
+      );
+      const target = join(".taskless", "vale", "rules", "other.yml");
+      const parsed = JSON.parse(
+        runRaw(cwd, [target], ["--no-exit"]).stdout
+      ) as Record<string, Array<{ Line: number }>>;
+      expect((parsed[target] ?? []).map((finding) => finding.Line)).toEqual([
+        2, 4,
+      ]);
+    });
+
+    it("lints a one-line MDX element's text", () => {
+      // Upstream 49422de5. The other MDX changes in the release (indented
+      // blocks, an expression followed by prose) measured the same on both
+      // binaries for the shapes tried and are not pinned. 3.21.0: line 7
+      // absent.
+      const document =
+        'import X from "y"\n\n# Heading bogus\n\nProse bogus {expr} after bogus.\n\n<Note>bogus inside one-line element</Note>\n\n    indented bogus block\n';
+      expect(
+        lines(
+          hedge("text").replace("worth noting", "bogus"),
+          document,
+          "page.mdx"
+        ).lines
+      ).toEqual([3, 5, 5, 7, 9]);
+    });
+
+    it("checks the parts of an identifier under split: true", () => {
+      // Upstream 85992f2a. 3.21.0 accepted the key, reported `recieveData`
+      // whole and missed `getHTTPResponsze_v2` entirely. The `split` field
+      // is a measured member of the `spelling` field table, so the schema
+      // already accepts it; this pins what it does.
+      const cwd = project(
+        `${header}\n[*]\nrules.sp = YES\n`,
+        {
+          sp: 'extends: spelling\nmessage: "spell: %s"\nlevel: warning\nsplit: true\n',
+        },
+        { "doc.md": "Call getHTTPResponsze_v2 and recieveData now.\n" }
+      );
+      const parsed = JSON.parse(
+        runRaw(cwd, ["doc.md"], ["--no-exit"]).stdout
+      ) as Record<string, Array<{ Match: string; Span: [number, number] }>>;
+      expect(
+        (parsed["doc.md"] ?? []).map((finding) => [
+          finding.Match,
+          ...finding.Span,
+        ])
+      ).toEqual([
+        ["Responsze", 13, 21],
+        ["recieve", 30, 36],
+      ]);
+    });
+  });
 });
 
 /**

From 1b1b680445537305ad54d311ab7de5a5bee62054 Mon Sep 17 00:00:00 2001
From: Jakob Heuser <jakob@codedrift.com>
Date: Mon, 21 Sep 2026 16:06:16 -0700
Subject: [PATCH 4/5] docs(vale): recipe, ledger, changeset and OpenSpec change
 for 3.22.0

create-vale-rule (topic v11): the config template is three lines, a
paragraph says why BasedOnStyles is rejected with any value, and a
paragraph documents inline-element negation and warns off the release
note's text.raw and paragraph.link spellings. update (topic v9): the
0.11.3 entry gains the migration, the negation change, and the additions
a rule can use. The changeset grows in place, still patch. The OpenSpec
change restates the two modified requirements in full and adds the
migration-8 requirement; archived on this PR.
---
 .changeset/vale-3-22-0.md                     |  17 +++
 .../vale-3-22-basedonstyles/proposal.md       |  40 +++++
 .../specs/cli-rule-validation/spec.md         |  76 ++++++++++
 .../specs/cli-taskless-bootstrap/spec.md      |  30 ++++
 .../specs/cli-vale-rule-engine/spec.md        | 142 ++++++++++++++++++
 .../changes/vale-3-22-basedonstyles/tasks.md  |  35 +++++
 packages/cli/src/agent/create-vale-rule.md    |  40 +++--
 packages/cli/src/agent/update.md              |  59 +++++++-
 8 files changed, 429 insertions(+), 10 deletions(-)
 create mode 100644 openspec/changes/vale-3-22-basedonstyles/proposal.md
 create mode 100644 openspec/changes/vale-3-22-basedonstyles/specs/cli-rule-validation/spec.md
 create mode 100644 openspec/changes/vale-3-22-basedonstyles/specs/cli-taskless-bootstrap/spec.md
 create mode 100644 openspec/changes/vale-3-22-basedonstyles/specs/cli-vale-rule-engine/spec.md
 create mode 100644 openspec/changes/vale-3-22-basedonstyles/tasks.md

diff --git a/.changeset/vale-3-22-0.md b/.changeset/vale-3-22-0.md
index 92359317..442de221 100644
--- a/.changeset/vale-3-22-0.md
+++ b/.changeset/vale-3-22-0.md
@@ -3,3 +3,20 @@
 ---
 
 Update the bundled Vale to 3.22.0.
+
+For a rule under `.taskless/rules/vale/`, what you can now write:
+
+- `scope: text & ~link` (and `~strong`, `~emphasis`, `~code`) runs on the paragraph and blanks the element's text out of it before the rule sees it, so a wording or casing rule can leave link text and bold terms alone without giving up the sentence around them. Positions after the blanked element do not move. The release note's `text.raw` and `paragraph.link` spellings are not scopes; `verify` rejects them, so write the bare inline name.
+- `split: true` on a `spelling` rule checks the parts of an identifier (`getHTTPResponsze_v2` reports `Responsze`) and places each at its own position. 3.21.0 accepted the key and did neither.
+- A `frontmatter` or `frontmatter.<key>` rule reports every occurrence in a field at the field's own position; a token appearing twice in one field was reported once.
+- A one-line MDX element's text (`<Note>...</Note>`) is linted.
+
+What changes for a rule you already have:
+
+- **`BasedOnStyles =` is removed from every rule's `.vale.ini`, by migration 0008 on the next `init`, and `verify` now rejects the key with any value (`vale-config-no-based-on-styles`).** Every earlier version of the `create-vale-rule` recipe wrote the line into every matcher, where it was inert: no bundled style loads unless a run-level `BasedOnStyles` names one, and the assembled header names none. On 3.22.0 an empty value clears every setting a file inherited from an earlier matcher, and the assembled run config is every rule's matchers in id order, so a rule writing the line under `[docs/**]` silenced every alphabetically earlier rule under `docs/`, and `[*.md]` beside another rule's `[*.{md,markdown}]` silenced the first on every `.md` file, with nothing reported. `check` and `verify` refuse to run until `init` has migrated the configs, and name it; commit the rewritten files. A migrated config enables exactly what the old one did on 3.21.0.
+- A rule whose `scope` negates `link`, `strong`, `emphasis` or `code` no longer sees that element's text inside a paragraph. Through 3.21.0 the paragraph still carried it, so findings inside those elements disappear. Drop the negation if the rule was meant to reach them.
+- The isolating config `test` and `verify` build no longer writes `BasedOnStyles =`. Measured on both binaries, nothing fires without it and `Vale.Spelling` never could, so fixtures behave as before.
+
+Not changed for a rule this CLI assembles: a `[formats]` key may now be a file name or a glob, but no rule config can carry one and the assembled header writes none, so the extension still decides the parser. `UNSET` as a rule's value behaves as `NO` and is not accepted; `YES` and `NO` remain the two values.
+
+`taskless agent update` carries the same list, with what to do about each.
diff --git a/openspec/changes/vale-3-22-basedonstyles/proposal.md b/openspec/changes/vale-3-22-basedonstyles/proposal.md
new file mode 100644
index 00000000..c5e57d92
--- /dev/null
+++ b/openspec/changes/vale-3-22-basedonstyles/proposal.md
@@ -0,0 +1,40 @@
+## Why
+
+Vale 3.22.0 gives an empty `BasedOnStyles` a meaning (upstream c2d62437): it clears every setting a file inherited from an earlier matcher. The `create-vale-rule` recipe has told every author to write `BasedOnStyles =` in every matcher since the Vale engine shipped, on the belief that it kept bundled styles from loading, and the assembled run config is every rule's matchers interleaved in id order. Measured on the 3.22.0 binary against the exact layout `assembleValeConfig` writes: a rule writing the line under `[docs/**]` silences every alphabetically earlier rule under `docs/`; `[*.md]` beside another rule's `[*.{md,markdown}]` silences the first on every `.md` file; and a rule's own later `[docs/**]` matcher carrying only the line turns the rule off there. Nothing is reported. Only two rules whose globs are byte-identical escape, because Vale merges those into one section, which is the only reason this repository's own five rules did not notice. On 3.21.0 every one of those configs fired both rules.
+
+The belief the line rested on was also wrong. Measured on both binaries with a document baited for `Vale.Spelling`, `Vale.Repetition` and `Vale.Terms`: nothing but the rule under test fires when the key is absent, and the control (`BasedOnStyles = Vale`) fires all of them. No bundled style loads unless a run-level `BasedOnStyles` names one, and the assembled header names none.
+
+## What Changes
+
+- **The config schema rejects `BasedOnStyles` in a rule's config with any value**, under `vale-config-no-based-on-styles` (renamed from `vale-config-based-on-styles-empty`, which accepted the empty form; the id was never published in a release, so the rename is free). The message says what the line does on the pinned Vale and to delete it.
+- **Migration 8 deletes the line** from every `.taskless/rules/vale/<id>/.vale.ini`, and nothing else: a line edit over the author's own bytes, never a parse and re-serialize, anchored on the key at line start so a comment survives, idempotent, and skipping a file without the line. `check` and `verify` refuse to run on a scaffold behind the current version and name `init`, which applies it; `init`, `demo`, `onboard`, the wizard and rule delivery run migrations directly.
+- **The three isolating configs** (`buildIsolatingConfig`, the generator's `probe()`, `runOne` in the schema contract test) stop writing `BasedOnStyles =`, and their docblocks now carry the measurement instead of the belief.
+- **Every fixture, corpus config, the demo asset and the recipe template drop the line.** The recipe explains why the key is rejected; the `update` ledger tells a project what `init` rewrites and that `verify` names anything left.
+- **The 3.22.0 contract is pinned** in `vale-vendor-contract.test.ts` on the assembled layout: the `BasedOnStyles` table above, `UNSET`, that no bundled style loads without the key, negated inline scopes (`~link`, `~strong`, `~emphasis` blank the element's text out of the block; `text.raw` and `paragraph.link` from the release note are not operands), `[formats]` by file name and glob (and that the schema refuses a `[formats]` section in a rule config), front-matter placement, a rule file's `message` and `description` being the only prose in it, a one-line MDX element, and `split: true`. `VALE_VERSION` moves to 3.22.0 and the vocabulary is regenerated (unchanged beyond the stamp).
+
+## Delivery shape
+
+**Single PR**, merging down into the bot's pin-bump branch `vendor/vale/upgrade` (taskless/cli#368). The pin bump alone does not land green (`VALE_VERSION` disagrees with the pins) and, worse, would ship the silencing above to every project with two Vale rules on different globs; the schema rejection alone would turn every project's `check` red until someone deleted the lines by hand. Pin, rejection and migration are correct only together, so they reach `main` atomically through the bot's branch.
+
+Nothing here is **BREAKING**, and the bump is `patch`. A rule that carried the key is rewritten by the migration to a config that enables exactly what it enabled on 3.21.0, and a rule copied in afterwards with the key fails `verify` naming the line, where on 3.22.0 without this change it would have silenced a neighbour silently.
+
+## Capabilities
+
+### New Capabilities
+
+None.
+
+### Modified Capabilities
+
+- `cli-vale-rule-engine`: "Per-rule scoping is expressed in the rule's own Vale config" states that a rule's config carries no `BasedOnStyles` and why, with a scenario for overlapping matchers and one for the refusal; "A rule's Vale config is validated against a schema before it is assembled" moves the key from "must be empty" to "rejected with any value" and adds the `[formats]` scenario.
+- `cli-rule-validation`: "Verify checks a rule's required components" gains the rejection scenario.
+- `cli-taskless-bootstrap`: a new requirement for migration 8.
+
+## Impact
+
+- `packages/cli/src/schemas/vale-config.ts`, `src/rules/constraints.ts`, `assets/reference.json` (regenerated).
+- `packages/cli/src/filesystem/migrations/0008-drop-based-on-styles.ts` (new), registered in `migrate.ts`; `LATEST_SCHEMA_VERSION` becomes 8 and this repository's own `.taskless/` is migrated and committed.
+- `packages/cli/src/rules/vale/verify.ts`, `scripts/generate-vale-schema.ts`, `test/vale-schema-contract.test.ts`: isolating configs.
+- `packages/cli/src/rules/capabilities.ts` (`VALE_VERSION`, the bump note in the tier table), `src/generated/vale-vocabulary*` (regenerated), `src/rules/assemble.ts` (docblock).
+- `packages/cli/src/agent/create-vale-rule.md` (topic v11), `src/agent/update.md` (topic v9), `.changeset/vale-3-22-0.md` (grown in place).
+- Tests: the schema fixture set, the constraint table, migration tests, the corpus, the vendor contract's new `Vale 3.22.0` block, and every inline config in the suite that carried the line.
diff --git a/openspec/changes/vale-3-22-basedonstyles/specs/cli-rule-validation/spec.md b/openspec/changes/vale-3-22-basedonstyles/specs/cli-rule-validation/spec.md
new file mode 100644
index 00000000..360b47a9
--- /dev/null
+++ b/openspec/changes/vale-3-22-basedonstyles/specs/cli-rule-validation/spec.md
@@ -0,0 +1,76 @@
+## MODIFIED Requirements
+
+### Requirement: Verify checks a rule's required components
+
+`verify` SHALL check that a rule has the components its engine requires and that they are well formed, and SHALL NOT require fixtures or test cases to exist.
+
+The two commands split because they have different preconditions. An agent part-way through authoring has a rule and no fixtures yet, and needs to know the rule itself is valid before it can write a meaningful test for it.
+
+Per engine, `verify` SHALL check:
+
+| Engine    | Components                                                                                                                     |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `sg`      | `<id>.yml` against the ast-grep schema and the Taskless required fields                                                        |
+| `vale`    | `<id>.yml` against the Vale rule schema and the Taskless required fields, and the rule's `.vale.ini` against the config schema |
+| `runtime` | `check.ts` present, and at least one capture rule under `captures/`                                                            |
+
+The `vale` row previously read "against Vale's own validation." Measured against the pinned 3.18.0 binary, that covers less than it claims: `level: bananas` is reported, while `extends: nonsense` and `scope: fenced` both verify clean and produce a rule that matches nothing. Vale validates a rule when it _runs_ one, and it runs one field at a time — so a name it does not recognize is not an error, it is a check that never fires. Schema validation is therefore its own layer for `vale`, as it already is for `sg`.
+
+#### Scenario: A rule with no fixtures still verifies
+
+- **WHEN** `verify` runs against a rule whose fixture buckets are empty or absent
+- **THEN** it SHALL report on the rule's components only
+- **AND** the absence of fixtures SHALL NOT be a verify failure
+
+#### Scenario: A malformed rule reports its own error
+
+- **WHEN** a Vale style declares a `level` outside `suggestion`/`warning`/`error`
+- **THEN** `verify` SHALL report that error, naming the field
+
+#### Scenario: An unrecognized extension point is rejected
+
+- **WHEN** a Vale style declares an `extends` that is not one of Vale's check types
+- **THEN** `verify` SHALL report it, naming the field and the accepted values
+- **AND** it SHALL NOT report the rule as valid
+
+#### Scenario: An unrecognized scope is rejected
+
+- **WHEN** a Vale style declares a `scope` that is not one of Vale's scope values
+- **THEN** `verify` SHALL report it, naming the field
+- **AND** a scope using the `~` negation or `&` chaining syntax over recognized values SHALL be accepted
+
+#### Scenario: A field belonging to another check type is rejected
+
+- **WHEN** a Vale style declares a field its `extends` does not accept, such as `tokens` on an `occurrence` check
+- **THEN** `verify` SHALL report it before Vale is invoked
+
+The failure it prevents is not a local one: Vale reports this as `E201: has invalid keys` and reads one assembled config per run, so a single rule with a stray field suppresses every other Vale rule's findings.
+
+#### Scenario: A rule config that never enables the rule is rejected
+
+- **WHEN** a Vale rule's `.vale.ini` declares matchers but no `<id>.<id> = YES`
+- **THEN** `verify` SHALL report that the rule is present but off, naming the file
+
+#### Scenario: A rule config that carries BasedOnStyles is rejected
+
+- **WHEN** a Vale rule's `.vale.ini` assigns `BasedOnStyles` in any matcher, with any value
+- **THEN** `verify` SHALL report it under `vale-config-no-based-on-styles`, naming the line
+- **AND** it SHALL NOT report the rule as valid
+
+#### Scenario: A rule config that assigns a foreign key is rejected
+
+- **WHEN** a Vale rule's `.vale.ini` assigns a `<style>.<check>` key naming a different rule
+- **THEN** `verify` SHALL report it, naming the key and the line
+- **AND** it SHALL NOT report the rule as valid
+
+#### Scenario: A rule config advisory does not fail verify
+
+- **WHEN** a Vale rule's `.vale.ini` assigns the same key twice inside one matcher, and another matcher still enables the rule
+- **THEN** `verify` SHALL report the rule as valid
+- **AND** the repeat SHALL be printed as a notice on that rule
+
+#### Scenario: A rule config whose only enable is overridden is rejected
+
+- **WHEN** a Vale rule's `.vale.ini` assigns `<id>.<id> = YES` and then `<id>.<id> = NO` in its only matcher
+- **THEN** `verify` SHALL report that the rule is present but off, under `vale-config-enabled-somewhere`
+- **AND** the repeat SHALL still be printed as a notice on that rule
diff --git a/openspec/changes/vale-3-22-basedonstyles/specs/cli-taskless-bootstrap/spec.md b/openspec/changes/vale-3-22-basedonstyles/specs/cli-taskless-bootstrap/spec.md
new file mode 100644
index 00000000..c890d76b
--- /dev/null
+++ b/openspec/changes/vale-3-22-basedonstyles/specs/cli-taskless-bootstrap/spec.md
@@ -0,0 +1,30 @@
+## ADDED Requirements
+
+### Requirement: Migration 8 drops BasedOnStyles from Vale rule configs
+
+Migration `8` SHALL delete every `BasedOnStyles` assignment line from each `.taskless/rules/vale/<id>/.vale.ini`, whatever the value, and SHALL change nothing else in the file: every other line, comment, blank line and line ending SHALL be preserved byte for byte, and a comment that mentions `BasedOnStyles` SHALL be left alone. A config without the line SHALL NOT be rewritten. A project with no `rules/vale/` tree SHALL be left as it is. It SHALL NOT modify any shipped migration.
+
+The migration exists because the `create-vale-rule` recipe wrote `BasedOnStyles =` into every matcher through the release before this one, the config schema now rejects the key, and `check` and `verify` refuse to run on a scaffold behind the current version. Without the rewrite every upgraded project's first `check` would refuse the Vale engine over a line the CLI itself wrote.
+
+#### Scenario: An existing scaffold loses the line from every matcher
+
+- **WHEN** `taskless.json` records version 7, a rule's `.vale.ini` carries `BasedOnStyles =` in three matchers, and the CLI bootstraps `.taskless/`
+- **THEN** migration 8 SHALL run
+- **AND** the config SHALL contain no `BasedOnStyles` line and every other byte unchanged
+- **AND** the rewritten config SHALL pass the config schema
+- **AND** `taskless.json` SHALL record the latest schema version
+
+#### Scenario: A config without the line is untouched
+
+- **WHEN** a rule's `.vale.ini` carries no `BasedOnStyles` line and migration 8 runs
+- **THEN** the file SHALL NOT be written
+
+#### Scenario: A comment naming the key survives
+
+- **WHEN** a rule's `.vale.ini` carries a comment line that mentions `BasedOnStyles` and migration 8 runs
+- **THEN** the comment SHALL remain and only assignment lines SHALL be removed
+
+#### Scenario: Migration 8 is idempotent
+
+- **WHEN** migration 8 runs twice over the same scaffold
+- **THEN** the second run SHALL change nothing
diff --git a/openspec/changes/vale-3-22-basedonstyles/specs/cli-vale-rule-engine/spec.md b/openspec/changes/vale-3-22-basedonstyles/specs/cli-vale-rule-engine/spec.md
new file mode 100644
index 00000000..f3bba1b8
--- /dev/null
+++ b/openspec/changes/vale-3-22-basedonstyles/specs/cli-vale-rule-engine/spec.md
@@ -0,0 +1,142 @@
+## MODIFIED Requirements
+
+### Requirement: Per-rule scoping is expressed in the rule's own Vale config
+
+The system SHALL express a Vale rule's scope through **matchers** — `[<glob>]` sections — declared in that rule's own `.taskless/rules/vale/<id>/.vale.ini`. Include is `<id>.<id> = YES`, exclude is `<id>.<id> = NO`.
+
+Precedence is **positional**, and the system SHALL order matchers accordingly rather than relying on a disable to win on its own. Measured against Vale 3.21.0:
+
+- Where two matchers both match a file, the **last** one wins for that rule.
+- Where the same key is assigned twice inside one matcher — including across duplicate `[<glob>]` sections, which Vale merges — the **last** assignment wins. Through Vale 3.20.0 the first assignment won here; 3.21.0 made the two directions agree.
+
+A disable therefore SHALL be declared **after** the enable it narrows, within the rule's own config; the config schema rejects a `NO` matcher that precedes every `YES`. Because precedence is positional and the run config is assembled, **assembly SHALL be deterministic**: rules ordered by id, and each rule's own matcher order preserved verbatim. A non-deterministic assembly would make a rule's effective scope depend on directory iteration order.
+
+A rule SHALL NOT be able to override another rule's matchers. It cannot know its own position in the assembled file, and cross-rule overriding through a shared file is the coupling the per-rule layout removes. The config schema enforces this: an assignment key naming any rule but the config's own is a rejection, at `verify` and at assembly.
+
+A rule's config SHALL NOT carry `BasedOnStyles`, with any value. Measured against Vale 3.22.0, an empty `BasedOnStyles` in a matcher clears every setting the file inherited from an earlier matcher, and in the assembled config "earlier" means every other rule whose glob reaches the file, so the line is a cross-rule override in the other direction: a rule writing it under `[docs/**]` silences every alphabetically earlier rule under `docs/`, and only two rules with byte-identical globs, which Vale merges into one section, escape. Through 3.21.0 the line was inert. A non-empty value loads a bundled style alongside every rule whose matchers overlap. Neither value has a job in a rule's config: Vale loads no bundled style unless a run-level `BasedOnStyles` names one, and the assembled header names none. The config schema rejects the key, and migration 8 deletes it from installed configs.
+
+#### Scenario: A rule scopes itself
+
+- **WHEN** a rule's own config enables it under `[marketing/**]`
+- **THEN** the rule produces findings in `marketing/` files and none in `api/` files
+
+#### Scenario: A rule narrows itself
+
+- **WHEN** a rule's config enables it under `[marketing/**]` and then disables it under `[marketing/legacy/**]`
+- **THEN** the rule fires in `marketing/` but not in `marketing/legacy/`
+
+#### Scenario: A repeated key keeps its last assignment
+
+- **WHEN** a rule's config assigns `<id>.<id> = YES` and then `<id>.<id> = NO` inside one matcher, or across two `[<glob>]` sections with the same glob
+- **THEN** the rule does not fire on a matching file
+- **AND** the reverse order fires
+
+#### Scenario: Assembly order is stable
+
+- **WHEN** the same set of rules is assembled twice
+- **THEN** the resulting config SHALL be byte-identical
+- **AND** each rule's matchers SHALL appear in the order that rule declared them
+
+#### Scenario: Duplicate matchers merge
+
+- **WHEN** two rules each declare a `[*.md]` matcher
+- **THEN** both rules run on a matching `.md` file (Vale merges the matchers)
+
+#### Scenario: Overlapping matchers do not interfere
+
+- **WHEN** one rule declares `[*.md]` and another declares `[docs/**]`, and neither config carries `BasedOnStyles`
+- **THEN** both rules run on a matching file under `docs/`
+
+#### Scenario: A BasedOnStyles line is refused rather than assembled
+
+- **WHEN** a rule's config carries `BasedOnStyles =` in any matcher
+- **THEN** `verify` SHALL reject the rule under `vale-config-no-based-on-styles`, naming the line
+- **AND** the Vale run SHALL be refused rather than assembled with the line, which on the pinned Vale would silence every earlier rule under that matcher's files
+
+#### Scenario: A rule cannot assign another rule's key
+
+- **WHEN** `no-simply/.vale.ini` assigns `no-hedging.no-hedging = NO`
+- **THEN** `verify` SHALL reject `no-simply`, naming the foreign key
+- **AND** the Vale run SHALL be refused rather than assembled without that rule's config
+
+### Requirement: A rule's Vale config is validated against a schema before it is assembled
+
+The system SHALL parse each rule's `.vale.ini` into an ordered, lossless AST and validate that AST against a schema keyed by the rule's directory id, before the config is assembled into the run config and when the rule is verified. Validation SHALL be performed on the parsed structure, never by matching the file's text.
+
+The schema SHALL reject a config that:
+
+- assigns any property above its first matcher (`StylesPath`, `MinAlertLevel`, or anything else; Vale ignores such a line with a `W101` warning and the rule verifies clean while enabled nowhere)
+- declares a matcher without a `tskl) rule = <id>` breadcrumb naming this rule
+- assigns a key other than `<id>.<id>` (a `<style>.<check>` key naming any other rule is a cross-rule override)
+- assigns a value other than `YES` or `NO`
+- assigns `BasedOnStyles`, with any value, empty included (on Vale 3.22.0 an empty value clears every earlier matcher's settings for the file, which in the assembled config silences every other rule whose glob reaches it; a named style loads alongside every overlapping rule; and no rule config ever needed either, since no bundled style loads unless a run-level `BasedOnStyles` names one)
+- declares no matcher
+- never assigns `<id>.<id> = YES` in its final per-matcher verdicts (matchers with the same glob are folded, as Vale merges them, and the last assignment wins, so a `YES` that a later `NO` in the same matcher overrides does not count)
+- declares a `NO`-verdict matcher before every `YES`-verdict matcher (no style is loaded, so a rule is off until a `YES`, and such a `NO` is either dead or overridden by the `YES` that follows; no config means it)
+
+The schema SHALL report, without rejecting, a config that:
+
+- assigns the same key twice inside one matcher (Vale 3.21.0 keeps the last assignment; 3.20.0 kept the first)
+- declares a `[*]` matcher
+- declares a matcher under `.taskless/**` (`check` excludes that tree before Vale runs, so the matcher acts only under a bare `vale` invocation)
+
+A rejected config SHALL refuse the Vale engine for that `check` run: the engine reports a failure naming the rule and the offending line, that failure SHALL reach the exit code, and other engines SHALL still run. A rule with a rejected config SHALL NOT be silently omitted from the assembled config, because a rule that is present, verifies, and reports nothing is the silent-disable failure this engine's design exists to prevent. Advisories SHALL be surfaced as notices and SHALL NOT affect the exit code.
+
+Assembly SHALL write each accepted config's source verbatim. The parsed structure is read for validation and for the list of matcher patterns; it is not re-serialized.
+
+#### Scenario: A foreign assignment refuses the run
+
+- **WHEN** `no-simply/.vale.ini` assigns `no-hedging.no-hedging = NO` and `check` runs
+- **THEN** the Vale engine SHALL report a failure naming `no-simply` and that line
+- **AND** the exit code SHALL be non-zero
+- **AND** ast-grep results for the same run SHALL still be reported
+
+#### Scenario: A run-level key in a rule config is rejected
+
+- **WHEN** a rule's config places `StylesPath = .` above its first matcher
+- **THEN** `verify` SHALL reject the rule, naming the key and the line
+- **AND** `check` SHALL refuse the Vale engine rather than strip the line
+
+#### Scenario: A matcher without a breadcrumb is rejected
+
+- **WHEN** a rule's config declares `[*.md]` with `<id>.<id> = YES` and no `tskl) rule` key
+- **THEN** `verify` SHALL reject the rule, naming the matcher
+
+#### Scenario: A disable that precedes every enable is rejected
+
+- **WHEN** a rule's config declares `[docs/legacy/**]` with `<id>.<id> = NO` and then `[docs/**]` with `<id>.<id> = YES`
+- **THEN** `verify` SHALL reject the rule, naming the `NO` matcher and the `YES` that re-enables it
+
+#### Scenario: A BasedOnStyles assignment is rejected
+
+- **WHEN** a rule's config sets `BasedOnStyles =` inside a matcher
+- **THEN** `verify` SHALL reject the rule under `vale-config-no-based-on-styles`, naming the line and saying that the line silences the other rules whose globs overlap
+- **AND** a `BasedOnStyles` naming a style SHALL be rejected under the same constraint
+
+#### Scenario: A [formats] section is rejected as a matcher it cannot be
+
+- **WHEN** a rule's config declares a `[formats]` section
+- **THEN** `verify` SHALL reject it for the breadcrumb it lacks and the foreign key it assigns, so no rule config can move a file between parser tiers
+
+#### Scenario: A repeated key is reported, not rejected
+
+- **WHEN** one matcher assigns `<id>.<id> = YES` and then `<id>.<id> = NO`, and an earlier matcher assigns `<id>.<id> = YES`
+- **THEN** `verify` SHALL accept the rule and report the repeat as a notice
+- **AND** `check` SHALL run the Vale engine and carry the same text in its notices
+
+#### Scenario: A rule whose only enable is overridden is rejected
+
+- **WHEN** the only matcher assigning `<id>.<id> = YES` later assigns `<id>.<id> = NO`, in the same section or in a second section with the same glob
+- **THEN** `verify` SHALL reject the rule as present but off, under `vale-config-enabled-somewhere`
+- **AND** the repeat SHALL still be reported as a notice
+
+#### Scenario: A `.taskless/**` matcher is reported as unnecessary
+
+- **WHEN** a rule's config declares a matcher under `.taskless/**`
+- **THEN** `verify` SHALL accept the rule and report that `check` already excludes that tree
+
+#### Scenario: An accepted config is assembled byte-for-byte
+
+- **WHEN** a config passes the schema
+- **THEN** the assembled run config SHALL contain that file's bytes unchanged under the rule's breadcrumb comment
+- **AND** the matcher patterns reported for the run SHALL equal the section names in the parsed structure
diff --git a/openspec/changes/vale-3-22-basedonstyles/tasks.md b/openspec/changes/vale-3-22-basedonstyles/tasks.md
new file mode 100644
index 00000000..48d6df4b
--- /dev/null
+++ b/openspec/changes/vale-3-22-basedonstyles/tasks.md
@@ -0,0 +1,35 @@
+## 1. Measure
+
+- [x] 1.1 Run the two-rule assembled layout (`StylesPath = rules/vale`, breadcrumbs, id order) against the 3.21.0 and 3.22.0 binaries: identical globs, `[*.md]` beside `[*.{md,markdown}]`, `[*.md]` beside `[docs/**]` in both id orders, neither rule writing the key, a single rule's later matcher carrying only the key, a `NO` matcher carrying the key, `UNSET` as a rule value and at the style level. Record which rule fires on which file for each.
+- [x] 1.2 Measure whether any bundled style fires with no `BasedOnStyles` line, on both binaries, with a control that names `Vale` to prove the bait.
+- [x] 1.3 Measure the rest of the release against both binaries: negated inline scopes and the release note's dotted spellings, `[formats]` by file name and glob against a fenced-block discriminator, front-matter placement with a token twice in one field, a rule `.yml` as a lint target with bait in every field, a notebook, MDX with a one-line element, `split: true`. Re-time the timeout fixtures.
+
+## 2. Schema and constraints
+
+- [x] 2.1 `schemas/vale-config.ts`: reject `BasedOnStyles` with any value under `vale-config-no-based-on-styles`; message for the empty form says what 3.22.0 does with it and to delete the line. Drop the "an empty BasedOnStyles" allowance from the own-key message and the ordering comment.
+- [x] 2.2 `rules/constraints.ts`: rename the entry, rewrite summary and rationale from the measurement; adjust the two neighbouring rationales that named the empty key. Regenerate `assets/reference.json`.
+- [x] 2.3 Fixture set: strip the line from every `test/fixtures/vale-config/*.ini` but the rejection fixture; add `based-on-styles-named.ini`; fix the shifted line numbers in `vale-config-schema.test.ts`; add the `[formats]` rejection test. Update `constraints.test.ts`.
+
+## 3. Migration
+
+- [x] 3.1 Add `filesystem/migrations/0008-drop-based-on-styles.ts` (line edit, anchored on the key, idempotent, skips untouched files and a missing tree) and register `"8"` in `migrate.ts`.
+- [x] 3.2 `test/migrate-drop-based-on-styles.test.ts`: three matchers with three value shapes, byte-exact result, schema accepts the result, untouched file keeps its mtime, comment survives, idempotent, CRLF and no trailing newline, no rules tree, runner from version 7. Fix the 0007 test that pinned `version` to 7.
+- [x] 3.3 Migrate this repository's own `.taskless/` with `pnpm cli init` after `pnpm build`, and commit the rewritten configs and manifest.
+
+## 4. Isolating configs, fixtures, recipe, ledger
+
+- [x] 4.1 Drop `BasedOnStyles =` from `buildIsolatingConfig`, the generator's `probe()` and `runOne`; replace the three docblocks' claim with the measurement from 1.2; flip the `vale-verify.test.ts` assertion.
+- [x] 4.2 Drop the line from `assets/demo-vale/.vale.ini`, `example/`, the mixed-engines fixture project and every inline config in the test suite.
+- [x] 4.3 `agent/create-vale-rule.md`: template is three lines, a paragraph on why the key is rejected, a paragraph on inline-element negation and the release note's dotted spellings; topic v11. `agent/update.md`: extend "Migrating to 0.11.3" with the migration, the negation change, and the additions; topic v9.
+
+## 5. Version, vocabulary, contract
+
+- [x] 5.1 `VALE_VERSION` to 3.22.0; `reconcile-marker.test.ts`; regenerate the vocabulary; add the bump paragraph to the tier table's docblock after checking the upstream tree for a learned format (none).
+- [x] 5.2 `vale-vendor-contract.test.ts`: a `Vale 3.22.0` block pinning everything from 1.1 through 1.3 on the assembled layout. Corpus rows for `~link`, `~strong & ~emphasis`, `text.raw`, `paragraph.link`. Timing note in `vale-run.test.ts`.
+- [x] 5.3 Grow `.changeset/vale-3-22-0.md` in place: what you can now write, what changes for a rule you already have, what did not change.
+
+## 6. Land
+
+- [x] 6.1 `pnpm build`, `pnpm typecheck`, `pnpm lint`, `pnpm --filter @taskless/cli test`, `pnpm openspec validate --all`.
+- [x] 6.2 Dry-run the archive: wip commit, `pnpm openspec archive vale-3-22-basedonstyles -y`, count scenarios in the three specs before and after, reset to the wip SHA.
+- [x] 6.3 Archive for real on this PR, since it is the single PR of the change.
diff --git a/packages/cli/src/agent/create-vale-rule.md b/packages/cli/src/agent/create-vale-rule.md
index 0e277efc..3d52e31d 100644
--- a/packages/cli/src/agent/create-vale-rule.md
+++ b/packages/cli/src/agent/create-vale-rule.md
@@ -1,4 +1,4 @@
-# Topic: create-vale-rule     (CLI v%(CLI_VERSION)s / topic v10)
+# Topic: create-vale-rule     (CLI v%(CLI_VERSION)s / topic v11)
 
 ## You are here
 This is `create-vale-rule`. It helps you write a Vale rule: a check over
@@ -231,6 +231,19 @@ it.
    code; `text & ~code` chains two operands; a list (`[code, text]`) is a
    union. All three parse and behave.
 
+   **Negating an inline element removes its text from the paragraph, as
+   of Vale 3.22.0.** `~link`, `~strong`, `~emphasis` and `~code` are the
+   four. A rule with `text & ~link` still runs on every paragraph, and
+   the link text inside a paragraph is blanked before the rule sees it,
+   so a casing or wording rule can leave link text and bold terms alone
+   without giving up the sentence around them. Positions after the
+   blanked element do not move. Through 3.21.0 the same scope only kept
+   the rule off the link's own fragment, and the paragraph still carried
+   the link text, so a rule written this way now reports fewer findings.
+   The release note spells these `text.raw` and `paragraph.link`; those
+   dotted forms are not scopes on the binary, bare or negated, and
+   `verify` rejects them. Write the bare inline name.
+
    **A negation over a scope Vale does not know is a silent no-op.**
    Measured: `~banana` and `text & ~banana` both fire on everything,
    because there is no such scope to subtract. A typo inside a `~` does
@@ -503,11 +516,10 @@ it.
    # Which files this rule applies to.
    [*.md]
    tskl) rule = no-simply
-   BasedOnStyles =
    no-simply.no-simply = YES
    ```
 
-   Four lines, and each one earns its place:
+   Three lines, and each one earns its place:
 
    - `[*.md]` is a **matcher**: a glob over paths, deciding which files
      this rule sees. Match it to the files the rule is actually about,
@@ -520,14 +532,25 @@ it.
      matchers into one file. Vale parses the key and ignores it. Write it
      in every matcher you add, or the tooling loses track of who owns
      what.
-   - `BasedOnStyles =` with an empty value says explicitly that no
-     bundled style loads. The default is already empty, so this changes
-     nothing today. Write it anyway: it tells the next reader that no
-     style is missing.
    - `no-simply.no-simply = YES` turns the rule on. The first half is
      the style, which is this rule's directory; the second is the check
      inside it, which is the file. Both are the id.
 
+   **Do not write `BasedOnStyles`, empty or otherwise.** Older versions
+   of this recipe put `BasedOnStyles =` in every matcher, on the belief
+   that it kept Vale's bundled styles from loading. It never did that
+   (no bundled style loads unless a run-level `BasedOnStyles` names one,
+   and the assembled header names none), and as of Vale 3.22.0 an empty
+   value has a meaning: it clears every setting the file inherited from
+   an earlier matcher. Taskless assembles every rule's matchers into one
+   file in id order, so a rule writing the line under `[docs/**]`
+   silences every alphabetically earlier rule under `docs/`, and
+   `[*.md]` beside another rule's `[*.{md,markdown}]` silences the first
+   on every `.md` file. Only two rules with byte-identical globs escape,
+   because Vale merges those into one section. `verify` rejects the key
+   in any matcher, and `%(TASKLESS_CLI)s init` deletes it from configs
+   written by the older recipe.
+
    **Scope a rule *out* with a second matcher, not a cleverer glob.** A
    glob says which files a rule sees; it has no way to say "these but not
    those". The exclusion is a second matcher that assigns `NO`, and
@@ -538,7 +561,6 @@ it.
    # Every markdown file…
    [*.md]
    tskl) rule = no-simply
-   BasedOnStyles =
    no-simply.no-simply = YES
 
    # …except the changelog, which quotes release notes verbatim.
@@ -580,7 +602,7 @@ it.
    - an assignment key other than `<id>.<id>` (a key naming another rule
      is a cross-rule override, which a rule cannot do)
    - a value other than `YES` or `NO`
-   - a `BasedOnStyles` that is not empty
+   - a `BasedOnStyles` assignment, with any value, empty included
    - a config with no matcher, or one that never assigns `YES`
    - a `NO` matcher that precedes every `YES` matcher
 
diff --git a/packages/cli/src/agent/update.md b/packages/cli/src/agent/update.md
index 4463a5f8..b1b1d936 100644
--- a/packages/cli/src/agent/update.md
+++ b/packages/cli/src/agent/update.md
@@ -1,4 +1,4 @@
-# Topic: update     (CLI v%(CLI_VERSION)s / topic v8)
+# Topic: update     (CLI v%(CLI_VERSION)s / topic v9)
 
 ## You are here
 This is `update`. It tells you what an upgrade changed for the rules
@@ -329,6 +329,63 @@ than rejected, since `check` excludes that tree before Vale runs;
 delete it. `%(TASKLESS_CLI)s agent create-vale-rule` lists every
 rejection and advisory.
 
+Vale also moves from 3.21.0 to 3.22.0 in this release. Two things
+follow for existing Vale rules, both measured against both binaries;
+the rest of the release is additions a rule can now use.
+
+**`BasedOnStyles =` is deleted from every rule's `.vale.ini`, and
+`verify` rejects one that still carries it.** Every version of the
+`create-vale-rule` recipe before this one told you to write the line in
+every matcher. Through 3.21.0 it was inert: no bundled style loads
+unless a run-level `BasedOnStyles` names one, and the assembled header
+names none. Vale 3.22.0 gave an empty value a meaning (upstream
+c2d62437): it clears every setting the file inherited from an earlier
+matcher. Taskless assembles every rule's matchers into one file in id
+order, so under 3.22.0 a rule writing the line under `[docs/**]`
+silenced every alphabetically earlier rule under `docs/`, and `[*.md]`
+beside another rule's `[*.{md,markdown}]` silenced the first on every
+`.md` file, with nothing reported. Only rules whose globs were
+byte-identical escaped, because Vale merges those into one section.
+Running `%(TASKLESS_CLI)s init` applies migration 0008, which deletes
+every `BasedOnStyles` line from `.taskless/rules/vale/*/.vale.ini` and
+touches nothing else in the file; `check` and `verify` refuse to run
+until it has, naming `init`. Commit the rewritten configs. A config
+that still carries the key after that, from a hand edit or a rule
+copied in from elsewhere, fails `verify` under
+`vale-config-no-based-on-styles` and refuses the Vale engine at
+`check`, so the failure names the line rather than silencing a
+neighbour. Nothing about a rule's scope changes once the line is gone;
+the migrated config enables exactly what the old one did on 3.21.0.
+
+**A negated inline scope no longer sees the element's text.** A rule
+whose `scope` carries `~link`, `~strong`, `~emphasis` or `~code` still
+runs on the paragraph the element sits in, and the element's text is
+now blanked out of that paragraph before the rule sees it (upstream
+79a48752). Through 3.21.0 the negation only kept the rule off the
+element's own fragment, and the paragraph still carried the text, so a
+token inside a link or a bold span was reported from the paragraph.
+Findings inside those elements disappear; positions of findings after
+them do not move. If the rule was meant to reach link text after all,
+drop the negation. Search `.taskless/rules/vale` for a `scope:` line
+carrying `~link`, `~strong`, `~emphasis` or `~code` to find the rules
+to read.
+
+A `[formats]` key may now be a file name or a glob (upstream 6c2d99d9).
+No rule config can carry one, since the schema reads `[formats]` as a
+matcher named `formats` and rejects it, and the assembled header writes
+none, so nothing installed changes. A front-matter finding is now placed
+at the field's own position, every occurrence (5ab91a5d): a
+`frontmatter` rule that matched twice in one field reported the first
+match only; it now reports both. A `.yml` file that is itself a Vale
+rule has only its `message` and `description` linted as prose
+(f2785853); `check` never reaches `.taskless/rules/vale/`, so this
+touches only a project linting other styles under a `[*.yml]` matcher.
+A one-line MDX element's text is linted (49422de5), and a `spelling`
+rule with `split: true` checks the parts of an identifier and reports
+each at its own position (85992f2a); 3.21.0 accepted the key and did
+neither. `UNSET` as a rule's value behaves as `NO` and is not accepted
+by the schema; YES and NO remain the two values.
+
 ## Errors
 
 With `--json`, `--rules` failures emit `{ ok: false, code, message }`:

From e5147274a93ca5c9379028aec9b34030ef0cc830 Mon Sep 17 00:00:00 2001
From: Jakob Heuser <jakob@codedrift.com>
Date: Mon, 21 Sep 2026 16:07:05 -0700
Subject: [PATCH 5/5] spec(vale): archive vale-3-22-basedonstyles

Dry-run counted first: cli-vale-rule-engine 33 to 37 scenarios,
cli-rule-validation 31 to 32, cli-taskless-bootstrap 29 to 33 and 9 to
10 requirements, nothing dropped.
---
 .../proposal.md                               |  0
 .../specs/cli-rule-validation/spec.md         |  0
 .../specs/cli-taskless-bootstrap/spec.md      |  0
 .../specs/cli-vale-rule-engine/spec.md        |  0
 .../tasks.md                                  |  0
 openspec/specs/cli-rule-validation/spec.md    |  6 ++++
 openspec/specs/cli-taskless-bootstrap/spec.md | 29 +++++++++++++++++++
 openspec/specs/cli-vale-rule-engine/spec.md   | 28 ++++++++++++++++--
 8 files changed, 61 insertions(+), 2 deletions(-)
 rename openspec/changes/{vale-3-22-basedonstyles => archive/2026-09-21-vale-3-22-basedonstyles}/proposal.md (100%)
 rename openspec/changes/{vale-3-22-basedonstyles => archive/2026-09-21-vale-3-22-basedonstyles}/specs/cli-rule-validation/spec.md (100%)
 rename openspec/changes/{vale-3-22-basedonstyles => archive/2026-09-21-vale-3-22-basedonstyles}/specs/cli-taskless-bootstrap/spec.md (100%)
 rename openspec/changes/{vale-3-22-basedonstyles => archive/2026-09-21-vale-3-22-basedonstyles}/specs/cli-vale-rule-engine/spec.md (100%)
 rename openspec/changes/{vale-3-22-basedonstyles => archive/2026-09-21-vale-3-22-basedonstyles}/tasks.md (100%)

diff --git a/openspec/changes/vale-3-22-basedonstyles/proposal.md b/openspec/changes/archive/2026-09-21-vale-3-22-basedonstyles/proposal.md
similarity index 100%
rename from openspec/changes/vale-3-22-basedonstyles/proposal.md
rename to openspec/changes/archive/2026-09-21-vale-3-22-basedonstyles/proposal.md
diff --git a/openspec/changes/vale-3-22-basedonstyles/specs/cli-rule-validation/spec.md b/openspec/changes/archive/2026-09-21-vale-3-22-basedonstyles/specs/cli-rule-validation/spec.md
similarity index 100%
rename from openspec/changes/vale-3-22-basedonstyles/specs/cli-rule-validation/spec.md
rename to openspec/changes/archive/2026-09-21-vale-3-22-basedonstyles/specs/cli-rule-validation/spec.md
diff --git a/openspec/changes/vale-3-22-basedonstyles/specs/cli-taskless-bootstrap/spec.md b/openspec/changes/archive/2026-09-21-vale-3-22-basedonstyles/specs/cli-taskless-bootstrap/spec.md
similarity index 100%
rename from openspec/changes/vale-3-22-basedonstyles/specs/cli-taskless-bootstrap/spec.md
rename to openspec/changes/archive/2026-09-21-vale-3-22-basedonstyles/specs/cli-taskless-bootstrap/spec.md
diff --git a/openspec/changes/vale-3-22-basedonstyles/specs/cli-vale-rule-engine/spec.md b/openspec/changes/archive/2026-09-21-vale-3-22-basedonstyles/specs/cli-vale-rule-engine/spec.md
similarity index 100%
rename from openspec/changes/vale-3-22-basedonstyles/specs/cli-vale-rule-engine/spec.md
rename to openspec/changes/archive/2026-09-21-vale-3-22-basedonstyles/specs/cli-vale-rule-engine/spec.md
diff --git a/openspec/changes/vale-3-22-basedonstyles/tasks.md b/openspec/changes/archive/2026-09-21-vale-3-22-basedonstyles/tasks.md
similarity index 100%
rename from openspec/changes/vale-3-22-basedonstyles/tasks.md
rename to openspec/changes/archive/2026-09-21-vale-3-22-basedonstyles/tasks.md
diff --git a/openspec/specs/cli-rule-validation/spec.md b/openspec/specs/cli-rule-validation/spec.md
index 1fd51284..5cd76ba9 100644
--- a/openspec/specs/cli-rule-validation/spec.md
+++ b/openspec/specs/cli-rule-validation/spec.md
@@ -85,6 +85,12 @@ The failure it prevents is not a local one: Vale reports this as `E201: has inva
 - **WHEN** a Vale rule's `.vale.ini` declares matchers but no `<id>.<id> = YES`
 - **THEN** `verify` SHALL report that the rule is present but off, naming the file
 
+#### Scenario: A rule config that carries BasedOnStyles is rejected
+
+- **WHEN** a Vale rule's `.vale.ini` assigns `BasedOnStyles` in any matcher, with any value
+- **THEN** `verify` SHALL report it under `vale-config-no-based-on-styles`, naming the line
+- **AND** it SHALL NOT report the rule as valid
+
 #### Scenario: A rule config that assigns a foreign key is rejected
 
 - **WHEN** a Vale rule's `.vale.ini` assigns a `<style>.<check>` key naming a different rule
diff --git a/openspec/specs/cli-taskless-bootstrap/spec.md b/openspec/specs/cli-taskless-bootstrap/spec.md
index 981f8352..1ebf9708 100644
--- a/openspec/specs/cli-taskless-bootstrap/spec.md
+++ b/openspec/specs/cli-taskless-bootstrap/spec.md
@@ -240,3 +240,32 @@ Migration `7` SHALL add `/.tmp-*` to `.taskless/.gitignore` through the shared g
 
 - **WHEN** `.taskless/.gitignore` already contains `/.tmp-*` and migration 7 runs
 - **THEN** the file SHALL contain exactly one `/.tmp-*` line afterwards
+
+### Requirement: Migration 8 drops BasedOnStyles from Vale rule configs
+
+Migration `8` SHALL delete every `BasedOnStyles` assignment line from each `.taskless/rules/vale/<id>/.vale.ini`, whatever the value, and SHALL change nothing else in the file: every other line, comment, blank line and line ending SHALL be preserved byte for byte, and a comment that mentions `BasedOnStyles` SHALL be left alone. A config without the line SHALL NOT be rewritten. A project with no `rules/vale/` tree SHALL be left as it is. It SHALL NOT modify any shipped migration.
+
+The migration exists because the `create-vale-rule` recipe wrote `BasedOnStyles =` into every matcher through the release before this one, the config schema now rejects the key, and `check` and `verify` refuse to run on a scaffold behind the current version. Without the rewrite every upgraded project's first `check` would refuse the Vale engine over a line the CLI itself wrote.
+
+#### Scenario: An existing scaffold loses the line from every matcher
+
+- **WHEN** `taskless.json` records version 7, a rule's `.vale.ini` carries `BasedOnStyles =` in three matchers, and the CLI bootstraps `.taskless/`
+- **THEN** migration 8 SHALL run
+- **AND** the config SHALL contain no `BasedOnStyles` line and every other byte unchanged
+- **AND** the rewritten config SHALL pass the config schema
+- **AND** `taskless.json` SHALL record the latest schema version
+
+#### Scenario: A config without the line is untouched
+
+- **WHEN** a rule's `.vale.ini` carries no `BasedOnStyles` line and migration 8 runs
+- **THEN** the file SHALL NOT be written
+
+#### Scenario: A comment naming the key survives
+
+- **WHEN** a rule's `.vale.ini` carries a comment line that mentions `BasedOnStyles` and migration 8 runs
+- **THEN** the comment SHALL remain and only assignment lines SHALL be removed
+
+#### Scenario: Migration 8 is idempotent
+
+- **WHEN** migration 8 runs twice over the same scaffold
+- **THEN** the second run SHALL change nothing
diff --git a/openspec/specs/cli-vale-rule-engine/spec.md b/openspec/specs/cli-vale-rule-engine/spec.md
index 7d441e12..ffdbcb5d 100644
--- a/openspec/specs/cli-vale-rule-engine/spec.md
+++ b/openspec/specs/cli-vale-rule-engine/spec.md
@@ -142,6 +142,8 @@ A disable therefore SHALL be declared **after** the enable it narrows, within th
 
 A rule SHALL NOT be able to override another rule's matchers. It cannot know its own position in the assembled file, and cross-rule overriding through a shared file is the coupling the per-rule layout removes. The config schema enforces this: an assignment key naming any rule but the config's own is a rejection, at `verify` and at assembly.
 
+A rule's config SHALL NOT carry `BasedOnStyles`, with any value. Measured against Vale 3.22.0, an empty `BasedOnStyles` in a matcher clears every setting the file inherited from an earlier matcher, and in the assembled config "earlier" means every other rule whose glob reaches the file, so the line is a cross-rule override in the other direction: a rule writing it under `[docs/**]` silences every alphabetically earlier rule under `docs/`, and only two rules with byte-identical globs, which Vale merges into one section, escape. Through 3.21.0 the line was inert. A non-empty value loads a bundled style alongside every rule whose matchers overlap. Neither value has a job in a rule's config: Vale loads no bundled style unless a run-level `BasedOnStyles` names one, and the assembled header names none. The config schema rejects the key, and migration 8 deletes it from installed configs.
+
 #### Scenario: A rule scopes itself
 
 - **WHEN** a rule's own config enables it under `[marketing/**]`
@@ -169,6 +171,17 @@ A rule SHALL NOT be able to override another rule's matchers. It cannot know its
 - **WHEN** two rules each declare a `[*.md]` matcher
 - **THEN** both rules run on a matching `.md` file (Vale merges the matchers)
 
+#### Scenario: Overlapping matchers do not interfere
+
+- **WHEN** one rule declares `[*.md]` and another declares `[docs/**]`, and neither config carries `BasedOnStyles`
+- **THEN** both rules run on a matching file under `docs/`
+
+#### Scenario: A BasedOnStyles line is refused rather than assembled
+
+- **WHEN** a rule's config carries `BasedOnStyles =` in any matcher
+- **THEN** `verify` SHALL reject the rule under `vale-config-no-based-on-styles`, naming the line
+- **AND** the Vale run SHALL be refused rather than assembled with the line, which on the pinned Vale would silence every earlier rule under that matcher's files
+
 #### Scenario: A rule cannot assign another rule's key
 
 - **WHEN** `no-simply/.vale.ini` assigns `no-hedging.no-hedging = NO`
@@ -211,10 +224,10 @@ The schema SHALL reject a config that:
 - declares a matcher without a `tskl) rule = <id>` breadcrumb naming this rule
 - assigns a key other than `<id>.<id>` (a `<style>.<check>` key naming any other rule is a cross-rule override)
 - assigns a value other than `YES` or `NO`
-- sets `BasedOnStyles` to anything but empty
+- assigns `BasedOnStyles`, with any value, empty included (on Vale 3.22.0 an empty value clears every earlier matcher's settings for the file, which in the assembled config silences every other rule whose glob reaches it; a named style loads alongside every overlapping rule; and no rule config ever needed either, since no bundled style loads unless a run-level `BasedOnStyles` names one)
 - declares no matcher
 - never assigns `<id>.<id> = YES` in its final per-matcher verdicts (matchers with the same glob are folded, as Vale merges them, and the last assignment wins, so a `YES` that a later `NO` in the same matcher overrides does not count)
-- declares a `NO`-verdict matcher before every `YES`-verdict matcher (with `BasedOnStyles` empty a rule is off until a `YES`, so such a `NO` is either dead or overridden by the `YES` that follows; no config means it)
+- declares a `NO`-verdict matcher before every `YES`-verdict matcher (no style is loaded, so a rule is off until a `YES`, and such a `NO` is either dead or overridden by the `YES` that follows; no config means it)
 
 The schema SHALL report, without rejecting, a config that:
 
@@ -249,6 +262,17 @@ Assembly SHALL write each accepted config's source verbatim. The parsed structur
 - **WHEN** a rule's config declares `[docs/legacy/**]` with `<id>.<id> = NO` and then `[docs/**]` with `<id>.<id> = YES`
 - **THEN** `verify` SHALL reject the rule, naming the `NO` matcher and the `YES` that re-enables it
 
+#### Scenario: A BasedOnStyles assignment is rejected
+
+- **WHEN** a rule's config sets `BasedOnStyles =` inside a matcher
+- **THEN** `verify` SHALL reject the rule under `vale-config-no-based-on-styles`, naming the line and saying that the line silences the other rules whose globs overlap
+- **AND** a `BasedOnStyles` naming a style SHALL be rejected under the same constraint
+
+#### Scenario: A [formats] section is rejected as a matcher it cannot be
+
+- **WHEN** a rule's config declares a `[formats]` section
+- **THEN** `verify` SHALL reject it for the breadcrumb it lacks and the foreign key it assigns, so no rule config can move a file between parser tiers
+
 #### Scenario: A repeated key is reported, not rejected
 
 - **WHEN** one matcher assigns `<id>.<id> = YES` and then `<id>.<id> = NO`, and an earlier matcher assigns `<id>.<id> = YES`