claude-dev-env 1.94.0 → 2.0.0

package/hooks/blocking/claude_md_orphan_file_blocker_parts/subtree_scan.py

@@ -0,0 +1,179 @@
+"""Resolve a CLAUDE.md's scan root and find the referenced files absent from it.
+
+The scan root is the CLAUDE.md directory's parent, covering the directory, its
+subdirectories, and its siblings. A bounded walk collects the file basenames;
+when the budget truncates the walk, a direct ``rglob`` probe resolves any name
+the partial set missed, so a truncated slice never reports a present file as
+missing.
+"""
+
+from pathlib import Path
+
+from claude_md_orphan_file_blocker_parts.references import (
+    find_referenced_filenames,
+    find_run_command_filenames,
+)
+
+from hooks_constants.claude_md_orphan_file_blocker_constants import (
+    ALL_NOISE_DIRECTORY_NAMES,
+    MAX_ORPHAN_FILE_ISSUES,
+    MAX_SUBTREE_FILES_SCANNED,
+)
+
+
+def _resolve_scan_root(claude_md_directory: Path) -> Path:
+    """Return the directory whose subtree bounds the filename existence search.
+
+    Args:
+        claude_md_directory: The directory that holds the target CLAUDE.md.
+
+    Returns:
+        The CLAUDE.md directory's parent, or the directory itself when it has no
+        distinct parent.
+    """
+    parent_directory = claude_md_directory.parent
+    if parent_directory == claude_md_directory:
+        return claude_md_directory
+    return parent_directory
+
+
+class _SubtreeScan:
+    """The basenames a bounded subtree walk collected and whether it ran complete.
+
+    Attributes:
+        all_basenames: Each file basename the walk reached.
+        was_scan_complete: True when the walk visited the whole subtree within the
+            budget, so ``all_basenames`` is authoritative.
+    """
+
+    def __init__(self, all_basenames: set[str], was_scan_complete: bool) -> None:
+        self.all_basenames = all_basenames
+        self.was_scan_complete = was_scan_complete
+
+
+def _is_under_noise_directory(scan_root: Path, candidate_path: Path) -> bool:
+    """Return whether *candidate_path* lies inside a pruned noise directory.
+
+    Args:
+        scan_root: The directory the walk descends from.
+        candidate_path: A path the walk yielded under the scan root.
+
+    Returns:
+        True when any path segment below *scan_root* names a noise directory.
+    """
+    try:
+        relative_segments = candidate_path.relative_to(scan_root).parts
+    except ValueError:
+        relative_segments = candidate_path.parts
+    return any(each_segment in ALL_NOISE_DIRECTORY_NAMES for each_segment in relative_segments)
+
+
+def _is_countable_file(candidate_path: Path) -> bool:
+    """Return whether *candidate_path* is a readable regular file.
+
+    Args:
+        candidate_path: A path the walk yielded.
+
+    Returns:
+        True when the path is a file; a per-entry stat error reads as False.
+    """
+    try:
+        return candidate_path.is_file()
+    except OSError:
+        return False
+
+
+def _scan_subtree_basenames(scan_root: Path) -> _SubtreeScan:
+    """Return the bounded basename scan of *scan_root*, skipping unreadable entries.
+
+    Args:
+        scan_root: The directory whose subtree bounds the existence search.
+
+    Returns:
+        The collected basenames paired with the scan-completeness flag.
+    """
+    all_basenames: set[str] = set()
+    scanned_count = 0
+    for each_path in scan_root.rglob("*"):
+        if _is_under_noise_directory(scan_root, each_path):
+            continue
+        if not _is_countable_file(each_path):
+            continue
+        all_basenames.add(each_path.name)
+        scanned_count += 1
+        if scanned_count >= MAX_SUBTREE_FILES_SCANNED:
+            return _SubtreeScan(all_basenames, was_scan_complete=False)
+    return _SubtreeScan(all_basenames, was_scan_complete=True)
+
+
+def _filename_exists_under(scan_root: Path, filename: str) -> bool:
+    """Return whether a file with basename *filename* exists anywhere under root.
+
+    Args:
+        scan_root: The directory whose subtree bounds the existence search.
+        filename: The bare basename to look for.
+
+    Returns:
+        True when at least one matching file is reachable under the scan root.
+    """
+    for each_match in scan_root.rglob(filename):
+        if _is_under_noise_directory(scan_root, each_match):
+            continue
+        if _is_countable_file(each_match):
+            return True
+    return False
+
+
+def _present_referenced_filenames(all_referenced_filenames: list[str], scan_root: Path) -> set[str]:
+    """Return the referenced filenames that exist under the scan root.
+
+    Args:
+        all_referenced_filenames: The bare filenames a CLAUDE.md table names.
+        scan_root: The directory whose subtree bounds the existence search.
+
+    Returns:
+        The subset of *all_referenced_filenames* that resolve to an existing file.
+    """
+    subtree_scan = _scan_subtree_basenames(scan_root)
+    present_filenames: set[str] = set()
+    for each_filename in all_referenced_filenames:
+        if each_filename in subtree_scan.all_basenames:
+            present_filenames.add(each_filename)
+            continue
+        if subtree_scan.was_scan_complete:
+            continue
+        if _filename_exists_under(scan_root, each_filename):
+            present_filenames.add(each_filename)
+    return present_filenames
+
+
+def find_missing_filenames(content: str, claude_md_directory: Path) -> list[str]:
+    """Return the referenced filenames absent from the CLAUDE.md's scan root.
+
+    Args:
+        content: The CLAUDE.md content being written.
+        claude_md_directory: The directory that holds the target CLAUDE.md.
+
+    Returns:
+        Each referenced filename with no matching file under the scan root.
+    """
+    referenced_filenames = find_referenced_filenames(content) + find_run_command_filenames(content)
+    if not referenced_filenames:
+        return []
+    scan_root = _resolve_scan_root(claude_md_directory)
+    try:
+        present_filenames = _present_referenced_filenames(referenced_filenames, scan_root)
+    except OSError:
+        return []
+    missing_filenames: list[str] = []
+    already_reported: set[str] = set()
+    for each_filename in referenced_filenames:
+        if each_filename in already_reported:
+            continue
+        if each_filename in present_filenames:
+            continue
+        already_reported.add(each_filename)
+        missing_filenames.append(each_filename)
+        if len(missing_filenames) >= MAX_ORPHAN_FILE_ISSUES:
+            break
+    return missing_filenames

