sloplint 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2530123f6520e2abc31a875cc53787cc4492669c2bc7919c5ab19fa3541601a1
+  data.tar.gz: 61b2542547165a0f8e632c2ce89a679386edc8bbde24a71f92f69091603bf6e8
+SHA512:
+  metadata.gz: 607445e1bdb23eacb5d460b01e72d1ebb140136974c7988ebdd023c7db4cccfd4540e1e4ddb68031938fe936d73d173c52d0818d3573ea045cbbc0b7db46696c
+  data.tar.gz: 55faafabedfbde617ea5cfed7e3ac89a3e7e82f24521346b21b6ddc3fe0a775e41dd1bfeacc5860326fcfaa7ab006316a9b9ab6b09fbe956678cf6de172a71c5

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [0.1.0] - Unreleased
+
+First public release.
+
+- 24-rule catalog across four categories: rhetorical-tic, puffery, structure,
+  hedging. See `sloplint rules` or `README.md` for the full list.
+- `check`, `rules`, `explain`, `version` commands; JSON and human-readable
+  output; `--select`/`--ignore` by rule id or category; `--markdown` to skip
+  fenced code, inline code, and URLs before scanning.
+- Exit codes: `0` clean, `1` notes found, `2` bad arguments or invalid input
+  (including invalid UTF-8 and unknown `--select`/`--ignore` ids).
+- Zero runtime dependencies; requires Ruby >= 3.3.
+- `-v`/`--version` print the version and exit 0. optparse auto-registers its
+  own `--version` switch on any parser that doesn't define one, and that
+  default printed "version unknown" to the real stdout and hard-exited,
+  bypassing the `out:`/return-a-code contract every other path honors --
+  caught by hand-testing the freshly built gem before this release shipped.
+- Rationale text (`sloplint explain`) across six rules no longer narrates the
+  rule's own implementation -- pattern scoping, anchoring, tuning history,
+  corpus-driven thresholds. It states why the construct reads as AI writing
+  and nothing else.
+
+Rules narrowed against a corpus of real human prose (the Federalist Papers,
+Moby-Dick, Walden) before release:
+
+- `not-just-x-but-y` anchored on a preceding copula so it no longer flags
+  ordinary correlative conjunctions ("not only... but...").
+- `puffery-words` dropped the bare adjective "profound" and narrowed "in the
+  heart of" to require a place object, both unguarded false-positive sources.
+- `em-dash-overuse`, `thats-how-x`, and `announced-takeaway` scoped to real
+  paragraphs (blank-line boundaries) instead of source lines, so hit counts
+  no longer swing on Markdown line-wrapping.
+- `clause-triad-then` removed: went 0-for-40 on its own description against
+  the human corpus, and no reliable narrowing was found.
+- `no-x-no-y`'s rationale corrected to match what the pattern actually does
+  (fires at two items; the frequency gap between human and model prose is
+  the justification, not an item-count claim the pattern didn't enforce).

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Benjamin Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,179 @@
+# sloplint
+
+A dependency-free CLI that scans prose for the tells of AI-generated **slop** and reports them as linting notes. Think `proselint`, but aimed narrowly at the rhetorical tics and puffery that mark LLM writing: the "no X, no Y" chains, the "rich tapestry of," the "some critics argue" hedging. It writes JSON an agent can act on and human text a person can read.
+
+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.
+
+## 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.
+
+## Installation
+
+Requires **Ruby 3.3+** and nothing else. The runtime is standard library only (`optparse`, `json`, native regex).
+
+```bash
+gem install sloplint
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/benjaminjackson/sloplint
+cd sloplint
+gem build sloplint.gemspec
+gem install ./sloplint-*.gem
+```
+
+Either way, that puts a `sloplint` executable on your path.
+
+## Quick start
+
+The recipe sloplint is built around, and the one an agent should use:
+
+```bash
+cat draft.md | sloplint check --markdown -o json -
+```
+
+`--markdown` blanks out code and URLs first, `-o json` emits the machine-readable form, and `-` reads stdin. Exit 0 means clean, 1 means notes found, anything higher is an error. A bare `sloplint` with piped stdin is the same as `sloplint check -`.
+
+The human-readable form drops `-o json`:
+
+```
+$ echo "A rich tapestry of vibrant cultures. That's exactly the point." | sloplint check -
+-:1:3: warning rich-tapestry  "rich tapestry"/"tapestry of" is a signature AI cliché.
+    excerpt: rich tapestry
+    fix: Cut the metaphor; name the actual things.
+
+-:1:20: warning puffery-words  Wikipedia-style puffery word/phrase — a common AI tell.
+    excerpt: vibrant
+    fix: Replace with a concrete, specific detail or cut it.
+
+-:1:38: warning exactly-the  "exactly the point/kind/problem/…" is an overused LLM emphasis tic.
+    excerpt: That's exactly the point
+    fix: Drop 'exactly the'; state the point without the intensifier.
+```
+
+## Commands
+
+```
+sloplint [-o full|json] <command> [args]
+
+check        scan paths (or stdin) for AI-slop tells and report notes [default]
+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
+```
+
+`check` takes files as arguments, or `-` (or nothing) to read stdin, and these options:
+
+- `--markdown` skips fenced code, inline code, and URLs before scanning. Off by default so it never silently eats prose.
+- `--select IDS` runs only these rules. Accepts comma-separated rule ids or category names.
+- `--ignore IDS` skips these rules. Same id-or-category form.
+
+`explain` is the command an agent calls to decide whether a flag is worth acting on:
+
+```
+$ sloplint explain no-x-no-y
+no-x-no-y  (rhetorical-tic, warning)
+
+"No X, no Y" chain (%{count} items) reads as AI cadence.
+
+Why: LLMs love asyndetic negation triplets. A careful writer rarely stacks three.
+Fix: Cut the chain or make it one plain sentence.
+
+Flags:    No fluff, no filler, no jargon.
+Does not: No parking on Sundays.
+```
+
+## 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:
+
+```json
+{
+  "path": "draft.md",
+  "line": 12,
+  "column": 5,
+  "severity": "warning",
+  "rule": "no-x-no-y",
+  "category": "rhetorical-tic",
+  "message": "\"No X, no Y\" chain (3 items) reads as AI cadence.",
+  "excerpt": "No fluff, no filler, no jargon",
+  "count": 3,
+  "suggestion": "Cut the chain or make it one plain sentence."
+}
+```
+
+`line` and `column` are 1-indexed and point at the start of the match. `count` appears only when the rule tallies items (a "no X, no Y" chain, a "did not, did not" chain). `suggestion` is a short fix hint.
+
+## Exit codes
+
+Three 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 |
+
+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.
+
+## The rule catalog
+
+24 rules across four categories. `sloplint rules` prints them; `sloplint rules --json` gives an agent the enumerable form.
+
+- **rhetorical-tic** (15) the cadence patterns: `no-x-no-y`, `thats-the-whole`, `thats-how-x`, `announced-takeaway`, `exactly-the`, `you-already-know`, `sit-with-that`, `thats-not-nothing`, and more.
+- **puffery** (5) Wikipedia's "signs of AI writing": `puffery-words` (vibrant, nestled, groundbreaking, in the heart of), `rich-tapestry`, `vital-role`, `stands-serves-as`, `underscores-highlights`.
+- **structure** (3) `not-just-x-but-y`, `em-dash-overuse` (three or more em dashes in a paragraph), and `rule-of-three`.
+- **hedging** (1) `vague-attribution`: "some critics argue," "it is widely regarded."
+
+Severity is `warning` for strong tells, `info` for weak or contextual ones. No rule currently ships at `error`; the tier is reserved for a pattern with essentially zero false-positive risk, and none has earned that yet.
+
+One rule ships **off by default**: `rule-of-three` flags three parallel comma items closing a sentence, which humans do all the time, so it false-positives. It runs only when you name it: `sloplint check --select rule-of-three -`.
+
+### Markdown handling
+
+`--markdown` replaces fenced code, inline code, and URLs with same-length whitespace before scanning, so line and column stay correct. Without it, sloplint treats the whole file as prose and will flag text inside your code fences. Pass `--markdown` whenever the input is Markdown.
+
+## Adding a rule
+
+Rules are data, not code. Each is a `Data.define` object in `lib/sloplint/rules.rb` with a regex, a message, a suggestion, and one bad and one ok fixture:
+
+```ruby
+Rule.new(
+  id:           "no-x-no-y",
+  category:     "rhetorical-tic",
+  severity:     "warning",
+  pattern:      /\bno\s+[\w'-]+,\s+no\s+[\w'-]+(?:,?\s+(?:and\s+)?no\s+[\w'-]+)*/i,
+  message:      '"No X, no Y" chain (%{count} items) reads as AI cadence.',
+  suggestion:   "Cut the chain or make it one plain sentence.",
+  count_group:  /\bno\b/i,                     # optional: a regex tallied over the match
+  skip:         [/real estate/i],              # optional: drop the note if these match
+  examples_bad: ["No fluff, no filler, no jargon."],
+  examples_ok:  ["No parking on Sundays."],
+  rationale:    "Asyndetic negation chains are a signature model cadence, rare in human prose."
+)
+```
+
+Adding a rule is one entry plus its fixtures. `rules_spec.rb` iterates the catalog and asserts every `examples_bad` produces at least one note and every `examples_ok` produces none, so a rule without fixtures, or one whose regex is too greedy, fails the suite.
+
+## Development
+
+No `Gemfile` -- install `rspec` and `rake` yourself (`gem install rspec rake`), then:
+
+```bash
+rake spec        # or: rspec
+```
+
+`rules_spec.rb` checks every rule against its fixtures. `cli_spec.rb` covers exit codes, stdin, JSON schema, `--select` and `--ignore`, and that `--markdown` skips code. A slop fixture in `spec/fixtures/` doubles as an integration check.
+
+See [`docs/SPEC.md`](docs/SPEC.md) for the full design, including why this is a fresh tool rather than a proselint extension.
+
+## Author
+
+Benjamin Jackson ([@benjaminjackson](https://github.com/benjaminjackson))
+
+## License
+
+MIT

data/bin/sloplint

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/sloplint/cli"
+exit Sloplint::CLI.run(ARGV)

data/docs/SPEC.md

@@ -0,0 +1,308 @@
+# sloplint — spec
+
+A CLI that scans prose for the tells of AI-generated "slop" and reports them as
+linting notes. Think `proselint`, but narrowly aimed at the rhetorical tics and
+puffery that mark LLM writing.
+
+Primary consumer is an **agent** (Claude Code and friends) that runs sloplint,
+reads the JSON, and rewrites the flagged text. Humans are the secondary
+consumer. Every design choice below favors machine-readability and a help text
+an agent can act on without guessing.
+
+## The one test for every rule
+
+A pattern earns a place in the catalog only if it **shows up constantly in AI
+writing and rarely in careful human writing.** That's the whole filter.
+
+If a thoughtful human writer does it all the time too — passive voice, weak
+adverbs, comma splices, wordiness — it belongs 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: the cadences, the puffery, the
+reflexive both-sidesing that a person almost never produces but an LLM produces
+by the paragraph.
+
+Two payoffs from holding this line: a low false-positive rate (so an agent can
+trust a flag instead of second-guessing it), and no overlap with tools that
+already do general prose well. When a rule is borderline, ask the test again and
+cut it if the answer is soft.
+
+## Prior art we're borrowing from
+
+- **proselint** — subcommand CLI (`check`, `version`, `dump-config`), `--output-format full|json|compact`, LSP-style diagnostics (line/column/severity/code/message), config file, clean exit codes. We copy this shape.
+- **vale** — markup-aware (skips code blocks, knows Markdown). We do a lighter version: optional `--markdown` to skip fenced code and inline code.
+- **write-good / alex** — naive regex rules, one module per rule. We keep rules as data, not code, so they're trivial to add.
+
+## Why build fresh instead of extending proselint
+
+proselint is a general prose linter. Extend it and our AI-tell rules land next
+to its checks for passive voice, clichés, and date formatting — a user who just
+wants "does this read like a bot?" can't get that without running everything and
+filtering. The narrow focus is the whole product, and folding into proselint
+dilutes it on day one.
+
+The practical cost is worse. Upstreaming our rules puts our release schedule at
+the mercy of their review and their view of scope. Forking means maintaining a
+whole prose linter to ship what is really a few hundred lines of regex. Both are
+bad trades for the size of this thing.
+
+And the part we actually care about — the agent-facing design (`explain` and
+`rules` commands, the JSON schema as a fixed contract, the copy-paste recipe in
+`--help`) — isn't in proselint. We'd be bolting it onto someone else's CLI (and
+proselint is Python; we're Ruby). Writing our own shell is about a day, and
+proselint already showed us
+what that shell should look like. The hard part was never the CLI; it's the
+rules and holding down false positives, and proselint helps with neither.
+
+One additive move, not either-or: once the rules exist as data, we can also
+package them as a proselint plugin, so people already using proselint get our
+checks without us inheriting their codebase. Cheap, because the rules are
+already pure data.
+
+## Language & shape
+
+Ruby 3.3+, **standard library only** (`optparse`, `json`, native regex). No gem
+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
+collision). Ships a `sloplint` executable via the gemspec's `bin`.
+
+Package layout (standard gem):
+
+```
+sloplint/
+  bin/sloplint             # thin shim: require "sloplint/cli"; exit Sloplint::CLI.run(ARGV)
+  lib/sloplint.rb          # requires the pieces below
+  lib/sloplint/version.rb
+  lib/sloplint/cli.rb      # optparse, subcommands, exit codes
+  lib/sloplint/rules.rb    # RULES: array of Rule (Data) objects — the catalog
+  lib/sloplint/engine.rb   # Engine.scan(text, rules:, config:) -> [Note]
+  lib/sloplint/output.rb   # format_human / format_json / format_compact
+docs/
+  SPEC.md                  # this file
+spec/
+  rules_spec.rb            # each rule: >=1 positive, >=1 negative fixture
+  cli_spec.rb              # exit codes, stdin, output formats
+  spec_helper.rb
+sloplint.gemspec
+.rspec
+Rakefile                   # rake spec
+```
+
+RSpec is a **development** dependency (in the gemspec's `add_development_
+dependency`), so the runtime stays dependency-free.
+
+## CLI surface
+
+```
+sloplint [GLOBAL] <command> [ARGS]
+
+commands:
+  check       scan paths (or stdin) and report notes   [default command]
+  rules       list the rule catalog (human or --json)
+  explain ID  print one rule's description, examples, and rationale
+  version     print version
+
+global options:
+  -o, --output-format  full | json   (default: full)
+
+check options:
+  paths ...            files to scan; "-" or no paths reads stdin
+  --markdown           skip fenced/inline code spans
+  --select IDS         only run these rules (comma-separated ids or categories)
+  --ignore IDS         skip these rules
+```
+
+Bare `sloplint` with piped stdin behaves as `sloplint check -`. This is the
+common agent path: `cat draft.md | sloplint check --markdown -o json -`.
+
+Deliberately left out of v1 (add when a real need shows up, not before):
+`compact` output, `--min-severity`, `--max-notes`, color, `-q/--quiet`, and a
+`--demo` flag (the slop fixture lives in `spec/` instead).
+
+## Exit codes
+
+Three 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 |
+
+## 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).
+
+```json
+{
+  "path": "draft.md",
+  "line": 12,
+  "column": 5,
+  "severity": "warning",
+  "rule": "no-x-no-y",
+  "category": "rhetorical-tic",
+  "message": "\"No X, no Y\" chain (3 items) reads as AI cadence.",
+  "excerpt": "No fluff, no filler, no jargon.",
+  "count": 3,
+  "suggestion": "Cut the chain or make it one plain sentence."
+}
+```
+
+- `line`/`column` are 1-indexed, pointing at the start of the match.
+- `count` present when the rule counts items (the "badge" in the examples).
+- `suggestion` is a short fix hint; agents may use it, humans see it too.
+
+## Rule model
+
+A rule is data, not a function. `rules.rb` holds an array of `Rule` objects
+built with `Data.define` (immutable value objects, Ruby 3.2+):
+
+```ruby
+Rule = Data.define(
+  :id, :category, :severity, :pattern, :message, :suggestion,
+  :examples_bad, :examples_ok, :count_group, :skip
+) do
+  # sensible defaults for the optional fields
+  def initialize(count_group: nil, skip: [], **rest) = super
+end
+
+RULES = [
+  Rule.new(
+    id:          "no-x-no-y",
+    category:    "rhetorical-tic",
+    severity:    "warning",
+    pattern:     /.../i,                       # regex literal; add /m if multiline
+    message:     "...",                         # may reference %{count}
+    suggestion:  "...",
+    examples_bad: ["No fluff, no filler, no jargon."],
+    examples_ok:  ["No parking on Sundays."],   # must NOT match; asserted in tests
+    count_group:  nil,                          # optional: capture group to tally
+    skip:        [/real estate/i, /real time/i] # optional exclusions
+  ),
+  # ...
+]
+```
+
+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).
+
+### Why Ruby literals, not JSON/YAML
+
+The rules are data, but they live in a `.rb` array on purpose:
+
+- **YAML** ships with Ruby, but regex in YAML is a string that has to be
+  re-parsed and re-escaped — every `\b` doubled, no `/i` flags inline, and the
+  good/bad fixtures drift away from the pattern they test.
+- **JSON** is stdlib too but worse for regex: same escaping tax, no comments,
+  no multiline patterns. Both external formats also need a load-and-validate
+  layer that a Ruby array gets for free — a typo is a syntax error at require
+  time, not a silent miss.
+
+A Ruby array with real regex literals (`/.../i`) is the nicest place to *author*
+regex — flags, comments, and fixtures all in one spot. The usual reason to move
+rules to a file (non-devs editing them, third-party rule packs) isn't real yet.
+If it becomes real, the migration is cheap precisely because the rules are
+already pure data: write one loader, point it at a JSON dir, done.
+
+Categories (for `--select`/`--ignore` by group):
+
+- `rhetorical-tic` — the cadence patterns (the user's list below)
+- `puffery` — Wikipedia "words to watch" (boasts, vibrant, nestled, tapestry…)
+- `structure` — rule-of-three, "not just X but Y", em-dash overuse
+- `hedging` — vague attribution ("some critics argue", "it is widely regarded")
+
+Severities: `warning` for strong tells, `info` for weak/contextual ones. No
+rule ships at `error` yet -- reserved for a pattern with essentially zero
+false-positive risk, which none has demonstrated.
+
+## Rule catalog (v1)
+
+### rhetorical-tic (from the request)
+
+| id | catches | notes |
+|----|---------|-------|
+| `no-x-no-y` | 2+ "no …" items in a row | counts items |
+| `thats-the-whole` | "that/this is the whole point/game/thing…" | |
+| `did-not-x-did-not-y` | 2+ "did not …"/"didn't …" in a row | counts items |
+| `dont-verb-it` | "Don't call it X. Call it Y." (negated verb+it, same verb+it) | |
+| `sit-with-that` | "sit with that/this/it", "sit with the discomfort" | |
+| `you-already-know` | "you already know" (+ the answer / standalone) | |
+| `is-the-entire` | "X is the entire point/game/business model" | |
+| `the-entire-is` | "the entire point/game/… is" (flip of above) | |
+| `is-real-and-not` | "the X is real, and/not…", "is the real … and it" | skip "real estate/time" |
+| `the-punchline-is` | "the punchline is/:/?" | |
+| `worth-naming` | "worth naming", "it's worth naming that…", "Worth naming:" | skip "naming names" |
+| `thats-not-nothing` | "that/this/it/which is not nothing" | |
+
+### puffery (Wikipedia: Signs of AI writing)
+
+Single flat rule per word-cluster, matched as whole words:
+
+- `puffery-words` — boasts a, vibrant, rich (history/cultural/tapestry), nestled, in the heart of (gated to a place object), groundbreaking, renowned, diverse array, breathtaking, natural beauty, stands as a testament, indelible mark, deeply rooted.
+- `stands-serves-as` — "stands as / serves as", "is a testament/reminder to".
+- `vital-role` — "plays a (vital/crucial/pivotal/significant/key) role".
+- `underscores-highlights` — "underscores/highlights/emphasizes its (importance/significance)".
+- `rich-tapestry` — "rich tapestry", "tapestry of".
+
+### structure
+
+- `not-just-x-but-y` — "not just X, but (also) Y", "not only … but".
+- `rule-of-three` — three parallel comma items ending a sentence (heuristic; `info` severity, off by default via `--select` since it false-positives).
+- `em-dash-overuse` — >N em dashes per paragraph (default N=2); `info`.
+
+### hedging
+
+- `vague-attribution` — "some (critics/experts/observers) (argue/say/believe)", "it is widely (regarded/considered/seen)", "many would argue".
+
+## Markdown handling
+
+`--markdown` blanks out fenced code (```` ``` ````), inline code (`` ` ``), and
+URLs before scanning, replacing them with same-length whitespace so line/column
+stay correct. Off by default (plain-text mode) so it never silently eats prose.
+
+## Agent-first help text
+
+This is a first-class requirement, not an afterthought.
+
+- `sloplint --help` opens with a one-line what-it-does, then a **copy-pasteable
+  agent recipe** block:
+
+  ```
+  # Recommended for agents:
+  cat FILE | sloplint check --markdown -o json -
+  # exit 0 = clean, 1 = notes found, >1 = error
+  # each note: {path,line,column,severity,rule,message,excerpt,suggestion}
+  ```
+
+- Every option has a full-sentence help string (no telegraphic fragments).
+- `sloplint rules` prints the catalog: id, category, severity, one-line
+  description — and with `--json`, the machine version an agent can enumerate.
+- `sloplint explain no-x-no-y` prints the rule's message, rationale, a bad
+  example and an ok (non-matching) example. Agents call this to decide whether a
+  flag is worth acting on.
+- JSON output is stable and documented here; the schema is the contract.
+- `--help` epilog links to `sloplint explain` and `docs/spec.md`.
+
+## Testing
+
+RSpec (dev dependency), run via `rake spec`.
+
+- Every rule ships `examples_bad` (must produce ≥1 note) and `examples_ok`
+  (must produce 0). `rules_spec.rb` iterates the catalog and asserts both — a
+  new rule without fixtures fails CI.
+- `cli_spec.rb` covers: exit codes (0/1/2), stdin path, `-o json` parses and
+  matches the schema, `--select`/`--ignore`, `--markdown` skips code.
+- A built-in slop fixture doubles as an integration example (known note count).
+
+## Explicitly out of scope for v1
+
+- Config files (`.sloplintrc`). Add when someone needs per-project rule tuning;
+  `--select`/`--ignore` cover the common case first.
+- 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.
+- ML/embedding-based detection. This is a regex linter on purpose — fast,
+  explainable, zero-dependency. Statistical detection is a different product.