claude-dev-env 4.2.0 → 4.3.0

package/hooks/gh_post_body_texts.py

@@ -0,0 +1,195 @@
+"""Extract durable GitHub post body text for privacy checks."""
+
+from __future__ import annotations
+
+import shlex
+from pathlib import Path
+
+from blocking._gh_body_arg_utils import (
+    all_body_flags,
+    body_file_flag,
+    body_file_short_flag,
+    count_extra_tokens_to_skip_for_split_quoted_value,
+    get_logical_first_line,
+    is_unresolvable_shell_value,
+    match_body_file_equals_prefix,
+    match_body_flag_equals_prefix,
+    strip_surrounding_quotes,
+)
+from hooks_constants.gh_post_body_texts_constants import (
+    ALL_GH_POST_SUBCOMMANDS,
+    ALL_MCP_BODY_PARAM_NAMES,
+    BODY_FILE_ENCODING,
+    BODY_FLAG_WITH_VALUE_STEP,
+    GH_COMMAND_NAME,
+    MINIMUM_POST_SUBCOMMAND_TOKEN_COUNT,
+    TOKEN_JOIN_SEPARATOR,
+)
+
+
+def _is_environment_assignment(token: str) -> bool:
+    equals_index = token.find("=")
+    if equals_index <= 0:
+        return False
+    name_part = token[:equals_index]
+    if not (name_part[0].isalpha() or name_part[0] == "_"):
+        return False
+    return all(each_character.isalnum() or each_character == "_" for each_character in name_part)
+
+
+def _tokens_name_gh_post_command(all_command_tokens: list[str]) -> bool:
+    command_index = 0
+    while command_index < len(all_command_tokens) and _is_environment_assignment(
+        all_command_tokens[command_index]
+    ):
+        command_index += 1
+    if command_index >= len(all_command_tokens):
+        return False
+    if all_command_tokens[command_index] != GH_COMMAND_NAME:
+        return False
+    remaining_tokens = all_command_tokens[command_index + 1 :]
+    if len(remaining_tokens) < MINIMUM_POST_SUBCOMMAND_TOKEN_COUNT:
+        return False
+    post_noun, post_verb = remaining_tokens[:MINIMUM_POST_SUBCOMMAND_TOKEN_COUNT]
+    return post_verb in ALL_GH_POST_SUBCOMMANDS.get(post_noun, frozenset())
+
+
+def _reassemble_split_quoted_value(
+    value_token: str,
+    all_following_tokens: list[str],
+) -> tuple[str, int]:
+    extra_token_count = count_extra_tokens_to_skip_for_split_quoted_value(
+        all_following_tokens, value_token
+    )
+    if not extra_token_count:
+        return strip_surrounding_quotes(value_token), 0
+    joined_value = (
+        value_token
+        + TOKEN_JOIN_SEPARATOR
+        + TOKEN_JOIN_SEPARATOR.join(all_following_tokens[:extra_token_count])
+    )
+    return strip_surrounding_quotes(joined_value), extra_token_count
+
+
+def _extract_flag_value_at(
+    all_command_tokens: list[str],
+    token_index: int,
+) -> tuple[bool, str, int] | None:
+    current_token = all_command_tokens[token_index]
+    following_tokens = all_command_tokens[token_index + 1 :]
+    body_prefix = match_body_flag_equals_prefix(current_token)
+    if body_prefix is not None:
+        value, extra_count = _reassemble_split_quoted_value(
+            current_token[len(body_prefix) :], following_tokens
+        )
+        return False, value, token_index + 1 + extra_count
+    body_file_prefix = match_body_file_equals_prefix(current_token)
+    if body_file_prefix is not None:
+        value, extra_count = _reassemble_split_quoted_value(
+            current_token[len(body_file_prefix) :], following_tokens
+        )
+        return True, value, token_index + 1 + extra_count
+    if current_token in all_body_flags and following_tokens:
+        value, extra_count = _reassemble_split_quoted_value(
+            following_tokens[0], following_tokens[1:]
+        )
+        return False, value, token_index + BODY_FLAG_WITH_VALUE_STEP + extra_count
+    if current_token in (body_file_flag, body_file_short_flag) and following_tokens:
+        value, extra_count = _reassemble_split_quoted_value(
+            following_tokens[0], following_tokens[1:]
+        )
+        return True, value, token_index + BODY_FLAG_WITH_VALUE_STEP + extra_count
+    return None
+
+
+def _collect_body_flag_values(
+    all_command_tokens: list[str],
+) -> tuple[list[str], list[str]]:
+    all_inline_bodies: list[str] = []
+    all_body_file_paths: list[str] = []
+    token_index = 0
+    while token_index < len(all_command_tokens):
+        extraction = _extract_flag_value_at(all_command_tokens, token_index)
+        if extraction is None:
+            token_index += 1
+            continue
+        is_body_file, value, token_index = extraction
+        if is_body_file:
+            all_body_file_paths.append(value)
+        else:
+            all_inline_bodies.append(value)
+    return all_inline_bodies, all_body_file_paths
+
+
+def _read_body_file(
+    body_file_path: str,
+    working_directory: str | None,
+) -> str | None:
+    if is_unresolvable_shell_value(body_file_path):
+        return None
+    resolved_path = Path(body_file_path)
+    if not resolved_path.is_absolute() and working_directory:
+        resolved_path = Path(working_directory) / body_file_path
+    try:
+        return resolved_path.read_text(encoding=BODY_FILE_ENCODING)
+    except (OSError, UnicodeError):
+        return None
+
+
+def _body_texts_from_tokens(
+    all_command_tokens: list[str],
+    working_directory: str | None,
+) -> tuple[list[str], str | None]:
+    if not _tokens_name_gh_post_command(all_command_tokens):
+        return [], None
+    all_body_texts, all_body_file_paths = _collect_body_flag_values(all_command_tokens)
+    for each_path in all_body_file_paths:
+        file_text = _read_body_file(each_path, working_directory)
+        if file_text is None:
+            return [], (
+                "BLOCKED [pii_prevention_blocker]: durable post uses --body-file "
+                f"but '{each_path}' could not be read for PII scanning. Use an "
+                "absolute path, ensure the file exists, or pass --body text."
+            )
+        all_body_texts.append(file_text)
+    return all_body_texts, None
+
+
+def extract_gh_post_body_texts_for_privacy_gate(
+    command: str,
+    working_directory: str | None = None,
+) -> tuple[list[str], str | None]:
+    """Extract GitHub post text and reject unreadable declared body files.
+
+    Args:
+        command: Raw GitHub CLI command.
+        working_directory: Base directory for relative body-file paths.
+
+    Returns:
+        Body texts and no error, or no texts and a rejection message without body text.
+    """
+    logical_line = get_logical_first_line(command)
+    if not logical_line:
+        return [], None
+    try:
+        all_command_tokens = shlex.split(logical_line, posix=False)
+    except ValueError:
+        return [], None
+    return _body_texts_from_tokens(all_command_tokens, working_directory)
+
+
+def extract_mcp_body_texts(all_tool_input: dict[str, object]) -> list[str]:
+    """Extract body and comment strings from a GitHub tool request.
+
+    Args:
+        all_tool_input: GitHub tool input mapping.
+
+    Returns:
+        Nonempty body and comment values.
+    """
+    all_body_texts: list[str] = []
+    for each_name in ALL_MCP_BODY_PARAM_NAMES:
+        candidate_text = all_tool_input.get(each_name)
+        if isinstance(candidate_text, str) and candidate_text:
+            all_body_texts.append(candidate_text)
+    return all_body_texts

