claude-dev-env 1.60.0 → 1.61.0

package/CLAUDE.md

@@ -57,6 +57,10 @@ Repair agents run only on reported findings; the verifier re-checks after each r
 - **Tight edit scope:** Edit exactly what the task names — no whole-file rewrites, no renaming public method parameters, no changes beyond the stated task. When the user asks for a "lasting" or "reusable" fix, prefer the durable systemic fix over a one-off edit. When the task touches a pipeline, generator, or other repeated process, fix the process itself, not its individual outputs — even when the request does not say so; for one-off targets, a scoped patch remains the default.
 - **GitHub MCP first:** The GitHub MCP (`mcp__plugin_github_github__*`) is the primary path for PR and review-thread inspection; raw `gh api` is the fallback, not the default — MCP calls work the same from any worktree.
 
+## Destructive-command literals in Bash
+
+Never put a destructive-command literal (`rm -rf`, `git reset --hard`, `dd`, `mkfs`) inside a Bash command string, even when the shell never runs it — a quoted `python -c` argument, a heredoc body, an echoed string, a commit or PR body. The `destructive_command_blocker` hook matches the raw text and asks for confirmation, which a background run cannot answer, so the call stalls. Run hook and deletion checks through the committed test suite (`python -m pytest <test_file>`), or a throwaway script under `$CLAUDE_JOB_DIR/tmp` run as `python <file>.py` — either way the command string carries no destructive text, so the hook stays silent. Group genuine cleanup deletions into one teardown step. See `~/.claude/rules/no-inline-destructive-literals.md`.
+
 ## Sub-agent Output Validation
 
 After any sub-agent returns a PR description, file list, or counts, verify each claim against the actual diff and repo state before using it. Flag and correct any invented paths, fabricated counts, or out-of-scope changes before they land in commits or PR bodies.

package/audit-rubrics/category_rubrics/category-f-silent-failures.md

@@ -20,7 +20,7 @@
 |---|---|---|
 | F1 | Catch-all except clauses | `except:` (bare), `except Exception:`, `except BaseException:` followed by `pass` / `continue` / log-only. |
 | F2 | Errors logged then swallowed | `logger.error(...)` followed by `return None` / `return default` without re-raise. |
-| F3 | Default fallback values masking failure | `dict.get(key, default)` where the absence of the key is itself a bug; `or default` short-circuits hiding `None`. |
+| F3 | Default fallback values masking failure | `dict.get(key, default)` where the absence of the key is itself a bug; `or default` short-circuits hiding `None`. Includes the stale-payload-key shape: a `payload.get("KEY", "")` (or `payload["KEY"]` wrapped in a fallback) read against an external-input dict whose contract the diff migrated — the rest of the module reads the payload through a different key set named in the docstring and bound to same-named variables, while this lone read targets a dropped key, so it resolves to the default on every real payload and silently records an empty value into the field it feeds. The audit teammate lists every string-literal key read from each `*_payload` / event / request dict, checks each key against the payload contract the module's docstring and other reads set up, and flags a key read at one site that no docstring, second read, or same-named binding anchors. A key consumed inline with a meaningful default (`resolve(payload.get("cwd", "."))`) is legitimate, not stale — the flag is the dropped key whose value the field needs but never receives. |
 | F4 | Async task error swallowing | `asyncio.create_task(...)` without exception observation; `gather(..., return_exceptions=True)` consumed loosely. |
 | F5 | Boolean / status returns identical on success and failure | A function returns `True` on the happy path and `True` on the catch-all error path. |
 | F6 | Ignored return values from fallible calls | `subprocess.run` without `check=True` and unchecked `returncode`; `os.write` return value discarded. |

package/audit-rubrics/prompts/category-e-dead-code.md

@@ -1,4 +1,4 @@
-Audit [REPO/ARTIFACT] [TARGET_ID] for **Category E only** (dead code and unused imports). Skip A–D, F–P. Sub-bucket forced-exhaustion mode: Category E is decomposed into 8 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
+Audit [REPO/ARTIFACT] [TARGET_ID] for **Category E only** (dead code and unused imports). Skip A–D, F–P. Sub-bucket forced-exhaustion mode: Category E is decomposed into 9 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
 
 [ARTIFACT METADATA]
 - Repo / artifact: [REPO_OR_ARTIFACT_NAME]
