claude-dev-env 8.75.1 → 8.75.2

package/.agents/skills/context-audit/scripts/context_audit_constants/config/test_constants.py

@@ -0,0 +1,35 @@
+import re
+
+from context_audit_constants.config import constants
+from context_audit_constants.config.constants import CapKey, RowKind, Trigger
+
+
+def test_every_cap_key_has_a_line_cap() -> None:
+    assert set(constants.ALL_LINE_CAP_BY_KEY) == set(CapKey)
+    assert constants.ALL_LINE_CAP_BY_KEY[CapKey.ROOT_INSTRUCTIONS] == 20
+    assert constants.ALL_LINE_CAP_BY_KEY[CapKey.SKILL_BODY] == 200
+
+
+def test_trigger_values_match_the_report_labels() -> None:
+    assert [each_trigger.value for each_trigger in Trigger] == [
+        "session-start",
+        "folder-enter",
+        "path-match",
+        "skill-invoke",
+        "on-link",
+        "file-open",
+    ]
+
+
+def test_stub_kinds_cover_instruction_files_only() -> None:
+    assert constants.ALL_STUB_KINDS == {
+        RowKind.INSTRUCTIONS,
+        RowKind.IMPORT,
+        RowKind.RULE,
+    }
+
+
+def test_link_pattern_drops_the_anchor_from_a_target() -> None:
+    assert re.findall(constants.LINK_PATTERN, "[a](guide.md#setup) [b](x y)") == [
+        "guide.md"
+    ]

package/.agents/skills/context-audit/scripts/test_context_inventory.py

@@ -0,0 +1,109 @@
+"""Behavior tests for walking a checkout into context rows."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+scripts_directory = str(Path(__file__).resolve().parent)
+if scripts_directory not in sys.path:
+    sys.path.insert(0, scripts_directory)
+
+from context_audit_constants.config.constants import DepthMode, RowKind, Trigger
+from context_inventory import ContextInventory, audit_checkout
+from context_sources import ContextRow
+
+
+def _tracked_checkout(root: Path, text_by_relative_path: dict[str, str]) -> Path:
+    for each_relative_path, each_text in text_by_relative_path.items():
+        path = root / each_relative_path
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(each_text, encoding="utf-8")
+    subprocess.run(["git", "init", "-q"], cwd=root, check=True)
+    subprocess.run(["git", "add", "-A"], cwd=root, check=True)
+    return root.resolve()
+
+
+def _row_by_key(all_rows: list[ContextRow]) -> dict[tuple[str, RowKind], ContextRow]:
+    return {(each_row.path, each_row.kind): each_row for each_row in all_rows}
+
+
+def test_should_mark_installed_rules_global_unless_path_scoped(tmp_path: Path) -> None:
+    root = _tracked_checkout(
+        tmp_path / "repo",
+        {
+            "rules/everywhere.md": "Always.\n",
+            "rules/scoped.md": "---\npaths:\n  - src/**\n---\nScoped.\n",
+        },
+    )
+
+    row_by_key = _row_by_key(audit_checkout(root, root / "rules", None, ()))
+
+    everywhere_row = row_by_key[("rules/everywhere.md", RowKind.RULE)]
+    scoped_row = row_by_key[("rules/scoped.md", RowKind.RULE)]
+    assert (everywhere_row.trigger, everywhere_row.note) == (
+        Trigger.SESSION_START,
+        "installed rule: loads in every project",
+    )
+    assert (scoped_row.trigger, scoped_row.note) == (Trigger.PATH_MATCH, "")
+    assert everywhere_row.loader == "Claude Code harness, installed rules folder"
+
+
+def test_should_skip_rule_folders_that_are_not_installed(tmp_path: Path) -> None:
+    root = _tracked_checkout(tmp_path / "repo", {"rules/everywhere.md": "Always.\n"})
+
+    assert audit_checkout(root, None, None, ()) == []
+
+
+def test_should_list_installed_and_plugin_skills_at_session_start(
+    tmp_path: Path,
+) -> None:
+    long_description = "x" * 1600
+    root = _tracked_checkout(
+        tmp_path / "repo",
+        {
+            "pack/skills/tidy/SKILL.md": "---\ndescription: Tidy up.\n---\nBody.\n",
+            "plugins/kit/skills/wide/SKILL.md": (
+                f"---\ndescription: {long_description}\n---\nBody.\n"
+            ),
+        },
+    )
+
+    row_by_key = _row_by_key(audit_checkout(root, None, root / "pack" / "skills", ()))
+
+    installed_row = row_by_key[("pack/skills/tidy/SKILL.md", RowKind.SKILL_DESCRIPTION)]
+    plugin_row = row_by_key[
+        ("plugins/kit/skills/wide/SKILL.md", RowKind.SKILL_DESCRIPTION)
+    ]
+    assert installed_row.loader == "skill listing, installed skills folder"
+    assert installed_row.trigger == Trigger.SESSION_START
+    assert installed_row.depth_mode == DepthMode.POINTS
+    assert plugin_row.loader == "skill listing, plugin skills folder"
+    assert (plugin_row.bytes, plugin_row.depth_mode) == (1536, DepthMode.CARRIES)
+    assert plugin_row.note == (
+        "loads when the plugin is installed; listing truncates at 1,536 characters"
+    )
+
+
+def test_should_name_how_codex_and_claude_reach_an_agents_file(tmp_path: Path) -> None:
+    root = _tracked_checkout(
+        tmp_path / "repo",
+        {
+            "AGENTS.md": "Root rules.\n",
+            "pkg/AGENTS.md": "Package rules.\n",
+            "pkg/CLAUDE.md": "Claude rules.\n",
+        },
+    )
+
+    row_by_key = _row_by_key(ContextInventory(root, None, None).collect(()))
+
+    assert row_by_key[("AGENTS.md", RowKind.INSTRUCTIONS)].loader == (
+        "Claude Code native AGENTS.md read; Codex reads it"
+    )
+    assert row_by_key[("pkg/AGENTS.md", RowKind.INSTRUCTIONS)].loader == (
+        "not read by Claude Code (sibling CLAUDE.md, no import); Codex reads it"
+    )
+    assert row_by_key[("pkg/AGENTS.md", RowKind.INSTRUCTIONS)].trigger == (
+        Trigger.FOLDER_ENTER
+    )

package/.agents/skills/context-audit/scripts/test_context_report.py

@@ -0,0 +1,123 @@
+"""Behavior tests for formatting inventory rows as a markdown report."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+scripts_directory = str(Path(__file__).resolve().parent)
+if scripts_directory not in sys.path:
+    sys.path.insert(0, scripts_directory)
+
+from context_audit_constants.config.constants import DepthMode, RowKind, Trigger
+from context_report import (
+    format_carries_section,
+    format_cleanup_list,
+    format_report,
+    format_split_section,
+    format_stub_section,
+    format_trigger_table,
+)
+from context_sources import ContextRow
+
+
+def _row(
+    path: str,
+    kind: RowKind,
+    trigger: Trigger,
+    depth_mode: DepthMode,
+    lines: int,
+    est_tokens: int,
+) -> ContextRow:
+    return ContextRow(
+        path=path,
+        kind=kind,
+        loader="harness",
+        trigger=trigger,
+        bytes=est_tokens * 4,
+        lines=lines,
+        est_tokens=est_tokens,
+        links_out=0,
+        depth_mode=depth_mode,
+        cap=20,
+        note="",
+    )
+
+
+_ROOT_ROW = _row(
+    "AGENTS.md", RowKind.INSTRUCTIONS, Trigger.SESSION_START, DepthMode.CARRIES, 30, 300
+)
+_RULE_ROW = _row(
+    "rules/big.md", RowKind.RULE, Trigger.SESSION_START, DepthMode.CARRIES, 40, 500
+)
+_STUB_ROW = _row(
+    "pkg/CLAUDE.md", RowKind.INSTRUCTIONS, Trigger.FOLDER_ENTER, DepthMode.EMPTY, 0, 0
+)
+_SKILL_ROW = _row(
+    "skills/x/SKILL.md",
+    RowKind.SKILL_BODY,
+    Trigger.SKILL_INVOKE,
+    DepthMode.CARRIES,
+    250,
+    900,
+)
+_EMPTY_DOCSTRING_ROW = _row(
+    "src/mod.py", RowKind.DOCSTRING, Trigger.FILE_OPEN, DepthMode.EMPTY, 0, 0
+)
+
+
+def test_should_total_each_present_trigger_in_enum_order() -> None:
+    all_lines = format_trigger_table([_STUB_ROW, _ROOT_ROW, _RULE_ROW])
+
+    assert all_lines[4:] == [
+        "| session-start | 2 | 70 | 800 |",
+        "| folder-enter | 1 | 0 | 0 |",
+    ]
+
+
+def test_should_list_carries_rows_or_say_none() -> None:
+    assert format_carries_section([])[-1] == "None."
+    assert format_carries_section([_RULE_ROW])[-1] == (
+        "| rules/big.md | rule | session-start | 40 | 20 | 500 |"
+    )
+
+
+def test_should_list_stub_rows_or_say_none() -> None:
+    assert format_stub_section([])[-1] == "None."
+    assert format_stub_section([_STUB_ROW])[-1] == "- pkg/CLAUDE.md (instructions)"
+
+
+def test_should_list_long_skills_or_say_none() -> None:
+    assert format_split_section([])[-1] == "None."
+    assert format_split_section([_SKILL_ROW])[-1] == (
+        "| skills/x/SKILL.md | 250 | 20 | 900 |"
+    )
+
+
+def test_should_sort_cleanup_rows_largest_first_and_route_each_kind() -> None:
+    all_lines = format_cleanup_list(
+        [_ROOT_ROW, _RULE_ROW, _STUB_ROW, _SKILL_ROW, _EMPTY_DOCSTRING_ROW]
+    )
+
+    carries_start = all_lines.index("## Carries depth over cap")
+    stubs_start = all_lines.index("## Empty instruction stubs")
+    all_carries_rows = all_lines[carries_start + 4 : stubs_start - 1]
+    assert all_carries_rows == [
+        "| rules/big.md | rule | session-start | 40 | 20 | 500 |",
+        "| AGENTS.md | instructions | session-start | 30 | 20 | 300 |",
+    ]
+    assert "- pkg/CLAUDE.md (instructions)" in all_lines
+    assert not any("src/mod.py" in each_line for each_line in all_lines)
+    assert "| skills/x/SKILL.md | 250 | 20 | 900 |" in all_lines
+
+
+def test_should_summarize_session_start_load_in_the_report() -> None:
+    report = format_report("demo", [_ROOT_ROW, _RULE_ROW, _STUB_ROW])
+
+    assert report.startswith(
+        "# Context audit: demo\n\n"
+        "3 loaded files. Startup loads 70 lines, about 800 tokens, from 2 files.\n"
+    )
+    assert report.endswith(
+        "- pkg/CLAUDE.md (instructions)\n\n## Long skills to split\n\nNone.\n"
+    )

package/.agents/skills/context-audit/scripts/test_context_sources.py

@@ -0,0 +1,118 @@
+"""Behavior tests for reading checkout files and measuring context rows."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+scripts_directory = str(Path(__file__).resolve().parent)
+if scripts_directory not in sys.path:
+    sys.path.insert(0, scripts_directory)
+
+from context_audit_constants.config.constants import DepthMode, RowKind, Trigger
+from context_sources import (
+    RowSource,
+    classify_depth,
+    count_lines,
+    find_import_targets,
+    find_relative_links,
+    list_tracked_files,
+    measure_row,
+    parse_frontmatter,
+    read_text,
+)
+
+
+def _write(root: Path, relative_path: str, text: str) -> Path:
+    path = root / relative_path
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+    return path
+
+
+def test_should_list_tracked_files_without_cache_folders_or_untracked_files(
+    tmp_path: Path,
+) -> None:
+    subprocess.run(["git", "init", "-q"], cwd=tmp_path, check=True)
+    _write(tmp_path, "AGENTS.md", "# Root\n")
+    _write(tmp_path, "node_modules/pkg/README.md", "vendored\n")
+    _write(tmp_path, "notes.md", "untracked\n")
+    subprocess.run(
+        ["git", "add", "-f", "AGENTS.md", "node_modules/pkg/README.md"],
+        cwd=tmp_path,
+        check=True,
+    )
+
+    assert list_tracked_files(tmp_path) == [tmp_path / "AGENTS.md"]
+
+
+def test_should_read_text_and_return_empty_for_a_missing_file(tmp_path: Path) -> None:
+    present_path = _write(tmp_path, "rule.md", "line one\n")
+
+    assert read_text(present_path) == "line one\n"
+    assert read_text(tmp_path / "absent.md") == ""
+
+
+def test_should_parse_frontmatter_and_join_continuation_lines() -> None:
+    text = "---\nname: demo\npaths:\n  - src/**\n---\n# Body\n"
+
+    assert parse_frontmatter(text) == {"name": "demo", "paths": "- src/**"}
+
+
+def test_should_return_no_frontmatter_when_the_fence_never_closes() -> None:
+    assert parse_frontmatter("---\nname: demo\n# Body\n") == {}
+
+
+def test_should_find_links_inside_the_checkout_only(tmp_path: Path) -> None:
+    source = _write(tmp_path, "docs/index.md", "")
+    guide = _write(tmp_path, "docs/guide.md", "guide\n")
+    text = (
+        "[guide](guide.md#setup) [web](https://example.com/page.md)"
+        " [missing](absent.md)"
+    )
+
+    assert find_relative_links(source, text, tmp_path.resolve()) == [guide.resolve()]
+
+
+def test_should_find_import_targets_that_exist(tmp_path: Path) -> None:
+    source = _write(tmp_path, "CLAUDE.md", "")
+    agents = _write(tmp_path, "AGENTS.md", "rules\n")
+
+    all_targets = find_import_targets(
+        source, "\n".join(["@AGENTS.md", "@missing.md", ""]), tmp_path.resolve()
+    )
+
+    assert all_targets == [agents.resolve()]
+
+
+def test_should_classify_each_depth_mode() -> None:
+    assert classify_depth(20, 0, 0, 0) == DepthMode.EMPTY
+    assert classify_depth(None, 900, 30, 0) == DepthMode.REFERENCE
+    assert classify_depth(20, 4000, 64, 2) == DepthMode.CARRIES
+    assert classify_depth(20, 2500, 10, 0) == DepthMode.CARRIES
+    assert classify_depth(20, 600, 12, 3) == DepthMode.POINTS
+    assert classify_depth(20, 600, 12, 0) == DepthMode.LEAN
+
+
+def test_should_count_an_unterminated_final_line() -> None:
+    assert count_lines("") == 0
+    assert count_lines("one\ntwo\n") == 2
+    assert count_lines("one\ntwo") == 2
+
+
+def test_should_measure_a_row_from_its_text() -> None:
+    source = RowSource(
+        "rules/plain.md", RowKind.RULE, "harness", Trigger.SESSION_START, "note"
+    )
+
+    row = measure_row(source, "a" * 39 + "\n", 20, 1)
+
+    assert (row.path, row.kind, row.trigger, row.note) == (
+        "rules/plain.md",
+        RowKind.RULE,
+        Trigger.SESSION_START,
+        "note",
+    )
+    assert (row.bytes, row.lines, row.est_tokens, row.links_out) == (40, 1, 10, 1)
+    assert (row.depth_mode, row.cap) == (DepthMode.POINTS, 20)

package/bin/ever-shipped-skills.test.mjs

@@ -53,6 +53,10 @@ test('EVER_SHIPPED_SKILL_NAMES includes the windows scheduled task skill', () =>
     assert.equal(EVER_SHIPPED_SKILL_NAMES.has('windows-scheduled-task'), true);
 });
 
+test('EVER_SHIPPED_SKILL_NAMES includes the mod playbooks skill', () => {
+    assert.equal(EVER_SHIPPED_SKILL_NAMES.has('mod-playbooks'), true);
+});
+
 test('build-eval ships under its matching name without the retired active directory', () => {
     const sourceSkillsDirectory = join(
         PACKAGE_DIRECTORY,

package/package.json

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

package/scripts/policy_lint/adapter_pairing.py

@@ -300,6 +300,10 @@ def _is_unpaired_production(
         return False
     if _is_test_path(production_path):
         return False
+    if production_path.name in constants.ALL_PAIRING_EXEMPT_FILE_NAMES:
+        return False
+    if not production_document.text.strip():
+        return False
     if _is_constants_only_python_document(production_document, load_module):
         return False
     if _is_docstring_only_python_document(production_document):

package/scripts/policy_lint/config/constants.py

@@ -198,6 +198,7 @@ ALL_INVENTORY_FILE_NAMES = frozenset(
     {"CHANGELOG.md", "README.md", "ever-shipped-skills.mjs"}
 )
 ALL_UNCALLED_EXEMPT_FILE_NAMES = frozenset({"__init__.py", "conftest.py"})
+ALL_PAIRING_EXEMPT_FILE_NAMES = frozenset({"conftest.py"})
 CALLER_NAME_PATTERN_TEMPLATE = r"(?<![\w-]){name}(?![\w-])"
 
 CONTEXT_BUDGET_RULE_ID = "context-budget"

package/scripts/tests/test_policy_lint_rules_pairing.py

@@ -149,6 +149,44 @@ def test_pairing_keeps_non_python_changes_on_existing_matching_rules(
     assert len(all_diagnostics) == 1
 
 
+def test_pairing_accepts_a_new_empty_package_marker(tmp_path: Path) -> None:
+    package_marker_path = PurePosixPath("src/feature_constants/__init__.py")
+    all_paths = _diagnostic_paths(
+        tmp_path,
+        Document(
+            package_marker_path, "", None, frozenset(), ContentOrigin.REVISION_DIFF
+        ),
+    )
+    assert all_paths == ()
+
+
+def test_pairing_accepts_a_module_emptied_of_its_body(tmp_path: Path) -> None:
+    all_paths = _diagnostic_paths(
+        tmp_path,
+        Document(
+            PurePosixPath("src/feature.py"),
+            "\n",
+            _BODY_BEFORE,
+            frozenset({1}),
+            ContentOrigin.REVISION_DIFF,
+        ),
+    )
+    assert all_paths == ()
+
+
+def test_pairing_accepts_a_conftest_body_change(tmp_path: Path) -> None:
+    all_paths = _diagnostic_paths(
+        tmp_path, _body_change_at(PurePosixPath("src/conftest.py"))
+    )
+    assert all_paths == ()
+
+
+def test_pairing_rejects_a_package_marker_with_a_body(tmp_path: Path) -> None:
+    package_marker_path = PurePosixPath("src/feature/__init__.py")
+    all_paths = _diagnostic_paths(tmp_path, _body_change_at(package_marker_path))
+    assert all_paths == (package_marker_path,)
+
+
 _APPROVED_PRODUCTION_PATH = PurePosixPath(
     "packages/claude-dev-env/scripts/automatic_advisory/state.py"
 )

package/scripts/tests/test_runner.py

@@ -12,10 +12,17 @@ if str(_TESTS_DIRECTORY) not in sys.path:
     sys.path.insert(0, str(_TESTS_DIRECTORY))
 
 from repository_checks.config.constants import (
+    ALL_CHECK_IDS,
+    CHECK_ID_CLAUDE_MD_ORPHANS,
+    CHECK_ID_ENV_VAR_DOCUMENTATION,
+    CHECK_ID_PACKAGE_INVENTORY,
+    CHECK_ID_PYTEST_TESTPATHS,
+    CHECK_ID_TRACKED_PERSONAL_DATA,
     CHECK_ID_TRACKED_PRIVATE_TERMS,
     FAILED_CHECK_EXIT_CODE,
     FINDINGS_EXIT_CODE,
 )
+from repository_checks.runner import run_repository_checks
 from repository_policy_test_support import (
     commit_tracked_files,
     initialize_repository,
@@ -77,3 +84,38 @@ def test_should_fail_closed_when_the_private_term_check_cannot_read_a_file(
     exit_code, stdout_text, _stderr_text = run_policy(repository_root)
     assert exit_code == FAILED_CHECK_EXIT_CODE
     assert f"error: rule failed: {CHECK_ID_TRACKED_PRIVATE_TERMS}" in stdout_text
+
+
+_COLLECTOR_NAME_BY_CHECK_ID = {
+    CHECK_ID_CLAUDE_MD_ORPHANS: "collect_claude_md_orphan_findings",
+    CHECK_ID_ENV_VAR_DOCUMENTATION: "collect_env_var_documentation_findings",
+    CHECK_ID_PACKAGE_INVENTORY: "collect_package_inventory_findings",
+    CHECK_ID_PYTEST_TESTPATHS: "collect_pytest_testpath_findings",
+    CHECK_ID_TRACKED_PERSONAL_DATA: "collect_tracked_secret_findings",
+    CHECK_ID_TRACKED_PRIVATE_TERMS: "collect_tracked_private_term_findings",
+}
+
+
+def test_should_name_a_collector_for_every_check_id() -> None:
+    assert tuple(_COLLECTOR_NAME_BY_CHECK_ID) == ALL_CHECK_IDS
+
+
+@pytest.mark.parametrize(
+    ("check_id", "collector_name"), sorted(_COLLECTOR_NAME_BY_CHECK_ID.items())
+)
+def test_should_fail_closed_under_the_check_id_of_the_collector_that_raised(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    check_id: str,
+    collector_name: str,
+) -> None:
+    repository_root = seed_clean_repository(tmp_path / "repo")
+
+    def fail_collector(_repository_root: Path, _all_tracked_paths: object) -> list[object]:
+        raise OSError("collector failed")
+
+    monkeypatch.setattr(f"repository_checks.runner.{collector_name}", fail_collector)
+
+    report = run_repository_checks(repository_root)
+
+    assert report.all_failed_check_ids == (check_id,)