claude-dev-env 8.74.1 → 8.75.0

package/hooks/features/conduct-gates.md

@@ -8,7 +8,6 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/edit_marker_gate.py` rejects strikethrough and edit-note markers in replacement chat text or cards.
 - `blocking/issue_close_handoff_gate.py` denies an issue comment or issue write that closes the issue and routes a found defect to another issue or epic.
 - `blocking/session_title_format_gate.py` denies a session title that breaks the `<emoji> <name>` shape or has a name longer than 25 characters.
-- `blocking/session_title_stop_gate.py` blocks a turn end once when no session title call succeeded in that turn.
 - `blocking/step_note_gate.py` requires a status line before a tool call while its opt-in flag is on.
 - `blocking/verify_before_acting.py` blocks a completed mutating call when the agent's reasoning contains an unchecked claim.
 - `blocking/pr_lifecycle_skill_gate.py` denies a commit, push, pull request action, or merge until the `pr-lifecycle` skill appears in the transcript since the last compaction.
@@ -20,7 +19,6 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/edit_marker_gate.py` runs on `PreToolUse`, matcher `mcp__.*__update_message`, timeout `10` seconds in `hooks.json`.
 - `blocking/issue_close_handoff_gate.py` runs on `PreToolUse`, matcher `mcp__.*__(add_issue_comment|issue_write|update_issue_comment)`, timeout `10` seconds in `hooks.json`.
 - `blocking/session_title_format_gate.py` runs on `PreToolUse`, matcher `mcp__.*__set_session_title`, timeout `10` seconds in `hooks.json`.
-- `blocking/session_title_stop_gate.py` runs on `Stop`, no matcher, timeout `10` seconds in `hooks.json`.
 - `blocking/step_note_gate.py` runs on `PreToolUse`, matcher `*`, timeout `15` seconds in `hooks.json`.
 - `blocking/verify_before_acting.py` runs on `PostToolUse`, matcher `Write|Edit|MultiEdit|NotebookEdit|Agent|Task|apply_patch|Bash|PowerShell|mcp__.*`, timeout `10` seconds in `hooks.json`.
 - `blocking/pr_lifecycle_skill_gate.py` runs on `PreToolUse`, matcher `Bash|PowerShell|mcp__.*__(create_pull_request|merge_pull_request|enable_pr_auto_merge|update_pull_request|actions_run_trigger)`, timeout `10` seconds in `hooks.json`.
@@ -36,7 +34,6 @@ Preconditions:
 - **Edit marker.** Input is an update message with strikethrough or an edit note. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_edit_marker_gate.py -q`. The adjacent test observes a denial; clean replacement text passes.
 - **Handoff close.** Input is an issue comment that says the issue is closed and that the found defect belongs to another issue. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_issue_close_handoff_gate.py -q`. The adjacent test observes a denial; a close with a plain cross-reference and a routing comment on an open issue both pass.
 - **Session title.** Input is a set session title call with no leading emoji or a name over 25 characters. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_format_gate.py -q`. The adjacent test observes a denial that names the broken rule; a well-formed title passes.
-- **Title at turn end.** Input is a remote session transcript whose last turn set no title. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_stop_gate.py -q`. The adjacent test observes a block; a turn with a successful title call passes.
 - **Step note.** Input is a tool call after a transcript message without a status line while the flag is on. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_step_note_gate.py -q`. The adjacent test observes a block until a status line appears.
 - **Checked claim.** Input is a Write after hedged reasoning in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_verify_before_acting.py -q`. The adjacent test observes a block and a logged blocked outcome.
 - **Lifecycle skill.** Input is a `git commit` or `gh pr create` command with no `pr-lifecycle` invocation in the transcript. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_pr_lifecycle_skill_gate.py -q`. The adjacent test observes a denial, then a silent allow once the skill or its slash command appears.

package/hooks/features/session-context.md

@@ -9,7 +9,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/working_style_prompt.py` injects the session's working style at session start.
 - `session/advisor_rules_prompt.py` injects advisor guidance when the built-in advisor is enabled.
 - `session/orchestrator_auto_starter.py` injects an orchestrator directive when its environment flag is enabled.