@@ -69,6 +69,13 @@ Inline the artifact under this section using the section types defined in the ch
 - Scaffolding bodies (`pass`, `...`, `raise NotImplementedError`, empty `else { }`, single-statement `return None` placeholders) without a `# TODO` comment ARE Category E findings under the project's "Document Temporary Code" rule.
 - Adversarial probes for proof-of-absence: (a) any empty brace block in PowerShell / TypeScript / Go (`{ }` with no statements)? (b) any function whose entire body is `pass` / `return` / `return None`? (c) any branch that exits cleanly only because the surrounding loop is no-op for an empty input — is the no-op intentional or a placeholder?
 
+**E9. Constants-module exports with no importer**
+- For every module-level `UPPER_SNAKE` constant the artifact adds to a `*_constants.py` or `config/` module, grep the whole repo for the constant name and locate at least one importer (`from <module> import <NAME>`) or in-file reference.
+- The file-global use-count gate exempts a constants module because every name it exports carries zero in-file references by design, so a genuinely dead export slips past the write-time gate; this sub-bucket is the audit-time backstop for that exemption.
+- A sibling that a consumer module imports is live; a constant that no `from ... import` line and no in-file reference names anywhere in the repo is dead and must be removed (CODE_RULES 9.8).
+- Constants reached only by string-form lookup (`getattr(config, name)`, settings registries) are live; name the dynamic consumer when you mark such a constant referenced.
+- Adversarial probes for proof-of-absence: (a) does the artifact add any constant to a `*_constants.py` / `config/` module whose name returns zero hits outside its own definition line? (b) is any newly added constant shadowed by a same-named constant in a sibling module so the importer resolves the other one? (c) does any constant exist only as an `__all__` re-export with no downstream importer of that re-export?
+
 ## Cross-bucket questions to answer at the end
 
 Q1: Are there imports unused locally but consumed by a re-export pattern in another file? Cite the cross-file pair if found, or state the hypothesis "none — neither file declares `__all__`" with the supporting evidence.
@@ -79,7 +86,7 @@ Q3: Which symbol most likely will *become* dead code after a near-future refacto
 
 ## Output
 
-Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket E1-E8, produce Shape A or Shape B (with ≥3 probes). Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 P2 dead-code instances across these 8 sub-buckets — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket E1-E9, produce Shape A or Shape B (with ≥3 probes). Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 P2 dead-code instances across these 9 sub-buckets — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
 
 Note: most Category E findings are P2 (style / cleanup) unless the dead code masks an actual bug; the adversarial-pass quota uses P2 here.
 
@@ -87,7 +94,7 @@ Note: most Category E findings are P2 (style / cleanup) unless the dead code mas
 
 # Worked example: jl-cmd/claude-code-config PR #394
 
-Audit jl-cmd/claude-code-config PR #394 for **Category E only** (dead code and unused imports). Skip A–D, F–N. Sub-bucket forced-exhaustion mode: Category E is decomposed into 8 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
+Audit jl-cmd/claude-code-config PR #394 for **Category E only** (dead code and unused imports). Skip A–D, F–N. Sub-bucket forced-exhaustion mode: Category E is decomposed into 9 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
 
 PR: feat(scripts): add sweep-empty-dirs utility and scheduled-task installer
 Head SHA: 62c9c169ee7a44824e5da25c4cf8b74fdca08a53
@@ -161,6 +168,12 @@ ID prefix: `find`.
 - No `# TODO` markers in the diff — the project's own rule (`code-standards.md` → "Document Temporary Code") requires TODOs only for scaffolding/placeholder code. The two `pass`/`continue` bodies above are production behavior, not scaffolding.
 - Adversarial probes for proof-of-absence: (a) does the PowerShell script have an empty `else { }` or empty branch body? — scan lines 14-71 for any `{ }` with no statements between the braces. (b) does any function body consist of a single `pass` or `return` with no work done? — every function body in this PR performs at least one statement. (c) does the `Status` branch (lines 14-31) exit cleanly even when `$task.Triggers` is empty? — the `foreach` loop at line 26 is a no-op for an empty collection, which is correct behavior, not a stub.
 
