claude-dev-env 1.60.0 → 1.62.0

package/hooks/blocking/code_rules_dead_config_field.py

@@ -0,0 +1,321 @@
+"""Dead config-dataclass field check: cross-module scan for ``*Config`` @dataclass fields.
+
+A config ``@dataclass`` (any class whose name ends in ``"Config"``) is defined
+in one module but constructed and consumed in others, so the per-file dead-field
+check in ``code_rules_dead_dataclass_field`` cannot judge its fields — it skips
+any class that is not constructed in the same file. This check resolves the
+enclosing package tree — the scan root — and flags a ``*Config`` dataclass field
+whose name appears as an attribute read (``obj.field``) in no production module
+anywhere under that root.
+
+The scan is deliberately conservative to keep false positives near zero:
+
+- Only ``@dataclass`` classes whose name ends in ``"Config"`` participate; other
+  dataclasses are covered by the per-file check.
+- Test and migration files are exempt as write destinations, so a field added to
+  a config dataclass inside a test is never flagged.
+- Production modules under the scan root are scanned for attribute reads; test
+  and migration modules are deliberately excluded so a field read only by test
+  code is still flagged as dead-in-production.
+- Field reads are collected as ``ast.Attribute.attr`` values (``obj.field``),
+  augmented-assignment targets (``cfg.field += 1`` reads ``field`` before
+  writing it), string literals (covers ``getattr(obj, "field")``),
+  keyword-argument names (covers ``ThemeUpdateConfig(debug_port=1)`` and
+  ``replace(cfg, debug_port=1)``), and match-pattern keyword attribute names
+  (``case Config(field=found)``). Plain ``ast.Name`` references are excluded — a
+  local variable named ``debug_port`` is not a read of ``config.debug_port``.
+- A production module that reflectively reads a whole instance — a bare or
+  ``dataclasses``-qualified call to ``asdict``, ``astuple``, ``fields``,
+  ``replace``, or ``vars``, or a read of ``obj.__dict__`` — consumes every field
+  at once without naming any single field, so the check is suppressed for the
+  whole tree (returns ``[]``).
+- A scan root whose total file count exceeds the configured cap cannot prove any
+  field dead, so the check returns ``[]`` on a cap hit.
+- A field read only by a module outside the resolved scan root is treated as dead
+  — the same conservative scoping the dead-module-constant check accepts.
+
+Unlike the per-file dead-dataclass-field check, this cross-module check does NOT
+suppress on a dataclass-dunder whole-instance read — instance comparison
+(``cfg == other``), set or dict membership, formatted-string conversion
+(``f"{cfg}"``), or whole-instance stringification
+(``str(cfg)``/``repr(cfg)``/``format(cfg)``). Those syntactic forms are not bound
+to a config instance, and tree-wide one incidental match anywhere would disable
+the check on any realistic package. The consequence is a documented, rare
+limitation: a ``*Config`` field read ONLY via whole-instance dunder comparison or
+stringification, and never read directly anywhere in production, may be flagged.
+The augmented-assignment read mechanism (``cfg.field += 1`` reads ``field``
+before writing it) is precise and remains a counted read.
+"""
+
+import ast
+import os
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_dead_dataclass_field import (  # noqa: E402
+    _augmented_assignment_attribute_names,
+    _dataclass_field_definitions,
+    _is_dataclass,
+)
+from code_rules_dead_module_constant import (  # noqa: E402
+    _scan_root_for_constants_module,
+)
+from code_rules_shared import (  # noqa: E402
+    is_migration_file,
+    is_test_file,
+)
+
+from hooks_constants.dead_config_field_constants import (  # noqa: E402
+    ALL_REFLECTIVE_FIELD_CONSUMER_NAMES,
+    CONFIG_CLASS_NAME_SUFFIX,
+    DATACLASSES_MODULE_NAME,
+    DEAD_CONFIG_FIELD_GUIDANCE,
+    MAX_DEAD_CONFIG_FIELD_ISSUES,
+    MAX_SCAN_ROOT_FILE_COUNT,
+    PYTHON_SOURCE_SUFFIX,
+    WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME,
+)
+
+
+def _is_config_dataclass(class_node: ast.ClassDef) -> bool:
+    """Return whether a class is a @dataclass whose name ends in ``"Config"``.
+
+    Args:
+        class_node: The class definition node to test.
+
+    Returns:
+        True when the class carries a ``@dataclass`` decorator and its name ends
+        in ``"Config"``.
+    """
+    return _is_dataclass(class_node) and class_node.name.endswith(CONFIG_CLASS_NAME_SUFFIX)
+
+
+def _reads_whole_instance_reflectively(tree: ast.Module) -> bool:
+    """Return whether a module consumes a whole instance via a reflective read.
+
+    Detects a bare call to any reflective whole-instance consumer (``asdict``,
+    ``astuple``, ``fields``, ``replace``, ``vars`` imported from ``dataclasses``),
+    a ``dataclasses``-qualified call to the same consumers
+    (``dataclasses.asdict(cfg)``, ``dataclasses.replace(cfg, ...)``), and a read
+    of the ``__dict__`` attribute. The method-call form must be ``dataclasses``-
+    qualified — an unrelated ``"text".replace(...)`` or ``frame.fields(...)`` on
+    another object does not match. Each matched form reads every field of an
+    instance at once without naming any single field, so a module that uses one
+    cannot prove a config field unread.
+
+    Args:
+        tree: The parsed module to inspect.
+
+    Returns:
+        True when the module makes a bare or ``dataclasses``-qualified call to a
+        reflective whole-instance consumer, or reads ``obj.__dict__``.
+    """
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Attribute):
+            if each_node.attr == WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME:
+                return True
+            continue
+        if not isinstance(each_node, ast.Call):
+            continue
+        function_node = each_node.func
+        if isinstance(function_node, ast.Name) and function_node.id in ALL_REFLECTIVE_FIELD_CONSUMER_NAMES:
+            return True
+        if (
+            isinstance(function_node, ast.Attribute)
+            and isinstance(function_node.value, ast.Name)
+            and function_node.value.id == DATACLASSES_MODULE_NAME
+            and function_node.attr in ALL_REFLECTIVE_FIELD_CONSUMER_NAMES
+        ):
+            return True
+    return False
+
+
+def _attribute_read_names_in_source(source: str) -> tuple[set[str], bool]:
+    """Return attribute names read in a module's source and a suppression flag.
+
+    Collects attribute names via five mechanisms: ``ast.Attribute.attr`` values
+    in Load context, augmented-assignment targets (so ``cfg.debug_port += 1``
+    contributes ``"debug_port"`` because ``+=`` reads the attribute before
+    writing it), string literals (so ``getattr(obj, "field")`` contributes
+    ``"field"``), keyword-argument names (so ``ThemeUpdateConfig(debug_port=1)``
+    and ``replace(cfg, debug_port=1)`` each contribute ``"debug_port"``), and
+    ``ast.MatchClass.kwd_attrs`` names (so ``case Config(field=x)`` contributes
+    ``"field"``). The boolean reports whether the module suppresses the
+    dead-field check, which it does only when it reflectively reads a whole
+    instance — a bare or ``dataclasses``-qualified ``asdict``/``astuple``/
+    ``fields``/``replace``/``vars`` call, or an ``obj.__dict__`` read — because
+    that pattern reads every field at once without naming any single field, so
+    the caller treats it as "cannot prove any field dead". A ``SyntaxError``
+    contributes no names and no suppression.
+
+    Args:
+        source: The full text of a ``.py`` module.
+
+    Returns:
+        A (read_names, suppresses_dead_field_check) pair. The name set is every
+        attribute name the module reads via any of the five mechanisms above;
+        suppresses_dead_field_check is True only when a reflective whole-instance
+        read is present.
+    """
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return set(), False
+    all_read_names: set[str] = _augmented_assignment_attribute_names(tree)
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Attribute) and isinstance(each_node.ctx, ast.Load):
+            all_read_names.add(each_node.attr)
+        elif isinstance(each_node, ast.Constant) and isinstance(each_node.value, str):
+            all_read_names.add(each_node.value)
+        elif isinstance(each_node, ast.MatchClass):
+            all_read_names.update(each_node.kwd_attrs)
+        elif isinstance(each_node, ast.keyword) and each_node.arg is not None:
+            all_read_names.add(each_node.arg)
+    suppresses_dead_field_check = _reads_whole_instance_reflectively(tree)
+    return all_read_names, suppresses_dead_field_check
+
+
+def _all_production_read_names_under_root(
+    scan_root: Path,
+    written_path: Path,
+    written_content: str,
+) -> tuple[set[str], bool, bool]:
+    """Return read names, a cap-hit flag, and a suppression flag for the tree.
+
+    Scans every production ``.py`` module under ``scan_root`` (excluding test and
+    migration files) for attribute reads. The written module's post-edit content
+    replaces its on-disk text so the current edit is included. Scanning stops at
+    the configured file cap. A module that reflectively reads a whole instance —
+    a bare or ``dataclasses``-qualified ``asdict``/``astuple``/``fields``/
+    ``replace``/``vars`` call, or an ``obj.__dict__`` read — sets the suppression
+    flag, signalling the caller that no field can be proven dead.
+
+    Args:
+        scan_root: The directory tree to scan.
+        written_path: The resolved path of the module being written.
+        written_content: The post-edit text of the written module.
+
+    Returns:
+        A (read_names, cap_was_hit, suppresses_dead_field_check) triple. The name
+        set is the union of attribute reads across every scanned production
+        module; cap_was_hit is True when the scan stopped at the configured file
+        cap before finishing the tree; suppresses_dead_field_check is True when
+        any scanned module reflectively reads a whole instance.
+    """
+    all_read_names, suppresses_dead_field_check = _attribute_read_names_in_source(written_content)
+    written_path_key = os.path.normcase(str(written_path))
+    scanned_file_count = 1
+    for each_path in scan_root.rglob("*" + PYTHON_SOURCE_SUFFIX):
+        if not each_path.is_file():
+            continue
+        if os.path.normcase(str(each_path.resolve())) == written_path_key:
+            continue
+        if is_test_file(str(each_path)):
+            continue
+        if is_migration_file(str(each_path)):
+            continue
+        scanned_file_count += 1
+        if scanned_file_count > MAX_SCAN_ROOT_FILE_COUNT:
+            return all_read_names, True, suppresses_dead_field_check
+        try:
+            sibling_source = each_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        sibling_read_names, sibling_suppresses_dead_field_check = _attribute_read_names_in_source(
+            sibling_source
+        )
+        all_read_names |= sibling_read_names
+        suppresses_dead_field_check = (
+            suppresses_dead_field_check or sibling_suppresses_dead_field_check
+        )
+    return all_read_names, False, suppresses_dead_field_check
+
+
+def check_dead_config_dataclass_fields(
+    content: str, file_path: str, full_file_content: str | None = None
+) -> list[str]:
+    """Flag a ``*Config`` @dataclass field read by no production module in the package tree.
+
+    Runs a cross-module scan restricted to ``@dataclass`` classes whose name ends
+    in ``"Config"``. For each such config dataclass in the written file, every
+    instance field whose name does not appear as an attribute read (``obj.field``),
+    augmented-assignment target (``cfg.field += 1``), string literal,
+    keyword-argument name (constructor or ``replace`` keyword), or match-pattern
+    keyword attribute in any production module under the enclosing scan root is
+    flagged as dead. When any production module under the scan root reflectively
+    reads a whole instance — a bare or ``dataclasses``-qualified call to
+    ``asdict``, ``astuple``, ``fields``, ``replace``, or ``vars``, or a read of
+    ``obj.__dict__`` — the check is suppressed for the whole tree and returns
+    ``[]``, since that pattern reads every field at once without naming any single
+    field. Test and
+    migration files are exempt as write destinations; production modules under the
+    scan root are scanned while test and migration modules in the tree are excluded
+    so fields read only by test code are still flagged as dead-in-production.
+    Whole-file analysis runs against ``full_file_content`` when supplied so an Edit
+    fragment is judged against the reconstructed post-edit file. A scan root
+    exceeding the file cap returns ``[]`` (cannot prove dead). The scan root is
+    resolved the same way as the dead-module-constant check: a ``config/`` module's
+    root is its parent directory, a module in a package directory's root is the
+    package's parent, and a top-level module's root is its enclosing directory.
+
+    Args:
+        content: The new content under validation (Edit fragment or whole file).
+        file_path: The destination path, used for the test/migration exemptions
+            and scan-root resolution.
+        full_file_content: The reconstructed post-edit whole-file content for an
+            Edit, or None for a Write where ``content`` is already the whole file.
+
+    Returns:
+        One violation message per dead config dataclass field, capped at the
+        configured maximum. Returns an empty list when the file is exempt, no
+        qualifying config dataclass is found, the scan root exceeds the file cap,
+        or a SyntaxError prevents parsing.
+    """
+    if is_test_file(file_path):
+        return []
+    if is_migration_file(file_path):
+        return []
+    effective_content = content if full_file_content is None else full_file_content
+    try:
+        tree = ast.parse(effective_content)
+    except SyntaxError:
+        return []
+    all_config_classes = [
+        each_node
+        for each_node in ast.walk(tree)
+        if isinstance(each_node, ast.ClassDef) and _is_config_dataclass(each_node)
+    ]
+    if not all_config_classes:
+        return []
+    scan_root = _scan_root_for_constants_module(file_path)
+    written_path = Path(file_path).resolve()
+    all_read_names, cap_was_hit, suppresses_dead_field_check = (
+        _all_production_read_names_under_root(
+            scan_root,
+            written_path,
+            effective_content,
+        )
+    )
+    if cap_was_hit:
+        return []
+    if suppresses_dead_field_check:
+        return []
+    all_issues: list[str] = []
+    for each_class in all_config_classes:
+        for each_field_name, each_field_line in _dataclass_field_definitions(each_class):
+            if each_field_name in all_read_names:
+                continue
+            all_issues.append(
+                f"Line {each_field_line}: config dataclass field {each_field_name!r}"
+                f" on {each_class.name} - {DEAD_CONFIG_FIELD_GUIDANCE}"
+            )
+            if len(all_issues) >= MAX_DEAD_CONFIG_FIELD_ISSUES:
+                return all_issues
+    return all_issues

