claude-dev-env 8.4.3 → 8.5.0

package/commands/fix-followups.md

@@ -0,0 +1,66 @@
+---
+description: Fix every non-breaking finding the follow-up ledger holds and open a draft PR for it
+argument-hint: [repository root, or blank for the current repository]
+---
+
+Fix the non-breaking findings a local gate recorded rather than blocked on,
+and deliver them as one draft pull request.
+
+The repository root is `$ARGUMENTS`, or the current repository when that is
+blank.
+
+Use `rules/asd-ste100-language.md` for user-facing wording.
+
+## 1. Read the ledger
+
+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.
+
+## 2. Group the findings
+
+Group the lines by rule identifier. A rule with several findings takes one
+pass over every file it names, so the same fix shape lands once.
+
+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.
+
+## 3. Fix each group
+
+Each finding is non-breaking, so the change that raised it already shipped.
+Keep every fix mechanical. Touch no behavior, change no signature, and add no
+abstraction.
+
+Run the repository's own fast checks over the files you changed. Where a
+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.
+
+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.
+
+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>`.
+
+A finding the pull request left alone goes back in the ledger with
+`cde followup ingest`, so the next pass picks it up.
+
+## Report
+
+Name the pull request link, the rule groups fixed, the findings dropped as no
+longer present, and anything left in the ledger.

package/hooks/followup_ledger.py

@@ -0,0 +1,143 @@
+"""Append-only ledger of non-breaking findings awaiting a follow-up fix.
+
+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.
+
+Every write is fail-safe. A ledger that cannot be created or appended 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 json
+import sys
+from pathlib import Path
+from typing import NamedTuple
+
+_hooks_directory = str(Path(__file__).resolve().parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from hooks_constants.followup_ledger_constants import (
+    FILE_PATH_KEY,
+    ALL_FOLLOWUP_LEDGER_PATH_SEGMENTS,
+    LEDGER_APPEND_MODE,
+    LEDGER_ENCODING,
+    MESSAGE_KEY,
+    RULE_ID_KEY,
+)
+
+
+class FollowupFinding(NamedTuple):
+    """One non-breaking finding a later pull request resolves.
+
+    Attributes:
+        rule_id: Stable identifier of the check that raised the finding.
+        file_path: Repository-relative path the finding names.
+        message: The text a reader acts on.
+    """
+
+    rule_id: str
+    file_path: str
+    message: str
+
+
+def followup_ledger_path(repository_root: Path) -> Path:
+    """Return the ledger path for one repository.
+
+    Args:
+        repository_root: The repository whose ledger to address.
+
+    Returns:
+        The absolute path of that repository's follow-up ledger.
+    """
+    return repository_root.joinpath(*ALL_FOLLOWUP_LEDGER_PATH_SEGMENTS)
+
+
+def record_followup_finding(repository_root: Path, finding: FollowupFinding) -> None:
+    """Append one finding to the repository's ledger, once.
+
+    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. 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.
+    """
+    if finding in all_recorded_findings(repository_root):
+        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,
+        }
+    )
+    try:
+        ledger_path.parent.mkdir(parents=True, exist_ok=True)
+        with ledger_path.open(LEDGER_APPEND_MODE, encoding=LEDGER_ENCODING) as ledger_file:
+            ledger_file.write(record_text + "\n")
+    except OSError:
+        return
+
+
+def all_recorded_findings(repository_root: Path) -> tuple[FollowupFinding, ...]:
+    """Return every finding the repository's ledger holds, in record order.
+
+    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.
+
+    Args:
+        repository_root: The repository whose ledger to read.
+
+    Returns:
+        The recorded findings, in the order they were appended.
+    """
+    ledger_path = followup_ledger_path(repository_root)
+    try:
+        ledger_text = ledger_path.read_text(encoding=LEDGER_ENCODING)
+    except (OSError, UnicodeError):
+        return ()
+
+    all_findings: list[FollowupFinding] = []
+    for each_line in ledger_text.splitlines():
+        each_finding = _finding_from_line(each_line)
+        if each_finding is not None:
+            all_findings.append(each_finding)
+    return tuple(all_findings)
+
+
+def _finding_from_line(ledger_line: str) -> FollowupFinding | None:
+    """Parse one ledger line into a finding.
+
+    Args:
+        ledger_line: One line of the ledger file.
+
+    Returns:
+        The parsed finding, or None when the line carries no complete record.
+    """
+    stripped_line = ledger_line.strip()
+    if not stripped_line:
+        return None
+    try:
+        parsed_record = json.loads(stripped_line)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(parsed_record, dict):
+        return 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):
+        return None
+    return FollowupFinding(rule_id, file_path, message)

package/hooks/hooks_constants/followup_ledger_constants.py

@@ -0,0 +1,27 @@
+"""Constants for the non-breaking-finding follow-up ledger."""
+
+from __future__ import annotations
+
+__all__ = [
+    "ALL_FOLLOWUP_LEDGER_PATH_SEGMENTS",
+    "LEDGER_ENCODING",
+    "LEDGER_APPEND_MODE",
+    "RULE_ID_KEY",
+    "FILE_PATH_KEY",
+    "MESSAGE_KEY",
+    "SEVERITY_BREAKING",
+    "SEVERITY_SMELL",
+    "ALL_SEVERITY_NAMES",
+]
+
+ALL_FOLLOWUP_LEDGER_PATH_SEGMENTS: tuple[str, ...] = (".claude", "followups", "smells.jsonl")
+LEDGER_ENCODING: str = "utf-8"
+LEDGER_APPEND_MODE: str = "a"
+
+RULE_ID_KEY: str = "rule_id"
+FILE_PATH_KEY: str = "file_path"
+MESSAGE_KEY: str = "message"
+
+SEVERITY_BREAKING: str = "breaking"
+SEVERITY_SMELL: str = "smell"
+ALL_SEVERITY_NAMES: frozenset[str] = frozenset({SEVERITY_BREAKING, SEVERITY_SMELL})

package/hooks/test_followup_ledger.py

@@ -0,0 +1,83 @@
+"""Behavior tests for the non-breaking-finding follow-up ledger."""
+
+import json
+import sys
+from pathlib import Path
+
+_hooks_directory = str(Path(__file__).resolve().parent)
+if _hooks_directory not in sys.path:
+    sys.path.insert(0, _hooks_directory)
+
+from followup_ledger import (
+    FollowupFinding,
+    all_recorded_findings,
+    followup_ledger_path,
+    record_followup_finding,
+)
+
+
+def test_record_followup_finding_appends_one_readable_record(tmp_path: Path) -> None:
+    finding = FollowupFinding(
+        rule_id="instruction-filename",
+        file_path="docs/Claude.md",
+        message="Use the canonical filename: docs/Claude.md",
+    )
+
+    record_followup_finding(tmp_path, finding)
+
+    assert all_recorded_findings(tmp_path) == (finding,)
+
+
+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")
+
+    record_followup_finding(tmp_path, first)
+    record_followup_finding(tmp_path, second)
+
+    assert all_recorded_findings(tmp_path) == (first, second)
+
+
+def test_record_followup_finding_records_a_repeat_once(tmp_path: Path) -> None:
+    finding = FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong mode")
+
+    record_followup_finding(tmp_path, finding)
+    record_followup_finding(tmp_path, finding)
+
+    assert all_recorded_findings(tmp_path) == (finding,)
+
+
+def test_all_recorded_findings_is_empty_without_a_ledger(tmp_path: Path) -> None:
+    assert all_recorded_findings(tmp_path) == ()
+
+
+def test_all_recorded_findings_skips_an_unreadable_line(tmp_path: Path) -> None:
+    finding = FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong 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:
+        ledger_file.write("{ not json\n")
+
+    assert all_recorded_findings(tmp_path) == (finding,)
+
+
+def test_record_followup_finding_writes_one_json_object_per_line(tmp_path: Path) -> None:
+    record_followup_finding(
+        tmp_path, FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong mode")
+    )
+
+    all_lines = followup_ledger_path(tmp_path).read_text(encoding="utf-8").splitlines()
+
+    assert len(all_lines) == 1
+    assert json.loads(all_lines[0])["rule_id"] == "instruction-mode"
+
+
+def test_record_followup_finding_swallows_a_write_failure(tmp_path: Path) -> None:
+    blocking_file = tmp_path / ".claude"
+    blocking_file.write_text("not a directory", encoding="utf-8")
+
+    record_followup_finding(
+        tmp_path, FollowupFinding("instruction-mode", "docs/AGENTS.md", "wrong mode")
+    )
+
+    assert all_recorded_findings(tmp_path) == ()

package/package.json

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

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

@@ -0,0 +1,72 @@
+# Flag Non-Breaking Findings
+
+**When this applies:** Writing or changing a local gate — a git hook, a
+pre-commit entry, a Claude tool-use hook — and deciding what one of its checks
+does when it finds something.
+
+## Rule
+
+A gate blocks on a breaking finding and records a non-breaking one.
+
+A **breaking** finding means the change is wrong: a bug, a secret in the
+tree, a broken test, a syntax error, an instruction file that fails to
+load. The gate fails and the work stops there.
+
+A **smell** finding means the change reads poorly: a length limit, a naming
+convention, a prose term, a comment rule, a structural preference. The gate
+records it and lets the commit, the push, or the tool call proceed. A later
+pull request carries the fix.
+
+Every check a gate runs declares which of the two it is. A check that cannot
+say which one it raises is a breaking check until someone decides otherwise.
+
+## Why
+
+A smell that blocks a commit stops delivery for something the reader would
+have fixed in the next pass anyway. The writer then reaches for the bypass
+flag, and the bypass turns off the breaking checks beside it. The gate that
+blocks on everything ends up enforcing nothing.
+
+Recording the smell keeps both halves working. The breaking checks stay
+sharp because nobody routes around them, and the smells still get fixed
+because the ledger holds them until a pull request does.
+
+## The ledger
+
+A recorded finding lands in `.claude/followups/smells.jsonl` at the
+repository root, one JSON object per line carrying the rule identifier, the
+repository-relative path, and the message. `hooks/followup_ledger.py` writes
+and reads it. Every write there is fail-safe, so a ledger failure leaves the
+gate's decision unchanged.
+
+The ledger is per-checkout state and stays out of the repository.
+
+## Reading and clearing it
+
+| Command | What it does |
+|---|---|
+| `cde followup list` | Names every recorded follow-up |
+| `cde followup ingest REPORT` | Records the diagnostics a policy-lint JSON report carries |
+| `cde followup brief` | Writes the task an agent fixes them from |
+| `cde followup clear` | Empties the ledger |
+
+The `/fix-followups` command drives the whole pass: it reads the brief, fixes
+each rule group, opens a draft pull request, and clears the ledger.
+
+## Worked example
+
+`scripts/validate_instruction_pairs.py` raises five findings and splits them
+on this line. A missing governing `AGENTS.md`, an import text that differs,
+and an instruction path that is not a regular file each stop the instructions
+loading, so the gate fails. A non-canonical filename and a Git mode other than
+100644 leave the instructions loading, so the gate records them and passes.
+
+`SEVERITY_BY_RULE_ID` in that module is the whole declaration. Add a check,
+add its row.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`ci-owns-the-gate.md`](ci-owns-the-gate.md) | The full check suite runs once, on CI |
+| [`git-workflow.md`](git-workflow.md) | A red required check blocks the branch |

package/scripts/dev_env_scripts_constants/followup_constants.py

@@ -0,0 +1,72 @@
+"""Constants for the follow-up ledger command and the instruction-pair gate.
+
+Script-level scalar constants live in dev_env_scripts_constants alongside
+timing.py and the other per-script constant modules.
+"""
+
+from __future__ import annotations
+
+FILENAME_RULE_ID: str = "instruction-filename"
+REGULAR_FILE_RULE_ID: str = "instruction-regular-file"
+GIT_MODE_RULE_ID: str = "instruction-git-mode"
+MISSING_AGENTS_RULE_ID: str = "instruction-missing-agents"
+IMPORT_TEXT_RULE_ID: str = "instruction-import-text"
+
+SEVERITY_BREAKING: str = "breaking"
+SEVERITY_SMELL: str = "smell"
+SEVERITY_BY_RULE_ID: dict[str, str] = {
+    FILENAME_RULE_ID: SEVERITY_SMELL,
+    REGULAR_FILE_RULE_ID: SEVERITY_BREAKING,
+    GIT_MODE_RULE_ID: SEVERITY_SMELL,
+    MISSING_AGENTS_RULE_ID: SEVERITY_BREAKING,
+    IMPORT_TEXT_RULE_ID: SEVERITY_BREAKING,
+}
+
+GATE_PASSED_EXIT_CODE: int = 0
+GATE_FAILED_EXIT_CODE: int = 1
+RECORDED_SMELL_TEMPLATE: str = "recorded for follow-up: %s"
+
+LIST_COMMAND_NAME: str = "list"
+INGEST_COMMAND_NAME: str = "ingest"
+BRIEF_COMMAND_NAME: str = "brief"
+CLEAR_COMMAND_NAME: str = "clear"
+ALL_COMMAND_NAMES: tuple[str, ...] = (
+    LIST_COMMAND_NAME,
+    INGEST_COMMAND_NAME,
+    BRIEF_COMMAND_NAME,
+    CLEAR_COMMAND_NAME,
+)
+
+SUCCESS_EXIT_CODE: int = 0
+INVALID_INPUT_EXIT_CODE: int = 2
+
+DIAGNOSTICS_KEY: str = "diagnostics"
+DIAGNOSTIC_RULE_ID_KEY: str = "rule_id"
+DIAGNOSTIC_MESSAGE_KEY: str = "message"
+DIAGNOSTIC_LOCATION_KEY: str = "location"
+LOCATION_PATH_KEY: str = "path"
+ABSENT_LOCATION_PATH: str = ""
+
+LINE_SEPARATOR: str = "\n"
+EMPTY_LEDGER_MESSAGE: str = "no follow-ups recorded"
+UNREADABLE_REPORT_TEMPLATE: str = "cannot read the lint report: {report_path}"
+USAGE_TEXT: str = (
+    "Usage: followup_cli.py <list|ingest|brief|clear> [--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"
+)
+
+BRIEF_HEADER: str = (
+    "Fix every finding below in one change, then open a draft pull request "
+    "for it. Each finding is non-breaking, so the change that raised it "
+    "already shipped. Keep the fixes mechanical, touch no behavior, and run "
+    "the repository's own checks before pushing."
+)
+BRIEF_FINDING_TEMPLATE: str = "- [{rule_id}] {file_path}: {message}"
+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}"