claude-dev-env 1.59.0 → 1.60.0

package/hooks/blocking/verifier_verdict_minter.py

@@ -0,0 +1,299 @@
+"""SubagentStop hook: mint a commit-gate verdict when code-verifier finishes.
+
+Only this hook writes verdict files — the main session is denied writes to
+the verdict directory, so a session cannot fabricate a passing verdict. The
+SubagentStop payload names the stopping subagent by ``agent_id``. The hook
+recovers the spawning agent type from the parent transcript
+(``transcript_path``), where the agent's completion record carries its
+identity as sibling ``agentId`` and ``agentType`` keys. When that type is
+``code-verifier``, the hook pulls the verdict block out of the agent's own
+transcript — the payload key ``agent_transcript_path``; the parent
+``transcript_path`` supplies only the spawning type and never the verdict, so
+text printed by the main session can never mint — recomputes the live
+change-surface hash for the session
+repository, and writes the verdict bound to that hash. The companion
+``verified_commit_gate.py`` (PreToolUse) then allows ``git commit`` /
+``git push`` only while the work tree still matches the verified state.
+
+The verifier's final message must end with a fenced block::
+
+    ```verdict
+    {"all_pass": true, "findings": []}
+    ```
+
+A missing or unparseable block mints nothing, which leaves the gate closed.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import sys
+import time
+from pathlib import Path
+
+blocking_directory = str(Path(__file__).resolve().parent)
+if blocking_directory not in sys.path:
+    sys.path.insert(0, blocking_directory)
+
+from config.verified_commit_constants import (
+    MINTING_AGENT_TYPE,
+    SPAWN_LOOKUP_ATTEMPT_COUNT,
+    SPAWN_LOOKUP_RETRY_DELAY_SECONDS,
+)
+from verification_verdict_store import (
+    branch_surface_manifest,
+    manifest_sha256,
+    resolve_merge_base,
+    resolve_repo_root,
+    write_verdict,
+)
+
+
+def assistant_text_blocks(transcript_path: str) -> list[str]:
+    """Collect every assistant text block from a transcript JSONL file.
+
+    Args:
+        transcript_path: Path to the subagent's transcript.
+
+    Returns:
+        The text of each assistant content block, in transcript order;
+        empty when the file is missing or holds no assistant text.
+    """
+    collected_blocks: list[str] = []
+    try:
+        transcript_lines = (
+            Path(transcript_path).read_text(encoding="utf-8", errors="replace").splitlines()
+        )
+    except OSError:
+        return collected_blocks
+    for each_line in transcript_lines:
+        try:
+            transcript_entry = json.loads(each_line)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(transcript_entry, dict):
+            continue
+        if transcript_entry.get("type") != "assistant":
+            continue
+        message_body = transcript_entry.get("message")
+        if not isinstance(message_body, dict):
+            continue
+        content_blocks = message_body.get("content")
+        if not isinstance(content_blocks, list):
+            continue
+        for each_block in content_blocks:
+            if isinstance(each_block, dict) and each_block.get("type") == "text":
+                block_text = each_block.get("text")
+                if isinstance(block_text, str):
+                    collected_blocks.append(block_text)
+    return collected_blocks
+
+
+def last_verdict_in_blocks(all_text_blocks: list[str]) -> dict | None:
+    """Extract the final verdict fence from assistant text blocks.
+
+    Args:
+        all_text_blocks: Assistant text blocks in transcript order.
+
+    Returns:
+        The parsed verdict mapping carrying a boolean ``all_pass`` and a
+        list ``findings``, or None when no block holds a wellformed fence.
+    """
+    verdict_fence_pattern = re.compile(r"```verdict\s*\n(.*?)```", re.DOTALL)
+    fence_bodies: list[str] = []
+    for each_block in all_text_blocks:
+        fence_bodies.extend(verdict_fence_pattern.findall(each_block))
+    for each_fence_body in reversed(fence_bodies):
+        try:
+            verdict_record = json.loads(each_fence_body)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(verdict_record, dict):
+            continue
+        if not isinstance(verdict_record.get("all_pass"), bool):
+            continue
+        if not isinstance(verdict_record.get("findings"), list):
+            continue
+        return verdict_record
+    return None
+
+
+def _transcript_entries(transcript_path: str) -> list[dict]:
+    """Parse every JSON object line of a transcript file.
+
+    Args:
+        transcript_path: Path to the parent session transcript.
+
+    Returns:
+        Each parseable object entry in transcript order; empty when the
+        file is missing or holds no object lines.
+    """
+    parsed_entries: list[dict] = []
+    try:
+        transcript_lines = (
+            Path(transcript_path).read_text(encoding="utf-8", errors="replace").splitlines()
+        )
+    except OSError:
+        return parsed_entries
+    for each_line in transcript_lines:
+        try:
+            transcript_entry = json.loads(each_line)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(transcript_entry, dict):
+            parsed_entries.append(transcript_entry)
+    return parsed_entries
+
+
+def _agent_type_in_node(transcript_node: object, agent_id: str) -> str | None:
+    """Search one parsed transcript value for a spawn record naming an agent.
+
+    Walks a transcript value and its nested mappings and sequences for a
+    mapping whose ``agentId`` equals the stopping agent and whose
+    ``agentType`` is a string. Only a structured ``agentType`` key counts, so
+    a main-session text block that merely quotes the words cannot match.
+
+    Args:
+        transcript_node: A JSON value drawn from a parsed transcript entry.
+        agent_id: The stopping subagent's id from the payload.
+
+    Returns:
+        The ``agentType`` of the matching mapping, or None when no nested
+        value names this agent.
+    """
+    if isinstance(transcript_node, dict):
+        recorded_type = transcript_node.get("agentType")
+        if transcript_node.get("agentId") == agent_id and isinstance(recorded_type, str):
+            return recorded_type
+        for each_value in transcript_node.values():
+            nested_type = _agent_type_in_node(each_value, agent_id)
+            if nested_type is not None:
+                return nested_type
+        return None
+    if isinstance(transcript_node, list):
+        for each_item in transcript_node:
+            nested_type = _agent_type_in_node(each_item, agent_id)
+            if nested_type is not None:
+                return nested_type
+    return None
+
+
+def _agent_type_from_entries(all_entries: list[dict], agent_id: str) -> str | None:
+    """Find the spawn record naming an agent across parent-transcript entries.
+
+    Args:
+        all_entries: Parsed parent-transcript entries.
+        agent_id: The stopping subagent's id from the payload.
+
+    Returns:
+        The ``agentType`` recorded for the agent, or None when no entry's
+        spawn record names it.
+    """
+    for each_entry in all_entries:
+        recorded_type = _agent_type_in_node(each_entry, agent_id)
+        if recorded_type is not None:
+            return recorded_type
+    return None
+
+
+def _resolve_agent_type_with_retry(transcript_path: str, agent_id: str) -> str | None:
+    """Read the parent transcript and resolve the agent's type, with retry.
+
+    The agent's completion record is not reliably flushed to the parent
+    transcript at the instant SubagentStop fires, so a single read can miss it
+    and silently mint nothing. Each attempt re-reads the transcript; a bounded
+    sleep separates attempts so a late-arriving record resolves on a later read.
+
+    Args:
+        transcript_path: Path to the parent session transcript.
+        agent_id: The stopping subagent's id from the payload.
+
+    Returns:
+        The recorded ``agentType``, or None when no attempt finds the spawn
+        record naming this agent.
+    """
+    for each_attempt_index in range(SPAWN_LOOKUP_ATTEMPT_COUNT):
+        all_entries = _transcript_entries(transcript_path)
+        recorded_type = _agent_type_from_entries(all_entries, agent_id)
+        if recorded_type is not None:
+            return recorded_type
+        if each_attempt_index < SPAWN_LOOKUP_ATTEMPT_COUNT - 1:
+            time.sleep(SPAWN_LOOKUP_RETRY_DELAY_SECONDS)
+    return None
+
+
+def resolved_subagent_type(subagent_stop_payload: dict) -> str | None:
+    """Recover the spawning agent type for a SubagentStop payload.
+
+    The payload names the stopping subagent by ``agent_id``. Its spawn type
+    lives on the agent's completion record in the parent transcript, attached
+    as sibling ``agentId`` and ``agentType`` keys, so the type is read from
+    that record. The read retries because the record may not be flushed at the
+    instant the hook fires.
+
+    Args:
+        subagent_stop_payload: The SubagentStop hook payload.
+
+    Returns:
+        The agent type this subagent was spawned with, or None when the agent
+        id is absent or no spawn record names its type.
+    """
+    agent_id = subagent_stop_payload.get("agent_id", "")
+    if not agent_id:
+        return None
+    return _resolve_agent_type_with_retry(
+        subagent_stop_payload.get("transcript_path", ""), agent_id
+    )
+
+
+def mint_for_payload(subagent_stop_payload: dict) -> Path | None:
+    """Mint a verdict file for a code-verifier stop event.
+
+    Args:
+        subagent_stop_payload: The SubagentStop hook payload.
+
+    Returns:
+        The verdict file path when minted; None when the payload is not a
+        code-verifier stop, the transcript holds no verdict, or the
+        session directory is not a work tree with an upstream base.
+    """
+    if resolved_subagent_type(subagent_stop_payload) != MINTING_AGENT_TYPE:
+        return None
+    agent_transcript_path = subagent_stop_payload.get("agent_transcript_path", "")
+    if not agent_transcript_path:
+        return None
+    verdict_record = last_verdict_in_blocks(assistant_text_blocks(agent_transcript_path))
+    if verdict_record is None:
+        return None
+    repo_root = resolve_repo_root(subagent_stop_payload.get("cwd", "."))
+    if repo_root is None:
+        return None
+    merge_base_sha = resolve_merge_base(repo_root)
+    if merge_base_sha is None:
+        return None
+    surface_manifest_text = branch_surface_manifest(repo_root, merge_base_sha)
+    if surface_manifest_text is None:
+        return None
+    return write_verdict(
+        repo_root,
+        manifest_sha256(surface_manifest_text),
+        verdict_record["all_pass"],
+        verdict_record["findings"],
+        str(subagent_stop_payload.get("agent_id", "")),
+    )
+
+
+def main() -> None:
+    """Read the SubagentStop payload and mint a verdict when one applies."""
+    try:
+        subagent_stop_payload = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        return
+    if not isinstance(subagent_stop_payload, dict):
+        return
+    mint_for_payload(subagent_stop_payload)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/diagnostic/test_hook_log_extractor.py

@@ -82,7 +82,7 @@ def _make_blocking_line(
     hook_event: str = "PreToolUse",
     tool_use_id: str = "toolu_002",
     blocking_message: str = "blocked for reason",
-    command: str = "python C:/Users/jon/.claude/hooks/blocking/content_search_to_zoekt_redirector.py",
+    command: str = "python C:/Users/jon/.claude/hooks/blocking/block_main_commit.py",
     timestamp: str = "2026-04-24T13:32:54.293Z",
     cwd: str = "Y:\\Projects\\repo",
     git_branch: str = "main",
@@ -640,7 +640,7 @@ def test_run_summary_prints_table_when_rows_returned(
 ) -> None:
     fake_cursor = MagicMock()
     fake_cursor.fetchall.return_value = [
-        ("content_search_to_zoekt_redirector.py", "blocking", 7, "Bash(grep foo)"),
+        ("block_main_commit.py", "blocking", 7, "Bash(git commit)"),
     ]
     fake_connection = MagicMock()
     fake_connection.cursor.return_value.__enter__.return_value = fake_cursor
@@ -652,7 +652,7 @@ def test_run_summary_prints_table_when_rows_returned(
 
     captured = capsys.readouterr()
     assert exit_code == 0
-    assert "content_search_to_zoekt_redirector.py" in captured.out
+    assert "block_main_commit.py" in captured.out
     assert "blocking" in captured.out
     assert "7" in captured.out
 

package/hooks/hooks.json

@@ -54,6 +54,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/hook_prose_detector_consistency.py",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verified_commit_message_accuracy_blocker.py",
+            "timeout": 10
           }
         ]
       },
@@ -118,7 +123,7 @@
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/precommit_code_rules_gate.py",
-            "timeout": 30
+            "timeout": 150
           },
           {
             "type": "command",
@@ -144,6 +149,31 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/gh_pr_author_enforcer.py",
             "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verified_commit_gate.py",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verdict_directory_write_blocker.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "PowerShell",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verified_commit_gate.py",
+            "timeout": 15
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verdict_directory_write_blocker.py",
+            "timeout": 10
           }
         ]
       },
@@ -247,6 +277,18 @@
         ]
       }
     ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/verifier_verdict_minter.py",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "matcher": "",

package/hooks/hooks_constants/blocking_check_limits.py

@@ -20,6 +20,7 @@ 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
+MAX_ZERO_PAYLOAD_ALIAS_ISSUES: int = 3
 MAX_LOGGING_FSTRING_ISSUES: int = 3
 MAX_WINDOWS_API_NONE_ISSUES: int = 3
 MAX_E2E_TEST_NAMING_ISSUES: int = 3

package/hooks/hooks_constants/dead_module_constant_constants.py

@@ -0,0 +1,20 @@
+"""Constants for the dead module-level constant detector in ``code_rules_enforcer``.
+
+Lives under the hooks-tree ``hooks_constants`` package so module-level
+UPPER_SNAKE constants satisfy the CODE_RULES "constants live in config"
+requirement and share a home with the other hook-tree configuration.
+"""
+
+PYTHON_SOURCE_SUFFIX: str = ".py"
+DUNDER_INIT_FILENAME: str = "__init__.py"
+CONSTANTS_MODULE_SUFFIX: str = "_constants.py"
+CONFIG_DIRECTORY_SEGMENT: str = "config"
+DUNDER_ALL_NAME: str = "__all__"
+MINIMUM_UPPER_SNAKE_LENGTH: int = 2
+MAX_DEAD_MODULE_CONSTANT_ISSUES: int = 25
+MAX_SCAN_ROOT_FILE_COUNT: int = 2000
+DEAD_MODULE_CONSTANT_GUIDANCE: str = (
+    "module-level constant is defined here but never imported or read by any"
+    " module in the enclosing package tree - remove the constant, or reference it"
+    " where its value is needed (CODE_RULES §9.8)"
+)

package/hooks/hooks_constants/duplicate_function_body_constants.py

@@ -1,9 +1,14 @@
-"""Constants for the cross-file duplicate-function-body scan in ``code_rules_enforcer``.
+"""Constants for the duplicate-function-body scan in ``code_rules_enforcer``.
 
-The scan flags a top-level function whose body is structurally identical to a
-top-level function already defined in a sibling ``.py`` module in the same
-directory. This catches the Reuse-before-create / DRY violation where a helper
-is copy-pasted across several modules instead of imported from one shared home.
+The blocking scan flags a top-level function whose body is structurally identical
+to a top-level function already defined in a sibling ``.py`` module in the same
+directory. This catches the Reuse-before-create / DRY violation where a helper is
+copy-pasted across several modules instead of imported from one shared home.
+
+The ``CROSS_SKILL_*`` and ``SKILL*`` constants feed the non-blocking companion
+advisory: a helper copied between two skills' ``scripts`` directories, where a
+shared module would break independent install. That advisory names the source
+skill on stderr rather than denying the write.
 """
 
 MINIMUM_DUPLICATE_BODY_STATEMENTS: int = 3
