claude-dev-env 1.49.0 → 1.50.0

package/hooks/blocking/test_code_rules_enforcer_naming_pattern.py

@@ -26,7 +26,7 @@ TEST_FILE_PATH = "src/app/test_feature.py"
 CONFIG_FILE_PATH = "src/config/settings.py"
 WORKFLOW_FILE_PATH = "src/workflow/orders_tab.py"
 HOOK_FILE_PATH = "/home/user/.claude/hooks/blocking/my_hook.py"
-EXPECTED_PREFIX_GUIDANCE = "prefix with is_/has_/should_/can_"
+EXPECTED_PREFIX_GUIDANCE = "prefix with is_/has_/should_/can_/was_/did_"
 
 
 def _assert_flags_name(issues: list[str], name: str, line_number: int) -> None:
@@ -210,3 +210,139 @@ def test_should_allow_is_prefix_at_start_when_compound_word_follows() -> None:
     assert issues == [], (
         f"is_left_upper_snake has prefix at position 0, must pass, got: {issues}"
     )
+
+
+PARAMETER_PREFIX_GUIDANCE = "prefix with is_/has_/should_/can_/was_/did_"
+
+
+def _assert_flags_parameter(issues: list[str], name: str, line_number: int) -> None:
+    expected = f"Line {line_number}: Boolean parameter {name} - {PARAMETER_PREFIX_GUIDANCE}"
+    assert expected in issues, f"expected {expected!r} in {issues!r}"
+
+
+def test_should_flag_bool_annotated_parameter_without_prefix() -> None:
+    source = "def run(dry_run: bool) -> None:\n    print(dry_run)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_parameter(issues, "dry_run", 1)
+    assert len(issues) == 1
+
+
+def test_should_flag_bool_default_parameter_without_annotation() -> None:
+    source = "def run(apply_historical_weight=False) -> None:\n    print(apply_historical_weight)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_parameter(issues, "apply_historical_weight", 1)
+    assert len(issues) == 1
+
+
+def test_should_flag_keyword_only_bool_parameter_without_prefix() -> None:
+    source = "def run(*, click_succeeded: bool = True) -> None:\n    print(click_succeeded)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_parameter(issues, "click_succeeded", 1)
+    assert len(issues) == 1
+
+
+def test_should_allow_is_prefixed_bool_parameter() -> None:
+    source = "def run(is_dry_run: bool) -> None:\n    print(is_dry_run)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_allow_was_prefixed_bool_parameter() -> None:
+    source = "def run(was_clicked: bool = False) -> None:\n    print(was_clicked)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_allow_did_prefixed_bool_parameter() -> None:
+    source = "def run(did_succeed: bool) -> None:\n    print(did_succeed)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_allow_was_prefixed_bool_assignment() -> None:
+    source = "def f() -> None:\n    was_clicked = True\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_allow_did_prefixed_bool_assignment() -> None:
+    source = "def f() -> None:\n    did_run = False\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_skip_single_letter_bool_parameter() -> None:
+    source = "def run(x: bool) -> None:\n    print(x)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_skip_self_parameter_in_method() -> None:
+    source = (
+        "class Runner:\n"
+        "    def run(self, enabled: bool) -> None:\n"
+        "        print(self, enabled)\n"
+    )
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_parameter(issues, "enabled", 2)
+    assert len(issues) == 1
+
+
+def test_should_not_flag_non_bool_parameter() -> None:
+    source = "def run(retries: int) -> None:\n    print(retries)\n"
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_should_skip_bool_parameter_in_test_file() -> None:
+    source = "def run(dry_run: bool) -> None:\n    print(dry_run)\n"
+    issues = check_boolean_naming(source, TEST_FILE_PATH)
+    assert issues == []
+
+
+def test_should_pair_positional_defaults_right_aligned() -> None:
+    source = (
+        "def run(name: str, verbose: bool = False) -> None:\n"
+        "    print(name, verbose)\n"
+    )
+    issues = check_boolean_naming(source, PRODUCTION_FILE_PATH)
+    _assert_flags_parameter(issues, "verbose", 1)
+    assert len(issues) == 1
+
+
+FULL_MODULE_WITH_TWO_UNPREFIXED_BOOL_PARAMETERS = (
+    "def pre_existing(verbose: bool) -> None:\n"
+    "    print(verbose)\n"
+    "\n\n"
+    "def edited(detailed: bool) -> None:\n"
+    "    print(detailed)\n"
+)
+PRE_EXISTING_BOOL_PARAMETER_LINE_NUMBER = 1
+EDITED_BOOL_PARAMETER_LINE_NUMBER = 5
+
+
+def test_should_flag_bool_parameter_on_changed_line() -> None:
+    issues = check_boolean_naming(
+        FULL_MODULE_WITH_TWO_UNPREFIXED_BOOL_PARAMETERS,
+        PRODUCTION_FILE_PATH,
+        {EDITED_BOOL_PARAMETER_LINE_NUMBER},
+        False,
+    )
+    _assert_flags_parameter(issues, "detailed", EDITED_BOOL_PARAMETER_LINE_NUMBER)
+    assert len(issues) == 1, (
+        "Only the bool parameter on the changed line must be flagged, got: "
+        f"{issues!r}"
+    )
+
+
+def test_should_not_flag_pre_existing_bool_parameter_on_unchanged_line() -> None:
+    issues = check_boolean_naming(
+        FULL_MODULE_WITH_TWO_UNPREFIXED_BOOL_PARAMETERS,
+        PRODUCTION_FILE_PATH,
+        {EDITED_BOOL_PARAMETER_LINE_NUMBER},
+        False,
+    )
+    assert not any("verbose" in each_issue for each_issue in issues), (
+        "A pre-existing unprefixed bool parameter on an unedited line must not block "
+        f"the edit, got: {issues!r}"
+    )

