claude-dev-env 8.74.1 → 8.75.0

package/.agents/skills/correction/SKILL.md

@@ -1,30 +1,30 @@
 ---
 name: correction
-description: File a correction the user made to an agent as one labeled GitHub issue, list the open corrections, write a handoff brief, or land the fix in this session with the fix playbook. Use when the user types /correction, /correction fix, says "file this as a correction", or asks to show the open corrections.
+description: Turn a correction the user made to an agent into a Suggested task card that starts a fix session in one click, list the corrections filed as issues before the card, write a handoff brief, or land the fix in this session with the fix playbook. Use when the user types /correction, /correction fix, says "file this as a correction", or asks to show the open corrections.
 argument-hint: "[fix] <what the agent got wrong, in the user's words>"
 ---
 
 # /correction
 
-The user corrected an agent and wants the fix to stick. A labeled issue is the shared store a corrections project watches. When `$ARGUMENTS` starts with the word `fix`, this session lands the fix itself: write the brief, then follow the fix playbook.
+The user corrected an agent and wants the fix to stick. By default the correction becomes a Suggested task card, and the user starts the fix session from it in one click. No issue is filed. When `$ARGUMENTS` starts with the word `fix`, this session lands the fix itself: write the brief, then follow the fix playbook.
 
-## File it
+## Hand it off
 
-Use this for `/correction <text>` and "file this as a correction: <text>". Run:
+Use this for `/correction <text>` and "file this as a correction: <text>".
 
-```bash
-python "${CLAUDE_SKILL_DIR}/scripts/correction_filing.py" file <<'CORRECTION'
-<the correction, word for word>
-CORRECTION
-```
-
-Pass the user's words exactly. The quoted heredoc keeps the shell from expanding `$`, backticks, and quotes in them. Print the one line the command prints, `Filed: <url>` or `Already filed: <url>`, and nothing else.
+1. Write the brief below, then build the card from it with [`scripts/correction_task_card.py`](scripts/correction_task_card.py). Pipe one JSON object in a quoted heredoc: `title` starts with a verb and stays under 60 characters, `tldr` is one plain sentence, `brief` is the brief block text, and `files` lists the repository-relative paths the brief names.
+   ```bash
+   python "${CLAUDE_SKILL_DIR}/scripts/correction_task_card.py" <<'CARD'
+   {"title": "<verb first>", "tldr": "<one sentence>", "brief": "<brief block, newlines as \n>", "files": ["<repo-relative path>"]}
+   CARD
+   ```
 
-When it prints `No correction filing config`, write the brief below instead and tell the user the config file it names.
+2. When the session has `mcp__ccd_session__spawn_task`, call it with the `title`, `tldr`, and `prompt` the script prints. Reply with the card title.
+3. Without that tool, run the script again with `--prompt-only` and print its output in one fenced `text` block as the handoff brief.
 
 ## List them
 
-For "show the open corrections", run `python "${CLAUDE_SKILL_DIR}/scripts/correction_filing.py" list` and print its lines.
+For "show the open corrections", run `python "${CLAUDE_SKILL_DIR}/scripts/correction_filing.py" list` and print its lines. It lists the issues filed before the card replaced filing, and the issues the correction flag mod still files.
 
 ## Brief
 
@@ -46,16 +46,19 @@ Keep each field to one or two lines. Leave out the layer and the fix design; the
 
 | Mode | What follows the brief |
 |---|---|
-| File, the default | The filed line, or the brief when no config exists. |
+| Hand off, the default | The task card, or the handoff brief when `spawn_task` is absent. |
 | `fix` | Read [`playbooks/fix.md`](playbooks/fix.md) right after the brief, and run its steps from step 2. |
 
 ## Layout
 
 | File | What it holds |
 |---|---|
-| `SKILL.md` | Filing, the brief, and the playbook index |
+| `SKILL.md` | The handoff, the listing, the brief, and the playbook index |
 | `playbooks/fix.md` | The steps that land one correction as a control and a pull request in this session |
