<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/2.x/2026-02-21-1-consistent-code-style-enforcement-via-git-hooks/">
  <id>https://docs.spec-kitty.ai/adr/2.x/2026-02-21-1-consistent-code-style-enforcement-via-git-hooks/</id>
  <title>Consistent Code Style Enforcement via Git Hooks</title>
  <updated>2026-02-21T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/2.x/2026-02-21-1-consistent-code-style-enforcement-via-git-hooks/"/>
  <summary>Runs ruff format, ruff check, and mypy over staged files at commit time, accepting an opinionated formatter in exchange for feedback that beats the CI round trip.</summary>
  <content type="html">&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The spec-kitty codebase had no automated style enforcement at commit time. Formatting inconsistencies and lint violations would only surface during CI (after push), creating slow feedback loops and noisy diffs that mix style fixes with functional changes.&lt;/p&gt;
&lt;p&gt;Python’s formatter ecosystem offers opinionated tools (Black, ruff format) that eliminate style debates but impose constraints: they are length-based and do not support per-construct formatting rules. For example, Black/ruff format will collapse a multi-line comprehension with &lt;code dir=&quot;auto&quot;&gt;for&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;if&lt;/code&gt; clauses onto a single line if it fits within the configured line length. There is no option to force line breaks between &lt;code dir=&quot;auto&quot;&gt;for&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;if&lt;/code&gt; clauses independently of line length.&lt;/p&gt;
&lt;p&gt;We evaluated whether custom lint rules could extend ruff’s formatter to cover these preferences, but ruff (like Black) has a closed rule set with no plugin or extension system. Unlike JavaScript’s ESLint or Rust’s rustfmt, Python’s formatting tools do not support layering custom rules on top of a baseline style.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Catch lint and format violations before they reach CI&lt;/li&gt;
&lt;li&gt;Eliminate style debates in code review&lt;/li&gt;
&lt;li&gt;Incremental enforcement — only check files being committed, not the entire codebase&lt;/li&gt;
&lt;li&gt;Validate commit messages before they reach the remote (commitlint)&lt;/li&gt;
&lt;li&gt;Accept minor personal style preferences as trade-offs for consistency&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Option 1:&lt;/strong&gt; No local enforcement (rely on CI only)&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 2:&lt;/strong&gt; ruff format (Black-compatible) + ruff check + mypy via git hooks&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 3:&lt;/strong&gt; ruff format + custom AST-based lint script for per-construct rules&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Option 4:&lt;/strong&gt; Lower line-length to force natural line breaks on long constructs&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen option:&lt;/strong&gt; “Option 2: ruff format (Black-compatible) + ruff check + mypy via git hooks”, because:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;It provides immediate feedback at commit time with zero CI wait&lt;/li&gt;
&lt;li&gt;Black-compatible formatting is the dominant Python standard, reducing onboarding friction&lt;/li&gt;
&lt;li&gt;Incremental enforcement (staged files only) avoids a mass-reformatting commit&lt;/li&gt;
&lt;li&gt;The trade-off of losing some multi-line formatting preferences (e.g., comprehension clause separation) is acceptable for the consistency gained&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;trade-offs-accepted&quot;&gt;Trade-offs Accepted&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Comprehension formatting:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;for&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;if&lt;/code&gt; clauses in comprehensions may collapse to a single line at &lt;code dir=&quot;auto&quot;&gt;line-length = 120&lt;/code&gt;. We accept this because there is no way to enforce per-construct line breaks in Black/ruff format without a plugin system, and writing a standalone AST checker for a single style preference adds maintenance burden disproportionate to the benefit.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Line length 120:&lt;/strong&gt; Wider than Black’s default of 88. Chosen to match the existing codebase style, but it causes more expressions to fit on a single line. Reducing to 88 would restore more multi-line formatting but would require reformatting a significant portion of the codebase.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;consequences&quot;&gt;Consequences&lt;/h3&gt;
&lt;h4 id=&quot;positive&quot;&gt;Positive&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Style violations caught before push, not after CI&lt;/li&gt;
&lt;li&gt;Commit messages validated against conventional commits before reaching the remote&lt;/li&gt;
&lt;li&gt;No style debates in code review — the formatter decides&lt;/li&gt;
&lt;li&gt;Incremental adoption — only touched files are checked&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;negative&quot;&gt;Negative&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Contributors must run &lt;code dir=&quot;auto&quot;&gt;git config core.hooksPath .githooks&lt;/code&gt; once after cloning&lt;/li&gt;
&lt;li&gt;Some multi-line formatting preferences cannot be expressed in Black/ruff format&lt;/li&gt;
&lt;li&gt;mypy strict mode on staged files may flag pre-existing issues in modified files&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;neutral&quot;&gt;Neutral&lt;/h4&gt;
&lt;ul&gt;
&lt;li&gt;Hooks are versioned in &lt;code dir=&quot;auto&quot;&gt;.githooks/&lt;/code&gt; (not &lt;code dir=&quot;auto&quot;&gt;.git/hooks/&lt;/code&gt;) for portability&lt;/li&gt;
&lt;li&gt;CI continues to run the same checks as a safety net&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;implementation&quot;&gt;Implementation&lt;/h2&gt;
&lt;h3 id=&quot;git-hook-setup&quot;&gt;Git Hook Setup&lt;/h3&gt;
&lt;p&gt;Hooks are stored in &lt;code dir=&quot;auto&quot;&gt;.githooks/&lt;/code&gt; and activated per-clone:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;config&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;core.hooksPath&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.githooks&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;pre-commit-hook&quot;&gt;pre-commit Hook&lt;/h3&gt;
&lt;p&gt;Runs on staged &lt;code dir=&quot;auto&quot;&gt;.py&lt;/code&gt; files only (Added, Copied, Modified, Renamed):&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ruff format --check&lt;/code&gt; — verify Black-compatible formatting&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;ruff check&lt;/code&gt; — lint rules (import order, unused imports, etc.)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;mypy --strict&lt;/code&gt; — type checking (src/ files only)&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;pre-push-hook&quot;&gt;pre-push Hook&lt;/h3&gt;
&lt;p&gt;Runs on commits about to be pushed:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;Determines commit range (remote SHA → local SHA)&lt;/li&gt;
&lt;li&gt;Runs &lt;code dir=&quot;auto&quot;&gt;commitlint&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;@commitlint/config-conventional&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Handles new branches (uses merge-base with default branch)&lt;/li&gt;
&lt;/ol&gt;
&lt;h3 id=&quot;ruff-configuration&quot;&gt;Ruff Configuration&lt;/h3&gt;
&lt;p&gt;In &lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt;:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;toml&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;[tool.ruff]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;line-length&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; = &lt;/span&gt;&lt;span style=&quot;--0:#F78C6C;--1:#AA0982&quot;&gt;120&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;
&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;[tool.ruff.format]&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;quote-style&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; = &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;double&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;indent-style&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; = &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;space&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;line-ending&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; = &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;auto&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;future-considerations-bootstrap-phase-integration&quot;&gt;Future Considerations: Bootstrap Phase Integration&lt;/h2&gt;
&lt;p&gt;When spec-kitty gains a &lt;code dir=&quot;auto&quot;&gt;bootstrap&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;init&lt;/code&gt; phase (for onboarding new projects), it should:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Prompt the user for their preferred code style guide&lt;/strong&gt; — e.g., Black (Python), Prettier (JS/TS), rustfmt (Rust), or a custom configuration&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Prompt for linting configuration&lt;/strong&gt; — e.g., ruff rule selection, ESLint config, clippy lints&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Generate &lt;code dir=&quot;auto&quot;&gt;.githooks/&lt;/code&gt; with appropriate pre-commit and pre-push hooks&lt;/strong&gt; tailored to the project’s language and style choices&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Set &lt;code dir=&quot;auto&quot;&gt;core.hooksPath&lt;/code&gt;&lt;/strong&gt; automatically during bootstrap&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Store the style configuration&lt;/strong&gt; in the project’s spec-kitty config (&lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt;) so that migrations and upgrades can regenerate hooks if the hook templates evolve&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;This would make consistent style enforcement a first-class citizen of every spec-kitty project, not just spec-kitty itself. The hook templates could live alongside mission templates in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/missions/&lt;/code&gt; and be deployed the same way slash command templates are today.&lt;/p&gt;
&lt;h2 id=&quot;pros-and-cons-of-the-options&quot;&gt;Pros and Cons of the Options&lt;/h2&gt;
&lt;h3 id=&quot;option-1-no-local-enforcement-ci-only&quot;&gt;Option 1: No Local Enforcement (CI Only)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Zero setup for contributors&lt;/li&gt;
&lt;li&gt;No local tooling requirements&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Style violations only caught after push (slow feedback)&lt;/li&gt;
&lt;li&gt;Noisy PRs mixing style fixes with functional changes&lt;/li&gt;
&lt;li&gt;Commit message violations discovered late&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-2-ruff-format--ruff-check--mypy-via-git-hooks&quot;&gt;Option 2: ruff format + ruff check + mypy via Git Hooks&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Immediate feedback at commit/push time&lt;/li&gt;
&lt;li&gt;Black-compatible formatting is industry standard&lt;/li&gt;
&lt;li&gt;Incremental enforcement on staged files only&lt;/li&gt;
&lt;li&gt;Hooks are versioned and portable&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Requires one-time &lt;code dir=&quot;auto&quot;&gt;git config&lt;/code&gt; setup per clone&lt;/li&gt;
&lt;li&gt;Cannot express all formatting preferences (e.g., comprehension clause breaks)&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-3-ruff-format--custom-ast-lint-script&quot;&gt;Option 3: ruff format + Custom AST Lint Script&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Could enforce per-construct formatting rules (e.g., multi-line comprehensions)&lt;/li&gt;
&lt;li&gt;Full control over style beyond what Black offers&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Maintenance burden for a custom linter&lt;/li&gt;
&lt;li&gt;Fragile — AST-based checks may not handle all edge cases&lt;/li&gt;
&lt;li&gt;Non-standard tooling that new contributors won’t recognize&lt;/li&gt;
&lt;li&gt;Disproportionate effort for marginal style preferences&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;option-4-lower-line-length-to-88-black-default&quot;&gt;Option 4: Lower line-length to 88 (Black Default)&lt;/h3&gt;
&lt;p&gt;&lt;strong&gt;Pros:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;More expressions naturally stay multi-line&lt;/li&gt;
&lt;li&gt;Matches Black’s default, familiar to most Python developers&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Cons:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Would require reformatting ~400+ files in the existing codebase&lt;/li&gt;
&lt;li&gt;88 chars may feel restrictive for a codebase already written at ~120&lt;/li&gt;
&lt;li&gt;Doesn’t actually solve the per-construct problem — just makes it less frequent&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;h3 id=&quot;activating-hooks&quot;&gt;Activating Hooks&lt;/h3&gt;
&lt;p&gt;After cloning the repository:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;git&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;config&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;core.hooksPath&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;.githooks&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;related-files&quot;&gt;Related Files&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.githooks/pre-commit&lt;/code&gt; — format + lint + type check on staged files&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;.githooks/pre-push&lt;/code&gt; — commitlint on outgoing commits&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pyproject.toml&lt;/code&gt; — ruff and mypy configuration&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;commitlint.config.cjs&lt;/code&gt; — conventional commit rules&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;package.json&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;@commitlint/config-conventional&lt;/code&gt; dependency&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;related-decisions&quot;&gt;Related Decisions&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Standardized automated quality gates ADR (planned but not published) — CI-level quality enforcement that these hooks complement locally&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