package/hooks/blocking/test_md_to_html_blocker.py

@@ -252,6 +252,44 @@ def test_blocks_changelog_not_at_root():
     assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
 
 
+def test_passes_claude_md_at_root():
+    result = _run_hook(
+        "Write",
+        {"file_path": "CLAUDE.md", "content": "# CLAUDE"},
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_passes_agents_md_at_root():
+    result = _run_hook(
+        "Write",
+        {"file_path": "AGENTS.md", "content": "# AGENTS"},
+    )
+    assert result.returncode == 0
+    assert result.stdout == ""
+
+
+def test_blocks_claude_md_not_at_root():
+    result = _run_hook(
+        "Write",
+        {"file_path": "docs/CLAUDE.md", "content": "# CLAUDE"},
+    )
+    assert result.returncode == 0
+    output = json.loads(result.stdout)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_blocks_agents_md_not_at_root():
+    result = _run_hook(
+        "Write",
+        {"file_path": "sub/AGENTS.md", "content": "# AGENTS"},
+    )
+    assert result.returncode == 0
+    output = json.loads(result.stdout)
+    assert output["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
 def test_blocks_relative_readme_when_cwd_is_not_repo_root():
     sandbox_parent = _get_sandbox_parent_directory()
     non_repo_cwd = os.path.join(sandbox_parent, "not-a-repo")

package/hooks/hooks_constants/blocking_check_limits.py

@@ -16,6 +16,8 @@ MAX_BARE_EXCEPT_ISSUES: int = 3
 MAX_BOUNDARY_TYPE_ISSUES: int = 5
 ALL_BANNED_PREFIX_NAMES: tuple[str, ...] = ("handle_", "process_", "manage_", "do_")
 MAX_DOCSTRING_FORMAT_ISSUES: int = 5
+MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES: int = 5
+MAX_IGNORED_MUST_CHECK_RETURN_ISSUES: int = 5
 MAX_TYPE_ESCAPE_HATCH_ISSUES: int = 5
 MAX_THIN_WRAPPER_ISSUES: int = 1
 DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT: int = 3

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -24,9 +24,23 @@ ALL_MIGRATION_PATH_PATTERNS = {"/migrations/", "\\migrations\\"}
 ADVISORY_LINE_THRESHOLD_SOFT = 400
 ADVISORY_LINE_THRESHOLD_HARD = 1000
 
-ALL_BOOLEAN_NAME_PREFIXES: tuple[str, ...] = ("is_", "has_", "should_", "can_")
+ALL_BOOLEAN_NAME_PREFIXES: tuple[str, ...] = ("is_", "has_", "should_", "can_", "was_", "did_")
 UPPER_SNAKE_CONSTANT_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
 
+ALL_MUST_CHECK_RETURN_FUNCTION_NAMES: frozenset[str] = frozenset({"find_and_click", "write_outcome"})
+
+DOCSTRING_ARG_ENTRY_PATTERN: re.Pattern[str] = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)\s*[:(]")
+ALL_DOCSTRING_ARGS_SECTION_HEADERS: tuple[str, ...] = ("Args:", "Arguments:")
+ALL_DOCSTRING_TERMINATING_SECTION_HEADERS: frozenset[str] = frozenset({
+    "Returns:",
+    "Yields:",
+    "Raises:",
+    "Examples:",
+    "Example:",
+    "Note:",
+    "Notes:",
+})
+
 
 TYPE_CHECKING_BLOCK_PATTERN = re.compile(r"^(?P<indent>\s*)if\s+(typing\.)?TYPE_CHECKING\s*:\s*$")
 ALL_IMPORT_STATEMENT_PREFIXES: tuple[str, ...] = ("import ", "from ")

package/hooks/hooks_constants/md_to_html_blocker_constants.py

@@ -19,7 +19,7 @@ MINIMUM_SEGMENT_COUNT_TO_MATCH_INDICATOR: int = 4
 ALL_EXEMPT_ANYWHERE_FILENAMES: tuple[str, ...] = ("SKILL.md",)
 ALL_EXEMPT_PLUGIN_DIRECTORY_SEGMENTS: tuple[str, ...] = ("agents", "skills", "commands")
 ALL_EXEMPT_HOME_RELATIVE_DIRECTORIES: tuple[str, ...] = ("SessionLog",)
-ALL_EXEMPT_ROOT_FILENAMES: tuple[str, ...] = ("readme.md", "changelog.md")
+ALL_EXEMPT_ROOT_FILENAMES: tuple[str, ...] = ("readme.md", "changelog.md", "claude.md", "agents.md")
 REPO_ROOT_MARKER_NAME: str = ".git"
 CLAUDE_DIRECTORY_NAME: str = ".claude"
 PLUGIN_ROOT_MARKER_DIRECTORY_NAME: str = ".claude-plugin"

package/hooks/hooks_constants/test_md_to_html_blocker_constants.py

@@ -82,10 +82,17 @@ def test_exempt_home_relative_directories_include_session_log() -> None:
     assert "ALL_EXEMPT_HOME_RELATIVE_DIRECTORIES" in constants_module.__all__
 
 
-def test_exempt_root_filenames_cover_readme_and_changelog() -> None:
-    """README.md and CHANGELOG.md at a repo root are universally exempt;
-    every repo with a `.git` marker satisfies the root check."""
-    assert constants_module.ALL_EXEMPT_ROOT_FILENAMES == ("readme.md", "changelog.md")
+def test_exempt_root_filenames_cover_readme_changelog_claude_and_agents() -> None:
+    """README.md, CHANGELOG.md, CLAUDE.md, and AGENTS.md at a repo root are
+    universally exempt; every repo with a `.git` marker satisfies the root
+    check. CLAUDE.md and AGENTS.md are functional agent-instruction files that
+    Claude Code loads by name and must stay Markdown."""
+    assert constants_module.ALL_EXEMPT_ROOT_FILENAMES == (
+        "readme.md",
+        "changelog.md",
+        "claude.md",
+        "agents.md",
+    )
     assert "ALL_EXEMPT_ROOT_FILENAMES" in constants_module.__all__
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.49.0",
+    "version": "1.50.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -20,6 +20,7 @@
         "system-prompts/",
         "scripts/",
         "_shared/",
+        "audit-rubrics/",
         "CLAUDE.md"
     ],
     "keywords": [

package/skills/bugteam/reference/teardown-publish-permissions.md

@@ -2,7 +2,12 @@
 
 ## Utility scripts (progressive disclosure)
 
-Fragile or repeatable shell sequences belong in `_shared/pr-loop/scripts/`. Bugteam-specific scripts (e.g. revoke, see Step 5) live in the skill-local [`scripts/`](../scripts/) directory. Anthropic: [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) — utility scripts are **executed**, not loaded into context as primary reading. Shared-script inventory: [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md). Bugteam-script inventory: [`../scripts/README.md`](../scripts/README.md). Gate-only merge-base / diff semantics: [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md).
+Fragile or repeatable shell sequences live in one of two shared script directories. Match the reference depth to the directory:
+
+- **Package-root** [`_shared/pr-loop/scripts/`](../../../_shared/pr-loop/scripts/) holds `code_rules_gate.py`, `preflight.py`, `post_audit_thread.py`, and the permission helpers. Reference it as `../../../_shared/…` in markdown and `${CLAUDE_SKILL_DIR}/../../_shared/…` at runtime (resolves to `~/.claude/_shared/`). Inventory: [`../../../_shared/pr-loop/scripts/README.md`](../../../_shared/pr-loop/scripts/README.md).
+- **Skill-tree** [`skills/_shared/pr-loop/scripts/`](../../_shared/pr-loop/scripts/) holds `teardown_worktrees.py`, `build_audit_prompt.py`, `build_fix_prompt.py`, `init_loop_state.py`, `write_audit_outcomes.py`, `write_fix_outcomes.py`, and `_path_resolver.py`. Reference it as `../../_shared/…` in markdown and `${CLAUDE_SKILL_DIR}/../_shared/…` at runtime (resolves to `~/.claude/skills/_shared/`).
+
+Bugteam-specific scripts (e.g. revoke, see Step 5) live in the skill-local [`scripts/`](../scripts/) directory. Anthropic: [Progressive disclosure patterns](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices#progressive-disclosure-patterns) — utility scripts are **executed**, not loaded into context as primary reading. Bugteam-script inventory: [`../scripts/README.md`](../scripts/README.md). Gate-only merge-base / diff semantics: [`../../../_shared/pr-loop/code-rules-gate.md`](../../../_shared/pr-loop/code-rules-gate.md).
 
 ### Pre-flight (recommended before Step 0)
 
@@ -19,7 +24,7 @@ When the cycle exits (any reason), run these steps in order from **this** sessio
    directory (Windows-safe `shutil.rmtree`):
 
    ```bash
-   python "${CLAUDE_SKILL_DIR}/../../_shared/pr-loop/scripts/teardown_worktrees.py" \
+   python "${CLAUDE_SKILL_DIR}/../_shared/pr-loop/scripts/teardown_worktrees.py" \
      --run-temp-dir "<run_temp_dir>" \
      --all-pr-jsons '<json array of {number, owner, repo}>'
    ```