claude-dev-env 1.28.1 → 1.29.0

package/agents/caveman.md

@@ -0,0 +1,74 @@
+---
+name: caveman
+description: Trims noise from an artifact the main caller has already authored. Input is a draft (skill, doc, plan, response, README, prompt, PR description) — output is the same artifact with filler, hedging, preamble, recap, and restatement removed. Preserves structure, technical substance, frontmatter, and anything load-bearing. Does NOT redesign, restructure, or overrule the caller's scope decisions.
+model: inherit
+color: red
+---
+
+You are the caveman. You trim. You do not build. You do not restructure.
+
+## What you are
+
+A noise filter. The main caller has already decided *what* the artifact is, *how* it is structured, and *what lives in it*. Your job is to strip fluff off that artifact without touching the bones.
+
+You are downstream of design decisions, not upstream.
+
+## What you trim
+
+| Noise type | Example |
+|---|---|
+| Preamble / recap | "As discussed above, this skill will..." |
+| Hedging | "This might, in some cases, potentially..." |
+| Filler transitions | "Now, moving on to..." / "It's worth noting that..." |
+| Restatement | the same point made twice in different words |
+| Empty future-proofing | parameters, sections, or fields with no current consumer |
+| Dead examples | examples that duplicate another example without adding coverage |
+| Pleasantries | "Hope this helps." / "Feel free to..." |
+| Vague qualifiers | "various", "several", "a number of" — replace with the actual count or cut |
+
+Rewrite prose into the caveman pattern only where it does not change meaning: `[thing] [action] [reason]. [next step].`
+
+## What you do NOT touch
+
+- **Structure the caller chose.** Four sections in, four sections out. Do not collapse or merge.
+- **Frontmatter fields.** All fields stay. Tighten values if verbose; do not drop fields.
+- **Technical substance.** Code, commands, paths, URLs, errors, JSON, schema — unchanged.
+- **Trigger words / activation phrases.** Load-bearing for skill matching.
+- **Safety / escape-hatch language.** Warnings about destructive ops, irreversible actions, credentials, money, production systems — preserve verbatim.
+- **Caller-flagged content.** If the caller said "keep X verbatim", X is untouchable.
+- **Counts and specifics.** Numbers, thresholds, version strings, identifiers — unchanged.
+- **Register in examples and docstrings.** Unless caller asked for caveman voice throughout, keep the original register of user-facing copy.
+
+## What you do NOT decide
+
+You do not tell the caller:
+- "Use the existing tool instead" — design call, caller's call.
+- "Make this one file instead of three" — structure call, caller's call.
+- "Drop this section" — scope call, caller's call.
+- "Add tests" / "remove tests" — scope call, caller's call.
+
+If you suspect a section is pure noise, flag it in the report. Leave it in place unless the caller told you to remove it.
+
+## Process
+
+1. Read the artifact end to end before touching it.
+2. Mark the bones — frontmatter, structure, technical substance, trigger words, safety language. Off-limits.
+3. Trim noise per the table above.
+4. Return the trimmed artifact in the caller's original file format.
+
+## Output shape
+
+```
+trimmed: <path or artifact name>
+removed: <bullets — noise categories cut, with rough line counts>
+preserved-verbatim: <what you refused to touch and why>
+flagged: <content you suspect is noise but left in place for caller to decide>
+```
+
+No recap of the artifact itself. Caller has it.
+
+## Escape hatch
+
+If trimming would drop a safety warning, remove an irreversible-action caveat, collapse a distinction the caller made deliberately, or if you are unsure whether content is load-bearing — leave it in place and flag it. Ask before cutting.
+
+Terse is for noise, not for substance.

package/hooks/blocking/code_rules_enforcer.py

@@ -28,13 +28,19 @@ import json
 import re
 import sys
 import tokenize
+from pathlib import Path
 from typing import Optional
 
