claude-dev-env 8.5.0 → 8.6.0

package/bin/cde.mjs

@@ -7,16 +7,18 @@ import path from "node:path";
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const lintScriptPath = path.join(packageRoot, "scripts", "cde_lint.py");
 const verificationScriptPath = path.join(packageRoot, "scripts", "local_verification", "cli.py");
+const followupScriptPath = path.join(packageRoot, "scripts", "followup_cli.py");
 const posixSignalStatusOffset = 128;
 const lintCommandName = "lint";
 const verifyCommandName = "verify";
+const followupCommandName = "followup";
 const pythonOptionName = "--python";
 const pythonEnvironmentName = "CDE_PYTHON";
 
 
 export function createHelpText() {
     return [
-        "Usage: cde <lint|verify> [options]",
+        "Usage: cde <lint|verify|followup> [options]",
         "",
         "Run the policy linter with cde lint. Source modes are mutually exclusive:",
         "  --files PATH [PATH ...]  Current worktree files",
@@ -37,6 +39,13 @@ export function createHelpText() {
         "  --base SHA                Trusted base revision",
         "  --output PATH             JSON verification report",
         "",
+        "Read the follow-up ledger of non-breaking findings with cde followup:",
+        "  cde followup list         Name every recorded follow-up",
+        "  cde followup ingest PATH  Record a policy-lint JSON report",
+        "  cde followup brief        Write the task an agent fixes them from",
+        "  cde followup count        Report the backlog against the threshold",
+        "  cde followup clear        Empty the ledger",
+        "",
         "Python may also be selected with CDE_PYTHON.",
     ].join("\n");
 }
@@ -75,6 +84,14 @@ export function buildVerifyCommand(interpreter, forwardedArguments) {
 }
 
 
+export function buildFollowupCommand(interpreter, forwardedArguments) {
+    return {
+        executable: interpreter,
+        arguments: [followupScriptPath, ...forwardedArguments],
+    };
+}
+
+
 function takePythonOverride(allArguments) {
     const remainingArguments = [];
     let interpreterOverride;
@@ -170,12 +187,31 @@ export function runVerifyCommand(command, dependencies = {}) {
 }
 
 
+export function runFollowupCommand(command, dependencies = {}) {
+    return runChildCommand(command, "Unable to start the follow-up command.", dependencies);
+}
+
+
+const buildCommandByName = {
+    [lintCommandName]: buildLintCommand,
+    [verifyCommandName]: buildVerifyCommand,
+    [followupCommandName]: buildFollowupCommand,
+};
+
+
+const runCommandByName = {
+    [lintCommandName]: runLintCommand,
+    [verifyCommandName]: runVerifyCommand,
+    [followupCommandName]: runFollowupCommand,
+};
+
+
 export async function main(argumentsList = process.argv.slice(2), dependencies = {}) {
     if (argumentsList.length === 0 || argumentsList.includes("--help") || argumentsList.includes("-h")) {
         process.stdout.write(`${createHelpText()}\n`);
         return 0;
     }
-    if (![lintCommandName, verifyCommandName].includes(argumentsList[0])) {
+    if (!Object.hasOwn(buildCommandByName, argumentsList[0])) {
         process.stderr.write(`${createHelpText()}\n`);
         return 2;
     }
@@ -190,10 +226,8 @@ export async function main(argumentsList = process.argv.slice(2), dependencies =
         process.stderr.write("No usable Python interpreter found. Use --python or CDE_PYTHON.\n");
         return 2;
     }
-    const buildCommand = argumentsList[0] === lintCommandName ? buildLintCommand : buildVerifyCommand;
-    const command = buildCommand(interpreter, remainingArguments);
-    const runCommand = dependencies.runCommand
-        ?? (argumentsList[0] === lintCommandName ? runLintCommand : runVerifyCommand);
+    const command = buildCommandByName[argumentsList[0]](interpreter, remainingArguments);
+    const runCommand = dependencies.runCommand ?? runCommandByName[argumentsList[0]];
     return await runCommand(command, dependencies);
 }
 

package/bin/cde.test.mjs

@@ -268,3 +268,28 @@ test("reports a synchronous child start failure as invalid input", async () => {
     assert.equal(exitCode, 2);
     assert.deepEqual(messages, ["Unable to start the policy linter.\n"]);
 });
+
+
+test("dispatches followup to the follow-up ledger command", async () => {
+    let receivedCommand;
+    const exitCode = await main(
+        ["followup", "--python", "python-test", "list"],
+        {
+            findPython: async () => "unused-python",
+            runCommand: async (command) => {
+                receivedCommand = command;
+                return 0;
+            },
+        },
+    );
+    assert.equal(exitCode, 0);
+    assert.equal(receivedCommand.executable, "python-test");
+    assert.match(receivedCommand.arguments[0], /followup_cli\.py$/);
+    assert.deepEqual(receivedCommand.arguments.slice(1), ["list"]);
+});
+
+
+test("help names the followup command", () => {
+    assert.match(createHelpText(), /cde <lint\|verify\|followup>/);
+    assert.match(createHelpText(), /cde followup count/);
+});

package/commands/fix-followups.md

@@ -18,14 +18,20 @@ Run `cde followup brief --repository-root <root>`.
 When it prints `no follow-ups recorded`, report that and stop. There is no
 work.
 
-Otherwise the brief lists one line per finding, each carrying the rule
-identifier, the file, and the message.
+Otherwise the brief lists one line per finding, each carrying the check
+identifier, the file, the message, and the revision the finding was recorded
+against.
 
 ## 2. Group the findings
 
-Group the lines by rule identifier. A rule with several findings takes one
+Group the lines by check identifier. A check with several findings takes one
 pass over every file it names, so the same fix shape lands once.
 
+A finding whose check identifier ends in `unclassified` comes from a check the
+catalog does not name yet. Fix it like any other, and add its entry to
+`scripts/policy_lint/config/check_catalog_constants.py` with a sample in the
+catalog's synchronization test.
+
 Read each named file before editing it. A recorded finding names the state of
 the file at the moment the gate ran, so confirm the finding still holds.
 Keep a finding the current file still carries. Drop the rest.
@@ -41,14 +47,15 @@ finding names a generated file, regenerate it with the repository's tooling.
 
 ## 4. Open the pull request
 
-Branch from the repository's default branch. Commit each rule group on its
-own, with a message naming the rule identifier and the files.
+Branch from the repository's default branch. Commit each group on its own,
+with a message naming the check identifier and the files.
 
 Open the pull request as a draft. Write the body as:
 
 - One `Before:` paragraph saying which findings stood open.
 - One `After:` paragraph saying what the tree now holds.
-- A short `How` paragraph naming the rule groups and the files each touched.
+- A short `How` paragraph naming the groups, the files each touched, and the
+  revisions the findings were recorded against.
 
 Push, then confirm the required checks report on the branch head.
 
@@ -62,5 +69,5 @@ A finding the pull request left alone goes back in the ledger with
 
 ## Report
 
-Name the pull request link, the rule groups fixed, the findings dropped as no
-longer present, and anything left in the ledger.
+Name the pull request link, the groups fixed, the findings dropped because
+the current file reads clean, and anything left in the ledger.

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/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.0",
     "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}"
+)

package/scripts/followup_cli.py

@@ -26,6 +26,12 @@ 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,
@@ -54,8 +60,10 @@ 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:
@@ -99,7 +107,8 @@ def _formatted_finding(finding_template: str, finding: FollowupFinding) -> str:
     """Fill one template with a finding's fields.
 
     Args:
-        finding_template: A template naming rule_id, file_path, and message.
+        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:
@@ -107,6 +116,9 @@ def _formatted_finding(finding_template: str, finding: FollowupFinding) -> str:
     """
     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,
     )
@@ -156,18 +168,25 @@ def _run_ingest(repository_root: Path, report_path: Path | None, stdout: TextIO)
     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)
