claude-dev-env 2.36.0 → 4.1.0

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

@@ -3,11 +3,51 @@ from __future__ import annotations
 from collections.abc import Iterable
 from contextlib import redirect_stderr, redirect_stdout
 from io import StringIO
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 
 from . import adapter_support
 from .config import constants
-from .model import Diagnostic, Document
+from .model import Diagnostic, Document, DocumentSet, Location, SelectionKind, Severity
+
+
+def _terminology_diagnostic(finding: str) -> Diagnostic:
+    finding_match = constants.TERMINOLOGY_FINDING_PATTERN.fullmatch(finding)
+    if finding_match is None:
+        raise ValueError(finding)
+    return Diagnostic(
+        constants.TERMINOLOGY_SWEEP_RULE_ID,
+        Severity.ERROR,
+        finding_match.group(constants.TERMINOLOGY_MESSAGE_GROUP),
+        Location(
+            PurePosixPath(finding_match.group(constants.TERMINOLOGY_PATH_GROUP)),
+            int(finding_match.group(constants.TERMINOLOGY_LINE_NUMBER_GROUP)),
+        ),
+    )
+
+
+def terminology_diagnostics(
+    document_set: DocumentSet,
+    load_module: adapter_support.HookModuleLoader,
+) -> tuple[Diagnostic, ...]:
+    """Report staged prose that near-misses a newly introduced identifier.
+
+    Args:
+        document_set: Candidate staged documents and repository root.
+        load_module: Shared script module loader.
+
+    Returns:
+        Diagnostics that name the prose file and line.
+    """
+    if document_set.selection is not SelectionKind.STAGED:
+        return ()
+    terminology_module = load_module(constants.TERMINOLOGY_SWEEP_MODULE_NAME)
+    helper_stdout = StringIO()
+    helper_stderr = StringIO()
+    with redirect_stdout(helper_stdout), redirect_stderr(helper_stderr):
+        all_findings = terminology_module.strict_staged_terminology_findings(
+            document_set.repository_root
+        )
+    return tuple(_terminology_diagnostic(each_finding) for each_finding in all_findings)
 
 
 def _stable_validator_message(document: Document, raw_message: str) -> str:

package/scripts/policy_lint/adapters.py

@@ -23,6 +23,16 @@ def _hooks_module(module_name: str) -> ModuleType:
     return importlib.import_module(module_name)
 
 
+def _pr_loop_script_module(module_name: str) -> ModuleType:
+    package_directory = Path(__file__).resolve().parent.parent.parent
+    scripts_directory = str(
+        package_directory.joinpath(*constants.ALL_PR_LOOP_SCRIPTS_PATH_SEGMENTS)
+    )
+    if scripts_directory not in sys.path:
+        sys.path.insert(0, scripts_directory)
+    return importlib.import_module(module_name)
+
+
 def validator_diagnostics(
     document: Document, repository_root: Path
 ) -> tuple[Diagnostic, ...]:
