Repository navigation

ci: lint documentation prose with Vale - #84

Merged

howmanysmall merged 26 commits into

mainfrom

chore/vale-prose-linting

Oct 7, 2026

Merged

ci: lint documentation prose with Vale#84
howmanysmall merged 26 commits into
mainfrom
chore/vale-prose-linting

howmanysmall commented Oct 7, 2026 •

edited

Loading

Owner

Summary

ci.yaml
  vale
    setup toolchain (vale)
    vale sync
    vale --no-color .

Packages in .vale.ini is the style source. Synced styles stay gitignored. The tracked vocabulary is hooks, God, and simple.

 published docs
-  first person ("I made `@pobammer-ts/small-rules`")
+  impersonal voice

Rule rationale pages were rewritten so they pass Google, ai-tells, alex, and proselint. Agent skills, docs/, migrations, release notes, and the agent meta docs stay on spelling-only Vale. Zed's Markdown and MDX buffers include the vale language server. mise installs vale and vale-ls.

Evidence

Before: the introduction said "I made @pobammer-ts/small-rules" and CI did not run Vale. The first Vale run failed on tracked docs/ and migrations/ prose.
After: those paths are spelling-only. git ls-files | xargs vale --minAlertLevel=error exits 0 with no errors. A clean checkout of vale --no-color . matches that. A dirty local tree still fails, because Vale walks untracked copies under .claude/skills/ and plans/.

Merge Danger

Door: two-way

The job, .vale.ini, and the wording revert cleanly. No rule behavior changes.

Blast Radius: CI

Later Markdown and MDX edits fail the Vale job, except the spelling-only paths. Consumers of the published rules are unaffected.

howmanysmall added 25 commits

October 7, 2026 15:19


          chore(tools): add vale-ls language server via mise

d9825b2

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          docs: update README and rule docs wording

4b58d41

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(editor): add vale prose linter to zed and ignores

f10f7a1

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(zed): remove vale language server settings

9e2a7c1

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          docs(anti-slop): reword rule rationales to drop first-person voice

333227b

Replace "I" and "I'd" phrasing in the anti-slop rule docs with neutral,
impersonal prose. Also fix a few inline code spans and minor wording
issues while touching these files.

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          docs(rules): clarify wording in english rule rationales

d3c84cb

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          docs(rules): clarify wording in general rule documentation

e81ea00

Rename several rule titles to use plainer terms ("Turn Off" for
"Disable", "Unread Store" for "Dead Store", "Regular Expressions" for
"Regex"), and reword rationale text across multiple rule pages for
clarity, replacing first-person phrasing and converting raw links to
inline anchors.

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          ci: install vale in checks workflow

712c3aa

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          docs(rules): use backticks for inline code in rule pages

88bebb3

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(vale): expand prose linting rules and styles

2360cfb

Enable suggestion-level alerts and add Google, Microsoft, RedHat, alex,
proselint, and write-good styles. Extend coverage to MDX and TSX files,
and tailor rules for README and project meta-docs.

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          build(vale): enable Readability package and update token ignores

b10c472

Add the Readability package and base the markdown style on it. Drop the
AsciiDoc package and the mdx-to-md format mapping, and widen the mdx
TokenIgnores pattern to also skip inline code spans.

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(vale): tune prose linting rules for markdown

d978e4b

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          docs(changelog): reword release process description

a3ea09d

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(vale): disable prose rules for release notes

a4c39bc

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          docs: tighten wording across rule rationale pages

a5dfae6

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(vale): track project vocabulary and ignore synced styles

5fa54a6

Only the Project vocabulary is committed. Other Vale style content is
downloaded at runtime, so ignore it and re-include just the custom
accept list.

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(vale): accept project vocabulary and tune style rules

716b69d

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          ci: add Vale prose linting job for markdown and docs

Add a Vale job to the CI workflow that lints markdown, MDX, and
documentation files. Styles are fetched from the packages declared in
.vale.ini at runtime, since the .vale/styles directory is gitignored.

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          docs: rewrite docs in impersonal voice

41bafab

Replace first-person narration in the documentation with neutral,
direct wording across the configuration, introduction, index, and
quick-start pages. Also fix a few small inconsistencies such as the
missing hyphen-free "Turn a rule off inline" heading wording and the
"Pass rule options" intro duplication.

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(vale): accept simple as a project vocabulary term

131e5b7

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(vale): skip spelling checks for agent skill docs

9c7cf4c

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(vale): disable prose lint rules for agent skills

f93ba56

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          docs: reflow prose and table padding in rule documentation

22a02c0

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          build(skills): update computed hashes for dry-refactoring and fallow

869fe5f

Refresh the computedHash entries for the dry-refactoring and fallow
skills in skills-lock.json to match their current upstream SKILL.md
content.

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>


          chore(tools): move vale-ls to top of tool list

1283ee2

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>

github-actions Bot commented Oct 7, 2026 •

edited

Loading

Contributor

Bundle size

Artifact	Base	Pull request	Change
`dist/index.js`	484.18 kB	484.18 kB	0 B (+0.00%)

_{Raw, uncompressed bytes from the minified prepublishOnly build. Measured for commit 9a9eb3f against base 8c1b798.}


          chore(vale): extend ignore scope to docs and migrations

9a9eb3f

Signed-off-by: howmanysmall <26746527+howmanysmall@users.noreply.github.com>

howmanysmall merged commit 3bfa142 into main

8 checks passed

howmanysmall deleted the chore/vale-prose-linting branch

October 7, 2026 22:52

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet