subedit 0.1.2__tar.gz → 0.1.4__tar.gz

{subedit-0.1.2 → subedit-0.1.4}/.claude-plugin/marketplace.json

@@ -1,10 +1,11 @@
 {
   "name": "mroops",
   "owner": { "name": "mroops0111" },
+  "description": "Plugins built alongside subedit.",
   "plugins": [
     {
       "name": "subedit",
-      "source": { "source": "github", "repo": "mroops0111/subedit" },
+      "source": "./plugins/subedit",
       "description": "Repairs comment layout silently on write, and returns only what needs rewriting."
     }
   ]

{subedit-0.1.2 → subedit-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: subedit
-Version: 0.1.2
+Version: 0.1.4
 Summary: A linter and formatter for the prose inside code comments, across languages.
 Project-URL: Homepage, https://github.com/mroops0111/subedit
 Project-URL: Repository, https://github.com/mroops0111/subedit
@@ -105,12 +105,14 @@ Rewriting a sentence needs its meaning, which a deterministic process cannot sup
 
 ## Agent Hook
 
-`subedit-hook` runs after every file an agent edits. It repairs the mechanical findings in place, and exits 2 only when a sentence needs rewriting, which hands the message back to the model.
+`subedit-hook` runs after every file an agent edits. It repairs the mechanical findings in place, and exits 2 only when a sentence needs rewriting, which hands the message back to the model. In Claude Code a warning reaches the model too, as context beside the tool result, without blocking the edit.
 
 ### Claude Code
 
 The plugin needs only [uv](https://docs.astral.sh/uv/). It runs subedit from PyPI with the `vale` extra, and warms that environment in the background when a session starts, so no edit waits on the first download.
 
+It also ships the `subedit:judging-findings` skill, which gives the model the criteria for every finding a tool cannot fix, such as when a spec identifier stays and a ticket number goes. Criteria in your `CLAUDE.md`, `AGENTS.md`, or a skill of your own come first.
+
 ```text
 /plugin marketplace add mroops0111/subedit
 /plugin install subedit@mroops

{subedit-0.1.2 → subedit-0.1.4}/README.md

@@ -71,12 +71,14 @@ Rewriting a sentence needs its meaning, which a deterministic process cannot sup
 
 ## Agent Hook
 
-`subedit-hook` runs after every file an agent edits. It repairs the mechanical findings in place, and exits 2 only when a sentence needs rewriting, which hands the message back to the model.
+`subedit-hook` runs after every file an agent edits. It repairs the mechanical findings in place, and exits 2 only when a sentence needs rewriting, which hands the message back to the model. In Claude Code a warning reaches the model too, as context beside the tool result, without blocking the edit.
 
 ### Claude Code
 
 The plugin needs only [uv](https://docs.astral.sh/uv/). It runs subedit from PyPI with the `vale` extra, and warms that environment in the background when a session starts, so no edit waits on the first download.
 
+It also ships the `subedit:judging-findings` skill, which gives the model the criteria for every finding a tool cannot fix, such as when a spec identifier stays and a ticket number goes. Criteria in your `CLAUDE.md`, `AGENTS.md`, or a skill of your own come first.
+
 ```text
 /plugin marketplace add mroops0111/subedit
 /plugin install subedit@mroops

{subedit-0.1.2 → subedit-0.1.4}/docs/rules.md

@@ -9,10 +9,10 @@ The level says whether a rewrite blocks. An error fails check and stops an agent
 | Rule | Fix kind | Level | Summary |
 | --- | --- | --- | --- |
 | `line-too-long` | reflow | error | A physical comment line must fit the configured width, counting indent and delimiter. |
-| `mid-clause-break` | reflow | error | A comment block must be laid out one sentence per line, splitting only at commas. |
+| `mid-clause-break` | reflow | error | A sentence sits on one line when it fits, and otherwise breaks at clause commas, on as few lines as it can. |
 | `block-too-long` | rewrite | warning | A comment block long enough to restate the code has stopped earning its place. |
 | `file-header-comment` | rewrite | warning | A file must not open with a banner comment before its first declaration. |
 | `plain-comment-on-public` | rewrite | error | A public symbol must be documented in the doc comment form its language renders. |
 | `signature-restating-tag` | rewrite | error | A doc comment must not restate what the type signature already carries. |
 | `stub-fragment` | rewrite | warning | A sentence forced to break must not leave a stub of a line behind. |
-| `unbreakable-sentence` | rewrite | error | A sentence over the width must carry a comma so it has somewhere legal to break. |
+| `unbreakable-sentence` | rewrite | error | A sentence over the width must carry a clause comma wherever it has to break. |

{subedit-0.1.2 → subedit-0.1.4/plugins/subedit}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "subedit",
   "displayName": "subedit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Repairs comment layout silently on write, and returns only what needs rewriting.",
   "author": {
     "name": "mroops0111"

{subedit-0.1.2 → subedit-0.1.4/plugins/subedit}/hooks/hooks.json

@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/run-subedit-hook.sh",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/run-subedit-hook.sh",
             "timeout": 30
           }
         ]
@@ -18,7 +18,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/run-subedit-hook.sh prepare",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/run-subedit-hook.sh prepare",
             "timeout": 10
           }
         ]

{subedit-0.1.2/hooks → subedit-0.1.4/plugins/subedit/scripts}/run-subedit-hook.sh

@@ -4,7 +4,7 @@
 # because the first run installs subedit and downloads Vale, which no edit should wait on.
 set -uo pipefail
 
-SPEC='subedit[vale]>=0.1.2'
+SPEC='subedit[vale]>=0.1.4'
 # A bare uvx takes the first Python it finds, which on a stock Mac is too old for subedit.
 PYTHON='>=3.11'
 

subedit-0.1.4/plugins/subedit/skills/judging-findings/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: judging-findings
+description: Decide what to do with a subedit finding that no tool can fix, such as subedit.ExternalRef, subedit.DateRef, subedit.MidSentenceColon, block-too-long, or unbreakable-sentence. Use when a subedit hook, `subedit check`, or `subedit fix` reports a finding that needs rewriting or a warning that is a judgment call.
+---
+
+# Judge subedit Findings
+
+subedit repairs comment layout on its own. What reaches you is either an error, which blocks until the text is rewritten, or a warning, which asks for a judgment and blocks nothing. For each finding, read the flagged comment, apply the criteria below, and either rewrite the text or leave it as it is.
+
+## Project Criteria Come First
+
+A project or its people can judge differently. Look for their criteria before applying these, and follow theirs where the two disagree:
+
+- `CLAUDE.md` or `AGENTS.md` in the repository, or the user's own instructions.
+- A project or personal skill that covers subedit findings.
+- `[tool.subedit.rules]` in `pyproject.toml`, or `[rules]` in `subedit.toml`. A rule set to `"off"` there is never reported. A rule a project wants left alone for good belongs there, not in a suppression comment.
+
+## Rewriting
+
+Rewrite in place, keep the meaning, and keep the comment to the constraint the code cannot show. Never add a suppression comment, and never reword a sentence only to dodge a pattern while keeping what the rule objects to.
+
+## Warnings
+
+A warning passes when the text meets its criterion. Leave such text exactly as it is, and say so in one line if anyone asks.
+
+| Rule | Keep the text when | Rewrite it when |
+| --- | --- | --- |
+| `subedit.ExternalRef` | The identifier is public and resolvable by anyone, such as an RFC, an MCP SEP, a PEP, a CVE, or an ISO standard. | It is a private ticket, such as a Jira key or an internal issue number. State the constraint the ticket recorded instead. |
+| `subedit.DateRef` | The date names a version or a spec revision, such as the dated revision an MCP specification is named by. | It records when something happened or changed. State the constraint that holds now. |
+| `subedit.MidSentenceColon` | The colon introduces a list, an indented block, or a label such as `Note:`. | The sentence runs on after the colon. Split it into two sentences, or join the clauses with a comma and a conjunction. |
+| `block-too-long` | Every sentence states a constraint the code cannot show. | Some sentences narrate what the code does. Cut them, or move the explanation into a name. |
+| `file-header-comment` | It states a constraint about the whole module that no single declaration owns. | It is a banner or a summary of the file. Delete it, or move the constraint to the declaration it applies to. |
+| `stub-fragment` | Never. A stub reads as a broken clause. | Always. Rewrite the sentence to fit one line, or split it into two complete sentences. |
+
+## Errors
+
+An error always needs a rewrite. The message states the fix, and these notes cover what it leaves out.
+
+- `unbreakable-sentence`: a line can break only at a comma that ends a clause, and a comma inside brackets or a code span does not count. Add a comma at a clause boundary, or split the sentence in two.
+- `plain-comment-on-public`: move the text into the docstring.
+- `signature-restating-tag` and `subedit.SignatureTag`: delete the tag, since the signature already says it.
+- `subedit.EditHistory`: state the current behavior, not its history.
+- `subedit.Semicolon`, `subedit.EmDash`: split into two sentences, or use a comma or parentheses.
+- `subedit.Ellipsis`: name two or three concrete examples after "such as", as in "a transport failure, such as a connect, timeout, or DNS error". Dropping the trailing word and joining the rest with "or" turns a sample into the whole set, which narrows what the sentence claims.

