claude-dev-env 7.4.1 → 7.5.0

package/rules/verify-runtime-state.md

@@ -22,7 +22,7 @@ Before stating a runtime claim, gather the matching live signal:
 | The config is in effect | Print the loaded config at runtime and read the value. |
 | The server is up | Probe the port; a refused connection means it is down. |
 | The process is running | List processes and match the name or PID. |
-| The change took effect | Drive the flow and watch the new behavior. |
+| The change took effect | Drive the flow and watch the new behavior. A script that proves a branch's behavior names the module file it loaded, as its first step, because an installed copy of the same package shadows the checkout you meant to test. |
 | The dependency is reachable | Send one real request and read the response. |
 | The release or deploy shipped | Read what it makes: the tag, the published version, the file on disk. |
 | The pipeline did the work | Read each job's own result. A run reports success while a job inside it is skipped. |

package/rules/windows-filesystem-safe.md

@@ -12,6 +12,6 @@ Never call `shutil.rmtree` with `ignore_errors=True` — Windows `ReadOnly` file
 
 In Node, call `mkdirSync(targetPath, { recursive: true })` on possibly-existing paths — `ReadOnly` directories break the non-recursive form. When the call must be non-recursive, strip the attribute first (`(Get-Item $path -Force).Attributes = "Directory"` / `os.chmod(path, stat.S_IWRITE)`).
 
-The `windows_rmtree_blocker.py` PreToolUse hook (Write/Edit/Bash) blocks the unsafe rmtree pattern and returns the full `force_rmtree` safe-pattern code.
+The staged policy lint carries this check as its `rmtree-safety` rule. It reports the unsafe rmtree pattern and returns the full `force_rmtree` safe-pattern code. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base.
 
-Define the safe handler trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`, and the `inspect.signature` onexc/onerror guard) once in a shared Windows-filesystem utility module, and import it from every call site. A second local copy drifts from the first — a fix lands in one and the other keeps the bug (CODE_RULES.md, CORE PRINCIPLES — "Reuse before create"). The `duplicate_rmtree_helper_blocker.py` PreToolUse hook (Write/Edit) blocks a local re-definition of any trio member outside the shared home and points the writer at the import. This complements the same-directory `check_duplicate_function_body_across_files` gate, which a copy between two distant packages slips past.
+Define the safe handler trio (`_strip_read_only_and_retry`, `_force_remove_tree` / `force_rmtree`, and the `inspect.signature` onexc/onerror guard) once in a shared Windows-filesystem utility module, and import it from every call site. A second local copy drifts from the first, so a fix lands in one and the other keeps the bug (CODE_RULES.md, CORE PRINCIPLES, "Reuse before create"). The same `rmtree-safety` lint rule reports a local re-definition of any trio member outside the shared home and points the writer at the import. This complements the same-directory `check_duplicate_function_body_across_files` check, which a copy between two distant packages slips past.

package/rules/workflow-substitution-slots.md

@@ -9,4 +9,4 @@ In a `.workflow.js` agent-prompt template, every per-call or per-iteration value
 
 When a loop builds a per-iteration path or output key, write the index as a slot — `cand_<i>` — or spell out `replace <i> with the iteration index 0, 1, 2` in the step text. Every per-call value in a `.workflow.js` template carries angle brackets so an agent fills in a fresh value per call.
 
-`workflow_substitution_slot_blocker.py` (PreToolUse on Write/Edit) blocks a `.workflow.js` write whose looped content carries a bare `<word>_<i|j|k>` token as a per-iteration path segment, and returns the corrective message.
+The staged policy lint carries this check as its `workflow-substitution` rule. It reports a `.workflow.js` file whose looped content holds a bare `<word>_<i|j|k>` token as a per-iteration path segment. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base. No write-time hook reports this, so a bare token stays on disk until the lint runs.

package/scripts/durable_post_lint_config/config/constants.py

@@ -55,10 +55,7 @@ CONVENTIONAL_TITLE_PATTERN: re.Pattern[str] = re.compile(
     rf"^(?:{'|'.join(ALL_CONVENTIONAL_TITLE_TYPES)})(?:\([^)\r\n]+\))?!?: [^\s].*$"
 )
 ALL_REQUIRED_PR_DESCRIPTION_HEADINGS: tuple[str, ...] = (
-    "Summary",
-    "Description",
     "Why",
-    "How",
     "Verification",
 )
 ALL_PATH_ANCHORED_VOLATILE_PATH_MARKERS: tuple[str, ...] = (

package/scripts/durable_post_lint_config/config/test_constants.py

@@ -4,6 +4,7 @@ from durable_post_lint_config.config.constants import (
     ALL_CONVENTIONAL_TITLE_TYPES,
     ALL_POST_ACTIONS,
     ALL_RELEASE_BODY_MARKERS,
+    ALL_REQUIRED_PR_DESCRIPTION_HEADINGS,
     CONVENTIONAL_TITLE_PATTERN,
     RELEASE_BRANCH_PREFIX,
 )
@@ -36,3 +37,7 @@ def should_carry_both_markers_release_automation_writes() -> None:
 
 def should_name_the_branch_prefix_release_automation_pushes() -> None:
     assert RELEASE_BRANCH_PREFIX == "release-please--branches--"
+
+
+def should_require_only_the_headings_both_pull_request_rule_sets_name() -> None:
+    assert ALL_REQUIRED_PR_DESCRIPTION_HEADINGS == ("Why", "Verification")

package/scripts/policy_lint/adapter_configuration.py

@@ -121,7 +121,31 @@ def _registered_nested_strings(each_entry: object) -> tuple[str, ...]:
     return tuple(all_registered_strings)
 
 
+def _names_exempt_registration_path(registered_string: str) -> bool:
+    """Return True when the registration names a chain that decides no policy.
+
+    ::
+
+        hooks/blocking/bash_pre_tool_use_dispatcher.py   -> exempt
+        hooks/blocking/some_new_blocker.py               -> flagged
+
+    The Bash PreToolUse dispatcher sits under ``blocking/`` for layout reasons
+    while its roster hosts one allow-and-rewrite hook. Its path segment reads as
+    a policy boundary that the chain never carries.
+
+    Args:
+        registered_string: One command, path, script, or entrypoint string.
+    """
+    path_shaped_string = registered_string.lower().replace("\\", "/")
+    return any(
+        each_exempt_path in path_shaped_string
+        for each_exempt_path in constants.ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS
+    )
+
+
 def _contains_action_boundary_marker(registered_string: str) -> bool:
+    if _names_exempt_registration_path(registered_string):
+        return False
     normalized_string = registered_string.lower().replace("\\", "/")
     normalized_string = normalized_string.replace(".", "/").replace("-", "/")
     return any(

package/scripts/policy_lint/adapter_retired_hook_prose.py

@@ -0,0 +1,201 @@
+"""Detect rules prose that credits a hook module which runs nowhere.
+
+A hook module runs when ``hooks/hooks.json`` registers it or a dispatcher
+roster hosts it. A module that survives on disk while appearing in neither
+one reaches no tool call, so prose that gives it a present-tense action
+describes a gate the reader never faces.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path, PurePosixPath
+
+from .config import constants
+from .model import Diagnostic, Document, Location, Severity
+
+
+def accepts_rules_markdown(document: Document) -> bool:
+    """Return whether the document is Markdown in a rules directory.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for a Markdown file directly under a ``rules`` directory.
+    """
+    return (
+        document.path.suffix.lower() in constants.ALL_MARKDOWN_SUFFIXES
+        and document.path.parent.name == constants.RULES_DIRECTORY_NAME
+    )
+
+
+def _package_root(repository_root: Path, document: Document) -> Path:
+    return repository_root / document.path.parent.parent.as_posix()
+
+
+def _read_text(path: Path) -> str:
+    if not path.is_file():
+        return ""
+    return path.read_text(
+        encoding="utf-8", errors=constants.REPLACEMENT_CHARACTER_ERRORS
+    )
+
+
+def _registered_hook_stems(hooks_root: Path) -> frozenset[str]:
+    all_stems = set(
+        re.findall(
+            constants.HOOKS_JSON_PATH_PATTERN,
+            _read_text(hooks_root / constants.HOOKS_CONFIGURATION_FILE_NAME),
+        )
+    )
+    constants_root = hooks_root / constants.HOOK_CONSTANTS_DIRECTORY_NAME
+    if constants_root.is_dir():
+        for each_path in sorted(
+            constants_root.glob(constants.DISPATCHER_CONSTANTS_GLOB)
+        ):
+            all_stems.update(
+                PurePosixPath(each_relative_path).stem
+                for each_relative_path in re.findall(
+                    constants.QUOTED_HOOK_PATH_PATTERN, _read_text(each_path)
+                )
+            )
+    return frozenset(all_stems)
+
+
+def _present_hook_stems(hooks_root: Path) -> frozenset[str]:
+    if not hooks_root.is_dir():
+        return frozenset()
+    return frozenset(
+        each_path.stem for each_path in hooks_root.rglob(constants.PYTHON_GLOB)
+    )
+
+
+def _retired_roster_stems(package_root: Path) -> frozenset[str]:
+    installer_path = package_root.joinpath(*constants.ALL_INSTALLER_PATH_SEGMENTS)
+    maybe_roster = re.search(
+        constants.RETIRED_ROSTER_PATTERN, _read_text(installer_path)
+    )
+    if maybe_roster is None:
+        return frozenset()
+    return frozenset(
+        PurePosixPath(each_relative_path).stem
+        for each_relative_path in re.findall(
+            constants.QUOTED_HOOK_PATH_PATTERN, maybe_roster.group(1)
+        )
+    )
+
+
+def _hook_stem_in_span(span_text: str) -> str | None:
+    candidate_name = (
+        span_text.strip()
+        .rsplit(constants.PATH_SEPARATOR, 1)[-1]
+        .removesuffix(constants.PYTHON_SUFFIX)
+    )
+    if not re.fullmatch(constants.HOOK_MODULE_NAME_PATTERN, candidate_name):
+        return None
+    if not candidate_name.endswith(constants.ALL_HOOK_MODULE_NAME_SUFFIXES):
+        return None
+    return candidate_name
+
+
+def _names_a_live_action(segment_text: str) -> bool:
+    return any(
+        each_word in constants.ALL_LIVE_CLAIM_VERBS
+        for each_word in re.findall(
+            constants.PROSE_WORD_PATTERN, segment_text.lower()
+        )
+    )
+
+
+def _describes_a_replacement(line_text: str) -> bool:
+    normalized_line = line_text.lower()
+    return any(
+        each_phrase in normalized_line
+        for each_phrase in constants.ALL_REPLACEMENT_DELIVERY_PHRASES
+    )
+
+
+def _claim_segment_end(
+    line_text: str, all_spans: tuple[re.Match[str], ...], span_index: int
+) -> int:
+    maybe_sentence_end = re.compile(constants.SENTENCE_BOUNDARY_PATTERN).search(
+        line_text, all_spans[span_index].end()
+    )
+    segment_end = (
+        len(line_text) if maybe_sentence_end is None else maybe_sentence_end.start()
+    )
+    for each_span in all_spans[span_index + 1 :]:
+        if each_span.start() >= segment_end:
+            break
+        if _hook_stem_in_span(each_span.group(1)) is not None:
+            return each_span.start()
+    return segment_end
+
+
+def _line_diagnostics(
+    document: Document,
+    line_text: str,
+    line_number: int,
+    all_known_stems: frozenset[str],
+    all_registered_stems: frozenset[str],
+) -> tuple[Diagnostic, ...]:
+    all_spans = tuple(re.finditer(constants.INLINE_CODE_PATTERN, line_text))
+    all_diagnostics: list[Diagnostic] = []
+    for each_index, each_span in enumerate(all_spans):
+        maybe_stem = _hook_stem_in_span(each_span.group(1))
+        if maybe_stem is None or maybe_stem not in all_known_stems:
+            continue
+        if maybe_stem in all_registered_stems:
+            continue
+        claim_end = _claim_segment_end(line_text, all_spans, each_index)
+        if not _names_a_live_action(line_text[each_span.end() : claim_end]):
+            continue
+        all_diagnostics.append(
+            Diagnostic(
+                constants.RETIRED_HOOK_PROSE_RULE_ID,
+                Severity.ERROR,
+                constants.RETIRED_HOOK_PROSE_MESSAGE.format(hook_name=maybe_stem),
+                Location(document.path, line_number, each_span.start() + 1),
+            )
+        )
+    return tuple(all_diagnostics)
+
+
+def _hook_stem_sets(package_root: Path) -> tuple[frozenset[str], frozenset[str]]:
+    hooks_root = package_root / constants.HOOKS_DIRECTORY_NAME
+    all_known_stems = _present_hook_stems(hooks_root) | _retired_roster_stems(
+        package_root
+    )
+    return all_known_stems, _registered_hook_stems(hooks_root)
+
+
+def retired_hook_prose_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Report rules prose that credits an unregistered hook with a live action.
+
+    Args:
+        document: Current rules Markdown text and path.
+        repository_root: Request repository root for package resolution.
+
+    Returns:
+        One diagnostic for each live claim about a hook that runs nowhere.
+    """
+    all_known_stems, all_registered_stems = _hook_stem_sets(
+        _package_root(repository_root, document)
+    )
+    all_diagnostics: list[Diagnostic] = []
+    for each_line_number, each_line in enumerate(document.text.splitlines(), 1):
+        if _describes_a_replacement(each_line):
+            continue
+        all_diagnostics.extend(
+            _line_diagnostics(
+                document,
+                each_line,
+                each_line_number,
+                all_known_stems,
+                all_registered_stems,
+            )
+        )
+    return tuple(all_diagnostics)

package/scripts/policy_lint/adapters.py

@@ -8,7 +8,13 @@ from types import ModuleType
 
 from shared_tree_paths import resolve_shared_scripts_directory
 
-from . import adapter_configuration, adapter_detectors, adapter_pairing, adapter_support
+from . import (
+    adapter_configuration,
+    adapter_detectors,
+    adapter_pairing,
+    adapter_retired_hook_prose,
+    adapter_support,
+)
 from .config import constants
 from .model import Diagnostic, Document, DocumentSet
 
@@ -377,3 +383,32 @@ def accepts_plans(document: Document) -> bool:
             )
         )
     )
+
+
+def accepts_rules_markdown(document: Document) -> bool:
+    """Return whether the document is Markdown in a rules directory.
+
+    Args:
+        document: Candidate document.
+
+    Returns:
+        True for a Markdown file directly under a ``rules`` directory.
+    """
+    return adapter_retired_hook_prose.accepts_rules_markdown(document)
+
+
+def retired_hook_prose_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Report rules prose that credits an unregistered hook with a live action.
+
+    Args:
+        document: Current rules Markdown text and path.
+        repository_root: Request repository root for package resolution.
+
+    Returns:
+        Retired-hook prose diagnostics.
+    """
+    return adapter_retired_hook_prose.retired_hook_prose_diagnostics(
+        document, repository_root
+    )

package/scripts/policy_lint/config/constants.py

@@ -57,6 +57,9 @@ ALL_ACTION_BOUNDARY_SEGMENTS = frozenset(
     }
 )
 ALL_ACTION_BOUNDARY_PREFIXES = ("deny_", "block_", "ask_")
+ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
+    "blocking/bash_pre_tool_use_dispatcher.py",
+)
 ALL_TEST_DIRECTORY_NAMES = frozenset({"tests"})
 ALL_TEST_FILE_PREFIXES = ("test_",)
 ALL_TEST_FILE_SUFFIXES = ("_test.py",)
@@ -80,3 +83,74 @@ TERMINOLOGY_MESSAGE_GROUP = "message"
 
 PR_LOOP_DIRECTORY_NAME = "pr-loop"
 SHARED_ROOT_PARENT_INDEX = 2
+
+RETIRED_HOOK_PROSE_RULE_ID = "retired-hook-prose"
+RULES_DIRECTORY_NAME = "rules"
+HOOKS_DIRECTORY_NAME = "hooks"
+HOOKS_CONFIGURATION_FILE_NAME = "hooks.json"
+HOOK_CONSTANTS_DIRECTORY_NAME = "hooks_constants"
+DISPATCHER_CONSTANTS_GLOB = "*dispatcher_constants.py"
+ALL_INSTALLER_PATH_SEGMENTS = ("bin", "install.mjs")
+PYTHON_GLOB = "*.py"
+REPLACEMENT_CHARACTER_ERRORS = "replace"
+ALL_HOOK_MODULE_NAME_SUFFIXES = (
+    "_advisor",
+    "_blocker",
+    "_dispatcher",
+    "_enforcer",
+    "_gate",
+    "_guard",
+    "_recorder",
+    "_rewriter",
+    "_tracker",
+    "_validator",
+)
+ALL_LIVE_CLAIM_VERBS = frozenset(
+    {
+        "allows",
+        "applies",
+        "blocks",
+        "catches",
+        "checks",
+        "denies",
+        "enforces",
+        "fires",
+        "flags",
+        "gates",
+        "hosts",
+        "matches",
+        "prevents",
+        "reads",
+        "records",
+        "refuses",
+        "rejects",
+        "reports",
+        "requires",
+        "runs",
+        "scans",
+        "stops",
+        "watches",
+    }
+)
+ALL_REPLACEMENT_DELIVERY_PHRASES = (
+    "staged policy lint",
+    "policy lint",
+    "cde_lint",
+    "repository_checks/",
+    "repository_policy.py",
+    "repository check",
+)
+INLINE_CODE_PATTERN = r"`([^`\n]+)`"
+HOOK_MODULE_NAME_PATTERN = r"[a-z_][a-z0-9_]*"
+PROSE_WORD_PATTERN = r"[a-z]+"
+RETIRED_ROSTER_PATTERN = (
+    r"(?s)RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS\s*=\s*new Set\(\[(.*?)\]\)"
+)
+QUOTED_HOOK_PATH_PATTERN = r"['\"]([a-z_]+/[a-z_0-9]+\.py)['\"]"
+HOOKS_JSON_PATH_PATTERN = r"hooks/[a-z_]+/([a-z_0-9]+)\.py"
+SENTENCE_BOUNDARY_PATTERN = r"[.!?](?:\s|$)"
+RETIRED_HOOK_PROSE_MESSAGE = (
+    "{hook_name} is named by no hooks.json entry and no dispatcher roster, so it "
+    "reaches no tool call. Say what the reader faces now, or drop the "
+    "present-tense action."
+)

package/scripts/policy_lint/registry.py

@@ -104,6 +104,11 @@ def _text_document_rules() -> tuple[model.Rule, ...]:
             adapters.accepts_workflow,
             adapters.workflow_substitution_diagnostics,
         ),
+        build_document_rule(
+            "retired-hook-prose",
+            adapters.accepts_rules_markdown,
+            adapters.retired_hook_prose_diagnostics,
+        ),
     )
 
 

