create-vale-rule: document the pitfalls that pass every local gate

[theCodeDrift]

A place to accumulate what goes wrong when authoring Vale rules, so the recipe can prevent it rather than each author rediscovering it.

The organizing principle: everything below passes verify and test. That is what makes these worth documenting. A malformed Vale rule is caught immediately; a wrong one is silent, ships green, and is discovered when someone notices the rule has never reported anything. The recipe already documents the %s interpolation trap on exactly this basis — these are the same class.

Each entry is measured against the pinned binary, not reasoned from the docs.

---

1. A token made of punctuation needs nonword: true

Vale wraps every token in word boundaries. An em dash is non-word on both sides, so \b—\b can never match.

extends: existence
level: error
tokens: ['—', '–']          # parses, verifies, and never fires

Adding nonword: true fixes it. Measured both ways: without it the fail/ fixture does not fire and test reports the rule as passing its own fixtures only because nothing fires anywhere.

This one bit us for real — the em-dash rule specified in #104 carries exactly this shape, so it would have shipped as a no-op.

Rule of thumb for the recipe: if a token is not made of word characters, it needs nonword: true.

2. The scope table, measured

scope	prose	inline code	fenced block
text	✓
code		✓
[code, text]	✓	✓
raw	✓	✓	✓

raw subsumes the other two, so a bare raw and [raw, code, text] behave identically.

3. scope is per-rule, and rules do not interfere

Vale assembles one config for the whole run, which makes it reasonable to assume scopes interact. They do not. Same document, same run: a default-scoped rule stayed out of a fenced block and honored a suppression comment, while a raw-scoped rule read through both.

Worth stating in the recipe explicitly, because the assumption otherwise discourages using raw at all.

4. raw and Vale's suppression comments are mutually exclusive

scope	<!-- vale Style.Rule = NO --> honored
[raw, code, text]	no
[code, text]	yes

Under raw Vale reads the unparsed text, so a markup-level directive is invisible. A rule that reaches into fenced blocks cannot be annotated away case by case — which matters because a rule about a command needs raw (see #167). Detail in the comment on that issue.

5. Prefer collocations to bare words

A token that is a whole word will find the sense you did not mean, and the near-miss is rarely the one you predicted. #104 anticipated this for land/landed and proposed landed on as a safe narrowing. Measured, landed on fires on "the plane landed on time" — the literal sense the issue was protecting. we landed already covered the decision sense, so the broader token added only false positives.

For the recipe: when narrowing a banned word to a collocation, write the pass/ fixture from the literal sense first, then check the collocation against it.

6. Fixture design should follow the rule's subject

The recipe says a pass/ fixture must contain the phrase outside the scope being narrowed. The converse is missing and is what catches #167: when the rule's subject normally appears in code, the fail/ fixture must contain it inline, fenced, and in prose. A fixture written only as prose passes while the rule is inert against every real document.

7. How to exclude files from a rule

The recipe explains how to scope a rule in, and never how to scope it out. A second matcher with = NO works:

[**/README.md]
tskl) rule = my-rule
BasedOnStyles =
my-rule.my-rule = YES

# Test fixtures are inputs to a test suite, not documentation.
[**/test/fixtures/**/README.md]
tskl) rule = my-rule
BasedOnStyles =
my-rule.my-rule = NO

Measured working, and needed immediately: without it the first house-style rules fired on the CLI's own test fixtures, which hold deliberately wrong prose. #104 anticipates the need and does not say how.

---

Refs #167
Refs #104

[theCodeDrift]

8. Passing fixtures do not prove the rule reaches any real file

verifyValeRule builds an isolating .vale.ini in a temp directory and runs the fixtures under that, not under the rule's own config. So test answers "does the pattern behave" and says nothing about whether the rule's .vale.ini matcher reaches a single file in the repository.

The gap is narrower than it sounds, because verify already catches two adjacent cases — a rule with no .vale.ini, and a .vale.ini that never enables <id>.<id>. What survives both is a matcher whose glob matches nothing: a typo'd directory, a path that moved, a **/ where the tree needs *. The rule is well-formed, enabled, green on its fixtures, and inert.

Hit while adding a rule scoped to [packages/cli/src/**/*.ts]. It reported zero findings, which was the correct answer — but indistinguishable from a scoping failure until reach was checked separately, by planting a matching comment in a real source file and re-running check.

For the recipe: after a rule passes test, confirm reach against a real file before believing a clean check. Better, for verify: report the number of project files each matcher selects. Zero is almost always a defect, and it is cheap to compute at the point where the config is already being assembled.

9. A rule about source comments needs .ts fixtures, and those fight the repo's linters

Vale decides its comments-only tier by extension, so a rule about TypeScript comments must have .ts fixtures. Those files belong to no tsconfig, and type-aware ESLint fails on them:

Parsing error: .../\.tests/fail/probe.ts was not found by the project service.
Consider either including it in the tsconfig.json or including it in allowDefaultProject

lint-staged then blocks the commit that adds the rule. The fix is one ignore entry (.taskless/ in eslint.config.js and .prettierignore), and it generalizes: rule fixtures are inputs written to be flagged, so every root-level linter in a repository will eventually trip over them. Worth a line in the recipe, since the failure arrives at commit time rather than while authoring, and reads as a TypeScript problem rather than a Taskless one.