claude-dev-env 2.2.1 → 2.4.0

package/scripts/conftest.py

@@ -0,0 +1,8 @@
+"""Put the scripts directory on sys.path so tests import each script by name."""
+
+import sys
+from pathlib import Path
+
+_scripts_directory = str(Path(__file__).resolve().parent)
+if _scripts_directory not in sys.path:
+    sys.path.insert(0, _scripts_directory)

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -8,11 +8,12 @@ Named constants for scripts in `scripts/`. Follows the project convention that t
 |---|---|
 | `timing.py` | `sweep_empty_dirs.py` - `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode); `spawn_grok_batch.py` - `WORKER_STAGGER_SECONDS` (seconds between staggered headless grok worker starts); `invoke_code_review.py` - `DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS` (timeout for one headless `/code-review` chain run) |
 | `gh_artifact_upload_constants.py` | `gh_artifact_upload.py` - the `artifacts` release tag, title, and notes body, the GitHub CLI binary name, the asset-name timestamp format and template, the asset download URL template, the notes-file suffix, and the text encoding |
-| `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, the default timeout, CLI flag and separator tokens, config JSON keys, invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes |
+| `claude_chain_constants.py` | `claude_chain_runner.py` - the chain config filename and home subdirectory, the usage-limit signature text, the per-binary status labels, the default timeout, CLI flag and separator tokens, config JSON keys (including optional `credentials_path`), invalid-shape reason text, config-error and exhausted-chain message templates, and CLI exit codes; `invoke_code_review.py` and `resolve_worker_spawn.py` - the text-codec keyword names and the `collect_forwarded_text_codec` helper that forwards them to the subprocess runner for text-mode capture |
+| `claude_chain_usage_constants.py` | `claude_chain_usage.py` - full weekly percent scale, usage-pause skill path segments, CLI config-path flag, JSON report keys, and probe error message templates |
 | `grok_worker_constants.py` | `grok_worker_preflight.py`, `grok_headless_runner.py`, and `spawn_grok_batch.py` - the `grok` binary name and CLI flags, model and subcommand tokens, leader-socket and scratch-file name parts, auth and usage-limit signature lists, outcome classifications, fallthrough reasons, tool-profile names and prompt headers, timeouts and turn caps (including launch-failure return code and post-kill grace), ping-cache keys and TTL, batch-spec and summary JSON keys, the prompt-part and report-stream join separators, and the CLI launch-error stderr prefix |
