claude-dev-env 1.83.0 → 1.84.0

package/_shared/pr-loop/audit-contract.md

@@ -8,7 +8,8 @@ Shared output schema and audit-loop contract used by `/bugteam`, `/qbug`, `/find
 - Adversarial second pass
 - Haiku secondary auditor
 - Post-fix self-audit
-- Persistence (loop-N-audit.json, loop-N-diagnostics.json)
+- De-dup and merge
+- Persistence (loop-<L>-audit.json, loop-<L>-diagnostics.json)
 
 ## Finding schema
 
@@ -18,7 +19,7 @@ Each finding an audit produces MUST be one of exactly two shapes.
 
 ```json
 {
-  "id": "loop<N>-<K>",
+  "id": "loop<L>-<K>",
   "file": "path/relative/to/repo/root.py",
   "line": 123,
   "category": "A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P",
@@ -29,7 +30,7 @@ Each finding an audit produces MUST be one of exactly two shapes.
 }
 ```
 
-`id` is `loop<N>-<K>` where `N` is the loop counter (1-based) and `K` is the 1-based index within the loop. For `/findbugs` which runs once, use `find<K>`.
+`id` is `loop<L>-<K>` where `L` is the loop counter (1-based) and `K` is the 1-based index within the loop. For `/findbugs` which runs once, use `find<K>`.
 
 ### Shape B — structured proof-of-absence
 
@@ -98,16 +99,16 @@ For single-subagent skills (`/qbug`, `/findbugs`) the LEAD spawns two `Agent()`
 
 Both audit the same diff. The secondary returns findings to the LEAD only — never posted to the PR.
 
-Merge rules:
+Merge rules — applied whenever the LEAD combines findings from multiple sources (primary auditor, Haiku secondary auditor, adversarial pass):
 
-- **De-dup key**: `(file, line, category)`.
-- **Severity conflict**: max wins (P0 > P1 > P2).
-- **Unique-to-Haiku findings**: added to the primary set with Haiku's severity and source annotation.
+- **De-dup key**: `(file, line, category)`. Two findings sharing the same `(file, line, category)` tuple are the same finding and collapse into one entry.
+- **Severity conflict**: max wins (`P0 > P1 > P2`). When sources disagree on severity for the same de-dup key, the merged entry keeps the highest severity.
+- **Unique-to-secondary findings**: added to the merged set with the secondary's severity and source annotation.
 - **Unique-to-primary findings**: kept as-is.
-- **Zero Haiku findings**: primary set trusted; proceed.
-- **Malformed or non-parseable Haiku output**: lead trusts the primary set, logs the event in `loop-<N>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
+- **Zero secondary findings**: the primary set is trusted and the audit moves on.
+- **Malformed or non-parseable secondary output**: lead trusts the primary set and logs the event in `loop-<L>-diagnostics.json` under `haiku_findings` as `[{"parse_error": "<message>"}]`.
 
-For multi-subagent skills (`/bugteam`) the parallel-auditors pattern in [`audit-and-teammates.md`](audit-and-teammates.md) already provides cross-model coverage via the three variant teammates.
+For `/bugteam`, the single audit agent provides per-category coverage by walking all A–P rubrics in one invocation.
 
 ## Post-fix self-audit
 
@@ -128,11 +129,22 @@ Sequence:
 
 `converged` exit condition: `primary_audit_clean AND post_fix_audit_clean` for the committing loop.
 
+## De-dup and merge
+
+Findings from primary, adversarial, Haiku secondary, and post-fix passes are merged into a single deduped finding list before persistence.
+
+- **De-dup key:** `(file, line, category)`. Two findings sharing the same `(file, line, category)` tuple collapse into a single deduped entry.
+- **Severity conflict resolution:** `max wins`. When merged findings disagree on severity, the deduped entry carries the highest severity (`P0 > P1 > P2`).
+- **Excerpt and failure_mode:** the deduped entry inherits these fields from the highest-severity contributing finding. Ties keep the first observed contributor.
+- **`evidence_files`:** the deduped entry carries the union of every contributor's `evidence_files`, deduplicated and sorted.
+
+The merged list lands in `loop-<L>-diagnostics.json` under both `merged` (one entry per contributing finding) and `deduped` (one entry per unique `(file, line, category)` tuple).
+
 ## Persistence
 
 Every audit loop writes two JSON files under the skill's scoped temp directory (resolved via `tempfile.gettempdir()`):
 
-### `loop-<N>-audit.json`
+### `loop-<L>-audit.json`
 
 ```json
 {
@@ -142,7 +154,7 @@ Every audit loop writes two JSON files under the skill's scoped temp directory (
 }
 ```
 
-### `loop-<N>-diagnostics.json`
+### `loop-<L>-diagnostics.json`
 
 ```json
 {

package/_shared/pr-loop/scripts/_claude_permissions_common.py

@@ -299,9 +299,11 @@ def write_atomically_with_mode(
 
     Raises:
         OSError: When os.open or os.fdopen fails. The raw file descriptor
-            is closed before re-raising so the descriptor does not leak.
+            is closed and the on-disk temporary file is unlinked before
+            re-raising so neither the descriptor nor the file leaks.
         MemoryError: When os.fdopen runs out of buffer memory; the file
-            descriptor is closed before re-raising.
+            descriptor is closed and the temporary file is unlinked
+            before re-raising.
     """
     file_descriptor = os.open(
         str(temporary_path),
@@ -312,6 +314,10 @@ def write_atomically_with_mode(
         writer = os.fdopen(file_descriptor, "w", encoding=TEXT_FILE_ENCODING)
     except (OSError, MemoryError):
         os.close(file_descriptor)
+        try:
+            os.unlink(str(temporary_path))
+        except OSError:
+            pass
         raise
     with writer:
         writer.write(serialized_content)
@@ -321,7 +327,8 @@ def save_settings(settings_path: Path, all_settings: dict[str, object]) -> None:
     """Write settings to a JSON file atomically with permission preservation.
 
     Creates a temporary sibling file, writes content, then atomically
-    replaces the target. Cleans up the temporary file in a finally block.
+    replaces the target. Cleans up the temporary file in a finally block,
+    printing a warning to stderr when that cleanup unlink fails.
 
     Args:
         settings_path: Path to the target settings JSON file.
@@ -352,8 +359,12 @@ def save_settings(settings_path: Path, all_settings: dict[str, object]) -> None:
         if temporary_path.exists():
             try:
                 temporary_path.unlink()
-            except OSError:
-                pass
+            except OSError as unlink_error:
+                print(
+                    f"Warning: could not remove temp file {temporary_path}: "
+                    f"{type(unlink_error).__name__}: {unlink_error}",
+                    file=sys.stderr,
+                )
 
 
 def append_if_missing(all_target_list: list[object], new_value: str) -> bool:

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -1673,7 +1673,6 @@ def main(all_arguments: list[str]) -> int:
     if arguments.staged:
         all_terminology_findings = staged_terminology_findings(repository_root)
         _report_terminology_findings(all_terminology_findings)
-        terminology_exit_code = 1 if all_terminology_findings else 0
         staged_test_exit_code = run_staged_test_files(repository_root)
         staged_file_paths = paths_from_git_staged(repository_root)
         staged_file_paths = filter_paths_under_prefixes(
@@ -1682,7 +1681,7 @@ def main(all_arguments: list[str]) -> int:
             arguments.only_under,
         )
         if not staged_file_paths:
-            return terminology_exit_code or staged_test_exit_code
+            return staged_test_exit_code
         staged_added_lines = added_lines_by_file_staged(
             repository_root, staged_file_paths
         )
@@ -1693,7 +1692,7 @@ def main(all_arguments: list[str]) -> int:
             all_added_lines_by_path=staged_added_lines,
             read_staged_content_flag=True,
         )
-        return gate_exit_code or terminology_exit_code or staged_test_exit_code
+        return gate_exit_code or staged_test_exit_code
     file_paths = paths_from_git_diff(repository_root, arguments.base)
     file_paths = filter_paths_under_prefixes(
         file_paths,

package/_shared/pr-loop/scripts/reviews_disabled.py

@@ -103,6 +103,7 @@ def parse_arguments(all_argv: list[str]) -> argparse.Namespace:
         choices=[
             CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN,
             CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN,
+            CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN,
         ],
         help="Reviewer token to test against CLAUDE_REVIEWS_DISABLED",
     )
@@ -122,6 +123,7 @@ def main(all_arguments: list[str]) -> int:
     disabled_checker_by_reviewer = {
         CLAUDE_REVIEWS_DISABLED_BUGBOT_TOKEN: is_bugbot_disabled_via_env,
         CLAUDE_REVIEWS_DISABLED_BUGTEAM_TOKEN: is_bugteam_disabled_via_env,
+        CLAUDE_REVIEWS_DISABLED_COPILOT_TOKEN: is_copilot_disabled_via_env,
     }
     return 0 if disabled_checker_by_reviewer[arguments.reviewer]() else 1
 

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

@@ -133,3 +133,215 @@ def test_path_contains_glob_metacharacters_accepts_windows_paths_with_parens() -
     assert common.path_contains_glob_metacharacters("C:/Users/Jon (Admin)/project") is False
     assert common.path_contains_glob_metacharacters("C:/Projects/a,b/file.py") is False
 
+
+def test_get_mode_to_preserve_returns_existing_file_mode(tmp_path: Path) -> None:
+    """When the file exists, the actual filesystem mode must be returned (not the default)."""
+    target_path = tmp_path / "settings.json"
+    target_path.write_text("{}", encoding="utf-8")
+    actual_filesystem_mode = target_path.stat().st_mode & 0o777
+    returned_mode = common.get_mode_to_preserve(target_path)
+    assert returned_mode == actual_filesystem_mode
+
+
+def test_get_mode_to_preserve_returns_secure_default_when_file_missing(
+    tmp_path: Path,
+) -> None:
+    """A missing settings file must fall back to the secure 0o600 default mode."""
+    missing_settings_path = tmp_path / "no_such_file.json"
+    returned_mode = common.get_mode_to_preserve(missing_settings_path)
+    assert returned_mode == 0o600
+
+
+def test_write_atomically_with_mode_raises_oserror_when_open_fails(
+    tmp_path: Path,
+) -> None:
+    """OSError from os.open must propagate to the caller."""
+    target_path = tmp_path / "subdirectory" / "missing" / "settings.json.tmp"
+    with pytest.raises(OSError):
+        common.write_atomically_with_mode(target_path, "payload", file_mode=0o600)
+
+
+def test_write_atomically_with_mode_unlinks_temp_when_fdopen_raises(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A failure inside os.fdopen must remove the on-disk temp file.
+
+    The file exists the moment os.open returns; closing only the raw
+    descriptor would leave an empty temp sibling on disk after the
+    exception propagates to the caller.
+    """
+
+    def failing_fdopen(*_args: object, **_kwargs: object) -> object:
+        raise MemoryError("fdopen failure")
+
+    monkeypatch.setattr(common.os, "fdopen", failing_fdopen)
+    target_path = tmp_path / "settings.json.tmp"
+    with pytest.raises(MemoryError):
+        common.write_atomically_with_mode(target_path, "payload", file_mode=0o600)
+    assert not target_path.exists(), (
+        "the temp file created by os.open must be unlinked before re-raising"
+    )
+
+
+def test_save_settings_warns_on_stderr_when_temp_unlink_fails(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """A swallowed unlink in the finally block must surface to stderr.
+
+    Forces a write success followed by os.replace failure so the temp file
+    survives into the finally branch, then makes Path.unlink raise.
+    """
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text('{"existing": true}\n', encoding="utf-8")
+
+    def failing_replace(*_args: object, **_kwargs: object) -> None:
+        raise OSError("replace blocked by AV")
+
+    def failing_unlink(_self: Path, *_args: object, **_kwargs: object) -> None:
+        raise PermissionError("temp file held by AV")
+
+    monkeypatch.setattr(common.os, "replace", failing_replace)
+    monkeypatch.setattr(Path, "unlink", failing_unlink)
+    with pytest.raises(SystemExit):
+        common.save_settings(settings_path, {"new_key": "value"})
+    captured = capsys.readouterr()
+    assert ".tmp" in captured.err
+    assert "PermissionError" in captured.err or "held by AV" in captured.err
+
+
+def test_save_settings_finally_skips_unlink_when_no_temp_was_created(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """When this invocation never created the temp file, finally must not unlink it."""
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text('{"existing": true}\n', encoding="utf-8")
+
+    unlink_call_paths: list[Path] = []
+    original_unlink = Path.unlink
+
+    def recording_unlink(unlink_target: Path, *args: object, **kwargs: object) -> None:
+        unlink_call_paths.append(unlink_target)
+        original_unlink(unlink_target, *args, **kwargs)
+
+    def write_raises(*_args: object, **_kwargs: object) -> None:
+        raise FileExistsError("another writer's temp")
+
+    monkeypatch.setattr(common, "write_atomically_with_mode", write_raises)
+    monkeypatch.setattr(Path, "unlink", recording_unlink)
+    with pytest.raises(SystemExit):
+        common.save_settings(settings_path, {"new_key": "value"})
+    assert not any(
+        ".tmp." in each_path.name for each_path in unlink_call_paths
+    ), "finally must not unlink a temp file this invocation never created"
+
+
+def test_exit_with_error_prints_prefixed_message_and_exits_nonzero(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    with pytest.raises(SystemExit) as raised_exit:
+        common.exit_with_error("boom")
+    assert raised_exit.value.code == 1
+    assert "Error: boom" in capsys.readouterr().err
+
+
+def test_build_permission_rules_builds_one_rule_per_tool() -> None:
+    built_rules = common.build_permission_rules("/proj", ("Edit", "Read"))
+    assert built_rules == ["Edit(/proj/.claude/**)", "Read(/proj/.claude/**)"]
+
+
+def test_build_agent_config_deny_rule_embeds_tool_path_and_pattern() -> None:
+    built_rule = common.build_agent_config_deny_rule("Write", "/proj", "hooks/**")
+    assert built_rule == "Write(/proj/.claude/hooks/**)"
+
+
+def test_remove_matching_entries_from_list_filters_in_place_and_counts() -> None:
+    all_entries: list[object] = ["keep", "drop", "drop", 7]
+    removed_count = common.remove_matching_entries_from_list(
+        all_entries, lambda each_entry: each_entry == "drop"
+    )
+    assert removed_count == 2
+    assert all_entries == ["keep", 7]
+
+
+def test_load_settings_returns_empty_dict_when_file_missing(tmp_path: Path) -> None:
+    assert common.load_settings(tmp_path / "absent.json") == {}
+
+
+def test_load_settings_parses_existing_json_object(tmp_path: Path) -> None:
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text('{"permissions": {"allow": []}}', encoding="utf-8")
+    assert common.load_settings(settings_path) == {"permissions": {"allow": []}}
+
+
+def test_load_settings_exits_when_file_holds_invalid_json(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    settings_path = tmp_path / "settings.json"
+    settings_path.write_text("not json", encoding="utf-8")
+    with pytest.raises(SystemExit):
+        common.load_settings(settings_path)
+    assert "not valid JSON" in capsys.readouterr().err
+
+
+def test_serialize_settings_to_json_text_sorts_keys() -> None:
+    serialized_text = common.serialize_settings_to_json_text({"b": 1, "a": 2})
+    assert serialized_text.index('"a"') < serialized_text.index('"b"')
+    assert json.loads(serialized_text) == {"a": 2, "b": 1}
+
+
+def test_append_if_missing_appends_only_new_values() -> None:
+    all_entries: list[object] = ["existing"]
+    assert common.append_if_missing(all_entries, "fresh") is True
+    assert common.append_if_missing(all_entries, "fresh") is False
+    assert all_entries == ["existing", "fresh"]
+
+
+def test_ensure_dict_section_creates_missing_and_returns_existing() -> None:
+    all_settings: dict[str, object] = {}
+    created_section = common.ensure_dict_section(all_settings, "permissions")
+    assert created_section == {}
+    assert all_settings["permissions"] is created_section
+    assert common.ensure_dict_section(all_settings, "permissions") is created_section
+
+
+def test_ensure_dict_section_exits_on_non_dict_value(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    all_settings: dict[str, object] = {"permissions": "oops"}
+    with pytest.raises(SystemExit):
+        common.ensure_dict_section(all_settings, "permissions")
+    assert "not a JSON object" in capsys.readouterr().err
+
+
+def test_ensure_list_entry_creates_missing_and_returns_existing() -> None:
+    permissions_section: dict[str, object] = {}
+    created_entry = common.ensure_list_entry(permissions_section, "allow")
+    assert created_entry == []
+    assert permissions_section["allow"] is created_entry
+    assert common.ensure_list_entry(permissions_section, "allow") is created_entry
+
+
+def test_ensure_list_entry_exits_on_non_list_value(
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    permissions_section: dict[str, object] = {"allow": {}}
+    with pytest.raises(SystemExit):
+        common.ensure_list_entry(permissions_section, "allow")
+    assert "not a JSON array" in capsys.readouterr().err
+
+
+def test_prune_empty_list_then_empty_section_removes_empty_structures() -> None:
+    all_settings: dict[str, object] = {"permissions": {"allow": []}}
+    common.prune_empty_list_then_empty_section(all_settings, "permissions", "allow")
+    assert all_settings == {}
+
+
+def test_prune_empty_list_then_empty_section_keeps_populated_structures() -> None:
+    all_settings: dict[str, object] = {
+        "permissions": {"allow": ["Edit(/proj/.claude/**)"], "deny": []}
+    }
+    common.prune_empty_list_then_empty_section(all_settings, "permissions", "deny")
+    assert all_settings == {"permissions": {"allow": ["Edit(/proj/.claude/**)"]}}
+

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

@@ -355,6 +355,24 @@ def test_is_trust_entry_rejects_cross_project_path_suffix_collision() -> None:
     )
 
 
+def test_is_valid_project_root_shared_by_grant_and_revoke_modules(
+    tmp_path: Path,
+) -> None:
+    """Grant and revoke import the same helper, so both agree on the marker contract."""
+    grant_module = _load_grant_module()
+    revoke_module = _load_revoke_module()
+    git_marker_project_root = tmp_path / "git_project"
+    (git_marker_project_root / ".git").mkdir(parents=True)
+    claude_marker_project_root = tmp_path / "claude_project"
+    (claude_marker_project_root / ".claude").mkdir(parents=True)
+    bare_directory = tmp_path / "no_marker"
+    bare_directory.mkdir()
+    for each_module in (grant_module, revoke_module):
+        assert each_module.is_valid_project_root(git_marker_project_root) is True
+        assert each_module.is_valid_project_root(claude_marker_project_root) is True
+        assert each_module.is_valid_project_root(bare_directory) is False
+
+
 def test_second_grant_is_idempotent_when_no_other_settings_changed(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:

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/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',
 ]);
 
 /**