claude-dev-env 7.4.0 → 7.5.0

package/rules/no-cross-skill-duplicate-helpers.md

@@ -8,7 +8,7 @@ paths: "**/skills/*/scripts/**/*.py"
 
 ## The two duplication cases differ
 
-CODE_RULES "Reuse before create" / DRY says one helper lives in one home and both call sites import it. That rule is blocking **within one skill** — two `.py` modules in the same skill's `scripts/` directory that carry the same top-level function body fail the `code_rules_duplicate_body` gate, and the fix is a shared module both import.
+CODE_RULES "Reuse before create" / DRY says one helper lives in one home and both call sites import it. That rule is enforced **within one skill**. Two `.py` modules in the same skill's `scripts/` directory that carry the same top-level function body fail the `code_rules_duplicate_body` check, which the staged policy lint runs through `code_rules_enforcer.py`. The fix is a shared module both import.
 
 Across **two skill folders** the same copy is a different call. Each skill folder installs on its own, so a shared module would couple two skills the install model keeps separate: deleting or reinstalling one skill would break a helper the other depends on. A small launch helper copied into each skill (for example a Chrome-open helper that reads the registry and runs `chrome.exe`) is a defensible skill-isolation tradeoff, not a regression.
 
@@ -16,14 +16,14 @@ Across **two skill folders** the same copy is a different call. Each skill folde
 
 Before you copy a top-level helper from one skill's `scripts/` directory into another:
 
-- **Same skill, two modules** — extract one shared module in that skill and import it from both. The `code_rules_duplicate_body` gate blocks the copy.
-- **Two skill folders, a small self-contained helper** — copy it; the skill-isolation tradeoff stands. A non-blocking `[CODE_RULES advisory]` names the source skill at Write time so the copy is a deliberate choice on record, not an oversight.
+- **Same skill, two modules.** Extract one shared module in that skill and import it from both. The `code_rules_duplicate_body` check reports the copy.
+- **Two skill folders, a small self-contained helper.** Copy it, and the skill-isolation tradeoff stands. An advisory `[CODE_RULES advisory]` line names the source skill when the lint runs, so the copy is a deliberate choice on record, not an oversight.
 - **Two skill folders, a large or behavior-bearing body** — when the copied body is large, holds business logic, or would drift in a way that changes behavior, raise the choice through `AskUserQuestion`: copy and accept drift, or stand up a shared dependency both skills declare (for example a published package both `requirements` files name, or a `_shared` module the install step writes into each skill). A shared dependency that survives independent install is the only shared-home path that does not break the install model.
 
 ## What the advisory tells you
 
-The `advise_cross_skill_duplicate_helper` check in `code_rules_duplicate_body` prints to stderr (never blocks) when a top-level function in the file being written has the same normalized body as a top-level function in another skill's `scripts/` directory. The message names the source skill and function so a reviewer can confirm the copy was intentional. It fires only across skill folders; within one skill the blocking gate already covers the copy.
+The `advise_cross_skill_duplicate_helper` check in `code_rules_duplicate_body` prints to stderr (never fails the lint) when a top-level function in a changed file has the same normalized body as a top-level function in another skill's `scripts/` directory. The message names the source skill and function so a reviewer can confirm the copy was intentional. It fires only across skill folders. Within one skill the reporting check already covers the copy.
 
-## Why this is a rule, not a wider gate
+## Why this is a rule, not a wider check
 
-Extending the blocking duplicate-body gate to span skill folders would deny the exact skill-isolation copy that keeps skills independently installable — a false positive on a sanctioned pattern. The boundary between "same skill, block" and "two skills, signal" is a judgment the writer makes with the source skill named in front of them. The rule states the judgment; the `[CODE_RULES advisory]` surfaces the signal; neither blocks the defensible copy.
+Extending the duplicate-body check to span skill folders would report the exact skill-isolation copy that keeps skills independently installable, a false positive on a sanctioned pattern. The boundary between "same skill, report" and "two skills, signal" is a judgment the writer makes with the source skill named in front of them. The rule states the judgment, and the `[CODE_RULES advisory]` line surfaces the signal. Neither one fails the defensible copy.

package/rules/orphan-css-class.md

@@ -13,16 +13,16 @@ Every class name a markup string references has a matching `.<class>` selector i
 
 When you add a `class="..."` attribute, add its `.<class>` selector to the `<style>` block in the same change. When you drop a selector, drop the class attribute it styled.
 
-## What the gate checks
+## What the check covers
 
-The `check_orphan_css_classes` check in `code_rules_orphan_css_class.py` (wired into `code_rules_enforcer.py`) runs on every production Python write. It:
+The `check_orphan_css_classes` check in `code_rules_orphan_css_class.py` reaches production Python through the staged policy lint, whose `code-rules` rule loads `code_rules_enforcer.py` and applies it to each changed file. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base. It:
 
 1. Collects each class name referenced in a `class="..."` attribute across the file's string literals.
 2. Collects each class selector defined in a `<style>` block — both in the file under edit and in every Python module beside it (its own directory and immediate child directories), since a markup module commonly imports its style constant from a companion package directory.
 3. Flags each referenced class with no matching selector in that whole set.
 
-The check stays quiet for a file that emits no `class="..."` markup, and for a file whose markup has no `<style>` source nearby (its stylesheet lives outside the scan, so the gate cannot judge it). Test files are exempt, since a fixture may carry intentional orphan markup.
+The check stays quiet for a file that emits no `class="..."` markup, and for a file whose markup has no `<style>` source nearby (its stylesheet lives outside the scan, so the check cannot judge it). Test files are exempt, since a fixture may carry intentional orphan markup.
 
-## Why this is a hook, not a lint pass
+## Why this check is mechanical
 
-A class attribute with no matching selector reads as styled but renders unstyled. Native elements such as `<details>` stay functional without CSS, so the gap survives review as a cosmetic defect rather than a crash — exactly the class of issue that slips past a manual pass and lands as a deferred code-standard finding. Catching it at Write time keeps the markup and the stylesheet in step as each line is written.
+A class attribute with no matching selector reads as styled but renders unstyled. Native elements such as `<details>` stay functional without CSS, so the gap survives review as a cosmetic defect rather than a crash. That is the class of issue a manual pass slips past, and it lands later as a deferred code-standard finding. Running the lint on every staged change keeps the markup and the stylesheet in step.

package/rules/paired-test-coverage.md

@@ -16,9 +16,9 @@ Every public function a production module defines is exercised by a test in the
 
 When you add a public function to a module whose test suite already exercises that module — covering a sibling public function, or testing one of its private helpers — add a behavioral test that calls the new function and asserts on its return value or side effect — in the same change that adds the function. A suite that exercises only a private helper (such as a color-conversion helper) while leaving the module's public renderers untested is the exact gap this rule closes. This is the function-level half of the project rule "Every new production code path gets a paired behavioral test ... call the path and assert on what it does."
 
-## What the gate checks
+## What the check covers
 
-Two complementary checks in `code_rules_paired_test.py` (both dispatched from `code_rules_enforcer.py`) cover the two write orders.
+Two complementary checks in `code_rules_paired_test.py` reach changed files through `code_rules_enforcer.py`, which the staged policy lint runs under its `code-rules` rule. No write-time hook runs them, so run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base. The two checks cover the two write orders.
 
 `check_public_function_missing_paired_test` runs on a production Python write or edit and flags a public function when all of these hold:
 
