claude-dev-env 8.72.2 → 8.73.1

package/hooks/context_budget/tests/budget_support.py

@@ -0,0 +1,71 @@
+"""Shared builders for the context budget tests."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+FIXTURE_DIRECTORY = Path(__file__).resolve().parents[2] / "test_files" / "context_budget"
+ORCHESTRATOR_PATH = "packages/claude-dev-env/.agents/skills/orchestrator/SKILL.md"
+SKILL_PATH = "tools/example/SKILL.md"
+
+
+def fixture_text(file_name: str) -> str:
+    """Return one committed fixture's text.
+
+    Args:
+        file_name: Fixture file name under ``test_files/context_budget``.
+
+    Returns:
+        The fixture text.
+    """
+    return (FIXTURE_DIRECTORY / file_name).read_text(encoding="utf-8")
+
+
+def policy_text(baseline_files: dict | None = None) -> str:
+    """Return a policy JSON text with three kinds and one hook.
+
+    Args:
+        baseline_files: Baseline file entries, or None for an empty list.
+
+    Returns:
+        Policy JSON text.
+    """
+    raw_policy: dict[str, object] = {
+        "section_detail_line_limit": 6,
+        "kinds": [
+            {"name": "archived skill", "patterns": ["**/skills-archived/**"], "line_limit": None},
+            {
+                "name": "skill entry",
+                "patterns": ["**/SKILL.md"],
+                "line_limit": 200,
+                "section_rule": True,
+            },
+            {"name": "rule", "patterns": ["rules/*.md"], "line_limit": 30, "section_rule": True},
+        ],
+        "hooks": [
+            {"name": "greeter", "command": ["python3", "g.py"], "stdin": {}, "char_limit": 1500}
+        ],
+        "baseline": {"files": baseline_files or {}, "hooks": {}},
+    }
+    return json.dumps(raw_policy)
+
+
+def section_text(heading: str, detail_count: int, pointer_line: str = "") -> str:
+    """Return one Markdown section with numbered detail lines.
+
+    Args:
+        heading: Section heading text.
+        detail_count: Number of detail lines.
+        pointer_line: Optional extra line, such as a link.
+
+    Returns:
+        The section text ending in a newline.
+    """
+    all_lines = [
+        f"## {heading}",
+        *(f"Detail line {each} of the section." for each in range(detail_count)),
+    ]
+    if pointer_line:
+        all_lines.append(pointer_line)
+    return "\n".join(all_lines) + "\n"

package/hooks/context_budget/tests/test_baseline.py

@@ -0,0 +1,43 @@
+"""The generated over-budget list records exactly the items over budget."""
+
+from __future__ import annotations
+
+import json
+
+from context_budget.baseline import build_baseline, policy_text_with_baseline
+from context_budget.policy_file import parse_policy
+from context_budget.tests.budget_support import policy_text, section_text
+
+
+def test_baseline_records_over_budget_files_and_hooks_only() -> None:
+    policy = parse_policy(policy_text())
+    text_by_path = {
+        "b/SKILL.md": section_text("Plan", 7) + section_text("Plan", 8),
+        "c/SKILL.md": section_text("Plan", 7) + "\n" * 200,
+        "a/SKILL.md": "short\n",
+        "x/skills-archived/SKILL.md": section_text("Old", 40),
+        "docs/notes.md": section_text("Notes", 40),
+    }
+
+    baseline = build_baseline(policy, text_by_path, {"greeter": 1501, "unlisted": 9000})
+
+    assert baseline == {
+        "files": {
+            "b/SKILL.md": {"lines": None, "sections": ["Plan", "Plan"]},
+            "c/SKILL.md": {"lines": 208, "sections": ["Plan"]},
+        },
+        "hooks": {"greeter": 1501},
+    }
+
+
+def test_rewriting_the_baseline_keeps_every_other_key() -> None:
+    raw_policy = json.loads(policy_text())
+    raw_policy["kept_by_another_tool"] = [1]
+
+    rewritten = json.loads(
+        policy_text_with_baseline(json.dumps(raw_policy), {"files": {}, "hooks": {"g": 2}})
+    )
+
+    assert rewritten["kept_by_another_tool"] == [1]
+    assert rewritten["baseline"] == {"files": {}, "hooks": {"g": 2}}
+    assert rewritten["kinds"] == raw_policy["kinds"]

package/hooks/context_budget/tests/test_findings.py

@@ -0,0 +1,120 @@
+"""File findings, the CI ratchet, and the findings an edit introduces."""
+
+from __future__ import annotations
+
+from context_budget.tests.budget_support import SKILL_PATH, policy_text, section_text
+from context_budget.findings import edit_findings, file_findings
+from context_budget.policy_file import default_policy, parse_policy
+
+
+def test_unlisted_file_reports_line_limit_and_eachsection_text() -> None:
+    policy = parse_policy(policy_text())
+    text = section_text("Alpha", 7) + "\n" * 200
+
+    all_findings = file_findings(policy, SKILL_PATH, text, None)
+
+    assert [each.scope for each in all_findings] == ["file", "Alpha"]
+    assert "file has 208 lines (skill entry limit 200)" in all_findings[0].message
+
+
+def _section_only_policy():
+    return parse_policy(policy_text({SKILL_PATH: {"lines": None, "sections": ["Alpha", "Alpha"]}}))
+
+
+def test_section_only_listed_file_grows_under_its_limit_and_passes() -> None:
+    text = section_text("Alpha", 7) + section_text("Alpha", 8) + section_text("Beta", 7)
+
+    assert [each.scope for each in file_findings(_section_only_policy(), SKILL_PATH, text, None)] == [
+        "Beta"
+    ]
+    grown_text = text + "one more\n" * (200 - len(text.splitlines()))
+    assert [
+        each.scope for each in file_findings(_section_only_policy(), SKILL_PATH, grown_text, None)
+    ] == ["Beta"]
+
+
+def test_section_only_listed_file_crossing_its_limit_fails() -> None:
+    text = section_text("Alpha", 7) + section_text("Alpha", 8)
+    crossed_text = text + "one more\n" * (201 - len(text.splitlines()))
+
+    all_findings = file_findings(_section_only_policy(), SKILL_PATH, crossed_text, None)
+
+    assert [each.scope for each in all_findings] == ["file"]
+    assert "file has 201 lines (skill entry limit 200)" in all_findings[0].message
+
+
+def test_over_limit_listed_file_may_not_grow_past_its_record() -> None:
+    text = section_text("Alpha", 7) + "\n" * 202
+    policy = parse_policy(policy_text({SKILL_PATH: {"lines": 210, "sections": ["Alpha"]}}))
+
+    assert file_findings(policy, SKILL_PATH, text, None) == ()
+    grown_findings = file_findings(policy, SKILL_PATH, text + "one more\n", None)
+    assert [each.scope for each in grown_findings] == ["file"]
+    assert "grew from 210 to 211 lines" in grown_findings[0].message
+
+
+def test_ratchet_asks_to_lower_null_or_remove_the_entry_of_a_changed_listed_file() -> None:
+    prior_text = section_text("Alpha", 7) + section_text("Beta", 7) + "\n" * 200
+    policy = parse_policy(policy_text({SKILL_PATH: {"lines": 216, "sections": ["Alpha", "Beta"]}}))
+    lowered_text = section_text("Alpha", 7) + section_text("Beta", 7) + "\n" * 190
+    nulled_text = section_text("Alpha", 7) + section_text("Beta", 7)
+
+    lowered = file_findings(policy, SKILL_PATH, lowered_text, prior_text)
+    nulled = file_findings(policy, SKILL_PATH, nulled_text, prior_text)
+    removed = file_findings(policy, SKILL_PATH, "short\n", prior_text)
+
+    assert len(lowered) == 1
+    assert '{"lines": 206, "sections": ["Alpha", "Beta"]}' in lowered[0].message
+    assert '{"lines": null, "sections": ["Alpha", "Beta"]}' in nulled[0].message
+    assert "Remove its entry" in removed[0].message
+    assert file_findings(policy, SKILL_PATH, lowered_text, None) == ()
+
+
+def test_ratchet_asks_to_drop_a_lost_section_from_a_section_only_entry() -> None:
+    policy = parse_policy(policy_text({SKILL_PATH: {"lines": None, "sections": ["Alpha", "Beta"]}}))
+    prior_text = section_text("Alpha", 7) + section_text("Beta", 7)
+    shrunk_text = section_text("Alpha", 7) + section_text("Beta", 3, "[b](reference/beta.md)")
+
+    lowered = file_findings(policy, SKILL_PATH, shrunk_text, prior_text)
+
+    assert len(lowered) == 1
+    assert '{"lines": null, "sections": ["Alpha"]}' in lowered[0].message
+
+
+def test_edit_that_only_shrinks_has_no_findings_without_a_policy_file() -> None:
+    prior_text = section_text("Alpha", 9) + "\n" * 220
+    shrunk_text = section_text("Alpha", 8) + "\n" * 210
+
+    assert edit_findings(default_policy(), SKILL_PATH, prior_text, shrunk_text, True) == ()
+
+
+def test_edit_that_grows_or_adds_a_section_is_reported_without_a_policy_file() -> None:
+    prior_text = section_text("Alpha", 9) + "\n" * 220
+    grown = edit_findings(default_policy(), SKILL_PATH, prior_text, prior_text + "x\n", True)
+    added = edit_findings(
+        default_policy(), SKILL_PATH, prior_text, section_text("Beta", 7) + "\n" * 200, True
+    )
+
+    assert [each.scope for each in grown] == ["file"]
+    assert "was already over its limit at 230 lines and may only shrink" in grown[0].message
+    assert "list" not in grown[0].message
+    assert [each.scope for each in added] == ["Beta"]
+
+
+def test_short_skill_with_one_long_section_accepts_an_added_line_without_a_policy_file() -> None:
+    prior_text = "# Skill\nIntro.\n" + section_text("Alpha", 8)
+    post_text = "# Skill\nIntro.\nOne more intro line.\n" + section_text("Alpha", 8)
+
+    assert len(prior_text.splitlines()) == 11
+    assert edit_findings(default_policy(), SKILL_PATH, prior_text, post_text, True) == ()
+
+
+def test_edit_of_an_unlisted_over_budget_file_is_allowed_when_it_shrinks_under_a_policy() -> None:
+    policy = parse_policy(policy_text())
+    prior_text = section_text("Alpha", 9) + "\n" * 220
+
+    assert edit_findings(policy, SKILL_PATH, prior_text, prior_text[:-5], False) == ()
+    assert [each.scope for each in edit_findings(policy, SKILL_PATH, None, prior_text, False)] == [
+        "file",
+        "Alpha",
+    ]

package/hooks/context_budget/tests/test_hook_measure.py

@@ -0,0 +1,57 @@
+"""Hook output measurement and the hook budget."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from context_budget.hook_measure import (
+    HookMeasurementError,
+    hook_findings,
+    injected_character_count,
+    run_hook_command,
+    split_command_environment,
+)
+from context_budget.model import BudgetPolicy, HookBudget
+
+
+def test_injected_characters_count_context_and_system_message_or_raw_stdout() -> None:
+    json_output = json.dumps(
+        {"hookSpecificOutput": {"additionalContext": "abcd"}, "systemMessage": "xy"}
+    )
+
+    assert injected_character_count(json_output) == 6
+    assert injected_character_count("plain text") == 10
+    assert injected_character_count("") == 0
+
+
+def test_hook_is_held_to_its_limit_or_its_baseline() -> None:
+    hook = HookBudget("greeter", ("python3", "g.py"), "{}", 100)
+    unlisted_policy = BudgetPolicy(6, ())
+    listed_policy = BudgetPolicy(6, (), (hook,), {}, {"greeter": 150})
+
+    assert hook_findings(unlisted_policy, hook, 100) == ()
+    assert "injects 101 characters (limit 100)" in hook_findings(unlisted_policy, hook, 101)[0]
+    assert hook_findings(listed_policy, hook, 150) == ()
+    assert "over its baseline of 150" in hook_findings(listed_policy, hook, 151)[0]
+
+
+def test_env_prefix_lifts_into_environment_pairs() -> None:
+    assert split_command_environment(["env", "A=1", "B=", "python3", "x.py"]) == (
+        {"A": "1", "B": ""},
+        ("python3", "x.py"),
+    )
+    assert split_command_environment(["python3", "x.py"]) == ({}, ("python3", "x.py"))
+
+
+def test_a_failed_hook_with_output_is_not_a_measurement(tmp_path: Path) -> None:
+    hook_path = tmp_path / "failed.py"
+    hook_path.write_text(
+        "print('partial output')\nraise RuntimeError('fixture failure')\n", encoding="utf-8"
+    )
+    hook = HookBudget("failed", ("python3", str(hook_path)), "{}", 1500)
+
+    with pytest.raises(HookMeasurementError, match='hook "failed" exited with status 1'):
+        run_hook_command(hook, tmp_path)