+_BLOCKING_DIR = str(Path(__file__).resolve().parent)
+if _BLOCKING_DIR not in sys.path:
+    sys.path.insert(0, _BLOCKING_DIR)
+
+from code_rules_path_utils import is_config_file  # noqa: E402
+
 PYTHON_EXTENSIONS = {".py"}
 JAVASCRIPT_EXTENSIONS = {".js", ".ts", ".tsx", ".jsx"}
 ALL_CODE_EXTENSIONS = PYTHON_EXTENSIONS | JAVASCRIPT_EXTENSIONS
 
-CONFIG_PATH_PATTERNS = {"config/", "config\\", "/config.", "\\config.", "settings.py"}
 TEST_PATH_PATTERNS = {"test_", "_test.", ".test.", ".spec.", "/tests/", "\\tests\\", "/tests.py", "\\tests.py"}
 HOOK_INFRASTRUCTURE_PATTERNS = {"/.claude/hooks/", "\\.claude\\hooks\\", "\\.claude/hooks/", "/packages/claude-dev-env/hooks/", "\\packages\\claude-dev-env\\hooks\\"}
 WORKFLOW_REGISTRY_PATTERNS = {"/workflow/", "\\workflow\\", "_tab.py", "/states.py", "\\states.py", "/modules.py", "\\modules.py"}
@@ -69,12 +75,6 @@ def is_hook_infrastructure(file_path: str) -> bool:
     return any(pattern.replace("\\", "/") in path_lower for pattern in HOOK_INFRASTRUCTURE_PATTERNS)
 
 
-def is_config_file(file_path: str) -> bool:
-    """Check if file is in a config directory or is a config file."""
-    path_lower = file_path.lower()
-    return any(pattern in path_lower for pattern in CONFIG_PATH_PATTERNS)
-
-
 def is_test_file(file_path: str) -> bool:
     """Check if file is a test file."""
     path_lower = file_path.lower()
@@ -780,6 +780,79 @@ def check_constants_outside_config(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def _is_exempt_for_advisory_scan(file_path: str) -> bool:
+    """Return True when the file is exempt from the function-local UPPER_SNAKE advisory."""
+    if is_config_file(file_path):
+        return True
+    if is_test_file(file_path):
+        return True
+    if is_workflow_registry_file(file_path):
+        return True
+    if is_migration_file(file_path):
+        return True
+    return False
+
+
+def _scan_function_body_constants(content: str) -> list[str]:
+    """Return advisory messages for UPPER_SNAKE assignments inside function bodies.
+
+    Only lines inside a function body (tracked via an indent stack) are
+    flagged. Module-level assignments and class-body assignments are ignored.
+    Returns at most MAX_ISSUES_PER_CHECK entries.
+    """
+    advisory_issues: list[str] = []
+    lines = content.split("\n")
+    function_indent_stack: list[int] = []
+    constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})\s*=\s*[^=]")
+
+    for line_number, line in enumerate(lines, 1):
+        stripped = line.strip()
+
+        if not stripped:
+            continue
+
+        indent = len(line) - len(line.lstrip())
+
+        while function_indent_stack and indent <= function_indent_stack[-1] and not stripped.startswith(("#", "@", ")")):
+            function_indent_stack.pop()
+
+        if re.match(r"^class\s+\w+", stripped):
+            if indent == 0:
+                function_indent_stack.clear()
+            continue
+
+        if re.match(r"^(async\s+)?def\s+\w+", stripped):
+            function_indent_stack.append(indent)
+            continue
+
+        if function_indent_stack:
+            match = constant_pattern.match(stripped)
+            if match:
+                constant_name = match.group(1)
+                advisory_issues.append(
+                    f"Line {line_number}: Function-local constant {constant_name} - consider moving to config/"
+                )
+
+        if len(advisory_issues) >= MAX_ISSUES_PER_CHECK:
+            break
+
+    return advisory_issues
+
+
+def check_constants_outside_config_advisory(content: str, file_path: str) -> list[str]:
+    """Return advisory entries for UPPER_SNAKE assignments inside function bodies.
+
+    Module-level UPPER_SNAKE outside config/ is blocking (see
+    check_constants_outside_config). Function-local UPPER_SNAKE is a softer
+    smell — it belongs in config/ but does not block the write. This function
+    surfaces those as advisory so callers can route them to stderr rather than
+    to the blocking deny payload.
+    """
+    if _is_exempt_for_advisory_scan(file_path):
+        return []
+    return _scan_function_body_constants(content)
+
+
 BANNED_IDENTIFIERS: frozenset[str] = frozenset({"result", "data", "output", "response", "value", "item", "temp"})
 MAX_BANNED_IDENTIFIER_ISSUES: int = 3
 BANNED_IDENTIFIER_MESSAGE_SUFFIX: str = "use descriptive name (see CODE_RULES Naming section)"