{subedit-0.1.2 → subedit-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "subedit"
-version = "0.1.2"
+version = "0.1.4"
 description = "A linter and formatter for the prose inside code comments, across languages."
 authors = [
     {name = "Yun-Tai Yang"},

{subedit-0.1.2 → subedit-0.1.4}/src/subedit/__init__.py

@@ -1,3 +1,3 @@
-__version__ = '0.1.2'
+__version__ = '0.1.4'
 
 __all__ = ['__version__']

{subedit-0.1.2 → subedit-0.1.4}/src/subedit/domain/models/comment.py

@@ -1,8 +1,9 @@
 import dataclasses
 import enum
+import itertools
 
 from .position import SourceRange
-from .prose import Prose, reflow_sentence
+from .prose import Prose, Sentence, break_cost, comma_breaks, reflow_sentence
 from .text import TextEdit
 
 
@@ -102,14 +103,25 @@ class CommentGroup:
         if self.form is CommentForm.DOC and self.line_count == 1 and self.longest_line <= width:
             return self
         texts = self._reflow_into_texts(width, stub_floor)
+        # Text that ends up on one line closes there too, so the closing quotes need room beside it.
+        closing_width = len(self._closing_quotes())
+        if len(texts) == 1 and len(texts[0]) > self.text_budget(width, first_line=True) - closing_width:
+            texts = self._reflow_into_texts(width, stub_floor, closing_width)
         if not texts:
             return self
         return self._rebuild_lines(texts)
 
-    # A sentence whose split strands a stub needs its author,
-    # so the block keeps the layout they gave it rather than one its own check rejects.
-    def _reflow_into_texts(self, width: int, stub_floor: int) -> tuple[str, ...]:
-        budget = max(20, width - self.lines[0].prefix_width)
+    def text_budget(self, width: int, *, first_line: bool) -> int:
+        """The characters of text a line holds, which on a docstring's opening line also cede the quotes."""
+        opening = self.lines[0]
+        quoted = first_line or self.form is not CommentForm.DOC
+        return max(20, width - (opening.prefix_width if quoted else len(opening.indent)))
+
+    # A sentence takes as few lines as fit, and the author's layout stays when it breaks no worse than the best one.
+    # A sentence whose new layout would strand a stub or still overflow needs its author,
+    # so it keeps the layout they gave it rather than one its own check rejects.
+    def _reflow_into_texts(self, width: int, stub_floor: int, reserve: int = 0) -> tuple[str, ...]:
+        body_budget = self.text_budget(width, first_line=False)
         out: list[str] = []
         for paragraph_index, (paragraph, is_literal) in enumerate(self._split_into_paragraphs()):
             if out:
@@ -117,14 +129,23 @@ class CommentGroup:
             if is_literal:
                 out.extend(paragraph)
                 continue
-            joined_text = ' '.join(line.strip() for line in paragraph if line.strip())
-            for sentence_index, sentence in enumerate(Prose(joined_text).sentences()):
+            lines = tuple(line.strip() for line in paragraph if line.strip())
+            for sentence_index, sentence in enumerate(Prose(' '.join(lines)).sentences()):
                 if sentence_index == 1 and paragraph_index == 0 and self.form is CommentForm.DOC:
                     out.append('')
-                sentence_lines = reflow_sentence(sentence.text, budget)
-                if len(sentence_lines) > 1 and min(map(len, sentence_lines)) < stub_floor:
+                first_budget = self.text_budget(width, first_line=not out) - (reserve if not out else 0)
+                best_lines = reflow_sentence(sentence.text, body_budget, stub_floor, first_width=first_budget)
+                given_lines = _given_lines(lines, sentence)
+                if given_lines and _keeps_given(given_lines, best_lines, (first_budget, body_budget), stub_floor):
+                    out.extend(given_lines)
+                elif _is_legal(best_lines, (first_budget, body_budget), stub_floor):
+                    out.extend(best_lines)
+                elif given_lines:
+                    out.extend(given_lines)
+                elif _strands_stub(best_lines, stub_floor):
                     return ()
-                out.extend(sentence_lines)
+                else:
+                    out.extend(best_lines)
         return tuple(out)
 
     def _split_into_paragraphs(self) -> tuple[tuple[tuple[str, ...], bool], ...]:
@@ -156,9 +177,14 @@ class CommentGroup:
             if not closes_alone:
                 body[-1] = dataclasses.replace(body[-1], delimiter=opening.delimiter.strip())
         else:
-            body[0] = dataclasses.replace(body[0], suffix=closing.suffix or opening.delimiter.strip())
+            body[0] = dataclasses.replace(body[0], suffix=self._closing_quotes())
         return dataclasses.replace(self, lines=tuple(body))
 
+    def _closing_quotes(self) -> str:
+        if self.form is not CommentForm.DOC:
+            return ''
+        return self.lines[-1].suffix or self.lines[0].delimiter.strip()
+
     def with_texts(self, texts: tuple[str, ...]) -> 'CommentGroup':
         if not texts:
             raise ValueError('A comment block needs at least one line')
@@ -177,3 +203,59 @@ class CommentGroup:
 
     def as_edit(self) -> TextEdit:
         return TextEdit(self.range, self.render())
+
+
+# The lines a sentence already occupies, when it has them to itself.
+def _given_lines(lines: tuple[str, ...], sentence: Sentence) -> tuple[str, ...] | None:
+    covering: list[str] = []
+    start = 0
+    for line in lines:
+        end = start + len(line)
+        if start < sentence.end and end > sentence.offset:
+            if not covering and start != sentence.offset:
+                return None
+            covering.append(line)
+            if end == sentence.end:
+                return tuple(covering)
+            if end > sentence.end:
+                return None
+        start = end + 1
+    return None
+
+
+def _keeps_given(
+    given_lines: tuple[str, ...], best_lines: tuple[str, ...], budgets: tuple[int, int], stub_floor: int
+) -> bool:
+    # A colon ending a line in mid sentence is a rewrite finding, so its layout waits for that rewrite.
+    if _breaks_at_a_colon(given_lines):
+        return _fits(given_lines, budgets)
+    return (
+        len(given_lines) == len(best_lines)
+        and _is_legal(given_lines, budgets, stub_floor)
+        and break_cost(given_lines) <= break_cost(best_lines)
+    )
+
+
+def _breaks_at_a_colon(lines: tuple[str, ...]) -> bool:
+    return any(line.endswith(':') for line in lines[:-1])
+
+
+def _fits(lines: tuple[str, ...], budgets: tuple[int, int]) -> bool:
+    first_budget, body_budget = budgets
+    return all(len(line) <= (first_budget if index == 0 else body_budget) for index, line in enumerate(lines))
+
+
+def _is_legal(lines: tuple[str, ...], budgets: tuple[int, int], stub_floor: int) -> bool:
+    if not _fits(lines, budgets):
+        return False
+    if len(lines) == 1:
+        return True
+    if _strands_stub(lines, stub_floor):
+        return False
+    breaks = set(comma_breaks(' '.join(lines)))
+    line_ends = itertools.accumulate(len(line) + 1 for line in lines[:-1])
+    return all(line_end - 1 in breaks for line_end in line_ends)
+
+
+def _strands_stub(lines: tuple[str, ...], stub_floor: int) -> bool:
+    return len(lines) > 1 and min(map(len, lines)) < stub_floor

{subedit-0.1.2 → subedit-0.1.4}/src/subedit/domain/models/prose.py

@@ -1,4 +1,5 @@
 import dataclasses
+import itertools
 import re
 
 
@@ -21,7 +22,9 @@ ABBREVIATIONS = frozenset(
 _SENTENCE_END = re.compile(r'[.!?]')
 _TRAILING_WORD = re.compile(r'([A-Za-z][A-Za-z.]*)$')
 _URL = re.compile(r'\b(?:https?://|www\.)\S+')
-_CODE_SPAN = re.compile(r'`[^`]*`')
+# A span opened by two backticks, as reStructuredText writes code, closes on two.
+_CODE_RUN = re.compile(r'(`+).+?\1')
+_BRACKET_PAIRS = {'(': ')', '[': ']', '{': '}'}
 _FENCE = re.compile(r'^\s*(```|~~~)')
 _LIST_DELIMITER = re.compile(r'^\s*(?:[0-9]+[.)]|[-*+]|[a-zA-Z][.)])\s')
 _LITERAL_DELIMITER = '\\b'
@@ -148,9 +151,10 @@ class Prose:
             found_sentences.append(Sentence(text[start:].strip(), start))
         return tuple(sentence for sentence in found_sentences if sentence.text)
 
+    # A period inside brackets, as in an ellipsis closing a list of examples, ends no sentence outside them.
     def _find_protected_spans(self, text: str) -> tuple[tuple[int, int], ...]:
         spans = [(url.start(), url.end()) for url in _URL.finditer(text)]
-        spans.extend((code_span.start(), code_span.end()) for code_span in _CODE_SPAN.finditer(text))
+        spans.extend(_enclosed_spans(text))
         return tuple(spans)
 
     def _is_protected(self, offset: int, spans: tuple[tuple[int, int], ...]) -> bool:
@@ -183,27 +187,62 @@ class Prose:
         return not rest or rest[0] == ' '
 
 
-def reflow_sentence(sentence: str, width: int) -> tuple[str, ...]:
-    if len(sentence) <= width:
+def reflow_sentence(sentence: str, width: int, stub_floor: int = 0, first_width: int | None = None) -> tuple[str, ...]:
+    """Lay a sentence out on as few lines as fit, breaking only at clause commas.
+
+    Among layouts with that fewest count, one that leaves no stub wins, then one whose breaks split no list,
+    then one whose breaks each open a clause, then the one with the longest opening line.
+    A sentence with a clause too long for any line falls back to filling each line greedily,
+    which leaves the overflow where a rewrite finds it.
+    """
+    opening_width = width if first_width is None else first_width
+    if len(sentence) <= opening_width:
         return (sentence,)
     pieces = _comma_pieces(sentence)
     if len(pieces) == 1:
         return (sentence,)
-    return _pack(pieces, width)
+    return _best_layout(pieces, width, opening_width, stub_floor) or _pack(pieces, width)
 
 
 def _comma_pieces(sentence: str) -> tuple[str, ...]:
     pieces: list[str] = []
     start = 0
-    for comma in re.finditer(r',\s+', sentence):
-        pieces.append(sentence[start : comma.end()].rstrip())
-        start = comma.end()
+    for offset in comma_breaks(sentence):
+        pieces.append(sentence[start:offset].strip())
+        start = offset
     tail = sentence[start:].strip()
     if tail:
         pieces.append(tail)
     return tuple(pieces) if pieces else (sentence,)
 
 
+def comma_breaks(sentence: str) -> tuple[int, ...]:
+    """Offsets just past each comma that ends a clause, which are the only places a sentence may break.
+
+    A comma inside brackets or a code span separates items of one phrase, so a break there splits the phrase.
+    """
+    enclosed = _enclosed_spans(sentence)
+    return tuple(
+        comma.start() + 1
+        for comma in re.finditer(r',\s+', sentence)
+        if not any(start < comma.start() < end for start, end in enclosed)
+    )
+
+
+# Only a matched pair encloses anything, so a stray bracket such as the one in "1)" never swallows the sentence.
+def _enclosed_spans(sentence: str) -> tuple[tuple[int, int], ...]:
+    spans = [(code_span.start(), code_span.end()) for code_span in _CODE_RUN.finditer(sentence)]
+    open_brackets: list[tuple[str, int]] = []
+    for offset, character in enumerate(sentence):
+        if any(start <= offset < end for start, end in spans):
+            continue
+        if character in _BRACKET_PAIRS:
+            open_brackets.append((_BRACKET_PAIRS[character], offset))
+        elif open_brackets and character == open_brackets[-1][0]:
+            spans.append((open_brackets.pop()[1], offset + 1))
+    return tuple(spans)
+
+
 def _pack(pieces: tuple[str, ...], width: int) -> tuple[str, ...]:
     lines: list[str] = []
     current_line = ''
@@ -217,3 +256,104 @@ def _pack(pieces: tuple[str, ...], width: int) -> tuple[str, ...]:
     if current_line:
         lines.append(current_line)
     return tuple(lines)
+
+
+# Words that open a clause, so a comma before one is where a sentence divides in meaning.
+# As is left out, since it opens an aside such as "as this once did" as often as a clause.
+CLAUSE_OPENERS = frozenset(
+    {
+        'although',
+        'and',
+        'because',
+        'but',
+        'nor',
+        'or',
+        'otherwise',
+        'since',
+        'so',
+        'then',
+        'though',
+        'unless',
+        'until',
+        'whereas',
+        'which',
+        'while',
+        'yet',
+    }
+)
+# A piece this short between two commas is an item in a list, such as "base URL,", not a clause.
+LIST_ITEM_WORDS = 3
+LIST_CLOSERS = frozenset({'and', 'or'})
+ARTICLES = frozenset({'a', 'an', 'the'})
+
+
+def _best_layout(pieces: tuple[str, ...], width: int, opening_width: int, stub_floor: int) -> tuple[str, ...] | None:
+    """Pick break points by dynamic programming over the pieces, scoring each layout from the end backwards."""
+    count = len(pieces)
+    finished: tuple[tuple[int, int, int, int], tuple[str, ...]] = ((0, 0, 0, 0), ())
+    best: list[tuple[tuple[int, int, int, int], tuple[str, ...]] | None] = [None] * count
+    best.append(finished)
+    for start in reversed(range(count)):
+        line_width = opening_width if start == 0 else width
+        for stop in range(start + 1, count + 1):
+            line = ' '.join(pieces[start:stop])
+            if len(line) > line_width:
+                break
+            rest = best[stop]
+            if rest is None:
+                continue
+            (rest_lines, rest_stubs, rest_lists, rest_asides), rest_layout = rest
+            is_stub = (start, stop) != (0, count) and len(line) < stub_floor
+            splits_list = stop < count and _splits_a_list(pieces, stop)
+            opens_aside = stop < count and not _opens_a_clause(pieces[stop])
+            score = (rest_lines + 1, rest_stubs + is_stub, rest_lists + splits_list, rest_asides + opens_aside)
+            candidate = (score, (line, *rest_layout))
+            current = best[start]
+            # On a tie the longer line wins, as filling greedily would choose.
+            if current is None or score <= current[0]:
+                best[start] = candidate
+    found = best[0]
+    return None if found is None else found[1]
+
+
+def _splits_a_list(pieces: tuple[str, ...], index: int) -> bool:
+    """Whether a break before ``pieces[index]`` falls beside an item of a list rather than between clauses."""
+    return _is_list_item(pieces, index - 1) or _is_list_item(pieces, index)
+
+
+# A short piece is an item, such as "base URL,", when the run goes on with another short piece or closes on and or or.
+# One standing alone, such as "returns ``None``,", or one opening a clause, such as "then optional params,", is not.
+def _is_list_item(pieces: tuple[str, ...], index: int) -> bool:
+    if not 0 < index < len(pieces) - 1 or not _is_short(pieces[index]) or _opens_a_clause(pieces[index]):
+        return False
+    following = pieces[index + 1].split()
+    if _is_appositive(pieces[index], following):
+        return False
+    closes_run = bool(following) and following[0].lower() in LIST_CLOSERS
+    return closes_run or _is_short(pieces[index + 1]) or (index >= 2 and _is_short(pieces[index - 1]))
+
+
+# "``owner``, a ``Person``," renames what came before it,
+# unless the next piece runs on in parallel, as in "a cat, a dog".
+def _is_appositive(piece: str, following: list[str]) -> bool:
+    words = piece.split()
+    if not words or words[0].lower() not in ARTICLES:
+        return False
+    parallel = following[1:] if following and following[0].lower() in LIST_CLOSERS else following
+    return not parallel or parallel[0].lower() not in ARTICLES
+
+
+def _is_short(piece: str) -> bool:
+    return len(piece.split()) <= LIST_ITEM_WORDS
+
+
+def _opens_a_clause(piece: str) -> bool:
+    words = piece.split()
+    return bool(words) and words[0].lower() in CLAUSE_OPENERS
+
+
+def break_cost(lines: tuple[str, ...]) -> int:
+    """Count the breaks in a laid out sentence that split a list."""
+    pieces = _comma_pieces(' '.join(lines))
+    piece_ends = itertools.accumulate(len(_comma_pieces(line)) for line in lines[:-1])
+    return sum(_splits_a_list(pieces, piece_end) for piece_end in piece_ends)

{subedit-0.1.2 → subedit-0.1.4}/src/subedit/domain/rules/layout.py

@@ -8,7 +8,7 @@ from .rewrite import stub_floor
 
 MID_CLAUSE_BREAK = RuleMetadata(
     rule_id='mid-clause-break',
-    summary='A comment block must be laid out one sentence per line, splitting only at commas.',
+    summary='A sentence sits on one line when it fits, and otherwise breaks at clause commas, on as few lines as it can.',
     fix_kind=FixKind.REFLOW,
 )
 
@@ -31,7 +31,7 @@ class MidClauseBreakRule(Rule):
             range=group.range,
             message=(
                 'Comment layout differs from one sentence per line. '
-                'Break only at a period or a comma, never mid clause.'
+                'A sentence that fits takes one line, and a longer one breaks only at a comma ending a clause.'
             ),
             fix=Fix.reflow(reflowed.as_edit()),
         )

{subedit-0.1.2 → subedit-0.1.4}/src/subedit/domain/rules/rewrite.py

@@ -15,12 +15,13 @@ STUB_FRAGMENT = RuleMetadata(
 
 UNBREAKABLE_SENTENCE = RuleMetadata(
     rule_id='unbreakable-sentence',
-    summary='A sentence over the width must carry a comma so it has somewhere legal to break.',
+    summary='A sentence over the width must carry a clause comma wherever it has to break.',
     fix_kind=FixKind.REWRITE,
 )
 
 
 DEFAULT_MINIMUM_CHARACTERS = 24
+BRACKET_NOTE = 'A comma inside brackets or a code span separates items, so it is no place to break. '
 
 
 def prose_sentences(group: CommentGroup) -> tuple[str, ...]:
@@ -32,8 +33,12 @@ def prose_sentences(group: CommentGroup) -> tuple[str, ...]:
     )
 
 
-def sentence_budget(group: CommentGroup, context: RuleContext) -> int:
-    return max(20, context.line_width - group.lines[0].prefix_width)
+def budgeted_sentences(group: CommentGroup, context: RuleContext) -> tuple[tuple[str, int], ...]:
+    """Pair each sentence with the budget reflow lays it out in, so no rule judges a layout reflow would not make."""
+    return tuple(
+        (sentence, group.text_budget(context.line_width, first_line=index == 0))
+        for index, sentence in enumerate(prose_sentences(group))
+    )
 
 
 def stub_floor(context: RuleContext) -> int:
@@ -47,10 +52,9 @@ class StubFragmentRule(Rule):
     metadata = STUB_FRAGMENT
 
     def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
-        budget = sentence_budget(group, context)
         minimum_length = stub_floor(context)
-        for sentence in prose_sentences(group):
-            split_pieces = reflow_sentence(sentence, budget)
+        for sentence, budget in budgeted_sentences(group, context):
+            split_pieces = reflow_sentence(sentence, budget, minimum_length)
             if len(split_pieces) < 2:
                 continue
             shortest_piece = min(split_pieces, key=len)
@@ -73,17 +77,23 @@ class UnbreakableSentenceRule(Rule):
     metadata = UNBREAKABLE_SENTENCE
 
     def check(self, group: CommentGroup, context: RuleContext) -> typing.Iterable[Diagnostic]:
-        budget = max(20, context.line_width - group.lines[0].prefix_width)
-        for sentence in prose_sentences(group):
-            if len(sentence) <= budget or ',' in sentence:
+        for sentence, budget in budgeted_sentences(group, context):
+            longest_line = max(reflow_sentence(sentence, budget), key=len)
+            if len(longest_line) <= budget:
                 continue
+            if longest_line == sentence:
+                cause = 'contains no comma that ends a clause, so there is no legal place to break it'
+            else:
+                cause = f'still leaves a line of {len(longest_line)} characters when broken at every clause comma'
             yield Diagnostic(
                 rule_id=self.metadata.rule_id,
                 range=group.range,
                 message=(
                     f'This sentence runs to {len(sentence)} characters against a budget of {budget} characters '
-                    'and contains no comma, so there is no legal place to break it. '
-                    'Add a comma at a clause boundary, or split it into two sentences.'
+                    f'and {cause}. '
+                    f'{BRACKET_NOTE if "," in sentence else ""}'
+                    'Add a comma at a clause boundary, or split it into two sentences. '
+                    f'The part that does not fit is "{longest_line}".'
                 ),
                 fix=Fix.rewrite(),
             )

{subedit-0.1.2 → subedit-0.1.4}/src/subedit/presentation/harnesses/agent_harness.py

@@ -35,6 +35,13 @@ class AgentHarness(abc.ABC):
         """
         ...
 
+    def advisory_output(self, advice: str) -> str:
+        """Stdout that puts advice in front of the model without blocking, or nothing where the agent has no channel.
+
+        Exit two is the only shared way to reach the model, and it blocks, so a warning needs one of its own.
+        """
+        return ''
+
 
 def existing_source_files(
     candidates: typing.Iterable[str | pathlib.Path], extensions: frozenset[str]

{subedit-0.1.2 → subedit-0.1.4}/src/subedit/presentation/harnesses/claude_code_harness.py

@@ -1,3 +1,4 @@
+import json
 import pathlib
 import typing
 
@@ -35,3 +36,7 @@ class ClaudeCodeHarness(AgentHarness):
     def _tool_input(self, payload: Payload) -> typing.Mapping[str, object]:
         tool_input = payload.get('tool_input')
         return tool_input if isinstance(tool_input, dict) else {}
+
+    def advisory_output(self, advice: str) -> str:
+        # Claude Code reads stdout as JSON on exit zero, and adds this field beside the tool result.
+        return json.dumps({'hookSpecificOutput': {'hookEventName': 'PostToolUse', 'additionalContext': advice}})