claude-dev-env 4.3.0 → 7.1.0

package/_shared/pr-loop/scripts/tests/test_post_audit_thread_constants.py

@@ -1,129 +0,0 @@
-"""Tests for post_audit_thread_constants.py extracted constant set."""
-
-import importlib.util
-from pathlib import Path
-from types import ModuleType
-
-
-def _load_constants_module() -> ModuleType:
-    module_path = (
-        Path(__file__).parent.parent
-        / "pr_loop_shared_constants"
-        / "post_audit_thread_constants.py"
-    )
-    specification = importlib.util.spec_from_file_location(
-        "pr_loop_shared_constants.post_audit_thread_constants", module_path
-    )
-    assert specification is not None
-    assert specification.loader is not None
-    module = importlib.util.module_from_spec(specification)
-    specification.loader.exec_module(module)
-    return module
-
-
-constants_module = _load_constants_module()
-
-
-def test_http_request_content_type_is_application_json() -> None:
-    assert constants_module.HTTP_REQUEST_CONTENT_TYPE == "application/json"
-
-
-def test_http_method_post_constant_is_post() -> None:
-    assert constants_module.HTTP_METHOD_POST == "POST"
-
-
-def test_http_header_authorization_constant_is_authorization() -> None:
-    assert constants_module.HTTP_HEADER_AUTHORIZATION == "Authorization"
-
-
-def test_http_header_accept_constant_is_accept() -> None:
-    assert constants_module.HTTP_HEADER_ACCEPT == "Accept"
-
-
-def test_http_header_content_type_constant_is_content_type() -> None:
-    assert constants_module.HTTP_HEADER_CONTENT_TYPE == "Content-Type"
-
-
-def test_http_header_github_api_version_constant_is_x_github_api_version() -> None:
-    assert constants_module.HTTP_HEADER_GITHUB_API_VERSION == "X-GitHub-Api-Version"
-
-
-def test_http_header_user_agent_constant_is_user_agent() -> None:
-    assert constants_module.HTTP_HEADER_USER_AGENT == "User-Agent"
-
-
-def test_http_authorization_bearer_prefix_is_bearer_with_trailing_space() -> None:
-    prefix = constants_module.HTTP_AUTHORIZATION_BEARER_PREFIX
-    assert prefix == "Bearer "
-    assert prefix.endswith(" ")
-
-
-def test_http_request_timeout_seconds_is_positive_int() -> None:
-    timeout_seconds = constants_module.HTTP_REQUEST_TIMEOUT_SECONDS
-    assert isinstance(timeout_seconds, int)
-    assert timeout_seconds > 0
-
-
-def test_error_response_preview_chars_is_positive_int() -> None:
-    preview_chars = constants_module.ERROR_RESPONSE_PREVIEW_CHARS
-    assert isinstance(preview_chars, int)
-    assert preview_chars > 0
-
-
-def test_single_review_api_path_template_uses_pr_number_placeholder() -> None:
-    template_text = constants_module.SINGLE_REVIEW_API_PATH_TEMPLATE
-    assert "{owner}" in template_text
-    assert "{repo}" in template_text
-    assert "{pr_number}" in template_text
-    assert "{review_id}" in template_text
-
-
-def test_single_review_comments_api_path_template_uses_pr_number_placeholder() -> None:
-    template_text = constants_module.SINGLE_REVIEW_COMMENTS_API_PATH_TEMPLATE
-    assert "{owner}" in template_text
-    assert "{repo}" in template_text
-    assert "{pr_number}" in template_text
-    assert "{review_id}" in template_text
-    assert template_text.endswith("/comments")
-
-
-def test_audit_body_skeleton_marker_tokens_present() -> None:
-    open_marker = constants_module.AUDIT_BODY_SKELETON_OPEN_MARKER
-    close_marker = constants_module.AUDIT_BODY_SKELETON_CLOSE_MARKER
-    assert open_marker.startswith("<!--") and open_marker.endswith("-->")
-    assert close_marker.startswith("<!--") and close_marker.endswith("-->")
-    assert open_marker != close_marker
-
-
-def test_template_path_resolves_to_existing_markdown_file() -> None:
-    resolved_path = constants_module.template_path()
-    assert resolved_path.is_file(), f"missing: {resolved_path}"
-    assert resolved_path.suffix == ".md"
-
-
-def test_template_contains_skeleton_markers() -> None:
-    resolved_path = constants_module.template_path()
-    template_text = resolved_path.read_text(encoding="utf-8")
-    assert constants_module.AUDIT_BODY_SKELETON_OPEN_MARKER in template_text
-    assert constants_module.AUDIT_BODY_SKELETON_CLOSE_MARKER in template_text
-
-
-def test_live_test_fixture_names_are_not_exposed_from_production_config_module() -> None:
-    forbidden_attribute_names = [
-        "LIVE_TEST_OWNER",
-        "LIVE_TEST_REPO",
-        "LIVE_TEST_BRANCH_PREFIX",
-        "LIVE_TEST_PR_TITLE",
-        "LIVE_TEST_PR_BODY",
-        "LIVE_TEST_BASE_BRANCH",
-        "LIVE_TEST_FIXTURE_FILENAME",
-        "LIVE_TEST_FIXTURE_CONTENT",
-        "LIVE_TEST_FIXTURE_LINE_FOR_FINDING_ONE",
-        "LIVE_TEST_FIXTURE_LINE_FOR_FINDING_TWO",
-        "LIVE_TEST_FIXTURE_LINE_FOR_FINDING_THREE",
-    ]
-    for each_attribute_name in forbidden_attribute_names:
-        assert not hasattr(constants_module, each_attribute_name), (
-            f"production config module exposes test-only fixture "
-            f"{each_attribute_name!r}; move it to test_post_audit_thread.py"
-        )

