claude-dev-env 1.67.2 → 1.69.0

package/hooks/blocking/code_rules_docstrings.py

@@ -20,11 +20,17 @@ from code_rules_shared import (  # noqa: E402
 )
 
 from hooks_constants.blocking_check_limits import (  # noqa: E402
+    ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES,
     ALL_DOCSTRING_EXEMPT_DECORATOR_NAMES,
     ALL_DOCSTRING_IMPLICIT_INSTANCE_PARAMETER_NAMES,
+    ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES,
+    DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT,
     DOCSTRING_TRIVIAL_FUNCTION_BODY_LINE_LIMIT,
+    MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES,
     MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES,
+    MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES,
     MAX_DOCSTRING_FORMAT_ISSUES,
+    MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_DOCSTRING_ARGS_SECTION_HEADERS,
@@ -306,3 +312,250 @@ def check_docstring_args_match_signature(content: str, file_path: str) -> list[s
             if len(issues) >= MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES:
                 return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]
     return issues[:MAX_DOCSTRING_ARGS_SIGNATURE_ISSUES]
+
+
+def _callee_expression_name(expression: ast.expr) -> str:
+    if isinstance(expression, ast.Name):
+        return expression.id
+    if isinstance(expression, ast.Attribute):
+        receiver_name = _callee_expression_name(expression.value)
+        if not receiver_name:
+            return ast.unparse(expression)
+        return f"{receiver_name}.{expression.attr}"
+    return ""
+
+
+def _call_callee_name(call_node: ast.Call) -> str:
+    return _callee_expression_name(call_node.func)
+
+
+def _branch_routes_directly_to_call(branch_node: ast.If) -> str:
+    """Return the callee name an early-return guard routes to, or empty string.
+
+    A guard counts when its block contains exactly one call expression and then
+    returns. A second call expression disqualifies the block; non-call
+    statements such as an assignment or a loop are skipped and do not
+    disqualify it. The await wrapper around an async call is unwrapped first.
+    """
+    routed_callee = ""
+    saw_return = False
+    for each_statement in branch_node.body:
+        candidate_expression: ast.expr | None = None
+        if isinstance(each_statement, ast.Expr):
+            candidate_expression = each_statement.value
+        elif isinstance(each_statement, ast.Return):
+            saw_return = True
+            continue
+        if candidate_expression is None:
+            continue
+        if isinstance(candidate_expression, ast.Await):
+            candidate_expression = candidate_expression.value
+        if not isinstance(candidate_expression, ast.Call):
+            return ""
+        if routed_callee:
+            return ""
+        routed_callee = _call_callee_name(candidate_expression)
+    if not saw_return:
+        return ""
+    return routed_callee
+
+
+def _shared_fallback_route_count(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> tuple[str, int]:
+    route_count_by_callee: dict[str, int] = {}
+    for each_statement in function_node.body:
+        if not isinstance(each_statement, ast.If):
+            continue
+        routed_callee = _branch_routes_directly_to_call(each_statement)
+        if not routed_callee:
+            continue
+        route_count_by_callee[routed_callee] = (
+            route_count_by_callee.get(routed_callee, 0) + 1
+        )
+    if not route_count_by_callee:
+        return "", 0
+    busiest_callee = max(route_count_by_callee, key=lambda name: route_count_by_callee[name])
+    return busiest_callee, route_count_by_callee[busiest_callee]
+
+
+def _summary_contains_phrase_at_word_boundary(summary_text: str, phrase: str) -> bool:
+    search_start = 0
+    while True:
+        match_index = summary_text.find(phrase, search_start)
+        if match_index == -1:
+            return False
+        preceding_is_boundary = (
+            match_index == 0 or not summary_text[match_index - 1].isalnum()
+        )
+        following_index = match_index + len(phrase)
+        following_is_boundary = (
+            following_index >= len(summary_text)
+            or not summary_text[following_index].isalnum()
+        )
+        if preceding_is_boundary and following_is_boundary:
+            return True
+        search_start = match_index + 1
+
+
+def _summary_joins_multiple_conditions(summary_text: str) -> bool:
+    return any(
+        joining_phrase in summary_text
+        for joining_phrase in ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES
+    )
+
+
+def _docstring_summary_scopes_a_single_condition(docstring_text: str) -> bool:
+    summary_text = docstring_text.split("\n\n", 1)[0].lower()
+    has_scope_phrase = any(
+        _summary_contains_phrase_at_word_boundary(summary_text, each_phrase)
+        for each_phrase in ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES
+    )
+    if not has_scope_phrase:
+        return False
+    return not _summary_joins_multiple_conditions(summary_text)
+
+
+def check_docstring_fallback_branch_coverage(content: str, file_path: str) -> list[str]:
+    """Flag a fallback docstring that scopes a branch the body reaches twice.
+
+    The drift this catches: a function whose summary describes a fallback
+    action under a single condition (``only when``, ``falls back to ... when``)
+    while the body routes to that same fallback call from two or more distinct
+    early-return guards. The second guard fires under a condition the prose
+    never names, so the enumeration the reader trusts is incomplete. This is
+    the deterministic slice of Category O6 (docstring prose vs implementation
+    drift): a structural branch-count-versus-prose-condition mismatch.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per function whose fallback prose omits a second route to the
+        same call, capped at the module limit.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_has_exempt_decorator(each_node):
+            continue
+        docstring_text = _function_docstring_text(each_node)
+        if not docstring_text:
+            continue
+        if not _docstring_summary_scopes_a_single_condition(docstring_text):
+            continue
+        fallback_callee, route_count = _shared_fallback_route_count(each_node)
+        if route_count < DOCSTRING_FALLBACK_BRANCH_MINIMUM_ROUTE_COUNT:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name}() docstring scopes a fallback to "
+            f"one condition, but the body routes to {fallback_callee}() from {route_count} "
+            "distinct branches — enumerate every condition that reaches the fallback "
+            "(Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_FALLBACK_BRANCH_ISSUES]
+
+
+def _class_docstring_summary_is_single_line(docstring_text: str) -> bool:
+    stripped_text = docstring_text.strip()
+    if not stripped_text:
+        return False
+    summary_line, separator, _remainder = stripped_text.partition("\n")
+    if separator and stripped_text[len(summary_line):].strip():
+        return False
+    return bool(summary_line.strip())
+
+
+def _public_method_names(class_node: ast.ClassDef) -> list[str]:
+    deduplicated_names: dict[str, None] = {}
+    for each_statement in class_node.body:
+        if not isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            continue
+        if _function_is_private_or_dunder(each_statement.name):
+            continue
+        deduplicated_names[each_statement.name] = None
+    return list(deduplicated_names)
+
+
+def _name_tokens(method_name: str) -> list[str]:
+    return [each_token for each_token in method_name.split("_") if each_token]
+
+
+def _docstring_mentions_method(docstring_text: str, method_name: str) -> bool:
+    lowered_docstring = docstring_text.lower()
+    if method_name.lower() in lowered_docstring:
+        return True
+    return all(
+        each_token.lower() in lowered_docstring for each_token in _name_tokens(method_name)
+    )
+
+
+def _unmentioned_public_methods(class_node: ast.ClassDef, docstring_text: str) -> list[str]:
+    return [
+        each_name
+        for each_name in _public_method_names(class_node)
+        if not _docstring_mentions_method(docstring_text, each_name)
+    ]
+
+
+def check_class_docstring_names_public_methods(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a one-line class docstring that omits two or more public methods.
+
+    A class whose docstring is a single summary line names one responsibility,
+    so a reader trusts that line to describe the whole class. When the class
+    later gains a second public entry point — the drift pattern where a
+    coffee-break reporter grows a regular-pace method — the terse summary keeps
+    describing only the original feature. Each public method whose name (or all
+    of its underscore-separated tokens) appears nowhere in the summary counts as
+    omitted; a class with two or more omitted public methods is reported so the
+    summary is widened to name the broader surface. Classes with a multi-line
+    docstring body are left to the audit lane, since their prose can carry the
+    enumeration without naming each method by name.
+
+    Args:
+        content: The source text to inspect.
+        file_path: The path the source will be written to, used for exemptions.
+
+    Returns:
+        One issue per class whose single-line docstring omits two or more of its
+        public methods, capped at the module limit.
+    """
+    if is_test_file(file_path) or is_hook_infrastructure(file_path):
+        return []
+    try:
+        parsed_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in _walk_skipping_type_checking_blocks(parsed_tree):
+        if not isinstance(each_node, ast.ClassDef):
+            continue
+        class_docstring = ast.get_docstring(each_node) or ""
+        if not _class_docstring_summary_is_single_line(class_docstring):
+            continue
+        public_names = _public_method_names(each_node)
+        if len(public_names) < MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH:
+            continue
+        unmentioned_names = _unmentioned_public_methods(each_node, class_docstring)
+        if len(unmentioned_names) < MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH:
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name} one-line docstring omits "
+            f"public method(s) {', '.join(unmentioned_names)} — widen the summary "
+            "so it names the class's full public surface"
+        )
+        if len(issues) >= MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES:
+            break
+    return issues[:MAX_CLASS_DOCSTRING_PUBLIC_METHOD_ISSUES]

