claude-dev-env 8.4.3 → 8.6.0

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

@@ -0,0 +1,105 @@
+# Flag Non-Breaking Findings
+
+**When this applies:** Writing or changing a local gate — a git hook, a
+pre-commit entry, a Claude tool-use hook — and deciding what one of its checks
+does when it finds something.
+
+## Rule
+
+A gate blocks on a breaking finding and records a non-breaking one.
+
+A **breaking** finding means the change is wrong: a bug, a secret in the
+tree, a broken test, a syntax error, an instruction file that fails to
+load. The gate fails and the work stops there.
+
+A **smell** finding means the change reads poorly: a length limit, a naming
+convention, a prose term, a comment rule, a structural preference. The gate
+records it and lets the commit, the push, or the tool call proceed. A later
+pull request carries the fix.
+
+Every check a gate runs declares which of the two it is. A check that cannot
+say which one it raises is a breaking check until someone decides otherwise.
+
+## Why
+
+A smell that blocks a commit stops delivery for something the reader would
+have fixed in the next pass anyway. The writer then reaches for the bypass
+flag, and the bypass turns off the breaking checks beside it. The gate that
+blocks on everything ends up enforcing nothing.
+
+Recording the smell keeps both halves working. The breaking checks stay
+sharp because nobody routes around them, and the smells still get fixed
+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. `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 |
+|---|---|
+| `cde followup list` | Names every recorded follow-up |
+| `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.
+
+## Worked example
+
+`scripts/validate_instruction_pairs.py` raises five findings and splits them
+on this line. A missing governing `AGENTS.md`, an import text that differs,
+and an instruction path that is not a regular file each stop the instructions
+loading, so the gate fails. A non-canonical filename and a Git mode other than
+100644 leave the instructions loading, so the gate records them and passes.
+
+`SEVERITY_BY_RULE_ID` in that module is the whole declaration. Add a check,
+add its row.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`ci-owns-the-gate.md`](ci-owns-the-gate.md) | The full check suite runs once, on CI |
+| [`git-workflow.md`](git-workflow.md) | A red required check blocks the branch |

package/scripts/dev_env_scripts_constants/followup_constants.py

@@ -0,0 +1,89 @@
+"""Constants for the follow-up ledger command and the instruction-pair gate.
+
+Script-level scalar constants live in dev_env_scripts_constants alongside
+timing.py and the other per-script constant modules.
+"""
+
+from __future__ import annotations
+
+FILENAME_RULE_ID: str = "instruction-filename"
+REGULAR_FILE_RULE_ID: str = "instruction-regular-file"
+GIT_MODE_RULE_ID: str = "instruction-git-mode"
+MISSING_AGENTS_RULE_ID: str = "instruction-missing-agents"
+IMPORT_TEXT_RULE_ID: str = "instruction-import-text"
+
+SEVERITY_BREAKING: str = "breaking"
+SEVERITY_SMELL: str = "smell"
+SEVERITY_BY_RULE_ID: dict[str, str] = {
+    FILENAME_RULE_ID: SEVERITY_SMELL,
+    REGULAR_FILE_RULE_ID: SEVERITY_BREAKING,
+    GIT_MODE_RULE_ID: SEVERITY_SMELL,
+    MISSING_AGENTS_RULE_ID: SEVERITY_BREAKING,
+    IMPORT_TEXT_RULE_ID: SEVERITY_BREAKING,
+}
+
+GATE_PASSED_EXIT_CODE: int = 0
+GATE_FAILED_EXIT_CODE: int = 1
+RECORDED_SMELL_TEMPLATE: str = "recorded for follow-up: %s"
+
+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"
+ABSENT_LOCATION_PATH: str = ""
+
+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|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\n"
+    "  count             Report the backlog size against the threshold"
+)
+
+BRIEF_HEADER: str = (
+    "Fix every finding below in one change, then open a draft pull request "
+    "for it. Each finding is non-breaking, so the change that raised it "
+    "already shipped. Keep the fixes mechanical, touch no behavior, and run "
+    "the repository's own checks before pushing."
+)
+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 = (
+    "{check_id}\t{file_path}\t{origin_commit}\t{message}"
+)

package/scripts/followup_cli.py