package/hooks/blocking/claude_md_orphan_file_blocker_parts/tests/conftest.py

@@ -0,0 +1,10 @@
+"""Put the blocking and hooks directories on sys.path for the parts tests."""
+
+import sys
+from pathlib import Path
+
+_blocking_directory = str(Path(__file__).resolve().parents[2])
+_hooks_directory = str(Path(__file__).resolve().parents[3])
+for each_bootstrap_directory in (_blocking_directory, _hooks_directory):
+    if each_bootstrap_directory not in sys.path:
+        sys.path.insert(0, each_bootstrap_directory)

package/hooks/blocking/claude_md_orphan_file_blocker_parts/tests/test_decision.py

@@ -0,0 +1,34 @@
+"""Tests for the CLAUDE.md orphan-file blocker decision parts module."""
+
+import json
+
+import pytest
+from claude_md_orphan_file_blocker_parts import decision as decision_module
+from claude_md_orphan_file_blocker_parts.config.orphan_blocker_constants import (
+    ROW_FIRST_RETRY_HINT,
+)
+from claude_md_orphan_file_blocker_parts.decision import (
+    build_block_payload,
+    deny_orphan_files,
+)
+
+
+def test_deny_orphan_files_emits_deny(
+    capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(decision_module, "log_hook_block", lambda **each_argument: None)
+    deny_orphan_files("Write", "/pkg/CLAUDE.md", "/pkg", ["absent.py"])
+    emitted_payload = json.loads(capsys.readouterr().out)
+    assert emitted_payload["hookSpecificOutput"]["permissionDecision"] == "deny"
+
+
+def test_build_block_payload_names_missing_files_and_denies() -> None:
+    block_payload = build_block_payload(["absent.py"], "/pkg")
+    hook_output = block_payload["hookSpecificOutput"]
+    assert hook_output["permissionDecision"] == "deny"
+    assert "absent.py" in hook_output["permissionDecisionReason"]
+
+
+def test_build_block_payload_appends_retry_hint() -> None:
+    block_payload = build_block_payload(["absent.py"], "/pkg")
+    assert ROW_FIRST_RETRY_HINT in block_payload["hookSpecificOutput"]["permissionDecisionReason"]

package/hooks/blocking/claude_md_orphan_file_blocker_parts/tests/test_references.py

@@ -0,0 +1,42 @@
+"""Tests for the CLAUDE.md reference-extraction parts module."""
+
+from claude_md_orphan_file_blocker_parts.references import (
+    find_referenced_filenames,
+    find_run_command_filenames,
+    is_claude_md_file,
+)
+
+
+def test_is_claude_md_file_matches_basename() -> None:
+    assert is_claude_md_file("/pkg/CLAUDE.md") is True
+    assert is_claude_md_file("/pkg/README.md") is False
+
+
+def test_find_referenced_filenames_reads_table_cell() -> None:
+    content = "# t\n\n| File | Note |\n|---|---|\n| `alpha.py` | a |\n"
+    assert find_referenced_filenames(content) == ["alpha.py"]
+
+
+def test_find_referenced_filenames_skips_fenced_table() -> None:
+    content = "# t\n\n```\n| File | Note |\n|---|---|\n| `ghost.py` | a |\n```\n"
+    assert find_referenced_filenames(content) == []
+
+
+def test_find_referenced_filenames_skips_relative_path_block() -> None:
+    content = "# t\n\nSourced from `../shared`:\n\n| File | Note |\n|---|---|\n| `alpha.py` | a |\n"
+    assert find_referenced_filenames(content) == []
+
+
+def test_find_run_command_filenames_reads_fenced_command() -> None:
+    content = "# t\n\n```bash\npython tools/verify.py --flag\n```\n"
+    assert find_run_command_filenames(content) == ["verify.py"]
+
+
+def test_find_run_command_filenames_ignores_prose_command() -> None:
+    content = "# t\n\nJust run python outside.py somewhere in prose.\n"
+    assert find_run_command_filenames(content) == []
+
+
+def test_find_run_command_filenames_drops_trailing_comment() -> None:
+    content = "# t\n\n```bash\npython real.py  # was python old.py\n```\n"
+    assert find_run_command_filenames(content) == ["real.py"]

package/hooks/blocking/claude_md_orphan_file_blocker_parts/tests/test_scan_plan.py

@@ -0,0 +1,27 @@
+"""Tests for the CLAUDE.md scan-plan parts module."""
+
+from pathlib import Path
+
+from claude_md_orphan_file_blocker_parts.scan_plan import (
+    build_orphan_scan_plan,
+    collect_missing_filenames,
+)
+
+
+def test_build_orphan_scan_plan_uses_write_content(tmp_path: Path) -> None:
+    content = "# t\n\n| File | Note |\n|---|---|\n| `absent.py` | a |\n"
+    scan_plan = build_orphan_scan_plan(
+        "Write", {"content": content}, str(tmp_path / "CLAUDE.md"), tmp_path
+    )
+    assert scan_plan.candidate_contents == [content]
+    assert scan_plan.baseline_missing_filenames == set()
+
+
+def test_collect_missing_filenames_reports_write_orphan(tmp_path: Path) -> None:
+    package_directory = tmp_path / "package"
+    package_directory.mkdir()
+    content = "# t\n\n| File | Note |\n|---|---|\n| `absent.py` | a |\n"
+    scan_plan = build_orphan_scan_plan(
+        "Write", {"content": content}, str(package_directory / "CLAUDE.md"), package_directory
+    )
+    assert collect_missing_filenames(scan_plan, package_directory) == ["absent.py"]

package/hooks/blocking/claude_md_orphan_file_blocker_parts/tests/test_subtree_scan.py

@@ -0,0 +1,30 @@
+"""Tests for the CLAUDE.md subtree-scan parts module."""
+
+from pathlib import Path
+
+from claude_md_orphan_file_blocker_parts.subtree_scan import find_missing_filenames
+
+
+def test_find_missing_filenames_reports_absent_reference(tmp_path: Path) -> None:
+    package_directory = tmp_path / "package"
+    package_directory.mkdir()
+    content = "# t\n\n| File | Note |\n|---|---|\n| `absent.py` | a |\n"
+    assert find_missing_filenames(content, package_directory) == ["absent.py"]
+
+
+def test_find_missing_filenames_allows_present_reference(tmp_path: Path) -> None:
+    package_directory = tmp_path / "package"
+    package_directory.mkdir()
+    (package_directory / "present.py").write_text("x = 1\n", encoding="utf-8")
+    content = "# t\n\n| File | Note |\n|---|---|\n| `present.py` | a |\n"
+    assert find_missing_filenames(content, package_directory) == []
+
+
+def test_find_missing_filenames_finds_sibling_under_parent(tmp_path: Path) -> None:
+    package_directory = tmp_path / "package"
+    package_directory.mkdir()
+    sibling_directory = tmp_path / "sibling"
+    sibling_directory.mkdir()
+    (sibling_directory / "neighbor.py").write_text("x = 1\n", encoding="utf-8")
+    content = "# t\n\n| File | Note |\n|---|---|\n| `neighbor.py` | a |\n"
+    assert find_missing_filenames(content, package_directory) == []

package/hooks/blocking/code_rules_boolean_mustcheck.py

@@ -154,7 +154,7 @@ def _bool_parameters_for_function(
             continue
         if _argument_is_boolean(each_argument, default_node):
             bool_parameters.append((each_argument.arg, each_argument.lineno))
-    for each_argument, each_default in zip(arguments.kwonlyargs, arguments.kw_defaults):
+    for each_argument, each_default in zip(arguments.kwonlyargs, arguments.kw_defaults, strict=False):
         if each_argument.arg in ALL_SELF_AND_CLS_PARAMETER_NAMES:
             continue
         if _argument_is_boolean(each_argument, each_default):

package/hooks/blocking/code_rules_enforcer.py

@@ -158,6 +158,7 @@ from code_rules_shared import (  # noqa: E402
     is_ephemeral_script_path,
     is_hook_infrastructure,
     is_test_file,
+    is_under_session_scratchpad,
 )
 from code_rules_string_magic import (  # noqa: E402
     check_inline_literal_collections,
@@ -1104,6 +1105,9 @@ def main(all_arguments: list[str]) -> None:
     tool_input = pretooluse_payload.get("tool_input", {})
     file_path = tool_input.get("file_path", "")
 
+    if is_under_session_scratchpad(file_path, pretooluse_payload):
+        sys.exit(0)
+
     runs_full_verdict = _is_validated_target(file_path)
     if not runs_full_verdict and not _is_hook_infrastructure_python_target(file_path):
         sys.exit(0)

package/hooks/blocking/code_rules_mock_completeness.py

@@ -276,7 +276,7 @@ def check_incomplete_mocks(content: str, file_path: str) -> None:
 
     all_scoped_definitions = _collect_scoped_mock_definitions(module_tree)
 
-    for each_scope_id, each_mock_name, each_declared_keys, each_definition_line, each_scope_node in all_scoped_definitions:
+    for each_scope_id, each_mock_name, each_declared_keys, each_definition_line, each_scope_node in all_scoped_definitions:  # noqa: B007
         assigned_attributes = _collect_mock_attribute_assignments_in_scope(each_scope_node, each_mock_name)
         all_known_fields = each_declared_keys | assigned_attributes
         field_accesses = _collect_mock_field_accesses_in_scope(each_scope_node, each_mock_name)

package/hooks/blocking/code_rules_optional_params.py

@@ -36,10 +36,10 @@ def _collect_optional_param_defaults(
     all_args = arguments.posonlyargs + arguments.args
     defaults_aligned = [None] * (len(all_args) - len(arguments.defaults)) + list(arguments.defaults)
     param_defaults: dict[str, ast.expr] = {}
-    for each_arg, each_default in zip(all_args, defaults_aligned):
+    for each_arg, each_default in zip(all_args, defaults_aligned, strict=False):
         if each_default is not None:
             param_defaults[each_arg.arg] = each_default
-    for each_kwarg, each_kwdefault in zip(arguments.kwonlyargs, arguments.kw_defaults):
+    for each_kwarg, each_kwdefault in zip(arguments.kwonlyargs, arguments.kw_defaults, strict=False):
         if each_kwdefault is not None:
             param_defaults[each_kwarg.arg] = each_kwdefault
     return param_defaults

package/hooks/blocking/code_rules_shared.py

@@ -4,6 +4,7 @@ import ast
 import difflib
 import os
 import sys
+import tempfile
 from collections.abc import Collection, Iterator
 from pathlib import Path
 
@@ -29,6 +30,13 @@ from hooks_constants.code_rules_enforcer_constants import (  # noqa: E402
     LEADING_DRIVE_LETTER_PATTERN,
     STRICT_TEST_FILE_BASENAME_PATTERN,
 )
+from hooks_constants.harness_scratchpad_constants import (  # noqa: E402
+    HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
+    HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT,
+    HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX,
+    HOOK_PAYLOAD_SESSION_ID_KEY,
+    HOOK_PAYLOAD_WORKING_DIRECTORY_KEY,
+)
 from hooks_constants.unused_module_import_constants import (  # noqa: E402
     TYPE_CHECKING_IDENTIFIER,
 )
@@ -175,7 +183,7 @@ def _collect_fixture_injection_arguments(
     undefaulted_keyword_only_arguments = [
         each_keyword_argument
         for each_keyword_argument, each_default in zip(
-            arguments.kwonlyargs, arguments.kw_defaults
+            arguments.kwonlyargs, arguments.kw_defaults, strict=False
         )
         if each_default is None
     ]
@@ -267,6 +275,80 @@ def is_ephemeral_script_path(file_path: str) -> bool:
     return False
 
 
+def _resolve_session_scratchpad_root(hook_payload: dict) -> str | None:
+    """Rebuild the harness session scratchpad directory from a PreToolUse payload.
+
+    ::
+
+        payload.cwd = /home/user/project    payload.session_id = 5f2c...
+                          |                            |
+        <tempdir>/claude-<uid>/-home-user-project/5f2c.../scratchpad
+                     |               |
+                  os.getuid()   cwd with each "/" turned to "-"
+
+    No environment variable carries this path, so it is rebuilt from the three
+    signals a hook can read: the POSIX user id and the ``cwd`` and ``session_id``
+    fields the harness puts in every PreToolUse payload. The rebuilt directory
+    is returned only when it exists on disk, so a wrong guess or a non-POSIX
+    platform yields None and the gates keep full enforcement.
+
+    Args:
+        hook_payload: The PreToolUse payload carrying ``cwd`` and ``session_id``.
+
+    Returns:
+        The scratchpad directory path when it exists on disk, else None.
+    """
+    get_user_id = getattr(os, "getuid", None)
+    if get_user_id is None:
+        return None
+    session_id = hook_payload.get(HOOK_PAYLOAD_SESSION_ID_KEY, "")
+    working_directory = hook_payload.get(HOOK_PAYLOAD_WORKING_DIRECTORY_KEY, "")
+    if not isinstance(session_id, str) or not session_id:
+        return None
+    if not isinstance(working_directory, str) or not working_directory:
+        return None
+    mangled_working_directory = working_directory.replace("\\", "/").replace(
+        "/", HARNESS_SCRATCHPAD_PATH_SEPARATOR_REPLACEMENT
+    )
+    user_directory_name = f"{HARNESS_SCRATCHPAD_USER_DIRECTORY_PREFIX}{get_user_id()}"
+    scratchpad_root = os.path.join(
+        tempfile.gettempdir(),
+        user_directory_name,
+        mangled_working_directory,
+        session_id,
+        HARNESS_SCRATCHPAD_LEAF_DIRECTORY_NAME,
+    )
+    if not os.path.isdir(scratchpad_root):
+        return None
+    return scratchpad_root
+
+
+def is_under_session_scratchpad(file_path: str, hook_payload: dict) -> bool:
+    """Return True when file_path resolves under the harness session scratchpad.
+
+    One-off scripts written to the session scratchpad are throwaway tooling
+    outside every repo, so the TDD and CODE_RULES gates skip them. Both
+    file_path and the rebuilt scratchpad root are resolved through the real
+    filesystem (symlinks followed) before the containment test, so a symlink
+    into the scratchpad exempts and a symlink out of it does not.
+
+    Args:
+        file_path: The path the write targets.
+        hook_payload: The PreToolUse payload carrying ``cwd`` and ``session_id``.
+
+    Returns:
+        True when file_path's real path sits at or under the session scratchpad.
+    """
+    if not file_path:
+        return False
+    scratchpad_root = _resolve_session_scratchpad_root(hook_payload)
+    if scratchpad_root is None:
+        return False
+    real_target = os.path.realpath(file_path)
+    real_root = os.path.realpath(scratchpad_root)
+    return real_target == real_root or real_target.startswith(real_root + os.sep)
+
+
 def is_migration_file(file_path: str) -> bool:
     """Check if file is a Django migration (must be self-contained)."""
     path_lower = file_path.lower().replace("\\", "/")

package/hooks/blocking/code_rules_test_assertions.py

@@ -557,7 +557,7 @@ def _leading_token_overlap(first_name: str, second_name: str) -> int:
     first_tokens = first_name.split("_")
     second_tokens = second_name.split("_")
     shared = 0
-    for first_token, second_token in zip(first_tokens, second_tokens):
+    for first_token, second_token in zip(first_tokens, second_tokens, strict=False):
         if first_token != second_token:
             break
         shared += 1

package/hooks/blocking/code_rules_test_layout.py

@@ -133,7 +133,11 @@ def _referenced_names(tree: ast.Module) -> set[str]:
     }
     return load_names | literal_values
 
-def _dead_constant_messages(tree: ast.Module, referenced_names: set[str]) -> list[str]:
+def _dead_constant_messages(
+    tree: ast.Module,
+    referenced_names: set[str],
+    maximum_issues: int,
+) -> list[str]:
     """Return one message per module constant absent from the referenced set."""
     issues: list[str] = []
     for each_name, each_line in _module_constant_targets(tree):
@@ -142,7 +146,7 @@ def _dead_constant_messages(tree: ast.Module, referenced_names: set[str]) -> lis
         issues.append(
             f"Line {each_line}: constant {each_name!r} - {DEAD_TEST_CONSTANT_GUIDANCE}"
         )
-        if len(issues) >= MAX_TEST_LAYOUT_ISSUES:
+        if len(issues) >= maximum_issues:
             break
     return issues
 
@@ -174,7 +178,9 @@ def check_dead_test_module_constant(content: str, file_path: str) -> list[str]:
     tree = _parse_module(content)
     if tree is None:
         return []
-    return _dead_constant_messages(tree, _referenced_names(tree))
+    return _dead_constant_messages(
+        tree, _referenced_names(tree), MAX_TEST_LAYOUT_ISSUES
+    )
 
 def _node_names_fixture(node: ast.AST) -> bool:
     """Return whether one decorator sub-node spells the pytest fixture marker."""

package/hooks/blocking/code_rules_typeddict_stub.py

@@ -180,7 +180,7 @@ def _forwards_parameters_unchanged(call_node: ast.Call, all_parameter_names: lis
         return False
     if len(call_node.args) != len(all_parameter_names):
         return False
-    for each_argument, each_parameter_name in zip(call_node.args, all_parameter_names):
+    for each_argument, each_parameter_name in zip(call_node.args, all_parameter_names, strict=False):
         if not isinstance(each_argument, ast.Name) or each_argument.id != each_parameter_name:
             return False
     return True

package/hooks/blocking/gh_pr_author_enforcer.py

@@ -149,7 +149,7 @@ def _write_swap_state(
     serialized_payload = json.dumps(swap_state).encode(STATE_FILE_PAYLOAD_TEXT_ENCODING_NAME)
     open_flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
     if hasattr(os, OS_O_NOFOLLOW_ATTRIBUTE_NAME):
-        open_flags |= os.O_NOFOLLOW  # type: ignore[attr-defined]  # POSIX-only flag, guarded by hasattr above
+        open_flags |= getattr(os, OS_O_NOFOLLOW_ATTRIBUTE_NAME)
     file_descriptor = _open_state_file_with_retry(state_file, open_flags)
     if file_descriptor is None:
         return False

package/hooks/blocking/inventory_intent_records/CLAUDE.md

@@ -0,0 +1,26 @@
+# inventory_intent_records
+
+The shared pending-intent store that lets `package_inventory_stale_blocker.py`
+and `claude_md_orphan_file_blocker.py` add a new file and its inventory row in
+one change, in either order. When one blocker denies, it records a note; the
+sibling blocker reads that note to allow the matching second write.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `records.py` | Read, record, peek, and consume the per-session file and row intents; a missing or corrupt store reads as no notes |
+| `__init__.py` | Package marker |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `config/` | The records-file name shape, the freshness window, the list keys, and the note field names (`intent_records_constants.py`) |
+| `tests/` | pytest suite for the records store |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/hooks/blocking/inventory_intent_records/tests/
+```

package/hooks/blocking/inventory_intent_records/__init__.py

@@ -0,0 +1 @@
+"""Shared pending-intent notes both inventory blockers read to break the deadlock."""

package/hooks/blocking/inventory_intent_records/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration home for the shared intent-records constants."""

package/hooks/blocking/inventory_intent_records/config/intent_records_constants.py

@@ -0,0 +1,20 @@
+"""Constants for the shared inventory/orphan pending-intent records.
+
+Holds the per-session records-file name shape, the freshness window a pending
+note lives inside, the two list keys the file stores under, and the field names
+of one stored note.
+"""
+
+from __future__ import annotations
+
+INTENT_FILE_PREFIX: str = "claude-inventory-intent-"
+INTENT_FILE_SUFFIX: str = ".json"
+
+INTENT_FRESHNESS_WINDOW_SECONDS: float = 900.0
+
+ALL_FILE_INTENTS_KEY: str = "pending_file_intents"
+ALL_ROW_INTENTS_KEY: str = "pending_row_intents"
+
+INTENT_DIRECTORY_FIELD: str = "directory"
+INTENT_FILENAME_FIELD: str = "filename"
+INTENT_RECORDED_AT_FIELD: str = "recorded_at"