claude-dev-env 8.46.31 → 8.47.1

package/hooks/blocking/followup_pr_dedupe.py

@@ -0,0 +1,202 @@
+"""Find an open follow-up pull request that already holds a new one's parent findings."""
+
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+import sys
+import urllib.request
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+
+hooks_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_directory not in sys.path:
+    sys.path.insert(0, hooks_directory)
+
+from hooks_constants.followup_pr_dedupe_constants import (
+    ALL_BODY_FILE_OPTIONS,
+    ALL_BODY_OPTIONS,
+    ALL_REPOSITORY_OPTIONS,
+    CREATE_PULL_REQUEST_TOOL_SUFFIX,
+    DUPLICATE_FOLLOWUP_REASON_TEMPLATE,
+    FOLLOWUP_PARENT_PATTERN,
+    ALL_GH_CREATE_WORDS,
+    ALL_GIT_REMOTE_COMMAND_WORDS,
+    GITHUB_API_ROOT,
+    GITHUB_REMOTE_PATTERN,
+    OPEN_PULL_REQUESTS_PATH_TEMPLATE,
+    READ_TIMEOUT_SECONDS,
+    STANDARD_INPUT_PATH,
+)
+from hooks_constants.pr_lifecycle_skill_gate_constants import SHELL_TOOL_NAMES
+from hooks_constants.pytest_invocation import unquoted_token
+from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
+from hooks_constants.shell_command_pipeline import pipeline_segments_for_command
+from hooks_constants.shell_command_wrappers import (
+    all_wrapped_command_texts,
+    segment_program_and_arguments,
+)
+
+
+@dataclass(frozen=True)
+class PullRequestDraft:
+    """The repository and body of a pull request about to be opened."""
+
+    owner: str
+    repo: str
+    body: str
+
+
+OpenPullRequestReader = Callable[[str, str], list[Mapping[str, object]]]
+
+
+def followup_parent_number(body: str) -> int | None:
+    """Return the parent number a "Follow-up to #N" line names, or None."""
+    match = re.search(FOLLOWUP_PARENT_PATTERN, body, re.IGNORECASE)
+    return int(match.group(1)) if match else None
+
+
+def read_open_pull_requests(owner: str, repo: str) -> list[Mapping[str, object]]:
+    """Read one page of a repository's open pull requests from the GitHub API."""
+    url = GITHUB_API_ROOT + OPEN_PULL_REQUESTS_PATH_TEMPLATE.format(owner=owner, repo=repo)
+    request = urllib.request.Request(url, headers={"Accept": "application/vnd.github+json"})
+    with urllib.request.urlopen(request, timeout=READ_TIMEOUT_SECONDS) as reply:
+        answer = json.loads(reply.read())
+    return [each_entry for each_entry in answer if isinstance(each_entry, dict)]
+
+
+def _option_value(all_arguments: list[str], all_option_names: frozenset[str]) -> str | None:
+    for each_index, each_argument in enumerate(all_arguments):
+        option_name, separator, inline_value = each_argument.partition("=")
+        if option_name not in all_option_names:
+            continue
+        if separator:
+            return unquoted_token(inline_value)
+        if each_index + 1 < len(all_arguments):
+            return unquoted_token(all_arguments[each_index + 1])
+    return None
+
+
+def _body_from_arguments(all_arguments: list[str], working_directory: str) -> str | None:
+    inline_body = _option_value(all_arguments, ALL_BODY_OPTIONS)
+    if inline_body is not None:
+        return inline_body
+    body_path = _option_value(all_arguments, ALL_BODY_FILE_OPTIONS)
+    if body_path is None or body_path == STANDARD_INPUT_PATH:
+        return None
+    try:
+        return (Path(working_directory) / body_path).read_text(
+            encoding=UTF8_ENCODING, errors=DECODE_ERRORS_POLICY
+        )
+    except OSError:
+        return None
+
+
+def _origin_repository(working_directory: str) -> tuple[str, str] | None:
+    try:
+        completed = subprocess.run(
+            ALL_GIT_REMOTE_COMMAND_WORDS,
+            cwd=working_directory or None,
+            capture_output=True,
+            text=True,
+            timeout=READ_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    match = re.search(GITHUB_REMOTE_PATTERN, completed.stdout.strip())
+    return (match.group(1), match.group(2)) if match else None
+
+
+def _repository_from_arguments(
+    all_arguments: list[str], working_directory: str
+) -> tuple[str, str] | None:
+    named_repository = _option_value(all_arguments, ALL_REPOSITORY_OPTIONS)
+    if named_repository is None:
+        return _origin_repository(working_directory)
+    owner, separator, repo = named_repository.rpartition("/")
+    owner = owner.rpartition("/")[2]
+    return (owner, repo) if separator and owner and repo else None
+
+
+def _segment_draft(all_segment_tokens: list[str], working_directory: str) -> PullRequestDraft | None:
+    program, all_arguments = segment_program_and_arguments(all_segment_tokens)
+    if program != "gh" or all_arguments[: len(ALL_GH_CREATE_WORDS)] != ALL_GH_CREATE_WORDS:
+        return None
+    body = _body_from_arguments(all_arguments, working_directory)
+    repository = _repository_from_arguments(all_arguments, working_directory)
+    if body is None or repository is None:
+        return None
+    return PullRequestDraft(repository[0], repository[1], body)
+
+
+def _shell_draft(command: str, working_directory: str) -> PullRequestDraft | None:
+    all_drafts = (
+        _segment_draft(each_segment, working_directory)
+        for each_text in all_wrapped_command_texts(command)
+        for each_segment, _each_following_operator in pipeline_segments_for_command(each_text)
+    )
+    return next((each_draft for each_draft in all_drafts if each_draft is not None), None)
+
+
+def pull_request_draft(all_payload_fields: Mapping[str, object]) -> PullRequestDraft | None:
+    """Return the pull request a PreToolUse payload is about to open, or None."""
+    tool_name = all_payload_fields.get("tool_name")
+    tool_input = all_payload_fields.get("tool_input")
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        return None
+    if tool_name.endswith(CREATE_PULL_REQUEST_TOOL_SUFFIX):
+        owner, repo, body = (tool_input.get(each_key) for each_key in ("owner", "repo", "body"))
+        if isinstance(owner, str) and isinstance(repo, str) and isinstance(body, str):
+            return PullRequestDraft(owner, repo, body)
+        return None
+    command = tool_input.get("command")
+    if tool_name not in SHELL_TOOL_NAMES or not isinstance(command, str):
+        return None
+    working_directory = all_payload_fields.get("cwd")
+    return _shell_draft(command, working_directory if isinstance(working_directory, str) else "")
+
+
+def _reason_for_parent(
+    parent_number: int, all_open_pull_requests: list[Mapping[str, object]]
+) -> str | None:
+    all_same_parent = [
+        each_pull_request
+        for each_pull_request in all_open_pull_requests
+        if followup_parent_number(str(each_pull_request.get("body") or "")) == parent_number
+    ]
+    if not all_same_parent:
+        return None
+    return DUPLICATE_FOLLOWUP_REASON_TEMPLATE.format(
+        open_number=all_same_parent[0].get("number"),
+        parent_number=parent_number,
+        open_url=all_same_parent[0].get("html_url"),
+    )
+
+
+def duplicate_followup_reason(
+    all_payload_fields: Mapping[str, object],
+    read_open: OpenPullRequestReader | None = None,
+) -> str | None:
+    """Return a deny reason when an open pull request already follows up the same parent.
+
+    Any read failure returns None, so the pull request opens.
+
+    Args:
+        all_payload_fields: The parsed PreToolUse input.
+        read_open: Reads the open pull requests of an owner and repository;
+            None reads them from the GitHub API.
+    """
+    draft = pull_request_draft(all_payload_fields)
+    if draft is None:
+        return None
+    parent_number = followup_parent_number(draft.body)
+    if parent_number is None:
+        return None
+    try:
+        all_open_pull_requests = (read_open or read_open_pull_requests)(draft.owner, draft.repo)
+    except Exception:
+        return None
+    return _reason_for_parent(parent_number, all_open_pull_requests)

package/hooks/blocking/pr_lifecycle_skill_gate.py

@@ -50,6 +50,7 @@ from hooks_constants.pr_lifecycle_skill_gate_constants import (
 )
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.setup_project_paths_constants import DECODE_ERRORS_POLICY, UTF8_ENCODING
+from blocking.followup_pr_dedupe import duplicate_followup_reason
 from transcript_skill_scan import is_skill_loaded_after_last_compaction
 
 
@@ -195,26 +196,35 @@ def _subagent_transcript_path(all_payload_fields: dict[str, object]) -> str | No
 
 
 def decision_for(all_payload_fields: dict[str, object]) -> dict[str, object] | None:
-    """Return a deny for a governed action with readable, unloaded transcripts.
+    """Return a deny for an unloaded skill or a second follow-up pull request for one parent.
 
     Args:
         all_payload_fields: The parsed PreToolUse input.
     """
     if not _is_governed_action(all_payload_fields):
         return None
+    if _is_skill_unloaded(all_payload_fields):
+        return _deny(DENY_REASON)
+    duplicate_reason = duplicate_followup_reason(all_payload_fields)
+    return None if duplicate_reason is None else _deny(duplicate_reason)
+
+
+def _is_skill_unloaded(all_payload_fields: dict[str, object]) -> bool:
     paths = [all_payload_fields.get(field) for field in ALL_TRANSCRIPT_PATH_FIELDS]
     paths.append(_subagent_transcript_path(all_payload_fields))
     readable_paths = list(dict.fromkeys(path for path in paths if isinstance(path, str) and path))
     if not readable_paths:
-        return None
+        return False
     statuses = [_transcript_load_status(path) for path in readable_paths]
-    if any(status is None or status for status in statuses):
-        return None
+    return not any(status is None or status for status in statuses)
+
+
+def _deny(reason: str) -> dict[str, object]:
     return {
         HOOK_SPECIFIC_OUTPUT_KEY: {
             "hookEventName": HOOK_EVENT_NAME,
             PERMISSION_DECISION_KEY: DENY_DECISION,
-            PERMISSION_DECISION_REASON_KEY: DENY_REASON,
+            PERMISSION_DECISION_REASON_KEY: reason,
         }
     }
 

package/hooks/blocking/test_followup_pr_dedupe.py

@@ -0,0 +1,86 @@
+"""Behavior tests for the one-follow-up-pull-request-per-parent check."""
+
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+
+HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
+if str(HOOKS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(HOOKS_DIRECTORY))
+
+from blocking import followup_pr_dedupe as dedupe
+
+OPEN_FOLLOWUP = {
+    "number": 1769,
+    "html_url": "https://github.com/jl-cmd/claude-dev-env/pull/1769",
+    "body": "Follow-up to #1731. Fixes one smell.",
+}
+OTHER_FOLLOWUP = {
+    "number": 1777,
+    "html_url": "https://github.com/jl-cmd/claude-dev-env/pull/1777",
+    "body": "follow-up to #17",
+}
+
+
+def _reader(all_open: list[Mapping[str, object]]) -> dedupe.OpenPullRequestReader:
+    def read(owner: str, repo: str) -> list[Mapping[str, object]]:
+        assert (owner, repo) == ("jl-cmd", "claude-dev-env")
+        return all_open
+
+    return read
+
+
+def _failing_reader(*_all_reader_arguments: str) -> list[Mapping[str, object]]:
+    raise OSError("network down")
+
+
+def _mcp_payload(body: str) -> dict[str, object]:
+    return {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": body},
+    }
+
+
+def test_second_followup_for_one_parent_is_denied() -> None:
+    reason = dedupe.duplicate_followup_reason(
+        _mcp_payload("FOLLOW-UP TO #1731: another smell"), _reader([OTHER_FOLLOWUP, OPEN_FOLLOWUP])
+    )
+    assert reason is not None
+    assert "#1769" in reason
+    assert "Add this finding to the open follow-up pull request #1769" in reason
+
+
+def test_first_followup_passes() -> None:
+    assert dedupe.duplicate_followup_reason(_mcp_payload("Follow-up to #1731"), _reader([OTHER_FOLLOWUP])) is None
+
+
+def test_parent_prefix_number_does_not_match_longer_parent() -> None:
+    assert dedupe.duplicate_followup_reason(_mcp_payload("Follow-up to #173"), _reader([OPEN_FOLLOWUP])) is None
+
+
+def test_non_followup_pull_request_skips_the_read() -> None:
+    assert dedupe.duplicate_followup_reason(_mcp_payload("Adds a hook."), _failing_reader) is None
+
+
+def test_read_failure_fails_open() -> None:
+    assert dedupe.duplicate_followup_reason(_mcp_payload("Follow-up to #1731"), _failing_reader) is None
+
+
+def test_gh_pr_create_inline_body_is_denied() -> None:
+    payload = {
+        "tool_name": "Bash",
+        "tool_input": {"command": "gh pr create -R jl-cmd/claude-dev-env --title t --body 'Follow-up to #1731'"},
+    }
+    reason = dedupe.duplicate_followup_reason(payload, _reader([OPEN_FOLLOWUP]))
+    assert reason is not None and "pull request #1769" in reason
+
+
+def test_powershell_body_file_is_denied(tmp_path: Path) -> None:
+    (tmp_path / "body.md").write_text("Follow-up to #1731\n", encoding="utf-8")
+    payload = {
+        "tool_name": "PowerShell",
+        "cwd": str(tmp_path),
+        "tool_input": {"command": "gh pr create --repo jl-cmd/claude-dev-env --body-file body.md"},
+    }
+    reason = dedupe.duplicate_followup_reason(payload, _reader([OPEN_FOLLOWUP]))
+    assert reason is not None and "pull request #1769" in reason

package/hooks/blocking/test_pr_lifecycle_skill_gate.py

@@ -10,6 +10,7 @@ HOOKS_DIRECTORY = Path(__file__).resolve().parent.parent
 if str(HOOKS_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(HOOKS_DIRECTORY))
 
+from blocking import followup_pr_dedupe as gate_dedupe
 from blocking import pr_lifecycle_skill_gate as gate
 from hooks_constants.pr_lifecycle_skill_gate_constants import DENY_REASON
 
@@ -231,3 +232,27 @@ def test_hook_has_its_own_pre_tool_use_registration() -> None:
             ],
         }
     ]
+
+
+def test_loaded_skill_still_denies_a_second_followup_for_one_parent(tmp_path: Path) -> None:
+    payload = {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": "Follow-up to #1731"},
+        "transcript_path": str(_transcript(tmp_path, "pr-lifecycle")),
+    }
+    open_followup = {"number": 1769, "html_url": "https://github.com/jl-cmd/claude-dev-env/pull/1769", "body": "Follow-up to #1731"}
+    with patch.object(gate_dedupe, "read_open_pull_requests", return_value=[open_followup]):
+        decision = gate.decision_for(payload)
+    assert decision is not None
+    assert decision["hookSpecificOutput"]["permissionDecision"] == "deny"
+    assert "open follow-up pull request #1769" in decision["hookSpecificOutput"]["permissionDecisionReason"]
+
+
+def test_loaded_skill_allows_a_followup_when_the_read_fails(tmp_path: Path) -> None:
+    payload = {
+        "tool_name": "mcp__github__create_pull_request",
+        "tool_input": {"owner": "jl-cmd", "repo": "claude-dev-env", "body": "Follow-up to #1731"},
+        "transcript_path": str(_transcript(tmp_path, "pr-lifecycle")),
+    }
+    with patch.object(gate_dedupe, "read_open_pull_requests", side_effect=OSError("offline")):
+        assert gate.decision_for(payload) is None

package/hooks/hooks_constants/followup_pr_dedupe_constants.py

@@ -0,0 +1,19 @@
+"""Constants for the one-follow-up-pull-request-per-parent check."""
+
+FOLLOWUP_PARENT_PATTERN = r"follow[- ]?up to #(\d+)(?!\d)"
+GITHUB_API_ROOT = "https://api.github.com"
+OPEN_PULL_REQUESTS_PATH_TEMPLATE = "/repos/{owner}/{repo}/pulls?state=open&per_page=100"
+READ_TIMEOUT_SECONDS = 4
+ALL_GH_CREATE_WORDS = ["pr", "create"]
+ALL_BODY_OPTIONS = frozenset({"-b", "--body"})
+ALL_BODY_FILE_OPTIONS = frozenset({"-F", "--body-file"})
+ALL_REPOSITORY_OPTIONS = frozenset({"-R", "--repo"})
+STANDARD_INPUT_PATH = "-"
+CREATE_PULL_REQUEST_TOOL_SUFFIX = "__create_pull_request"
+GITHUB_REMOTE_PATTERN = r"github\.com[:/]([^/\s]+)/([^/\s]+?)(?:\.git)?/?$"
+ALL_GIT_REMOTE_COMMAND_WORDS = ("git", "remote", "get-url", "origin")
+DUPLICATE_FOLLOWUP_REASON_TEMPLATE = (
+    "Pull request #{open_number} already holds the follow-up findings for parent #{parent_number}"
+    " ({open_url}). Add this finding to the open follow-up pull request #{open_number}."
+    " One combined follow-up pull request per parent pull request."
+)

package/hooks/hooks_constants/test_followup_pr_dedupe_constants.py

@@ -0,0 +1,12 @@
+import re
+
+from hooks_constants import followup_pr_dedupe_constants as constants
+
+
+def test_parent_pattern_reads_both_spellings_and_stops_at_the_number() -> None:
+    assert re.search(constants.FOLLOWUP_PARENT_PATTERN, "followup to #12", re.IGNORECASE)
+    assert re.search(constants.FOLLOWUP_PARENT_PATTERN, "Follow-up to #1731", re.IGNORECASE).group(1) == "1731"
+
+
+def test_read_timeout_fits_inside_the_hook_timeout() -> None:
+    assert constants.READ_TIMEOUT_SECONDS * 2 < 10

package/package.json

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

package/rules/flag-non-breaking-findings.md

@@ -13,7 +13,7 @@ paths:
 
 **When:** Writing a local gate or changing a check's severity.
 
-Give every check ID a breaking or smell severity row; style and structure findings are smells. Fail the gate and stop for a bug, secret, broken test, syntax error, or instruction file that cannot load. Record a smell in `.claude/followups/smells.jsonl`, proceed, and fix it in a later pull request; ledger failure leaves the gate decision unchanged. Treat an unclassified check as breaking.
+Give every check ID a breaking or smell severity row; style and structure findings are smells. Fail the gate and stop for a bug, secret, broken test, syntax error, or instruction file that cannot load. Record a smell in `.claude/followups/smells.jsonl`, proceed, and fix it later in one combined follow-up pull request per parent pull request, whose body names the parent as `Follow-up to #N`; ledger failure leaves the gate decision unchanged. Treat an unclassified check as breaking.
 
 **Enforcement:** none, the agent applies it.
 

package/scripts/dev_env_scripts_constants/followup_pr_uniqueness_constants.py

@@ -0,0 +1,14 @@
+"""Constants for the one-follow-up-pull-request-per-parent CI check."""
+
+FOLLOWUP_PARENT_PATTERN = r"follow[- ]?up to #(\d+)(?!\d)"
+RULE_START_TIMESTAMP = "2026-10-04T12:00:00Z"
+OPEN_PULL_REQUESTS_ENDPOINT_TEMPLATE = "{api_root}/repos/{slug}/pulls?state=open&per_page=100"
+PASS_EXIT_CODE = 0
+DUPLICATE_EXIT_CODE = 1
+ERROR_EXIT_CODE = 2
+PASS_MESSAGE = "No earlier open follow-up pull request names this parent."
+DUPLICATE_FOLLOWUP_MESSAGE_TEMPLATE = (
+    "Pull request #{open_number} already holds the follow-up findings for parent #{parent_number}"
+    " ({open_url}). Add this finding to the open follow-up pull request #{open_number}."
+    " One combined follow-up pull request per parent pull request."
+)

package/scripts/followup_pr_uniqueness.py

@@ -0,0 +1,132 @@
+"""Fail a follow-up pull request when an earlier open one already names its parent.
+
+Usage::
+
+    python followup_pr_uniqueness.py OWNER/REPO NUMBER
+
+Only pull requests opened at or after the rule start take part, so follow-up
+groups opened before the rule existed stay green.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from collections.abc import Mapping, Sequence
+
+from dev_env_scripts_constants.followup_pr_uniqueness_constants import (
+    DUPLICATE_EXIT_CODE,
+    DUPLICATE_FOLLOWUP_MESSAGE_TEMPLATE,
+    ERROR_EXIT_CODE,
+    FOLLOWUP_PARENT_PATTERN,
+    OPEN_PULL_REQUESTS_ENDPOINT_TEMPLATE,
+    PASS_EXIT_CODE,
+    PASS_MESSAGE,
+    RULE_START_TIMESTAMP,
+)
+from dev_env_scripts_constants.review_closure_constants import GET_METHOD, GITHUB_API_ROOT
+from pr_verification.github_parsing import GitHubError
+from review_closure_github import github_token, read_pull_request, request_json
+
+
+def followup_parent_number(body: object) -> int | None:
+    """Read the parent number a "Follow-up to #N" line names.
+
+    Args:
+        body: The pull request body, or any other value GitHub sent.
+
+    Returns:
+        The parent number, or None when the body names no parent.
+    """
+    if not isinstance(body, str):
+        return None
+    match = re.search(FOLLOWUP_PARENT_PATTERN, body, re.IGNORECASE)
+    return int(match.group(1)) if match else None
+
+
+def _is_under_rule(all_pull_request_fields: Mapping[str, object]) -> bool:
+    created_at = all_pull_request_fields.get("created_at")
+    return isinstance(created_at, str) and created_at >= RULE_START_TIMESTAMP
+
+
+def _earlier_followups(
+    own_number: int, parent_number: int, all_open_pull_requests: Sequence[Mapping[str, object]]
+) -> list[Mapping[str, object]]:
+    return [
+        each_open
+        for each_open in all_open_pull_requests
+        if isinstance(each_open.get("number"), int)
+        and each_open["number"] < own_number
+        and _is_under_rule(each_open)
+        and followup_parent_number(each_open.get("body")) == parent_number
+    ]
+
+
+def duplicate_message(
+    all_pull_request_fields: Mapping[str, object],
+    all_open_pull_requests: Sequence[Mapping[str, object]],
+) -> str | None:
+    """Return the failure message when an earlier open follow-up names the same parent.
+
+    Args:
+        all_pull_request_fields: The pull request under test.
+        all_open_pull_requests: The repository's open pull requests.
+
+    Returns:
+        The failure message, or None when this pull request may stay open.
+    """
+    parent_number = followup_parent_number(all_pull_request_fields.get("body"))
+    own_number = all_pull_request_fields.get("number")
+    if parent_number is None or not isinstance(own_number, int) or not _is_under_rule(all_pull_request_fields):
+        return None
+    all_earlier_followups = _earlier_followups(own_number, parent_number, all_open_pull_requests)
+    if not all_earlier_followups:
+        return None
+    first_followup = min(all_earlier_followups, key=lambda entry: entry["number"])
+    return DUPLICATE_FOLLOWUP_MESSAGE_TEMPLATE.format(
+        open_number=first_followup["number"],
+        parent_number=parent_number,
+        open_url=first_followup.get("html_url"),
+    )
+
+
+def _open_pull_requests(slug: str, token: str) -> list[Mapping[str, object]]:
+    document = request_json(
+        GET_METHOD,
+        OPEN_PULL_REQUESTS_ENDPOINT_TEMPLATE.format(api_root=GITHUB_API_ROOT, slug=slug),
+        token,
+        None,
+    )
+    if not isinstance(document, list):
+        raise GitHubError(str(document))
+    return [each_entry for each_entry in document if isinstance(each_entry, Mapping)]
+
+
+def main(all_arguments: Sequence[str]) -> int:
+    """Print the verdict for one pull request and return its exit code.
+
+    Args:
+        all_arguments: The command line, without the program name.
+
+    Returns:
+        Zero when no earlier follow-up names the parent, one on a duplicate,
+        and two when GitHub could not be read.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("slug")
+    parser.add_argument("number", type=int)
+    parsed = parser.parse_args(all_arguments)
+    try:
+        token = github_token()
+        pull_request = read_pull_request(parsed.slug, parsed.number, token)
+        message = duplicate_message(pull_request, _open_pull_requests(parsed.slug, token))
+    except GitHubError as failure:
+        print(failure, file=sys.stderr)
+        return ERROR_EXIT_CODE
+    print(message or PASS_MESSAGE)
+    return PASS_EXIT_CODE if message is None else DUPLICATE_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/scripts/policy_lint/adapter_configuration.py

@@ -140,7 +140,9 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
 
     The pull request lifecycle gate denies a commit, push, pull request, or
     merge call once, until the session loads the ``pr-lifecycle`` skill. It
-    decides when a rule set loads and no code or safety policy.
+    decides when a rule set loads and no code or safety policy. It also denies
+    a second open ``Follow-up to #N`` pull request for one parent, a delivery
+    rule that names the open follow-up to extend.
 
     The step-note gate allows every call until the user runs ``/step-notes on``.
     It asks for a readable status line and decides no code or safety policy.

package/scripts/tests/test_followup_pr_uniqueness.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parents[1]
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+import followup_pr_uniqueness as command
+from pr_verification.github_parsing import GitHubError
+
+AFTER_RULE = "2026-10-05T00:00:00Z"
+BEFORE_RULE = "2026-10-04T03:00:00Z"
+
+
+def pull_request(number: int, body: str, created_at: str = AFTER_RULE) -> dict[str, object]:
+    return {
+        "number": number,
+        "body": body,
+        "created_at": created_at,
+        "html_url": f"https://github.com/jl-cmd/claude-dev-env/pull/{number}",
+    }
+
+
+def test_second_followup_fails_naming_the_first() -> None:
+    first = pull_request(1900, "Follow-up to #1731")
+    second = pull_request(1901, "follow-up to #1731: one more")
+    message = command.duplicate_message(second, [first, second])
+    assert message is not None
+    assert "Add this finding to the open follow-up pull request #1900" in message
+
+
+def test_first_followup_stays_green_after_a_duplicate_opens() -> None:
+    first = pull_request(1900, "Follow-up to #1731")
+    second = pull_request(1901, "Follow-up to #1731")
+    assert command.duplicate_message(first, [first, second]) is None
+
+
+def test_followups_opened_before_the_rule_do_not_count() -> None:
+    legacy = pull_request(1769, "Follow-up to #1731", BEFORE_RULE)
+    assert command.duplicate_message(pull_request(1900, "Follow-up to #1731"), [legacy]) is None
+    later_legacy = pull_request(1770, "Follow-up to #1731", BEFORE_RULE)
+    assert command.duplicate_message(later_legacy, [legacy, later_legacy]) is None
+
+
+def test_other_parent_and_non_followup_pass() -> None:
+    first = pull_request(1900, "Follow-up to #173")
+    assert command.duplicate_message(pull_request(1901, "Follow-up to #1731"), [first]) is None
+    assert command.duplicate_message(pull_request(1901, "Adds a hook."), [first]) is None
+
+
+def test_main_exits_one_on_duplicate_and_two_on_read_failure(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    first = pull_request(1900, "Follow-up to #1731")
+    second = pull_request(1901, "Follow-up to #1731")
+    monkeypatch.setattr(command, "github_token", lambda: "token")
+    monkeypatch.setattr(command, "read_pull_request", lambda slug, number, token: second)
+    monkeypatch.setattr(command, "request_json", lambda method, url, token, body: [first, second])
+    assert command.main(["jl-cmd/claude-dev-env", "1901"]) == 1
+    assert "#1900" in capsys.readouterr().out
+
+    def fail(slug: str, number: int, token: str) -> dict[str, object]:
+        raise GitHubError("offline")
+
+    monkeypatch.setattr(command, "read_pull_request", fail)
+    assert command.main(["jl-cmd/claude-dev-env", "1901"]) == 2
+
+
+def test_parent_number_reads_both_spellings_and_ignores_other_values() -> None:
+    assert command.followup_parent_number("FOLLOWUP to #1731.") == 1731
+    assert command.followup_parent_number("Follow-up to #17310") == 17310
+    assert command.followup_parent_number(None) is None

package/scripts/tests/test_pr_verification_lock.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import subprocess
 import sys
+import threading
 import time
 from pathlib import Path
 from typing import cast
@@ -50,6 +51,7 @@ RESULT_WAIT_SECONDS = 5
 PROCESS_WAIT_SECONDS = 10
 POLL_INTERVAL_SECONDS = 0.01
 LEGACY_LOCK_CONTENT = "legacy owner metadata"
+DELAYED_OUTCOME_WRITE_SECONDS = 0.2
 BASE_PYTHON_EXECUTABLE = cast(str, getattr(sys, "_base_executable", sys.executable))
 
 
@@ -72,13 +74,20 @@ def _start_lock_contender(
     )
 
 
+def _read_reported_outcome(result_path: Path) -> str:
+    if not result_path.is_file():
+        return ""
+    return result_path.read_text(encoding="utf-8")
+
+
 def _wait_for_lock_outcomes(all_result_paths: list[Path]) -> list[str]:
     deadline = time.monotonic() + RESULT_WAIT_SECONDS
     while time.monotonic() < deadline:
-        if all(each_path.is_file() for each_path in all_result_paths):
-            return [
-                each_path.read_text(encoding="utf-8") for each_path in all_result_paths
-            ]
+        all_outcomes = [
+            _read_reported_outcome(each_path) for each_path in all_result_paths
+        ]
+        if all(all_outcomes):
+            return all_outcomes
         time.sleep(POLL_INTERVAL_SECONDS)
     raise AssertionError("lock contenders did not report within five seconds")
 
@@ -146,6 +155,22 @@ def test_process_lock_survives_contention_and_owner_termination(
             _terminate_owned_child(each_child_process)
 
 
+def test_wait_for_lock_outcomes_waits_for_written_content(tmp_path: Path) -> None:
+    result_path = tmp_path / "delayed.result"
+    result_path.touch()
+    delayed_writer = threading.Timer(
+        DELAYED_OUTCOME_WRITE_SECONDS,
+        result_path.write_text,
+        args=("acquired",),
+        kwargs={"encoding": "utf-8"},
+    )
+    delayed_writer.start()
+    try:
+        assert _wait_for_lock_outcomes([result_path]) == ["acquired"]
+    finally:
+        delayed_writer.join()
+
+
 def test_lock_io_error_is_presented_as_supervisor_lock_error(
     tmp_path: Path,
 ) -> None: