claude-dev-env 1.30.0 → 1.31.0

package/bin/install.test.mjs

@@ -0,0 +1,158 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { collectPackageSourceConflicts } from './install.mjs';
+
+
+function createTemporaryGitRepository() {
+    const repositoryRoot = mkdtempSync(join(tmpdir(), 'cdev-installer-validation-'));
+    const gitOptions = { cwd: repositoryRoot, stdio: 'ignore' };
+    execFileSync('git', ['init', '--initial-branch=main'], gitOptions);
+    execFileSync('git', ['config', 'user.email', 'test@example.com'], gitOptions);
+    execFileSync('git', ['config', 'user.name', 'Test'], gitOptions);
+    execFileSync('git', ['config', 'commit.gpgsign', 'false'], gitOptions);
+    execFileSync('git', ['config', 'core.autocrlf', 'false'], gitOptions);
+    return repositoryRoot;
+}
+
+
+function commitAllChanges(repositoryRoot, commitMessage) {
+    execFileSync('git', ['add', '.'], { cwd: repositoryRoot, stdio: 'ignore' });
+    execFileSync('git', ['commit', '-m', commitMessage], {
+        cwd: repositoryRoot,
+        stdio: 'ignore',
+    });
+}
+
+
+function tryMergeAllowingConflict(repositoryRoot, branchName) {
+    try {
+        execFileSync('git', ['merge', '--no-edit', branchName], {
+            cwd: repositoryRoot,
+            stdio: 'ignore',
+        });
+    } catch {
+        return;
+    }
+}
+
+
+test('collectPackageSourceConflicts returns empty list when working tree is clean', () => {
+    const repositoryRoot = createTemporaryGitRepository();
+    try {
+        const packageDirectory = join(repositoryRoot, 'packages', 'thing');
+        mkdirSync(packageDirectory, { recursive: true });
+        writeFileSync(join(packageDirectory, 'README.md'), 'hello\n');
+        commitAllChanges(repositoryRoot, 'init');
+
+        const conflicts = collectPackageSourceConflicts(packageDirectory);
+        assert.deepEqual(conflicts, []);
+    } finally {
+        rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+});
+
+
+test('collectPackageSourceConflicts surfaces both-modified paths under the package directory', () => {
+    const repositoryRoot = createTemporaryGitRepository();
+    try {
+        const packageDirectory = join(repositoryRoot, 'packages', 'thing');
+        mkdirSync(packageDirectory, { recursive: true });
+        const conflictedFile = join(packageDirectory, 'shared.txt');
+        writeFileSync(conflictedFile, 'base content\n');
+        commitAllChanges(repositoryRoot, 'base');
+
+        execFileSync('git', ['checkout', '-b', 'branch-a'], { cwd: repositoryRoot, stdio: 'ignore' });
+        writeFileSync(conflictedFile, 'a side\n');
+        commitAllChanges(repositoryRoot, 'a');
+
+        execFileSync('git', ['checkout', '-b', 'branch-b', 'main'], { cwd: repositoryRoot, stdio: 'ignore' });
+        writeFileSync(conflictedFile, 'b side\n');
+        commitAllChanges(repositoryRoot, 'b');
+
+        tryMergeAllowingConflict(repositoryRoot, 'branch-a');
+
+        const conflicts = collectPackageSourceConflicts(packageDirectory);
+        assert.equal(conflicts.length, 1);
+        assert.equal(conflicts[0].statusCode, 'UU');
+        assert.match(conflicts[0].path, /shared\.txt/);
+    } finally {
+        rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+});
+
+
+test('collectPackageSourceConflicts ignores conflicts outside the package directory', () => {
+    const repositoryRoot = createTemporaryGitRepository();
+    try {
+        const packageDirectory = join(repositoryRoot, 'packages', 'thing');
+        const otherDirectory = join(repositoryRoot, 'packages', 'other');
+        mkdirSync(packageDirectory, { recursive: true });
+        mkdirSync(otherDirectory, { recursive: true });
+        writeFileSync(join(packageDirectory, 'inside.txt'), 'inside\n');
+        const otherFile = join(otherDirectory, 'outside.txt');
+        writeFileSync(otherFile, 'base outside\n');
+        commitAllChanges(repositoryRoot, 'init');
+
+        execFileSync('git', ['checkout', '-b', 'side'], { cwd: repositoryRoot, stdio: 'ignore' });
+        writeFileSync(otherFile, 'side change\n');
+        commitAllChanges(repositoryRoot, 'side');
+
+        execFileSync('git', ['checkout', 'main'], { cwd: repositoryRoot, stdio: 'ignore' });
+        writeFileSync(otherFile, 'main change\n');
+        commitAllChanges(repositoryRoot, 'main');
+
+        tryMergeAllowingConflict(repositoryRoot, 'side');
+
+        const conflicts = collectPackageSourceConflicts(packageDirectory);
+        assert.deepEqual(conflicts, []);
+    } finally {
+        rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+});
+
+
+test('collectPackageSourceConflicts returns empty when directory is not inside a git repo', () => {
+    const standaloneDirectory = mkdtempSync(join(tmpdir(), 'cdev-installer-no-git-'));
+    try {
+        const conflicts = collectPackageSourceConflicts(standaloneDirectory);
+        assert.deepEqual(conflicts, []);
+    } finally {
+        rmSync(standaloneDirectory, { recursive: true, force: true });
+    }
+});
+
+
+test('collectPackageSourceConflicts surfaces both-added and deleted-by-them entries', () => {
+    const repositoryRoot = createTemporaryGitRepository();
+    try {
+        const packageDirectory = join(repositoryRoot, 'packages', 'thing');
+        mkdirSync(packageDirectory, { recursive: true });
+        writeFileSync(join(packageDirectory, 'shared.txt'), 'base\n');
+        writeFileSync(join(packageDirectory, 'about_to_disappear.txt'), 'will be removed\n');
+        commitAllChanges(repositoryRoot, 'base');
+
+        execFileSync('git', ['checkout', '-b', 'theirs'], { cwd: repositoryRoot, stdio: 'ignore' });
+        rmSync(join(packageDirectory, 'about_to_disappear.txt'));
+        writeFileSync(join(packageDirectory, 'fresh.txt'), 'theirs version\n');
+        commitAllChanges(repositoryRoot, 'theirs');
+
+        execFileSync('git', ['checkout', '-b', 'ours', 'main'], { cwd: repositoryRoot, stdio: 'ignore' });
+        writeFileSync(join(packageDirectory, 'about_to_disappear.txt'), 'ours edit\n');
+        writeFileSync(join(packageDirectory, 'fresh.txt'), 'ours version\n');
+        commitAllChanges(repositoryRoot, 'ours');
+
+        tryMergeAllowingConflict(repositoryRoot, 'theirs');
+
+        const conflicts = collectPackageSourceConflicts(packageDirectory);
+        const allStatusCodes = new Set(conflicts.map(conflictEntry => conflictEntry.statusCode));
+        assert.ok(allStatusCodes.has('UD'), `expected UD in ${[...allStatusCodes].join(',')}`);
+        assert.ok(allStatusCodes.has('AA'), `expected AA in ${[...allStatusCodes].join(',')}`);
+    } finally {
+        rmSync(repositoryRoot, { recursive: true, force: true });
+    }
+});

package/bin/install_mypy_ini.mjs

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const MYPY_INI_FILENAME = '.mypy.ini';
+const MYPY_CONFIG_SECTION_HEADER = '[mypy]';
+
+
+function normalizeClaudeHooksPathToForwardSlashes(claudeHooksDirectory) {
+    return claudeHooksDirectory.replace(/\\/g, '/');
+}
+
+
+function buildExpectedMypyPathLine(claudeHooksDirectory) {
+    const claudeHooksAsForwardSlashes = normalizeClaudeHooksPathToForwardSlashes(claudeHooksDirectory);
+    return `mypy_path = ${claudeHooksAsForwardSlashes}`;
+}
+
+
+function buildMypyIniContentForClaudeHooks(claudeHooksDirectory) {
+    const expectedMypyPathLine = buildExpectedMypyPathLine(claudeHooksDirectory);
+    return `${MYPY_CONFIG_SECTION_HEADER}\n${expectedMypyPathLine}\n`;
+}
+
+
+function hasExactMatchingLine(fileContent, expectedLine) {
+    const lineBreakPattern = /\r?\n/;
+    const allLines = fileContent.split(lineBreakPattern);
+    return allLines.some((eachLine) => eachLine.trim() === expectedLine);
+}
+
+
+export function installMypyIniForClaudeHooks({ homeDirectory, claudeHooksDirectory }) {
+    const mypyIniDestinationPath = join(homeDirectory, MYPY_INI_FILENAME);
+    const expectedMypyPathLine = buildExpectedMypyPathLine(claudeHooksDirectory);
+
+    if (existsSync(mypyIniDestinationPath)) {
+        const existingMypyIniContent = readFileSync(mypyIniDestinationPath, 'utf8');
+        if (hasExactMatchingLine(existingMypyIniContent, expectedMypyPathLine)) {
+            return { action: 'already-configured', path: mypyIniDestinationPath };
+        }
+        return {
+            action: 'skipped-existing',
+            path: mypyIniDestinationPath,
+            expectedLine: expectedMypyPathLine,
+        };
+    }
+
+    const mypyIniContent = buildMypyIniContentForClaudeHooks(claudeHooksDirectory);
+    writeFileSync(mypyIniDestinationPath, mypyIniContent);
+    return { action: 'created', path: mypyIniDestinationPath };
+}

package/bin/install_mypy_ini.test.mjs

@@ -0,0 +1,121 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdtempSync, rmSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { installMypyIniForClaudeHooks } from './install_mypy_ini.mjs';
+
+
+function makeTemporaryHomeWithClaudeHooks() {
+    const temporaryHomeDirectory = mkdtempSync(join(tmpdir(), 'cdev-mypy-ini-test-'));
+    const claudeHooksDirectory = join(temporaryHomeDirectory, '.claude', 'hooks');
+    mkdirSync(claudeHooksDirectory, { recursive: true });
+    return { temporaryHomeDirectory, claudeHooksDirectory };
+}
+
+
+test('installMypyIniForClaudeHooks creates a new .mypy.ini when none exists', () => {
+    const { temporaryHomeDirectory, claudeHooksDirectory } = makeTemporaryHomeWithClaudeHooks();
+    try {
+        const installResult = installMypyIniForClaudeHooks({
+            homeDirectory: temporaryHomeDirectory,
+            claudeHooksDirectory,
+        });
+
+        assert.equal(installResult.action, 'created');
+        assert.equal(installResult.path, join(temporaryHomeDirectory, '.mypy.ini'));
+
+        const writtenContent = readFileSync(installResult.path, 'utf8');
+        assert.match(writtenContent, /^\[mypy\]$/m);
+        assert.match(writtenContent, /^mypy_path = /m);
+
+        const claudeHooksAsForwardSlashes = claudeHooksDirectory.replace(/\\/g, '/');
+        assert.ok(
+            writtenContent.includes(claudeHooksAsForwardSlashes),
+            `expected content to include ${claudeHooksAsForwardSlashes}`,
+        );
+    } finally {
+        rmSync(temporaryHomeDirectory, { recursive: true, force: true });
+    }
+});
+
+
+test('installMypyIniForClaudeHooks leaves existing file untouched when already configured', () => {
+    const { temporaryHomeDirectory, claudeHooksDirectory } = makeTemporaryHomeWithClaudeHooks();
+    try {
+        const claudeHooksAsForwardSlashes = claudeHooksDirectory.replace(/\\/g, '/');
+        const preExistingContent = `[mypy]\nmypy_path = ${claudeHooksAsForwardSlashes}\nstrict = True\n`;
+        const mypyIniPath = join(temporaryHomeDirectory, '.mypy.ini');
+        writeFileSync(mypyIniPath, preExistingContent);
+
+        const installResult = installMypyIniForClaudeHooks({
+            homeDirectory: temporaryHomeDirectory,
+            claudeHooksDirectory,
+        });
+
+        assert.equal(installResult.action, 'already-configured');
+        assert.equal(installResult.path, mypyIniPath);
+
+        const contentAfterInstall = readFileSync(mypyIniPath, 'utf8');
+        assert.equal(contentAfterInstall, preExistingContent);
+    } finally {
+        rmSync(temporaryHomeDirectory, { recursive: true, force: true });
+    }
+});
+
+
+test('installMypyIniForClaudeHooks treats an existing mypy_path that is a strict prefix of the expected path as not configured', () => {
+    const { temporaryHomeDirectory, claudeHooksDirectory } = makeTemporaryHomeWithClaudeHooks();
+    try {
+        const claudeHooksAsForwardSlashes = claudeHooksDirectory.replace(/\\/g, '/');
+        const prefixCollidingPath = `${claudeHooksAsForwardSlashes}-old`;
+        const preExistingContent = `[mypy]\nmypy_path = ${prefixCollidingPath}\nstrict = True\n`;
+        const mypyIniPath = join(temporaryHomeDirectory, '.mypy.ini');
+        writeFileSync(mypyIniPath, preExistingContent);
+
+        const installResult = installMypyIniForClaudeHooks({
+            homeDirectory: temporaryHomeDirectory,
+            claudeHooksDirectory,
+        });
+
+        assert.equal(installResult.action, 'skipped-existing');
+        assert.equal(installResult.path, mypyIniPath);
+        assert.equal(
+            installResult.expectedLine,
+            `mypy_path = ${claudeHooksAsForwardSlashes}`,
+        );
+
+        const contentAfterInstall = readFileSync(mypyIniPath, 'utf8');
+        assert.equal(contentAfterInstall, preExistingContent);
+    } finally {
+        rmSync(temporaryHomeDirectory, { recursive: true, force: true });
+    }
+});
+
+
+test('installMypyIniForClaudeHooks does not overwrite existing .mypy.ini that lacks the expected mypy_path', () => {
+    const { temporaryHomeDirectory, claudeHooksDirectory } = makeTemporaryHomeWithClaudeHooks();
+    try {
+        const preExistingContent = `[mypy]\nmypy_path = /some/other/project\nstrict = True\n`;
+        const mypyIniPath = join(temporaryHomeDirectory, '.mypy.ini');
+        writeFileSync(mypyIniPath, preExistingContent);
+
+        const installResult = installMypyIniForClaudeHooks({
+            homeDirectory: temporaryHomeDirectory,
+            claudeHooksDirectory,
+        });
+
+        assert.equal(installResult.action, 'skipped-existing');
+        assert.equal(installResult.path, mypyIniPath);
+        assert.ok(
+            installResult.expectedLine.includes(claudeHooksDirectory.replace(/\\/g, '/')),
+            `expected expectedLine to include ${claudeHooksDirectory.replace(/\\/g, '/')}`,
+        );
+
+        const contentAfterInstall = readFileSync(mypyIniPath, 'utf8');
+        assert.equal(contentAfterInstall, preExistingContent);
+    } finally {
+        rmSync(temporaryHomeDirectory, { recursive: true, force: true });
+    }
+});

package/commands/hook-log-extract.md

@@ -0,0 +1,70 @@
+---
+description: Extract hook-firing records from session transcripts into Neon and show blocker summary
+allowed-tools: Bash
+---
+
+Scan every JSONL session transcript under `~/.claude/projects/` (or the
+path set by the `CLAUDE_HOME` env var) and ingest `attachment` records
+whose inner `type` is one of the five enumerated variants in
+`OUTCOME_BY_ATTACHMENT_TYPE` (`hook_success`, `hook_blocking_error`,
+`hook_non_blocking_error`, `hook_system_message`,
+`hook_additional_context`). Each ingested record becomes one row in
+the Neon `hook_events` table. Unknown `hook_`-prefixed variants are
+skipped until `OUTCOME_BY_ATTACHMENT_TYPE` is extended to cover them.
+The Stop hook runs this on every session end using the `--incremental`
+flag.
+
+## Run modes
+
+```
+bws run -- python packages/claude-dev-env/hooks/diagnostic/hook_log_extractor.py
+```
+
+Full extraction using the current byte offsets in
+`~/.claude/logs/hooks/.state/offsets.json` (override the `~/.claude`
+root by setting `CLAUDE_HOME`). Equivalent to the Stop hook's
+`--incremental` invocation; passing `--incremental` explicitly is a
+documented no-op that selects the same default resumption path.
+
+```
+bws run -- python packages/claude-dev-env/hooks/diagnostic/hook_log_extractor.py --full-rebuild
+```
+
+Clear offsets, truncate `hook_events`, and re-read every JSONL from byte
+zero. Use this after a schema migration or when the offsets file is
+suspected of drift.
+
+```
+bws run -- python packages/claude-dev-env/hooks/diagnostic/hook_log_extractor.py --summary
+```
+
+Skip extraction. Print the top-10 blockers of the last 24 hours with
+their block count and a single truncated command preview, or
+`No new blocks since last run.` when the window is empty.
+
+```
+bws run -- python packages/claude-dev-env/hooks/diagnostic/hook_log_extractor.py --query <name>
+```
+
+Run the pre-baked query `queries/<name>.sql` and print the result as an
+aligned text table. Available query names match the SQL files in
+`packages/claude-dev-env/hooks/diagnostic/queries/`:
+
+- `top_blockers_overall`
+- `top_blockers_last_24_hours`
+- `blocks_last_7_days`
+- `blocks_by_category`
+- `blocks_by_tool`
+- `block_details_for_hook`
+
+## Offline behavior
+
+If the psycopg connection fails with `OperationalError`, the
+5-second timeout elapses, `NEON_HOOK_LOGS_DATABASE_URL` is unset, or
+the `psycopg` driver is not installed, the extractor appends one
+ISO-8601 line to `~/.claude/logs/hook-extractor.log` (override the
+`~/.claude` root with the `CLAUDE_HOME` env var) and exits with
+status 0. Session shutdown stays fast, and the next online run
+backfills from the existing offsets. The warning line records only
+the timestamp and the exception class name so connection URLs never
+leak into the log.

package/commands/hook-log-init.md

@@ -0,0 +1,76 @@
+---
+description: Initialize the Neon schema used by the hook-log extractor
+allowed-tools: Bash
+---
+
+Initialize the Neon Postgres schema that backs the hook-log diagnostic
+extractor. Run this once per new machine, or after rotating the Neon
+project, before the Stop hook begins inserting rows.
+
+## Prerequisites
+
+One-time setup on each machine:
+
+1. **Install the Bitwarden Secret Manager CLI** so the `bws` command is on PATH.
+   See https://bitwarden.com/help/secrets-manager-cli/ for platform-specific instructions.
+
+2. **Create a Bitwarden machine account** scoped to the Neon connection
+   secret, generate its access token, and export it to the current user
+   environment.
+
+   On Windows (PowerShell):
+
+   ```powershell
+   setx BWS_ACCESS_TOKEN "<machine-account-access-token>"
+   ```
+
+   Open a new terminal so the variable takes effect.
+
+   On macOS or Linux (bash/zsh — add to `~/.bashrc`, `~/.zshrc`, or the
+   equivalent profile so new shells inherit it):
+
+   ```bash
+   export BWS_ACCESS_TOKEN="<machine-account-access-token>"
+   ```
+
+3. **Store the Neon connection string** in the Bitwarden Secrets Manager
+   under the key `NEON_HOOK_LOGS_DATABASE_URL`. The value is the full
+   `postgres://user:password@host/database?sslmode=require` URL that
+   Neon provides on the project dashboard.
+
+4. **Install the Python dependencies** so the extractor can reach Neon.
+   Production runtime:
+
+   ```
+   pip install -r packages/claude-dev-env/hooks/diagnostic/requirements-hook-logs.txt
+   ```
+
+   Development (adds `pytest` on top of the runtime deps):
+
+   ```
+   pip install -r packages/claude-dev-env/hooks/diagnostic/requirements-hook-logs-dev.txt
+   ```
+
+## Run the init
+
+```
+bws run -- python packages/claude-dev-env/hooks/diagnostic/hook_log_init.py
+```
+
+The init script performs these steps in order:
+
+1. Verifies `NEON_HOOK_LOGS_DATABASE_URL` is set. `BWS_ACCESS_TOKEN` is
+   consumed by the outer `bws` CLI before it spawns the Python child
+   process; `bws run` intentionally strips it from the child
+   environment to prevent subprocess credential leakage, so the Python
+   script never sees it.
+2. Connects to Neon with a 5-second timeout.
+3. Applies the DDL in `packages/claude-dev-env/hooks/diagnostic/schema.sql`
+   using `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and
+   `CREATE OR REPLACE VIEW` so the script stays idempotent.
+4. Inserts a sentinel row with `outcome = 'init_probe'`, selects it back,
+   and deletes it to confirm read-write parity.
+5. Prints a success report showing the Neon host, table name, and row count.
+
+A missing environment variable exits with status 1 and lists the
+missing name on stderr; any other failure surfaces the psycopg exception.

package/docs/CODE_RULES.md

@@ -169,6 +169,44 @@ Always: Functions when no state, concrete classes, simple imports
 
 ---
 
+## 7.5 SOLID PRINCIPLES
+
+**Apply where two or more concrete implementations already share a contract. For code with a single concretion, §7 (Right-Sized Engineering) takes precedence: use concrete classes, functions when no state, and direct imports.**
+
+Reference: Robert C. Martin, *Agile Software Development: Principles, Patterns, and Practices* (2002), Ch. 8–12.
+
+| Letter | Principle | What it means here |
+|--------|-----------|--------------------|
+| **S** | Single Responsibility Principle | A class, function, or module has one reason to change. One unit = one axis of variation. Ties to §6.5 (file length as smell signal) and Fowler's "Large Class" / "Long Function" smells. |
+| **O** | Open/Closed Principle | Extend behavior by adding new code. Favor a new branch/handler/subclass over editing the same switch in five places. |
+| **L** | Liskov Substitution Principle | A subtype must be usable anywhere its parent type is expected without surprising the caller. If a subclass override breaks caller assumptions, flatten the hierarchy or prefer composition. |
+| **I** | Interface Segregation Principle | Each client depends on exactly the methods it calls. Split one fat interface into several role-specific ones so each caller imports only the role it needs. |
+| **D** | Dependency Inversion Principle | When two or more concretions exist or are imminent, depend on the shared abstraction. With exactly one concretion, import the concrete type directly (see §7). |
+
+### Reconciling SOLID with Right-Sized Engineering (§7)
+
+SOLID was written for OO codebases where most abstract types have two or more concrete subclasses. In this codebase:
+
+- **SRP always applies.** Functions, classes, and modules must have one reason to change regardless of paradigm. This is the only SOLID letter that applies immediately, without waiting for a second implementation.
+- **OCP, LSP, ISP, DIP apply where two or more concrete implementations already share a contract.** A single concrete class satisfies SOLID by default. Introduce interfaces, ABCs, or DI containers only when the second concretion lands.
+- **For code with fewer than two concretions, §7 wins:** concrete classes, functions when no state, direct imports. Refactor toward OCP/DIP at the commit that introduces the second concrete implementation (YAGNI).
+
+### Signals that SOLID is being misapplied
+
+- Creating an interface or ABC with exactly one implementation (violates §7 DIP guard)
+- Splitting a cohesive 80-line class with one reason to change into four 20-line classes because "SRP" — SRP counts distinct change reasons; size is a separate signal tracked in §6.5
+- Abstract factories for types that have exactly one concrete product
+- Dependency-injection containers where every injected type has exactly one concrete implementation across production and tests
+
+### When SOLID adds value
+
+- Two or more concrete implementations already exist → DIP and ISP earn their keep
+- A class shows multiple unrelated change reasons in git history → SRP split is justified
+- Subclass overrides break caller assumptions → LSP violation; fix or flatten the hierarchy
+- Editing the same `if`/`switch` block every time a new case is added → OCP refactor is justified
+
+---
+
 ## 8. TDD PROCESS
 
 1. **RED** - Failing test first
@@ -221,5 +259,7 @@ Manual check:
 [ ] No abbreviations?
 [ ] Complete type hints?
 [ ] Self-contained components?
+[ ] SRP holds (one reason to change per function/class/module)?
+[ ] OCP/LSP/ISP/DIP only applied where abstractions already earn their keep (see §7.5)?
 [ ] Readability: /check or /readability-review
 ```

package/hooks/blocking/code_rules_enforcer.py

@@ -1339,13 +1339,15 @@ def check_file_global_constants_use_count(content: str, file_path: str) -> list[
     """Flag module-level UPPER_SNAKE constants referenced by only one function/method.
 
     Enforces jl-cmd/claude-code-config#180: a file-global constant used by just
-    one caller belongs in that caller's scope. Test files and non-Python files
-    are exempt. Constants with zero function references are out of scope.
-    Hook infrastructure files define module-level scalar constants by
+    one caller belongs in that caller's scope. Test files, config files, and
+    non-Python files are exempt. Constants with zero references are out of
+    scope. Hook infrastructure files define module-level scalar constants by
     convention and are exempt to avoid self-blocking.
     """
     if is_test_file(file_path):
         return []
+    if is_config_file(file_path):
+        return []
     if get_file_extension(file_path) not in PYTHON_EXTENSIONS:
         return []
     if file_path.replace("\\", "/").endswith("hooks/blocking/code_rules_enforcer.py"):