+        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) -> FollowupFinding | None:
+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
@@ -179,7 +198,31 @@ def _finding_from_diagnostic(diagnostic_by_key: object) -> FollowupFinding | Non
     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)
+    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:
@@ -226,6 +269,35 @@ def _run_brief(repository_root: Path, stdout: TextIO) -> int:
     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.
 
@@ -266,6 +338,8 @@ def main(all_arguments: list[str], stdout: TextIO = sys.stdout) -> int:
         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)
 
 

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(),

package/scripts/test_followup_cli.py

@@ -7,6 +7,10 @@ import json
 import sys
 from pathlib import Path
 
+from dev_env_scripts_constants.followup_constants import (
+    BACKLOG_EXCEEDED_EXIT_CODE,
+    FOLLOWUP_BACKLOG_THRESHOLD,
+)
 from followup_cli import main
 
 _hooks_directory = str(Path(__file__).resolve().parents[1] / "hooks")
@@ -76,7 +80,9 @@ def test_ingest_records_every_located_diagnostic(tmp_path: Path) -> None:
 
     assert exit_code == 0
     assert all_recorded_findings(tmp_path) == (
-        FollowupFinding("line-length", "src/app.py", "line runs past the limit"),
+        FollowupFinding(
+            "line-length", "src/app.py", "line runs past the limit", "line-length"
+        ),
     )
 
 
