sloplint 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0aabc7314411211ed5adcbb5e09bb81a4291b2ffb7748e8d07d15f0150e6c43c
-  data.tar.gz: f8c9af283d490a6acb2d4cd6260ccc776e868542be3f1b10066ec6232e856ea0
+  metadata.gz: 9031ddb2a2a80637f1958c3ec24014261a23b017c25cc3032e72e85f9acf0313
+  data.tar.gz: 53389164a5fdf74367d985bc1d3eff0d661c47cb70d22469ab89e55f56e4ac22
 SHA512:
-  metadata.gz: 508f10329c7698ab4cce5b1dd09902984975ed2baeaa5646b7c288d33ee913f1a8f19e2aba36ab860a77a7b2ea2acde07748ce11db39367958c6ec86af3b4b1f
-  data.tar.gz: b75def69bddf045ddab9f99798985cf210ae7b3997266f9199600cf77638b5db8759738879b51949f31945b2ad183706b34654736cfdd7420f292c5442d2445d
+  metadata.gz: 2029db5c55bdaed221ff62c629eaf9989bf05044274f340295ecb5122ba5cd063c773566c9c9bf8e201050348284103f6910aed13b6b24745b538ed030738612
+  data.tar.gz: 46130960f17c5fd70b7a8752065fc85520b8eeac94498588b3d0b798daa3bdb8683ab5084e258e561a9b502227793d9746c0fc7e2d7ab2f143a0b5f7364c2fc7

data/CHANGELOG.md

@@ -3,7 +3,129 @@
 All notable changes to this project are documented here. Format loosely
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [Unreleased]
+## sloplint-judge
+
+### [0.1.0] - 2026-09-21
+
+- New sentence rule `unnamed-authority` (`info`, `medium`): a claim handed to
+  experts, studies, research, critics or many, an authority the reader could
+  not find and that speaks for nobody. Officials, a spokesperson and the
+  other sources news quotes by convention pass, and so does an abstract's
+  prior work. The reading behind the regex `vague-attribution`.
+- New sentence rule `stated-stakes` (`info`, `low`, off by default): a sentence
+  that says something is crucial, vital or key and gives no fact, number or
+  consequence, in it or in the sentence after it. Off by default because the
+  model rarely answers it above low confidence; `--select stated-stakes` or
+  `--strict` runs it.
+- A rule at `low` confidence (`same-weight`, `matched-shape`) now reports its
+  notes when `--select` names it; before, they ran and printed nothing
+  without `--strict`. The rule's `low` caps the note's confidence; what a
+  default run drops is an answer the model itself gave at low confidence.
+- `check --judge` always writes the `{"notes", "judge"}` object, with 0
+  requests when no judge rule survived selection. `compare` accepts
+  `--drift` after the two files and refuses a third. `status` refuses a key
+  with a control character the way `check --judge` does.
+- Graveyard: `owned-claim` was retried as `no-actor` and stays out, and
+  `buried-verbs`, the paragraph reading of the nominalization shift, joins
+  it; neither crossed the flag on any side. The entries in `docs/JUDGE.md`
+  say so.
+- New paragraph rule `promotional` (`warning`, `medium`): a paragraph in
+  which every judgment is favorable, none comes with a measure and no
+  drawback appears. The paragraph-level reading behind `puffery-words`,
+  which catches the register after the watch words have aged out.
+- New paragraph rule `self-narration` (`info`, `medium`): a paragraph whose
+  sentences signpost the document, what comes first, what a section covers,
+  what the reader should take away, instead of saying something about the
+  subject. `throat-clearing` sees the first sentence; this is the paragraph.
+- `script/calibrate run` also prints how many units each side would have
+  flagged at the confidence `check` reports. A rare flag barely moves the
+  rank statistic, so for such a rule the count is the number to quote.
+- New paragraph rule `same-weight` (`info`, `low`, off by default): a paragraph
+  that states its inferences and opinions as flatly as its measurements, with
+  no probably, no we think, and no reason given. Separates model from human
+  text in news and abstracts; off by default because a design document argues
+  in flat sentences on purpose. `--select same-weight` or `--strict` runs it.
+- New sentence rule `trailing-gloss` (`info`, `medium`): a sentence that ends
+  on a comma and an -ing clause that interprets the fact before it
+  ("highlighting the value of", "underscoring the importance of") rather than
+  adding a fact or a consequence. The reading the regex
+  `trailing-significance-participle` could not do.
+- Graveyard: `redundancy` was retried as `restatement` with the fairness
+  reading it was owed, reversed in news against every model side, and stays
+  out. The entry in `docs/JUDGE.md` says why.
+- `wrap-up` also flags a last sentence that admits problems and then
+  promises a bright future ("Despite these challenges, the future looks
+  promising"). Its flagged level says so, its message now reads "Paragraph
+  ends on a summary, a moral or a hope", and fixtures pin both sides: the
+  hope that names nothing is flagged, the same frame closing on a dated
+  fact is not. Wikipedia's field guide documents the formula across
+  unrelated topics, and the GPT family ends documents on it.
+
+- First release of the judge gem: the rule catalog in `docs/JUDGE.md`, the
+  Jev backend, `check`, `compare`, `rules`, `explain`, and `script/calibrate`.
+  Requires sloplint 0.9; see "Phase two" in `docs/JUDGE.md` for what is next.
+- `check` reports what the judge spent: JSON output is `{"notes", "judge"}`
+  with the backend, request count, token counts and cost in dollars under
+  `judge`, and the same line goes to stderr. Jev returns no price, so the
+  cost is computed from TypeSafe's public price: $42 per billion input
+  tokens, output tokens free.
+- The key can live in the OS keychain instead of the environment.
+  `sloplint-judge key set` stores it once (the keychain tool prompts, so the
+  key is never on a command line), the Jev adapter reads it after
+  `TYPESAFE_API_KEY`, and `sloplint-judge status` says whether a run could
+  happen and where the key is, without reading it. `sloplint-judge key
+  unset` removes the item. The check skill probes with `status`.
+- `SYSTEMONE_URL` must point at a `typesafe.ai` host, not only be `https`:
+  the key and the document go there, so an injected URL on the sanctioned
+  command is refused with exit 2.
+
+## sloplint
+
+## [0.9.0] - 2026-09-21
+
+### Added
+
+- `sloplint check --judge` runs the rules of sloplint-judge alongside the
+  regex catalog and merges the notes in document order. The judge is a second
+  gem built from this repository (`sloplint-judge.gemspec`, `exe/sloplint-judge`)
+  whose rules are questions put to a System One model. sloplint loads it by
+  name only and exits 2 with an install hint when it is missing. A backend
+  failure under `--judge` is exit 3 and writes no notes. See `docs/JUDGE.md`.
+- `Sloplint::Split`, a paragraph and sentence splitter that keeps offsets into
+  the source, and `Engine.context_window`, the note's context drawn for any
+  span rather than only a regex match. Both are used by the judge.
+- `script/calibrate`, which measures a judge backend against RAID and a
+  current-model side generated from RAID's own prompts, and reports the
+  pass lines from `docs/JUDGE.md`.
+
+### Fixed
+
+- `--markdown` opens and closes a fenced code block only at the start of a
+  line, at any indent, so a fence under `10. ` or a nested bullet still
+  pairs. A fence quoted inside a sentence (```` ``` ````) used to open a
+  block there, and every fence after it paired wrong for the rest of the file.
+- The splitter also drops indented code blocks (four spaces or a tab), lines
+  that are one HTML tag, and YAML front matter under `--markdown`, so none of
+  them reach the judge as prose.
+
+## [0.8.1] - 2026-09-20
+
+### Added
+
+- `cataphoric-teaser` (self-rating, warning, high confidence): the
+  forward-pointing tease that sells a claim as rare knowledge before making
+  it. "Here's what nobody tells you about hiring.", "The part most people get
+  wrong is the rollback." Three closed frames (a forward demonstrative, a
+  noun slot, a scarcity subject and a verb of telling); the bare-subject
+  form must reach a copula or colon, and "that's what nobody understands"
+  points backward and is left alone.
+- `punch-sentence` (cadence, info, medium confidence): the verbless beat of
+  one to three words wedged between two long sentences in the middle of a
+  paragraph, "Not anymore." and "Simple.", which `mic-drop-closer` and
+  `bare-auxiliary-closer` only see at a paragraph's end. Two closed shapes:
+  a negator with up to two words after it, or one capitalised word of five
+  letters or more. Titles, initials and case citations before the stop are
+  guarded, and short clauses with a subject ("He agrees.") are not matched.
 
 ## [0.8.0] - 2026-09-15
 

data/README.md

@@ -4,6 +4,8 @@ A dependency-free CLI that scans prose for the tells of AI-generated **slop** an
 
 The primary reader is an agent (Claude Code and friends) that runs sloplint, reads the JSON, and rewrites what it flags. Humans are the secondary reader, and everything is built to keep the false-positive rate low enough that a flag is worth trusting.
 
+For the tells a regex cannot see, there is a second gem, [sloplint-judge](#sloplint-judge), whose rules are questions put to a model and whose notes come back in the same JSON. It is optional, it needs an API key, and it is the only part of sloplint that sends your text anywhere.
+
 ## What it catches, and what it doesn't
 
 A pattern earns a place in the catalog only if it shows up constantly in AI writing and rarely in careful human writing. Passive voice, weak adverbs, wordiness, clichés a person reaches for too: those belong in `proselint` or `write-good`, not here. sloplint is not a general prose linter and never tries to be. It hunts the specific fingerprints of a language model, so an agent can act on a flag instead of second-guessing it.
@@ -118,9 +120,13 @@ Flags:    No fluff, no filler, no jargon.
 Does not: No parking on Sundays.
 ```
 
+### `--judge`
+
+`sloplint check --judge` adds the rules of [sloplint-judge](#sloplint-judge) to the run, questions put to a model rather than regexes, and merges the notes into the same array in document order. It needs the sloplint-judge gem and an API key; the section below covers both.
+
 ## The note
 
-One match is one note. JSON output is an array of these, or an object keyed by path when more than one file is scanned. The schema is the contract:
+One match is one note. JSON output is an array of these, or an object keyed by path when more than one file is scanned. Under `--judge` that array or object sits under a `notes` key next to a `judge` key with the backend name, request count and token counts (see [sloplint-judge](#sloplint-judge)). The schema is the contract:
 
 ```json
 {
@@ -144,23 +150,102 @@ One match is one note. JSON output is an array of these, or an object keyed by p
 
 ## Exit codes
 
-Three codes carry the contract. A crash exits nonzero on its own.
+Four codes carry the contract. A crash exits nonzero on its own.
 
 | code | meaning |
 |------|---------|
 | 0    | ran, no notes |
 | 1    | ran, notes found |
 | 2    | bad arguments or usage error |
+| 3    | `--judge` only: the model could not be reached, no notes written |
 
 An unknown id or category in `--select`/`--ignore` is a usage error (exit 2, naming the id) rather than a silent no-op, so a typo can't masquerade as a clean scan. Input that is empty or only whitespace is exit 2 for the same reason: a pipe that delivered nothing must not read as a clean draft. Only when every source is empty — one empty file among several named ones is taken as deliberate.
 
+## sloplint-judge
+
+A second gem in this repository, for the tells a regex cannot see. Its rules are questions put to a System One model (Jev, from TypeSafe) about one paragraph or one sentence at a time: does this paragraph end on a summary, a moral or a hope, does this sentence tell the stated reader anything they did not know, does it name anything a reader could check. The answers come back as sloplint notes, same fields, same JSON, same exit codes, so anything that already reads sloplint's output reads the judge's without change.
+
+One thing is different from the rest of sloplint: the judge sends your text to an API. sloplint on its own never leaves the machine. Every paragraph the judge examines goes to `api.typesafe.ai` over HTTPS, and nothing goes anywhere until you set a key, so the plain `sloplint check` stays offline whether or not the judge is installed.
+
+### Install
+
+```bash
+gem install sloplint sloplint-judge
+sloplint-judge key set        # stores your TypeSafe API key in the OS keychain; it prompts for it
+```
+
+`key set` hands your terminal to the keychain tool (`security` on macOS, `secret-tool` from libsecret on Linux), which asks for the key with echo off, so the key is never on a command line, in shell history or in a dotfile. Setting `TYPESAFE_API_KEY` in the environment works too and takes precedence. One thing the keychain does not do: it keeps the key out of the agent's environment, not out of your account, since any process running as you can read the item back. `sloplint-judge status` says whether a key was found and where, without printing it, and `sloplint-judge key unset` removes the item.
+
+Requires Ruby 3.3+ and sloplint 0.9 or later. The judge is not a plugin of its own: the Claude Code plugin at the root of this repository already carries it, and the `/sloplint:check` skill asks before it runs the judge. A key in the environment makes the judge possible; it does not make it run. The skill puts the question once per conversation, says what leaves the machine and what it costs, and stays offline unless the answer is yes or the request already asked for the judge.
+
+### Run
+
+The one command to know, and the one an agent should use:
+
+```bash
+sloplint check --judge --markdown -o json draft.md
+```
+
+That runs both catalogs and merges the notes in document order. Because the judge spent money, the JSON says how much: the notes sit under `notes` and a `judge` object carries the backend, the number of requests, the token counts the backend reported and the cost in dollars. The same figures go to stderr in one line for the human formats.
+
+```json
+{
+  "notes": [ ... ],
+  "judge": { "backend": "jev-latest", "requests": 9, "input_tokens": 14200, "output_tokens": 610, "cost_usd": 0.000596 }
+}
+```
+
+Without the sloplint-judge gem it exits 2 and says to install it. Without a key it exits 2 and says which variable to set. If the model cannot be reached, or answers in a shape the judge does not understand, it exits 3 and writes no notes at all, the regex ones included, so a partial run can never pass as a clean one.
+
+The gem also puts a `sloplint-judge` executable on your path for the judge on its own:
+
+```
+sloplint-judge [-o full|json] [--register TEXT] [--backend NAME] [command] [args]
+
+check         scan paths (or stdin) with the judge's rules only [default]
+compare A B   which of two passages a plain-prose editor keeps (--drift for rewrites)
+rules         list the judge's rule catalog (add --json)
+explain ID    print one rule's question, levels, rationale and fixtures
+status        say whether a run could happen here, and where the key is, without reading it
+key set       store the backend's key in the OS keychain (the keychain tool prompts for it)
+key unset     remove it from the OS keychain
+version       print the sloplint-judge version
+```
+
+`check` takes `--markdown`, `--select`, `--ignore` and `--strict` with the same meanings as sloplint's. `--strict` runs the three rules that are off by default, runs the sentence rules on every sentence, rather than only in the paragraphs a paragraph rule flagged or skipped as too short, and keeps the notes the model was not confident about. `--register TEXT` says who the reader is; the default is an engineer on the team reading a design document, and every question is asked on that reader's behalf, so a rule such as `no-news` flags a sentence that reader already knows rather than one anybody would.
+
+### The rules
+
+Fourteen rules in two categories. `sloplint-judge rules` lists them and `sloplint-judge explain ID` prints the question the model is asked, the answer that flags, and the fixtures. The bar is a little different from the regex catalog's: a judge rule ships when a reader shown the flagged unit agrees it should go, whoever wrote it, and how sharply it separates model prose from human prose sets its severity. So `throat-clearing` is `info`, not gone: human abstracts open by announcing the paper, and it is dead weight either way.
+
+- **paragraph** (6): `particulars`, a paragraph that names nothing a reader could check; `wrap-up`, a paragraph that ends on a summary, a moral or a hope; `throat-clearing`, a paragraph that opens by announcing its topic; `self-narration`, a paragraph that signposts the document instead of saying something; `promotional`, a paragraph that praises its subject and measures nothing; `same-weight`, a paragraph that states its guesses and opinions as flatly as its measurements. `same-weight` is off by default; name it in `--select` or pass `--strict`.
+- **sentence** (8): `stock-figure`, a stock figure of speech; `no-news`, a sentence that explains what the stated reader already knows; `names-nothing`, a sentence with no specific noun in it; `ends-on-verdict`, a sentence that ends by grading the fact it just stated; `trailing-gloss`, a sentence that ends on an -ing clause drawing its own moral; `unnamed-authority`, a claim handed to experts, studies or many; `stated-stakes`, a sentence that says something matters and not why; `matched-shape`, a pair or triple built to a rhythm rather than to the content. `stated-stakes` and `matched-shape` are off by default; name them in `--select` or pass `--strict`.
+
+Each note's `confidence` is the lower of the rule's own ceiling and how sure the model was of that answer. A note the model was unsure about is dropped unless you pass `--strict`, the same way sloplint drops its low-confidence rules.
+
+### Cost and configuration
+
+One request per paragraph carries the paragraph questions, and one request per examined sentence carries the sentence questions, about eight in parallel. A 2,000-word document runs in a few seconds. Every run reports requests, tokens and cost, in the JSON under `judge` and on stderr. Jev returns token counts and no price, so the dollar figure is computed from TypeSafe's public price: $42 per billion input tokens, and output tokens are free. At that rate a 2,000-word document costs well under a cent.
+
+Configuration is from the environment, plus the OS keychain for the key:
+
+| variable | default | meaning |
+|---|---|---|
+| `TYPESAFE_API_KEY` | none, required | bearer key sent with every request; from the environment, else the keychain item `key set` wrote |
+| `SYSTEMONE_MODEL` | `jev-latest` | model name |
+| `SYSTEMONE_URL` | `https://api.typesafe.ai/v1/systemone` | endpoint; must be `https` on a `typesafe.ai` host |
+| `SLOPLINT_JUDGE_BACKEND` | `jev` | which adapter to use |
+| `SLOPLINT_JUDGE_CONCURRENCY` | `8` | parallel requests |
+
+The design, the calibration that decides which rules ship, and how to add a backend are in [docs/JUDGE.md](docs/JUDGE.md).
+
 ## The rule catalog
 
-80 rules across nine categories, each named for the rhetorical move the construct makes. `sloplint rules` prints them; `sloplint rules --json` gives an agent the enumerable form.
+82 rules across nine categories, each named for the rhetorical move the construct makes. `sloplint rules` prints them; `sloplint rules --json` gives an agent the enumerable form.
 
-- **self-rating** (15) the writer grades their own prose or claim: `clean-x`, `clean-count`, `cleanest-x`, `cleanly`, `honest-x`, `most-honest-x`, `honestly` (the honesty family, built the same way as the four `clean` rules), `worth-naming`, `worth-saying-plainly`, `earns-its-place`, `does-a-lot-of-work`, `exact-exactly`, `genuinely` (off by default), `the-punchline-is`, `announced-takeaway`.
+- **self-rating** (16) the writer grades their own prose or claim: `clean-x`, `clean-count`, `cleanest-x`, `cleanly`, `honest-x`, `most-honest-x`, `honestly` (the honesty family, built the same way as the four `clean` rules), `worth-naming`, `worth-saying-plainly`, `earns-its-place`, `does-a-lot-of-work`, `exact-exactly`, `genuinely` (off by default), `the-punchline-is`, `announced-takeaway`, `cataphoric-teaser` ("Here's what nobody tells you", "the part most people get wrong").
 - **closer** (12) closes by restating or announcing the point: `thats-the-whole`, `is-the-whole-x` (the same closer on any subject: "Consistency is the real test.", at `medium` confidence), `is-the-entire`, `the-entire-is`, `thats-how-x`, `thats-the-tension`, `right-up-until`, `and-nothing-else` (the trailing "…, and nothing else"), `nothing-else-frag`, `bare-equative` ("The lesson is the handoff.", at `medium` confidence), `trailing-restatement` (the "…, which means …" tail that says the sentence again, off by default), `and-what-it-should` (the elliptical tail: "…, and what it should.").
-- **cadence** (17) rhythm: repetition, parallelism, and the long-then-short kicker: `no-x-no-y`, `no-x-no-y-frag`, `did-not-x-did-not-y`, `one-x-one-y` ("one reviewer, one queue, one deadline"), `from-x-to-y-chain` ("from guessing to measuring, from hoping to knowing"), `same-determiner-chain` (any other repeated determiner, at `medium` confidence), `real-x-real-y`, `epistrophe` (off by default), `phrase-echo` (off by default), `is-is` (doubled copula), `the-x-is-the-x` ("the problem with A is the problem with B"), `rule-of-three` (off by default), `everyone-nobody` (the comma-spliced antithesis: "Everyone wants the dashboard, nobody maintains it."), `short-run` (three sentences of thirty characters or fewer in a row, at `medium` confidence), `mic-drop-closer` (the short quantifier-led sentence that ends a paragraph after a long one, at `medium` confidence), `bare-auxiliary-closer` (the same shape, but the closer's verb is elided down to a bare auxiliary: "The agent did.", at `medium` confidence), `np-fragment-and` (the verbless "A named owner and a quarterly review.", at `medium` confidence).
+- **cadence** (18) rhythm: repetition, parallelism, and the long-then-short kicker: `no-x-no-y`, `no-x-no-y-frag`, `did-not-x-did-not-y`, `one-x-one-y` ("one reviewer, one queue, one deadline"), `from-x-to-y-chain` ("from guessing to measuring, from hoping to knowing"), `same-determiner-chain` (any other repeated determiner, at `medium` confidence), `real-x-real-y`, `epistrophe` (off by default), `phrase-echo` (off by default), `is-is` (doubled copula), `the-x-is-the-x` ("the problem with A is the problem with B"), `rule-of-three` (off by default), `everyone-nobody` (the comma-spliced antithesis: "Everyone wants the dashboard, nobody maintains it."), `short-run` (three sentences of thirty characters or fewer in a row, at `medium` confidence), `mic-drop-closer` (the short quantifier-led sentence that ends a paragraph after a long one, at `medium` confidence), `bare-auxiliary-closer` (the same shape, but the closer's verb is elided down to a bare auxiliary: "The agent did.", at `medium` confidence), `np-fragment-and` (the verbless "A named owner and a quarterly review.", at `medium` confidence), `punch-sentence` (the verbless beat of three words or fewer between two long sentences, "Not anymore.", at `medium` confidence).
 - **puffery** (8) inflates the subject: `puffery-words` (vibrant, nestled, groundbreaking, in the heart of), `rich-tapestry`, `vital-role`, `stands-serves-as`, `underscores-highlights`, `impact-noun-vague` ("a significant impact", "make an impact"), `trailing-significance-participle` (the "…, showcasing its importance" clause), `abstract-lives-in` ("the value sits in the follow-up", at `medium` confidence).
 - **false-correction** (8) corrects a reading nobody offered: `not-just-x-but-y`, `not-x-but-y` (the bare corrective), `not-by-x-but-by-y` ("not by luck, but by design"), `isnt-x-its-y` (the same corrective split across two clauses: "It isn't the tool. It's the habit."), `question-isnt` (the corrective frame in interrogative dress), `less-about-more-about`, `actually-not-x`, `dont-verb-it`.
 - **false-concession** (7) performs balance or candour and gives nothing up: `two-things-true`, `none-of-this-is-to-say`, `is-real-and-not`, `not-nothing`, `vague-attribution` ("some critics argue", "it is widely regarded"), `if-im-being-honest` (the candor preamble, from slopwash.com's "false intimacy"), `and-thats-fine`.

data/docs/SPEC.md

@@ -47,6 +47,9 @@ so the source never needs to enter the repository.
 - **A reference corpus of human prose must be public domain.** Copyrighted text
   can't be redistributed, so a corpus built from it can't live in the repo, and
   neither can the false-positive check that depends on it.
+- **The probe corpus is fetched, not committed.** `script/probe-raid fetch` pulls
+  RAID (Dugan et al. 2024, MIT) into `.corpus/`, which is ignored. The script
+  and the numbers it prints may be quoted in a commit message; the texts may not.
 
 This repository is MIT-licensed, so anything committed is redistributable by
 anyone. Writing the fixtures ourselves also means nobody's prose gets held up as
@@ -93,7 +96,8 @@ dependencies at runtime.
 
 Rationale: rules are regexes; the whole thing is a scanner plus an output
 formatter. A dependency-free `gem install sloplint` is the robust, boring
-choice. The name is free on RubyGems (taken on PyPI, so this also sidesteps the
+choice. The one exception is `check --judge`, which loads the separate
+sloplint-judge gem and calls a model over the network; see `docs/JUDGE.md`. The name is free on RubyGems (taken on PyPI, so this also sidesteps the
 collision). Ships a `sloplint` executable from `exe/` (claude.ai rejects a
 plugin with a top-level `bin/`, and sloplint ships as a Claude Code plugin
 too).
@@ -121,7 +125,7 @@ Rakefile                   # rake spec
 ```
 
 RSpec is a **development** dependency (in the gemspec's `add_development_
-dependency`), so the runtime stays dependency-free.
+dependency`), so the runtime stays dependency-free unless `--judge` is passed.
 
 ## CLI surface
 
@@ -157,13 +161,14 @@ Deliberately left out of v1 (add when a real need shows up, not before):
 
 ## Exit codes
 
-Three codes carry the contract. A crash just exits nonzero on its own.
+Four codes carry the contract. A crash just exits nonzero on its own.
 
 | code | meaning |
 |------|---------|
 | 0    | ran, **no notes** |
 | 1    | ran, **notes found** |
 | 2    | bad arguments / usage error |
+| 3    | `--judge` only: the model backend could not be reached, no notes written |
 
 Empty or whitespace-only input is exit 2, like a mistyped rule id: a scan of
 nothing must not report as a clean scan. The text is tested before
@@ -173,7 +178,9 @@ block still exits 0. Only when every source is empty.
 ## Note (the diagnostic object)
 
 One match = one Note. JSON output is an array of these (or an object keyed by
-path when multiple files are scanned).
+path when multiple files are scanned). Under `--judge` the array or object sits
+under `"notes"` beside a `"judge"` object with the backend name, request count
+and token counts; see `docs/JUDGE.md` "Note".
 
 ```json
 {
@@ -246,7 +253,9 @@ RULES = [
 ```
 
 Adding a rule = appending one entry + one bad and one ok fixture. That's the
-whole extension story. No new files, no plugin system (YAGNI).
+whole extension story. The only thing that plugs in is sloplint-judge, and it
+plugs in by name: `check --judge` does a lazy `require "sloplint/judge"` and
+exits 2 with an install hint when it is missing. See `docs/JUDGE.md`.
 
 ### Why Ruby literals, not JSON/YAML
 
@@ -313,6 +322,7 @@ The writer grades their own prose or claim.
 - `genuinely` — any "genuinely"; `low` confidence, off by default; no narrowing holds
 - `the-punchline-is` — "the punchline is/:/?", "the honest answer/version is"; "short version" left out; ordinary writing
 - `announced-takeaway` — colon-led label: "The pattern/lesson/takeaway…:"; sentence-initial
+- `cataphoric-teaser` — the forward-pointing tease, sentence-initial, in three closed frames: an optional forward demonstrative ("here's", "here is", "this is", with one lead-in word allowed: "So here's"), a noun slot (what / the part / the thing / the bit / the secret), a scarcity subject (nobody, no one, most X, few people, hardly anyone, almost nobody, people), up to two adverbs, and a verb of telling, getting wrong, talking about, admitting or noticing: "Here's what nobody tells you about hiring.", "The part most people get wrong is the rollback." Without the demonstrative the sentence must reach a copula or a colon ("What nobody tells you is…"), since "What nobody tells you gets forgotten." is a report, and "they" is allowed only after a demonstrative, since a bare "What they don't realize is" refers to the people in the story. "That's what nobody understands" points backward and is left alone.
 
 ### closer
 
@@ -351,7 +361,7 @@ Rhythm: repetition, parallelism, and the long-then-short kicker.
 - `short-run` — three consecutive sentences of thirty characters or fewer, each letter-led and closing on a full stop, no quotation marks or digits, no lone-letter labels (either case, though a possessive is not one) or abbreviations, starting at a real sentence boundary (never on a wrap continuation), crossing a hard wrap but not a paragraph break; `medium` confidence. A list marker may open a run but never sit inside one, so consecutive bullets are a list — the marker set covers glyphs, the literal "o" plain-text documents use as a bullet, and numbered and lettered items. Two whole-run exclusions keep document furniture out, each a property of the run rather than of any sentence in it: three single-word sentences in a row is a citation line ("Natl. Inst. Stand. Technol."), and three lowercase-led sentences in a row is transcribed speech ("we all get gas. we go to divert to Albany."). One single-word sentence is the archetypal kicker and stays, and a run that reaches a capital anywhere is prose, so identifier-initial writing ("npm was slow. git blame helped. We moved on.") is untouched. One is a question; a draft that repeats it is the tell.
 - `mic-drop-closer` — a sentence of 60+ characters, then a paragraph-final closer of two to eight words opening on a **quantifier** (Nothing, Most, None, Everything, Everyone, Nobody, Then, Neither, Both): "Nothing here needs a new login."; `medium` confidence. The bare demonstratives (That, This, It) were in the list and are out: procedural writing ends a step with one as a matter of course ("This completes the roughing operations."). A blank line or the end of the text must follow the closer; both sentences may be hard-wrapped; whitespace runs in the long sentence are capped so blanked Markdown cannot make it, and the long-sentence prefix is an atomic group so an unpunctuated stretch cannot send it into catastrophic backtracking. The note points at the closer. One means nothing; a draft where it repeats is the tell.
 - `bare-auxiliary-closer` — the same long-sentence-then-short-closer shape as `mic-drop-closer`, but the tell sits in the verb rather than the subject: the closer's verb phrase is elided down to a bare auxiliary with no object, "The agent did."; `medium` confidence. No subject list is needed — a one-to-three word subject runs straight into a bare `did/does/do/was/were/is/are/had/has/can/could/would/will/should/might/must` (contracted forms included) and a period, and the closer must be the last thing in the paragraph, same as `mic-drop-closer`, so a closing quotation mark after the period excludes quoted dialogue the same way `short-run` excludes it. A negative lookahead drops a closer that still holds "what", "that", "which", "who", "why" or "how", since those introduce a subordinate clause supplying its own complement rather than an elided one ("Nobody knew who did." asks who did it). Reuses `mic-drop-closer`'s long-sentence prefix rather than a second copy of it. One means nothing; a draft where it repeats is the tell.
-- `np-fragment-and` — a whole sentence made of two noun phrases and an "and", opening on A/An/One at a sentence start or after a list marker ("A named owner and a quarterly review."). One to three words a side, no auxiliary or modal anywhere (contractions included); a lexical verb is invisible, so "A car and a truck collided." flags, which is why it ships at `medium` confidence.
+- `punch-sentence` — the same long-then-short shape in the middle of a paragraph, where the closer rules refuse it: after the shared sixty-character prefix, a verbless beat of one to three words closing on a full stop, then one or two spaces and a sentence of forty or more characters on the same paragraph ("…three nights running that week. Not anymore. The job now checks…"); `info`, `medium` confidence. The beat is one of two closed shapes: a negator (Not, No, Never, Nothing, None) followed by up to two lowercase words, or a single capitalised word of five letters or more ("Simple."). The stop before the beat may not close a capitalised word of one to four letters or a lone lowercase letter, so a title, an initial or a case citation ("Mrs. Cadaver.", "John F. Kennedy.", "Swift v. Tyson.") never yields a one-word sentence. Short clauses with a subject ("He agrees.", "Dawes refuses.") are how plot summaries and news briefs move and are not matched; a one-word imperative in procedural prose ("Drain.") is, at about one per 25,000 words of recipes. A run of short sentences is `short-run`'s, and a paragraph-final beat is `mic-drop-closer`'s or `bare-auxiliary-closer`'s.- `np-fragment-and` — a whole sentence made of two noun phrases and an "and", opening on A/An/One at a sentence start or after a list marker ("A named owner and a quarterly review."). One to three words a side, no auxiliary or modal anywhere (contractions included); a lexical verb is invisible, so "A car and a truck collided." flags, which is why it ships at `medium` confidence.
 
 ### puffery
 
@@ -472,6 +482,21 @@ RSpec (dev dependency), run via `rake spec`.
 - LSP server mode, editor plugins, autofix/rewrite. sloplint *flags*; the agent
   rewrites. Autofix is a separate tool if ever.
 - Non-English. Languages other than English are a v2 conversation.
+- Grammar-frequency tells from the corpus-linguistics literature. Reinhart et
+  al. (PNAS 2025) measure GPT-4o at 2.1 times the human rate for
+  nominalizations and 2.6 times for "that" relative clauses on a subject noun
+  ("a framework that enables real-time analysis"). Both shifts are real in RAID
+  and in Claude Sonnet 5 text generated from RAID's prompts, and neither is a
+  shape a regex can flag. A single that-relative is ordinary English ("a move
+  that is likely to put a dent in its accounts", human BBC news) and human
+  news carries one every 650 words; two in one sentence separate no better,
+  and flagging either pushes a writer toward the nominalization instead.
+  Nominalization is a density, not a sentence shape: five or more suffix nouns
+  in one sentence fires on human abstracts at the 2023 model rate, and 50k
+  words of README prose gave 22 hits, every one a bullet list or feature
+  table. Both belong to a judge that reads a paragraph, not to this catalog.
+  Sentence-initial clausal subjects ("That the cache was stale is not in
+  dispute.") were also tried and are near zero on both sides everywhere.
 - ML/embedding-based detection. This is a regex linter on purpose — fast,
   explainable, zero-dependency. Statistical detection is a different product.
 - Scraped corpora. Platform terms prohibit automated collection, and finding a

data/exe/sloplint

@@ -9,5 +9,6 @@ if (RUBY_VERSION.split(".").map(&:to_i).first(2) <=> [3, 3]) < 0
         "macOS ships Ruby 2.6 at /usr/bin/ruby. Install a current one with `brew install ruby`."
 end
 
-require_relative "../lib/sloplint/cli"
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "sloplint/cli"
 exit Sloplint::CLI.run(ARGV)