claude-dev-env 4.3.0 → 7.0.0

package/hooks/git-hooks/test_installed_policy_lint.py

@@ -0,0 +1,159 @@
+"""Prove retirement and local enforcement through an actual disposable install."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from test_pre_commit import ALL_RULE_FIXTURES, _git, _stage
+from test_pre_commit import repository_root as repository_root
+
+ALL_RETIRED_HOOK_PATHS = (
+    "blocking/code_rules_enforcer.py",
+    "blocking/tdd_enforcer.py",
+    "blocking/windows_rmtree_blocker.py",
+    "blocking/state_description_blocker.py",
+    "blocking/subprocess_budget_completeness.py",
+    "blocking/hook_prose_detector_consistency.py",
+    "blocking/workflow_substitution_slot_blocker.py",
+)
+PACKAGE_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _legacy_settings_bytes(managed_root: Path, foreign_command: str) -> bytes:
+    original_settings = {
+        "permissions": {"allow": ["Read"]},
+        "hooks": {"PreToolUse": [{
+            "matcher": "Write|Edit|MultiEdit|apply_patch",
+            "hooks": [
+                {"type": "command", "command": foreign_command, "timeout": 17},
+                *({
+                    "type": "command",
+                    "command": f"python {managed_root.as_posix()}/hooks/{each_path}",
+                    "timeout": 10,
+                } for each_path in ALL_RETIRED_HOOK_PATHS),
+            ],
+        }]},
+    }
+    return json.dumps(original_settings, indent=2).encode("utf-8")
+
+
+def _install_environment(home: Path) -> dict[str, str]:
+    environment = {
+        each_name: each_value for each_name, each_value in os.environ.items()
+        if not each_name.startswith("GIT_")
+    }
+    environment.update({
+        "HOME": str(home),
+        "USERPROFILE": str(home),
+        "CLAUDE_CONFIG_DIR": str(home / ".claude"),
+        "CODEX_HOME": str(home / ".codex"),
+        "GIT_CONFIG_GLOBAL": str(home / "gitconfig"),
+        "GIT_CONFIG_NOSYSTEM": "1",
+    })
+    return environment
+
+
+def _install_twice(home: Path, settings_path: Path) -> bytes:
+    all_settings_bytes: list[bytes] = []
+    for each_run in range(2):
+        completed = subprocess.run(
+            ["node", str(PACKAGE_ROOT / "bin/install.mjs"), "--only", "core"],
+            cwd=PACKAGE_ROOT, env=_install_environment(home),
+            capture_output=True, text=True, check=False, timeout=180,
+        )
+        (home / f"install-{each_run}.log").write_text(
+            completed.stdout + completed.stderr, encoding="utf-8"
+        )
+        assert completed.returncode == 0, completed.stdout + completed.stderr
+        all_settings_bytes.append(settings_path.read_bytes())
+    assert all_settings_bytes[0] == all_settings_bytes[1]
+    return all_settings_bytes[-1]
+
+
+def _assert_retired_registrations(managed_root: Path, settings_bytes: bytes, foreign_command: str) -> None:
+    settings = json.loads(settings_bytes)
+    all_commands = [
+        each_hook["command"]
+        for each_groups in settings["hooks"].values()
+        for each_group in each_groups
+        for each_hook in each_group["hooks"]
+    ]
+    assert all_commands.count(foreign_command) == 1
+    assert "Read" in settings["permissions"]["allow"]
+    for each_relative_path in ALL_RETIRED_HOOK_PATHS:
+        assert not any(each_relative_path in each_command for each_command in all_commands)
+        source = PACKAGE_ROOT / "hooks" / each_relative_path
+        installed = managed_root / "hooks" / each_relative_path
+        assert hashlib.sha256(installed.read_bytes()).digest() == hashlib.sha256(source.read_bytes()).digest()
+
+
+@pytest.fixture(scope="module")
+def managed_installation(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    """Install twice into a private home while retaining exact prior settings."""
+    home = tmp_path_factory.mktemp("installed-policy")
+    managed_root = home / ".claude"
+    managed_root.mkdir()
+    foreign_command = "python /unmanaged/fixture_notice.py"
+    original_bytes = _legacy_settings_bytes(managed_root, foreign_command)
+    settings_path = managed_root / "settings.json"
+    settings_path.write_bytes(original_bytes)
+    backup_directory = home / "before-cutover"
+    backup_directory.mkdir()
+    (backup_directory / "settings.json").write_bytes(original_bytes)
+    installed_settings = _install_twice(home, settings_path)
+    _assert_retired_registrations(managed_root, installed_settings, foreign_command)
+    assert (backup_directory / "settings.json").read_bytes() == original_bytes
+    hook_path = _git(home, "config", "--file", str(home / "gitconfig"), "--get", "core.hooksPath")
+    assert Path(hook_path).resolve() == (managed_root / "hooks/git-hooks").resolve()
+    return managed_root
+
+
+@pytest.mark.parametrize(("rule_id", "relative_path", "content"), ALL_RULE_FIXTURES)
+def test_installed_native_commit_catches_each_retired_file_rule(
+    managed_installation: Path,
+    repository_root: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    rule_id: str,
+    relative_path: str,
+    content: str,
+) -> None:
+    _git(repository_root, "config", "core.hooksPath", str(managed_installation / "hooks/git-hooks"))
+    monkeypatch.delenv("CLAUDE_CONFIG_DIR", raising=False)
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(repository_root / "missing-old-gate.py"))
+    before = _git(repository_root, "rev-parse", "HEAD")
+    _stage(repository_root, relative_path, content)
+    completed = subprocess.run(
+        ["git", "commit", "-m", "invalid fixture"],
+        cwd=repository_root, capture_output=True, text=True, check=False, timeout=240,
+    )
+    assert completed.returncode != 0
+    assert rule_id in completed.stdout + completed.stderr
+    assert _git(repository_root, "rev-parse", "HEAD") == before
+
+
+def test_installed_linter_and_native_commit_allow_valid_changes(
+    managed_installation: Path,
+    repository_root: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    _git(repository_root, "config", "core.hooksPath", str(managed_installation / "hooks/git-hooks"))
+    monkeypatch.delenv("CLAUDE_CONFIG_DIR", raising=False)
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(repository_root / "missing-old-gate.py"))
+    _stage(repository_root, "docs/guide.md", "# Guide\n\nThe API uses port 8080.\n")
+    completed = subprocess.run(
+        [sys.executable, str(managed_installation / "scripts/cde_lint.py"), "--staged", "--format", "json"],
+        cwd=repository_root, capture_output=True, text=True, check=False, timeout=240,
+    )
+    assert completed.returncode == 0, completed.stdout + completed.stderr
+    report = json.loads(completed.stdout)
+    assert report["failed_rules"] == []
+    assert "terminology-sweep" in report["executed_rules"]
+    before = _git(repository_root, "rev-parse", "HEAD")
+    _git(repository_root, "commit", "-m", "valid installed fixture")
+    assert _git(repository_root, "rev-parse", "HEAD") != before

package/hooks/git-hooks/test_native_policy_commit.py

@@ -0,0 +1,87 @@
+"""Exercise the native Git commit boundary in disposable repositories."""
+
+from __future__ import annotations
+
+import json
+import shlex
+import subprocess
+import sys
+from pathlib import Path
+
+import pre_commit
+import pytest
+from test_pre_commit import _git, _stage
+from test_pre_commit import repository_root as repository_root
+
+
+@pytest.fixture()
+def installed_native_hook(
+    repository_root: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> Path:
+    """Install a native fixture shim pointing to the actual pre-commit owner."""
+    hook_directory = repository_root / ".git" / "fixture-native-hooks"
+    hook_directory.mkdir()
+    hook_path = hook_directory / "pre-commit"
+    command = " ".join(
+        shlex.quote(each_argument)
+        for each_argument in (sys.executable, str(Path(pre_commit.__file__).resolve()))
+    )
+    hook_path.write_text(f"#!/bin/sh\nexec {command}\n", encoding="utf-8")
+    hook_path.chmod(0o755)
+    _git(repository_root, "config", "core.hooksPath", str(hook_directory))
+    monkeypatch.setenv("CODE_RULES_GATE_PATH", str(repository_root / "missing-legacy-gate.py"))
+    return repository_root
+
+
+def test_valid_commit_passes_the_installed_native_hook(installed_native_hook: Path) -> None:
+    before = _git(installed_native_hook, "rev-parse", "HEAD")
+    _stage(installed_native_hook, "docs/config.md", "The API uses port 8080.\n")
+    _git(installed_native_hook, "commit", "-m", "valid fixture")
+    assert _git(installed_native_hook, "rev-parse", "HEAD") != before
+
+
+def _assert_write_proceeds(repository_root: Path, relative_path: str, content: str) -> None:
+    """Exercise the actual dispatcher before attempting the staged commit."""
+    hooks_root = Path(pre_commit.__file__).resolve().parent.parent
+    payload = {
+        "tool_name": "Write",
+        "cwd": str(repository_root),
+        "tool_input": {
+            "file_path": str(repository_root / relative_path),
+            "content": content,
+        },
+    }
+    edit_result = subprocess.run(
+        [sys.executable, str(hooks_root / "blocking/pre_tool_use_dispatcher.py")],
+        cwd=repository_root,
+        input=json.dumps(payload),
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=90,
+    )
+    assert edit_result.returncode == 0, edit_result.stderr
+    edit_output = json.loads(edit_result.stdout or "{}")
+    assert edit_output.get("hookSpecificOutput", {}).get("permissionDecision") != "deny"
+
+
+def test_retired_write_check_allows_edit_but_local_commit_catches_violation(
+    installed_native_hook: Path,
+) -> None:
+    relative_path = "docs/config.md"
+    content = "Previously set via env var.\n"
+    _assert_write_proceeds(installed_native_hook, relative_path, content)
+    before = _git(installed_native_hook, "rev-parse", "HEAD")
+    _stage(installed_native_hook, relative_path, content)
+    commit_result = subprocess.run(
+        ["git", "commit", "-m", "invalid fixture"],
+        cwd=installed_native_hook,
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=240,
+    )
+    assert commit_result.returncode != 0
+    assert "state-description" in commit_result.stdout + commit_result.stderr
+    assert _git(installed_native_hook, "rev-parse", "HEAD") == before

package/hooks/git-hooks/test_pre_commit.py

@@ -1,10 +1,16 @@
 from __future__ import annotations
 
+import json
+import os
+import subprocess
+import sys
 from pathlib import Path
 
 import pre_commit
 import pytest
 
+from git_hooks_constants.staged_policy_lint import POLICY_LINT_TIMEOUT_SECONDS
+
 
 def make_gate_script_returning(exit_code: int, target_path: Path) -> Path:
     target_path.write_text(
@@ -170,3 +176,243 @@ 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)
+
+
+RMTREE_FIXTURE_KEYWORD = "ignore_errors"
+ALL_RULE_FIXTURES = (
+    (
+        "code-rules",
+        "src/worker.py",
+        "from typing import Any\n\ndef worker() -> Any:\n    return None\n",
+    ),
+    (
+        "test-pairing",
+        "src/feature.py",
+        "def work() -> None:\n    pass\n",
+    ),
+    (
+        "rmtree-safety",
+        "src/cleanup.py",
+        f"import shutil\nshutil.rmtree('fixture', {RMTREE_FIXTURE_KEYWORD}=True)\n",
+    ),
+    (
+        "state-description",
+        "docs/config.md",
+        "# Config\n\nPreviously set via env var.\n",
+    ),
+    (
+        "subprocess-budget",
+        "src/timing.py",
+        "import subprocess\n"
+        "PYTHON_FORMAT_TIMEOUT_SECONDS = 12\n"
+        "GIT_CHECK_TIMEOUT_SECONDS = 5\n"
+        "def worst_case_python_format_seconds() -> int:\n"
+        "    fix_phase_seconds = PYTHON_FORMAT_TIMEOUT_SECONDS\n"
+        "    format_phase_seconds = PYTHON_FORMAT_TIMEOUT_SECONDS\n"
+        "    return fix_phase_seconds + format_phase_seconds\n"
+        "def is_untracked_in_git(file_path: str) -> bool:\n"
+        "    git_check = subprocess.run(['git', 'ls-files', file_path], "
+        "timeout=GIT_CHECK_TIMEOUT_SECONDS)\n"
+        "    return git_check.returncode != 0\n"
+        "def run_format(file_path: str) -> None:\n"
+        "    subprocess.run(['ruff', 'format', file_path], "
+        "timeout=PYTHON_FORMAT_TIMEOUT_SECONDS)\n"
+        "def main(file_path: str) -> None:\n"
+        "    if is_untracked_in_git(file_path):\n"
+        "        return\n"
+        "    run_format(file_path)\n",
+    ),
+    (
+        "hook-prose-consistency",
+        "hooks/hooks_constants/probe_constants.py",
+        'CORRECTIVE_MESSAGE = "appears as a path or output-key segment"\n',
+    ),
+    (
+        "workflow-substitution",
+        "scripts/sample.workflow.js",
+        "For EACH candidate i, build a bible dir cand_i per the contract.\n"
+        "   & ${PY} compose.py --out ${args.work_dir}\\\\cand_i\\\\sample.png "
+        "--glow <candidate glow_hex>\n"
+        'Return: {key: "cand_i", name, sample_png}\n',
+    ),
+)
+
+
+def _git(repository_root: Path, *all_arguments: str) -> str:
+    completed = subprocess.run(
+        ["git", *all_arguments],
+        cwd=repository_root,
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    return completed.stdout.strip()
+
+
+@pytest.fixture()
+def repository_root(
+    tmp_path_factory: pytest.TempPathFactory, monkeypatch: pytest.MonkeyPatch,
+) -> Path:
+    """Create a repository with private Git configuration and no inherited hooks."""
+    tmp_path = tmp_path_factory.mktemp("policy-fixture")
+    home_directory = tmp_path / "home"
+    home_directory.mkdir()
+    monkeypatch.setenv("HOME", str(home_directory))
+    monkeypatch.setenv("USERPROFILE", str(home_directory))
+    monkeypatch.setenv("GIT_CONFIG_GLOBAL", os.devnull)
+    monkeypatch.setenv("GIT_CONFIG_NOSYSTEM", "1")
+    monkeypatch.delenv("GIT_INDEX_FILE", raising=False)
+    monkeypatch.delenv("GIT_DIR", raising=False)
+    monkeypatch.delenv("GIT_WORK_TREE", raising=False)
+    root = tmp_path / "repository"
+    root.mkdir()
+    _git(root, "init")
+    _git(root, "config", "core.hooksPath", str(tmp_path / "disabled-fixture-hooks"))
+    _git(root, "config", "user.name", "Fixture")
+    _git(root, "config", "user.email", "fixture@example.com")
+    _git(root, "commit", "--allow-empty", "-m", "fixture base")
+    monkeypatch.chdir(root)
+    return root
+
+
+def _stage(repository_root: Path, relative_path: str, content: str) -> Path:
+    file_path = repository_root / relative_path
+    file_path.parent.mkdir(parents=True, exist_ok=True)
+    file_path.write_text(content, encoding="utf-8")
+    _git(repository_root, "add", "--", relative_path)
+    return file_path
+
+
+def _lint_report(repository_root: Path) -> tuple[int, dict[str, object]]:
+    completed = subprocess.run(
+        [
+            sys.executable,
+            str(pre_commit.resolve_policy_lint_script_path()),
+            "--staged",
+            "--format",
+            "json",
+        ],
+        cwd=repository_root,
+        check=False,
+        capture_output=True,
+        text=True,
+        timeout=POLICY_LINT_TIMEOUT_SECONDS,
+    )
+    assert completed.stderr == "", completed.stderr
+    return completed.returncode, json.loads(completed.stdout)
+
+
+@pytest.mark.parametrize(("rule_id", "relative_path", "content"), ALL_RULE_FIXTURES)
+def test_real_staged_linter_catches_each_replaced_rule(
+    repository_root: Path,
+    rule_id: str,
+    relative_path: str,
+    content: str,
+) -> None:
+    _stage(repository_root, relative_path, content)
+    exit_code, report = _lint_report(repository_root)
+    assert exit_code == 1, report
+    assert report["failed_rules"] == [], report
+    all_diagnostics = report["diagnostics"]
+    assert isinstance(all_diagnostics, list)
+    assert rule_id in {each["rule_id"] for each in all_diagnostics}, report
+
+
+def _stage_valid_pair(repository_root: Path, relative_path: str) -> None:
+    source_path = Path(relative_path)
+    clean_content = {
+        ".py": (
+            "def is_ready() -> bool:\n"
+            '    """Report readiness.\n\n'
+            "    Returns:\n        True for the fixture.\n"
+            '    """\n'
+            "    return True\n"
+        ),
+        ".js": "export const isEnabled = true;\n",
+        ".md": "# Config\n\nThe API uses port 8080.\n",
+    }[source_path.suffix]
+    _stage(repository_root, relative_path, clean_content)
+    paired_name = (
+        f"test_{source_path.stem}.py"
+        if source_path.suffix == ".py"
+        else f"{source_path.stem}.test{source_path.suffix}"
+    )
+    paired_content = (
+        f"from {source_path.stem} import is_ready\n\n"
+        "def test_is_ready() -> None:\n    assert is_ready()\n"
+        if source_path.suffix == ".py"
+        else ""
+    )
+    _stage(repository_root, (source_path.parent / paired_name).as_posix(), paired_content)
+
+
+@pytest.mark.parametrize(("rule_id", "relative_path", "content"), ALL_RULE_FIXTURES)
+def test_valid_paired_content_passes_the_real_local_commit_linter(
+    repository_root: Path,
+    rule_id: str,
+    relative_path: str,
+    content: str,
+) -> None:
+    _stage_valid_pair(repository_root, relative_path)
+    assert pre_commit.run_staged_policy_lint() == 0
+
+
+def test_unstaged_fix_does_not_hide_staged_violation(repository_root: Path) -> None:
+    target = _stage(repository_root, "docs/config.md", "Previously set via env var.\n")
+    target.write_text("The API uses port 8080.\n", encoding="utf-8")
+    assert pre_commit.run_staged_policy_lint() == 1
+
+
+def test_alternate_git_index_is_checked(
+    repository_root: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    alternate_index = repository_root / ".git" / "alternate-index"
+    monkeypatch.setenv("GIT_INDEX_FILE", str(alternate_index))
+    _git(repository_root, "read-tree", "HEAD")
+    _stage(repository_root, "docs/config.md", "Previously set via env var.\n")
+    assert pre_commit.run_staged_policy_lint() == 1
+    monkeypatch.delenv("GIT_INDEX_FILE")
+    assert pre_commit.run_staged_policy_lint() == 0
+
+
+def test_missing_linter_does_not_allow_commit(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setattr(
+        pre_commit, "resolve_policy_lint_script_path", lambda: tmp_path / "missing.py"
+    )
+    assert pre_commit.main() == 2
+
+
+@pytest.mark.parametrize("exit_code", (1, 2, 3))
+def test_linter_failure_reaches_git_before_legacy_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    exit_code: int,
+) -> None:
+    monkeypatch.setattr(pre_commit, "run_staged_policy_lint", lambda: exit_code)
+    all_gate_calls: list[object] = []
+    monkeypatch.setattr(
+        pre_commit,
+        "resolve_gate_script_path",
+        lambda: all_gate_calls.append("unexpected gate"),
+    )
+    assert pre_commit.main() == exit_code
+    assert all_gate_calls == []
+
+
+def test_timeout_is_an_infrastructure_failure(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    script_path = tmp_path / "lint.py"
+    script_path.write_text("", encoding="utf-8")
+    monkeypatch.setattr(pre_commit, "resolve_policy_lint_script_path", lambda: script_path)
+
+    def timed_out(*all_arguments: object, **all_options: object) -> object:
+        raise subprocess.TimeoutExpired("lint fixture", POLICY_LINT_TIMEOUT_SECONDS)
+
+    monkeypatch.setattr(pre_commit.subprocess, "run", timed_out)
+    assert pre_commit.run_staged_policy_lint() == 2

package/hooks/hooks.json

@@ -245,7 +245,7 @@
         ]
       },
       {
-        "matcher": "Bash",
+        "matcher": "Bash|PowerShell",
         "hooks": [
           {
             "type": "command",

package/hooks/hooks_constants/bash_post_call_dispatcher_constants.py

@@ -10,12 +10,25 @@ no second copy of either.
 from __future__ import annotations
 
 from hooks_constants.bash_pre_tool_use_dispatcher_constants import (
+    ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
     ALL_BASH_ONLY_TOOL_NAMES,
     BashHostedHookEntry,
 )
 
-__all__ = ["ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES"]
+__all__ = [
+    "ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES",
+    "POST_TOOL_USE_HOOK_EVENT_NAME",
+    "HOOK_SPECIFIC_OUTPUT_KEY",
+    "ADDITIONAL_CONTEXT_KEY",
+    "ADDITIONAL_CONTEXT_JOIN_SEPARATOR",
+]
 
 ALL_BASH_POST_TOOL_USE_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
     BashHostedHookEntry("observability/test_failure_recorder.py", ALL_BASH_ONLY_TOOL_NAMES),
+    BashHostedHookEntry("advisory/pr_done_reminder.py", ALL_BASH_AND_POWERSHELL_TOOL_NAMES),
 )
+
+POST_TOOL_USE_HOOK_EVENT_NAME: str = "PostToolUse"
+HOOK_SPECIFIC_OUTPUT_KEY: str = "hookSpecificOutput"
+ADDITIONAL_CONTEXT_KEY: str = "additionalContext"
+ADDITIONAL_CONTEXT_JOIN_SEPARATOR: str = "\n\n"

package/hooks/hooks_constants/pr_done_reminder_constants.py

@@ -0,0 +1,98 @@
+"""Constants for the PR done-checklist context reminder.
+
+The reminder is a PostToolUse observer on Bash. It never blocks. After a
+successful ``git push`` or ``gh pr create`` it probes the branch's pull request
+through ``gh`` and adds one loud checklist to the agent's context.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "GIT_PROGRAM_NAME",
+    "GIT_PUSH_SUBCOMMAND",
+    "GH_PROGRAM_NAME",
+    "GH_PR_SUBCOMMAND",
+    "GH_PR_CREATE_ACTION",
+    "ALL_GIT_OPTIONS_WITH_VALUE",
+    "ALL_POWERSHELL_PROGRAM_NAMES",
+    "ALL_POWERSHELL_COMMAND_FLAGS",
+    "ALL_GH_PR_VIEW_ARGUMENTS",
+    "GH_PR_VIEW_TIMEOUT_SECONDS",
+    "NO_PULL_REQUEST_MARKER",
+    "EXIT_CODE_ERROR_PREFIX",
+    "DONE_LABEL_NAME",
+    "MERGEABLE_CLEAN_VALUE",
+    "MERGEABLE_CONFLICTING_VALUE",
+    "MERGEABLE_UNKNOWN_VALUE",
+    "ALL_FAILING_CHECK_CONCLUSIONS",
+    "ALL_PASSING_CHECK_CONCLUSIONS",
+    "CHECK_COMPLETED_STATUS",
+    "STATUS_CONTEXT_STATE_KEY",
+    "REMINDER_HEADER",
+    "REMINDER_FOOTER",
+    "REMINDER_LINE_SEPARATOR",
+    "ALL_REMINDER_HINTS_BY_MERGEABLE",
+    "VERDICT_DONE",
+    "VERDICT_NOT_DONE",
+    "NO_PULL_REQUEST_REMINDER",
+    "RECHECK_COMMAND_TEMPLATE",
+    "ADD_LABEL_COMMAND_TEMPLATE",
+]
+
+GIT_PROGRAM_NAME: str = "git"
+GIT_PUSH_SUBCOMMAND: str = "push"
+GH_PROGRAM_NAME: str = "gh"
+GH_PR_SUBCOMMAND: str = "pr"
+GH_PR_CREATE_ACTION: str = "create"
+ALL_GIT_OPTIONS_WITH_VALUE: frozenset[str] = frozenset({"-C", "-c"})
+ALL_POWERSHELL_PROGRAM_NAMES: frozenset[str] = frozenset(
+    {"pwsh", "pwsh.exe", "powershell", "powershell.exe"}
+)
+ALL_POWERSHELL_COMMAND_FLAGS: frozenset[str] = frozenset({"-command", "-c"})
+
+ALL_GH_PR_VIEW_ARGUMENTS: tuple[str, ...] = (
+    "gh",
+    "pr",
+    "view",
+    "--json",
+    "number,url,isDraft,mergeable,mergeStateStatus,statusCheckRollup,labels",
+)
+GH_PR_VIEW_TIMEOUT_SECONDS: int = 20
+NO_PULL_REQUEST_MARKER: str = "no pull requests found"
+EXIT_CODE_ERROR_PREFIX: str = "Error: Exit code "
+
+DONE_LABEL_NAME: str = "done"
+
+MERGEABLE_CLEAN_VALUE: str = "MERGEABLE"
+MERGEABLE_CONFLICTING_VALUE: str = "CONFLICTING"
+MERGEABLE_UNKNOWN_VALUE: str = "UNKNOWN"
+
+ALL_FAILING_CHECK_CONCLUSIONS: frozenset[str] = frozenset(
+    {"FAILURE", "ERROR", "CANCELLED", "TIMED_OUT", "ACTION_REQUIRED", "STARTUP_FAILURE"}
+)
+ALL_PASSING_CHECK_CONCLUSIONS: frozenset[str] = frozenset({"SUCCESS", "NEUTRAL", "SKIPPED"})
+CHECK_COMPLETED_STATUS: str = "COMPLETED"
+STATUS_CONTEXT_STATE_KEY: str = "state"
+
+REMINDER_HEADER: str = "=== PR DONE CHECKLIST (context reminder, never a block) ==="
+REMINDER_FOOTER: str = "A PR is done only when every line above is clean."
+REMINDER_LINE_SEPARATOR: str = "\n"
+ALL_REMINDER_HINTS_BY_MERGEABLE: dict[str, str] = {
+    MERGEABLE_CLEAN_VALUE: "no conflicts with the base branch",
+    MERGEABLE_CONFLICTING_VALUE: (
+        "CONFLICTS with the base branch. Merge origin/main into this branch, "
+        "resolve every conflict, run the tests, push again."
+    ),
+    MERGEABLE_UNKNOWN_VALUE: "GitHub is still computing. Re-run the re-check command in a minute.",
+}
+VERDICT_DONE: str = "DONE. Add the label now:"
+VERDICT_NOT_DONE: str = "NOT DONE. Do not add the done label yet."
+NO_PULL_REQUEST_REMINDER: str = (
+    "=== PR DONE CHECKLIST (context reminder, never a block) ===\n"
+    "No open pull request found for this branch. Open a draft PR with gh pr create --draft.\n"
+    "A branch is done only when its PR has clean CI, no merge conflicts, and the done label."
+)
+RECHECK_COMMAND_TEMPLATE: str = (
+    "gh pr view {number} --json mergeable,mergeStateStatus,statusCheckRollup,labels"
+)
+ADD_LABEL_COMMAND_TEMPLATE: str = "gh pr edit {number} --add-label {label}"