+**E9. Constants-module exports with no importer**
+- `config/sweep_config.py` is the only constants module this PR adds; it declares `DEFAULT_AGE_SECONDS` and `DEFAULT_POLL_INTERVAL` and imports nothing.
+- `DEFAULT_AGE_SECONDS` — imported by `sweep_empty_dirs.py` line 10 (`from config.sweep_config import DEFAULT_AGE_SECONDS`) and read in `_build_parser`'s `--age` default. Live.
+- `DEFAULT_POLL_INTERVAL` — imported by `sweep_empty_dirs.py` line 11 and read in `_build_parser`'s `--interval` default. Live.
+- Adversarial probes for proof-of-absence: (a) does either constant return zero importers when grepped across the repo? — each has exactly one importer (`sweep_empty_dirs.py`), so neither is dead. (b) is either name shadowed by a same-named constant in a sibling module? — `sweep_config.py` is the only module that declares them. (c) does either constant exist only as an `__all__` re-export with no downstream consumer? — `sweep_config.py` declares no `__all__`; both are imported directly.
+
 ## Cross-bucket questions to answer at the end
 
 Q1: Are there imports unused locally but consumed by a re-export pattern in another file? Cite the cross-file pair if found. (Hypothesis: none — neither `sweep_empty_dirs.py` nor `test_sweep_empty_dirs.py` defines `__all__`, so re-export is not in play. `config/sweep_config.py` declares two constants that ARE consumed by `sweep_empty_dirs.py` lines 10-11; this is normal cross-file consumption, not a re-export.)
@@ -169,7 +182,7 @@ Q3: Which symbol most likely will *become* dead code after a near-future refacto
 
 ## Output
 
-Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket E1-E8, produce Shape A or Shape B (with ≥3 probes). Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 P2 dead-code instances across these 8 sub-buckets — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket E1-E9, produce Shape A or Shape B (with ≥3 probes). Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 P2 dead-code instances across these 9 sub-buckets — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
 
 Note: most Category E findings are P2 (style / cleanup) unless the dead code masks an actual bug; the adversarial-pass quota uses P2 here.
 

package/audit-rubrics/prompts/category-f-silent-failures.md

@@ -37,6 +37,7 @@ Repeat for every section in scope.
 
 **F3. Default fallback values masking failure**
 - `dict.get(key, default)` where the absence of the key is itself a bug.
+- Stale-payload-key shape: for each external-input dict (`*_payload`, event, request, parsed-JSON body), list every string-literal key read from it. Check each key against the contract the module's docstring and its other reads set up — a payload whose other reads bind to same-named variables and whose docstring names a key set is an established contract. Flag a lone read of a key outside that contract: it resolves to the `.get` default on every real payload and silently records an empty value into the field it feeds. A key consumed inline with a meaningful default (`resolve(payload.get("cwd", "."))`) is legitimate; the flag is the dropped key whose value the consuming field needs but never receives.
 - `or default` short-circuits hiding `None` returns from fallible calls.
 - `getattr(obj, attr, default)` masking `AttributeError` from the wrong object type.
 - argparse `default=...` for values that should fail-loud when absent.

package/docs/CODE_RULES.md