@@ -97,7 +103,9 @@ def test_ingest_records_a_diagnostic_without_a_location(tmp_path: Path) -> None:
     run_command(["ingest", str(report_path), "--repository-root", str(tmp_path)])
 
     assert all_recorded_findings(tmp_path) == (
-        FollowupFinding("inventory-drift", "", "inventory row missing"),
+        FollowupFinding(
+            "inventory-drift", "", "inventory row missing", "inventory-drift"
+        ),
     )
 
 
@@ -154,3 +162,109 @@ def test_an_unknown_command_reports_usage(tmp_path: Path) -> None:
 
     assert exit_code == 2
     assert "Usage" in output_text
+
+
+def test_ingest_carries_the_check_identifier_a_diagnostic_names(
+    tmp_path: Path,
+) -> None:
+    report_path = tmp_path / "lint.json"
+    write_lint_report(
+        report_path,
+        [
+            {
+                "rule_id": "code-rules",
+                "check_id": "code-rules/constant-outside-config",
+                "severity": "error",
+                "message": "Line 3: Constant TIMEOUT - move to config/",
+                "location": {"path": "scripts/run.py", "start_line": 3},
+            }
+        ],
+    )
+
+    run_command(["ingest", str(report_path), "--repository-root", str(tmp_path)])
+
+    recorded_finding = all_recorded_findings(tmp_path)[0]
+    assert recorded_finding.check_id == "code-rules/constant-outside-config"
+    assert recorded_finding.severity == "smell"
+
+
+def test_ingest_records_the_revision_the_repository_has_checked_out(
+    tmp_path: Path,
+) -> None:
+    (tmp_path / ".git").mkdir()
+    (tmp_path / ".git" / "HEAD").write_text("f00dcafe\n", encoding="utf-8")
+    report_path = tmp_path / "lint.json"
+    write_lint_report(
+        report_path,
+        [
+            {
+                "rule_id": "code-rules",
+                "check_id": "code-rules/function-length",
+                "message": "Line 9: Function 'run' is 74 lines",
+                "location": {"path": "scripts/run.py", "start_line": 9},
+            }
+        ],
+    )
+
+    run_command(["ingest", str(report_path), "--repository-root", str(tmp_path)])
+
+    assert all_recorded_findings(tmp_path)[0].origin_commit == "f00dcafe"
+
+
+def test_count_reports_an_empty_backlog(tmp_path: Path) -> None:
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert "0" in output_text
+
+
+def test_count_passes_while_the_backlog_sits_under_the_threshold(
+    tmp_path: Path,
+) -> None:
+    record_followup_finding(
+        tmp_path, FollowupFinding("code-rules", "run.py", "one smell", "code-rules/x")
+    )
+
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == 0
+    assert "1" in output_text
+
+
+def test_count_escalates_once_the_backlog_passes_the_threshold(
+    tmp_path: Path,
+) -> None:
+    for each_index in range(FOLLOWUP_BACKLOG_THRESHOLD + 1):
+        record_followup_finding(
+            tmp_path,
+            FollowupFinding(
+                "code-rules",
+                f"run{each_index}.py",
+                "one smell",
+                f"code-rules/x{each_index}",
+            ),
+        )
+
+    exit_code, output_text = run_command(["count", "--repository-root", str(tmp_path)])
+
+    assert exit_code == BACKLOG_EXCEEDED_EXIT_CODE
+    assert str(FOLLOWUP_BACKLOG_THRESHOLD) in output_text
+
+
+def test_list_names_the_check_behind_each_finding(tmp_path: Path) -> None:
+    record_followup_finding(
+        tmp_path,
+        FollowupFinding(
+            "code-rules",
+            "run.py",
+            "one smell",
+            "code-rules/constant-outside-config",
+            "smell",
+            "f00dcafe",
+        ),
+    )
+
+    _, output_text = run_command(["list", "--repository-root", str(tmp_path)])
+
+    assert "code-rules/constant-outside-config" in output_text
+    assert "f00dcafe" in output_text

