claude-dev-env 1.73.0 → 1.74.0

package/CLAUDE.md

@@ -35,6 +35,8 @@ When I ask you to "show me", "open", "display", "let me see", or "pull up" a fil
 
 It sizes each image window to the image (scaled down to fit the screen) and opens non-image files in their default app; pass every path I name. Printing a path or attaching the file is not showing it — do that only when the file truly cannot be opened, and say why.
 
+The `send_user_file_open_locally_blocker` hook backs this up: it blocks a desk-side `SendUserFile` attach and sends you back to this command, while a phone push (`status: "proactive"`) stays allowed.
+
 ## Test Philosophy
 
 When writing tests, always write tests that actually test the behavior of the function against actual, real data and environments.

package/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md

@@ -25,7 +25,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O3 | Predicate-name and -docstring vs body breadth | A boolean helper's name and docstring promise a narrow predicate. Walk the body's branches: every branch's `return True` path is consistent with the promised name. Bodies that accept inputs broader than the name (`_dir_value_resolves_to_shared_temp` also accepting HOME/TMP env-derived paths) are O3 findings. |
 | O4 | Step-ordering narrative | A docstring describes processing as `A then B then C`. Walk the body and confirm the call order matches. Mismatched order is an O4 finding regardless of whether the final output is the same. A docstring step enumeration that names the body's linear steps but omits a corrective workflow step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`) is also an O4 finding: the reader trusts the step list to be complete and misses the conditional path. The branch-guarded-dispatch shape of this drift — a docstring that names two or more linear-step callees while the body guards a two-or-more-token dispatch callee inside a branch whose name the prose never spells out — is gated deterministically at Write/Edit time by `check_docstring_step_enumeration_dispatch_coverage` (`packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`), so the audit lane focuses on the step-ordering shapes the gate cannot match (re-ordered steps, plain unguarded steps the prose omits). |
 | O5 | Named-sentinel / filename references | A docstring names a sentinel marker, environment variable, filename, or magic string. Confirm the named token actually exists in the module body or in the repo's naming convention. |
-| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. When a docstring sentence excludes a named category of input from what the function flags (`X are not dispatch steps`, `Y is not a match`), confirm the axis the prose excludes on is the axis the body's branch condition actually keys on. A body that flags a call when it sits inside an `If.test` guard, paired with prose that excludes by the call's receiver shape (`method-on-local calls inside a branch are not dispatch steps`), is an O6 finding: a guarded method-on-local call is flagged even though the prose lists it as excluded — the exclusion is keyed to the wrong axis. The single-condition shared-fallback shape of this drift — a summary that scopes a fallback call to one condition while the body routes to that same call from two or more early-return guards — is gated deterministically at Write/Edit time by `check_docstring_fallback_branch_coverage`, so the audit lane focuses on the O6 shapes the gate cannot match. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
+| O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. When a docstring sentence excludes a named category of input from what the function flags (`X are not dispatch steps`, `Y is not a match`), confirm the axis the prose excludes on is the axis the body's branch condition actually keys on. A body that flags a call when it sits inside an `If.test` guard, paired with prose that excludes by the call's receiver shape (`method-on-local calls inside a branch are not dispatch steps`), is an O6 finding: a guarded method-on-local call is flagged even though the prose lists it as excluded — the exclusion is keyed to the wrong axis. The single-condition shared-fallback shape of this drift — a summary that scopes a fallback call to one condition while the body routes to that same call from two or more early-return guards — is gated deterministically at Write/Edit time by `check_docstring_fallback_branch_coverage`, so the audit lane focuses on the O6 shapes the gate cannot match. The exception-guard shape of this drift — a docstring that promises a malformed payload `resolves to None` while a payload subscript (`payload["key"]`, `float(payload["key"])`) sits outside the try/except whose handler returns None, so a present-but-malformed payload raises rather than resolving to None — is gated deterministically at Write/Edit time by `check_docstring_unguarded_malformed_payload_claim`, so the audit lane focuses on the wider Raises/None-on-failure claims the gate cannot match. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
 | O7 | Module-doc-vs-split-module after refactor | When a refactor moves a responsibility to a sibling module, the originating module's docstring and the receiving module's docstring both describe the home of that responsibility. A module docstring should describe only the responsibilities it owns. |
 | O8 | Companion-doc ordering/content vs producer | When a PR changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the PR diff never touched the `.md` file, because the behavior change orphaned the doc claim. See `../../rules/docstring-prose-matches-implementation.md`. |
 