@@ -23,9 +23,9 @@ Compact reference for agents. ⚡ marks rules enforced by `code_rules_enforcer.p
 
 `code_rules_enforcer.py` blocks each of these at Write/Edit and explains the specific violation when it fires; exact patterns and exemption lists live in the hook:
 
-no new comments · imports at top · logging format args (`log_*("...", arg)`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …)
+no new comments · imports at top · logging format args (`log_*("...", arg)`) · no magic values in production bodies (0, 1, -1 exempt) · UPPER_SNAKE constants only in `config/` (exempt: `config/*`, `/migrations/`, workflow registries `/workflow/` + `_tab.py` + `/states.py` + `/modules.py`, test files) · no hardcoded user home paths · guarded `sys.path.insert` · no unused module-level imports · banned identifiers (`ctx`, `cfg`, `msg`, `btn`, `idx`, `cnt`, `tmp`, `elem`, `val`) · banned function prefixes (`handle_`, `process_`, `manage_`, `do_`) · no type escape hatches (`Any` import, `cast()`, inline `Any`) outside boundary files · no bare/broad `except` · no `Any` in signatures or class attributes · no stub bodies (`pass`/`...`/`raise NotImplementedError`) outside abstract/Protocol · TypedDict `_encode_*`/`_decode_*` companions in the same module · no test-mode branching in production (use dependency injection) · no thin wrapper modules · Google-style docstrings on public functions with `Args:` matching the signature · boolean names prefixed `is_`/`has_`/`should_`/`can_`/`was_`/`did_` (assignments AND bool-typed parameters) · must-check returns (`find_and_click`, `write_outcome`) assigned and checked · known pytest fixture parameters in test files annotated with their single documented type (`tmp_path: Path`, `monkeypatch: pytest.MonkeyPatch`, `capsys`, `caplog`, `request`, …) · known pytest fixture parameters a test function declares but never references (drop the unused parameter — pytest still pays its setup cost)
 
-Test files are exempt from most checks. The one annotation the test-file exemption does NOT cover is a known pytest builtin fixture parameter: `tmp_path`, `monkeypatch`, `capsys`, `capfd`, `caplog`, `request`, and `tmp_path_factory` each have a single documented injected type, so the gate requires that annotation (`tmp_path: Path`) even inside a test file. Ordinary test parameters stay exempt. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
+Test files are exempt from most checks. The one annotation the test-file exemption does NOT cover is a known pytest builtin fixture parameter: `tmp_path`, `monkeypatch`, `capsys`, `capfd`, `caplog`, `request`, and `tmp_path_factory` each have a single documented injected type, so the gate requires that annotation (`tmp_path: Path`) even inside a test file. The same set of fixtures is also subject to a use check: a pytest-collected test function that declares one of these parameters and never references it in its body fails the gate, because pytest materializes the fixture's setup (the temp directory, the monkeypatch context, the output capture) on every run whether or not the body reads the value — drop the unused parameter. A parameter counts as referenced when its name is read, augmented-assigned, or deleted anywhere in the body, including inside a nested function or comprehension. Only pytest-collectable functions are inspected — those at module top level or defined directly in a class body; a function nested inside another function's body is a local helper pytest never collects, so its fixture-named parameter is exempt. A `@pytest.fixture`-decorated function is exempt from the use check, since injecting one fixture into another purely to order its setup is intentional. Ordinary test parameters stay exempt from both checks. See also the file-global constants use-count rule: [`rules/file-global-constants.md`](../rules/file-global-constants.md).
 
 ---
 

package/hooks/blocking/code_rules_annotations_length.py

@@ -29,6 +29,7 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     FUNCTION_LENGTH_BLOCKING_MESSAGE_SUFFIX,
     FUNCTION_LENGTH_BLOCKING_THRESHOLD,
     KNOWN_PYTEST_FIXTURE_ANNOTATION_MESSAGE_SUFFIX,
+    UNUSED_PYTEST_FIXTURE_PARAMETER_MESSAGE_SUFFIX,
 )
 
 
@@ -55,6 +56,36 @@ def check_parameter_annotations(content: str, file_path: str) -> list[str]:
     return issues
 
 
+def _has_pytest_fixture_decorator(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    """Return True when a function carries an ``@pytest.fixture`` decorator.
+
+    The decorator is recognized whether it is written as a dotted
+    ``@pytest.fixture`` attribute or a bare ``@fixture`` name, and whether or not
+    it is called with arguments (``@pytest.fixture(scope="module")``). The call
+    form is unwrapped to its callee before the name is matched.
+
+    Args:
+        node: The function definition AST node to inspect.
+
+    Returns:
+        True when any decorator on the node is a call or bare reference whose
+        final name is ``fixture``; False otherwise.
+    """
+    for each_decorator in node.decorator_list:
+        unwrapped = (
+            each_decorator.func
+            if isinstance(each_decorator, ast.Call)
+            else each_decorator
+        )
+        if isinstance(unwrapped, ast.Name) and unwrapped.id == "fixture":
+            return True
+        if isinstance(unwrapped, ast.Attribute) and unwrapped.attr == "fixture":
+            return True
+    return False
+
+
 def _is_pytest_fixture_injection_site(
     node: ast.FunctionDef | ast.AsyncFunctionDef,
 ) -> bool:
@@ -77,13 +108,7 @@ def _is_pytest_fixture_injection_site(
     """
     if node.name.startswith("test"):
         return True
-    for each_decorator in node.decorator_list:
-        unwrapped = each_decorator.func if isinstance(each_decorator, ast.Call) else each_decorator
-        if isinstance(unwrapped, ast.Name) and unwrapped.id == "fixture":
-            return True
-        if isinstance(unwrapped, ast.Attribute) and unwrapped.attr == "fixture":
-            return True
-    return False
+    return _has_pytest_fixture_decorator(node)
 
 
 def _normalize_fixture_annotation_text(annotation_text: str) -> str:
@@ -159,6 +184,11 @@ def check_known_pytest_fixture_annotations(content: str, file_path: str) -> list
     fixture; and a ``*args`` or ``**kwargs`` parameter that happens to share a
     fixture name is never a fixture injection.
 
+    Only pytest-collectable functions are inspected: functions at module top
+    level and methods defined directly in a class body. A fixture-named
+    parameter on a function nested inside another function's body is exempt,
+    because pytest never injects a fixture into a function-nested definition.
+
     Args:
         content: The Python source to analyze.
         file_path: The path of the file being checked.
@@ -177,9 +207,7 @@ def check_known_pytest_fixture_annotations(content: str, file_path: str) -> list
     except SyntaxError:
         return []
     issues: list[str] = []
-    for each_node in ast.walk(tree):
-        if not isinstance(each_node, (ast.FunctionDef, ast.AsyncFunctionDef)):
-            continue
+    for each_node in _collect_pytest_collectable_functions(tree):
         if not _is_pytest_fixture_injection_site(each_node):
             continue
         for each_arg in _collect_fixture_injection_arguments(each_node):
@@ -205,6 +233,157 @@ def check_known_pytest_fixture_annotations(content: str, file_path: str) -> list
     return issues
 
 
+def _names_referenced_in_subtree(node: ast.AST) -> set[str]:
+    """Return every identifier referenced anywhere within an AST subtree.
+
+    A name counts as referenced when it is read (an ``ast.Name`` in load
+    context), deleted (an ``ast.Name`` in delete context), or augmented-assigned
+    (the ``ast.Name`` target of an ``ast.AugAssign``, which reads the prior value
+    before storing). The walk reaches into nested function and comprehension
+    bodies, so a parameter referenced only inside an inner function still counts.
+    A name appearing solely as a plain assignment target — ``ast.Store`` context
+    without augmentation — is absent, because rebinding the name without reading
+    it leaves the fixture's setup genuinely unused.
+
+    Args:
+        node: The AST node whose subtree is scanned for referenced identifiers.
+
+    Returns:
+        The set of identifier strings read, deleted, or augmented-assigned at
+        least once within the subtree.
+    """
+    referenced_names: set[str] = set()
+    for each_descendant in ast.walk(node):
+        if isinstance(each_descendant, ast.Name) and isinstance(
+            each_descendant.ctx, (ast.Load, ast.Del)
+        ):
+            referenced_names.add(each_descendant.id)
+        if isinstance(each_descendant, ast.AugAssign) and isinstance(
+            each_descendant.target, ast.Name
+        ):
+            referenced_names.add(each_descendant.target.id)
+    return referenced_names
+
+
+def _is_pytest_test_function(
+    node: ast.FunctionDef | ast.AsyncFunctionDef,
+) -> bool:
+    """Return True when a function is a pytest-collected test function.
+
+    A test function is one whose name begins with the ``test`` prefix, matching
+    pytest's default ``python_functions = test*`` collection rule. A
+    ``@pytest.fixture``-decorated function is deliberately excluded regardless of
+    its name: a fixture that injects another fixture only to compose its setup,
+    without reading the value, is an intentional pattern this check must not flag.
+    The decorator is recognized written as ``@pytest.fixture`` or a bare
+    ``@fixture``, with or without call arguments.
+
+    Args:
+        node: The function definition AST node to inspect.
+
+    Returns:
+        True when the node's name begins with ``test`` and the node carries no
+        ``@pytest.fixture`` decorator; False otherwise.
+    """
+    if _has_pytest_fixture_decorator(node):
+        return False
+    return node.name.startswith("test")
+
+
+def _collect_pytest_collectable_functions(
+    tree: ast.AST,
+) -> "list[ast.FunctionDef | ast.AsyncFunctionDef]":
+    """Return the function nodes pytest can collect as tests, in source order.
+
+    pytest collects a test function only at module top level or as a method
+    defined directly in a class body; a function nested inside another
+    function's body is never collected, so its parameters are ordinary local
+    arguments rather than injected fixtures. The walk descends through the
+    module body and through class bodies (including nested classes, so methods
+    of a nested class are reached), collects each ``FunctionDef`` /
+    ``AsyncFunctionDef`` it encounters, and never descends into a function's own
+    body — function-nested definitions are excluded.
+
+    Args:
+        tree: The parsed module (or any node whose body holds the candidates).
+
+    Returns:
+        Module-level and class-method function definitions in source order;
+        never a function-nested definition.
+    """
+    collectable_functions: list[ast.FunctionDef | ast.AsyncFunctionDef] = []
+    for each_statement in getattr(tree, "body", []):
+        if isinstance(each_statement, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            collectable_functions.append(each_statement)
+            continue
+        if isinstance(each_statement, ast.ClassDef):
+            collectable_functions.extend(
+                _collect_pytest_collectable_functions(each_statement)
+            )
+    return collectable_functions
+
+
+def check_unused_known_pytest_fixture_parameters(
+    content: str, file_path: str
+) -> list[str]:
+    """Flag well-known pytest fixture parameters a test declares but never reads.
+
+    A pytest test function that names a builtin fixture from
+    ``ANNOTATION_BY_PYTEST_FIXTURE`` — ``tmp_path``, ``monkeypatch``,
+    ``capsys``, and the rest — pays the fixture's setup cost on every run:
+    pytest materializes the temp directory, installs the monkeypatch context,
+    or captures output even when the body never touches the value. A parameter
+    the body never references is therefore dead weight, and most often a
+    copy-paste remnant from a sibling test that did use it. This check flags
+    each such parameter so the author drops it.
+
+    Only pytest-collected test functions are inspected: functions at module top
+    level and methods defined directly in a class body. A function nested inside
+    another function's body is excluded — pytest never collects it, so its
+    fixture-named parameter is an ordinary local argument. A
+    ``@pytest.fixture``-decorated function is exempt because injecting a fixture
+    into another fixture purely to order its setup is an intentional pattern. A
+    parameter counts as used when its name is referenced anywhere in the function
+    body — read, augmented-assigned, or deleted — including inside a nested
+    function or comprehension; an attribute access such as
+    ``monkeypatch.setenv(...)`` reads the name and so counts. Only the named
+    injection slots pytest fills — undefaulted positional-or-keyword and
+    keyword-only parameters — are considered, matching
+    ``check_known_pytest_fixture_annotations``.
+
+    Args:
+        content: The Python source to analyze.
+        file_path: The path of the file being checked.
+
+    Returns:
+        One blocking issue per known fixture parameter declared on a test
+        function whose body never references it, naming the parameter.
+    """
+    if not is_test_file(file_path):
+        return []
+    if is_workflow_registry_file(file_path) or is_migration_file(file_path):
+        return []
+    try:
+        tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    issues: list[str] = []
+    for each_node in _collect_pytest_collectable_functions(tree):
+        if not _is_pytest_test_function(each_node):
+            continue
+        referenced_names = _names_referenced_in_subtree(each_node)
+        for each_arg in _collect_fixture_injection_arguments(each_node):
+            if each_arg.arg not in ANNOTATION_BY_PYTEST_FIXTURE:
+                continue
+            if each_arg.arg in referenced_names:
+                continue
+            issues.append(
+                f"Line {each_arg.lineno}: parameter {each_arg.arg!r} on "
+                f"{each_node.name!r} - {UNUSED_PYTEST_FIXTURE_PARAMETER_MESSAGE_SUFFIX}"
+            )
+    return issues
+
+
 def check_return_annotations(content: str, file_path: str) -> list[str]:
     if is_test_file(file_path):
         return []

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,
@@ -89,6 +90,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,
@@ -281,6 +285,9 @@ def validate_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 +301,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"}
 )
@@ -83,8 +97,6 @@ OPTION_WITH_VALUE_STEP = 2
 ALL_GATED_TOOL_NAMES = ("Bash", "PowerShell")
 HASH_PREVIEW_LENGTH = 16
 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 "