claude-dev-env 1.79.0 → 1.81.0

package/_shared/pr-loop/scripts/CLAUDE.md

@@ -11,8 +11,10 @@ Python scripts invoked at runtime by the PR-loop skills. Each script is a standa
 | `post_audit_thread.py` | Posts an audit review (APPROVE / REQUEST_CHANGES) to a draft PR via the GitHub reviews API; reads the body skeleton from `audit-reply-template.md` at runtime |
 | `grant_project_claude_permissions.py` | Writes idempotent allow-rules and `additionalDirectories` entries into `~/.claude/settings.json` so subagents can edit the project's `.claude/` tree without prompting |
 | `revoke_project_claude_permissions.py` | Removes the allow-rules and entries that `grant_project_claude_permissions.py` wrote; safe to run when no prior grant exists |
-| `code_rules_gate.py` | Pre-commit gate that runs `code_rules_enforcer` checks on staged Python files before a fix commit lands |
+| `code_rules_gate.py` | Pre-commit gate that runs `code_rules_enforcer` checks on staged Python files before a fix commit lands, and the terminology sweep over the staged diff |
+| `terminology_sweep.py` | Flags a prose term that near-misses an identifier introduced on added code lines of a unified diff (shared leading word, divergent tail) |
 | `reviews_disabled.py` | Shared helper for the `CLAUDE_REVIEWS_DISABLED` opt-out gate; parses the env-var token to find which reviewer types are suppressed |
+| `copilot_quota.py` | Copilot premium-request quota pre-check: resolves a configured GitHub account, reads its remaining `premium_interactions` quota via `gh api copilot_internal/user`, and exits 0 (run Copilot) or non-zero (skip: out of quota, API down, or no account configured) |
 | `fix_hookspath.py` | Repairs a malformed `core.hooksPath` global git config entry |
 | `_claude_permissions_common.py` | Internal helpers shared by the grant/revoke scripts: atomic settings.json writes, list mutation, path helpers |
 

package/_shared/pr-loop/scripts/code_rules_gate.py

@@ -15,16 +15,17 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     ALL_CODE_FILE_EXTENSIONS,
     ALL_GIT_DIFF_CACHED_NAME_ONLY_NULL_TERMINATED_COMMAND,
     ALL_GIT_DIFF_NAME_ONLY_NULL_TERMINATED_COMMAND_PREFIX,
+    ALL_PYTEST_MODULE_INVOCATION,
     ALL_TEST_FILENAME_GLOB_SUFFIXES,
     ALL_TEST_FILENAME_SUFFIXES,
-    EXPECTED_NON_RENAME_COLUMN_COUNT,
-    EXPECTED_RENAME_COLUMN_COUNT,
     BANNED_NOUN_DEFINITION_LINE_GROUP_INDEX,
     BANNED_NOUN_SPAN_GROUP_INDEX,
     BANNED_NOUN_VIOLATION_PATTERN,
     DUPLICATE_BODY_DEFINITION_LINE_GROUP_INDEX,
     DUPLICATE_BODY_SPAN_GROUP_INDEX,
     DUPLICATE_BODY_VIOLATION_PATTERN,
+    EXPECTED_NON_RENAME_COLUMN_COUNT,
+    EXPECTED_RENAME_COLUMN_COUNT,
     FUNCTION_LENGTH_DEFINITION_LINE_GROUP_INDEX,
     FUNCTION_LENGTH_SPAN_GROUP_INDEX,
     FUNCTION_LENGTH_VIOLATION_PATTERN,
@@ -35,10 +36,15 @@ from pr_loop_shared_constants.code_rules_gate_constants import (  # noqa: E402
     ISOLATION_VIOLATION_PATTERN,
     MAX_VIOLATIONS_PER_CHECK,
     PYTHON_FILE_EXTENSION,
+    STAGED_PYTEST_TIMEOUT_SECONDS,
+    STAGED_TEST_FAILURE_HEADER,
     TEST_CONFTEST_FILENAME,
     TEST_FILENAME_PREFIX,
     TESTS_PATH_SEGMENT,
 )