package/scripts/policy_lint/selection.py

@@ -18,6 +18,7 @@ from .model import (
     TextDocument,
 )
 from .selection_git import (
+    GitBlobItemBlocked,
     GitSelectionError,
     git_bytes_for,
     head_revision,
@@ -30,6 +31,10 @@ class SelectionRunFatal(ValueError):
     """Raised when a source selection cannot be resolved safely."""
 
 
+class SelectionItemBlocked(ValueError):
+    """Raised when one file holds bytes that are not a policy document."""
+
+
 SelectionError = SelectionRunFatal
 
 
@@ -54,9 +59,7 @@ def select_documents(request: LintRequest) -> DocumentSet:
 
 def _select_source(repository_root: Path, source: object) -> DocumentSet:
     if isinstance(source, ExplicitFiles):
-        all_documents = tuple(
-            _worktree_document(repository_root, each_path) for each_path in source.paths
-        )
+        all_documents = _explicit_documents(repository_root, source.paths)
         return DocumentSet(all_documents, SelectionKind.FILES, repository_root)
     if isinstance(source, StagedChanges):
         return _select_changes(repository_root, True, None)
@@ -89,13 +92,28 @@ def _validated_repository_root(repository_root: Path) -> Path:
     return resolved_root
 
 
+def _explicit_documents(
+    repository_root: Path, all_paths: tuple[Path, ...]
+) -> tuple[Document, ...]:
+    all_documents: list[Document] = []
+    for each_path in all_paths:
+        try:
+            all_documents.append(_worktree_document(repository_root, each_path))
+        except SelectionItemBlocked:
+            continue
+    return tuple(all_documents)
+
+
 def _select_repository_tree(repository_root: Path) -> DocumentSet:
-    all_documents = tuple(
-        _tracked_worktree_document(repository_root, each_path)
-        for each_path in _tracked_paths(repository_root)
-        if (repository_root / each_path).is_file()
-    )
-    return DocumentSet(all_documents, SelectionKind.REPOSITORY, repository_root)
+    all_documents: list[Document] = []
+    for each_path in _tracked_paths(repository_root):
+        if not (repository_root / each_path).is_file():
+            continue
+        try:
+            all_documents.append(_tracked_worktree_document(repository_root, each_path))
+        except SelectionItemBlocked:
+            continue
+    return DocumentSet(tuple(all_documents), SelectionKind.REPOSITORY, repository_root)
 
 
 def _tracked_worktree_document(repository_root: Path, raw_path: str) -> Document:
@@ -189,13 +207,16 @@ def _append_change(
     old_path, new_path = all_paths if status[:1] in {"R", "C"} else (all_paths[0], all_paths[0])
     normalized_old_path = _normalize_path(repository_root, old_path)
     normalized_new_path = _normalize_path(repository_root, new_path)
-    document = _change_document(
-        repository_root, old_path, new_path, normalized_old_path,
-        normalized_new_path, is_staged, base_revision, status,
-    )
-    if document is None:
+    if status == "D":
         all_deleted_paths.append(normalized_old_path)
         return
+    try:
+        document = _change_document(
+            repository_root, old_path, new_path, normalized_old_path,
+            normalized_new_path, is_staged, base_revision, status,
+        )
+    except (SelectionItemBlocked, GitBlobItemBlocked):
+        return
     all_documents.append(document)
     if document.prior_path is not None:
         all_renamed_paths.append((normalized_old_path, normalized_new_path))
@@ -210,9 +231,7 @@ def _change_document(
     is_staged: bool,
     base_revision: str | None,
     status: str,
-) -> Document | None:
-    if status == "D":
-        return None
+) -> Document:
     is_copy = status[:1] == "C"
     is_rename = status[:1] == "R"
     prior_text = _change_prior_text(
@@ -274,7 +293,7 @@ def _read_worktree_text(file_path: Path) -> str:
     try:
         return file_path.read_bytes().decode(constants.UTF8_ENCODING)
     except UnicodeDecodeError as error:
-        raise SelectionRunFatal(f"File is not UTF-8: {file_path}") from error
+        raise SelectionItemBlocked(f"File is not UTF-8: {file_path}") from error
     except OSError as error:
         raise SelectionRunFatal(f"File cannot be read: {file_path}") from error
 

package/scripts/policy_lint/selection_git.py

@@ -21,6 +21,10 @@ class GitSelectionError(ValueError):
     """Raised when Git cannot provide the requested source bytes."""
 
 
+class GitBlobItemBlocked(GitSelectionError):
+    """Raised when one Git blob holds bytes that are not UTF-8 text."""
+
+
 def git_bytes_for(repository_root: Path, all_arguments: tuple[str, ...]) -> bytes:
     """Run a fixed Git argument vector and return raw stdout bytes.
 
@@ -89,7 +93,7 @@ def read_blob(repository_root: Path, revision: str, relative_path: str) -> str |
         Decoded blob text, or None when the blob is absent.
 
     Raises:
-        GitSelectionError: If the blob is not UTF-8.
+        GitBlobItemBlocked: If the blob is not UTF-8.
     """
     blob_bytes = _read_blob_bytes(repository_root, revision, relative_path)
     if blob_bytes is None:
@@ -97,7 +101,7 @@ def read_blob(repository_root: Path, revision: str, relative_path: str) -> str |
     try:
         return blob_bytes.decode(UTF8_ENCODING)
     except UnicodeDecodeError as error:
-        raise GitSelectionError(f"Git blob is not UTF-8: {relative_path}") from error
+        raise GitBlobItemBlocked(f"Git blob is not UTF-8: {relative_path}") from error
 
 
 def _git_subprocess_environment() -> dict[str, str]:

package/scripts/test_durable_post_lint.py

@@ -15,21 +15,29 @@ if str(_SCRIPTS_DIRECTORY) not in sys.path:
 import durable_post_lint
 
 SCRIPT_PATH = _SCRIPTS_DIRECTORY / "durable_post_lint.py"
-VALID_PR_BODY = """## Summary
+VALID_PR_BODY = """## Why
 
-Summary text.
+Why text.
 
-## Description
+## Scope
 
-Description text.
+Scope text.
 
-## Why
+## Tradeoffs
 
-Why text.
+Tradeoffs text.
+
+## Blast Radius
+
+Blast radius text.
+
+## Verification
 
-## How
+Verification text.
+"""
+MINIMAL_PR_BODY = """## Why
 
-How text.
+Why text.
 
 ## Verification
 
@@ -156,7 +164,7 @@ def test_pr_titles_reject_nonconventional_forms(title: str) -> None:
 
 @pytest.mark.parametrize(
     "missing_heading",
-    ["Summary", "Description", "Why", "How", "Verification"],
+    durable_post_lint.ALL_REQUIRED_PR_DESCRIPTION_HEADINGS,
 )
 def test_pr_body_reports_each_missing_heading(missing_heading: str) -> None:
     body_text = VALID_PR_BODY.replace(f"## {missing_heading}\n", "")
@@ -170,6 +178,31 @@ def test_pr_body_reports_each_missing_heading(missing_heading: str) -> None:
     ]
 
 
+@pytest.mark.parametrize("action", ["pr-create", "pr-edit"])
+def should_accept_a_body_carrying_only_the_two_required_headings(action: str) -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action=action,
+        title="fix(cli): tighten input handling",
+        body_text=MINIMAL_PR_BODY,
+    )
+    assert all_findings == ()
+
+
+def should_still_accept_a_body_published_under_the_superseded_heading_set() -> None:
+    all_findings = durable_post_lint.lint_durable_post(
+        action="pr-edit",
+        title=None,
+        body_text=(
+            "## Summary\n\nSummary text.\n\n"
+            "## Description\n\nDescription text.\n\n"
+            "## Why\n\nWhy text.\n\n"
+            "## How\n\nHow text.\n\n"
+            "## Verification\n\nVerification text.\n"
+        ),
+    )
+    assert all_findings == ()
+
+
 def test_non_pr_body_needs_no_pr_headings() -> None:
     all_findings = durable_post_lint.lint_durable_post(
         action="issue-comment",

package/scripts/tests/test_adapter_configuration.py

@@ -42,6 +42,14 @@ def test_incremental_blocker_removal_is_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_bash_pre_tool_use_dispatcher_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/bash_pre_tool_use_dispatcher.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_blocker_in_staged_change_is_rejected(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/new.py"],