@@ -0,0 +1,347 @@
+#!/usr/bin/env python3
+"""Read and brief the follow-up ledger of non-breaking findings.
+
+A gate that finds a non-breaking smell records it rather than stopping the
+work. This command reads those records back.
+
+::
+
+    $ cde followup list
+    instruction-git-mode    CLAUDE.md    Commit the instruction file with Git mode 100644
+
+``list`` names what is outstanding, ``ingest`` adds the diagnostics from a
+policy-lint JSON report, ``brief`` writes the task an agent works from, and
+``clear`` empties the ledger once the follow-up pull request carries the
+fixes.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import TextIO
+
+from dev_env_scripts_constants.followup_constants import (
+    ABSENT_LOCATION_PATH,
+    ALL_COMMAND_NAMES,
+    BACKLOG_EXCEEDED_EXIT_CODE,
+    BACKLOG_EXCEEDED_TEMPLATE,
+    BACKLOG_WITHIN_TEMPLATE,
+    COUNT_COMMAND_NAME,
+    DIAGNOSTIC_CHECK_ID_KEY,
+    FOLLOWUP_BACKLOG_THRESHOLD,
+    BRIEF_COMMAND_NAME,
+    BRIEF_FINDING_TEMPLATE,
+    BRIEF_FOOTER_TEMPLATE,
+    BRIEF_HEADER,
+    DIAGNOSTIC_LOCATION_KEY,
+    DIAGNOSTIC_MESSAGE_KEY,
+    DIAGNOSTIC_RULE_ID_KEY,
+    DIAGNOSTICS_KEY,
+    EMPTY_LEDGER_MESSAGE,
+    INGEST_COMMAND_NAME,
+    INVALID_INPUT_EXIT_CODE,
+    LINE_SEPARATOR,
+    LIST_COMMAND_NAME,
+    LIST_FINDING_TEMPLATE,
+    LOCATION_PATH_KEY,
+    SUCCESS_EXIT_CODE,
+    UNREADABLE_REPORT_TEMPLATE,
+    USAGE_TEXT,
+)
+
+_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,
+    followup_ledger_path,
+    head_commit,
+    record_followup_finding,
+)
+from hooks_constants.followup_ledger_constants import SEVERITY_SMELL
+
+
+def _parse_arguments(all_arguments: list[str]) -> argparse.Namespace | None:
+    """Parse the command arguments.
+
+    Args:
+        all_arguments: The argument list after the program name.
+
+    Returns:
+        The parsed arguments, or None when the command name is unknown.
+    """
+    if not all_arguments or all_arguments[0] not in ALL_COMMAND_NAMES:
+        return None
+    argument_parser = argparse.ArgumentParser(add_help=False)
+    argument_parser.add_argument("command", choices=ALL_COMMAND_NAMES)
+    argument_parser.add_argument("report_path", nargs="?", default=None)
+    argument_parser.add_argument("--repository-root", type=Path, default=Path.cwd())
+    return argument_parser.parse_args(all_arguments)
+
+
+def _run_list(repository_root: Path, stdout: TextIO) -> int:
+    """Write one line per recorded finding.
+
+    Args:
+        repository_root: The repository whose ledger to read.
+        stdout: The stream the lines go to.
+
+    Returns:
+        SUCCESS_EXIT_CODE.
+    """
+    all_findings = all_recorded_findings(repository_root)
+    if not all_findings:
+        stdout.write(EMPTY_LEDGER_MESSAGE + LINE_SEPARATOR)
+        return SUCCESS_EXIT_CODE
+    for each_finding in all_findings:
+        stdout.write(_formatted_finding(LIST_FINDING_TEMPLATE, each_finding) + LINE_SEPARATOR)
+    return SUCCESS_EXIT_CODE
+
+
+def _formatted_finding(finding_template: str, finding: FollowupFinding) -> str:
+    """Fill one template with a finding's fields.
+
+    Args:
+        finding_template: A template naming any of rule_id, check_id,
+            severity, origin_commit, file_path, and message.
+        finding: The finding whose fields fill the template.
+
+    Returns:
+        The filled line.
+    """
+    return finding_template.format(
+        rule_id=finding.rule_id,
+        check_id=finding.check_id or finding.rule_id,
+        severity=finding.severity,
+        origin_commit=finding.origin_commit,
+        file_path=finding.file_path,
+        message=finding.message,
+    )
+
+
+def _parsed_lint_report(report_path: Path) -> dict[str, object] | None:
+    """Read one policy-lint JSON report into a mapping.
+
+    Args:
+        report_path: Path of the JSON report to read.
+
+    Returns:
+        The report mapping, or None when the file cannot be read as one.
+    """
+    try:
+        report_text = report_path.read_text(encoding="utf-8")
+        parsed_report = json.loads(report_text)
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return None
+    if not isinstance(parsed_report, dict):
+        return None
+    return parsed_report
+
+
+def _run_ingest(repository_root: Path, report_path: Path | None, stdout: TextIO) -> int:
+    """Record every diagnostic a policy-lint JSON report carries.
+
+    Args:
+        repository_root: The repository whose ledger receives the findings.
+        report_path: Path of the JSON report to read.
+        stdout: The stream messages go to.
+
+    Returns:
+        SUCCESS_EXIT_CODE once the report is recorded, or
+        INVALID_INPUT_EXIT_CODE when the report cannot be read.
+    """
+    if report_path is None:
+        stdout.write(USAGE_TEXT + LINE_SEPARATOR)
+        return INVALID_INPUT_EXIT_CODE
+    parsed_report = _parsed_lint_report(report_path)
+    if parsed_report is None:
+        stdout.write(
+            UNREADABLE_REPORT_TEMPLATE.format(report_path=report_path) + LINE_SEPARATOR
+        )
+        return INVALID_INPUT_EXIT_CODE
+
+    all_diagnostics = parsed_report.get(DIAGNOSTICS_KEY, [])
+    if not isinstance(all_diagnostics, list):
+        return SUCCESS_EXIT_CODE
+    origin_commit = head_commit(repository_root)
+    for each_diagnostic in all_diagnostics:
+        each_finding = _finding_from_diagnostic(each_diagnostic, origin_commit)
+        if each_finding is not None:
+            record_followup_finding(repository_root, each_finding)
+    return SUCCESS_EXIT_CODE
+
+
+def _finding_from_diagnostic(
+    diagnostic_by_key: object, origin_commit: str
+) -> FollowupFinding | None:
+    """Convert one lint diagnostic into a ledger finding.
+
+    A report reaches this command once its blocking findings are settled, so
+    every diagnostic it carries records as a smell.
+
+    Args:
+        diagnostic_by_key: One entry of the report's diagnostics list.
+        origin_commit: The revision the repository has checked out.
+
+    Returns:
+        The finding, or None when the entry carries no rule identifier and
+        message.
+    """
+    if not isinstance(diagnostic_by_key, dict):
+        return None
+    rule_id = diagnostic_by_key.get(DIAGNOSTIC_RULE_ID_KEY)
+    message = diagnostic_by_key.get(DIAGNOSTIC_MESSAGE_KEY)
+    if not isinstance(rule_id, str) or not isinstance(message, str):
+        return None
+    return FollowupFinding(
+        rule_id,
+        _diagnostic_file_path(diagnostic_by_key),
+        message,
+        _diagnostic_check_id(diagnostic_by_key, rule_id),
+        SEVERITY_SMELL,
+        origin_commit,
+    )
+
+
+def _diagnostic_check_id(diagnostic_by_key: dict[str, object], rule_id: str) -> str:
+    """Return the check identifier a diagnostic names.
+
+    Args:
+        diagnostic_by_key: One entry of the report's diagnostics list.
+        rule_id: The rule the diagnostic carries.
+
+    Returns:
+        The diagnostic's check identifier, or the rule identifier when a
+        report written before that field carries none.
+    """
+    check_id = diagnostic_by_key.get(DIAGNOSTIC_CHECK_ID_KEY)
+    if isinstance(check_id, str) and check_id:
+        return check_id
+    return rule_id
+
+
+def _diagnostic_file_path(diagnostic_by_key: dict[str, object]) -> str:
+    """Return the path a diagnostic names, or an empty string.
+
+    Args:
+        diagnostic_by_key: One entry of the report's diagnostics list.
+
+    Returns:
+        The diagnostic's path, or ABSENT_LOCATION_PATH when it names none.
+    """
+    location_by_key = diagnostic_by_key.get(DIAGNOSTIC_LOCATION_KEY)
+    if not isinstance(location_by_key, dict):
+        return ABSENT_LOCATION_PATH
+    location_path = location_by_key.get(LOCATION_PATH_KEY)
+    if not isinstance(location_path, str):
+        return ABSENT_LOCATION_PATH
+    return location_path
+
+
+def _run_brief(repository_root: Path, stdout: TextIO) -> int:
+    """Write the task an agent works the recorded follow-ups from.
+
+    Args:
+        repository_root: The repository whose ledger to read.
+        stdout: The stream the brief goes to.
+
+    Returns:
+        SUCCESS_EXIT_CODE.
+    """
+    all_findings = all_recorded_findings(repository_root)
+    if not all_findings:
+        stdout.write(EMPTY_LEDGER_MESSAGE + LINE_SEPARATOR)
+        return SUCCESS_EXIT_CODE
+
+    all_lines = [BRIEF_HEADER, ""]
+    all_lines.extend(
+        _formatted_finding(BRIEF_FINDING_TEMPLATE, each_finding)
+        for each_finding in all_findings
+    )
+    all_lines.append("")
+    all_lines.append(BRIEF_FOOTER_TEMPLATE.format(command_path=Path(__file__).resolve()))
+    stdout.write(LINE_SEPARATOR.join(all_lines) + LINE_SEPARATOR)
+    return SUCCESS_EXIT_CODE
+
+
+def _run_count(repository_root: Path, stdout: TextIO) -> int:
+    """Report the backlog size against the threshold.
+
+    Args:
+        repository_root: The repository whose ledger to measure.
+        stdout: The stream the line goes to.
+
+    Returns:
+        SUCCESS_EXIT_CODE while the backlog sits at or under the threshold,
+        and BACKLOG_EXCEEDED_EXIT_CODE once it passes it.
+    """
+    finding_count = len(all_recorded_findings(repository_root))
+    if finding_count <= FOLLOWUP_BACKLOG_THRESHOLD:
+        stdout.write(
+            BACKLOG_WITHIN_TEMPLATE.format(
+                finding_count=finding_count, threshold=FOLLOWUP_BACKLOG_THRESHOLD
+            )
+            + LINE_SEPARATOR
+        )
+        return SUCCESS_EXIT_CODE
+    stdout.write(
+        BACKLOG_EXCEEDED_TEMPLATE.format(
+            finding_count=finding_count, threshold=FOLLOWUP_BACKLOG_THRESHOLD
+        )
+        + LINE_SEPARATOR
+    )
+    return BACKLOG_EXCEEDED_EXIT_CODE
+
+
+def _run_clear(repository_root: Path) -> int:
+    """Empty the repository's ledger.
+
+    Args:
+        repository_root: The repository whose ledger to empty.
+
+    Returns:
+        SUCCESS_EXIT_CODE.
+    """
+    try:
+        followup_ledger_path(repository_root).unlink(missing_ok=True)
+    except OSError:
+        return SUCCESS_EXIT_CODE
+    return SUCCESS_EXIT_CODE
+
+
+def main(all_arguments: list[str], stdout: TextIO = sys.stdout) -> int:
+    """Run one follow-up command.
+
+    Args:
+        all_arguments: The argument list after the program name.
+        stdout: The stream every message goes to.
+
+    Returns:
+        The command's exit code.
+    """
+    parsed_arguments = _parse_arguments(all_arguments)
+    if parsed_arguments is None:
+        stdout.write(USAGE_TEXT + LINE_SEPARATOR)
+        return INVALID_INPUT_EXIT_CODE
+
+    repository_root = parsed_arguments.repository_root.resolve()
+    if parsed_arguments.command == LIST_COMMAND_NAME:
+        return _run_list(repository_root, stdout)
+    if parsed_arguments.command == INGEST_COMMAND_NAME:
+        raw_report_path = parsed_arguments.report_path
+        report_path = None if raw_report_path is None else Path(raw_report_path)
+        return _run_ingest(repository_root, report_path, stdout)
+    if parsed_arguments.command == BRIEF_COMMAND_NAME:
+        return _run_brief(repository_root, stdout)
+    if parsed_arguments.command == COUNT_COMMAND_NAME:
+        return _run_count(repository_root, stdout)
+    return _run_clear(repository_root)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/scripts/policy_lint/adapter_support.py

@@ -4,6 +4,7 @@ from collections.abc import Callable, Iterable
 from pathlib import Path
 from types import ModuleType
 
+from .check_catalog import check_id_for_message
 from .model import Diagnostic, Document, Location, Severity
 
 HookModuleLoader = Callable[[str], ModuleType]
@@ -69,7 +70,13 @@ def _diagnostics_for_messages(
             None if maybe_line is None else Location(document.path, maybe_line, 1)
         )
         all_diagnostics.append(
-            Diagnostic(rule_id, Severity.ERROR, each_message, location)
+            Diagnostic(
+                rule_id,
+                Severity.ERROR,
+                each_message,
+                location,
+                check_id_for_message(rule_id, each_message),
+            )
         )
     return tuple(all_diagnostics)
 

package/scripts/policy_lint/check_catalog.py

@@ -0,0 +1,44 @@
+"""Name the check behind one finding of a bundling rule.
+
+::
+
+    rule "code-rules", "Line 3: Constant TIMEOUT - move to config/"
+      -> code-rules/constant-outside-config
+    rule "code-rules", "Line 4: something no entry names"
+      -> code-rules/unclassified
+    rule "rmtree-safety", any message
+      -> rmtree-safety
+
+A consumer partitions findings into blocking and advisory ones by this
+identifier. A message no catalog entry names resolves to the unclassified
+identifier, which a partition treats as blocking, so a reworded message
+reports louder rather than quieter.
+"""
+
+from __future__ import annotations
+
+from .config.check_catalog_constants import (
+    ALL_BUNDLING_RULE_IDS,
+    ALL_CHECK_CATALOG_ENTRIES,
+    CHECK_ID_SEPARATOR,
+    UNCLASSIFIED_CHECK_NAME,
+)
+
+
+def check_id_for_message(rule_id: str, message: str) -> str:
+    """Return the check identifier one rule and message resolve to.
+
+    Args:
+        rule_id: The rule that raised the finding.
+        message: The finding's message text.
+
+    Returns:
+        The rule identifier for a rule that runs one check, or the rule
+        identifier joined to the name of the check the message names.
+    """
+    if rule_id not in ALL_BUNDLING_RULE_IDS:
+        return rule_id
+    for each_entry in ALL_CHECK_CATALOG_ENTRIES:
+        if each_entry.message_marker in message:
+            return rule_id + CHECK_ID_SEPARATOR + each_entry.check_name
+    return rule_id + CHECK_ID_SEPARATOR + UNCLASSIFIED_CHECK_NAME

package/scripts/policy_lint/config/check_catalog_constants.py

@@ -0,0 +1,59 @@
+"""The message markers that name which check inside a bundling rule spoke.
+
+Most lint rules run one check, so their rule identifier already names the
+check. Two rules bundle many checks behind one identifier, and a consumer that
+classifies a finding by severity needs to know which of them raised it. Each
+entry below pairs a stable fragment of a check's message with the name that
+identifies the check.
+"""
+
+from __future__ import annotations
+
+from typing import NamedTuple
+
+
+class CheckCatalogEntry(NamedTuple):
+    """One check inside a bundling rule, and the text that identifies it.
+
+    Attributes:
+        message_marker: A fragment the check's message always carries.
+        check_name: The name that identifies the check inside its rule.
+    """
+
+    message_marker: str
+    check_name: str
+
+
+CHECK_ID_SEPARATOR: str = "/"
+UNCLASSIFIED_CHECK_NAME: str = "unclassified"
+ALL_BUNDLING_RULE_IDS: frozenset[str] = frozenset({"code-rules", "validators"})
+
+ALL_CHECK_CATALOG_ENTRIES: tuple[CheckCatalogEntry, ...] = (
+    CheckCatalogEntry(
+        "exceeds blocking threshold - split into helpers", "function-length"
+    ),
+    CheckCatalogEntry(" - consider moving to config/", "function-local-constant"),
+    CheckCatalogEntry(" - move to config/", "constant-outside-config"),
+    CheckCatalogEntry(" - prefix with all_ (CODE_RULES §5)", "collection-name-prefix"),
+    CheckCatalogEntry(" - prefix with each_ (CODE_RULES §5)", "loop-variable-prefix"),
+    CheckCatalogEntry("Stuttering collection prefix", "stuttering-collection-prefix"),
+    CheckCatalogEntry("string separator", "unnamed-string-separator"),
+    CheckCatalogEntry("string magic value", "string-magic-value"),
+    CheckCatalogEntry(
+        "Block comment found - refactor to self-documenting code",
+        "block-comment-added",
+    ),
+    CheckCatalogEntry(
+        "Comment found - refactor to self-documenting code", "comment-added"
+    ),
+    CheckCatalogEntry("comment added:", "comment-diff"),
+    CheckCatalogEntry("docstring carries a", "docstring-runon-sentence"),
+    CheckCatalogEntry("summary runs", "docstring-prose-wall"),
+    CheckCatalogEntry(
+        "return type annotation (CODE_RULES §6)", "missing-return-annotation"
+    ),
+    CheckCatalogEntry(
+        "missing type annotation (CODE_RULES §6)", "missing-type-annotation"
+    ),
+    CheckCatalogEntry("Single-letter variable", "single-letter-variable"),
+)

package/scripts/policy_lint/model.py

@@ -254,15 +254,18 @@ class Diagnostic:
     severity: Severity
     message: str
     location: Location | None = None
+    check_id: str | None = None
 
     def as_dict(self) -> dict[str, object]:
         """Return a JSON-compatible diagnostic.
 
         Returns:
-            The diagnostic mapping.
+            The diagnostic mapping, whose check_id names the single check
+            behind the finding and falls back to the rule identifier.
         """
         return {
             "rule_id": self.rule_id,
+            "check_id": self.check_id or self.rule_id,
             "severity": self.severity.value,
             "message": self.message,
             "location": None if self.location is None else self.location.as_dict(),