From 9cd447ff9656571703f23634d05d3811ac9572c5 Mon Sep 17 00:00:00 2001 From: Tony Burns Date: Mon, 23 Feb 2026 21:30:04 -0500 Subject: [PATCH 1/5] fix: use lint-prose instead of non-existent lint-prose-summary, default to whole project - SKILL.md: replace `just lint-prose-summary` with `just lint-prose` - linter-output.md: replace fictitious summary format with standard vale output - Justfile: change lint-prose default from `README.md` to `.` --- .claude/skills/fix-docs/SKILL.md | 6 +- .../skills/fix-docs/examples/linter-output.md | 69 ++++++------------- Justfile | 2 +- 3 files changed, 25 insertions(+), 52 deletions(-) diff --git a/.claude/skills/fix-docs/SKILL.md b/.claude/skills/fix-docs/SKILL.md index d00c47b..2f22f32 100644 --- a/.claude/skills/fix-docs/SKILL.md +++ b/.claude/skills/fix-docs/SKILL.md @@ -26,10 +26,10 @@ Run both linters against the target files. Capture the full output from each com **Prose linting (`vale`)**: -- With files: `just lint-prose-summary ...` -- Without files: `just lint-prose-summary` +- With files: `just lint-prose ...` +- Without files: `just lint-prose` -This prints a structured summary with sections: total counts, findings by file, findings by rule, spelling words to add, and all findings grouped by file. The summary output is already categorized, so you can proceed directly to fixing. +Vale prints each finding as `file:line:col: severity rule message`. Review all findings and proceed to fixing. If both linters return zero findings, report success and stop. diff --git a/.claude/skills/fix-docs/examples/linter-output.md b/.claude/skills/fix-docs/examples/linter-output.md index b8019ff..b29ebd8 100644 --- a/.claude/skills/fix-docs/examples/linter-output.md +++ b/.claude/skills/fix-docs/examples/linter-output.md @@ -15,60 +15,33 @@ Run `rumdl fmt` to automatically fix 3 of the 3 issues Each line follows the pattern `file:line:column: [RULE] description [*]`. The `[*]` suffix means the finding supports auto-fix via `rumdl fmt`. -## `vale` summary output (`just lint-prose-summary`) +## `vale` output (`just lint-prose`) ```text -## 6 findings (2 error, 4 warning) - -### By file - 3 docs/CONCEPT.md - 3 docs/design/overview.md - -### By rule - 2 write-good.TooWordy - 2 Vale.Spelling - 1 little-matches.Headings - 1 ai-tells.HedgingPhrases - -### Spelling (2 words to add to vocabulary) - metareasoning - skeuomorphic - -### Findings - - docs/CONCEPT.md - 12:1 w little-matches.Headings: 'Key Design Decisions' should use sentence-style capitalization. - 45:15 e Vale.Spelling: Did you really mean 'metareasoning'? - 78:5 w write-good.TooWordy: 'in order to' is too wordy. - - docs/design/overview.md - 3:20 e ai-tells.HedgingPhrases: AI hedge: 'it is important to note that'. Delete this throat-clearing and state your point directly. - 15:8 e Vale.Spelling: Did you really mean 'skeuomorphic'? - 22:12 w write-good.TooWordy: 'due to the fact that' is too wordy. + docs/CONCEPT.md + 12:1 warning 'Key Design Decisions' should little-matches.Headings + use sentence-style + capitalization. + 45:15 error Did you really mean Vale.Spelling + 'metareasoning'? + 78:5 warning 'in order to' is too wordy. write-good.TooWordy + + docs/design/overview.md + 3:20 error AI hedge: 'it is important to ai-tells.HedgingPhrases + note that'. Delete this + throat-clearing and state your + point directly. + 15:8 error Did you really mean Vale.Spelling + 'skeuomorphic'? + 22:12 warning 'due to the fact that' is too write-good.TooWordy + wordy. ``` -The summary is pre-categorized into sections: +Each finding shows `line:col severity message rule`. Findings are grouped by file. -- **By file** — which files need work and how many findings each -- **By rule** — what categories of fixes are needed -- **Spelling** — words to add to the vocabulary accept list (only present when there are spelling findings) -- **Findings** — all findings grouped by file, one line each: `line:col severity rule: message` - -Severity codes: `e` = error, `w` = warning, `s` = suggestion. +Severity levels: `error`, `warning`, `suggestion`. Use the rule name to categorize: -- `Vale.Spelling` or `Google.Spelling` = vocabulary finding (listed in the Spelling section) +- `Vale.Spelling` or `Google.Spelling` = vocabulary finding (add the word to the accept list) - `little-matches.Headings`, `write-good.*`, `Google.*`, `proselint.*`, `ai-tells.*` = prose style finding - -### Filtering - -The summary script supports `--file` and `--rule` flags for filtered views: - -```bash -# Show only findings for a specific file -uvx vale --output=JSON --no-exit . | python3 tools/vale_summary.py --file CONCEPT.md - -# Show only findings for a specific rule -uvx vale --output=JSON --no-exit . | python3 tools/vale_summary.py --rule Spelling -``` diff --git a/Justfile b/Justfile index c8a4083..f46bae6 100644 --- a/Justfile +++ b/Justfile @@ -62,7 +62,7 @@ lint-markdown *args: # Lint prose in Markdown files lint-prose *args: - vale {{ if args == "" { "README.md" } else { args } }} + vale {{ if args == "" { "." } else { args } }} # Check spelling lint-spelling: From 0dc5a90514695457d4d8e8692022d27a5e3a62b8 Mon Sep 17 00:00:00 2001 From: Tony Burns Date: Wed, 25 Feb 2026 01:19:53 -0500 Subject: [PATCH 2/5] ci: add lint workflow --- .github/workflows/ci.yml | 66 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..93c46bf --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,66 @@ +--- +name: CI + +on: + pull_request: + branches: [main] + push: + branches: [main] + workflow_dispatch: + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + lint: + name: Lint + runs-on: ubuntu-latest + timeout-minutes: 15 + + steps: + - name: Checkout code + uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + + - name: Install uv + uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1 + + - name: Install Biome + uses: biomejs/setup-biome@1cbe33ead22c7a2fded3b52fa2893611c815c9b5 # v2.5.0 + + - name: Install just + uses: extractions/setup-just@e33e0265a09d6d736e2ee1e0eb685ef1de4669ff # v3 + + - name: Install rumdl + run: | + url="https://github.com/rvben/rumdl/releases/download" + url="${url}/v0.1.26/rumdl-v0.1.26-x86_64-unknown-linux-gnu.tar.gz" + curl -fsSL "${url}" | tar xz + sudo mv rumdl /usr/local/bin/ + + - name: Install linting tools + run: | + uv tool install yamllint + uv tool install codespell + + - name: Cache Vale styles + uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3 + with: + path: .vale + key: vale-styles-${{ hashFiles('.vale.ini') }} + restore-keys: | + vale-styles- + + - name: Install and sync Vale + run: | + uv tool install vale + vale sync + + - name: Run linters + run: just lint + + - name: Lint GitHub Actions workflows + uses: reviewdog/action-actionlint@4b9ef3f43a0b9162e3c83c1a08d1cc8d4235164b # v1.70.0 From 48427830d951575f249e697dc72e7b1ab1a83cc6 Mon Sep 17 00:00:00 2001 From: Tony Burns Date: Wed, 25 Feb 2026 01:21:48 -0500 Subject: [PATCH 3/5] ci: install just via curl instead of setup-just action --- .github/workflows/ci.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 93c46bf..4973077 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -32,7 +32,10 @@ jobs: uses: biomejs/setup-biome@1cbe33ead22c7a2fded3b52fa2893611c815c9b5 # v2.5.0 - name: Install just - uses: extractions/setup-just@e33e0265a09d6d736e2ee1e0eb685ef1de4669ff # v3 + run: | + url="https://github.com/casey/just/releases/download" + url="${url}/1.46.0/just-1.46.0-x86_64-unknown-linux-musl.tar.gz" + curl -fsSL "${url}" | tar xz -C /usr/local/bin just - name: Install rumdl run: | From 62b1d194da5dff6eddced5189ea7bd82067371ee Mon Sep 17 00:00:00 2001 From: Tony Burns Date: Wed, 25 Feb 2026 01:27:26 -0500 Subject: [PATCH 4/5] ci: pin biome version to 2.3.2 to match repo config --- .github/workflows/ci.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 4973077..37762bb 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -30,6 +30,8 @@ jobs: - name: Install Biome uses: biomejs/setup-biome@1cbe33ead22c7a2fded3b52fa2893611c815c9b5 # v2.5.0 + with: + version: 2.3.2 - name: Install just run: | From aa5981a340ec6b9f136ec8138a90adf2524c16b6 Mon Sep 17 00:00:00 2001 From: Tony Burns Date: Wed, 25 Feb 2026 01:29:05 -0500 Subject: [PATCH 5/5] ci: install biome 2.3.2 via direct download --- .github/workflows/ci.yml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 37762bb..eca25f1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -29,9 +29,12 @@ jobs: uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1 - name: Install Biome - uses: biomejs/setup-biome@1cbe33ead22c7a2fded3b52fa2893611c815c9b5 # v2.5.0 - with: - version: 2.3.2 + run: | + tag="%40biomejs/biome%402.3.2" + url="https://github.com/biomejs/biome/releases/download" + curl -fsSL "${url}/${tag}/biome-linux-x64" -o biome + chmod +x biome + sudo mv biome /usr/local/bin/ - name: Install just run: |