claude-dev-env 1.61.0 → 1.62.0

package/CLAUDE.md

@@ -73,6 +73,14 @@ When asked to sync git ("get X onto origin main", "update main"), fast-forward l
 
 For scheduled/cron tasks, default to sub-hour intervals (30-minute); do not propose hourly cadences.
 
+## Task Tracking
+
+Track every task with the task tool, always — for all sessions and all tasks. Capture each task with `TaskCreate` as it arrives, mark it `in_progress` with `TaskUpdate` when you start, and `completed` when it is done. Run `/task-build` to gather any open tasks and add them to the list in one pass.
+
+## Working in the claude-code-config Repo
+
+When changing how skills, rules, or hooks install or sync in this repo (for example adding a skill), read `docs/references/skill-install-system.md` — it maps the install pipeline in `packages/claude-dev-env/bin/install.mjs`.
+
 ## Additional Non-overlapping Rules
 
 - **task_scope:** Match every action to what was explicitly requested. When intent is ambiguous, research official docs and present options via AskUserQuestion before making any changes. Proceed with edits only on explicit instruction.

package/bin/install.mjs

@@ -149,7 +149,7 @@ const INSTALL_GROUPS = {
         skills: [
             'anthropic-plan', 'everything-search',
             'pr-review-responder',
-            'recall', 'remember'
+            'recall', 'remember', 'task-build'
         ],
         includeDirectories: ['rules', 'docs', 'commands', 'agents', 'audit-rubrics'],
         includeAllHooks: true,

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

@@ -52,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,
 )
@@ -279,6 +282,9 @@ 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)
         )

package/hooks/blocking/config/verified_commit_constants.py

@@ -96,6 +96,7 @@ 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"
 VERDICT_DIRECTORY_GUARD_MESSAGE = (
     "BLOCKED: [VERDICT_DIRECTORY_GUARD] Shell access to the verification "