package/_shared/pr-loop/state-schema.md

@@ -1,45 +0,0 @@
-# State schema
-
-State each PR-loop workflow tracks across iterations. Workflows differ on persistence (in-memory vs files) and which fields they use; shapes overlap.
-
-## Common fields
-
-| Field | Type | Purpose |
-|---|---|---|
-| `loop_count` | int | Iterations completed; bumps on each AUDIT or tick |
-| `last_action` | enum | `fresh`, `audited`, `fixed` — drives next-step dispatch |
-| `last_findings` | object | `{p0, p1, p2, total}` count of findings from most recent AUDIT |
-| `audit_log` | list[str] | Per-iteration one-line summaries for the final report |
-| `starting_sha` | str | `git rev-parse HEAD` at workflow start |
-| `loop_comment_index` | dict | `{finding_id: {finding_comment_id, finding_comment_url, thread_node_id, fix_status, ...}}` (`thread_node_id` is the PR review thread node id — `PRRT_kwDOxxx` — captured at audit time when calling `get_review_comments`, used by `resolve_thread` at FIX time) |
-
-## autoconverge (workflow and portable pacer)
-
-Workflow runs hold round state in the workflow journal. On `pacer=portable`, the
-continuous driver seeds `pr-converge-state.json` under the job directory and
-advances phases through `portable_converge_driver.py`. Portable state carries
-`current_head`, `phase`, `codex_clean_at`, `codex_down`, `codex_required`, and
-pending `next` / `wait_seconds` stamps. Round shape and terminal gates are
-documented in
-[`../../.agents/skills/autoconverge/reference/convergence.md`](../../.agents/skills/autoconverge/reference/convergence.md).
-The machine readiness checklist is
-[`../../.agents/skills/autoconverge/reference/convergence-gates.md`](../../.agents/skills/autoconverge/reference/convergence-gates.md).
-
-## Archived workflow extensions
-
-Historical field lists for retired entry skills live under
-`packages/claude-dev-env/.agents/skills-archived/`:
-
-- **bugteam** — inline orchestrator state, `team_name`, `gate_round_count`, exit payload fields. See [`../../.agents/skills-archived/bugteam/SKILL.md`](../../.agents/skills-archived/bugteam/SKILL.md).
-- **pr-converge** — file-backed multi-PR state, phase enum, dual persistence. See [`../../.agents/skills-archived/pr-converge/reference/state-schema.md`](../../.agents/skills-archived/pr-converge/reference/state-schema.md) and [`../../.agents/skills-archived/pr-converge/reference/multi-pr-orchestration.md`](../../.agents/skills-archived/pr-converge/reference/multi-pr-orchestration.md).
-
-## Reset semantics
-
-- **autoconverge** — portable state resets on a fresh `open-run`; workflow journal is per run id.
-- **Archived bugteam** — cleared on each new invocation; see archived skill body.
-- **Archived pr-converge** — see archived [`state-schema.md`](../../.agents/skills-archived/pr-converge/reference/state-schema.md); multi-PR file state persists across orchestrator runs and only `last_seen_comment_id` advances monotonically.
-
-## Convergence checks
-
-- **autoconverge** — `packages/claude-dev-env/_shared/pr-loop/scripts/check_convergence.py` is the single readiness source; gate labels are listed in [`../../.agents/skills/autoconverge/reference/convergence-gates.md`](../../.agents/skills/autoconverge/reference/convergence-gates.md). On pass, mark the PR ready (`gh pr ready`).
-- **Archived pr-converge** — same script and archived [`convergence-gates.md`](../../.agents/skills-archived/pr-converge/reference/convergence-gates.md) reference.

