claude-dev-env 8.10.0 → 8.11.0

package/scripts/policy_lint/adapter_pairing.py

@@ -5,9 +5,10 @@ from collections import Counter
 from pathlib import PurePosixPath
 
 from . import adapter_support
+from .check_catalog import severity_for_check_id
 from .config import constants
 from .config.approved_test_pairs import APPROVED_TEST_PATHS_BY_PRODUCTION_PATH
-from .model import Diagnostic, Document, DocumentSet, Location, SelectionKind, Severity
+from .model import Diagnostic, Document, DocumentSet, Location, SelectionKind
 
 
 def _is_test_path(path: PurePosixPath) -> bool:
@@ -319,9 +320,10 @@ def _changed_test_paths(document_set: DocumentSet) -> frozenset[PurePosixPath]:
 def _pairing_diagnostic(document: Document) -> Diagnostic:
     return Diagnostic(
         "test-pairing",
-        Severity.ERROR,
+        severity_for_check_id("test-pairing"),
         "Changed production file has no changed matching test",
         Location(document.path, 1, 1),
+        "test-pairing",
     )
 
 

package/scripts/policy_lint/adapter_support.py

@@ -4,7 +4,7 @@ from collections.abc import Callable, Iterable
 from pathlib import Path
 from types import ModuleType
 
-from .check_catalog import check_id_for_message
+from .check_catalog import check_id_for_message, severity_for_check_id
 from .model import Diagnostic, Document, Location, Severity
 
 HookModuleLoader = Callable[[str], ModuleType]
