claude-dev-env 4.1.0 → 4.3.0

package/hooks/hooks_constants/test_gh_post_body_texts_constants.py

@@ -0,0 +1,19 @@
+"""Tests for GitHub post body extraction constants."""
+
+from hooks_constants import gh_post_body_texts_constants as constants
+
+
+def test_post_actions_cover_pull_requests_and_issues() -> None:
+    assert constants.ALL_GH_POST_SUBCOMMANDS == {
+        "issue": frozenset({"comment", "create", "edit"}),
+        "pr": frozenset({"comment", "create", "edit", "review"}),
+    }
+    assert constants.ALL_MCP_BODY_PARAM_NAMES == ("body", "comment")
+
+
+def test_parser_constants_are_stable() -> None:
+    assert constants.BODY_FILE_ENCODING == "utf-8"
+    assert constants.BODY_FLAG_WITH_VALUE_STEP == 2
+    assert constants.GH_COMMAND_NAME == "gh"
+    assert constants.MINIMUM_POST_SUBCOMMAND_TOKEN_COUNT == 2
+    assert constants.TOKEN_JOIN_SEPARATOR == " "

package/hooks/observability/test_failure_recorder.py

@@ -101,13 +101,13 @@ try:
     for each_bootstrap_directory in (_hooks_root_directory, _blocking_directory):
         if each_bootstrap_directory not in sys.path:
             sys.path.insert(0, each_bootstrap_directory)
