@ethlete/agent-rules 0.1.0-next.1 → 0.1.0-next.11

package/content/hooks/context-warning.py

@@ -2,20 +2,47 @@
 """UserPromptSubmit hook: warn when the context window is getting large.
 
 Reads the hook input JSON from stdin, estimates the current context size from
-the last main-chain assistant message in the session transcript, and emits a
-warning (visible to both the user and Claude) when it crosses a threshold.
-Recommends the /handoff skill so work can continue in a fresh session.
+the session transcript, and emits a warning (visible to both the user and the
+agent) when it crosses a threshold. Recommends the handoff skill so work can
+continue in a fresh session.
 
-The thresholds are fractions of a token budget, and the budget is capped at the
-200k long-context pricing boundary: on models with a larger window, every
-request past that point bills the entire context at the premium rate, which
-costs far more than handing off into a fresh session ever would.
+Runs under both Claude Code and Codex, selected by `--agent` on the command
+line rather than sniffed from the payload — the generator writes the flag, so
+the two never have to be told apart at runtime. The two differ in three ways
+that matter here, all captured in AGENT_PROFILES:
+
+  * Transcript format. Claude writes one JSON object per message with
+    `message.usage`; Codex writes a rollout stream whose `token_count` events
+    carry a TokenUsageInfo. Codex's rollout format is explicitly not a stable
+    interface, so the parser searches each line for the usage object instead of
+    walking a fixed path.
+  * Context budget. Claude's budget is capped at the 200k long-context pricing
+    boundary: on models with a larger window, every request past that point
+    bills the entire context at the premium rate, which costs far more than
+    handing off into a fresh session ever would. Codex has no such boundary, so
+    its budget is just the window.
+  * How a handoff is invoked. Claude has a slash command and /clear; Codex has
+    neither and reads the skill from disk. The skill's own name differs per repo
+    (`ethlete-handoff` where the generator installed it, `handoff` where the repo
+    ships its own copy), so it is resolved at runtime — see handoff_skill().
+
+At the critical tier, if the session's permission_mode is "auto", the
+instruction escalates from "recommend" to "just do it": auto mode already
+means the user wants the agent acting without stopping to ask, and clearing +
+resuming can't be triggered programmatically (no hook or tool can submit
+input to a running session), so the best available automation is to save the
+handoff file itself immediately rather than waiting for a natural stopping
+point. Codex's permission_mode value set is undocumented, so its profile lists
+no auto modes and the escalation stays off there.
 
 Warns once per tier per session (state kept in a temp file); re-arms itself
-if the context shrinks again (e.g. after /compact).
+if the context shrinks again (e.g. after a compaction).
 
 Can be disabled per machine via a gitignored ethlete-agents.config.local.json
 at the repo root: {"disableHooks": true} or {"disableHooks": ["context-warning"]}.
+To keep the tiered warnings but drop just the auto-mode auto-save escalation,
+use {"disableAutoHandoffSave": true} instead - the critical tier then falls
+back to recommending a handoff, same as non-auto mode.
 
 Fail-safe: any error exits 0 with no output — the hook must never block a prompt.
 """
@@ -53,20 +80,131 @@ CONTEXT_WINDOWS = (
 )
 DEFAULT_WINDOW = 200_000
 
