[theCodeDrift]

Stack (root → tip):

• chore(vale): upgrade to Vale 3.24.0 #546
  • ➡️ fix(vale): make the Vale 3.24.0 upgrade land green, and refuse a rule's tests: key #549 (you are here)
    • feat(update): move a Vale rule's tests: cases into fixtures on 3.24.0 #551

#546 moves the six @taskless/vale-* pins to Vale 3.24.0. Run locally it has 10 failures, not the 8 its report lists: the report runs only the contract suites, and the two it missed were a real break for users. This PR makes the upgrade correct and pins what 3.24.0 changed. It merges down into vendor/vale/upgrade, so the pin, the fixes and the guidance reach main together.

The break the report missed

Vale 3.24.0 warns about every key it does not recognise inside a matcher (upstream validateLevel). That includes the tskl) rule = <id> breadcrumb every rule's .vale.ini carries:

W101 'tskl) rule' isn't a section option; Vale is ignoring it.

Two effects:

• Every check printed one notice per matcher.
• The warning lands on stderr ahead of a fatal error's JSON, so the JSON no longer parsed. That threw away the error's Path and with it the One unparseable file zeroes findings for the whole check run #300 narrowing. One file with bad front matter took every other file's Vale findings down again (mixed-engine-check caught it).

Fix, at assembly, with no migration. valeRuleBlock puts # in front of each breadcrumb line, at the lines the config schema already located (breadcrumbLines on the verdict). Nothing searches the text. Line counts are kept, so a line Vale reports is still the author's. Rule files on disk and recipes are unchanged.

And in runVale. Vale's leading W\d{3} lines are peeled off before its error is parsed, so a user's own warning (3.24.0 also warns on <id>.<id> = maybe) cannot block the narrowing either. Each warning is now its own notice.

The 8 reported failures

The converter E100 dropped its checker tag. [lintAdoc] Runtime error is now asciidoctor not found; it's needed to read AsciiDoc. The run still dies the same way (exit 2, --no-exit does not help), and only the test read the tag. VALE_CONVERTER_CHECKERS becomes VALE_CONVERTER_READERS, keyed to the format Vale names. .xml keeps its host split: where xsltproc is present it reports the missing stylesheet instead.

What changed that no test caught

A new Vale 3.24.0 block in vale-vendor-contract.test.ts, each case run against 3.22.0 and 3.24.0 on the same fixture:

	3.22.0 / 3.23.0	3.24.0
unknown key in a matcher	silent	W101
# tskl) rule comment in a matcher	silent	silent
warnings, then a fatal error	(no warnings)	W101 lines, then the JSON
C# // ReSharper disable, // NOSONAR	linted	not read
word after a link and U+00A0	fused, unmatched	matched
.adoc where every rule is NO	aborts the run	not parsed

The new C# reader the report flagged (code/cs.go) moves no tier. .cs and .csx were already comment rows, read with the C grammar. Conditional sections ([*.md if .Meta.draft]) pass validate and work in check as-is.

tests: is refused

Vale 3.24.0 ships vale test, which runs cases written in a rule's tests: list. Taskless never runs it: verify judges a Vale rule by its .tests/pass and .tests/fail documents. validate and verify now reject the key rather than let a rule read as tested by cases nothing runs. check still runs such a rule. The vocabulary keeps tests, since Vale reads it, and the corpus row moves to DIVERGENCES so the disagreement is counted.

A deterministic rule migration that turns each case into a fixture follows as its own PR on #548's update --rules mechanism, now on main. Until then the ledger gives the steps by hand.

Guidance

• update (topic v18): the Vale entries are folded into the ### Migrating to 0.13.3 section the ast-grep stack (chore(ast-grep): upgrade to ast-grep 0.51.0 #545/test(ast-grep): make the ast-grep 0.51.0 upgrade land green #548) put on main, after its paragraphs, and the opener names both engines. The header stays v18, since both ship in one release. The opener says the one thing needing work by hand is a Vale rule carrying tests:, until the migrator lands.
• The changeset on chore(vale): upgrade to Vale 3.24.0 #546 is extended, not duplicated, and stays patch.

Checks

pnpm typecheck, pnpm lint and pnpm test (2497 passed) are green locally on this branch, rebased onto main with ast-grep 0.51.0 and built.

Not in this PR

• The upgrade report could also run vale-run and mixed-engine-check, which would have caught the two failures it missed.

Refs #546

Contains #551

#549 makes validate and verify refuse a Vale rule's tests: key. 0.12.0 had accepted it, so a rule written since then would stop validating on upgrade. This adds a rule migration on #548's mechanism, so update --rules moves those cases into fixtures instead of leaving the author a by-hand list. It merges down into vendor/vale/3-24-0-contract.

What it does

src/rules/rule-migrations/vale-3-24-0-tests-to-fixtures.ts, registered in RULE_MIGRATIONS, keyed on Vale 3.24.0. It runs when the recorded Vale engine is below 3.24.0.

A case is a document and whether the rule fires on it, which is exactly a fixture. An in-rule case loads only its own rule, so any alert it expects is that rule's:

the case	becomes
want with any text	.tests/fail/
want that is empty	.tests/pass/
no want, but contains	.tests/fail/
only absent	.tests/pass/

• The fixture: the case's input, byte for byte. It is named for the case (flags a hedge → flags-a-hedge.md), with format as the extension (md by default, as Vale reads it). What want pins beyond that (line, column, message) is not something verification needs, and it is not carried.
• The rule file: the tests: block is removed by its byte range from the YAML parser. Nothing is re-serialized, so comments and every other line stay as written.
• Safe to rerun: fixtures are written before the rule file. A fixture with identical bytes counts as done, and a different file with the same name gets -2. A rerun, or a run that died between the two steps, changes nothing it already did.
• Left alone: a rule with a case that reads through a view (this layout defines none) or names another rule file in rule:. Moving half its cases would be harder to finish than none. validate keeps naming that rule.

Issued rules

Per the rule-migration contract, the rewrite only applies to shapes the service never issued. Nothing in the Cloud corpus carries tests: (confirmed 2026-10-20), so no signed rule is touched. Rules users wrote themselves are what this is for.

Guidance

• update (topic v18): the 0.13.3 opener is back to "Nothing here needs work by hand." The tests: paragraph now reads like the Haskell one: update --rules moves them for you, so don't do it by hand. It names the view and rule: cases as the exception.
• The changeset on chore(vale): upgrade to Vale 3.24.0 #546 gains one sentence.

Tests

• rule-migrate.test.ts: block removal for an indented list, a list at the key's column, a blank line inside, and a block ending the file with no newline. The bucket for each kind of case, naming and extensions, the rules it leaves alone, idempotence, finishing an interrupted run, never overwriting, failing on an unreadable rules tree, and keying on 3.24.0. A migrated rule passes validateValeRule.
• reconcile-marker.test.ts: update --rules through the built CLI moves the cases, reports the files, and stamps the engines.
• Two existing Haskell migration tests now record the current Vale version. They recorded only sg, so the Vale migration also read as pending in them.

pnpm typecheck, pnpm lint and pnpm test (2526 passed) are green locally, built.

Refs #549