package/_shared/pr-loop/worker-spawn.md

@@ -1,189 +0,0 @@
-# Worker-spawn protocol
-
-Single home for the worker-spawn dispatcher contract and for Claude-only
-slash-step host routing. Skills that need a role-bound headless worker call
-[`scripts/resolve_worker_spawn.py`](../../scripts/resolve_worker_spawn.py)
-(or import `resolve_worker_spawn`) and read this page for the tier walk, inputs,
-JSON result shape, host rules, and setup. Skills that run a Claude-only slash
-step (for example `/code-review`) read the code-review host-routing section.
-
-Composed helpers (preflight, headless runners, and the code-review invoker)
-stay documented at their own modules; this page states how callers use them.
-
-## Three tiers
-
-Walk order is fixed: soft-gate preflight for tier 1, then tier 1, then host
-branching for tiers 2 and 3.
-
-| Tier | Name | Who runs it |
-|---|---|---|
-| 1 | Grok headless | Python helper: `grok_worker_preflight` then `grok_headless_runner.run_headless_worker` |
-| 2 | `claude_agent_required` | **Not** the Python helper. A stop signal so the **calling skill / harness** runs the Claude Code Agent tool itself |
-| 3 | Claude headless | Python helper: `claude_chain_runner.run_claude` with `-p --output-format json --agent <stem>`, prompt body on stdin from the prompt file, and subprocess `cwd` set to the caller's working directory |
-
-### `claude_agent_required` boundary
-
-A Python helper cannot spawn Claude Code Agent-tool subagents. On a **Claude**
-host, when the claude headless tier is **not** enabled (`--enable-claude-tier`
-absent / `is_claude_tier_enabled=False`), a grok fallthrough records tier 2 with
-reason `claude_agent_required`, leaves `tier_used` null, and returns. The
-calling skill must then run the Agent tool in-process.
-
-On a **ThirdParty** host, or when the claude tier is enabled on a Claude host,
-the dispatcher continues to tier 3.
-
-## Tier-1 fleets via grok-spawn
-
-For a fleet of tier-1 grok workers (batch spec in, reports out), use the
-**grok-spawn** skill when that skill is installed on the host (it ships on a
-sibling stack and is not part of this dispatcher page). When present, that
-skill owns the batch playbook and flag profiles under its reference docs.
-This page stays the single-worker dispatcher contract (`resolve_worker_spawn`).
-
-The calling session owns verification and every commit, push, or GitHub post.
-Workers never commit or post.
-
-## Required inputs
-
-### CLI
-
-```
-python resolve_worker_spawn.py \
-  --role <role> \
-  --prompt-file <path> \
-  --cwd <dir> \
-  --run-temp-dir <dir> \
-  [--timeout-seconds N] \
-  [--enable-claude-tier]
-```
-
-| Flag | Required | Meaning |
-|---|---|---|
-| `--role` | no (default `bugteam`) | Role name for preflight agent-set checks; mapped to the primary agent stem for headless `--agent` (for example `bugteam` → `code-quality-agent`, `clean-coder` → `clean-coder`; unknown roles fall back to the raw role string) |
-| `--prompt-file` | yes | Prompt file path for headless workers |
-| `--cwd` | yes | Working directory for headless grok and claude workers |
-| `--run-temp-dir` | yes | Run-scoped directory for leader sockets and preflight cache (created if missing) |
-| `--timeout-seconds` | no (default `600`) | Per-tier timeout in seconds |
-| `--enable-claude-tier` | no | Allow tier 3 on a Claude host |
-
-There is no separate outcome-file flag. The result surface is **stdout JSON**
-plus the process exit code.
-
-### Import API
-
-`resolve_worker_spawn(...)` takes keyword-only arguments:
-`role`, `prompt_file`, `working_directory`, `timeout_seconds`,
-`is_claude_tier_enabled`, `run_state_directory`.
-`encode_spawn_outcome` turns a `SpawnOutcome` into the same JSON shape the CLI
-prints.
-
-The grok tier runs with no turn cap; `timeout_seconds` is its only bound.
-
-## JSON result shape
-
-Stdout is one JSON object:
-
-```json
-{
-  "tier_used": 1,
-  "ok": true,
-  "attempts": [
-    {"tier": 1, "ok": true, "reason": null}
-  ],
-  "output": "<serving tier stdout>",
-  "returncode": 0
-}
-```
-
-| Key | Meaning |
-|---|---|
-| `tier_used` | Serving tier number (`1` or `3`), or `null` when no tier served |
-| `ok` | Whether the serving call completed successfully |
-| `attempts` | Ordered list of tries: each `{tier, ok, reason}` |
-| `output` | Captured stdout from the serving tier (empty when none) |
-| `returncode` | Process return code from the last tier run (or config-error code) |
-
-`attempts` is in tried order. A Claude-host stop records tier `2` with
-`reason: "claude_agent_required"`. Preflight or grok fallthrough reasons use the
-preflight/runner classification strings (for example `grok_binary_missing`,
-`usage_limit`).
-
-### Exit codes
-
-| Code | Meaning |
-|---|---|
-| `0` | A tier served (`tier_used` is not null) |
-| `2` | Exhausted — no tier served |
-| `3` | Config error: the `--prompt-file` path is not an existing file (`output` = `prompt_file_missing`) or claude chain configuration missing or invalid |
-
-## Host detection
-
-After a grok fallthrough the dispatcher calls `detect_host_profile()` from
-`tier_model_ids` (advisor scripts). Detection order:
-
-1. `ADVISOR_HOST_PROFILE` when set — must be `Claude`, `Codex`, or `ThirdParty` (any letter case).
-2. `THIRD_PARTY` when truthy — `1`, `true`, `yes`, or `on`.
-3. Default: `Claude`.
-
-Profiles are the real names `Claude`, `Codex`, and `ThirdParty` (not a separate Grok host
-profile). Grok is tier 1 on every host; host profile only chooses the post-grok
-branch (Agent-tool handoff vs headless claude chain). A Codex profile takes the
-non-Claude branch.
-
-## Code-review host routing
-
-Claude-only slash steps need a Claude Code harness. The built-in
-`/code-review` command is the main case. The host-routing pair is:
-
-- `detect_host_profile()` from `tier_model_ids` — same host detection as the
-  worker-spawn dispatcher above
-- `invoke_code_review` — host-aware invoker for `/code-review` (lives next to
-  `resolve_worker_spawn` under the package scripts tree)
-
-Mode decision:
-
-| Host profile | Session model | Mode | Who runs `/code-review` |
-|---|---|---|---|
-| `Claude` | `opus` | `in_session` | The calling skill runs the slash command in-process |
-| `Claude` | any other alias | `chain` | Headless spawn through `claude_chain_runner` |
-| `ThirdParty` | any | `chain` | Headless spawn through `claude_chain_runner` |
-
-The review always runs at effort **high** on model **opus**. Chain mode builds
-a single-turn prompt `/code-review ultra --fix`, pins `--model opus`, sets
-subprocess `cwd` to the PR working tree, and reads stdin from the empty stream
-so the spawn does not wait for input.
-
-After a chain run, a non-empty `git status --porcelain` means the review
-applied fixes. The calling host commits and pushes those fixes per the fix
-protocol. The chain process never commits or posts. A clean stamp requires
-`returncode == 0` and a non-null `served_command` plus a clean tree —
-`dirty_tree` false alone is not enough when the chain failed or never served.
-
-GitHub transport (`pr-loop-cloud-transport`) is a separate axis from this
-harness branch. That skill routes `gh` vs MCP; it does not change which host
-can run Claude-only slash commands.
-
-## Leader-socket rule
-
-Every concurrent grok process gets its own `--leader-socket` path under the
-caller-supplied run temp directory. The headless runner mints a unique
-`grok-leader-<uuid>.sock` per invocation. Preflight auth and ping probes use
-their own fixed socket filenames under the same directory so they never share a
-socket with a live worker.
-
-## Cloud setup
-
-Unattended grok auth uses the `XAI_API_KEY` environment variable. Install the
-CLI via the vendor curl installer or the `@xai-official/grok` package. Keep
-agent definitions and hook config in parity with `npx claude-dev-env` so the
-preflight role-agent check and local `~/.claude` layout match what the worker
-expects.
-
-Use placeholders for account-specific values; do not hardcode personal paths or
-keys in skills or docs.
-
-## GitHub transport
-
-`pr-loop-cloud-transport` is a separate axis. This utility never posts reviews,
-opens PRs, or substitutes `gh` for MCP. GitHub reachability and cloud session
-routing stay outside the worker-spawn contract.

