claude-dev-env 8.74.0 → 8.74.2

package/hooks/followup_ledger_maintenance.py

@@ -0,0 +1,127 @@
+"""Clear and normalize the follow-up ledger directory.
+
+``cde followup clear`` and ``cde followup dedupe`` run these. The gates that
+record findings use only ``followup_ledger``.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import NamedTuple
+
+_hooks_directory = str(Path(__file__).resolve().parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from followup_ledger import (
+    all_finding_files,
+    all_record_paths,
+    finding_from_text,
+    finding_path,
+    followup_directory,
+    record_followup_finding,
+)
+from hooks_constants.followup_ledger_constants import (
+    LEDGER_ENCODING,
+    LEGACY_LEDGER_FILE_NAME,
+)
+
+
+def clear_recorded_findings(repository_root: Path) -> None:
+    """Remove every recorded finding and any legacy ledger file.
+
+    The directory and its ``.gitignore`` stay. A file that cannot be removed
+    is left in place.
+
+    Args:
+        repository_root: The repository whose ledger to empty.
+    """
+    directory = followup_directory(repository_root)
+    all_paths = [*all_record_paths(directory), directory / LEGACY_LEDGER_FILE_NAME]
+    for each_path in all_paths:
+        try:
+            each_path.unlink(missing_ok=True)
+        except OSError:
+            continue
+
+
+class LedgerNormalization(NamedTuple):
+    """What one ``normalize_ledger`` run changed.
+
+    Attributes:
+        migrated_count: Legacy ledger lines written as finding files.
+        removed_count: Finding files removed as duplicates.
+    """
+
+    migrated_count: int
+    removed_count: int
+
+
+def normalize_ledger(repository_root: Path) -> LedgerNormalization:
+    """Move every record to the file its tracking key names.
+
+    A legacy ``smells.jsonl`` ledger is split into one file per finding and
+    removed. A finding file whose name does not match its tracking key moves
+    to the matching name, or is removed when that name already holds the
+    finding.
+
+    Args:
+        repository_root: The repository whose ledger to normalize.
+
+    Returns:
+        How many legacy lines moved and how many duplicate files left.
+    """
+    migrated_count = _migrate_legacy_ledger(repository_root)
+    all_pairs = all_finding_files(repository_root)
+    all_readable_paths = {each_path for each_path, _each_finding in all_pairs}
+    removed_count = sum(
+        _settle_finding_file(
+            each_path,
+            finding_path(repository_root, each_finding),
+            all_readable_paths,
+        )
+        for each_path, each_finding in all_pairs
+    )
+    return LedgerNormalization(migrated_count, removed_count)
+
+
+def _settle_finding_file(
+    current_path: Path, expected_path: Path, all_readable_paths: set[Path]
+) -> int:
+    if current_path == expected_path:
+        return 0
+    try:
+        if expected_path in all_readable_paths:
+            current_path.unlink()
+            return 1
+        if not expected_path.exists():
+            current_path.rename(expected_path)
+    except OSError:
+        return 0
+    return 0
+
+
+def _migrate_legacy_ledger(repository_root: Path) -> int:
+    legacy_path = followup_directory(repository_root) / LEGACY_LEDGER_FILE_NAME
+    try:
+        legacy_text = legacy_path.read_text(encoding=LEDGER_ENCODING)
+    except (OSError, UnicodeError):
+        return 0
+    all_legacy_findings = [
+        each_finding
+        for each_finding in map(finding_from_text, legacy_text.splitlines())
+        if each_finding is not None
+    ]
+    for each_finding in all_legacy_findings:
+        record_followup_finding(repository_root, each_finding)
+    if not all(
+        finding_path(repository_root, each_finding).is_file()
+        for each_finding in all_legacy_findings
+    ):
+        return 0
+    try:
+        legacy_path.unlink()
+    except OSError:
+        return 0
+    return len(all_legacy_findings)

package/hooks/hooks.json

@@ -332,17 +332,6 @@
         ]
       }
     ],
-    "Stop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/session_title_stop_gate.py",
-            "timeout": 10
-          }
-        ]
-      }
-    ],
     "PostToolUse": [
       {
         "matcher": "Write|Edit",

package/hooks/hooks_constants/artifact_template_pointer_constants.py

@@ -26,7 +26,11 @@ ALL_ARTIFACT_DESIGN_SKILL_NAMES = frozenset({"artifact-design"})
 TEMPLATES_DIRECTORY = Path(__file__).resolve().parents[2] / "docs" / "templates"
 ARTIFACT_TEMPLATE_PATH = TEMPLATES_DIRECTORY / "artifact-page" / "README.md"
 HTML_PLAN_TEMPLATE_README_PATH = TEMPLATES_DIRECTORY / "html-plan" / "README.md"
-POINTER_TEXT_PREFIX = "Build this artifact page from the html-plan skill, following "
+POINTER_TEXT_PREFIX = (
+    "Pick the visual by scope. For one flow or one comparison, draw an inline SVG"
+    " flowchart artifact with minimal text, using the artifact-diagramming skill."
+    " For a multi-part plan or evidence, build an html-plan page following "
+)
 POINTER_ALTERNATIVE_PREFIX = (
     ". When the request names the older artifact page template,"
     " pick the one that fits the ask from "

package/hooks/hooks_constants/followup_ledger_constants.py

@@ -3,9 +3,14 @@
 from __future__ import annotations
 
 __all__ = [
-    "ALL_FOLLOWUP_LEDGER_PATH_SEGMENTS",
+    "ALL_FOLLOWUP_DIRECTORY_SEGMENTS",
+    "LEGACY_LEDGER_FILE_NAME",
+    "FINDING_FILE_SUFFIX",
+    "FINDING_FILE_PATTERN",
+    "FINDING_FILE_NAME_HASH_LENGTH",
     "LEDGER_ENCODING",
-    "LEDGER_APPEND_MODE",
+    "LEDGER_CREATE_MODE",
+    "LEDGER_JSON_INDENT",
     "LEDGER_IGNORE_FILE_NAME",
     "LEDGER_IGNORE_TEXT",
     "RULE_ID_KEY",
@@ -15,7 +20,12 @@ __all__ = [
     "SEVERITY_KEY",
     "ORIGIN_COMMIT_KEY",
     "ABSENT_ORIGIN_COMMIT",
-    "ALL_GIT_HEAD_PATH_SEGMENTS",
+    "GIT_HEAD_FILE_NAME",
+    "GIT_DIRECTORY_FILE_PREFIX",
+    "GIT_COMMON_DIRECTORY_FILE_NAME",
+    "GIT_PACKED_REFERENCES_FILE_NAME",
+    "GIT_PACKED_REFERENCES_COMMENT_PREFIX",
+    "GIT_PACKED_REFERENCES_PEELED_PREFIX",
     "GIT_DIRECTORY_NAME",
     "GIT_REFERENCE_PREFIX",
     "SEVERITY_BREAKING",
@@ -23,9 +33,14 @@ __all__ = [
     "ALL_SEVERITY_NAMES",
 ]
 
-ALL_FOLLOWUP_LEDGER_PATH_SEGMENTS: tuple[str, ...] = (".claude", "followups", "smells.jsonl")
+ALL_FOLLOWUP_DIRECTORY_SEGMENTS: tuple[str, ...] = (".claude", "followups")
+LEGACY_LEDGER_FILE_NAME: str = "smells.jsonl"
+FINDING_FILE_SUFFIX: str = ".json"
+FINDING_FILE_PATTERN: str = "*.json"
+FINDING_FILE_NAME_HASH_LENGTH: int = 16
 LEDGER_ENCODING: str = "utf-8"
-LEDGER_APPEND_MODE: str = "a"
+LEDGER_CREATE_MODE: str = "x"
+LEDGER_JSON_INDENT: int = 2
 LEDGER_IGNORE_FILE_NAME: str = ".gitignore"
 LEDGER_IGNORE_TEXT: str = "*\n"
 
@@ -38,7 +53,12 @@ ORIGIN_COMMIT_KEY: str = "origin_commit"
 
 ABSENT_ORIGIN_COMMIT: str = ""
 GIT_DIRECTORY_NAME: str = ".git"
-ALL_GIT_HEAD_PATH_SEGMENTS: tuple[str, ...] = (GIT_DIRECTORY_NAME, "HEAD")
+GIT_HEAD_FILE_NAME: str = "HEAD"
+GIT_DIRECTORY_FILE_PREFIX: str = "gitdir: "
+GIT_COMMON_DIRECTORY_FILE_NAME: str = "commondir"
+GIT_PACKED_REFERENCES_FILE_NAME: str = "packed-refs"
+GIT_PACKED_REFERENCES_COMMENT_PREFIX: str = "#"
+GIT_PACKED_REFERENCES_PEELED_PREFIX: str = "^"
 GIT_REFERENCE_PREFIX: str = "ref: "
 
 SEVERITY_BREAKING: str = "breaking"

package/hooks/hooks_constants/session_title_constants.py

@@ -1,21 +1,14 @@
-"""Constants for session_title_format_gate.py and session_title_stop_gate.py."""
+"""Constants for session_title_format_gate.py."""
 
 import re
 
 TITLE_TOOL_NAME_PATTERN = re.compile(r"^mcp__.+__set_session_title$")
-REMOTE_SESSION_ENVIRONMENT_VARIABLE = "CLAUDE_CODE_REMOTE_SESSION_ID"
 TITLE_INPUT_KEY = "title"
 TOOL_NAME_KEY = "tool_name"
 TOOL_INPUT_KEY = "tool_input"
-TRANSCRIPT_PATH_KEY = "transcript_path"
-STOP_HOOK_ACTIVE_KEY = "stop_hook_active"
 FORMAT_GATE_EVENT_NAME = "PreToolUse"
-STOP_GATE_EVENT_NAME = "Stop"
 ALLOW_EXIT_CODE = 0
 BLOCK_EXIT_CODE = 2
-BLOCK_DECISION = "block"
-DEFERRED_TOOL_ATTACHMENT_TYPES = frozenset({"deferred_tools_delta", "deferred_tools_record"})
-HOOK_BLOCKING_ERROR_ATTACHMENT_TYPE = "hook_blocking_error"
 
 STATUS_PREFIX_PATTERN = re.compile("^(\U0001f6a9|\u2705|\u23f3)\ufe0f? (?=\\S)")
 MAXIMUM_NAME_LENGTH = 25
@@ -38,24 +31,3 @@ FORMAT_RETRY_INSTRUCTION = (
     " the main change or outcome in concrete nouns, such as"
     " '\u23f3 Broker gate + replay rule'."
 )
-
-STOP_BLOCK_REASON = (
-    "Before you end this turn, set the session title to its current status."
-    " Call the session title tool ({tool_name}); when it asks for a session id,"
-    " get it from get_session with no session_id."
-    " Use the shape '<emoji> <name>'."
-    " Emoji: \U0001f6a9 when the user must act (a question, an approval, or a step only the user can do);"
-    " \u2705 when the work is done (merged, or nothing left);"
-    " \u23f3 while work, CI or a merge queue still runs and nothing waits on the user."
-    " Name: 25 characters or fewer, the main change or outcome in concrete nouns,"
-    " two parts joined with ' + ', sentence case, no end punctuation,"
-    " no dates, IDs, branch names or filler words."
-    " Rename it when the scope of the work has changed."
-    " The title is a silent step: make the call and end the turn."
-    " Say nothing to the user about the title, its emoji or this reminder."
-    " When the user already has your answer this turn, end with no text."
-    " Next time, set the title before your final reply."
-)
-REMOTE_TITLE_TOOL_NAME = "mcp__claude-code-remote__set_session_title"
-REMOTE_SERVER_TOOL_PREFIX = "mcp__claude-code-remote__"
-UNKNOWN_TITLE_TOOL_NAME = "its name ends in __set_session_title"

package/hooks/session/artifact_template_pointer.py

@@ -1,10 +1,11 @@
 #!/usr/bin/env python3
-"""PreToolUse hook: point an agent about to build an artifact page at html-plan.
+"""PreToolUse hook: route an agent about to build an artifact page by scope.
 
 Registered on ``Artifact|Skill``. It adds one line of ``additionalContext``
-naming ``docs/templates/html-plan/README.md`` as the default and
-``docs/templates/artifact-page/README.md`` as the alternative when a
-session starts a new artifact page:
+when a session starts a new artifact page. One flow or one comparison is an
+inline SVG flowchart with minimal text. A multi-part plan or evidence is an
+html-plan page from ``docs/templates/html-plan/README.md``, and
+``docs/templates/artifact-page/README.md`` stays the alternative:
 
 ::
 

package/hooks/session/test_artifact_template_pointer.py

@@ -44,6 +44,19 @@ def test_artifact_quickstart_gets_the_template_pointer() -> None:
     assert "permissionDecision" not in specific_output
 
 
+def test_pointer_routes_a_simple_visual_to_a_flowchart_ahead_of_html_plan() -> None:
+    hook_output = artifact_template_pointer.decide_hook_output(
+        _payload("Artifact", {"action": "quickstart", "intent": "other"})
+    )
+    assert hook_output is not None
+    pointer_text = hook_output["hookSpecificOutput"]["additionalContext"]
+    assert pointer_text.index("one flow or one comparison") < pointer_text.index("flowchart")
+    assert pointer_text.index("flowchart") < pointer_text.index("multi-part plan or evidence")
+    assert pointer_text.index("multi-part plan or evidence") < pointer_text.index(
+        str(HTML_PLAN_TEMPLATE_README_PATH)
+    )
+
+
 def test_artifact_design_skill_gets_the_template_pointer() -> None:
     hook_output = artifact_template_pointer.decide_hook_output(
         _payload("Skill", {"skill": "artifact-design"})

package/hooks/test_followup_ledger.py

@@ -12,9 +12,8 @@ if _hooks_directory not in sys.path:
 from followup_ledger import (
     FollowupFinding,
     all_recorded_findings,
-    deduplicate_ledger,
-    deduplicated_lines,
-    followup_ledger_path,
+    finding_path,
+    followup_directory,
     head_commit,
     record_followup_finding,
 )
@@ -62,27 +61,29 @@ def test_all_recorded_findings_is_empty_without_a_ledger(tmp_path: Path) -> None
     assert all_recorded_findings(tmp_path) == ()
 
 
-def test_all_recorded_findings_skips_an_unreadable_line(tmp_path: Path) -> None:
+def test_all_recorded_findings_skips_an_unreadable_file(tmp_path: Path) -> None:
     finding = FollowupFinding(
         "instruction-mode", "docs/AGENTS.md", "wrong mode", "instruction-mode"
     )
     record_followup_finding(tmp_path, finding)
-    ledger_path = followup_ledger_path(tmp_path)
-    with ledger_path.open("a", encoding="utf-8") as ledger_file:
-        ledger_file.write("{ not json\n")
+    (followup_directory(tmp_path) / "damaged.json").write_text(
+        "{ not json\n", encoding="utf-8"
+    )
 
     assert all_recorded_findings(tmp_path) == (finding,)
 
 
-def test_record_followup_finding_writes_one_json_object_per_line(tmp_path: Path) -> None:
-    record_followup_finding(
-        tmp_path, FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong mode")
-    )
+def test_record_followup_finding_writes_one_json_file_per_finding(
+    tmp_path: Path,
+) -> None:
+    finding = FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong mode")
 
-    all_lines = followup_ledger_path(tmp_path).read_text(encoding="utf-8").splitlines()
+    record_followup_finding(tmp_path, finding)
 
-    assert len(all_lines) == 1
-    assert json.loads(all_lines[0])["rule_id"] == "instruction-mode"
+    all_record_paths = list(followup_directory(tmp_path).glob("*.json"))
+    assert all_record_paths == [finding_path(tmp_path, finding)]
+    recorded = json.loads(all_record_paths[0].read_text(encoding="utf-8"))
+    assert recorded["rule_id"] == "instruction-mode"
 
 
 def test_a_recorded_ledger_stays_out_of_git_status(tmp_path: Path) -> None:
@@ -98,7 +99,7 @@ def test_a_recorded_ledger_stays_out_of_git_status(tmp_path: Path) -> None:
         capture_output=True,
         text=True,
     )
-    assert followup_ledger_path(tmp_path).is_file()
+    assert any(followup_directory(tmp_path).glob("*.json"))
     assert status_result.stdout == ""
 
 
@@ -133,9 +134,9 @@ def test_a_recorded_finding_carries_its_check_severity_and_origin(
 def test_a_record_written_without_the_tracking_fields_still_reads(
     tmp_path: Path,
 ) -> None:
-    ledger_path = followup_ledger_path(tmp_path)
-    ledger_path.parent.mkdir(parents=True, exist_ok=True)
-    ledger_path.write_text(
+    record_path = followup_directory(tmp_path) / "older.json"
+    record_path.parent.mkdir(parents=True, exist_ok=True)
+    record_path.write_text(
         json.dumps(
             {
                 "rule_id": "instruction-mode",
@@ -191,57 +192,152 @@ def test_head_commit_is_empty_outside_a_repository(tmp_path: Path) -> None:
     assert head_commit(tmp_path) == ""
 
 
-def test_deduplicated_lines_keeps_the_first_of_each_exact_line_in_order() -> None:
-    assert deduplicated_lines(["a", "b", "a", "c", "b"]) == ["a", "b", "c"]
+def _committed_repository(repository_root: Path) -> str:
+    subprocess.run(["git", "init", "--quiet", str(repository_root)], check=True)
+    subprocess.run(
+        [
+            "git",
+            "-C",
+            str(repository_root),
+            "-c",
+            "user.name=t",
+            "-c",
+            "user.email=t@t",
+            "commit",
+            "--quiet",
+            "--allow-empty",
+            "-m",
+            "start",
+        ],
+        check=True,
+    )
+    return subprocess.run(
+        ["git", "-C", str(repository_root), "rev-parse", "HEAD"],
+        check=True,
+        capture_output=True,
+        text=True,
+    ).stdout.strip()
+
+
+def test_head_commit_reads_a_linked_worktree_branch(tmp_path: Path) -> None:
+    main_root = tmp_path / "main"
+    worktree_root = tmp_path / "linked"
+    expected_commit = _committed_repository(main_root)
+    subprocess.run(
+        [
+            "git",
+            "-C",
+            str(main_root),
+            "worktree",
+            "add",
+            "--quiet",
+            "-b",
+            "feature",
+            str(worktree_root),
+        ],
+        check=True,
+    )
+
+    assert head_commit(worktree_root) == expected_commit
 
 
-def test_record_followup_finding_removes_lines_a_union_merge_repeated(
+def test_head_commit_reads_a_packed_branch_from_a_linked_worktree(
     tmp_path: Path,
 ) -> None:
-    ledger_path = followup_ledger_path(tmp_path)
-    ledger_path.parent.mkdir(parents=True)
-    first_line = '{"rule_id": "r1", "file_path": "a.py", "message": "m1"}'
-    second_line = '{"rule_id": "r2", "file_path": "b.py", "message": "m2"}'
-    ledger_path.write_text(
-        f"{first_line}\n{second_line}\n{first_line}\n", encoding="utf-8"
+    main_root = tmp_path / "main"
+    worktree_root = tmp_path / "linked"
+    expected_commit = _committed_repository(main_root)
+    subprocess.run(
+        [
+            "git",
+            "-C",
+            str(main_root),
+            "worktree",
+            "add",
+            "--quiet",
+            "-b",
+            "feature",
+            str(worktree_root),
+        ],
+        check=True,
+    )
+    subprocess.run(
+        ["git", "-C", str(main_root), "pack-refs", "--all"], check=True
     )
 
-    record_followup_finding(tmp_path, FollowupFinding("r3", "c.py", "m3", "r3"))
+    assert not (main_root / ".git" / "refs" / "heads" / "feature").exists()
+    assert head_commit(worktree_root) == expected_commit
 
-    all_ledger_lines = ledger_path.read_text(encoding="utf-8").splitlines()
-    assert all_ledger_lines[:2] == [first_line, second_line]
-    assert [json.loads(each_line)["rule_id"] for each_line in all_ledger_lines] == [
-        "r1",
-        "r2",
-        "r3",
-    ]
 
+def test_the_file_name_depends_on_the_tracking_key_alone(tmp_path: Path) -> None:
+    first = FollowupFinding("r1", "a.py", "m1", "r1", "smell", "aaa1111")
+    later = first._replace(origin_commit="bbb2222")
+    other = first._replace(message="m2")
 
-def test_record_followup_finding_removes_a_repeat_of_an_already_recorded_finding(
-    tmp_path: Path,
-) -> None:
-    finding = FollowupFinding("r1", "a.py", "m1", "r1")
-    record_followup_finding(tmp_path, finding)
-    ledger_path = followup_ledger_path(tmp_path)
-    recorded_text = ledger_path.read_text(encoding="utf-8")
-    ledger_path.write_text(recorded_text * 2, encoding="utf-8")
+    assert finding_path(tmp_path, first) == finding_path(tmp_path, later)
+    assert finding_path(tmp_path, first) != finding_path(tmp_path, other)
+
+
+def _git(repository_root: Path, *all_arguments: str) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [
+            "git",
+            "-C",
+            str(repository_root),
+            "-c",
+            "user.name=t",
+            "-c",
+            "user.email=t@t",
+            *all_arguments,
+        ],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
 
-    record_followup_finding(tmp_path, finding)
 
-    assert ledger_path.read_text(encoding="utf-8") == recorded_text
+def _commit_finding_on_branch(
+    repository_root: Path, branch_name: str, finding: FollowupFinding
+) -> set[str]:
+    _git(repository_root, "checkout", "--quiet", "-b", branch_name, "main")
+    record_followup_finding(repository_root, finding)
+    _git(repository_root, "add", "--all")
+    _git(repository_root, "commit", "--quiet", "-m", branch_name)
+    changed_text = _git(
+        repository_root, "diff", "--name-only", "main", branch_name
+    ).stdout
+    return set(changed_text.split())
+
+
+def test_two_parallel_writers_share_no_file_and_merge_cleanly(tmp_path: Path) -> None:
+    repository_root = tmp_path / "repo"
+    subprocess.run(
+        ["git", "init", "--quiet", "-b", "main", str(repository_root)], check=True
+    )
+    ignore_path = followup_directory(repository_root) / ".gitignore"
+    ignore_path.parent.mkdir(parents=True)
+    ignore_path.write_text("!*.json\n", encoding="utf-8")
+    _git(repository_root, "add", "--all")
+    _git(repository_root, "commit", "--quiet", "-m", "start")
+    first = FollowupFinding("r1", "a.py", "m1", "r1")
+    second = FollowupFinding("r2", "b.py", "m2", "r2")
 
+    first_files = _commit_finding_on_branch(repository_root, "first", first)
+    second_files = _commit_finding_on_branch(repository_root, "second", second)
+    _git(repository_root, "checkout", "--quiet", "first")
+    merge_result = _git(repository_root, "merge", "--no-edit", "second")
 
-def test_deduplicate_ledger_reports_how_many_lines_it_removed(tmp_path: Path) -> None:
-    ledger_path = followup_ledger_path(tmp_path)
-    ledger_path.parent.mkdir(parents=True)
-    ledger_path.write_text("x\ny\nx\nx\n", encoding="utf-8")
+    assert first_files and second_files
+    assert not first_files & second_files
+    assert merge_result.returncode == 0, merge_result.stdout + merge_result.stderr
+    assert all_recorded_findings(repository_root) == (first, second)
 
-    removed_count = deduplicate_ledger(tmp_path)
 
-    assert removed_count == 2
-    assert ledger_path.read_text(encoding="utf-8") == "x\ny\n"
+def test_a_committed_ignore_file_is_left_as_it_stands(tmp_path: Path) -> None:
+    ignore_path = followup_directory(tmp_path) / ".gitignore"
+    ignore_path.parent.mkdir(parents=True)
+    ignore_path.write_text("!*.json\n", encoding="utf-8")
 
+    record_followup_finding(tmp_path, FollowupFinding("r1", "a.py", "m1", "r1"))
 
-def test_deduplicate_ledger_leaves_an_absent_ledger_absent(tmp_path: Path) -> None:
-    assert deduplicate_ledger(tmp_path) == 0
-    assert not followup_ledger_path(tmp_path).exists()
+    assert ignore_path.read_text(encoding="utf-8") == "!*.json\n"