+AGENT_PROFILES = {
+    "claude": {
+        "premium_boundary": PREMIUM_BOUNDARY,
+        # Claude's transcript reports no window, so it is resolved from the model id.
+        "default_window": None,
+        "auto_modes": ("auto",),
+        "emits_system_message": True,
+        "act_now": "Run /{handoff} now and continue in a fresh session.",
+        "act_later": "consider /{handoff} to continue in a fresh session",
+        "recommend": "recommend the user run /{handoff} to save state and start a fresh session",
+        "suggest": "suggest the user run /{handoff} to save state and start a fresh session",
+        "save_now": (
+            "run the handoff skill's save mode right now (finish only an in-flight atomic "
+            "edit first, nothing new). Then tell the user exactly which handoff file was "
+            "written and that they should run /clear, then '/{handoff} resume <slug>', to "
+            "continue — clearing and resuming can't be done programmatically, so this is "
+            "the one step still on them."
+        ),
+    },
+    "codex": {
+        "premium_boundary": None,
+        # Only reached if a rollout omits model_context_window; the CONTEXT_WINDOWS table
+        # holds Claude model ids and would never match a Codex one.
+        "default_window": 272_000,
+        # Codex's permission_mode values are undocumented; until one is confirmed to mean
+        # "never ask", no value enables the auto-save escalation.
+        "auto_modes": (),
+        # Only hookSpecificOutput.additionalContext is documented for Codex, so the
+        # user-facing line is folded into the model-facing text instead.
+        "emits_system_message": False,
+        "act_now": "Save a handoff now and continue in a fresh session.",
+        "act_later": "consider saving a handoff and continuing in a fresh session",
+        "recommend": (
+            "tell the user you are near the context limit, then follow "
+            ".agents/skills/{handoff}/SKILL.md to save a handoff and have them start a "
+            "fresh session"
+        ),
+        "suggest": (
+            "suggest saving a handoff via .agents/skills/{handoff}/SKILL.md and "
+            "continuing in a fresh session"
+        ),
+        "save_now": (
+            "follow .agents/skills/{handoff}/SKILL.md and save a handoff right now "
+            "(finish only an in-flight atomic edit first, nothing new). Then tell the user "
+            "exactly which handoff file was written and that they should start a fresh "
+            "codex session and resume from it."
+        ),
+    },
+}
 
-def disabled_locally():
-    """True when the local config disables this hook (or all hooks) on this machine."""
-    root = os.environ.get("CLAUDE_PROJECT_DIR")
+
+def handoff_skill(root):
+    """Name of the handoff skill installed in this repo.
+
+    The generator prefixes every skill it writes, so the command is /ethlete-handoff in a
+    consumer repo — but a repo that excludes the generated copy and ships its own (the SDK
+    itself) has a plain /handoff instead. Naming the wrong one sends the user to a slash
+    command that does not exist, so it is read off disk rather than assumed.
+    """
+    for name in ("ethlete-handoff", "handoff"):
+        for skills_dir in (".claude/skills", ".agents/skills"):
+            if os.path.isdir(os.path.join(root or ".", skills_dir, name)):
+                return name
+    return "ethlete-handoff"
+
+
+def resolve_profile(profile, skill):
+    """Fills the installed handoff skill's name into a profile's message fragments."""
+    return {
+        key: value.replace("{handoff}", skill) if isinstance(value, str) else value
+        for key, value in profile.items()
+    }
+
+
+def agent_name(argv):
+    """The --agent value, defaulting to claude — older registrations pass no flag."""
+    for index, arg in enumerate(argv):
+        if arg == "--agent" and index + 1 < len(argv):
+            return argv[index + 1]
+        if arg.startswith("--agent="):
+            return arg.split("=", 1)[1]
+    return "claude"
+
+
+def repo_root(data):
+    """Repo root: the env var the agent sets, else derived from this script's own location.
+
+    The script always lives at <root>/.<agent>/hooks/ethlete/context-warning.py, so walking
+    four levels up works for any agent that has no project-dir variable of its own.
+    """
+    for variable in ("CLAUDE_PROJECT_DIR", "CODEX_PROJECT_DIR"):
+        value = os.environ.get(variable)
+        if value:
+            return value
+    here = os.path.abspath(__file__)
+    derived = os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(here))))
+    if os.path.isfile(os.path.join(derived, LOCAL_CONFIG_FILE)):
+        return derived
+    cwd = data.get("cwd")
+    return cwd if isinstance(cwd, str) and cwd else derived
+
+
+def load_local_config(root):
+    """Parsed ethlete-agents.config.local.json at the repo root, or {} if missing/unreadable."""
     if not root:
-        return False
+        return {}
     try:
         with open(os.path.join(root, LOCAL_CONFIG_FILE), encoding="utf-8") as f:
-            disabled = json.load(f).get("disableHooks")
+            config = json.load(f)
     except (OSError, ValueError, AttributeError):
-        return False
+        return {}
+    return config if isinstance(config, dict) else {}
+
+
+def disabled_locally(config):
+    """True when the local config disables this hook (or all hooks) on this machine."""
+    disabled = config.get("disableHooks")
     return disabled is True or (isinstance(disabled, list) and HOOK_NAME in disabled)
 
 
+def auto_handoff_save_disabled(config):
+    """True when the local config opts out of the auto-mode critical-tier auto-save."""
+    return config.get("disableAutoHandoffSave") is True
+
+
 def window_for(model):
     """Context window for a model id, by first substring match; DEFAULT_WINDOW otherwise."""
     if model:
@@ -76,10 +214,11 @@ def window_for(model):
     return DEFAULT_WINDOW
 
 
-def context_state(transcript_path):
-    """(tokens, model) from the last main-chain assistant message.
+def claude_context_state(transcript_path):
+    """(tokens, model, window) from the last main-chain assistant message.
 
-    tokens ≈ its total input tokens (fresh + cache read + cache creation).
+    tokens ≈ its total input tokens (fresh + cache read + cache creation). Claude reports no
+    window in the transcript, so it is resolved from the model id by the caller.
     """
     last_usage = None
     last_model = None
@@ -97,82 +236,154 @@ def context_state(transcript_path):
                 last_usage = usage
                 last_model = message.get("model") or last_model
     if not last_usage:
-        return 0, last_model
+        return 0, last_model, None
     tokens = (
         last_usage.get("input_tokens", 0)
         + last_usage.get("cache_read_input_tokens", 0)
         + last_usage.get("cache_creation_input_tokens", 0)
     )
-    return tokens, last_model
+    return tokens, last_model, None
+
+
+def find_token_usage_info(node):
+    """The deepest TokenUsageInfo-shaped dict in a parsed rollout line, or None.
+
+    Codex documents its rollout format as unstable, so this searches for the shape
+    (a dict carrying `last_token_usage`) rather than walking a fixed key path.
+    """
+    if isinstance(node, dict):
+        if isinstance(node.get("last_token_usage"), dict):
+            return node
+        for value in node.values():
+            found = find_token_usage_info(value)
+            if found:
+                return found
+    elif isinstance(node, list):
+        for value in node:
+            found = find_token_usage_info(value)
+            if found:
+                return found
+    return None
+
+
+def codex_context_state(transcript_path):
+    """(tokens, model, window) from the last token_count event in a Codex rollout.
+
+    tokens is the last request's `total_tokens` — Codex's own `tokens_in_context_window()`
+    is exactly that field, and `last_token_usage` is replaced per request while
+    `total_token_usage` accumulates across the whole session.
+    """
+    last_info = None
+    last_model = None
+    with open(transcript_path, encoding="utf-8") as f:
+        for line in f:
+            try:
+                obj = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            model = (obj.get("payload") or {}).get("model") if isinstance(obj.get("payload"), dict) else None
+            if isinstance(model, str) and model:
+                last_model = model
+            info = find_token_usage_info(obj)
+            if info:
+                last_info = info
+    if not last_info:
+        return 0, last_model, None
+    usage = last_info.get("last_token_usage") or {}
+    window = last_info.get("model_context_window")
+    return usage.get("total_tokens", 0), last_model, window if isinstance(window, int) else None
+
+
+CONTEXT_READERS = {"claude": claude_context_state, "codex": codex_context_state}
 
 
-def messages(tier, tokens, budget, priced):
+def messages(profile, tier, tokens, budget, priced, auto_mode):
     """(systemMessage, additionalContext) for a tier.
 
     priced: the budget is the pricing boundary, not the window — the reason to
     hand off is cost, not an imminent auto-compact.