package/hooks/blocking/ask_user_question_shape_blocker.py

@@ -1,83 +0,0 @@
-#!/usr/bin/env python3
-"""PreToolUse hook that enforces AskUserQuestion field shape."""
-
-from __future__ import annotations
-
-import json
-import sys
-from collections.abc import Mapping, Sequence
-from pathlib import Path
-
-_hooks_dir = str(Path(__file__).resolve().parent.parent)
-if _hooks_dir not in sys.path:
-    sys.path.insert(0, _hooks_dir)
-
-from hooks_constants.ask_user_question_shape import (  # noqa: E402
-    analyze_ask_user_question_shape,
-)
-from hooks_constants.ask_user_question_shape_constants import (  # noqa: E402
-    ASK_USER_QUESTION_TOOL_NAME,
-    LEAN_QUESTION_BLOCK_GUIDANCE,
-    LEAN_QUESTION_BLOCK_PREFIX,
-    LEAN_QUESTION_VIOLATION_SEPARATOR,
-    USER_FACING_LEAN_QUESTION_NOTICE,
-)
-from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
-
-
-def build_lean_block_reason(all_violations: Sequence[str]) -> str:
-    """Build a deny reason that names each field-shape violation."""
-    violation_list = LEAN_QUESTION_VIOLATION_SEPARATOR.join(all_violations)
-    return f"{LEAN_QUESTION_BLOCK_PREFIX}{violation_list}. {LEAN_QUESTION_BLOCK_GUIDANCE}"
-
-
-def evaluate(payload_by_key: Mapping[str, object]) -> str | None:
-    """Return a deny reason when an AskUserQuestion payload breaks field shape."""
-    tool_name = payload_by_key.get("tool_name", "")
-    tool_input = payload_by_key.get("tool_input", {})
-    if tool_name != ASK_USER_QUESTION_TOOL_NAME:
-        return None
-    if not isinstance(tool_input, Mapping):
-        return None
-    shape_result = analyze_ask_user_question_shape(tool_input)
-    if shape_result.is_lean:
-        return None
-    return build_lean_block_reason(shape_result.all_violations)
-
-
-def build_deny_payload(deny_reason: str) -> dict[str, object]:
-    """Build the standard PreToolUse deny payload for a shape violation."""
-    log_hook_block(
-        calling_hook_name="ask_user_question_shape_blocker.py",
-        hook_event="PreToolUse",
-        block_reason=deny_reason,
-    )
-    return {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "permissionDecisionReason": deny_reason,
-        },
-        "systemMessage": USER_FACING_LEAN_QUESTION_NOTICE,
-        "suppressOutput": True,
-    }
-
-
-def main() -> None:
-    """Read one PreToolUse payload and deny malformed question shape."""
-    try:
-        payload_by_key = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    if not isinstance(payload_by_key, dict):
-        sys.exit(0)
-    deny_reason = evaluate(payload_by_key)
-    if deny_reason is None:
-        sys.exit(0)
-    sys.stdout.write(json.dumps(build_deny_payload(deny_reason)))
-    sys.stdout.flush()
-
-
-if __name__ == "__main__":
-    main()