+from pr_loop_shared_constants.preflight_constants import (  # noqa: E402
+    PYTEST_NO_TESTS_COLLECTED_EXIT_CODE,
+)
 from pr_loop_shared_constants.inline_duplicate_body_span_constants import (  # noqa: E402
     INLINE_DUPLICATE_BODY_ENCLOSING_LINE_GROUP_INDEX,
     INLINE_DUPLICATE_BODY_ENCLOSING_SPAN_GROUP_INDEX,
@@ -46,7 +52,10 @@ from pr_loop_shared_constants.inline_duplicate_body_span_constants import (  # n
     INLINE_DUPLICATE_BODY_HELPER_SPAN_GROUP_INDEX,
     INLINE_DUPLICATE_BODY_VIOLATION_PATTERN,
 )
-
+from pr_loop_shared_constants.terminology_sweep_constants import (  # noqa: E402
+    TERMINOLOGY_SWEEP_GATE_HEADER,
+)
+from terminology_sweep import staged_terminology_findings  # noqa: E402
 
 ValidateContentCallable = Callable[..., list[str]]
 
@@ -768,12 +777,13 @@ def renamed_file_source_map_since(
 
     Runs `git diff --name-status -M -z merge_base..HEAD` and collects both
     paths of every rename entry (status code starting with R, e.g. `R100`).
-    Keys are destination posix paths; values are source posix paths. The
-    -z flag asks git for null-terminated, unquoted output so paths
-    containing tab or newline bytes are not misparsed by column or line
-    splitting; rename records emit three null-terminated tokens in
-    sequence (status, source, destination), other status records emit
-    two (status, path).
+    Keys are destination posix paths; values are source posix paths.
+
+    The -z flag asks git for null-terminated, unquoted output. A path
+    holding a tab or newline byte then survives column and line splitting
+    unmangled. Each rename record emits three null-terminated tokens
+    (status, source, destination). Every other status record emits two
+    (status, path).
 
     Args:
         repository_root: Repository root used as the ``git -C`` target.
@@ -1024,11 +1034,13 @@ def duplicate_body_span_range(violation_text: str) -> range | None:
     The duplicate-body message carries the copied function's definition line and
     its full body span: ``Function 'NAME' duplicates location.py::name — ...
     (duplicate body span at line X, spanning Y lines)``. The function occupies
-    lines ``X`` through ``X + Y - 1`` inclusive, so a duplicate of a sibling helper
-    is blocking only when the diff touches the copied function and advisory when an
-    unrelated edit leaves a pre-existing copy untouched — matching the span-scoped
-    PreToolUse Write/Edit behavior rather than blocking every duplicate-body
-    message unconditionally.
+    lines ``X`` through ``X + Y - 1`` inclusive.
+
+    So a duplicate of a sibling helper blocks only when the diff touches the
+    copied function. An unrelated edit that leaves a pre-existing copy
+    untouched keeps it advisory. This matches the span-scoped PreToolUse
+    Write/Edit behavior rather than blocking every duplicate-body message
+    unconditionally.
 
     Args:
         violation_text: A single violation string emitted by the enforcer.
@@ -1048,16 +1060,18 @@ def duplicate_body_span_range(violation_text: str) -> range | None:
 def inline_duplicate_body_span_lines(violation_text: str) -> frozenset[int] | None:
     """Return the union of both spans of a same-file inline-duplicate issue, or None.
 
-    The same-file inline-duplicate message names two functions that share a body —
-    the helper and the enclosing function carrying the inline copy — and the live
-    Write/Edit hook scopes the violation by the UNION of both spans, blocking when
-    an edit touches either function. So the message carries both spans: ``(inline
-    duplicate body spans: helper at line H spanning P lines, enclosing at line E
-    spanning Q lines)``. The two spans can be disjoint (an unrelated function may
-    sit between the helper and its inline copy), so this returns the union as a
-    line-number set rather than a single contiguous range — a range covering the
-    gap would wrongly block an edit confined to that intervening function, which
-    the PreToolUse path leaves unflagged.
+    The same-file inline-duplicate message names two functions that share a body:
+    the helper and the enclosing function carrying the inline copy. The live
+    Write/Edit hook scopes the violation by the union of both spans. It blocks
+    when an edit touches either function. So the message carries both spans:
+    ``(inline duplicate body spans: helper at line H spanning P lines,
+    enclosing at line E spanning Q lines)``.
+
+    The two spans can be disjoint: an unrelated function may sit between the
+    helper and its inline copy. This returns the union as a line-number set
+    rather than a single contiguous range. A range covering the gap would
+    wrongly block an edit confined to that intervening function, which the
+    PreToolUse path leaves unflagged.
 
     Args:
         violation_text: A single violation string emitted by the enforcer.
@@ -1096,10 +1110,10 @@ def enclosing_span_range(violation_text: str) -> range | None:
 
     Every diff-scoped enforcer check tags its message with an enclosing-unit
     span fragment. This dispatcher tries each span extractor from
-    ``_all_span_range_extractors`` so the gate reconstructs every scoped
-    check's span through one shared mechanism — adding a new scoped check means
-    adding one extractor to that registry rather than threading a new branch
-    through ``split_violations_by_scope``.
+    ``_all_span_range_extractors``, so the gate reconstructs every scoped
+    check's span through one shared mechanism. Adding a new scoped check
+    means adding one extractor to that registry rather than threading a new
+    branch through ``split_violations_by_scope``.
 
     Args:
         violation_text: A single violation string emitted by the enforcer.
@@ -1510,6 +1524,73 @@ def _report_partitioned_violations(
     return 0
 
 
+def _staged_test_file_paths(repository_root: Path) -> list[Path]:
+    """Return the staged Python test files that exist under a repository.
+
+    Args:
+        repository_root: The repository root whose staged index is read.
+
+    Returns:
+        The staged paths whose extension is Python, whose name matches a
+        test-file pattern, and which exist on disk.
+    """
+    all_test_paths: list[Path] = []
+    for each_path in paths_from_git_staged(repository_root):
+        if each_path.suffix != PYTHON_FILE_EXTENSION:
+            continue
+        if is_test_path(str(each_path)) and each_path.is_file():
+            all_test_paths.append(each_path)
+    return all_test_paths
+
+
+def run_staged_test_files(repository_root: Path) -> int:
+    """Run pytest over the staged test files and return the gate exit code.
+
+    Args:
+        repository_root: The repository root the staged test files belong to.
+
+    Returns:
+        0 when no test file is staged, when the staged test files collect
+        no tests (pytest's no-tests-collected exit code), or when every staged
+        test passes. pytest's non-zero exit code otherwise, which blocks the
+        commit.
+    """
+    all_test_paths = _staged_test_file_paths(repository_root)
+    if not all_test_paths:
+        return 0
+    pytest_process = subprocess.run(
+        [
+            sys.executable,
+            *ALL_PYTEST_MODULE_INVOCATION,
+            *[str(each_path) for each_path in all_test_paths],
+        ],
+        cwd=str(repository_root),
+        timeout=STAGED_PYTEST_TIMEOUT_SECONDS,
+        check=False,
+    )
+    if pytest_process.returncode == PYTEST_NO_TESTS_COLLECTED_EXIT_CODE:
+        return 0
+    if pytest_process.returncode != 0:
+        print(STAGED_TEST_FAILURE_HEADER, file=sys.stderr)
+    return pytest_process.returncode
+
+
+def _report_terminology_findings(all_findings: list[str]) -> None:
+    """Print the terminology-sweep findings, when any, to standard error.
+
+    Args:
+        all_findings: The near-miss findings from the staged terminology sweep.
+    """
+    if not all_findings:
+        return
+    print(
+        TERMINOLOGY_SWEEP_GATE_HEADER.format(finding_count=len(all_findings)),
+        file=sys.stderr,
+    )
+    for each_finding in all_findings:
+        print(f"  {each_finding}", file=sys.stderr)
+
+
 def parse_arguments(all_arguments: list[str]) -> argparse.Namespace:
     """Parse the command-line arguments for the code-rules gate.
 
@@ -1590,6 +1671,10 @@ def main(all_arguments: list[str]) -> int:
             validate_content, file_paths, repository_root, all_added_lines_by_path=None
         )
     if arguments.staged:
+        all_terminology_findings = staged_terminology_findings(repository_root)
+        _report_terminology_findings(all_terminology_findings)
+        terminology_exit_code = 1 if all_terminology_findings else 0
+        staged_test_exit_code = run_staged_test_files(repository_root)
         staged_file_paths = paths_from_git_staged(repository_root)
         staged_file_paths = filter_paths_under_prefixes(
             staged_file_paths,
@@ -1597,17 +1682,18 @@ def main(all_arguments: list[str]) -> int:
             arguments.only_under,
         )
         if not staged_file_paths:
-            return 0
+            return terminology_exit_code or staged_test_exit_code
         staged_added_lines = added_lines_by_file_staged(
             repository_root, staged_file_paths
         )
-        return run_gate(
+        gate_exit_code = run_gate(
             validate_content,
             staged_file_paths,
             repository_root,
             all_added_lines_by_path=staged_added_lines,
             read_staged_content_flag=True,
         )
+        return gate_exit_code or terminology_exit_code or staged_test_exit_code
     file_paths = paths_from_git_diff(repository_root, arguments.base)
     file_paths = filter_paths_under_prefixes(
         file_paths,

package/_shared/pr-loop/scripts/copilot_quota.py

@@ -0,0 +1,360 @@
+"""Copilot premium-interaction quota pre-check.
+
+Run this before any Copilot review step spawns. It reads a configured GitHub
+account's remaining premium-interaction quota and decides whether Copilot has
+quota to run. An account already out of quota skips the Copilot step instead of
+wasting a whole review cycle on it.
+
+Account resolution order: the ``--account`` flag, then the
+``COPILOT_QUOTA_ACCOUNT`` environment variable, then that same key parsed from a
+git-ignored ``.env`` file. The account's ``gh`` token is resolved with
+``gh auth token -u <account>`` and the quota is read from
+``gh api copilot_internal/user``. The config file names the account only and
+stores no secret.
+
+The exit code tells the caller what to do. Exit 0 means run Copilot. A non-zero
+exit means skip it: the account is out of quota (scenario A), the quota API or
+account access is down (scenario B), or no account is configured (scenario C).
+Every path prints one line: the run line to stdout, each skip line to stderr.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from pr_loop_shared_constants.copilot_quota_constants import (
+    COPILOT_INTERNAL_USER_API_PATH,
+    COPILOT_QUOTA_ACCOUNT_ENV_VAR_NAME,
+    COPILOT_QUOTA_DEFAULT_ENV_FILE_PATH,
+    EXIT_CODE_NO_ACCOUNT_CONFIGURED,
+    EXIT_CODE_OUT_OF_QUOTA,
+    EXIT_CODE_QUOTA_API_DOWN,
+    EXIT_CODE_QUOTA_AVAILABLE,
+    GH_TOKEN_ENV_VAR_NAME,
+    PREMIUM_ENTITLEMENT_FIELD_NAME,
+    PREMIUM_INTERACTIONS_FIELD_NAME,
+    PREMIUM_OVERAGE_PERMITTED_FIELD_NAME,
+    PREMIUM_PERCENT_REMAINING_FIELD_NAME,
+    PREMIUM_REMAINING_FIELD_NAME,
+    PREMIUM_UNLIMITED_FIELD_NAME,
+    QUOTA_SNAPSHOTS_FIELD_NAME,
+)
+
+
+@dataclass(frozen=True)
+class QuotaDecision:
+    """One quota pre-check outcome: the exit code and the single log line.
+
+    The exit code tells the caller what to do, where 0 runs Copilot and any
+    non-zero skips it. The CLI prints the message on one line, to stdout on a
+    run and to stderr on a skip.
+    """
+
+    exit_code: int
+    message: str
+
+
+def _run_gh(
+    all_command_arguments: list[str],
+    all_environment_overrides: dict[str, str] | None = None,
+) -> tuple[int, str]:
+    """Run a ``gh`` subprocess and return its exit code and stdout.
+
+    Args:
+        all_command_arguments: Arguments after the ``gh`` program name, for
+            example ``["api", "copilot_internal/user"]``.
+        all_environment_overrides: Environment entries to overlay on the current
+            environment for this call, or None to inherit it unchanged.
+
+    Returns:
+        The subprocess exit code paired with its captured stdout.
+    """
+    process_environment = dict(os.environ)
+    if all_environment_overrides:
+        process_environment.update(all_environment_overrides)
+    completed_process = subprocess.run(
+        ["gh", *all_command_arguments],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+        env=process_environment,
+    )
+    return completed_process.returncode, completed_process.stdout
+
+
+def _read_account_from_env_file(env_file_path: Path) -> str | None:
+    """Read the configured account from a git-ignored ``.env`` file.
+
+    Args:
+        env_file_path: Path to the ``.env`` file that may carry a
+            ``COPILOT_QUOTA_ACCOUNT=<login>`` line.
+
+    Returns:
+        The configured account login, or None when the file is absent,
+        unreadable, or carries no non-empty account line.
+    """
+    try:
+        file_text = env_file_path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+    for each_line in file_text.splitlines():
+        stripped_line = each_line.strip()
+        if not stripped_line or stripped_line.startswith("#"):
+            continue
+        key_text, separator, raw_account = stripped_line.partition("=")
+        if not separator or key_text.strip() != COPILOT_QUOTA_ACCOUNT_ENV_VAR_NAME:
+            continue
+        resolved_login = raw_account.strip().strip('"').strip("'")
+        if resolved_login:
+            return resolved_login
+    return None
+
+
+def _resolve_account(cli_account: str | None, env_file_path: Path) -> str | None:
+    """Resolve the account whose Copilot quota to check.
+
+    Args:
+        cli_account: The ``--account`` value, or None when the flag is absent.
+        env_file_path: The ``.env`` file consulted when neither the flag nor
+            the environment variable names an account.
+
+    Returns:
+        The resolved account login from the flag, then the
+        ``COPILOT_QUOTA_ACCOUNT`` environment variable, then the ``.env``
+        file, or None when none of the three names an account.
+    """
+    if cli_account and cli_account.strip():
+        return cli_account.strip()
+    environment_account = os.environ.get(COPILOT_QUOTA_ACCOUNT_ENV_VAR_NAME, "").strip()
+    if environment_account:
+        return environment_account
+    return _read_account_from_env_file(env_file_path)
+
+
+def _resolve_gh_token(account_login: str) -> str | None:
+    """Resolve the account's gh token via ``gh auth token -u <account>``.
+
+    Args:
+        account_login: The GitHub login to resolve a token for.
+
+    Returns:
+        The token string, or None when ``gh`` exits non-zero or prints no
+        token, so an account that is not ``gh auth login``-ed reads as down.
+    """
+    returncode, stdout = _run_gh(["auth", "token", "-u", account_login])
+    if returncode != 0:
+        return None
+    token = stdout.strip()
+    return token or None
+
+
+def _fetch_copilot_user(token: str) -> dict[str, object] | None:
+    """Read the ``copilot_internal/user`` payload for a resolved token.
+
+    Args:
+        token: A gh token authorized for the account under check.
+
+    Returns:
+        The parsed response object, or None when ``gh`` exits non-zero or
+        returns a body that is not a JSON object.
+    """
+    returncode, stdout = _run_gh(
+        ["api", COPILOT_INTERNAL_USER_API_PATH],
+        {GH_TOKEN_ENV_VAR_NAME: token},
+    )
+    if returncode != 0:
+        return None
+    try:
+        parsed_payload = json.loads(stdout)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(parsed_payload, dict):
+        return None
+    return parsed_payload
+
+
+def _extract_premium_snapshot(
+    all_user_fields: dict[str, object],
+) -> dict[str, object] | None:
+    """Pull the ``premium_interactions`` quota snapshot from the user payload.
+
+    Args:
+        all_user_fields: The parsed ``copilot_internal/user`` response object.
+
+    Returns:
+        The ``quota_snapshots.premium_interactions`` object, or None when
+        either level is missing or is not an object.
+    """
+    quota_snapshots = all_user_fields.get(QUOTA_SNAPSHOTS_FIELD_NAME)
+    if not isinstance(quota_snapshots, dict):
+        return None
+    premium_snapshot = quota_snapshots.get(PREMIUM_INTERACTIONS_FIELD_NAME)
+    if not isinstance(premium_snapshot, dict):
+        return None
+    return premium_snapshot
+
+
+def _is_premium_quota_exhausted(all_premium_fields: dict[str, object]) -> bool:
+    """Report whether the premium-interaction quota is exhausted.
+
+    The quota counts as exhausted when it is not unlimited, its remaining count
+    has reached zero, and overage is not permitted. That is the one state in
+    which a Copilot review request cannot be served. Any missing or malformed
+    gating field leaves the quota reported as not exhausted, so the caller runs
+    Copilot rather than skipping on an unreadable snapshot.
+
+    Args:
+        all_premium_fields: The ``premium_interactions`` quota snapshot object.
+
+    Returns:
+        True when unlimited is False, remaining is at or below zero, and overage
+        is not permitted.
+    """
+    is_unlimited = all_premium_fields.get(PREMIUM_UNLIMITED_FIELD_NAME)
+    is_overage_permitted = all_premium_fields.get(PREMIUM_OVERAGE_PERMITTED_FIELD_NAME)
+    remaining = all_premium_fields.get(PREMIUM_REMAINING_FIELD_NAME)
+    if not isinstance(is_unlimited, bool) or not isinstance(is_overage_permitted, bool):
+        return False
+    if isinstance(remaining, bool) or not isinstance(remaining, (int, float)):
+        return False
+    return is_unlimited is False and remaining <= 0 and is_overage_permitted is False
+
+
+def _describe_quota_amount(all_premium_fields: dict[str, object]) -> str:
+    """Render the remaining/entitlement/percent fragment for a snapshot.
+
+    Args:
+        all_premium_fields: The ``premium_interactions`` quota snapshot object.
+
+    Returns:
+        A fragment naming the remaining count over the entitlement with the
+        percent remaining, built from the snapshot's remaining, entitlement,
+        and percent-remaining fields.
+    """
+    remaining = all_premium_fields.get(PREMIUM_REMAINING_FIELD_NAME)
+    entitlement = all_premium_fields.get(PREMIUM_ENTITLEMENT_FIELD_NAME)
+    percent_remaining = all_premium_fields.get(PREMIUM_PERCENT_REMAINING_FIELD_NAME)
+    return f"{remaining}/{entitlement} remaining ({percent_remaining}%)"
+
+
+def evaluate_copilot_quota(
+    cli_account: str | None, env_file_path: Path
+) -> QuotaDecision:
+    """Decide whether Copilot has premium quota to run for a configured account.
+
+    Resolves the account, reads its remaining ``premium_interactions`` quota via
+    ``gh``, and maps the result to one of four outcomes: premium quota available
+    (run Copilot), out of quota, quota API or account access down, and no
+    account configured.
+
+    Args:
+        cli_account: The ``--account`` value, or None when the flag is absent.
+        env_file_path: The ``.env`` file consulted for the account when neither
+            the flag nor the environment variable names one.
+
+    Returns:
+        A QuotaDecision carrying the exit code and the single log line for the
+        resolved outcome.
+    """
+    account_login = _resolve_account(cli_account, env_file_path)
+    if account_login is None:
+        return QuotaDecision(
+            EXIT_CODE_NO_ACCOUNT_CONFIGURED,
+            f"copilot-quota: no account configured — set "
+            f"{COPILOT_QUOTA_ACCOUNT_ENV_VAR_NAME}=<login> in {env_file_path} "
+            f"(or pass --account). Skipping Copilot (scenario C).",
+        )
+    token = _resolve_gh_token(account_login)
+    if token is None:
+        return QuotaDecision(
+            EXIT_CODE_QUOTA_API_DOWN,
+            f"copilot-quota: could not resolve a gh token for '{account_login}' "
+            f"(is it gh auth login-ed?) — skipping Copilot (scenario B).",
+        )
+    all_user_fields = _fetch_copilot_user(token)
+    if all_user_fields is None:
+        return QuotaDecision(
+            EXIT_CODE_QUOTA_API_DOWN,
+            f"copilot-quota: gh api {COPILOT_INTERNAL_USER_API_PATH} failed or "
+            f"returned non-JSON for '{account_login}' — skipping Copilot "
+            f"(scenario B).",
+        )
+    premium_snapshot = _extract_premium_snapshot(all_user_fields)
+    if premium_snapshot is None:
+        return QuotaDecision(
+            EXIT_CODE_QUOTA_API_DOWN,
+            f"copilot-quota: the {COPILOT_INTERNAL_USER_API_PATH} response for "
+            f"'{account_login}' carried no "
+            f"{QUOTA_SNAPSHOTS_FIELD_NAME}.{PREMIUM_INTERACTIONS_FIELD_NAME} — "
+            f"skipping Copilot (scenario B).",
+        )
+    if _is_premium_quota_exhausted(premium_snapshot):
+        return QuotaDecision(
+            EXIT_CODE_OUT_OF_QUOTA,
+            f"copilot-quota: {account_login} is out of premium-interaction "
+            f"quota — {_describe_quota_amount(premium_snapshot)}, overage not "
+            f"permitted — skipping Copilot (scenario A).",
+        )
+    return QuotaDecision(
+        EXIT_CODE_QUOTA_AVAILABLE,
+        f"copilot-quota: {account_login} — premium interactions "
+        f"{_describe_quota_amount(premium_snapshot)} — running Copilot.",
+    )
+
+
+def _parse_arguments(all_argv: list[str]) -> argparse.Namespace:
+    """Parse command-line arguments for the quota pre-check.
+
+    Args:
+        all_argv: Argument list excluding the program name, typically
+            ``sys.argv[1:]``.
+
+    Returns:
+        Namespace exposing an ``account`` attribute holding the ``--account``
+        value, or None when the flag is absent.
+    """
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--account",
+        default=None,
+        help=(
+            "GitHub login whose Copilot premium-interaction quota to check; "
+            "overrides COPILOT_QUOTA_ACCOUNT and the .env file"
+        ),
+    )
+    return parser.parse_args(all_argv)
+
+
+def main(all_arguments: list[str]) -> int:
+    """Run the quota pre-check end-to-end and print its one-line decision.
+
+    Args:
+        all_arguments: Argument list excluding the program name.
+
+    Returns:
+        The pre-check exit code: 0 to run Copilot, or a non-zero skip code for
+        out-of-quota (scenario A), quota API or access down (scenario B), and no
+        account configured (scenario C).
+    """
+    arguments = _parse_arguments(all_arguments)
+    decision = evaluate_copilot_quota(
+        cli_account=arguments.account,
+        env_file_path=COPILOT_QUOTA_DEFAULT_ENV_FILE_PATH,
+    )
+    message_stream = (
+        sys.stdout if decision.exit_code == EXIT_CODE_QUOTA_AVAILABLE else sys.stderr
+    )
+    print(decision.message, file=message_stream)
+    return decision.exit_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/_shared/pr-loop/scripts/pr_loop_shared_constants/CLAUDE.md

@@ -15,6 +15,8 @@ Named constants for every script in `_shared/pr-loop/scripts/`. Each module owns
 | `preflight_constants.py` | `preflight.py` — env-var names, git subcommands, pytest exit codes, test discovery patterns |
 | `preflight_self_heal_constants.py` | `preflight_self_heal.py` — git config keys and local-scope detection strings |
 | `reviews_disabled_constants.py` | `reviews_disabled.py` — `CLAUDE_REVIEWS_DISABLED` token taxonomy |
+| `copilot_quota_constants.py` | `copilot_quota.py` — `COPILOT_QUOTA_ACCOUNT` env-var name, `copilot_internal/user` API path, the `premium_interactions` gating field names, the four skip/run exit codes, and the default `.env` path |
+| `terminology_sweep_constants.py` | `terminology_sweep.py` — identifier and prose-token regexes, diff-parsing prefixes, code-file extensions, and the finding-message template |
 | `__init__.py` | Empty package marker |
 
 ## Convention

package/_shared/pr-loop/scripts/pr_loop_shared_constants/code_rules_gate_constants.py

@@ -80,3 +80,16 @@ ALL_GIT_DIFF_NAME_ONLY_NULL_TERMINATED_COMMAND_PREFIX: tuple[str, ...] = (
     "--name-only",
     "-z",
 )
+
+
+ALL_PYTEST_MODULE_INVOCATION: tuple[str, ...] = (
+    "-m",
+    "pytest",
+    "-q",
+)
+
+STAGED_PYTEST_TIMEOUT_SECONDS: int = 600
+
+STAGED_TEST_FAILURE_HEADER: str = (
+    "code_rules_gate: staged test file(s) failed under pytest; commit blocked."
+)

package/_shared/pr-loop/scripts/pr_loop_shared_constants/copilot_quota_constants.py

@@ -0,0 +1,24 @@
+"""Configuration constants for the Copilot premium-interaction quota pre-check."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+COPILOT_QUOTA_ACCOUNT_ENV_VAR_NAME: str = "COPILOT_QUOTA_ACCOUNT"
+GH_TOKEN_ENV_VAR_NAME: str = "GH_TOKEN"
+COPILOT_INTERNAL_USER_API_PATH: str = "copilot_internal/user"
+
+QUOTA_SNAPSHOTS_FIELD_NAME: str = "quota_snapshots"
+PREMIUM_INTERACTIONS_FIELD_NAME: str = "premium_interactions"
+PREMIUM_UNLIMITED_FIELD_NAME: str = "unlimited"
+PREMIUM_REMAINING_FIELD_NAME: str = "remaining"
+PREMIUM_OVERAGE_PERMITTED_FIELD_NAME: str = "overage_permitted"
+PREMIUM_ENTITLEMENT_FIELD_NAME: str = "entitlement"
+PREMIUM_PERCENT_REMAINING_FIELD_NAME: str = "percent_remaining"
+
+EXIT_CODE_QUOTA_AVAILABLE: int = 0
+EXIT_CODE_OUT_OF_QUOTA: int = 1
+EXIT_CODE_QUOTA_API_DOWN: int = 2
+EXIT_CODE_NO_ACCOUNT_CONFIGURED: int = 3
+
+COPILOT_QUOTA_DEFAULT_ENV_FILE_PATH: Path = Path(__file__).resolve().parents[4] / ".env"