@@ -1118,6 +1191,8 @@ def validate_content(content: str, file_path: str, old_content: str = "") -> lis
         all_issues.extend(check_magic_values(content, file_path))
         all_issues.extend(check_fstring_structural_literals(content, file_path))
         all_issues.extend(check_constants_outside_config(content, file_path))
+        for each_advisory in check_constants_outside_config_advisory(content, file_path):
+            print(f"[CODE_RULES advisory] {file_path}: {each_advisory}", file=sys.stderr)
         all_issues.extend(check_file_global_constants_use_count(content, file_path))
         all_issues.extend(check_type_escape_hatches(content, file_path))
         all_issues.extend(check_banned_identifiers(content, file_path))

package/hooks/blocking/code_rules_path_utils.py

@@ -0,0 +1,31 @@
+"""Shared path-classification helpers for the blocking hook layer.
+
+Both ``code_rules_enforcer.py`` (pre-write gate) and
+``validators/exempt_paths.py`` (pre-push validator) need to agree on what
+constitutes a config file. This module is the single implementation; both
+import ``is_config_file`` from here so they cannot drift apart.
+
+``validators/exempt_paths.py`` re-exports this function and documents that
+the canonical implementation lives here.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+def is_config_file(file_path: str) -> bool:
+    """Return True when the path points to a config file.
+
+    Uses pathlib parts so a filename of ``config.py`` does not match — any
+    directory segment before the filename must be literally ``config``.
+    ``settings.py`` matches regardless of parent directory.  Filename-only
+    matches such as ``scripts/db/config.py`` or ``lib/myconfig.py`` return
+    False because the check requires a *directory* segment named ``config``,
+    not a filename stem.
+    """
+    normalized = file_path.replace("\\", "/").lower()
+    if normalized.endswith("/settings.py") or normalized == "settings.py":
+        return True
+    path_parts = Path(normalized).parts
+    return "config" in path_parts[:-1]

package/hooks/blocking/es_exe_path_rewriter.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: rewrite es.exe commands by substituting registry tokens with absolute paths.
+
+Reads tool_input.command from stdin JSON. When the command invokes the Everything
+command-line binary, substitutes {project-name} placeholder tokens and bare registry-key
+tokens with their quoted absolute paths from ~/.claude/project-paths.json before
+the Bash call runs. Never blocks or denies — on any error exits 0 with empty output.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+import sys
+from pathlib import Path, PurePosixPath, PureWindowsPath
+
+
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.dynamic_stderr_handler import DynamicStderrHandler
+from config.path_rewriter_constants import (
+    BASH_TOOL_NAME,
+    HOOK_EVENT_NAME,
+    PERMISSION_ALLOW,
+    PLACEHOLDER_TOKEN_PATTERN,
+)
+from config.project_paths_reader import load_registry
+
+_ES_EXE_TRIGGER_PATTERN = re.compile(
+    r"(?i)(?<![\w.])(?:Everything[/\\])?es\.exe(?![\w.])",
+)
+
+
+_logger = logging.getLogger("es_exe_path_rewriter")
+if not _logger.handlers:
+    _stderr_handler = DynamicStderrHandler()
+    _stderr_handler.setFormatter(logging.Formatter("%(name)s: %(message)s"))
+    _logger.addHandler(_stderr_handler)
+    _logger.setLevel(logging.INFO)
+    _logger.propagate = False
+
+
+def command_invokes_es_exe(command: str) -> bool:
+    """Return True when the command string contains an es.exe invocation."""
+    return bool(_ES_EXE_TRIGGER_PATTERN.search(command))
+
+
+def _token_is_absolute_path(token: str) -> bool:
+    stripped = token.strip("\"'")
+    try:
+        return (
+            PureWindowsPath(stripped).is_absolute()
+            or PurePosixPath(stripped).is_absolute()
+        )
+    except (ValueError, TypeError):
+        return False
+
+
+def _quote_path(absolute_path: str) -> str:
+    return f'"{absolute_path}"'
+
+
+def _rewrite_placeholder_tokens(command_suffix: str, registry: dict[str, str]) -> str:
+    def replace_placeholder(match: re.Match) -> str:
+        inner_name = match.group(1)
+        if inner_name not in registry:
+            return match.group(0)
+        return _quote_path(registry[inner_name])
+
+    return PLACEHOLDER_TOKEN_PATTERN.sub(replace_placeholder, command_suffix)
+
+
+def _split_on_es_exe(command: str) -> tuple[str, str]:
+    match = _ES_EXE_TRIGGER_PATTERN.search(command)
+    if not match:
+        return command, ""
+    return command[: match.end()], command[match.end() :]
+
+
+def _strip_matching_outer_quotes(token: str) -> tuple[str, bool]:
+    """Return (inner_text, was_quoted) after removing matched outer quotes."""
+    if len(token) > 1 and token[0] in ('"', "'") and token[-1] == token[0]:
+        return token[1:-1], True
+    return token, False
+
+
+def _rewrite_bare_tokens(command_suffix: str, registry: dict[str, str]) -> str:
+    all_raw_parts = re.split(r"(\s+)", command_suffix)
+    all_rewritten_parts: list[str] = []
+    for each_raw_part in all_raw_parts:
+        if not each_raw_part or each_raw_part.isspace():
+            all_rewritten_parts.append(each_raw_part)
+            continue
+        unquoted_text, _was_quoted = _strip_matching_outer_quotes(each_raw_part)
+        if unquoted_text in registry and not _token_is_absolute_path(unquoted_text):
+            all_rewritten_parts.append(_quote_path(registry[unquoted_text]))
+        else:
+            all_rewritten_parts.append(each_raw_part)
+    return "".join(all_rewritten_parts)
+
+
+def rewrite_command(command: str, registry: dict[str, str]) -> str:
+    """Apply registry substitutions to any es.exe argument tokens.
+
+    Applies placeholder form {name} first, then bare-token form.
+    Absolute-path arguments and unknown tokens are left untouched.
+    Returns the original command when no substitution applies.
+    """
+    if not registry:
+        return command
+    prefix, suffix = _split_on_es_exe(command)
+    rewritten_suffix = _rewrite_placeholder_tokens(suffix, registry)
+    rewritten_suffix = _rewrite_bare_tokens(rewritten_suffix, registry)
+    return prefix + rewritten_suffix
+
+
+def _build_allow_response(rewritten_command: str, original_tool_input: dict) -> dict:
+    updated_input = {**original_tool_input, "command": rewritten_command}
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": HOOK_EVENT_NAME,
+            "permissionDecision": PERMISSION_ALLOW,
+            "updatedInput": updated_input,
+        }
+    }
+
+
+def main() -> None:
+    try:
+        hook_input = json.load(sys.stdin)
+        tool_name = hook_input.get("tool_name", "")
+        if tool_name != BASH_TOOL_NAME:
+            sys.exit(0)
+        tool_input = hook_input.get("tool_input", {})
+        command = tool_input.get("command", "")
+        if not command_invokes_es_exe(command):
+            sys.exit(0)
+        known_registry = load_registry()
+        if not known_registry:
+            sys.exit(0)
+        rewritten_command = rewrite_command(command, known_registry)
+        if rewritten_command == command:
+            sys.exit(0)
+        print(json.dumps(_build_allow_response(rewritten_command, tool_input)))
+    except Exception as e:
+        _logger.error("%s", e)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/hedging_language_blocker.py

@@ -10,9 +10,19 @@ import json
 import os
 import re
 import sys
+from pathlib import Path
 
-sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "config"))
-from messages import USER_FACING_NOTICE
+
+def _insert_hooks_tree_for_imports() -> None:
+    hooks_tree = Path(__file__).resolve().parent.parent
+    hooks_tree_string = str(hooks_tree)
+    if hooks_tree_string not in sys.path:
+        sys.path.insert(0, hooks_tree_string)
+
+
+_insert_hooks_tree_for_imports()
+
+from config.messages import USER_FACING_NOTICE
 
 PLUGIN_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
 

package/hooks/blocking/test_code_rules_enforcer.py

@@ -10,6 +10,7 @@ the "zero function references" exemption does not swallow real references.
 from __future__ import annotations
 
 import importlib.util
+import sys
 from pathlib import Path
 from types import ModuleType
 
@@ -26,6 +27,11 @@ def _load_enforcer_module() -> ModuleType:
 
 code_rules_enforcer = _load_enforcer_module()
 
+_BLOCKING_DIR = Path(__file__).resolve().parent
+if str(_BLOCKING_DIR) not in sys.path:
+    sys.path.insert(0, str(_BLOCKING_DIR))
+
+from code_rules_path_utils import is_config_file as path_utils_is_config_file  # noqa: E402
 
 PRODUCTION_FILE_PATH = "packages/claude-dev-env/hooks/blocking/example_production.py"
 
@@ -59,3 +65,145 @@ def test_should_flag_constant_used_once_at_module_scope_and_once_in_function() -
     assert issues == [], (
         f"Expected module-scope + function usage to count as 2 distinct callers, got: {issues}"
     )
+
+
+def test_is_config_file_rejects_filename_only_config_pattern() -> None:
+    """Paths where 'config' appears only in the filename (not as a directory segment) must return False."""
+    assert code_rules_enforcer.is_config_file("scripts/db/config.py") is False, (
+        "scripts/db/config.py — filename is config.py but parent dir is db, must be False"
+    )
+    assert code_rules_enforcer.is_config_file("lib/myconfig.py") is False, (
+        "lib/myconfig.py — config appears only in the filename stem, must be False"
+    )
+    assert code_rules_enforcer.is_config_file("src/app_config.py") is False, (
+        "src/app_config.py — config appears only in the filename stem, must be False"
+    )
+
+
+def test_is_config_file_via_path_utils_returns_same_results_as_enforcer() -> None:
+    """is_config_file from code_rules_path_utils must agree with the enforcer on all sample paths."""
+    all_sample_paths = [
+        "scripts/db/config.py",
+        "config/timing.py",
+        "settings.py",
+    ]
+    for each_path in all_sample_paths:
+        enforcer_result = code_rules_enforcer.is_config_file(each_path)
+        path_utils_result = path_utils_is_config_file(each_path)
+        assert enforcer_result == path_utils_result, (
+            f"is_config_file diverged for {each_path!r}: "
+            f"enforcer={enforcer_result}, code_rules_path_utils={path_utils_result}"
+        )
+
+
+def test_is_exempt_for_advisory_scan_returns_true_for_config_file() -> None:
+    assert code_rules_enforcer._is_exempt_for_advisory_scan("project/config/constants.py") is True
+
+
+def test_is_exempt_for_advisory_scan_returns_true_for_test_file() -> None:
+    assert code_rules_enforcer._is_exempt_for_advisory_scan("test_example.py") is True
+
+
+def test_is_exempt_for_advisory_scan_returns_true_for_workflow_registry() -> None:
+    assert code_rules_enforcer._is_exempt_for_advisory_scan("app/workflow/states.py") is True
+
+
+def test_is_exempt_for_advisory_scan_returns_true_for_migration() -> None:
+    assert code_rules_enforcer._is_exempt_for_advisory_scan("app/migrations/0001_initial.py") is True
+
+
+def test_is_exempt_for_advisory_scan_returns_false_for_production_file() -> None:
+    assert code_rules_enforcer._is_exempt_for_advisory_scan("packages/myapp/some_module.py") is False
+
+
+def test_scan_function_body_constants_finds_upper_snake_in_function() -> None:
+    source = (
+        "def fetch():\n"
+        "    MAX_RETRIES = 3\n"
+        "    for attempt in range(MAX_RETRIES):\n"
+        "        pass\n"
+    )
+    advisory_issues = code_rules_enforcer._scan_function_body_constants(source)
+    assert any("MAX_RETRIES" in issue for issue in advisory_issues)
+
+
+def test_scan_function_body_constants_does_not_flag_module_level() -> None:
+    source = "MAX_RETRIES = 3\n\ndef fetch():\n    pass\n"
+    advisory_issues = code_rules_enforcer._scan_function_body_constants(source)
+    assert advisory_issues == []
+
+
+def test_advisory_should_not_flag_class_attribute_after_method_def() -> None:
+    source_with_class_attribute_after_method = (
+        "class ExampleModel:\n"
+        "    def method_a(self) -> None:\n"
+        "        pass\n"
+        "\n"
+        "    TABLE_NAME = \"example\"\n"
+    )
+    advisory_issues = code_rules_enforcer.check_constants_outside_config_advisory(
+        source_with_class_attribute_after_method,
+        "example_module.py",
+    )
+    assert advisory_issues == [], (
+        "Class-level TABLE_NAME attribute must not be flagged as function-local"
+    )
+
+
+def test_advisory_should_still_flag_actual_method_body_constant() -> None:
+    source_with_method_body_constant = (
+        "class ExampleModel:\n"
+        "    def method_a(self) -> None:\n"
+        "        MAXIMUM_RETRIES = 3\n"
+        "        return None\n"
+    )
+    advisory_issues = code_rules_enforcer.check_constants_outside_config_advisory(
+        source_with_method_body_constant,
+        "example_module.py",
+    )
+    assert len(advisory_issues) == 1, (
+        "Method-body UPPER_SNAKE constant must still surface as advisory"
+    )
+    assert "MAXIMUM_RETRIES" in advisory_issues[0]
+
+
+def test_advisory_cap_matches_max_issues_per_check_constant() -> None:
+    many_constants_source = (
+        "def crowded_function():\n"
+        "    ALPHA_CONSTANT = 1\n"
+        "    BETA_CONSTANT = 2\n"
+        "    GAMMA_CONSTANT = 3\n"
+        "    DELTA_CONSTANT = 4\n"
+        "    EPSILON_CONSTANT = 5\n"
+    )
+    advisory_issues = code_rules_enforcer.check_constants_outside_config_advisory(
+        many_constants_source,
+        "example_module.py",
+    )
+    assert len(advisory_issues) == code_rules_enforcer.MAX_ISSUES_PER_CHECK, (
+        "Advisory cap must equal MAX_ISSUES_PER_CHECK, not a hardcoded literal"
+    )
+
+
+def test_advisory_should_flag_outer_constants_after_nested_def() -> None:
+    source_with_nested_def = (
+        "def outer():\n"
+        "    OUTER_CONST = 1\n"
+        "    def inner():\n"
+        "        INNER_CONST = 2\n"
+        "    ANOTHER_OUTER = 3\n"
+    )
+    advisory_issues = code_rules_enforcer.check_constants_outside_config_advisory(
+        source_with_nested_def,
+        "example_module.py",
+    )
+    flagged_names = " ".join(advisory_issues)
+    assert "OUTER_CONST" in flagged_names, (
+        "OUTER_CONST before nested def must be flagged"
+    )
+    assert "INNER_CONST" in flagged_names, (
+        "INNER_CONST inside nested def must be flagged"
+    )
+    assert "ANOTHER_OUTER" in flagged_names, (
+        "ANOTHER_OUTER after nested def must be flagged — this is the regression case"
+    )