claude-dev-env 8.5.0 → 8.6.1

package/hooks/followup_ledger.py

@@ -22,12 +22,20 @@ if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
 from hooks_constants.followup_ledger_constants import (
-    FILE_PATH_KEY,
+    ABSENT_ORIGIN_COMMIT,
     ALL_FOLLOWUP_LEDGER_PATH_SEGMENTS,
+    ALL_GIT_HEAD_PATH_SEGMENTS,
+    CHECK_ID_KEY,
+    FILE_PATH_KEY,
+    GIT_DIRECTORY_NAME,
+    GIT_REFERENCE_PREFIX,
     LEDGER_APPEND_MODE,
     LEDGER_ENCODING,
     MESSAGE_KEY,
+    ORIGIN_COMMIT_KEY,
     RULE_ID_KEY,
+    SEVERITY_KEY,
+    SEVERITY_SMELL,
 )
 
 
@@ -35,14 +43,33 @@ class FollowupFinding(NamedTuple):
     """One non-breaking finding a later pull request resolves.
 
     Attributes:
-        rule_id: Stable identifier of the check that raised the finding.
+        rule_id: Identifier of the rule that raised the finding.
         file_path: Repository-relative path the finding names.
         message: The text a reader acts on.
+        check_id: Identifier of the single check behind the finding. An empty
+            value reads back as the rule identifier.
+        severity: The class the gate put the finding in.
+        origin_commit: The revision checked out when the finding was recorded,
+            which groups a follow-up pull request by the change that raised it.
     """
 
     rule_id: str
     file_path: str
     message: str
+    check_id: str = ""
+    severity: str = SEVERITY_SMELL
+    origin_commit: str = ABSENT_ORIGIN_COMMIT
+
+    def tracking_key(self) -> tuple[str, str, str]:
+        """Return the fields that make this finding the same one over time.
+
+        The origin commit stays out of the key, so a smell seen again under a
+        later revision keeps the revision that first raised it.
+
+        Returns:
+            The check identifier, path, and message.
+        """
+        return (self.check_id or self.rule_id, self.file_path, self.message)
 
 
 def followup_ledger_path(repository_root: Path) -> Path:
