claude-dev-env 4.3.0 → 7.1.0

package/hooks/git-hooks/verification_notice_state.py

@@ -0,0 +1,237 @@
+"""Evaluate local verification state for the native Git notice."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from pathlib import Path
+from typing import Protocol
+
+from git_hooks_constants.verification_notice_constants import (
+    ALL_GIT_BASE_QUERY_PREFIX,
+    GIT_COMMAND_SUCCESS_EXIT_CODE,
+    HEX_DIGITS,
+    NOTICE_FAILED_LINE,
+    NOTICE_NO_PASS_LINE,
+    NOTICE_PASSED_LINE,
+    NOTICE_SETUP_PENDING_LINE,
+    NOTICE_STALE_LINE,
+    REPORT_AGGREGATE_FIELD,
+    REPORT_BASE_FIELD,
+    REPORT_EXIT_CODE_FIELD,
+    REPORT_FAILED_FIELD,
+    REPORT_HEAD_FIELD,
+    REPORT_INCOMPLETE_FIELD,
+    REPORT_INPUTS_UNCHANGED_FIELD,
+    REPORT_MANIFEST_DIGEST_FIELD,
+    REPORT_PASSED_FIELD,
+    REPORT_PUBLISHABLE_FIELD,
+    REPORT_STATUS_FIELD,
+    REPORT_TOTAL_FIELD,
+    REPORT_WORKTREE_CLEAN_FIELD,
+    RESOLVED_SHA_LENGTH,
+    STATUS_FAILED,
+    STATUS_PASSED,
+    STATUS_PENDING,
+    STATUS_STALE,
+    STATUS_UNVERIFIED,
+)
+from local_verification.manifest import (
+    ManifestRunFatal,
+    compute_manifest_digest,
+    load_manifest,
+)
+
+
+class _VerificationNoticeContext(Protocol):
+    @property
+    def current_head(self) -> str | None: ...
+
+    @property
+    def repository_root(self) -> Path: ...
+
+    @property
+    def manifest_path(self) -> Path | None: ...
+
+    @property
+    def manifest_is_available(self) -> bool: ...
+
+    @property
+    def report_is_present(self) -> bool: ...
+
+    @property
+    def all_report_fields(self) -> Mapping[str, object] | None: ...
+
+
+def _evaluate_context(
+    context: _VerificationNoticeContext,
+    run_git_query: Callable[[Path, tuple[str, ...], bool], str | None],
+) -> tuple[str, str | None]:
+    context_state = _context_setup_state(context)
+    if context_state is not None:
+        return context_state, None
+    if context.current_head is None or context.all_report_fields is None:
+        return STATUS_UNVERIFIED, None
+    reported_head = _read_text_field(context.all_report_fields, REPORT_HEAD_FIELD)
+    if reported_head is None:
+        return STATUS_UNVERIFIED, None
+    if reported_head != context.current_head:
+        return STATUS_STALE, None
+    if _read_report_status(context.all_report_fields) == STATUS_FAILED:
+        return STATUS_FAILED, None
+    if _is_complete_pass(context, run_git_query):
+        return STATUS_PASSED, context.current_head
+    return STATUS_UNVERIFIED, None
+
+
+def _context_setup_state(context: _VerificationNoticeContext) -> str | None:
+    if context.all_report_fields is None:
+        return STATUS_UNVERIFIED if context.report_is_present else STATUS_PENDING
+    if context.all_report_fields is not None and context.manifest_path is None:
+        return STATUS_UNVERIFIED
+    if not context.manifest_is_available:
+        return STATUS_PENDING
+    return None
+
+
+def _read_text_field(
+    all_fields: Mapping[str, object],
+    field_name: str,
+) -> str | None:
+    field_text = all_fields.get(field_name)
+    if not isinstance(field_text, str):
+        return None
+    return field_text.strip() or None
+
+
+def _read_report_status(all_report_fields: Mapping[str, object]) -> str | None:
+    status_text = _read_text_field(all_report_fields, REPORT_STATUS_FIELD)
+    if status_text:
+        return status_text
+    all_aggregate_fields = all_report_fields.get(REPORT_AGGREGATE_FIELD)
+    if isinstance(all_aggregate_fields, Mapping):
+        return _read_text_field(all_aggregate_fields, REPORT_STATUS_FIELD)
+    return None
+
+
+def _build_state_message(state: str, is_manifest_available: bool) -> str:
+    if not is_manifest_available:
+        return NOTICE_SETUP_PENDING_LINE
+    message_by_state = {
+        STATUS_STALE: NOTICE_STALE_LINE,
+        STATUS_FAILED: NOTICE_FAILED_LINE,
+        STATUS_PASSED: NOTICE_PASSED_LINE,
+    }
+    return message_by_state.get(state, NOTICE_NO_PASS_LINE)
+
+
+def _is_complete_pass(
+    context: _VerificationNoticeContext,
+    run_git_query: Callable[[Path, tuple[str, ...], bool], str | None],
+) -> bool:
+    all_report_fields = context.all_report_fields
+    if all_report_fields is None or context.manifest_path is None:
+        return False
+    base_revision = _read_text_field(all_report_fields, REPORT_BASE_FIELD)
+    if not _report_has_complete_pass(all_report_fields, base_revision):
+        return False
+    if base_revision is None or not _base_matches_current(
+        context.repository_root,
+        base_revision,
+        run_git_query,
+    ):
+        return False
+    if not _worktree_is_clean(context.repository_root, run_git_query):
+        return False
+    if not _manifest_digest_matches(all_report_fields, context.manifest_path):
+        return False
+    all_aggregate_fields = all_report_fields.get(REPORT_AGGREGATE_FIELD)
+    return isinstance(all_aggregate_fields, Mapping) and _aggregate_is_complete_pass(
+        all_aggregate_fields
+    )
+
+
+def _report_has_complete_pass(
+    all_report_fields: Mapping[str, object],
+    base_revision: str | None,
+) -> bool:
+    return (
+        _read_report_status(all_report_fields) == STATUS_PASSED
+        and _report_is_publishable(all_report_fields)
+        and base_revision is not None
+        and _is_resolved_sha(base_revision)
+    )
+
+
+def _report_is_publishable(all_report_fields: Mapping[str, object]) -> bool:
+    return all(
+        all_report_fields.get(each_field) is True
+        for each_field in (
+            REPORT_PUBLISHABLE_FIELD,
+            REPORT_WORKTREE_CLEAN_FIELD,
+            REPORT_INPUTS_UNCHANGED_FIELD,
+        )
+    )
+
+
+def _base_matches_current(
+    repository_root: Path,
+    base_revision: str,
+    run_git_query: Callable[[Path, tuple[str, ...], bool], str | None],
+) -> bool:
+    current_base_revision = run_git_query(
+        repository_root,
+        (*ALL_GIT_BASE_QUERY_PREFIX, "origin/main^{commit}"),
+        False,
+    )
+    return current_base_revision == base_revision
+
+
+def _worktree_is_clean(
+    repository_root: Path,
+    run_git_query: Callable[[Path, tuple[str, ...], bool], str | None],
+) -> bool:
+    status_text = run_git_query(
+        repository_root,
+        ("status", "--porcelain=v1", "--untracked-files=all"),
+        True,
+    )
+    return status_text == ""
+
+
+def _is_resolved_sha(revision_text: str) -> bool:
+    return len(revision_text) == RESOLVED_SHA_LENGTH and all(
+        each_character.casefold() in HEX_DIGITS for each_character in revision_text
+    )
+
+
+def _manifest_digest_matches(
+    all_report_fields: Mapping[str, object],
+    manifest_path: Path | None,
+) -> bool:
+    manifest_digest = _read_text_field(all_report_fields, REPORT_MANIFEST_DIGEST_FIELD)
+    if not manifest_digest or manifest_path is None:
+        return False
+    try:
+        loaded_manifest = load_manifest(manifest_path)
+        actual_digest = compute_manifest_digest(loaded_manifest)
+    except (ManifestRunFatal, OSError, UnicodeError, ValueError):
+        return False
+    return actual_digest == manifest_digest.casefold()
+
+
+def _aggregate_is_complete_pass(
+    all_aggregate_fields: Mapping[str, object],
+) -> bool:
+    total_checks = all_aggregate_fields.get(REPORT_TOTAL_FIELD)
+    passed_checks = all_aggregate_fields.get(REPORT_PASSED_FIELD)
+    failed_checks = all_aggregate_fields.get(REPORT_FAILED_FIELD)
+    incomplete_checks = all_aggregate_fields.get(REPORT_INCOMPLETE_FIELD)
+    exit_code = all_aggregate_fields.get(REPORT_EXIT_CODE_FIELD)
+    return (
+        isinstance(total_checks, int)
+        and total_checks > 0
+        and passed_checks == total_checks
+        and failed_checks == 0
+        and incomplete_checks == 0
+        and exit_code == GIT_COMMAND_SUCCESS_EXIT_CODE
+    )

package/hooks/git-hooks/verification_start.py

@@ -0,0 +1,100 @@
+"""Start automatic local verification for a supported native Git event."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from typing import Mapping
+
+from git_hooks_constants.verification_notice_constants import (
+    ALL_NOTICE_EVENTS,
+    ALL_RUNNER_FIELDS,
+    AUTOMATIC_ADVISORY_CLI_FILE_NAME,
+    AUTOMATIC_ADVISORY_DIRECTORY_NAME,
+    CREATE_NO_WINDOW_ATTRIBUTE,
+    EXECUTOR_DIRECTORY_NAME,
+    GIT_DIRECTORY_NAME,
+    JSON_ENCODING,
+    LOCAL_VERIFICATION_DIRECTORY_NAME,
+    RUNNER_FILE_NAME,
+    RUNNER_PYTHON_FIELD,
+    RUNNER_SETTINGS_FIELD,
+    TARGET_REPOSITORY_REMOTE,
+    WINDOWS_PLATFORM,
+)
+from verification_notice_context import VerificationNoticeContext
+
+
+def start_automatic_advisory(context: VerificationNoticeContext) -> None:
+    """Start the detached advisory poller when native metadata is valid."""
+    if context.repository_remote != TARGET_REPOSITORY_REMOTE:
+        return
+    if context.event not in ALL_NOTICE_EVENTS:
+        return
+    runner_configuration = load_runner_configuration(context)
+    if runner_configuration is None:
+        return
+    python_path, settings_path = runner_configuration
+    advisory_cli_path = (
+        Path(__file__).resolve().parents[2]
+        / EXECUTOR_DIRECTORY_NAME
+        / AUTOMATIC_ADVISORY_DIRECTORY_NAME
+        / AUTOMATIC_ADVISORY_CLI_FILE_NAME
+    )
+    try:
+        _launch_advisory(
+            context,
+            python_path,
+            settings_path,
+            advisory_cli_path,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return
+
+
+def _launch_advisory(
+    context: VerificationNoticeContext,
+    python_path: str,
+    settings_path: str,
+    advisory_cli_path: Path,
+) -> None:
+    subprocess.Popen(
+        [python_path, str(advisory_cli_path), "--settings", settings_path, "--start"],
+        cwd=context.repository_root,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        creationflags=_windows_creation_flags(),
+    )
+
+
+def load_runner_configuration(
+    context: VerificationNoticeContext,
+) -> tuple[str, str] | None:
+    git_directory = context.git_directory or context.repository_root / GIT_DIRECTORY_NAME
+    runner_path = git_directory / LOCAL_VERIFICATION_DIRECTORY_NAME / RUNNER_FILE_NAME
+    try:
+        runner_document = json.loads(runner_path.read_text(encoding=JSON_ENCODING))
+    except (OSError, UnicodeError, ValueError):
+        return None
+    if not isinstance(runner_document, Mapping):
+        return None
+    if set(runner_document) != ALL_RUNNER_FIELDS:
+        return None
+    python_path = runner_document.get(RUNNER_PYTHON_FIELD)
+    settings_path = runner_document.get(RUNNER_SETTINGS_FIELD)
+    if not isinstance(python_path, str) or not python_path.strip():
+        return None
+    if not isinstance(settings_path, str) or not settings_path.strip():
+        return None
+    if not Path(python_path).is_absolute() or not Path(settings_path).is_absolute():
+        return None
+    return python_path, settings_path
+
+
+def _windows_creation_flags() -> int:
+    if sys.platform != WINDOWS_PLATFORM:
+        return 0
+    return getattr(subprocess, CREATE_NO_WINDOW_ATTRIBUTE, 0)

package/hooks/hooks.json

@@ -2,16 +2,6 @@
   "description": "Code standards enforcement, safety guards, and development workflow hooks",
   "hooks": {
     "PreToolUse": [
-      {
-        "matcher": "Write|Edit|MultiEdit|apply_patch",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 -c \"import sys; sys.path.insert(0, r'${CLAUDE_PLUGIN_ROOT}/hooks'); from validators.run_all_validators import main; sys.exit(main())\" --pre-tool-use",
-            "timeout": 30
-          }
-        ]
-      },
       {
         "matcher": "Write|Edit|MultiEdit|apply_patch",
         "hooks": [
@@ -22,91 +12,6 @@
           }
         ]
       },
