bugfix: render-diff.py bracket placement respects word boundaries (M212)

- Add expand_to_word_boundary() to extend brackets to complete words
- Add _find_wrap_point() to avoid splitting inside [...] brackets
- Fixes: [ma]x_width now shows [max_width]

Author: cowwoc

.claude/cat/retrospectives/mistakes.json

@@ -2495,6 +2495,32 @@
         "catches_variations": true
       },
       "correct_behavior": "Copy-paste the EXACT render-diff.py Bash output into response - do not extract, reformat, or summarize"
+    },
+    {
+      "id": "M212",
+      "timestamp": "2026-01-23T12:15:00Z",
+      "category": "logical_error",
+      "description": "render-diff.py placed [] brackets incorrectly, splitting words like max_width into [ma]x_width",
+      "root_cause": "Character-level diff matching found minimal differences without respecting word boundaries, and line wrapping could split bracketed regions",
+      "rca_method": "C",
+      "rca_method_name": "causal-barrier",
+      "prevention_type": "code_fix",
+      "prevention_path": "/workspace/plugin/scripts/render-diff.py",
+      "pattern_keywords": [
+        "render-diff",
+        "brackets",
+        "word-boundary",
+        "wrapping"
+      ],
+      "prevention_implemented": true,
+      "prevention_verified": true,
+      "recurrence_of": null,
+      "prevention_quality": {
+        "verification_type": "positive",
+        "fragility": "low",
+        "catches_variations": true
+      },
+      "correct_behavior": "Expand bracket boundaries to complete words and wrap lines at safe points outside brackets"
     }
   ]
 }

.claude/cat/retrospectives/retrospectives.json

