claude-dev-env 1.90.0 → 1.92.0

package/hooks/validators/run_all_validators.py

@@ -6,6 +6,7 @@ Exit code 0 = all checks pass, 1 = violations found.
 # pragma: no-tdd-gate
 
 import argparse
+import json
 import os
 import subprocess
 import sys
@@ -27,6 +28,15 @@ VALIDATORS_DIR = Path(__file__).parent
 hooks_dir = VALIDATORS_DIR.parent
 package_name = VALIDATORS_DIR.name
 
+_hooks_directory_on_path = str(hooks_dir.resolve())
+if _hooks_directory_on_path not in sys.path:
+    sys.path.insert(0, _hooks_directory_on_path)
+
+from hooks_constants.multi_edit_reconstruction import (  # noqa: E402
+    apply_edits,
+    edits_for_tool,
+)
+
 
 def _windows_non_unc_working_directory_string(
     candidate_directory_strings: list[str | None],
@@ -99,8 +109,19 @@ def invoke_validator_module(module_stem: str, forwarded_file_paths: List[str]) -
 
 def run_validators_entrypoint_subprocess(
     extra_arguments: List[str],
+    stdin_text: Optional[str] = None,
 ) -> subprocess.CompletedProcess[str]:
-    """Run ``python -m validators.run_all_validators`` with a Windows-safe cwd."""
+    """Run ``python -m validators.run_all_validators`` with a Windows-safe cwd.
+
+    Args:
+        extra_arguments: Argument vector appended after the module name.
+        stdin_text: Text replayed as the subprocess stdin, or None to leave
+            stdin empty. The PreToolUse gate mode reads its payload from stdin,
+            so a caller exercising ``--pre-tool-use`` passes the payload here.
+
+    Returns:
+        The completed subprocess carrying its captured stdout and stderr.
+    """
     working_directory_string, environment = (
         _hooks_subprocess_working_directory_and_environment()
     )
@@ -111,6 +132,7 @@ def run_validators_entrypoint_subprocess(
         text=True,
         cwd=working_directory_string,
         env=environment,
+        input=stdin_text,
     )
 
 
@@ -375,9 +397,9 @@ def run_comment_checks(files: List[Path]) -> ValidatorResult:
     """Comment preservation is enforced by code_rules_enforcer hook.
 
     The hook compares old vs new content to block NEW comments and
-    block DELETION of existing comments. This standalone validator
-    is disabled because it flags ALL comments in existing files,
-    which forces agents to remove them to pass validation.
+    print a stderr advisory when an existing comment is removed. This
+    standalone validator is disabled because it flags ALL comments in
+    existing files, which forces agents to remove them to pass validation.
     """
     return ValidatorResult(
         name="No Comments",
@@ -658,6 +680,188 @@ def get_changed_files() -> List[Path]:
     return [Path(f) for f in files if f]
 
 
+def _read_target_file_content(file_path: str) -> Optional[str]:
+    """Return the on-disk content of *file_path*, or None when it cannot be read."""
+    try:
+        with open(file_path, "r", encoding="utf-8") as readable_file:
+            return readable_file.read()
+    except (FileNotFoundError, OSError, UnicodeDecodeError):
+        return None
+
+
+def reconstruct_proposed_content(
+    tool_name: str, tool_input: Dict[str, object]
+) -> Optional[str]:
+    """Return the post-edit content one Write, Edit, or MultiEdit payload leaves on disk.
+
+    ::
+
+        Write     -> tool_input["content"] verbatim
+        Edit      -> existing file, each old_string rewritten to new_string
+        MultiEdit -> existing file, each edit applied in order
+
+    The Edit and MultiEdit reconstruction reuses the shared applier so this gate
+    judges the same post-edit content the standalone blockers judge.
+
+    Args:
+        tool_name: The intercepted tool — Write, Edit, or MultiEdit.
+        tool_input: The tool's input payload.
+
+    Returns:
+        The proposed post-edit content, or None when the payload carries no
+        readable target for an edit or no string content for a write.
+    """
+    if tool_name == "Write":
+        written_content = tool_input.get("content", "")
+        return written_content if isinstance(written_content, str) else None
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not file_path:
+        return None
+    existing_content = _read_target_file_content(file_path)
+    if existing_content is None:
+        return None
+    return apply_edits(existing_content, edits_for_tool(tool_name, dict(tool_input)))
+
+
+def run_file_scoped_validators(all_files: List[Path]) -> List[ValidatorResult]:
+    """Run every validator scoped to individual files against *all_files*.
+
+    Excludes the branch-scoped File Structure and Git validators, which grade
+    the whole project rather than a single proposed file.
+
+    Args:
+        all_files: The files under validation — a single reconstructed file in
+            gate mode.
+
+    Returns:
+        One ValidatorResult per file-scoped validator, in run order.
+    """
+    return [
+        run_python_style_checks(all_files),
+        run_test_safety_checks(all_files),
+        run_react_checks(all_files),
+        run_ruff_checks(all_files),
+        run_mypy_checks(all_files),
+        run_abbreviation_checks(all_files),
+        run_pr_reference_checks(all_files),
+        run_magic_value_checks(all_files),
+        run_useless_test_checks(all_files),
+        run_security_checks(all_files),
+        run_code_quality_checks(all_files),
+        run_python_antipattern_checks(all_files),
+        run_todo_checks(all_files),
+        run_type_safety_checks(all_files),
+    ]
+
+
+def validate_proposed_file(
+    file_path: str, proposed_content: str
+) -> List[ValidatorResult]:
+    """Validate *proposed_content* as if written to *file_path*.
+
+    Writes the content to a temporary file that carries the target's basename so
+    suffix-based and test-name-based validator filtering matches the real path,
+    then runs the file-scoped validators against it.
+
+    Args:
+        file_path: The destination path the write or edit targets.
+        proposed_content: The reconstructed post-edit content of that file.
+
+    Returns:
+        One ValidatorResult per file-scoped validator.
+    """
+    base_name = Path(file_path).name
+    with tempfile.TemporaryDirectory() as temporary_directory:
+        temporary_file = Path(temporary_directory) / base_name
+        temporary_file.write_text(proposed_content, encoding="utf-8")
+        return run_file_scoped_validators([temporary_file])
+
+
+def _proposed_content_deny_reason(failed_results: List[ValidatorResult]) -> str:
+    """Compose the deny reason naming each failing validator and its output.
+
+    Args:
+        failed_results: The validator results that did not pass.
+
+    Returns:
+        The composed ``permissionDecisionReason`` text.
+    """
+    violation_summaries = [
+        f"{each_result.name} (checks {each_result.checks}): {each_result.output.strip()}"
+        for each_result in failed_results
+    ]
+    deny_reason_item_separator = " | "
+    joined_summaries = deny_reason_item_separator.join(violation_summaries)
+    return (
+        f"BLOCKED: [validators] {len(failed_results)} "
+        f"validator(s) failed: {joined_summaries}"
+    )
+
+
+def _emit_pre_tool_use_deny(deny_reason: str) -> None:
+    """Write one PreToolUse deny JSON payload carrying *deny_reason* to stdout."""
+    deny_payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": deny_reason,
+        }
+    }
+    sys.stdout.write(json.dumps(deny_payload) + "\n")
+    sys.stdout.flush()
+
+
+def _evaluate_pre_tool_use_payload() -> None:
+    """Read the PreToolUse payload from stdin and deny a violating file write.
+
+    Reconstructs the proposed post-edit content of the one target file and runs
+    the file-scoped validators against it. Emits a deny decision naming each
+    failing validator when any fires; writes nothing for a clean file, an
+    unparseable payload, or a payload no validator covers.
+    """
+    pre_tool_use_payload = json.load(sys.stdin)
+    if not isinstance(pre_tool_use_payload, dict):
+        return
+    tool_name = pre_tool_use_payload.get("tool_name", "")
+    tool_input = pre_tool_use_payload.get("tool_input", {})
+    if not isinstance(tool_name, str) or not isinstance(tool_input, dict):
+        return
+    file_path = tool_input.get("file_path", "")
+    if not isinstance(file_path, str) or not file_path:
+        return
+    proposed_content = reconstruct_proposed_content(tool_name, tool_input)
+    if not proposed_content:
+        return
+    all_results = validate_proposed_file(file_path, proposed_content)
+    failed_results = [
+        each_result
+        for each_result in all_results
+        if not each_result.passed and not each_result.skipped
+    ]
+    if failed_results:
+        _emit_pre_tool_use_deny(_proposed_content_deny_reason(failed_results))
+
+
+def run_pre_tool_use_gate() -> int:
+    """Run the PreToolUse gate, never crashing the tool call on an internal error.
+
+    A hook that raises is rendered by the harness as a tool malfunction, so an
+    unexpected failure here logs to stderr and returns 0 rather than propagating.
+
+    Returns:
+        Always 0 — the gate signals a block through the deny payload, not an
+        exit code.
+    """
+    try:
+        _evaluate_pre_tool_use_payload()
+    except json.JSONDecodeError:
+        return 0
+    except Exception as error:
+        sys.stderr.write(f"[run_all_validators] pre-tool-use gate error: {error}\n")
+        sys.stderr.flush()
+    return 0
+
+
 def main() -> int:
     """Run all validators and report results."""
     parser = argparse.ArgumentParser(description="Run pre-push validators")
