claude-dev-env 8.4.3 → 8.6.0

package/bin/cde.mjs

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

package/bin/cde.test.mjs

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

package/commands/fix-followups.md

@@ -0,0 +1,73 @@
+---
+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 check
+identifier, the file, the message, and the revision the finding was recorded
+against.
+
+## 2. Group the findings
+
+Group the lines by check identifier. A check with several findings takes one
+pass over every file it names, so the same fix shape lands once.
+
+A finding whose check identifier ends in `unclassified` comes from a check the
+catalog does not name yet. Fix it like any other, and add its entry to
+`scripts/policy_lint/config/check_catalog_constants.py` with a sample in the
+catalog's synchronization test.
+
+Read each named file before editing it. A recorded finding names the state of
+the file at the moment the gate ran, so confirm the finding still holds.
+Keep a finding the current file still carries. Drop the rest.
+
+## 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 group on its own,
+with a message naming the check identifier and the files.
+
+Open the pull request as a draft. Write the body as:
+
+- One `Before:` paragraph saying which findings stood open.
+- One `After:` paragraph saying what the tree now holds.
+- A short `How` paragraph naming the groups, the files each touched, and the
+  revisions the findings were recorded against.
+
+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 groups fixed, the findings dropped because
+the current file reads clean, and anything left in the ledger.

package/hooks/followup_ledger.py

@@ -0,0 +1,248 @@
+"""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 (
+    ABSENT_ORIGIN_COMMIT,
+    ALL_FOLLOWUP_LEDGER_PATH_SEGMENTS,
+    ALL_GIT_HEAD_PATH_SEGMENTS,
+    CHECK_ID_KEY,
+    FILE_PATH_KEY,
+    GIT_DIRECTORY_NAME,
+    GIT_REFERENCE_PREFIX,
+    LEDGER_APPEND_MODE,
+    LEDGER_ENCODING,
+    MESSAGE_KEY,
+    ORIGIN_COMMIT_KEY,
+    RULE_ID_KEY,
+    SEVERITY_KEY,
+    SEVERITY_SMELL,
+)
+
+
+class FollowupFinding(NamedTuple):
+    """One non-breaking finding a later pull request resolves.
+
+    Attributes:
+        rule_id: Identifier of the rule that raised the finding.
+        file_path: Repository-relative path the finding names.
+        message: The text a reader acts on.
+        check_id: Identifier of the single check behind the finding. An empty
+            value reads back as the rule identifier.
+        severity: The class the gate put the finding in.
+        origin_commit: The revision checked out when the finding was recorded,
+            which groups a follow-up pull request by the change that raised it.
+    """
+
+    rule_id: str
+    file_path: str
+    message: str
+    check_id: str = ""
+    severity: str = SEVERITY_SMELL
+    origin_commit: str = ABSENT_ORIGIN_COMMIT
+
+    def tracking_key(self) -> tuple[str, str, str]:
+        """Return the fields that make this finding the same one over time.
+
+        The origin commit stays out of the key, so a smell seen again under a
+        later revision keeps the revision that first raised it.
+
+        Returns:
+            The check identifier, path, and message.
+        """
+        return (self.check_id or self.rule_id, self.file_path, self.message)
+
+
+def followup_ledger_path(repository_root: Path) -> Path:
+    """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.
+    """
+    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,
+        }
+    )
+    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,
+        _text_field(parsed_record, CHECK_ID_KEY, rule_id),
+        _text_field(parsed_record, SEVERITY_KEY, SEVERITY_SMELL),
+        _text_field(parsed_record, ORIGIN_COMMIT_KEY, ABSENT_ORIGIN_COMMIT),
+    )
+
+
+def _text_field(
+    all_record_fields: dict[str, object], field_key: str, fallback: str
+) -> str:
+    """Read one text field of a ledger record.
+
+    Args:
+        all_record_fields: The mapping one ledger line parsed into.
+        field_key: The key to read.
+        fallback: The value a record written before this field carried it takes.
+
+    Returns:
+        The field's text, or the fallback.
+    """
+    field_value = all_record_fields.get(field_key)
+    if isinstance(field_value, str) and field_value:
+        return field_value
+    return fallback
+
+
+def head_commit(repository_root: Path) -> str:
+    """Return the revision one repository has checked out.
+
+    ::
+
+        .git/HEAD holding "ref: refs/heads/main" -> the sha in refs/heads/main
+        .git/HEAD holding a sha                  -> that sha
+        no .git directory                        -> ""
+
+    The revision comes from the files git writes rather than from a git
+    process, so recording a finding starts no subprocess.
+
+    Args:
+        repository_root: The repository whose revision to read.
+
+    Returns:
+        The checked-out revision, or an empty string when none can be read.
+    """
+    head_path = repository_root.joinpath(*ALL_GIT_HEAD_PATH_SEGMENTS)
+    head_text = _file_text(head_path)
+    if head_text is None:
+        return ABSENT_ORIGIN_COMMIT
+    if not head_text.startswith(GIT_REFERENCE_PREFIX):
+        return head_text
+    reference_path = repository_root / GIT_DIRECTORY_NAME / head_text[
+        len(GIT_REFERENCE_PREFIX) :
+    ]
+    return _file_text(reference_path) or ABSENT_ORIGIN_COMMIT
+
+
+def _file_text(file_path: Path) -> str | None:
+    """Read one small git file into stripped text.
+
+    Args:
+        file_path: The file to read.
+
+    Returns:
+        The stripped text, or None when the file cannot be read.
+    """
+    try:
+        return file_path.read_text(encoding=LEDGER_ENCODING).strip()
+    except (OSError, UnicodeError):
+        return None

package/hooks/hooks_constants/followup_ledger_constants.py

@@ -0,0 +1,42 @@
+"""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",
+    "CHECK_ID_KEY",
+    "SEVERITY_KEY",
+    "ORIGIN_COMMIT_KEY",
+    "ABSENT_ORIGIN_COMMIT",
+    "ALL_GIT_HEAD_PATH_SEGMENTS",
+    "GIT_DIRECTORY_NAME",
+    "GIT_REFERENCE_PREFIX",
+    "SEVERITY_BREAKING",
+    "SEVERITY_SMELL",
+    "ALL_SEVERITY_NAMES",
+]
+
+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"
+CHECK_ID_KEY: str = "check_id"
+SEVERITY_KEY: str = "severity"
+ORIGIN_COMMIT_KEY: str = "origin_commit"
+
+ABSENT_ORIGIN_COMMIT: str = ""
+GIT_DIRECTORY_NAME: str = ".git"
+ALL_GIT_HEAD_PATH_SEGMENTS: tuple[str, ...] = (GIT_DIRECTORY_NAME, "HEAD")
+GIT_REFERENCE_PREFIX: str = "ref: "
+
+SEVERITY_BREAKING: str = "breaking"
+SEVERITY_SMELL: str = "smell"
+ALL_SEVERITY_NAMES: frozenset[str] = frozenset({SEVERITY_BREAKING, SEVERITY_SMELL})