-| `scripts/correction_filing.py` | Files one correction as a labeled issue, deduplicated, or lists the open ones |
+| `scripts/correction_task_card.py` | Builds the `spawn_task` title, tldr, and standalone prompt from the brief and the fix playbook |
+| `scripts/correction_task_card_constants/config/constants.py` | Card field rules and the prompt template |
+| `scripts/test_correction_task_card.py` | Behavior tests for the card against the shipped fix playbook |
+| `scripts/correction_filing.py` | Lists the open correction issues, and files one for the correction flag mod |
 | `scripts/correction_filing_constants/config/constants.py` | Config keys, issue shape, and redaction patterns |
 | `scripts/test_correction_filing.py` | Behavior tests with a stand-in `gh` |
 | `references/filing.md` | Config file, issue shape, dedupe, and commands |

package/.agents/skills/correction/references/filing.md

@@ -1,6 +1,6 @@
 # Correction filing
 
-`scripts/correction_filing.py` is the one filing path. The skill calls it.
+`scripts/correction_filing.py` files a correction as a labeled issue for the correction flag mod in claude-mods-framework, which runs `correction_filing.py file --source flag`. `/correction` hands a correction off as a task card and files no issue. The skill runs only `list`, which reads the issues filed before the card and the issues the flag mod files.
 
 ## Config
 

package/.agents/skills/correction/scripts/correction_task_card.py

