claude-dev-env 2.35.0 → 4.0.0

package/hooks/validators/run_all_validators.py

@@ -19,7 +19,7 @@ from dataclasses import dataclass
 from functools import lru_cache
 from datetime import datetime
 from pathlib import Path
-from typing import Callable, Dict, List, Optional, Tuple
+from typing import Callable, Collection, Dict, List, Optional, Tuple
 
 from ._path_setup import hooks_directory_on_path  # noqa: F401
 from .config.baseline_identity_constants import (
@@ -51,7 +51,7 @@ from blocking.codex_apply_patch import (
     parse_codex_apply_patch,
     payload_patch_command,
 )
-from hooks_constants.pre_tool_use_dispatcher_constants import (
+from hooks_constants.tool_names import (
     APPLY_PATCH_TOOL_NAME,
 )
 from hooks_constants.hook_block_logger import log_hook_block
@@ -885,6 +885,8 @@ def validate_proposed_file(
     file_path: str,
     proposed_content: str,
     config_source_path: Optional[Path] = None,
+    include_ruff: bool = True,
+    excluded_validator_names: Collection[str] = (),
 ) -> List[ValidatorResult]:
     """Validate *proposed_content* as if written to *file_path*.
 
@@ -901,10 +903,12 @@ def validate_proposed_file(
         proposed_content: The reconstructed post-edit content of that file.
         config_source_path: Path Ruff resolves its config from; defaults to
             *file_path* when the caller passes nothing.
+        include_ruff: Whether to run Ruff after the in-process validators.
+        excluded_validator_names: Display names omitted from the in-process run.
 
     Returns:
-        One ValidatorResult per save-path check, plus Ruff. Mypy never runs
-        here; CLI/full mode is the only caller that still runs it.
+        One ValidatorResult per in-process check, plus Ruff when requested.
+        Mypy never runs here; CLI/full mode is the only caller that still runs it.
     """
     with tempfile.TemporaryDirectory() as temporary_directory:
         temporary_file = _temporary_path_preserving_directory_signal(
@@ -916,10 +920,14 @@ def validate_proposed_file(
             if config_source_path is not None
             else Path(file_path)
         )
-        return [
-            *run_fast_save_validators([temporary_file]),
-            run_ruff_checks([temporary_file], resolved_config_source_path),
-        ]
+        all_results = run_fast_save_validators(
+            [temporary_file], excluded_validator_names
+        )
+        if include_ruff:
+            all_results.append(
+                run_ruff_checks([temporary_file], resolved_config_source_path)
+            )
+        return all_results
 
 
 def _validator_summaries(results: List[ValidatorResult]) -> str:

package/hooks/validators/test_fast_save_validators_policy_lint.py

@@ -0,0 +1,25 @@
+"""Prove the fast-save validator seam can omit native or duplicate checks."""
+
+from pathlib import Path
+
+from .fast_save_validators import run_fast_save_validators
+
+_CLEAN_SOURCE = (
+    "def add_two_numbers(first_number: int, second_number: int) -> int:\n"
+    "    return first_number + second_number\n"
+)
+_OVERLAPPING_VALIDATOR_NAMES = frozenset(
+    {"Python Style", "Magic Values", "Type Safety", "Test Safety", "React"}
+)
+
+
+def test_fast_save_validators_excludes_requested_outcomes(tmp_path: Path) -> None:
+    target_path = tmp_path / "probe.py"
+    target_path.write_text(_CLEAN_SOURCE, encoding="utf-8")
+    all_results = run_fast_save_validators(
+        [target_path], _OVERLAPPING_VALIDATOR_NAMES
+    )
+
+    all_result_names = {each_result.name for each_result in all_results}
+    assert all_result_names.isdisjoint(_OVERLAPPING_VALIDATOR_NAMES)
+    assert "Abbreviations" in all_result_names

package/hooks/validators/test_run_all_validators_policy_lint.py

@@ -0,0 +1,52 @@
+"""Prove the policy-linter validator seam keeps native tools separate."""
+
+from pathlib import Path
+
+import pytest
+
+from . import run_all_validators
+
+_CLEAN_SOURCE = (
+    "def add_two_numbers(first_number: int, second_number: int) -> int:\n"
+    "    return first_number + second_number\n"
+)
+_OVERLAPPING_VALIDATOR_NAMES = frozenset(
+    {"Python Style", "Magic Values", "Type Safety", "Test Safety", "React"}
+)
+
+
+def _result_names(all_results: list[run_all_validators.ValidatorResult]) -> set[str]:
+    return {each_result.name for each_result in all_results}
+
+
+def test_policy_lint_can_run_only_unique_in_process_validators(tmp_path: Path) -> None:
+    all_results = run_all_validators.validate_proposed_file(
+        str(tmp_path / "probe.py"),
+        _CLEAN_SOURCE,
+        include_ruff=False,
+        excluded_validator_names=_OVERLAPPING_VALIDATOR_NAMES,
+    )
+
+    all_result_names = _result_names(all_results)
+    assert all_result_names.isdisjoint(_OVERLAPPING_VALIDATOR_NAMES)
+    assert "Ruff" not in all_result_names
+    assert "Abbreviations" in all_result_names
+
+
+def test_validate_proposed_file_keeps_ruff_as_an_explicit_native_step(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setattr(
+        run_all_validators,
+        "run_ruff_checks",
+        lambda _files, _config_source_path: run_all_validators.ValidatorResult(
+            "Ruff", "37", True, "clean"
+        ),
+    )
+    all_results = run_all_validators.validate_proposed_file(
+        str(tmp_path / "probe.py"),
+        _CLEAN_SOURCE,
+        excluded_validator_names=_OVERLAPPING_VALIDATOR_NAMES,
+    )
+
+    assert "Ruff" in _result_names(all_results)

package/package.json

@@ -1,11 +1,12 @@
 {
     "name": "claude-dev-env",
-    "version": "2.35.0",
+    "version": "4.0.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
         "claude-dev-env": "bin/install.mjs",
-        "codex-compat": "bin/codex-compat.mjs"
+        "codex-compat": "bin/codex-compat.mjs",
+        "cde": "bin/cde.mjs"
     },
     "scripts": {
         "test": "node --test \"bin/*.test.mjs\" \".agents/skills/**/*.test.mjs\" \"tests/fresh-session/**/*.test.mjs\""

package/rules/pstack-models.md

@@ -0,0 +1,119 @@
+# Pstack delegation policy
+
+Pstack uses portable role requirements. Model IDs belong to host preference
+files. The active native subagent tool decides which model IDs the current host
+accepts.
+
+This policy replaces the fixed model defaults in pstack skills and setup-pstack's
+legacy step that writes one universal model rule. Setup updates only the selected
+host preference JSON. The installer keeps this portable policy current.
+
+## Setup
+
+When setup-pstack runs, read the active native subagent tool metadata. Use the
+host name from that tool or the current host context. Do not infer the host from
+CODEX_HOME, CLAUDE_CONFIG_DIR, or another environment variable.
+
+Save choices in the agents home under
+`rules/pstack-model-preferences.<host>.json`. Keep each host in its own file.
+The file contains this shape:
+
+```json
+{
+  "host": "current-host",
+  "modelsByRole": {
+    "feature, refactoring": ["confirmed-host-model"]
+  }
+}
+```
+
+Offer only model IDs the active native tool accepts. Keep the user's order.
+Treat `inherit-parent` and `auto` as parent inheritance, not model IDs. A
+different host starts with its own confirmed choices. It never copies the Codex
+preference file.
+
+## Selection before every delegation
+
+Refresh the accepted model IDs from the active native subagent tool immediately
+before each native delegation. Run the installed selector once for each agent.
+Use `~/.agents/scripts/select_pstack_models.mjs` for the main profile. For a
+named or explicit profile, use the selector under that profile's sibling agents
+home.
+
+Send one JSON object through standard input. Use the active host shell on
+other operating systems:
+
+```powershell
+$selectorInput = @'
+{
+  "host": "current-host",
+  "inventoryHost": "current-host",
+  "role": "how critics",
+  "delegationIndex": 0,
+  "panel": {
+    "agentCount": 3,
+    "requiresDistinctModels": false
+  },
+  "availableModelIds": ["confirmed-host-model"],
+  "confirmedSuitableModelIds": [],
+  "parentModelId": "current-parent-model",
+  "parentFallback": {
+    "isAllowed": true,
+    "hasMaterialCapabilityLoss": false
+  }
+}
+'@
+$selection = $selectorInput | node "$HOME/.agents/scripts/select_pstack_models.mjs"
+```
+
+`availableModelIds` comes from the current native tool metadata.
+`confirmedSuitableModelIds` contains available alternatives whose suitability
+for this role the host metadata or user has confirmed. Do not rank or classify a
+model from its name.
+
+Use the returned `nativeSpawnArguments` in the native subagent call. An empty
+object with `omitNativeModelArgument: true` means parent inheritance, so omit
+the native `model` argument. Stop when `canDelegate` is false. Ask the user
+when `requiresUserChoice` is true.
+
+Run the selector again before the next agent call. Pass the same panel contract
+and the new delegation index with the refreshed inventory. Report
+`panel.selectedModelIds` and `panel.isCrossModelDiverse` as returned. A panel
+that repeats one model is a same-model panel.
+
+## Portable role requirements
+
+feature, refactoring: reliable code execution
+bug-fix: careful diagnosis and code execution
+perf-issue: systems reasoning and performance analysis
+hillclimb: strong iterative judgment
+judgment and prose: strong judgment and clear prose
+hardest tasks: highest available reasoning capability
+how explorer: fast codebase exploration
+how explainer: clear technical synthesis
+how critics: independent technical criticism
+why investigators: fast evidence gathering
+why synthesizer: strong evidence synthesis
+reflect tooling: reliable tool and workflow analysis
+reflect judgment, divergent, synthesizer: strong judgment and divergent analysis
+arena runners: independent solution development
+arena cross-judge pool: independent comparative judgment
+swarm workers: fast bounded task execution
+architect runners: independent architecture design
+interrogate reviewers: independent adversarial review
+
+## Panel requirements
+
+Panel size and model diversity are separate from model preferences.
+
+- How critics use three agents by default. Cross-model diversity is optional.
+- Arena runners use three agents by default and require distinct models.
+- The arena cross-judge pool selects one judge. Pass `parentModelId` so the
+  selector chooses another available preference before the parent's model.
+- Swarm uses the requested worker count. Same-model workers are valid.
+- Architect uses two agents by default and requires distinct models.
+- Interrogate uses three agents by default and requires distinct models.
+
+A required-diversity panel stops when the current host lacks enough distinct
+confirmed models. Parent inheritance is the last fallback. When inheritance
+causes material capability loss, stop and ask the user before delegating.

package/scripts/cde_lint.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""Run the policy linter."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Never, TextIO
+
+from policy_lint.config.constants import INVALID_INPUT_EXIT_CODE
+from policy_lint.engine import lint
+from policy_lint.model import LintReport, LintRequest, SelectionKind, TextDocument
+from policy_lint.render import ReportFormat, render
+from policy_lint.selection import SelectionRunFatal
+from policy_lint.selection_git import GitSelectionError, git_bytes_for
+
+
+class _LintUsageError(ValueError):
+    """Raised when command arguments cannot form a source selection."""
+
+
+class _LintArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> Never:
+        """Raise a usage error instead of printing and exiting.
+
+        Args:
+            message: Parser error text.
+
+        Raises:
+            _LintUsageError: Always.
+        """
+        raise _LintUsageError(message)
+
+
+def _discover_repository_root(starting_directory: Path) -> Path:
+    """Find the Git root that contains the command's current directory.
+
+    Args:
+        starting_directory: Directory where the command started.
+
+    Returns:
+        The resolved Git repository root.
+
+    Raises:
+        _LintUsageError: If the directory is not inside a Git repository.
+    """
+    try:
+        root_bytes = git_bytes_for(
+            starting_directory.resolve(), ("rev-parse", "--show-toplevel")
+        )
+    except (GitSelectionError, OSError) as error:
+        raise _LintUsageError("Current directory is not inside a Git repository") from error
+    root_text = root_bytes.decode("utf-8").strip()
+    if not root_text:
+        raise _LintUsageError("Git returned an empty repository root")
+    return Path(root_text).resolve()
+
+
+def _resolve_shell_file_arguments(
+    all_arguments: Sequence[str], starting_directory: Path
+) -> list[str]:
+    all_resolved_arguments: list[str] = []
+    is_reading_file_paths = False
+    for each_argument in all_arguments:
+        if each_argument in ("--files", "--text-as"):
+            is_reading_file_paths = True
+            all_resolved_arguments.append(each_argument)
+            continue
+        if each_argument.startswith("--"):
+            is_reading_file_paths = False
+            all_resolved_arguments.append(each_argument)
+            continue
+        if not is_reading_file_paths:
+            all_resolved_arguments.append(each_argument)
+            continue
+        candidate_path = Path(each_argument)
+        all_resolved_arguments.append(
+            str(
+                candidate_path
+                if candidate_path.is_absolute()
+                else starting_directory / candidate_path
+            )
+        )
+    return all_resolved_arguments
+
+
+def _add_file_sources(source_group: argparse._MutuallyExclusiveGroup) -> None:
+    source_group.add_argument(
+        "--files",
+        nargs="+",
+        dest="all_file_paths",
+        metavar="PATH",
+        default=None,
+        help="Lint current worktree files.",
+    )
+    source_group.add_argument(
+        "--staged",
+        action="store_const",
+        const=SelectionKind.STAGED,
+        dest="selection_kind",
+        help="Lint staged index content.",
+    )
+
+
+def _add_repository_sources(
+    source_group: argparse._MutuallyExclusiveGroup,
+) -> None:
+    source_group.add_argument(
+        "--base",
+        dest="base_revision",
+        metavar="REVISION",
+        default=None,
+        help="Lint changes from a base revision.",
+    )
+    source_group.add_argument(
+        "--repository",
+        action="store_const",
+        const=SelectionKind.REPOSITORY,
+        dest="selection_kind",
+        help="Lint tracked worktree files.",
+    )
+    source_group.add_argument(
+        "--text-as",
+        dest="text_path",
+        metavar="PATH",
+        default=None,
+        help="Lint one editor buffer from standard input.",
+    )
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = _LintArgumentParser(prog="cde lint")
+    source_group = parser.add_mutually_exclusive_group(required=True)
+    _add_file_sources(source_group)
+    _add_repository_sources(source_group)
+    parser.add_argument(
+        "--format",
+        dest="report_format",
+        choices=tuple(each_format.value for each_format in ReportFormat),
+        default=ReportFormat.TEXT.value,
+        help="Report format.",
+    )
+    parser.set_defaults(selection_kind=None)
+    return parser
+
+
+def _request_from_namespace(
+    namespace: argparse.Namespace,
+    stdin: TextIO,
+    repository_root: Path,
+) -> LintRequest:
+    if namespace.all_file_paths is not None:
+        return LintRequest.files(
+            repository_root,
+            [Path(each_path) for each_path in namespace.all_file_paths],
+        )
+    if namespace.base_revision is not None:
+        return LintRequest.base(repository_root, namespace.base_revision)
+    if namespace.text_path is not None:
+        return LintRequest(
+            repository_root,
+            TextDocument(Path(namespace.text_path), stdin.read()),
+        )
+    if namespace.selection_kind is SelectionKind.STAGED:
+        return LintRequest.staged(repository_root)
+    if namespace.selection_kind is SelectionKind.REPOSITORY:
+        return LintRequest.repository(repository_root)
+    raise _LintUsageError("A source selection is required")
+
+
+def _parse_lint_invocation(
+    all_arguments: Sequence[str],
+    stdin: TextIO,
+    repository_root: Path,
+) -> tuple[LintRequest, ReportFormat]:
+    namespace = _build_parser().parse_args(list(all_arguments))
+    return (
+        _request_from_namespace(namespace, stdin, repository_root),
+        ReportFormat(namespace.report_format),
+    )
+
+
+def _run_linter(
+    all_arguments: Sequence[str],
+    stdin: TextIO,
+    repository_root: Path,
+    lint_runner: Callable[[LintRequest], LintReport],
+) -> tuple[LintReport, ReportFormat]:
+    request, report_format = _parse_lint_invocation(
+        list(all_arguments),
+        stdin,
+        repository_root,
+    )
+    return lint_runner(request), report_format
+
+
+def _write_invalid_input(error: Exception, stderr: TextIO) -> int:
+    stderr.write(f"{error}\n")
+    return INVALID_INPUT_EXIT_CODE
+
+
+def _render_lint(
+    all_arguments: Sequence[str],
+    repository_root: Path,
+    stdin: TextIO,
+    stdout: TextIO,
+    lint_runner: Callable[[LintRequest], LintReport],
+) -> int:
+    report, report_format = _run_linter(
+        all_arguments, stdin, repository_root, lint_runner
+    )
+    stdout.write(render(report, report_format))
+    return report.exit_code
+
+
+def main(
+    all_arguments: Sequence[str],
+    repository_root: Path,
+    *,
+    stdin: TextIO = sys.stdin,
+    stdout: TextIO = sys.stdout,
+    stderr: TextIO = sys.stderr,
+    lint_runner: Callable[[LintRequest], LintReport] = lint,
+) -> int:
+    """Run the policy-lint command.
+
+    Args:
+        all_arguments: Command arguments.
+        repository_root: Repository root.
+        stdin: Input stream.
+        stdout: Output stream.
+        stderr: Error stream.
+        lint_runner: Policy-lint engine.
+
+    Returns:
+        The process exit code.
+    """
+    try:
+        return _render_lint(
+            all_arguments, repository_root, stdin, stdout, lint_runner
+        )
+    except _LintUsageError as usage_error:
+        return _write_invalid_input(usage_error, stderr)
+    except SelectionRunFatal as selection_error:
+        return _write_invalid_input(selection_error, stderr)
+
+
+if __name__ == "__main__":
+    try:
+        shell_directory = Path.cwd()
+        shell_repository_root = _discover_repository_root(shell_directory)
+    except _LintUsageError as usage_error:
+        sys.stderr.write(f"{usage_error}\n")
+        raise SystemExit(INVALID_INPUT_EXIT_CODE) from usage_error
+    all_shell_arguments = _resolve_shell_file_arguments(sys.argv[1:], shell_directory)
+    raise SystemExit(main(all_shell_arguments, shell_repository_root))

package/scripts/check.ps1

@@ -1,8 +1,9 @@
 #!/usr/bin/env pwsh
 <#
 .SYNOPSIS
-    One-shot quality gate — runs ruff, hooks mypy, pr-loop mypy,
-    process-tree mypy, and the blocking pytest suite from a single entry point.
+    One-shot quality gate. Runs ruff, hooks mypy, pr-loop mypy,
+    process-tree mypy, repository-policy, and the blocking pytest suite from a
+    single entry point.
 
 .DESCRIPTION
     Resolves paths relative to $PSScriptRoot so the script works from any CWD
@@ -11,9 +12,10 @@
     propagates this file). Tools: ruff over hooks/, mypy over hooks blocking
     and validators, mypy-pr-loop over _shared/pr-loop/scripts production
     modules, mypy-process-tree over the shared process-tree kill helper and
-    its constants, and optional pytest over the blocking enforcer suite. Each tool
-    runs sequentially; the first non-zero exit code is preserved as the
-    script's exit code so CI/pre-commit can short-circuit on the first failure.
+    its constants, repository-policy over the committed tree, and optional
+    pytest over the blocking enforcer suite. Each tool runs in sequence. The
+    first non-zero exit code is preserved as the script's exit code so CI and
+    pre-commit can stop on the first failure.
 
 .PARAMETER SkipTests
     Skip the pytest run. Useful during local iteration when you want only the
@@ -25,19 +27,23 @@
 .PARAMETER SkipRuff
     Skip the ruff run.
 
+.PARAMETER SkipRepositoryPolicy
+    Skip the committed-tree repository_policy.py run.
+
 .PARAMETER CommentPolicyBase
     Optional git reference used as the comment-policy baseline.
 
 .OUTPUTS
     Per-tool status lines on stdout. Final summary line:
         CHECK: OK
-        CHECK: FAILED tools=ruff,mypy,mypy-pr-loop,mypy-process-tree,pytest
+        CHECK: FAILED tools=ruff,repository-policy,mypy,mypy-pr-loop,mypy-process-tree,pytest
 #>
 [CmdletBinding()]
 param(
     [switch]$SkipTests,
     [switch]$SkipMypy,
     [switch]$SkipRuff,
+    [switch]$SkipRepositoryPolicy,
     [string]$CommentPolicyBase
 )
 
@@ -121,6 +127,12 @@ Invoke-Tool -Label 'comment-policy' -Action {
     }
 }
 
+if (-not $SkipRepositoryPolicy) {
+    Invoke-Tool -Label 'repository-policy' -Action {
+        python (Join-Path $PSScriptRoot 'repository_policy.py') --repository-root $repositoryRoot
+    }
+}
+
 if (-not $SkipMypy) {
     Invoke-Tool -Label 'mypy' -Action {
         Push-Location $hooksRoot

package/scripts/policy_lint/__init__.py

@@ -0,0 +1,41 @@
+from .engine import lint
+from .model import (
+    BaseChanges,
+    ChangeSetRule,
+    ContentOrigin,
+    Diagnostic,
+    Document,
+    DocumentRule,
+    DocumentSet,
+    ExplicitFiles,
+    LintReport,
+    LintRequest,
+    Location,
+    RepositoryRule,
+    RepositoryTree,
+    SelectionKind,
+    Severity,
+    StagedChanges,
+    TextDocument,
+)
+
+__all__ = [
+    "BaseChanges",
+    "ChangeSetRule",
+    "ContentOrigin",
+    "Diagnostic",
+    "Document",
+    "DocumentRule",
+    "DocumentSet",
+    "ExplicitFiles",
+    "LintReport",
+    "LintRequest",
+    "Location",
+    "RepositoryRule",
+    "RepositoryTree",
+    "SelectionKind",
+    "Severity",
+    "StagedChanges",
+    "TextDocument",
+    "lint",
+]