@@ -15,3 +20,15 @@ DUPLICATE_BODY_GUIDANCE: str = (
     "extract a single shared helper (for example in hooks_constants/) and "
     "import it from both modules instead of copying it (Reuse before create / DRY)"
 )
+
+SKILLS_DIRECTORY_NAME: str = "skills"
+SKILL_SCRIPTS_DIRECTORY_NAME: str = "scripts"
+MAX_CROSS_SKILL_ADVISORY_ISSUES: int = 25
+CROSS_SKILL_ADVISORY_PREFIX: str = "[CODE_RULES advisory]"
+CROSS_SKILL_DUPLICATE_GUIDANCE: str = (
+    "two skill folders install on their own, so this copy is a defensible "
+    "skill-isolation tradeoff; a shared module would couple the skills and "
+    "break independent install. Confirm the copy is intentional, or for a "
+    "large or behavior-bearing body raise the choice through AskUserQuestion "
+    "(see the no-cross-skill-duplicate-helpers rule)"
+)

package/hooks/hooks_constants/precommit_code_rules_gate_constants.py

@@ -8,7 +8,7 @@ from pathlib import Path
 
 GIT_DASH_C_COMMIT_PATTERN: str = r"git\s+-C\s+[\"']?[^\"';&|]+?[\"']?\s+commit\b"
 GIT_COMMAND_TIMEOUT_SECONDS: int = 5