@@ -0,0 +1,194 @@
+"""Build the Suggested task card that hands one correction to a fix session.
+
+The agent pipes a JSON object on standard input, and the script prints the
+three fields `spawn_task` takes::
+
+    python correction_task_card.py <<'CARD'
+    {"title": "Add a lint for bare except in hooks",
+     "tldr": "Agents keep writing bare except blocks in hooks.",
+     "brief": "Correction: stop writing bare except ...",
+     "files": ["packages/claude-dev-env/hooks/blocking/example.py"]}
+    CARD
+    {"title": "Add a lint ...", "tldr": "Agents keep ...", "prompt": "Land this correction ..."}
+
+The prompt carries the brief, the files, and the fix playbook steps from step 2
+on, so a fresh session needs nothing else. `--prompt-only` prints the prompt
+alone, for the handoff brief a session without `spawn_task` shows instead.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+from correction_task_card_constants.config.constants import (
+    ABSOLUTE_PATH_PATTERN,
+    ALL_CARD_KEYS,
+    BRIEF_KEY,
+    FAILURE_EXIT_CODE,
+    FILE_LINE_TEMPLATE,
+    FILES_KEY,
+    FIX_PLAYBOOK_DIRECTORY_NAME,
+    FIX_PLAYBOOK_FILE_NAME,
+    FIX_PLAYBOOK_FIRST_HANDED_OFF_STEP,
+    INVALID_INPUT_MESSAGE_TEMPLATE,
+    LINE_SEPARATOR,
+    MARKDOWN_LINK_PATTERN,
+    MAXIMUM_TITLE_LENGTH,
+    NO_FILES_LINE,
+    PROMPT_TEMPLATE,
+    REASON_ABSOLUTE_FILE_TEMPLATE,
+    REASON_EMPTY_FIELD_TEMPLATE,
+    REASON_FILES_NOT_A_LIST,
+    REASON_MULTI_LINE_FIELD_TEMPLATE,
+    REASON_NOT_AN_OBJECT,
+    REASON_TITLE_TOO_LONG_TEMPLATE,
+    SUCCESS_EXIT_CODE,
+    TITLE_KEY,
+    TLDR_KEY,
+    UTF8_ENCODING,
+)
+
+
+class CardInputRunFatal(ValueError):
+    """Stop the run when the piped card input breaks a field rule."""
+
+
+def _fix_playbook_path() -> Path:
+    skill_directory = Path(__file__).resolve().parent.parent
+    return skill_directory / FIX_PLAYBOOK_DIRECTORY_NAME / FIX_PLAYBOOK_FILE_NAME
+
+
+def handed_off_playbook_steps(playbook_text: str) -> str:
+    """Return the fix playbook from step 2 on, with each link reduced to its text.
+
+    Args:
+        playbook_text: the whole fix playbook.
+
+    Returns:
+        Step 2 through the reply line, readable without the skill's folder.
+    """
+    first_step_index = (
+        playbook_text.index(LINE_SEPARATOR + FIX_PLAYBOOK_FIRST_HANDED_OFF_STEP) + 1
+    )
+    return re.sub(
+        MARKDOWN_LINK_PATTERN, r"\1", playbook_text[first_step_index:]
+    ).strip()
+
+
+def _required_text(all_card_fields: dict[str, object], field: str) -> str:
+    raw_text = all_card_fields.get(field, "")
+    text = raw_text.strip() if isinstance(raw_text, str) else ""
+    if not text:
+        raise CardInputRunFatal(REASON_EMPTY_FIELD_TEMPLATE.format(field=field))
+    return text
+
+
+def _one_line_text(all_card_fields: dict[str, object], field: str) -> str:
+    text = _required_text(all_card_fields, field)
+    if LINE_SEPARATOR in text:
+        raise CardInputRunFatal(REASON_MULTI_LINE_FIELD_TEMPLATE.format(field=field))
+    return text
+
+
+def _card_title(all_card_fields: dict[str, object]) -> str:
+    title = _one_line_text(all_card_fields, TITLE_KEY)
+    if len(title) > MAXIMUM_TITLE_LENGTH:
+        raise CardInputRunFatal(
+            REASON_TITLE_TOO_LONG_TEMPLATE.format(
+                length=len(title), limit=MAXIMUM_TITLE_LENGTH
+            )
+        )
+    return title
+
+
+def _file_lines(all_card_fields: dict[str, object]) -> str:
+    all_files = all_card_fields.get(FILES_KEY, [])
+    if not isinstance(all_files, list) or not all(
+        isinstance(each, str) for each in all_files
+    ):
+        raise CardInputRunFatal(REASON_FILES_NOT_A_LIST)
+    all_named_paths = [each_path.strip() for each_path in all_files if each_path.strip()]
+    for each_path in all_named_paths:
+        if re.match(ABSOLUTE_PATH_PATTERN, each_path):
+            raise CardInputRunFatal(REASON_ABSOLUTE_FILE_TEMPLATE.format(path=each_path))
+    all_lines = [FILE_LINE_TEMPLATE.format(path=each_path) for each_path in all_named_paths]
+    return LINE_SEPARATOR.join(all_lines) or NO_FILES_LINE
+
+
+def build_task_card(
+    all_card_fields: dict[str, object], playbook_text: str
+) -> dict[str, str]:
+    """Return the title, tldr, and standalone prompt for `spawn_task`.
+
+    Args:
+        all_card_fields: the parsed object with title, tldr, brief, and files.
+        playbook_text: the whole fix playbook.
+
+    Returns:
+        The three `spawn_task` fields, in the order the tool lists them.
+
+    Raises:
+        CardInputRunFatal: a field is empty, spans lines, runs long, or names
+            an absolute file path.
+    """
+    prompt = PROMPT_TEMPLATE.format(
+        brief=_required_text(all_card_fields, BRIEF_KEY),
+        file_lines=_file_lines(all_card_fields),
+        playbook_steps=handed_off_playbook_steps(playbook_text),
+    )
+    all_card_texts = (
+        _card_title(all_card_fields),
+        _one_line_text(all_card_fields, TLDR_KEY),
+        prompt,
+    )
+    return dict(zip(ALL_CARD_KEYS, all_card_texts))
+
+
+def _parsed_card_fields(piped_text: str) -> dict[str, object]:
+    try:
+        all_card_fields = json.loads(piped_text)
+    except json.JSONDecodeError as error:
+        raise CardInputRunFatal(REASON_NOT_AN_OBJECT) from error
+    if not isinstance(all_card_fields, dict):
+        raise CardInputRunFatal(REASON_NOT_AN_OBJECT)
+    return all_card_fields
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Build a correction task card.")
+    parser.add_argument("--prompt-only", action="store_true")
+    return parser
+
+
+def main(all_arguments: list[str]) -> int:
+    """Read the card input from standard input and print the card or its prompt.
+
+    Args:
+        all_arguments: the command-line arguments after the script name.
+
+    Returns:
+        The process exit code.
+    """
+    parsed_arguments = _build_parser().parse_args(all_arguments)
+    playbook_text = _fix_playbook_path().read_text(encoding=UTF8_ENCODING)
+    try:
+        all_card_fields = _parsed_card_fields(
+            sys.stdin.buffer.read().decode(UTF8_ENCODING)
+        )
+        task_card = build_task_card(all_card_fields, playbook_text)
+    except CardInputRunFatal as error:
+        sys.stderr.write(INVALID_INPUT_MESSAGE_TEMPLATE.format(reason=error))
+        return FAILURE_EXIT_CODE
+    if parsed_arguments.prompt_only:
+        sys.stdout.write(task_card["prompt"])
+    else:
+        sys.stdout.write(json.dumps(task_card) + LINE_SEPARATOR)
+    return SUCCESS_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

package/.agents/skills/correction/scripts/correction_task_card_constants/config/constants.py

@@ -0,0 +1,38 @@
+"""Configuration constants for the correction task card command."""
+
+ABSOLUTE_PATH_PATTERN = r"^(?:[/\\~]|[A-Za-z]:)"
+BRIEF_KEY = "brief"
+ALL_CARD_KEYS = ("title", "tldr", "prompt")
+FAILURE_EXIT_CODE = 1
+LINE_SEPARATOR = "\n"
+FILE_LINE_TEMPLATE = "- `{path}`"
+FILES_KEY = "files"
+FIX_PLAYBOOK_FILE_NAME = "fix.md"
+FIX_PLAYBOOK_FIRST_HANDED_OFF_STEP = "2. "
+FIX_PLAYBOOK_DIRECTORY_NAME = "playbooks"
+MARKDOWN_LINK_PATTERN = r"\[([^\]]+)\]\([^)]+\)"
+MAXIMUM_TITLE_LENGTH = 59
+NO_FILES_LINE = "- None named in the session. Step 4 finds them."
+PROMPT_TEMPLATE = (
+    "Land this correction as one control and one pull request.\n\n"
+    "## Correction brief\n\n"
+    "{brief}\n\n"
+    "## Files, relative to the repository root\n\n"
+    "{file_lines}\n\n"
+    "## Fix playbook\n\n"
+    "The brief above is step 1. Start at step 2.\n\n"
+    "{playbook_steps}\n"
+)
+SUCCESS_EXIT_CODE = 0
+TITLE_KEY = "title"
+TLDR_KEY = "tldr"
+UTF8_ENCODING = "utf-8"
+INVALID_INPUT_MESSAGE_TEMPLATE = "Invalid card input: {reason}\n"
+REASON_NOT_AN_OBJECT = "standard input must hold one JSON object"
+REASON_EMPTY_FIELD_TEMPLATE = "{field} is empty"
+REASON_MULTI_LINE_FIELD_TEMPLATE = "{field} must be one line"
+REASON_TITLE_TOO_LONG_TEMPLATE = "title has {length} characters; the limit is {limit}"
+REASON_FILES_NOT_A_LIST = "files must be a list of strings"
+REASON_ABSOLUTE_FILE_TEMPLATE = (
+    "{path} is absolute; name it relative to the repository root"
+)

package/.agents/skills/correction/scripts/test_correction_task_card.py

@@ -0,0 +1,142 @@
+"""Behavior tests for correction_task_card against the shipped fix playbook."""
+
+from __future__ import annotations
+
+import importlib
+import io
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+SCRIPTS_DIRECTORY = Path(__file__).resolve().parent
+if str(SCRIPTS_DIRECTORY) not in sys.path:
+    sys.path.insert(0, str(SCRIPTS_DIRECTORY))
+
+correction_task_card = importlib.import_module("correction_task_card")
+
+FIX_PLAYBOOK_TEXT = (SCRIPTS_DIRECTORY.parent / "playbooks" / "fix.md").read_text(
+    encoding="utf-8"
+)
+
+
+def _card_input(**overrides: object) -> dict[str, object]:
+    card_input: dict[str, object] = {
+        "title": "Add a lint for bare except blocks in hooks",
+        "tldr": "Agents keep writing bare except blocks in hook files.",
+        "brief": "Correction: stop writing bare except\nEvidence: hooks/example.py:12",
+        "files": ["packages/claude-dev-env/hooks/blocking/example.py"],
+    }
+    card_input.update(overrides)
+    return card_input
+
+
+def _run_main(
+    card_input: object, all_arguments: list[str], monkeypatch: pytest.MonkeyPatch
+) -> int:
+    piped_bytes = json.dumps(card_input).encode("utf-8")
+    monkeypatch.setattr(
+        sys, "stdin", io.TextIOWrapper(io.BytesIO(piped_bytes), encoding="utf-8")
+    )
+    return correction_task_card.main(all_arguments)
+
+
+def test_should_print_the_three_spawn_task_fields(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    assert _run_main(_card_input(), [], monkeypatch) == 0
+    task_card = json.loads(capsys.readouterr().out)
+    assert list(task_card) == ["title", "tldr", "prompt"]
+    assert task_card["title"] == "Add a lint for bare except blocks in hooks"
+    assert task_card["tldr"] == "Agents keep writing bare except blocks in hook files."
+
+
+def test_should_carry_the_brief_files_and_playbook_steps_in_the_prompt() -> None:
+    prompt = correction_task_card.build_task_card(_card_input(), FIX_PLAYBOOK_TEXT)[
+        "prompt"
+    ]
+    assert (
+        "Correction: stop writing bare except\nEvidence: hooks/example.py:12" in prompt
+    )
+    assert "- `packages/claude-dev-env/hooks/blocking/example.py`" in prompt
+    assert "Start at step 2." in prompt
+    for each_step_number in range(2, 9):
+        assert f"\n{each_step_number}. " in prompt
+    assert "**Reply:**" in prompt
+
+
+def test_should_leave_out_step_one_and_relative_links() -> None:
+    prompt = correction_task_card.build_task_card(_card_input(), FIX_PLAYBOOK_TEXT)[
+        "prompt"
+    ]
+    assert "\n1. Write the brief" not in prompt
+    assert "](../" not in prompt
+    assert "`correction-lens.md`" in prompt
+
+
+def test_should_print_only_the_prompt_for_the_handoff_brief(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    assert _run_main(_card_input(), ["--prompt-only"], monkeypatch) == 0
+    printed = capsys.readouterr().out
+    assert (
+        printed
+        == correction_task_card.build_task_card(_card_input(), FIX_PLAYBOOK_TEXT)[
+            "prompt"
+        ]
+    )
+
+
+def test_should_name_no_files_when_the_session_names_none() -> None:
+    prompt = correction_task_card.build_task_card(
+        _card_input(files=[]), FIX_PLAYBOOK_TEXT
+    )["prompt"]
+    assert "- None named in the session. Step 4 finds them." in prompt
+
+
+@pytest.mark.parametrize(
+    ("overrides", "reason_fragment"),
+    [
+        ({"title": "x" * 60}, "title has 60 characters; the limit is 59"),
+        ({"title": "  "}, "title is empty"),
+        ({"title": "Add a lint\nfor hooks"}, "title must be one line"),
+        ({"tldr": "first line\nsecond line"}, "tldr must be one line"),
+        ({"brief": ""}, "brief is empty"),
+        ({"files": "hooks/example.py"}, "files must be a list of strings"),
+        ({"files": ["/home/me/repo/hooks/example.py"]}, "is absolute"),
+        ({"files": ["C:\\repo\\hooks\\example.py"]}, "is absolute"),
+        ({"files": ["~/repo/hooks/example.py"]}, "is absolute"),
+        ({"files": ["  /home/me/repo/hooks/example.py"]}, "is absolute"),
+    ],
+)
+def test_should_refuse_a_card_that_breaks_a_field_rule(
+    overrides: dict[str, object],
+    reason_fragment: str,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    assert _run_main(_card_input(**overrides), [], monkeypatch) == 1
+    captured = capsys.readouterr()
+    assert captured.out == ""
+    assert reason_fragment in captured.err
+
+
+def test_should_accept_a_title_at_the_length_limit() -> None:
+    task_card = correction_task_card.build_task_card(
+        _card_input(title="A" * 59), FIX_PLAYBOOK_TEXT
+    )
+    assert len(task_card["title"]) == 59
+
+
+def test_should_refuse_input_that_is_not_one_json_object(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    assert _run_main(["a", "list"], [], monkeypatch) == 1
+    assert "standard input must hold one JSON object" in capsys.readouterr().err
+
+
+def test_should_return_the_playbook_from_step_two() -> None:
+    handed_off_steps = correction_task_card.handed_off_playbook_steps(FIX_PLAYBOOK_TEXT)
+    assert handed_off_steps.startswith("2. ")
+    assert "pull request link" in handed_off_steps

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