claude-dev-env 2.35.0 → 2.36.0

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": "2.36.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/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",
+]

package/scripts/policy_lint/adapter_configuration.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from . import adapter_support
+from .config import constants
+from .model import Diagnostic, Document
+
+
+def hook_configuration_diagnostics(
+    document: Document, repository_root: Path
+) -> tuple[Diagnostic, ...]:
+    """Check hook configuration for policy decision fields.
+
+    Args:
+        document: Current hook configuration text.
+        repository_root: Request repository root for document-path resolution.
+
+    Returns:
+        Hook configuration diagnostics.
+    """
+    adapter_support._document_path(repository_root, document)
+    if document.path.name != "hooks.json":
+        return ()
+    all_messages = _hook_configuration_messages(document.text)
+    return adapter_support._diagnostics_for_messages(
+        document, "hook-configuration", all_messages
+    )
+
+
+def _hook_configuration_messages(configuration_text: str) -> tuple[str, ...]:
+    try:
+        parsed_configuration = json.loads(configuration_text)
+    except json.JSONDecodeError:
+        return ("Hook configuration is not valid JSON",)
+    if not isinstance(parsed_configuration, dict):
+        return ("Hook configuration must be an object",)
+    all_registered_strings = _registered_hook_strings(parsed_configuration)
+    if any(
+        _contains_action_boundary_marker(each_string)
+        for each_string in all_registered_strings
+    ):
+        return ("Hook configuration registers a deny, block, or ask policy path",)
+    return ()
+
+
+def _registered_hook_strings(
+    all_configuration_entries: dict[object, object]
+) -> tuple[str, ...]:
+    all_registered_strings: list[str] = []
+    for each_key, each_entry in all_configuration_entries.items():
+        all_registered_strings.extend(
+            _registered_strings_for_entry(each_key, each_entry)
+        )
+    return tuple(all_registered_strings)
+
+
+def _registered_strings_for_entry(
+    each_key: object, each_entry: object
+) -> tuple[str, ...]:
+    all_registered_strings: list[str] = []
+    if each_key in constants.ALL_HOOK_REGISTRATION_KEYS and isinstance(each_entry, str):
+        all_registered_strings.append(each_entry)
+    if each_key in constants.ALL_DECISION_REGISTRATION_KEYS and isinstance(each_entry, str):
+        all_registered_strings.append(each_entry)
+    all_registered_strings.extend(_registered_nested_strings(each_entry))
+    return tuple(all_registered_strings)
+
+
+def _registered_nested_strings(each_entry: object) -> tuple[str, ...]:
+    if isinstance(each_entry, dict):
+        return _registered_hook_strings(each_entry)
+    if not isinstance(each_entry, list):
+        return ()
+    all_registered_strings: list[str] = []
+    for each_nested_entry in each_entry:
+        if isinstance(each_nested_entry, dict):
+            all_registered_strings.extend(_registered_hook_strings(each_nested_entry))
+    return tuple(all_registered_strings)
+
+
+def _contains_action_boundary_marker(registered_string: str) -> bool:
+    normalized_string = registered_string.lower().replace("\\", "/")
+    normalized_string = normalized_string.replace(".", "/").replace("-", "/")
+    return any(
+        each_segment in constants.ALL_ACTION_BOUNDARY_SEGMENTS
+        or each_segment.startswith(constants.ALL_ACTION_BOUNDARY_PREFIXES)
+        for each_segment in normalized_string.split("/")
+        if each_segment
+    )