@@ -687,8 +891,16 @@ def main() -> int:
         default=2,
         help="Lines of context around violations",
     )
+    parser.add_argument(
+        "--pre-tool-use",
+        action="store_true",
+        help="Run as a PreToolUse gate on the single proposed file write from stdin",
+    )
     args = parser.parse_args()
 
+    if args.pre_tool_use:
+        return run_pre_tool_use_gate()
+
     if args.health:
         health = get_system_health()
         print_health_report(health)

package/hooks/validators/test_run_all_validators_pretooluse.py

@@ -0,0 +1,102 @@
+"""Behavioral tests for the run_all_validators PreToolUse gate mode.
+
+The gate mode validates the proposed post-edit content of the single file a
+Write, Edit, or MultiEdit would produce and emits a PreToolUse deny decision
+when that content violates a validator, rather than grading the whole branch.
+"""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+from .run_all_validators import main, run_validators_entrypoint_subprocess
+
+CLEAN_PYTHON_SOURCE = (
+    "def add_two_numbers(first_number: int, second_number: int) -> int:\n"
+    "    return first_number + second_number\n"
+)
+VIOLATING_PYTHON_SOURCE = (
+    "def calculate_total_price(unit_price: int, quantity: int) -> int:\n"
+    "    return unit_price * quantity * 199 * 42\n"
+)
+
+
+def run_gate(payload: dict[str, object]) -> "subprocess.CompletedProcess[str]":
+    return run_validators_entrypoint_subprocess(["--pre-tool-use"], stdin_text=json.dumps(payload))
+
+
+class TestPreToolUseGate:
+    def test_write_with_violating_content_denies(self) -> None:
+        completed = run_gate(
+            {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": "calculate.py",
+                    "content": VIOLATING_PYTHON_SOURCE,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "Magic Values" in completed.stdout
+
+    def test_write_with_clean_content_allows(self) -> None:
+        completed = run_gate(
+            {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": "add.py",
+                    "content": CLEAN_PYTHON_SOURCE,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
+    def test_edit_validates_reconstructed_post_edit_content(self, tmp_path: Path) -> None:
+        target_file = tmp_path / "calculate.py"
+        target_file.write_text(CLEAN_PYTHON_SOURCE, encoding="utf-8")
+        completed = run_gate(
+            {
+                "tool_name": "Edit",
+                "tool_input": {
+                    "file_path": str(target_file),
+                    "old_string": "    return first_number + second_number\n",
+                    "new_string": "    return first_number + second_number + 199 * 42\n",
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+
+    def test_unparseable_payload_exits_silently(self) -> None:
+        completed = run_validators_entrypoint_subprocess(
+            ["--pre-tool-use"], stdin_text="not json at all"
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
+
+class TestCliModeRegression:
+    def test_cli_mode_reports_violations_and_exits_one(
+        self, tmp_path: Path, capsys: pytest.CaptureFixture[str]
+    ) -> None:
+        violating_file = tmp_path / "calculate.py"
+        violating_file.write_text(VIOLATING_PYTHON_SOURCE, encoding="utf-8")
+        with patch(
+            "validators.run_all_validators.get_changed_files",
+            return_value=[violating_file],
+        ):
+            original_argv = sys.argv
+            try:
+                sys.argv = ["run_all_validators.py"]
+                exit_code = main()
+            finally:
+                sys.argv = original_argv
+        captured = capsys.readouterr()
+        assert exit_code == 1
+        assert "PRE-PUSH VALIDATOR RESULTS" in captured.out

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.90.0",
+    "version": "1.92.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/CLAUDE.md

@@ -25,6 +25,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images |
 | `hook-prose-matches-detector.md` | Hook prose descriptions match what the hook actually detects |
 | `long-horizon-autonomy.md` | Autonomous-run behaviors: act on what you have, do not end on a promise, delegate and keep working |
+| `nas-ssh-invocation.md` | Reach the NAS at `192.168.1.100` through the `System32/OpenSSH` binary with `-o BatchMode=yes`; bare `ssh`/`scp`/`sftp` stalls on an interactive password prompt |
 | `no-cross-skill-duplicate-helpers.md` | No duplicating shared helpers across skills; use `_shared/` |
 | `no-historical-clutter.md` | Documentation describes current state only; no historical or transitional language |
 | `no-inline-destructive-literals.md` | No destructive-command literals in Bash tool command strings, even as data |
@@ -37,6 +38,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code l
 | `plain-illustrative-docstrings.md` | Public docstring narrative reads plainly and shows behavior with a diagram block (a `::` example or a doctest), painting a concrete scene a general developer follows on first read; a run-on backstop hook, a prose-wall backstop hook, and Category O9 audit enforce it |
 | `plain-language.md` | Everyday words, short active sentences, lead with the answer |
 | `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
+| `proof-of-work-pr-comments.md` | Every PR carries one five-part proof-of-work comment before it leaves draft; the `pr_description_enforcer` hook audits proof-shaped comments and gates `gh pr ready` |
 | `re-stage-before-commit.md` | Stage the files edited this session before `git commit`; the session edit stage gate denies a commit that leaves a tracked session edit unstaged, with `-a`, a pathspec, a preceding `git add`, and `# partial-commit` as escapes |
 | `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
 | `right-sized-engineering.md` | Simple over clever; functions over classes; concrete over abstract |

package/rules/nas-ssh-invocation.md

@@ -0,0 +1,21 @@
+# NAS SSH Invocation Policy
+
+**When this applies:** Any `ssh`, `scp`, or `sftp` command against the NAS at `192.168.1.100`.
+
+## Rule
+
+Reach the NAS through the Windows OpenSSH binary with batch mode on. Git Bash's MSYS `ssh` reads `~/.ssh/id_ed25519` as world-readable through its ACL mapping, rejects the key as bad permissions, offers no key, and falls back to an interactive password prompt. In an unattended session no one answers that prompt, so the session hangs. The `System32/OpenSSH` binary authenticates the same key without a prompt.
+
+Use this form for every NAS ssh command:
+
+```
+"/c/Windows/System32/OpenSSH/ssh.exe" -o BatchMode=yes -o ConnectTimeout=10 -p 9222 jon@192.168.1.100 "<cmd>"
+```
+
+`scp` and `sftp` take the matching `System32/OpenSSH` binary, `-o BatchMode=yes`, and port `9222` (`-P` for `scp`).
+
+`-o BatchMode=yes` is required, not optional: it turns a key-authentication failure into a loud non-zero exit rather than a silent password prompt, so an auth regression surfaces as an error you can read.
+
+## Enforcement
+
+`nas_ssh_binary_enforcer.py` (PreToolUse on Bash) denies a bare `ssh`/`scp`/`sftp` command word aimed at `192.168.1.100` and points at the full-binary form. It also denies the full `System32/OpenSSH` binary to that host when the command omits `-o BatchMode=yes`. Commands to any other host, and commands that mention the address without an ssh-family command word, pass.

package/rules/proof-of-work-pr-comments.md

@@ -0,0 +1,26 @@
+# Proof-of-Work PR Comments
+
+**When this applies:** Every pull request. One comment on the PR carries the proof of the work — posted after `gh pr create` or after a material new commit, and always before the PR leaves draft.
+
+## The standard
+
+A proof comment has five parts:
+
+1. **The exact commands run on real data.** A fenced code block showing the command(s) that produced the artifact — not test output alone.
+2. **Measured outcomes.** Numbers read from the produced artifact — counts, dimensions, hashes, byte sizes, rankings — as a table or a bullet list of facts.
+3. **Plan linkage.** One sentence naming the parent issue or phase the PR advances, with the issue reference (for example: "Advances phase 2 of issue #12").
+4. **Visual evidence for values a human cannot read at a glance.** When the change is visual (the diff touches images, HTML, CSS, or hex color values), embed an image: hex colors as inline swatch images (`![](https://placehold.co/20x20/RRGGBB/RRGGBB.png)`), coordinates as marked-up screenshots, size changes as before/after pairs. A wall of raw values fails the standard even when every value is correct.
+5. **Honest gaps.** State plainly what the offline proof cannot show, and what covers that gap.
+
+## Enforcement
+
+The `pr_description_enforcer` hook enforces the standard at two points:
+
+- **On `gh pr comment`:** a comment body whose heading names proof or verification is audited for the five parts. The audit looks for a fenced code block with content, a table row or bullet line carrying a number, a line pairing an issue reference (`#123`) with a linkage word (issue, phase, plan, parent, advances, milestone, part of), an image embed when the PR diff is visual, and a gap phrase (gap, limitation, cannot, does not show, not shown, unverified, not covered). The block message names each missing part.
+- **On `gh pr ready`:** the hook reads the PR's comments and blocks readying while no comment passes the audit. `gh pr ready --undo` returns a PR to draft and is never blocked.
+
+A `gh` failure (network, auth, missing executable) never blocks — the gate fails open on tooling problems, and the comment audit skips bodies it cannot read.
+
+## Why
+
+A PR body says what changed; the proof comment shows that it worked. Real command output, measured numbers, and a rendered image let a reviewer check the claim in seconds, with no need to re-run the work. Stating the gaps keeps the proof honest: the reviewer knows exactly what still rests on trust and where that is covered. Gating draft-to-ready makes the comment land before review starts, on every machine, whatever the session's habits.

package/scripts/CLAUDE.md

@@ -6,6 +6,7 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 
 | File | Purpose |
 |---|---|
+| `claude_chain_runner.py` | Runs a `claude` invocation through a config-driven fallback chain (`~/.claude/claude-chain.json`): the leading binary serves the call, and only a usage-limit failure falls over to the next logged-in binary; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your binaries in fallback order |
 | `gh_artifact_upload.py` | Uploads a file to a repo's durable `artifacts` prerelease under a timestamped asset name and prints the permanent download URL a GitHub post can link |
 | `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
 | `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |

package/scripts/claude-chain.example.json

@@ -0,0 +1,8 @@
+{
+  "chain": [
+    { "command": "claude", "extra_args": [] },
+    { "command": "claude-1", "extra_args": [] },
+    { "command": "claude-2", "extra_args": [] },
+    { "command": "claude-3", "extra_args": [] }
+  ]
+}