+    auto_mode: at the critical tier, escalates from "recommend a handoff" to
+    "save it now" — see the module docstring for why.
     """
     k = f"~{tokens // 1000}k"
     pct = round(tokens / budget * 100)
     budget_k = f"{budget // 1000}k"
-    if tier == 2 and priced:
-        return (
-            f"🔴 Context is at {k} tokens — about to cross the {budget_k} long-context "
-            f"pricing boundary, after which every request bills the whole context at the "
-            f"premium rate. Run /handoff now and continue in a fresh session.",
-            f"[context-warning hook] The context is at {k} tokens — {pct}% of the "
-            f"{budget_k} long-context pricing boundary. Past it every request is billed at "
-            "the premium rate. Finish only the immediate step, then recommend the user run "
-            "/handoff to save state and start a fresh session. Do not start new sub-tasks.",
+
+    if priced:
+        approach = "about to cross" if tier == 2 else "approaching"
+        headline = f"Context is at {k} tokens — {approach} the {budget_k} long-context pricing boundary"
+        detail = (
+            f"The context is at {k} tokens — {pct}% of the {budget_k} long-context "
+            f"pricing boundary."
         )
+    else:
+        headline = f"Context is at {k} tokens ({pct}% of the {budget_k} window)"
+        detail = (
+            f"The context window is at {k} tokens — {pct}% of this model's "
+            f"{budget_k} window"
+        )
+
     if tier == 2:
-        return (
-            f"🔴 Context is at {k} tokens ({pct}% of the {budget_k} window) — "
-            f"auto-compact is imminent. Run /handoff now and continue in a fresh session.",
-            f"[context-warning hook] The context window is at {k} tokens — {pct}% of "
-            f"this model's {budget_k} window (critical, ≥{int(CRITICAL_FRACTION * 100)}%). "
-            "Finish only the immediate step, then recommend the user run /handoff to "
-            "save state and start a fresh session. Do not start new sub-tasks.",
+        threshold = f" (critical, ≥{int(CRITICAL_FRACTION * 100)}%)"
+        detail = detail if priced else f"{detail}{threshold}."
+        pressure = (
+            "Past it every request is billed at the premium rate. "
+            if priced
+            else ""
         )
-    if priced:
+        tail = "" if priced else " — auto-compact is imminent"
+        if auto_mode:
+            return (
+                f"🔴 {headline}{tail}. Auto mode is active: saving a handoff now.",
+                f"[context-warning hook] {detail} {pressure}Auto mode is active, so don't "
+                f"just recommend a handoff — {profile['save_now']}",
+            )
         return (
-            f"🟡 Context is at {k} tokens, approaching the {budget_k} long-context "
-            f"pricing boundary. At the next natural stopping point, consider /handoff "
-            f"to continue in a fresh session.",
-            f"[context-warning hook] The context is at {k} tokens — {pct}% of the "
-            f"{budget_k} long-context pricing boundary, past which every request is "
-            "billed at the premium rate. When the current task reaches a natural "
-            "stopping point, suggest the user run /handoff to save state and start a "
-            "fresh session. Keep working normally until then.",
+            f"🔴 {headline}{tail}. {profile['act_now']}",
+            f"[context-warning hook] {detail} {pressure}Finish only the immediate step, "
+            f"then {profile['recommend']}. Do not start new sub-tasks.",
         )
+
+    threshold = f" (≥{int(WARN_FRACTION * 100)}%)"
+    detail = detail if priced else f"{detail}{threshold}."
+    pressure = "Past it every request is billed at the premium rate. " if priced else ""
     return (
-        f"🟡 Context is at {k} tokens ({pct}% of the {budget_k} window). At the next "
-        f"natural stopping point, consider /handoff to continue in a fresh session.",
-        f"[context-warning hook] The context window is at {k} tokens — {pct}% of "
-        f"this model's {budget_k} window (≥{int(WARN_FRACTION * 100)}%). When the "
-        "current task reaches a natural stopping point, suggest the user run "
-        "/handoff to save state and start a fresh session. Keep working normally until then.",
+        f"🟡 {headline}. At the next natural stopping point, {profile['act_later']}.",
+        f"[context-warning hook] {detail} {pressure}When the current task reaches a "
+        f"natural stopping point, {profile['suggest']}. Keep working normally until then.",
     )
 
 
 def main():
-    if disabled_locally():
+    agent = agent_name(sys.argv[1:])
+    profile = AGENT_PROFILES.get(agent)
+    if not profile:
         return
+
     data = json.load(sys.stdin)
+    root = repo_root(data)
+    local_config = load_local_config(root)
+    if disabled_locally(local_config):
+        return
+
+    profile = resolve_profile(profile, handoff_skill(root))
+
     transcript_path = data.get("transcript_path")
     session_id = data.get("session_id", "unknown")
+    auto_mode = data.get("permission_mode") in profile["auto_modes"] and not auto_handoff_save_disabled(local_config)
     if not transcript_path or not os.path.isfile(transcript_path):
         return
 
-    tokens, model = context_state(transcript_path)
-    window = window_for(model)
-    budget = min(window, PREMIUM_BOUNDARY)
+    tokens, model, reported_window = CONTEXT_READERS[agent](transcript_path)
+    window = reported_window or profile["default_window"] or window_for(model)
+    boundary = profile["premium_boundary"]
+    budget = min(window, boundary) if boundary else window
     warn_tokens = int(budget * WARN_FRACTION)
     critical_tokens = int(budget * CRITICAL_FRACTION)
     tier = 2 if tokens >= critical_tokens else 1 if tokens >= warn_tokens else 0
 
     state_file = os.path.join(
-        tempfile.gettempdir(), f"claude-context-warning-{session_id}"
+        tempfile.gettempdir(), f"{agent}-context-warning-{session_id}"
     )
     prev_tier = 0
     try:
@@ -191,21 +402,25 @@ def main():
     if tier <= prev_tier:
         return  # already warned at this tier (or context shrank — state re-armed above)
 
-    system_message, additional_context = messages(tier, tokens, budget, budget < window)
-
-    print(
-        json.dumps(
-            {
-                "systemMessage": system_message,
-                "suppressOutput": True,
-                "hookSpecificOutput": {
-                    "hookEventName": "UserPromptSubmit",
-                    "additionalContext": additional_context,
-                },
-            }
-        )
+    system_message, additional_context = messages(
+        profile, tier, tokens, budget, budget < window, auto_mode
     )
 
+    if not profile["emits_system_message"]:
+        additional_context = f"{additional_context}\n\nTell the user: {system_message}"
+
+    payload = {
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": additional_context,
+        }
+    }
+    if profile["emits_system_message"]:
+        payload["systemMessage"] = system_message
+        payload["suppressOutput"] = True
+
+    print(json.dumps(payload))
+
 
 if __name__ == "__main__":
     try:

package/content/output-styles/ste-clarity.md

@@ -0,0 +1,131 @@
+---
+name: ste-clarity
+description: Write all prose in ASD-STE100 Simplified Technical English — approved words, simple verb forms, active voice, one idea per sentence.
+keep-coding-instructions: true
+---
+
+# ASD-STE100 output style
+
+Write every sentence you show the user in Simplified Technical English, as specified
+by ASD-STE100. Clarity comes first. Never sacrifice technical accuracy for brevity.
+
+## Scope
+
+Apply STE to your own prose: answers, explanations, plans, summaries, commit
+messages, and pull request text.
+
+Do not apply STE to:
+
+- Code, identifiers, file paths, and command names.
+- Quoted material: error messages, log lines, command output, and text from files.
+  Copy these exactly. Never rewrite a quote to make it simpler.
+- Text the user asks you to write in a different style.
+
+Markdown is still available. Use code blocks, and use `file.ts:42` references.
+
+## Words
+
+1. Use the most common, shortest word that has one clear meaning.
+2. Use one word for one meaning. Do not use synonyms for the same thing. If you
+   write "flag" for a variable, do not later call it a "switch" or an "option".
+3. Use one meaning for one word. Do not use "close" for both a state and an action
+   if this can confuse the reader.
+4. Technical names are permitted. Use the exact name from the code or the domain.
+5. Do not use slang, idioms, or figures of speech. "The build blew up" is wrong.
+   "The build failed" is correct.
+6. Do not use "etc." Complete the list, or write "for example" and give two items.
+7. Do not use a noun as a verb. Write "make a request", not "request it", when
+   "request" is a name in the code.
+
+Prefer the word on the right:
+
+| Not approved             | Use               |
+| ------------------------ | ----------------- |
+| utilize, employ          | use               |
+| initiate, commence       | start             |
+| terminate                | stop, end         |
+| perform, execute         | do, run           |
+| modify                   | change            |
+| indicate                 | show              |
+| ascertain, determine     | find, find out    |
+| assist, aid              | help              |
+| attempt                  | try               |
+| require                  | need              |
+| sufficient               | enough            |
+| additional               | more              |
+| numerous, multiple       | many              |
+| approximately            | about             |
+| currently, presently     | now               |
+| prior to                 | before            |
+| subsequent to, following | after             |
+| in order to              | to                |
+| due to the fact that     | because           |
+| via                      | with, by, through |
+| such as                  | for example       |
+| in the event that        | if                |
+| at this point in time    | now               |
+
+This table is a guide, not the full ASD-STE100 Dictionary. The Dictionary holds about
+900 approved words, each with one approved part of speech and one approved meaning.
+When you do not know if a word is approved, choose the shortest common word that has
+one clear meaning.
+
+## Verbs
+
+1. Use only these verb forms: the infinitive, the imperative, the simple present, the
+   simple past, the simple future, and the past participle as an adjective.
+2. Do not use complex tenses. Write "I changed the config", not "I have changed the
+   config".
+3. Do not use "-ing" forms, unless the form is part of a technical name, for example
+   "a logging module".
+4. Use the active voice. Write "the parser drops the field", not "the field is dropped
+   by the parser". Use the passive voice only when the actor is unknown or does not
+   matter.
+5. Do not leave out a verb to make a sentence shorter.
+
+## Noun phrases
+
+1. Do not build a cluster of more than three nouns. Break up "user account balance
+   sync failure" as "a failure in the sync of the user account balance".
+2. Add articles ("a", "the") where they help the reader.
+
+## Sentences
+
+1. Instructions: 20 words maximum.
+2. Descriptions: 25 words maximum.
+3. One idea per sentence. One instruction per sentence.
+4. A paragraph holds 6 sentences maximum, and covers one topic.
+5. Put a condition at the start of the sentence, before the instruction. Write "If the
+   sync fails, restart the server".
+6. Use connecting words such as "however", "therefore", and "then" to show the link
+   between sentences.
+7. Use a vertical list when the content has more than three parallel parts. Do not use
+   a list to give structure to a single idea.
+
+## Procedures
+
+1. Use the imperative for each step. Write "Open the file", not "You should open the
+   file" or "We can open the file".
+2. Number the steps in the order the user must do them.
+3. Give the result after the action, if the result is not obvious.
+
+## Warnings
+
+1. Put a warning or a caution before the step it applies to, never after.
+2. Start the warning with a clear command. Write "Do not run this on the production
+   database. The command deletes all rows."
+3. State the consequence in a separate, simple sentence.
+
+## Punctuation
+
+1. Do not use a slash to mean "and" or "or". Write "the date or the payee".
+2. Do not use parentheses for information the reader needs. Put it in its own sentence.
+3. Do not use a dash to join two thoughts. Use two sentences.
+4. Use a hyphen only to make a compound word clear.
+
+## When STE and accuracy conflict
+
+Accuracy wins. If a simple word would hide a real distinction, use the exact term and
+define it once in a short sentence. Never simplify a claim about what the code does.
+Keep the difference between what you verified and what you assume: write "I ran the
+tests and they passed" or "I did not run the tests", not a sentence that blurs the two.

package/content/rules/comments.md

@@ -1,31 +1,61 @@
 ---
 name: comments
-description: Write comments for the next reader of the file, not for the reviewer of your change.
+description: Comments are an allowlist of four cases. Everything else gets deleted before the change is done.
 kind: rule
 scope: both
 ---
 
-## Comments: write for the next reader of this file, not for the reviewer of your change
+## Comments: almost none, and never for the reviewer of your change
 
-A comment earns its place by telling someone **using or editing this code** something the
-code cannot. Explaining _why the change was made_ is not that — it belongs in the commit
-message, the changeset, or the docs.
+**Write no comment unless it fits one of the four cases below.** This is an allowlist, not a
+set of tips. Anything outside it gets **deleted** before you call the change done — not
+softened, not shortened. Code that needs prose to be understood needs a better name, a
+smaller function, or a type; fix that instead of narrating it.
 
-Do **not** leave behind:
+### The only comments allowed
 
-- **Rationale for a mechanical choice.** `Record<Size, X>` with literal keys, a `@__PURE__`
-  annotation, a factory instead of a literal, a helper moved to another file — the type,
-  the annotation and the import already say what happens.
-- **Migration narration.** "moved here from X", "used to be a tuple", "so Y no longer pulls Z".
-  Git knows. A reader six months from now does not care.
-- **The same explanation repeated per call site.** If a pattern needs explaining, explain it
-  once where the pattern is defined (the helper's JSDoc, the lint rule's message, the guide)
-  and let every use site stay silent.
-- **Restating the code.** `// increment the counter` above `counter++`.
+1. **An ordering or timing constraint** a reasonable edit would break. Say what breaks.
+2. **An invariant the types cannot express**, that a caller or a future edit could violate.
+3. **A workaround**, naming its concrete cause (browser bug, upstream issue, framework
+   limitation) and linking it where a link exists, so the next reader can tell when it may go.
+4. **Public API JSDoc** — what it does and how to call it, on something a lib actually
+   exports. One or two sentences. Not internals, not history, not why it is shaped that way.
 
-Do keep: non-obvious behaviour and ordering constraints, a real invariant a future edit could
-break, a workaround with the reason it exists, and public API JSDoc (what it does and how to
-use it — not why it is shaped that way).
+Nothing else qualifies. Not "this is subtle", not "worth noting", not a heading over a group
+of members, not a summary of the function underneath it.
 
-When you catch yourself writing "because", check whether the sentence is aimed at the reviewer
-of your diff. If it is, cut it.
+### The test each one still has to pass
+
+Delete it unless **both** are true:
+
+- a competent reader who never sees your diff would be **surprised** without it, and
+- a future edit could **break something** that this sentence is the only warning about.
+
+Unsure counts as no. A missing comment costs a minute of reading; a stale one misleads for
+years.
+
+### Always delete
+
+- **Restating the code** — `// increment the counter` over `counter++`; a JSDoc on `size` that
+  says nothing beyond "the size of the button".
+- **Section headers and dividers** — `// --- Inputs ---`, `// Helpers`, `// Public API`.
+- **Rationale for a mechanical choice** — `Record<Size, X>` with literal keys, a `@__PURE__`
+  annotation, a factory instead of a literal, a helper moved into its own file. The type, the
+  annotation and the import already say what happens.
+- **Migration narration** — "moved here from X", "used to be a tuple", "so Y no longer pulls
+  Z", "renamed for clarity". Git knows; the next reader does not care.
+- **The same explanation at every call site.** Explain a pattern once where it is defined (the
+  helper's JSDoc, the lint rule's message, the guide) and let every use site stay silent.
+- **Commented-out code.**
+- **`TODO`/`FIXME` without an issue link.** Fix it now or leave nothing.
+- **Hedging and meta** — "note that", "for clarity", "just in case", "this is cleaner", "we
+  could also…".
+
+### Before you call the change done
+
+Re-read every comment in your diff and cut the ones that are not one of the four. Then fix or
+delete any existing comment your change made wrong — one describing behaviour that no longer
+exists is worse than none.
+
+Two signals you have already over-commented: you wrote the word "because", or the diff adds
+more than a handful of comments. Both mean go back and cut.