feat: Improved comment etiquette for the sisyphus suite

assets/agents/coder/graph.yaml

@@ -222,7 +222,8 @@ nodes:
       3. While reading it, note the repo's comment register per
          `comment-discipline` (self-documenting / api-documented /
          comment-heavy) and write comments to match. When the signal is
-         weak, write NO comment.
+         weak, write NO comment. Every comment must EARN ITS KEEP — if
+         the code already tells the reader, don't add it.
       4. If the change touches boundaries, error paths, jobs, or state
          transitions, also note the logging register per
          `logging-discipline` (logger, message style, payload vs IDs,
@@ -323,7 +324,8 @@ nodes:
         - Suppressed errors (as any, @ts-ignore, #[allow(...)] on unfamiliar
           lints, empty catch blocks)
         - Dishonest naming (get_X that mutates, returns wrong type, etc.)
-        - Useless comments that restate the code
+        - Useless comments that restate the code, or that otherwise don't earn
+          their keep (the code already tells the reader)
         - AI slop (filler prose, multi-paragraph docstrings, defensive
           handling of impossible cases)
 

assets/agents/sisyphus/config.yaml

@@ -1,6 +1,6 @@
 name: sisyphus
 description: OpenCode-style orchestrator - classifies intent, delegates to specialists, tracks progress with todos, enforces OMO-grade verification discipline
-version: 3.14.0
+version: 3.15.0
 
 agent_session: temp
 auto_continue: true
@@ -575,7 +575,7 @@ instructions: |
 
   When you write or modify files yourself (rather than delegating to coder):
 
-  - **Calibrate comments before writing.** Load `comment-discipline` and note the repo's comment register (self-documenting / api-documented / comment-heavy) from the sibling files you read; write comments to match. When the signal is weak, write NO comment.
+  - **Calibrate comments before writing.** Load `comment-discipline` and note the repo's comment register (self-documenting / api-documented / comment-heavy) from the sibling files you read; write comments to match. When the signal is weak, write NO comment. In every register, a comment must EARN ITS KEEP — if the code already tells the reader, don't add it.
   - **Calibrate logging before writing.** When the change touches boundaries, error paths, jobs, or state transitions, load `logging-discipline` and note the repo's logging register (logger, message style, payload vs IDs, level semantics) from the same sibling reads; match it. No discernible convention → its best-judgment defaults. Never leave a new error path silently swallowed, and never delete existing log lines as drive-by cleanup.
   - **For editing an existing file**, prefer `fs_patch`. It's a surgical edit that preserves unchanged content. Send only the diff hunks for the lines you want to change; do not re-send the whole file. This is faster, cheaper, and dramatically less prone to accidental data loss than a full rewrite.
   - **For writing a NEW file or doing a COMPLETE rewrite**, use `fs_write`. Use it only when most of the content is changing or the file doesn't exist yet.

assets/skills/comment-discipline/SKILL.md

@@ -1,7 +1,7 @@
 ---
 description: Calibrate comment density and style to the repository's existing conventions before writing code. Detects the repo's comment register (self-documenting / api-documented / comment-heavy) from the sibling files you already read for pattern matching, or from a declared policy in workspace instructions, then dictates when a comment is warranted. Default when signal is weak - write NO comment. Complements ai-slop-remover (which bans comments that restate code in every register).
 ---
-You are about to write or modify code. LLMs systematically over-comment — narrating every block, restating signatures, banner-ing sections — and that default is wrong in most repositories. Before writing, determine the repo's **comment register** and match it, exactly the way you already match imports, naming, and error handling.
+You are about to write or modify code. LLMs systematically over-comment — narrating every block, restating signatures, banner-ing sections — and that default is wrong in most repositories. Before writing, determine the repo's **comment register** and match it, exactly the way you already match imports, naming, and error handling. Across every register, one test governs each comment you write: it must **earn its keep**. If the code already tells the reader, the comment doesn't get written — don't add comments you don't need; make the code tell them instead.
 
 ## Step 0: Check for a declared policy first