claude-dev-env 8.74.1 → 8.74.2

package/bin/cde.mjs

@@ -45,7 +45,7 @@ export function createHelpText() {
         "  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",
-        "  cde followup dedupe       Remove exact repeated ledger lines",
+        "  cde followup dedupe       Give each finding its own file, once",
         "",
         "Python may also be selected with CDE_PYTHON.",
     ].join("\n");

package/bin/cde.test.mjs

@@ -292,5 +292,5 @@ test("dispatches followup to the follow-up ledger command", async () => {
 test("help names the followup command", () => {
     assert.match(createHelpText(), /cde <lint\|verify\|followup>/);
     assert.match(createHelpText(), /cde followup count/);
-    assert.match(createHelpText(), /cde followup dedupe/);
+    assert.match(createHelpText(), /cde followup dedupe +Give each finding its own file, once/);
 });

package/bin/install.mjs

@@ -1255,6 +1255,7 @@ export const RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS = new Set([
     'blocking/question_to_user_enforcer.py',
     'blocking/session_handoff_blocker.py',
     'blocking/artifact_look_gate.py',
+    'blocking/session_title_stop_gate.py',
     'session/issue_tracker_session_starter.py',
 ]);
 

package/bin/install.test.mjs

@@ -1231,6 +1231,7 @@ test('retired hook registrations stay managed so reinstall removes them', () =>
         'blocking/question_to_user_enforcer.py',
         'blocking/session_handoff_blocker.py',
         'blocking/artifact_look_gate.py',
+        'blocking/session_title_stop_gate.py',
         'session/issue_tracker_session_starter.py',
     ]);
     const shippedHooks = JSON.parse(

package/bin/merge_profile_settings.mjs

@@ -8,9 +8,8 @@
  * timestamped `.bak` beside it.
  *
  * Each run also retires the profile-level session-title Stop gate an earlier
- * install copied to `~/.claude`. The plugin's own session-title stop gate does
- * that job, so the merge removes the profile gate's Stop hook and allow rule
- * from each file and deletes the gate files.
+ * install copied to `~/.claude`. The merge removes that gate's Stop hook and
+ * allow rule from each file and deletes the gate files.
  *
  * Run `node merge_profile_settings.mjs --dry-run` to list the changes for
  * every profile on this machine without writing anything.

package/bin/merge_profile_settings.test.mjs

@@ -17,7 +17,7 @@ import {
 
 const FIXED_NOW = new Date('2026-10-04T12:00:00.000Z');
 const BACKUP_SUFFIX = '.2026-10-04T12-00-00-000Z.bak';
-const PLUGIN_STOP_GATE_COMMAND = 'python3 /plugin/hooks/blocking/session_title_stop_gate.py';
+const OTHER_STOP_HOOK_COMMAND = 'python3 /plugin/hooks/lifecycle/other_stop_hook.py';
 const PERMISSION_ALLOW_ITEMS = DECLARED_PROFILE_SETTINGS
     .find((eachEntry) => eachEntry.keyPath.join('.') === 'permissions.allow').items;
 const AUTO_MODE_ALLOW_ITEMS = DECLARED_PROFILE_SETTINGS
@@ -73,7 +73,7 @@ test('a missing settings.json is created with every declared entry and no Stop h
     assert.deepEqual(outcome.gate.removedPaths, []);
 });
 
-test('the retired profile gate leaves settings.json and ~/.claude, and the plugin gate stays', () => {
+test('the retired profile gate leaves settings.json and ~/.claude, and another Stop hook stays', () => {
     const homeDirectory = makeHome();
     const claudeDirectory = join(homeDirectory, '.claude');
     const settingsPath = join(claudeDirectory, 'settings.json');
@@ -83,7 +83,7 @@ test('the retired profile gate leaves settings.json and ~/.claude, and the plugi
                 {
                     hooks: [
                         { type: 'command', command: expandedRetiredGateCommand(homeDirectory), timeout: 10 },
-                        { type: 'command', command: PLUGIN_STOP_GATE_COMMAND },
+                        { type: 'command', command: OTHER_STOP_HOOK_COMMAND },
                     ],
                 },
                 { hooks: [{ type: 'command', command: expandedRetiredGateCommand(homeDirectory), timeout: 10 }] },
@@ -96,7 +96,7 @@ test('the retired profile gate leaves settings.json and ~/.claude, and the plugi
     const outcome = mergeProfileSettings([settingsPath], { dryRun: false, homeDirectory, now: FIXED_NOW });
 
     const mergedSettings = readSettings(settingsPath);
-    assert.deepEqual(stopCommands(mergedSettings), [PLUGIN_STOP_GATE_COMMAND]);
+    assert.deepEqual(stopCommands(mergedSettings), [OTHER_STOP_HOOK_COMMAND]);
     assert.equal(mergedSettings.hooks.Stop.length, 1);
     assert.equal(mergedSettings.permissions.allow.includes(RETIRED_SESSION_TITLE_GATE_PERMISSION), false);
     assert.equal(outcome.files[0].removals.length, 3);
@@ -152,7 +152,7 @@ test('a partial file gains only the missing entries, keeps other keys, and is ba
     const originalSettings = {
         model: 'opus',
         hooks: {
-            Stop: [{ hooks: [{ type: 'command', command: PLUGIN_STOP_GATE_COMMAND, timeout: 30 }] }],
+            Stop: [{ hooks: [{ type: 'command', command: OTHER_STOP_HOOK_COMMAND, timeout: 30 }] }],
             PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'python3 guard.py' }] }],
         },
         permissions: { allow: ['Read', 'mcp__claude-code-remote__set_session_title'], deny: ['Bash(rm:*)'] },

package/commands/fix-followups.md

@@ -13,7 +13,8 @@ Use `docs/rule-guides/asd-ste100-language.md` for user-facing wording.
 
 ## 1. Read the ledger
 
-Run `cde followup brief --repository-root <root>`.
+Run `cde followup brief --repository-root <root>`. The ledger is the
+`.claude/followups/` directory, one JSON file per finding.
 
 When it prints `no follow-ups recorded`, report that and stop. There is no
 work.
@@ -62,7 +63,9 @@ Push, then confirm the required checks report on the branch head.
 ## 5. Empty the ledger
 
 Once the pull request is open, run
-`cde followup clear --repository-root <root>`.
+`cde followup clear --repository-root <root>`. It removes every finding file.
+When the repository commits its ledger, commit those removals on the pull
+request branch and push.
 
 A finding the pull request left alone goes back in the ledger with
 `cde followup ingest`, so the next pass picks it up.

package/docs/rule-guides/flag-non-breaking-findings.md

@@ -10,7 +10,7 @@ A smell that blocks a commit stops delivery for something the reader could fix i
 
 ## The ledger
 
-Recorded findings land in `.claude/followups/smells.jsonl` at the repository root, one JSON object per line. `hooks/followup_ledger.py` writes and reads it. Ledger writes are fail-safe, so a ledger failure leaves the gate's decision unchanged.
+Recorded findings land in `.claude/followups/` at the repository root, one JSON file per finding. The file name is the first 16 hex digits of a SHA-256 hash over the check identifier, path, and message, so the same finding always writes the same file and two branches that record different findings never touch one file. `hooks/followup_ledger.py` writes and reads the directory. Ledger writes are fail-safe, so a ledger failure leaves the gate's decision unchanged.
 
 | Field | What it carries |
 |---|---|
@@ -21,7 +21,7 @@ Recorded findings land in `.claude/followups/smells.jsonl` at the repository roo
 | `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 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 first write into a directory with no `.gitignore` adds one holding `*`, so the ledger stays out of the repository by default. A repository that commits its findings commits its own `.gitignore`. This repository commits one holding `!*.json`.
 
 ## The check identifier
 
@@ -38,12 +38,10 @@ A message with no catalog entry resolves to `<rule>/unclassified`, which a parti
 | `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 |
-| `cde followup dedupe` | Removes exact repeated lines and keeps the first of each |
+| `cde followup dedupe` | Moves a legacy `smells.jsonl` into finding files and removes duplicate finding files |
 
 `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. The number is the repository's setting.
 
-`.gitattributes` marks the ledger `merge=union`, so a local `git merge` keeps both sides' appended lines without a conflict. GitHub's server-side merge ignores the attribute. Every ledger write drops exact repeated lines, and the `followup-ledger-duplicates` repository check fails a tree that still holds one.
-
 The `/fix-followups` command reads the brief, fixes each rule group, opens a pull request, and clears the ledger.
 
 ## Worked example

package/docs/rule-guides/paired-test-coverage.md

@@ -17,7 +17,7 @@ When you add a public function to a module whose test suite already exercises th
 
 Two complementary checks in `code_rules_paired_test.py` reach changed files through `code_rules_enforcer.py`, which the staged policy lint runs under its `code-rules` rule. No write-time hook runs them, so CI is where they report, against the merge base. The two checks cover the two write orders.
 
-Both checks record smells, per [`flag-non-breaking-findings.md`](../../rules/flag-non-breaking-findings.md). `SEVERITY_BY_CHECK_ID` in `scripts/policy_lint/config/check_catalog_constants.py` declares `code-rules/paired-test-missing-function` and `code-rules/paired-test-omitted-function` as smells. The lint prints each finding as a warning, records it in `.claude/followups/smells.jsonl`, and exits zero when every finding is a warning. A later pull request adds the missing tests.
+Both checks record smells, per [`flag-non-breaking-findings.md`](../../rules/flag-non-breaking-findings.md). `SEVERITY_BY_CHECK_ID` in `scripts/policy_lint/config/check_catalog_constants.py` declares `code-rules/paired-test-missing-function` and `code-rules/paired-test-omitted-function` as smells. The lint prints each finding as a warning, records it as one file in `.claude/followups/`, and exits zero when every finding is a warning. A later pull request adds the missing tests.
 
 `check_public_function_missing_paired_test` runs on a production Python write or edit and flags a public function when all of these hold:
 

package/docs/rule-guides/session-title.md

@@ -6,7 +6,7 @@ Back to the [rules index](../../rules/index.md).
 
 Before each turn ends, set the title to `<emoji> <name>`. Use the red flag when the user must act, the check mark when the work is done, and the hourglass while work, CI, or a merge queue runs. The name has 25 characters or fewer, in sentence case, with concrete nouns and no IDs, dates, or branch names.
 
-**Enforcement:** `hooks/blocking/session_title_format_gate.py` denies a malformed title; `hooks/blocking/session_title_stop_gate.py` blocks a turn end with no title.
+**Enforcement:** `hooks/blocking/session_title_format_gate.py` denies a malformed title.
 
 **When this applies:** The session has a tool whose name ends in `__set_session_title`, such as `mcp__claude-code-remote__set_session_title` in a cloud session or `mcp__ccd_session_mgmt__set_session_title` in the desktop app.
 
@@ -14,7 +14,7 @@ Before each turn ends, set the title to `<emoji> <name>`. Use the red flag when
 
 Before each turn ends, set the title to `<emoji> <name>`. Get the session id from `get_session` with no `session_id` when the tool asks for one.
 
-Set the title before the final reply, and set it in silence. The reply to the user carries no mention of the title, its emoji, or the reminder that asked for it. When a Stop hook asks for the title after the answer went out, make the call and end the turn with no text.
+Set the title before the final reply, and set it in silence. The reply to the user carries no mention of the title, its emoji, or the reminder that asked for it.
 
 ## Status emoji
 
@@ -30,4 +30,4 @@ The name has 25 characters or fewer and names the main change or outcome in conc
 
 ## Enforcement
 
-`hooks/blocking/session_title_format_gate.py` denies a malformed title. `hooks/blocking/session_title_stop_gate.py` blocks the end of a turn that set no title.
+`hooks/blocking/session_title_format_gate.py` denies a malformed title.

package/docs/templates/html-plan/README.md

@@ -1,6 +1,6 @@
 # html-plan page template
 
-Build a new artifact page from the html-plan skill. Load `house.css` from this folder after the plugin's `htmlplan.css`. The older [artifact page template](../artifact-page/README.md) stays available; use it when the request names it.
+Build a complex visual, such as a multi-part plan or evidence, from the html-plan skill. Load `house.css` from this folder after the plugin's `htmlplan.css`. The older [artifact page template](../artifact-page/README.md) stays available; use it when the request names it.
 
 ## Get the skill
 

package/hooks/features/conduct-gates.md

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

package/hooks/features/session-context.md

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

package/hooks/followup_ledger.py

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