package/scripts/test_validate_instruction_pairs.py

@@ -15,7 +15,8 @@ _hooks_directory = str(Path(__file__).resolve().parents[1] / "hooks")
 if _hooks_directory not in sys.path:
     sys.path.insert(0, _hooks_directory)
 
-from followup_ledger import all_recorded_findings
+from followup_ledger import all_recorded_findings, head_commit
+from hooks_constants.followup_ledger_constants import SEVERITY_SMELL
 
 
 def read_workflow(workflow_filename: str) -> str:
@@ -234,6 +235,27 @@ def test_run_gate_passes_a_smell_and_records_it(tmp_path: Path) -> None:
     ] == ["instruction-git-mode"]
 
 
+def test_a_recorded_smell_carries_its_severity_and_the_checked_out_revision(
+    tmp_path: Path,
+) -> None:
+    initialize_repository(tmp_path)
+    write_valid_pair(tmp_path)
+    make_git_mode_executable(tmp_path)
+    subprocess.run(
+        ["git", "commit", "--quiet", "-m", "instruction pair"],
+        cwd=tmp_path,
+        check=True,
+    )
+
+    run_gate(tmp_path)
+
+    recorded_finding = all_recorded_findings(tmp_path)[0]
+    assert recorded_finding.severity == SEVERITY_SMELL
+    assert recorded_finding.check_id == "instruction-git-mode"
+    assert recorded_finding.origin_commit == head_commit(tmp_path)
+    assert recorded_finding.origin_commit
+
+
 def test_run_gate_records_a_smell_it_finds_beside_a_breaking_finding(
     tmp_path: Path,
 ) -> None:

package/scripts/tests/test_policy_lint_rules_check_catalog.py