@@ -31,10 +31,10 @@ Two complementary checks in `code_rules_paired_test.py` (both dispatched from `c
 
 A public function counts as covered when its name appears — imported, called, or named — in any `test_*.py` or `*_test.py` file in the suite directory, so a function exercised by a differently-named sibling test still counts. `main` and underscore-prefixed functions are never required to carry a test.
 
-## Relationship to the file-level TDD gate
+## Relationship to the file-level TDD order
 
-`tdd_enforcer.py` requires a fresh test file to exist before a production module is written; it judges coverage one file at a time. This check judges coverage one function at a time for a module that already carries such a test file. The two compose: the file-level gate ensures a test file exists, and this check ensures that file covers every public function the module exposes.
+`tdd_enforcer.py` once required a fresh test file to exist before a production module was written, judging coverage one file at a time. Nothing runs it now, and the staged policy lint carries no replacement, so the test-first order is yours to hold. This check judges coverage one function at a time for a module that already carries such a test file. Write the test file first, and the lint then reports any public function that file leaves uncovered.
 
-## Why this is a hook, not a lint pass
+## Why this check is mechanical
 
-A public function with no test reads as covered when the module's test file sits right beside it and exercises its siblings. The gap survives review because the suite looks complete. Catching it as the function is written keeps the module's public surface and its test suite in step.
+A public function with no test reads as covered when the module's test file sits right beside it and exercises its siblings. The gap survives review because the suite looks complete. Running the lint on every staged change keeps the module's public surface and its test suite in step.

package/rules/plain-illustrative-docstrings.md

@@ -86,6 +86,6 @@ one — and you're debugging blind.
 
 Two surfaces carry this standard:
 
-- **Hook (the run-on backstop).** `check_docstring_runon_sentence` in `~/.claude/hooks/blocking/code_rules_docstrings.py` flags the one mechanical mark of a wall: a single narrative sentence that is both over the word limit and joined by an em-dash or a semicolon. A hook cannot judge whether prose paints a picture, so it catches only this structural mark. It reads the narrative through a shared partition that sets aside any `::` literal block and any doctest, so a diagram's own arrows and dashes never count against the sentence.
-- **Hook (the prose-wall backstop).** `check_docstring_prose_wall_without_illustration` in the same module flags a narrative that runs more than six prose lines with no diagram block. It marks the wall so the writer shows the behavior with a `::` example or a doctest and trims the prose to a few short lines. It cannot judge whether the diagram illustrates well; that stays with the audit lane.
-- **Audit (the judgment lane).** Category O sub-bucket O9 in `~/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` carries the illustrative-and-brief judgment the hook cannot. The audit teammate reads each changed docstring's narrative and asks whether a general developer follows it on the first read.
+- **Lint (the run-on backstop).** `check_docstring_runon_sentence` in `code_rules_docstrings.py` flags the one mechanical mark of a wall, a single narrative sentence that is both over the word limit and joined by an em-dash or a semicolon. The staged policy lint reaches it through `code_rules_enforcer.py`, and no write-time hook runs it. A mechanical check cannot judge whether prose paints a picture, so it catches only this structural mark. It reads the narrative through a shared partition that sets aside any `::` literal block and any doctest, so a diagram's own arrows and dashes never count against the sentence.
+- **Lint (the prose-wall backstop).** `check_docstring_prose_wall_without_illustration` in the same module flags a narrative that runs more than six prose lines with no diagram block. It marks the wall so the writer shows the behavior with a `::` example or a doctest and trims the prose to a few short lines. It cannot judge whether the diagram illustrates well, and that stays with the audit lane.
+- **Audit (the judgment lane).** Category O sub-bucket O9 in `~/.claude/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` carries the illustrative-and-brief judgment the lint cannot. The audit teammate reads each changed docstring's narrative and asks whether a general developer follows it on the first read.

package/rules/re-stage-before-commit.md

@@ -2,15 +2,15 @@
 
 Stage the files you edited this session right before you commit them. A plain `git commit` records only the staged snapshot; a tracked file this session changed but left unstaged stays behind in the working tree.
 
-`session_edit_stage_gate` (PreToolUse on Bash `git commit`) denies a commit that would drop tracked session edits and names the fix: `git add <paths>`, `git commit -a`, or a `# partial-commit` marker.
+No hook denies a commit that would drop tracked session edits. Run `git status` before you commit, then stage what you changed with `git add <paths>` or commit with `git commit -a`.
 
-Staging covers tracked files you edited. Do not commit untracked files unless the user explicitly instructs it — an untracked file in the working tree is outside the change until they say otherwise.
+Staging covers tracked files you edited. Do not commit untracked files unless the user explicitly instructs it. An untracked file in the working tree is outside the change until they say otherwise.
 
-## Escapes the denial does not restate
+## Staging shapes
 
-- **A pathspec** — `git commit -- <paths>` or `git commit <paths>` commits only the named paths on purpose and steps the gate aside.
-- **A preceding `git add` / `git stage`** — `git add <paths> && git commit …` stages the files in its own segment before the commit runs.
+- **A pathspec.** `git commit -- <paths>` or `git commit <paths>` commits only the named paths on purpose.
+- **A preceding `git add` or `git stage`.** `git add <paths> && git commit …` stages the files in its own segment before the commit runs.
 
-A `--amend` does not step the gate aside: an amend records the staged snapshot too, so an unstaged session edit is dropped the same way a plain commit drops it.
+A `--amend` carries the same risk. An amend records the staged snapshot too, so an unstaged session edit is dropped the same way a plain commit drops it.
 
-`session_file_edit_tracker` (PostToolUse) records each Write/Edit/MultiEdit path; `session_edit_tracker_cleanup` (SessionStart, SessionEnd) clears the session's tracker.
+`session_file_edit_tracker` (PostToolUse) still records each Write/Edit/MultiEdit path, and `session_edit_tracker_cleanup` (SessionStart, SessionEnd) still clears the session's tracker. No gate reads that record today, so it serves as history rather than a precondition.

package/rules/retired-hook-prose.md

@@ -0,0 +1,16 @@
+---
+paths:
+  - "**/rules/*.md"
+---
+
+# Rules Prose Names Only Hooks That Run
+
+A hook module runs when `hooks/hooks.json` registers it or a dispatcher roster hosts it. A module can survive on disk while appearing in neither place, and it then reaches no tool call. Prose that gives such a module a present-tense action describes a gate the reader never faces, and a reader who trusts it skips the check they were meant to run by hand.
+
+The staged policy lint carries this check as its `retired-hook-prose` rule. It reads each Markdown file under a `rules/` directory, takes every backticked hook module name, and reports the ones that are registered nowhere and that carry a present-tense action verb in the rest of the sentence. Run `python packages/claude-dev-env/scripts/cde_lint.py --staged` before you commit. CI runs the same lint against the merge base.
+
+A module name counts as a hook when it ends in one of the hook families, such as `_blocker`, `_enforcer`, `_gate`, `_tracker`, or `_dispatcher`, and when it either sits under `hooks/` or appears in `RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS` in `bin/install.mjs`. A support module inside the hooks tree carries no such family suffix, so it stays out of the check. A hook deleted from disk without an entry in that roster resolves nowhere, so add the roster entry when you retire a hook.
+
+Two shapes pass. A past-tense sentence that records what a hook once did makes no live claim. A sentence that names the staged policy lint, `cde_lint`, or a repository check tells the reader where the work runs now, so the module name reads as a pointer to code.
+
+When the rule reports a line, say what the reader faces now. Name the harness permission prompt, the staged policy lint, or the repository check that carries the work, or drop the claim.

package/rules/shell-invocation.md

@@ -18,4 +18,20 @@ When a script file's literal body needs `$(...)`, author it with the Write tool,
 
 ## Enforcement
 
-`shell_substitution_blocker.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) denies a command carrying a live substitution and returns the split-into-two-calls rewrite. Single-quoted runs are stripped before the scan, and a backtick preceded by an odd number of backslashes is escaped, so an inert mention passes. A quoted heredoc body is dropped for the same reason: the opener forms that quote or escape the delimiter tell bash to expand nothing down to the terminator, so a backtick there is text the file receives. A bare delimiter expands its body and keeps its scan.
+No PreToolUse hook denies a Bash command. Commit `0f21faf8e` retired the blocking policy hooks and left the Bash PreToolUse roster empty. `shell_substitution_blocker.py` was one of them. The substitution constraint above is guidance a reader follows, and a permission prompt on a wrapped command is the signal that one slipped through.
+
+One PreToolUse hook does run on a Bash command, and it only rewrites. `blocking/msys_rev_path_rewriter.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) reads a git command before it runs and keeps Git Bash from converting a `<rev>:<path>` argument. That roster holds this one hook, and a test asserts its whole content, so a blocking hook added beside it fails the suite.
+
+Git Bash rewrites that argument when the revision holds a slash and the path after the colon starts with a slash or a dot. It turns the colon into a semicolon and the slashes into backslashes, so `git show origin/main:.claude/settings.json` reaches git as `origin\main;.claude\settings.json` and git reports a revision that does not exist. A leading dot on a file is enough. `origin/main:.gitignore` reaches git as `origin\main;.gitignore`. `git show origin/main:packages/app.py` passes through untouched, and so does any path after the colon that starts with `./`, `../`, or `~/`. A revision without a slash, such as `HEAD:.claude/settings.json`, passes through too.
+
+On that shape the rewriter names only the arguments it found, so `git show origin/main:.claude/settings.json` runs as:
+
+```
+export MSYS2_ARG_CONV_EXCL='origin/main:'; git show origin/main:.claude/settings.json
+```
+
+`MSYS2_ARG_CONV_EXCL` takes a semicolon-separated list of argument prefixes. Naming one prefix per detected token leaves every other argument in the command converting as before. The blanket pair `MSYS_NO_PATHCONV=1 MSYS2_ARG_CONV_EXCL='*'` turns conversion off for the whole command, which changes a path the command meant to convert, so the rewriter does not emit it.
+
+A quoted token is not a revision. `git commit -m "fix a/b:.py"` carries a slash and a dot in one token, and a rewrite there would break the message, so the detection skips a token holding whitespace or a quote.
+
+`advisory/msys_path_conversion_advisor.py` (PostToolUse on Bash, hosted by `bash_post_call_dispatcher`) stays behind it. It reads a failed git call, looks for the mark MSYS leaves, and names the fix. It covers a shape the rewriter misses.

package/rules/testing.md

@@ -23,10 +23,8 @@ Incomplete mocks make it impossible to distinguish "broken code" from "missing d
 
 Tests exercise real behavior, real data, and production code paths. A test that asserts on a stand-in for the production path proves the stand-in works.
 
-## The File-Level TDD Gate Reads Content
+## No Gate Holds the Test-First Order
 
-`tdd_enforcer.py` records each candidate test's content hash at every sighting and compares that hash on the next write. A first sighting requires content that differs from HEAD.
+`tdd_enforcer.py` once required a fresh, failing test before a production module was written. Nothing runs it now, and the staged policy lint carries no replacement. Hold the red-green-refactor order yourself, and let review check it on the diff.
 
-## The Gate Reads a Recorded Failing Run First
-
-`hooks/observability/test_failure_recorder.py` runs on every Bash call and records a single unchained pytest run that names a real test file path and reports a failing exit status. It stores the command, that exit status, and the path in the same content-hash store the gate reads. The gate consults that record before its freshness fallback, and honours it while the candidate's content still matches what failed. `content_hash_store.py`'s module docstring holds the full contract.
+`hooks/observability/test_failure_recorder.py` still runs on every Bash call. It records a single unchained pytest run that names a test file path and reports a failing exit status, storing the command, that exit status, and the path in the content-hash store. `content_hash_store.py`'s module docstring holds the full contract. No gate reads that store today, so the record serves as history rather than a precondition.

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,
+        ),
     )