-GATE_TIMEOUT_SECONDS: int = 25
+GATE_TIMEOUT_SECONDS: int = 120
 GATE_RELATIVE_PATH: Path = Path("_shared") / "pr-loop" / "scripts" / "code_rules_gate.py"
 ALL_STAGED_PYTHON_FILES_COMMAND: tuple[str, ...] = (
     "git",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.59.0",
+    "version": "1.60.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/file-global-constants.md

@@ -20,7 +20,13 @@ Test-file detection uses the following anchored patterns against the full relati
 
 ## `config/` files are exempt
 
-Constants placed in `config/` satisfy the constants-location rule; the use-count requirement applies only to production code outside `config/`.
+Constants placed in `config/` satisfy the constants-location rule; the use-count rule applies only to production code outside `config/`.
+
+## Dead constant in a dedicated constants module (cross-module)
+
+The use-count rule above governs a file-global constant in production code outside `config/` by counting same-file references. A dedicated constants module — a file whose name ends in `_constants.py`, or any module under a `config/` directory — exports its constants to importer modules elsewhere, so a same-file count proves nothing. A separate hook, `check_dead_module_constants` (dispatched from `code_rules_enforcer`), governs these modules: it flags an `UPPER_SNAKE` constant defined in the written module whose name appears in no `.py` module anywhere under the enclosing package tree — not imported, not read, not listed in an `__all__` literal, not named in a string annotation. That is the dead exported constant CODE_RULES §9.8 targets, caught at Write/Edit time.
+
+The scan resolves the enclosing package tree from the written file: for a constants module inside a package subdirectory, the tree is the package's parent (so an importer one directory up is in scope); for a `config/` module, the tree is the parent of the `config` directory. A module that declares its own `__all__` is skipped — the author's explicit export surface is taken as the liveness contract. A reference from a test module under the tree keeps a constant live. Test modules and migration modules are themselves exempt from the check.
 
 ## Examples
 

package/rules/no-cross-skill-duplicate-helpers.md

@@ -0,0 +1,29 @@
+---
+paths: "**/skills/*/scripts/**/*.py"
+---
+
+# Cross-Skill Duplicate Helpers
+
+**When this applies:** Any Write or Edit to a `.py` file under a skill's `scripts/` directory (`**/skills/<skill-name>/scripts/**/*.py`) that copies a top-level helper from another skill's `scripts/` directory.
+
+## The two duplication cases differ
+
+CODE_RULES "Reuse before create" / DRY says one helper lives in one home and both call sites import it. That rule is blocking **within one skill** — two `.py` modules in the same skill's `scripts/` directory that carry the same top-level function body fail the `code_rules_duplicate_body` gate, and the fix is a shared module both import.
+
+Across **two skill folders** the same copy is a different call. Each skill folder installs on its own, so a shared module would couple two skills the install model keeps separate: deleting or reinstalling one skill would break a helper the other depends on. A small launch helper copied into each skill (for example a Chrome-open helper that reads the registry and runs `chrome.exe`) is a defensible skill-isolation tradeoff, not a regression.
+
+## Decision
+
+Before you copy a top-level helper from one skill's `scripts/` directory into another:
+
+- **Same skill, two modules** — extract one shared module in that skill and import it from both. The `code_rules_duplicate_body` gate blocks the copy.
+- **Two skill folders, a small self-contained helper** — copy it; the skill-isolation tradeoff stands. A non-blocking `[CODE_RULES advisory]` names the source skill at Write time so the copy is a deliberate choice on record, not an oversight.
+- **Two skill folders, a large or behavior-bearing body** — when the copied body is large, holds business logic, or would drift in a way that changes behavior, raise the choice through `AskUserQuestion`: copy and accept drift, or stand up a shared dependency both skills declare (for example a published package both `requirements` files name, or a `_shared` module the install step writes into each skill). A shared dependency that survives independent install is the only shared-home path that does not break the install model.
+
+## What the advisory tells you
+
+The `advise_cross_skill_duplicate_helper` check in `code_rules_duplicate_body` prints to stderr (never blocks) when a top-level function in the file being written has the same normalized body as a top-level function in another skill's `scripts/` directory. The message names the source skill and function so a reviewer can confirm the copy was intentional. It fires only across skill folders; within one skill the blocking gate already covers the copy.
+
+## Why this is a rule, not a wider gate
+
+Extending the blocking duplicate-body gate to span skill folders would deny the exact skill-isolation copy that keeps skills independently installable — a false positive on a sanctioned pattern. The boundary between "same skill, block" and "two skills, signal" is a judgment the writer makes with the source skill named in front of them. The rule states the judgment; the `[CODE_RULES advisory]` surfaces the signal; neither blocks the defensible copy.