.vale.ini's own comments named the issues that gated
write-good.Passive, but the tracker-tag lint's extension list didn't
cover .ini, so it never caught its own violation. Extend the scope
and reword the comment to prose that stands on its own.
Both blockers are done — #4548 (353 hits in hand-written docs) and
#4549 (46 hits in generated CLI reference docs, hivectl/swarmctl/hive-forge's
own clap help text) — and the previous commit suppresses the reviewed
false-positive remainder. vale --minAlertLevel=error docs now returns
0 errors, matching CI's existing prose-lint-errors job.
Closes#4546.
HeadingColons conflicts with this repo's sentence-case heading
convention -- same shape as the existing Dashes disable, a house-style
conflict rather than a defect.
Percentages had zero true positives on the full docs/ tree: it only
ever fired on identifier uses of "percent" (cpu.percent, percent
resolver), never on an actual spelled-out percentage.
Plurals: rewrote the two real hits to always use the plural form
instead of the parenthetical (s) construction, per house style.
mara's review, addressed with evidence not assertions:
- Microsoft.Contractions: re-enabled per her flat disagreement, no
argument.
- Microsoft.Passive vs write-good.Passive: she asked what the
difference actually is. Ran both individually against the full
docs/ tree and diffed the exact file:line:col sets -- 726/726
identical, zero difference either direction. Genuinely redundant,
not assumed. write-good.Passive stays enabled (agreed base style),
Microsoft.Passive drops as the literal duplicate.
- write-good.Passive: she disputed my invented examples (correctly --
a clean single-actor rewrite does read better active). Pulled 10
real hits from the actual docs tree instead of inventing more
sentences; most have a generic/implicit actor where passive reads
naturally, not a clear active-voice win. Re-enabled per the
redundancy point above rather than disabled as "mostly noise".
- Microsoft.Dashes: same outcome (stays disabled, retrofitting ~2000
existing occurrences is out of scope here) but the reasoning was
wrong -- not a "deliberate convention", an incidental one nobody
chose. Rewritten.
- Microsoft.Adverbs, alex.ProfanityUnlikely, write-good.E-Prime,
Microsoft.HeadingAcronyms: moved to an explicit "wave 2 candidates"
section -- disabled for this rollout, not dismissed. Each needs a
real false-positive-rate pass or an actual rewrite pass through the
flagged instances before a permanent call.
- Dropped the .vale.ini header's pointer to "the PR description" for
rationale -- not durable/visible enough as a reference from a file
that lives in the repo. Rationale is now fully inline per rule.
1069 more hits than the previous round (726 write-good.Passive + 343
Contractions, Microsoft.Passive's 726 removed) -- 1732 total across 50
files.
