claude-dev-env 1.70.0 → 1.71.0

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

@@ -27,6 +27,7 @@ Decomposition is by the **kind of docstring claim** that needs to be cross-check
 | O5 | Named-sentinel / filename references | A docstring names a sentinel marker, environment variable, filename, or magic string. Confirm the named token actually exists in the module body or in the repo's naming convention. |
 | 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. 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. 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`. |
 
 ---
 

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

@@ -1,4 +1,4 @@
-Audit [REPO/ARTIFACT] [TARGET_ID] for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A–N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 7 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
+Audit [REPO/ARTIFACT] [TARGET_ID] for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A–N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 8 sub-buckets below. Each sub-bucket REQUIRES at least one Shape A finding OR exactly one Shape B proof-of-absence with **at least 3 adversarial probes** specific to that sub-bucket. A sub-bucket returning neither is a protocol gap.
 
 [ARTIFACT METADATA — include every changed module's docstring AND the exported symbols of that module so the audit can compare claim vs body]
 
@@ -47,9 +47,13 @@ ID prefix: `find`.
 - When the diff includes a module split (one file becomes two), verify both modules' docstrings describe the responsibility each one actually owns after the split.
 - Adversarial probes: (a) for each module in the split, list its exported symbols and compare to the docstring's claimed responsibilities; (b) grep the responsibility's verb against the originating module — does the originating docstring still claim what moved; (c) check for cross-module imports that reveal which file hosts each responsibility.
 
+**O8. Companion-doc ordering/content vs producer**
+- When the diff 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 diff never touched the `.md` file, because the behavior change orphaned the doc claim.
+- Adversarial probes: (a) for each changed producer, name the artifact it builds and grep the skill's `SKILL.md` and sibling `.md` files for any sentence naming that artifact; (b) walk the producer body's build step — does it sort, or does it merge stored names and append in file order — and compare against the doc's order word (`sorted`, `alphabetical`); (c) check whether the doc's content claim (`just the at-risk names`, `only the current set`) hides merged-in prior entries the producer carries over from the stored file.
+
 ## Cross-bucket questions to answer at the end
 
-Q1: Across all 7 sub-buckets, which docstring claim is the most misleading — i.e., a future maintainer reading only the docstring would write or change code that contradicts the body? Cite file:line of the docstring AND the body line(s) that contradict it.
+Q1: Across all 8 sub-buckets, which docstring claim is the most misleading — i.e., a future maintainer reading only the docstring would write or change code that contradicts the body? Cite file:line of the docstring AND the body line(s) that contradict it.
 
 Q2: Which docstring claim is at highest risk of becoming load-bearing — i.e., a future caller or test author would rely on the claim to skip reading the body? Cite the claim and the use case.
 
@@ -57,13 +61,13 @@ Q3: Of the changed docstrings, which one most clearly shows a refactor was incom
 
 ## Output
 
-Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket O1-O7, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the docstring file:line, (b) the body file:line that contradicts it, and (c) one sentence describing the contradiction in concrete terms. Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 module-level docstring claims whose implementation moved during a refactor — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
+Lead: `Total: N (P0=N, P1=N, P2=N)`. For each sub-bucket O1-O8, produce Shape A or Shape B (with ≥3 probes). Each Shape A finding must cite (a) the docstring file:line, (b) the body file:line that contradicts it, and (c) one sentence describing the contradiction in concrete terms. Cross-bucket Q1-Q3 answers after the per-sub-bucket walk. Adversarial second pass: "assume your first pass missed at least 3 module-level docstring claims whose implementation moved during a refactor — find them." Open Questions section for ambiguities. Read-only. No edits, no commits.
 
 ---
 
 # Worked example: jl-cmd/claude-code-config PR #522
 
-Audit jl-cmd/claude-code-config PR #522 for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A-N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 7 sub-buckets below.
+Audit jl-cmd/claude-code-config PR #522 for **Category O only** (docstring / fixture-prose vs implementation drift). Skip A-N, P. Sub-bucket forced-exhaustion mode: Category O is decomposed into 8 sub-buckets below.
 
 PR #522 split `pr_description_command_parser.py` into two modules — the original parser and a new `pr_description_pr_number.py` — but the originating module's docstring still claims the PR-number recovery responsibility. A sibling change to `pr_description_body_audit.py` introduced a module docstring whose verb (`detects vague language`) overstates the module's actual responsibility (it only exposes `_extract_vague_scan_text()`; detection runs elsewhere).
 

package/hooks/blocking/claude_md_orphan_file_blocker.py

@@ -24,6 +24,7 @@ if _hooks_dir not in sys.path:
     sys.path.insert(0, _hooks_dir)
 
 from hooks_constants.claude_md_orphan_file_blocker_constants import (  # noqa: E402
+    ALL_NOISE_DIRECTORY_NAMES,
     ALL_REFERENCED_FILE_EXTENSIONS,
     CLAUDE_MD_FILENAME,
     CODE_FENCE_PATTERN,
@@ -237,13 +238,35 @@ class _SubtreeScan:
         self.was_scan_complete = was_scan_complete
 
 
+def _is_under_noise_directory(scan_root: Path, candidate_path: Path) -> bool:
+    """Return whether *candidate_path* lies inside a pruned noise directory.
+
+    A noise directory (``.git``, ``__pycache__``, ``node_modules``, and the test
+    and lint caches) holds volatile generated files that no CLAUDE.md table
+    documents, so the walk skips them. This keeps generated files out of the
+    basename set and keeps them from consuming the scan budget.
+
+    Args:
+        scan_root: The directory the walk descends from.
+        candidate_path: A path the walk yielded under the scan root.
+
+    Returns:
+        True when any path segment below *scan_root* names a noise directory.
+    """
+    try:
+        relative_segments = candidate_path.relative_to(scan_root).parts
+    except ValueError:
+        relative_segments = candidate_path.parts
+    return any(each_segment in ALL_NOISE_DIRECTORY_NAMES for each_segment in relative_segments)
+
+
 def _scan_subtree_basenames(scan_root: Path) -> _SubtreeScan:
     """Return the bounded basename scan of *scan_root*, skipping unreadable entries.
 
     Walks the subtree collecting each file's basename, stopping once the scan
-    budget is reached. A per-entry stat error skips that entry. The result records
-    whether the walk completed within the budget, so the caller knows whether the
-    set is authoritative.
+    budget is reached. A path inside a noise directory is pruned, and a per-entry
+    stat error skips that entry. The result records whether the walk completed
+    within the budget, so the caller knows whether the set is authoritative.
 
     Args:
         scan_root: The directory whose subtree bounds the existence search.
@@ -254,6 +277,8 @@ def _scan_subtree_basenames(scan_root: Path) -> _SubtreeScan:
     all_basenames: set[str] = set()
     scanned_count = 0
     for each_path in scan_root.rglob("*"):
+        if _is_under_noise_directory(scan_root, each_path):
+            continue
         try:
             if not each_path.is_file():
                 continue
@@ -270,7 +295,9 @@ def _filename_exists_under(scan_root: Path, filename: str) -> bool:
     """Return whether a file with basename *filename* exists anywhere under root.
 
     A direct probe that resolves one filename deterministically even when the
-    bounded subtree walk was truncated. An unreadable entry mid-walk is skipped.
+    bounded subtree walk was truncated. A match inside a noise directory is pruned
+    so the probe agrees with the bounded walk, and an unreadable entry mid-walk is
+    skipped.
 
     Args:
         scan_root: The directory whose subtree bounds the existence search.
@@ -280,6 +307,8 @@ def _filename_exists_under(scan_root: Path, filename: str) -> bool:
         True when at least one matching file is reachable under the scan root.
     """
     for each_match in scan_root.rglob(filename):
+        if _is_under_noise_directory(scan_root, each_match):
+            continue
         try:
             if each_match.is_file():
                 return True
@@ -327,9 +356,10 @@ def find_missing_filenames(content: str, claude_md_directory: Path) -> list[str]
     siblings. A table block that declares an explicit relative-path source (a
     ``../`` token in the block or the prose that introduces it) yields no findings
     for that block's rows, since those files legitimately live elsewhere; an
-    unrelated block in the same file is still checked. A filesystem error that
-    halts the whole subtree walk yields no findings (fail open), so an unreadable
-    tree never blocks a write.
+    unrelated block in the same file is still checked. When the content references
+    no bare filename, no findings result and the subtree walk is skipped. A
+    filesystem error that halts the whole subtree walk yields no findings (fail
+    open), so an unreadable tree never blocks a write.
 
     Args:
         content: The CLAUDE.md content being written.
@@ -340,6 +370,8 @@ def find_missing_filenames(content: str, claude_md_directory: Path) -> list[str]
         first-seen order with duplicates removed, capped at the issue budget.
     """
     referenced_filenames = find_referenced_filenames(content)
+    if not referenced_filenames:
+        return []
     scan_root = _resolve_scan_root(claude_md_directory)
     try:
         present_filenames = _present_referenced_filenames(referenced_filenames, scan_root)

package/hooks/blocking/test_claude_md_orphan_file_blocker.py

@@ -576,6 +576,42 @@ def test_oserror_during_subtree_walk_fails_open(
     assert missing_filenames == []
 
 
+def test_no_referenced_filenames_performs_no_subtree_walk(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+):
+    def _fail_if_walked(self, pattern):
+        raise AssertionError("rglob walked the subtree with no filenames to verify")
+
+    monkeypatch.setattr(Path, "rglob", _fail_if_walked)
+    claude_md_path = tmp_path / "CLAUDE.md"
+    content = (
+        "# example\n\n"
+        "| Task | Command |\n"
+        "|---|---|\n"
+        "| Run the tests | npm test |\n"
+    )
+    missing_filenames = find_missing_filenames(content, claude_md_path.parent)
+    assert missing_filenames == []
+
+
+def test_noise_directories_are_excluded_from_the_walk(tmp_path: Path):
+    package_directory = tmp_path / "package_directory"
+    package_directory.mkdir()
+    for each_noise_name in (".git", "__pycache__", "node_modules", ".pytest_cache", ".ruff_cache"):
+        noise_directory = tmp_path / each_noise_name
+        noise_directory.mkdir()
+        (noise_directory / "buried_target.py").write_text("x = 1\n", encoding="utf-8")
+    claude_md_path = package_directory / "CLAUDE.md"
+    content = (
+        "# example\n\n"
+        "| File | Note |\n"
+        "|---|---|\n"
+        "| `buried_target.py` | only present inside noise directories |\n"
+    )
+    missing_filenames = find_missing_filenames(content, claude_md_path.parent)
+    assert missing_filenames == ["buried_target.py"]
+
+
 def test_blocker_module_has_no_collection_parameter_naming_violations():
     blocker_source = Path(HOOK_SCRIPT_PATH).read_text(encoding="utf-8")
     assert check_collection_prefix(blocker_source, HOOK_SCRIPT_PATH) == []

package/hooks/git-hooks/CLAUDE.md

@@ -7,7 +7,7 @@ Native git hooks that run outside the Claude Code lifecycle — invoked directly
 | File | Git hook | What it does |
 |---|---|---|
 | `pre_commit.py` | `pre-commit` | Runs the CODE_RULES gate (`precommit_code_rules_gate.py`) over staged changes; exits 1 when any staged file has a blocking violation |
-| `pre_push.py` | `pre-push` | Runs the verified-commit gate check before a push reaches the remote |
+| `pre_push.py` | `pre-push` | Blocks a push that would land a non-`main` local branch onto remote `main` (or `master`), then runs the CODE_RULES gate over the commits about to be pushed |
 | `post_commit.py` | `post-commit` | Runs after a commit lands; performs any post-commit bookkeeping |
 | `gate_utils.py` | — | Shared helpers: resolves the gate script path, checks that the path is a safe regular file |
 | `test_config.py` | — | Test configuration helpers |

package/hooks/git-hooks/git_hooks_constants/__init__.py

@@ -16,6 +16,8 @@ DEFAULT_REMOTE_BASE_REFERENCE: str = "origin/HEAD"
 ALL_ZEROS_OBJECT_NAME_CHARACTER: str = "0"
 STDIN_LINE_FIELD_COUNT: int = 4
 STDIN_REMOTE_OBJECT_FIELD_INDEX: int = 3
+LOCAL_REFERENCE_FIELD_INDEX: int = 0
+REMOTE_REFERENCE_FIELD_INDEX: int = 2
 GATE_PATH_OVERRIDE_ENV_VAR: str = "CODE_RULES_GATE_PATH"
 CLAUDE_HOME_ENV_VAR: str = "CLAUDE_HOME"
 CLAUDE_HOME_DEFAULT_SUBDIRECTORY: str = ".claude"
@@ -46,3 +48,14 @@ NO_PARSEABLE_STDIN_LINES_MESSAGE: str = (
     "claude-dev-env pre-push: no parseable stdin lines; aborting"
 )
 NO_PARSEABLE_STDIN_LINES_SENTINEL: str = "__no_parseable_stdin_lines__"
+LOCAL_BRANCH_REFERENCE_PREFIX: str = "refs/heads/"
+ALL_PROTECTED_BRANCH_PUSH_NAMES: tuple[str, ...] = ("main", "master")
+PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE: int = 1
+PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE: str = (
+    "claude-dev-env pre-push: blocked a push of local branch {local_branch!r} "
+    "onto protected remote branch {remote_branch!r}.\n"
+    "A local branch that tracks origin/{remote_branch}, with push.default=upstream, "
+    "resolves a bare 'git push' to {remote_branch}.\n"
+    "To push the feature branch to its own ref, name the destination: "
+    "git push origin {local_branch}:refs/heads/{local_branch}"
+)

package/hooks/git-hooks/pre_push.py

@@ -1,20 +1,30 @@
 #!/usr/bin/env python3
-"""Git pre-push hook: run the CODE_RULES gate over commits about to be pushed.
+"""Git pre-push hook: guard the push destination, then run the CODE_RULES gate.
 
 Installed to the user's shared git-hooks directory via the claude-dev-env
 installer; git invokes this file as `pre-push` (the installer strips the
 `_` and `.py` suffix when copying into the live hooks path).
 
 Protocol: git pre-push provides remote name and URL as argv, then writes
-`<local-ref> <local-sha> <remote-ref> <remote-sha>` lines on stdin. The
-first non-zero remote-sha is used as the gate `--base`, so violations are
-scoped to commits that are not already on the remote. When every remote
-object name is zero (new branch) or stdin is empty, the gate falls back
-to the remote's default branch symbolic ref.
+`<local-ref> <local-sha> <remote-ref> <remote-sha>` lines on stdin.
+
+Destination guard: any line that pushes a local branch onto a protected
+remote branch (`main` or `master`) whose name differs from the local
+branch is blocked before the gate runs. This catches a branch that tracks
+`origin/main` under `push.default=upstream`, where a bare `git push`
+resolves to `main`. The guard runs whether or not the CODE_RULES gate is
+installed; deletions and same-name pushes pass.
+
+Gate base: the first non-zero remote-sha is used as the gate `--base`, so
+violations are scoped to commits that are not already on the remote. When
+every remote object name is zero (new branch) or stdin is empty, the gate
+falls back to the remote's default branch symbolic ref.
 
 Exit codes:
-  0 - commits to be pushed pass the gate (or the gate is not installed).
-  1 - one or more commits introduce blocking violations.
+  0 - the push destination is allowed and its commits pass the gate (or
+      the gate is not installed).
+  1 - the push would land a non-protected local branch onto a protected
+      remote branch, or a commit introduces a blocking violation.
   2 - unexpected invocation failure (e.g., subprocess could not launch).
 """
 
@@ -25,16 +35,22 @@ import sys
 from pathlib import Path
 
 from git_hooks_constants import (
+    ALL_PROTECTED_BRANCH_PUSH_NAMES,
     ALL_ZEROS_OBJECT_NAME_CHARACTER,
     BASE_REFERENCE_ARGUMENT,
     DEFAULT_REMOTE_BASE_REFERENCE,
     GATE_INFRASTRUCTURE_FAILURE_EXIT_CODE,
     INVOKE_GATE_FAILURE_MESSAGE,
+    LOCAL_BRANCH_REFERENCE_PREFIX,
+    LOCAL_REFERENCE_FIELD_INDEX,
     LOCAL_SHA_FIELD_INDEX,
     MALFORMED_STDIN_LINE_MESSAGE,
     NO_PARSEABLE_STDIN_LINES_MESSAGE,
     NO_PARSEABLE_STDIN_LINES_SENTINEL,
     PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE,
+    PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE,
+    PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE,
+    REMOTE_REFERENCE_FIELD_INDEX,
     STDIN_LINE_FIELD_COUNT,
     STDIN_READ_FAILURE_MESSAGE,
     STDIN_REMOTE_OBJECT_FIELD_INDEX,
@@ -88,6 +104,36 @@ def resolve_base_reference_from_stdin(stdin_text: str) -> str | None:
     return default_remote_base_reference
 
 
+def find_protected_branch_push_violation(stdin_text: str) -> tuple[str, str] | None:
+    stdin_line_field_count = STDIN_LINE_FIELD_COUNT
+    local_reference_field_index = LOCAL_REFERENCE_FIELD_INDEX
+    local_sha_field_index = LOCAL_SHA_FIELD_INDEX
+    remote_reference_field_index = REMOTE_REFERENCE_FIELD_INDEX
+    local_branch_reference_prefix = LOCAL_BRANCH_REFERENCE_PREFIX
+    protected_branch_push_names = ALL_PROTECTED_BRANCH_PUSH_NAMES
+    for each_line in stdin_text.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line:
+            continue
+        fields = stripped_line.split()
+        if len(fields) < stdin_line_field_count:
+            continue
+        if is_all_zeros_object_name(fields[local_sha_field_index]):
+            continue
+        local_branch_name = fields[local_reference_field_index].removeprefix(
+            local_branch_reference_prefix
+        )
+        remote_branch_name = fields[remote_reference_field_index].removeprefix(
+            local_branch_reference_prefix
+        )
+        if (
+            remote_branch_name in protected_branch_push_names
+            and local_branch_name != remote_branch_name
+        ):
+            return (local_branch_name, remote_branch_name)
+    return None
+
+
 def invoke_gate(gate_script_path: Path, base_reference: str) -> int:
     base_reference_argument = BASE_REFERENCE_ARGUMENT
     invoke_gate_failure_message = INVOKE_GATE_FAILURE_MESSAGE
@@ -118,13 +164,8 @@ def main() -> int:
     pre_push_gate_script_not_found_message = PRE_PUSH_GATE_SCRIPT_NOT_FOUND_MESSAGE
     no_parseable_stdin_lines_message = NO_PARSEABLE_STDIN_LINES_MESSAGE
     no_parseable_stdin_lines_sentinel = NO_PARSEABLE_STDIN_LINES_SENTINEL
-    gate_script_path, exact_allowed_path = resolve_gate_script_path()
-    if not is_safe_regular_file(gate_script_path, exact_allowed_path):
-        print(
-            pre_push_gate_script_not_found_message.format(path=gate_script_path),
-            file=sys.stderr,
-        )
-        return 0
+    protected_branch_push_block_message = PROTECTED_BRANCH_PUSH_BLOCK_MESSAGE
+    protected_branch_push_block_exit_code = PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE
     try:
         stdin_text = sys.stdin.read()
     except OSError as read_error:
@@ -133,6 +174,24 @@ def main() -> int:
             file=sys.stderr,
         )
         return gate_infrastructure_failure_exit_code
+    protected_branch_push_violation = find_protected_branch_push_violation(stdin_text)
+    if protected_branch_push_violation is not None:
+        local_branch_name, remote_branch_name = protected_branch_push_violation
+        print(
+            protected_branch_push_block_message.format(
+                local_branch=local_branch_name,
+                remote_branch=remote_branch_name,
+            ),
+            file=sys.stderr,
+        )
+        return protected_branch_push_block_exit_code
+    gate_script_path, exact_allowed_path = resolve_gate_script_path()
+    if not is_safe_regular_file(gate_script_path, exact_allowed_path):
+        print(
+            pre_push_gate_script_not_found_message.format(path=gate_script_path),
+            file=sys.stderr,
+        )
+        return 0
     base_reference = resolve_base_reference_from_stdin(stdin_text)
     if base_reference is None:
         return 0

package/hooks/git-hooks/test_pre_push.py

@@ -321,3 +321,121 @@ def test_invoke_gate_uses_resolved_path(
     assert exit_code == 0
     executed_path = recorded_path_file.read_text(encoding="utf-8")
     assert executed_path == str(resolved_path)
+
+
+def test_find_protected_branch_push_violation_flags_feature_branch_to_main() -> None:
+    stdin_text = (
+        f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation == ("feat/example", "main")
+
+
+def test_find_protected_branch_push_violation_flags_feature_branch_to_master() -> None:
+    stdin_text = (
+        f"refs/heads/topic {NON_ZERO_LOCAL_SHA} refs/heads/master {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation == ("topic", "master")
+
+
+def test_find_protected_branch_push_violation_allows_main_onto_main() -> None:
+    stdin_text = (
+        f"refs/heads/main {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation is None
+
+
+def test_find_protected_branch_push_violation_allows_feature_onto_own_ref() -> None:
+    stdin_text = (
+        f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/feat/example {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation is None
+
+
+def test_find_protected_branch_push_violation_ignores_deletion_of_main() -> None:
+    stdin_text = (
+        f"(delete) {ALL_ZEROS_OBJECT_NAME} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+    )
+
+    violation = pre_push.find_protected_branch_push_violation(stdin_text)
+
+    assert violation is None
+
+
+def test_main_blocks_feature_branch_push_onto_main(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    passing_gate_path = tmp_path / "gate.py"
+    passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == git_hooks_constants.PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE
+    captured = capsys.readouterr()
+    assert "feat/example" in captured.err
+    assert "main" in captured.err
+
+
+def test_main_blocks_protected_push_even_when_gate_script_missing(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    monkeypatch.setenv(
+        "CODE_RULES_GATE_PATH",
+        str(tmp_path / "does_not_exist.py"),
+    )
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            f"refs/heads/feat/example {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == git_hooks_constants.PROTECTED_BRANCH_PUSH_BLOCK_EXIT_CODE
+    captured = capsys.readouterr()
+    assert "feat/example" in captured.err
+
+
+def test_main_allows_main_onto_main_push(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    passing_gate_path = tmp_path / "gate.py"
+    passing_gate_path.write_text("import sys\nsys.exit(0)\n", encoding="utf-8")
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(passing_gate_path))
+    monkeypatch.setattr(
+        sys,
+        "stdin",
+        io.StringIO(
+            f"refs/heads/main {NON_ZERO_LOCAL_SHA} refs/heads/main {NON_ZERO_REMOTE_SHA_ONE}\n"
+        ),
+    )
+
+    exit_code = pre_push.main()
+
+    assert exit_code == 0

package/hooks/hooks_constants/claude_md_orphan_file_blocker_constants.py

@@ -8,8 +8,8 @@ subdirectories, and its siblings), the table points a reader at a file that is
 not there. This module holds the patterns that find those cells, the filename
 extensions that mark a cell as a file reference, the region-boundary marker that
 scopes a prose region to one section, the relative-path marker that exempts a
-cross-directory table block, the subtree scan budget, and the block-message text
-the hook emits.
+cross-directory table block, the directory names the subtree walk prunes, the
+subtree scan budget, and the block-message text the hook emits.
 """
 
 import re
@@ -23,6 +23,7 @@ __all__ = [
     "REGION_BOUNDARY_PATTERN",
     "RELATIVE_PATH_SOURCE_PATTERN",
     "ALL_REFERENCED_FILE_EXTENSIONS",
+    "ALL_NOISE_DIRECTORY_NAMES",
     "MAX_SUBTREE_FILES_SCANNED",
     "MAX_ORPHAN_FILE_ISSUES",
     "ORPHAN_FILE_MESSAGE_TEMPLATE",
@@ -65,6 +66,16 @@ ALL_REFERENCED_FILE_EXTENSIONS: frozenset[str] = frozenset(
     }
 )
 
+ALL_NOISE_DIRECTORY_NAMES: frozenset[str] = frozenset(
+    {
+        ".git",
+        "__pycache__",
+        "node_modules",
+        ".pytest_cache",
+        ".ruff_cache",
+    }
+)
+
 MAX_SUBTREE_FILES_SCANNED: int = 5000
 
 MAX_ORPHAN_FILE_ISSUES: int = 20

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.70.0",
+    "version": "1.71.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/docstring-prose-matches-implementation.md

@@ -1,6 +1,6 @@
 # Docstring Prose Matches Implementation
 
-**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps.
+**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps. It applies equally to a skill's companion `SKILL.md` (or any sibling `.md`) that describes a producer the skill's `scripts/` carry out: a doc sentence that claims a produced artifact's ordering or content is the prose this rule governs, and it tracks the producer function's own docstring and body.
 
 ## Rule
 
@@ -17,6 +17,7 @@ Read the body and the docstring side by side:
 - **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. When the body routes to the same fallback from two or more early-return guards (`if a is None: fallback(); return` and `if random() < p: fallback(); return`), the prose enumerates both guards. The `check_docstring_fallback_branch_coverage` gate blocks the single-condition form of this drift at Write/Edit time.
 - **Step order.** A docstring that says `A then B then C` matches the call order in the body.
 - **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
+- **Companion-doc ordering and content claims.** A `SKILL.md` (or sibling `.md`) sentence that names a produced artifact and claims its order (`sorted`, `alphabetical`, `in sorted order`) or its content (`the at-risk names`, `just the current set`) matches the producer function's docstring and body for that same artifact. A producer that builds the artifact by merging stored names with new names and appending — preserving file order, not re-sorting the union — leaves a doc that still says `sorted` drifted on both counts: the order claim is wrong, and the content claim hides the merged-in prior entries. When the producer's ordering or union changes, the same change updates the companion doc. The two move together in one commit, even when the producer edit does not touch the `.md` file.
 
 When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
 
@@ -39,6 +40,8 @@ A docstring that enumerates "attribute read, augmented-assignment target, class-
 
 This drift class is sub-bucket **O6** in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` (free-form `Note:` / `Returns:` / responsibility-list claims). The audit teammate lists every prose enumeration in a changed docstring and verifies each item against the body, and lists every union member / suppressor / step in the body and verifies each appears in the prose. A union member or suppressor in the body that the prose omits is an O6 finding. The single-condition shared-fallback shape of this drift is gated deterministically by `check_docstring_fallback_branch_coverage` (`packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`); the audit lane covers every O6 shape the gate cannot match.
 
+When a changed PR touches a producer function whose ordering or union shifts, the O8 audit lane also reads that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact. A doc sentence that claims the artifact is `sorted` or holds `just the at-risk names` while the producer merges prior names and appends without re-sorting is an O8 finding, even when the PR diff never touched the `.md` file — the behavior change orphaned the doc claim.
+
 ## Why
 
 A docstring enumeration earns its place by being trustworthy. A complete list lets a reader reason about the function without scanning the body; a list missing one item is worse than no list, because it asserts completeness it does not have. Naming this standard makes the gap a first-class finding at write time and at audit, rather than a surprise a reader hits months later.