@@ -1,6 +1,6 @@
 {
   "last_retrospective": "2026-01-22T17:40:38-05:00",
-  "mistake_count_since_last": 5,
+  "mistake_count_since_last": 6,
   "config": {
     "mistake_count_threshold": 10,
     "trigger_interval_days": 7

plugin/scripts/render-diff.py

@@ -164,8 +164,33 @@ def common_suffix_len(s1: str, s2: str) -> int:
     return max_len
 
 
+def is_word_char(c: str) -> bool:
+    """Check if character is part of a word/identifier."""
+    return c.isalnum() or c == '_'
+
+
+def expand_to_word_boundary(line: str, start: int, end: int) -> tuple[int, int]:
+    """Expand a range to include complete words at boundaries.
+
+    If start is in the middle of a word, expand left to word start.
+    If end is in the middle of a word, expand right to word end.
+    """
+    # Expand start leftward if in middle of word
+    while start > 0 and is_word_char(line[start - 1]) and is_word_char(line[start]):
+        start -= 1
+
+    # Expand end rightward if in middle of word
+    while end < len(line) and is_word_char(line[end - 1]) and is_word_char(line[end]):
+        end += 1
+
+    return start, end
+
+
 def highlight_word_diff(old_line: str, new_line: str, is_old: bool, used: UsedSymbols) -> str:
-    """Apply word-level diff highlighting with [] brackets."""
+    """Apply word-level diff highlighting with [] brackets.
+
+    Expands bracket boundaries to complete words to avoid splitting identifiers.
+    """
     prefix_len = common_prefix_len(old_line, new_line)
     suffix_len = common_suffix_len(old_line, new_line)
 
@@ -183,18 +208,24 @@ def highlight_word_diff(old_line: str, new_line: str, is_old: bool, used: UsedSy
     if old_diff_len <= 0 or new_diff_len <= 0:
         return old_line if is_old else new_line
 
-    used.bracket = True
-
+    # Expand to word boundaries for cleaner highlighting
     if is_old:
-        prefix = old_line[:prefix_len]
-        diff_part = old_line[prefix_len:prefix_len + old_diff_len]
-        suffix = old_line[prefix_len + old_diff_len:]
-        return f"{prefix}[{diff_part}]{suffix}"
+        start = prefix_len
+        end = prefix_len + old_diff_len
+        start, end = expand_to_word_boundary(old_line, start, end)
+        prefix = old_line[:start]
+        diff_part = old_line[start:end]
+        suffix = old_line[end:]
     else:
-        prefix = new_line[:prefix_len]
-        diff_part = new_line[prefix_len:prefix_len + new_diff_len]
-        suffix = new_line[prefix_len + new_diff_len:]
-        return f"{prefix}[{diff_part}]{suffix}"
+        start = prefix_len
+        end = prefix_len + new_diff_len
+        start, end = expand_to_word_boundary(new_line, start, end)
+        prefix = new_line[:start]
+        diff_part = new_line[start:end]
+        suffix = new_line[end:]
+
+    used.bracket = True
+    return f"{prefix}[{diff_part}]{suffix}"
 
 
 class DiffRenderer:
@@ -287,6 +318,47 @@ def _print_column_header(self, context: str):
             f"{fill_char(BOX_HORIZONTAL, self.content_width + 1)}{BOX_T_LEFT}"
         )
 
+    def _find_wrap_point(self, content: str, max_width: int) -> int:
+        """Find safe wrap point that doesn't split inside [...] brackets.
+
+        Returns character index to wrap at, preserving bracket integrity.
+        """
+        if len(content) <= max_width:
+            return len(content)
+
+        # Track bracket nesting to avoid splitting inside [...]
+        bracket_depth = 0
+        last_safe_point = 0
+        current_width = 0
+
+        for i, char in enumerate(content):
+            # Calculate display width
+            ea = unicodedata.east_asian_width(char)
+            char_width = 2 if ea in ('W', 'F') else 1
+
+            if current_width + char_width > max_width - 1:  # -1 for wrap indicator
+                # Must wrap here or earlier
+                if bracket_depth == 0:
+                    return i
+                elif last_safe_point > 0:
+                    return last_safe_point
+                else:
+                    # No safe point found, wrap anyway (rare edge case)
+                    return i
+
+            current_width += char_width
+
+            if char == '[':
+                bracket_depth += 1
+            elif char == ']':
+                bracket_depth = max(0, bracket_depth - 1)
+
+            # Safe points are outside brackets
+            if bracket_depth == 0:
+                last_safe_point = i + 1
+
+        return len(content)
+
     def _print_row(self, old_num: str, symbol: str, new_num: str, content: str):
         """Print a content row, handling wrapping for long lines."""
         content_len = display_width(content)
@@ -300,16 +372,20 @@ def _print_row(self, old_num: str, symbol: str, new_num: str, content: str):
                 f"{padded_content}{BOX_VERTICAL}"
             )
         else:
-            # Wrap long lines
+            # Wrap long lines, preserving bracket integrity
             self.used.wrap = True
-            first_part = content[:self.content_width - 1]
+            wrap_point = self._find_wrap_point(content, self.content_width)
+            first_part = content[:wrap_point]
+            first_width = display_width(first_part)
+            # Pad to content_width - 1 to leave room for wrap indicator
+            padding = ' ' * max(0, self.content_width - 1 - first_width)
             self.output.append(
                 f"{BOX_VERTICAL}{pad_num(old_num, COL_OLD)}{BOX_VERTICAL} {symbol} "
                 f"{BOX_VERTICAL}{pad_num(new_num, COL_NEW)}{BOX_VERTICAL} "
-                f"{first_part}↩{BOX_VERTICAL}"
+                f"{first_part}{padding}↩{BOX_VERTICAL}"
             )
 
-            remaining = content[self.content_width - 1:]
+            remaining = content[wrap_point:]
             while remaining:
                 part_len = display_width(remaining)
                 if part_len <= self.content_width:
@@ -321,13 +397,16 @@ def _print_row(self, old_num: str, symbol: str, new_num: str, content: str):
                     )
                     remaining = ''
                 else:
-                    next_part = remaining[:self.content_width - 1]
+                    wrap_point = self._find_wrap_point(remaining, self.content_width)
+                    next_part = remaining[:wrap_point]
+                    next_width = display_width(next_part)
+                    padding = ' ' * max(0, self.content_width - 1 - next_width)
                     self.output.append(
                         f"{BOX_VERTICAL}{' ' * COL_OLD}{BOX_VERTICAL}   "
                         f"{BOX_VERTICAL}{' ' * COL_NEW}{BOX_VERTICAL} "
-                        f"{next_part}↩{BOX_VERTICAL}"
+                        f"{next_part}{padding}↩{BOX_VERTICAL}"
                     )
-                    remaining = remaining[self.content_width - 1:]
+                    remaining = remaining[wrap_point:]
 
     def _print_hunk_bottom(self):
         """Print hunk box bottom."""