claude-dev-env 1.78.0 → 1.80.0

package/hooks/blocking/test_code_rules_enforcer_docstring_field_runmode_outcome.py

@@ -0,0 +1,129 @@
+"""Tests for check_docstring_field_runmode_outcome — O6 run-mode-vs-per-record drift.
+
+A dataclass field whose name marks a run-mode flag (``is_dry_run``) is documented
+in the class Attributes block with per-record write-outcome prose ("True when no
+STP was written"), while the value is set the same way for every record from the
+run mode (``is_dry_run=not is_execute``). An already-OK record in an execute run
+writes no file yet still stores ``False``, so the per-record prose misleads every
+reader. This is the deterministic single-file slice of Category O6 drift.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_docstring_field_runmode_outcome(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_field_runmode_outcome(content, file_path)
+
+
+PRODUCTION_FILE_PATH = "/project/src/jsonl_writer.py"
+TEST_FILE_PATH = "/project/src/test_jsonl_writer.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _drifted_record() -> str:
+    return (
+        "@dataclass(frozen=True)\n"
+        "class PerThemeJsonlRecord:\n"
+        '    """Exact schema for the per-theme JSONL line.\n'
+        "\n"
+        "    Attributes:\n"
+        "        theme_name: Theme directory basename.\n"
+        "        is_dry_run: True when no STP was written.\n"
+        '    """\n'
+        "\n"
+        "    theme_name: str\n"
+        "    is_dry_run: bool\n"
+    )
+
+
+def _run_mode_record() -> str:
+    return (
+        "@dataclass(frozen=True)\n"
+        "class PerThemeJsonlRecord:\n"
+        '    """Exact schema for the per-theme JSONL line.\n'
+        "\n"
+        "    Attributes:\n"
+        "        theme_name: Theme directory basename.\n"
+        "        is_dry_run: True for a dry run; False for an execute run.\n"
+        '    """\n'
+        "\n"
+        "    theme_name: str\n"
+        "    is_dry_run: bool\n"
+    )
+
+
+def test_flags_run_mode_field_documented_as_per_record_write_outcome() -> None:
+    issues = check_docstring_field_runmode_outcome(_drifted_record(), PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "is_dry_run" in issues[0]
+    assert "run-mode" in issues[0]
+
+
+def test_run_mode_phrasing_is_left_alone() -> None:
+    issues = check_docstring_field_runmode_outcome(_run_mode_record(), PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_multiline_description_continuation_still_flags() -> None:
+    source = (
+        "@dataclass\n"
+        "class Record:\n"
+        '    """Schema.\n'
+        "\n"
+        "    Attributes:\n"
+        "        is_dry_run: True for the record when\n"
+        "            no STP was written.\n"
+        '    """\n'
+        "\n"
+        "    is_dry_run: bool\n"
+    )
+    issues = check_docstring_field_runmode_outcome(source, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+
+
+def test_non_run_mode_field_with_write_outcome_is_left_alone() -> None:
+    source = (
+        "@dataclass\n"
+        "class Record:\n"
+        '    """Schema.\n'
+        "\n"
+        "    Attributes:\n"
+        "        stp_path: Path the STP was written to disk.\n"
+        '    """\n'
+        "\n"
+        "    stp_path: str\n"
+    )
+    issues = check_docstring_field_runmode_outcome(source, PRODUCTION_FILE_PATH)
+    assert issues == []
+
+
+def test_test_file_is_exempt() -> None:
+    issues = check_docstring_field_runmode_outcome(_drifted_record(), TEST_FILE_PATH)
+    assert issues == []
+
+
+def test_hook_infrastructure_is_exempt() -> None:
+    issues = check_docstring_field_runmode_outcome(_drifted_record(), HOOK_INFRASTRUCTURE_PATH)
+    assert issues == []
+
+
+def test_syntax_error_returns_no_issues() -> None:
+    issues = check_docstring_field_runmode_outcome("class Record(\n", PRODUCTION_FILE_PATH)
+    assert issues == []

package/hooks/blocking/test_code_rules_enforcer_docstring_length_constant_superlative.py

@@ -0,0 +1,198 @@
+"""Tests for check_docstring_length_constant_superlative_vs_exact_gate.
+
+A config module defines an integer ``*_LENGTH`` constant and its docstring
+describes it with a superlative word ("the longest color string the swatch
+accepts"), while the only consumer treats the constant as an exact-length
+equality gate ("len(hex_color) != COLOR_AARRGGBB_LENGTH") in a sibling module.
+A shorter valid string is rejected, not accepted at a shorter length, so the
+"longest" prose claims a range of accepted lengths the code never allows. This
+is the deterministic exact-gate slice of Category O6/O8
+docstring-vs-implementation drift.
+
+The package trees these tests build live under a neutral OS temp directory
+rather than the pytest ``tmp_path`` fixture: the production check exempts any
+path containing "test", and the pytest fixture root carries that substring, so a
+fixture-rooted package would be skipped as test code and prove nothing.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import tempfile
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_length_gate(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_length_constant_superlative_vs_exact_gate(
+        content, file_path
+    )
+
+
+SUPERLATIVE_SWATCH_MODULE = '''"""Color-swatch rendering constants for the HTML run report.
+
+These constants name the longest color string the swatch accepts and the
+channel maximum the alpha byte is divided by.
+"""
+
+from typing import Final
+
+COLOR_AARRGGBB_LENGTH: Final[int] = 9
+'''
+
+
+def _run_gate_over_package(
+    swatch_content: str, consumer_body: str, swatch_basename: str = "color_swatch.py"
+) -> list[str]:
+    with tempfile.TemporaryDirectory() as temp_root:
+        config_directory = Path(temp_root) / "stp_contrast_fix" / "config"
+        config_directory.mkdir(parents=True)
+        swatch_path = config_directory / swatch_basename
+        swatch_path.write_text(swatch_content, encoding="utf-8")
+        consumer_path = config_directory.parent / "html_report_fragments.py"
+        consumer_path.write_text(consumer_body, encoding="utf-8")
+        return check_length_gate(swatch_content, str(swatch_path))
+
+
+def test_superlative_describing_exact_length_gate_is_flagged() -> None:
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH\n\n\n"
+        "def to_css(hex_color: str) -> str | None:\n"
+        '    if not hex_color.startswith("#") or len(hex_color) != '
+        "COLOR_AARRGGBB_LENGTH:\n"
+        "        return None\n"
+        "    return hex_color\n"
+    )
+    issues = _run_gate_over_package(SUPERLATIVE_SWATCH_MODULE, consumer_body)
+    assert len(issues) == 1
+    assert "COLOR_AARRGGBB_LENGTH" in issues[0]
+
+
+def test_ordered_comparison_treated_as_maximum_is_not_flagged() -> None:
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH\n\n\n"
+        "def truncated(hex_color: str) -> bool:\n"
+        "    return len(hex_color) <= COLOR_AARRGGBB_LENGTH\n"
+    )
+    assert _run_gate_over_package(SUPERLATIVE_SWATCH_MODULE, consumer_body) == []
+
+
+def test_no_superlative_phrase_is_not_flagged() -> None:
+    plain_module = (
+        '"""The exact required #AARRGGBB length the swatch renders."""\n\n'
+        "from typing import Final\n\n"
+        "COLOR_AARRGGBB_LENGTH: Final[int] = 9\n"
+    )
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH\n\n\n"
+        "def to_css(hex_color: str) -> bool:\n"
+        "    return len(hex_color) == COLOR_AARRGGBB_LENGTH\n"
+    )
+    assert _run_gate_over_package(plain_module, consumer_body) == []
+
+
+def test_constant_without_length_suffix_is_not_flagged() -> None:
+    non_length_module = (
+        '"""The longest swatch threshold value used by the renderer."""\n\n'
+        "from typing import Final\n\n"
+        "COLOR_CHANNEL_MAXIMUM: Final[int] = 255\n"
+    )
+    consumer_body = (
+        "from config.color_swatch import COLOR_CHANNEL_MAXIMUM\n\n\n"
+        "def saturated(channel: str) -> bool:\n"
+        "    return len(channel) == COLOR_CHANNEL_MAXIMUM\n"
+    )
+    assert _run_gate_over_package(non_length_module, consumer_body) == []
+
+
+def test_constant_with_no_length_comparison_is_not_flagged() -> None:
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH\n\n\n"
+        "def pad(hex_color: str) -> str:\n"
+        "    return hex_color.ljust(COLOR_AARRGGBB_LENGTH)\n"
+    )
+    assert _run_gate_over_package(SUPERLATIVE_SWATCH_MODULE, consumer_body) == []
+
+
+def test_superlative_in_function_docstring_is_not_flagged() -> None:
+    function_docstring_module = (
+        '"""The exact #AARRGGBB length the swatch renders."""\n\n'
+        "from typing import Final\n\n"
+        "COLOR_AARRGGBB_LENGTH: Final[int] = 9\n\n\n"
+        "def describe() -> str:\n"
+        '    """Return the longest color string the swatch accepts."""\n'
+        '    return "swatch"\n'
+    )
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH\n\n\n"
+        "def to_css(hex_color: str) -> bool:\n"
+        "    return len(hex_color) == COLOR_AARRGGBB_LENGTH\n"
+    )
+    assert _run_gate_over_package(function_docstring_module, consumer_body) == []
+
+
+def test_superlative_bound_to_other_constant_is_not_flagged() -> None:
+    two_constant_module = (
+        '"""Color-swatch rendering constants for the HTML run report.\n\n'
+        "COLOR_AARRGGBB_LENGTH is the exact #AARRGGBB length the swatch renders.\n"
+        "MAX_NAME_LENGTH is the longest swatch label the legend lays out.\n"
+        '"""\n\n'
+        "from typing import Final\n\n"
+        "COLOR_AARRGGBB_LENGTH: Final[int] = 9\n"
+        "MAX_NAME_LENGTH: Final[int] = 32\n"
+    )
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH, MAX_NAME_LENGTH\n\n\n"
+        "def to_css(hex_color: str) -> str | None:\n"
+        "    if len(hex_color) != COLOR_AARRGGBB_LENGTH:\n"
+        "        return None\n"
+        "    return hex_color\n\n\n"
+        "def fits(label: str) -> bool:\n"
+        "    return len(label) <= MAX_NAME_LENGTH\n"
+    )
+    assert _run_gate_over_package(two_constant_module, consumer_body) == []
+
+
+def test_superlative_bound_to_exact_gated_constant_is_flagged() -> None:
+    two_constant_module = (
+        '"""Color-swatch rendering constants for the HTML run report.\n\n'
+        "COLOR_AARRGGBB_LENGTH is the longest #AARRGGBB string the swatch accepts.\n"
+        "MAX_NAME_LENGTH is the exact swatch label width the legend lays out.\n"
+        '"""\n\n'
+        "from typing import Final\n\n"
+        "COLOR_AARRGGBB_LENGTH: Final[int] = 9\n"
+        "MAX_NAME_LENGTH: Final[int] = 32\n"
+    )
+    consumer_body = (
+        "from config.color_swatch import COLOR_AARRGGBB_LENGTH, MAX_NAME_LENGTH\n\n\n"
+        "def to_css(hex_color: str) -> str | None:\n"
+        "    if len(hex_color) != COLOR_AARRGGBB_LENGTH:\n"
+        "        return None\n"
+        "    return hex_color\n\n\n"
+        "def fits(label: str) -> bool:\n"
+        "    return len(label) <= MAX_NAME_LENGTH\n"
+    )
+    issues = _run_gate_over_package(two_constant_module, consumer_body)
+    assert len(issues) == 1
+    assert "COLOR_AARRGGBB_LENGTH" in issues[0]
+    assert "MAX_NAME_LENGTH" not in issues[0]
+
+
+def test_syntax_error_returns_empty() -> None:
+    issues = check_length_gate(
+        "def broken(\n", "/stp_contrast_fix/config/color_swatch.py"
+    )
+    assert issues == []

package/hooks/blocking/test_code_rules_enforcer_docstring_no_network.py

@@ -0,0 +1,115 @@
+"""Tests for check_docstring_no_network_claim_with_metadata_access — Category O6.
+
+A docstring promising a code path returns "without touching the network" drifts
+when the body calls a path-metadata method (``is_file``, ``stat``, ...): on a
+network share each metadata call is a round-trip over the wire, so the no-network
+claim is false. This is the deterministic slice of Category O6 (docstring prose
+versus implementation drift) for a no-network claim.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_docstring_no_network_claim(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_no_network_claim_with_metadata_access(
+        content, file_path
+    )
+
+
+PRODUCTION_FILE_PATH = "/project/shared_utils/bws/secret_fetch.py"
+TEST_FILE_PATH = "/project/shared_utils/bws/tests/test_secret_fetch.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def test_flags_no_network_claim_with_is_file_and_stat() -> None:
+    content = (
+        "def _ensure_local_bws_cache() -> str:\n"
+        '    """Return the local cache path, repopulating when stale.\n'
+        "\n"
+        "    An existing cache is returned without touching the network; a\n"
+        "    missing or size-mismatched cache is repopulated from the bundled\n"
+        "    executable.\n"
+        '    """\n'
+        "    if BUNDLED_BWS_EXECUTABLE_PATH.is_file():\n"
+        "        bundled_size = BUNDLED_BWS_EXECUTABLE_PATH.stat().st_size\n"
+        "        return str(LOCAL_BWS_CACHE_PATH)\n"
+        "    return str(LOCAL_BWS_CACHE_PATH)\n"
+    )
+    issues = check_docstring_no_network_claim(content, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1
+    assert "_ensure_local_bws_cache" in issues[0]
+    assert "without touching the network" in issues[0]
+
+
+def test_flags_no_network_access_phrase_with_exists() -> None:
+    content = (
+        "def read_warm_cache(cache_path) -> str:\n"
+        '    """Serve the warm cache with no network access."""\n'
+        "    if cache_path.exists():\n"
+        "        return cache_path.read_text()\n"
+        "    return ''\n"
+    )
+    assert len(check_docstring_no_network_claim(content, PRODUCTION_FILE_PATH)) == 1
+
+
+def test_passes_when_claim_present_but_no_metadata_access() -> None:
+    content = (
+        "def read_warm_cache(cache_path) -> str:\n"
+        '    """Serve the warm cache without touching the network."""\n'
+        "    return cache_path.read_text()\n"
+    )
+    assert check_docstring_no_network_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_passes_when_metadata_access_but_no_network_claim() -> None:
+    content = (
+        "def _ensure_local_bws_cache(share_path) -> str:\n"
+        '    """Return the local cache path, repopulating when stale.\n'
+        "\n"
+        "    The bundled share is stat-checked on every call to validate the\n"
+        "    cache against the bundled executable size.\n"
+        '    """\n'
+        "    if share_path.is_file():\n"
+        "        return str(share_path)\n"
+        "    return ''\n"
+    )
+    assert check_docstring_no_network_claim(content, PRODUCTION_FILE_PATH) == []
+
+
+def test_test_files_are_exempt() -> None:
+    content = (
+        "def _ensure_local_bws_cache(share_path) -> str:\n"
+        '    """Return the cache without touching the network."""\n'
+        "    if share_path.is_file():\n"
+        "        return str(share_path)\n"
+        "    return ''\n"
+    )
+    assert check_docstring_no_network_claim(content, TEST_FILE_PATH) == []
+
+
+def test_hook_infrastructure_is_exempt() -> None:
+    content = (
+        "def _ensure_local_bws_cache(share_path) -> str:\n"
+        '    """Return the cache without touching the network."""\n'
+        "    if share_path.is_file():\n"
+        "        return str(share_path)\n"
+        "    return ''\n"
+    )
+    assert check_docstring_no_network_claim(content, HOOK_INFRASTRUCTURE_PATH) == []

package/hooks/blocking/test_code_rules_enforcer_docstring_unreferenced_param.py

@@ -0,0 +1,160 @@
+"""Tests for check_docstring_documents_unreferenced_parameter.
+
+A parameter named in the ``Args:`` block but referenced nowhere in the body is
+dead: the function does not read it, yet the docstring describes behavior keyed
+to it. The common shape is a flag a caller wired in before the real logic moved
+up a level, leaving the parameter and its Args line claiming a behavior the body
+does not implement.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+
+def check_documents_unreferenced_parameter(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_docstring_documents_unreferenced_parameter(content, file_path)
+
+
+def validate_content(content: str, file_path: str, old_content: str) -> list[str]:
+    return code_rules_enforcer.validate_content(content, file_path, old_content)
+
+
+PRODUCTION_FILE_PATH = "/project/src/per_theme_loop.py"
+TEST_FILE_PATH = "/project/src/test_per_theme_loop.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _function_with_dead_documented_flag() -> str:
+    return (
+        "def run_per_theme_loop_and_finalize(themes: list, is_no_notify: bool) -> int:\n"
+        '    """Run the per-theme loop and finalize the report.\n'
+        "\n"
+        "    Args:\n"
+        "        themes: The themes to process.\n"
+        "        is_no_notify: When True, suppresses opening the HTML report.\n"
+        "\n"
+        "    Returns:\n"
+        "        The resolved exit code.\n"
+        '    """\n'
+        "    exit_code = 0\n"
+        "    for each_theme in themes:\n"
+        "        exit_code = max(exit_code, each_theme.run())\n"
+        "    render_and_write_html_report(themes)\n"
+        "    return exit_code\n"
+    )
+
+
+def test_should_flag_documented_parameter_never_referenced() -> None:
+    issues = check_documents_unreferenced_parameter(
+        _function_with_dead_documented_flag(), PRODUCTION_FILE_PATH
+    )
+    assert any("is_no_notify" in each for each in issues), (
+        f"Expected dead 'is_no_notify' flag, got: {issues!r}"
+    )
+    assert len(issues) == 1
+
+
+def test_should_not_flag_parameter_referenced_in_body() -> None:
+    source = (
+        "def run_per_theme_loop_and_finalize(themes: list, is_no_notify: bool) -> int:\n"
+        '    """Run the per-theme loop and finalize the report.\n'
+        "\n"
+        "    Args:\n"
+        "        themes: The themes to process.\n"
+        "        is_no_notify: When True, suppresses opening the HTML report.\n"
+        "\n"
+        "    Returns:\n"
+        "        The resolved exit code.\n"
+        '    """\n'
+        "    exit_code = 0\n"
+        "    for each_theme in themes:\n"
+        "        exit_code = max(exit_code, each_theme.run())\n"
+        "    if not is_no_notify:\n"
+        "        open_html_report(themes)\n"
+        "    return exit_code\n"
+    )
+    issues = check_documents_unreferenced_parameter(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Referenced parameter must not be flagged, got: {issues!r}"
+
+
+def test_should_not_flag_when_kwargs_present() -> None:
+    source = (
+        "def render(themes: list, is_no_notify: bool, **overrides) -> int:\n"
+        '    """Render the report.\n'
+        "\n"
+        "    Args:\n"
+        "        themes: The themes to process.\n"
+        "        is_no_notify: When True, suppresses opening the report.\n"
+        '    """\n'
+        "    settings = dict(overrides)\n"
+        "    for each_theme in themes:\n"
+        "        each_theme.render(settings)\n"
+        "    return 0\n"
+    )
+    issues = check_documents_unreferenced_parameter(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"**kwargs functions must be skipped, got: {issues!r}"
+
+
+def test_should_skip_private_function() -> None:
+    source = (
+        "def _drive(themes: list, is_no_notify: bool) -> int:\n"
+        '    """Drive internally.\n'
+        "\n"
+        "    Args:\n"
+        "        themes: The themes to process.\n"
+        "        is_no_notify: When True, suppresses the report.\n"
+        '    """\n'
+        "    exit_code = 0\n"
+        "    for each_theme in themes:\n"
+        "        exit_code = max(exit_code, each_theme.run())\n"
+        "    return exit_code\n"
+    )
+    issues = check_documents_unreferenced_parameter(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Private functions exempt, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_documents_unreferenced_parameter(
+        _function_with_dead_documented_flag(), TEST_FILE_PATH
+    )
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_documents_unreferenced_parameter(
+        _function_with_dead_documented_flag(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_documents_unreferenced_parameter("def fetch(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def test_validate_content_surfaces_unreferenced_parameter() -> None:
+    issues = validate_content(
+        _function_with_dead_documented_flag(), PRODUCTION_FILE_PATH, old_content=""
+    )
+    matching_issues = [
+        each for each in issues if "is_no_notify" in each and "never references" in each
+    ]
+    assert matching_issues, (
+        f"Expected validate_content to surface the dead-parameter issue, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_js_returns_object.py

@@ -0,0 +1,72 @@
+"""Enforcer-dispatch tests for the JS returns-object schema-less branch check.
+
+These drive ``validate_content`` end-to-end on a ``.mjs`` payload, so they prove
+the check is wired into the JavaScript branch of the enforcer, not just callable
+in isolation. The drift: a ``function`` whose JSDoc ``@returns {Promise<object>}``
+promises a structured object while one branch returns the agent helper with an
+options object that omits ``schema`` and so resolves to a transcript string.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+_HOOKS_DIRECTORY = str(Path(__file__).resolve().parent.parent)
+if _HOOKS_DIRECTORY not in sys.path:
+    sys.path.insert(0, _HOOKS_DIRECTORY)
+
+
+def _load_enforcer_module() -> ModuleType:
+    module_path = Path(__file__).parent / "code_rules_enforcer.py"
+    spec = importlib.util.spec_from_file_location("code_rules_enforcer", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+code_rules_enforcer = _load_enforcer_module()
+
+_MJS_PATH = "skills/autoconverge/workflow/converge.mjs"
+
+
+def _mixed_schema_mjs() -> str:
+    return (
+        "/**\n"
+        " * Spawn a git-utility agent.\n"
+        " * @returns {Promise<object>} the structured output\n"
+        " */\n"
+        "function runGitTask(task, head) {\n"
+        "  if (task === 'resolve-head') {\n"
+        "    return convergeAgent(`head ${x}`, { label: 'g', schema: HEAD_SCHEMA, agentType: 'Explore' })\n"
+        "  }\n"
+        "  return convergeAgent(`fetch ${x}`, { label: 'g', agentType: 'Explore' })\n"
+        "}\n"
+    )
+
+
+def _all_schema_mjs() -> str:
+    return _mixed_schema_mjs().replace(
+        "{ label: 'g', agentType: 'Explore' })",
+        "{ label: 'g', schema: FETCH_SCHEMA, agentType: 'Explore' })",
+    )
+
+
+def _has_returns_object_finding(all_issues: list[str]) -> bool:
+    return any("runGitTask" in each_issue and "@returns" in each_issue for each_issue in all_issues)
+
+
+def test_enforcer_reports_schema_less_branch_under_returns_object() -> None:
+    drift_source = _mixed_schema_mjs()
+    all_issues = code_rules_enforcer.validate_content(drift_source, _MJS_PATH, drift_source)
+    assert _has_returns_object_finding(all_issues)
+
+
+def test_enforcer_accepts_every_branch_with_a_schema() -> None:
+    clean_source = _all_schema_mjs()
+    all_issues = code_rules_enforcer.validate_content(clean_source, _MJS_PATH, clean_source)
+    assert not _has_returns_object_finding(all_issues)