claude-dev-env 8.4.2 → 8.5.0

package/scripts/validate_instruction_pairs.py

@@ -7,10 +7,63 @@ import logging
 import os
 import stat
 import subprocess
+import sys
 from pathlib import Path
 
+from typing import NamedTuple
+
 from subprocess_window_access import hidden_window_creation_flags
 
+_hooks_directory = str(Path(__file__).resolve().parents[1] / "hooks")
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from dev_env_scripts_constants.followup_constants import (
+    FILENAME_RULE_ID,
+    GATE_FAILED_EXIT_CODE,
+    GATE_PASSED_EXIT_CODE,
+    GIT_MODE_RULE_ID,
+    IMPORT_TEXT_RULE_ID,
+    MISSING_AGENTS_RULE_ID,
+    RECORDED_SMELL_TEMPLATE,
+    REGULAR_FILE_RULE_ID,
+    SEVERITY_BY_RULE_ID,
+)
+from followup_ledger import FollowupFinding, record_followup_finding
+from hooks_constants.followup_ledger_constants import SEVERITY_BREAKING
+
+class InstructionFinding(NamedTuple):
+    """One instruction-pair finding and the severity that decides the gate.
+
+    Attributes:
+        rule_id: Stable identifier of the check that raised the finding.
+        file_path: Repository-relative path the finding names.
+        message: The text a reader acts on.
+        severity: The severity SEVERITY_BY_RULE_ID declares for rule_id.
+    """
+
+    rule_id: str
+    file_path: str
+    message: str
+    severity: str
+
+
+def _finding(rule_id: str, relative_path: Path, message: str) -> InstructionFinding:
+    """Build one finding carrying the severity its rule identifier declares.
+
+    Args:
+        rule_id: The check's stable identifier.
+        relative_path: Repository-relative path the finding names.
+        message: The text a reader acts on.
+
+    Returns:
+        The finding with its declared severity attached.
+    """
+    return InstructionFinding(
+        rule_id, relative_path.as_posix(), message, SEVERITY_BY_RULE_ID[rule_id]
+    )
+
+
 git_directory_name = ".git"
 git_listing_commands = (
     (("git", "ls-files", "--stage", "-z"), True),
@@ -97,65 +150,248 @@ def _is_regular_file(each_path: Path) -> bool:
         return False
 
 
-def validate_repository(repository_root: Path) -> list[str]:
-    """Validate instruction filenames, modes, and exact Claude imports.
+def _all_file_check_rows(
+    instruction_path: Path, all_tracked_modes: set[str]
+) -> tuple[tuple[str, bool, str], ...]:
+    """Pair each per-file rule with whether it failed and the text it reports.
 
     Args:
-        repository_root: Repository directory containing the Git metadata.
+        instruction_path: The AGENTS.md or CLAUDE.md to check.
+        all_tracked_modes: Committed Git modes this path carries.
 
     Returns:
-        Human-readable validation errors, with an empty list for a valid tree.
+        One row per per-file rule, each holding its rule identifier, whether
+        the check failed, and its message prefix.
     """
-    repository_root = repository_root.resolve()
-    all_errors: list[str] = []
-    all_git_paths, modes_by_path = _read_git_paths_and_modes(repository_root)
-    all_agents_paths = _discover_named_files(
-        repository_root, all_git_paths, "AGENTS.md"
+    return (
+        (
+            FILENAME_RULE_ID,
+            instruction_path.name not in canonical_instruction_names,
+            "Use the canonical filename",
+        ),
+        (
+            REGULAR_FILE_RULE_ID,
+            not _is_regular_file(instruction_path),
+            "Use a regular file",
+        ),
+        (
+            GIT_MODE_RULE_ID,
+            all_tracked_modes != {regular_git_file_mode},
+            "Commit the instruction file with Git mode 100644",
+        ),
+    )
+
+
+def _instruction_file_findings(
+    instruction_path: Path,
+    repository_root: Path,
+    all_tracked_modes: set[str],
+) -> list[InstructionFinding]:
+    """Check one instruction file's name, kind, and committed Git mode.
+
+    Args:
+        instruction_path: The AGENTS.md or CLAUDE.md to check.
+        repository_root: The resolved repository root.
+        all_tracked_modes: Committed Git modes this path carries.
+
+    Returns:
+        Every finding these three checks raise for this file.
+    """
+    relative_path = instruction_path.relative_to(repository_root)
+    return [
+        _finding(each_rule_id, relative_path, f"{each_text}: {relative_path}")
+        for each_rule_id, each_check_failed, each_text in _all_file_check_rows(
+            instruction_path, all_tracked_modes
+        )
+        if each_check_failed
+    ]
+
+
+def _import_text_finding(
+    claude_path: Path, agents_path: Path, repository_root: Path
+) -> InstructionFinding | None:
+    """Compare one CLAUDE.md against the import text its AGENTS.md requires.
+
+    Args:
+        claude_path: The CLAUDE.md to read.
+        agents_path: The AGENTS.md it must import.
+        repository_root: The resolved repository root.
+
+    Returns:
+        The finding, or None when the import text is exact.
+    """
+    if not _is_regular_file(claude_path):
+        return None
+    if claude_path.read_bytes() == _expected_import_text(claude_path, agents_path):
+        return None
+    relative_claude_path = claude_path.relative_to(repository_root)
+    relative_import_path = _relative_import_path(claude_path, agents_path)
+    relative_agents_path = agents_path.relative_to(repository_root)
+    return _finding(
+        IMPORT_TEXT_RULE_ID,
+        relative_claude_path,
+        f"Make {relative_claude_path} exactly import "
+        f"@{relative_import_path} for {relative_agents_path}",
     )
-    all_claude_paths = _discover_named_files(
-        repository_root, all_git_paths, "CLAUDE.md"
+
+
+def _import_finding(
+    claude_path: Path,
+    repository_root: Path,
+    agents_by_directory: dict[Path, Path],
+) -> InstructionFinding | None:
+    """Check one CLAUDE.md against the AGENTS.md it must import.
+
+    Args:
+        claude_path: The CLAUDE.md to check.
+        repository_root: The resolved repository root.
+        agents_by_directory: Discovered AGENTS.md paths keyed by directory.
+
+    Returns:
+        The finding this file raises, or None when its import text is exact.
+    """
+    agents_path = _find_nearest_agents_path(
+        claude_path, repository_root, agents_by_directory
     )
-    agents_by_directory = {
+    if agents_path is None:
+        relative_claude_path = claude_path.relative_to(repository_root)
+        return _finding(
+            MISSING_AGENTS_RULE_ID,
+            relative_claude_path,
+            f"Add the nearest governing AGENTS.md: {relative_claude_path}",
+        )
+    return _import_text_finding(claude_path, agents_path, repository_root)
+
+
+def _agents_paths_by_directory(all_agents_paths: list[Path]) -> dict[Path, Path]:
+    """Key each discovered AGENTS.md by the directory that holds it.
+
+    Args:
+        all_agents_paths: Every AGENTS.md discovered in the tree.
+
+    Returns:
+        The AGENTS.md path for each directory that holds one.
+    """
+    return {
         each_path.parent: each_path
         for each_path in all_agents_paths
         if each_path.name == "AGENTS.md"
     }
 
-    for each_instruction_path in (*all_agents_paths, *all_claude_paths):
-        relative_path = each_instruction_path.relative_to(repository_root)
-        tracked_modes = modes_by_path.get(each_instruction_path, set())
-        if each_instruction_path.name not in canonical_instruction_names:
-            all_errors.append(f"Use the canonical filename: {relative_path}")
-        if not _is_regular_file(each_instruction_path):
-            all_errors.append(f"Use a regular file: {relative_path}")
-        if tracked_modes != {regular_git_file_mode}:
-            all_errors.append(
-                f"Commit the instruction file with Git mode 100644: {relative_path}"
+
+def _all_file_findings(
+    all_instruction_paths: tuple[Path, ...],
+    repository_root: Path,
+    modes_by_path: dict[Path, set[str]],
+) -> list[InstructionFinding]:
+    """Run the per-file checks over every discovered instruction file.
+
+    Args:
+        all_instruction_paths: Every AGENTS.md and CLAUDE.md discovered.
+        repository_root: The resolved repository root.
+        modes_by_path: Committed Git modes keyed by absolute path.
+
+    Returns:
+        Every per-file finding, in discovery order.
+    """
+    all_findings: list[InstructionFinding] = []
+    for each_instruction_path in all_instruction_paths:
+        all_findings.extend(
+            _instruction_file_findings(
+                each_instruction_path,
+                repository_root,
+                modes_by_path.get(each_instruction_path, set()),
             )
+        )
+    return all_findings
+
+
+def all_instruction_findings(repository_root: Path) -> tuple[InstructionFinding, ...]:
+    """Collect every instruction-pair finding with the severity that decides the gate.
 
+    Args:
+        repository_root: Repository directory containing the Git metadata.
+
+    Returns:
+        Every finding in discovery order, each carrying its rule identifier,
+        the repository-relative path it names, its text, and its severity.
+    """
+    repository_root = repository_root.resolve()
+    all_git_paths, modes_by_path = _read_git_paths_and_modes(repository_root)
+    all_agents_paths = _discover_named_files(repository_root, all_git_paths, "AGENTS.md")
+    all_claude_paths = _discover_named_files(repository_root, all_git_paths, "CLAUDE.md")
+    agents_by_directory = _agents_paths_by_directory(all_agents_paths)
+
+    all_findings = _all_file_findings(
+        (*all_agents_paths, *all_claude_paths), repository_root, modes_by_path
+    )
     for each_claude_path in all_claude_paths:
-        relative_claude_path = each_claude_path.relative_to(repository_root)
-        each_agents_path = _find_nearest_agents_path(
+        each_finding = _import_finding(
             each_claude_path, repository_root, agents_by_directory
         )
-        if each_agents_path is None:
-            all_errors.append(f"Add the nearest governing AGENTS.md: {relative_claude_path}")
-            continue
-        if not _is_regular_file(each_claude_path):
+        if each_finding is not None:
+            all_findings.append(each_finding)
+    return tuple(all_findings)
+
+
+def validate_repository(repository_root: Path) -> list[str]:
+    """Validate instruction filenames, modes, and exact Claude imports.
+
+    Args:
+        repository_root: Repository directory containing the Git metadata.
+
+    Returns:
+        Human-readable validation errors, with an empty list for a valid tree.
+    """
+    return [
+        each_finding.message
+        for each_finding in all_instruction_findings(repository_root)
+    ]
+
+
+def _record_smell(repository_root: Path, finding: InstructionFinding) -> None:
+    """Record one smell finding in the repository's follow-up ledger.
+
+    Args:
+        repository_root: The repository whose ledger receives the finding.
+        finding: The non-breaking finding to record.
+    """
+    record_followup_finding(
+        repository_root,
+        FollowupFinding(finding.rule_id, finding.file_path, finding.message),
+    )
+    logger.warning(RECORDED_SMELL_TEMPLATE, finding.message)
+
+
+def run_gate(repository_root: Path) -> int:
+    """Report breaking findings, record smells, and return the gate exit code.
+
+    A breaking finding means the instruction files do not load as written, so
+    the gate fails. A smell is recorded in the repository's follow-up ledger
+    and leaves the gate passing, so a later pull request resolves it.
+
+    Args:
+        repository_root: Repository directory containing the Git metadata.
+
+    Returns:
+        GATE_FAILED_EXIT_CODE when any breaking finding is present, otherwise
+        GATE_PASSED_EXIT_CODE.
+    """
+    resolved_root = repository_root.resolve()
+    all_breaking_messages: list[str] = []
+
+    for each_finding in all_instruction_findings(resolved_root):
+        if each_finding.severity == SEVERITY_BREAKING:
+            all_breaking_messages.append(each_finding.message)
             continue
-        expected_bytes = _expected_import_text(each_claude_path, each_agents_path)
-        actual_bytes = each_claude_path.read_bytes()
-        if actual_bytes != expected_bytes:
-            relative_import_path = _relative_import_path(
-                each_claude_path, each_agents_path
-            )
-            relative_agents_path = each_agents_path.relative_to(repository_root)
-            all_errors.append(
-                f"Make {relative_claude_path} exactly import "
-                f"@{relative_import_path} for {relative_agents_path}"
-            )
+        _record_smell(resolved_root, each_finding)
+
+    for each_message in all_breaking_messages:
+        logger.error("%s", each_message)
 
-    return all_errors
+    if all_breaking_messages:
+        return GATE_FAILED_EXIT_CODE
+    return GATE_PASSED_EXIT_CODE
 
 
 def _parse_arguments() -> argparse.Namespace:
@@ -173,13 +409,7 @@ def _parse_arguments() -> argparse.Namespace:
 
 def _main() -> int:
     parsed_arguments = _parse_arguments()
-    repository_root = parsed_arguments.repository_root.resolve()
-    all_errors = validate_repository(repository_root)
-    if all_errors:
-        for each_error in all_errors:
-            logger.error("%s", each_error)
-        return 1
-    return 0
+    return run_gate(parsed_arguments.repository_root)
 
 
 if __name__ == "__main__":

package/scripts/windows/pstack/pstack-command-shim.ps1

@@ -32,8 +32,15 @@ $scriptsRoot = Split-Path -Parent (Split-Path -Parent $entrypoint)
 $exitCode = 1
 Push-Location $scriptsRoot
 try {
-  & bun $entrypoint @commandArguments
-  $exitCode = $LASTEXITCODE
+  & bun -e 'import { ensureDependenciesInstalled } from "./bootstrap.ts"; ensureDependenciesInstalled();'
+  $bootstrapExitCode = $LASTEXITCODE
+  if ($bootstrapExitCode -ne 0) {
+    Write-Error "The pstack dependencies could not be installed"
+    $exitCode = $bootstrapExitCode
+  } else {
+    & bun $entrypoint @commandArguments
+    $exitCode = $LASTEXITCODE
+  }
 }
 finally {
   Pop-Location

package/scripts/audit-hooks-cli.mjs

@@ -1,59 +0,0 @@
-import { writeFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { auditHooks } from "./audit-hooks.mjs";
-
-function parseArguments(argv) {
-  const options = {
-    catalogPath: null,
-    format: "text",
-    homeDirectory: null,
-    includeInstalled: false,
-    outputPath: null,
-    requireNonblocking: false,
-    repositoryRoot: path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../.."),
-  };
-  for (let offset = 0; offset < argv.length; offset += 1) {
-    const argument = argv[offset];
-    if (argument === "--installed") options.includeInstalled = true;
-    else if (argument === "--catalog") options.catalogPath = argv[++offset];
-    else if (argument === "--format") options.format = argv[++offset];
-    else if (argument === "--home") options.homeDirectory = argv[++offset];
-    else if (argument === "--output") options.outputPath = argv[++offset];
-    else if (argument === "--require-nonblocking") options.requireNonblocking = true;
-    else if (argument === "--repository-root") options.repositoryRoot = argv[++offset];
-    else throw new Error(`unknown argument ${argument}`);
-  }
-  return options;
-}
-
-function renderText(report) {
-  const summary = report.summary;
-  return [
-    `canonical direct: ${summary.directCount}`,
-    `dispatchers: ${summary.dispatcherCount}`,
-    `hosted entries: ${summary.effectiveCount}`,
-    `logical associations: ${summary.logicalAssociationCount}`,
-    `unclassified targets: ${summary.unclassifiedCount}`,
-    `installed Claude direct: ${summary.claudeDirectCount}`,
-    `installed Codex direct: ${summary.codexDirectCount}`,
-    `active native Git hooks: ${summary.gitHookCount}`,
-    `known native Git hooks: ${summary.knownGitHookCount}`,
-    `registration eligibility: ${report.registrationEligibility.status}`,
-    "runtime proof: separate verification required",
-    `findings: ${summary.findingCount}`,
-  ].join("\n");
-}
-
-function main() {
-  const options = parseArguments(process.argv.slice(2));
-  const report = auditHooks(options);
-  const rendered =
-    options.format === "json" ? `${JSON.stringify(report, null, 2)}\n` : `${renderText(report)}\n`;
-  if (options.outputPath) writeFileSync(options.outputPath, rendered, "utf8");
-  else process.stdout.write(rendered);
-  process.exitCode = report.findings.some(({ severity }) => severity === "error") ? 1 : 0;
-}
-
-main();