package/hooks/blocking/CLAUDE.md

@@ -62,6 +62,7 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `code_verifier_spawn_preflight_gate.py` | PreToolUse (Agent) | Spawning the `code-verifier` subagent when the branch has a merge conflict vs its base or a CODE_RULES violation on a working-tree-added line |
 | `convergence_gate_blocker.py` | PreToolUse (Bash) | Convergence workflow actions on a conflicting PR |
 | `destructive_command_blocker.py` | PreToolUse (Bash/PowerShell) | Shell commands with destructive literals (`rm -rf`, `git reset --hard`, etc.) |
+| `docstring_rule_gate_count_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | A stale spelled-out gate-validator count in `docstring-prose-matches-implementation.md` — the "N more gate validators" / "M gated slices" count drifting from the `check_docstring_*` validators the prose names |
 | `es_exe_path_rewriter.py` | PreToolUse | Rewrites paths referencing `.exe` under the Everything search path |
 | `gh_body_arg_blocker.py` | PreToolUse (Bash) | `gh` commands passing `--body`/`-b` directly (requires `--body-file` instead) |
 | `gh_pr_author_enforcer.py` | PreToolUse | Enforces PR author identity rules |
@@ -71,12 +72,14 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work |
 | `md_to_html_blocker.py` | PreToolUse (Write/Edit) | Writing `.md` files when an `.html` companion is required |
 | `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
+| `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory names two or more sibling files but no entry for the new file |
 | `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
 | `pr_converge_bugteam_enforcer.py` | PreToolUse | Enforces that bugteam runs in parallel with bugbot in pr-converge loops |
 | `pr_description_enforcer.py` | PreToolUse (Bash) | `gh pr create`/`edit` without a PR-description-writer-authored body |
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
 | `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
 | `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |
+| `send_user_file_open_locally_blocker.py` | PreToolUse (SendUserFile) | A desk-side file attach (`SendUserFile` with `status` not `proactive`); points to opening the file locally via `Show-Asset.ps1` |
 | `sensitive_file_protector.py` | PreToolUse (Write/Edit) | Writes to sensitive credential or config files |
 | `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |
 | `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation |

package/hooks/blocking/block_main_commit.py

@@ -15,6 +15,13 @@ import os
 import re
 import subprocess
 import sys
+from pathlib import Path
+
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 
 GIT_COMMAND_TIMEOUT_SECONDS = 5
 PROTECTED_BRANCHES = ("main", "master")
@@ -172,6 +179,13 @@ def main() -> None:
         sys.exit(0)
 
     denial = build_denial_response(current_branch, target_dir)
+    log_hook_block(
+        calling_hook_name="block_main_commit.py",
+        hook_event="PreToolUse",
+        block_reason=denial["hookSpecificOutput"]["permissionDecisionReason"],
+        tool_name="Bash",
+        offending_input_preview=bash_command,
+    )
     print(json.dumps(denial))
     sys.exit(0)
 

package/hooks/blocking/bot_mention_comment_blocker.py

@@ -21,6 +21,7 @@ from hooks_constants.bot_mention_comment_blocker_constants import (  # noqa: E40
     CURSOR_MENTION_TOKEN,
     TOOL_NAME,
 )
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 
 
 def _body_contains_token(body: str, token: str) -> bool:
@@ -60,6 +61,12 @@ def main() -> None:
             "permissionDecisionReason": corrective_message,
         }
     }
+    log_hook_block(
+        calling_hook_name="bot_mention_comment_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=corrective_message,
+        tool_name=TOOL_NAME,
+    )
     print(json.dumps(deny_payload))
     sys.stdout.flush()
     sys.exit(0)