-- `session/artifact_template_pointer.py` points an agent that starts an artifact page at `docs/templates/html-plan/README.md`. When the request names the older artifact page template, it points at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
+- `session/artifact_template_pointer.py` routes an agent that starts an artifact page by scope. 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`. When the request names the older artifact page template, it points at `docs/templates/artifact-page/README.md`, which names the tracker template and the diagram template and which ask each fits.
 - `advisory/auto_mode_denial_quick_fix.py` proposes one `autoMode.allow` entry and a PowerShell block that writes it after an auto mode denial. It never retries the denied call.
 
 ## When it fires

package/hooks/followup_ledger.py

@@ -1,20 +1,23 @@
-"""Append-only ledger of non-breaking findings awaiting a follow-up fix.
+"""Ledger of non-breaking findings awaiting a follow-up fix, one file each.
 
 A gate that finds a breaking defect stops the commit, the push, or the tool
 call. A gate that finds a non-breaking smell records the finding here and lets
-the work proceed. ``cde followup`` reads the ledger and briefs the agent that
-fixes the recorded smells in their own pull request.
+the work proceed. Each finding is its own JSON file under
+``.claude/followups/``, named by a hash of the finding, so parallel branches
+that record different findings never edit the same file. ``cde followup``
+reads the ledger and briefs the agent that fixes the recorded smells in their
+own pull request.
 
-Every write is fail-safe. A ledger that cannot be created or appended to leaves
+Every write is fail-safe. A ledger that cannot be created or written to leaves
 the calling gate's decision unchanged, so recording a finding never becomes a
 new way for a gate to fail.
 """
 
 from __future__ import annotations
 
+import hashlib
 import json
 import sys
-from collections.abc import Sequence
 from pathlib import Path
 from typing import NamedTuple
 
@@ -24,9 +27,12 @@ if _hooks_directory not in sys.path:
 
 from hooks_constants.followup_ledger_constants import (
     ABSENT_ORIGIN_COMMIT,
-    ALL_FOLLOWUP_LEDGER_PATH_SEGMENTS,
+    ALL_FOLLOWUP_DIRECTORY_SEGMENTS,
     CHECK_ID_KEY,
     FILE_PATH_KEY,
+    FINDING_FILE_NAME_HASH_LENGTH,
+    FINDING_FILE_PATTERN,
+    FINDING_FILE_SUFFIX,
     GIT_COMMON_DIRECTORY_FILE_NAME,
     GIT_DIRECTORY_FILE_PREFIX,
     GIT_DIRECTORY_NAME,
@@ -35,10 +41,11 @@ from hooks_constants.followup_ledger_constants import (
     GIT_PACKED_REFERENCES_FILE_NAME,
     GIT_PACKED_REFERENCES_PEELED_PREFIX,
     GIT_REFERENCE_PREFIX,
-    LEDGER_APPEND_MODE,
+    LEDGER_CREATE_MODE,
     LEDGER_ENCODING,
     LEDGER_IGNORE_FILE_NAME,
     LEDGER_IGNORE_TEXT,
+    LEDGER_JSON_INDENT,
     MESSAGE_KEY,
     ORIGIN_COMMIT_KEY,
     RULE_ID_KEY,
@@ -80,151 +87,144 @@ class FollowupFinding(NamedTuple):
         return (self.check_id or self.rule_id, self.file_path, self.message)
 
 
-def deduplicated_lines(all_lines: Sequence[str]) -> list[str]:
-    """Return the lines with every exact repeat removed.
-
-    The first occurrence of each line keeps its place, so the ledger keeps its
-    record order after a ``merge=union`` merge writes both sides' lines.
+def followup_directory(repository_root: Path) -> Path:
+    """Return the directory that holds one repository's recorded findings.
 
     Args:
-        all_lines: The ledger lines, in file order.
+        repository_root: The repository whose ledger to address.
 
     Returns:
-        The lines in file order, each exact line once.
+        The absolute path of that repository's follow-up directory.
     """
-    return list(dict.fromkeys(all_lines))
-
-
-def deduplicate_ledger(repository_root: Path) -> int:
-    """Rewrite the repository's ledger without exact repeated lines.
-
-    An absent or unreadable ledger, and a ledger that cannot be rewritten, are
-    left as they are, so a ledger failure never becomes a gate failure.
+    return repository_root.joinpath(*ALL_FOLLOWUP_DIRECTORY_SEGMENTS)
 
-    Args:
-        repository_root: The repository whose ledger to clean.
-
-    Returns:
-        How many lines the rewrite removed.
-    """
-    ledger_path = followup_ledger_path(repository_root)
-    try:
-        all_ledger_lines = ledger_path.read_text(encoding=LEDGER_ENCODING).splitlines()
-    except (OSError, UnicodeError):
-        return 0
-    all_unique_lines = deduplicated_lines(all_ledger_lines)
-    removed_line_count = len(all_ledger_lines) - len(all_unique_lines)
-    if not removed_line_count:
-        return 0
-    try:
-        ledger_path.write_text(
-            "".join(each_line + "\n" for each_line in all_unique_lines),
-            encoding=LEDGER_ENCODING,
-        )
-    except OSError:
-        return 0
-    return removed_line_count
 
+def finding_path(repository_root: Path, finding: FollowupFinding) -> Path:
+    """Return the file one finding is recorded in.
 
-def followup_ledger_path(repository_root: Path) -> Path:
-    """Return the ledger path for one repository.
+    The file name is a hash of the finding's tracking key, so the same finding
+    always maps to the same file and two different findings never share one.
 
     Args:
-        repository_root: The repository whose ledger to address.
+        repository_root: The repository whose ledger holds the finding.
+        finding: The finding to locate.
 
     Returns:
-        The absolute path of that repository's follow-up ledger.
+        The absolute path of the finding's file.
     """
-    return repository_root.joinpath(*ALL_FOLLOWUP_LEDGER_PATH_SEGMENTS)
+    key_text = json.dumps(list(finding.tracking_key()), ensure_ascii=True)
+    key_digest = hashlib.sha256(key_text.encode(LEDGER_ENCODING)).hexdigest()
+    file_name = key_digest[:FINDING_FILE_NAME_HASH_LENGTH] + FINDING_FILE_SUFFIX
+    return followup_directory(repository_root) / file_name
 
 
 def record_followup_finding(repository_root: Path, finding: FollowupFinding) -> None:
-    """Append one finding to the repository's ledger, once.
+    """Write one finding to its own file in the repository's ledger, once.
 
-    The ledger first loses every exact repeated line, so lines a
-    ``merge=union`` merge wrote twice leave on the next write. A finding
-    already present in the ledger is left alone, so a gate that runs on every
-    commit records a standing smell a single time. The ledger
-    directory carries a ``.gitignore`` matching every file in it, so the
-    ledger stays out of ``git status`` in any repository. Every filesystem
-    error is swallowed, so a ledger failure leaves the caller's gate decision
-    unchanged.
+    The file is created exclusively, so a finding already on disk keeps the
+    record that first raised it, and a gate that runs on every commit records
+    a standing smell a single time. Two writers recording different findings
+    write different files, so parallel branches never edit a shared file. The
+    first write in a directory with no ``.gitignore`` adds one matching every
+    file, so the ledger stays out of ``git status`` in any repository that
+    does not commit its own. Every filesystem error is swallowed, so a ledger
+    failure leaves the caller's gate decision unchanged.
 
     Args:
         repository_root: The repository whose ledger receives the finding.
         finding: The non-breaking finding to record.
     """
-    deduplicate_ledger(repository_root)
-    all_recorded_keys = {
-        each_finding.tracking_key()
-        for each_finding in all_recorded_findings(repository_root)
-    }
-    if finding.tracking_key() in all_recorded_keys:
-        return
-
-    ledger_path = followup_ledger_path(repository_root)
-    record_text = json.dumps(
-        {
-            RULE_ID_KEY: finding.rule_id,
-            FILE_PATH_KEY: finding.file_path,
-            MESSAGE_KEY: finding.message,
-            CHECK_ID_KEY: finding.check_id or finding.rule_id,
-            SEVERITY_KEY: finding.severity,
-            ORIGIN_COMMIT_KEY: finding.origin_commit,
-        }
-    )
+    record_path = finding_path(repository_root, finding)
+    record_text = json.dumps(_record_fields(finding), indent=LEDGER_JSON_INDENT)
     try:
-        ledger_path.parent.mkdir(parents=True, exist_ok=True)
-        ignore_path = ledger_path.parent / LEDGER_IGNORE_FILE_NAME
+        record_path.parent.mkdir(parents=True, exist_ok=True)
+        ignore_path = record_path.parent / LEDGER_IGNORE_FILE_NAME
         if not ignore_path.exists():
             ignore_path.write_text(LEDGER_IGNORE_TEXT, encoding=LEDGER_ENCODING)
-        with ledger_path.open(LEDGER_APPEND_MODE, encoding=LEDGER_ENCODING) as ledger_file:
-            ledger_file.write(record_text + "\n")
+        with record_path.open(LEDGER_CREATE_MODE, encoding=LEDGER_ENCODING) as record_file:
+            record_file.write(record_text + "\n")
     except OSError:
         return
 
 
+def _record_fields(finding: FollowupFinding) -> dict[str, str]:
+    return {
+        RULE_ID_KEY: finding.rule_id,
+        FILE_PATH_KEY: finding.file_path,
+        MESSAGE_KEY: finding.message,
+        CHECK_ID_KEY: finding.check_id or finding.rule_id,
+        SEVERITY_KEY: finding.severity,
+        ORIGIN_COMMIT_KEY: finding.origin_commit,
+    }
+
+
 def all_recorded_findings(repository_root: Path) -> tuple[FollowupFinding, ...]:
-    """Return every finding the repository's ledger holds, in record order.
+    """Return every finding the repository's ledger holds, ordered by check.
 
-    An absent or unreadable ledger reads as empty, and a line that does not
-    parse into a complete record is skipped, so one damaged line never hides
-    the findings around it.
+    An absent directory reads as empty, and a file that does not parse into a
+    complete record is skipped, so one damaged file never hides the findings
+    around it.
 
     Args:
         repository_root: The repository whose ledger to read.
 
     Returns:
-        The recorded findings, in the order they were appended.
+        The recorded findings, sorted by check identifier, path, and message.
+    """
+    all_findings = [
+        each_finding
+        for _each_path, each_finding in all_finding_files(repository_root)
+    ]
+    return tuple(sorted(all_findings, key=FollowupFinding.tracking_key))
+
+
+def all_record_paths(directory: Path) -> list[Path]:
+    """Return every finding file in one ledger directory, sorted by name.
+
+    Args:
+        directory: The follow-up directory to list.
+
+    Returns:
+        The finding file paths, or an empty list when none can be listed.
     """
-    ledger_path = followup_ledger_path(repository_root)
     try:
-        ledger_text = ledger_path.read_text(encoding=LEDGER_ENCODING)
-    except (OSError, UnicodeError):
-        return ()
+        return sorted(directory.glob(FINDING_FILE_PATTERN))
+    except OSError:
+        return []
 
-    all_findings: list[FollowupFinding] = []
-    for each_line in ledger_text.splitlines():
-        each_finding = _finding_from_line(each_line)
+
+def all_finding_files(repository_root: Path) -> list[tuple[Path, FollowupFinding]]:
+    """Return each readable finding file with the finding it holds.
+
+    Args:
+        repository_root: The repository whose ledger to read.
+
+    Returns:
+        Path and finding pairs, sorted by file name.
+    """
+    all_pairs: list[tuple[Path, FollowupFinding]] = []
+    for each_path in all_record_paths(followup_directory(repository_root)):
+        try:
+            record_text = each_path.read_text(encoding=LEDGER_ENCODING)
+        except (OSError, UnicodeError):
+            continue
+        each_finding = finding_from_text(record_text)
         if each_finding is not None:
-            all_findings.append(each_finding)
-    return tuple(all_findings)
+            all_pairs.append((each_path, each_finding))
+    return all_pairs
 
 
-def _finding_from_line(ledger_line: str) -> FollowupFinding | None:
-    """Parse one ledger line into a finding.
+def finding_from_text(record_text: str) -> FollowupFinding | None:
+    """Parse one JSON record into a finding.
 
     Args:
-        ledger_line: One line of the ledger file.
+        record_text: One finding file's text, or one legacy ledger line.
 
     Returns:
-        The parsed finding, or None when the line carries no complete record.
+        The parsed finding, or None when the text carries no complete record.
     """
-    stripped_line = ledger_line.strip()
-    if not stripped_line:
-        return None
     try:
-        parsed_record = json.loads(stripped_line)
+        parsed_record = json.loads(record_text)
     except json.JSONDecodeError:
         return None
     if not isinstance(parsed_record, dict):
@@ -232,9 +232,7 @@ def _finding_from_line(ledger_line: str) -> FollowupFinding | None:
     rule_id = parsed_record.get(RULE_ID_KEY)
     file_path = parsed_record.get(FILE_PATH_KEY)
     message = parsed_record.get(MESSAGE_KEY)
-    if not isinstance(rule_id, str) or not isinstance(file_path, str):
-        return None
-    if not isinstance(message, str):
+    if not all(isinstance(each, str) for each in (rule_id, file_path, message)):
         return None
     return FollowupFinding(
         rule_id,
@@ -252,7 +250,7 @@ def _text_field(
     """Read one text field of a ledger record.
 
     Args:
-        all_record_fields: The mapping one ledger line parsed into.
+        all_record_fields: The mapping one record parsed into.
         field_key: The key to read.
         fallback: The value a record written before this field carried it takes.
 

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",
@@ -28,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"
 

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"})