claude-dev-env 1.82.0 → 1.84.0

package/bin/install.test.mjs

@@ -718,12 +718,13 @@ const OLD_FOLDED_HOOKS_SETTINGS = {
 };
 
 
-test('FOLDED_HOOK_RELATIVE_PATHS contains all 16 hooks removed from hooks.json', () => {
-    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 16);
+test('FOLDED_HOOK_RELATIVE_PATHS contains all 16 hooks removed from hooks.json plus the retired md_to_html_blocker', () => {
+    assert.equal(FOLDED_HOOK_RELATIVE_PATHS.size, 17);
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/write_existing_file_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/plain_language_blocker.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/code_rules_enforcer.py'));
     assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/pytest_testpaths_orphan_blocker.py'));
+    assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has('blocking/md_to_html_blocker.py'));
 });
 
 
@@ -746,16 +747,25 @@ test('FOLDED_HOOK_RELATIVE_PATHS lists every hook the PreToolUse dispatcher host
         'blocking/open_questions_in_plans_blocker.py',
         'blocking/plain_language_blocker.py',
     ];
+    const retiredHooks = [
+        'blocking/md_to_html_blocker.py',
+    ];
     for (const hostedPath of dispatcherHostedHooks) {
         assert.ok(
             FOLDED_HOOK_RELATIVE_PATHS.has(hostedPath),
             `dispatcher-hosted hook ${hostedPath} must be in FOLDED_HOOK_RELATIVE_PATHS so a reinstall prunes its stale standalone entry and it does not double-run`
         );
     }
+    for (const retiredPath of retiredHooks) {
+        assert.ok(
+            FOLDED_HOOK_RELATIVE_PATHS.has(retiredPath),
+            `retired hook ${retiredPath} must be in FOLDED_HOOK_RELATIVE_PATHS so a reinstall prunes its stale standalone entry pointing at a script no longer on disk`
+        );
+    }
     assert.equal(
         FOLDED_HOOK_RELATIVE_PATHS.size,
-        dispatcherHostedHooks.length,
-        'FOLDED_HOOK_RELATIVE_PATHS must hold exactly the dispatcher-hosted hooks, no more, no fewer'
+        dispatcherHostedHooks.length + retiredHooks.length,
+        'FOLDED_HOOK_RELATIVE_PATHS must hold exactly the dispatcher-hosted hooks plus the retired hooks, no more, no fewer'
     );
 });
 
@@ -887,11 +897,12 @@ const OLD_POST_FOLDED_HOOKS_SETTINGS = {
 };
 
 
-test('POST_FOLDED_HOOK_RELATIVE_PATHS contains the three after-write hooks folded into the PostToolUse dispatcher', () => {
-    assert.equal(POST_FOLDED_HOOK_RELATIVE_PATHS.size, 3);
+test('POST_FOLDED_HOOK_RELATIVE_PATHS contains the after-write hooks and the retired md_to_html_companion', () => {
+    assert.equal(POST_FOLDED_HOOK_RELATIVE_PATHS.size, 4);
     assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('validation/mypy_validator.py'));
     assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/auto_formatter.py'));
     assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/doc_gist_auto_publish.py'));
+    assert.ok(POST_FOLDED_HOOK_RELATIVE_PATHS.has('workflow/md_to_html_companion.py'));
 });
 
 

package/commands/CLAUDE.md

@@ -7,7 +7,6 @@ Slash-command definitions installed into `~/.claude/commands/` by `bin/install.m
 | File | Command | What it does |
 |---|---|---|
 | `commit.md` | `/commit` | Commits and pushes changes to GitHub |
-| `doc-gist.md` | `/doc-gist` | Uploads an HTML file as a secret gist and opens the htmlpreview URL |
 | `docupdate.md` | `/docupdate` | Updates documentation to match current code state |
 | `hook-log-extract.md` | `/hook-log-extract` | Extracts and formats hook log entries for a session |
 | `hook-log-init.md` | `/hook-log-init` | Initializes the Neon Postgres schema that backs the hook-log extractor (one-time per machine) |

package/docs/CODE_RULES.md

@@ -94,4 +94,4 @@ If you already have the data, don't fetch it again.
 
 ## 11. ENFORCEMENT SURFACES
 
-⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit.
+⚡ **Hooks** block pattern-matchable violations at Write/Edit time. 🤖 **Prompt context** carries judgment principles (SRP, Right-Sized Engineering, conservative-action, BDD discovery, docstring-prose-matches-implementation; the `/code` skill prepends strict mode for a session: no `Any`/`cast()`, immutable TypedDicts with `_encode_*`/`_decode_*` + `require_*` validation, per-module `_test_hooks.py` DI, 100% statement + branch coverage, zero mocks). 👥 **Audit rubrics** (`/check`, `packages/claude-dev-env/audit-rubrics/` categories A–Q) cover cross-file architectural concerns. Rules with documented-but-pending hook coverage live in `~/.claude/rules/*.md` and `skills/code/SKILL.md`; each names its own promotion path. The docstring-prose standard (free-form enumerations match the body) lives in `packages/claude-dev-env/rules/docstring-prose-matches-implementation.md`, enforced via Category O6 audit. The diagram-first docstring standard (a summary line, then a `::` example or doctest, then a couple of short prose lines) lives in `packages/claude-dev-env/rules/plain-illustrative-docstrings.md`, enforced by the `check_docstring_runon_sentence` and `check_docstring_prose_wall_without_illustration` backstop hooks and Category O9 audit.

package/hooks/blocking/CLAUDE.md

@@ -77,7 +77,6 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`) |
 | `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on |
 | `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work |
-| `md_to_html_blocker.py` | PreToolUse (Write/Edit) | Writing `.md` files when an `.html` companion is required |
 | `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
 | `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
 | `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
@@ -86,9 +85,11 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `precommit_code_rules_gate.py` | PreToolUse (Bash) | Staged changes that fail the CODE_RULES gate at commit time |
 | `pytest_testpaths_orphan_blocker.py` | PreToolUse (Write/Edit/MultiEdit) | New `test_*.py` files created under a directory absent from a package's explicit pytest `testpaths` allowlist |
 | `question_to_user_enforcer.py` | Stop | User-directed questions not routed through `AskUserQuestion` |
+| `reviewer_spawn_gate.py` | PreToolUse (Bash) | A sentinel-marked autoconverge reviewer-spawn command (Copilot review request, Bugbot rerun comment) run while `reviewer_availability.py` reports that reviewer down or out of quota |
 | `send_user_file_open_locally_blocker.py` | PreToolUse (SendUserFile) | A desk-side file attach (`SendUserFile` with `status` not `proactive`); points to opening the file locally via `Show-Asset.ps1` |
 | `sensitive_file_protector.py` | PreToolUse (Write/Edit) | Writes to sensitive credential or config files |
 | `session_handoff_blocker.py` | Stop | Responses suggesting a new session mid-task |
+| `stale_comment_reference_blocker.py` | PreToolUse (Edit) | An Edit that rewrites a Python code line while keeping the standalone comment directly above it, when that comment names an identifier the rewrite removes from the line |
 | `state_description_blocker.py` | PreToolUse (Write/Edit) | Historical/comparative language in documentation |
 | `subprocess_budget_completeness.py` | PreToolUse | Subprocess calls missing required budget arguments |
 | `tdd_enforcer.py` | PreToolUse (Write/Edit) | Production code written without a matching failing test |
@@ -105,8 +106,6 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | File | Role |
 |---|---|
 | `_gh_body_arg_utils.py` | Parsing helpers for `gh_body_arg_blocker.py` |
-| `_md_to_html_blocker_test_support.py` | Test fixtures shared across `md_to_html_blocker` tests |
-| `md_path_exemptions.py` | Path exemption logic for `md_to_html_blocker.py` |
 | `pr_description_body_audit.py` | Body audit logic for `pr_description_enforcer.py` |
 | `pr_description_command_parser.py` | `gh` command parsing for `pr_description_enforcer.py` |
 | `pr_description_pr_number.py` | PR number extraction logic |
@@ -117,4 +116,3 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 
 - Tests live beside each hook as `test_<hookname>.py` or `test_<hookname>_<suffix>.py`. Run with `python -m pytest <test_file>`.
 - Tunable constants live in `hooks_constants/<hook_name>_constants.py`; the verified-commit family uses `blocking/config/verified_commit_constants.py`.
-- `conftest.py` gives shared pytest fixtures for the blocking test suite.

package/hooks/blocking/code_rules_constants_config.py

@@ -1,4 +1,9 @@
-"""Constants-outside-config checks and the file-global constant use-count check."""
+"""Constants-outside-config checks and the file-global constant use-count check.
+
+Also carries check_config_duplicate_path_anchor, which flags a config module
+that rebuilds a directory a sibling module in the same package already
+anchors from its own location.
+"""
 
 import ast
 import re
@@ -18,12 +23,16 @@ from code_rules_path_utils import (  # noqa: E402
 )
 from code_rules_shared import (  # noqa: E402
     _build_parent_map,
+    docstring_line_numbers,
     get_file_extension,
     is_migration_file,
     is_test_file,
     is_workflow_registry_file,
 )
 
+from hooks_constants.blocking_check_limits import (  # noqa: E402
+    MAX_CONFIG_DUPLICATE_PATH_ANCHOR_ISSUES,
+)
 from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     ALL_PYTHON_EXTENSIONS,
     FILE_GLOBAL_UPPER_SNAKE_PATTERN,
@@ -102,6 +111,7 @@ def _scan_function_body_constants(content: str) -> list[str]:
     """
     advisory_issues: list[str] = []
     lines = content.split("\n")
+    all_docstring_line_numbers = docstring_line_numbers(content)
     function_indent_stack: list[int] = []
     constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})(?:\s*:\s*[^=]+)?\s*=\s*[^=]")
 
@@ -111,6 +121,9 @@ def _scan_function_body_constants(content: str) -> list[str]:
         if not stripped:
             continue
 
+        if each_line_number in all_docstring_line_numbers:
+            continue
+
         indent = len(each_line) - len(each_line.lstrip())
 
         while function_indent_stack and indent <= function_indent_stack[-1] and not stripped.startswith(("#", "@", ")")):
@@ -253,3 +266,153 @@ def check_file_global_constants_use_count(content: str, file_path: str) -> list[
             )
 
     return issues
+
+
+def _references_dunder_file(node: ast.AST) -> bool:
+    """Return True when the expression tree reads ``__file__``."""
+    return any(
+        isinstance(each_node, ast.Name) and each_node.id == "__file__"
+        for each_node in ast.walk(node)
+    )
+
+
+def _file_anchor_up_count(node: ast.AST) -> Optional[int]:
+    """Return how many directory levels a ``__file__`` anchor climbs, else None.
+
+    A ``parents[N]`` subscript on a ``__file__``-rooted expression climbs
+    ``N + 1`` levels; a chain of ``.parent`` attributes climbs one level per
+    link. Any other expression returns None.
+    """
+    if isinstance(node, ast.Subscript):
+        subscripted = node.value
+        if (
+            isinstance(subscripted, ast.Attribute)
+            and subscripted.attr == "parents"
+            and isinstance(node.slice, ast.Constant)
+            and isinstance(node.slice.value, int)
+            and _references_dunder_file(subscripted.value)
+        ):
+            return node.slice.value + 1
+    parent_step_count = 0
+    current_node = node
+    while isinstance(current_node, ast.Attribute) and current_node.attr == "parent":
+        parent_step_count += 1
+        current_node = current_node.value
+    if parent_step_count and _references_dunder_file(current_node):
+        return parent_step_count
+    return None
+
+
+def _anchored_join_signature(node: ast.AST) -> Optional[tuple[int, str]]:
+    """Return (up_count, first literal segment) for an anchored ``/`` join, else None.
+
+    Flattens a left-leaning ``/`` chain, requires the left-most operand to be
+    a ``__file__`` anchor, and requires the first joined segment to be a
+    string literal.
+    """
+    if not isinstance(node, ast.BinOp) or not isinstance(node.op, ast.Div):
+        return None
+    all_segments: list[str] = []
+    current_node: ast.expr = node
+    while isinstance(current_node, ast.BinOp) and isinstance(current_node.op, ast.Div):
+        right_operand = current_node.right
+        if isinstance(right_operand, ast.Constant) and isinstance(right_operand.value, str):
+            all_segments.insert(0, right_operand.value)
+        else:
+            all_segments.insert(0, "")
+        current_node = current_node.left
+    anchor_up_count = _file_anchor_up_count(current_node)
+    if anchor_up_count is None or not all_segments or not all_segments[0]:
+        return None
+    return anchor_up_count, all_segments[0]
+
+
+def _module_anchor_signatures(module_tree: ast.Module) -> dict[tuple[int, str], int]:
+    """Return line numbers keyed by anchored-join signature for top-level assignments."""
+    signatures_by_key: dict[tuple[int, str], int] = {}
+    for each_statement in module_tree.body:
+        if isinstance(each_statement, ast.Assign):
+            assigned_expression = each_statement.value
+        elif isinstance(each_statement, ast.AnnAssign) and each_statement.value is not None:
+            assigned_expression = each_statement.value
+        else:
+            continue
+        for each_node in ast.walk(assigned_expression):
+            signature = _anchored_join_signature(each_node)
+            if signature is not None:
+                signatures_by_key.setdefault(signature, each_statement.lineno)
+    return signatures_by_key
+
+
+def _config_anchor_check_applies(file_path: str) -> bool:
+    """Return whether the duplicate-path-anchor check should inspect this file."""
+    return (
+        is_config_file(file_path)
+        and not is_test_file(file_path)
+        and get_file_extension(file_path) in ALL_PYTHON_EXTENSIONS
+    )
+
+
+def _sibling_anchor_owner_names(config_directory: Path, written_name: str) -> dict[tuple[int, str], str]:
+    """Return the sibling config module name that first builds each anchor signature."""
+    owner_name_by_signature: dict[tuple[int, str], str] = {}
+    for each_sibling_path in sorted(config_directory.glob("*.py")):
+        if each_sibling_path.name == written_name or is_test_file(str(each_sibling_path)):
+            continue
+        try:
+            sibling_tree = ast.parse(each_sibling_path.read_text(encoding="utf-8"))
+        except (OSError, SyntaxError, UnicodeDecodeError):
+            continue
+        for each_signature in _module_anchor_signatures(sibling_tree):
+            owner_name_by_signature.setdefault(each_signature, each_sibling_path.name)
+    return owner_name_by_signature
+
+
+def check_config_duplicate_path_anchor(content: str, file_path: str) -> list[str]:
+    """Flag a config module re-anchoring a path a sibling config module already builds.
+
+    Two config modules in the same ``config/`` directory that each anchor
+    ``Path(__file__)`` the same number of levels up and join the same first
+    literal segment are two sources of truth for one directory: a rename in
+    one module silently leaves the other pointing at the old folder. The
+    check fires on a config-module write whose module-level assignment joins
+    a ``__file__`` anchor (``parents[N]`` or a ``.parent`` chain) with a
+    literal segment that a sibling module in the same directory also joins at
+    the same depth. Compose one shared base constant and build the other path
+    from it. Test files, non-Python files, and modules outside a config
+    directory are exempt; an unreadable or unparseable sibling is skipped.
+
+    Args:
+        content: The Python source under validation.
+        file_path: The destination path, used to locate sibling config modules.
+
+    Returns:
+        One issue line per duplicated anchor, capped at the configured maximum.
+    """
+    if not _config_anchor_check_applies(file_path):
+        return []
+    try:
+        module_tree = ast.parse(content)
+    except SyntaxError:
+        return []
+    written_signatures = _module_anchor_signatures(module_tree)
+    if not written_signatures:
+        return []
+    config_directory = Path(file_path).parent
+    if not config_directory.is_dir():
+        return []
+    owner_name_by_signature = _sibling_anchor_owner_names(config_directory, Path(file_path).name)
+    issues: list[str] = []
+    for each_signature, each_line_number in sorted(written_signatures.items(), key=lambda pair: pair[1]):
+        owner_name = owner_name_by_signature.get(each_signature)
+        if owner_name is None:
+            continue
+        anchor_up_count, first_segment = each_signature
+        issues.append(
+            f"Line {each_line_number}: joins {first_segment} onto the same base, "
+            f"{anchor_up_count} levels above this file, that {owner_name} "
+            "already builds - define the base once and compose both paths from it"
+        )
+        if len(issues) >= MAX_CONFIG_DUPLICATE_PATH_ANCHOR_ISSUES:
+            break
+    return issues