claude-dev-env 8.21.0 → 8.22.0

package/hooks/blocking/reply_length_gate.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python3
+"""PreToolUse hook that caps the length of a chat reply before it posts.
+
+The gate reads the ``text`` field of the chat tools that post to the user.
+It denies the call when the text holds more than MAXIMUM_SENTENCE_COUNT
+sentences, or a sentence longer than MAXIMUM_WORDS_PER_SENTENCE words.
+Each non-empty line counts as its own sentence, so a list counts one
+sentence per item. URLs, markdown link targets, inline code spans, and
+fenced blocks carry no words.
+
+A length limit is a smell elsewhere in this package, recorded and fixed in a
+later pass. A posted reply reaches the user the moment it sends and has no
+later pass, so this gate denies it and the model resends a shorter one.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.reply_length_gate_constants import (
+    ALL_CHECKED_TOOL_NAMES,
+    ALLOW_EXIT_CODE,
+    BLOCK_EXIT_CODE,
+    FENCED_BLOCK_PATTERN,
+    HOOK_EVENT_NAME,
+    INLINE_CODE_PATTERN,
+    LINE_BREAK_PATTERN,
+    LINK_TARGET_PATTERN,
+    LONG_SENTENCE_MESSAGE,
+    MAXIMUM_SENTENCE_COUNT,
+    MAXIMUM_WORDS_PER_SENTENCE,
+    RETRY_INSTRUCTION,
+    SENTENCE_END_PATTERN,
+    SENTENCE_PREVIEW_SUFFIX,
+    SENTENCE_PREVIEW_WORD_COUNT,
+    TEXT_KEY,
+    TOO_MANY_SENTENCES_MESSAGE,
+    TOOL_INPUT_KEY,
+    TOOL_NAME_KEY,
+    URL_PATTERN,
+    WORD_PATTERN,
+    WORD_SEPARATOR,
+)
+
+
+def countable_text(reply_text: str) -> str:
+    """Remove the spans that carry no words: fenced blocks, code, link targets, URLs."""
+    without_fences = FENCED_BLOCK_PATTERN.sub(" ", reply_text)
+    without_code = INLINE_CODE_PATTERN.sub(" ", without_fences)
+    without_link_targets = LINK_TARGET_PATTERN.sub("]", without_code)
+    return URL_PATTERN.sub(" ", without_link_targets)
+
+
+def sentence_word_lists(reply_text: str) -> list[list[str]]:
+    """Split the text into sentences, one per line or terminal mark, as word lists."""
+    all_sentence_texts = [
+        each_sentence
+        for each_line in LINE_BREAK_PATTERN.split(countable_text(reply_text))
+        for each_sentence in SENTENCE_END_PATTERN.split(each_line)
+    ]
+    all_word_lists = [WORD_PATTERN.findall(each_sentence) for each_sentence in all_sentence_texts]
+    return [each_word_list for each_word_list in all_word_lists if each_word_list]
+
+
+def length_violation(reply_text: str) -> str | None:
+    """Return the deny reason for an over-long reply, or None when it fits."""
+    all_sentences = sentence_word_lists(reply_text)
+    if len(all_sentences) > MAXIMUM_SENTENCE_COUNT:
+        return TOO_MANY_SENTENCES_MESSAGE.format(
+            sentence_count=len(all_sentences), sentence_limit=MAXIMUM_SENTENCE_COUNT
+        )
+    for each_sentence in all_sentences:
+        if len(each_sentence) > MAXIMUM_WORDS_PER_SENTENCE:
+            sentence_preview = WORD_SEPARATOR.join(each_sentence[:SENTENCE_PREVIEW_WORD_COUNT])
+            return LONG_SENTENCE_MESSAGE.format(
+                word_count=len(each_sentence),
+                word_limit=MAXIMUM_WORDS_PER_SENTENCE,
+                sentence_preview=sentence_preview + SENTENCE_PREVIEW_SUFFIX,
+            )
+    return None
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    tool_name = hook_input.get(TOOL_NAME_KEY)
+    if tool_name not in ALL_CHECKED_TOOL_NAMES:
+        return ALLOW_EXIT_CODE
+    tool_input = hook_input.get(TOOL_INPUT_KEY)
+    if not isinstance(tool_input, dict):
+        return ALLOW_EXIT_CODE
+    reply_text = tool_input.get(TEXT_KEY)
+    if not isinstance(reply_text, str):
+        return ALLOW_EXIT_CODE
+    violation = length_violation(reply_text)
+    if violation is None:
+        return ALLOW_EXIT_CODE
+    block_reason = violation + RETRY_INSTRUCTION
+    log_hook_block(
+        Path(__file__).name,
+        HOOK_EVENT_NAME,
+        block_reason,
+        tool_name=str(tool_name),
+        offending_input_preview=reply_text,
+    )
+    sys.stderr.write(block_reason)
+    return BLOCK_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/test_edit_marker_gate.py

@@ -0,0 +1,110 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import edit_marker_gate
+
+UPDATE_TOOL_NAME = "mcp__chat__update_message"
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tool_name: str,
+    tool_input: dict[str, object],
+) -> tuple[int, str]:
+    hook_input = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": tool_name,
+        "tool_input": tool_input,
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = edit_marker_gate.main()
+    return exit_code, capsys.readouterr().err
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+
+
+def test_should_allow_a_clean_replacement_text(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, UPDATE_TOOL_NAME, {"message_id": "m1", "text": "The fix is filed."}
+    )
+    assert (exit_code, stderr_text) == (0, "")
+
+
+def test_should_deny_strikethrough_and_ask_for_the_clean_text(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        UPDATE_TOOL_NAME,
+        {"text": "~~Please pass this on.~~ The thread files it."},
+    )
+    assert exit_code == 2
+    assert "strikethrough" in stderr_text
+    assert "clean new text" in stderr_text
+
+
+@pytest.mark.parametrize(
+    "edited_text",
+    [
+        "Please pass this on. [Edit: nothing needed from you here.]",
+        "Done. [edit: the thread filed it]",
+        "Done. [ Edit : filed]",
+    ],
+)
+def test_should_deny_an_edit_note_in_any_case(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    edited_text: str,
+) -> None:
+    exit_code, stderr_text = run_gate(monkeypatch, capsys, UPDATE_TOOL_NAME, {"text": edited_text})
+    assert exit_code == 2
+    assert "[Edit:" in stderr_text
+
+
+def test_should_deny_a_marker_inside_a_replacement_card(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    card = {"blocks": [{"type": "section", "text": "~~Old plan~~ New plan."}]}
+    exit_code, _ = run_gate(
+        monkeypatch, capsys, UPDATE_TOOL_NAME, {"text": "New plan.", "card": card}
+    )
+    assert exit_code == 2
+
+
+def test_should_allow_markers_on_tools_that_edit_no_message(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch, capsys, "mcp__chat__reply", {"text": "~~old~~ [Edit: new]"}
+    )
+    assert exit_code == 0
+
+
+def test_should_allow_a_single_tilde_pair_and_the_word_edit(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        UPDATE_TOOL_NAME,
+        {"text": "Edit the file at ~/notes, about ~5 lines."},
+    )
+    assert exit_code == 0
+
+
+def test_should_allow_input_without_a_payload(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(b"not json")))
+    assert edit_marker_gate.main() == 0

package/hooks/blocking/test_reply_length_gate.py

@@ -0,0 +1,193 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import reply_length_gate
+
+REPLY_TOOL_NAME = "mcp__hearthbot__reply"
+POST_TOOL_NAME = "mcp__hearthbot__post_message"
+SIXTEEN_WORD_SENTENCE = (
+    "One two three four five six seven eight nine ten eleven twelve thirteen "
+    "fourteen fifteen sixteen."
+)
+FIFTEEN_WORD_SENTENCE = (
+    "One two three four five six seven eight nine ten eleven twelve thirteen fourteen fifteen."
+)
+
+
+def run_gate(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    tool_name: str,
+    tool_input: dict[str, object],
+) -> tuple[int, str]:
+    hook_input = {
+        "hook_event_name": "PreToolUse",
+        "tool_name": tool_name,
+        "tool_input": tool_input,
+    }
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = reply_length_gate.main()
+    return exit_code, capsys.readouterr().err
+
+
+@pytest.fixture(autouse=True)
+def isolated_home(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("USERPROFILE", str(tmp_path))
+
+
+def test_should_allow_three_short_sentences(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "The fix is in. Tests pass on CI. It ships with the next release."},
+    )
+    assert (exit_code, stderr_text) == (0, "")
+
+
+def test_should_allow_a_fifteen_word_sentence(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"text": FIFTEEN_WORD_SENTENCE})
+    assert exit_code == 0
+
+
+def test_should_deny_four_sentences_and_name_the_count(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "One. Two. Three. Four."},
+    )
+    assert exit_code == 2
+    assert "4 sentences" in stderr_text
+    assert "3" in stderr_text
+
+
+def test_should_deny_a_sixteen_word_sentence_and_name_it(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch, capsys, REPLY_TOOL_NAME, {"text": SIXTEEN_WORD_SENTENCE}
+    )
+    assert exit_code == 2
+    assert "16 words" in stderr_text
+    assert "15" in stderr_text
+    assert "One two three" in stderr_text
+
+
+def test_should_check_the_project_chat_post_tool(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, POST_TOOL_NAME, {"text": "One. Two. Three. Four."})
+    assert exit_code == 2
+
+
+def test_should_count_each_line_of_a_list_as_a_sentence(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, stderr_text = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "Done:\n- first item\n- second item\n- third item"},
+    )
+    assert exit_code == 2
+    assert "4 sentences" in stderr_text
+
+
+def test_should_not_count_urls_as_words(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    long_url = "https://example.com/" + "/".join(["segment"] * 20)
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": f"The draft is up at {long_url} for review."},
+    )
+    assert exit_code == 0
+
+
+def test_should_not_count_link_targets_as_words(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {
+            "text": "Read [the pull request](https://example.com/a/b/c/d/e/f/g/h/i/j/k/l/m/n/o/p) now."
+        },
+    )
+    assert exit_code == 0
+
+
+def test_should_not_count_backticked_spans_as_words(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {
+            "text": "Run `one two three four five six seven eight nine ten eleven twelve thirteen` now."
+        },
+    )
+    assert exit_code == 0
+
+
+def test_should_not_count_fenced_blocks(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    fenced_block = "```\nOne.\nTwo.\nThree.\nFour.\n" + SIXTEEN_WORD_SENTENCE + "\n```"
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": f"Paste this block.\n{fenced_block}"},
+    )
+    assert exit_code == 0
+
+
+def test_should_not_split_on_decimal_points(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch,
+        capsys,
+        REPLY_TOOL_NAME,
+        {"text": "Version 4.5 shipped. Speed rose 2.5 times. Nothing else moved."},
+    )
+    assert exit_code == 0
+
+
+def test_should_allow_other_tools(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(
+        monkeypatch, capsys, "mcp__other__reply", {"text": "One. Two. Three. Four."}
+    )
+    assert exit_code == 0
+
+
+def test_should_allow_a_call_without_text(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, _ = run_gate(monkeypatch, capsys, REPLY_TOOL_NAME, {"card": {"blocks": []}})
+    assert exit_code == 0
+
+
+def test_should_allow_empty_stdin(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr("sys.stdin", io.TextIOWrapper(io.BytesIO(b"")))
+    assert reply_length_gate.main() == 0

package/hooks/hooks.json

@@ -52,6 +52,26 @@
           }
         ]
       },
+      {
+        "matcher": "mcp__hearthbot__reply|mcp__hearthbot__post_message",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/reply_length_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
+      {
+        "matcher": "mcp__.*__update_message",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/edit_marker_gate.py",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "matcher": "*",
         "hooks": [

package/hooks/hooks_constants/edit_marker_gate_constants.py

@@ -0,0 +1,18 @@
+"""Constants for the edit marker gate PreToolUse hook."""
+
+import re
+
+MESSAGE_EDIT_TOOL_SUFFIX = "update_message"
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+HOOK_EVENT_NAME = "PreToolUse"
+ALLOW_EXIT_CODE = 0
+BLOCK_EXIT_CODE = 2
+STRIKETHROUGH_PATTERN = re.compile(r"~~[^~]+~~")
+EDIT_NOTE_PATTERN = re.compile(r"\[\s*edit\s*:", re.IGNORECASE)
+STRIKETHROUGH_MESSAGE = "Edited message holds strikethrough (~~text~~)."
+EDIT_NOTE_MESSAGE = 'Edited message holds an "[Edit:" note.'
+RETRY_INSTRUCTION = (
+    " An edit replaces the whole message. Resend the clean new text,"
+    " with nothing kept from the old version."
+)

package/hooks/hooks_constants/reply_length_gate_constants.py

@@ -0,0 +1,28 @@
+"""Constants for the reply length gate PreToolUse hook."""
+
+import re
+
+MAXIMUM_SENTENCE_COUNT = 3
+MAXIMUM_WORDS_PER_SENTENCE = 15
+ALL_CHECKED_TOOL_NAMES = frozenset({"mcp__hearthbot__reply", "mcp__hearthbot__post_message"})
+TOOL_NAME_KEY = "tool_name"
+TOOL_INPUT_KEY = "tool_input"
+TEXT_KEY = "text"
+HOOK_EVENT_NAME = "PreToolUse"
+ALLOW_EXIT_CODE = 0
+BLOCK_EXIT_CODE = 2
+FENCED_BLOCK_PATTERN = re.compile(r"```.*?(?:```|\Z)", re.DOTALL)
+INLINE_CODE_PATTERN = re.compile(r"`[^`\n]*`")
+LINK_TARGET_PATTERN = re.compile(r"\]\([^)\s]*\)")
+URL_PATTERN = re.compile(r"(?:https?://|www\.)\S+")
+LINE_BREAK_PATTERN = re.compile(r"\n+")
+SENTENCE_END_PATTERN = re.compile(r"(?<=[.!?])\s+")
+WORD_PATTERN = re.compile(r"[A-Za-z0-9]+(?:['.,-][A-Za-z0-9]+)*")
+SENTENCE_PREVIEW_WORD_COUNT = 6
+WORD_SEPARATOR = " "
+SENTENCE_PREVIEW_SUFFIX = "..."
+RETRY_INSTRUCTION = " Cut the text and resend the call."
+TOO_MANY_SENTENCES_MESSAGE = "Reply too long: {sentence_count} sentences, limit {sentence_limit}."
+LONG_SENTENCE_MESSAGE = (
+    'Sentence too long: {word_count} words, limit {word_limit}: "{sentence_preview}".'
+)

package/hooks/hooks_constants/test_edit_marker_gate_constants.py

@@ -0,0 +1,9 @@
+from hooks_constants import edit_marker_gate_constants as constants
+
+
+def test_gate_checks_every_message_edit_tool() -> None:
+    assert constants.MESSAGE_EDIT_TOOL_SUFFIX == "update_message"
+
+
+def test_gate_exit_codes_match_the_hook_contract() -> None:
+    assert (constants.ALLOW_EXIT_CODE, constants.BLOCK_EXIT_CODE) == (0, 2)

package/hooks/hooks_constants/test_reply_length_gate_constants.py

@@ -0,0 +1,15 @@
+from hooks_constants import reply_length_gate_constants as constants
+
+
+def test_gate_limits_replies_to_three_sentences_of_fifteen_words() -> None:
+    assert (constants.MAXIMUM_SENTENCE_COUNT, constants.MAXIMUM_WORDS_PER_SENTENCE) == (3, 15)
+
+
+def test_gate_checks_the_two_chat_tools_that_post_to_the_user() -> None:
+    assert constants.ALL_CHECKED_TOOL_NAMES == frozenset(
+        {"mcp__hearthbot__reply", "mcp__hearthbot__post_message"}
+    )
+
+
+def test_gate_exit_codes_match_the_hook_contract() -> None:
+    assert (constants.ALLOW_EXIT_CODE, constants.BLOCK_EXIT_CODE) == (0, 2)

package/package.json

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

package/rules/asd-ste100-language.md

@@ -26,6 +26,7 @@ definitions and dictionary decisions.
 - Use inclusive, neutral language.
 - Use periods, commas, colons, and bullets to show structure.
 - Preserve exact quoted labels, identifiers, formulas, titles, and interface text.
+- Send the reader only a result, a blocker, or a question. Leave out a line that says nothing is needed from them, and leave out which agent, session, or coordinator did the work.
 - Use `WARNING` for a risk of injury or death. Use `CAUTION` for a risk of equipment, tool, or machine damage. State the command or condition first, then state the result.
 - Aim for 20 words or fewer in a procedure sentence when the technical content allows.
 - Aim for 25 words or fewer in a descriptive sentence when the technical content allows.

package/rules/ci-owns-the-gate.md

@@ -64,6 +64,34 @@ A cache stays available on one condition. CI derives the key itself from the
 tree it is about to test, looks for a previous run under that key, and
 republishes that result. CI computes, CI verifies, CI decides.
 
+## A repository that runs no CI
+
+An owner can rule that a repository spends no CI minutes. There the local gate
+is the gate, and the agent that drives the pull request runs it on every head
+it asks to merge. The repository carries the gate as a `cde verify` manifest at
+`.claude/local-gate.json`: tests with collection floors, and lint.
+
+1. Check out the pull request head with a clean tree and fetch its base.
+2. Run the manifest against the base commit the pull request names:
+
+   ```
+   python <cde>/scripts/local_verification/cli.py --manifest .claude/local-gate.json --repo . --base <base sha> --output <outside the repository>/report.json
+   ```
+
+3. Publish the report:
+
+   ```
+   python <cde>/scripts/local_report_publisher.py --token-environment GH_TOKEN --repository <owner>/<name> --pull-number <number> --local-repo . --manifest .claude/local-gate.json --report <outside the repository>/report.json
+   ```
+
+The publisher checks the report against the manifest digest, the clean tree,
+and the live head and base, then posts the `local-checks` commit status. A
+report that fails any of those posts a failure or an error. The branch ruleset
+lists `local-checks` as a required status check, so the host refuses a merge
+until a passing report covers the head, and `agent_merge_check.py` prints
+`HOLD` on the same requirement. A push moves the head and leaves the status
+behind, so each new head runs the gate again.
+
 ## Sibling rules
 
 | Rule | Role |

package/rules/memory-stores-durable-facts.md

@@ -0,0 +1,57 @@
+# Memory Stores Durable Facts
+
+**When this applies:** Before you write or update a file in an auto-memory
+directory, and before you add its line to `MEMORY.md`.
+
+## Rule
+
+A memory must still help a fresh session, with no context, weeks later.
+
+Run one test on the draft. Strip every date, pull request number, issue number,
+commit, job path, session ID, and task number. When what remains is empty or
+false, the draft is run state. Put it in the task tracker, the pull request, or
+a handoff file beside the work, and save no memory.
+
+## What never becomes a memory
+
+| Shape | Example | Where it belongs |
+|---|---|---|
+| Run or program state | "paused at", "resume from", "4 of 11 merged", a pointer to a handoff file | The task tracker or the handoff file |
+| A pull request, issue, stack, or commit map | "#583, #605, #610 merged" | The epic issue or the pull request |
+| A temporary condition | A concurrency schedule, credits out, a fleet that works this week, a fix "until X lands" | The current conversation |
+| One session's topology | A session ID, a parallel session's worktree, a second-account dispatch setup | The current conversation |
+| A workaround for a hook, gate, or verifier as it behaved one day | "the minter never fires, so skip the check" | A fix to the hook, per [`correction-lens.md`](correction-lens.md) |
+| The story of one incident or bug fix | "the fold checkbox took five tries" | Git history and the pull request body |
+| Where code lives, or a design recipe for one build phase | A module layout, a prompt recipe for one engine version | The repository and its inventories |
+| A restatement of a rule file | "CI owns the gate" | The rule file already loaded |
+
+## What a memory holds
+
+- A preference or standing order the user stated, with the date the user set it.
+- A trap in the local setup or the platform that stays true, such as a shared
+  `rr-cache` that replays one-sided resolutions without a marker.
+- A pointer to an external resource: a dashboard, a repository, a tracker.
+
+Write the fact first. A date belongs only on a rule the user set on that date.
+
+## Keeping the folder current
+
+When a memory goes stale, delete it and its `MEMORY.md` line in the same run.
+A "superseded" note on a stale memory keeps a false fact loading into every
+session.
+
+## Why
+
+One project's memory folder held 104 index entries. A cleanup pass removed 57
+of them, and each one failed the test above. Handoffs outlived their work,
+pull request maps named merged branches, and a capacity schedule and a
+dispatch topology contradicted newer standing orders. Every stale memory loads
+into each session and reads as current.
+
+## Sibling rules
+
+| Rule | Role |
+|---|---|
+| [`correction-lens.md`](correction-lens.md) | A memory records a decision, and the control holds the behavior |
+| [`verify-before-asking.md`](verify-before-asking.md) | A recalled fact is a claim to re-check |
+| [`cleanup-temp-files.md`](cleanup-temp-files.md) | Scratch output leaves with the task |

package/rules/review-closure-is-a-check.md

@@ -25,6 +25,7 @@ It prints `CLOSED` and exits 0 when every finding on the head is answered. It pr
 | A thread the driving account opened | Itself |
 | A blocking `Claude Approvals` row | A push, which moves the head the check reports on |
 | A top-level comment on the pull request | A later top-level comment from the driving account |
+| A bot notice: a review-skipped note, a pointer to an updated summary, a Graphite verdict mirror, a Qodo change summary, a Qodo in-progress placeholder, or a Qodo review that found no issues | Itself |
 
 A review bot rewrites its summary comment on each pass. Its edit leaves an answered summary closed, because each new finding it has arrives as a review thread or a new comment. An edit from a person reopens the comment.
 

package/scripts/dev_env_scripts_constants/grok_worker_constants.py

@@ -87,12 +87,16 @@ ROLE_BUGTEAM: str = "bugteam"
 ROLE_CLEAN_CODER: str = "clean-coder"
 """Compatibility role for FIX and standards-fix using poteto-agent."""
 
+ROLE_TRANSLATOR: str = "translator"
+"""Role the shared_utils translation chain dispatches, served by poteto-agent."""
+
 DEFAULT_ROLE: str = ROLE_BUGTEAM
 """Role applied when the caller does not pass ``--role``."""
 
 ALL_AGENT_FILENAMES_BY_ROLE: dict[str, tuple[str, ...]] = {
     ROLE_BUGTEAM: ("poteto-agent.md",),
     ROLE_CLEAN_CODER: ("poteto-agent.md",),
+    ROLE_TRANSLATOR: ("poteto-agent.md",),
 }
 """Agent definition filenames required under ``agents/`` for each known role."""