package/hooks/blocking/claude_md_orphan_file_blocker.py

@@ -39,6 +39,11 @@ from hooks_constants.claude_md_orphan_file_blocker_constants import (  # noqa: E
     SEPARATOR_CELL_PATTERN,
     TABLE_ROW_PATTERN,
 )
+from hooks_constants.multi_edit_reconstruction import (  # noqa: E402
+    apply_edits,
+    edits_for_tool,
+)
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
     read_hook_input_dictionary_from_stdin,
 )
@@ -409,29 +414,6 @@ def _read_existing_file_content(file_path: str) -> str | None:
         return None
 
 
-def _apply_edits(existing_content: str, all_edits: list[dict]) -> str:
-    """Return *existing_content* with each MultiEdit replacement applied in order.
-
-    Args:
-        existing_content: The current on-disk file content.
-        all_edits: The MultiEdit ``edits`` list, each a mapping with an
-            ``old_string`` and a ``new_string``.
-
-    Returns:
-        The content after replacing the first occurrence of each edit's
-        ``old_string`` with its ``new_string``, in list order.
-    """
-    edited_content = existing_content
-    for each_edit in all_edits:
-        if not isinstance(each_edit, dict):
-            continue
-        old_string = each_edit.get("old_string", "")
-        new_string = each_edit.get("new_string", "")
-        if isinstance(old_string, str) and isinstance(new_string, str) and old_string:
-            edited_content = edited_content.replace(old_string, new_string, 1)
-    return edited_content
-
-
 def _edit_fragments(all_edits: list[dict]) -> list[str]:
     """Return each MultiEdit ``new_string`` fragment present as a non-empty string.
 
@@ -498,29 +480,12 @@ def _build_orphan_scan_plan(
         content = tool_input.get("content", "")
         candidate_contents = [content] if isinstance(content, str) and content else []
         return _OrphanScanPlan(candidate_contents, set())
-    all_edits = _edits_for_tool(tool_name, tool_input)
+    all_edits = edits_for_tool(tool_name, tool_input)
     existing_content = _read_existing_file_content(file_path)
     if existing_content is None:
         return _OrphanScanPlan(_edit_fragments(all_edits), set())
     baseline_missing = set(find_missing_filenames(existing_content, claude_md_directory))
-    return _OrphanScanPlan([_apply_edits(existing_content, all_edits)], baseline_missing)
-
-
-def _edits_for_tool(tool_name: str, tool_input: dict) -> list[dict]:
-    """Return the edit mappings an Edit or MultiEdit payload carries.
-
-    Args:
-        tool_name: The intercepted tool — ``Edit`` or ``MultiEdit``.
-        tool_input: The tool's input payload.
-
-    Returns:
-        A single-element list holding the Edit payload, or the MultiEdit
-        ``edits`` list when it is present as a list; an empty list otherwise.
-    """
-    if tool_name == "Edit":
-        return [tool_input]
-    all_edits = tool_input.get("edits", [])
-    return all_edits if isinstance(all_edits, list) else []
+    return _OrphanScanPlan([apply_edits(existing_content, all_edits)], baseline_missing)
 
 
 def _collect_missing_filenames(scan_plan: _OrphanScanPlan, claude_md_directory: Path) -> list[str]:
@@ -623,6 +588,13 @@ def main() -> None:
         sys.exit(0)
 
     block_payload = _build_block_payload(missing_filenames, str(claude_md_directory))
+    log_hook_block(
+        calling_hook_name="claude_md_orphan_file_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=block_payload["hookSpecificOutput"]["permissionDecisionReason"],
+        tool_name=tool_name,
+        offending_input_preview=file_path,
+    )
     _emit_hook_result(block_payload, sys.stdout)
     sys.exit(0)
 

package/hooks/blocking/code_rules_docstrings.py

@@ -25,6 +25,7 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     ALL_DOCSTRING_EXCLUSIVE_SCOPE_PHRASES,
     ALL_DOCSTRING_EXEMPT_DECORATOR_NAMES,
     ALL_DOCSTRING_FILE_REFERENCE_SUFFIXES,
+    ALL_DOCSTRING_GUARDED_FAILURE_CLAIM_PHRASES,
     ALL_DOCSTRING_IMPLICIT_INSTANCE_PARAMETER_NAMES,
     ALL_DOCSTRING_MULTIPLE_CONDITION_JOINING_PHRASES,
     ALL_DOCSTRING_NO_CONSUMER_CLAIM_PHRASES,
@@ -42,14 +43,17 @@ from hooks_constants.blocking_check_limits import (  # noqa: E402
     MAX_DOCSTRING_INLINE_LITERAL_CLAIM_ISSUES,
     MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES,
     MAX_DOCSTRING_STEP_DISPATCH_ISSUES,
+    MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES,
     MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES,
     MAX_DOCSTRING_UNDEFINED_CONSTANT_ISSUES,
+    MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES,
     MAX_MODULE_DOCSTRING_CHECK_ROSTER_ISSUES,
     MINIMUM_NAMED_LINEAR_STEPS_FOR_DISPATCH_CHECK,
     MINIMUM_PUBLIC_CHECKS_FOR_MODULE_DOCSTRING_ROSTER,
     MINIMUM_PUBLIC_METHODS_FOR_CLASS_DOCSTRING_BREADTH,
     MINIMUM_TOKENS_FOR_DISPATCH_CALLEE,
     MINIMUM_TUPLE_MEMBERS_FOR_DOCSTRING_ENUMERATION,
+    SINGLE_DICT_KEY_COUNT_FOR_PLURAL_CARDINALITY_DRIFT,
 )
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_CAPS_WITH_UNDERSCORE_PATTERN,
@@ -57,6 +61,7 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_DOCSTRING_TERMINATING_SECTION_HEADERS,
     ALL_SELF_AND_CLS_PARAMETER_NAMES,
     DOCSTRING_ARG_ENTRY_PATTERN,
+    DOCSTRING_PLURAL_FAMILY_STOP_PATTERN,
     IDENTIFIER_SHAPED_TUPLE_MEMBER_PATTERN,
     INLINE_CODE_TOKEN_PATTERN,
 )
@@ -641,6 +646,123 @@ def check_docstring_no_consumer_claim(content: str, file_path: str) -> list[str]
     return issues[:MAX_DOCSTRING_NO_CONSUMER_CLAIM_ISSUES]
 
 
+def _docstring_claims_malformed_payload_is_guarded(docstring_text: str) -> str:
+    collapsed_docstring = " ".join(docstring_text.lower().split())
+    for each_phrase in ALL_DOCSTRING_GUARDED_FAILURE_CLAIM_PHRASES:
+        if each_phrase in collapsed_docstring:
+            return each_phrase
+    return ""
+
+
+def _try_handler_returns_none(try_node: ast.Try) -> bool:
+    for each_handler in try_node.handlers:
+        for each_statement in each_handler.body:
+            if isinstance(each_statement, ast.Return) and isinstance(
+                each_statement.value, ast.Constant
+            ):
+                if each_statement.value.value is None:
+                    return True
+    return False
+
+
+def _names_bound_in_try_body(try_node: ast.Try) -> set[str]:
+    all_bound_names: set[str] = set()
+    for each_statement in try_node.body:
+        for each_descendant in ast.walk(each_statement):
+            if isinstance(each_descendant, ast.Name) and isinstance(
+                each_descendant.ctx, ast.Store
+            ):
+                all_bound_names.add(each_descendant.id)
+    return all_bound_names
+
+
+def _statement_subscripts_one_of(
+    statement: ast.stmt, all_payload_names: set[str]
+) -> bool:
+    for each_descendant in ast.walk(statement):
+        if (
+            isinstance(each_descendant, ast.Subscript)
+            and isinstance(each_descendant.value, ast.Name)
+            and each_descendant.value.id in all_payload_names
+        ):
+            return True
+    return False
+
+
+def _function_has_unguarded_payload_dereference(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    all_payload_names: set[str] = set()
+    saw_returning_guard = False
+    for each_statement in function_node.body:
+        if isinstance(each_statement, ast.Try) and _try_handler_returns_none(
+            each_statement
+        ):
+            all_payload_names |= _names_bound_in_try_body(each_statement)
+            saw_returning_guard = True
+            continue
+        if not saw_returning_guard:
+            continue
+        if _statement_subscripts_one_of(each_statement, all_payload_names):
+            return True
+    return False
+
+
+def check_docstring_unguarded_malformed_payload_claim(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag a docstring that promises malformed-payload safety the guard misses.
+
+    The drift this catches: a function whose docstring states that a malformed
+    payload "resolves to None" while a subscript dereference of that payload
+    (``payload["key"]``, ``float(payload["key"])``) sits OUTSIDE the try/except
+    whose handler returns None. A present-but-malformed payload then raises
+    KeyError or TypeError from that unguarded access and propagates rather than
+    resolving to None, so the docstring overstates the protection. This is the
+    deterministic slice of Category O6 (docstring prose vs implementation drift)
+    for an exception-guard claim: move the dereference inside the guarded block,
+    or narrow the docstring to the failures the guard actually catches.
+
+    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 malformed-payload claim outruns its guard,
+        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
+        matched_phrase = _docstring_claims_malformed_payload_is_guarded(docstring_text)
+        if not matched_phrase:
+            continue
+        if not _function_has_unguarded_payload_dereference(each_node):
+            continue
+        issues.append(
+            f"Line {each_node.lineno}: {each_node.name}() docstring claims "
+            f"'{matched_phrase}' but a payload subscript sits outside the try/except that "
+            "returns None — a malformed-but-present payload raises rather than resolving to "
+            "None; move the dereference inside the guard or narrow the docstring "
+            "(Category O6 docstring-vs-implementation drift)"
+        )
+        if len(issues) >= MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES:
+            break
+    return issues[:MAX_DOCSTRING_UNGUARDED_PAYLOAD_CLAIM_ISSUES]
+
+
 def _module_docstring_claims_no_inline_literal(module_docstring: str) -> str:
     collapsed_docstring = " ".join(module_docstring.lower().split())
     for each_phrase in ALL_DOCSTRING_NO_INLINE_LITERAL_CLAIM_PHRASES:
@@ -888,6 +1010,107 @@ def check_docstring_tuple_enumeration_match(content: str, file_path: str) -> lis
     return issues[:MAX_DOCSTRING_TUPLE_ENUMERATION_ISSUES]
 
 
+def _returns_section_text(docstring_text: str) -> str:
+    docstring_lines = docstring_text.splitlines()
+    returns_section_lines: list[str] = []
+    inside_returns_section = False
+    for each_line in docstring_lines:
+        stripped_line = each_line.strip()
+        if stripped_line in ("Returns:", "Yields:"):
+            inside_returns_section = True
+            continue
+        if not inside_returns_section:
+            continue
+        if _is_docstring_terminating_section_header(stripped_line):
+            break
+        returns_section_lines.append(stripped_line)
+    return " ".join(returns_section_lines)
+
+
+def _plural_families_in_returns_section(returns_section_text: str) -> set[str]:
+    return {
+        each_match.group(1)
+        for each_match in DOCSTRING_PLURAL_FAMILY_STOP_PATTERN.finditer(returns_section_text)
+    }
+
+
+def _returned_dict_key_names(
+    function_node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> set[str]:
+    all_key_names: set[str] = set()
+    for each_node in ast.walk(function_node):
+        if not isinstance(each_node, ast.Return):
+            continue
+        if not isinstance(each_node.value, ast.Dict):
+            continue
+        for each_key in each_node.value.keys:
+            if isinstance(each_key, ast.Constant) and isinstance(each_key.value, str):
+                all_key_names.add(each_key.value)
+    return all_key_names
+
+
+def _family_prefixed_key_count(family: str, all_key_names: set[str]) -> int:
+    family_prefix = f"{family}_"
+    return sum(1 for each_key in all_key_names if each_key.startswith(family_prefix))
+
+
+def check_docstring_returns_plural_cardinality(content: str, file_path: str) -> list[str]:
+    """Flag a Returns clause plural noun that names one dict key in its family.
+
+    The drift this catches: a function returns a dict literal whose keys carry
+    prefix families (``sheen_mid``, ``body_highlight``), and its Returns clause
+    names one family with a plural noun (``the sheen stops``) while exactly one
+    key in that family exists. The plural prose claims two or more entries the
+    dict no longer holds — the shape that appears when a producer removes the
+    second key in a family but leaves the plural prose untouched. The check binds
+    only when the plural family prefixes exactly one returned dict key, so a
+    singular noun, a family with two or more keys, and a family absent from the
+    dict are all left alone. This is the deterministic single-key slice of
+    Category O6 docstring-prose-vs-implementation drift.
+
+    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 Returns clause names a plural family that
+        prefixes a single returned dict key, 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
+        docstring_text = _function_docstring_text(each_node)
+        if not docstring_text:
+            continue
+        returns_section_text = _returns_section_text(docstring_text)
+        if not returns_section_text:
+            continue
+        plural_families = _plural_families_in_returns_section(returns_section_text)
+        if not plural_families:
+            continue
+        all_key_names = _returned_dict_key_names(each_node)
+        for each_family in sorted(plural_families):
+            matching_key_count = _family_prefixed_key_count(each_family, all_key_names)
+            if matching_key_count != SINGLE_DICT_KEY_COUNT_FOR_PLURAL_CARDINALITY_DRIFT:
+                continue
+            issues.append(
+                f"Line {each_node.lineno}: {each_node.name}() Returns clause says "
+                f"'the {each_family} stops' (plural) but the returned dict holds a "
+                f"single {each_family}_ key — match the noun to the cardinality "
+                "(Category O6 docstring-vs-implementation drift)"
+            )
+            if len(issues) >= MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES:
+                return issues[:MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES]
+    return issues[:MAX_DOCSTRING_RETURNS_PLURAL_CARDINALITY_ISSUES]
+
+
 def _called_callee_name(statement: ast.stmt) -> str:
     candidate_expression: ast.expr | None = None
     if isinstance(statement, ast.Expr):

