claude-dev-env 2.2.1 → 2.4.0

package/hooks/validators/test_mypy_integration.py

@@ -165,6 +165,37 @@ def test_run_mypy_check_accepts_relative_path_under_nested_root(
     assert mypy_result.passed, mypy_result.output
 
 
+def test_run_mypy_check_applies_config_resolved_from_config_source_path(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A staged file is checked under the config resolved from the original path.
+
+    A strict ``[tool.mypy]`` config flags an untyped def only when
+    ``config_source_path`` resolves it; native discovery from the detached
+    file finds no config and passes.
+    """
+    strict_repo = tmp_path / "strict_repo"
+    strict_repo.mkdir()
+    (strict_repo / "pyproject.toml").write_text(
+        "[tool.mypy]\ndisallow_untyped_defs = true\n", encoding="utf-8"
+    )
+    detached_file = tmp_path / "detached" / "untyped.py"
+    detached_file.parent.mkdir(parents=True)
+    detached_file.write_text(
+        "def annotate_nothing(value):\n    return value\n", encoding="utf-8"
+    )
+
+    monkeypatch.chdir(tmp_path)
+
+    without_source = run_mypy_check([detached_file])
+    with_source = run_mypy_check(
+        [detached_file], config_source_path=strict_repo / "pyproject.toml"
+    )
+
+    assert without_source.passed, without_source.output
+    assert not with_source.passed
+
+
 def test_mypy_result_dataclass() -> None:
     """Test MypyResult dataclass creation."""
     result = MypyResult(passed=True, output="test", error_count=0)
@@ -183,6 +214,7 @@ def test_run_mypy_check_returns_passed_for_empty_files() -> None:
     """Test that run_mypy_check passes with no files."""
     result = run_mypy_check([])
     assert result.passed is True
+    assert result.error_count == 0
     assert "No files" in result.output
 
 

package/hooks/validators/test_pyproject_config_discovery.py

@@ -0,0 +1,94 @@
+"""Tests for the shared pyproject config-discovery walk-up primitive.
+
+The primitive walks up from a starting path and returns the first pyproject.toml
+whose ``[tool.<name>]`` table exists, so each tool matches only a config that
+actually configures it — a mypy-only pyproject is no ruff config.
+"""
+
+from pathlib import Path
+
+from hooks_constants.pyproject_config_discovery_constants import (
+    MYPY_TOOL_TABLE_NAME,
+    RUFF_TOOL_TABLE_NAME,
+)
+
+from .pyproject_config_discovery import (
+    ancestor_directories,
+    find_pyproject_configuring_tool,
+)
+
+
+def test_ancestor_directories_lists_directory_then_parents_nearest_first(
+    tmp_path: Path,
+) -> None:
+    nested_directory = tmp_path / "outer" / "inner"
+    nested_directory.mkdir(parents=True)
+    nested_file = nested_directory / "module.py"
+    nested_file.write_text("sample_number: int = 1\n", encoding="utf-8")
+
+    walked = ancestor_directories(nested_file)
+
+    assert walked[0] == nested_directory.resolve()
+    assert walked[1] == (tmp_path / "outer").resolve()
+
+
+def test_find_pyproject_configuring_tool_returns_table_owning_pyproject(
+    tmp_path: Path,
+) -> None:
+    project_root = tmp_path / "project"
+    nested_directory = project_root / "src" / "deep"
+    nested_directory.mkdir(parents=True)
+    owning_pyproject = project_root / "pyproject.toml"
+    owning_pyproject.write_text("[tool.ruff.lint]\nselect = ['B']\n", encoding="utf-8")
+    target_file = nested_directory / "module.py"
+
+    found = find_pyproject_configuring_tool(target_file, RUFF_TOOL_TABLE_NAME)
+
+    assert found == owning_pyproject
+
+
+def test_find_pyproject_configuring_tool_skips_pyproject_without_the_table(
+    tmp_path: Path,
+) -> None:
+    outer_root = tmp_path / "outer"
+    inner_root = outer_root / "inner"
+    inner_root.mkdir(parents=True)
+    outer_pyproject = outer_root / "pyproject.toml"
+    outer_pyproject.write_text("[tool.mypy]\nignore_missing_imports = true\n", encoding="utf-8")
+    (inner_root / "pyproject.toml").write_text("[project]\nname = 'inner'\n", encoding="utf-8")
+    target_file = inner_root / "module.py"
+
+    found = find_pyproject_configuring_tool(target_file, MYPY_TOOL_TABLE_NAME)
+
+    assert found == outer_pyproject
+
+
+def test_find_pyproject_configuring_tool_is_table_specific(tmp_path: Path) -> None:
+    project_root = tmp_path / "mypy_only"
+    project_root.mkdir()
+    (project_root / "pyproject.toml").write_text(
+        "[tool.mypy]\nignore_missing_imports = true\n", encoding="utf-8"
+    )
+    target_file = project_root / "module.py"
+
+    assert find_pyproject_configuring_tool(target_file, MYPY_TOOL_TABLE_NAME) is not None
+    assert find_pyproject_configuring_tool(target_file, RUFF_TOOL_TABLE_NAME) is None
+
+
+def test_find_pyproject_configuring_tool_returns_none_when_no_match(tmp_path: Path) -> None:
+    isolated_directory = tmp_path / "isolated"
+    isolated_directory.mkdir()
+    target_file = isolated_directory / "module.py"
+
+    assert find_pyproject_configuring_tool(target_file, RUFF_TOOL_TABLE_NAME) is None
+
+
+def test_find_pyproject_configuring_tool_treats_malformed_toml_as_no_match(
+    tmp_path: Path,
+) -> None:
+    project_root = tmp_path / "broken"
+    project_root.mkdir()
+    (project_root / "pyproject.toml").write_text("[tool.ruff\nbroken = true\n", encoding="utf-8")
+    target_file = project_root / "module.py"
+
+    assert find_pyproject_configuring_tool(target_file, RUFF_TOOL_TABLE_NAME) is None

package/hooks/validators/test_ruff_integration.py

@@ -3,7 +3,47 @@
 from pathlib import Path
 from unittest.mock import patch
 
-from .ruff_integration import RuffResult, check_ruff_available, run_ruff_check
+from .ruff_integration import (
+    RuffResult,
+    _config_relative_stdin_filename,
+    _parse_fixed_count,
+    check_ruff_available,
+    run_ruff_check,
+)
+
+
+def test_parse_fixed_count_reads_the_count_from_the_fixed_line() -> None:
+    """The ``Fixed N`` summary line yields its integer count."""
+    assert _parse_fixed_count("Found 3 errors (2 fixed).\nFixed 2 errors\n") == 2
+
+
+def test_parse_fixed_count_returns_zero_without_a_fixed_line() -> None:
+    """Output with no ``Fixed`` line yields a zero count."""
+    assert _parse_fixed_count("All checks passed!\n") == 0
+
+
+def test_config_relative_stdin_filename_returns_posix_path_under_config_directory() -> None:
+    """A target under the config directory resolves to its config-relative path."""
+    config_directory = Path("/repo/hooks")
+    target_path = Path("/repo/hooks/validators/run_all_validators.py")
+
+    relative_filename = _config_relative_stdin_filename(target_path, config_directory)
+
+    assert relative_filename == "validators/run_all_validators.py"
+
+
+def test_config_relative_stdin_filename_falls_back_to_basename_off_tree() -> None:
+    """A target outside the config directory falls back to the bare basename.
+
+    Path-scoped per-file-ignores cannot apply to a file that does not sit under
+    the config directory, so a ``..``-laden relative path is never handed to ruff.
+    """
+    config_directory = Path("/repo/hooks")
+    target_path = Path("/elsewhere/run_all_validators.py")
+
+    relative_filename = _config_relative_stdin_filename(target_path, config_directory)
+
+    assert relative_filename == "run_all_validators.py"
 
 
 def test_ruff_result_dataclass() -> None:
@@ -24,9 +64,36 @@ def test_run_ruff_check_returns_passed_for_empty_files() -> None:
     """Test that run_ruff_check passes with no files."""
     result = run_ruff_check([])
     assert result.passed is True
+    assert result.fixed_count == 0
     assert "No files" in result.output
 
 
+def test_run_ruff_check_applies_config_resolved_from_config_source_path(
+    tmp_path: Path,
+) -> None:
+    """A given config_source_path resolves the ruff config for a staged copy.
+
+    A ``[tool.ruff.lint]`` selecting B flags an ``assert False`` (B011) only when
+    ``config_source_path`` — the original ``.py`` target — resolves it; native
+    discovery from the detached staged copy finds no ruff config and passes.
+    """
+    ruff_repo = tmp_path / "ruff_repo"
+    ruff_repo.mkdir()
+    (ruff_repo / "pyproject.toml").write_text(
+        "[tool.ruff.lint]\nselect = ['B']\n", encoding="utf-8"
+    )
+    original_target = ruff_repo / "asserts.py"
+    staged_copy = tmp_path / "detached" / "asserts.py"
+    staged_copy.parent.mkdir(parents=True)
+    staged_copy.write_text("def probe() -> None:\n    assert False\n", encoding="utf-8")
+
+    without_source = run_ruff_check([staged_copy])
+    with_source = run_ruff_check([staged_copy], config_source_path=original_target)
+
+    assert "B011" not in without_source.output
+    assert "B011" in with_source.output
+
+
 def test_run_ruff_check_emits_location_prefixed_lines(tmp_path: Path) -> None:
     """Each reported violation carries a ``path:line:col:`` prefix on its own line.
 

package/hooks/validators/test_run_all_validators.py

@@ -20,8 +20,33 @@ from .run_all_validators import (
     run_git_checks,
     run_python_style_checks,
     run_with_fallback,
+    validate_proposed_file,
 )
 
+_VALIDATORS_DIRECTORY = Path(__file__).parent
+_ASSERT_FALSE_SOURCE = (
+    "def probe_condition(observed_total: int) -> None:\n"
+    "    assert False, observed_total\n"
+)
+
+
+def test_validate_proposed_file_threads_ruff_config_from_original_path() -> None:
+    """A non-test staged file is linted under the project ruff config (B selected).
+
+    ::
+
+        original path .../validators/threading_probe.py, assert False body
+        ok: config resolved from the original path -> Ruff output carries B011
+    """
+    probe_path = _VALIDATORS_DIRECTORY / "threading_probe.py"
+
+    all_results = validate_proposed_file(str(probe_path), _ASSERT_FALSE_SOURCE)
+
+    ruff_output = next(
+        each_result.output for each_result in all_results if each_result.name == "Ruff"
+    )
+    assert "B011" in ruff_output
+
 
 class TestFixFlag:
     """Test --fix flag functionality."""

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/package.json

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

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

@@ -12,56 +12,33 @@ paths:
 
 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
+## Write-time checks
 
-A `@dataclass` dead-field check builds its set of "field counts as read" sources by union:
+Read the body and the docstring side by side. Apply each check that matches the prose:
 
-```python
-read_names = (
-    attribute_read_names
-    | dynamic_literal_names
-    | _match_pattern_attribute_names(tree)
-    | _exported_names(tree)
-)
-```
+- **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.
 
-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.
+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.
 
-## Enforcement (audit lane)
+## Full standard
 
-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.
+The full Category O judgment standard — sub-buckets O1–O9, the complete write-time gate inventory, free-form checklists, and worked examples — lives in:
 
-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.
+`packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md`
 
-## Why
+## Division of labor
 
-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.
+| 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/scripts/CLAUDE.md

@@ -6,7 +6,8 @@ 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 |
+| `claude_chain_runner.py` | Runs a `claude` invocation through a usage-ranked fallback chain (`~/.claude/claude-chain.json`): probes weekly remaining once via `claude_chain_usage` / the usage-pause OAuth probe, tries the highest-remaining account first, and falls over to the next ranked binary only on a usage-limit failure; usable as an imported module (`run_claude`) or a CLI. Copy `claude-chain.example.json` to `~/.claude/claude-chain.json` and list your account binaries. Optional per-entry `credentials_path` names that account's OAuth credentials file for the usage probe |
+| `claude_chain_usage.py` | Reports remaining weekly usage for every account in `~/.claude/claude-chain.json` via the usage-pause OAuth probe; prints JSON (`accounts` with `weekly_remaining_percent` or null plus `error`); importable `report_chain_weekly_usage` and `rank_accounts_by_weekly_remaining` (highest remaining first, ties keep config order, unmeasurable last). The chain runner consumes this ranking for try 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 |
 | `grok_headless_runner.py` | Runs one worker as headless `grok`: builds argv, mints a unique leader socket, captures streams, kills on timeout with grace, classifies ok/usage_limit/auth_failure/timeout/error; imported by `spawn_grok_batch.py` |
 | `grok_worker_preflight.py` | Soft gate for the headless grok tier: binary on PATH, `grok models` auth, install manifest + role agents, opt-in cached live ping; non-zero exit is fallthrough, not failure |

package/scripts/claude-chain.example.json

@@ -1,8 +1,20 @@
 {
   "chain": [
     { "command": "claude", "extra_args": [] },
-    { "command": "claude-1", "extra_args": [] },
-    { "command": "claude-2", "extra_args": [] },
-    { "command": "claude-3", "extra_args": [] }
+    {
+      "command": "claude-1",
+      "extra_args": [],
+      "credentials_path": "/path/to/account-1/.credentials.json"
+    },
+    {
+      "command": "claude-2",
+      "extra_args": [],
+      "credentials_path": "/path/to/account-2/.credentials.json"
+    },
+    {
+      "command": "claude-3",
+      "extra_args": [],
+      "credentials_path": "/path/to/account-3/.credentials.json"
+    }
   ]
 }