claude-dev-env 1.44.0 → 1.46.0

package/hooks/hooks.json

@@ -62,6 +62,16 @@
           }
         ]
       },
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/open_questions_in_plans_blocker.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "Edit",
         "hooks": [

package/hooks/hooks_constants/banned_identifiers_constants.py

@@ -1,5 +1,7 @@
 """Configuration constants for the banned-identifier check in code_rules_enforcer."""
 
+import re
+
 ALL_BANNED_IDENTIFIERS: frozenset[str] = frozenset(
     {
         "result",
@@ -26,10 +28,27 @@ ALL_BANNED_IDENTIFIERS: frozenset[str] = frozenset(
         "val",
     }
 )
+ALL_BANNED_NOUN_WORDS: frozenset[str] = frozenset(
+    {
+        "result", "results",
+        "data",
+        "output", "outputs",
+        "response", "responses",
+        "value", "values",
+        "item", "items",
+        "temp",
+    }
+)
+CAMEL_CASE_WORD_PATTERN: re.Pattern[str] = re.compile(
+    r"[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+"
+)
 MAX_BANNED_IDENTIFIER_ISSUES: int = 3
 BANNED_IDENTIFIER_MESSAGE_SUFFIX: str = (
     "use descriptive name (see CODE_RULES Naming section)"
 )
+BANNED_NOUN_WORD_MESSAGE_SUFFIX: str = (
+    "contains banned noun word - rename to a domain-specific term (see CODE_RULES §5)"
+)
 BANNED_IDENTIFIER_SKIP_ADVISORY: str = (
     "banned-identifier check skipped: file did not parse as Python"
 )

package/hooks/hooks_constants/code_rules_enforcer_constants.py

@@ -30,16 +30,20 @@ UPPER_SNAKE_CONSTANT_PATTERN = re.compile(r"^[A-Z][A-Z0-9_]*$")
 
 TYPE_CHECKING_BLOCK_PATTERN = re.compile(r"^(?P<indent>\s*)if\s+(typing\.)?TYPE_CHECKING\s*:\s*$")
 ALL_IMPORT_STATEMENT_PREFIXES: tuple[str, ...] = ("import ", "from ")
-ALL_EXEMPT_PYTHON_COMMENT_BODIES: tuple[str, ...] = (
-    "type:",
+ALL_TOKEN_ANCHORED_EXEMPT_COMMENT_BODIES: tuple[str, ...] = (
     "noqa",
     "pylint:",
     "pragma:",
+)
+ALL_TOKEN_ANCHORED_DIRECTIVE_BOUNDARY_CHARACTERS: frozenset[str] = frozenset({":"})
+ALL_FREE_FORM_EXEMPT_COMMENT_BODIES: tuple[str, ...] = (
+    "type:",
     "TODO",
     "FIXME",
     "HACK",
     "XXX",
 )
+CHAINED_INLINE_COMMENT_PATTERN = re.compile(r"#")
 ALL_JAVASCRIPT_EXEMPT_COMMENT_PREFIXES: tuple[str, ...] = (
     "// @ts-",
     "// eslint-",
@@ -88,3 +92,126 @@ BARE_EACH_TOKEN = "each"
 INLINE_COLLECTION_MIN_LENGTH = 3
 ALL_CAPS_WITH_UNDERSCORE_PATTERN = re.compile(r"^[A-Z][A-Z0-9]*(?:_[A-Z0-9]+)+$")
 DOTTED_SEGMENT_PATTERN = re.compile(r"^\.[a-z][a-z0-9_]*$")
+
+ALL_DIFF_CHANGED_OPCODE_TAGS: tuple[str, str] = ("replace", "insert")
+
+FUNCTION_LENGTH_BLOCKING_THRESHOLD: int = 60
+FUNCTION_LENGTH_BLOCKING_MESSAGE_SUFFIX: str = (
+    "exceeds blocking threshold - split into helpers (small functions: Robert C. "
+    "Martin, Clean Code Ch. 3 'Functions'; Google Python Style Guide ~40-line "
+    "function review hint)"
+)
+
+BANNED_NOUN_SPAN_FRAGMENT_TEMPLATE: str = (
+    "(binding span at line {definition_line}, spanning {line_span} lines)"
+)
+
+ALL_PYTEST_FILESYSTEM_ISOLATION_FIXTURE_NAMES: frozenset[str] = frozenset({
+    "monkeypatch",
+})
+PYTEST_USEFIXTURES_MARKER_NAME: str = "usefixtures"
+PYTEST_TEST_CLASS_NAME_PREFIX: str = "Test"
+ALL_HOME_DIRECTORY_ENV_VAR_NAMES: frozenset[str] = frozenset({
+    "HOME",
+    "USERPROFILE",
+    "XDG_CONFIG_HOME",
+    "XDG_DATA_HOME",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+})
+ALL_FILESYSTEM_HOME_PROBE_DOTTED_NAMES: frozenset[str] = frozenset({
+    "Path.home",
+    "pathlib.Path.home",
+    "tempfile.gettempdir",
+    "tempfile.gettempdirb",
+    "tempfile.gettempprefix",
+    "tempfile.mkstemp",
+    "tempfile.mkdtemp",
+    "tempfile.mktemp",
+    "tempfile.NamedTemporaryFile",
+    "tempfile.TemporaryFile",
+    "tempfile.TemporaryDirectory",
+    "tempfile.SpooledTemporaryFile",
+})
+ALL_DIR_ACCEPTING_TEMPFILE_FACTORY_DOTTED_NAMES: frozenset[str] = frozenset({
+    "tempfile.mkstemp",
+    "tempfile.mkdtemp",
+    "tempfile.mktemp",
+    "tempfile.NamedTemporaryFile",
+    "tempfile.TemporaryFile",
+    "tempfile.TemporaryDirectory",
+    "tempfile.SpooledTemporaryFile",
+})
+TEMPFILE_FACTORY_ISOLATION_DIRECTORY_KEYWORD: str = "dir"
+ALL_SHARED_TEMP_SOURCE_PROBE_DOTTED_NAMES: frozenset[str] = frozenset({
+    "tempfile.gettempdir",
+    "tempfile.gettempdirb",
+    "tempfile.gettempprefix",
+})
+EXPANDVARS_DOTTED_NAME: str = "os.path.expandvars"
+EXPANDUSER_DOTTED_NAME: str = "os.path.expanduser"
+ALL_PATHLIB_STATIC_EXPANDUSER_DOTTED_NAMES: frozenset[str] = frozenset({
+    "Path.expanduser",
+    "pathlib.Path.expanduser",
+})
+PATHLIB_EXPANDUSER_METHOD_NAME: str = "expanduser"
+ALL_PATHLIB_PATH_CONSTRUCTOR_CANONICAL_NAMES: frozenset[str] = frozenset({
+    "Path",
+    "pathlib.Path",
+})
+ALL_PROBE_ALIASABLE_CANONICAL_PREFIXES: frozenset[str] = frozenset({
+    "os",
+    "os.path",
+    "os.environ",
+    "os.getenv",
+    "pathlib",
+    "pathlib.Path",
+    "Path",
+    "tempfile",
+})
+HOME_DIRECTORY_TILDE_PREFIX: str = "~"
+ENVIRONMENT_VARIABLE_REFERENCE_PATTERN: re.Pattern[str] = re.compile(
+    r"\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?"
+)
+WINDOWS_PERCENT_VARIABLE_REFERENCE_PATTERN: re.Pattern[str] = re.compile(
+    r"%([A-Za-z_][A-Za-z0-9_]*)%"
+)
+OS_GETENV_DOTTED_NAME: str = "os.getenv"
+OS_ENVIRON_GET_DOTTED_NAME: str = "os.environ.get"
+OS_ENVIRON_DOTTED_NAME: str = "os.environ"
+ENVIRON_GET_METHOD_NAME: str = "get"
+ALL_ENVIRONMENT_GETTER_DOTTED_NAMES: frozenset[str] = frozenset({
+    OS_GETENV_DOTTED_NAME,
+    OS_ENVIRON_GET_DOTTED_NAME,
+})
+ALL_PROBE_RELEVANT_MODULE_CANONICAL_NAMES: frozenset[str] = frozenset({
+    "os",
+    "os.path",
+    "pathlib",
+    "tempfile",
+})
+ALL_CANONICAL_DOTTED_NAMES_BY_BARE_IMPORT: dict[tuple[str, str], str] = {
+    ("os.path", "expanduser"): "os.path.expanduser",
+    ("os.path", "expandvars"): "os.path.expandvars",
+    ("os", "path"): "os.path",
+    ("os", "getenv"): "os.getenv",
+    ("os", "environ"): "os.environ",
+    ("tempfile", "gettempdir"): "tempfile.gettempdir",
+    ("tempfile", "gettempdirb"): "tempfile.gettempdirb",
+    ("tempfile", "gettempprefix"): "tempfile.gettempprefix",
+    ("tempfile", "mkstemp"): "tempfile.mkstemp",
+    ("tempfile", "mkdtemp"): "tempfile.mkdtemp",
+    ("tempfile", "mktemp"): "tempfile.mktemp",
+    ("tempfile", "NamedTemporaryFile"): "tempfile.NamedTemporaryFile",
+    ("tempfile", "TemporaryFile"): "tempfile.TemporaryFile",
+    ("tempfile", "TemporaryDirectory"): "tempfile.TemporaryDirectory",
+    ("tempfile", "SpooledTemporaryFile"): "tempfile.SpooledTemporaryFile",
+    ("pathlib", "Path"): "Path",
+}
+TEST_ISOLATION_MESSAGE_SUFFIX: str = (
+    "must take a monkeypatch fixture and route HOME/TMP env reads through "
+    "monkeypatch.setenv; tmp_path / tmpdir allocate a sandbox path but do "
+    "not intercept env reads, so they leak across the suite (CODE_RULES — "
+    "see audits 2026-05-22 Theme M)"
+)

package/hooks/hooks_constants/open_questions_in_plans_blocker_constants.py

@@ -0,0 +1,35 @@
+"""Configuration constants for the open_questions_in_plans_blocker PreToolUse hook."""
+
+from __future__ import annotations
+
+from re import IGNORECASE, MULTILINE, Pattern, compile
+
+
+MARKDOWN_EXTENSION: str = ".md"
+
+PLANS_PATH_SEGMENT: str = "/.claude/plans/"
+PLANS_PATH_PREFIX: str = ".claude/plans/"
+
+PLAN_FILE_ENCODING: str = "utf-8"
+
+UNREADABLE_FILE_SYNTHETIC_CONTENT: str = "## Open Questions\n"
+
+OPEN_QUESTIONS_HEADING_PATTERN: Pattern[str] = compile(
+    r"^\s*(?:#{1,6}\s+|\*\*\s*|__\s*)open[\s_-]+questions(?:[^A-Za-z0-9]|$)",
+    IGNORECASE | MULTILINE,
+)
+
+CODE_FENCE_PATTERN: Pattern[str] = compile(r"```[\s\S]*?```")
+INLINE_CODE_PATTERN: Pattern[str] = compile(r"``[^`\n]+``|`[^`\n]+`")
+
+
+__all__ = [
+    "CODE_FENCE_PATTERN",
+    "INLINE_CODE_PATTERN",
+    "MARKDOWN_EXTENSION",
+    "OPEN_QUESTIONS_HEADING_PATTERN",
+    "PLANS_PATH_PREFIX",
+    "PLANS_PATH_SEGMENT",
+    "PLAN_FILE_ENCODING",
+    "UNREADABLE_FILE_SYNTHETIC_CONTENT",
+]

package/hooks/hooks_constants/test_open_questions_in_plans_blocker_constants.py

@@ -0,0 +1,125 @@
+"""Behavior tests for open_questions_in_plans_blocker_constants module."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+_HOOKS_ROOT = Path(__file__).resolve().parent.parent
+if str(_HOOKS_ROOT) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_ROOT))
+
+from hooks_constants import open_questions_in_plans_blocker_constants as constants_module
+
+
+def test_markdown_extension_is_lowercase_dot_md() -> None:
+    assert constants_module.MARKDOWN_EXTENSION == ".md"
+    assert "MARKDOWN_EXTENSION" in constants_module.__all__
+
+
+def test_plans_path_segment_matches_nested_plans_directory() -> None:
+    assert constants_module.PLANS_PATH_SEGMENT == "/.claude/plans/"
+    assert "PLANS_PATH_SEGMENT" in constants_module.__all__
+
+
+def test_plans_path_prefix_matches_project_local_plans_directory() -> None:
+    assert constants_module.PLANS_PATH_PREFIX == ".claude/plans/"
+    assert "PLANS_PATH_PREFIX" in constants_module.__all__
+
+
+def test_open_questions_heading_pattern_matches_atx_heading() -> None:
+    assert constants_module.OPEN_QUESTIONS_HEADING_PATTERN.search("## Open Questions\n")
+
+
+def test_open_questions_heading_pattern_matches_bold_heading() -> None:
+    assert constants_module.OPEN_QUESTIONS_HEADING_PATTERN.search("**Open Questions**\n")
+
+
+def test_open_questions_heading_pattern_matches_underscore_bold_heading() -> None:
+    assert constants_module.OPEN_QUESTIONS_HEADING_PATTERN.search("__Open Questions__\n")
+
+
+def test_open_questions_heading_pattern_is_case_insensitive() -> None:
+    assert constants_module.OPEN_QUESTIONS_HEADING_PATTERN.search("# open questions\n")
+
+
+def test_open_questions_heading_pattern_does_not_match_concatenated_word() -> None:
+    assert constants_module.OPEN_QUESTIONS_HEADING_PATTERN.search("## OpenQuestions\n") is None
+
+
+def test_open_questions_heading_pattern_does_not_match_longer_word() -> None:
+    assert constants_module.OPEN_QUESTIONS_HEADING_PATTERN.search("## Open Questionable\n") is None
+
+
+def test_open_questions_heading_pattern_in_export_list() -> None:
+    assert "OPEN_QUESTIONS_HEADING_PATTERN" in constants_module.__all__
+
+
+def test_code_fence_pattern_matches_triple_backtick_block() -> None:
+    fenced_block_sample = "```markdown\n## Open Questions\n- placeholder\n```"
+    assert constants_module.CODE_FENCE_PATTERN.fullmatch(fenced_block_sample)
+
+
+def test_code_fence_pattern_is_non_greedy_across_two_blocks() -> None:
+    two_blocks_sample = "```first```\n\n```second```"
+    all_matches = constants_module.CODE_FENCE_PATTERN.findall(two_blocks_sample)
+    assert all_matches == ["```first```", "```second```"]
+
+
+def test_code_fence_pattern_in_export_list() -> None:
+    assert "CODE_FENCE_PATTERN" in constants_module.__all__
+
+
+def test_inline_code_pattern_matches_single_backtick_span() -> None:
+    assert constants_module.INLINE_CODE_PATTERN.fullmatch("`code`")
+
+
+def test_inline_code_pattern_matches_double_backtick_span() -> None:
+    assert constants_module.INLINE_CODE_PATTERN.fullmatch("``double tick span``")
+
+
+def test_inline_code_pattern_does_not_cross_newlines() -> None:
+    """CommonMark inline-code spans cannot cross newlines. A stray opening backtick
+    followed later by another backtick must NOT be treated as a single inline-code
+    span — otherwise the inline-code stripper deletes everything between the two
+    backticks, including any text that lives on intervening lines."""
+    stray_backtick_sample = "stray `here.\n\nreal heading.\n\nmore `code`"
+    all_matches = constants_module.INLINE_CODE_PATTERN.findall(stray_backtick_sample)
+    assert all_matches == ["`code`"]
+
+
+def test_inline_code_pattern_does_not_match_span_spanning_newlines() -> None:
+    multiline_span_sample = "`opens here\nbut never closes on the same line`"
+    assert constants_module.INLINE_CODE_PATTERN.search(multiline_span_sample) is None
+
+
+def test_inline_code_pattern_in_export_list() -> None:
+    assert "INLINE_CODE_PATTERN" in constants_module.__all__
+
+
+def test_plan_file_encoding_is_utf8() -> None:
+    assert constants_module.PLAN_FILE_ENCODING == "utf-8"
+    assert "PLAN_FILE_ENCODING" in constants_module.__all__
+
+
+def test_unreadable_file_synthetic_content_triggers_heading_pattern() -> None:
+    """The synthetic content used when an existing plan file cannot be read must
+    contain a heading the open-questions regex matches. This guarantees the
+    downstream scan denies the write rather than silently passing."""
+    synthetic = constants_module.UNREADABLE_FILE_SYNTHETIC_CONTENT
+    assert constants_module.OPEN_QUESTIONS_HEADING_PATTERN.search(synthetic)
+    assert "UNREADABLE_FILE_SYNTHETIC_CONTENT" in constants_module.__all__
+
+
+def test_all_exports_enumerates_eight_public_constants_in_sorted_order() -> None:
+    expected_exports = [
+        "CODE_FENCE_PATTERN",
+        "INLINE_CODE_PATTERN",
+        "MARKDOWN_EXTENSION",
+        "OPEN_QUESTIONS_HEADING_PATTERN",
+        "PLANS_PATH_PREFIX",
+        "PLANS_PATH_SEGMENT",
+        "PLAN_FILE_ENCODING",
+        "UNREADABLE_FILE_SYNTHETIC_CONTENT",
+    ]
+    assert constants_module.__all__ == expected_exports

package/package.json

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

package/skills/_shared/pr-loop/scripts/_path_resolver.py

@@ -7,6 +7,7 @@ file is edited. Pure functions with no side effects.
 from __future__ import annotations
 
 import tempfile
+from dataclasses import dataclass
 from pathlib import Path
 
 from skills_pr_loop_constants.path_resolver_constants import (
@@ -23,6 +24,27 @@ from skills_pr_loop_constants.path_resolver_constants import (
 )
 
 
+@dataclass(frozen=True)
+class PerPrWorkspace:
+    """Resolved per-PR workspace paths for a pr-loop run.
+
+    Attributes:
+        worktree: Absolute path to the git worktree checkout.
+        diff_patch_template: A ``str.format`` template carrying a ``{loop}``
+            placeholder for the per-loop diff/patch file path.
+        outcome_xml_template: A ``str.format`` template carrying ``{number}``
+            and ``{loop}`` placeholders for the AUDIT outcome XML filename.
+        fix_outcome_xml_template: A ``str.format`` template carrying
+            ``{number}`` and ``{loop}`` placeholders for the FIX outcome XML
+            filename.
+    """
+
+    worktree: Path
+    diff_patch_template: str
+    outcome_xml_template: str
+    fix_outcome_xml_template: str
+
+
 def sanitize_branch_name(head_branch: str) -> str:
     """Replace filesystem-unsafe characters in a git branch name.
 
@@ -83,8 +105,8 @@ def slugify_pr_identity(owner: str, repo: str, pr_number: int) -> str:
 
 def per_pr_workspace(
     run_temp_dir: Path, owner: str, repo: str, pr_number: int
-) -> dict[str, object]:
-    """Build the per-PR workspace paths dict.
+) -> PerPrWorkspace:
+    """Build the per-PR workspace paths.
 
     Args:
         run_temp_dir: Run temp directory (from resolve_run_temp_dir).
@@ -93,20 +115,19 @@ def per_pr_workspace(
         pr_number: Pull request number.
 
     Returns:
-        Dict with keys:
-          - worktree: Path to the git worktree checkout
-          - diff_patch_template: str template with {loop} placeholder
-          - outcome_xml_template: str template with {number} and {loop} placeholders
-          - fix_outcome_xml_template: str template with {number} and {loop} placeholders
+        A PerPrWorkspace whose ``worktree`` is the git worktree checkout Path
+        and whose ``diff_patch_template`` / ``outcome_xml_template`` /
+        ``fix_outcome_xml_template`` are ``str.format`` templates carrying
+        ``{loop}`` (and, for the XML templates, ``{number}``) placeholders.
     """
     pr_workspace_dir = run_temp_dir / PER_PR_WORKSPACE_TEMPLATE.format(number=pr_number)
     slug = slugify_pr_identity(owner, repo, pr_number)
-    return {
-        "worktree": pr_workspace_dir / WORKTREE_DIRNAME,
-        "diff_patch_template": str(pr_workspace_dir / slug / DIFF_PATCH_TEMPLATE),
-        "outcome_xml_template": OUTCOME_XML_TEMPLATE,
-        "fix_outcome_xml_template": FIX_OUTCOME_XML_TEMPLATE,
-    }
+    return PerPrWorkspace(
+        worktree=pr_workspace_dir / WORKTREE_DIRNAME,
+        diff_patch_template=str(pr_workspace_dir / slug / DIFF_PATCH_TEMPLATE),
+        outcome_xml_template=OUTCOME_XML_TEMPLATE,
+        fix_outcome_xml_template=FIX_OUTCOME_XML_TEMPLATE,
+    )
 
 
 def outcome_xml_path(worktree_path: Path, pr_number: int, loop_number: int) -> Path:

package/skills/_shared/pr-loop/scripts/init_loop_state.py

@@ -60,8 +60,7 @@ def create_loop_state(
     run_name = build_run_name(pr_number, head_ref, is_multi_pr=is_multi_pr)
     run_temp_dir = resolve_run_temp_dir(run_name)
     workspace = per_pr_workspace(run_temp_dir, "", "", pr_number)
-    worktree_path = workspace["worktree"]
-    assert isinstance(worktree_path, Path)
+    worktree_path = workspace.worktree
 
     worktree_path.mkdir(parents=True, exist_ok=True)
     state_path = worktree_path / "loop-state.json"

package/skills/_shared/pr-loop/scripts/teardown_worktrees.py

@@ -118,10 +118,7 @@ def teardown_run(
         if not isinstance(pr_number, int):
             continue
         workspace = per_pr_workspace(run_temp_dir, str(owner), str(repo), pr_number)
-        worktree_path = workspace["worktree"]
-        if not isinstance(worktree_path, Path):
-            continue
-        if remove_worktree(worktree_path):
+        if remove_worktree(workspace.worktree):
             removed_count += 1
 
     force_rmtree(str(run_temp_dir))

package/skills/_shared/pr-loop/scripts/test__path_resolver.py

@@ -0,0 +1,57 @@
+"""Tests for _path_resolver.per_pr_workspace typed structure."""
+
+from __future__ import annotations
+
+import dataclasses
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+
+def _load_path_resolver() -> ModuleType:
+    module_path = _SCRIPTS_DIR / "_path_resolver.py"
+    spec = importlib.util.spec_from_file_location("_path_resolver", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    sys.modules["_path_resolver"] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+path_resolver = _load_path_resolver()
+
+
+def test_per_pr_workspace_returns_typed_structure_with_concrete_fields() -> None:
+    run_temp_dir = Path("/tmp/bugteam-pr-422")
+    workspace = path_resolver.per_pr_workspace(
+        run_temp_dir, "jl-cmd", "claude-code-config", 422
+    )
+    assert isinstance(workspace, path_resolver.PerPrWorkspace)
+    assert isinstance(workspace.worktree, Path)
+    assert workspace.worktree == run_temp_dir / "pr-422" / "worktree"
+    assert isinstance(workspace.diff_patch_template, str)
+    assert isinstance(workspace.outcome_xml_template, str)
+    assert isinstance(workspace.fix_outcome_xml_template, str)
+
+
+def test_per_pr_workspace_diff_patch_template_carries_loop_placeholder() -> None:
+    run_temp_dir = Path("/tmp/bugteam-pr-7")
+    workspace = path_resolver.per_pr_workspace(run_temp_dir, "owner", "repo", 7)
+    rendered = workspace.diff_patch_template.format(loop=3)
+    assert rendered.endswith("loop-3.patch")
+    assert "owner-repo-pr-7" in rendered.replace("\\", "/")
+
+
+def test_per_pr_workspace_is_frozen() -> None:
+    run_temp_dir = Path("/tmp/bugteam-pr-9")
+    workspace = path_resolver.per_pr_workspace(run_temp_dir, "owner", "repo", 9)
+    with pytest.raises(dataclasses.FrozenInstanceError):
+        workspace.worktree = Path("/tmp/other")

package/skills/_shared/pr-loop/scripts/test_init_loop_state.py

@@ -0,0 +1,48 @@
+"""Tests for init_loop_state.create_loop_state consuming the typed workspace."""
+
+from __future__ import annotations
+
+import importlib.util
+import json
+import sys
+from pathlib import Path
+from types import ModuleType
+
+import pytest
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+
+def _load_init_loop_state_module() -> ModuleType:
+    module_path = _SCRIPTS_DIR / "init_loop_state.py"
+    spec = importlib.util.spec_from_file_location("init_loop_state", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+init_loop_state = _load_init_loop_state_module()
+
+
+def test_create_loop_state_writes_state_under_typed_worktree(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """create_loop_state resolves the worktree from PerPrWorkspace.worktree and
+    writes loop-state.json inside it, with the starting SHA recorded."""
+    path_resolver_module = init_loop_state.resolve_run_temp_dir.__globals__["tempfile"]
+    monkeypatch.setattr(path_resolver_module, "gettempdir", lambda: str(tmp_path))
+    state_path = init_loop_state.create_loop_state(
+        pr_number=422,
+        head_ref="feat/branch",
+        starting_sha="abc1234",
+        is_multi_pr=False,
+    )
+    assert state_path.name == "loop-state.json"
+    assert state_path.parent.name == "worktree"
+    written_state = json.loads(state_path.read_text(encoding="utf-8"))
+    assert written_state["starting_sha"] == "abc1234"
+    assert written_state["loop_count"] == 0

package/skills/_shared/pr-loop/scripts/test_teardown_worktrees.py

@@ -0,0 +1,59 @@
+"""Tests for teardown_worktrees.teardown_run consuming the typed workspace."""
+
+from __future__ import annotations
+
+import importlib.util
+import sys
+from pathlib import Path
+from types import ModuleType
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+
+def _load_teardown_module() -> ModuleType:
+    module_path = _SCRIPTS_DIR / "teardown_worktrees.py"
+    spec = importlib.util.spec_from_file_location("teardown_worktrees", module_path)
+    assert spec is not None
+    assert spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+teardown_worktrees = _load_teardown_module()
+
+
+def test_teardown_run_returns_zero_when_no_worktrees_exist(tmp_path: Path) -> None:
+    """With absent worktrees, teardown_run removes nothing and reports zero,
+    reading each worktree path from the typed PerPrWorkspace.worktree attribute
+    rather than a dict lookup."""
+    run_temp_dir = tmp_path / "run"
+    run_temp_dir.mkdir()
+    all_pr_entries: list[dict[str, object]] = [
+        {"number": 7, "owner": "owner", "repo": "repo"},
+    ]
+    removed_count = teardown_worktrees.teardown_run(
+        run_temp_dir=run_temp_dir,
+        all_pr_entries=all_pr_entries,
+    )
+    assert removed_count == 0
+    assert not run_temp_dir.exists()
+
+
+def test_teardown_run_skips_entries_without_integer_number(tmp_path: Path) -> None:
+    """A PR entry whose number is not an integer is skipped before any workspace
+    resolution, so teardown_run reports zero removals and still clears the run
+    temp directory."""
+    run_temp_dir = tmp_path / "run"
+    run_temp_dir.mkdir()
+    all_pr_entries: list[dict[str, object]] = [
+        {"number": "not-an-int", "owner": "owner", "repo": "repo"},
+    ]
+    removed_count = teardown_worktrees.teardown_run(
+        run_temp_dir=run_temp_dir,
+        all_pr_entries=all_pr_entries,
+    )
+    assert removed_count == 0
+    assert not run_temp_dir.exists()