package/hooks/blocking/code_rules_enforcer.py

@@ -72,8 +72,10 @@ from code_rules_docstrings import (  # noqa: E402
     check_docstring_names_undefined_constant,
     check_docstring_no_consumer_claim,
     check_docstring_no_inline_literal_claim,
+    check_docstring_returns_plural_cardinality,
     check_docstring_step_enumeration_dispatch_coverage,
     check_docstring_tuple_enumeration_match,
+    check_docstring_unguarded_malformed_payload_claim,
     check_module_docstring_names_public_checks,
 )
 from code_rules_duplicate_body import (  # noqa: E402
@@ -159,6 +161,7 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     PRECHECK_USAGE_EXIT_CODE,
     PRECHECK_USAGE_MESSAGE,
 )
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.setup_project_paths_constants import (  # noqa: E402
     UTF8_BYTE_ORDER_MARK,
 )
@@ -260,6 +263,11 @@ def validate_content(
         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_docstring_no_consumer_claim(effective_content, file_path))
+        all_issues.extend(
+            check_docstring_unguarded_malformed_payload_claim(
+                effective_content, file_path
+            )
+        )
         all_issues.extend(
             check_docstring_no_inline_literal_claim(effective_content, file_path)
         )
@@ -277,6 +285,9 @@ def validate_content(
                 effective_content, file_path
             )
         )