-| `code_review_constants.py` | `invoke_code_review.py` - the `/code-review high --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers |
+| `code_review_constants.py` | `invoke_code_review.py` - the `/code-review xhigh --fix` prompt, opus model alias, permission-mode flag and value, result mode and JSON keys, session-model CLI flag, git dirty-check tokens, and in-session return markers |
 | `__init__.py` | Empty package marker |
 
 ## Convention
 
-Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies.
+Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies.

package/scripts/dev_env_scripts_constants/claude_chain_constants.py

@@ -1,4 +1,5 @@
-"""Named constants for the claude fallback-chain runner.
+"""Named constants for the claude fallback-chain runner, and the helper that
+picks which text-codec kwargs a chain subprocess wrapper forwards.
 
 Per the project's configuration conventions, every scalar and structural
 constant the runner needs lives here rather than inline in the module.
@@ -6,18 +7,63 @@ constant the runner needs lives here rather than inline in the module.
 
 from __future__ import annotations
 
+from collections.abc import Mapping
+
 UTF8_ENCODING: str = "utf-8"
 """Encoding used to read the chain configuration file."""
 
 CODEC_ERROR_STRATEGY: str = "replace"
 """Codec error handler that maps any unencodable or undecodable value to a marker."""
 
+SUBPROCESS_ENCODING_KEYWORD: str = "encoding"
+"""Keyword name for text encoding when forwarding chain subprocess runner kwargs."""
+
+SUBPROCESS_ERRORS_KEYWORD: str = "errors"
+"""Keyword name for text decode error policy when forwarding chain subprocess runner kwargs."""
+
+ALL_SUBPROCESS_TEXT_CODEC_KEYWORDS: tuple[str, ...] = (
+    SUBPROCESS_ENCODING_KEYWORD,
+    SUBPROCESS_ERRORS_KEYWORD,
+)
+"""Keyword names to forward from the chain runner for text-mode subprocess capture."""
+
+
+def collect_forwarded_text_codec(
+    all_keywords: Mapping[str, object],
+) -> dict[str, object]:
+    """Return only the text-codec kwargs present in ``all_keywords``.
+
+    ::
+
+        collect_forwarded_text_codec({"encoding": "utf-8", "timeout": 30})
+        # -> {"encoding": "utf-8"}
+
+        collect_forwarded_text_codec({"timeout": 30})
+        # -> {}
+
+    Args:
+        all_keywords: Keyword arguments received by a chain subprocess wrapper.
+
+    Returns:
+        Mapping of codec keyword names to their values, limited to keys listed
+        in ``ALL_SUBPROCESS_TEXT_CODEC_KEYWORDS`` that are present in the input.
+    """
+    return {
+        each_key: all_keywords[each_key]
+        for each_key in ALL_SUBPROCESS_TEXT_CODEC_KEYWORDS
+        if each_key in all_keywords
+    }
+
+
 CLAUDE_HOME_SUBDIRECTORY: str = ".claude"
 """Per-user directory under the home directory that holds the chain config."""
 
 CONFIG_FILENAME: str = "claude-chain.json"
 """Real chain-configuration filename read from the user's home directory."""
 
+CHAIN_USAGE_MODULE_NAME: str = "claude_chain_usage"
+"""Import name of the weekly-usage report module loaded lazily by the runner."""
+
 EXAMPLE_CONFIG_FILENAME: str = "claude-chain.example.json"
 """Committed template filename referenced in the config-error guidance."""
 
@@ -30,6 +76,9 @@ CONFIG_COMMAND_KEY: str = "command"
 CONFIG_EXTRA_ARGS_KEY: str = "extra_args"
 """Chain-entry key holding per-account arguments appended to each invocation."""
 
+CONFIG_CREDENTIALS_PATH_KEY: str = "credentials_path"
+"""Optional chain-entry key naming that account's OAuth credentials file path."""
+
 ALL_USAGE_LIMIT_SIGNATURES: tuple[str, ...] = (
     "hit your session limit",
     "usage limit reached",
@@ -91,9 +140,15 @@ CONFIG_ENTRY_EXTRA_ARGS_INVALID_REASON: str = (
 )
 """Reason detail when a chain entry's extra_args value is the wrong shape."""
 
+CONFIG_ENTRY_CREDENTIALS_PATH_INVALID_REASON: str = (
+    "a chain entry's 'credentials_path' is not a non-empty string"
+)
+"""Reason detail when a chain entry's credentials_path value is the wrong shape."""
+
 CONFIG_MISSING_MESSAGE_TEMPLATE: str = (
     "Claude chain config not found at {config_path}. Copy {example_filename} to "
-    "{config_path} and list your logged-in claude binaries in fallback order."
+    "{config_path} and list your account binaries. Try order comes from weekly "
+    "remaining; config order is the tiebreak."
 )
 """Guidance shown when the config file is absent."""
 

package/scripts/dev_env_scripts_constants/claude_chain_usage_constants.py

@@ -0,0 +1,58 @@
+"""Named constants for the claude chain weekly-usage report tool.
+
+Per the project's configuration conventions, every scalar and structural
+constant the usage reporter needs lives here rather than inline in the module.
+"""
+
+from __future__ import annotations
+
+FULL_WEEKLY_PERCENT: float = 100.0
+"""Percent scale ceiling for weekly utilization (remaining = this minus used)."""
+
+USAGE_PAUSE_SKILL_DIRECTORY_NAME: str = "skills"
+"""Package-root directory name that holds skill trees (sibling of ``scripts/``)."""
+
+USAGE_PAUSE_SKILL_NAME: str = "usage-pause"
+"""Skill directory name under ``skills/`` that owns the OAuth usage probe."""
+
+USAGE_PAUSE_SCRIPTS_DIRECTORY_NAME: str = "scripts"
+"""Directory under the usage-pause skill that holds the OAuth probe module."""
+
+RESOLVE_USAGE_WINDOW_MODULE_NAME: str = "resolve_usage_window"
+"""Module name of the usage-pause OAuth probe loader."""
+
+RESOLVE_USAGE_WINDOW_FILENAME: str = "resolve_usage_window.py"
+"""Filename of the usage-pause OAuth probe module on disk."""
+
+JSON_ACCOUNTS_KEY: str = "accounts"
+"""Top-level key in the CLI JSON report holding the per-account list."""
+
+JSON_COMMAND_KEY: str = "command"
+"""Per-account JSON key naming the chain binary."""
+
+JSON_WEEKLY_REMAINING_PERCENT_KEY: str = "weekly_remaining_percent"
+"""Per-account JSON key for remaining weekly usage percent (or null)."""
+
+JSON_ERROR_KEY: str = "error"
+"""Per-account JSON key carrying the unmeasurable-reason string."""
+
+CLI_CONFIG_PATH_FLAG: str = "--config-path"
+"""CLI flag that overrides the chain configuration file path."""
+
+NO_ACCESS_TOKEN_ERROR_TEMPLATE: str = (
+    "no usable bearer token from the OAuth credential file at {credentials_path}"
+)
+"""Error when the entry credential file yields no usable OAuth bearer."""
+
+WEEKLY_UTILIZATION_MISSING_ERROR: str = (
+    "usage response carried no weekly utilization"
+)
+"""Error when the OAuth usage payload has no readable seven_day utilization."""
+
+USAGE_PROBE_FAILED_ERROR_TEMPLATE: str = "usage probe failed: {error}"
+"""Error when the OAuth usage HTTP probe raises."""
+
+RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE: str = (
+    "usage-pause probe module not found at {module_path}"
+)
+"""Error when the resolve_usage_window script cannot be located on disk."""

package/scripts/dev_env_scripts_constants/code_review_constants.py

@@ -1,27 +1,76 @@
 """Named constants for the host-aware `/code-review` invoker.
 
-`invoke_code_review.py` imports every scalar and structural constant it
-needs from this module (and shared flag tokens from
-`grok_worker_constants`) so the prompt, model alias, and JSON keys are
-never hardcoded twice.
+::
+
+    ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
+        ok: ("low", "medium", "high", "xhigh", "max")
+        flag: "ultra"  (rejected; needs an interactive terminal)
+    RECORD_STAMP_FLAG
+        ok: "--record-stamp"
+
+Effort tokens re-export the hooks enforcement constants (single source).
+Scalar flags, JSON keys, and mint-loop messages live here for the invoker.
 """
 
 from __future__ import annotations
 
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+
+def _load_enforcement_constants_module() -> ModuleType:
+    """Load the hooks enforcement constants by explicit file path.
+
+    Binds a private module name so a foreign ``config`` package on
+    ``sys.path`` cannot win the import and drift the effort token set.
+    """
+    package_root_directory = Path(__file__).resolve().parent.parent.parent
+    constants_file_path = (
+        package_root_directory
+        / "hooks"
+        / "blocking"
+        / "config"
+        / "code_review_enforcement_constants.py"
+    )
+    module_name = "_code_review_enforcement_constants_for_scripts"
+    cached_module = sys.modules.get(module_name)
+    if cached_module is not None:
+        return cached_module
+    module_spec = importlib.util.spec_from_file_location(
+        module_name,
+        constants_file_path,
+    )
+    if module_spec is None or module_spec.loader is None:
+        raise ImportError(
+            f"could not load code-review enforcement constants from {constants_file_path}"
+        )
+    constants_module = importlib.util.module_from_spec(module_spec)
+    sys.modules[module_name] = constants_module
+    module_spec.loader.exec_module(constants_module)
+    return constants_module
+
+
+_ENFORCEMENT_CONSTANTS = _load_enforcement_constants_module()
+
+ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER: tuple[str, ...] = (
+    _ENFORCEMENT_CONSTANTS.ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
+)
+"""Effort tokens ordered low to max; single source from enforcement constants."""
+
+RECORD_STAMP_FLAG: str = _ENFORCEMENT_CONSTANTS.SANCTIONED_STAMP_MINTER_FLAG
+"""CLI flag that forces chain mode and mints a clean stamp on a stable pass."""
+
+DEFAULT_CODE_REVIEW_EFFORT: str = "high"
+"""Default effort when the caller omits the positional effort token."""
+
 CODE_REVIEW_SLASH_COMMAND: str = "/code-review"
 """Built-in Claude Code slash command that runs the repository review."""
 
-CODE_REVIEW_EFFORT: str = "high"
-"""Effort level passed to the built-in review slash command."""
-
 CODE_REVIEW_FIX_FLAG: str = "--fix"
 """Slash-command flag that applies automatic fixes for review findings."""
 
-CODE_REVIEW_PROMPT: str = (
-    f"{CODE_REVIEW_SLASH_COMMAND} {CODE_REVIEW_EFFORT} {CODE_REVIEW_FIX_FLAG}"
-)
-"""Single-turn prompt that runs the built-in review slash command with fixes."""
-
 CODE_REVIEW_MODEL_ALIAS: str = "opus"
 """CLI `--model` short alias the review always pins to."""
 
@@ -69,3 +118,71 @@ HOST_PROFILE_ERROR_RETURNCODE: int = 1
 
 SUCCESSFUL_REVIEW_RETURNCODE: int = 0
 """Return code required before a clean stamp may advance past CODE_REVIEW."""
+
+RESULT_KEY_STAMP_MINTED: str = "stamp_minted"
+"""JSON result key holding whether a clean stamp was written this run."""
+
+RESULT_KEY_PASS_COUNT: str = "pass_count"
+"""JSON result key holding how many review passes the mint loop ran."""
+
+RESULT_KEY_BOUND_HASH: str = "bound_hash"
+"""JSON result key holding the surface hash bound into a minted stamp, or null."""
+
+CLI_EFFORT_METAVAR: str = "effort"
+"""Argparse metavar for the positional effort token."""
+
+CLI_EFFORT_HELP: str = (
+    "Review effort token: low, medium, high, xhigh, or max "
+    "(ultra is rejected; default high)."
+)
+"""Help text for the positional effort argument."""
+
+CLI_RECORD_STAMP_HELP: str = (
+    "Force chain mode, loop a capped number of review passes, and mint a "
+    "clean stamp only when a pass exits 0 with a stable surface hash."
+)
+"""Help text for the --record-stamp flag."""
+
+INVALID_EFFORT_RETURNCODE: int = 2
+"""Return code when the caller passes an unknown or unsupported effort token."""
+
+STAMP_DID_NOT_CONVERGE_RETURNCODE: int = 1
+"""Return code when the mint loop hits its pass cap without a stable clean pass."""
+
+MAXIMUM_STAMP_MINT_PASSES: int = 3
+"""Cap on review passes under --record-stamp before the invoker gives up."""
+
+EFFORT_TOKEN_LIST_SEPARATOR: str = ", "
+"""Separator used when listing allowed effort tokens in error messages."""
+
+INVALID_EFFORT_MESSAGE: str = (
+    "invalid effort {effort!r}: must be one of {allowed}; "
+    "'ultra' is rejected because it requires an interactive terminal"
+)
+"""Stderr template when the caller supplies an unknown or ultra effort token."""
+
+STAMP_DID_NOT_CONVERGE_MESSAGE: str = (
+    "code-review stamp minting did not converge after {pass_count} passes "
+    "(surface kept changing or review return codes stayed non-zero); no stamp written"
+)
+"""Stderr template when the mint loop hits the pass cap without minting."""
+
+STAMP_STORE_IMPORT_FAILURE_MESSAGE: str = (
+    "code-review stamp store could not be imported for --record-stamp: {error}"
+)
+"""Stderr template when --record-stamp cannot load the stamp store module."""
+
+STAMP_STORE_MODULE_FILE_NAME: str = "code_review_stamp_store.py"
+"""File name of the stamp store module under hooks/blocking."""
+
+STAMP_STORE_MODULE_NAME: str = "code_review_stamp_store"
+"""Import name of the stamp store module."""
+
+STAMP_STORE_LIVE_SURFACE_HASH_NAME: str = "live_surface_hash"
+"""Attribute name of the live surface-hash helper on the stamp store module."""
+
+STAMP_STORE_RECORD_CLEAN_STAMP_NAME: str = "record_clean_stamp"
+"""Attribute name of the stamp-mint helper on the stamp store module."""
+
+STAMP_STORE_RESOLVE_REPO_ROOT_NAME: str = "resolve_repo_root"
+"""Attribute name of the repo-root resolver on the stamp store module."""

package/scripts/dev_env_scripts_constants/test_code_review_constants.py

@@ -0,0 +1,55 @@
+"""Behavioral tests for the host-aware code-review invoker constants module.
+
+These assert the single-source wiring: the effort tokens and the record-stamp
+flag the invoker exposes are the exact values the hooks enforcement module
+holds, so a threshold change in one place cannot drift the other.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from types import ModuleType
+
+from dev_env_scripts_constants import code_review_constants as review_constants
+
+_PACKAGE_ROOT = Path(__file__).resolve().parent.parent.parent
+_ENFORCEMENT_CONSTANTS_PATH = (
+    _PACKAGE_ROOT
+    / "hooks"
+    / "blocking"
+    / "config"
+    / "code_review_enforcement_constants.py"
+)
+
+
+def _load_enforcement_module() -> ModuleType:
+    module_spec = importlib.util.spec_from_file_location(
+        "code_review_enforcement_constants_under_test", _ENFORCEMENT_CONSTANTS_PATH
+    )
+    assert module_spec is not None
+    assert module_spec.loader is not None
+    enforcement_module = importlib.util.module_from_spec(module_spec)
+    module_spec.loader.exec_module(enforcement_module)
+    return enforcement_module
+
+
+def test_effort_tokens_reexport_the_enforcement_source() -> None:
+    enforcement_module = _load_enforcement_module()
+    assert review_constants.ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER == getattr(
+        enforcement_module, "ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER"
+    )
+
+
+def test_record_stamp_flag_matches_sanctioned_minter_flag() -> None:
+    enforcement_module = _load_enforcement_module()
+    assert review_constants.RECORD_STAMP_FLAG == getattr(
+        enforcement_module, "SANCTIONED_STAMP_MINTER_FLAG"
+    )
+
+
+def test_default_effort_is_a_known_token() -> None:
+    assert (
+        review_constants.DEFAULT_CODE_REVIEW_EFFORT
+        in review_constants.ALL_EFFORT_TOKENS_IN_ASCENDING_ORDER
+    )

package/scripts/dev_env_scripts_constants/timing.py

@@ -13,5 +13,5 @@ DEFAULT_POLL_INTERVAL: int = 30
 WORKER_STAGGER_SECONDS: int = 15
 """Seconds between staggered headless grok worker process starts in a batch."""
 
-DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS: int = 600
+DEFAULT_CODE_REVIEW_TIMEOUT_SECONDS: int = 2400
 """Default timeout applied to one headless `/code-review` chain invocation, in seconds."""