package/hooks/blocking/bot_mention_comment_blocker.py

@@ -1,76 +0,0 @@
-#!/usr/bin/env python3
-"""PreToolUse hook: block @cursor or @copilot mentions in add_issue_comment body.
-
-Bugbot trigger requires exactly ``bugbot run`` with no other text. Copilot review
-requires the GitHub REST API endpoint, not an issue comment mention. This hook
-catches both mistakes and returns the correct procedure for each.
-"""
-
-import json
-import sys
-from pathlib import Path
-
-_hooks_dir = str(Path(__file__).resolve().parent.parent)
-if _hooks_dir not in sys.path:
-    sys.path.insert(0, _hooks_dir)
-
-from hooks_constants.bot_mention_comment_blocker_constants import (  # noqa: E402
-    COPILOT_MENTION_TOKEN,
-    CORRECTIVE_MESSAGE_COPILOT,
-    CORRECTIVE_MESSAGE_CURSOR,
-    CURSOR_MENTION_TOKEN,
-    TOOL_NAME,
-)
-from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
-
-
-def _body_contains_token(body: str, token: str) -> bool:
-    return token.lower() in body.lower()
-
-
-def _detect_bot_mention(body: str) -> str | None:
-    """Return corrective message if body contains a blocked mention, else None."""
-    if _body_contains_token(body, COPILOT_MENTION_TOKEN):
-        return CORRECTIVE_MESSAGE_COPILOT
-    if _body_contains_token(body, CURSOR_MENTION_TOKEN):
-        return CORRECTIVE_MESSAGE_CURSOR
-    return None
-
-
-def main() -> None:
-    try:
-        hook_input = json.load(sys.stdin)
-    except json.JSONDecodeError:
-        sys.exit(0)
-
-    if hook_input.get("tool_name", "") != TOOL_NAME:
-        sys.exit(0)
-
-    body = hook_input.get("tool_input", {}).get("body", "")
-    if not body:
-        sys.exit(0)
-
-    corrective_message = _detect_bot_mention(body)
-    if corrective_message is None:
-        sys.exit(0)
-
-    deny_payload = {
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "permissionDecisionReason": corrective_message,
-        }
-    }
-    log_hook_block(
-        calling_hook_name="bot_mention_comment_blocker.py",
-        hook_event="PreToolUse",
-        block_reason=corrective_message,
-        tool_name=TOOL_NAME,
-    )
-    print(json.dumps(deny_payload))
-    sys.stdout.flush()
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()

