claude-dev-env 8.74.2 → 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/package.json

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