package/hooks/blocking/code_rules_enforcer.py

@@ -65,7 +65,9 @@ from code_rules_dead_module_constant import (  # noqa: E402
     check_dead_module_constants,
 )
 from code_rules_docstrings import (  # noqa: E402
+    check_class_docstring_names_public_methods,
     check_docstring_args_match_signature,
+    check_docstring_fallback_branch_coverage,
     check_docstring_format,
 )
 from code_rules_duplicate_body import (  # noqa: E402
@@ -248,6 +250,10 @@ def validate_content(
         all_issues.extend(check_boundary_types(effective_content, file_path))
         all_issues.extend(check_docstring_format(effective_content, file_path))
         all_issues.extend(check_docstring_args_match_signature(effective_content, file_path))
+        all_issues.extend(check_docstring_fallback_branch_coverage(effective_content, file_path))
+        all_issues.extend(
+            check_class_docstring_names_public_methods(effective_content, file_path)
+        )
         all_issues.extend(
             check_boolean_naming(
                 effective_content,

package/hooks/blocking/config/CLAUDE.md

@@ -0,0 +1,22 @@
+# hooks/blocking/config
+
+A Python package that holds shared constants for the verified-commit gate family. Three modules in `blocking/` import from here:
+
+- `verification_verdict_store.py`
+- `verified_commit_gate.py`
+- `verifier_verdict_minter.py`
+
+## Key files
+
+| File | Contents |
+|---|---|
+| `__init__.py` | Declares this as a regular package (not a namespace package) so it resolves first on `sys.path` |
+| `verified_commit_constants.py` | All tunables for the gate: directory names, regex patterns for detecting verdict paths and obfuscation attempts, timeout values, git subcommand sets, bypass marker, and corrective messages |
+
+## Key constants in `verified_commit_constants.py`
+
+- `VERIFICATION_BYPASS_MARKER` — the `# verify-skip` comment that exempts a single commit/push from the gate
+- `MINTING_AGENT_TYPE` — `"code-verifier"`, the agent type whose SubagentStop hook mints verdicts
+- `VERDICT_DIRECTORY_NAME` — `"verification"`, the directory under `~/.claude/` that holds verdict JSON files
+- `DOCS_ONLY_EXTENSIONS` — extensions (`.md`, `.txt`, images) whose changes are mechanically exempt from the gate
+- `CORRECTIVE_MESSAGE` / `VERDICT_DIRECTORY_GUARD_MESSAGE` — user-facing block messages

package/hooks/blocking/test_code_rules_enforcer_class_docstring_methods.py

@@ -0,0 +1,262 @@
+"""Tests for check_class_docstring_names_public_methods — class prose breadth.
+
+A class whose docstring is a single summary line names one responsibility. When
+the class exposes a second public entry point the summary never names, the prose
+under-describes the class — the same drift the os_update_workflow break reporter
+hit when it grew a regular-pace method beside its coffee-break method.
+"""
+
+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_class_docstring_names_public_methods(content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_class_docstring_names_public_methods(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/break_reporter.py"
+TEST_FILE_PATH = "/project/src/test_break_reporter.py"
+HOOK_INFRASTRUCTURE_PATH = "/home/user/.claude/hooks/blocking/example.py"
+
+
+def _narrow_class_with_widened_surface() -> str:
+    return (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility: announce, then count down."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+
+
+def test_should_flag_single_line_docstring_omitting_two_public_methods() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _narrow_class_with_widened_surface(), PRODUCTION_FILE_PATH
+    )
+    assert any("pause_then_resume" in each for each in issues), (
+        f"Expected omitted-method flag, got: {issues!r}"
+    )
+    assert any("stretch_then_resume" in each for each in issues)
+    assert len(issues) == 1
+
+
+def test_should_not_flag_when_summary_names_every_public_method() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Announce a pause then resume, or stretch then resume, with a countdown."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Summary naming every method must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_when_only_one_public_method_is_omitted() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Pause then resume the submission run with an operator countdown."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"A single omitted method must not flag, got: {issues!r}"
+
+
+def test_should_not_flag_multi_line_docstring_body() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility.\n'
+        "\n"
+        "    Also paces the regular between-theme waits through the same seam.\n"
+        '    """\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Multi-line docstrings go to the audit lane, got: {issues!r}"
+
+
+def test_should_not_flag_class_with_single_public_method() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"A one-method class must not flag, got: {issues!r}"
+
+
+def test_should_skip_private_methods_when_counting_surface() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee break with operator visibility."""\n'
+        "\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def _sleep(self, seconds: float) -> None:\n"
+        "        await self._clock.sleep(seconds)\n"
+        "\n"
+        "    def __init__(self) -> None:\n"
+        "        self._clock = None\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"Private and dunder methods are not public surface, got: {issues!r}"
+
+
+def test_should_skip_class_without_docstring() -> None:
+    source = (
+        "class ConsoleBreakReporter:\n"
+        "    async def pause_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+        "\n"
+        "    async def stretch_then_resume(self, seconds: float) -> None:\n"
+        "        await self._sleep(seconds)\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert issues == [], f"No-docstring classes are out of scope, got: {issues!r}"
+
+
+def test_should_skip_test_file() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _narrow_class_with_widened_surface(), TEST_FILE_PATH
+    )
+    assert issues == [], f"Test files exempt, got: {issues!r}"
+
+
+def test_should_skip_hook_infrastructure() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _narrow_class_with_widened_surface(), HOOK_INFRASTRUCTURE_PATH
+    )
+    assert issues == [], f"Hook infrastructure exempt, got: {issues!r}"
+
+
+def test_should_handle_syntax_error_gracefully() -> None:
+    issues = check_class_docstring_names_public_methods("class Broken(\n", PRODUCTION_FILE_PATH)
+    assert issues == [], f"Syntax error must yield no issues, got: {issues!r}"
+
+
+def _real_break_reporter_drift() -> str:
+    return (
+        "class ConsoleBreakReporter:\n"
+        '    """Run a coffee-break with operator visibility: announce, then count down."""\n'
+        "\n"
+        "    async def announce_and_pause(self, nominal_break_seconds: float) -> None:\n"
+        "        await self._announce(nominal_break_seconds)\n"
+        "\n"
+        "    async def announce_and_pause_exact(self, break_seconds: float) -> None:\n"
+        "        await self._announce(break_seconds)\n"
+    )
+
+
+def test_should_flag_real_break_reporter_widened_surface() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _real_break_reporter_drift(), PRODUCTION_FILE_PATH
+    )
+    assert any("announce_and_pause_exact" in each for each in issues), (
+        f"Expected the regular-pace method to flag, got: {issues!r}"
+    )
+    assert any("announce_and_pause" in each for each in issues)
+    assert len(issues) == 1
+
+
+def _overload_class_omitting_the_only_method() -> str:
+    return (
+        "from typing import overload\n"
+        "\n"
+        "class PayloadTransformer:\n"
+        '    """Hold a fixed payload value for later use."""\n'
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: str) -> dict[str, str]: ...\n"
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: bytes) -> dict[str, str]: ...\n"
+        "\n"
+        "    def transform(self, payload: str | bytes) -> dict[str, str]:\n"
+        "        return self._normalize(payload)\n"
+    )
+
+
+def test_should_not_flag_single_overloaded_method_below_breadth_threshold() -> None:
+    issues = check_class_docstring_names_public_methods(
+        _overload_class_omitting_the_only_method(), PRODUCTION_FILE_PATH
+    )
+    assert issues == [], f"One overloaded public method must not flag, got: {issues!r}"
+
+
+def test_should_not_repeat_an_overloaded_name_in_the_issue_message() -> None:
+    source = (
+        "from typing import overload\n"
+        "\n"
+        "class PayloadTransformer:\n"
+        '    """Hold a fixed payload value for later use."""\n'
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: str) -> dict[str, str]: ...\n"
+        "\n"
+        "    @overload\n"
+        "    def transform(self, payload: bytes) -> dict[str, str]: ...\n"
+        "\n"
+        "    def transform(self, payload: str | bytes) -> dict[str, str]:\n"
+        "        return self._normalize(payload)\n"
+        "\n"
+        "    def reset(self) -> None:\n"
+        "        self._payload = None\n"
+    )
+    issues = check_class_docstring_names_public_methods(source, PRODUCTION_FILE_PATH)
+    assert len(issues) == 1, f"Expected a single drift issue, got: {issues!r}"
+    only_issue = issues[0]
+    assert only_issue.count("transform") == 1, (
+        f"Overloaded name must appear once in the message, got: {only_issue!r}"
+    )
+    assert "reset" in only_issue
+
+
+def test_validate_content_surfaces_class_docstring_breadth_drift() -> None:
+    issues = validate_content(
+        _narrow_class_with_widened_surface(), PRODUCTION_FILE_PATH, old_content=""
+    )
+    matching_issues = [
+        each for each in issues if "pause_then_resume" in each and "public method" in each
+    ]
+    assert matching_issues, (
+        f"Expected validate_content to surface the class-breadth drift, got: {issues!r}"
+    )

package/hooks/blocking/test_code_rules_enforcer_dead_module_constant.py

@@ -56,6 +56,12 @@ def _check(source: str, file_path: str) -> list[str]:
     return code_rules_enforcer.check_dead_module_constants(source, file_path)
 
 
+def _check_edit(fragment: str, full_file_content: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_dead_module_constants(
+        fragment, file_path, full_file_content
+    )
+
+
 def _build_constants_package(
     workflow_directory: Path,
     constants_body: str,
@@ -94,6 +100,36 @@ def test_flags_constant_imported_by_no_module_in_the_tree(neutral_root: Path) ->
     ), f"Imported constants must not be flagged, got: {issues}"
 
 
+def test_flags_a_dead_constant_added_by_an_edit_to_an_existing_module(
+    neutral_root: Path,
+) -> None:
+    consumer_body = (
+        "from report_constants.render_report_constants import (\n"
+        "    MEDIUM_CODE,\n"
+        "    MEDIUM_TERMINAL,\n"
+        ")\n"
+        "\n"
+        "def panel_class(medium: str) -> str:\n"
+        "    if medium == MEDIUM_TERMINAL:\n"
+        "        return 'terminal'\n"
+        "    return 'code-panel' if medium == MEDIUM_CODE else 'text-panel'\n"
+    )
+    prior_body = 'MEDIUM_TERMINAL = "terminal"\nMEDIUM_CODE = "code"\n'
+    constants_path = _build_constants_package(
+        neutral_root / "workflow", prior_body, consumer_body
+    )
+    edit_fragment = 'MEDIUM_CODE = "code"\nMEDIUM_TEXT = "text"\n'
+    post_edit_body = prior_body + 'MEDIUM_TEXT = "text"\n'
+    issues = _check_edit(edit_fragment, post_edit_body, str(constants_path))
+    assert any("MEDIUM_TEXT" in each_issue for each_issue in issues), (
+        f"An Edit that inserts a dead constant must be flagged, got: {issues}"
+    )
+    assert not any(
+        "MEDIUM_TERMINAL" in each_issue or "MEDIUM_CODE" in each_issue
+        for each_issue in issues
+    ), f"Imported constants must not be flagged on an edit, got: {issues}"
+
+
 def test_does_not_flag_constant_imported_one_directory_up(neutral_root: Path) -> None:
     consumer_uses_text = (
         "from report_constants.render_report_constants import (\n"