package/hooks/blocking/claude_md_orphan_file_blocker.py

@@ -1,129 +0,0 @@
-#!/usr/bin/env python3
-"""PreToolUse hook: blocks a per-directory CLAUDE.md that names a file absent from its subtree.
-
-A per-directory ``CLAUDE.md`` documents the files reachable from its own
-directory in a markdown table whose first column names each file in backticks,
-and shows run commands inside fenced code blocks that invoke those files. When a
-first-column cell, or an interpreter invocation inside a fenced run command
-(``python script.py``), names a bare filename that exists nowhere under the scan
-root (the CLAUDE.md directory's parent, which covers the directory, its
-subdirectories, and its siblings), the doc points a reader at a file that is not
-there. This hook fires on Write, Edit, and MultiEdit targeting a file named
-``CLAUDE.md`` and blocks the write when any such cell or run command names a file
-absent from the scan root. A table block or a run-command fence whose own region
-declares an explicit relative-path source (a ``../`` token, in the rows/fence or
-the prose that introduces it) documents files outside the subtree, so that block's
-rows or that fence's commands are left alone — the exemption is scoped to the
-region, not the whole file.
-"""
-
-import sys
-from pathlib import Path
-
-try:
-    _hooks_root_directory = str(Path(__file__).resolve().parent.parent)
-    _blocking_directory = str(Path(__file__).resolve().parent)
-    for each_bootstrap_directory in (_hooks_root_directory, _blocking_directory):
-        if each_bootstrap_directory not in sys.path:
-            sys.path.insert(0, each_bootstrap_directory)
-    from claude_md_orphan_file_blocker_parts import (
-        decision,
-        references,
-        scan_plan,
-        subtree_scan,
-    )
-    from claude_md_orphan_file_blocker_parts.subtree_scan import (
-        MAX_SUBTREE_FILES_SCANNED,  # noqa: F401
-    )
-    from inventory_intent_records import records
-
-    from hooks_constants.pre_tool_use_stdin import (
-        read_hook_input_dictionary_from_stdin,
-    )
-except ImportError as import_error:
-    raise ImportError(
-        "claude_md_orphan_file_blocker: cannot import its parts submodules; "
-        "ensure the hooks directory is importable."
-    ) from import_error
-
-
-is_claude_md_file = references.is_claude_md_file
-find_referenced_filenames = references.find_referenced_filenames
-find_run_command_filenames = references.find_run_command_filenames
-find_missing_filenames = subtree_scan.find_missing_filenames
-build_orphan_scan_plan = scan_plan.build_orphan_scan_plan
-collect_missing_filenames = scan_plan.collect_missing_filenames
-deny_orphan_files = decision.deny_orphan_files
-
-
-def _partition_by_file_intent(
-    session_id: str, directory: str, all_missing_filenames: list[str]
-) -> tuple[list[str], list[str]]:
-    """Split missing filenames into those with a pending file intent and those without."""
-    matched_filenames = [
-        each_filename
-        for each_filename in all_missing_filenames
-        if records.has_fresh_file_intent(session_id, directory, each_filename)
-    ]
-    unmatched_filenames = [
-        each_filename
-        for each_filename in all_missing_filenames
-        if each_filename not in matched_filenames
-    ]
-    return matched_filenames, unmatched_filenames
-
-
-def _emit_orphan_decision(
-    input_data: dict,
-    tool_name: str,
-    file_path: str,
-    directory: str,
-    all_missing_filenames: list[str],
-) -> None:
-    """Consume covered rows and deny any genuine orphan the change introduces."""
-    session_id = str(input_data.get("session_id") or "")
-    matched_filenames, unmatched_filenames = _partition_by_file_intent(
-        session_id, directory, all_missing_filenames
-    )
-    if unmatched_filenames:
-        for each_filename in unmatched_filenames:
-            records.record_row_intent(session_id, directory, each_filename)
-        deny_orphan_files(tool_name, file_path, directory, unmatched_filenames)
-        return
-    for each_filename in matched_filenames:
-        records.consume_file_intent(session_id, directory, each_filename)
-
-
-def main() -> None:
-    """Read the PreToolUse payload from stdin and block an orphan-file CLAUDE.md."""
-    input_data = read_hook_input_dictionary_from_stdin()
-    if input_data is None:
-        sys.exit(0)
-    tool_name = input_data.get("tool_name", "")
-    if not isinstance(tool_name, str):
-        sys.exit(0)
-    tool_input = input_data.get("tool_input", {})
-    if not isinstance(tool_input, dict):
-        sys.exit(0)
-    if tool_name not in ("Write", "Edit", "MultiEdit"):
-        sys.exit(0)
-    file_path = tool_input.get("file_path", "")
-    if not isinstance(file_path, str) or not is_claude_md_file(file_path):
-        sys.exit(0)
-    claude_md_directory = Path(file_path).resolve().parent
-    if not claude_md_directory.is_dir():
-        sys.exit(0)
-    scan_plan_result = build_orphan_scan_plan(tool_name, tool_input, file_path, claude_md_directory)
-    if not scan_plan_result.candidate_contents:
-        sys.exit(0)
-    missing_filenames = collect_missing_filenames(scan_plan_result, claude_md_directory)
-    if not missing_filenames:
-        sys.exit(0)
-    _emit_orphan_decision(
-        input_data, tool_name, file_path, str(claude_md_directory), missing_filenames
-    )
-    sys.exit(0)
-
-
-if __name__ == "__main__":
-    main()