package/hooks/blocking/code_rules_enforcer.py

@@ -33,6 +33,7 @@ from code_rules_annotations_length import (  # noqa: E402
     check_known_pytest_fixture_annotations,
     check_parameter_annotations,
     check_return_annotations,
+    check_unused_known_pytest_fixture_parameters,
 )
 from code_rules_banned_identifiers import (  # noqa: E402
     check_banned_identifiers,
@@ -51,6 +52,9 @@ from code_rules_constants_config import (  # noqa: E402
     check_constants_outside_config_advisory,
     check_file_global_constants_use_count,
 )
+from code_rules_dead_config_field import (  # noqa: E402
+    check_dead_config_dataclass_fields,
+)
 from code_rules_dead_dataclass_field import (  # noqa: E402
     check_dead_dataclass_fields,
 )
@@ -89,6 +93,9 @@ from code_rules_optional_params import (  # noqa: E402
     check_duplicated_format_patterns,
     check_unused_optional_parameters,
 )
+from code_rules_orphan_css_class import (  # noqa: E402
+    check_orphan_css_classes,
+)
 from code_rules_paths_syspath import (  # noqa: E402
     check_hardcoded_user_paths,
     check_sys_path_insert_deduplication_guard,
@@ -275,12 +282,18 @@ def validate_content(
         all_issues.extend(
             check_dead_dataclass_fields(content, file_path, full_file_content)
         )
+        all_issues.extend(
+            check_dead_config_dataclass_fields(content, file_path, full_file_content)
+        )
         all_issues.extend(
             check_dead_module_constants(content, file_path, full_file_content)
         )
         all_issues.extend(check_library_print(content, file_path))
         all_issues.extend(check_parameter_annotations(content, file_path))
         all_issues.extend(check_known_pytest_fixture_annotations(content, file_path))
+        all_issues.extend(
+            check_unused_known_pytest_fixture_parameters(content, file_path)
+        )
         all_issues.extend(check_return_annotations(content, file_path))
         all_issues.extend(
             check_function_length(
@@ -294,6 +307,7 @@ def validate_content(
         all_issues.extend(check_inline_literal_collections(content, file_path))
         all_issues.extend(check_inline_tuple_string_magic(content, file_path))
         all_issues.extend(check_string_literal_magic(content, file_path))
+        all_issues.extend(check_orphan_css_classes(effective_content, file_path))
         check_incomplete_mocks(content, file_path)
         check_duplicated_format_patterns(content, file_path)
         advise_cross_skill_duplicate_helper(effective_content, file_path)

package/hooks/blocking/code_rules_orphan_css_class.py

@@ -0,0 +1,196 @@
+"""Orphan-CSS-class check: class attributes in markup with no matching selector."""
+
+import ast
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parent)
+_hooks_directory = str(Path(__file__).resolve().parent.parent)
+if _blocking_directory not in sys.path:
+    sys.path.insert(0, _blocking_directory)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from code_rules_shared import (  # noqa: E402
+    is_test_file,
+)
+
+from hooks_constants.orphan_css_class_constants import (  # noqa: E402
+    CLASS_ATTRIBUTE_PATTERN,
+    CSS_CLASS_SELECTOR_PATTERN,
+    MAX_ORPHAN_CSS_CLASS_ISSUES,
+    MAX_SIBLING_MODULES_SCANNED,
+    ORPHAN_CSS_CLASS_MESSAGE_SUFFIX,
+    PYTHON_MODULE_GLOB,
+    STYLE_BLOCK_PATTERN,
+)
+
+
+def _string_literals_with_lines(tree: ast.Module) -> list[tuple[str, int]]:
+    """Return every string-constant value in the tree paired with its line number.
+
+    Args:
+        tree: The parsed module to walk.
+
+    Returns:
+        A list of ``(string_value, line_number)`` pairs, one per string constant.
+    """
+    literals: list[tuple[str, int]] = []
+    for each_node in ast.walk(tree):
+        if isinstance(each_node, ast.Constant) and isinstance(each_node.value, str):
+            literals.append((each_node.value, each_node.lineno))
+    return literals
+
+
+def _class_names_in_attribute(attribute_text: str) -> list[str]:
+    """Return the individual class names in a single ``class="..."`` attribute.
+
+    Args:
+        attribute_text: The whitespace-separated class list from one attribute.
+
+    Returns:
+        Each non-empty class token, in order.
+    """
+    return [each_token for each_token in attribute_text.split() if each_token]
+
+
+def _class_references_with_lines(
+    all_string_literals: list[tuple[str, int]],
+) -> list[tuple[str, int]]:
+    """Return every class name referenced in a ``class="..."`` attribute.
+
+    Args:
+        all_string_literals: The ``(literal_text, line_number)`` constants to scan.
+
+    Returns:
+        A list of ``(class_name, line_number)`` pairs, one per referenced class.
+    """
+    references: list[tuple[str, int]] = []
+    for each_text, each_line in all_string_literals:
+        for each_match in CLASS_ATTRIBUTE_PATTERN.finditer(each_text):
+            for each_class_name in _class_names_in_attribute(each_match.group(1)):
+                references.append((each_class_name, each_line))
+    return references
+
+
+def _defined_class_selectors(all_string_literals: list[tuple[str, int]]) -> set[str]:
+    """Return every CSS class name defined by a selector inside a ``<style>`` block.
+
+    Args:
+        all_string_literals: The ``(literal_text, line_number)`` constants to scan.
+
+    Returns:
+        The set of class names that carry a matching ``.<class>`` selector.
+    """
+    defined: set[str] = set()
+    for each_text, _ in all_string_literals:
+        for each_style_match in STYLE_BLOCK_PATTERN.finditer(each_text):
+            for each_selector in CSS_CLASS_SELECTOR_PATTERN.finditer(
+                each_style_match.group(1)
+            ):
+                defined.add(each_selector.group(1))
+    return defined
+
+
+def _sibling_module_paths(file_path: str) -> list[Path]:
+    """Return the importable sibling Python modules near *file_path*.
+
+    Scans the file's own directory and its immediate child directories, since a
+    markup module commonly imports its ``<style>`` constant from a companion
+    package directory beside it. The scan is bounded so a large tree never
+    stalls a write.
+
+    Args:
+        file_path: The absolute path of the file under validation.
+
+    Returns:
+        The sibling ``.py`` paths to read for cross-module selector resolution,
+        excluding the file itself, capped at the scan budget.
+    """
+    target = Path(file_path)
+    base_directory = target.parent
+    if not base_directory.is_dir():
+        return []
+    siblings: list[Path] = []
+    for each_path in sorted(base_directory.rglob(PYTHON_MODULE_GLOB)):
+        if each_path.resolve() == target.resolve():
+            continue
+        siblings.append(each_path)
+        if len(siblings) >= MAX_SIBLING_MODULES_SCANNED:
+            break
+    return siblings
+
+
+def _selectors_from_sibling_modules(file_path: str) -> set[str]:
+    """Return CSS class selectors defined in ``<style>`` blocks of sibling modules.
+
+    Args:
+        file_path: The absolute path of the file under validation.
+
+    Returns:
+        The union of class names whose selectors appear in any readable sibling
+        module's string literals.
+    """
+    selectors: set[str] = set()
+    for each_sibling in _sibling_module_paths(file_path):
+        try:
+            sibling_source = each_sibling.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError):
+            continue
+        try:
+            sibling_tree = ast.parse(sibling_source)
+        except SyntaxError:
+            continue
+        selectors |= _defined_class_selectors(_string_literals_with_lines(sibling_tree))
+    return selectors
+
+
+def check_orphan_css_classes(content: str, file_path: str) -> list[str]:
+    """Flag ``class="..."`` markup whose class has no matching CSS selector.
+
+    A module that emits HTML names each class it references with a matching
+    ``.<class>`` selector, either in a ``<style>`` block in the same file or in
+    a companion module beside it. A referenced class with no selector anywhere
+    is a dead attribute (or a missing rule), so this flags it. The check only
+    fires for a file that itself emits markup, and only after a ``<style>``
+    block exists in the file or a sibling — a file with markup but no style
+    source nearby is left alone, since its stylesheet lives outside the scan.
+    Test files are exempt, since a fixture may carry intentional orphan markup.
+
+    Args:
+        content: The new or whole-file content being written.
+        file_path: The destination path of the write or edit.
+
+    Returns:
+        One issue per orphan class reference, capped at the issue budget.
+    """
+    if is_test_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    all_string_literals = _string_literals_with_lines(tree)
+    class_references = _class_references_with_lines(all_string_literals)
+    if not class_references:
+        return []
+    defined_selectors = _defined_class_selectors(all_string_literals)
+    defined_selectors |= _selectors_from_sibling_modules(file_path)
+    if not defined_selectors:
+        return []
+    issues: list[str] = []
+    reported_classes: set[str] = set()
+    for each_class_name, each_line in class_references:
+        if each_class_name in defined_selectors:
+            continue
+        if each_class_name in reported_classes:
+            continue
+        reported_classes.add(each_class_name)
+        issues.append(
+            f"Line {each_line}: CSS class {each_class_name!r} used in markup"
+            f" has no matching '.{each_class_name}' selector - "
+            f"{ORPHAN_CSS_CLASS_MESSAGE_SUFFIX}"
+        )
+        if len(issues) >= MAX_ORPHAN_CSS_CLASS_ISSUES:
+            break
+    return issues

package/hooks/blocking/config/verified_commit_constants.py

@@ -47,6 +47,20 @@ WRITE_CALL_REGION_PATTERN = (
 )
 VERDICT_KEY_ALL_PASS = "all_pass"
 VERDICT_KEY_MANIFEST_SHA256 = "manifest_sha256"
+VERDICT_KEY_FINDINGS = "findings"
+SUBAGENTS_DIRECTORY_NAME = "subagents"
+AGENT_TRANSCRIPT_GLOB = "agent-*.jsonl"
+AGENT_META_SIDECAR_SUFFIX = ".meta.json"
+AGENT_META_TYPE_KEY = "agentType"
+TRANSCRIPT_ENTRY_TYPE_KEY = "type"
+TRANSCRIPT_ASSISTANT_ENTRY_TYPE = "assistant"
+TRANSCRIPT_MESSAGE_KEY = "message"
+TRANSCRIPT_CONTENT_KEY = "content"
+TRANSCRIPT_CONTENT_TYPE_KEY = "type"
+TRANSCRIPT_TEXT_CONTENT_TYPE = "text"
+TRANSCRIPT_TEXT_KEY = "text"
+VERDICT_FENCE_PATTERN = r"```verdict\s*\n(.*?)```"
+MANIFEST_HASH_CLI_FLAG = "--manifest-hash"
 DOCS_ONLY_EXTENSIONS = frozenset(
     {".md", ".txt", ".rst", ".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp", ".ico"}
 )
@@ -82,9 +96,8 @@ COMMAND_AFTER_DIRECTORY_CHANGE_PATTERN = r"[;&|\n][\s]*\S"
 OPTION_WITH_VALUE_STEP = 2
 ALL_GATED_TOOL_NAMES = ("Bash", "PowerShell")
 HASH_PREVIEW_LENGTH = 16
+VERIFICATION_BYPASS_MARKER = "# verify-skip"
 MINTING_AGENT_TYPE = "code-verifier"
-SPAWN_LOOKUP_ATTEMPT_COUNT = 3
-SPAWN_LOOKUP_RETRY_DELAY_SECONDS = 0.1
 VERDICT_DIRECTORY_GUARD_MESSAGE = (
     "BLOCKED: [VERDICT_DIRECTORY_GUARD] Shell access to the verification "
     "verdict directory (~/.claude/verification/) is denied. Only the "