@@ -69,7 +96,11 @@ def record_followup_finding(repository_root: Path, finding: FollowupFinding) ->
         repository_root: The repository whose ledger receives the finding.
         finding: The non-breaking finding to record.
     """
-    if finding in all_recorded_findings(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)
@@ -78,6 +109,9 @@ def record_followup_finding(repository_root: Path, finding: FollowupFinding) ->
             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,
         }
     )
     try:
@@ -140,4 +174,75 @@ def _finding_from_line(ledger_line: str) -> FollowupFinding | None:
         return None
     if not isinstance(message, str):
         return None
-    return FollowupFinding(rule_id, file_path, message)
+    return FollowupFinding(
+        rule_id,
+        file_path,
+        message,
+        _text_field(parsed_record, CHECK_ID_KEY, rule_id),
+        _text_field(parsed_record, SEVERITY_KEY, SEVERITY_SMELL),
+        _text_field(parsed_record, ORIGIN_COMMIT_KEY, ABSENT_ORIGIN_COMMIT),
+    )
+
+
+def _text_field(
+    all_record_fields: dict[str, object], field_key: str, fallback: str
+) -> str:
+    """Read one text field of a ledger record.
+
+    Args:
+        all_record_fields: The mapping one ledger line parsed into.
+        field_key: The key to read.
+        fallback: The value a record written before this field carried it takes.
+
+    Returns:
+        The field's text, or the fallback.
+    """
+    field_value = all_record_fields.get(field_key)
+    if isinstance(field_value, str) and field_value:
+        return field_value
+    return fallback
+
+
+def head_commit(repository_root: Path) -> str:
+    """Return the revision one repository has checked out.
+
+    ::
+
+        .git/HEAD holding "ref: refs/heads/main" -> the sha in refs/heads/main
+        .git/HEAD holding a sha                  -> that sha
+        no .git directory                        -> ""
+
+    The revision comes from the files git writes rather than from a git
+    process, so recording a finding starts no subprocess.
+
+    Args:
+        repository_root: The repository whose revision to read.
+
+    Returns:
+        The checked-out revision, or an empty string when none can be read.
+    """
+    head_path = repository_root.joinpath(*ALL_GIT_HEAD_PATH_SEGMENTS)
+    head_text = _file_text(head_path)
+    if head_text is None:
+        return ABSENT_ORIGIN_COMMIT
+    if not head_text.startswith(GIT_REFERENCE_PREFIX):
+        return head_text
+    reference_path = repository_root / GIT_DIRECTORY_NAME / head_text[
+        len(GIT_REFERENCE_PREFIX) :
+    ]
+    return _file_text(reference_path) or ABSENT_ORIGIN_COMMIT
+
+
+def _file_text(file_path: Path) -> str | None:
+    """Read one small git file into stripped text.
+
+    Args:
+        file_path: The file to read.
+
+    Returns:
+        The stripped text, or None when the file cannot be read.
+    """
+    try:
+        return file_path.read_text(encoding=LEDGER_ENCODING).strip()
+    except (OSError, UnicodeError):
+        return None

package/hooks/hooks_constants/followup_ledger_constants.py

@@ -9,6 +9,13 @@ __all__ = [
     "RULE_ID_KEY",
     "FILE_PATH_KEY",
     "MESSAGE_KEY",
+    "CHECK_ID_KEY",
+    "SEVERITY_KEY",
+    "ORIGIN_COMMIT_KEY",
+    "ABSENT_ORIGIN_COMMIT",
+    "ALL_GIT_HEAD_PATH_SEGMENTS",
+    "GIT_DIRECTORY_NAME",
+    "GIT_REFERENCE_PREFIX",
     "SEVERITY_BREAKING",
     "SEVERITY_SMELL",
     "ALL_SEVERITY_NAMES",
@@ -21,6 +28,14 @@ LEDGER_APPEND_MODE: str = "a"
 RULE_ID_KEY: str = "rule_id"
 FILE_PATH_KEY: str = "file_path"
 MESSAGE_KEY: str = "message"
+CHECK_ID_KEY: str = "check_id"
+SEVERITY_KEY: str = "severity"
+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_REFERENCE_PREFIX: str = "ref: "
 
 SEVERITY_BREAKING: str = "breaking"
 SEVERITY_SMELL: str = "smell"

package/hooks/hooks_constants/state_description_blocker_constants.py

@@ -40,12 +40,16 @@ ALL_COMMENT_TRANSITION_PATTERNS: list[Pattern[str]] = [
     compile(r"\bas of\b", IGNORECASE),
 ]
 
-CODE_FENCE_PATTERN: Pattern[str] = compile(r"```[\s\S]*?```")
+BLOCK_COMMENT_OPEN_MARKER: str = "/*"
+BLOCK_COMMENT_CLOSE_MARKER: str = "*/"
+
 INLINE_CODE_PATTERN: Pattern[str] = compile(r"``[^`]+``|`[^`]+`")
 DOUBLE_QUOTED_SPAN_PATTERN: Pattern[str] = compile(r'"[^"\n]*"')
 TRIPLE_QUOTED_BLOCK_PATTERN: Pattern[str] = compile(
     r'"""([\s\S]*?)"""|\'\'\'([\s\S]*?)\'\'\''
 )
+DOUBLE_QUOTE_BODY_GROUP: int = 1
+SINGLE_QUOTE_BODY_GROUP: int = 2
 
 PYTHON_EXTENSION: str = ".py"
 

package/hooks/hooks_constants/test_state_description_blocker_constants.py

@@ -0,0 +1,85 @@
+"""Behavior tests for state_description_blocker configuration constants."""
+
+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 blocking.state_description_blocker import _extract_comment_lines
+from hooks_constants.state_description_blocker_constants import (
+    ALL_BLOCK_COMMENT_EXTENSIONS,
+    ALL_COMMENT_TRANSITION_PATTERNS,
+    ALL_HASH_ONLY_EXTENSIONS,
+    ALL_MARKDOWN_EXTENSIONS,
+    BLOCK_COMMENT_CLOSE_MARKER,
+    BLOCK_COMMENT_OPEN_MARKER,
+    DOUBLE_QUOTE_BODY_GROUP,
+    SINGLE_QUOTE_BODY_GROUP,
+    TRIPLE_QUOTED_BLOCK_PATTERN,
+)
+
+
+def test_transition_patterns_match_their_own_phrase() -> None:
+    all_phrases = [
+        "instead of",
+        "previously",
+        "was previously",
+        "used to",
+        "no longer",
+        "switched to",
+    ]
+    for each_phrase in all_phrases:
+        sentence = f"The field is {each_phrase} required."
+        assert any(
+            each_pattern.search(sentence) for each_pattern in ALL_COMMENT_TRANSITION_PATTERNS
+        ), each_phrase
+
+
+def test_transition_patterns_do_not_match_unrelated_prose() -> None:
+    sentence = "The path selects the scan strategy for the file."
+    assert not any(
+        each_pattern.search(sentence) for each_pattern in ALL_COMMENT_TRANSITION_PATTERNS
+    )
+
+
+def test_block_comment_markers_close_a_single_line_block_comment() -> None:
+    text = f"{BLOCK_COMMENT_OPEN_MARKER} note {BLOCK_COMMENT_CLOSE_MARKER}\ncode();"
+    all_comment_lines = _extract_comment_lines(text, ".js")
+    assert all_comment_lines == [
+        (1, f"{BLOCK_COMMENT_OPEN_MARKER} note {BLOCK_COMMENT_CLOSE_MARKER}")
+    ]
+
+
+def test_block_comment_markers_carry_an_unclosed_comment_to_the_next_line() -> None:
+    text = f"{BLOCK_COMMENT_OPEN_MARKER} still open\nclosed here {BLOCK_COMMENT_CLOSE_MARKER}"
+    all_comment_lines = _extract_comment_lines(text, ".js")
+    assert all_comment_lines == [
+        (1, f"{BLOCK_COMMENT_OPEN_MARKER} still open"),
+        (2, f"closed here {BLOCK_COMMENT_CLOSE_MARKER}"),
+    ]
+
+
+def test_double_and_single_quote_body_groups_index_the_matching_quote_style() -> None:
+    double_quoted_match = TRIPLE_QUOTED_BLOCK_PATTERN.search('"""double body"""')
+    assert double_quoted_match is not None
+    assert double_quoted_match.group(DOUBLE_QUOTE_BODY_GROUP) == "double body"
+    assert double_quoted_match.group(SINGLE_QUOTE_BODY_GROUP) is None
+
+    single_quoted_match = TRIPLE_QUOTED_BLOCK_PATTERN.search("'''single body'''")
+    assert single_quoted_match is not None
+    assert single_quoted_match.group(SINGLE_QUOTE_BODY_GROUP) == "single body"
+    assert single_quoted_match.group(DOUBLE_QUOTE_BODY_GROUP) is None
+
+
+def test_extension_sets_are_disjoint_from_markdown_extensions() -> None:
+    assert not (ALL_HASH_ONLY_EXTENSIONS & ALL_MARKDOWN_EXTENSIONS)
+    assert not (ALL_BLOCK_COMMENT_EXTENSIONS & ALL_MARKDOWN_EXTENSIONS)
+
+
+def test_python_is_hash_only_and_never_block_comment() -> None:
+    assert ".py" in ALL_HASH_ONLY_EXTENSIONS
+    assert ".py" not in ALL_BLOCK_COMMENT_EXTENSIONS

package/hooks/test_followup_ledger.py

@@ -12,6 +12,7 @@ from followup_ledger import (
     FollowupFinding,
     all_recorded_findings,
     followup_ledger_path,
+    head_commit,
     record_followup_finding,
 )
 
@@ -21,6 +22,7 @@ def test_record_followup_finding_appends_one_readable_record(tmp_path: Path) ->
         rule_id="instruction-filename",
         file_path="docs/Claude.md",
         message="Use the canonical filename: docs/Claude.md",
+        check_id="instruction-filename",
     )
 
     record_followup_finding(tmp_path, finding)
@@ -29,8 +31,12 @@ def test_record_followup_finding_appends_one_readable_record(tmp_path: Path) ->
 
 
 def test_record_followup_finding_keeps_distinct_findings_apart(tmp_path: Path) -> None:
-    first = FollowupFinding("instruction-filename", "docs/Claude.md", "wrong name")
-    second = FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong mode")
+    first = FollowupFinding(
+        "instruction-filename", "docs/Claude.md", "wrong name", "instruction-filename"
+    )
+    second = FollowupFinding(
+        "instruction-mode", "docs/AGENTS.md", "wrong mode", "instruction-mode"
+    )
 
     record_followup_finding(tmp_path, first)
     record_followup_finding(tmp_path, second)
@@ -39,7 +45,9 @@ def test_record_followup_finding_keeps_distinct_findings_apart(tmp_path: Path) -
 
 
 def test_record_followup_finding_records_a_repeat_once(tmp_path: Path) -> None:
-    finding = FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong mode")
+    finding = FollowupFinding(
+        "instruction-mode", "docs/AGENTS.md", "wrong mode", "instruction-mode"
+    )
 
     record_followup_finding(tmp_path, finding)
     record_followup_finding(tmp_path, finding)
@@ -52,7 +60,9 @@ def test_all_recorded_findings_is_empty_without_a_ledger(tmp_path: Path) -> None
 
 
 def test_all_recorded_findings_skips_an_unreadable_line(tmp_path: Path) -> None:
-    finding = FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong mode")
+    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:
@@ -81,3 +91,81 @@ def test_record_followup_finding_swallows_a_write_failure(tmp_path: Path) -> Non
     )
 
     assert all_recorded_findings(tmp_path) == ()
+
+
+def test_a_recorded_finding_carries_its_check_severity_and_origin(
+    tmp_path: Path,
+) -> None:
+    finding = FollowupFinding(
+        rule_id="code-rules",
+        file_path="scripts/run.py",
+        message="Line 3: Constant TIMEOUT - move to config/",
+        check_id="code-rules/constant-outside-config",
+        severity="smell",
+        origin_commit="abc1234",
+    )
+
+    record_followup_finding(tmp_path, finding)
+
+    assert all_recorded_findings(tmp_path) == (finding,)
+
+
+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(
+        json.dumps(
+            {
+                "rule_id": "instruction-mode",
+                "file_path": "docs/AGENTS.md",
+                "message": "wrong mode",
+            }
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+
+    recorded_finding = all_recorded_findings(tmp_path)[0]
+
+    assert recorded_finding.check_id == "instruction-mode"
+    assert recorded_finding.severity == "smell"
+    assert recorded_finding.origin_commit == ""
+
+
+def test_one_smell_seen_under_a_later_commit_stays_one_record(tmp_path: Path) -> None:
+    first = FollowupFinding(
+        "code-rules", "run.py", "Line 3: x", "code-rules/x", "smell", "aaa1111"
+    )
+    same_smell_later = first._replace(origin_commit="bbb2222")
+
+    record_followup_finding(tmp_path, first)
+    record_followup_finding(tmp_path, same_smell_later)
+
+    assert all_recorded_findings(tmp_path) == (first,)
+
+
+def test_head_commit_reads_the_checked_out_revision(tmp_path: Path) -> None:
+    git_directory = tmp_path / ".git"
+    (git_directory / "refs" / "heads").mkdir(parents=True)
+    (git_directory / "HEAD").write_text("ref: refs/heads/main\n", encoding="utf-8")
+    (git_directory / "refs" / "heads" / "main").write_text(
+        "0123456789abcdef0123456789abcdef01234567\n", encoding="utf-8"
+    )
+
+    assert head_commit(tmp_path) == "0123456789abcdef0123456789abcdef01234567"
+
+
+def test_head_commit_reads_a_detached_revision(tmp_path: Path) -> None:
+    git_directory = tmp_path / ".git"
+    git_directory.mkdir()
+    (git_directory / "HEAD").write_text(
+        "0123456789abcdef0123456789abcdef01234567\n", encoding="utf-8"
+    )
+
+    assert head_commit(tmp_path) == "0123456789abcdef0123456789abcdef01234567"
+
+
+def test_head_commit_is_empty_outside_a_repository(tmp_path: Path) -> None:
+    assert head_commit(tmp_path) == ""

package/package.json

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

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

@@ -34,13 +34,39 @@ because the ledger holds them until a pull request does.
 ## The ledger
 
 A recorded finding lands in `.claude/followups/smells.jsonl` at the
-repository root, one JSON object per line carrying the rule identifier, the
-repository-relative path, and the message. `hooks/followup_ledger.py` writes
+repository root, one JSON object per line. `hooks/followup_ledger.py` writes
 and reads it. Every write there is fail-safe, so a ledger failure leaves the
 gate's decision unchanged.
 
+| Field | What it carries |
+|---|---|
+| `rule_id` | The rule that raised the finding |
+| `check_id` | The single check behind it, which a severity table keys on |
+| `file_path` | The repository-relative path the finding names |
+| `message` | The text a reader acts on |
+| `severity` | The class the gate put it in |
+| `origin_commit` | The revision checked out when it was recorded |
+
+The origin commit groups a follow-up pull request by the change that raised
+the findings. A smell seen again under a later revision keeps the revision
+that first raised it, so one smell stays one record.
+
 The ledger is per-checkout state and stays out of the repository.
 
+## The check identifier
+
+Most lint rules run one check, so their rule identifier already names it. The
+`code-rules` and `validators` rules bundle many checks behind one identifier.
+`scripts/policy_lint/check_catalog.py` resolves those to a `<rule>/<check>`
+identifier, which `cde lint --format json` emits as `check_id` on every
+diagnostic. A consumer partitions findings by that identifier rather than by
+message text.
+
+A message no catalog entry names resolves to `<rule>/unclassified`, which a
+partition treats as blocking. A check whose wording moves reports louder
+rather than going quiet, and the catalog's synchronization tests fail on the
+same change.
+
 ## Reading and clearing it
 
 | Command | What it does |
@@ -49,6 +75,13 @@ The ledger is per-checkout state and stays out of the repository.
 | `cde followup ingest REPORT` | Records the diagnostics a policy-lint JSON report carries |
 | `cde followup brief` | Writes the task an agent fixes them from |
 | `cde followup clear` | Empties the ledger |
+| `cde followup count` | Reports the backlog against the threshold |
+
+`count` exits non-zero once the backlog passes
+`FOLLOWUP_BACKLOG_THRESHOLD` in
+`scripts/dev_env_scripts_constants/followup_constants.py`, so a scheduled job
+escalates rather than opening one more quiet pull request. The number is the
+repository's setting, and raising or lowering it is one edit there.
 
 The `/fix-followups` command drives the whole pass: it reads the brief, fixes
 each rule group, opens a draft pull request, and clears the ledger.

package/scripts/dev_env_scripts_constants/followup_constants.py

@@ -30,18 +30,29 @@ LIST_COMMAND_NAME: str = "list"
 INGEST_COMMAND_NAME: str = "ingest"
 BRIEF_COMMAND_NAME: str = "brief"
 CLEAR_COMMAND_NAME: str = "clear"
+COUNT_COMMAND_NAME: str = "count"
 ALL_COMMAND_NAMES: tuple[str, ...] = (
     LIST_COMMAND_NAME,
     INGEST_COMMAND_NAME,
     BRIEF_COMMAND_NAME,
     CLEAR_COMMAND_NAME,
+    COUNT_COMMAND_NAME,
 )
 
 SUCCESS_EXIT_CODE: int = 0
 INVALID_INPUT_EXIT_CODE: int = 2
+BACKLOG_EXCEEDED_EXIT_CODE: int = 1
+
+FOLLOWUP_BACKLOG_THRESHOLD: int = 20
+BACKLOG_WITHIN_TEMPLATE: str = "{finding_count} follow-ups recorded, threshold {threshold}"
+BACKLOG_EXCEEDED_TEMPLATE: str = (
+    "{finding_count} follow-ups recorded, over the threshold of {threshold}. "
+    "Work the backlog down before the next change records more."
+)
 
 DIAGNOSTICS_KEY: str = "diagnostics"
 DIAGNOSTIC_RULE_ID_KEY: str = "rule_id"
+DIAGNOSTIC_CHECK_ID_KEY: str = "check_id"
 DIAGNOSTIC_MESSAGE_KEY: str = "message"
 DIAGNOSTIC_LOCATION_KEY: str = "location"
 LOCATION_PATH_KEY: str = "path"
@@ -51,11 +62,13 @@ LINE_SEPARATOR: str = "\n"
 EMPTY_LEDGER_MESSAGE: str = "no follow-ups recorded"
 UNREADABLE_REPORT_TEMPLATE: str = "cannot read the lint report: {report_path}"
 USAGE_TEXT: str = (
-    "Usage: followup_cli.py <list|ingest|brief|clear> [--repository-root PATH]\n"
+    "Usage: followup_cli.py <list|ingest|brief|clear|count> "
+    "[--repository-root PATH]\n"
     "  list              Name every recorded follow-up\n"
     "  ingest REPORT     Record every diagnostic in a policy-lint JSON report\n"
     "  brief             Write the task an agent works the follow-ups from\n"
-    "  clear             Empty the ledger"
+    "  clear             Empty the ledger\n"
+    "  count             Report the backlog size against the threshold"
 )
 
 BRIEF_HEADER: str = (
@@ -64,9 +77,13 @@ BRIEF_HEADER: str = (
     "already shipped. Keep the fixes mechanical, touch no behavior, and run "
     "the repository's own checks before pushing."
 )
-BRIEF_FINDING_TEMPLATE: str = "- [{rule_id}] {file_path}: {message}"
+BRIEF_FINDING_TEMPLATE: str = (
+    "- [{check_id}] {file_path}: {message} (recorded at {origin_commit})"
+)
 BRIEF_FOOTER_TEMPLATE: str = (
     "Once the pull request is open, empty the ledger with "
     "`python {command_path} clear`."
 )
-LIST_FINDING_TEMPLATE: str = "{rule_id}\t{file_path}\t{message}"
+LIST_FINDING_TEMPLATE: str = (
+    "{check_id}\t{file_path}\t{origin_commit}\t{message}"
+)