@@ -69,13 +69,14 @@ def _diagnostics_for_messages(
         location = (
             None if maybe_line is None else Location(document.path, maybe_line, 1)
         )
+        check_id = check_id_for_message(rule_id, each_message)
         all_diagnostics.append(
             Diagnostic(
                 rule_id,
-                Severity.ERROR,
+                severity_for_check_id(check_id),
                 each_message,
                 location,
-                check_id_for_message(rule_id, each_message),
+                check_id,
             )
         )
     return tuple(all_diagnostics)

package/scripts/policy_lint/adapters.py

@@ -9,6 +9,7 @@ from types import ModuleType
 from shared_tree_paths import resolve_shared_scripts_directory
 
 from . import (
+    adapter_callers,
     adapter_configuration,
     adapter_contrast_framing,
     adapter_detectors,
@@ -245,6 +246,20 @@ def test_pairing_diagnostics(document_set: DocumentSet) -> tuple[Diagnostic, ...
     return adapter_pairing.test_pairing_diagnostics(document_set, _hooks_module)
 
 
+def uncalled_new_file_diagnostics(
+    document_set: DocumentSet,
+) -> tuple[Diagnostic, ...]:
+    """Report new code files that nothing outside their tests calls.
+
+    Args:
+        document_set: Staged or base change selection.
+
+    Returns:
+        One diagnostic for each uncalled new file.
+    """
+    return adapter_callers.uncalled_new_file_diagnostics(document_set)
+
+
 def terminology_diagnostics(document_set: DocumentSet) -> tuple[Diagnostic, ...]:
     """Report staged prose that near-misses a newly introduced identifier.
 

package/scripts/policy_lint/check_catalog.py

@@ -21,8 +21,12 @@ from .config.check_catalog_constants import (
     ALL_BUNDLING_RULE_IDS,
     ALL_CHECK_CATALOG_ENTRIES,
     CHECK_ID_SEPARATOR,
+    SEVERITY_BREAKING,
+    SEVERITY_BY_CHECK_ID,
+    SEVERITY_SMELL,
     UNCLASSIFIED_CHECK_NAME,
 )
+from .model import Severity
 
 
 def check_id_for_message(rule_id: str, message: str) -> str:
@@ -42,3 +46,23 @@ def check_id_for_message(rule_id: str, message: str) -> str:
         if each_entry.message_marker in message:
             return rule_id + CHECK_ID_SEPARATOR + each_entry.check_name
     return rule_id + CHECK_ID_SEPARATOR + UNCLASSIFIED_CHECK_NAME
+
+
+def severity_for_check_id(check_id: str) -> Severity:
+    """Return the severity ``SEVERITY_BY_CHECK_ID`` declares for one check.
+
+    ::
+
+        "code-rules/paired-test-missing-function" -> Severity.WARNING
+        "code-rules/unclassified"                 -> Severity.ERROR
+
+    Args:
+        check_id: The identifier ``check_id_for_message`` returned.
+
+    Returns:
+        ``Severity.WARNING`` for a smell, which the lint records and passes,
+        and ``Severity.ERROR`` for every other check.
+    """
+    if SEVERITY_BY_CHECK_ID.get(check_id, SEVERITY_BREAKING) == SEVERITY_SMELL:
+        return Severity.WARNING
+    return Severity.ERROR

package/scripts/policy_lint/config/approved_test_pairs.py

@@ -6,11 +6,11 @@ APPROVED_TEST_PATHS_BY_PRODUCTION_PATH: dict[
     PurePosixPath, frozenset[PurePosixPath]
 ] = {
     PurePosixPath(
-        ".cursor/skills/verify-claude-dev-env/scripts/verify_installer_constants/constants.mjs"
+        ".agents/skills/verify/scripts/verify_installer_constants/constants.mjs"
     ): frozenset(
         {
             PurePosixPath(
-                ".cursor/skills/verify-claude-dev-env/scripts/verify-installer.test.mjs"
+                ".agents/skills/verify/scripts/verify-installer.test.mjs"
             ),
         }
     ),
@@ -21,6 +21,7 @@ APPROVED_TEST_PATHS_BY_PRODUCTION_PATH: dict[
     ),
     PurePosixPath("packages/claude-dev-env/bin/install.mjs"): frozenset(
         {
+            PurePosixPath("packages/claude-dev-env/bin/install.agents-home.test.mjs"),
             PurePosixPath("packages/claude-dev-env/bin/install.cursor-rules.test.mjs"),
         }
     ),

package/scripts/policy_lint/config/check_catalog_constants.py

@@ -56,4 +56,17 @@ ALL_CHECK_CATALOG_ENTRIES: tuple[CheckCatalogEntry, ...] = (
         "missing type annotation (CODE_RULES §6)", "missing-type-annotation"
     ),
     CheckCatalogEntry("Single-letter variable", "single-letter-variable"),
+    CheckCatalogEntry(
+        "is exercised by no test in the module's paired test suite",
+        "paired-test-missing-function",
+    ),
+    CheckCatalogEntry("but exercises nowhere", "paired-test-omitted-function"),
 )
+
+SEVERITY_BREAKING: str = "breaking"
+SEVERITY_SMELL: str = "smell"
+SEVERITY_BY_CHECK_ID: dict[str, str] = {
+    "code-rules/paired-test-missing-function": SEVERITY_SMELL,
+    "code-rules/paired-test-omitted-function": SEVERITY_SMELL,
+    "test-pairing": SEVERITY_SMELL,
+}

package/scripts/policy_lint/config/constants.py

@@ -6,6 +6,7 @@ GIT_EXECUTABLE = "git"
 UTF8_ENCODING = "utf-8"
 PATH_SEPARATOR = "/"
 ARCHIVED_SKILLS_DIRECTORY_NAME = "skill-archive"
+ARCHIVED_HOOKS_DIRECTORY_NAME = "hooks-archived"
 NUL_BYTE = b"\0"
 ALL_GIT_ROOT_ARGUMENTS = ("rev-parse", "--show-toplevel")
 ALL_GIT_HEAD_ARGUMENTS = ("rev-parse", "--verify", "HEAD")
@@ -20,6 +21,7 @@ ALL_MISSING_BLOB_ERROR_FRAGMENTS = (
     "does not exist in",
     "does not exist (at stage",
     "exists on disk, but not in",
+    ": bad file",
 )
 GIT_DIFF_ARGUMENT = "diff"
 GIT_CACHED_FLAG = "--cached"
@@ -170,3 +172,19 @@ RETIRED_HOOK_PROSE_MESSAGE = (
 )
 
 CONTRAST_FRAMING_RULE_ID = "contrast-framing"
+
+UNCALLED_NEW_FILE_RULE_ID = "uncalled-new-file"
+UNCALLED_NEW_FILE_MESSAGE = (
+    "New file {file_name} has no caller outside its tests. Wire it into a hook,"
+    " workflow, skill, command or import in this change, or drop it."
+)
+ALL_CALLED_CODE_SUFFIXES = frozenset({".py", ".mjs", ".js", ".sh", ".ps1"})
+ALL_CALLED_CODE_SEGMENTS = ("/scripts/", "/hooks/", "/bin/")
+ALL_CALLER_SEARCH_SKIPPED_DIRECTORIES = frozenset(
+    {".git", "node_modules", "__pycache__", ".venv"}
+)
+ALL_INVENTORY_FILE_NAMES = frozenset(
+    {"CHANGELOG.md", "README.md", "ever-shipped-skills.mjs"}
+)
+ALL_UNCALLED_EXEMPT_FILE_NAMES = frozenset({"__init__.py", "conftest.py"})
+CALLER_NAME_PATTERN_TEMPLATE = r"(?<![\w-]){name}(?![\w-])"

package/scripts/policy_lint/engine.py

@@ -3,7 +3,10 @@ from __future__ import annotations
 from collections.abc import Iterable, Sequence
 from pathlib import Path, PurePosixPath
 
-from .config.constants import ARCHIVED_SKILLS_DIRECTORY_NAME
+from .config.constants import (
+    ARCHIVED_HOOKS_DIRECTORY_NAME,
+    ARCHIVED_SKILLS_DIRECTORY_NAME,
+)
 from .model import (
     ChangeSetRule,
     Diagnostic,
@@ -27,7 +30,7 @@ def lint(
     """Run the selected rules on one source selection.
 
     Repository and diff selections check active code. File and editor
-    selections include archived skills.
+    selections include archived skills and archived hooks.
 
     Args:
         request: Repository root, source, and rule sets.
@@ -55,7 +58,10 @@ def lint(
 
 
 def _is_runtime_path(path: PurePosixPath) -> bool:
-    return path.parts[0] != ARCHIVED_SKILLS_DIRECTORY_NAME
+    return (
+        path.parts[0] != ARCHIVED_SKILLS_DIRECTORY_NAME
+        and ARCHIVED_HOOKS_DIRECTORY_NAME not in path.parts
+    )
 
 
 def _runtime_document_set(document_set: DocumentSet) -> DocumentSet:

package/scripts/policy_lint/model.py

@@ -341,11 +341,15 @@ class LintReport:
         """Return the process exit code for this report.
 
         Returns:
-            Zero for clean output, one for findings, or three for rule failure.
+            Zero for clean output or warnings only, one for an error finding,
+            or three for rule failure.
         """
         if self.failed_rules:
             return INCOMPLETE_EXIT_CODE
-        if self.diagnostics:
+        if any(
+            each_diagnostic.severity is Severity.ERROR
+            for each_diagnostic in self.diagnostics
+        ):
             return 1
         return 0
 

package/scripts/policy_lint/registry.py

@@ -154,6 +154,12 @@ def default_registry() -> tuple[model.Rule, ...]:
             frozenset({model.SelectionKind.STAGED, model.SelectionKind.BASE}),
             adapters.terminology_diagnostics,
         ),
+        model.ChangeSetRule(
+            "uncalled-new-file",
+            frozenset({"changed"}),
+            frozenset({model.SelectionKind.STAGED, model.SelectionKind.BASE}),
+            adapters.uncalled_new_file_diagnostics,
+        ),
         model.RepositoryRule(
             "repository-path-collision",
             frozenset({"repository"}),

package/scripts/policy_lint/selection.py

@@ -205,6 +205,8 @@ def _append_change(
     all_renamed_paths: list[tuple[PurePosixPath, PurePosixPath]],
 ) -> None:
     old_path, new_path = all_paths if status[:1] in {"R", "C"} else (all_paths[0], all_paths[0])
+    if status != "D" and (repository_root / new_path).is_symlink():
+        return
     normalized_old_path = _normalize_path(repository_root, old_path)
     normalized_new_path = _normalize_path(repository_root, new_path)
     if status == "D":

package/scripts/tests/test_cde_lint.py

@@ -396,3 +396,53 @@ def test_should_emit_only_located_diagnostics_in_editor_format(
     assert exit_code == 1
     assert "src/app.py:4:2:" in stdout_text
     assert "unlocated finding" not in stdout_text
+
+
+def test_should_exit_zero_and_record_a_followup_when_only_warnings_exist(
+    tmp_path: Path,
+) -> None:
+    warning_report = LintReport(
+        1,
+        (
+            Diagnostic(
+                "code-rules",
+                Severity.WARNING,
+                "Line 4: paired test gap",
+                Location(PurePosixPath("src/app.py"), 4, 1),
+                "code-rules/paired-test-missing-function",
+            ),
+        ),
+        (PurePosixPath("src/app.py"),),
+        ("code-rules",),
+        (),
+        (),
+    )
+    exit_code, stdout_text, _stderr_text = _run_cli(
+        ["--files", "src/app.py"],
+        lint_runner=lambda _request: warning_report,
+        repository_root=tmp_path,
+    )
+    ledger_path = tmp_path / ".claude" / "followups" / "smells.jsonl"
+    all_ledger_records = [
+        json.loads(each_line)
+        for each_line in ledger_path.read_text(encoding="utf-8").splitlines()
+    ]
+    assert exit_code == 0
+    assert "paired test gap" in stdout_text
+    assert [each_record["check_id"] for each_record in all_ledger_records] == [
+        "code-rules/paired-test-missing-function"
+    ]
+    assert all_ledger_records[0]["file_path"] == "src/app.py"
+
+
+def test_should_leave_the_ledger_absent_when_every_finding_is_an_error(
+    tmp_path: Path,
+) -> None:
+    _run_cli(
+        ["--files", "src/app.py"],
+        lint_runner=lambda _request: LintReport(
+            1, (_located_diagnostic(),), (), ("rule-a",), (), ()
+        ),
+        repository_root=tmp_path,
+    )
+    assert not (tmp_path / ".claude" / "followups" / "smells.jsonl").exists()

package/scripts/tests/test_policy_lint_rules_archive.py

@@ -118,3 +118,19 @@ def test_retirement_and_restoration_preserve_live_change_metadata(tmp_path: Path
     assert tuple(document.path for document in runtime_set.documents) == (restored_path,)
     assert runtime_set.deleted_paths == (deleted_path, retired_path)
     assert runtime_set.renamed_paths == ((restored_source, restored_path),)
+
+
+def test_archived_hook_moves_leave_the_automatic_checks(tmp_path: Path) -> None:
+    live_hook_path = PurePosixPath("packages/tool/hooks/blocking/retired_gate.py")
+    archived_hook_path = PurePosixPath("packages/tool/hooks-archived/blocking/retired_gate.py")
+    document_set = DocumentSet(
+        (Document.from_text(archived_hook_path, "archived"),),
+        SelectionKind.BASE,
+        tmp_path,
+        (),
+        ((live_hook_path, archived_hook_path),),
+    )
+    runtime_set = _runtime_document_set(document_set)
+    assert runtime_set.documents == ()
+    assert runtime_set.deleted_paths == (live_hook_path,)
+    assert runtime_set.renamed_paths == ()

package/scripts/tests/test_policy_lint_rules_callers.py

@@ -0,0 +1,126 @@
+"""Tests for the uncalled-new-file rule over a change set."""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+
+from policy_lint import adapter_callers, registry
+from policy_lint.model import (
+    ChangeSetRule,
+    ContentOrigin,
+    Document,
+    DocumentSet,
+    SelectionKind,
+)
+
+_PACKAGE = "packages/claude-dev-env"
+_NEW_SCRIPT = f"{_PACKAGE}/scripts/lonely_watcher.py"
+
+
+def _write(repository_root: Path, relative_path: str, text: str) -> None:
+    target = repository_root / relative_path
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(text, "utf-8")
+
+
+def _added(relative_path: str, prior_text: str | None = None) -> Document:
+    return Document(
+        PurePosixPath(relative_path),
+        "print('hi')\n",
+        prior_text,
+        None,
+        ContentOrigin.REVISION_DIFF,
+    )
+
+
+def _messages(
+    repository_root: Path,
+    all_documents: tuple[Document, ...],
+    selection: SelectionKind = SelectionKind.BASE,
+) -> tuple[str, ...]:
+    document_set = DocumentSet(all_documents, selection, repository_root)
+    return tuple(
+        each_diagnostic.message
+        for each_diagnostic in adapter_callers.uncalled_new_file_diagnostics(
+            document_set
+        )
+    )
+
+
+def test_should_report_a_new_script_only_its_own_test_names(tmp_path: Path) -> None:
+    _write(tmp_path, _NEW_SCRIPT, "print('hi')\n")
+    _write(
+        tmp_path,
+        f"{_PACKAGE}/scripts/tests/test_lonely_watcher.py",
+        "import lonely_watcher\n",
+    )
+    _write(tmp_path, f"{_PACKAGE}/CHANGELOG.md", "added lonely_watcher\n")
+    _write(tmp_path, f"{_PACKAGE}/README.md", "| lonely_watcher | x |\n")
+    _write(tmp_path, f"{_PACKAGE}/bin/ever-shipped-skills.mjs", "'lonely_watcher'\n")
+
+    all_messages = _messages(tmp_path, (_added(_NEW_SCRIPT),))
+
+    assert len(all_messages) == 1
+    assert "lonely_watcher" in all_messages[0]
+
+
+def test_should_pass_a_new_script_a_workflow_runs(tmp_path: Path) -> None:
+    _write(tmp_path, _NEW_SCRIPT, "print('hi')\n")
+    _write(
+        tmp_path,
+        ".github/workflows/ci.yml",
+        f"run: python {_NEW_SCRIPT}\n",
+    )
+
+    assert _messages(tmp_path, (_added(_NEW_SCRIPT),)) == ()
+
+
+def test_should_pass_a_new_hook_that_hooks_json_registers(tmp_path: Path) -> None:
+    hook_path = f"{_PACKAGE}/hooks/advisory/quiet_guard.py"
+    _write(tmp_path, hook_path, "")
+    _write(
+        tmp_path,
+        f"{_PACKAGE}/hooks/hooks.json",
+        '{"command": "python hooks/advisory/quiet_guard.py"}',
+    )
+
+    assert _messages(tmp_path, (_added(hook_path),)) == ()
+
+
+def test_should_ignore_a_file_that_existed_before_the_change(tmp_path: Path) -> None:
+    _write(tmp_path, _NEW_SCRIPT, "print('hi')\n")
+
+    assert _messages(tmp_path, (_added(_NEW_SCRIPT, "old\n"),)) == ()
+
+
+def test_should_ignore_new_tests_and_files_outside_code_folders(
+    tmp_path: Path,
+) -> None:
+    test_path = f"{_PACKAGE}/scripts/tests/test_orphan.py"
+    rule_path = f"{_PACKAGE}/rules/orphan.md"
+    _write(tmp_path, test_path, "")
+    _write(tmp_path, rule_path, "")
+
+    assert _messages(tmp_path, (_added(test_path), _added(rule_path))) == ()
+
+
+def test_should_not_count_a_longer_name_that_contains_the_stem(
+    tmp_path: Path,
+) -> None:
+    _write(tmp_path, _NEW_SCRIPT, "print('hi')\n")
+    _write(tmp_path, f"{_PACKAGE}/scripts/runner.py", "import lonely_watcher_v2\n")
+
+    assert len(_messages(tmp_path, (_added(_NEW_SCRIPT),))) == 1
+
+
+def test_should_run_on_staged_and_base_selections() -> None:
+    uncalled_rule = next(
+        each_rule
+        for each_rule in registry.default_registry()
+        if each_rule.rule_id == "uncalled-new-file"
+    )
+
+    assert isinstance(uncalled_rule, ChangeSetRule)
+    assert uncalled_rule.selections == frozenset(
+        {SelectionKind.STAGED, SelectionKind.BASE}
+    )

package/scripts/tests/test_policy_lint_rules_check_catalog.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 from pathlib import Path
 
 import pytest
-from policy_lint.check_catalog import check_id_for_message
+from policy_lint.check_catalog import check_id_for_message, severity_for_check_id
 from policy_lint.config.check_catalog_constants import (
     ALL_CHECK_CATALOG_ENTRIES,
     UNCLASSIFIED_CHECK_NAME,
@@ -71,6 +71,17 @@ ALL_MESSAGE_SAMPLES: tuple[tuple[str, str], ...] = (
         "missing-return-annotation",
     ),
     ("src/app.py:3: Single-letter variable 'p'", "single-letter-variable"),
+    (
+        "Line 45: public function 'run' is exercised by no test in the module's"
+        " paired test suite, though that suite already exercises this module",
+        "paired-test-missing-function",
+    ),
+    (
+        "app.py public function 'run' is a public function this stem-matched test"
+        " suite defines its module for but exercises nowhere, though the suite"
+        " already covers another public function in that module",
+        "paired-test-omitted-function",
+    ),
 )
 
 
@@ -149,3 +160,16 @@ def test_a_diagnostic_reports_the_check_identifier_it_carries() -> None:
     )
 
     assert diagnostic.as_dict()["check_id"] == "code-rules/constant-outside-config"
+
+
+@pytest.mark.parametrize(
+    "check_name", ("paired-test-missing-function", "paired-test-omitted-function")
+)
+def test_a_paired_test_check_reports_as_a_warning(check_name: str) -> None:
+    assert severity_for_check_id(f"{_BUNDLING_RULE_ID}/{check_name}") is Severity.WARNING
+
+
+def test_an_unclassified_check_reports_as_an_error() -> None:
+    unclassified_check_id = f"{_BUNDLING_RULE_ID}/{UNCLASSIFIED_CHECK_NAME}"
+
+    assert severity_for_check_id(unclassified_check_id) is Severity.ERROR

package/scripts/tests/test_policy_lint_rules_pairing.py

@@ -14,6 +14,7 @@ from policy_lint.model import (
     Document,
     DocumentSet,
     SelectionKind,
+    Severity,
 )
 
 _MODULE_DOCSTRING_BEFORE = '''"""Before."""
@@ -117,6 +118,17 @@ def test_pairing_requires_a_test_for_python_body_changes(tmp_path: Path) -> None
     assert len(all_diagnostics) == 1
 
 
+def test_pairing_reports_an_unpaired_change_as_a_recorded_warning(
+    tmp_path: Path,
+) -> None:
+    all_diagnostics = _pairing_diagnostics(
+        tmp_path,
+        _changed_document(_BODY_AFTER, _BODY_BEFORE),
+    )
+    assert [each.severity for each in all_diagnostics] == [Severity.WARNING]
+    assert all_diagnostics[0].check_id == "test-pairing"
+
+
 def test_pairing_rejects_python_syntax_errors_without_a_test(tmp_path: Path) -> None:
     all_diagnostics = _pairing_diagnostics(
         tmp_path,
@@ -186,10 +198,10 @@ def test_cursor_verifier_constants_require_the_changed_driver_suite(
     tmp_path: Path,
 ) -> None:
     constants_path = PurePosixPath(
-        ".cursor/skills/verify-claude-dev-env/scripts/verify_installer_constants/constants.mjs"
+        ".agents/skills/verify/scripts/verify_installer_constants/constants.mjs"
     )
     suite_path = PurePosixPath(
-        ".cursor/skills/verify-claude-dev-env/scripts/verify-installer.test.mjs"
+        ".agents/skills/verify/scripts/verify-installer.test.mjs"
     )
     constants_change = _body_change_at(constants_path)
     assert _diagnostic_paths(tmp_path, constants_change) == (constants_path,)
@@ -528,6 +540,23 @@ def test_pairing_accepts_installer_modules_with_the_cursor_rules_suite(
     assert all_paths == ()
 
 
+_INSTALLER_MODULE_PATH = PurePosixPath("packages/claude-dev-env/bin/install.mjs")
+_AGENTS_HOME_SUITE_PATH = PurePosixPath(
+    "packages/claude-dev-env/bin/install.agents-home.test.mjs"
+)
+
+
+def test_pairing_accepts_installer_module_with_the_agents_home_suite(
+    tmp_path: Path,
+) -> None:
+    all_paths = _diagnostic_paths(
+        tmp_path,
+        _body_change_at(_INSTALLER_MODULE_PATH),
+        _body_change_at(_AGENTS_HOME_SUITE_PATH),
+    )
+    assert all_paths == ()
+
+
 _COMMENT_RULES_PRODUCTION_PATH = PurePosixPath(
     "packages/claude-dev-env/hooks/blocking/code_rules_comments.py"
 )

package/scripts/tests/test_policy_lint_selection.py

@@ -285,6 +285,41 @@ def test_base_source_should_compare_merge_base_and_read_worktree_bytes(
     assert selected_document.origin == ContentOrigin.REVISION_DIFF
 
 
+def test_base_file_that_was_a_directory_at_base_should_have_no_prior_text(
+    tmp_path: Path,
+) -> None:
+    repository_root = _initialize_repository(tmp_path)
+    _commit_text(repository_root, "skills/verify/notes.md", "base-text\n")
+    _run_git(repository_root, "checkout", "--quiet", "-b", "feature")
+    _run_git(repository_root, "rm", "--quiet", "-r", "--", "skills")
+    _commit_text(repository_root, "skills", "../shared/skills\n")
+
+    document_set = select_documents(LintRequest.base(repository_root, "main"))
+    selected_document = _document_for(document_set, "skills")
+
+    assert selected_document.text == "../shared/skills\n"
+    assert selected_document.prior_text is None
+
+
+def test_base_directory_pointer_should_be_left_out_of_the_selection(
+    tmp_path: Path,
+) -> None:
+    repository_root = _initialize_repository(tmp_path)
+    _commit_text(repository_root, "shared/skills/verify/notes.md", "base-text\n")
+    _run_git(repository_root, "checkout", "--quiet", "-b", "feature")
+    try:
+        os.symlink("shared/skills", repository_root / "skills", target_is_directory=True)
+    except OSError as error:
+        pytest.skip(f"this host cannot create a directory pointer: {error}")
+    _run_git(repository_root, "add", "--", "skills")
+    _run_git(repository_root, "commit", "--quiet", "-m", "selection pointer fixture")
+
+    document_set = select_documents(LintRequest.base(repository_root, "main"))
+
+    assert "skills" not in _all_selected_paths(document_set)
+    assert "shared/skills" not in _all_selected_paths(document_set)
+
+
 def test_base_selection_records_merge_base_revision_and_staged_does_not(
     tmp_path: Path,
 ) -> None: