claude-dev-env 2.4.0 → 2.5.0

package/hooks/validators/test_run_all_validators_pretooluse.py

@@ -8,6 +8,7 @@ when that content violates a validator, rather than grading the whole branch.
 import json
 import subprocess
 import sys
+import tempfile
 from collections import Counter
 from pathlib import Path
 from unittest.mock import patch
@@ -16,12 +17,21 @@ import pytest
 
 from .run_all_validators import (
     ValidatorResult,
+    _escapes_temporary_root,
+    _hooks_subprocess_working_directory_and_environment,
     _scope_new_and_preexisting,
+    _temporary_path_preserving_directory_signal,
     _violation_line_number,
     main,
     run_validators_entrypoint_subprocess,
 )
 
+CONFIG_DIR_TARGET_PATH = (
+    "CDP Automations/os_update_workflow/config/submission_constants.py"
+)
+PARENT_TRAVERSAL_TARGET_PATH = "../../escape_target.py"
+RELATIVE_CONFIG_TARGET_PATH = "config/x.py"
+
 CLEAN_PYTHON_SOURCE = (
     "def add_two_numbers(first_number: int, second_number: int) -> int:\n"
     "    return first_number + second_number\n"
@@ -85,7 +95,9 @@ class TestPreToolUseGate:
     def test_edit_validates_reconstructed_post_edit_content(
         self, tmp_path: Path
     ) -> None:
-        target_file = tmp_path / "calculate.py"
+        target_directory = tmp_path / "neutral_edit_target"
+        target_directory.mkdir(exist_ok=True)
+        target_file = target_directory / "calculate.py"
         target_file.write_text(CLEAN_PYTHON_SOURCE, encoding="utf-8")
         completed = run_gate(
             {
@@ -107,6 +119,152 @@ class TestPreToolUseGate:
         assert completed.returncode == 0, completed.stderr
         assert "deny" not in completed.stdout
 
+    def test_write_to_config_dir_path_is_not_denied(self) -> None:
+        completed = run_gate(
+            {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": CONFIG_DIR_TARGET_PATH,
+                    "content": VIOLATING_PYTHON_SOURCE,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
+    def test_write_relative_config_path_not_denied_when_cwd_under_system_temp(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        system_temp_root = Path(tempfile.gettempdir()).resolve()
+        monkeypatch.setenv("TEMP", str(system_temp_root))
+        monkeypatch.setenv("TMP", str(system_temp_root))
+        monkeypatch.setenv("TMPDIR", str(system_temp_root))
+        with tempfile.TemporaryDirectory(
+            dir=str(system_temp_root), prefix="gate_cwd_"
+        ) as temporary_root_string:
+            temporary_cwd = Path(temporary_root_string) / "gate_cwd"
+            temporary_cwd.mkdir()
+
+            def working_directory_under_system_temp() -> tuple[str, dict[str, str]]:
+                _working_directory, environment = (
+                    _hooks_subprocess_working_directory_and_environment()
+                )
+                return str(temporary_cwd), environment
+
+            with patch(
+                "validators.run_all_validators._hooks_subprocess_working_directory_and_environment",
+                side_effect=working_directory_under_system_temp,
+            ):
+                completed = run_gate(
+                    {
+                        "tool_name": "Write",
+                        "tool_input": {
+                            "file_path": RELATIVE_CONFIG_TARGET_PATH,
+                            "content": VIOLATING_PYTHON_SOURCE,
+                        },
+                    }
+                )
+        assert completed.returncode == 0, completed.stderr
+        assert "deny" not in completed.stdout
+
+    def test_write_to_parent_traversal_path_still_validates(self) -> None:
+        completed = run_gate(
+            {
+                "tool_name": "Write",
+                "tool_input": {
+                    "file_path": PARENT_TRAVERSAL_TARGET_PATH,
+                    "content": VIOLATING_PYTHON_SOURCE,
+                },
+            }
+        )
+        assert completed.returncode == 0, completed.stderr
+        assert '"permissionDecision": "deny"' in completed.stdout
+        assert "Magic Values" in completed.stdout
+
+
+class TestTemporaryPathPreservingDirectorySignal:
+    def test_strips_parent_traversal_segments(self, tmp_path: Path) -> None:
+        assert _escapes_temporary_root("..") is True
+        staged_path = _temporary_path_preserving_directory_signal(
+            tmp_path, PARENT_TRAVERSAL_TARGET_PATH
+        )
+        assert staged_path == tmp_path / "escape_target.py"
+        assert staged_path.resolve().is_relative_to(tmp_path.resolve())
+
+    def test_keeps_config_directory_segment(self, tmp_path: Path) -> None:
+        staged_path = _temporary_path_preserving_directory_signal(
+            tmp_path, CONFIG_DIR_TARGET_PATH
+        )
+        assert staged_path.name == "submission_constants.py"
+        assert "config" in staged_path.parts
+        assert staged_path == tmp_path / "config" / "submission_constants.py"
+
+    def test_drops_leading_anchor(self, tmp_path: Path) -> None:
+        absolute_target = tmp_path / "config" / "submission_constants.py"
+        staging_root = tmp_path / "staging_root"
+        staging_root.mkdir()
+        staged_path = _temporary_path_preserving_directory_signal(
+            staging_root, str(absolute_target)
+        )
+        relative_parts = staged_path.relative_to(staging_root).parts
+        assert relative_parts == ("config", "submission_constants.py")
+        assert absolute_target.anchor not in relative_parts
+        assert staged_path.resolve().is_relative_to(staging_root.resolve())
+
+    def test_path_without_exemption_directory_stages_flat_basename(
+        self, tmp_path: Path
+    ) -> None:
+        pytest_shaped_target = (
+            tmp_path / "test_edit_introducing_new_viol0" / "legacy_module.py"
+        )
+        pytest_shaped_target.parent.mkdir(parents=True, exist_ok=True)
+        pytest_shaped_target.write_text(CLEAN_MARKER_FUNCTION, encoding="utf-8")
+        staging_root = tmp_path / "staging_root"
+        staging_root.mkdir()
+        staged_path = _temporary_path_preserving_directory_signal(
+            staging_root, str(pytest_shaped_target)
+        )
+        assert staged_path == staging_root / "legacy_module.py"
+
+    def test_relative_config_path_preserves_config_under_system_temp_cwd(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        system_temp_root = Path(tempfile.gettempdir()).resolve()
+        monkeypatch.setenv("TEMP", str(system_temp_root))
+        monkeypatch.setenv("TMP", str(system_temp_root))
+        monkeypatch.setenv("TMPDIR", str(system_temp_root))
+        with tempfile.TemporaryDirectory(
+            dir=str(system_temp_root), prefix="staging_cwd_"
+        ) as temporary_root_string:
+            temporary_root = Path(temporary_root_string)
+            previous_cwd = Path.cwd()
+            try:
+                monkeypatch.chdir(temporary_root)
+                staging_root = temporary_root / "staging_root"
+                staging_root.mkdir()
+                staged_path = _temporary_path_preserving_directory_signal(
+                    staging_root, RELATIVE_CONFIG_TARGET_PATH
+                )
+                assert staged_path == staging_root / "config" / "x.py"
+                assert "config" in staged_path.parts
+                assert staged_path.name == "x.py"
+            finally:
+                monkeypatch.chdir(previous_cwd)
+
+    def test_escapes_temporary_root_rejects_absolute_and_parent_parts(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        sandbox_temp_root = tmp_path / "system_temp"
+        sandbox_temp_root.mkdir()
+        monkeypatch.setenv("TEMP", str(sandbox_temp_root))
+        monkeypatch.setenv("TMP", str(sandbox_temp_root))
+        monkeypatch.setenv("TMPDIR", str(sandbox_temp_root))
+        assert _escapes_temporary_root("..") is True
+        assert _escapes_temporary_root("scripts") is False
+        assert _escapes_temporary_root("config") is False
+        absolute_part = str(Path(tempfile.gettempdir()).resolve().anchor) or "/"
+        assert _escapes_temporary_root(absolute_part) is True
+
 
 class TestCliModeRegression:
     def test_cli_mode_reports_violations_and_exits_one(

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "2.4.0",
+    "version": "2.5.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -21,7 +21,15 @@
         "scripts/",
         "_shared/",
         "audit-rubrics/",
-        "CLAUDE.md"
+        "CLAUDE.md",
+        "!**/__pycache__/**",
+        "!**/*.py[cod]",
+        "!**/.pytest_cache/**",
+        "!**/.mypy_cache/**",
+        "!**/.ruff_cache/**",
+        "!**/*.log",
+        "!**/debug-*.log",
+        "!**/*.egg-info/**"
     ],
     "keywords": [
         "claude-code",

package/rules/CLAUDE.md

@@ -51,6 +51,7 @@ Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. A rule withou
 | `right-sized-engineering.md` | Simple over clever; functions over classes; concrete over abstract |
 | `self-contained-docs.md` | Every document is fully self-contained; no references to the conversation that produced it |
 | `shell-invocation-policy.md` | All Windows shell commands use `pwsh`; `Audit-ShellPolicy.ps1` reports the non-`pwsh` forms in the `settings.json` permission rules and `Migrate-ShellPolicy.ps1` rewrites them to `pwsh`, both run on demand, not as a live gate |
+| `state-what-is.md` | Assert claims, decisions, and actions directly; replace exclusion (naming what a claim is not) and elimination (walking rejected candidates) with the claim or answer itself |
 | `tdd.md` | Test-driven development: red → green → refactor, no production code before a failing test |
 | `testing.md` | Test quality and infrastructure standards |
 | `vault-context.md` | Search Obsidian vault for prior sessions and decisions before substantive project work |

package/rules/docstring-prose-matches-implementation.md

@@ -1,44 +1,45 @@
----
-paths:
-  - "**/*.py"
-  - "**/*.md"
----
-
-# Docstring Prose Matches Implementation
-
-**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps. It applies equally to a skill's companion `SKILL.md` (or any sibling `.md`) that describes a producer the skill's `scripts/` carry out: a doc sentence that claims a produced artifact's ordering or content is the prose this rule governs, and it tracks the producer function's own docstring and body.
-
-## Rule
-
-When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
-
-When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
-
-## Write-time checks
-
-Read the body and the docstring side by side. Apply each check that matches the prose:
-
-- **Unions / match sources** — every member of a "what counts" union appears in the prose.
-- **Suppressors / skip lists** — every early-return suppressor appears in the prose.
-- **Step order** — named order matches call order; branch-guarded corrective steps are named too.
-- **Shared fallbacks** — every condition that reaches a fallback call is named.
-- **Predicate breadth** — the body accepts only the inputs the prose names.
-- **Exclusion axis** — an exclusion clause keys on the same axis the body classifies on.
-- **Companion docs** — a `SKILL.md` (or sibling) order/content claim matches the producer body.
-- **Returns / Raises / Note claims** — each free-form claim matches the body.
-
-Many deterministic shapes of this drift have Write/Edit gates in `packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py` (and the JS/`.mjs` slices in `code_rules_imports_logging.py`). Free-form rest is judgment.
-
-## Full standard
-
-The full Category O judgment standard — sub-buckets O1–O9, the complete write-time gate inventory, free-form checklists, and worked examples — lives in:
-
-`packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`
-
-## Division of labor
-
-| Surface | Role |
-|---|---|
-| **This rule** | Always-on write-time policy and the compact checklist above. |
-| Category O rubric | Single thick source for the full standard (on demand). |
-| Category O prompt | Audit template; points at the rubric for judgment. |
+---
+paths:
+  - "**/*.py"
+  - "**/*.md"
+---
+
+# Docstring Prose Matches Implementation
+
+**When this applies:** Any Write or Edit to a public function, method, class, or module whose docstring prose makes an enumerable claim about behavior — a list of inputs the code handles, the conditions it treats as a match, the cases it skips, or the order of its steps. It applies equally to a skill's companion `SKILL.md` (or any sibling `.md`) that describes a producer the skill's `scripts/` carry out: a doc sentence that claims a produced artifact's ordering or content is the prose this rule governs, and it tracks the producer function's own docstring and body.
+
+## Rule
+
+When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
+
+When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
+
+## Write-time checks
+
+Read the body and the docstring side by side. Apply each check that matches the prose:
+
+- **Unions / match sources** — every member of a "what counts" union appears in the prose.
+- **Suppressors / skip lists** — every early-return suppressor appears in the prose.
+- **Step order** — named order matches call order; branch-guarded corrective steps are named too.
+- **Shared fallbacks** — every condition that reaches a fallback call is named.
+- **Predicate breadth** — the body accepts only the inputs the prose names.
+- **Exclusion axis** — an exclusion clause keys on the same axis the body classifies on.
+- **Companion docs** — a `SKILL.md` (or sibling) order/content claim matches the producer body.
+- **Gate-outcome status flags** — an outcome routed to a blocker (`blocker = ...; break`) reads as blocked everywhere, never as a bypass.
+- **Returns / Raises / Note claims** — each free-form claim matches the body.
+
+Many deterministic shapes of this drift have Write/Edit gates in `packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py` (and the JS/`.mjs` slices in `code_rules_imports_logging.py`). Free-form rest is judgment.
+
+## Full standard
+
+The full Category O judgment standard — sub-buckets O1–O9, the complete write-time gate inventory, free-form checklists, and worked examples — lives in:
+
+`packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`
+
+## Division of labor
+
+| Surface | Role |
+|---|---|
+| **This rule** | Always-on write-time policy and the compact checklist above. |
+| Category O rubric | Single thick source for the full standard (on demand). |
+| Category O prompt | Audit template; points at the rubric for judgment. |

package/rules/state-what-is.md

@@ -0,0 +1,25 @@
+---
+paths:
+  - "**/*.md"
+  - "**/*.py"
+  - "**/*.mjs"
+  - "**/*.js"
+  - "**/*.ts"
+  - "**/*.ps1"
+  - "**/*.sh"
+---
+
+# State What Is
+
+Write settled facts, decisions, and actions that are load-bearing for the reader now. Assert each claim, decision, or action directly, and let it stand on its own evidence.
+
+A detail earns its place by mattering now, or by being timeless enough to matter for future work or plans. Omit everything else as noise.
+
+## Two patterns to replace on sight
+
+- **Exclusion** — establishing a claim by naming what it is not, or by listing what is out of bounds. Replace it with the claim itself.
+- **Elimination** — walking rejected candidates (causes, options, paths, explanations) to reach the answer. Replace it with the answer and the evidence that supports it.
+
+## Sibling rules
+
+This rule sits beside the other prose-quality rules in this directory: [`no-historical-clutter.md`](no-historical-clutter.md) cuts references to old state, [`self-contained-docs.md`](self-contained-docs.md) cuts references to the conversation that produced a doc, [`no-justification-noise.md`](no-justification-noise.md) cuts sentences that only justify a stated choice, and [`plain-language.md`](plain-language.md) swaps heavy words for everyday ones. This rule governs how a claim gets established — directly, not by elimination or exclusion.

package/rules/verified-commit-gate-skip.md

@@ -17,7 +17,7 @@ That situation arises when the verdict fails to cover the current surface even t
 
 ## When the marker is not allowed
 
-Every other case runs the verification: spawn the `code-verifier` agent and let the SubagentStop hook mint the verdict. In particular, never use the marker to:
+Every other case runs the verification: spawn the `code-verifier` agent — `model: sonnet`, worker-model routing per [`skills/orchestrator/SKILL.md`](../skills/orchestrator/SKILL.md#workflow-agent-routing); resolver-supplied sonnet-equivalent on third-party hosts — and let the SubagentStop hook mint the verdict. In particular, never use the marker to:
 
 - Skip a branch's first verification.
 - Commit or push after any real code change since the last clean verdict — one changed line means a fresh verification.

package/scripts/CLAUDE.md

@@ -27,6 +27,7 @@ Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each s
 | `check.ps1` | Runs the full code-quality check suite |
 | `Show-Asset.ps1` | Opens files on screen, sizing each image window to the image's pixel dimensions (scaled to fit the screen); non-image files open in their default application |
 | `Get-SessionAccount.ps1` | Reports which Claude account the current session is actually logged into by comparing `~/.claude.json`'s CLI login against a `CLAUDE_USER_DATA_DIR` desktop profile's `lastKnownAccountUuid`, recovering the desktop account's email from profile storage when the two accounts differ |
+| `Capture-PoolHealth.ps1` | Captures Windows memory pool counters, high-handle processes, and kernel pool tags (via `NtQuerySystemInformation` class 22), prints a threshold verdict with a remediation map, and exits non-zero when any alert threshold fires |
 
 ## Subdirectories