Add Vale for prose linting - #102
Merged
Merged
Conversation
Lints the repo's Markdown against the Microsoft style package, with a project vocabulary for domain terms and code identifiers that appear in prose. A few deliberate scoping decisions: - Microsoft.Dashes is off. We write spaced em dashes throughout, and that one rule accounted for 70 of the initial 210 alerts. - Generated planning/spec artifacts under docs/superpowers/ and the gitignored .claude/ tree are excluded; neither is hand-written prose. - TokenIgnores skips URLs and Slack channel handles, so the lowercase repo name in a clone command isn't read as a miscased product name. CI is advisory only: the workflow reports findings in the job summary but always exits green, so a style nit never blocks a merge. It judges the result by whether Vale printed anything rather than by exit status, since Vale exits non-zero only for errors and warnings alone would otherwise look like a pass. Vale is pinned in mise.toml so CI and local runs match. Also corrects "Docuseal" to "DocuSeal" in three places, which is what turned the linter up in the first place.
leowilkin
enabled auto-merge (squash)
September 1, 2026 15:29
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Lints the repo's Markdown against the Microsoft style package, with a project vocabulary for domain terms and code identifiers that appear in prose.
Scoping decisions
A stock Microsoft config produced 210 alerts, most of them noise. Three deliberate narrowings:
Microsoft.Dashesis off. We write spaced em dashes throughout. That one rule was 70 of the 210 — it's our house style, not a defect.docs/superpowers/and the gitignored.claude/tree. Neither is hand-written prose.TokenIgnoresskips URLs and Slack channel handles, so the lowercase repo name in agit clonecommand isn't read as a miscased product name.Ordinary words that can start a sentence are written as regexes in the vocabulary (
[Ss]afeguarding,[Oo]nboarding) soVale.Termsdoesn't demand one fixed casing.CI is advisory only
The workflow reports findings in the job summary but always exits green, so a style nit never blocks a merge and it won't show up as a required check.
It judges the result by whether Vale printed anything rather than by exit status — Vale exits non-zero only for errors, so a warnings-only run would otherwise report a false pass. Vale is pinned in
mise.tomland installed viajdx/mise-action, so CI and local runs use the same version.Also
Corrects
DocusealtoDocuSealin three places (README twice, AGENTS once) —PRODUCT.mdalready had it right. This inconsistency is what the linter turned up first.Current state on
mainis 31 errors and 25 warnings across 15 files, down from 210. I left those for follow-up rather than tuning them away — they're judgment calls about voice (contractions, adverbs,e.g.vsfor example), not config problems.One known false positive worth flagging:
Microsoft.Termswants "personal digital assistant" instead of "Agent" inAGENTS.md:1. Harmless while CI is non-blocking;Microsoft.Terms = NOwould kill it if it gets annoying.