package/hooks/context_budget/tests/test_policy_changes.py

@@ -0,0 +1,175 @@
+"""The over-budget list may only shrink."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from context_budget.tests.budget_support import policy_text
+from context_budget.policy_changes import policy_shrink_findings
+from context_budget.policy_file import parse_policy
+
+
+@pytest.mark.parametrize(
+    ("mutation", "expected_fragment"),
+    [
+        (
+            lambda raw: raw["baseline"]["files"].update(
+                {"b/SKILL.md": {"lines": 300, "sections": []}}
+            ),
+            'adds file "b/SKILL.md"',
+        ),
+        (
+            lambda raw: raw["baseline"]["files"]["a/SKILL.md"].update({"lines": 301}),
+            "from 300 to 301 lines",
+        ),
+        (
+            lambda raw: raw["baseline"]["files"]["a/SKILL.md"]["sections"].append("X"),
+            'adds section "X"',
+        ),
+        (lambda raw: raw["baseline"]["hooks"].update({"other": 1600}), 'adds hook "other"'),
+        (
+            lambda raw: raw["baseline"]["hooks"].update({"greeter": 2001}),
+            "from 2000 to 2001 characters",
+        ),
+        (lambda raw: raw.update({"section_detail_line_limit": 7}), "rises from 6 to 7"),
+        (
+            lambda raw: raw["kinds"][1].update({"line_limit": 250}),
+            "line_limit rises from 200 to 250",
+        ),
+        (lambda raw: raw["kinds"].pop(2), 'kind "rule" is deleted'),
+        (
+            lambda raw: raw["kinds"][1].update({"patterns": ["no-skills/*.md"]}),
+            'kind "skill entry" patterns change',
+        ),
+        (lambda raw: raw["kinds"].reverse(), "kind selection order changes"),
+        (lambda raw: raw["hooks"].clear(), 'hook "greeter" is deleted'),
+        (
+            lambda raw: raw["hooks"][0].update({"char_limit": 1501}),
+            "char_limit rises from 1500 to 1501",
+        ),
+    ],
+)
+def test_policy_change_that_loosens_the_budget_is_a_finding(
+    mutation, expected_fragment: str, tmp_path: Path
+) -> None:
+    (tmp_path / "g.py").write_text("", encoding="utf-8")
+    raw_prior = json.loads(policy_text({"a/SKILL.md": {"lines": 300, "sections": []}}))
+    raw_prior["baseline"]["hooks"] = {"greeter": 2000}
+    raw_current = json.loads(json.dumps(raw_prior))
+    mutation(raw_current)
+
+    all_findings = policy_shrink_findings(
+        ".claude/context-budget.json",
+        parse_policy(json.dumps(raw_prior)),
+        parse_policy(json.dumps(raw_current)),
+        tmp_path,
+    )
+
+    assert len(all_findings) == 1
+    assert expected_fragment in all_findings[0].message
+    assert "the over-budget list may only shrink" in all_findings[0].message
+
+
+def test_deleting_a_hook_whose_script_is_still_in_the_tree_is_a_finding(
+    tmp_path: Path,
+) -> None:
+    (tmp_path / "g.py").write_text("", encoding="utf-8")
+    raw_prior = json.loads(policy_text())
+    raw_current = json.loads(json.dumps(raw_prior))
+    raw_current["hooks"].clear()
+
+    all_findings = policy_shrink_findings(
+        "p", parse_policy(json.dumps(raw_prior)), parse_policy(json.dumps(raw_current)), tmp_path
+    )
+
+    assert len(all_findings) == 1
+    assert 'hook "greeter" is deleted' in all_findings[0].message
+
+
+def test_deleting_a_hook_together_with_its_script_passes(tmp_path: Path) -> None:
+    raw_prior = json.loads(policy_text())
+    raw_current = json.loads(json.dumps(raw_prior))
+    raw_current["hooks"].clear()
+
+    assert policy_shrink_findings(
+        "p", parse_policy(json.dumps(raw_prior)), parse_policy(json.dumps(raw_current)), tmp_path
+    ) == ()
+
+
+def test_policy_change_that_shrinks_or_adds_the_file_passes(tmp_path: Path) -> None:
+    prior_policy = parse_policy(policy_text({"a/SKILL.md": {"lines": 300, "sections": ["X"]}}))
+    shrunk_policy = parse_policy(policy_text({"a/SKILL.md": {"lines": 250, "sections": []}}))
+    nulled_policy = parse_policy(policy_text({"a/SKILL.md": {"lines": None, "sections": ["X"]}}))
+
+    assert policy_shrink_findings("p", prior_policy, shrunk_policy, tmp_path) == ()
+    assert policy_shrink_findings("p", prior_policy, nulled_policy, tmp_path) == ()
+    assert policy_shrink_findings("p", None, shrunk_policy, tmp_path) == ()
+
+
+def test_policy_change_from_null_lines_to_a_number_fails_shrink_only(tmp_path: Path) -> None:
+    prior_policy = parse_policy(policy_text({"a/SKILL.md": {"lines": None, "sections": ["X"]}}))
+    numbered_policy = parse_policy(policy_text({"a/SKILL.md": {"lines": 250, "sections": ["X"]}}))
+
+    all_findings = policy_shrink_findings("p", prior_policy, numbered_policy, tmp_path)
+
+    assert len(all_findings) == 1
+    assert 'records 250 lines for "a/SKILL.md"' in all_findings[0].message
+    assert "the over-budget list may only shrink" in all_findings[0].message
+
+
+@pytest.mark.parametrize("position", [0, 1])
+def test_a_new_kind_cannot_precede_an_existing_kind(position: int, tmp_path: Path) -> None:
+    raw_prior = json.loads(policy_text())
+    raw_current = json.loads(json.dumps(raw_prior))
+    raw_current["kinds"].insert(
+        position,
+        {"name": "unlimited", "patterns": ["**/*"], "line_limit": None},
+    )
+
+    findings = policy_shrink_findings(
+        "p",
+        parse_policy(json.dumps(raw_prior)),
+        parse_policy(json.dumps(raw_current)),
+        tmp_path,
+    )
+
+    assert len(findings) == 1
+    assert "kind selection order changes" in findings[0].message
+
+
+def test_a_duplicate_name_cannot_hide_a_raised_limit(tmp_path: Path) -> None:
+    raw_prior = json.loads(policy_text())
+    raw_current = json.loads(json.dumps(raw_prior))
+    raw_current["kinds"][1]["line_limit"] = None
+    raw_current["kinds"].append(raw_prior["kinds"][1])
+
+    findings = policy_shrink_findings(
+        "p",
+        parse_policy(json.dumps(raw_prior)),
+        parse_policy(json.dumps(raw_current)),
+        tmp_path,
+    )
+
+    assert len(findings) == 1
+    assert "kind selection order changes" in findings[0].message
+
+
+def test_appending_a_kind_and_tightening_limits_passes(tmp_path: Path) -> None:
+    raw_prior = json.loads(policy_text())
+    raw_current = json.loads(json.dumps(raw_prior))
+    raw_current["kinds"][1]["line_limit"] = 100
+    raw_current["hooks"][0]["char_limit"] = 1000
+    raw_current["section_detail_line_limit"] = 5
+    raw_current["kinds"].append(
+        {"name": "extra", "patterns": ["extra/*.md"], "line_limit": 20}
+    )
+
+    assert policy_shrink_findings(
+        "p",
+        parse_policy(json.dumps(raw_prior)),
+        parse_policy(json.dumps(raw_current)),
+        tmp_path,
+    ) == ()

package/hooks/context_budget/tests/test_policy_file.py

@@ -0,0 +1,62 @@
+"""Policy parsing and repository lookup."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from context_budget.tests.budget_support import policy_text
+from context_budget.model import ContextBudgetPolicyError
+from context_budget.policy_file import find_repository_root, parse_policy, read_policy_file
+
+
+def test_parse_ignores_unknown_keys_and_rejects_a_bad_shape() -> None:
+    raw_policy = json.loads(policy_text())
+    raw_policy["added_by_another_tool"] = {"anything": True}
+    raw_policy["kinds"][1]["extra"] = 1
+
+    assert len(parse_policy(json.dumps(raw_policy)).all_kinds) == 3
+    with pytest.raises(ContextBudgetPolicyError):
+        parse_policy("[1, 2]")
+    with pytest.raises(ContextBudgetPolicyError):
+        parse_policy(json.dumps({"kinds": [{"name": "x", "patterns": "**/a.md"}]}))
+    with pytest.raises(ContextBudgetPolicyError):
+        parse_policy("{not json")
+
+
+def test_baseline_lines_may_be_null_but_may_not_be_missing() -> None:
+    policy = parse_policy(policy_text({"a/SKILL.md": {"lines": None, "sections": ["Plan"]}}))
+
+    assert policy.baseline_entry_by_path["a/SKILL.md"].lines is None
+    with pytest.raises(ContextBudgetPolicyError):
+        parse_policy(policy_text({"a/SKILL.md": {"sections": ["Plan"]}}))
+
+
+def test_duplicate_hook_names_are_rejected_before_measurement() -> None:
+    raw_policy = json.loads(policy_text())
+    raw_policy["hooks"].append(dict(raw_policy["hooks"][0]))
+
+    with pytest.raises(ContextBudgetPolicyError, match="hook names must be unique"):
+        parse_policy(json.dumps(raw_policy))
+
+
+def test_repository_root_accepts_a_git_file_and_policy_reads_from_it(tmp_path: Path) -> None:
+    repository_root = tmp_path / "worktree"
+    (repository_root / ".claude").mkdir(parents=True)
+    (repository_root / ".git").write_text("gitdir: elsewhere\n", encoding="utf-8")
+    (repository_root / ".claude" / "context-budget.json").write_text(
+        policy_text(), encoding="utf-8"
+    )
+
+    found_root = find_repository_root(repository_root / "new" / "dir" / "SKILL.md")
+
+    assert found_root == repository_root
+    policy = read_policy_file(repository_root)
+    assert policy is not None and len(policy.all_hooks) == 1
+    assert read_policy_file(tmp_path) is None
+    assert (
+        find_repository_root(tmp_path / "x.md") is None
+        or find_repository_root(tmp_path / "x.md") != repository_root
+    )

package/hooks/context_budget/tests/test_sections.py

@@ -0,0 +1,112 @@
+"""Path classification and Markdown section measurement."""
+
+from __future__ import annotations
+
+import pytest
+
+from context_budget.tests.budget_support import (
+    ORCHESTRATOR_PATH,
+    fixture_text,
+    policy_text,
+    section_text,
+)
+from context_budget.findings import file_findings
+from context_budget.policy_file import default_policy, parse_policy
+from context_budget.sections import context_kind_for_path, path_matches_pattern, scan_sections
+
+
+def test_calibration_old_orchestrator_fails_on_oversee_delegated_work() -> None:
+    all_findings = file_findings(
+        default_policy(),
+        ORCHESTRATOR_PATH,
+        fixture_text("orchestrator_skill_3f2c3ef.txt"),
+        None,
+    )
+
+    assert [each_finding.scope for each_finding in all_findings] == ["Oversee delegated work"]
+    assert (
+        'section "Oversee delegated work" has 9 detail lines and no pointer (limit 6)'
+        in all_findings[0].message
+    )
+    assert "reference/oversee-delegated-work.md" in all_findings[0].message
+
+
+def test_calibration_new_orchestrator_passes_with_largest_unpointed_section_at_five() -> None:
+    text = fixture_text("orchestrator_skill_98f45b1.txt")
+    all_unpointed_counts = [
+        each_scan.detail_line_count
+        for each_scan in scan_sections(text)
+        if not each_scan.has_pointer
+    ]
+
+    assert max(all_unpointed_counts) == 5
+    assert file_findings(default_policy(), ORCHESTRATOR_PATH, text, None) == ()
+
+
+@pytest.mark.parametrize(
+    ("pattern", "relative_path", "is_expected_match"),
+    [
+        ("**/SKILL.md", "SKILL.md", True),
+        ("**/SKILL.md", "a/SKILL.md", True),
+        ("**/SKILL.md", "a/b/SKILL.md", True),
+        ("**/SKILL.md", "a/SKILL.md.bak", False),
+        ("packages/claude-dev-env/rules/*.md", "packages/claude-dev-env/rules/a.md", True),
+        ("packages/claude-dev-env/rules/*.md", "packages/claude-dev-env/rules/deep/a.md", False),
+        ("**/skills-archived/**", "x/skills-archived/a/b/SKILL.md", True),
+        ("skill-archive/**", "skill-archive/a/SKILL.md", True),
+        ("skill-archive/**", "other/skill-archive/a/SKILL.md", False),
+    ],
+)
+def test_glob_matches_whole_repository_relative_paths(
+    pattern: str, relative_path: str, is_expected_match: bool
+) -> None:
+    assert path_matches_pattern(pattern, relative_path) is is_expected_match
+
+
+def test_first_matching_kind_wins_and_a_skipped_kind_hides_the_path() -> None:
+    policy = parse_policy(policy_text())
+
+    assert context_kind_for_path(policy, "pkg/skills-archived/old/SKILL.md") is None
+    skill_kind = context_kind_for_path(policy, "pkg/live/SKILL.md")
+    assert skill_kind is not None and skill_kind.name == "skill entry"
+    assert context_kind_for_path(policy, "docs/notes.md") is None
+
+
+def test_section_rule_counts_detail_and_skips_tables_link_lists_and_frontmatter() -> None:
+    text = (
+        "---\nname: x\ndescription: y\nmore: z\nand: w\nkeys: v\nhere: u\nlast: t\n---\n"
+        "# Title\n"
+        "| a | b |\n| - | - |\n| 1 | 2 |\n| 3 | 4 |\n| 5 | 6 |\n| 7 | 8 |\n| 9 | 0 |\n"
+        "- [one](https://example.com/one)\n- [two](https://example.com/two)\n"
+        "- [three](https://example.com/three)\n1. [four](https://example.com/four)\n"
+        "- [five](https://example.com/five)\n- [six](https://example.com/six)\n"
+        "- [seven](https://example.com/seven)\n"
+    )
+
+    all_scans = scan_sections(text)
+
+    assert [(each.heading, each.detail_line_count, each.has_pointer) for each in all_scans] == [
+        ("(top)", 0, False),
+        ("Title", 0, False),
+    ]
+
+
+def test_fenced_lines_count_as_detail_and_hide_headings_and_links() -> None:
+    text = "## Example\n```bash\n# not a heading\nrun [x](ref.md)\n\nmore\n```\n"
+
+    all_scans = scan_sections(text)
+
+    assert [(each.heading, each.detail_line_count, each.has_pointer) for each in all_scans] == [
+        ("(top)", 0, False),
+        ("Example", 5, False),
+    ]
+
+
+def test_relative_link_is_a_pointer_and_external_or_anchor_links_are_not() -> None:
+    pointed = section_text("Plan", 9, "Read [the plan](reference/plan.md).")
+    external = section_text(
+        "Plan", 9, "See [site](https://example.com) and [here](#plan) and [m](mailto:a@b.c)."
+    )
+
+    assert scan_sections(pointed)[1].has_pointer is True
+    assert scan_sections(external)[1].has_pointer is False

