fix(lint-org): stop flagging correctly paired verbatim blocks

org-lint's invalid-block checker flags both delimiters of a paired example or src block whose body holds a heading-shaped line. Its parser reads the `** ` as a structural break and loses the open block. Every org file that documents org syntax inside a block collects two false findings.

The checker is org-lint's own, not one lint-org implements, so I filtered its output instead of patching a local checker. `lo--matched-block-regions` pairs blocks by scanning lines under org's real rule (once open, only the block's own `#+end_TYPE` closes it). A finding inside a matched region gets dropped, delimiters included, since that's where org-lint reports. I scanned lines rather than asking org because org's parser is what's confused.

An unterminated block never lands in a matched region, so it still reports. Three tests cover the false positives: a heading in an example block, a literal `#+end_example` inside a src block, and uppercase delimiters. Two more guard the real finding, including a file with one paired and one unterminated block that proves the suppression is per-block.

5 files changed, 336 insertions, 2 deletions

diff --git a/.ai/scripts/lint-org.el b/.ai/scripts/lint-org.el
index 928f83b..33dc52f 100644
--- a/.ai/scripts/lint-org.el
+++ b/.ai/scripts/lint-org.el
@@ -306,6 +306,52 @@ Craig-specific annotation marker rather than Babel src-block syntax."
     (lo--goto-line line)
     (looking-at-p "^[ \t]*#\\+begin_src[ \t]+cj:")))
 