+        all_issues.extend(
+            check_docstring_returns_plural_cardinality(effective_content, file_path)
+        )
         all_issues.extend(
             check_docstring_names_undefined_constant(effective_content, file_path)
         )
@@ -783,6 +794,11 @@ def _write_deny_payload(deny_reason: str, deny_stream: TextIO) -> None:
             "permissionDecisionReason": deny_reason,
         }
     }
+    log_hook_block(
+        calling_hook_name="code_rules_enforcer.py",
+        hook_event="PreToolUse",
+        block_reason=deny_reason,
+    )
     deny_stream.write(json.dumps(deny_payload) + "\n")
     deny_stream.flush()
 

package/hooks/blocking/code_verifier_spawn_preflight_gate.py

@@ -25,14 +25,14 @@ import sys
 from pathlib import Path
 from typing import TextIO
 
-_hooks_dir = str(Path(__file__).resolve().parent.parent)
-if _hooks_dir not in sys.path:
-    sys.path.insert(0, _hooks_dir)
-
 _blocking_dir = str(Path(__file__).resolve().parent)
 if _blocking_dir not in sys.path:
     sys.path.insert(0, _blocking_dir)
 
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.append(_hooks_dir)
+
 from verification_verdict_store import (  # noqa: E402
     candidate_base_references,
     resolve_merge_base,
@@ -54,6 +54,7 @@ from hooks_constants.code_verifier_spawn_preflight_gate_constants import (  # no
     MERGE_TREE_CONFLICT_EXIT_CODE,
     MERGE_TREE_TIMEOUT_SECONDS,
 )
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.pr_converge_bugteam_enforcer_constants import (  # noqa: E402
     AGENT_TOOL_NAME,
 )
@@ -370,6 +371,11 @@ def _emit_deny_payload(output_stream: TextIO, reason: str) -> None:
             "permissionDecisionReason": reason,
         }
     }
+    log_hook_block(
+        calling_hook_name="code_verifier_spawn_preflight_gate.py",
+        hook_event="PreToolUse",
+        block_reason=reason,
+    )
     output_stream.write(json.dumps(deny_payload) + "\n")
     output_stream.flush()
 

package/hooks/blocking/convergence_gate_blocker.py

@@ -14,6 +14,13 @@ import subprocess
 import sys
 from pathlib import Path
 
+_hooks_dir = str(Path(__file__).resolve().parent.parent)
+if _hooks_dir not in sys.path:
+    sys.path.insert(0, _hooks_dir)
+
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
+
+
 def _resolve_pr_number(command: str, cwd: str | None) -> int | None:
     direct_match = re.search(r"\bgh\s+pr\s+ready\s+(\d+)", command)
     if direct_match:
@@ -112,15 +119,22 @@ def main() -> None:
     if completed_process.returncode in (0, 2):
         sys.exit(0)
 
+    block_reason = (
+        "Convergence check failed — PR is not ready to mark ready:\n\n" + completed_process.stdout
+    )
     deny_payload = {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",
             "permissionDecision": "deny",
-            "permissionDecisionReason": (
-                "Convergence check failed — PR is not ready to mark ready:\n\n" + completed_process.stdout
-            ),
+            "permissionDecisionReason": block_reason,
         }
     }
