claude-dev-env 1.19.0 → 1.19.2

package/docs/CODE_RULES.md

@@ -44,7 +44,7 @@ These rules are automatically enforced by `code-rules-enforcer.py`. Violations b
 | No NEW comments | `#` / `//` in new code only (existing comments NEVER removed; shebangs, type:, noqa, eslint, docstrings exempt) |
 | Imports at top | No `import` inside function bodies |
 | Logging format args | No `log_*(f"...")` - use `log_*("...", arg)` |
-| File line count | Max 400 lines per file |
+| File line count | Advisory only — see [File length guidance](#65-file-length-guidance) |
 | Magic values | No literals in function bodies (0, 1, -1 exempt). Includes string templates — if you strip the interpolations from an f-string and the remaining literal text is structural (paths, URLs, patterns), those fragments are magic values that belong in config |
 | Constants location | No `UPPER_SNAKE =` outside `config/` |
 
@@ -121,6 +121,28 @@ def function_name(
 
 ---
 
+## 6.5 FILE LENGTH GUIDANCE
+
+File length is a **smell signal, not a hard threshold**. Long files often hide multiple responsibilities, but legitimately long files exist (migrations, generated code, registries, fixtures). The hook surfaces advisories instead of blocking.
+
+**Two advisory thresholds (non-blocking, stderr only):**
+
+| Threshold | Source basis | Hook behavior |
+|-----------|--------------|---------------|
+| `>= 400` lines | Robert C. Martin, *Clean Code* (2008), Ch. 5 "Formatting" — small files preferred; Martin Fowler, *Refactoring* — "Large Class" code smell | Soft advisory: "consider splitting" |
+| `>= 1000` lines | pylint default `max-module-lines=1000`; SonarQube rule S104 default `1000` | Strong nudge: "exceeds widely-used static-analysis defaults" |
+
+**What we deliberately reject:**
+
+- **Hard numeric blocks** — Google's Python Style Guide imposes no file-length cap (only a ~40-line function review hint at https://google.github.io/styleguide/pyguide.html). A blocking rule produces false positives on legitimate cases.
+- **A single magic number** — Different sources land at 200 (*Clean Code* preference), 750 (some SonarQube language profiles), or 1000 (pylint, Sonar Java). No source justifies a single universal cap.
+
+**When to actually split:**
+
+The size signal matters *because* of what it usually indicates: multiple responsibilities (Single Responsibility Principle — Robert C. Martin, *Agile Software Development*, 2002), poor cohesion (Steve McConnell, *Code Complete 2e*, 2004, Ch. 5–6), or the "Large Class" / "Long Function" smells (Fowler). Use the readability rubric (`~/.claude/skills/readability-review/SKILL.md`) when an advisory fires — split based on cohesion, not line count.
+
+---
+
 ## 7. RIGHT-SIZED ENGINEERING
 
 **Simple > Clever. Functions > Classes. Concrete > Abstract.**
@@ -175,7 +197,7 @@ Hook will enforce:
 [⚡] No magic values
 [⚡] Imports at top
 [⚡] Logging format args
-[⚡] File under 400 lines
+[ ] File length reasonable (advisory at 400, strong nudge at 1000 — see §6.5)
 [⚡] Constants in config/
 
 Manual check:

package/hooks/blocking/code-rules-enforcer.py

@@ -2,15 +2,17 @@
 """
 CODE_RULES.md enforcer - blocks code that violates mandatory rules.
 
-Checks (all blocking):
+Checks (blocking):
 1. No comments (# or // in code, excluding shebangs/type: ignore)
 2. Imports at top (no imports inside functions)
 3. Logging f-strings (log_* calls must use format args)
-4. File line count (>400 blocks)
-5. Windows API None (win32gui calls with None parameter)
-6. Magic values (literals in function bodies)
-7. E2E test naming (no online/offline in test names)
-8. Constants outside config (UPPER_SNAKE = in non-config files)
+4. Windows API None (win32gui calls with None parameter)
+5. Magic values (literals in function bodies)
+6. E2E test naming (no online/offline in test names)
+7. Constants outside config (UPPER_SNAKE = in non-config files)
+
+Advisory only (non-blocking):
+- File line count: stderr warning at 400 lines (soft) and 1000 lines (hard)
 """
 import json
 import re
@@ -27,6 +29,9 @@ HOOK_INFRASTRUCTURE_PATTERNS = {"/.claude/hooks/", "\\.claude\\hooks\\", "\\.cla
 WORKFLOW_REGISTRY_PATTERNS = {"/workflow/", "\\workflow\\", "_tab.py", "/states.py", "\\states.py", "/modules.py", "\\modules.py"}
 MIGRATION_PATH_PATTERNS = {"/migrations/", "\\migrations\\"}
 
+ADVISORY_LINE_THRESHOLD_SOFT = 400
+ADVISORY_LINE_THRESHOLD_HARD = 1000
+
 
 def get_file_extension(file_path: str) -> str:
     """Extract lowercase file extension."""
@@ -308,12 +313,27 @@ def check_logging_fstrings(content: str) -> list[str]:
     return issues
 
 
-def check_file_line_count(content: str) -> list[str]:
-    """Check file line count."""
-    line_count = content.count("\n") + 1
-    if line_count > 400:
-        return [f"File has {line_count} lines (max 400) - split into smaller modules"]
-    return []
+def advise_file_line_count(content: str, file_path: str) -> None:
+    """Emit non-blocking stderr advisories when a file crosses size smell thresholds.
+
+    Thresholds are smell signals, not hard caps. See CODE_RULES.md "File length guidance"
+    for rationale. Soft threshold aligns with Clean Code Ch. 5 / Fowler "Large Class".
+    Hard threshold matches pylint default max-module-lines and SonarQube S104 default.
+    """
+    line_count = len(content.splitlines())
+    if line_count >= ADVISORY_LINE_THRESHOLD_HARD:
+        print(
+            f"[CODE_RULES advisory] {file_path}: {line_count} lines - "
+            f"exceeds pylint/SonarQube default ({ADVISORY_LINE_THRESHOLD_HARD}); "
+            f"strongly consider splitting by responsibility (SRP / cohesion)",
+            file=sys.stderr,
+        )
+    elif line_count >= ADVISORY_LINE_THRESHOLD_SOFT:
+        print(
+            f"[CODE_RULES advisory] {file_path}: {line_count} lines - "
+            f"consider splitting (Clean Code Ch. 5; Fowler 'Large Class' smell)",
+            file=sys.stderr,
+        )
 
 
 def check_windows_api_none(content: str) -> list[str]:
@@ -485,7 +505,7 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
         all_issues.extend(check_e2e_test_naming(content, file_path))
 
     if extension in ALL_CODE_EXTENSIONS:
-        all_issues.extend(check_file_line_count(content))
+        advise_file_line_count(content, file_path)
 
     return all_issues
 

package/hooks/blocking/content-search-to-zoekt-redirector.py

@@ -8,7 +8,10 @@ import sys
 from content_search_zoekt_bash_block_reason import block_reason_for_bash_command
 from content_search_zoekt_block_payload import build_block_payload
 from content_search_zoekt_indexed_paths import is_in_indexed_repo, is_specific_file
-from content_search_zoekt_redirect_guidance import get_zoekt_redirect_guidance
+from content_search_zoekt_redirect_guidance import (
+    get_zoekt_redirect_guidance,
+    get_zoekt_redirect_reason_brief,
+)
 
 
 def main() -> None:
@@ -45,7 +48,8 @@ def main() -> None:
     short_label = f"blocked {block_reason}; use Zoekt MCP"
     payload = build_block_payload(
         brief_label=short_label,
-        permission_decision_reason=get_zoekt_redirect_guidance(),
+        permission_decision_reason=get_zoekt_redirect_reason_brief(),
+        additional_context=get_zoekt_redirect_guidance(),
     )
     print(json.dumps(payload))
     sys.exit(0)

package/hooks/blocking/content_search_zoekt_block_payload.py

@@ -4,14 +4,18 @@
 def build_block_payload(
     brief_label: str,
     permission_decision_reason: str,
+    additional_context: str | None = None,
 ) -> dict:
     destructive_gate_label_prefix = "[destructive-gate]"
+    hook_specific_output: dict = {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "deny",
+        "permissionDecisionReason": permission_decision_reason,
+    }
+    if additional_context is not None:
+        hook_specific_output["additionalContext"] = additional_context
     return {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "permissionDecisionReason": permission_decision_reason,
-        },
+        "hookSpecificOutput": hook_specific_output,
         "systemMessage": f"{destructive_gate_label_prefix} {brief_label}",
         "suppressOutput": True,
     }

package/hooks/blocking/content_search_zoekt_redirect_guidance.py

@@ -1,4 +1,10 @@
-"""Zoekt MCP usage and repo-to-disk path mapping for PreToolUse permissionDecisionReason."""
+"""Zoekt MCP usage and repo-to-disk path mapping for PreToolUse outputs."""
+
+
+def get_zoekt_redirect_reason_brief() -> str:
+    return (
+        "Use Zoekt MCP (e.g. mcp__zoekt__search) instead of Grep/Search in Zoekt-indexed trees."
+    )
 
 
 def get_zoekt_redirect_guidance() -> str:

package/hooks/blocking/test_content_search_to_zoekt_redirector_integration.py

@@ -13,7 +13,10 @@ class ContentSearchHookIntegrationTests(unittest.TestCase):
         hook_directory = pathlib.Path(__file__).resolve().parent
         if str(hook_directory) not in sys.path:
             sys.path.insert(0, str(hook_directory))
-        from content_search_zoekt_redirect_guidance import get_zoekt_redirect_guidance
+        from content_search_zoekt_redirect_guidance import (
+            get_zoekt_redirect_guidance,
+            get_zoekt_redirect_reason_brief,
+        )
 
         hook_path = hook_directory / "content-search-to-zoekt-redirector.py"
         destructive_gate_label_prefix = "[destructive-gate]"
@@ -38,6 +41,10 @@ class ContentSearchHookIntegrationTests(unittest.TestCase):
         )
         self.assertEqual(
             payload["hookSpecificOutput"]["permissionDecisionReason"],
+            get_zoekt_redirect_reason_brief(),
+        )
+        self.assertEqual(
+            payload["hookSpecificOutput"]["additionalContext"],
             get_zoekt_redirect_guidance(),
         )
         self.assertEqual(

package/hooks/blocking/test_content_search_to_zoekt_redirector_unit.py

@@ -11,7 +11,10 @@ if str(HOOK_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(HOOK_DIRECTORY))
 
 from content_search_zoekt_block_payload import build_block_payload
-from content_search_zoekt_redirect_guidance import get_zoekt_redirect_guidance
+from content_search_zoekt_redirect_guidance import (
+    get_zoekt_redirect_guidance,
+    get_zoekt_redirect_reason_brief,
+)
 
 
 class BuildBlockPayloadTests(unittest.TestCase):
@@ -32,12 +35,14 @@ class BuildBlockPayloadTests(unittest.TestCase):
         self.assertEqual(payload["suppressOutput"], True)
         self.assertNotIn("decision", payload)
         self.assertNotIn("reason", payload)
+        self.assertNotIn("additionalContext", payload["hookSpecificOutput"])
 
     def test_serialized_payload_under_documented_context_cap(self) -> None:
         cap_characters = 10_000
         payload = build_block_payload(
             brief_label="blocked Bash(grep); use Zoekt MCP",
-            permission_decision_reason=get_zoekt_redirect_guidance(),
+            permission_decision_reason=get_zoekt_redirect_reason_brief(),
+            additional_context=get_zoekt_redirect_guidance(),
         )
         serialized = json.dumps(payload)
         self.assertLessEqual(

package/hooks/hooks.json

@@ -2,6 +2,16 @@
   "description": "Code standards enforcement, safety guards, and development workflow hooks",
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "Grep|Search",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/content-search-to-zoekt-redirector.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [
@@ -84,6 +94,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/test-preflight-check.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/content-search-to-zoekt-redirector.py",
+            "timeout": 10
           }
         ]
       },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.19.0",
+    "version": "1.19.2",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {