claude-dev-env 1.83.0 → 1.85.0

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

@@ -160,6 +160,24 @@ def test_path_contains_glob_metacharacters_local_tuple_uses_all_collection_prefi
     )
 
 
+def test_is_valid_project_root_detects_git_marker(tmp_path: Path) -> None:
+    git_project_root = tmp_path / "git_project"
+    (git_project_root / ".git").mkdir(parents=True)
+    assert common.is_valid_project_root(git_project_root) is True
+
+
+def test_is_valid_project_root_detects_claude_marker(tmp_path: Path) -> None:
+    claude_project_root = tmp_path / "claude_project"
+    (claude_project_root / ".claude").mkdir(parents=True)
+    assert common.is_valid_project_root(claude_project_root) is True
+
+
+def test_is_valid_project_root_rejects_unmarked_directory(tmp_path: Path) -> None:
+    unmarked_directory = tmp_path / "no_marker"
+    unmarked_directory.mkdir()
+    assert common.is_valid_project_root(unmarked_directory) is False
+
+
 def test_is_valid_project_root_uses_extracted_directory_marker_constants() -> None:
     """is_valid_project_root must reference extracted constants, not inline string literals."""
     source_text = inspect.getsource(common.is_valid_project_root)

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

@@ -9,6 +9,7 @@ Covers:
 
 import importlib.util
 import inspect
+import os
 import subprocess
 import sys
 import unittest.mock
@@ -93,6 +94,13 @@ def stage_file(repository_root: Path, relative_path: str) -> None:
     run_git_in_repository(repository_root, "add", "--", relative_path)
 
 
+@pytest.fixture(autouse=True)
+def isolated_git_environment(monkeypatch: pytest.MonkeyPatch) -> None:
+    for each_variable_name in list(os.environ):
+        if each_variable_name.startswith("GIT_"):
+            monkeypatch.delenv(each_variable_name, raising=False)
+
+
 @pytest.fixture()
 def temporary_git_repository(tmp_path: Path) -> Path:
     repository_root = tmp_path / "repository_under_test"