package/hooks/test_followup_ledger.py

@@ -0,0 +1,171 @@
+"""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,
+    head_commit,
+    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",
+        check_id="instruction-filename",
+    )
+
+    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", "instruction-filename"
+    )
+    second = FollowupFinding(
+        "instruction-mode", "docs/AGENTS.md", "wrong mode", "instruction-mode"
+    )
+
+    record_followup_finding(tmp_path, first)
+    record_followup_finding(tmp_path, second)
+
+    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", "instruction-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", "instruction-mode"
+    )
+    record_followup_finding(tmp_path, finding)
+    ledger_path = followup_ledger_path(tmp_path)
+    with ledger_path.open("a", encoding="utf-8") as ledger_file:
+        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) == ()
+
+
+def test_a_recorded_finding_carries_its_check_severity_and_origin(
+    tmp_path: Path,
+) -> None:
+    finding = FollowupFinding(
+        rule_id="code-rules",
+        file_path="scripts/run.py",
+        message="Line 3: Constant TIMEOUT - move to config/",
+        check_id="code-rules/constant-outside-config",
+        severity="smell",
+        origin_commit="abc1234",
+    )
+
+    record_followup_finding(tmp_path, finding)
+
+    assert all_recorded_findings(tmp_path) == (finding,)
+
+
+def test_a_record_written_without_the_tracking_fields_still_reads(
+    tmp_path: Path,
+) -> None:
+    ledger_path = followup_ledger_path(tmp_path)
+    ledger_path.parent.mkdir(parents=True, exist_ok=True)
+    ledger_path.write_text(
+        json.dumps(
+            {
+                "rule_id": "instruction-mode",
+                "file_path": "docs/AGENTS.md",
+                "message": "wrong mode",
+            }
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+
+    recorded_finding = all_recorded_findings(tmp_path)[0]
+
+    assert recorded_finding.check_id == "instruction-mode"
+    assert recorded_finding.severity == "smell"
+    assert recorded_finding.origin_commit == ""
+
+
+def test_one_smell_seen_under_a_later_commit_stays_one_record(tmp_path: Path) -> None:
+    first = FollowupFinding(
+        "code-rules", "run.py", "Line 3: x", "code-rules/x", "smell", "aaa1111"
+    )
+    same_smell_later = first._replace(origin_commit="bbb2222")
+
+    record_followup_finding(tmp_path, first)
+    record_followup_finding(tmp_path, same_smell_later)
+
+    assert all_recorded_findings(tmp_path) == (first,)
+
+
+def test_head_commit_reads_the_checked_out_revision(tmp_path: Path) -> None:
+    git_directory = tmp_path / ".git"
+    (git_directory / "refs" / "heads").mkdir(parents=True)
+    (git_directory / "HEAD").write_text("ref: refs/heads/main\n", encoding="utf-8")
+    (git_directory / "refs" / "heads" / "main").write_text(
+        "0123456789abcdef0123456789abcdef01234567\n", encoding="utf-8"
+    )
+
+    assert head_commit(tmp_path) == "0123456789abcdef0123456789abcdef01234567"
+
+
+def test_head_commit_reads_a_detached_revision(tmp_path: Path) -> None:
+    git_directory = tmp_path / ".git"
+    git_directory.mkdir()
+    (git_directory / "HEAD").write_text(
+        "0123456789abcdef0123456789abcdef01234567\n", encoding="utf-8"
+    )
+
+    assert head_commit(tmp_path) == "0123456789abcdef0123456789abcdef01234567"
+
+
+def test_head_commit_is_empty_outside_a_repository(tmp_path: Path) -> None:
+    assert head_commit(tmp_path) == ""

package/package.json

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