Enforce the comment standards at build time - #24
Merged
Conversation
miridius
force-pushed
the
review-standards-tooling
branch
2 times, most recently
from
July 24, 2026 19:00
2195de0 to
587306a
Compare
New .claude/rules/comments.md auto-loads the review comment standards for anyone editing src, test, or scripts (naming the concrete defect classes: narrating the obvious, restating tests, change justification, redundant contrast; a file's existing density is never a license). scripts/ check-dashes.sh gates en/em dashes out of every tracked .ts file, called from both check.sh and CI (for pushes that bypass the local hook). The gate scans the INDEX (git grep --cached: exactly what a commit records), pins LC_ALL=C for byte-wise PCRE, and fails loud when the scan itself cannot run. Failing at build time replaces a whole review round. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01DL3md3a3RoeRNStaDv1PDf
miridius
force-pushed
the
review-standards-tooling
branch
from
July 24, 2026 19:06
587306a to
5eb831c
Compare
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.
Problem
The review pipeline kept catching the same mechanical classes of finding, comment-style violations and stray en/em dashes, at review time, where each catch costs a full review round. The standards the reviewers enforce were not visible to whoever writes the code, and nothing checked for the banned characters before review.
Fix
Two build-time mechanisms:
.claude/rules/comments.md: the comment standards as an auto-loading rules file scoped tosrc/**,test/**, andscripts/**, so anyone editing those files gets the standards injected up front instead of learning them from a review finding.scripts/check-dashes.sh: scans the staged.tsfiles (the exact content a commit records) for literal en/em dashes and fails the commit if any are found. Run bycheck.sh(so the pre-commit hook enforces it) and mirrored in CI for pushes that bypass the local hook.The gate keys on the index, not the worktree: a staged dash blocks the commit even if the worktree copy is clean, and an unstaged-only dash does not block. A scan that cannot run (missing PCRE, bad invocation) exits non-zero rather than passing silently.
Deliberate trade-offs: the gate covers
.tsfiles only, matching where the comment standards apply (dashes in Markdown, shell, and YAML prose stay legal), and fixtures that need the real character use the\u2013/\u2014escapes, an intentional bypass for payload fidelity.