@@ -320,6 +328,35 @@ def test_main_staged_mode_exits_zero_when_nothing_staged(
     assert exit_code == 0
 
 
+def test_main_staged_mode_passes_when_only_terminology_findings_exist(
+    temporary_git_repository: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    write_file(temporary_git_repository / "quota.py", "first_count = 1\n")
+    commit_all_files(temporary_git_repository, "initial")
+    write_file(
+        temporary_git_repository / "quota.py",
+        "first_count = 1\npremium_interactions = 1\n",
+    )
+    write_file(
+        temporary_git_repository / "README.md",
+        "The premium-request budget gates the run.\n",
+    )
+    stage_file(temporary_git_repository, "quota.py")
+    stage_file(temporary_git_repository, "README.md")
+
+    monkeypatch.chdir(temporary_git_repository)
+    terminology_findings = gate_module.staged_terminology_findings(
+        temporary_git_repository
+    )
+    exit_code = gate_module.main(["--staged"])
+
+    assert any(
+        "premium-request" in each_finding for each_finding in terminology_findings
+    )
+    assert exit_code == 0
+
+
 def test_added_lines_for_staged_file_returns_empty_for_modified_file_with_no_additions(
     temporary_git_repository: Path,
 ) -> None:

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

@@ -120,3 +120,17 @@ def test_cli_main_supports_bugteam_reviewer(
 ) -> None:
     monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugteam")
     assert reviews_disabled.main(["--reviewer", "bugteam"]) == 0
+
+
+def test_cli_main_supports_copilot_reviewer(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "copilot")
+    assert reviews_disabled.main(["--reviewer", "copilot"]) == 0
+
+
+def test_cli_main_returns_one_for_copilot_when_only_bugbot_disabled(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("CLAUDE_REVIEWS_DISABLED", "bugbot")
+    assert reviews_disabled.main(["--reviewer", "copilot"]) == 1

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

@@ -23,13 +23,22 @@ main = sweep_module.main
 parse_added_lines = sweep_module._parse_added_lines
 
 
+_git_environment = sweep_module._git_environment
+
+
 def _init_git_repository(repository_path: Path) -> None:
     for each_command in (
         ["git", "init"],
         ["git", "config", "user.email", "test@example.com"],
         ["git", "config", "user.name", "Test"],
     ):
-        subprocess.run(each_command, cwd=repository_path, check=True, capture_output=True)
+        subprocess.run(
+            each_command,
+            cwd=repository_path,
+            check=True,
+            capture_output=True,
+            env=_git_environment(),
+        )
 
 
 CODE_AND_PROSE_DIFF = (
@@ -220,17 +229,86 @@ def test_does_not_flag_ordinary_sentence_sharing_loop_variable_prefix() -> None:
 
 
 def test_flags_near_miss_inside_code_comment() -> None:
+    diff = (
+        "diff --git a/api/quota.mjs b/api/quota.mjs\n"
+        "--- a/api/quota.mjs\n"
+        "+++ b/api/quota.mjs\n"
+        "@@ -0,0 +1,2 @@\n"
+        "+const premium_interactions = 5\n"
+        "+// the premium-request path resets the counter\n"
+    )
+    findings = sweep_diff(diff)
+    assert len(findings) == 1
+    assert "premium-request" in findings[0]
+
+
+def test_flags_near_miss_inside_code_string_literal() -> None:
+    diff = (
+        "diff --git a/api/quota.mjs b/api/quota.mjs\n"
+        "--- a/api/quota.mjs\n"
+        "+++ b/api/quota.mjs\n"
+        "@@ -0,0 +1,2 @@\n"
+        "+const premium_interactions = 5\n"
+        '+throw new Error("the premium-request budget")\n'
+    )
+    findings = sweep_diff(diff)
+    assert len(findings) == 1
+    assert "premium-request" in findings[0]
+
+
+def test_does_not_flag_prose_inside_code_string_literal() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,2 @@\n"
+        "+premium_interactions = 5\n"
+        '+message = "the premium-request budget"\n'
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_prose_inside_code_docstring() -> None:
     diff = (
         "diff --git a/api/quota.py b/api/quota.py\n"
         "--- a/api/quota.py\n"
         "+++ b/api/quota.py\n"
         "@@ -0,0 +1,2 @@\n"
         "+premium_interactions = 5\n"
-        "+# the premium-request path resets the counter\n"
+        '+    """Gate the run on the premium-request budget."""\n'
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_does_not_flag_prose_in_test_file() -> None:
+    diff = (
+        "diff --git a/api/quota.test.mjs b/api/quota.test.mjs\n"
+        "--- a/api/quota.test.mjs\n"
+        "+++ b/api/quota.test.mjs\n"
+        "@@ -0,0 +1,2 @@\n"
+        "+const premium_interactions = 5\n"
+        "+// the premium-request path resets the counter\n"
+    )
+    assert sweep_diff(diff) == []
+
+
+def test_flags_prose_in_test_named_markdown_doc() -> None:
+    diff = (
+        "diff --git a/api/quota.py b/api/quota.py\n"
+        "--- a/api/quota.py\n"
+        "+++ b/api/quota.py\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+premium_interactions = 5\n"
+        "diff --git a/docs/test_plan.md b/docs/test_plan.md\n"
+        "--- a/docs/test_plan.md\n"
+        "+++ b/docs/test_plan.md\n"
+        "@@ -0,0 +1,1 @@\n"
+        "+The premium-request budget gates the run.\n"
     )
     findings = sweep_diff(diff)
     assert len(findings) == 1
     assert "premium-request" in findings[0]
+    assert "test_plan.md" in findings[0]
 
 
 def test_no_findings_when_no_multiword_identifier_introduced() -> None:
@@ -273,7 +351,13 @@ def test_staged_terminology_findings_flags_staged_prose(tmp_path: Path) -> None:
     (tmp_path / "README.md").write_text(
         "The premium-request budget gates the run.\n", encoding="utf-8"
     )
-    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True, capture_output=True)
+    subprocess.run(
+        ["git", "add", "-A"],
+        cwd=tmp_path,
+        check=True,
+        capture_output=True,
+        env=_git_environment(),
+    )
     findings = staged_terminology_findings(tmp_path)
     assert any("premium-request" in each_finding for each_finding in findings)
 
@@ -281,7 +365,13 @@ def test_staged_terminology_findings_flags_staged_prose(tmp_path: Path) -> None:
 def test_staged_terminology_findings_empty_when_clean(tmp_path: Path) -> None:
     _init_git_repository(tmp_path)
     (tmp_path / "README.md").write_text("Nothing notable here.\n", encoding="utf-8")
-    subprocess.run(["git", "add", "-A"], cwd=tmp_path, check=True, capture_output=True)
+    subprocess.run(
+        ["git", "add", "-A"],
+        cwd=tmp_path,
+        check=True,
+        capture_output=True,
+        env=_git_environment(),
+    )
     assert staged_terminology_findings(tmp_path) == []
 
 

package/agents/clean-coder.md

@@ -1,6 +1,7 @@
 ---
 name: clean-coder
 description: "Use PROACTIVELY for ALL code generation — feature development, bug fixes, refactoring, hook creation, automation scripts, and any task that produces code. Internalizes CODE_RULES.md and the 8-dimension readability standard so thoroughly that /check finds zero issues. The definitive code-writing agent."
+model: opus
 tools: Read, Write, Edit, Bash, Grep, Glob, Task, Skill
 color: green
 ---
@@ -436,6 +437,8 @@ This default is overridden by explicit user instruction such as "refactor this e
 
 Docstrings on functions, methods, classes, and modules are encouraged for public APIs. The self-documenting-names gate inspects inline `#` and block `#` comments only; docstrings are exempt from that gate.
 
+Write a behavior-illustrating docstring in the diagram-first shape: one summary line, then a `::` literal block or a doctest that shows a concrete input and its marked outcome (with `ok:` / `flag:` contrast lines where a pass-and-fail pair helps), then a couple of short neutral prose lines, then the `Args:` / `Returns:` sections. Two hooks back this: `check_docstring_runon_sentence` flags a run-on prose wall, and `check_docstring_prose_wall_without_illustration` flags a narrative that runs long with no diagram. See `../rules/plain-illustrative-docstrings.md` for the shape and a worked example.
+
 ## Audit Awareness
 
 Code clean-coder writes will be audited later against the A–P bug categories from `code-quality-agent`. The hooks listed in this file enforce the Category J slice at write time, but A–I and K–P surface only in audit. For each category's full rubric, sub-bucket decomposition, and concrete checks, see `../audit-rubrics/category_rubrics/` (relative to this agent file). While generating code, anticipate the full A–P surface so the first write clears every audit category.

package/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md

@@ -28,7 +28,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O6 | Free-form `Args:`-adjacent claims | A docstring's `Returns:` / `Raises:` / `Note:` / `Example:` sections make claims (`returns shared-temp only`, `raises ValueError on missing key`). Verify each claim against the body. When a docstring enumerates the inputs a body counts (a "field counts as read when ..." list, a list of conditions treated as a match, a list of cases the body skips), list every union member and every suppressor the body applies (`read_names = a | b | c`, each early-return guard) and confirm each appears in the prose enumeration. A union member or suppressor the body applies but the prose omits is an O6 finding. When a docstring sentence excludes a named category of input from what the function flags (`X are not dispatch steps`, `Y is not a match`), confirm the axis the prose excludes on is the axis the body's branch condition actually keys on. A body that flags a call when it sits inside an `If.test` guard, paired with prose that excludes by the call's receiver shape (`method-on-local calls inside a branch are not dispatch steps`), is an O6 finding: a guarded method-on-local call is flagged even though the prose lists it as excluded — the exclusion is keyed to the wrong axis. The single-condition shared-fallback shape of this drift — a summary that scopes a fallback call to one condition while the body routes to that same call from two or more early-return guards — is gated deterministically at Write/Edit time by `check_docstring_fallback_branch_coverage`, so the audit lane focuses on the O6 shapes the gate cannot match. The exception-guard shape of this drift — a docstring that promises a malformed payload `resolves to None` while a payload subscript (`payload["key"]`, `float(payload["key"])`) sits outside the try/except whose handler returns None, so a present-but-malformed payload raises rather than resolving to None — is gated deterministically at Write/Edit time by `check_docstring_unguarded_malformed_payload_claim`, so the audit lane focuses on the wider Raises/None-on-failure claims the gate cannot match. A `Returns:` that names the mechanism, tool, or output format the function produces (`instructing a StructuredOutput summary`, `returns a YAML document`, `emits a JSON object`) matches the artifact the body actually builds: a prompt body that asks the agent to "Return strictly a JSON object" while the docstring claims it "instruct[s] a StructuredOutput" summary is an O6 finding, because the named tool appears nowhere in the emitted text. See `../../rules/docstring-prose-matches-implementation.md`. |
 | O7 | Module-doc-vs-split-module after refactor | When a refactor moves a responsibility to a sibling module, the originating module's docstring and the receiving module's docstring both describe the home of that responsibility. A module docstring should describe only the responsibilities it owns. |
 | O8 | Companion-doc ordering/content vs producer | When a PR changes a producer function's ordering or union, read that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact (a file path, a JSON key, a named list). A doc sentence that claims the artifact is `sorted` / `alphabetical` / `in sorted order`, or holds `just the at-risk names` / `only the current set`, while the producer merges stored names with new names and appends — preserving file order, not re-sorting the union — is an O8 finding on both counts (wrong order claim, hidden merged-in entries). The finding stands even when the PR diff never touched the `.md` file, because the behavior change orphaned the doc claim. See `../../rules/docstring-prose-matches-implementation.md`. |
-| O9 | Python docstring plainness for a general developer | A changed module / class / public-function docstring's narrative prose — the summary and description before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section — reads plainly and paints a concrete scene a general developer follows on first read. Flag a narrative that stacks abstract machinery nouns into a wall (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`), that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence long while joining clauses with an em-dash or a semicolon. The deterministic run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence` in `code_rules_docstrings.py`, so this lane carries the illustrative-and-brief judgment the gate cannot: whether a stranger to the code pictures the moment, the input, and the outcome after one read. See `../../rules/plain-illustrative-docstrings.md`. |
+| O9 | Python docstring plainness for a general developer | A changed module / class / public-function docstring's narrative prose — the summary and description before the first `Args:` / `Returns:` / `Raises:` / `Yields:` section — reads plainly and paints a concrete scene a general developer follows on first read. Flag a narrative that stacks abstract machinery nouns into a wall (`the SIGINT install/restore/installability check, the atexit terminal-record registration, and the interrupted-run finalizer`), that defines a thing by what it is not (`the non-promoter-specific machinery`), or that runs one sentence long while joining clauses with an em-dash or a semicolon. The diagram-first shape carries this best: a summary line, then a `::` example block or a doctest that shows a concrete input and its marked outcome, then a couple of short prose lines. The deterministic run-on mark is gated at Write/Edit time by `check_docstring_runon_sentence` in `code_rules_docstrings.py`, and a narrative that runs more than six prose lines with no such block is gated by `check_docstring_prose_wall_without_illustration` in the same module, so this lane carries the judgment the gates cannot: whether a stranger to the code pictures the moment, the input, and the outcome after one read, and whether the diagram truly illustrates — a real input, a marked outcome, an `ok:` / `flag:` contrast a reader learns from. See `../../rules/plain-illustrative-docstrings.md`. |
 
 ---
 

package/bin/install.mjs

@@ -294,10 +294,13 @@ function backupClaudeHubBeforeOverwrite(destPath, incomingPath) {
 }
 
 /**
- * Hook script paths that were folded into the PreToolUse dispatcher in Stage 1.
- * These entries no longer appear in hooks.json but must still be recognized as
- * managed so a reinstall from an older settings shape prunes them and they do
- * not double-run alongside the dispatcher.
+ * PreToolUse hook script paths the installer manages even though hooks.json
+ * carries no standalone entry for them. Most were folded into the PreToolUse
+ * dispatcher in Stage 1; md_to_html_blocker is a retired hook with no script on
+ * disk. Each path stays in this set so a reinstall from an older settings shape
+ * prunes its standalone entry — a folded hook would otherwise double-run
+ * alongside the dispatcher, and the retired hook's entry would point at a
+ * missing script.
  */
 export const FOLDED_HOOK_RELATIVE_PATHS = new Set([
     'blocking/write_existing_file_blocker.py',
@@ -316,18 +319,23 @@ export const FOLDED_HOOK_RELATIVE_PATHS = new Set([
     'blocking/pytest_testpaths_orphan_blocker.py',
     'blocking/open_questions_in_plans_blocker.py',
     'blocking/plain_language_blocker.py',
+    'blocking/md_to_html_blocker.py',
 ]);
 
 /**
- * Hook script paths that were folded into the PostToolUse dispatcher. These
- * after-write hooks no longer appear in hooks.json but must still be recognized
- * as managed so a reinstall from an older settings shape prunes them and they do
- * not double-run alongside the PostToolUse dispatcher.
+ * After-write hook script paths the installer manages even though hooks.json
+ * carries no standalone entry for them. mypy_validator and auto_formatter run
+ * hosted inside the PostToolUse dispatcher; doc_gist_auto_publish and
+ * md_to_html_companion are retired hooks with no script on disk. Each path stays
+ * in this set so a reinstall from an older settings shape prunes its standalone
+ * entry — a hosted hook would otherwise double-run alongside the dispatcher, and
+ * a retired hook's entry would point at a missing script.
  */
 export const POST_FOLDED_HOOK_RELATIVE_PATHS = new Set([
     'validation/mypy_validator.py',
     'workflow/auto_formatter.py',
     'workflow/doc_gist_auto_publish.py',
+    'workflow/md_to_html_companion.py',
 ]);
 
 /**

package/bin/install.test.mjs

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

package/commands/CLAUDE.md

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

package/docs/CODE_RULES.md

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

package/hooks/blocking/CLAUDE.md

@@ -77,7 +77,6 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | `hedging_language_blocker.py` | Stop | Responses with hedging words (`likely`, `probably`, `appears to`) |
 | `hook_prose_detector_consistency.py` | PreToolUse (Write/Edit) | Hook docstrings/messages that claim a trigger the detector cannot fire on |
 | `intent_only_ending_blocker.py` | Stop | Responses that end on a plan or intent without doing the work |
-| `md_to_html_blocker.py` | PreToolUse (Write/Edit) | Writing `.md` files when an `.html` companion is required |
 | `open_questions_in_plans_blocker.py` | PreToolUse (Write/Edit) | Plan documents with unresolved open questions |
 | `package_inventory_stale_blocker.py` | PreToolUse (Write) | A new production code file created in a directory whose `README.md`/`CLAUDE.md` inventory (or a parent skill's `SKILL.md` Layout table mapping the `scripts/` subdirectory) names two or more sibling files but no entry for the new file |
 | `plain_language_blocker.py` | PreToolUse (Write/Edit/AskUserQuestion) | Heavy or jargon words in user-facing prose |
@@ -107,8 +106,6 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 | File | Role |
 |---|---|
 | `_gh_body_arg_utils.py` | Parsing helpers for `gh_body_arg_blocker.py` |
-| `_md_to_html_blocker_test_support.py` | Test fixtures shared across `md_to_html_blocker` tests |
-| `md_path_exemptions.py` | Path exemption logic for `md_to_html_blocker.py` |
 | `pr_description_body_audit.py` | Body audit logic for `pr_description_enforcer.py` |
 | `pr_description_command_parser.py` | `gh` command parsing for `pr_description_enforcer.py` |
 | `pr_description_pr_number.py` | PR number extraction logic |
@@ -119,4 +116,3 @@ The check modules it calls are the `code_rules_<concern>.py` files below.
 
 - Tests live beside each hook as `test_<hookname>.py` or `test_<hookname>_<suffix>.py`. Run with `python -m pytest <test_file>`.
 - Tunable constants live in `hooks_constants/<hook_name>_constants.py`; the verified-commit family uses `blocking/config/verified_commit_constants.py`.
-- `conftest.py` gives shared pytest fixtures for the blocking test suite.

package/hooks/blocking/claude_md_orphan_file_blocker.py

@@ -45,11 +45,11 @@ from hooks_constants.claude_md_orphan_file_blocker_constants import (  # noqa: E
     SEPARATOR_CELL_PATTERN,
     TABLE_ROW_PATTERN,
 )
+from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.multi_edit_reconstruction import (  # noqa: E402
     apply_edits,
     edits_for_tool,
 )
-from hooks_constants.hook_block_logger import log_hook_block  # noqa: E402
 from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
     read_hook_input_dictionary_from_stdin,
 )

package/hooks/blocking/code_rules_constants_config.py

@@ -23,6 +23,7 @@ from code_rules_path_utils import (  # noqa: E402
 )
 from code_rules_shared import (  # noqa: E402
     _build_parent_map,
+    docstring_line_numbers,
     get_file_extension,
     is_migration_file,
     is_test_file,
@@ -110,6 +111,7 @@ def _scan_function_body_constants(content: str) -> list[str]:
     """
     advisory_issues: list[str] = []
     lines = content.split("\n")
+    all_docstring_line_numbers = docstring_line_numbers(content)
     function_indent_stack: list[int] = []
     constant_pattern = re.compile(r"^([A-Z][A-Z0-9_]{2,})(?:\s*:\s*[^=]+)?\s*=\s*[^=]")
 
@@ -119,6 +121,9 @@ def _scan_function_body_constants(content: str) -> list[str]:
         if not stripped:
             continue
 
+        if each_line_number in all_docstring_line_numbers:
+            continue
+
         indent = len(each_line) - len(each_line.lstrip())
 
         while function_indent_stack and indent <= function_indent_stack[-1] and not stripped.startswith(("#", "@", ")")):