claude-dev-env 8.10.0 → 8.11.0

package/hooks/lifecycle/test_nested_project_hooks.py

@@ -0,0 +1,251 @@
+"""Behavior tests for the nested project hooks forwarder.
+
+Each case builds a session directory that holds child checkouts, runs the hook
+script the way Claude Code does (payload on stdin, ``CLAUDE_PROJECT_DIR`` set
+to the session directory), and reads the exit code and output it produces.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import subprocess
+import sys
+
+import pytest
+
+HOOK_SCRIPT_PATH = pathlib.Path(__file__).parent / "nested_project_hooks.py"
+BLOCKING_EXIT_CODE = 2
+
+
+def _make_checkout(
+    session_directory: pathlib.Path,
+    checkout_name: str,
+    all_hook_groups_by_event: dict[str, list[dict[str, object]]],
+) -> pathlib.Path:
+    checkout_directory = session_directory / checkout_name
+    (checkout_directory / ".git").mkdir(parents=True)
+    settings_directory = checkout_directory / ".claude"
+    settings_directory.mkdir()
+    (settings_directory / "settings.json").write_text(
+        json.dumps({"hooks": all_hook_groups_by_event}), encoding="utf-8"
+    )
+    return checkout_directory
+
+
+def _command_group(matcher: str, command: str) -> dict[str, object]:
+    return {"matcher": matcher, "hooks": [{"type": "command", "command": command}]}
+
+
+def _run_hook(
+    session_directory: pathlib.Path, payload: dict[str, object]
+) -> subprocess.CompletedProcess[str]:
+    hook_environment = dict(os.environ)
+    hook_environment["CLAUDE_PROJECT_DIR"] = str(session_directory)
+    return subprocess.run(
+        [sys.executable, str(HOOK_SCRIPT_PATH)],
+        input=json.dumps(payload),
+        capture_output=True,
+        text=True,
+        env=hook_environment,
+        check=False,
+        timeout=60,
+    )
+
+
+def _pre_tool_use_payload(tool_name: str) -> dict[str, object]:
+    return {"hook_event_name": "PreToolUse", "tool_name": tool_name, "tool_input": {}}
+
+
+def _session_start_payload() -> dict[str, object]:
+    return {"hook_event_name": "SessionStart", "source": "startup"}
+
+
+def test_should_run_a_child_session_start_hook_inside_that_child(
+    tmp_path: pathlib.Path,
+) -> None:
+    record_path = tmp_path / "record.txt"
+    checkout_directory = _make_checkout(
+        tmp_path / "session",
+        "alpha",
+        {
+            "SessionStart": [
+                _command_group(
+                    "",
+                    f'echo "$CLAUDE_PROJECT_DIR|$(pwd)" > "{record_path}"',
+                )
+            ]
+        },
+    )
+
+    completed_process = _run_hook(tmp_path / "session", _session_start_payload())
+
+    assert completed_process.returncode == 0
+    resolved_checkout = str(checkout_directory.resolve())
+    project_directory, working_directory = (
+        record_path.read_text(encoding="utf-8").strip().split("|")
+    )
+    assert str(pathlib.Path(project_directory).resolve()) == resolved_checkout
+    assert str(pathlib.Path(working_directory).resolve()) == resolved_checkout
+
+
+def test_should_carry_child_session_start_output_as_additional_context(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"SessionStart": [_command_group("", "echo alpha is ready")]},
+    )
+    _make_checkout(
+        tmp_path,
+        "beta",
+        {"SessionStart": [_command_group("", "echo beta is ready")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _session_start_payload())
+
+    assert completed_process.returncode == 0
+    hook_output = json.loads(completed_process.stdout)
+    additional_context = hook_output["hookSpecificOutput"]["additionalContext"]
+    assert hook_output["hookSpecificOutput"]["hookEventName"] == "SessionStart"
+    assert "alpha is ready" in additional_context
+    assert "beta is ready" in additional_context
+    assert additional_context.index("alpha") < additional_context.index("beta")
+
+
+def test_should_block_a_tool_call_when_a_child_hook_exits_two(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("Bash", "echo the gate refused this >&2; exit 2")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == BLOCKING_EXIT_CODE
+    assert "the gate refused this" in completed_process.stderr
+
+
+def test_should_pass_a_child_deny_decision_through(tmp_path: pathlib.Path) -> None:
+    deny_output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": "no receipt for this commit",
+        }
+    }
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {
+            "PreToolUse": [
+                _command_group(
+                    "Bash|mcp__github__merge_pull_request",
+                    f"echo '{json.dumps(deny_output)}'",
+                )
+            ]
+        },
+    )
+
+    completed_process = _run_hook(
+        tmp_path, _pre_tool_use_payload("mcp__github__merge_pull_request")
+    )
+
+    assert completed_process.returncode == 0
+    assert json.loads(completed_process.stdout) == deny_output
+
+
+def test_should_not_forward_a_child_allow_decision(tmp_path: pathlib.Path) -> None:
+    allow_output = {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "allow",
+        }
+    }
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("", f"echo '{json.dumps(allow_output)}'")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout.strip() == ""
+
+
+def test_should_skip_a_child_hook_whose_matcher_names_another_tool(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("Write|Edit", "exit 2")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+
+
+def test_should_do_nothing_when_the_session_directory_is_a_checkout(
+    tmp_path: pathlib.Path,
+) -> None:
+    (tmp_path / ".git").mkdir()
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("", "exit 2")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+    assert completed_process.stdout.strip() == ""
+
+
+def test_should_skip_a_child_directory_that_is_not_a_checkout(
+    tmp_path: pathlib.Path,
+) -> None:
+    checkout_directory = _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("", "exit 2")]},
+    )
+    (checkout_directory / ".git").rmdir()
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+
+
+def test_should_let_the_call_through_when_a_child_hook_fails_to_start(
+    tmp_path: pathlib.Path,
+) -> None:
+    _make_checkout(
+        tmp_path,
+        "alpha",
+        {"PreToolUse": [_command_group("", "a-command-that-does-not-exist")]},
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0
+
+
+@pytest.mark.parametrize("unreadable_settings", ["{not json", "[]", '{"hooks": []}'])
+def test_should_skip_a_child_whose_settings_cannot_be_read(
+    tmp_path: pathlib.Path, unreadable_settings: str
+) -> None:
+    checkout_directory = _make_checkout(tmp_path, "alpha", {})
+    (checkout_directory / ".claude" / "settings.json").write_text(
+        unreadable_settings, encoding="utf-8"
+    )
+
+    completed_process = _run_hook(tmp_path, _pre_tool_use_payload("Bash"))
+
+    assert completed_process.returncode == 0

package/hooks/test_followup_ledger.py

@@ -1,6 +1,7 @@
 """Behavior tests for the non-breaking-finding follow-up ledger."""
 
 import json
+import subprocess
 import sys
 from pathlib import Path
 
@@ -82,6 +83,23 @@ def test_record_followup_finding_writes_one_json_object_per_line(tmp_path: Path)
     assert json.loads(all_lines[0])["rule_id"] == "instruction-mode"
 
 
+def test_a_recorded_ledger_stays_out_of_git_status(tmp_path: Path) -> None:
+    subprocess.run(["git", "init", "--quiet", str(tmp_path)], check=True)
+
+    record_followup_finding(
+        tmp_path, FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong mode")
+    )
+
+    status_result = subprocess.run(
+        ["git", "-C", str(tmp_path), "status", "--porcelain", "--untracked-files=all"],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    assert followup_ledger_path(tmp_path).is_file()
+    assert status_result.stdout == ""
+
+
 def test_record_followup_finding_swallows_a_write_failure(tmp_path: Path) -> None:
     blocking_file = tmp_path / ".claude"
     blocking_file.write_text("not a directory", encoding="utf-8")

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.10.0",
+    "version": "8.11.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {
@@ -27,6 +27,7 @@
         "_shared/",
         "audit-rubrics/",
         "codex-rules/",
+        "pstack-codex-models.md",
         "AGENTS.md",
         ".claude/CLAUDE.md",
         "!**/__pycache__/**",

package/pstack-codex-models.md

@@ -0,0 +1,37 @@
+# pstack model configuration
+
+feature, refactoring: gpt-6-sol
+bug-fix: gpt-6-astra
+perf-issue: gpt-6-sol
+hillclimb: gpt-6-sol
+judgment and prose: gpt-6-astra
+strongest judgment: gpt-6-astra
+how explorer: gpt-6-luna
+how explainer: gpt-6-luna
+why investigators: gpt-6-luna
+why synthesizer: gpt-6-luna
+reflect tooling: gpt-6-sol
+reflect judgment, divergent, synthesizer: gpt-6-astra
+arena runners: gpt-6-astra, gpt-6-sol, gpt-6-luna
+arena cross-judge pool: gpt-6-astra, gpt-6-sol, gpt-6-luna
+swarm workers: gpt-6-luna
+architect runners: gpt-6-astra, gpt-6-sol, gpt-6-luna
+interrogate reviewers: gpt-6-astra, gpt-6-sol, gpt-6-luna
+
+## Reasoning effort
+
+Single-model Luna roles use max. Astra roles use low. Sol roles use medium.
+Panel entries use low, max, xhigh in the listed order.
+Keep duplicate panel entries. Each entry specifies one candidate.
+The cross-judge pool retains the effort paired with each entry.
+
+Apply these substitutions once to incoming model requests:
+- Sol medium through Luna max requests use gpt-6-luna with max effort.
+- Sol high or higher requests use gpt-6-astra with low effort.
+- Terra requests use gpt-6-luna with xhigh effort.
+- Existing Luna requests use gpt-6-luna with high effort.
+
+Explicit role and panel settings above take precedence over substitutions.
+Do not apply substitutions again to their output.
+
+session hook: on

package/rules/bdd.md

@@ -13,7 +13,7 @@
 1. **Deliberate Discovery** — Reduce uncertainty before code; surface what you do not know (Smart & Molak §5.4).
 2. **Illustrate** — Explore goals, constraints, and concrete examples in chat; "given … when … then …" style outcomes.
 3. **Formulate** — Express behavior as narrow **"should …"** specifications the user can approve.
-4. **Automate** — Build each formulated behavior through the TDD inner loop: CODE_RULES §8, red-green-refactor, canonical as stated in [`code-standards.md`](code-standards.md).
+4. **Automate** — Build each formulated behavior with tests. Red-green-refactor is the default loop, and the TDD skill (`pstack:tdd`) carries it: CODE_RULES §8, as stated in [`code-standards.md`](code-standards.md). A prototype may run ahead of its tests and adds them before the pull request goes ready.
 
 Conversation is the essential practice: if discovery is skipped, structured formats do not rescue the workflow (Minimal BDD).
 

package/rules/build-needs-a-user.md

@@ -0,0 +1,53 @@
+# Build Needs a User
+
+**When this applies:** Before you build a new tool, script, hook, gate, skill,
+command, or workflow step. That includes a hook or check built to answer a
+correction.
+
+## Rule
+
+Answer three questions before the first line of the build:
+
+1. **Who calls it?** Name the hook entry, workflow step, skill, command, or
+   module that will run it in this same change.
+2. **When does it first run?** Name the date or the event of first use.
+3. **When was this job last done by hand?** Name the last time, and how often it
+   comes up.
+
+Build when all three have a concrete answer. When the only answer is "it might
+help" or "we could use it later", stop and send the owner one line: what the
+build is for and which question has no answer. Keep the rest of the task moving
+while that line waits.
+
+Search first, per [`prefer-existing-tools.md`](prefer-existing-tools.md). A
+tool that already exists answers the need, and the build is the glue.
+
+## Size the first build to the first use
+
+Build the smallest version that serves the first caller. A correction starts
+as a row in a rule file. It becomes a hook or a lint only when the same
+correction arrives a second time, per
+[`correction-lens.md`](correction-lens.md).
+
+## Where it is enforced
+
+The staged policy lint's `uncalled-new-file` rule reads each code file a change
+adds under `scripts/`, `hooks/`, or `bin/`. It reports the file when its name
+appears only in its own tests, `CHANGELOG.md`, `README.md`, and
+`bin/ever-shipped-skills.mjs`. CI runs that lint against the merge base, so a
+file with no caller turns the pull request red.
+
+## Why
+
+The history of this package holds files that lived weeks and ran never. The
+Codex compatibility watcher shipped 502 lines and 599 lines of tests in July,
+and PR 1488 deleted it in September. Its own test was the only file that named
+it.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`prefer-existing-tools.md`](prefer-existing-tools.md) | Search before you build |
+| [`correction-lens.md`](correction-lens.md) | A repeated correction moves up a layer |
+| [`archiving-agent-config.md`](archiving-agent-config.md) | How an unused capability leaves service |

package/rules/code-standards.md

@@ -18,7 +18,7 @@ Load `CODE_RULES.md` when reviewing a PR, resolving a policy conflict, or genera
 
 Two standards live in `CODE_RULES.md` in full:
 
-- **TDD** — CODE_RULES §8 / AGENTS Tests: red, green, refactor; no production code before a failing test.
+- **TDD** — CODE_RULES §8: red, green, refactor is the default loop for a bug fix and for new behavior, and the TDD skill (`pstack:tdd`) carries the procedure. A prototype may run ahead of its tests and adds them before the pull request goes ready. A bug fix ships with a test that reproduces the bug.
 - **Right-sized engineering** — CODE_RULES §7 / AGENTS Design: functions over classes; concrete over abstract; add an abstraction at the commit that introduces its second concrete implementation. That count is a house call, one occurrence earlier than the rule of three Fowler credits to Don Roberts. The direction comes from the literature; the number does not, so read it as this package's setting rather than as a cited standard.
 
 BDD is the outer process and TDD is the inner loop: [`bdd.md`](bdd.md) discovers and formulates the behavior a feature needs, then each formulated behavior is built through the TDD cycle.

package/rules/flag-non-breaking-findings.md

@@ -108,6 +108,13 @@ naming a file that does not exist, an env-var row naming a file that never
 reads the variable, a test outside the testpaths allowlist, and a tracked
 secret.
 
+`scripts/cde_lint.py` splits the policy-lint findings the same way.
+`SEVERITY_BY_CHECK_ID` in `scripts/policy_lint/config/check_catalog_constants.py`
+carries one row per smell, and a check id with no row reads as breaking. Three
+checks are smells there: `test-pairing` and the two paired-test coverage
+checks. The lint prints each as a warning, records it in the ledger, and exits
+zero when no error remains.
+
 ## Sibling rules
 
 | Rule | Role |

package/rules/paired-test-coverage.md

@@ -20,6 +20,8 @@ When you add a public function to a module whose test suite already exercises th
 
 Two complementary checks in `code_rules_paired_test.py` reach changed files through `code_rules_enforcer.py`, which the staged policy lint runs under its `code-rules` rule. No write-time hook runs them, so CI is where they report, against the merge base. The two checks cover the two write orders.
 
+Both checks record smells, per [`flag-non-breaking-findings.md`](flag-non-breaking-findings.md). `SEVERITY_BY_CHECK_ID` in `scripts/policy_lint/config/check_catalog_constants.py` declares `code-rules/paired-test-missing-function` and `code-rules/paired-test-omitted-function` as smells. The lint prints each finding as a warning, records it in `.claude/followups/smells.jsonl`, and exits zero when every finding is a warning. A later pull request adds the missing tests.
+
 `check_public_function_missing_paired_test` runs on a production Python write or edit and flags a public function when all of these hold:
 
 1. The target is production code — not a test module, hook infrastructure, config module, migration, workflow registry, or `__init__.py`.
@@ -33,8 +35,8 @@ A public function counts as covered when its name appears — imported, called,
 
 ## Relationship to the file-level TDD order
 
-`tdd_enforcer.py` once required a fresh test file to exist before a production module was written, judging coverage one file at a time. Nothing runs it now, and the staged policy lint carries no replacement, so the test-first order is yours to hold. This check judges coverage one function at a time for a module that already carries such a test file. Write the test file first, and the lint then reports any public function that file leaves uncovered.
+No hook or lint checks the order in which a test and its module are written. Red-green-refactor is the default loop, and the TDD skill (`pstack:tdd`) carries it; a prototype may run ahead of its tests and adds them before the pull request goes ready. This check judges coverage one function at a time for a module that already carries a stem-matched test file, and reports any public function that file leaves uncovered.
 
 ## Why this check is mechanical
 
-A public function with no test reads as covered when the module's test file sits right beside it and exercises its siblings. The gap survives review because the suite looks complete. Running the lint on every staged change keeps the module's public surface and its test suite in step.
+A public function with no test reads as covered when the module's test file sits right beside it and exercises its siblings. The gap survives review because the suite looks complete. Running the lint on every staged change records each gap in the follow-up ledger, where `cde followup list` names it until a pull request closes it.

package/rules/testing.md

@@ -25,4 +25,8 @@ Tests exercise production behavior, production data, and production code paths.
 
 ## No Gate Holds the Test-First Order
 
-`tdd_enforcer.py` once required a fresh, failing test before a production module was written. Nothing runs it now, and the staged policy lint carries no replacement. Hold the red-green-refactor order yourself, and let review check it on the diff.
+Red, green, refactor is the default loop for a bug fix and for new behavior. The TDD skill (`pstack:tdd`) carries the procedure, and no hook or lint checks the order. A prototype may run ahead of its tests and adds them before the pull request goes ready. A bug fix ships with a test that reproduces the bug. Review reads the tests on the diff.
+
+## A Fix Carries Its Proof Test
+
+The `Fix test proof` job in `.github/workflows/pr-check.yml` runs `_shared/pr-loop/scripts/fix_pr_test_proof.py` on every pull request whose title starts with `fix`. A fix that changes production code must change at least one Python test that fails on the base and passes on the head. A fix that changes only docs or CI config passes. Version one reads Python tests only, so a fix proven by a JavaScript or PowerShell test needs a Python test beside it.

package/scripts/cde_lint.py

@@ -11,11 +11,24 @@ from typing import Never, TextIO
 
 from policy_lint.config.constants import INVALID_INPUT_EXIT_CODE
 from policy_lint.engine import lint
-from policy_lint.model import LintReport, LintRequest, SelectionKind, TextDocument
+from policy_lint.model import (
+    LintReport,
+    LintRequest,
+    SelectionKind,
+    Severity,
+    TextDocument,
+)
 from policy_lint.render import ReportFormat, render
 from policy_lint.selection import SelectionRunFatal
 from policy_lint.selection_git import GitSelectionError, git_bytes_for
 
+_hooks_directory = str(Path(__file__).resolve().parents[1] / "hooks")
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from followup_ledger import FollowupFinding, head_commit, record_followup_finding
+from hooks_constants.followup_ledger_constants import SEVERITY_SMELL
+
 
 class _LintUsageError(ValueError):
     """Raised when command arguments cannot form a source selection."""
@@ -201,6 +214,38 @@ def _write_invalid_input(error: Exception, stderr: TextIO) -> int:
     return INVALID_INPUT_EXIT_CODE
 
 
+def _record_warning_followups(report: LintReport, repository_root: Path) -> None:
+    """Append each warning in the report to the repository's follow-up ledger.
+
+    Args:
+        report: The findings this run produced.
+        repository_root: The repository whose ledger receives the warnings.
+    """
+    all_warnings = [
+        each_diagnostic
+        for each_diagnostic in report.diagnostics
+        if each_diagnostic.severity is Severity.WARNING
+    ]
+    if not all_warnings:
+        return
+    origin_commit = head_commit(repository_root)
+    for each_warning in all_warnings:
+        file_path = (
+            "" if each_warning.location is None else each_warning.location.path.as_posix()
+        )
+        record_followup_finding(
+            repository_root,
+            FollowupFinding(
+                each_warning.rule_id,
+                file_path,
+                each_warning.message,
+                each_warning.check_id or each_warning.rule_id,
+                SEVERITY_SMELL,
+                origin_commit,
+            ),
+        )
+
+
 def _render_lint(
     all_arguments: Sequence[str],
     repository_root: Path,
@@ -212,6 +257,7 @@ def _render_lint(
         all_arguments, stdin, repository_root, lint_runner
     )
     stdout.write(render(report, report_format))
+    _record_warning_followups(report, repository_root)
     return report.exit_code
 
 

package/scripts/policy_lint/adapter_callers.py

@@ -0,0 +1,124 @@
+"""Report a new code file that nothing outside its own tests calls.
+
+A script, hook or skill script earns its place when something runs it: a
+``hooks.json`` entry, a workflow step, a skill or command, or an import from
+live code. A file whose only mention is its own test ships work nobody uses.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path, PurePosixPath
+
+from .config import constants
+from .model import Diagnostic, Document, DocumentSet, Location, SelectionKind, Severity
+
+
+def _is_test_path(path: PurePosixPath) -> bool:
+    return (
+        path.name.startswith("test_")
+        or path.stem.endswith("_test")
+        or ".test." in path.name
+        or "tests" in path.parts
+        or "test" in path.parts
+    )
+
+
+def _is_new_code_file(document: Document) -> bool:
+    if document.prior_text is not None or document.prior_path is not None:
+        return False
+    path = document.path
+    if path.suffix.lower() not in constants.ALL_CALLED_CODE_SUFFIXES:
+        return False
+    if path.name in constants.ALL_UNCALLED_EXEMPT_FILE_NAMES or _is_test_path(path):
+        return False
+    normalized_path = f"/{path.as_posix()}"
+    return any(
+        each_segment in normalized_path
+        for each_segment in constants.ALL_CALLED_CODE_SEGMENTS
+    )
+
+
+def _is_caller_source(
+    relative_path: PurePosixPath, all_candidate_paths: frozenset[PurePosixPath]
+) -> bool:
+    if constants.ALL_CALLER_SEARCH_SKIPPED_DIRECTORIES.intersection(
+        relative_path.parts
+    ):
+        return False
+    if relative_path.name in constants.ALL_INVENTORY_FILE_NAMES:
+        return False
+    return relative_path not in all_candidate_paths and not _is_test_path(
+        relative_path
+    )
+
+
+def _read_caller_text(file_path: Path) -> str:
+    try:
+        return file_path.read_text("utf-8")
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
+def _caller_texts(
+    repository_root: Path, all_candidate_paths: frozenset[PurePosixPath]
+) -> tuple[str, ...]:
+    return tuple(
+        _read_caller_text(each_path)
+        for each_path in repository_root.rglob("*")
+        if each_path.is_file()
+        and _is_caller_source(
+            PurePosixPath(each_path.relative_to(repository_root).as_posix()),
+            all_candidate_paths,
+        )
+    )
+
+
+def _has_caller(document: Document, all_caller_texts: tuple[str, ...]) -> bool:
+    name_pattern = re.compile(
+        constants.CALLER_NAME_PATTERN_TEMPLATE.format(
+            name=re.escape(document.path.stem)
+        )
+    )
+    return any(name_pattern.search(each_text) for each_text in all_caller_texts)
+
+
+def _uncalled_diagnostic(document: Document) -> Diagnostic:
+    return Diagnostic(
+        constants.UNCALLED_NEW_FILE_RULE_ID,
+        Severity.ERROR,
+        constants.UNCALLED_NEW_FILE_MESSAGE.format(file_name=document.path.name),
+        Location(document.path, 1, 1),
+    )
+
+
+def uncalled_new_file_diagnostics(
+    document_set: DocumentSet,
+) -> tuple[Diagnostic, ...]:
+    """Report each new code file with no caller outside its tests.
+
+    Args:
+        document_set: Staged or base change selection.
+
+    Returns:
+        One diagnostic for each added script, hook or skill script whose name
+        appears only in tests and inventory files.
+    """
+    if document_set.selection not in {SelectionKind.STAGED, SelectionKind.BASE}:
+        return ()
+    all_new_documents = tuple(
+        each_document
+        for each_document in document_set.documents
+        if _is_new_code_file(each_document)
+    )
+    if not all_new_documents:
+        return ()
+    all_caller_texts = _caller_texts(
+        document_set.repository_root,
+        frozenset(each_document.path for each_document in all_new_documents),
+    )
+    return tuple(
+        _uncalled_diagnostic(each_document)
+        for each_document in all_new_documents
+        if not _has_caller(each_document, all_caller_texts)
+    )