package/hooks/features/write-edit-blocking.md

@@ -6,11 +6,13 @@ This family decides whether an agent's file mutation can run.
 
 - `blocking/pre_tool_use_dispatcher.py` runs its native description check and returns one permission decision.
 - `blocking/state_description_blocker.py` rejects historical or comparative prose in supported comments, docstrings, and Markdown.
+- `blocking/context_budget_blocker.py` rejects a write that grows a skill entry, `AGENTS.md`, `CLAUDE.md`, or rule file past its context budget.
 
 ## When it fires
 
 - `blocking/pre_tool_use_dispatcher.py` runs on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds in `hooks.json`.
 - `blocking/state_description_blocker.py` runs through the dispatcher's native evaluator on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds. Its evaluator checks `Write`, `Edit`, and `MultiEdit` payloads and skips `apply_patch`.
+- `blocking/context_budget_blocker.py` runs inside that dispatcher as a blocking hosted entry on `PreToolUse`, matcher `Write|Edit|MultiEdit|apply_patch`, timeout `60` seconds. It reads `.claude/context-budget.json` from the edited file's own repository.
 
 ## Proving it
 
@@ -19,11 +21,13 @@ Preconditions:
 - Run each command from the repository root with Python and pytest available. The tests use disposable paths where they need files.
 
 - **Dispatcher decision.** Input is a clean Write payload. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pre_tool_use_dispatcher.py -q`. The adjacent test checks that the dispatcher allows clean writes and carries denials from its checks.
+- **Context budget gate.** Input is a Write of the orchestrator skill at commit `3f2c3ef`, then at `98f45b1`. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_context_budget_blocker.py -q`. The adjacent test observes a denial naming "Oversee delegated work" for the first and an allow for the second.
 - **Description gate.** Input is a Write containing historical prose in a Python comment. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_state_description_blocker.py -q`. The adjacent test observes a denial reason.
 
 ## Gotchas
 
-- `ALL_HOSTED_HOOK_ENTRIES` is empty. The dispatcher calls the description evaluator through its native hook table.
+- `ALL_HOSTED_HOOK_ENTRIES` lists the blocking context budget gate. The dispatcher calls the description evaluator through its native hook table.
+- The context budget gate denies only what an edit adds. A repository with no policy file uses built-in kinds and treats the file's current text as its baseline entry, so a file under its line limit may grow to the limit and a file over it may only shrink. The CI ratchet runs in `scripts/policy_lint/adapter_context_budget.py`, never in the hook. See the [context budget reference](../../.agents/skills/build-eval/reference/context-budget.md).
 - The dispatcher runs hosted entries in roster order. A hosted advisory crash stays silent; a native blocking check can deny the write.
 - `scripts/policy_lint/adapter_detectors.py` also loads `blocking/state_description_blocker.py`. Check that adapter when changing its evaluator.
 - `bin/install.mjs` names folded and retired script paths so reinstall can remove stale registrations.