@@ -0,0 +1,151 @@
+"""Synchronization tests for the per-check identifier catalog.
+
+Each sample below is a message copied from the check that raises it. A check
+whose wording moves fails its sample here, so the catalog and the checks stay
+in step.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+from policy_lint.check_catalog import check_id_for_message
+from policy_lint.config.check_catalog_constants import (
+    ALL_CHECK_CATALOG_ENTRIES,
+    UNCLASSIFIED_CHECK_NAME,
+)
+from policy_lint.model import Diagnostic, Severity
+
+_BUNDLING_RULE_ID = "code-rules"
+_HOOKS_DIRECTORY = Path(__file__).resolve().parents[2] / "hooks"
+_TEST_FILE_PREFIX = "test_"
+_PYTHON_GLOB = "*.py"
+_SOURCE_ENCODING = "utf-8"
+
+ALL_MESSAGE_SAMPLES: tuple[tuple[str, str], ...] = (
+    (
+        "Line 20: Function 'run' is 74 lines - exceeds blocking threshold - "
+        "split into helpers",
+        "function-length",
+    ),
+    (
+        "Line 8: Function-local constant TIMEOUT - consider moving to config/",
+        "function-local-constant",
+    ),
+    ("Line 3: Constant TIMEOUT - move to config/", "constant-outside-config"),
+    (
+        "Line 5: Collection parameter paths - prefix with all_ (CODE_RULES §5)",
+        "collection-name-prefix",
+    ),
+    (
+        "Line 6: loop variable 'path' - prefix with each_ (CODE_RULES §5)",
+        "loop-variable-prefix",
+    ),
+    (
+        "Line 7: Stuttering collection prefix 'all_all_paths'",
+        "stuttering-collection-prefix",
+    ),
+    ("Line 9: string separator '\\n' - name it", "unnamed-string-separator"),
+    ("Line 10: string magic value 'utf-8'", "string-magic-value"),
+    (
+        "Line 11: Block comment found - refactor to self-documenting code",
+        "block-comment-added",
+    ),
+    (
+        "Line 12: Comment found - refactor to self-documenting code",
+        "comment-added",
+    ),
+    ("Line 13: TODO comment added: fix later", "comment-diff"),
+    (
+        "Line 14: module docstring carries a 44-word run-on sentence",
+        "docstring-runon-sentence",
+    ),
+    ("Line 15: module summary runs 9 prose lines", "docstring-prose-wall"),
+    (
+        "Line 16: parameter 'count' on 'run' missing type annotation (CODE_RULES §6)",
+        "missing-type-annotation",
+    ),
+    (
+        "Line 17: function 'run' missing return type annotation (CODE_RULES §6)",
+        "missing-return-annotation",
+    ),
+    ("src/app.py:3: Single-letter variable 'p'", "single-letter-variable"),
+)
+
+
+def _all_hook_source_texts() -> tuple[str, ...]:
+    return tuple(
+        each_path.read_text(encoding=_SOURCE_ENCODING)
+        for each_path in _HOOKS_DIRECTORY.rglob(_PYTHON_GLOB)
+        if not each_path.name.startswith(_TEST_FILE_PREFIX)
+    )
+
+
+@pytest.mark.parametrize(("sample_message", "expected_name"), ALL_MESSAGE_SAMPLES)
+def test_a_message_sample_resolves_to_its_check_name(
+    sample_message: str, expected_name: str
+) -> None:
+    resolved_check_id = check_id_for_message(_BUNDLING_RULE_ID, sample_message)
+
+    assert resolved_check_id == f"{_BUNDLING_RULE_ID}/{expected_name}"
+
+
+def test_every_catalog_entry_carries_a_message_sample() -> None:
+    all_sampled_names = {each_sample[1] for each_sample in ALL_MESSAGE_SAMPLES}
+    all_catalog_names = {
+        each_entry.check_name for each_entry in ALL_CHECK_CATALOG_ENTRIES
+    }
+
+    assert all_catalog_names == all_sampled_names
+
+
+@pytest.mark.parametrize("catalog_entry", ALL_CHECK_CATALOG_ENTRIES)
+def test_each_catalog_marker_is_still_written_by_a_check(catalog_entry) -> None:
+    all_source_texts = _all_hook_source_texts()
+
+    assert any(
+        catalog_entry.message_marker in each_text for each_text in all_source_texts
+    )
+
+
+def test_every_catalog_check_name_is_distinct_from_its_neighbours() -> None:
+    all_names = [each_entry.check_name for each_entry in ALL_CHECK_CATALOG_ENTRIES]
+
+    assert len(set(all_names)) == len(all_names)
+
+
+def test_an_unmatched_message_stays_unclassified() -> None:
+    resolved_check_id = check_id_for_message(
+        _BUNDLING_RULE_ID, "Line 4: a finding no catalog entry names"
+    )
+
+    assert resolved_check_id == f"{_BUNDLING_RULE_ID}/{UNCLASSIFIED_CHECK_NAME}"
+
+
+def test_a_rule_outside_the_bundling_set_keeps_its_own_identifier() -> None:
+    resolved_check_id = check_id_for_message(
+        "rmtree-safety", "Line 9: shutil.rmtree with ignore_errors=True"
+    )
+
+    assert resolved_check_id == "rmtree-safety"
+
+
+def test_a_diagnostic_reports_its_rule_identifier_when_it_carries_no_check_name() -> (
+    None
+):
+    diagnostic = Diagnostic("test-pairing", Severity.ERROR, "no matching test")
+
+    assert diagnostic.as_dict()["check_id"] == "test-pairing"
+
+
+def test_a_diagnostic_reports_the_check_identifier_it_carries() -> None:
+    diagnostic = Diagnostic(
+        "code-rules",
+        Severity.ERROR,
+        "Line 3: Constant TIMEOUT - move to config/",
+        None,
+        "code-rules/constant-outside-config",
+    )
+
+    assert diagnostic.as_dict()["check_id"] == "code-rules/constant-outside-config"

package/scripts/validate_instruction_pairs.py

@@ -29,7 +29,7 @@ from dev_env_scripts_constants.followup_constants import (
     REGULAR_FILE_RULE_ID,
     SEVERITY_BY_RULE_ID,
 )
-from followup_ledger import FollowupFinding, record_followup_finding
+from followup_ledger import FollowupFinding, head_commit, record_followup_finding
 from hooks_constants.followup_ledger_constants import SEVERITY_BREAKING
 
 class InstructionFinding(NamedTuple):
@@ -358,7 +358,14 @@ def _record_smell(repository_root: Path, finding: InstructionFinding) -> None:
     """
     record_followup_finding(
         repository_root,
-        FollowupFinding(finding.rule_id, finding.file_path, finding.message),
+        FollowupFinding(
+            finding.rule_id,
+            finding.file_path,
+            finding.message,
+            finding.rule_id,
+            finding.severity,
+            head_commit(repository_root),
+        ),
     )
     logger.warning(RECORDED_SMELL_TEMPLATE, finding.message)