+(defvar-local lo--matched-blocks-cache nil
+  "Cons of (TICK . REGIONS) memoizing `lo--matched-block-regions'.
+TICK is the `buffer-chars-modified-tick' the regions were computed at, so a
+fix applied mid-pass invalidates them.")
+
+(defun lo--matched-block-regions ()
+  "Return ((BEGIN-LINE . END-LINE) ...) for every correctly paired block.
+Scans lines directly rather than asking org, because org's own parser is what
+mis-reads these blocks: a heading-shaped line inside a verbatim body reads as a
+structural break and loses the open block.  The scan applies org's real rule —
+once a block is open, only its own `#+end_TYPE' closes it, so a nested
+`#+begin_' or a foreign `#+end_' in the body is just text."
+  (let ((tick (buffer-chars-modified-tick)))
+    (if (eql (car lo--matched-blocks-cache) tick)
+        (cdr lo--matched-blocks-cache)
+      (let ((case-fold-search t)
+            (regions nil) (open-type nil) (open-line nil) (line 0))
+        (save-excursion
+          (goto-char (point-min))
+          (while (not (eobp))
+            (setq line (1+ line))
+            (let ((text (buffer-substring-no-properties
+                         (line-beginning-position) (line-end-position))))
+              (cond
+               (open-type
+                (when (string-match
+                       (format "\\`[ \t]*#\\+end_%s[ \t]*\\'"
+                               (regexp-quote open-type))
+                       text)
+                  (push (cons open-line line) regions)
+                  (setq open-type nil open-line nil)))
+               ((string-match "\\`[ \t]*#\\+begin_\\([^ \t\n]+\\)" text)
+                (setq open-type (match-string 1 text)
+                      open-line line))))
+            (forward-line 1)))
+        (setq lo--matched-blocks-cache (cons tick (nreverse regions)))
+        (cdr lo--matched-blocks-cache)))))
+
+(defun lo--in-matched-block-p (line)
+  "Non-nil when LINE sits within a correctly paired block, delimiters included.
+org-lint reports `invalid-block' at the delimiter lines themselves, so the
+range has to be inclusive for the suppression to reach them."
+  (cl-some (lambda (region)
+             (and (>= line (car region)) (<= line (cdr region))))
+           (lo--matched-block-regions)))
+
 (defun lo--handle-item (item)
   (let ((name (lo--checker-name item))
         (line (lo--line item))
@@ -318,6 +364,13 @@ Craig-specific annotation marker rather than Babel src-block syntax."
                         wrong-header-argument))
            (lo--cj-comment-block-opener-p line))
       nil)
+     ;; `invalid-block' on a block that is in fact correctly paired — the
+     ;; checker is org-lint's own, so this filters its output rather than
+     ;; fixing a local checker.  A genuinely unterminated block isn't in any
+     ;; matched region, so it still reports.
+     ((and (eq name 'invalid-block)
+           (lo--in-matched-block-p line))
+      nil)
      ((eq name 'item-number)
       (lo--apply-or-preview name line msg #'lo-fix-item-number))
      ((eq name 'missing-language-in-src-block)
diff --git a/.ai/scripts/tests/test-lint-org.el b/.ai/scripts/tests/test-lint-org.el
index d398c4c..ceee209 100644
--- a/.ai/scripts/tests/test-lint-org.el
+++ b/.ai/scripts/tests/test-lint-org.el
@@ -193,6 +193,65 @@ real suspicious-language warning here
 #+end_src
 ")
 
+;; invalid-block, false-positive case — a correctly paired example block whose
+;; body holds a heading-shaped line.  org's parser reads the `** ' inside the
+;; verbatim body as a structural break, loses the open block, and flags BOTH
+;; delimiters as "Possible incomplete block".
+(defconst lo-test--verbatim-heading-block "\
+* Heading
+
+#+begin_example
+** Feature Name or Topic
+Body line.
+#+end_example
+
+Trailing prose.
+")
+
+;; invalid-block, literal-delimiter case — a paired src block whose body holds
+;; a literal `#+end_example' plus a heading-shaped line.  Only `#+end_src'
+;; closes a src block, so all three findings here are false.
+(defconst lo-test--literal-end-in-src "\
+* Heading
+
+#+begin_src text
+#+end_example
+** heading shaped
+#+end_src
+")
+
+;; invalid-block, uppercase-delimiter case — org accepts #+BEGIN_/#+END_ in
+;; either case, and the pre-fix script flagged both delimiters here too.
+(defconst lo-test--uppercase-verbatim-block "\
+* Heading
+
+#+BEGIN_EXAMPLE
+** heading shaped
+#+END_EXAMPLE
+")
+
+;; invalid-block, genuine case — a block that really is never closed.  The
+;; suppression must not reach this one.
+(defconst lo-test--unterminated-block "\
+* Heading
+
+#+begin_example
+truly unterminated block body
+")
+
+;; A genuinely unterminated block *after* a correctly paired one — verifies the
+;; suppression is scoped per block rather than per file.
+(defconst lo-test--paired-then-unterminated "\
+* Heading
+
+#+begin_example
+** heading shaped
+#+end_example
+
+#+begin_example
+never closed
+")
+
 ;; Mixed fixture — each category once.
 (defconst lo-test--mixed "\
 * Mixed
@@ -392,6 +451,55 @@ suspicious-language judgment."
     (should (= 1 suspicious))))
 
 ;;; ---------------------------------------------------------------------------
+;;; invalid-block — false positives on correctly paired verbatim blocks
+
+(ert-deftest lo-verbatim-heading-block-emits-no-invalid-block ()
+  "Normal: a paired example block containing a heading-shaped body line emits
+no invalid-block judgment.  Both delimiters are flagged by org-lint because the
+parser treats the `** ' inside the verbatim body as a structural break."
+  (let* ((out (lo-test--run lo-test--verbatim-heading-block))
+         (res (plist-get out :result))
+         (judgments (lo-test--judgments (plist-get out :issues))))
+    ;; File untouched, no fixes applied — suppression only, never a rewrite.
+    (should (equal lo-test--verbatim-heading-block res))
+    (should (= 0 (plist-get out :fixes)))
+    (should-not (member 'invalid-block (lo-test--checkers judgments)))))
+
+(ert-deftest lo-literal-end-delimiter-in-src-emits-no-invalid-block ()
+  "Boundary: a paired src block whose body holds a literal `#+end_example' and
+a heading-shaped line emits no invalid-block judgment.  Only `#+end_src' closes
+a src block, so the interior delimiter is body text."
+  (let* ((out (lo-test--run lo-test--literal-end-in-src))
+         (judgments (lo-test--judgments (plist-get out :issues))))
+    (should-not (member 'invalid-block (lo-test--checkers judgments)))))
+
+(ert-deftest lo-uppercase-verbatim-block-emits-no-invalid-block ()
+  "Boundary: block delimiters are case-insensitive in org, so an uppercase
+`#+BEGIN_EXAMPLE' pair is suppressed the same as a lowercase one."
+  (let* ((out (lo-test--run lo-test--uppercase-verbatim-block))
+         (judgments (lo-test--judgments (plist-get out :issues))))
+    (should-not (member 'invalid-block (lo-test--checkers judgments)))))
+
+(ert-deftest lo-unterminated-block-still-emits-invalid-block ()
+  "Error: a block that is never closed still emits its invalid-block judgment.
+This is the finding the checker exists for — the suppression must not mask it."
+  (let* ((out (lo-test--run lo-test--unterminated-block))
+         (judgments (lo-test--judgments (plist-get out :issues))))
+    (should (member 'invalid-block (lo-test--checkers judgments)))))
+
+(ert-deftest lo-invalid-block-suppression-is-scoped-per-block ()
+  "Boundary: a paired block and an unterminated block in the same file — the
+paired one is suppressed and the unterminated one still reports.  Exactly one
+invalid-block judgment, and it points at the unterminated opener (line 7)."
+  (let* ((out (lo-test--run lo-test--paired-then-unterminated))
+         (judgments (lo-test--judgments (plist-get out :issues)))
+         (invalid (cl-remove-if-not
+                   (lambda (i) (eq (plist-get i :checker) 'invalid-block))
+                   judgments)))
+    (should (= 1 (length invalid)))
+    (should (= 7 (plist-get (car invalid) :line)))))
+
+;;; ---------------------------------------------------------------------------
 ;;; --check mode
 
 (ert-deftest lo-check-mode-does-not-modify-file ()
diff --git a/claude-templates/.ai/scripts/lint-org.el b/claude-templates/.ai/scripts/lint-org.el
index 928f83b..33dc52f 100644
--- a/claude-templates/.ai/scripts/lint-org.el
+++ b/claude-templates/.ai/scripts/lint-org.el
@@ -306,6 +306,52 @@ Craig-specific annotation marker rather than Babel src-block syntax."
     (lo--goto-line line)
     (looking-at-p "^[ \t]*#\\+begin_src[ \t]+cj:")))
 
+(defvar-local lo--matched-blocks-cache nil
+  "Cons of (TICK . REGIONS) memoizing `lo--matched-block-regions'.
+TICK is the `buffer-chars-modified-tick' the regions were computed at, so a
+fix applied mid-pass invalidates them.")
+
+(defun lo--matched-block-regions ()
+  "Return ((BEGIN-LINE . END-LINE) ...) for every correctly paired block.
+Scans lines directly rather than asking org, because org's own parser is what
+mis-reads these blocks: a heading-shaped line inside a verbatim body reads as a
+structural break and loses the open block.  The scan applies org's real rule —
+once a block is open, only its own `#+end_TYPE' closes it, so a nested
+`#+begin_' or a foreign `#+end_' in the body is just text."
+  (let ((tick (buffer-chars-modified-tick)))
+    (if (eql (car lo--matched-blocks-cache) tick)
+        (cdr lo--matched-blocks-cache)
+      (let ((case-fold-search t)
+            (regions nil) (open-type nil) (open-line nil) (line 0))
+        (save-excursion
+          (goto-char (point-min))
+          (while (not (eobp))
+            (setq line (1+ line))
+            (let ((text (buffer-substring-no-properties
+                         (line-beginning-position) (line-end-position))))
+              (cond
+               (open-type
+                (when (string-match
+                       (format "\\`[ \t]*#\\+end_%s[ \t]*\\'"
+                               (regexp-quote open-type))
+                       text)
+                  (push (cons open-line line) regions)
+                  (setq open-type nil open-line nil)))
+               ((string-match "\\`[ \t]*#\\+begin_\\([^ \t\n]+\\)" text)
+                (setq open-type (match-string 1 text)
+                      open-line line))))
+            (forward-line 1)))
+        (setq lo--matched-blocks-cache (cons tick (nreverse regions)))
+        (cdr lo--matched-blocks-cache)))))
+
+(defun lo--in-matched-block-p (line)
+  "Non-nil when LINE sits within a correctly paired block, delimiters included.
+org-lint reports `invalid-block' at the delimiter lines themselves, so the
+range has to be inclusive for the suppression to reach them."
+  (cl-some (lambda (region)
+             (and (>= line (car region)) (<= line (cdr region))))
+           (lo--matched-block-regions)))
+
 (defun lo--handle-item (item)
   (let ((name (lo--checker-name item))
         (line (lo--line item))
@@ -318,6 +364,13 @@ Craig-specific annotation marker rather than Babel src-block syntax."
                         wrong-header-argument))
            (lo--cj-comment-block-opener-p line))
       nil)
+     ;; `invalid-block' on a block that is in fact correctly paired — the
+     ;; checker is org-lint's own, so this filters its output rather than
+     ;; fixing a local checker.  A genuinely unterminated block isn't in any
+     ;; matched region, so it still reports.
+     ((and (eq name 'invalid-block)
+           (lo--in-matched-block-p line))
+      nil)
      ((eq name 'item-number)
       (lo--apply-or-preview name line msg #'lo-fix-item-number))
      ((eq name 'missing-language-in-src-block)
diff --git a/claude-templates/.ai/scripts/tests/test-lint-org.el b/claude-templates/.ai/scripts/tests/test-lint-org.el
index d398c4c..ceee209 100644
--- a/claude-templates/.ai/scripts/tests/test-lint-org.el
+++ b/claude-templates/.ai/scripts/tests/test-lint-org.el
@@ -193,6 +193,65 @@ real suspicious-language warning here
 #+end_src
 ")
 
+;; invalid-block, false-positive case — a correctly paired example block whose
+;; body holds a heading-shaped line.  org's parser reads the `** ' inside the
+;; verbatim body as a structural break, loses the open block, and flags BOTH
+;; delimiters as "Possible incomplete block".
+(defconst lo-test--verbatim-heading-block "\
+* Heading
+
+#+begin_example
+** Feature Name or Topic
+Body line.
+#+end_example
+
+Trailing prose.
+")
+
+;; invalid-block, literal-delimiter case — a paired src block whose body holds
+;; a literal `#+end_example' plus a heading-shaped line.  Only `#+end_src'
+;; closes a src block, so all three findings here are false.
+(defconst lo-test--literal-end-in-src "\
+* Heading
+
+#+begin_src text
+#+end_example
+** heading shaped
+#+end_src
+")
+
+;; invalid-block, uppercase-delimiter case — org accepts #+BEGIN_/#+END_ in
+;; either case, and the pre-fix script flagged both delimiters here too.
+(defconst lo-test--uppercase-verbatim-block "\
+* Heading
+
+#+BEGIN_EXAMPLE
+** heading shaped
+#+END_EXAMPLE
+")
+
+;; invalid-block, genuine case — a block that really is never closed.  The
+;; suppression must not reach this one.
+(defconst lo-test--unterminated-block "\
+* Heading
+
+#+begin_example
+truly unterminated block body
+")
+
+;; A genuinely unterminated block *after* a correctly paired one — verifies the
+;; suppression is scoped per block rather than per file.
+(defconst lo-test--paired-then-unterminated "\
+* Heading
+
+#+begin_example
+** heading shaped
+#+end_example
+
+#+begin_example
+never closed
+")
+
 ;; Mixed fixture — each category once.
 (defconst lo-test--mixed "\
 * Mixed
@@ -392,6 +451,55 @@ suspicious-language judgment."
     (should (= 1 suspicious))))
 
 ;;; ---------------------------------------------------------------------------
+;;; invalid-block — false positives on correctly paired verbatim blocks
+
+(ert-deftest lo-verbatim-heading-block-emits-no-invalid-block ()
+  "Normal: a paired example block containing a heading-shaped body line emits
+no invalid-block judgment.  Both delimiters are flagged by org-lint because the
+parser treats the `** ' inside the verbatim body as a structural break."
+  (let* ((out (lo-test--run lo-test--verbatim-heading-block))
+         (res (plist-get out :result))
+         (judgments (lo-test--judgments (plist-get out :issues))))
+    ;; File untouched, no fixes applied — suppression only, never a rewrite.
+    (should (equal lo-test--verbatim-heading-block res))
+    (should (= 0 (plist-get out :fixes)))
+    (should-not (member 'invalid-block (lo-test--checkers judgments)))))
+
+(ert-deftest lo-literal-end-delimiter-in-src-emits-no-invalid-block ()
+  "Boundary: a paired src block whose body holds a literal `#+end_example' and
+a heading-shaped line emits no invalid-block judgment.  Only `#+end_src' closes
+a src block, so the interior delimiter is body text."
+  (let* ((out (lo-test--run lo-test--literal-end-in-src))
+         (judgments (lo-test--judgments (plist-get out :issues))))
+    (should-not (member 'invalid-block (lo-test--checkers judgments)))))
+
+(ert-deftest lo-uppercase-verbatim-block-emits-no-invalid-block ()
+  "Boundary: block delimiters are case-insensitive in org, so an uppercase
+`#+BEGIN_EXAMPLE' pair is suppressed the same as a lowercase one."
+  (let* ((out (lo-test--run lo-test--uppercase-verbatim-block))
+         (judgments (lo-test--judgments (plist-get out :issues))))
+    (should-not (member 'invalid-block (lo-test--checkers judgments)))))
+
+(ert-deftest lo-unterminated-block-still-emits-invalid-block ()
+  "Error: a block that is never closed still emits its invalid-block judgment.
+This is the finding the checker exists for — the suppression must not mask it."
+  (let* ((out (lo-test--run lo-test--unterminated-block))
+         (judgments (lo-test--judgments (plist-get out :issues))))
+    (should (member 'invalid-block (lo-test--checkers judgments)))))
+
+(ert-deftest lo-invalid-block-suppression-is-scoped-per-block ()
+  "Boundary: a paired block and an unterminated block in the same file — the
+paired one is suppressed and the unterminated one still reports.  Exactly one
+invalid-block judgment, and it points at the unterminated opener (line 7)."
+  (let* ((out (lo-test--run lo-test--paired-then-unterminated))
+         (judgments (lo-test--judgments (plist-get out :issues)))
+         (invalid (cl-remove-if-not
+                   (lambda (i) (eq (plist-get i :checker) 'invalid-block))
+                   judgments)))
+    (should (= 1 (length invalid)))
+    (should (= 7 (plist-get (car invalid) :line)))))
+
+;;; ---------------------------------------------------------------------------
 ;;; --check mode
 
 (ert-deftest lo-check-mode-does-not-modify-file ()
diff --git a/todo.org b/todo.org
index 3131db0..f13ebbc 100644
--- a/todo.org
+++ b/todo.org
@@ -39,10 +39,17 @@ Tags are assigned and refreshed by =task-audit=; =task-review= keeps them honest
 
 * Rulesets Open Work
 
-** TODO [#C] lint-org invalid-block false-positives inside example/src blocks :bug:solo:
+** DONE [#C] lint-org invalid-block false-positives inside example/src blocks :bug:solo:
+CLOSED: [2026-07-24 Fri]
 :PROPERTIES:
 :LAST_REVIEWED: 2026-07-24
 :END:
+Fixed 2026-07-24, test-first. =lo--matched-block-regions= scans lines for correctly paired blocks under org's real rule — once a block is open, only its own =#+end_TYPE= closes it — and =lo--handle-item= drops an =invalid-block= finding whose line falls in one, delimiters included (org-lint reports at the delimiters themselves). Line-scanning rather than asking org is the point: org's parser is what mis-reads these blocks. 4 ERT tests: the heading-in-example case, a src block holding a literal =#+end_example=, a genuinely unterminated block that must still report, and a file with one of each proving the suppression is per-block not per-file.
+
+Verified against home's fixture end to end: =/home/cjennings/projects/home/.ai/notes.org= produced exactly the two reported findings (lines 386, 398) under the pre-change script and zero under the new one, file untouched. Full suite green.
+
+Left alone deliberately: the =,**= comma-escape in =claude-templates/.ai/notes.org= line 53. The task noted the fix "lets that escape be reverted," but the escape is the documented org convention for a literal =**= inside a verbatim block, so reverting it would trade correct org for no gain now that the finding is suppressed either way.
+
 home reported it, and I verified it: an =#+begin_example= block whose body contains a line beginning =** = (or any heading-shaped line) makes =invalid-block= flag *both* delimiters as "Possible incomplete block", even though the block is correctly paired. The checker reads the heading line inside the verbatim body as a structural break and loses the open block.
 
 Reproduced 2026-07-24 on a three-line example block: 2 judgment findings, both false. This is a docs-file-common shape — any org file documenting org syntax inside an example block hits it (home's notes.org PENDING DECISIONS section does).
@@ -51,7 +58,12 @@ Reproduced 2026-07-24 on a three-line example block: 2 judgment findings, both f
 
 Grading: Minor severity (judgment output, nothing mutates; pure noise that trains the reader to skim) x most users, frequently (every org file documenting org syntax in a verbatim block) = P3 = [#C].
 
-Fix direction (per home): while inside a =begin_example= / =begin_src= block, skip structural parsing of the body until the matching =#+end_= line — verbatim blocks contain no headings, timestamps, or delimiters by definition. The same class hits a src block containing =#+end_example= as literal text. Open question to settle at fix time: is =invalid-block= lint-org.el's own checker (fix in place) or org-lint's own (filter its output)? =link-to-local-file= turned out to be org-lint's; this one needs the same determination before the approach is chosen. Tagged :solo: because once that's known the fix and its test are mechanical.
+Fix direction (per home): while inside a =begin_example= / =begin_src= block, skip structural parsing of the body until the matching =#+end_= line — verbatim blocks contain no headings, timestamps, or delimiters by definition. The same class hits a src block containing =#+end_example= as literal text. Tagged :solo: because the fix and its test are mechanical.
+
+*** 2026-07-24 Fri @ 20:10:00 -0500 Open question settled — invalid-block is org-lint's, so the fix is a filter
+Home answered it and I re-verified both halves here: =grep invalid-block= over =lint-org.el= returns nothing, and =org-lint--checkers= enumerates =invalid-block= in batch Emacs alongside =link-to-local-file=, =invalid-babel-call-block=, and =missing-language-in-src-block=. So this is the same shape as the =link-to-local-file= episode: suppress an =invalid-block= finding whose line falls inside a verbatim block, on our side of org-lint's output. No local checker to edit.
+
+Regression fixture, ready to use: home's own =.ai/notes.org= PENDING DECISIONS example block (lines 386-398) holds an unescaped =** Feature Name or Topic= and trips both delimiters — findings at lines 386 and 398. Home is deliberately leaving its copy unescaped so it stays a fixture, and asked to be pinged when the filter lands so it can re-run. The filter should take those two findings to zero without touching the file.
 
 ** VERIFY [#B] Parked: telegram source treats "down" as launch, not SCAN FAILED (from .emacs.d)
 :PROPERTIES: