#+TITLE: lint-org.el bug: invalid-block false positive on an example 
#+SOURCE: from home
#+DATE: 2026-07-24 12:48:05 -0500

lint-org.el bug: invalid-block false positive on an example block containing a heading line.

Repro: an org file with

  #+begin_example
  ** Feature Name or Topic
  #+end_example

reports BOTH delimiters as judgment findings — 'Possible incomplete block "#+begin_example"' on the begin line and 'Possible incomplete block "#+end_example"' on the end line — even though the block is correctly paired. The trigger is the literal '** ' heading line inside the block body; the checker appears to treat it as a structural break rather than block content, so it loses track of the open block.

Seen in home's .ai/notes.org (the PENDING DECISIONS section documents its own task format inside an example block, which is a legitimate and common shape for a docs file). These are the only 2 findings left in that file after I cleaned up the real defects, so they're pure noise now and they'll recur on any org file that documents org syntax inside an example block.

Suggested fix: while inside a begin_example/begin_src block, skip structural parsing of the body entirely until the matching #+end_ line. Example and src blocks are verbatim by definition, so nothing inside them should be read as a heading, a timestamp, or a block delimiter.

Worth noting the same class of bug would hit a src block containing '#+end_example' or similar as literal text.

Context on what surfaced it: home's notes.org had 17 lint findings that had been dismissed as false positives across several sessions. 15 were real — the file used markdown '**bold**' where org wants single asterisks, so it rendered as literal asterisks and looked heading-shaped to the checker. Fixing the markup cleared those. That left these 2, which are the genuine checker bug. The lesson for the checker's credibility: a persistent block of 'known false positives' hid 15 real defects, because nobody re-examined the pile once it got labeled.