sloplint 0.8.0 → 0.9.0

data/lib/sloplint/cli.rb

@@ -56,6 +56,10 @@ module Sloplint
       strict = false
       select = nil
       ignore = nil
+      judge = false
+      register = nil
+      backend = nil
+      help = false
       p = OptionParser.new do |o|
         o.banner = "usage: sloplint check [options] [paths...]  (\"-\" or no paths = stdin)"
         o.on("-o", "--output-format FORMAT", %w[full json],
@@ -63,21 +67,143 @@ module Sloplint
         o.on("--markdown", "Skip fenced/inline code spans, HTML comments, and URLs before scanning.") { markdown = true }
         o.on("--select IDS", "Only run these rules (comma-separated rule ids or category names).") { |v| select = v.split(",").map(&:strip) }
         o.on("--ignore IDS", "Skip these rules (comma-separated rule ids or category names).") { |v| ignore = v.split(",").map(&:strip) }
-        o.on("--strict", "Run every rule, including the ones that are off by default.") { strict = true }
+        o.on("--strict", "Run every rule, including the ones that are off by default;",
+             "with --judge, also ask the sentence rules about every sentence, about three times the requests.") { strict = true }
+        o.on("--judge", "Also run sloplint-judge's rules, which ask a model (needs the gem and a key).") { judge = true }
+        o.on("--register TEXT", "With --judge: who the reader is.") { |v| register = v }
+        o.on("--backend NAME", "With --judge: which model adapter to use.") { |v| backend = v }
+        # OptionParser answers -h itself when nobody else does, and it answers
+        # it on the real stdout and ends the process. This command prints to
+        # the out it was given and returns, as every other one does.
+        o.on("-h", "--help", "Show this help.") { out.puts(o.help); help = true }
       end
-      p.order!(argv)
+      # permute!, so a flag written after the path is a flag: `sloplint check
+      # draft.md --judge` reads the way anyone would write it.
+      p.permute!(argv)
+      return 0 if help
 
-      unknown = unknown_rule_refs(select) + unknown_rule_refs(ignore)
+      # The judge is a separate gem that depends on this one. The bare require
+      # goes through the load path: exe/sloplint puts this checkout's lib/ at
+      # the front, so from the plugin tree the judge files beside this one win,
+      # and an installed sloplint-judge gem is found otherwise. Only a missing
+      # judge is the install hint; any other LoadError is a real one.
+      if judge
+        begin
+          require "sloplint/judge"
+        # A Gem::LoadError is an installed sloplint-judge that RubyGems will
+        # not activate beside this sloplint: a conflict, or no version that
+        # fits. It carries no path, and to the reader it is the same thing as
+        # no judge at all, which is how `--help` already reports it.
+        rescue LoadError => e
+          raise unless e.path == "sloplint/judge" || e.is_a?(Gem::LoadError)
+
+          err.puts("sloplint: --judge needs the sloplint-judge gem: gem install sloplint-judge")
+          # An installed judge that RubyGems will not activate is a version
+          # conflict, and the hint above tells the reader to install what
+          # they already have. RubyGems says which versions fell out, so
+          # print that too rather than throwing it away.
+          err.puts("sloplint: #{e.message}") if e.is_a?(Gem::LoadError)
+          return 2
+        end
+      end
+      # Accepted and then dropped, these two read as a judge run that was
+      # never asked for: `sloplint check --register "a lawyer" brief.md` runs
+      # the regex rules and says nothing about the reader it was given.
+      unless judge
+        { "--register" => register, "--backend" => backend }.each do |flag, value|
+          next if value.nil?
+
+          err.puts("sloplint: #{flag} needs --judge: without it no model is asked anything.")
+          return 2
+        end
+      end
+      catalog = judge ? RULES + Judge::RULES : RULES
+
+      unknown = unknown_rule_refs(select, catalog) + unknown_rule_refs(ignore, catalog)
       unless unknown.empty?
         err.puts("sloplint: unknown rule or category: #{unknown.join(", ")}")
-        err.puts("run `sloplint rules` to list them.")
+        # Under --judge the selection is read against both catalogs, and
+        # `sloplint rules` lists only one of them: a judge rule id typed with
+        # a letter wrong is not in the list the hint would send you to.
+        lists = judge ? "`sloplint rules` and `sloplint-judge rules`" : "`sloplint rules`"
+        err.puts("run #{lists} to list them.")
         return 2
       end
 
-      rules = select_rules(select, ignore, strict)
+      rules = select_rules(select, ignore, strict, catalog)
       paths = argv.empty? ? ["-"] : argv
       by_path = paths.reject { |x| x == "-" }.size > 1
 
+      # Only the read is invalid input. An ArgumentError out of a scan or a
+      # judge run is a bug in this code, and it raises like one instead of
+      # sending the reader to look for bad bytes in a file that has none.
+      sources = begin
+        read_sources(paths, err:, stdin:)
+      rescue ArgumentError, Encoding::CompatibilityError => e
+        err.puts("sloplint: invalid input: #{e.message}")
+        return 2
+      end
+      return 2 unless sources
+
+      regex_rules, judge_rules = rules.partition { |r| r.is_a?(Rule) }
+
+      judge_usage = nil
+      # Under --judge the output is the {"notes", "judge"} object whether or
+      # not a judge rule survived selection: a caller that asked for the judge
+      # reads the wrapper, and an empty selection is 0 requests, not a
+      # different output shape. 0 requests also means no key: `--judge
+      # --select em-dash` must run on a machine that has none.
+      #
+      # Before the regex scan, not after it: a missing key or a bad
+      # SYSTEMONE_URL is known without asking anything, and finding it out
+      # after every file has been scanned throws that work away to print the
+      # same message.
+      if judge
+        # With nothing to ask, no key is read: the backend is named and never
+        # built, and `sloplint-judge check` reports an empty selection through
+        # the same helper, so the two commands print one line. Either way an
+        # unknown --backend or a key that is not there is the same usage
+        # error, so one rescue answers for both.
+        begin
+          if judge_rules.empty?
+            judge_usage = Judge::Engine.nothing_asked(backend)
+          else
+            judge_backend = Judge::Backend.load(backend)
+          end
+        rescue ArgumentError => e
+          err.puts("sloplint: --judge: #{e.message}")
+          return 2
+        end
+      end
+
+      all_notes = sources.flat_map do |label, text|
+        Engine.scan(text, rules: regex_rules, markdown:, path: label)
+      end
+
+      if judge_usage
+        err.puts("sloplint: judge #{Judge::Engine.usage_line(judge_usage)}")
+      elsif judge_backend
+        begin
+          judged = Judge::Engine.scan_sources(sources, name: "sloplint: judge", err:, rules: judge_rules, backend: judge_backend,
+                                                       markdown:, register: register || Judge::Engine::DEFAULT_REGISTER, strict:)
+        # Exit 3 withholds the regex notes too: a caller that asked for both
+        # and got one would read it as a clean judge run.
+        rescue Judge::BackendError => e
+          err.puts("sloplint: judge backend failure: #{e.message}")
+          return 3
+        end
+        order = sources.each_with_index.to_h { |(label, _), i| [label, i] }
+        all_notes = (all_notes + judged.notes).sort_by.with_index { |n, i| [order[n.path], n.line, n.column, i] }
+        judge_usage = judged.usage
+      end
+
+      emit(all_notes, opts[:format], out:, by_path:, judge: judge_usage)
+      all_notes.empty? ? 0 : 1
+    end
+
+    # Read every path (or stdin for "-") as UTF-8. Returns [[label, text], ...]
+    # or nil after writing the error, so the caller exits 2.
+    def read_sources(paths, err:, stdin: $stdin, name: "sloplint")
       sources = []
       paths.each do |path|
         # Read as UTF-8 whatever the locale says. A sandbox with no LANG set
@@ -90,11 +216,20 @@ module Sloplint
             stdin.read.force_encoding(Encoding::UTF_8)
           else
             unless File.file?(path)
-              err.puts("sloplint: no such file: #{path}")
-              return 2
+              err.puts("#{name}: no such file: #{path}")
+              return nil
             end
             File.read(path, encoding: Encoding::UTF_8)
           end
+        # Prose that is not valid UTF-8 is an invalid input, said here rather
+        # than left to whatever reads the text first: a scan raises on the
+        # first regex, and the judge sends the text to a backend, where it
+        # would be a JSON error after the request was paid for.
+        unless text.valid_encoding?
+          err.puts("#{name}: invalid input: #{path == "-" ? "stdin" : path} is not valid UTF-8")
+          return nil
+        end
+
         sources << [path == "-" ? "-" : path, text]
       end
 
@@ -104,29 +239,19 @@ module Sloplint
       # mistyped rule id sets, and it exits 2 for the same reason.
       if sources.all? { |_, text| text.strip.empty? }
         names = sources.map { |label, _| label == "-" ? "stdin" : label }
-        err.puts("sloplint: empty input: nothing to check in #{names.join(", ")}")
-        return 2
-      end
-
-      all_notes = sources.flat_map do |label, text|
-        Engine.scan(text, rules:, markdown:, path: label)
+        err.puts("#{name}: empty input: nothing to check in #{names.join(", ")}")
+        return nil
       end
+      sources
+    end
 
-      case opts[:format]
-      when "json"
-        out.puts(Output.format_json(all_notes, by_path:))
+    def emit(notes, format, out:, by_path:, judge: nil)
+      if format == "json"
+        out.puts(Output.format_json(notes, by_path:, judge:))
       else
-        text = Output.format_human(all_notes)
+        text = Output.format_human(notes)
         out.puts(text) unless text.empty?
       end
-
-      all_notes.empty? ? 0 : 1
-    # Invalid UTF-8 reaches this two ways: String#strip in the empty check
-    # raises Encoding::CompatibilityError, the engine's regexes raise
-    # ArgumentError. Both are the same thing to the reader.
-    rescue ArgumentError, Encoding::CompatibilityError => e
-      err.puts("sloplint: invalid input: #{e.message}")
-      2
     end
 
     # ── rules ───────────────────────────────────────────────────────────────
@@ -137,19 +262,26 @@ module Sloplint
         o.on("--json", "Emit the catalog as JSON for machine enumeration.") { as_json = true }
       end.order!(argv)
 
-      if as_json
-        payload = RULES.map do |r|
+      render_rules(RULES, json: as_json, out:)
+      0
+    end
+
+    # The catalog as a table or as JSON. Shared with sloplint-judge, whose
+    # rules also carry a unit.
+    def render_rules(catalog, json:, out:)
+      if json
+        payload = catalog.map do |r|
           { id: r.id, category: r.category, severity: r.severity, confidence: r.confidence,
             message: r.message, rationale: r.rationale, suggestion: r.suggestion }
+            .merge(r.respond_to?(:unit) ? { unit: r.unit } : {})
         end
         out.puts(JSON.pretty_generate(payload))
       else
-        RULES.each do |r|
+        catalog.each do |r|
           off = r.confidence == "low" ? " [off by default]" : ""
           out.puts("#{r.id.ljust(24)} #{r.category.ljust(18)} #{r.severity.ljust(8)} #{r.confidence.ljust(7)} #{r.message}#{off}")
         end
       end
-      0
     end
 
     # ── explain ID ────────────────────────────────────────────────────────
@@ -190,10 +322,10 @@ module Sloplint
     # ── helpers ─────────────────────────────────────────────────────────────
     # Ids/categories in refs that match no rule in the catalog. nil (no --select
     # or --ignore given) passes through as no unknowns.
-    def unknown_rule_refs(refs)
+    def unknown_rule_refs(refs, catalog = RULES)
       return [] unless refs
 
-      known = RULES.flat_map { |r| [r.id, r.category] }.uniq
+      known = catalog.flat_map { |r| [r.id, r.category] }.uniq
       refs - known
     end
 
@@ -201,15 +333,15 @@ module Sloplint
     # excludes low-confidence rules unless they are explicitly selected. A
     # category ref selects only that category's non-low rules unless --strict
     # is set; naming a rule by its own id still selects it whatever its
-    # confidence.
-    def select_rules(select, ignore, strict = false)
+    # confidence. catalog is RULES, or RULES plus the judge's under --judge.
+    def select_rules(select, ignore, strict = false, catalog = RULES)
       runs_by_default = ->(r) { r.confidence != "low" }
       rules = if select
-        RULES.select { |r| select.include?(r.id) || (select.include?(r.category) && (runs_by_default.call(r) || strict)) }
+        catalog.select { |r| select.include?(r.id) || (select.include?(r.category) && (runs_by_default.call(r) || strict)) }
       elsif strict
-        RULES
+        catalog
       else
-        RULES.select(&runs_by_default)
+        catalog.select(&runs_by_default)
       end
       if ignore
         rules = rules.reject { |r| ignore.include?(r.id) || ignore.include?(r.category) }
@@ -217,9 +349,37 @@ module Sloplint
       rules
     end
 
-    def global_parser(opts, out:)
-      OptionParser.new do |o|
-        o.banner = <<~BANNER
+    # The judge's part of the agent recipe, which depends on whether the gem
+    # is here. Looked up on the load path without loading it: help must not
+    # pull a model adapter in. The text says the one thing an agent must know
+    # before the flag: the judge sends the text to an API, so ask the person.
+    def judge_recipe
+      # Installed as a gem, the judge is not on the load path until RubyGems
+      # activates it, so the load path alone reports a missing gem. A gem on
+      # disk that asks for a different sloplint cannot be activated beside
+      # this one, and advertising it would send the agent into a conflict.
+      installed = $LOAD_PATH.resolve_feature_path("sloplint/judge") ||
+                  Gem::Specification.find_all_by_name("sloplint-judge").any? { |spec|
+                    spec.dependencies.find { |d| d.name == "sloplint" }&.match?("sloplint", Sloplint::VERSION)
+                  }
+      unless installed
+        return "# sloplint-judge (not installed here) adds model-backed rules for what a regex cannot see: gem install sloplint-judge\n"
+      end
+
+      <<~RECIPE
+        # With the judge (sloplint-judge is installed here). It sends the text to api.typesafe.ai,
+        # so an agent asks the person before running it. Check first, ask, then run:
+        sloplint-judge status                            # exit 0 = a key is set up (reads no key), 2 = not
+        sloplint check --judge --markdown -o json FILE    # output becomes {"notes": [...], "judge": {requests, tokens, cost_usd}}
+        # exit 3 = the model could not be reached; nothing was checked, not even the regex rules
+      RECIPE
+    end
+
+    # The banner names whether the judge gem is here, which costs a scan of
+    # the installed gems. Only --help reads it, so it is built when it is
+    # read and never on the way to a scan.
+    def global_banner
+      <<~BANNER
           sloplint — flag the rhetorical tics and puffery that mark AI-generated prose.
 
           # Recommended for agents:
@@ -228,17 +388,23 @@ module Sloplint
           # each note: {path,line,column,severity,confidence,rule,category,message,excerpt,context,rationale,suggestion,count}
           # (count is present only for the rules that tally items)
 
+          #{judge_recipe}
           usage: sloplint [-o full|json] [command] [args]
 
           commands:
             check        scan paths (or stdin) for AI-slop tells and report notes [default]
                          a first argument that is not a command name is taken as a path
+                         --judge adds sloplint-judge's model-backed rules when that gem is installed
             rules        list the rule catalog (add --json for the machine-readable form)
             explain ID   print one rule's message, rationale, and a bad/ok example
             version      print the sloplint version
 
           global options:
-        BANNER
+      BANNER
+    end
+
+    def global_parser(opts, out:)
+      parser = OptionParser.new do |o|
         o.on("-o", "--output-format FORMAT", %w[full json],
              "Output format: 'full' (human-readable text) or 'json' (default: full).") do |v|
           opts[:format] = v
@@ -254,6 +420,8 @@ module Sloplint
         o.separator ""
         o.separator "See `sloplint explain <id>` for any rule, or docs/SPEC.md for the JSON contract."
       end
+      parser.define_singleton_method(:banner) { CLI.global_banner }
+      parser
     end
   end
 end

data/lib/sloplint/engine.rb

@@ -59,14 +59,21 @@ module Sloplint
     # over blanked text shows code and URLs as a run of spaces. Offsets here are
     # character offsets (MatchData#begin), matching the char-based line_starts_for.
     def context_for(source, match)
-      return "[#{match[0].gsub(/\s+/, " ").strip}]" if match[0].length >= CONTEXT_CHARS
+      context_window(source, match.begin(0), match.end(0))
+    end
+
+    # The same window for any span [b, e) of source, so a tool that locates a
+    # sentence rather than a regex match (the judge) draws its context the
+    # way sloplint does.
+    def context_window(source, b, e)
+      span = source[b...e]
+      return "[#{span.gsub(/\s+/, " ").strip}]" if span.length >= CONTEXT_CHARS
 
-      b, e = match.begin(0), match.end(0)
       pre  = source[[b - CONTEXT_CHARS, 0].max...b]
       post = source[e, CONTEXT_CHARS].to_s
       pre  = "…#{pre.sub(/\A\S*\s+/, "")}" if b > CONTEXT_CHARS
       post = "#{post.sub(/\s+\S*\z/, "")}…" if e + CONTEXT_CHARS < source.length
-      "#{pre}[#{match[0]}]#{post}".gsub(/\s+/, " ").strip
+      "#{pre}[#{span}]#{post}".gsub(/\s+/, " ").strip
     end
 
     # 1-indexed line and column for a char offset into text. Binary-searches a
@@ -101,8 +108,28 @@ module Sloplint
     # with one alternation, so whichever construct opens first is the one that
     # gets consumed: a `<!--` quoted inside backticks is inline code, and a
     # backtick inside a comment is part of the comment.
+    # A URL ends before the punctuation that ends the sentence it sits in:
+    # "See https://example.com. Then do X." is two sentences, and swallowing
+    # the first period would make it one. A URL that really ends in one of
+    # these, a Wikipedia link closing on a bracket, loses that character to
+    # the sentence instead; the text is only being blanked, so what it costs
+    # is one visible character, not a broken link.
+    # A fence opens and closes at the start of a line, with three or more
+    # backticks; the opener may carry an info string and the closer nothing
+    # but whitespace. The line start is the shape that matters: a fence
+    # quoted inside a code span, which is how a document explains fences,
+    # opened a block in the middle of a sentence and every fence after it in
+    # the file paired with the wrong one.
+    #
+    # Any indent is allowed, because CommonMark measures a fence's indent
+    # from its container and a fence under "10. " or a nested bullet stands
+    # further in than three spaces. What that costs is an indented code block
+    # whose own content has a line of backticks in it, which is rare, and the
+    # only thing it costs there is more blanking.
+    MARKDOWN_NOISE = /(?<block>^[ \t]*`{3,}[^\n]*\n.*?^[ \t]*`{3,}[ \t]*$|<!--.*?-->)|(?<inline>`[^`\n]*`|https?:\/\/\S*[^\s.,;:!?)\]])/m
+
     def blank_markdown(text)
-      text.gsub(/```.*?```|<!--.*?-->|`[^`\n]*`|https?:\/\/\S+/m) { |s| s.gsub(/[^\n]/, " ") }
+      text.gsub(MARKDOWN_NOISE) { |s| s.gsub(/[^\n]/, " ") }
     end
   end
 end

data/lib/sloplint/output.rb

@@ -20,13 +20,17 @@ module Sloplint
     end
 
     # JSON: an array of notes, or an object keyed by path when >1 file was scanned.
-    def format_json(notes, by_path: false)
-      if by_path
-        grouped = notes.group_by(&:path).transform_values { |ns| ns.map { |n| note_hash(n) } }
-        JSON.pretty_generate(grouped)
+    # judge: when the judge ran, its backend name and usage; the notes then
+    # sit under "notes" and the usage under "judge", so a caller who asked for
+    # the model's opinion also gets what it cost.
+    def format_json(notes, by_path: false, judge: nil)
+      payload = if by_path
+        notes.group_by(&:path).transform_values { |ns| ns.map { |n| note_hash(n) } }
       else
-        JSON.pretty_generate(notes.map { |n| note_hash(n) })
+        notes.map { |n| note_hash(n) }
       end
+      payload = { "notes" => payload, "judge" => judge } if judge
+      JSON.pretty_generate(payload)
     end
 
     def note_hash(note)

data/lib/sloplint/rules.rb

@@ -1895,6 +1895,59 @@ module Sloplint
       rationale: "Labelling a claim as the portable lesson does the persuading that the claim " \
                  "should be doing — a model habit borrowed from thought-leader prose."
     ),