@@ -222,6 +232,20 @@ def test_pairing_diagnostics(document_set: DocumentSet) -> tuple[Diagnostic, ...
     return adapter_pairing.test_pairing_diagnostics(document_set, _hooks_module)
 
 
+def terminology_diagnostics(document_set: DocumentSet) -> tuple[Diagnostic, ...]:
+    """Report staged prose that near-misses a newly introduced identifier.
+
+    Args:
+        document_set: Candidate staged documents and repository root.
+
+    Returns:
+        Diagnostics that name the prose file and line.
+    """
+    return adapter_detectors.terminology_diagnostics(
+        document_set, _pr_loop_script_module
+    )
+
+
 def hook_format_diagnostics(
     document: Document, repository_root: Path
 ) -> tuple[Diagnostic, ...]:

package/scripts/policy_lint/config/constants.py

@@ -1,3 +1,5 @@
+import re
+
 INCOMPLETE_EXIT_CODE = 3
 INVALID_INPUT_EXIT_CODE = 2
 GIT_EXECUTABLE = "git"
@@ -64,3 +66,12 @@ FAST_SAVE_VALIDATORS_STEM = "fast_save_validators"
 ALL_OVERLAPPING_VALIDATOR_NAMES = frozenset(
     {"Python Style", "Magic Values", "Type Safety", "Test Safety", "React"}
 )
+ALL_PR_LOOP_SCRIPTS_PATH_SEGMENTS = ("_shared", "pr-loop", "scripts")
+TERMINOLOGY_SWEEP_MODULE_NAME = "terminology_sweep"
+TERMINOLOGY_SWEEP_RULE_ID = "terminology-sweep"
+TERMINOLOGY_FINDING_PATTERN = re.compile(
+    r"^(?P<path>.+):(?P<line_number>\d+): (?P<message>.+)$"
+)
+TERMINOLOGY_PATH_GROUP = "path"
+TERMINOLOGY_LINE_NUMBER_GROUP = "line_number"
+TERMINOLOGY_MESSAGE_GROUP = "message"

package/scripts/policy_lint/engine.py

@@ -180,7 +180,7 @@ def _run_changeset_rule(
     all_diagnostics: list[Diagnostic],
     all_skipped_rules: list[str],
 ) -> None:
-    if document_set.selection not in {SelectionKind.STAGED, SelectionKind.BASE}:
+    if document_set.selection not in rule.selections:
         all_skipped_rules.append(rule.rule_id)
         return
     all_diagnostics.extend(rule.check(document_set))

package/scripts/policy_lint/model.py

@@ -284,6 +284,7 @@ class DocumentRule:
 class ChangeSetRule:
     rule_id: str
     rule_sets: frozenset[str]
+    selections: frozenset[SelectionKind]
     check: DocumentSetChecker
 
 

package/scripts/policy_lint/registry.py

@@ -133,7 +133,16 @@ def default_registry() -> tuple[model.Rule, ...]:
         *_text_document_rules(),
         *_configuration_document_rules(),
         model.ChangeSetRule(
-            "test-pairing", frozenset({"changed"}), adapters.test_pairing_diagnostics
+            "test-pairing",
+            frozenset({"changed"}),
+            frozenset({model.SelectionKind.STAGED, model.SelectionKind.BASE}),
+            adapters.test_pairing_diagnostics,
+        ),
+        model.ChangeSetRule(
+            "terminology-sweep",
+            frozenset({"changed"}),
+            frozenset({model.SelectionKind.STAGED}),
+            adapters.terminology_diagnostics,
         ),
         model.RepositoryRule(
             "repository-path-collision",

package/scripts/repository_checks/__init__.py

@@ -0,0 +1 @@
+"""Committed-tree repository checks used by the repository_policy command."""

package/scripts/repository_checks/claude_md.py

@@ -0,0 +1,108 @@
+"""CLAUDE.md reference checks for committed trees."""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Sequence
+from pathlib import Path
+from types import ModuleType
+
+from policy_lint.config.constants import PATH_SEPARATOR, UTF8_ENCODING
+
+from repository_checks.config.constants import (
+    CHECK_ID_CLAUDE_MD_ORPHANS,
+    CLAUDE_MD_CONSTANTS_MODULE_NAME,
+    CLAUDE_MD_MISSING_FILE_MESSAGE_TEMPLATE,
+    CLAUDE_MD_SCAN_MODULE_NAME,
+    WINDOWS_PATH_SEPARATOR,
+)
+from repository_checks.hook_modules import load_hooks_module
+from repository_checks.models import RepositoryFinding
+
+
+def collect_claude_md_orphan_findings(
+    repository_root: Path, all_tracked_paths: Sequence[str]
+) -> list[RepositoryFinding]:
+    """Return missing CLAUDE.md references in the tracked tree.
+
+    Args:
+        repository_root: Git repository root.
+        all_tracked_paths: Repository-relative tracked paths.
+
+    Returns:
+        Findings for references whose files are absent.
+    """
+    subtree_scan = load_hooks_module(CLAUDE_MD_SCAN_MODULE_NAME)
+    claude_md_constants = load_hooks_module(CLAUDE_MD_CONSTANTS_MODULE_NAME)
+    all_findings: list[RepositoryFinding] = []
+    for each_relative_path in all_tracked_paths:
+        all_findings.extend(
+            find_orphan_findings_for_path(
+                repository_root,
+                each_relative_path,
+                subtree_scan,
+                claude_md_constants,
+            )
+        )
+    return all_findings
+
+
+def find_orphan_findings_for_path(
+    repository_root: Path,
+    relative_path: str,
+    subtree_scan: ModuleType,
+    claude_md_constants: ModuleType,
+) -> list[RepositoryFinding]:
+    """Return missing files named by one CLAUDE.md file.
+
+    Args:
+        repository_root: Git repository root.
+        relative_path: Repository-relative path to inspect.
+        subtree_scan: Existing reference detector module.
+        claude_md_constants: Existing detector constants module.
+
+    Returns:
+        Findings for referenced files that are absent from the scan root.
+    """
+    if Path(relative_path).name != claude_md_constants.CLAUDE_MD_FILENAME:
+        return []
+    absolute_path = repository_root / relative_path
+    if not absolute_path.is_file():
+        return []
+    return _find_orphans_in_claude_md(absolute_path, relative_path, subtree_scan)
+
+
+def _find_orphans_in_claude_md(
+    absolute_path: Path,
+    relative_path: str,
+    subtree_scan: ModuleType,
+) -> list[RepositoryFinding]:
+    content = absolute_path.read_text(encoding=UTF8_ENCODING)
+    claude_md_directory = absolute_path.parent
+    subtree_root = _subtree_root_for(claude_md_directory)
+    subtree_root.stat()
+    deque(subtree_root.rglob("*"), maxlen=0)
+    all_missing_filenames = subtree_scan.find_missing_filenames(
+        content, claude_md_directory
+    )
+    return _build_findings(relative_path, all_missing_filenames)
+
+
+def _subtree_root_for(claude_md_directory: Path) -> Path:
+    parent_directory = claude_md_directory.parent
+    if parent_directory == claude_md_directory:
+        return claude_md_directory
+    return parent_directory
+
+
+def _build_findings(
+    relative_path: str, all_missing_filenames: Sequence[str]
+) -> list[RepositoryFinding]:
+    return [
+        RepositoryFinding(
+            CHECK_ID_CLAUDE_MD_ORPHANS,
+            relative_path.replace(WINDOWS_PATH_SEPARATOR, PATH_SEPARATOR),
+            CLAUDE_MD_MISSING_FILE_MESSAGE_TEMPLATE.format(filename=each_filename),
+        )
+        for each_filename in all_missing_filenames
+    ]

package/scripts/repository_checks/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration for the committed-tree repository checker."""

package/scripts/repository_checks/config/constants.py

@@ -0,0 +1,150 @@
+"""Stable identifiers, report tokens, and committed-tree exemption tables."""
+
+from policy_lint.config.constants import (
+    GIT_FILES_ARGUMENT,
+    GIT_ZERO_TERMINATED_FLAG,
+    INCOMPLETE_EXIT_CODE,
+    INVALID_INPUT_EXIT_CODE,
+)
+
+CHECK_ID_CLAUDE_MD_ORPHANS = "claude-md-orphans"
+CHECK_ID_ENV_VAR_DOCUMENTATION = "env-var-documentation"
+CHECK_ID_PACKAGE_INVENTORY = "package-inventory"
+CHECK_ID_PYTEST_TESTPATHS = "pytest-testpaths"
+CHECK_ID_TRACKED_PERSONAL_DATA = "tracked-secrets"
+
+ALL_CHECK_IDS = (
+    CHECK_ID_CLAUDE_MD_ORPHANS,
+    CHECK_ID_ENV_VAR_DOCUMENTATION,
+    CHECK_ID_PACKAGE_INVENTORY,
+    CHECK_ID_PYTEST_TESTPATHS,
+    CHECK_ID_TRACKED_PERSONAL_DATA,
+)
+
+SUCCESS_EXIT_CODE = 0
+FINDINGS_EXIT_CODE = 1
+FAILED_CHECK_EXIT_CODE = INCOMPLETE_EXIT_CODE
+USAGE_EXIT_CODE = INVALID_INPUT_EXIT_CODE
+
+REPOSITORY_ROOT_FLAG = "--repository-root"
+FINDING_LINE_TEMPLATE = "{check_id}: {relative_path}: {message}"
+RULE_FAILED_LINE_TEMPLATE = "error: rule failed: {check_id}"
+REPORT_LINE_SEPARATOR = "\n"
+EMPTY_REPORT_TEXT = ""
+TRACKED_MATCH_MESSAGE_TEMPLATE = "[{category}] {preview}"
+CLAUDE_MD_MISSING_FILE_MESSAGE_TEMPLATE = "references missing file {filename}"
+PACKAGE_INVENTORY_MESSAGE_TEMPLATE = "production file is absent from package inventory"
+PYTEST_TESTPATH_MESSAGE_TEMPLATE = (
+    "test file is outside the package testpaths allowlist"
+)
+ALL_GIT_LS_FILES_ARGUMENTS = (GIT_FILES_ARGUMENT, GIT_ZERO_TERMINATED_FLAG)
+PYPROJECT_FILENAME = "pyproject.toml"
+WINDOWS_PATH_SEPARATOR = "\\"
+
+CLAUDE_MD_SCAN_MODULE_NAME = "blocking.claude_md_orphan_file_blocker_parts.subtree_scan"
+CLAUDE_MD_CONSTANTS_MODULE_NAME = (
+    "hooks_constants.claude_md_orphan_file_blocker_constants"
+)
+ENV_VAR_DRIFT_MODULE_NAME = "blocking.env_var_table_code_drift_blocker"
+ENV_VAR_DRIFT_CONSTANTS_MODULE_NAME = (
+    "hooks_constants.env_var_table_code_drift_constants"
+)
+PACKAGE_INVENTORY_DETECTION_MODULE_NAME = (
+    "blocking.package_inventory_stale_blocker_parts.inventory_detection"
+)
+PACKAGE_INVENTORY_CONSTANTS_MODULE_NAME = (
+    "hooks_constants.package_inventory_stale_blocker_constants"
+)
+PYTEST_TESTPATHS_MODULE_NAME = "blocking.pytest_testpaths_orphan_blocker"
+PII_SCANNER_MODULE_NAME = "blocking.pii_scanner"
+REPOSITORY_EXEMPTION_MODULE_NAME = (
+    "blocking.pii_prevention_blocker_parts.repository_exemption"
+)
+
+ALL_FAIL_CLOSED_EXCEPTION_TYPES = (
+    AttributeError,
+    ImportError,
+    KeyError,
+    OSError,
+    RuntimeError,
+    SyntaxError,
+    TypeError,
+    UnicodeError,
+    ValueError,
+)
+
+ALL_ARCHIVED_SKILL_DIRECTORY_SEGMENTS = (".agents", "skills-archived")
+ALL_TRACKED_SECRET_EXACT_EXEMPTIONS: frozenset[tuple[str, str, str]] = frozenset(
+    (
+        (
+            "packages/claude-dev-env/.agents/skills-archived/pr-converge/reference/per-tick.md",
+            "email",
+            "3de132cd98be7bf26b6f08e81c31c799a891bc32046b61f0b6fe3671ca2e44b5",
+        ),
+        (
+            "packages/claude-dev-env/.agents/skills/_shared/pr-loop/prompts/pr-consistency-audit.xml",
+            "home-path",
+            "805e3271caeec55a94438e221726e9349e46fa4970592bd03ffd3adac5e0ea8a",
+        ),
+        (
+            "packages/claude-dev-env/.agents/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/path_resolver_constants.py",
+            "home-path",
+            "a4f1f978f88b601288424144a5f5066cdc9154868cf2aaab6e0869a103be72a5",
+        ),
+        (
+            "packages/claude-dev-env/.agents/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/path_resolver_constants.py",
+            "home-path",
+            "665e48f1b198dd2a6526e25700fbcb86566d1f8b47d4475a6cc318b1634a4546",
+        ),
+        (
+            "packages/claude-dev-env/_shared/pr-loop/scripts/_claude_permissions_common.py",
+            "home-path",
+            "9c48917645524d03ea0a4f4d8755aa8f0d59f3108e1aa976202a02e613c1444d",
+        ),
+        (
+            "packages/claude-dev-env/_shared/pr-loop/scripts/_claude_permissions_common.py",
+            "home-path",
+            "07ba214cb23325675bc68e5513c030e968eccf2760cb5917d932ae5da29d5af1",
+        ),
+        (
+            "packages/claude-dev-env/_shared/pr-loop/scripts/_claude_permissions_common.py",
+            "home-path",
+            "d41ce8d0f21de2d5320bdd8cd4e8693a2f3d6ea59db6df5ea102a7d2be4b2c22",
+        ),
+        (
+            "packages/claude-dev-env/audit-rubrics/prompts/category-n-test-name-scenario-verifier.md",
+            "home-path",
+            "550c7b16a2a04e1d05a8a6b4f5b764b8d4fdef65e9d79d09e5dbb3a15a855812",
+        ),
+        (
+            "packages/claude-dev-env/audit-rubrics/prompts/category-n-test-name-scenario-verifier.md",
+            "home-path",
+            "b8bbdd1a7ebdad16f4e51377a3f21d05dd35992d89e35971b28b05f53245c69d",
+        ),
+        (
+            "packages/claude-dev-env/bin/expand_home_directory_tokens.mjs",
+            "home-path",
+            "10d5571e7126d2018ee7fb06aa29c72a9d503cac79a4e52d6848602ee10e8832",
+        ),
+        (
+            "packages/claude-dev-env/bin/expand_home_directory_tokens.mjs",
+            "home-path",
+            "09f83c224a02c370d3d63de5c330e1a830fc92866330fc7963b5b5fd20ffcb91",
+        ),
+        (
+            "packages/claude-dev-env/hooks/blocking/volatile_path_in_post_blocker.py",
+            "home-path",
+            "ed9203c8078e4c6b832600085f28f24656d679aa8dca82ecc2557afc3df25036",
+        ),
+        (
+            "packages/claude-dev-env/hooks/hooks_constants/hardcoded_user_path_constants.py",
+            "home-path",
+            "0967160658d782c558722232cad7d47dc19267943d4667b41d3eff1e605be2f4",
+        ),
+        (
+            "packages/claude-dev-env/hooks/hooks_constants/hardcoded_user_path_constants.py",
+            "home-path",
+            "a541acfac2e649581bca0cd03e4c3dcf306344915017d9cd6be4ad57a8fd7379",
+        ),
+    )
+)