claude-dev-env 1.61.0 → 1.62.0

package/hooks/blocking/test_code_rules_enforcer_dead_config_field.py

@@ -0,0 +1,432 @@
+from __future__ import annotations
+
+import importlib.util
+import os
+import shutil
+import stat
+import tempfile
+from collections.abc import Callable, Iterator
+from pathlib import Path
+
+import pytest
+
+ENFORCER_PATH = Path(__file__).resolve().parent / "code_rules_enforcer.py"
+specification = importlib.util.spec_from_file_location("code_rules_enforcer", ENFORCER_PATH)
+assert specification is not None and specification.loader is not None
+code_rules_enforcer = importlib.util.module_from_spec(specification)
+specification.loader.exec_module(code_rules_enforcer)
+
+PRODUCTION_FILE_PATH = "packages/app/services/report.py"
+TEST_FILE_PATH = "packages/app/services/test_report.py"
+MIGRATION_FILE_PATH = "packages/app/migrations/0001_initial.py"
+
+THEME_UPDATE_CONFIG_BODY = (
+    "from dataclasses import dataclass\n"
+    "\n"
+    "@dataclass\n"
+    "class ThemeUpdateConfig:\n"
+    "    portal_url: str\n"
+    "    debug_port: int\n"
+    "    timeout_seconds: int\n"
+)
+
+
+def _strip_read_only_and_retry(
+    removal_function: Callable[[str], object],
+    target_path: str,
+    _exc_info: BaseException,
+) -> None:
+    try:
+        os.chmod(target_path, stat.S_IWRITE)
+        removal_function(target_path)
+    except OSError:
+        pass
+
+
+@pytest.fixture
+def neutral_root() -> Iterator[Path]:
+    """Yield a temp directory whose path carries no ``test_`` segment.
+
+    The enforcer's ``is_test_file`` keys on the full path string, and pytest's
+    own ``tmp_path`` directory name embeds the test name, which would make every
+    synthetic config path look like a test file. A neutral ``mkdtemp`` root
+    mirrors how a production config module path looks.
+    """
+    neutral_directory = Path(tempfile.mkdtemp(prefix="deadcfg-")).resolve()
+    try:
+        yield neutral_directory
+    finally:
+        shutil.rmtree(neutral_directory, onexc=_strip_read_only_and_retry)
+
+
+def _check(source: str, file_path: str) -> list[str]:
+    return code_rules_enforcer.check_dead_config_dataclass_fields(source, file_path)
+
+
+def _build_config_package(
+    workflow_directory: Path,
+    config_body: str,
+    consumer_body: str,
+) -> Path:
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(config_body, encoding="utf-8")
+    (workflow_directory / "runner.py").write_text(consumer_body, encoding="utf-8")
+    return config_path
+
+
+def test_flags_config_field_read_by_no_production_module(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def run(configuration: ThemeUpdateConfig) -> None:\n"
+        "    print(configuration.portal_url)\n"
+        "    print(configuration.timeout_seconds)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Expected dead 'debug_port' flagged, got: {issues}"
+    )
+    assert not any(
+        "'portal_url'" in each_issue or "'timeout_seconds'" in each_issue for each_issue in issues
+    ), f"Fields read in consumer must not be flagged, got: {issues}"
+
+
+def test_does_not_flag_field_read_as_attribute_in_sibling_module(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def run(configuration: ThemeUpdateConfig) -> None:\n"
+        "    print(configuration.portal_url)\n"
+        "    print(configuration.debug_port)\n"
+        "    print(configuration.timeout_seconds)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], f"All fields are read in consumer, none must be flagged, got: {issues}"
+
+
+def test_flags_field_read_only_by_test_module(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(THEME_UPDATE_CONFIG_BODY, encoding="utf-8")
+    test_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def test_debug_port_default() -> None:\n"
+        "    cfg = ThemeUpdateConfig(portal_url='x', debug_port=9222, timeout_seconds=30)\n"
+        "    assert cfg.debug_port == 9222\n"
+        "    assert cfg.portal_url == 'x'\n"
+        "    assert cfg.timeout_seconds == 30\n"
+    )
+    (workflow_directory / "test_config.py").write_text(test_body, encoding="utf-8")
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Field read only by test code must still be flagged as dead-in-production, got: {issues}"
+    )
+
+
+def test_ignores_non_config_named_dataclass(neutral_root: Path) -> None:
+    source = (
+        "from dataclasses import dataclass\n"
+        "\n"
+        "@dataclass\n"
+        "class ThemeMetadata:\n"
+        "    title: str\n"
+        "    debug_port: int\n"
+    )
+    workflow_directory = neutral_root / "workflow"
+    workflow_directory.mkdir(parents=True)
+    module_path = workflow_directory / "metadata.py"
+    module_path.write_text(source, encoding="utf-8")
+    issues = _check(source, str(module_path))
+    assert issues == [], (
+        f"Non-Config-named dataclasses are outside scope of this check, got: {issues}"
+    )
+
+
+def test_does_not_flag_field_read_via_string_literal(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def read_field(configuration: ThemeUpdateConfig, field_name: str) -> object:\n"
+        "    return getattr(configuration, 'debug_port')\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert not any("'debug_port'" in each_issue for each_issue in issues), (
+        f"String literal getattr read must count as a field read, got: {issues}"
+    )
+
+
+def test_does_not_flag_when_consumer_serializes_whole_instance_via_asdict(
+    neutral_root: Path,
+) -> None:
+    consumer_body = (
+        "from dataclasses import asdict\n"
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def serialize(configuration: ThemeUpdateConfig) -> dict[str, object]:\n"
+        "    return asdict(configuration)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], (
+        f"asdict reads every field at once, so no field may be flagged, got: {issues}"
+    )
+
+
+def test_does_not_flag_when_consumer_reads_instance_dict(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def serialize(configuration: ThemeUpdateConfig) -> dict[str, object]:\n"
+        "    return dict(configuration.__dict__)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], (
+        f"__dict__ read consumes every field at once, so none may be flagged, got: {issues}"
+    )
+
+
+def test_does_not_flag_field_used_only_as_replace_keyword(neutral_root: Path) -> None:
+    consumer_body = (
+        "from dataclasses import replace\n"
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def repoint(configuration: ThemeUpdateConfig) -> ThemeUpdateConfig:\n"
+        "    return replace(configuration, debug_port=9999)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert not any("'debug_port'" in each_issue for each_issue in issues), (
+        f"replace keyword usage of debug_port must count as a read, got: {issues}"
+    )
+
+
+def test_does_not_flag_field_used_only_as_constructor_keyword(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def build() -> ThemeUpdateConfig:\n"
+        "    return ThemeUpdateConfig(portal_url='x', debug_port=1, timeout_seconds=99)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], (
+        f"Constructor keyword arguments name every field, so none may be flagged, got: {issues}"
+    )
+
+
+def test_returns_empty_list_at_file_cap(
+    neutral_root: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr("code_rules_dead_config_field.MAX_SCAN_ROOT_FILE_COUNT", 0)
+    config_path = _build_config_package(
+        neutral_root / "workflow",
+        THEME_UPDATE_CONFIG_BODY,
+        "def noop() -> None:\n    pass\n",
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], f"File cap hit must return [] (cannot prove dead), got: {issues}"
+
+
+def test_returns_empty_list_on_syntax_error(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    workflow_directory.mkdir(parents=True)
+    broken_path = workflow_directory / "config.py"
+    broken_source = "@dataclass\nclass BrokenConfig(\n"
+    broken_path.write_text(broken_source, encoding="utf-8")
+    issues = _check(broken_source, str(broken_path))
+    assert issues == [], f"SyntaxError must return [], got: {issues}"
+
+
+def test_is_skipped_on_test_file_destination() -> None:
+    issues = _check(THEME_UPDATE_CONFIG_BODY, TEST_FILE_PATH)
+    assert issues == [], f"Test file destinations are exempt, got: {issues}"
+
+
+def test_is_skipped_on_migration_file_destination() -> None:
+    issues = _check(THEME_UPDATE_CONFIG_BODY, MIGRATION_FILE_PATH)
+    assert issues == [], f"Migration file destinations are exempt, got: {issues}"
+
+
+def test_real_world_shape_theme_update_config_with_dead_debug_port(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(THEME_UPDATE_CONFIG_BODY, encoding="utf-8")
+    orchestrator_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def build_session(configuration: ThemeUpdateConfig) -> None:\n"
+        "    url = configuration.portal_url\n"
+        "    seconds = configuration.timeout_seconds\n"
+        "    print(url, seconds)\n"
+    )
+    (workflow_directory / "orchestrator.py").write_text(orchestrator_body, encoding="utf-8")
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"debug_port field unused in production must be flagged, got: {issues}"
+    )
+    assert not any(
+        "'portal_url'" in each_issue or "'timeout_seconds'" in each_issue for each_issue in issues
+    ), f"Fields read in orchestrator must not be flagged, got: {issues}"
+
+
+def test_does_not_flag_field_used_only_via_augmented_assignment(neutral_root: Path) -> None:
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def run(configuration: ThemeUpdateConfig) -> None:\n"
+        "    print(configuration.portal_url)\n"
+        "    print(configuration.timeout_seconds)\n"
+        "    configuration.debug_port += 1\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert not any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Augmented assignment reads debug_port before writing, so it is not dead, got: {issues}"
+    )
+
+
+def test_flags_field_read_only_via_whole_instance_comparison(neutral_root: Path) -> None:
+    """A field read ONLY via whole-instance comparison IS flagged (accepted limitation).
+
+    Unlike the per-file dead-dataclass-field check, this cross-module check does
+    not suppress on a dataclass-dunder whole-instance read: instance comparison
+    (``left == right``) is not bound to a config instance, and tree-wide one
+    incidental ``==`` anywhere would disable the check on any realistic package.
+    A ``*Config`` field whose only production read is this whole-instance
+    comparison, and that is never read directly, is therefore flagged — a
+    documented, rare limitation.
+    """
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def is_same(left: ThemeUpdateConfig, right: ThemeUpdateConfig) -> bool:\n"
+        "    return left == right\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Field read only via whole-instance comparison is flagged, got: {issues}"
+    )
+
+
+def test_flags_field_read_only_via_whole_instance_stringification(neutral_root: Path) -> None:
+    """A field read ONLY via whole-instance stringification IS flagged (accepted limitation).
+
+    The cross-module check does not suppress on a formatted-string conversion of
+    a whole instance (``f'{configuration}'``): the f-string is not bound to a
+    config instance, and tree-wide one incidental f-string anywhere would disable
+    the check on any realistic package. A ``*Config`` field whose only production
+    read is this whole-instance stringification, and that is never read directly,
+    is therefore flagged — a documented, rare limitation.
+    """
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def describe(configuration: ThemeUpdateConfig) -> str:\n"
+        "    return f'{configuration}'\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Field read only via whole-instance stringification is flagged, got: {issues}"
+    )
+
+
+def test_unrelated_string_method_does_not_suppress_so_dead_field_flagged(
+    neutral_root: Path,
+) -> None:
+    """An unrelated ``.replace(...)`` on a string must not suppress the tree.
+
+    ``"some text".replace("a", "b")`` is a string method, not a ``dataclasses``-
+    qualified reflective consumer, so it does not make the check treat the tree
+    as a whole-instance read. A genuinely dead ``debug_port`` is still flagged.
+    """
+    consumer_body = (
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def run(configuration: ThemeUpdateConfig) -> str:\n"
+        "    print(configuration.portal_url)\n"
+        "    print(configuration.timeout_seconds)\n"
+        "    return 'some text'.replace('a', 'b')\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Unrelated string .replace must not suppress, so dead debug_port is flagged, got: {issues}"
+    )
+
+
+def test_dataclasses_qualified_replace_call_suppresses_so_no_field_flagged(
+    neutral_root: Path,
+) -> None:
+    """A ``dataclasses.replace(cfg, ...)`` call suppresses the whole tree.
+
+    A genuine ``dataclasses``-qualified reflective consumer reads every field at
+    once, so the check is suppressed for the whole tree and no field is flagged.
+    """
+    consumer_body = (
+        "import dataclasses\n"
+        "from os_update_workflow.config import ThemeUpdateConfig\n"
+        "\n"
+        "def repoint(configuration: ThemeUpdateConfig) -> ThemeUpdateConfig:\n"
+        "    return dataclasses.replace(configuration, debug_port=9999)\n"
+    )
+    config_path = _build_config_package(
+        neutral_root / "workflow", THEME_UPDATE_CONFIG_BODY, consumer_body
+    )
+    issues = _check(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert issues == [], (
+        f"dataclasses.replace reads every field at once, so none may be flagged, got: {issues}"
+    )
+
+
+def test_validate_content_dispatch_runs_dead_config_field_check(neutral_root: Path) -> None:
+    workflow_directory = neutral_root / "workflow"
+    config_package = workflow_directory / "os_update_workflow"
+    config_package.mkdir(parents=True)
+    (config_package / "__init__.py").write_text("", encoding="utf-8")
+    config_path = config_package / "config.py"
+    config_path.write_text(THEME_UPDATE_CONFIG_BODY, encoding="utf-8")
+    (workflow_directory / "runner.py").write_text(
+        "def noop() -> None:\n    pass\n", encoding="utf-8"
+    )
+    issues = code_rules_enforcer.validate_content(THEME_UPDATE_CONFIG_BODY, str(config_path))
+    assert any("'debug_port'" in each_issue for each_issue in issues), (
+        f"Expected the enforcer dispatch to surface the dead config field, got: {issues}"
+    )

package/hooks/blocking/test_verified_commit_gate.py

@@ -6,6 +6,7 @@ decide what to gate.
 """
 
 import importlib.util
+import io
 import json
 import os
 import pathlib
@@ -28,6 +29,7 @@ gate_module = importlib.util.module_from_spec(gate_spec)
 gate_spec.loader.exec_module(gate_module)
 gated_repo_directories = gate_module.gated_repo_directories
 deny_reason_for_directory = gate_module.deny_reason_for_directory
+gate_main = gate_module.main
 
 store_spec = importlib.util.spec_from_file_location(
     "verification_verdict_store",
@@ -493,3 +495,33 @@ def test_no_verdict_of_either_kind_denies_the_commit(
     deny_reason = deny_reason_for_directory(str(work_dir), str(transcript_path))
     assert deny_reason is not None
     assert "VERIFIED_COMMIT_GATE" in deny_reason
+
+
+def _run_gate_main(
+    monkeypatch: pytest.MonkeyPatch, command_text: str, work_dir: pathlib.Path
+) -> None:
+    payload_text = json.dumps(
+        {
+            "tool_name": "Bash",
+            "tool_input": {"command": command_text},
+            "cwd": str(work_dir),
+            "transcript_path": "",
+        }
+    )
+    monkeypatch.setattr(sys, "stdin", io.StringIO(payload_text))
+    gate_main()
+
+
+def test_verification_bypass_marker_allows_an_otherwise_gated_commit(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tmp_path: pathlib.Path,
+) -> None:
+    fake_home = tmp_path / "home"
+    fake_home.mkdir()
+    _isolate_home(monkeypatch, fake_home)
+    work_dir = _make_gated_repo(tmp_path)
+    _run_gate_main(monkeypatch, "git commit -m x", work_dir)
+    assert "VERIFIED_COMMIT_GATE" in capsys.readouterr().out
+    _run_gate_main(monkeypatch, "git commit -m x # verify-skip", work_dir)
+    assert capsys.readouterr().out == ""

package/hooks/blocking/verified_commit_gate.py

@@ -5,6 +5,8 @@ Fires on Bash and PowerShell tool calls. When the command carries a
 targets, computes the live change-surface manifest against the merge base,
 and allows the command only when one of these holds:
 
+- the command carries the verification bypass marker (``# verify-skip``),
+  a manual on-the-fly override that skips the gate for that one command,
 - the repository has no resolvable upstream base — no ``origin/HEAD``, no
   configured tracking ref, and neither ``origin/main`` nor ``origin/master``
   (scratch repos with no remote branch are out of scope),
@@ -47,6 +49,7 @@ from config.verified_commit_constants import (
     OPTION_WITH_VALUE_STEP,
     REPO_DIRECTORY_OPTION,
     VALUE_TAKING_GIT_OPTIONS,
+    VERIFICATION_BYPASS_MARKER,
     WORK_TREE_OPTION,
 )
 from verification_verdict_store import (
@@ -504,7 +507,12 @@ def deny_reason_for_directory(target_directory: str, transcript_path: str) -> st
 
 
 def main() -> None:
-    """Read the PreToolUse payload and deny unverified commit/push commands."""
+    """Read the PreToolUse payload and decide whether to allow the command.
+
+    Allows the command without a verdict when it carries the verification
+    bypass marker (``VERIFICATION_BYPASS_MARKER``), a manual on-the-fly
+    override; otherwise denies an unverified commit or push.
+    """
     try:
         pretooluse_payload = json.load(sys.stdin)
     except json.JSONDecodeError:
@@ -514,6 +522,8 @@ def main() -> None:
     command_text = pretooluse_payload.get("tool_input", {}).get("command", "")
     if not command_text:
         return
+    if VERIFICATION_BYPASS_MARKER in command_text:
+        return
     session_directory = pretooluse_payload.get("cwd", ".")
     transcript_path = pretooluse_payload.get("transcript_path", "")
     for each_target_directory in gated_repo_directories(command_text, session_directory):

package/hooks/hooks_constants/dead_config_field_constants.py

@@ -0,0 +1,39 @@
+"""Constants for the dead config-dataclass field detector in ``code_rules_enforcer``.
+
+Lives under the hooks-tree ``hooks_constants`` package so module-level
+UPPER_SNAKE constants satisfy the CODE_RULES "constants live in config"
+requirement and share a home with the other hook-tree configuration.
+"""
+
+from hooks_constants.dead_dataclass_field_constants import (
+    ALL_REFLECTIVE_FIELD_CONSUMER_NAMES,
+    WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME,
+)
+from hooks_constants.dead_module_constant_constants import (
+    CONFIG_DIRECTORY_SEGMENT,
+    DUNDER_INIT_FILENAME,
+    MAX_SCAN_ROOT_FILE_COUNT,
+    PYTHON_SOURCE_SUFFIX,
+)
+
+CONFIG_CLASS_NAME_SUFFIX: str = "Config"
+DATACLASSES_MODULE_NAME: str = "dataclasses"
+MAX_DEAD_CONFIG_FIELD_ISSUES: int = 25
+DEAD_CONFIG_FIELD_GUIDANCE: str = (
+    "config dataclass field is defined but read by no production module in the"
+    " enclosing package tree - remove the dead field, or read it where the value"
+    " is needed (CODE_RULES §9.8)"
+)
+
+__all__ = [
+    "ALL_REFLECTIVE_FIELD_CONSUMER_NAMES",
+    "CONFIG_CLASS_NAME_SUFFIX",
+    "CONFIG_DIRECTORY_SEGMENT",
+    "DATACLASSES_MODULE_NAME",
+    "DEAD_CONFIG_FIELD_GUIDANCE",
+    "DUNDER_INIT_FILENAME",
+    "MAX_DEAD_CONFIG_FIELD_ISSUES",
+    "MAX_SCAN_ROOT_FILE_COUNT",
+    "PYTHON_SOURCE_SUFFIX",
+    "WHOLE_INSTANCE_DICT_ATTRIBUTE_NAME",
+]

package/package.json

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

package/skills/autoconverge/reference/gotchas.md

@@ -45,3 +45,14 @@ fails in a new way.
 - **`gh` token drift across accounts.** When a run touches more than one GitHub
   account, pin the token with `--user <login>`; `gh auth token` alone can return
   another account's token after a switch.
+
+- **The verified-commit gate can block the fix from landing.** The fix lens
+  commits and pushes through the `verified_commit_gate` hook, which denies a
+  `git commit`/`git push` until a `code-verifier` verdict covers the branch
+  surface. A run can reach a clean fix yet fail to land it — the push stays
+  blocked when no verdict is minted for that surface. A manual override exists:
+  a trailing `# verify-skip` comment on the commit or push command skips the
+  gate for that one command. Autoconverge must never apply that override on its
+  own. When landing a fix needs it, stop and tell the user the verified-commit
+  gate is blocking the push and that going forward needs either a `# verify-skip`
+  bypass or a switch to `/pr-converge`, then let the user decide.

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

@@ -215,6 +215,11 @@ HTML_STYLE_BLOCK = """\
   .cause { background:#fff; border:1px solid #e2e8f0; border-radius:10px; padding:14px 18px; margin-top:16px; font-size:14px; color:#475569; }
   .cause b { color:#0f172a; }
 
+  .appendix { background:#fff; border:1px solid #e2e8f0; border-radius:10px; padding:14px 18px; margin-top:16px; font-size:13px; color:#475569; }
+  .appendix summary { font-weight:600; color:#0f172a; cursor:pointer; }
+  .appendix-body { margin-top:10px; }
+  .appendix-item { font-family:'JetBrains Mono',monospace; font-size:12px; color:#475569; padding:5px 0; border-top:1px solid #f1f5f9; }
+
   footer { margin-top:40px; padding-top:16px; border-top:1px solid #e2e8f0; color:#94a3b8; font-size:12px; }
   footer code { background:#e2e8f0; padding:1px 6px; border-radius:4px; font-family:'JetBrains Mono',monospace; }
   @media (max-width:680px){ .pf-grid,.term-grid{grid-template-columns:1fr;} }

package/skills/autoconverge/workflow/test_render_report.py

@@ -43,6 +43,31 @@ def _render_cli(journal_path: Path, out_path: Path) -> subprocess.CompletedProce
     )
 
 
+def test_rendered_report_defines_every_referenced_css_class(tmp_path: Path) -> None:
+    """Every class the rendered report markup references resolves to a CSS selector.
+
+    Renders the report from the findings fixture so the raw-findings appendix is
+    present, then asserts no class attribute names a style the stylesheet omits,
+    keeping the report markup and HTML_STYLE_BLOCK from drifting apart.
+    """
+    out_path = tmp_path / "report.html"
+    completed = _render_cli(FIXTURE_JOURNAL, out_path)
+    assert completed.returncode == 0, f"CLI failed:\n{completed.stderr}"
+    html_content = out_path.read_text(encoding="utf-8")
+
+    style_match = re.search(r"<style>(.*?)</style>", html_content, re.DOTALL)
+    assert style_match is not None
+    defined_classes = set(re.findall(r"\.([A-Za-z][\w-]*)", style_match.group(1)))
+    referenced_classes = {
+        each_name
+        for attribute_value in re.findall(r'class="([^"]*)"', html_content)
+        for each_name in attribute_value.split()
+    }
+
+    orphan_classes = referenced_classes - defined_classes
+    assert not orphan_classes, f"classes referenced but undefined: {sorted(orphan_classes)}"
+
+
 def _copy_run_tree_without_summary_entry(destination_root: Path) -> Path:
     """Copy the fixture run tree, dropping the convergence-summary workflowProgress entry.
 

package/skills/doc-gist/SKILL.md

@@ -58,7 +58,7 @@ Reads HTML from `--input <path>` or stdin (`--input -`), runs `gh gist create`,
 
 ## Designing fresh — the example gallery
 
-The skill ships [`references/examples/`](references/examples/) with all 20 of Thariq's html-effectiveness prototypes verbatim from [thariqs.github.io/html-effectiveness](https://thariqs.github.io/html-effectiveness/). They are *examples to learn from, not templates to fill.*
+The skill ships [`references/examples/`](references/examples/) with 21 html-effectiveness examples: Thariq's 20 prototypes verbatim from [thariqs.github.io/html-effectiveness](https://thariqs.github.io/html-effectiveness/) (`01`–`20`), plus one original addition (`21-decision-signoff.html`). They are *examples to learn from, not templates to fill.*
 
 When the user requests an artifact, decide the shape that fits. Use the gallery for grounding:
 
@@ -84,6 +84,7 @@ When the user requests an artifact, decide the shape that fits. Use the gallery
 | Triage / kanban board (drag-drop) | `18-editor-triage-board.html` |
 | Feature flag toggles with deps | `19-editor-feature-flags.html` |
 | Live-updating template editor | `20-editor-prompt-tuner.html` |
+| Decision / sign-off doc (accept-or-change each call, export digest) | `21-decision-signoff.html` |
 
 Read the matching example for the artifact you're designing. Crib palette, typography, spatial idioms, component patterns. **Adapt — do not copy.** A PR writeup for a hooks PR shouldn't look identical to one for a notification-queue PR. The gallery teaches what shapes work; the request decides which shape fits.
 
@@ -92,5 +93,5 @@ Read the matching example for the artifact you're designing. Crib palette, typog
 - `SKILL.md` — this file.
 - `skills/doc-gist/scripts/gist_upload.py` — transport: HTML in, gist + preview URLs out.
 - `skills/doc-gist/scripts/doc_gist_scripts_constants/gist_upload_constants.py` — the URL prefixes and template strings.
-- `references/examples/` — Thariq's 20 html-effectiveness prototypes.
+- `references/examples/` — Thariq's 20 html-effectiveness prototypes (`01`–`20`) plus one original addition (`21-decision-signoff.html`).
 - (PostToolUse hook lives in `packages/claude-dev-env/hooks/workflow/doc_gist_auto_publish.py` — wired into the plugin's `hooks.json`.)