-      {
-        "matcher": "Bash|PowerShell",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/bash_pre_tool_use_dispatcher.py",
-            "timeout": 400
-          }
-        ]
-      },
-      {
-        "matcher": "mcp__plugin_github_github__add_issue_comment",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/bot_mention_comment_blocker.py",
-            "timeout": 10
-          }
-        ]
-      },
-      {
-        "matcher": "mcp__plugin_github_github__.*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pii_prevention_blocker.py",
-            "timeout": 20
-          }
-        ]
-      },
-      {
-        "matcher": "Agent|Task",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/fable_spawn_gate.py",
-            "timeout": 10
-          }
-        ]
-      },
-      {
-        "matcher": "Agent|Task|multi_agent_v1__spawn_agent",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/luna_fast_mode_gate.py",
-            "timeout": 10
-          }
-        ]
-      },
-      {
-        "matcher": "ScheduleWakeup|CronCreate",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/orchestrator_refresh_reschedule_gate.py",
-            "timeout": 15
-          }
-        ]
-      },
-      {
-        "matcher": "AskUserQuestion",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/plain_language_blocker.py",
-            "timeout": 10
-          },
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/ask_user_question_shape_blocker.py",
-            "timeout": 10
-          }
-        ]
-      },
-      {
-        "matcher": "SendUserFile",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/send_user_file_open_locally_blocker.py",
-            "timeout": 10
-          }
-        ]
-      },
       {
         "matcher": "EnterWorktree",
         "hooks": [
@@ -172,18 +77,6 @@
         ]
       }
     ],
