claude-dev-env 8.73.0 → 8.73.2

package/scripts/test_followup_cli.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import io
 import json
-import sys
 from pathlib import Path
 
 from dev_env_scripts_constants.followup_constants import (
@@ -14,11 +13,6 @@ from dev_env_scripts_constants.followup_constants import (
     FOLLOWUP_BACKLOG_THRESHOLD,
 )
 from followup_cli import main
-
-_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,
     all_recorded_findings,

package/scripts/test_resolve_worker_spawn.py

@@ -4,7 +4,6 @@ from __future__ import annotations
 
 import json
 import subprocess
-import sys
 import threading
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
@@ -12,13 +11,9 @@ from pathlib import Path
 
 import pytest
 
-_SCRIPTS_DIR = Path(__file__).resolve().parent
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
-
 import account_broker
 import invoke_code_review as invoker
-import resolve_worker_spawn as dispatcher  # noqa: E402
+import resolve_worker_spawn as dispatcher
 from dev_env_scripts_constants.account_broker_constants import (
     Account,
     BrokerConfigurationError,
@@ -28,7 +23,7 @@ from dev_env_scripts_constants.account_broker_constants import (
     ProductAdapter,
     WAIT_EXIT_CODE,
 )
-from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
+from dev_env_scripts_constants.grok_worker_constants import (
     AGENT_FLAG,
     CLI_AGENT_FLAG,
     ALL_AGENT_FILENAMES_BY_ROLE,
@@ -67,12 +62,12 @@ from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
     TIER_CLAUDE_HEADLESS,
     TIER_GROK,
 )
-import grok_headless_runner  # noqa: E402
-from grok_headless_runner import (  # noqa: E402
+import grok_headless_runner
+from grok_headless_runner import (
     GrokRunnerOutcome,
     run_headless_worker,
 )
-from grok_worker_preflight import PreflightOutcome  # noqa: E402
+from grok_worker_preflight import PreflightOutcome
 
 HOST_PROFILE_CLAUDE = "Claude"
 HOST_PROFILE_THIRD_PARTY = "ThirdParty"

package/scripts/test_setup_project_paths.py

@@ -3,23 +3,11 @@
 import inspect
 import json
 import subprocess
-import sys
 from pathlib import Path
 from unittest.mock import patch
 
 import pytest
 
-_SCRIPTS_DIR = Path(__file__).resolve().parent
-_HOOKS_DIR = _SCRIPTS_DIR.parent / "hooks"
-_SESSION_HOOKS_PACKAGE_DIR = _SCRIPTS_DIR.parent / "hooks" / "session"
-for each_sys_path_entry in (
-    str(_SCRIPTS_DIR),
-    str(_HOOKS_DIR),
-    str(_SESSION_HOOKS_PACKAGE_DIR),
-):
-    if each_sys_path_entry not in sys.path:
-        sys.path.insert(0, each_sys_path_entry)
-
 import setup_project_paths as setup
 import untracked_repo_detector as detector_module
 from hooks_constants.project_paths_reader import registry_file_path

package/scripts/test_shared_tree_paths.py

@@ -9,12 +9,8 @@ from pathlib import Path
 
 import pytest
 
-_SCRIPTS_DIR = Path(__file__).resolve().parent
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
-
-import shared_tree_paths  # noqa: E402
-from dev_env_scripts_constants.grok_worker_constants import (  # noqa: E402
+import shared_tree_paths
+from dev_env_scripts_constants.grok_worker_constants import (
     CLAUDE_CONFIG_DIR_ENV_VAR,
     PROCESS_TREE_DIRECTORY_NAME,
     PROCESS_TREE_KILL_MODULE_FILENAME,

package/scripts/test_validate_instruction_pairs.py

@@ -1,8 +1,6 @@
 import subprocess
 from pathlib import Path
 
-import sys
-
 from validate_instruction_pairs import (
     GATE_FAILED_EXIT_CODE,
     GATE_PASSED_EXIT_CODE,
@@ -10,11 +8,6 @@ from validate_instruction_pairs import (
     run_gate,
     validate_repository,
 )
-
-_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 all_recorded_findings, head_commit
 from hooks_constants.followup_ledger_constants import SEVERITY_SMELL
 

package/scripts/test_verify_installable_package.py

@@ -6,14 +6,9 @@ command walking without requiring a full npm pack on every case.
 
 from __future__ import annotations
 
-import sys
 import tarfile
 from pathlib import Path
 
-_SCRIPTS_DIR = Path(__file__).resolve().parent
-if str(_SCRIPTS_DIR) not in sys.path:
-    sys.path.insert(0, str(_SCRIPTS_DIR))
-
 import verify_installable_package as mod
 from dev_env_scripts_constants.verify_installable_package_constants import (
     CLASS_PACKAGED,

package/scripts/tests/test_contrast_framing.py

@@ -89,12 +89,12 @@ def test_form_named_rejects_an_unknown_name() -> None:
         form_named("no-such-form")
 
 
-def test_every_form_is_named_in_the_rule_document() -> None:
-    rule_text = (PACKAGE_ROOT / CONTRAST_FRAMING_RULE_DOCUMENT).read_text(
+def test_every_form_is_named_in_the_rule_guide() -> None:
+    guide_text = (PACKAGE_ROOT / CONTRAST_FRAMING_RULE_DOCUMENT).read_text(
         encoding="utf-8"
     )
     for each_form in ALL_CONTRAST_FRAMING_FORMS:
-        assert f"`{each_form.name}`" in rule_text
+        assert f"`{each_form.name}`" in guide_text
 
 
 def test_a_list_of_not_items_stays_quiet() -> None:

package/scripts/tests/test_rule_index_shape.py

@@ -1,4 +1,4 @@
-"""Each rule entry keeps the index shape, and the always-loaded entries stay inside a byte budget."""
+"""The rules index and each rule entry keep their shape, and the always-loaded rules stay inside a byte budget."""
 
 import re
 import sys
@@ -28,11 +28,16 @@ DOUBLED_WHEN_LEAD_IN_PATTERN = re.compile(
     r"^\*\*When(?: this applies)?:\*\* When\b", re.MULTILINE
 )
 
+INDEX_LINE_PATTERN = re.compile(r"^- \*\*[^*]+\*\*(?: \(\[guide\]\((\.\./docs/rule-guides/[^)#\s]+\.md)\)\))?\. \S")
+INDEX_SKILL_POINTER_PATTERN = re.compile(r"the `[a-z-]+` skill")
+
+INDEX_FILE_NAME = "index.md"
+INDEX_PATH = RULES_DIRECTORY / INDEX_FILE_NAME
 MAXIMUM_ENTRY_BYTES = 1_500
-MAXIMUM_ALWAYS_ON_BYTES = 12_000
-POINTER_ENTRY_NAMES = frozenset({"skill-pointers.md"})
+MAXIMUM_INDEX_BYTES = 4_000
+MAXIMUM_ALWAYS_ON_BYTES = 6_000
 CODEX_VERBATIM_ENTRY_NAMES = frozenset({"question-presentation.md"})
-INDEX_SHAPE_EXEMPT_ENTRY_NAMES = POINTER_ENTRY_NAMES | CODEX_VERBATIM_ENTRY_NAMES
+INDEX_SHAPE_EXEMPT_ENTRY_NAMES = CODEX_VERBATIM_ENTRY_NAMES
 CODEX_MATERIALIZED_GUIDE_NAMES = frozenset(
     Path(each_path).name for each_path in codex_instruction_rule_relative_paths
 )
@@ -43,6 +48,7 @@ def _entry_paths() -> list[Path]:
         each_path
         for each_path in RULES_DIRECTORY.glob("*.md")
         if each_path.name not in instruction_alias_filenames
+        and each_path.name != INDEX_FILE_NAME
     )
 
 
@@ -183,11 +189,59 @@ def test_each_entry_links_a_full_text_guide_that_exists() -> None:
     assert all_problems == []
 
 
+def _index_lines() -> list[str]:
+    return [
+        each_line
+        for each_line in INDEX_PATH.read_text(encoding="utf-8").splitlines()
+        if each_line.startswith("- ")
+    ]
+
+
+def _index_guide_names() -> list[str]:
+    return [
+        Path(each_match.group(1)).name
+        for each_line in _index_lines()
+        if (each_match := INDEX_LINE_PATTERN.match(each_line)) and each_match.group(1)
+    ]
+
+
+def test_each_index_line_names_a_rule_and_a_trigger() -> None:
+    malformed = [
+        each_line for each_line in _index_lines() if not INDEX_LINE_PATTERN.match(each_line)
+    ]
+    assert malformed == []
+
+
+def test_each_index_line_links_a_guide_or_names_a_skill() -> None:
+    unlinked = [
+        each_line
+        for each_line in _index_lines()
+        if not INDEX_LINE_PATTERN.match(each_line).group(1)
+        and not INDEX_SKILL_POINTER_PATTERN.search(each_line)
+    ]
+    assert unlinked == []
+
+
+def test_each_index_guide_exists() -> None:
+    missing = [
+        each_guide_name
+        for each_guide_name in _index_guide_names()
+        if not (RULE_GUIDES_DIRECTORY / each_guide_name).is_file()
+    ]
+    assert missing == []
+
+
+def test_index_stays_inside_its_byte_budget() -> None:
+    assert len(INDEX_PATH.read_bytes()) <= MAXIMUM_INDEX_BYTES
+
+
 def test_each_guide_has_exactly_one_owner() -> None:
     owners_by_guide: dict[str, list[str]] = {}
     for each_path in _entry_paths():
         for each_guide_name in _linked_guide_names(_entry_text(each_path)):
             owners_by_guide.setdefault(each_guide_name, []).append(each_path.name)
+    for each_guide_name in _index_guide_names():
+        owners_by_guide.setdefault(each_guide_name, []).append(INDEX_FILE_NAME)
     unowned = sorted(
         each_guide.name
         for each_guide in RULE_GUIDES_DIRECTORY.glob("*.md")
@@ -204,7 +258,7 @@ def test_each_guide_has_exactly_one_owner() -> None:
 
 
 def test_always_loaded_entries_stay_inside_the_total_byte_budget() -> None:
-    always_on_bytes = sum(
+    always_on_bytes = len(INDEX_PATH.read_bytes()) + sum(
         len(each_path.read_bytes())
         for each_path in _entry_paths()
         if _loads_in_every_session(_entry_text(each_path))

package/scripts/tests/test_rule_load_scopes.py

@@ -8,24 +8,9 @@ SKILLS_DIRECTORY = PACKAGE_ROOT / ".agents" / "skills"
 
 ALWAYS_ON_RULE_NAMES = frozenset(
     {
-        "asd-ste100-language.md",
-        "cleanup-temp-files.md",
         "correction-lens.md",
-        "destructive-commands.md",
-        "explore-thoroughly.md",
-        "features-start-with-an-eval.md",
-        "filesystem-search.md",
-        "memory-stores-durable-facts.md",
-        "no-contrast-framing.md",
-        "proof-before-pull-request.md",
+        "index.md",
         "question-presentation.md",
-        "research-mode.md",
-        "request-scope.md",
-        "session-title.md",
-        "skill-pointers.md",
-        "shell-invocation.md",
-        "verify-before-asking.md",
-        "verify-runtime-state.md",
     }
 )
 

package/system-prompts/software-engineer.xml

@@ -7,7 +7,7 @@
 </role>
 
 <task_scope>
-  Apply rules/asd-ste100-language.md for user-facing word choice, sentence style, tone, punctuation,
+  Apply docs/rule-guides/asd-ste100-language.md for user-facing word choice, sentence style, tone, punctuation,
   and prose form. Keep the behavior contracts below within their named scope.
   Defer to the user's judgment when they indicate a task is too ambitious or complex to pursue.
   Match the scope of every action to what the user explicitly requested: a bug fix delivers the
@@ -28,7 +28,7 @@
 <output_style>
   When a user-facing response needs beginner presentation, use ELI5: beginner framing, large
   visuals, minimal text, one stable self-contained HTML artifact, update-in-place continuity,
-  and sharing. Apply rules/asd-ste100-language.md to sentence-level prose inside that artifact.
+  and sharing. Apply docs/rule-guides/asd-ste100-language.md to sentence-level prose inside that artifact.
   Lead every response with the direct answer or result. Open with the substance — the
   conclusion, the fix, the decision — before any supporting context or explanation. Expand
   depth in proportion to the complexity of the ask: a direct question earns a sentence; a
@@ -67,7 +67,7 @@
   Reserve user questions for preferences, missing context the user holds, judgment calls, and
   scope decisions.
 
-  Source every claim as rules/research-mode.md describes.
+  Source every claim as docs/rule-guides/research-mode.md describes.
 </investigation>
 
 <problem_solving>
@@ -363,7 +363,7 @@
   Visible output is concise by default. The first progress update is one sentence.
   Later updates mark only important discoveries or direction changes. The final
   response begins with the outcome.
-  Language policy: rules/asd-ste100-language.md. This section owns visible progress,
+  Language policy: docs/rule-guides/asd-ste100-language.md. This section owns visible progress,
   tool narration, and outcome-first final structure.
 </communication_contract>
 

package/hooks/blocking/artifact_look_gate.py

@@ -1,223 +0,0 @@
-#!/usr/bin/env python3
-"""PreToolUse hook: refuse to publish an artifact page nobody has looked at.
-
-An agent that writes a page and publishes it without rendering it cannot know
-the page matches the ask. The hook walks the session transcript and allows the
-publish only when a Read opened an image file whose modification time is at
-least the page file's::
-
-    Write page.html -> shoot shot.png -> Read shot.png -> publish -> allowed
-    Write page.html -> publish                                    -> refused
-    Read shot.png -> change page.html in any tool -> publish      -> refused
-    Read an image older than the page -> publish                  -> refused
-
-A Read that returned an error, or whose result came before the page's last
-change, does not count. A non-HTML file, an asset
-upload, a non-publish action and an unreadable transcript all pass, so the
-hook never fails closed.
-"""
-
-from __future__ import annotations
-
-import json
-import sys
-from datetime import datetime
-from pathlib import Path
-
-hooks_root_directory = str(Path(__file__).resolve().parent.parent)
-if hooks_root_directory not in sys.path:
-    sys.path.insert(0, hooks_root_directory)
-
-from hooks_constants.artifact_look_gate_constants import (
-    ALL_IMAGE_FILE_SUFFIXES,
-    ALL_PAGE_FILE_SUFFIXES,
-    ARTIFACT_ACTION_INPUT_KEY,
-    ARTIFACT_ASSET_INPUT_KEY,
-    ARTIFACT_PUBLISH_ACTION,
-    ARTIFACT_TOOL_NAME,
-    ASSISTANT_ENTRY_TYPE,
-    DENY_DECISION,
-    ENTRY_TIMESTAMP_KEY,
-    FILE_PATH_INPUT_KEY,
-    IMAGE_READING_TOOL_NAME,
-    PRE_TOOL_USE_EVENT_NAME,
-    TOOL_INPUT_KEY,
-    TOOL_NAME_KEY,
-    TOOL_RESULT_BLOCK_TYPE,
-    TOOL_USE_BLOCK_TYPE,
-    TRANSCRIPT_DECODE_ERRORS,
-    TRANSCRIPT_ENCODING,
-    TRANSCRIPT_PATH_KEY,
-    UNSEEN_PAGE_REASON_TEMPLATE,
-    USER_ENTRY_TYPE,
-)
-from hooks_constants.hook_specific_output_keys import (
-    HOOK_EVENT_NAME_KEY,
-    HOOK_SPECIFIC_OUTPUT_KEY,
-    PERMISSION_DECISION_KEY,
-)
-from hooks_constants.pr_lifecycle_skill_gate_constants import (
-    PERMISSION_DECISION_REASON_KEY,
-)
-from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
-
-
-def _content_blocks(
-    all_entry_fields: dict[str, object], entry_type: str
-) -> list[dict[str, object]]:
-    if all_entry_fields.get("type") != entry_type:
-        return []
-    message = all_entry_fields.get("message")
-    content = message.get("content") if isinstance(message, dict) else None
-    if not isinstance(content, list):
-        return []
-    return [each_block for each_block in content if isinstance(each_block, dict)]
-
-
-def _parsed_entry(transcript_line: str) -> dict[str, object]:
-    try:
-        parsed_line = json.loads(transcript_line)
-    except json.JSONDecodeError:
-        return {}
-    return parsed_line if isinstance(parsed_line, dict) else {}
-
-
-def _entry_epoch(all_entry_fields: dict[str, object]) -> float | None:
-    timestamp_text = all_entry_fields.get(ENTRY_TIMESTAMP_KEY)
-    if not isinstance(timestamp_text, str):
-        return None
-    try:
-        return datetime.fromisoformat(timestamp_text.replace("Z", "+00:00")).timestamp()
-    except ValueError:
-        return None
-
-
-def _successful_result_epochs(all_entries: list[dict[str, object]]) -> dict[str, float]:
-    return {
-        str(each_block.get("tool_use_id")): result_epoch
-        for each_entry in all_entries
-        if (result_epoch := _entry_epoch(each_entry)) is not None
-        for each_block in _content_blocks(each_entry, USER_ENTRY_TYPE)
-        if each_block.get("type") == TOOL_RESULT_BLOCK_TYPE and not each_block.get("is_error")
-    }
-
-
-def _tool_calls(all_entries: list[dict[str, object]]) -> list[tuple[str, object, object]]:
-    return [
-        (str(each_block.get("id")), each_block.get("name"), tool_input.get(FILE_PATH_INPUT_KEY))
-        for each_entry in all_entries
-        for each_block in _content_blocks(each_entry, ASSISTANT_ENTRY_TYPE)
-        if each_block.get("type") == TOOL_USE_BLOCK_TYPE
-        and isinstance(tool_input := each_block.get("input"), dict)
-    ]
-
-
-def _is_image_read(tool_name: object, file_path: object) -> bool:
-    return (
-        tool_name == IMAGE_READING_TOOL_NAME
-        and isinstance(file_path, str)
-        and file_path.lower().endswith(ALL_IMAGE_FILE_SUFFIXES)
-    )
-
-
-def _modified_time(file_path: str) -> float | None:
-    try:
-        return Path(file_path).stat().st_mtime
-    except OSError:
-        return None
-
-
-def page_was_looked_at(all_transcript_lines: list[str], page_path: str) -> bool:
-    """Return True when a screenshot made after the page's last change was read.
-
-    The page's modification time covers every way it can change, including a
-    Bash command or a subagent. A Read counts only when it succeeded, its
-    result arrived after the page last changed, and its image file is at
-    least as new as the page.
-
-    Args:
-        all_transcript_lines: The session transcript, one JSON record per line.
-        page_path: The file the Artifact call publishes.
-    """
-    page_modified_time = _modified_time(page_path)
-    if page_modified_time is None:
-        return False
-    all_entries = [_parsed_entry(each_line) for each_line in all_transcript_lines]
-    result_epoch_by_id = _successful_result_epochs(all_entries)
-    for each_id, each_tool_name, each_file_path in _tool_calls(all_entries):
-        result_epoch = result_epoch_by_id.get(each_id)
-        if not _is_image_read(each_tool_name, each_file_path) or result_epoch is None:
-            continue
-        image_modified_time = _modified_time(str(each_file_path))
-        if (
-            image_modified_time is not None
-            and image_modified_time >= page_modified_time
-            and result_epoch >= page_modified_time
-        ):
-            return True
-    return False
-
-
-def _published_page_path(all_hook_fields: dict[str, object]) -> str | None:
-    tool_input = all_hook_fields.get(TOOL_INPUT_KEY)
-    if all_hook_fields.get(TOOL_NAME_KEY) != ARTIFACT_TOOL_NAME or not isinstance(tool_input, dict):
-        return None
-    page_path = tool_input.get(FILE_PATH_INPUT_KEY)
-    is_page_publish = (
-        tool_input.get(ARTIFACT_ACTION_INPUT_KEY, ARTIFACT_PUBLISH_ACTION) == ARTIFACT_PUBLISH_ACTION
-        and tool_input.get(ARTIFACT_ASSET_INPUT_KEY) is not True
-        and isinstance(page_path, str)
-        and page_path.lower().endswith(ALL_PAGE_FILE_SUFFIXES)
-    )
-    return page_path if is_page_publish else None
-
-
-def unseen_page_reason(all_hook_fields: dict[str, object]) -> str | None:
-    """Return the refusal for an unseen page publish, or None to allow it.
-
-    Args:
-        all_hook_fields: The parsed PreToolUse payload.
-    """
-    page_path = _published_page_path(all_hook_fields)
-    transcript_path = all_hook_fields.get(TRANSCRIPT_PATH_KEY)
-    if page_path is None or not isinstance(transcript_path, str):
-        return None
-    try:
-        all_transcript_lines = Path(transcript_path).read_text(
-            encoding=TRANSCRIPT_ENCODING, errors=TRANSCRIPT_DECODE_ERRORS
-        ).splitlines()
-    except OSError:
-        return None
-    if page_was_looked_at(all_transcript_lines, page_path):
-        return None
-    return UNSEEN_PAGE_REASON_TEMPLATE.format(page_path=page_path)
-
-
-def main() -> int:
-    """Read the PreToolUse payload and print a deny decision for an unseen page.
-
-    Returns:
-        0 in every case; the decision travels in the JSON output.
-    """
-    hook_payload = read_hook_input_dictionary_from_stdin()
-    if hook_payload is None:
-        return 0
-    refusal_reason = unseen_page_reason(hook_payload)
-    if refusal_reason is not None:
-        sys.stdout.write(
-            json.dumps(
-                {
-                    HOOK_SPECIFIC_OUTPUT_KEY: {
-                        HOOK_EVENT_NAME_KEY: PRE_TOOL_USE_EVENT_NAME,
-                        PERMISSION_DECISION_KEY: DENY_DECISION,
-                        PERMISSION_DECISION_REASON_KEY: refusal_reason,
-                    }
-                }
-            )
-        )
-        sys.stdout.flush()
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())