Markdown Style Enforcer

A Git pre-commit hook that uses Claude Code to review markdown files against a rigorous prose style guide. The style rules draw from Strunk's Elements of Style, Coase's analytical prose tradition, and the NRC Fault Tree Handbook.

What It Does

Every time you commit markdown files, the hook sends each file to Claude for style review. The review checks against 20+ rules organized into four categories.

Blocking Violations (commit fails)

Hard violations (any count blocks the commit):

• H1: Em dashes or en dashes used as em dashes. Use commas, semicolons, colons, periods, or parentheses instead.
• H2: "Not X, but Y" framing constructions. State the positive claim directly.

Table violations (any count blocks the commit):

• C6 substitution table: Explicit banned phrases from the C6 wordiness table ("it is important to note that", "owing to the fact that", "the question as to whether", etc.). These have unambiguous mechanical replacements.
• C3 stacked passives: Multiple passive constructions chained together ("has been reported to have been seen"). The rules declare these "always wrong."

Soft violation threshold (5+ per file blocks the commit):

• Comma splices (M3), sentence fragments (M5), dangling modifiers (M6)
• Missing serial commas (M1), passive voice (C3), vague language (C5)
• Needless words (C6 general), non-parallel structure (C7), and others

Soft violations below the threshold are reported as warnings but do not block the commit.

Non-Blocking Warnings

Soft violations under the threshold (default: 5 per file) are printed with quoted passages and suggested corrections. These help improve writing quality without blocking work in progress.

Setup

Prerequisites

• Claude Code CLI installed and authenticated
• Git repository
• Bash shell

Installation

Clone this repository, then run the install script pointing at your target repo:

git clone <repo-url> style
bash style/install-hook.sh /path/to/your/repo

This copies two files into the target repo:

• .style-rules.md (the complete style ruleset, at the repo root)
• .git/hooks/pre-commit (the hook script)

The hook runs automatically on every git commit that includes .md files.

If you omit the path, it installs into the current directory:

cd /path/to/your/repo
bash /path/to/style/install-hook.sh

Manual Installation

Copy the files yourself:

cp /path/to/style/.style-rules.md /path/to/your/repo/
cp /path/to/style/hooks/pre-commit /path/to/your/repo/.git/hooks/pre-commit
chmod +x /path/to/your/repo/.git/hooks/pre-commit

Configuration

Soft Violation Threshold

The default threshold is 5 soft violations per file. Adjust it with an environment variable:

# Stricter: block on 3+ soft violations
STYLE_SOFT_THRESHOLD=3 git commit -m "my message"

# More lenient: block on 10+ soft violations
STYLE_SOFT_THRESHOLD=10 git commit -m "my message"

To set a permanent threshold, export the variable in your shell profile:

export STYLE_SOFT_THRESHOLD=3

Excluding Files

The hook automatically excludes .style-rules.md from review. To exclude additional files, edit the grep -v pattern in hooks/pre-commit:

STAGED_MD_FILES=$(git diff --cached --name-only --diff-filter=ACM -- '*.md' \
    | grep -v '\.style-rules\.md$' \
    | grep -v 'CHANGELOG\.md$' \
    || true)

Skipping the Hook

For emergency commits that must bypass the style check:

git commit --no-verify -m "emergency fix"

Use this sparingly. The hook exists because the violations it catches degrade prose quality.

How It Works

1. The hook identifies staged .md files (added, copied, or modified).
2. For each file, it extracts the staged content using git show :filename.
3. It sends the content to Claude Code (claude -p) with the style rules as context.
4. Claude reviews the prose and outputs structured violation reports.
5. The hook parses the summary line to count hard, table, and soft violations.
6. If any blocking condition is met, the commit is rejected with detailed feedback.

The hook uses claude -p (print mode) with --model sonnet for fast, cost-effective reviews. It disables all tools (--allowedTools "") since the review is pure text analysis.

Understanding the Output

A typical review looks like this:

Reviewing: design-doc.md
---
VIOLATION: H1
SEVERITY: HARD
PASSAGE: "The system — which we designed last quarter — handles 10K requests."
CORRECTION: "The system, which we designed last quarter, handles 10K requests."

VIOLATION: C6
SEVERITY: TABLE
PASSAGE: "owing to the fact that the cache is warm"
CORRECTION: "because the cache is warm"

VIOLATION: C3
SEVERITY: SOFT
PASSAGE: "The request is processed by the server."
CORRECTION: "The server processes the request."

SUMMARY: 1 hard, 1 table, 1 soft
---

Each violation includes the rule code, severity, the offending passage, and a corrected version. Use the corrections to fix your text before committing again.

The Style Rules

The complete ruleset lives in .style-rules.md. It contains:

• 2 hard rules (H1, H2): absolute prohibitions on em dashes and "not X, but Y" constructions
• 6 mechanical rules (M1-M6): serial comma, comma splices, sentence fragments, dangling modifiers
• 9 composition rules (C1-C9): paragraph structure, active voice, positive form, concrete language, concision, parallelism
• 5 argument structure rules (A1-A5): start from reality, define problems before solutions, reason through cases

The rules are drawn from Strunk's Elements of Style, Coase's analytical prose, and Orwell's "Politics and the English Language."

Tested Scenarios

The hook was developed through 30 simulation cycles covering:

• Clean documents (proper pass, 0-2 soft violations)
• Documents with em dashes and en dashes (correctly blocked)
• Documents with "not X, but Y" variants (correctly blocked)
• Documents heavy with C6 table phrases (correctly blocked as TABLE violations)
• Documents with stacked passives (correctly blocked as TABLE violations)
• Documents with 5+ soft violations (correctly blocked by threshold)
• Documents with code blocks (code content correctly ignored)
• Multi-file commits (each file evaluated independently)
• Very short documents (no false positives)
• Technical prose with legitimate negation (no false positives on "never" in precise denial)