-    "Stop": [
-      {
-        "matcher": "",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/stop_dispatcher.py",
-            "timeout": 90
-          }
-        ]
-      }
-    ],
     "SessionEnd": [
       {
         "matcher": "",
@@ -201,18 +94,6 @@
         ]
       }
     ],
-    "ConfigChange": [
-      {
-        "matcher": "user_settings",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/config_change_guard.py",
-            "timeout": 10
-          }
-        ]
-      }
-    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",
@@ -245,7 +126,7 @@
         ]
       },
       {
-        "matcher": "Bash",
+        "matcher": "Bash|PowerShell",
         "hooks": [
           {
             "type": "command",

package/hooks/hooks_constants/banned_identifiers_constants.py

@@ -2,6 +2,10 @@
 
 import re
 
+from hooks_constants.blast_radius_constants import ALL_BLAST_RADIUS_SUFFIXES
+
+ALL_BLAST_RADIUS_EXCEPTION_SUFFIXES: tuple[str, ...] = ALL_BLAST_RADIUS_SUFFIXES
+
 ALL_BANNED_IDENTIFIERS: frozenset[str] = frozenset(
     {
         "result",

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/bash_pre_tool_use_dispatcher_constants.py

@@ -54,18 +54,4 @@ class BashHostedHookEntry:
     applicable_tool_names: frozenset[str]
 
 
-ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = (
-    BashHostedHookEntry("blocking/destructive_command_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(
-        "blocking/cursor_cli_python_misfire_blocker.py",
-        ALL_BASH_AND_POWERSHELL_TOOL_NAMES,
-    ),
-    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/pii_prevention_blocker.py", ALL_BASH_AND_POWERSHELL_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/windows_rmtree_blocker.py", ALL_BASH_ONLY_TOOL_NAMES),
-)
+ALL_BASH_HOSTED_HOOK_ENTRIES: tuple[BashHostedHookEntry, ...] = ()

package/hooks/hooks_constants/post_tool_use_dispatcher_constants.py

@@ -54,10 +54,6 @@ class PostHostedHookEntry:
 
 
 ALL_POST_HOSTED_HOOK_ENTRIES: tuple[PostHostedHookEntry, ...] = (
-    PostHostedHookEntry(
-        script_relative_path="validation/mypy_validator.py",
-        is_blocking=True,
-    ),
     PostHostedHookEntry(
         script_relative_path="workflow/auto_formatter.py",
         is_blocking=False,

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}"