package/hooks/hooks.json

@@ -45,11 +45,6 @@
       {
         "matcher": "mcp__plugin_github_github__.*",
         "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/volatile_path_in_post_blocker.py",
-            "timeout": 10
-          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pii_prevention_blocker.py",
@@ -149,11 +144,6 @@
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/session_env_cleanup.py",
             "timeout": 10
           },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/gh_pr_author_session_cleanup.py",
-            "timeout": 30
-          },
           {
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/session_edit_tracker_cleanup.py",
@@ -251,11 +241,6 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/workflow/investigation_tracker_reset.py",
             "timeout": 30
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/observability/pr_description_writer_spawn_tracker.py",
-            "timeout": 30
           }
         ]
       },

package/hooks/hooks_constants/bash_post_call_dispatcher_constants.py

@@ -17,6 +17,5 @@ from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
 __all__ = ["ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES"]
 
 ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
-    BashHostedHookEntry("blocking/gh_pr_author_restore.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("observability/test_failure_recorder.py", ALL_BASH_ONLY_TOOL_NAMES),
 )

package/hooks/hooks_constants/bash_pre_tool_use_dispatcher_constants.py

@@ -56,7 +56,6 @@ class BashHostedHookEntry:
 
 ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
     BashHostedHookEntry("blocking/destructive_command_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
-    BashHostedHookEntry("blocking/gh_body_arg_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("blocking/shell_substitution_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("blocking/piped_pytest_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry(
@@ -65,15 +64,8 @@ ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
     ),
     BashHostedHookEntry("blocking/unscoped_search_blocker.py", ALL_BASH_AND_POWERSHELL_TOOL_NAMES),
     BashHostedHookEntry("blocking/nas_ssh_binary_enforcer.py", ALL_BASH_ONLY_TOOL_NAMES),
-    BashHostedHookEntry("blocking/volatile_path_in_post_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("blocking/pii_prevention_blocker.py", ALL_BASH_AND_POWERSHELL_TOOL_NAMES),
-    BashHostedHookEntry("blocking/conventional_pr_title_gate.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("blocking/block_main_commit.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("blocking/session_edit_stage_gate.py", ALL_BASH_ONLY_TOOL_NAMES),
-    BashHostedHookEntry("blocking/test_preflight_check.py", ALL_BASH_ONLY_TOOL_NAMES),
     BashHostedHookEntry("blocking/windows_rmtree_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
-    BashHostedHookEntry("blocking/gh_pr_author_enforcer.py", ALL_BASH_ONLY_TOOL_NAMES),
-    BashHostedHookEntry(
-        "blocking/pr_description_writer_gate.py", ALL_BASH_AND_POWERSHELL_TOOL_NAMES
-    ),
 )

package/hooks/hooks_constants/gh_post_body_texts_constants.py

@@ -0,0 +1,12 @@
+"""Configuration constants for GitHub post body extraction."""
+
+ALL_GH_POST_SUBCOMMANDS: dict[str, frozenset[str]] = {
+    "issue": frozenset({"comment", "create", "edit"}),
+    "pr": frozenset({"comment", "create", "edit", "review"}),
+}
+ALL_MCP_BODY_PARAM_NAMES: tuple[str, ...] = ("body", "comment")
+BODY_FILE_ENCODING = "utf-8"
+BODY_FLAG_WITH_VALUE_STEP = 2
+GH_COMMAND_NAME = "gh"
+MINIMUM_POST_SUBCOMMAND_TOKEN_COUNT = 2
+TOKEN_JOIN_SEPARATOR = " "

package/hooks/hooks_constants/test_bash_post_call_dispatcher_constants.py

@@ -6,13 +6,6 @@ from hooks_constants.bash_post_call_dispatcher_constants import (
 from hooks_constants.bash_pre_tool_use_dispatcher_constants import BASH_TOOL_NAME
 
 
-def test_roster_names_the_gh_pr_author_restore_hook() -> None:
-    all_script_paths = [
-        each_entry.script_relative_path for each_entry in ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES
-    ]
-    assert "blocking/gh_pr_author_restore.py" in all_script_paths
-
-
 def test_roster_names_the_test_failure_recorder_hook() -> None:
     all_script_paths = [
         each_entry.script_relative_path for each_entry in ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES

package/hooks/hooks_constants/test_bash_pre_tool_use_dispatcher_constants.py

@@ -20,28 +20,21 @@ POWERSHELL_TOOL_NAME = ALL_CONSTANT_BINDINGS["POWERSHELL_TOOL_NAME"]
 
 _EXPECTED_BASH_ORDER = (
     "blocking/destructive_command_blocker.py",
-    "blocking/gh_body_arg_blocker.py",
     "blocking/shell_substitution_blocker.py",
     "blocking/piped_pytest_blocker.py",
     "blocking/cursor_cli_python_misfire_blocker.py",
     "blocking/unscoped_search_blocker.py",
     "blocking/nas_ssh_binary_enforcer.py",
-    "blocking/volatile_path_in_post_blocker.py",
     "blocking/pii_prevention_blocker.py",
-    "blocking/conventional_pr_title_gate.py",
     "blocking/block_main_commit.py",
     "blocking/session_edit_stage_gate.py",
-    "blocking/test_preflight_check.py",
     "blocking/windows_rmtree_blocker.py",
-    "blocking/gh_pr_author_enforcer.py",
-    "blocking/pr_description_writer_gate.py",
 )
 
 _POWERSHELL_APPLICABLE = (
     "blocking/cursor_cli_python_misfire_blocker.py",
     "blocking/unscoped_search_blocker.py",
     "blocking/pii_prevention_blocker.py",
-    "blocking/pr_description_writer_gate.py",
 )
 
 

package/hooks/hooks_constants/test_failure_recorder_constants.py

@@ -6,9 +6,7 @@ tokens that keep the recognizer to one unchained command, the pytest program
 and Python interpreter basenames, and the flag-token marker the path
 extractor uses to skip an option rather than an existing test file argument.
 
-``BASH_TOOL_NAME`` lives in ``gh_pr_author_swap_constants`` already; this
-module reuses that name rather than a second literal. The pytest-program and
-interpreter recognition here is deliberately its own small, stdlib-only
+The pytest-program and interpreter recognition here is deliberately its own small, stdlib-only
 check rather than a reuse of ``piped_pytest_blocker_constants`` /
 ``pytest_invocation``: those solve the harder pipe-and-wrapper problem and
 pull in a much larger transitive import for every Bash call regardless of
@@ -19,6 +17,8 @@ from __future__ import annotations
 
 import re
 
+BASH_TOOL_NAME = "Bash"
+
 ALL_PYTEST_MENTION_SUBSTRINGS: tuple[str, ...] = ("pytest", "py.test")
 EXIT_CODE_ERROR_PREFIX: str = "Error: Exit code "
 OPTION_TOKEN_PREFIX: str = "-"

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.2.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/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.