+    Rule.new(
+      id: "cataphoric-teaser",
+      category: "self-rating",
+      severity: "warning",
+      confidence: "high",
+      # The forward-pointing tease: "Here's what nobody tells you", "the
+      # part most people get wrong". Three parts, each a closed frame. A
+      # sentence-initial position, optionally opened by a forward demonstrative
+      # (here's / this is; "that's what nobody understands" points backward
+      # and is left alone). A noun slot: what / the part / the thing / the
+      # bit / the secret. A subject that claims scarcity for the reader's
+      # benefit: nobody, no one, most people, few people, hardly anyone,
+      # they, people. Then up to two adverbs and a verb of telling, getting
+      # wrong, talking about, admitting or noticing. The bare subject form
+      # ("What nobody tells you ...") must also reach a copula or colon in
+      # the same sentence, since that is what makes it a setup rather than a
+      # plain report ("What nobody tells you gets forgotten."), and it may
+      # not take "they": without a demonstrative in front, "what they don't
+      # realize is" refers to the people the story is about, and narrative
+      # says it. Read across 8.7 MB of RAID that was the one human hit.
+      pattern: /(?:\A|[.!?]\s+|\n\s*\n|:\s+)\s*
+                (?:(?<demo>(?:\w+,?\s+)?(?:here'?s|here\s+is|this\s+is)\s+)|(?-i:(?=[A-Z])))
+                (?:what|the\s+(?:part|thing|bit|secret))\s+
+                (?:nobody|no[-\s]?one|most\s+\w+(?:\s+\w+)?|few\s+people|hardly\s+anyone|almost\s+(?:nobody|no[-\s]?one)|people|(?(<demo>)they|(?!)))\s+
+                (?:(?:will|won'?t|don'?t|doesn'?t|actually|ever|really|never|rarely|wants?\s+to)\s+){0,2}
+                (?:tells?|gets?|talks?|says?|admits?|mentions?|warns?|teach(?:es)?|explains?|notices?|realizes?|understands?|hears?)\b
+                (?(<demo>)|[^.!?\n:]{0,60}?(?:\s+is\b|:))/ix,
+      message: "Cataphoric teaser promises a hidden insight before giving it.",
+      suggestion: "Cut the tease and state the thing itself.",
+      examples_bad: [
+        "Here's what nobody tells you about hiring.",
+        "Here is the part most people get wrong.",
+        "This is the thing they don't tell you.",
+        "What nobody tells you is that the migration is the easy part.",
+        "The part nobody talks about is the rollback.",
+        "What most senior engineers won't admit is that the estimate was a guess.",
+        "So here's what few people realize: the cache is cold on every deploy."
+      ],
+      examples_ok: [
+        # Backward-pointing: the sentence reports, it does not tease.
+        "That's what nobody understands.",
+        "That is the part most people get wrong.",
+        # A bare-subject sentence that never reaches a copula is a report.
+        "What nobody tells you gets forgotten by lunch.",
+        # Mid-sentence, the phrase is an object, not a setup.
+        "I finally learned what nobody tells you about hiring.",
+        # Lowercase after a hard wrap is a continuation, not a sentence start.
+        "the reviewer read it and\nwhat nobody tells you is that she signed it anyway."
+      ],
+      rationale: "The tease sells the claim as rare knowledge before the claim exists, so the " \
+                 "reader is asked to rate it before reading it. Models reach for it as an " \
+                 "opener because engagement training rewards the hook."
+    ),
     Rule.new(
       id: "is-is",
       category: "cadence",
@@ -3079,6 +3132,80 @@ module Sloplint
                  "it to close a setup; careful writers join the clauses with a conjunction " \
                  "or give the problem its own sentence."
     ),
+    Rule.new(
+      id: "punch-sentence",
+      category: "cadence",
+      severity: "info",
+      confidence: "medium",
+      # The mid-paragraph punch: a verbless beat of one to three words wedged
+      # between two long sentences. "...for the third time that quarter. Not
+      # anymore. The new rota puts..." mic-drop-closer and
+      # bare-auxiliary-closer take the long-then-short shape at the end of a
+      # paragraph; this is the one in the middle, which the closer rules
+      # refuse. The setup is the shared sixty-character prefix, and a
+      # sentence of forty or more characters must follow on the same
+      # paragraph, so a closer and a run of short sentences (short-run's
+      # tell) are both left to their own rules.
+      #
+      # Read against RAID, the first draft fired on human prose at four
+      # times its model rate, and every kind of hit is now a guard:
+      #
+      # A title or initial before the stop ("Mrs. Cadaver.", "John F.
+      # Kennedy.", "St. Petersburg.") makes the proper name after it look
+      # like a one-word sentence, so the stop the punch follows may not
+      # close a capitalised word of one to four letters, or a lone lowercase
+      # letter ("Swift v. Tyson"). The same guard on
+      # the punch's own last word ("When Mr.", "Felix and Rev.") is why a
+      # lone word must be five letters or more when capitalised; a lowercase
+      # last word ("Not anymore.") is never an abbreviation.
+      #
+      # A short clause with a pronoun subject ("He agrees.", "She complies.",
+      # "Both die.") is how a plot summary and a news brief move the story
+      # along, and an imperative with a name or a noun subject ("Dawes
+      # refuses.", "Set aside.") reads the same to a regex as a beat, so the
+      # punch is two closed shapes: a negator (Not, No, Never, Nothing,
+      # None) with up to two lowercase words after it, or one capitalised
+      # word of five letters or more. A one-word imperative in procedural
+      # prose ("Drain.", "Repeat.") still lands in the second shape, at about
+      # one per 25,000 words of recipes, which the info severity allows for.
+      pattern: /#{SENTENCE_OF_SIXTY_CHARACTERS_ENDING_IN_PUNCTUATION_AND_SPACE}\K
+                (?<![A-Z]\.[ \t]|[A-Z][a-z]\.[ \t]|[A-Z][a-z]{2}\.[ \t]|[A-Z][a-z]{3}\.[ \t]|[ \t][a-z]\.[ \t]
+                  |[A-Z]\.[ \t]{2}|[A-Z][a-z]\.[ \t]{2}|[A-Z][a-z]{2}\.[ \t]{2}|[A-Z][a-z]{3}\.[ \t]{2}|[ \t][a-z]\.[ \t]{2})
+                (?:(?:Not|No|Never|Nothing|None)(?:(?:[ \t]|\r?\n(?!\s*\n)[ \t]*)[a-z][A-Za-z'’-]*){0,2}
+                  |[A-Z][A-Za-z'’-]{4,})\.
+                (?=[ \t]{1,2}[A-Z](?:[^.!?\n]|\r?\n(?!\s*\n)){40,})/x,
+      message: "A verbless beat of three words or fewer between two long sentences is the AI punch.",
+      suggestion: "Fold the beat into the sentence before or after it, or cut it.",
+      examples_bad: [
+        "The on-call engineer had been paged for the same cron job three nights running that week. Not anymore. The job now checks the lock file before it starts and exits quietly.",
+        "The reviewers spent the whole afternoon arguing about whether the migration should run in one pass. Never again. The first half ran on Tuesday and the second half is still waiting on a sign-off.",
+        "Every team we talked to had a wiki page describing the release process in loving detail. No exceptions. The page had not been touched since the person who wrote it left the company.",
+        "The retry loop was supposed to give up after five attempts and page someone with the error. Simple. Instead it kept going all night because the counter reset on every restart."
+      ],
+      examples_ok: [
+        # Paragraph-final: that is the closer rules' shape, not this one.
+        "The reviewers spent the whole afternoon arguing about whether the migration should run in one pass. Not anymore.",
+        # Followed by another short sentence: short-run's territory.
+        "The reviewers spent the whole afternoon arguing about whether the migration should run in one pass. Not anymore. Nobody minded. The second half is still waiting on a sign-off from the platform team.",
+        # A short clause with a pronoun subject is narrative, not a beat.
+        "The reviewers spent the whole afternoon arguing about whether the migration should run in one pass. It didn't. The first half ran on Tuesday and the second half is still waiting on a sign-off.",
+        "Every team we talked to had a wiki page describing the release process in loving detail. Nobody read it. The page had not been touched since the person who wrote it left the company.",
+        # A title or initial with its complement on the far side of the stop.
+        "The committee met for the last time on a wet Thursday in the back room of the library annex. Mr. Whitaker moved that the minutes be approved as read and the motion carried without a vote.",
+        "The only survivor of the crash on the coast road that spring was the widow of the lighthouse keeper, Mrs. Cadaver. The inquest sat for two days in the town hall and returned no verdict at all.",
+        "The freight line ran west from the river through three counties before it reached the yards. St. Louis was the end of the line for most of the crews and the start of it for the rest.",
+        "The freight line ran west from the river through three counties before it reached the yards. Cyrus M. Jarrett owned the yards and every siding on the line from the river to the state line.",
+        "The rule that a federal court sitting in diversity applies general common law was set out in Swift v. Tyson. The decision stood for nearly a century before the court overruled it in Erie.",
+        # Digits are data, and a quotation mark is dialogue.
+        "The freight line ran west from the river through three counties before it reached the yards. Fig. 2 shows the route as it stood in 1890 and the sidings that were added after the flood.",
+        "The freight line ran west from the river through three counties before it reached the yards. \"Enough.\" The foreman waved the crew back toward the sheds and nobody argued with him.",
+        # Four or more words is a sentence, not a beat.
+        "The freight line ran west from the river through three counties before it reached the yards. The crews liked it. The foreman waved the crew back toward the sheds and nobody argued with him."
+      ],
+      rationale: "The beat withholds the verb and the object the long sentence set up and " \
+                 "hands the reader a pause instead. People write one on purpose; a draft " \
+                 "that keeps doing it is the tell, which is why it ships at info."
+    ),
     Rule.new(
       id: "np-fragment-and",
       category: "cadence",