claude-dev-env 2.3.0 → 2.5.0

package/hooks/validators/test_run_all_validators_config_discovery.py

@@ -0,0 +1,123 @@
+"""Regression tests: staged validation resolves ruff config from the original path.
+
+The PreToolUse gate stages proposed content to an OS-temp file, so ruff would
+discover its config by walking up from that temp path and never reach
+``packages/claude-dev-env/hooks/pyproject.toml``. Its ``[tool.ruff.lint]`` selects
+B and PL, so a dropped config leaves the staged run less strict than the project.
+
+``validate_proposed_file`` resolves the config from the ORIGINAL target path, so
+the project ruff config applies to the staged copy from any working directory.
+
+::
+
+    original path .../validators/config_probe_module.py, DIRTY_SOURCE (assert False)
+    flag (defect): staged temp copy -> no [tool.ruff] up-tree -> B011 not selected
+    ok  (fixed):   config resolved from original path         -> B011 fires
+
+    original path .../validators/test_config_probe_module.py, same DIRTY_SOURCE
+    ok: the test_*.py per-file-ignore reaches the staged copy -> B011 suppressed
+"""
+
+from pathlib import Path
+
+import pytest
+
+from .run_all_validators import ValidatorResult, get_project_root, validate_proposed_file
+
+VALIDATORS_DIRECTORY = Path(__file__).parent
+NON_TEST_PROBE_PATH = VALIDATORS_DIRECTORY / "config_probe_module.py"
+TEST_PROBE_PATH = VALIDATORS_DIRECTORY / "test_config_probe_module.py"
+
+RUN_ALL_VALIDATORS_PATH = VALIDATORS_DIRECTORY / "run_all_validators.py"
+EXEMPT_PATHS_PATH = VALIDATORS_DIRECTORY / "exempt_paths.py"
+
+DIRTY_SOURCE = (
+    "def probe_condition(observed_total: int) -> None:\n    assert False, observed_total\n"
+)
+
+UNCHECKED_SUBPROCESS_SOURCE = (
+    "import subprocess\n\n\ndef run_listing() -> None:\n    subprocess.run([\"ls\"])\n"
+)
+
+UNUSED_IMPORT_SOURCE = "import os\n"
+
+
+def _ruff_result(all_results: list[ValidatorResult]) -> ValidatorResult:
+    """Return the Ruff validator result from a validate_proposed_file run."""
+    for each_result in all_results:
+        if each_result.name == "Ruff":
+            return each_result
+    raise AssertionError("no Ruff validator result was produced")
+
+
+def _working_directory_for(cwd_kind: str, outside_repo_directory: Path) -> Path:
+    """Resolve the cwd a parametrized case runs from — repo root or outside it."""
+    if cwd_kind == "repo_root":
+        project_root = get_project_root()
+        assert project_root is not None, "repo root must resolve for this test"
+        return project_root
+    return outside_repo_directory
+
+
+@pytest.mark.parametrize("cwd_kind", ["repo_root", "outside_repo"])
+def test_staged_non_test_file_reports_b011_from_every_cwd(
+    cwd_kind: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(_working_directory_for(cwd_kind, tmp_path))
+
+    ruff_result = _ruff_result(validate_proposed_file(str(NON_TEST_PROBE_PATH), DIRTY_SOURCE))
+
+    assert "B011" in ruff_result.output
+
+
+def test_staged_test_file_suppresses_b011_via_per_file_ignore(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(tmp_path)
+
+    non_test_ruff_result = _ruff_result(
+        validate_proposed_file(str(NON_TEST_PROBE_PATH), DIRTY_SOURCE)
+    )
+    test_ruff_result = _ruff_result(validate_proposed_file(str(TEST_PROBE_PATH), DIRTY_SOURCE))
+
+    assert "B011" in non_test_ruff_result.output
+    assert "B011" not in test_ruff_result.output
+
+
+@pytest.mark.parametrize("cwd_kind", ["repo_root", "outside_repo"])
+def test_staged_run_all_validators_suppresses_plw1510_via_path_ignore(
+    cwd_kind: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(_working_directory_for(cwd_kind, tmp_path))
+
+    ruff_result = _ruff_result(
+        validate_proposed_file(str(RUN_ALL_VALIDATORS_PATH), UNCHECKED_SUBPROCESS_SOURCE)
+    )
+
+    assert "PLW1510" not in ruff_result.output
+    assert ruff_result.passed
+
+
+def test_staged_exempt_paths_suppresses_f401_via_path_ignore(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(tmp_path)
+
+    ruff_result = _ruff_result(
+        validate_proposed_file(str(EXEMPT_PATHS_PATH), UNUSED_IMPORT_SOURCE)
+    )
+
+    assert "F401" not in ruff_result.output
+    assert ruff_result.passed
+
+
+def test_staged_non_carved_path_still_reports_plw1510(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.chdir(tmp_path)
+
+    ruff_result = _ruff_result(
+        validate_proposed_file(str(NON_TEST_PROBE_PATH), UNCHECKED_SUBPROCESS_SOURCE)
+    )
+
+    assert "PLW1510" in ruff_result.output

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.3.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,67 +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.
-
-The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Eleven more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_delegation_summary_enumeration_drift` covers a thin delegating wrapper's docstring summary enumerating actions that the same-named function's summary in the named sibling file omits, compared from both save directions. `check_docstring_names_absent_type_checking_gate` covers a module or function docstring that names a `TYPE_CHECKING` gate-detection step, or a `type-checking-gate` helper family, while no identifier in the module's code carries the `type_checking` marker — the drift where the prose points a reader at a gate the body never performs; drop the `TYPE_CHECKING` gate wording, or add the detection the prose describes. `check_docstring_length_constant_superlative_vs_exact_gate` covers a length-constant module whose docstring describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`) while the only code consuming the constant compares `len(...)` against it with `==`/`!=` — an exact-length gate that rejects every other length — and never with an ordered operator; the check scans the constant module's package tree (its own directory, or the parent package when the module sits in a `config/` subdirectory), so the mismatching consumer may sit in a sibling module. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. `check_docstring_no_consumer_claim` covers a producer docstring asserting that no consumer reads its output yet (`producer-only artifact`, `no submission-run consumer reads it yet`) — a transitional claim that drifts the moment a reader lands and contradicts any companion `SKILL.md` that documents the consumer; this is the deterministic slice of the O8 companion-doc producer/consumer drift below. `check_docstring_returns_plural_cardinality` covers a `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) while the returned dict literal holds exactly one key in that family (`sheen_mid`) — the drift where a single-key family carries a plural noun, so the prose claims a cardinality of two or more that the dict does not hold. `check_docstring_args_single_line_scope_vs_span` covers an `Args:` entry whose prose scopes a finding to a single named line (`only when its block-anchor line is among the changed lines`) while the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper — the drift where the Args entry claims a narrower single-line scope than the span-intersection body applies, so an edit touching any non-anchor line of the span still blocks. `check_docstring_cardinal_count_matches_constant_family` covers a docstring that states a cardinal count of an outcome family (`Covers the four outcome branches: ...`) and lists those members, while the module references more members of the same `UPPER_SNAKE` constant family than the count names (`OUTCOME_OFFENDER_UNREADABLE` is imported and exercised, yet the summary stops at four) — the drift where a summary keeps the old count after the code grows another branch; this gate runs on test modules as well as production modules. `check_docstring_raises_unraisable_largezipfile` covers a `Raises:` clause that names `zipfile.LargeZipFile` while the function opens its `zipfile.ZipFile` writer in a write mode (`w`/`a`/`x`) with `allowZip64` left at its default of True — `zipfile` raises `LargeZipFile` only when an entry needs ZIP64 and `allowZip64` is False, so a writer that allows ZIP64 documents an exception the body cannot produce. `check_docstring_no_network_claim_with_metadata_access` covers a function docstring promising a code path returns `without touching the network` (or a sibling no-network phrase) while the body calls a path-metadata method (`is_file`, `is_dir`, `exists`, `stat`, `lstat`) — on a network share each metadata call is a round-trip over the wire, so a cache-hit path the docstring swore avoids the network still pays a stat on every call; reword the claim to state the path is stat-checked on every call, or short-circuit to the cached path before the share is touched. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and the broader module-responsibility paragraph outside the user-facing-text-scope slice the checklist below names — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the twelve gated slices.
-
-## What to check before you write the docstring
-
-Read the body and the docstring side by side:
-
-- **Read-source / match-source unions.** A body that computes `read_names = a | b | c` (or any union of "what counts") names each union member in the prose enumeration. A union member the code applies but the prose omits is a gap.
-- **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
-- **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. When the body routes to the same fallback from two or more early-return guards (`if a is None: fallback(); return` and `if random() < p: fallback(); return`), the prose enumerates both guards. The `check_docstring_fallback_branch_coverage` gate blocks the single-condition form of this drift at Write/Edit time.
-- **Step order.** A docstring that says `A then B then C` matches the call order in the body. A step enumeration that names the body's linear steps also names every corrective step the body guards inside an `if`/`elif` branch (`if not await cancel_and_reinitiate_update(...): return`). The `check_docstring_step_enumeration_dispatch_coverage` gate blocks the branch-guarded-dispatch form of this drift — a step-enumeration docstring that omits a two-or-more-token dispatch step the body guards inside a branch — at Write/Edit time.
-- **Delegation pointer summaries.** A thin delegating method whose docstring names its actions and points at the home of the real body (Apply Russia, review note, publication edits; full doc on `listing_edit_flow`) lists the same actions the delegated function's own summary lists. When an edit moves one action out of the delegated body, the same edit rewords both summaries. The `check_docstring_delegation_summary_enumeration_drift` gate blocks this drift as either side lands: a saved wrapper docstring gets compared against the delegated body beside it, and a saved delegated body gets compared against every neighboring wrapper docstring pointing at it. A conditional bullet in the delegated prose (`re-apply the privacy policy after the upload`) also names every exception the body honors (`unless the reopened button reads Re-register`) — that conditional-completeness slice stays a judgment call for the audit lane.
-- **JS/`.mjs` resume-task enumerations.** A `spawn<Role>Agent` JSDoc that enumerates its sibling `resume<Role>Agent`'s resume tasks in a parenthetical `resume (repair-verify, hardening-verify)` list names every `task === '<name>'` branch the resume body dispatches on. The `check_js_resume_task_enumeration_coverage` gate blocks the JavaScript form of this drift — a spawn JSDoc whose resume enumeration omits a dispatched task — at Write/Edit time. This is the `.mjs` slice of the same Category O6 standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
-- **JS/`.mjs` `@returns` object with a schema-less branch.** A `function` whose JSDoc `@returns {Promise<object>}` promises a structured object names a return type every branch honors. When the body returns one agent-spawn helper both with a `schema` options object and without one, the schema-less branch resolves to a transcript string, not the object the JSDoc claims. The `check_js_returns_object_schemaless_branch` gate blocks this drift — a `Promise<object>` JSDoc whose body returns the same helper with and without a `schema` key — at Write/Edit time. This is the `.mjs` slice of the same Category O6 standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
-- **JS/`.mjs` sibling return-object key drift.** Every return path of a function that yields the same record carries the same keys. When an early return in a workflow body omits exactly one key its sibling tail return carries (`allDeferredPrs`), a caller reading that key off the short path gets undefined where the documented contract and the sibling return both promise it. The `check_js_sibling_return_object_key_drift` gate blocks this drift — a `return { ... }` object literal whose key set misses exactly one key of a sibling return in the same function or module scope, with discriminated-union variants and two-or-more-key exit shapes left alone — at Write/Edit time. This is the `.mjs` slice of the same Category O standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
-- **JS/`.mjs` bare-flag return directive vs a stated full-result contract.** A converge-workflow preamble that states a full result-object contract (`{sha, clean:false, down:true, findings:[]}`) and adds "never a bare down flag" matches any `return <flag>: true`/`false` prose directive elsewhere in the file that repeats a status flag the stated contract rules out. When a step's prose says to "return down: true" once a budget runs out, that directive repeats the bare flag the preamble rules out — a StructuredOutput run whose schema needs every field would reject a lone `{down:true}`. The `check_js_bare_flag_return_directive` gate blocks this drift — a `return <name>: true`/`false` prose directive anywhere in the file that repeats a status flag a stated contract rules out, with no proximity or ordering check between the two — at Write/Edit time. This is the `.mjs` slice of the same Category O6 standard the Python gates carry; the Python AST docstring gates never inspect JavaScript source.
-- **Returns-clause cardinality.** A `Returns:` clause that names a dict-key prefix family with a plural noun (`the sheen stops`) matches the count of keys in that family in the returned dict literal. When the dict holds one key in the family (`sheen_mid`), the noun is singular (`the sheen stop`); a plural noun there claims two or more entries the dict does not hold. The `check_docstring_returns_plural_cardinality` gate blocks the single-key-with-plural-noun form of this drift at Write/Edit time.
-- **Length-constant superlative vs exact gate.** A module docstring that describes an integer `*_LENGTH` constant with a superlative or range word (`the longest color string the swatch accepts`, `no longer than`) matches how the code consumes the constant. When the only consumer compares `len(...)` against the constant with `==`/`!=` — an exact-length gate where every other length is rejected, not accepted at a shorter length — the superlative prose claims a range of accepted lengths the code never allows. State the exact required length (`the exact #AARRGGBB length`), not a longest/range form. The `check_docstring_length_constant_superlative_vs_exact_gate` gate blocks this drift at Write/Edit time, scanning the constant module's package tree so it sees a consumer that lives in a sibling module; a constant genuinely used as a ceiling (`len(x) <= LIMIT`) is left alone.
-- **Args single-line scope vs span body.** An `Args:` entry that scopes a finding to one named line (`a finding blocks only when its block-anchor line is among the changed lines`) matches the line breadth the body scopes by. When the body builds a `range(...)` span over the finding's source lines and scopes it through a span-intersection scoper that blocks when any line of the span is among the changed lines, the single-line Args wording understates the scope: an edit touching a non-anchor line of the span still blocks. State the Args entry on the same span breadth the body uses (`a finding blocks when any line of its block span is among the changed lines`). The `check_docstring_args_single_line_scope_vs_span` gate blocks the single-line-Args-over-span-body form of this drift at Write/Edit time.
-- **Cardinal-count enumerations.** A docstring that states a count of an outcome family (`the four outcome branches`) and lists those members names every member of that family the module references. When the module imports and exercises a fifth `OUTCOME_*` constant the summary leaves out, the count and the list both under-describe the code. The `check_docstring_cardinal_count_matches_constant_family` gate blocks this drift — a cardinal-count docstring that names two or more members of a referenced `UPPER_SNAKE` constant family, leaves at least one referenced member out, and states a count that differs from the family size (a count above it and one below it both trip) — at Write/Edit time, on test modules as well as production modules.
-- **Raises-clause reachability for `LargeZipFile`.** A `Raises:` clause that names `zipfile.LargeZipFile` matches a writer the body opens with ZIP64 forbidden. `zipfile` raises `LargeZipFile` only when an entry needs ZIP64 and `allowZip64` is False; a function that opens its `zipfile.ZipFile` writer in a write mode (`w`/`a`/`x`) with `allowZip64` at its default of True allows ZIP64 and never raises it, so the clause documents an unreachable exception. Drop the entry, or pass `allowZip64=False` when forbidding ZIP64 is the goal. The `check_docstring_raises_unraisable_largezipfile` gate blocks the default-ZIP64-writer form of this drift at Write/Edit time; a writer that forbids ZIP64 on any open, a read-only open, and a function that opens no writer are all left alone.
-- **Module summary scope versus data-schema constants.** A module whose one-line docstring scopes its contents to user-facing text (`User-facing strings: CLI flag names, help text, and log messages`) names every category of constant the body holds. When the body also defines serialization field keys (`JSONL_FIELD_*`), run-metadata schema keys (`RUN_METADATA_CLI_ARG_KEY_*`), or runtime config (`STDOUT_ENCODING`, `MAIN_LOGGING_FORMAT_STRING`), the strings-only summary under-describes the module — the module-responsibility drift the repo flags. Broaden the summary to name the data-schema keys and runtime config. The `check_module_docstring_scope_omits_data_schema_constants` gate blocks this drift at Write/Edit time, and fires only when the summary claims a user-facing-text scope and names no data-schema or runtime-config category, so a summary that already names `field keys`, `schema`, or `runtime config` passes.
-- **Field meaning: run mode versus per record.** A dataclass or `TypedDict` field documented in the class `Attributes:` block states what the field means for one record. When the code sets that field the same way for every record (a run-mode flag such as `is_dry_run = not is_execute` at each write site), the description states the run-mode meaning, not a per-record outcome. A field named `is_dry_run` documented as `True when no STP was written` reads as a per-record write result, but the value tracks the run mode, so a record that writes no file during an execute run still stores `False`. State the run-mode meaning the assignment gives the field. The `check_docstring_field_runmode_outcome` gate blocks the single-file shape of this drift at Write/Edit time — an `Attributes:` entry for a run-mode flag field (a name carrying `dry_run`) whose description carries a per-record write-outcome phrase and no run-mode phrase. The assignment that sets the field sits in another module, out of reach of that single-file gate, so any shape the gate cannot key on stays an O6 audit-lane judgment finding.
-- **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
-- **Exclusion-clause distinguisher.** A docstring sentence that says a named category of input "are not" / "is not" the thing the function flags (`plain logging, screenshot, or method-on-local calls inside a branch are not dispatch steps`) keys the exclusion to the same axis the body's classification keys on. When the body decides on one axis (a call sits in an `If.test` guard versus a plain statement) but the prose excludes on a different axis (the call's receiver shape — a method on a local), the exclusion clause names a category the body still flags: a guarded method-on-local call is flagged even though the prose lists method-on-local calls as excluded. Read the body's actual branch condition, then state the exclusion on that same axis (`plain (unguarded) calls inside a branch body are not dispatch steps`), so every member the prose excludes is a member the body also excludes.
-- **Companion-doc ordering and content claims.** A `SKILL.md` (or sibling `.md`) sentence that names a produced artifact and claims its order (`sorted`, `alphabetical`, `in sorted order`) or its content (`the at-risk names`, `just the current set`) matches the producer function's docstring and body for that same artifact. A producer that builds the artifact by merging stored names with new names and appending — preserving file order, not re-sorting the union — leaves a doc that still says `sorted` drifted on both counts: the order claim is wrong, and the content claim hides the merged-in prior entries. When the producer's ordering or union changes, the same change updates the companion doc. The two move together in one commit, even when the producer edit does not touch the `.md` file.
-- **TYPE_CHECKING gate claim vs code.** A docstring that names a `TYPE_CHECKING` gate-detection step, or a `type-checking-gate` helper family, matches a module whose code handles TYPE_CHECKING. When no identifier in the body carries the `type_checking` marker — no `TYPE_CHECKING` load, import alias, attribute, or helper name — the prose points a reader at a gate the module never performs. State what the module does, or add the detection the prose describes. The `check_docstring_names_absent_type_checking_gate` gate blocks this drift at Write/Edit time, and covers hook infrastructure, where the import-scan gates that carry this drift class live.
-
-When the body changes the set of behaviors it applies, the same edit updates the prose enumeration. The two move together in one commit.
-
-## Worked example
-
-A `@dataclass` dead-field check builds its set of "field counts as read" sources by union:
-
-```python
-read_names = (
-    attribute_read_names
-    | dynamic_literal_names
-    | _match_pattern_attribute_names(tree)
-    | _exported_names(tree)
-)
-```
-
-A docstring that enumerates "attribute read, augmented-assignment target, class-pattern keyword, literal `getattr`/`attrgetter`" but omits the `__all__` source (`_exported_names`) is drifted: a field whose name appears in `__all__` is treated as read, and the prose hides that. The fix adds the missing source to the enumeration so the list matches the union.
-
-## Enforcement (audit lane)
-
-This drift class is sub-bucket **O6** in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` (free-form `Note:` / `Returns:` / responsibility-list claims). The audit teammate lists every prose enumeration in a changed docstring and verifies each item against the body, and lists every union member / suppressor / step in the body and verifies each appears in the prose. A union member or suppressor in the body that the prose omits is an O6 finding. The single-condition shared-fallback shape of this drift is gated deterministically by `check_docstring_fallback_branch_coverage` (`packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`); the audit lane covers every O6 shape the gate cannot match.
-
-When a changed PR touches a producer function whose ordering or union shifts, the O8 audit lane also reads that skill's companion `SKILL.md` and sibling `.md` docs for any sentence naming the same produced artifact. A doc sentence that claims the artifact is `sorted` or holds `just the at-risk names` while the producer merges prior names and appends without re-sorting is an O8 finding, even when the PR diff never touched the `.md` file — the behavior change orphaned the doc claim.
-
-## Why
-
-A docstring enumeration earns its place by being trustworthy. A complete list lets a reader reason about the function without scanning the body; a list missing one item is worse than no list, because it asserts completeness it does not have. Naming this standard makes the gap a first-class finding at write time and at audit, rather than a surprise a reader hits months later.
+---
+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/durable-post-artifacts.md

@@ -26,6 +26,13 @@ Handle the two kinds of content differently:
 
 Both slash directions count.
 
+The worktree and job-scratch entries count as a path when either:
+
+- A `/` or `\` sits right before them — a drive-letter path (`C:\Users\me\.claude\worktrees\wt\f.py`), a home path (`~/.claude/worktrees/wt`), or a POSIX absolute path (`/home/me/.claude-editor/jobs/j/log.txt`).
+- A path segment follows them — a relative path that names a child under that directory (`see .claude/worktrees/wt-1/notes.md`, a markdown link target, or `cd .claude/worktrees/wt-199`).
+
+With neither anchor the text names the directory rather than something inside it, and it posts — a quoted config constant, a backticked directory name, or a placeholder form such as `.claude/worktrees/<name>`. Un-backticked prose that puts a word immediately after the marker reads the same as a relative path and is blocked; the placeholder form is the documented escape.
+
 ## Enforcement
 
 The `volatile_path_in_post_blocker` PreToolUse hook reads the body of each `gh` post command and each GitHub MCP post call, scans it for these markers, and blocks the post when it finds one. For a `--body-file`, the hook reads the file and scans its contents, so writing the body to a temp file and passing it with `--body-file` stays allowed — what the hook rejects is a volatile path inside the text that gets posted.

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