riff-lint 0.1.0__tar.gz

riff_lint-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Sync
+        run: uv sync
+      - name: Lint
+        run: uv run ruff check src tests scripts
+      - name: Test
+        # Live Jev tests skip automatically without TYPESAFE_API_KEY.
+        run: uv run pytest -q --cov

riff_lint-0.1.0/.github/workflows/pypi.yml

@@ -0,0 +1,51 @@
+name: PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  check-version:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check tag matches pyproject.toml version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(grep -m1 '^version' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "release tag $GITHUB_REF_NAME does not match pyproject.toml version $PKG_VERSION" >&2
+            exit 1
+          fi
+
+  build:
+    needs: check-version
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # trusted publishing (OIDC); no API token needed
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist

riff_lint-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.env
+dist/
+.DS_Store
+mutants/
+.mutmut-cache
+html/
+.coverage
+coverage.xml

riff_lint-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.9.6
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

riff_lint-0.1.0/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project aims to
+follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Changed
+- Raised the `JEV502` (vague-abstraction) threshold to 0.85. On a corpus of real professional
+  documents it was the most-fired rule and flagged concrete text, so it now triggers only on
+  strong cases; egregious vagueness still fires.
+
+### Added
+- PyPI publish workflow: a GitHub release (tag `vX.Y.Z`) builds and publishes to PyPI via Trusted Publishing.
+- Tuned rules from a full per-type dogfood: `JEV304` (promotional) skips ad-copy types where
+  selling is the point; `JEV207` (boilerplate) and `JEV502` (abstraction) skip terse genres
+  (notes, SMS, chat, script) and no longer flag conventional sign-offs or functional lines.
+  Cleared the false positives this surfaced on riff's own README (35 to 1).
+- Calibrated the documentation rules against riff's own README (dogfooding): `JEV601` and
+  `JEV602` are now opt-in (they over-fired on real docs), `JEV001` skips `documentation`, and
+  `samples/types/` now holds a neutral public example of every supported document type.
+- Type-specific rules mined from seminal style texts (JEV601-JEV670): task orientation and
+  undefined terms (docs), buried conclusion (report/memo), editorializing (news), feature-not-
+  benefit (marketing), on-the-nose dialogue (script), forced rhyme (poem), vague changelog entry
+  (release notes), and weak resume bullets. Each cites its source(s); the README maps sources by type.
+- Document-type classification: riff detects the kind of writing (email, memo, SMS, essay,
+  blog post, report, and ~20 more) with one Jev pass, and rules can gate on it via
+  `applies_to` / `skip_for`. New `JEV112` flags a greeting or sign-off outside an email or
+  letter. Force the type with `--type`, or turn classification off with `--no-classify`;
+  custom rules can gate on type too.
+- Test-quality pass: broader unit coverage (extraction for every format, reporter,
+  text metrics, rule-registry helpers, and offline `jev` helpers), a 90% coverage
+  floor enforced in CI, and a mutmut mutation-testing setup with docs.
+
+### Fixed
+- The summary no longer reports "All checks passed" when Jev requests failed; a
+  keyless-or-errored run with zero findings is now flagged as incomplete.
+
+### Added
+- Generic message-level rules: `JEV010` formulaic (template) structure, `JEV111`
+  canned low-pressure sign-off, `JEV207` interchangeable boilerplate, and `JEV208`
+  faux-personalization. These catch AI-shaped outreach that is clean sentence by
+  sentence.
+- Document-scope Jev rules: a rule can be asked once over the whole text (`scope =
+  "document"`), not just per paragraph.
+- Custom rules: define your own `[[custom_rules]]` in `riff.toml` (a Jev question or
+  a list of banned phrases) without touching the codebase. Firm- or domain-specific
+  checks live here; the built-in rules stay generic.
+- Initial release: a prose linter with ruff-style rule codes over Markdown, plain
+  text, HTML, Word (`.docx`), and PowerPoint (`.pptx`).
+- 48 rules: 42 semantic rules answered by TypeSafe's Jev model and 6 deterministic
+  code rules (glyphs, structure, and clarity metrics).
+- Rule sources: [tropes.fyi](https://tropes.fyi/tropes-md) AI-writing tells,
+  Williams' *Style: Lessons in Clarity and Grace*, and Strunk & White's
+  *The Elements of Style*.
+- Configuration via `riff.toml` or `[tool.riff]` with ruff-style
+  `select`/`ignore`/`extend-select`, per-rule Jev thresholds, and metric limits.
+- CLI: `--list-rules`, `--explain CODE`, `--no-jev`, `--format json`,
+  `--debug-jev`, and both `riff FILE` and `riff -f FILE` forms.

riff_lint-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,99 @@
+# Contributing to riff
+
+Thanks for your interest. riff is a prose linter: it flags AI-writing tells and
+clarity problems with ruff-style rule codes.
+
+## Setup
+
+riff uses [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/scale-venture-partners/riff
+cd riff
+uv sync
+uv run riff --help
+```
+
+The semantic rules call [TypeSafe's Jev](https://typesafe.ai) model. Set
+`TYPESAFE_API_KEY` in your environment to run them (create a key at
+<https://console.typesafe.ai/>). Without a key, use `--no-jev` to run the
+deterministic rules alone.
+
+## Checks
+
+```bash
+uv run ruff check src tests scripts   # lint
+uv run pytest --cov                    # tests + coverage (floor: 90%)
+```
+
+The static tests run offline. The live Jev tests skip automatically when
+`TYPESAFE_API_KEY` is unset, so a bare `pytest` is green without a key; set the
+key to exercise the model path. Coverage is enforced at 90% in CI; `jev.py`'s
+network calls are excluded from the floor since only the live tests reach them.
+
+### Mutation testing
+
+Coverage says a line ran; mutation testing says a test would *notice* if the line
+were wrong. We use [mutmut](https://mutmut.readthedocs.io/) on the deterministic
+modules to keep tests strict.
+
+```bash
+OBJC_DISABLE_INITIALIZE_FORK_SAFETY=YES uv run mutmut run   # macOS needs the flag
+uv run mutmut results                                        # list survivors
+uv run mutmut show <mutant-id>                               # see one mutant's diff
+```
+
+A survivor is a mutation no test caught. Prefer killing it with an exact
+assertion (a specific value, count, or position) over a loose one. Expected
+survivors: `jev.py` (network) and `cli.py` (I/O) are covered by unit and live
+tests instead, and some mutations of log/error strings are equivalent and safe to
+leave. mutmut is not run in CI (too slow); run it locally when changing the
+deterministic modules.
+
+## How rules work
+
+Each rule is registered in `src/riff/rules/` and has a stable code:
+
+- **Jev rules** (`jev_rules.py`) are one `Noul` question asked about a paragraph,
+  phrased so a high probability means the tell is present. This is where almost
+  every rule lives — pattern matching misses paraphrases and fires on look-alikes,
+  so anything that depends on meaning or context is a model question.
+- **Code rules** (`static_rules.py`) are only for what Jev cannot do: exact glyphs
+  it never sees (curly quotes, arrows), structural facts in markup, cross-document
+  comparison, and arithmetic metrics (sentence length, reading grade).
+
+### Adding a Jev rule
+
+Add a `jev_rule(...)` call with a unique code, a clear `question` (use a `not_for`
+field when it could be confused with a neighbouring rule), a `threshold`, and
+`default=False` if it is noisy or niche. Then:
+
+1. Probe it on a few positive and negative examples before committing, so it fires
+   on real violations and stays quiet on good prose.
+2. Add a case to the tests where practical.
+3. Regenerate the rule table: `uv run python scripts/gen_readme.py`.
+
+## Style
+
+- Line length 120, ruff-formatted (`select = ["E", "F", "I", "UP", "B"]`).
+- Comments state the constraint that makes the code correct, not change history.
+
+## Pull requests
+
+Keep changes focused. Run the checks above and regenerate the README rule table if
+you touched the catalog. Describe what the rule flags and why in the PR.
+
+## Releasing
+
+Publishing to PyPI is automated via `.github/workflows/pypi.yml`, which runs when a GitHub
+release is published. To cut a release:
+
+1. Bump `version` in `pyproject.toml` and update `CHANGELOG.md`.
+2. Tag the commit `vX.Y.Z` (the tag version must match `pyproject.toml`, or the workflow fails).
+3. Publish a GitHub release for that tag. The workflow builds the sdist and wheel with `uv build`
+   and uploads them with [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) —
+   no API token.
+
+One-time setup on PyPI (maintainer): add a trusted publisher for the `riff-lint` project pointing
+at this repository, workflow `pypi.yml`, and environment `pypi`. Until that exists, the publish
+step will fail; everything up to it (version check and build) still runs.

riff_lint-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Scale Venture Partners
+
+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.

riff_lint-0.1.0/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.5
+Name: riff-lint
+Version: 0.1.0
+Summary: A small, fast prose linter: ruff-style rule codes for writing, backed by TypeSafe's Jev model
+Project-URL: Repository, https://github.com/scale-venture-partners/riff
+Project-URL: Issues, https://github.com/scale-venture-partners/riff/issues
+Author: Scale Venture Partners
+License: MIT
+License-File: LICENSE
+Keywords: ai-writing,editing,jev,linter,prose,style,typesafe,writing
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: python-docx>=1.1
+Requires-Dist: python-pptx>=1.0
+Requires-Dist: typesafe-sdk>=0.6.0
+Description-Content-Type: text/markdown
+
+# riff
+
+[![CI](https://github.com/scale-venture-partners/riff/actions/workflows/ci.yml/badge.svg)](https://github.com/scale-venture-partners/riff/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+A small, fast prose linter. It reads a document, flags the writing tells and clarity
+problems it finds, and reports them with **ruff-style rule codes** you can select, ignore,
+and configure. Static rules are pure Python and run in milliseconds; the semantic rules are
+one call each to [TypeSafe's **Jev**](https://typesafe.ai) model, which returns a calibrated
+probability per judgment instead of generated text.
+
+```console
+$ riff draft.md
+draft.md:1:1: RIF002 heading is Title Case; use sentence case
+    Understanding The Impact Of Modern Technology
+draft.md:3:1: JEV001 Announces what it is about to say instead of saying it p=0.92
+    Before we dive in, let me lay out what this section will cover.
+draft.md:5:1: JEV301 Overused AI filler vocabulary used as filler p=0.88
+    We leverage a robust, seamless framework to unlock value.
+draft.md:9:1: JEV103 A standalone quotable line that carries no real information p=0.79
+    Every metric that rewards volume punishes leverage.
+
+12 findings in 1 file (JEV301 ×3, JEV001 ×2, RIF002 ×1).
+Jev: 14 calls, 9,210 input tokens (~$0.0004)
+```
+
+## Install
+
+riff is **not on PyPI yet**, so install it from source. It uses
+[uv](https://docs.astral.sh/uv/).
+
+**Clone and run:**
+
+```console
+git clone https://github.com/scale-venture-partners/riff
+cd riff
+uv sync
+uv run riff --help
+uv run riff draft.md
+```
+
+**Run directly from GitHub, no clone,** with uvx (the repo is private, so this uses
+your existing GitHub credentials via git):
+
+```console
+uvx --from git+https://github.com/scale-venture-partners/riff riff draft.md
+# SSH works too, if that's how you authenticate to GitHub:
+uvx --from git+ssh://git@github.com/scale-venture-partners/riff riff draft.md
+```
+
+To install it as a persistent `riff` command on your PATH from the repo:
+
+```console
+uv tool install git+https://github.com/scale-venture-partners/riff
+riff --help
+```
+
+When riff is published to PyPI, `uv tool install riff-lint` will install the same
+`riff` command (the `riff` name itself is taken on PyPI).
+
+## Usage
+
+The examples below assume `riff` is on your PATH (via `uv tool install` above). From a
+clone without installing, prefix each with `uv run` (e.g. `uv run riff draft.md`).
+
+```console
+riff draft.md                    # lint one file (positional)
+riff -f report.docx              # or the -f/--file flag form
+riff *.md notes.txt slides.pptx  # many files, mixed formats
+riff draft.md --no-jev           # static rules only, no API key needed
+riff draft.md --select JEV,RIF   # only these codes/prefixes
+riff draft.md --ignore JEV002    # keep defaults, drop one rule
+riff draft.md --debug-jev        # print every Jev probability, to tune thresholds
+riff email.txt --type email      # force the document type (skips classification)
+riff draft.md --no-classify      # don't classify; type-specific rules run everywhere
+riff draft.md --format json      # machine-readable output
+riff --list-rules                # the full catalog
+riff --explain JEV001            # one rule in detail
+```
+
+**Supported formats:** Markdown (`.md`), plain text (`.txt`), HTML (`.html`), Word (`.docx`),
+PowerPoint (`.pptx`). Findings report a line and column for text formats, and a paragraph or
+slide label for Office formats.
+
+**Exit codes:** `0` clean, `1` findings, `2` usage or file error.
+
+## The Jev-backed rules
+
+The semantic rules need a TypeSafe API key. Set `TYPESAFE_API_KEY` in the environment (create
+one at <https://console.typesafe.ai/>). Without it, `--no-jev` runs the static rules alone; if
+you select a Jev rule with no key, riff stops and tells you the two ways to fix it rather than
+degrading silently.
+
+Each Jev rule is one yes/no (Noul) question asked about a single paragraph. It is phrased so a
+high probability means the tell is present. riff prints that probability (`p=0.93`) on every Jev
+finding, and you set a per-rule `threshold` to tune sensitivity. The document text is sent to the
+API as data; treat any content you lint accordingly.
+
+## Configuration
+
+riff reads `riff.toml` (or `.riff.toml`), or a `[tool.riff]` table in `pyproject.toml`, from the
+file's directory upward. Command-line flags override the file. `select`/`ignore` take full codes
+(`JEV001`) or prefixes (`JEV`, `RIF1`), with ruff's semantics.
+
+```toml
+# riff.toml
+select = ["RIF", "CLR", "JEV"]          # omit to use every default-on rule
+ignore = ["JEV002"]                      # drop reasoning-leak (noisy on reflective writing)
+extend-select = ["JEV401"]               # turn on a default-off rule (passive voice)
+jev = true                               # set false to skip semantic rules
+model = "jev-latest"
+max-sentence-words = 40                  # CLR001 threshold
+max-reading-grade = 12                   # CLR002 threshold
+
+[thresholds]                             # per-rule Jev sensitivity, 0..1
+JEV001 = 0.7
+JEV103 = 0.75
+```
+
+## Document types
+
+Before the rules run, riff classifies the whole document with one Jev question: is it an
+email, a memo, an SMS, an essay, a blog post, a report, and so on. The detected type prints
+above the findings (`type: email (0.88)`).
+
+Types let a rule apply to some kinds of writing and not others. A greeting and sign-off are
+normal in an **email** but a tell in a **memo** or **SMS**, so the built-in `JEV112` rule skips
+`email` and `letter` and flags a greeting anywhere else.
+
+- Force the type with `--type email` (or any type below). This skips classification, so it
+  needs no API key and is the escape hatch when the classifier is wrong or the input is a short
+  excerpt.
+- Turn classification off with `--no-classify`. Type-specific rules then run everywhere,
+  since the type is unresolved. An unresolved type never silently drops a rule.
+
+The type identifiers are: `sms`, `email`, `chat_message`, `memo`, `letter`, `essay`,
+`blog_post`, `article`, `report`, `academic_paper`, `book_chapter`, `documentation`,
+`release_notes`, `marketing_copy`, `social_post`, `product_description`, `review`,
+`press_release`, `resume`, `script`, `poem`, `notes`, `other`.
+
+## Custom rules
+
+The built-in rules are deliberately generic. Anything specific to your team,
+house style, or domain you add in your own `riff.toml` with `[[custom_rules]]`. No
+code changes, no fork. Two kinds:
+
+```toml
+# A Jev rule: a yes/no question asked about your text (needs TYPESAFE_API_KEY).
+[[custom_rules]]
+code = "TEAM001"
+name = "no-competitor-names"
+type = "jev"
+summary = "Names a competitor"
+question = "Does this passage name a specific competing product or company?"
+threshold = 0.6
+scope = "block"      # "block" (per paragraph) or "document" (once over the whole text)
+skip_for = ["email", "letter"]   # never run for these document types
+# applies_to = ["memo", "report"]  # or: run ONLY for these types
+
+# A phrase rule: literal strings flagged offline, no API key needed.
+[[custom_rules]]
+code = "TEAM002"
+name = "house-style-bans"
+type = "phrase"
+summary = "House-style banned phrase"
+phrases = ["circle back", "synergy", "leverage", "boil the ocean"]
+```
+
+Custom codes must not collide with a built-in code. They are enabled by default and
+obey the same `select`/`ignore`/`threshold` controls as built-in rules, so
+`--select TEAM` runs only yours and `--ignore TEAM002` drops one.
+
+## Rules
+
+62 rules (56 semantic, 6 static). A `·` means off by default; enable it with `--select` or `--extend-select`.
+
+### CLR — Clarity metrics (arithmetic Jev can't do)
+
+| Code | Rule | On | Kind | What it flags | Source |
+|------|------|----|------|---------------|--------|
+| `CLR001` | long-sentence |   | static | Sentence longer than the configured word limit | Williams |
+| `CLR002` | hard-to-read | · | static | Paragraph reading grade above the configured level | Williams |
+| `CLR003` | duplicate-paragraph |   | static | Paragraph repeated near-verbatim elsewhere | tropes.fyi |
+
+### JEV — Semantic rules (Jev model) — the bulk of the catalog
+
+| Code | Rule | On | Kind | What it flags | Source |
+|------|------|----|------|---------------|--------|
+| `JEV001` | preamble |   | Jev | Announces what it is about to say instead of saying it | tropes.fyi |
+| `JEV002` | reasoning-leak |   | Jev | Narrates its own writing or thinking process | tropes.fyi |
+| `JEV003` | premise-stacking | · | Jev | Makes its point only after a wall of its own evidence | tropes.fyi |
+| `JEV004` | tie-back |   | Jev | Closes by restating the answer and looping back to the question | tropes.fyi |
+| `JEV005` | belaboring | · | Jev | Defends a minor point against an objection nobody raised | tropes.fyi |
+| `JEV006` | signposted-conclusion |   | Jev | Explicitly announces that it is concluding | tropes.fyi |
+| `JEV007` | fractal-summary | · | Jev | Restates itself at the start or end of a section | tropes.fyi |
+| `JEV008` | enumerated-prose |   | Jev | A listicle disguised as prose ("The first… The second…") | tropes.fyi |
+| `JEV009` | never-ending-conclusion | · | Jev | The ending stacks clause after clause instead of stopping | tropes.fyi |
+| `JEV010` | formulaic-structure |   | Jev | Follows a formulaic template, hitting every expected beat in order | tropes.fyi |
+| `JEV101` | stakes-inflation |   | Jev | Inflates ordinary stakes to world-historical significance | tropes.fyi |
+| `JEV102` | invented-concept-label |   | Jev | Coins an abstract term as if it were established | tropes.fyi |
+| `JEV103` | quotable-bait |   | Jev | A standalone quotable line that carries no real information | tropes.fyi |
+| `JEV104` | forced-figurative | · | Jev | A simile or metaphor reached for to sound clever, not to clarify | tropes.fyi |
+| `JEV105` | false-vulnerability | · | Jev | Performative self-awareness or risk-free 'honesty' | tropes.fyi |
+| `JEV106` | collaborative-we | · | Jev | Drifts into an unearned collective 'we' | tropes.fyi |
+| `JEV107` | rule-of-three | · | Jev | Stacks parallel triples (tricolons) back to back | tropes.fyi |
+| `JEV108` | false-suspense |   | Jev | A "here's the kicker" transition promising a revelation | tropes.fyi |
+| `JEV109` | pedagogical-voice |   | Jev | A hand-holding, teacher-to-student voice | tropes.fyi |
+| `JEV111` | formulaic-close |   | Jev | A canned, low-pressure sign-off | tropes.fyi |
+| `JEV112` | misplaced-greeting |   | Jev | A personal greeting or sign-off where the format doesn't call for one | tropes.fyi |
+| `JEV110` | futurist-invitation | · | Jev | "Imagine a world where…" salesmanship | tropes.fyi |
+| `JEV201` | one-point-dilution | · | Jev | Restates one idea several ways without adding anything | tropes.fyi |
+| `JEV202` | superficial-analysis |   | Jev | Attaches hollow significance to a mundane fact | tropes.fyi |
+| `JEV203` | despite-challenges | · | Jev | Raises a problem only to immediately wave it away | tropes.fyi |
+| `JEV204` | vague-attribution |   | Jev | Attributes a claim to an unnamed authority | tropes.fyi |
+| `JEV205` | appeal-to-familiarity | · | Jev | Asserts canonical status without evidence | tropes.fyi |
+| `JEV207` | generic-boilerplate |   | Jev | Interchangeable boilerplate that could describe almost anyone | tropes.fyi |
+| `JEV208` | faux-personalization | · | Jev | Sprinkles specifics to seem researched without genuine detail | tropes.fyi |
+| `JEV206` | rapid-fire-analogies | · | Jev | Lists historical companies or shifts to build false authority | tropes.fyi |
+| `JEV301` | ai-vocabulary |   | Jev | Overused AI filler vocabulary used as filler | tropes.fyi |
+| `JEV302` | magic-adverb |   | Jev | An adverb inflating significance ('quietly', 'fundamentally') | tropes.fyi |
+| `JEV303` | ornate-noun |   | Jev | An ornate or grandiose noun where a plain word fits | tropes.fyi |
+| `JEV304` | promotional-language |   | Jev | Reads like marketing copy rather than description | tropes.fyi |
+| `JEV305` | empty-transition | · | Jev | A filler transition that connects nothing | tropes.fyi |
+| `JEV306` | serves-as-dodge | · | Jev | A pompous copula ('serves as', 'stands as') instead of 'is' | tropes.fyi |
+| `JEV307` | synonym-cycling | · | Jev | Cycles synonyms for one referent instead of repeating the word | tropes.fyi |
+| `JEV308` | comma-clipped-tail | · | Jev | A short tail hung off a comma instead of landing the point | tropes.fyi |
+| `JEV401` | passive-voice | · | Jev | Passive voice where the actor matters | Williams |
+| `JEV402` | nominalization | · | Jev | The action is buried in an abstract noun | Williams |
+| `JEV403` | wordy-phrase |   | Jev | A multi-word phrase where one word would do | Williams |
+| `JEV404` | hedging | · | Jev | Vague hedging that weakens the claim without adding precision | Williams |
+| `JEV501` | negative-statement |   | Jev | Says what something is not, instead of what it is | Strunk & White, The Elements of Style |
+| `JEV502` | vague-abstraction |   | Jev | Abstract, general language where concrete detail would serve | Strunk & White, The Elements of Style |
+| `JEV503` | weak-intensifier |   | Jev | Leans on 'very', 'rather', 'pretty', 'quite' for emphasis | Strunk & White, The Elements of Style |
+| `JEV504` | loose-sentence-chain | · | Jev | Two or more clauses strung together with and / but / so / which | Strunk & White, The Elements of Style |
+| `JEV505` | faulty-parallelism | · | Jev | Coordinate ideas in a series expressed in mismatched forms | Strunk & White, The Elements of Style |
+| `JEV601` | not-task-oriented | · | Jev | Documentation that describes the thing instead of telling the reader how to use it | Hargis et al., Developing Quality Technical Information (IBM) |
+| `JEV602` | undefined-term | · | Jev | An acronym or specialized term used without being defined on first use | Hargis et al., Developing Quality Technical Information (IBM); Microsoft Writing Style Guide |
+| `JEV610` | buried-conclusion |   | Jev | Makes the reader work through context before stating the conclusion | Minto, The Pyramid Principle; Garner, HBR Guide to Better Business Writing |
+| `JEV620` | editorializing |   | Jev | Opinion or loaded language inserted into what is presented as reporting | AP Stylebook; Kovach & Rosenstiel, The Elements of Journalism |
+| `JEV630` | feature-not-benefit |   | Jev | Lists features without translating them into a benefit to the reader | Ogilvy, Ogilvy on Advertising; Bly, The Copywriter's Handbook |
+| `JEV640` | on-the-nose-dialogue |   | Jev | Dialogue that states feelings or plot directly instead of implying them | McKee, Story; Field, Screenplay |
+| `JEV650` | forced-rhyme |   | Jev | Rhyme that distorts word choice or syntax to hit the rhyme | Oliver, A Poetry Handbook; Fry, The Ode Less Travelled |
+| `JEV660` | vague-changelog-entry |   | Jev | A release note that says nothing specific ('various improvements') | Keep a Changelog (keepachangelog.com) |
+| `JEV670` | weak-resume-bullet |   | Jev | A resume entry with no strong action verb or concrete result | Resume conventions (strong action verbs, quantified results) |
+
+### RIF — Typography and structure (exact checks Jev can't see)
+
+| Code | Rule | On | Kind | What it flags | Source |
+|------|------|----|------|---------------|--------|
+| `RIF001` | decorative-unicode |   | static | Curly quotes or arrows (glyphs Jev can't see) | tropes.fyi |
+| `RIF002` | title-case-heading |   | static | Heading capitalizes every word | tropes.fyi |
+| `RIF003` | bold-first-bullets |   | static | Most list items open with a bold lead-in | tropes.fyi |
+
+## Sources
+
+The rule set comes from tropes.fyi, Williams, and Strunk & White:
+
+- AI writing tells, from [tropes.fyi](https://tropes.fyi/tropes-md): negative parallelism,
+  em-dash addiction, magic adverbs, signposted conclusions, and the rest.
+- Clarity and grace, from Joseph M. Williams, *Style: Lessons in Clarity and Grace*: wordy
+  phrases, nominalizations, passive voice, sentence length, and readability.
+- The Elements of Style, by Strunk & White: put statements in positive form, use concrete
+  language, cut weak intensifiers, avoid loose-sentence chains, and keep parallel form.
+
+Almost every tell is a Jev judgment: pattern-matching misses paraphrases and fires on look-alikes,
+so anything that depends on meaning or context is a model question, not a regex. Only what Jev
+genuinely cannot do stays in code — exact glyphs it never sees (curly quotes, arrows), structural
+facts in markup, cross-document duplicate detection, and arithmetic metrics (sentence length, grade).
+
+### Sources by document type
+
+The type-specific rules are mined from a style text per document type — Minto for reports, Ogilvy
+for marketing, Hargis for docs, and so on. Where a form has no single canonical work, we cite the recognized guide or
+convention. A rule may cite more than one source, and these overlap with the general catalog above.
+
+| Type | Source(s) mined |
+|---|---|
+| essay, book_chapter | Zinsser, *On Writing Well*; King, *On Writing* |
+| article, press_release | *AP Stylebook*; Kovach & Rosenstiel, *The Elements of Journalism* |
+| report, memo | Minto, *The Pyramid Principle*; Garner, *HBR Guide to Better Business Writing* |
+| academic_paper | Sword, *Stylish Academic Writing*; Williams, *Style* |
+| documentation | Hargis et al., *Developing Quality Technical Information* (IBM); Microsoft / Google style guides |
+| marketing_copy, product_description | Ogilvy, *Ogilvy on Advertising*; Bly, *The Copywriter's Handbook* |
+| script | McKee, *Story*; Field, *Screenplay* |
+| poem | Oliver, *A Poetry Handbook*; Fry, *The Ode Less Travelled* |
+| release_notes | *Keep a Changelog*; *Semantic Versioning* |
+| email, letter | Shipley & Schwalbe, *Send*; Garner, *HBR Guide* |
+| blog_post, social_post | Handley, *Everybody Writes* |
+| review | Barnet, *A Short Guide to Writing About …* |
+| sms, chat_message | Crystal, *Txtng: The Gr8 Db8*; McCulloch, *Because Internet* (descriptive, not prescriptive) |
+| resume | conventions: strong action verbs, quantified results, no first person |
+
+## Development
+
+```console
+uv sync
+uv run pytest            # static tests run offline; live Jev tests skip without a key
+uv run ruff check src tests
+uv run python scripts/gen_readme.py   # regenerate the rule table below
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how rules work and how to add one.
+
+## License
+
+[MIT](LICENSE) © Scale Venture Partners.