build(lint): enforce WH001 everywhere, drop vendored skill - #522
Conversation
#502 dropped the Go Coverage badge from the README but left everything that fed it running: the non-gating `badge` job kept firing on every main push, holding ci.yml's only `contents: write`, publishing coverage-go.json to the orphan `badges` branch for a badge no page rendered. Retire rather than restore (#509). Removes the `badge` job, its two producer steps in `coverage`, scripts/ci/publish-badge.sh, and the `cov badge` subcommand. The coverage GATE is untouched — make cov, threshold.total, per-suite minima, and the Code Quality PR comments all still run; only the published badge surface is gone. ci.yml now declares no `contents: write` in any job. Also fixes a latent break this surfaced: `timing`'s needs still listed `badge`, which is a workflow-level error once the job is gone. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MB4oPy9yfUHSe8FjnDmeZH
Four documentation-accuracy fixes from the pre-push code and docs reviewers, both of which independently flagged the first two: - The `badges` branch was described in the past tense as already gone. It isn't, and it can't be until this merges — while the `badge` job still exists on main, the next code push would recreate it. Both the workflows README and the CHANGELOG now state that sequencing. - "for weeks" was wrong: #502 merged 2026-08-20, six days ago. - ci.yml's header claimed docs-preview was the only job holding a write scope, undercounting coverage's `code-quality: write` — which it holds while executing the PR tree. Pre-existing, but exactly the class of stale permission claim this PR set out to correct. - The "restoring a badge means restoring contents: write" note asserted an implication and then offered the alternative that disproves it. A shields endpoint hosted outside the repo needs no write scope at all. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MB4oPy9yfUHSe8FjnDmeZH
CodeRabbit flagged the new bullet in .github/workflows/README.md as hard-wrapped, and it was right. I initially pushed back because .github/.markdownlint.json sets "WH001": false — but that exclusion contradicts CONTRIBUTING.md, which promises the rule is enforced "everywhere", and AGENTS.md, which states it with no carve-out. The config is the thing that's wrong, not the finding. This commit fixes only the prose this PR introduced, so the change stays scoped to the badge retirement. Removing both WH001 exclusions (.github/ and .claude/) and reflowing the 53 hard-wrapped paragraphs they were hiding (292 WH001 violation lines, since the rule reports one per line) is tracked in #521. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MB4oPy9yfUHSe8FjnDmeZH
Two path-scoped configs — .github/.markdownlint.json and .claude/.markdownlint.json — held nothing but "WH001": false, silently switching the no-hard-wrapped-prose rule off for CI docs and agent prompts ever since #489 introduced it. CONTRIBUTING.md tells contributors it is enforced everywhere, while AGENTS.md and the .markdownlint-cli2.jsonc header wrote up the carve-out — three descriptions of one rule, disagreeing. That cost a round trip on #520: a reviewer correctly flagged a hard-wrapped bullet, an agent pointed at "WH001": false for that path and pushed back, and the reviewer recorded a learning never to flag WH001 there — the wrong invariant, learned off the wrong side of the contradiction. Both configs deleted; the 51 paragraphs they hid are joined (41 in .github/workflows/README.md, 10 in pm-triage/references/routine.md), mechanical joins only. The vendored PostHog skill goes too — 9 files, ~1,456 lines, job finished in #277, nothing references it, and it was the only file that would have needed a special-case exclusion, so removing it is what lets WH001 apply with no exception at all. Review then found four more things the exclusion had hidden: WH001 skips lines indented 4+ spaces as code, so three nested bullets were invisible to the autofix (unwrapped by hand) and the "a list item is joined as a unit" claim was wrong for nested items; docs-prose.sh named two lockstep copies of its denylist when there are three, missing the gating subagent's own prompt; the config header overstated WH002's scope; and the job graph omitted docs-deploy's suite needs edges. Closes #521 Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MB4oPy9yfUHSe8FjnDmeZH
|
Note Currently processing new changes in this PR. This may take a few minutes, please wait... ⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (8)
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (20)
💤 Files with no reviewable changes (11)
Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review. 📜 Recent review details⏰ Context from checks skipped due to timeout. (6)
🧰 Additional context used📓 Path-based instructions (1)- **Never hard-wrap prose. One paragraph is one line.** No wrapping at 72/80 columns, no "semantic linefeeds" splitting a paragraph at sentence boundaries.📄 CodeRabbit inference engine (AGENTS.md) Files:
🧠 Learnings (1)📚 Learning: 2026-06-10T15:01:09.027ZApplied to files:
🪛 LanguageTool.github/prompts/docs-review.md[uncategorized] ~3-~3: The official name of this software platform is spelled with a capital “H”. (GITHUB) CHANGELOG.md[typographical] ~20-~20: Consider using an em dash in dialogues and enumerations. (DASH_RULE) [uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”. (GITHUB) [uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”. (GITHUB) [uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”. (GITHUB) [uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”. (GITHUB) [uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”. (GITHUB) [uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”. (GITHUB) [uncategorized] ~20-~20: The official name of this software platform is spelled with a capital “H”. (GITHUB) [style] ~20-~20: The word ‘caveat’ is a legal term. To make your text as clear as possible to all readers, do not use this foreign term unless it is used with its legal meaning. Possible alternatives are “caution” or “warning”. (CAVEAT) AGENTS.md[uncategorized] ~297-~297: The official name of this software platform is spelled with a capital “H”. (GITHUB) [style] ~326-~326: This word has been used in one of the immediately preceding sentences. Using a synonym could make your text more interesting to read, unless the repetition is intentional. (EN_REPEATEDWORDS_WHOLE) [uncategorized] ~342-~342: The official name of this software platform is spelled with a capital “H”. (GITHUB) [uncategorized] ~342-~342: The official name of this software platform is spelled with a capital “H”. (GITHUB) [uncategorized] ~342-~342: The official name of this software platform is spelled with a capital “H”. (GITHUB) .claude/skills/pm-triage/references/routine.md[style] ~7-~7: Since ownership is already implied, this phrasing may be redundant. (PRP_OWN) [style] ~11-~11: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym. (ENGLISH_WORD_REPEAT_BEGINNING_RULE) .github/workflows/README.md[typographical] ~3-~3: The word ‘How’ starts a question. Add a question mark (“?”) at the end of the sentence. (WRB_QUESTION_MARK) [uncategorized] ~51-~51: The official name of this software platform is spelled with a capital “H”. (GITHUB) [style] ~87-~87: Since ownership is already implied, this phrasing may be redundant. (PRP_OWN) [grammar] ~91-~91: Use a hyphen to join words. (QB_NEW_EN_HYPHEN) [style] ~93-~93: Since ownership is already implied, this phrasing may be redundant. (PRP_OWN) [style] ~149-~149: This sentence is over 40 words long. Consider splitting it up, as shorter sentences make the text easier to read. (TOO_LONG_SENTENCE) [style] ~151-~151: This word has been used in one of the immediately preceding sentences. Using a synonym could make your text more interesting to read, unless the repetition is intentional. (EN_REPEATEDWORDS_NEED) [style] ~151-~151: Since ownership is already implied, this phrasing may be redundant. (PRP_OWN) 🔇 Additional comments (8)
📝 WalkthroughSummary by CodeRabbit
WalkthroughThe change enforces WH001 across tracked Markdown files, updates related documentation and prose selection, reformats documentation, updates the CI architecture graph, and removes the unused vendored Astro View Transitions skill. ChangesLint and documentation cleanup
Estimated code review effort: 2 (Simple) | ~10 minutes Merge Risk: ⚪ Minimal · up to The change enables the existing Markdown rule across tracked documentation, reflows affected prose, reconciles guidance, and removes unused vendored content; no actionable merge-blocking risk remains beyond normal checks and review. Suggested reviewers: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
Full details: Docstring CoverageExplanation Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 1 files. (7 skipped: 7 unsupported.)
✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
documentation
# Conflicts: # .github/workflows/README.md # CHANGELOG.md
github-actions
Bot
added
go
|
📚 Docs preview is live → https://7437674f-wavehouse-docs.wave-rf.workers.dev
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Unlike docs/posthog-setup-report.md — a real file deleted in #502 that left a stale reference behind — PERF-CLAIMS-REVIEW.md was never tracked at all (`git log --all` finds nothing) and isn't gitignored, so the entry guarded a document that has never existed in this repo. The denylist's other general cases are patterns (*.draft.md, *.old.md) that already cover a one-off review write-up. A literal filename for a hypothetical file, restated in four places, is the outlier — and this PR is about not leaving speculative claims lying around in comments. Removed from all four lockstep locations, per the header rule the previous commit corrected. `scripts/docs-prose.sh all` still resolves the same 27-file prose set. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MB4oPy9yfUHSe8FjnDmeZH
Two review findings. The workflows README still told readers the orphan `badges` branch "is deleted separately once this lands: while the job still exists on main, the next code push would just recreate it." Both clauses stopped being true when #520 merged and the branch was deleted — so the canonical CI reference was handing readers an open action item that is already done. Past-tensed, keeping the reason it had to be sequenced that way. The twin sentence in CHANGELOG.md is deliberately NOT changed: that entry records what #520 did and planned at the time, and Keep a Changelog entries aren't rewritten as reality moves. The living reference doc tracks current state; the changelog tracks history. Also rewrapped a 112-character comment line in .markdownlint-cli2.jsonc to match the ~80 of its neighbours — hand-wrapped prose maintenance cost, in the file that configures the rule against it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MB4oPy9yfUHSe8FjnDmeZH
claude-code.md told readers that "when #121 lands a SigNoz dev stack with `make dev-obs`", Grafana MCP would become useful for trace/log inspection. Three ways wrong: - #121 closed as COMPLETED on 2026-05-24. - `dev-obs` exists nowhere in the tree — the real targets are obs-aspire, obs-grafana, and obs-front. - The project went the other way. deployment.md states outright that no heavy multi-node cluster like SigNoz is maintained for local dev, and deployments/signoz/ is gone. So the page deferred to future work that had already shipped under a different name, and handed readers a command that errors out. Now points at `make obs-grafana` and links the deployment section. Pre-existing rather than introduced here, but claude-code.md is in the docs-prose set and already edited by this PR — and stale prose that outlived its subject is precisely what this PR is about. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MB4oPy9yfUHSe8FjnDmeZH
Two review findings. The job graph still omitted two real `needs` edges — `changes --> ci` and `changes --> preview` — while the legend three lines below says flatly "Solid arrows are `needs` edges". Not a deliberate simplification either: `changes --> deploy` IS drawn, so the diagram contradicted itself. Adding both makes the edges into `ci` exactly the aggregator's nine `needs`. The earlier commit in this PR audited that diagram and stopped two edges short, which is the same defect class the PR exists to remove. The Grafana MCP fix also moves out of the WH001 entry into its own `### Fixed` bullet. That entry's headline is about WH001 applying everywhere; its last two sentences were about `make obs-grafana` and a closed issue, which a reader scanning for either would not find. The repo's convention is one thorough bullet per change. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MB4oPy9yfUHSe8FjnDmeZH
1 participant
Two path-scoped configs —
.github/.markdownlint.jsonand.claude/.markdownlint.json— held nothing but"WH001": false, silently switching the no-hard-wrapped-prose rule off for CI docs and agent prompts ever since #489 introduced it.CONTRIBUTING.md:97tells contributorsmake lintenforces WH001 everywhere, whileAGENTS.md:342and the.markdownlint-cli2.jsoncheader wrote up the carve-out — three descriptions of one rule, disagreeing.That cost a round trip on #520: a reviewer correctly flagged a hard-wrapped bullet in
.github/workflows/README.md, an agent pointed at"WH001": falsefor that path and pushed back, and the reviewer recorded a persistent learning never to flag WH001 there — the wrong invariant, learned off the wrong side of the contradiction.What changed
extends+ the override, so the root.markdownlint.json("WH001": true) governs again. Theignoresarray is untouched — there is now no path-scoped carve-out of any kind.make fix: 41 in.github/workflows/README.md(378 → 171 lines), 10 in.claude/skills/pm-triage/references/routine.md. Mechanical joins; no wording changed..claude/skills/integration-astro-view-transitions/, 9 files / ~1,456 lines including an 809-lineEXAMPLE.mdcopied wholesale fromPostHog/context-mill. Its integration job finished in feat(docs): prod-faithful dev loop, mermaid cache, favicon, doc fixes #277, nothing in the repo calls it, and the live docs-site setup is documented indocs/src/components/PostHog.astroand the CHANGELOG. Unowned third-party prose drifts silently on every upstream bump and nobody here reviews it — and it was the single file that would have needed a special-case exclusion, so removing it is what lets the rule apply with no exception at all rather than one documented one.AGENTS.md:342and the config header rewritten;AGENTS.md:326andCONTRIBUTING.md:97already said "everywhere" and are now true.AGENTS.md:342also tells future readers not to reintroduce a subtree override, pointing at an in-filemarkdownlint-disableas the visible escape hatch — verified to actually work, block form only.docs/posthog-setup-report.md(the wizard's other artifact, deleted in docs: update README.md #502) andPERF-CLAIMS-REVIEW.md— which was never tracked at all, so it guarded a file that has never existed. The list's other general cases are patterns (*.draft.md,*.old.md) that already cover a one-off review document. Removed from all four lockstep locations;scripts/docs-prose.sh allstill resolves the same 27-file prose set.What review turned up
None of this was in #521's scope. All of it is the same defect class — documentation asserting a state of the world that had moved on — which is what made a whole-file read worth doing.
no-hard-wrapped-prose.mjs:139classifies any line indented four or more spaces as an indented code block, so a nested list item is never joined. Three hard-wrapped bullets sat in.github/workflows/README.md— in the very file this PR reflowed — invisible to the autofix. Unwrapped by hand; they were the last hard-wrapped prose paragraphs in the repo.AGENTS.md:326anddevelopment.md:432both promised "a list item is joined as a unit". Not for nested items — a contributor would expectmake fixto unwrap one and it silently doesn't. Both now state the four-space caveat.scripts/docs-prose.sh's header undercounted its own lockstep set, naming two sibling copies of the denylist when there are three. The missed one is.claude/agents/docs-reviewer.md— the gating subagent's own system prompt — whichgit log -Sshows had been out of sync for the entire life of theposthog-setup-report.mdexclusion, and agreed only by accident of this branch removing it.docs-deploywas drawn without itsneedsedges fromunit,integration, ande2e, andci/docs-previewwere missingchanges— while the legend three lines below states "Solid arrows areneedsedges" andchanges --> deploywas drawn. Five edges added; the diagram now matchesci.ymledge-for-edge in both directions.claude-code.mddeferred to work that had already shipped. It told readers that "when feat(observability): o11y dev-stack cleanup + wire into make #121 lands a SigNoz dev stack withmake dev-obs" Grafana MCP would become useful. feat(observability): o11y dev-stack cleanup + wire into make #121 closed as completed in May,dev-obsexists nowhere in the tree (the real targets areobs-aspire/obs-grafana/obs-front), anddeployment.mdstates outright that no heavy multi-node cluster like SigNoz is maintained for local development. Now points atmake obs-grafana.Filed rather than fixed here: #523, where
deployment.mdclaims all three local observability stacks publish OTLP4318, but onlyobs-frontdoes.Test plan
make cigreen end to end on the final tree, marker matches HEAD.markdownlint-cli2reports 0 issues over all 42 tracked.md, andpnpm lint:md0 over all 48 tracked.md+.mdx— "every tracked Markdown file" is literally, not approximately, true.make fixis a fixpoint.markdownlint-cli2 --fix, and diffed: the branch files are byte-identical to the autofix output, ruling out a hand-edit in the reflow. Independently, word-level diffs againstmainshowroutine.mdis word-for-word identical and.github/workflows/README.md's only content changes are the five graph edges and the past-tensed badges sentence.ci.yml'sneeds, both directions — nine intoci, seven intodocs-deploy, two intodocs-preview, none spurious.shellcheck+bash -nclean ondocs-prose.sh; the new/deployment#local-observability-stackanchor is validated bystarlight-links-validatorduringmake ci's docs build.Closes #521