+    log_hook_block(
+        calling_hook_name="convergence_gate_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=block_reason,
+        tool_name="Bash",
+    )
     print(json.dumps(deny_payload))
     sys.stdout.flush()
     sys.exit(0)

package/hooks/blocking/destructive_command_blocker.py

@@ -19,6 +19,7 @@ from hooks_constants.convergence_branch_constants import (  # noqa: E402
     CONVERGENCE_BRANCH_SUFFIX_PATTERN,
     CONVERGENCE_FORCE_PUSH_DETECTION_PATTERN,
 )
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.destructive_command_segment_constants import (  # noqa: E402
     ALL_BENIGN_COMPOUND_SEGMENT_COMMANDS,
     ALL_COMMAND_LAUNCHER_WRAPPER_COMMANDS,
@@ -197,6 +198,12 @@ def _build_silent_gh_deny_response(matched_description: str) -> dict:
         "Bash call prevents duplicate execution."
     )
     _append_destructive_gate_log_entry(brief_label, full_reason)
+    log_hook_block(
+        calling_hook_name="destructive_command_blocker.py",
+        hook_event="PreToolUse",
+        block_reason=full_reason,
+        tool_name="Bash",
+    )
     return {
         "hookSpecificOutput": {
             "hookEventName": "PreToolUse",