claude-dev-env 1.60.0 → 1.61.0

package/hooks/blocking/verifier_verdict_minter.py

@@ -2,18 +2,18 @@
 
 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
+SubagentStop payload names the stopping subagent's own transcript
+(``agent_transcript_path``), which sits beside a harness-written
+``agent-<id>.meta.json`` sidecar naming the spawning ``agentType``. The hook
+reads that type from the sidecar, so it resolves identically in interactive,
+background, and worktree-switched sessions. 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.
+transcript (``agent_transcript_path``); the main session writes neither that
+transcript nor the sidecar, so text it prints 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::
 
@@ -29,18 +29,13 @@ 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 config.verified_commit_constants import MINTING_AGENT_TYPE
 from verification_verdict_store import (
     branch_surface_manifest,
     manifest_sha256,
@@ -119,131 +114,58 @@ def last_verdict_in_blocks(all_text_blocks: list[str]) -> dict | None:
     return None
 
 
-def _transcript_entries(transcript_path: str) -> list[dict]:
-    """Parse every JSON object line of a transcript file.
+def _agent_type_from_meta_sidecar(agent_transcript_path: str) -> str | None:
+    """Read the spawning agentType from a subagent transcript's sidecar.
 
-    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.
+    Each subagent transcript ``agent-<id>.jsonl`` sits beside a harness-written
+    ``agent-<id>.meta.json`` naming the spawning ``agentType``. Reading the type
+    from this sidecar binds it to the stopping subagent itself, so it resolves
+    identically in interactive, background, and worktree-switched sessions and
+    needs no parent-transcript scan or flush retry.
 
     Args:
-        transcript_node: A JSON value drawn from a parsed transcript entry.
-        agent_id: The stopping subagent's id from the payload.
+        agent_transcript_path: The stopping subagent's own transcript path from
+            the SubagentStop payload.
 
     Returns:
-        The ``agentType`` of the matching mapping, or None when no nested
-        value names this agent.
+        The recorded ``agentType``, or None when the path is empty, the sidecar
+        is absent or cannot be read or parsed, it does not hold a JSON object,
+        or it names no string ``agentType``.
     """
-    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
+    if not agent_transcript_path:
         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
+    transcript_file = Path(agent_transcript_path)
+    sidecar_file = transcript_file.with_name(f"{transcript_file.stem}.meta.json")
+    try:
+        sidecar_record = json.loads(sidecar_file.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(sidecar_record, dict):
+        return None
+    recorded_type = sidecar_record.get("agentType")
+    return recorded_type if isinstance(recorded_type, str) else 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.
+    The stopping subagent's own transcript (``agent_transcript_path``) sits
+    beside a harness-written ``agent-<id>.meta.json`` sidecar naming its
+    ``agentType``. Reading the type from that sidecar binds it to the subagent
+    itself, so it resolves the same across interactive, background, and
+    worktree-switched sessions.
 
     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.
+        The agent type this subagent was spawned with, or None when the
+        ``agent_transcript_path`` is empty, the sidecar is absent or cannot be
+        read or parsed, it does not hold a JSON object, or it names no string
+        ``agentType``.
     """
-    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
+    return _agent_type_from_meta_sidecar(
+        subagent_stop_payload.get("agent_transcript_path", "")
     )
 
 

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -124,6 +124,12 @@ KNOWN_PYTEST_FIXTURE_ANNOTATION_MESSAGE_SUFFIX: str = (
     "(CODE_RULES §6; pytest builtin fixture reference "
     "https://docs.pytest.org/en/stable/reference/fixtures.html)"
 )
+UNUSED_PYTEST_FIXTURE_PARAMETER_MESSAGE_SUFFIX: str = (
+    "known pytest fixture parameter is declared but never referenced in the "
+    "function body; pytest still materializes its setup, so drop the unused "
+    "parameter (pytest builtin fixture reference "
+    "https://docs.pytest.org/en/stable/reference/fixtures.html)"
+)
 ALL_LOOP_INDEX_LETTER_EXEMPTIONS: frozenset[str] = frozenset({"i", "j", "k", "_"})
 EACH_PREFIX = "each_"
 BARE_EACH_TOKEN = "each"

package/hooks/hooks_constants/destructive_command_segment_constants.py

@@ -41,6 +41,7 @@ ALL_INTERPRETER_AND_WRAPPER_COMMANDS: frozenset[str] = frozenset(
         "su",
         "env",
         "xargs",
+        "parallel",
         "awk",
         "gawk",
         "mawk",
@@ -66,6 +67,12 @@ ALL_REMOTE_AND_PROGRAM_STRING_EXECUTORS: frozenset[str] = frozenset(
     }
 )
 ALL_STRING_ARGUMENT_EXECUTION_FLAGS: frozenset[str] = frozenset({"-c", "-e"})
+FIND_PROGRAM_NAME: str = "find"
+ALL_FIND_EXEC_ACTION_FLAGS: frozenset[str] = frozenset({"-exec", "-execdir"})
+ALL_FIND_EXEC_ACTION_TERMINATORS: frozenset[str] = frozenset({";", "+"})
+ALL_FIND_GLOBAL_OPTION_FLAGS_WITHOUT_VALUE: frozenset[str] = frozenset({"-H", "-L", "-P"})
+ALL_FIND_GLOBAL_OPTION_FLAGS_TAKING_A_VALUE: frozenset[str] = frozenset({"-D"})
+FIND_OPTIMIZATION_LEVEL_OPTION_PREFIX: str = "-O"
 ALL_BENIGN_COMPOUND_SEGMENT_COMMANDS: frozenset[str] = frozenset(
     {
         "echo",
@@ -176,3 +183,11 @@ ALL_LAUNCHER_OPTIONS_TAKING_SEPARATE_VALUE: frozenset[str] = frozenset(
     }
 )
 ALL_SUBSHELL_GROUPING_CHARACTERS: str = "({"
+ALL_KNOWN_TEMPORARY_ENVIRONMENT_VARIABLE_NAMES: frozenset[str] = frozenset(
+    {
+        "TEMP",
+        "TMP",
+        "TMPDIR",
+        "CLAUDE_JOB_DIR",
+    }
+)

package/hooks/hooks_constants/orphan_css_class_constants.py

@@ -0,0 +1,40 @@
+"""Constants for the orphan-CSS-class check in code_rules_enforcer.
+
+A Python module that builds HTML emits ``class="..."`` attributes in string
+literals and pairs them with a ``<style>`` block whose selectors style those
+classes. When a class appears in the markup but no selector defines it, the
+markup carries a dead attribute or the style block is missing a rule. This
+module holds the patterns that pair the two halves and the package-scan
+budget that bounds the sibling read.
+"""
+
+import re
+
+__all__ = [
+    "CLASS_ATTRIBUTE_PATTERN",
+    "STYLE_BLOCK_PATTERN",
+    "CSS_CLASS_SELECTOR_PATTERN",
+    "PYTHON_MODULE_GLOB",
+    "MAX_ORPHAN_CSS_CLASS_ISSUES",
+    "MAX_SIBLING_MODULES_SCANNED",
+    "ORPHAN_CSS_CLASS_MESSAGE_SUFFIX",
+]
+
+CLASS_ATTRIBUTE_PATTERN: re.Pattern[str] = re.compile(r"""class\s*=\s*["']([^"']+)["']""")
+
+STYLE_BLOCK_PATTERN: re.Pattern[str] = re.compile(
+    r"<style[^>]*>(.*?)</style>", re.DOTALL | re.IGNORECASE
+)
+
+CSS_CLASS_SELECTOR_PATTERN: re.Pattern[str] = re.compile(r"\.(-?[_a-zA-Z][\w-]*)")
+
+PYTHON_MODULE_GLOB: str = "*.py"
+
+MAX_ORPHAN_CSS_CLASS_ISSUES: int = 10
+
+MAX_SIBLING_MODULES_SCANNED: int = 60
+
+ORPHAN_CSS_CLASS_MESSAGE_SUFFIX: str = (
+    "add a matching '.<class>' selector to the <style> block, "
+    "or drop the unused class attribute (CODE_RULES self-documenting markup)"
+)

package/hooks/validation/mypy_validator.py

@@ -69,13 +69,55 @@ def is_file_within_project(target_file: str, project_root: Path) -> bool:
         return False
 
 
-def build_mypy_command(relative_file_path: str) -> list[str]:
-    if IS_WINDOWS:
-        base_command = [sys.executable, "-m", "mypy"]
-    else:
-        base_command = ["mypy"]
+def discover_mypy_config(target_file: Path) -> Path | None:
+    """Return the nearest ancestor ``pyproject.toml`` that configures mypy.
+
+    Mypy applies a project's ``[tool.mypy]`` settings only when the config file
+    is on its invocation path; handing the discovered config to mypy lets a
+    check run from the repository root still honor the project's own import
+    resolution settings (such as ``ignore_missing_imports``) for a module that
+    imports its siblings by name. Reuses the validators-package walk-up so the
+    discovery logic lives in one place.
+
+    Args:
+        target_file: The Python file mypy will check.
+
+    Returns:
+        The nearest ancestor ``pyproject.toml`` declaring a ``[tool.mypy]``
+        table, or None when none exists above the file or the walk-up helper
+        cannot be imported.
+    """
+    validators_directory = os.path.join(
+        os.path.dirname(os.path.dirname(os.path.abspath(__file__))), "validators"
+    )
+    if validators_directory not in sys.path:
+        sys.path.insert(0, validators_directory)
+    try:
+        integration_module = importlib.import_module("mypy_integration")
+    except ImportError:
+        return None
+    discovered_config = integration_module.find_pyproject_with_mypy_config(target_file)
+    return discovered_config if isinstance(discovered_config, Path) else None
+
+
+def build_mypy_command(relative_file_path: str, mypy_config_file: Path | None) -> list[str]:
+    """Build the mypy command line for one file.
 
-    return base_command + [
+    Args:
+        relative_file_path: The target file path relative to the project root.
+        mypy_config_file: The ``pyproject.toml`` to pass via ``--config-file``,
+            or None to let mypy fall back to its own config discovery.
+
+    Returns:
+        The full mypy argument vector, including the interpreter prefix on
+        Windows and the config file when one was discovered.
+    """
+    base_command = [sys.executable, "-m", "mypy"] if IS_WINDOWS else ["mypy"]
+
+    config_arguments = (
+        ["--config-file", str(mypy_config_file)] if mypy_config_file is not None else []
+    )
+    return base_command + config_arguments + [
         "--no-error-summary",
         "--show-error-codes",
         "--no-color",
@@ -84,8 +126,18 @@ def build_mypy_command(relative_file_path: str) -> list[str]:
 
 
 def run_mypy(target_file: str, project_root: str) -> tuple[int, str]:
+    """Run mypy on one file from the project root and return its result.
+
+    Args:
+        target_file: The absolute path of the file to type-check.
+        project_root: The directory mypy runs from.
+
+    Returns:
+        The mypy exit code paired with its combined stdout and stderr text.
+    """
     relative_file_path = os.path.relpath(target_file, project_root)
-    mypy_command = build_mypy_command(relative_file_path)
+    mypy_config_file = discover_mypy_config(Path(target_file))
+    mypy_command = build_mypy_command(relative_file_path, mypy_config_file)
 
     completed_process = subprocess.run(
         mypy_command,

package/hooks/validation/test_mypy_validator.py

@@ -0,0 +1,94 @@
+"""Behavior tests for the mypy_validator config-discovery fix.
+
+The hook runs mypy from the project root, so without handing mypy the project's
+own ``[tool.mypy]`` config a module that imports its siblings by name draws a
+spurious ``import-not-found`` error. These tests drive the real production
+functions: ``discover_mypy_config`` walks up to the nearest configuring
+``pyproject.toml`` and ``run_mypy`` passes it through so the project's
+``ignore_missing_imports`` setting applies.
+"""
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+HOOK_PATH = Path(__file__).resolve().parent / "mypy_validator.py"
+
+MODULE_WITH_SIBLING_IMPORT = (
+    "from sibling_only_resolvable_at_runtime import value\n\nx: int = value\n"
+)
+TOOL_MYPY_PYPROJECT = "[tool.mypy]\nignore_missing_imports = true\n"
+NON_MYPY_PYPROJECT = "[tool.ruff]\nline-length = 100\n"
+
+
+def _load_validator() -> ModuleType:
+    spec = importlib.util.spec_from_file_location("mypy_validator_under_test", HOOK_PATH)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def test_discover_mypy_config_finds_nearest_tool_mypy_pyproject(tmp_path: Path) -> None:
+    validator = _load_validator()
+    (tmp_path / "pyproject.toml").write_text(TOOL_MYPY_PYPROJECT, encoding="utf-8")
+    nested_module = tmp_path / "package" / "module.py"
+    nested_module.parent.mkdir(parents=True)
+    nested_module.write_text("value: int = 1\n", encoding="utf-8")
+
+    discovered = validator.discover_mypy_config(nested_module)
+
+    assert discovered is not None
+    assert discovered.resolve() == (tmp_path / "pyproject.toml").resolve()
+
+
+def test_discover_mypy_config_returns_none_without_tool_mypy(tmp_path: Path) -> None:
+    validator = _load_validator()
+    (tmp_path / "pyproject.toml").write_text(NON_MYPY_PYPROJECT, encoding="utf-8")
+    standalone_module = tmp_path / "module.py"
+    standalone_module.write_text("value: int = 1\n", encoding="utf-8")
+
+    assert validator.discover_mypy_config(standalone_module) is None
+
+
+def test_build_mypy_command_includes_config_file_when_present(tmp_path: Path) -> None:
+    validator = _load_validator()
+    config_file = tmp_path / "pyproject.toml"
+
+    command = validator.build_mypy_command("package/module.py", config_file)
+
+    assert "--config-file" in command
+    assert command[command.index("--config-file") + 1] == str(config_file)
+    assert command[-1] == "package/module.py"
+
+
+def test_build_mypy_command_omits_config_file_when_absent(tmp_path: Path) -> None:
+    validator = _load_validator()
+
+    command = validator.build_mypy_command("package/module.py", None)
+
+    assert "--config-file" not in command
+    assert command[-1] == "package/module.py"
+
+
+def test_run_mypy_suppresses_sibling_import_error_with_tool_mypy_config(tmp_path: Path) -> None:
+    validator = _load_validator()
+    (tmp_path / "pyproject.toml").write_text(TOOL_MYPY_PYPROJECT, encoding="utf-8")
+    importer_module = tmp_path / "importer.py"
+    importer_module.write_text(MODULE_WITH_SIBLING_IMPORT, encoding="utf-8")
+
+    exit_code, output = validator.run_mypy(str(importer_module), str(tmp_path))
+
+    assert exit_code == 0, output
+    assert "import-not-found" not in output
+
+
+def test_run_mypy_reports_import_error_without_tool_mypy_config(tmp_path: Path) -> None:
+    validator = _load_validator()
+    importer_module = tmp_path / "importer.py"
+    importer_module.write_text(MODULE_WITH_SIBLING_IMPORT, encoding="utf-8")
+
+    exit_code, output = validator.run_mypy(str(importer_module), str(tmp_path))
+
+    assert exit_code != 0
+    assert "import-not-found" in output

package/package.json

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

package/rules/orphan-css-class.md

@@ -0,0 +1,23 @@
+# Orphan CSS Class in Generated Markup
+
+**When this applies:** Any Write or Edit to a production `.py` file that builds HTML by emitting `class="..."` attributes inside string literals and pairs them with a `<style>` block — in the same file or in a companion module beside it.
+
+## Rule
+
+Every class name a markup string references has a matching `.<class>` selector in the `<style>` block. A class that appears in the markup but carries no selector anywhere is a dead attribute (or a missing rule): the markup names a style that the stylesheet never defines, so a reader who trusts the class to be styled is misled, and the attribute adds noise without effect.
+
+When you add a `class="..."` attribute, add its `.<class>` selector to the `<style>` block in the same change. When you drop a selector, drop the class attribute it styled.
+
+## What the gate checks
+
+The `check_orphan_css_classes` check in `code_rules_orphan_css_class.py` (wired into `code_rules_enforcer.py`) runs on every production Python write. It:
+
+1. Collects each class name referenced in a `class="..."` attribute across the file's string literals.
+2. Collects each class selector defined in a `<style>` block — both in the file under edit and in every Python module beside it (its own directory and immediate child directories), since a markup module commonly imports its style constant from a companion package directory.
+3. Flags each referenced class with no matching selector in that whole set.
+
+The check stays quiet for a file that emits no `class="..."` markup, and for a file whose markup has no `<style>` source nearby (its stylesheet lives outside the scan, so the gate cannot judge it). Test files are exempt, since a fixture may carry intentional orphan markup.
+
+## Why this is a hook, not a lint pass
+
+A class attribute with no matching selector reads as styled but renders unstyled. Native elements such as `<details>` stay functional without CSS, so the gap survives review as a cosmetic defect rather than a crash — exactly the class of issue that slips past a manual pass and lands as a deferred code-standard finding. Catching it at Write time keeps the markup and the stylesheet in step as each line is written.

package/skills/autoconverge/workflow/autoconverge_report_constants/render_report_constants.py

@@ -62,7 +62,6 @@ SCENE_FIELD_CAPTION = "caption"
 
 MEDIUM_TERMINAL = "terminal"
 MEDIUM_CODE = "code"
-MEDIUM_TEXT = "text"
 
 CATEGORY_BUG = "bug"
 CATEGORY_LABEL_BY_VALUE = {