-    from hooks_constants.gh_pr_author_swap_constants import BASH_TOOL_NAME
     from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
     from hooks_constants.test_failure_recorder_constants import (
         ALL_CHAINING_OPERATOR_SUBSTRINGS,
         ALL_PYTEST_MENTION_SUBSTRINGS,
         ALL_PYTEST_PROGRAM_BASENAMES,
         ALL_REDIRECTION_TOKENS,
+        BASH_TOOL_NAME,
         EXIT_CODE_ERROR_PREFIX,
         MODULE_RUN_FLAG,
         NODE_ID_FILE_PATH_SEPARATOR,

package/hooks/pyproject.toml

@@ -24,7 +24,7 @@ exclude = [
 
 
 [[tool.mypy.overrides]]
-module = ["exempt_paths", "code_rules_path_utils", "gh_pr_author_enforcer"]
+module = ["exempt_paths", "code_rules_path_utils"]
 warn_unused_ignores = false
 
 [[tool.mypy.overrides]]

package/hooks/test_gh_post_body_texts.py

@@ -0,0 +1,79 @@
+"""Tests for durable GitHub post body extraction."""
+
+from pathlib import Path
+
+import pytest
+
+from gh_post_body_texts import (
+    extract_gh_post_body_texts_for_privacy_gate,
+    extract_mcp_body_texts,
+)
+
+
+@pytest.mark.parametrize(
+    ("command", "expected_text"),
+    [
+        ('gh pr create --body "pull request text"', "pull request text"),
+        ('gh pr comment 12 --body="comment text"', "comment text"),
+        ('gh issue edit 7 -b "issue text"', "issue text"),
+        ('GH_HOST=github.example gh pr review 8 --body "review text"', "review text"),
+    ],
+)
+def test_inline_post_bodies_are_extracted(command: str, expected_text: str) -> None:
+    all_body_texts, deny_reason = extract_gh_post_body_texts_for_privacy_gate(command)
+    assert all_body_texts == [expected_text]
+    assert deny_reason is None
+
+
+def test_relative_body_file_uses_supplied_working_directory(tmp_path: Path) -> None:
+    body_file = tmp_path / "body.md"
+    body_file.write_text("body file text", encoding="utf-8")
+    all_body_texts, deny_reason = extract_gh_post_body_texts_for_privacy_gate(
+        "gh pr comment 12 --body-file body.md",
+        str(tmp_path),
+    )
+    assert all_body_texts == ["body file text"]
+    assert deny_reason is None
+
+
+@pytest.mark.parametrize("body_file_text", ["missing.md", "$BODY_FILE", "-"])
+def test_unreadable_body_file_fails_closed(body_file_text: str) -> None:
+    all_body_texts, deny_reason = extract_gh_post_body_texts_for_privacy_gate(
+        f"gh pr comment 12 --body-file {body_file_text}"
+    )
+    assert all_body_texts == []
+    assert deny_reason is not None
+    assert "could not be read" in deny_reason
+
+
+def test_invalid_utf8_body_file_fails_closed(tmp_path: Path) -> None:
+    body_file = tmp_path / "body.md"
+    body_file.write_bytes(b"\xff")
+    all_body_texts, deny_reason = extract_gh_post_body_texts_for_privacy_gate(
+        f'gh issue create --body-file "{body_file}"'
+    )
+    assert all_body_texts == []
+    assert deny_reason is not None
+
+
+@pytest.mark.parametrize(
+    "command",
+    [
+        "gh pr view 12",
+        'echo "gh pr comment 12 --body text"',
+        "git status",
+        "",
+    ],
+)
+def test_non_post_commands_have_no_body(command: str) -> None:
+    assert extract_gh_post_body_texts_for_privacy_gate(command) == ([], None)
+
+
+def test_mcp_body_and_comment_values_are_extracted() -> None:
+    assert extract_mcp_body_texts(
+        {"body": "body text", "comment": "comment text", "title": "ignored"}
+    ) == ["body text", "comment text"]
+
+
+def test_mcp_non_string_and_empty_values_are_ignored() -> None:
+    assert extract_mcp_body_texts({"body": "", "comment": 7}) == []

package/package.json

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

package/rules/durable-post-artifacts.md

@@ -1,38 +1,49 @@
-# Durable Post Artifacts
+# GitHub post input rules
 
-**When this applies:** Any GitHub post that lives on the server — an issue, a pull request, a comment, or a review — created through `gh` (`gh pr create/comment/edit/review`, `gh issue create/comment/edit`) or a GitHub MCP post tool.
+## When this applies
+
+Use this rule for a GitHub issue, pull request, comment, or review created
+through `gh` or a GitHub MCP post tool.
 
 ## Rule
 
-A post lives forever. Job scratch directories, worktrees, and system temp folders do not — they are cleaned soon after the run that made them. So a post must never point at a path in that scratch. The moment the directory is cleaned, the reference breaks and the reader is left with a dead path.
+A post remains after the job ends. Job scratch directories, worktrees, and
+system temp folders do not. Do not put a path from one of those directories in
+a post.
 
-Handle the two kinds of content differently:
+Handle text and binary content differently:
 
-- **Text data** (logs, tables, diffs, stack traces): paste the actual text inline in the post body. Do not link a scratch file that holds it.
-- **Binary artifacts** (images, screenshots, archives): upload the file to the repository's durable `artifacts` release and link the permanent URL. Use the helper:
+- **Text data** such as logs, tables, diffs, and stack traces belongs inline in
+  the post body. Do not link a scratch file that holds text data.
+- **Binary artifacts** such as images, screenshots, and archives belong in the
+  repository's durable `artifacts` release. Use the helper:
 
   ```
   python3 ~/.claude/scripts/gh_artifact_upload.py <file-path> <owner/repo>
   ```
 
-  It ensures the repository has a prerelease tagged `artifacts`, uploads the file under a `YYYYMMDD_HHMMSS_<name>` asset name, and prints the permanent download URL. Put that URL in the post.
+  The helper creates the `artifacts` prerelease when needed, uploads the file
+  under a `YYYYMMDD_HHMMSS_<name>` asset name, and prints a permanent download
+  URL. Put that URL in the post.
 
 ## Volatile paths that must not appear in a post body
 
-- A job scratch directory (`.claude-profile-a/jobs/`)
-- A worktree (`.claude/worktrees/`)
-- A system temp location (`AppData\Local\Temp`, `%TEMP%`, `$env:TEMP`, `/tmp/`)
-- The job scratch environment variable (`$CLAUDE_JOB_DIR`)
-
-Both slash directions count.
-
-The worktree and job-scratch entries count as a path when either:
+- A job scratch directory: `.claude-profile-a/jobs/`
+- A worktree: `.claude/worktrees/`
+- A system temp location: `AppData\\Local\\Temp`, `%TEMP%`, `$env:TEMP`, or
+  `/tmp/`
+- The job scratch environment variable: `$CLAUDE_JOB_DIR`
 
-- A `/` or `\` sits right before them — a drive-letter path (`C:\Users\me\.claude\worktrees\wt\f.py`), a home path (`~/.claude/worktrees/wt`), or a POSIX absolute path (`/home/me/.claude-profile-a/jobs/j/log.txt`).
-- A path segment follows them — a relative path that names a child under that directory (`see .claude/worktrees/wt-1/notes.md`, a markdown link target, or `cd .claude/worktrees/wt-199`).
+Both slash directions count. The path rule applies when a slash or backslash
+precedes a marker, or when a path segment follows it. A standalone directory
+name does not form a path.
 
-With neither anchor the text names the directory rather than something inside it, and it posts — a quoted config constant, a backticked directory name, or a placeholder form such as `.claude/worktrees/<name>`. Un-backticked prose that puts a word immediately after the marker reads the same as a relative path and is blocked; the placeholder form is the documented escape.
+## Validation
 
-## Enforcement
+Run `.agents/skills/_shared/pr-loop/scripts/durable_post_lint.py` before the
+server write. Pass the matching action and body file. Use `pr-create`,
+`pr-edit`, `pr-comment`, `pr-review`, `issue-create`, `issue-edit`,
+`issue-comment`, or `github-mcp-post`.
 
-The `volatile_path_in_post_blocker` PreToolUse hook reads the body of each `gh` post command and each GitHub MCP post call, scans it for these markers, and blocks the post when it finds one. For a `--body-file`, the hook reads the file and scans its contents, so writing the body to a temp file and passing it with `--body-file` stays allowed — what the hook rejects is a volatile path inside the text that gets posted.
+The linter reads the body file and reports a volatile local path without
+printing the body. Fix the body and rerun the linter before posting.

package/rules/filesystem-search.md

@@ -1,6 +1,6 @@
 # Filesystem Search
 
-**When this applies:** Any search for files by name, path, extension, size, or date — through `es.exe`, a shell `find`, a recursive `Get-ChildItem` / `gci` / `dir` / `ls -R`, or the harness Grep and Glob tools.
+**When this applies:** Any search for files by name, path, extension, size, or date. That includes `es.exe`, a shell `find`, a recursive `Get-ChildItem` / `gci` / `dir` / `ls -R`, or the harness Grep and Glob tools.
 
 ## The scope invariant
 
@@ -14,7 +14,7 @@ Three tools are equally sanctioned; pick by what you know:
 
 | You know | Use |
 |---|---|
-| The exact path | `Read` — no search at all |
+| The exact path | `Read`. Do not search. |
 | A name, extension, or date, on Windows | `es.exe` with a path scope |
 | A name or path pattern | The harness `Glob` tool |
 | Text inside files | The harness `Grep` tool |
@@ -39,13 +39,13 @@ When `es.exe` fails or returns nothing, fall back to `Glob` or `Grep` without pa
 | Git Bash drive root | `find /c -name '*.py'` |
 | Windows drive root | `find C:\ -name foo` / `Get-ChildItem C:\ -Recurse` |
 | Bare home | `find ~ -name README.md` / `find $HOME -type f` |
-| Network share root | `find //server/share -name x` — a path under the share (`//server/share/project/src`) is allowed |
+| Network share root | `find //server/share -name x`. A path under the share (`//server/share/project/src`) is allowed |
 
 ## Shell batching
 
 Issue one shell search at a time when the walk is large. Parallel full-tree searches contend for the shell and can lock the host. Harness `Grep` and `Glob` calls carry no such cost and run in parallel freely.
 
-## Enforcement
+## Search controls
 
 - `unscoped_search_blocker` (PreToolUse on Bash and PowerShell, hosted by `bash_pre_tool_use_dispatcher`) denies a walk from an unscoped root and returns the scoped alternative.
-- `es_exe_path_rewriter` (PreToolUse on Bash) substitutes `{project-name}` placeholders and bare registry keys in an `es.exe` command with their quoted absolute paths, read from `~/.claude/project-paths.json`. It allows and rewrites; it never blocks, and a machine with no registry file passes the command through unchanged. `scripts/setup_project_paths.py` writes the registry.
+- For Everything searches that use a project name, run `python "${CLAUDE_SKILL_DIR}/scripts/everything_search.py" <project-name> <search arguments>`. An exact project name becomes its path from `~/.claude/project-paths.json`. The command then starts `es.exe` without a shell. `scripts/setup_project_paths.py` writes the registry.

package/rules/gh-cli-conventions.md

@@ -1,26 +1,36 @@
-# gh CLI Conventions
+# gh CLI conventions
 
-Two call shapes the `gh` CLI gets wrong by default.
+Two `gh` call shapes need explicit handling.
 
-## Body content goes in a file
+## Put body content in a file
 
-Every `gh` command carrying markdown body content (`gh pr create/edit/comment/review`, `gh issue create/edit/comment`) uses `--body-file <path>` with a temp file — never a `--body` / `-b` string, where backticks land on GitHub as a literal `` \` ``. Write the temp file BOM-free:
+Every `gh` command that carries markdown body content uses
+`--body-file <path>`. This applies to `gh pr create`, `gh pr edit`,
+`gh pr comment`, `gh pr review`, `gh issue create`, `gh issue edit`, and
+`gh issue comment`. Never pass a `--body` or `-b` string. Write the file as
+BOM-free UTF-8:
 
 ```powershell
 [IO.File]::WriteAllText($bodyPath, $body, [Text.UTF8Encoding]::new($false))
 ```
 
-MCP GitHub tools take `body` as a structured parameter and are unaffected.
+MCP GitHub tools take `body` as a structured parameter. Write the same body to
+a UTF-8 file and run the shared linter before sending that parameter.
 
-`gh_body_arg_blocker.py` (PreToolUse on Bash, hosted by `bash_pre_tool_use_dispatcher`) blocks `--body <arg>` and returns the corrective message.
+For pull requests, use
+`.agents/skills/pull-request/scripts/pull_request.py`. It passes
+`--body-file` to `gh` after the action-aware linter succeeds. For issues and
+GitHub MCP posts, run the linter directly with `issue-create`, `issue-edit`,
+`issue-comment`, or `github-mcp-post` as the action.
 
 ## Paginated reads slurp before they filter
 
-Every `gh api` read of a paginated GitHub list endpoint (PR `reviews` / `comments` / `files`, issue `comments`, `pulls`, `issues`) uses `--paginate --slurp` piped to **external** `jq`. The built-in `--jq` runs per page, so a cross-page operation like `sort_by | last` gives a wrong-but-confident result.
+Every `gh api` read of a paginated GitHub list endpoint uses
+`--paginate --slurp` and pipes the result to external `jq`. This applies to PR
+reviews, comments, and files, plus issue comments, pulls, and issues. The
+built-in `--jq` runs once per page and can produce a wrong cross-page result.
 
-Single-object endpoints (`pulls/<n>`, `issues/<n>`) skip pagination and may use `--jq` directly. For a newest-first walk, sort the slurped array and take the last element; for single-page bounds, cap with a `per_page` query parameter.
-
-## Sibling rules
-
-- [`destructive-commands.md`](destructive-commands.md) — why a body describing `rm -rf` must travel by file path.
-- [`durable-post-artifacts.md`](durable-post-artifacts.md) — what a post body may reference.
+Single-object endpoints such as `pulls/<n>` and `issues/<n>` do not need
+pagination and may use `--jq` directly. For a newest-first walk, sort the
+slurped array and take the last element. For one page, cap the request with a
+`per_page` query parameter.

package/rules/git-workflow.md

@@ -1,8 +1,8 @@
-# Git Workflow
+# Git workflow
 
-User-level rule: applies to **every** git repo that uses GitHub with `gh` (no exceptions for “small” or non-primary repos unless the user says otherwise in the session).
+User-level rule: applies to **every** git repo that uses GitHub with `gh`. Small or non-primary repos follow the same rule unless the user says otherwise in the session.
 
-## Workflow Decision Tree
+## Workflow decision tree
 
 **When to use stacked PRs:** Feature B depends on Feature A's implementation
 
@@ -13,19 +13,32 @@ User-level rule: applies to **every** git repo that uses GitHub with `gh` (no ex
 2. Get reviewed and MERGE infrastructure first
 3. Launch parallel feature PRs that use merged infrastructure
 
-## PR Submission Rules
+## Pull request submission rules
 
 **ALWAYS create PRs as DRAFT:** Use `gh pr create --draft` for ALL PRs
 
-**The pr-description-writer agent writes the body:** Spawn the `pr-description-writer` agent (Agent tool, `subagent_type` `pr-description-writer`), then publish what it returns with `--body-file`. `pr_description_writer_gate.py` (PreToolUse on Bash and PowerShell, hosted by `bash_pre_tool_use_dispatcher`) denies a `gh pr create` when the session records no such spawn. A trailing `# pr-description-skip` comment on the command opts out for a body you write yourself.
+Use the `pr-description-writer` agent before creating a pull request or
+rewriting its full description. Publish its title and body file through
+`.agents/skills/pull-request/scripts/pull_request.py`. The
+`pr-title-description` skill may review the writer's output but cannot replace
+the required writer.
 
-## Git Golden Rules (NON-NEGOTIABLE)
+Run `_shared/pr-loop/scripts/durable_post_lint.py` before any pull request,
+issue, or GitHub MCP post. The linter checks the action-specific title, body,
+and volatile-path rules before credential lookup or network access.
+
+Use `.agents/skills/pull-request/scripts/recover_legacy_author.py
+<exact-state-file> --confirm-inactive` only for one explicitly selected legacy
+author record. Do not infer a record from age alone. Keep every other record
+untouched.
+
+## Git golden rules
 
 1. **DRAFT BEFORE PUSH**: When pushing ANYTHING to a PR, it MUST be in draft state first
    - Before push: `gh pr ready --undo`
    - After review approved: `gh pr ready`
 
-## Never Commit Working Documents or Images
+## Never commit working documents or images
 
 **NEVER commit these files to the repo:**
 
@@ -49,4 +62,4 @@ An image a PR needs as visual evidence is not an exception to that row. Upload i
 
 Repair only reported findings, then re-verify after every repair.
 
-Every `gh` post in this workflow uses `--body-file` per `gh-cli-conventions.md` and keeps volatile scratch paths out per `durable-post-artifacts.md`; stage session edits per `re-stage-before-commit.md` before each commit.
+Every `gh` post in this workflow uses `--body-file` per `gh-cli-conventions.md` and keeps volatile scratch paths out per `durable-post-artifacts.md`. Stage session edits per `re-stage-before-commit.md` before each commit.

package/scripts/policy_lint/adapter_configuration.py

@@ -23,30 +23,69 @@ def hook_configuration_diagnostics(
     adapter_support._document_path(repository_root, document)
     if document.path.name != "hooks.json":
         return ()
-    all_messages = _hook_configuration_messages(document.text)
+    all_messages = _hook_configuration_messages(document.text, document.prior_text)
     return adapter_support._diagnostics_for_messages(
         document, "hook-configuration", all_messages
     )
 
 
-def _hook_configuration_messages(configuration_text: str) -> tuple[str, ...]:
+def _parsed_configuration(
+    configuration_text: str,
+    invalid_json_message: str,
+    invalid_object_message: str,
+) -> dict[object, object]:
     try:
         parsed_configuration = json.loads(configuration_text)
-    except json.JSONDecodeError:
-        return ("Hook configuration is not valid JSON",)
+    except json.JSONDecodeError as error:
+        raise ValueError(invalid_json_message) from error
     if not isinstance(parsed_configuration, dict):
-        return ("Hook configuration must be an object",)
-    all_registered_strings = _registered_hook_strings(parsed_configuration)
-    if any(
-        _contains_action_boundary_marker(each_string)
-        for each_string in all_registered_strings
-    ):
+        raise TypeError(invalid_object_message)
+    return parsed_configuration
+
+
+def _action_boundary_strings(
+    all_configuration_entries: dict[object, object],
+) -> frozenset[str]:
+    return frozenset(
+        each_string
+        for each_string in _registered_hook_strings(all_configuration_entries)
+        if _contains_action_boundary_marker(each_string)
+    )
+
+
+def _hook_configuration_messages(
+    configuration_text: str,
+    prior_configuration_text: str | None,
+) -> tuple[str, ...]:
+    try:
+        current_configuration = _parsed_configuration(
+            configuration_text,
+            "Hook configuration is not valid JSON",
+            "Hook configuration must be an object",
+        )
+        all_current_action_boundary_strings = _action_boundary_strings(
+            current_configuration
+        )
+        if prior_configuration_text is None:
+            all_prior_action_boundary_strings: frozenset[str] = frozenset()
+        else:
+            prior_configuration = _parsed_configuration(
+                prior_configuration_text,
+                "Prior hook configuration is not valid JSON",
+                "Prior hook configuration must be an object",
+            )
+            all_prior_action_boundary_strings = _action_boundary_strings(
+                prior_configuration
+            )
+    except (TypeError, ValueError) as error:
+        return (str(error),)
+    if all_current_action_boundary_strings - all_prior_action_boundary_strings:
         return ("Hook configuration registers a deny, block, or ask policy path",)
     return ()
 
 
 def _registered_hook_strings(
-    all_configuration_entries: dict[object, object]
+    all_configuration_entries: dict[object, object],
 ) -> tuple[str, ...]:
     all_registered_strings: list[str] = []
     for each_key, each_entry in all_configuration_entries.items():
@@ -62,7 +101,9 @@ def _registered_strings_for_entry(
     all_registered_strings: list[str] = []
     if each_key in constants.ALL_HOOK_REGISTRATION_KEYS and isinstance(each_entry, str):
         all_registered_strings.append(each_entry)
-    if each_key in constants.ALL_DECISION_REGISTRATION_KEYS and isinstance(each_entry, str):
+    if each_key in constants.ALL_DECISION_REGISTRATION_KEYS and isinstance(
+        each_entry, str
+    ):
         all_registered_strings.append(each_entry)
     all_registered_strings.extend(_registered_nested_strings(each_entry))
     return tuple(all_registered_strings)

package/scripts/repository_checks/config/constants.py

@@ -131,11 +131,6 @@ ALL_TRACKED_SECRET_EXACT_EXEMPTIONS: frozenset[tuple[str, str, str]] = frozenset
             "home-path",
             "09f83c224a02c370d3d63de5c330e1a830fc92866330fc7963b5b5fd20ffcb91",
         ),
-        (
-            "packages/claude-dev-env/hooks/blocking/volatile_path_in_post_blocker.py",
-            "home-path",
-            "ed9203c8078e4c6b832600085f28f24656d679aa8dca82ecc2557afc3df25036",
-        ),
         (
             "packages/claude-dev-env/hooks/hooks_constants/hardcoded_user_path_constants.py",
             "home-path",

package/scripts/tests/test_adapter_configuration.py

@@ -0,0 +1,54 @@
+"""Incremental migration tests for the hook-configuration lint rule."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import replace
+from pathlib import Path
+
+from policy_lint import adapters
+from policy_lint.model import Document
+
+
+def _hook_document(all_commands: list[str], prior_text: str) -> Document:
+    current_text = json.dumps(
+        {
+            "hooks": {
+                "PreToolUse": [
+                    {
+                        "hooks": [
+                            {"command": each_command} for each_command in all_commands
+                        ]
+                    }
+                ]
+            }
+        }
+    )
+    return replace(
+        Document.from_text("hooks/hooks.json", current_text),
+        prior_text=prior_text,
+    )
+
+
+def test_incremental_blocker_removal_is_clean(tmp_path: Path) -> None:
+    prior_text = _hook_document(
+        ["hooks/blocking/first.py", "hooks/blocking/second.py"],
+        '{"hooks": {}}',
+    ).text
+    current_document = _hook_document(
+        ["hooks/blocking/second.py"],
+        prior_text,
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
+def test_new_blocker_in_staged_change_is_rejected(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/new.py"],
+        '{"hooks": {}}',
+    )
+    all_diagnostics = adapters.hook_configuration_diagnostics(
+        current_document, tmp_path
+    )
+    assert len(all_diagnostics) == 1
+    assert all_diagnostics[0].rule_id == "hook-configuration"